JavaCard Wiki | Blog

Talking between Java Card applets with shareable interfaces

Fri, 23 Oct 2026 00:00:00 GMT

Java Card applets live behind a firewall. One applet cannot simply new another applet, grab a reference and call a method. Cross-applet calls go through the one door the JCRE provides: a shareable interface.

That door has more rules than a method signature suggests. To pin them down I built a deliberately small case: a ticket-service applet owns a balance, a client applet buys tickets through the service, and an unauthorized applet tries the same call. Four classes in four packages, run on a contactless D600 card. I measured what could be measured; spec-only boundaries are called out separately.

One door, two contexts

The Java Card firewall isolates package contexts: applets in different packages cannot touch each other’s objects. The exception is an interface that extends javacard.framework.Shareable. When a client invokes such an interface, the JCRE switches the active context to the server, runs the method there, and switches back on return.

So a shareable interface is not an ordinary Java interface:

the interface must extend Shareable (itself an empty marker interface);
the server applet implements it and decides in getShareableInterfaceObject which object, if any, to hand out;
the client obtains the reference from JCSystem.getAppletShareableInterfaceObject, casts it to the interface type and calls it;
the method body runs in the server context, while object references passed by the client are still subject to the firewall.

The demo has four packages, one of them a deliberate rogue:

Package	Content	Purpose
`com.javacardwiki.sio.api`	`TicketService`	Contract only; both sides import it
`com.javacardwiki.sio.server`	`TicketServerApplet`	Owns the balance, implements `TicketService`
`com.javacardwiki.sio.client`	`TicketClientApplet`	Buys tickets through the SIO
`com.javacardwiki.sio.rogue`	`TicketRogueApplet`	Unauthorized caller, used to verify the refusal path

Putting the contract in its own package is not tidiness for its own sake. The client imports the contract, not the server implementation, so the server can be replaced without recompiling the client. Conversely, while any client imports the contract package, the JCRE refuses to delete that package.

Contract, server, client

The contract keeps the business methods and a few probes used only to observe behaviour:

package com.javacardwiki.sio.api;

import javacard.framework.Shareable;

public interface TicketService extends Shareable {
    short addTickets(short count);
    short getTickets();

    // Demo probes only; a real service would not expose these
    short callerAidLength();
    byte callerAidByte(short index);
    short fill(byte[] buffer, short offset, short length);
    void fail();
}

The server grants access in getShareableInterfaceObject, which the JCRE calls when a client asks for the SIO. clientAID is supplied by the JCRE:

public Shareable getShareableInterfaceObject(AID clientAID, byte parameter) {
    if (!clientAID.equals(clientAppletAid)) {
        return null;
    }

    callerAidLength = clientAID.getBytes(callerAid, (short)0);
    return this;
}

public short addTickets(short count) {
    requireCaller();          // re-check the caller on every invocation
    tickets += count;
    return tickets;
}

private AID requireCaller() {
    AID caller = JCSystem.getPreviousContextAID();
    if (caller == null || !caller.equals(clientAppletAid)) {
        ISOException.throwIt(ISO7816.SW_SECURITY_STATUS_NOT_SATISFIED);
    }
    return caller;
}

The client fetches once, stores the reference, and calls it:

private TicketService getService() {
    if (service == null) {
        Shareable sio = JCSystem.getAppletShareableInterfaceObject(serverAid, (byte)0);
        if (sio == null) {
            ISOException.throwIt(ISO7816.SW_FILE_NOT_FOUND);
        }
        service = (TicketService)sio;
    }
    return service;
}

Storing the SIO in the service field is convenient, but it has a lifecycle consequence described below.

What showed up on the card

The test environment is the same card as the benchmark: the contactless reader ACS ACR1552 1S CL Reader PICC 0, CPLC D600 (commonly JCOP 4.5 / J3R452; card signals and performance data). The client commands returned:

Observation	Measured result
`clientAID` passed to `getShareableInterfaceObject`	`F053494F434C4901` — 8 bytes, exactly the client applet AID
`JCSystem.getPreviousContextAID()` inside a method	the same 8-byte applet AID
The client’s own `JCSystem.getAID()`	also the same AID
`getShareableInterfaceObject` count after two commands	still `1`, so the client cached the SIO
Unauthorized rogue applet asks for the SIO	`0000`, i.e. `null`
Ordinary `byte[]` passed to the server, server writes it	server catches `SecurityException`, returns `-1`; the array is unchanged
Array created with `JCSystem.makeGlobalArray`, passed to the server	works; all four bytes become `A5`
Storing that global array in a client field	`SecurityException` on assignment (probe returned `-6`)
Server calls `ISOException.throwIt(0x6A80)`	client catches reason `6A80`
Client starts a transaction, SIO adds 100, client aborts	balance is `1` before and after; the server’s write rolled back
`gp --delete` on the server applet while the client caches the SIO	`0x6985`, deletion refused
`gp --delete` on the contract package while the client imports it	`0x6985`, deletion refused

