[GH-ISSUE #3645] [Feature] Java Card reverse engineering: CAP files, applets, bytecode, AIDs and APDU handler reconstruction #1365

New issue

Open

opened 2026-10-16 21:04:42 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:04:42 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3645

Summary

Java Card is the global standard operating environment for secure elements, smart cards, SIM / eSIM (eUICC) telecommunication profiles, biometric electronic passports, and banking payment cards (EMV). Java Card applications are distributed and provisioned onto secure chips as Converted Applet (CAP) files (.cap packages), which represent an optimized, compact binary representation of Java bytecode executing on the 16-bit/32-bit Java Card Virtual Machine (JCVM).

While REA has proposed classic Java Applet reverse engineering (#3617), Java Card utilizes an entirely distinct, resource-constrained architecture:

No dynamic class loading, no threads, no floating point, no Garbage Collection (historically);
Package components (Header.cap, Directory.cap, Applet.cap, Method.cap, Class.cap, ConstantPool.cap, Export.cap, etc.);
Application Identifiers (AIDs) defined by ISO/IEC 7816-5;
Command/Response Application Protocol Data Unit (APDU) dispatch loops (process(APDU apdu)).

This feature proposal introduces dedicated Java Card Reverse Engineering to REA, enabling automated inspection and extraction of .cap packages, JCVM bytecode disassembly/decompilation, AID mapping, and APDU command handler reconstruction.

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: Java Card CAP File (.cap / ZIP)  |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | CAP Component Unpacker    |                                   | Manifest & GlobalPlatform |
           | (Header, Directory, Import|                                   | Metadata (AIDs, Privileges|
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Constant Pool & Export Table Parser   |
                                     | (ConstantPool.cap, Export.cap, JCR)   |
                                     +-------------------+-------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | JCVM Bytecode Disassembler            |
                                     | (Method.cap, 16-bit Compact Bytecode) |
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | Applet Lifecycle & AID Map|                                   | APDU Command Handler      |
           | (install(), select(), AIDs|                                   | Dispatch (CLA/INS/P1/P2)  |
           +-------------+-------------+                                   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: Java Card Class Dossier |
                                     | & APDU Command-Response Matrix        |
                                     +---------------------------------------+

1. CAP Package Component Unpacking

Container Format: Parse .cap files (stored as standard ZIP archives or concatenated component streams), extracting standard Java Card components:
- Header.cap: CAP format version (v2.1, v2.2, v3.x), package AID, package flags.
- Directory.cap: Component size table and presence bitmasks.
- Applet.cap: Declared applet definitions and their distinct instance AIDs.
- Import.cap: External package dependencies and version requirements.
- ConstantPool.cap: Constant pool resolution table (classes, fields, methods).
- Class.cap: Class interfaces, superclasses, and field counts.
- Method.cap: Bytecode method bodies, exception handlers, and local variable counts.
- StaticField.cap: Initializer arrays and static variables.
- Export.cap: Exported public and protected definitions for shared libraries.
- Descriptor.cap: Debug metadata, class names, method signatures (when unstripped).

2. JCVM (Java Card Virtual Machine) Bytecode Disassembly & Decompilation

Compact Bytecode Architecture: Disassemble specialized 1-byte and 2-byte JCVM opcodes tailored for 16-bit arithmetic:
- Stack and local manipulation: sspush, bspush, sload, sstore, aload, astore.
- Arithmetic operations: sadd, ssub, smul, sdiv, srem, sand, sor, sxor.
- Array operations: baload, bastore, saload, sastore, aaload, aastore.
- Branching and control flow: ifeq, ifne, iflt, goto, slookupswitch, stableswitch.
- Invocations: invokevirtual, invokestatic, invokespecial, invokeinterface.
High-Level Decompilation: Reconstruct high-level Java Card source code with typed 16-bit short variables and control flow structures.

3. Application Identifiers (AIDs) & GlobalPlatform Metadata

AID Parsing: Decode ISO/IEC 7816-5 AIDs into Registered Application Provider Identifier (RID - 5 bytes) and Proprietary Application Identifier Extension (PIX - up to 11 bytes). Identify known vendor RIDs (e.g. Visa, Mastercard, NXP, Gemalto/Thales, Giesecke+Devrient, GlobalPlatform).
Applet Installation Parameters: Parse install(byte[] bArray, short bOffset, byte bLength) parameters, extracting instance AIDs and privileges.

4. APDU Command Dispatch & Protocol Inversion

process(APDU) Method Inversion: Analyze the core message-processing loop of the applet.
APDU Structure Decoding: Track buffer extraction from apdu.getBuffer():
- CLA (Class byte: e.g. 0x00, 0x80 proprietary, 0x84 Secure Messaging).
- INS (Instruction byte: command identifier, e.g. 0xA4 SELECT, 0x20 VERIFY PIN, 0x82 EXTERNAL AUTH).
- P1 and P2 parameter bytes.
- Lc (Incoming data length) and Le (Expected response length).
Status Word (SW) Extraction: Catalog returned ISO 7816 status words (e.g. 0x9000 OK, 0x6A82 File Not Found, 0x63Cx PIN Retries Left, 0x6982 Security Status Not Satisfied).
APDU Matrix Generation: Emit a comprehensive matrix of supported APDU commands, parameter constraints, and security conditions.

Acceptance Criteria

Introduce analyze_javacard_cap in REA CLI and MCP contracts, accepting .cap files.
Accurately unpack all CAP components from synthetic Java Card 2.2 and 3.x test fixtures.
Disassemble JCVM bytecode in Method.cap into clean symbolic disassembly.
Extract package and applet AIDs and resolve recognized card vendor RIDs.
Invert process(APDU) handlers to document all handled INS codes and status words in structured evidence.

#3617 [Feature] Java Applets & JNLP reverse engineering
#3615 [Feature] Hardware and Embedded Reverse Engineering: ESP32 firmware
#3641 [Feature] USB protocol reverse engineering

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3645 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Game & Engine RE](https://img.shields.io/badge/domain-game_&_engine_RE-green.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Summary Java Card is the global standard operating environment for secure elements, smart cards, SIM / eSIM (eUICC) telecommunication profiles, biometric electronic passports, and banking payment cards (EMV). Java Card applications are distributed and provisioned onto secure chips as **Converted Applet (CAP)** files (`.cap` packages), which represent an optimized, compact binary representation of Java bytecode executing on the 16-bit/32-bit Java Card Virtual Machine (JCVM). While REA has proposed classic Java Applet reverse engineering (#3617), Java Card utilizes an entirely distinct, resource-constrained architecture: - No dynamic class loading, no threads, no floating point, no Garbage Collection (historically); - Package components (`Header.cap`, `Directory.cap`, `Applet.cap`, `Method.cap`, `Class.cap`, `ConstantPool.cap`, `Export.cap`, etc.); - Application Identifiers (AIDs) defined by ISO/IEC 7816-5; - Command/Response Application Protocol Data Unit (APDU) dispatch loops (`process(APDU apdu)`). This feature proposal introduces dedicated **Java Card Reverse Engineering** to REA, enabling automated inspection and extraction of `.cap` packages, JCVM bytecode disassembly/decompilation, AID mapping, and APDU command handler reconstruction. --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: Java Card CAP File (.cap / ZIP) | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | CAP Component Unpacker | | Manifest & GlobalPlatform | | (Header, Directory, Import| | Metadata (AIDs, Privileges| +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | Constant Pool & Export Table Parser | | (ConstantPool.cap, Export.cap, JCR) | +-------------------+-------------------+ | v +---------------------------------------+ | JCVM Bytecode Disassembler | | (Method.cap, 16-bit Compact Bytecode) | +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | Applet Lifecycle & AID Map| | APDU Command Handler | | (install(), select(), AIDs| | Dispatch (CLA/INS/P1/P2) | +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | REA Evidence: Java Card Class Dossier | | & APDU Command-Response Matrix | +---------------------------------------+ ``` ### 1. CAP Package Component Unpacking - **Container Format:** Parse `.cap` files (stored as standard ZIP archives or concatenated component streams), extracting standard Java Card components: - `Header.cap`: CAP format version (v2.1, v2.2, v3.x), package AID, package flags. - `Directory.cap`: Component size table and presence bitmasks. - `Applet.cap`: Declared applet definitions and their distinct instance AIDs. - `Import.cap`: External package dependencies and version requirements. - `ConstantPool.cap`: Constant pool resolution table (classes, fields, methods). - `Class.cap`: Class interfaces, superclasses, and field counts. - `Method.cap`: Bytecode method bodies, exception handlers, and local variable counts. - `StaticField.cap`: Initializer arrays and static variables. - `Export.cap`: Exported public and protected definitions for shared libraries. - `Descriptor.cap`: Debug metadata, class names, method signatures (when unstripped). ### 2. JCVM (Java Card Virtual Machine) Bytecode Disassembly & Decompilation - **Compact Bytecode Architecture:** Disassemble specialized 1-byte and 2-byte JCVM opcodes tailored for 16-bit arithmetic: - Stack and local manipulation: `sspush`, `bspush`, `sload`, `sstore`, `aload`, `astore`. - Arithmetic operations: `sadd`, `ssub`, `smul`, `sdiv`, `srem`, `sand`, `sor`, `sxor`. - Array operations: `baload`, `bastore`, `saload`, `sastore`, `aaload`, `aastore`. - Branching and control flow: `ifeq`, `ifne`, `iflt`, `goto`, `slookupswitch`, `stableswitch`. - Invocations: `invokevirtual`, `invokestatic`, `invokespecial`, `invokeinterface`. - **High-Level Decompilation:** Reconstruct high-level Java Card source code with typed 16-bit `short` variables and control flow structures. ### 3. Application Identifiers (AIDs) & GlobalPlatform Metadata - **AID Parsing:** Decode ISO/IEC 7816-5 AIDs into Registered Application Provider Identifier (RID - 5 bytes) and Proprietary Application Identifier Extension (PIX - up to 11 bytes). Identify known vendor RIDs (e.g. Visa, Mastercard, NXP, Gemalto/Thales, Giesecke+Devrient, GlobalPlatform). - **Applet Installation Parameters:** Parse `install(byte[] bArray, short bOffset, byte bLength)` parameters, extracting instance AIDs and privileges. ### 4. APDU Command Dispatch & Protocol Inversion - **`process(APDU)` Method Inversion:** Analyze the core message-processing loop of the applet. - **APDU Structure Decoding:** Track buffer extraction from `apdu.getBuffer()`: - `CLA` (Class byte: e.g. `0x00`, `0x80` proprietary, `0x84` Secure Messaging). - `INS` (Instruction byte: command identifier, e.g. `0xA4` SELECT, `0x20` VERIFY PIN, `0x82` EXTERNAL AUTH). - `P1` and `P2` parameter bytes. - `Lc` (Incoming data length) and `Le` (Expected response length). - **Status Word (SW) Extraction:** Catalog returned ISO 7816 status words (e.g. `0x9000` OK, `0x6A82` File Not Found, `0x63Cx` PIN Retries Left, `0x6982` Security Status Not Satisfied). - **APDU Matrix Generation:** Emit a comprehensive matrix of supported APDU commands, parameter constraints, and security conditions. --- ## Acceptance Criteria 1. Introduce `analyze_javacard_cap` in REA CLI and MCP contracts, accepting `.cap` files. 2. Accurately unpack all CAP components from synthetic Java Card 2.2 and 3.x test fixtures. 3. Disassemble JCVM bytecode in `Method.cap` into clean symbolic disassembly. 4. Extract package and applet AIDs and resolve recognized card vendor RIDs. 5. Invert `process(APDU)` handlers to document all handled `INS` codes and status words in structured evidence. --- ## Related - #3617 [Feature] Java Applets & JNLP reverse engineering - #3615 [Feature] Hardware and Embedded Reverse Engineering: ESP32 firmware - #3641 [Feature] USB protocol reverse engineering

bsakaguchi referenced this issue

2026-10-17 21:11:18 +00:00

[PR #1424] [MERGED] fix(javascript): unify package resolution and resolve exact exports subpaths #2876

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#1365

No description provided.

Rows
Columns