576eeca401
Updates the --step-up expected-output block to the actual STEP-UP M2 OK line emitted on 2026-06-12 verdict, and pins the verified card UID + log path. Memory step_up_implementation_notes.md filled in the 3 TODO markers (M2E + M2F + M2G.2 verdict) and added a J3R452 transient pool budget table (~2,835 / 3,120 B used post-M2G.2).
262 lines
12 KiB
Markdown
262 lines
12 KiB
Markdown
# Installing the Aliro applet on a real Java Card
|
|
|
|
Tested target: NXP J3R180 (JC 3.0.5, GP 2.3) over a USB PC/SC reader. Other
|
|
GP-2.2+ JC 3.0.5+ cards should work too.
|
|
|
|
## What you'll need
|
|
|
|
- A USB PC/SC reader (e.g. ACR1252U, ACR122U, OMNIKEY 5022).
|
|
- A Java Card with default GlobalPlatform test keys still in place (any
|
|
freshly-bought J3R180 from VivoKey-friendly suppliers ships this way).
|
|
- Java 11+ on the host. `pcscd` running (`sudo systemctl start pcscd` on
|
|
Linux).
|
|
- [GlobalPlatformPro](https://github.com/martinpaljak/GlobalPlatformPro)
|
|
(`gp.jar` — single fat jar, no install needed):
|
|
|
|
```
|
|
curl -sLO https://github.com/martinpaljak/GlobalPlatformPro/releases/latest/download/gp.jar
|
|
```
|
|
|
|
## Build the CAP
|
|
|
|
```
|
|
cd applet
|
|
./scripts/dt-mvn.sh clean package -DskipTests
|
|
```
|
|
|
|
Output: `applet/target/aliro-applet-j3r180.cap` (~42 KB). Built inside
|
|
the `vivokey/smartcard-ci` container by the `ant-javacard` plugin
|
|
against the JC 3.0.5 SDK. Add `-Pj3r452` to build the AMD-H variant
|
|
(`aliro-applet-j3r452.cap`) instead; the j3r180 default is what's
|
|
shipped in the field today, so use it if you're not sure.
|
|
|
|
## Install
|
|
|
|
```
|
|
java -jar gp.jar --info # confirm reader sees the card
|
|
|
|
# Multi-applet CAPs: load the package once, then create each instance.
|
|
# --create needs the instance AID, the applet class AID (same as instance
|
|
# here), and the package AID (printed by --load).
|
|
PKG=A0000009094454414C49524F02
|
|
java -jar gp.jar --load applet/target/aliro-applet-j3r180.cap
|
|
java -jar gp.jar --create A000000909ACCE5501 --applet A000000909ACCE5501 --package $PKG
|
|
java -jar gp.jar --create A000000909ACCE5502 --applet A000000909ACCE5502 --package $PKG
|
|
java -jar gp.jar --create A000000909ACCE559901 --applet A000000909ACCE559901 --package $PKG
|
|
```
|
|
|
|
(`--install <cap>` alone fails with `"CAP contains more than one applet,
|
|
specify the right one with --[applet]"`, and `--create AID` without
|
|
`--applet`/`--package` fails with `"Need --[package, pkg] and --[applet]
|
|
or --[cap]"`.)
|
|
|
|
**Partial install / recovery**: if a `--create` call fails mid-sequence
|
|
(card got reset, USB hiccup, RF dropout), the package stays loaded. Just
|
|
re-run the failed `--create` — no need to redo `--load` or the earlier
|
|
`--create` calls. The package only needs `--delete` + `--load` again if
|
|
the package itself is in a bad state.
|
|
|
|
**Credential store is package-static**: keys and the Access Document
|
|
written via `aliro-personalize` live on a static class shared by all
|
|
three applets. Personalization only requires `ACCE559901` to be
|
|
SELECTABLE; `5501` and `5502` can be `--create`d after personalize ran
|
|
and they'll see the same credentials. (Note: `aliro-personalize`
|
|
returning "Personalization complete" only confirms `559901` accepted the
|
|
writes — always cross-check `gp --list` to confirm `5501` and `5502`
|
|
are also SELECTABLE.)
|
|
|
|
Default GP test keys (`404142434445464748494A4B4C4D4E4F`) are tried
|
|
automatically. For non-default keys, pass `--key <hex>` to every command.
|
|
|
|
Three applets get registered, one CAP:
|
|
|
|
| AID | Class | Role |
|
|
| -------------------------------- | ---------------------- | -------------------------------------------- |
|
|
| `A0000009 09 ACCE 55 01` | `AliroApplet` | Aliro EXPEDITED phase (spec) |
|
|
| `A0000009 09 ACCE 55 02` | `StepUpApplet` | Aliro STEP_UP phase (spec; scaffold only ATM)|
|
|
| `A0000009 09 ACCE 55 99 01` | `PersonalizationApplet`| DT-internal provisioning channel |
|
|
|
|
All three share the package AID `A0000009 09 4454414C49524F 02` (CSA RID
|
|
+ ASCII "DTALIRO" + version byte). JavaCard requires applets in one CAP
|
|
to share the package's RID, hence the proprietary AID for personalization
|
|
is also under the CSA RID with a non-spec PIX (`99 01`).
|
|
|
|
## Verify
|
|
|
|
```
|
|
java -jar gp.jar --list
|
|
```
|
|
|
|
You should see all three AIDs in the `Application` list.
|
|
|
|
## Personalize
|
|
|
|
After install the card holds three applets but no Access Credential keys
|
|
or Access Document — every Aliro flow returns `SW_CONDITIONS_NOT_SATISFIED`.
|
|
|
|
Provision via the PersonalizationApplet (CLA `0x80`):
|
|
|
|
| INS | P1\|P2 | Data | Description |
|
|
| ------ | --------------- | --------------------------------------- | -------------------------------------------------------------- |
|
|
| `0x20` | `0000` | 32B credential_PrivK | Access Credential long-term privkey |
|
|
| `0x21` | `0000` | 64B credential_PubK (x\|\|y) | …matching pubkey |
|
|
| `0x22` | `0000` | 64B reader_PubK (x\|\|y) | reader long-term pubkey |
|
|
| `0x23` | offset (BE) | up to 255B chunk | Access Document chunk write |
|
|
| `0x24` | total_len (BE) | (none, Lc=0) | Finalize Access Document — runs IssuerAuth COSE_Sign1 verify |
|
|
| `0x25` | `0000` | 64B credential_issuer_PubK (x\|\|y) | Credential Issuer pubkey — trust anchor for IssuerAuth verify |
|
|
| `0x2C` | `0000` | (none) | COMMIT — locks all writes |
|
|
|
|
Required order: SELECT provisioning AID → write all keys (including
|
|
credential_issuer_PubK) + AD chunks → finalize → COMMIT. The issuer pubkey
|
|
MUST be set before FINALIZE — without it FINALIZE returns
|
|
`SW_CONDITIONS_NOT_SATISFIED`. A signature mismatch at FINALIZE returns
|
|
`SW_DATA_INVALID` and leaves the AD un-finalized. After COMMIT, every
|
|
write returns `SW_CONDITIONS_NOT_SATISFIED` (no factory-reset mechanism in v1).
|
|
|
|
Source bytes come from `aliro-trustgen init --out-dir ./out`:
|
|
- `out/access_credential.pem` → derive priv/pub bytes
|
|
- `out/reader.pem` → derive pub bytes
|
|
- `out/issuer.pem` → derive Credential Issuer pubkey
|
|
- `out/access_document.bin` → chunk into ≤255B writes
|
|
|
|
**One-shot personalization:** the harness ships an `aliro-personalize`
|
|
CLI that walks the entire INS sequence above against a PC/SC reader:
|
|
|
|
```
|
|
pip install -e harness/ # one-time, if not already installed
|
|
aliro-trustgen init --out-dir ./trust-out
|
|
aliro-personalize --trust-dir ./trust-out
|
|
```
|
|
|
|
Use `aliro-personalize --list-readers` to enumerate readers if more than
|
|
one is plugged in, then `--reader N` to pick by index.
|
|
|
|
The CLI fails fast on the first non-9000 status word and tells you which
|
|
step. After `COMMIT`, the card refuses every further write — there is no
|
|
factory-reset path in v1, so verify the trust artifacts before running.
|
|
|
|
## Validate after personalization
|
|
|
|
Once personalization has COMMITted, `aliro-bench-test` drives a full
|
|
AUTH0+AUTH1 exchange against the card from a Python orchestrator over
|
|
PC/SC. It's the real-hardware validation path that works without any
|
|
reader firmware (X-CUBE-ALIRO on X-NUCLEO-NFC09A1 is still pending).
|
|
|
|
```
|
|
pip install -e harness/ # one-time, same package that ships aliro-personalize
|
|
aliro-bench-test --trust-dir ~/aliro-trust
|
|
```
|
|
|
|
The `--trust-dir` must point at the same `aliro-trustgen init` output
|
|
that personalization used (it reads `reader.pem` to sign the AUTH1
|
|
challenge and `access_credential.pem` to verify the UD signature the
|
|
applet returns).
|
|
|
|
Successful output looks like:
|
|
|
|
```
|
|
Using reader: ACS ACR1252 1S CL Reader 0
|
|
Connected. ATR: 3B8F8001804F0CA000000306030001000000006A
|
|
Loaded trust artifacts from /home/you/aliro-trust
|
|
RESULT: OK — applet round-trip on real hardware.
|
|
0x5A credential_PubK: 65B
|
|
0x9E UD signature: 64B
|
|
0x5E signaling_bitmap: 0x0000
|
|
```
|
|
|
|
`0x5E signaling_bitmap` is `0x0000` when no Access Document was
|
|
provisioned and `0x0005` when one was (bit 0 = "Access Document
|
|
retrievable", bit 2 = "retrieval requires step-up AID SELECT" — see
|
|
Aliro Table 8-11).
|
|
|
|
Useful flags:
|
|
- `--list-readers` — enumerate PC/SC readers, then `--reader N` to pick.
|
|
|
|
Failure modes:
|
|
- **"trust dir not found" / missing `reader.pem`** — pass the right
|
|
`--trust-dir`, or regenerate with `aliro-trustgen init`.
|
|
- **"No reader with a card"** — card not powered on the field, or the
|
|
wrong reader index. `--list-readers` helps.
|
|
- **`SW=6985` on SELECT-EXPEDITED** — card wasn't personalized (no keys
|
|
COMMITted). Run `aliro-personalize` first.
|
|
- **`signature verification failed`** after AUTH1 — the `credential_PubK`
|
|
returned by the card doesn't match `access_credential.pem` in the
|
|
trust dir. Either the card was personalized from a different trust
|
|
bundle, or the bundle on disk was regenerated post-personalization.
|
|
There is no factory-reset in v1 — re-personalize on a fresh card.
|
|
- **AES-GCM decrypt failure** — ExpeditedSKDevice mismatch; usually
|
|
means the reader and applet derived different Kdh (check that
|
|
`reader_PubK` in the trust dir matches the one that was provisioned).
|
|
|
|
This exercises the full EXPEDITED protocol end-to-end — every crypto
|
|
step the real firmware will eventually run — so a green bench-test is
|
|
strong evidence the applet is correct independently of any future
|
|
reader implementation.
|
|
|
|
### Step-Up M2 verification (`--step-up`)
|
|
|
|
```
|
|
aliro-bench-test --trust-dir ~/aliro-trust --step-up
|
|
```
|
|
|
|
Adds the Step-Up phase on top of the EXPEDITED verdict: SELECT-STEPUP
|
|
(ACCE5502) derives session keys from the cached `StepUpSK`, EXCHANGE
|
|
+ ENVELOPE + chained GET RESPONSE drive a real mdoc DeviceRequest to
|
|
the card and pull the encrypted DeviceResponse back. The harness
|
|
decrypts under `StepUpSKDevice` and asserts the embedded Access
|
|
Document round-trips byte-for-byte against the personalized blob.
|
|
|
|
Successful output appends:
|
|
|
|
```
|
|
STEP-UP M2: OK — M2 step-up verified (EXCHANGE + ENVELOPE Access Document round-trip)
|
|
```
|
|
|
|
Verified against J3R452 UID `04555A4A0B2190` on 2026-06-12 — full verdict
|
|
log at `docs/verdicts/2026-06-12-m2-pcsc-verdict.log`.
|
|
|
|
A `STEP-UP M2: FAIL` line means one of: SELECT-STEPUP didn't arm
|
|
(no preceding AUTH1), GCM tag mismatch (key/counter divergence), or
|
|
the recovered AD bytes don't match. The Expedited block above still
|
|
needs to be `OK` for any of this to run.
|
|
|
|
## Uninstall / re-install
|
|
|
|
`gp --delete <pkg_AID>` won't succeed while applet *instances* still
|
|
reference the package, and `--deletedeps` isn't recognised by every
|
|
gp.jar build. The portable sequence is to delete each instance first,
|
|
then the package:
|
|
|
|
```
|
|
java -jar gp.jar --delete A000000909ACCE5501
|
|
java -jar gp.jar --delete A000000909ACCE5502
|
|
java -jar gp.jar --delete A000000909ACCE559901
|
|
java -jar gp.jar --delete A0000009094454414C49524F02
|
|
```
|
|
|
|
Then `--load` + the three `--create` commands above to reinstall the
|
|
fresh CAP.
|
|
|
|
`--uninstall <cap>` is also supported (parses the CAP for the AIDs and
|
|
deletes them) but only if the CAP file is reachable from the current
|
|
directory, since `gp` resolves it as a path:
|
|
|
|
```
|
|
java -jar gp.jar --uninstall ./aliro-applet-j3r180.cap
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
- **"No reader with a card found"**: confirm `pcsc_scan` (Linux/macOS)
|
|
sees both reader and card. On Linux, `pcscd` must be running.
|
|
- **`SW=6985 (Conditions not satisfied)`** on Aliro commands: provisioning
|
|
hasn't been COMMITted yet, or no AUTH0 preceded an AUTH1.
|
|
- **`SW=6A82 (File not found)`** on SELECT: applet didn't install — check
|
|
`gp --list` and re-run `--install`.
|
|
- **Auth failure on `gp --install`**: card uses non-default GP keys.
|
|
Either find the issuer keys or factory-reset (vendor-specific).
|
|
- **CAP build error "unsupported bytecode `new` in clinit"**: regression
|
|
from someone adding a `static final ... = new ...()` initializer. JC
|
|
3.0.5 forbids these. Move allocation to a constructor or to lazy init
|
|
inside an instance method.
|