The easiest wrong assumption is AID granularity. getPreviousContextAID() returns the AID of the applet instance that was active at the last context switch, not the package AID. The measured 8-byte value confirms it. Authenticate by instance AID; isolation is per package: applets in one package share a context and do not need an SIO to reach each other, while cross-package calls should use an applet-AID allow-list in the server, not a package AID comparison.

Five things that actually trip people up

1. Ordinary arrays do not cross; use a global array.

Hand the server a client byte[] and the first write raises SecurityException. That is not an implementation quirk: an ordinary array belongs to the context that created it, and another context may only access its own arrays or a global array.

Java Card 3.0.5 lets an applet create one:

byte[] global = (byte[])JCSystem.makeGlobalArray(JCSystem.ARRAY_TYPE_BYTE, (short)4);

The API arrived in 3.0.4, so 2.2.2 code cannot rely on it. More importantly, a global array is a temporary object: it can be used for the current command but must not be assigned to a field, instance variable or array element. My first version stored the result of makeGlobalArray in a client field, and the command returned SecurityException; with a local variable, the server wrote A5 A5 A5 A5 without complaint.

2. Do not use exceptions to refuse in getShareableInterfaceObject.

Return null. The specification requires the client to be unable to distinguish “server AID not found”, “server does not participate”, “caller not allowed” and “the server threw an exception”: the JCRE swallows exceptions from getShareableInterfaceObject, and the client sees only null. The client must handle null; it cannot assume the server is present.

3. Use ISOException for errors that cross the boundary.

ISOException.throwIt(sw) uses an exception instance owned by the JCRE, which is safe across contexts; the client caught reason 6A80. An exception object created by the server can be caught by the client, but reading its fields or calling its methods may then hit the firewall. Put the status in the ISO exception or in a return value; do not ask the client to interpret an object owned by the server.

4. Transactions cross the SIO; the server must not start its own.

After a client calls beginTransaction(), the server’s persistent writes during an SIO call belong to the same transaction. A client abortTransaction() rolls them back — measured: balance 1 before and after. Conversely, the server should not call beginTransaction() inside an SIO method: the transaction is a card-wide singleton, and starting one while the client already has one returns IN_PROGRESS.

5. Caching the SIO is convenient, but it blocks deletion of the server.

Storing the SIO in a client field really does avoid repeated getShareableInterfaceObject calls (the count stayed at 1 across two commands). The price is that the server applet owns an object referenced by a client instance, and the JCRE guarantees that deleting the server applet fails — gp --delete returned 0x6985. For the same reason, deleting the contract package fails while a client imports it.

If the server must be replaceable, do not keep the SIO forever: fetch it before use and check for null, or accept a maintenance order of “delete the client first, then the server”. That ordering is easy to get wrong during upgrades, especially after splitting contract, server and client into three packages.

What one SIO call costs

An SIO call is a context switch, not a local method call. To measure it, the client got two loop commands: one repeatedly calls getTickets() (which performs getPreviousContextAID plus an AID comparison on every call), the other repeatedly calls ping() (returns a constant, no authorization). The host timed the whole APDU at n = 0 / 1000 / 2000 and fitted the slope, using the same differential method as the benchmark:

Call	Per-call cost (fitted slope)
`ping()`, no authorization	about 187 µs
`getTickets()`, caller checked every time	about 787 µs
Fixed APDU cost (`n = 0` intercept)	about 4.9 ms

On this card, even the cheapest SIO call costs almost 0.2 ms, and adding the per-call getPreviousContextAID and AID comparison pushes it close to 0.8 ms. Authorization dominates; an SIO is not a microsecond-level local method. If an operation would loop hundreds of times, move the loop into the server and batch it instead of bouncing between the two contexts.

Reproducing it

Put the four classes into the four packages described above and convert them in order: contract, server, client, rogue. One tool detail: the contract package has no applet, so gp --install reports “CAP file has no applets”; use gp --load to load the package, then --install the applet packages. The load order is contract → server → client; uninstall is the reverse.

gp -r "<reader>" --load api.cap
gp -r "<reader>" --install server.cap
gp -r "<reader>" --install client.cap

The client AID is F053494F434C4901; select it and send the APDUs from the table above. To test the rogue path, select F053494F524F4701 instead and send 8001000000; it should return 0000.

This case covers only a single channel and a single client. Two spec boundaries are still worth remembering: a non-MultiSelectable server already active on another logical channel makes getAppletShareableInterfaceObject throw SecurityException, and RMI (javacard.framework.service) is an optional component rather than something every card implements, so it is not required for cross-applet calls.

