JavaCard Applet Development

JavaCard Applet Development

JavaCard is the Java platform for resource-constrained smart cards. It defines a strict subset of Java SE — no floating point, no threads, no dynamic class loading — tuned to run on processors with as little as 2 KB of RAM and 64 KB of non-volatile memory. Despite these constraints, JavaCardJavaCardSoftwareJava applet platform for smart cards.Click to view → enables portable, multi-vendor applet deployment that underpins billions of SIMSIMApplicationSmart card for mobile network authentication.Click to view →, banking, and identity cards worldwide.

Use the APDU Builder to construct and send raw APDUs to your applet during development without writing a full host application.

JavaCard API Essentials

The JavaCard API is organised into packages under javacard.* and javacardx.*. The two most important packages for any applet are:

All cryptographic objects must be instantiated during applet installation and stored in instance variables — not created on every APDU, because object creation allocates EEPROM write cycles and is slow.

Applet Lifecycle

A JavaCard applet follows the GlobalPlatform lifecycle and exposes three callback methods that the card runtime invokes:

install()     → Applet object created and registered with the card runtime
    ↓
select()      → Called when host sends SELECT AID ([AID](/glossary/aid/))
    ↓           Returns true to accept selection, false to decline
process()     → Called for every subsequent APDU until next SELECT or reset
    ↓
deselect()    → Called when another applet is selected or card reset occurs

The process() method is the heart of any applet. It receives the APDU object, reads the command bytes, dispatches to the appropriate handler, and writes the response — all within a single method call.

APDU Handler Pattern

A well-structured APDU handler dispatches on the INS byte and validates input length before touching any sensitive data:

public void process(APDU apdu) {
    byte[] buf = apdu.getBuffer();
    if (selectingApplet()) return;  // implicit 90 00 on SELECT

    byte ins = buf[ISO7816.OFFSET_INS];
    switch (ins) {
        case INS_VERIFY_PIN:
            verifyPin(apdu);
            break;
        case INS_SIGN:
            signData(apdu);
            break;
        default:
            ISOException.throwIt(ISO7816.SW_INS_NOT_SUPPORTED);
    }
}

Key patterns to follow:

• Always call apdu.setIncomingAndReceive() before reading Lc-length data
• Validate Lc and Le before cryptographic operations to prevent oracle attacks
• Use JCSystem.makeTransientByteArray() for temporary buffers — transient arrays live in RAM and are cleared on card reset, preventing leakage across sessions
• Never return sensitive data unconditionally — check PIN status or session authentication state before writing key material to the response buffer

Debugging and Testing

JavaCard simulation frameworks allow applet testing on a desktop before loading to physical hardware:

Use the APDU Builder to compose raw byte-level commands for regression testing applet branches that higher-level tools do not exercise. Always test all error paths (wrong PIN, wrong length, wrong P1/P2) because incorrect ISOException handling is a common source of information leakage.

Persistent vs Transient State

JavaCard distinguishes two memory regions with very different semantics:

Minimising persistent writes is critical for card longevity. Use transient arrays for cryptographic buffers, temporary results, and session state. Reserve persistent memory for keys, counters, and application data that must survive power cycles.

See APDU Command Reference for the full command set your applet can implement, and GlobalPlatform Card Management for how to load and manage your compiled CAP file on a real card.