One last caveat: these behaviours were measured on a Java Card 3.0.5 API, CPLC D600 JCOP card; the card’s getVersion() reports only 0x0300, which says nothing about the patch level. On another card or JCRE implementation, the array, exception and deletion error codes can differ. Run these probes before writing business code; it is more reliable than copying the documentation.

Benchmarking two Java Card 3.0.5 cards

Thu, 22 Oct 2026 00:00:00 GMT

It started with one contactless Java Card 3.0.5 card (CPLC D600, commonly JCOP 4.5 / J3R452). Once the benchmark worked, a second card of the same generation but a different model showed up (CPLC D321, commonly JCOP 4 / J3R180). Both ran the same applet version (v6) through the same host code on the same reader, so every difference comes from the card itself — which says more about “Java Card performance” than a single card ever could. The D321 data was later re-measured on another card of the same model, cleaned down to the ISD, the GlobalPlatform support package and the benchmark applet.

The suite lives in the repository’s benchmark/ directory: an on-card applet, a Java driver that keeps one PC/SC session open, and a Node harness that orchestrates and verifies. Cross-card comparison is on the results page, each card’s full data (ATR, CPLC, memory, capabilities and performance tables) is linked from the card signals page, and the method is on the methodology page.

You cannot time a single command

Java Card classic has no clock, so the card cannot time itself, and the host can only time an APDU round trip. That fixed cost is not small on a contactless link: about 3.2–4.1 ms for an empty command, and about 9.8–10.7 ms when the applet returns data, because the card answers 61xx and the host sends GET RESPONSE.

So the applet executes the operation n times per command and the host fits:

elapsed(n) = fixed cost + per-operation cost × n

The n = 0 point exists to measure the fixed cost directly; the slope is the per-operation time. Each test warms up, calibrates to about 80 ms, discards one sampling pass, then takes the median of three samples at four points and reports R² plus the coefficient of variation. You can see at a glance whether a number is trustworthy.

Six things that got in the way

1. No int. The converter rejects int locals, int return types and even int-typed array indexes. Every loop counter has to be a short, which caps a command at 32767 iterations.

2. A card response costs two round trips. When the applet returns data with sendBytesLong, the card first answers 61xx and the host then sends GET RESPONSE. It cancels out in the slope but inflates the intercept past 10 ms; without differential timing it would end up inside the “crypto performance” number.

3. Transient RAM is the binding constraint. With the applet’s own buffers allocated, the D600 card has only about 3.4 KB of transient memory left (1.7 KB before the factory applets were removed) and the D321 card about 2.8 KB, while every KeyPair, Signature and Cipher object takes a slice. Building the P-256 objects first and then generating an RSA key pair returns 6B02 (NO_TRANSIENT_SPACE). The suite therefore runs in four phases and sends RESET between them, where the applet drops all crypto objects and calls requestObjectDeletion().

4. Applets that were already on the card consume memory too. When the first D321 card arrived it reported roughly 2.8 KB of free persistent memory and only 295 B of transient memory — not even enough for the benchmark buffers. After removing the leftover third-party applets and packages (with the user’s permission), the same card reported about 96 KB of persistent memory and 2.8 KB of transient memory. Some of the earlier “algorithm unavailable” conclusions were really memory starvation: clean first, then measure. The D321 data that ended up published came from another card of the same model, cleaned down to the platform packages before the applet was installed, so its baseline is clean.

5. Capability probing is itself misled by transient memory. Probing dozens of algorithms inside one APDU keeps their transient objects alive until the command ends, so a tight card starts answering 0x7F (unexpected exception) partway through, which looks like “unsupported”. The fix was a second applet command that probes exactly one algorithm per APDU (INS 12), with the host retrying every anomalous bulk result. Only then did the real picture appear: on the D600 card HMAC gets as far as building the objects but every setKey returns ILLEGAL_VALUE; on the D321 card even Signature.getInstance returns NO_SUCH_ALGORITHM. Unusable either way, but at different points.

6. Signature.verify() behaves strangely. For a key pair generated in an earlier command, on-card verify returns false, while the same signature verifies on a PC with the card’s modulus; putting sign and verify in one command succeeds again. Modulus, exponent and signature bytes were all checked. Without a convincing explanation, the honest move is to record it: the standalone RSA and ECDSA verify timings would not be trustworthy, so they are marked “not reported”.

How the cards differ

	D600 card	D321 card
Inferred model	NXP P71D600 / JCOP 4.5 / J3R452	NXP P71D321 / JCOP 4 / J3R180
ATR (reader-synthesised)	`3B8A80010031C173C8400000900090`	`3B8C80015432433134504A34313890009A`
Free persistent memory	336,020 B	155,632 B
Free transient memory (RESET)	4,609 B	3,974 B
Free transient memory (DESELECT)	4,608 B	3,968 B
Empty command round trip	4.1 ms	3.2 ms
64 B response round trip	15.6 ms	6.4 ms
`getVersion()`	`0x0300`	`0x0300`

Link speed and chip speed do not move together: the D321 card’s link is much faster (6.4 ms versus 15.6 ms for a 64 B response), yet its RSA signature is slower (105.8 ms versus 87.9 ms) and re-initialising AES costs much more (init + encrypt 8.0 ms versus 3.1 ms). “The newer card” would have been the wrong conclusion.

Those three rows are read in the benchmark applet’s constructor, before it allocates its own test buffers. That step matters: getAvailableMemory reports what is left at the moment of the call, and allocating a few buffers or installing a couple more applets shifts the reading by kilobytes. The benchmark applet’s own fixed cost is 3,924 B persistent and 1,184 B in each transient view (two views of the same pool, not two pools to add), so while it runs the readings are lower by that much. It also explains an earlier hand measurement of about 3.8 KB: that was the transient baseline before the buffers were allocated (3,974 B on this D321 card), not what was left after the applet was installed. Align that premise before comparing cards — a single “free memory” number can support the opposite conclusion.

One difference remains after cleaning: the D321 card’s clean persistent baseline is only 155.6 KB, about half of the D600 card’s 336.0 KB. That is not applet overhead but a different NVM configuration.

The algorithm sets are almost identical: AES-128 only, no AES-192/256, no AES-GCM, no HMAC, and no default EC curve on either card (P-256 has to be imported, and setG needs the 65-byte 04 || x || y form). Even the HMAC failure point differs, so “same Java Card version” does not imply “same algorithm set”.

Measured numbers

Test	D600 card	D321 card
16-bit addition (single op)	34.0 µs	35.6 µs
16-bit multiply / divide	47.8 / 45.0 µs	50.0 / 47.3 µs
byte array read / write	96.0 / 91.3 µs	86.8 / 82.5 µs
AES-128 ECB encrypt (16 B)	1.67 ms	1.60 ms
AES-128 ECB `init + encrypt`	3.1 ms	8.0 ms
DES / 3DES ECB (8 B)	1.66 / 1.72 ms	1.58 / 1.65 ms
SHA-256 (32 B / 1 KiB)	2.38 / 26.0 ms	2.38 / 26.0 ms
secure random (32 B)	0.91 ms	0.76 ms
ECDSA P-256 sign	46.6 ms	53.7 ms
ECDH P-256	30.4 ms	38.1 ms
RSA-2048 sign / decrypt	87.9 / 84.7 ms	105.8 / 102.7 ms
RSA-2048 encrypt	6.6 ms	8.1 ms
key pair generation: P-256 / RSA-2048	135.4 ms / 0.9–11.5 s	139.0 ms / 5.2–12.1 s
`arrayCopy` 64 B (persistent destination)	3.23 ms	3.32 ms
one transaction per write	0.39 ms	0.39 ms
allocate a 32-byte persistent array	8.8 ms	9.2 ms

Single-byte reads and writes (about 82–97 µs) are already close to the interpreter loop cost, so they are not EEPROM read/write speed; arrayCopy and the transaction rows say more about the medium. Persistent writes also occasionally enter a slow state, the same test going from 84 µs to 1.4 ms, related to wear-levelling — which is why the harness re-measures when fit quality drops. Two storage rows have R² below 0.99 and carry a †, meaning the slope is only a local estimate.

Same-version re-run and cross-card comparison

In the first published run the two cards used different applet versions (D600 had v4, D321 had v5). To confirm that this would not contaminate the comparison, the D600 card was measured again with v5: across the 37 valid timing rows the median per-operation deviation was 0.5%, transport round trips differed by under 1.5%, and only the high-variance RSA key generation and allocate+delete rows moved substantially. Both cards’ data now comes from v6; v6 only adds the pre-allocation memory baseline and leaves the timing path unchanged.

The results page now has an interactive cross-card comparison: pick any card as the baseline, which is always shown in the first column, and the other cards show their relative timing change, with a green ↓ for faster and a red ↑ for slower. The data is read from latest.json, so future cards join the selector automatically.

What the numbers mean

They are considerably slower than the “hardware-accelerated Java Card” impression: 1.6 ms per symmetric block, roughly 90–105 ms for an RSA signature, and no AES beyond 128 bits at all. On these cards over this link, crypto acceleration cannot be assumed; which algorithm is usable and how fast it is has to be measured.

The link matters too: a contactless card is powered over RF and is inherently slower than a contact card. The same tool on a contact card and another reader could produce very different conclusions — which is exactly why it is built as a reproducible measurement method rather than a scorecard.

The cross-card comparison is on the results page, where any card can be selected as the baseline; each card’s full tables (fit quality, verification status and capability probes) and identity evidence are linked from the card signals page. To run it on your own card, the benchmark/ directory has the build, install and one-command runner scripts.