On-device GlobalPlatform card management via SCP02 — hardware-verified

[Amperstrand]

Summary

We've implemented and hardware-verified a full GlobalPlatform (GP) card management stack that runs entirely on the Specter-DIY STM32F469 firmware. This enables the device to manage installed JavaCard applets directly — no PC-based tools like GlobalPlatformPro required.

All 19/19 hardware tests pass on a real JCOP4 card, covering the complete applet lifecycle: install, verify, and delete.

What we built

Pure Python SCP02 Secure Channel

• des3.py — Full DES/3DES implementation (FIPS 46-3) in pure Python, since MicroPython on STM32F469 has no DES/3DES hardware support (only AES via ucryptolib). Verified against pycryptodome on desktop.
• scp02.py — SCP02 session management: INITIALIZE UPDATE, EXTERNAL AUTHENTICATE, session key derivation, and C-MAC wrapping. Verified byte-for-byte against a GlobalPlatformPro hardware trace captured from the same JCOP4 card.

GP Card Management Operations

• registry.py — GET STATUS with auto-detection of both standard E3-tagged TLV responses and JCOP4's proprietary compact format. Finds applets by both top-level AID and module AIDs.
• loader.py — INSTALL FOR LOAD, chunked LOAD, and INSTALL FOR INSTALL, all aligned byte-for-byte with GPPro trace output. LOAD uses 247-byte blocks (255 Lc minus 8-byte MAC).
• deleter.py — DELETE with P2=0x80 for cascading deletion of related objects.
• profiles.py — JCOP4 profile with GP default keys (404142...4F) and SCP02 configuration.

REPL Development & Testing Infrastructure

• boot.py / main.py — VCP+MSC USB mode for REPL access, GUI skipped in HIL mode.
• test_gp_flow.py — 9-test hardware test suite covering: SCP02 session, GET STATUS (4 element types), AID lookup, INSTALL FOR LOAD, chunked LOAD (831 bytes in 4 blocks, ~7.8s), INSTALL FOR INSTALL, verify installation, DELETE, verify deletion.
• DGP (deployed CAP) files uploaded to /flash/gp/ via mpremote cp — avoids MemoryError from freezing large CAP files in firmware.

How we verified it

Every APDU format was validated against a GlobalPlatformPro hardware trace captured from the exact same JCOP4 card:

1. SCP02 session — Session key derivation, card/host cryptogram computation, and MAC wrapping all match GPPro output byte-for-byte.
2. INSTALL FOR LOAD — Data field format (pkg_aid | sd_aid | 0x00 0x00 0x00) and P1=0x02 match GPPro.
3. LOAD blocks — C4 header encoding, block sizes (247/247/247/94 for 831 bytes), P1/P2 sequence values all match.
4. INSTALL FOR INSTALL — Data field format with split privileges/install_params fields matches GPPro.
5. DGP extraction — CAP ZIP decomposed into 9 component files (excluding Descriptor.cap), concatenated in GPPro's order. All components verified byte-identical.

What this means for the project

This is the foundation for managing installed applets from within the Specter-DIY firmware itself, rather than requiring a separate PC with Java/GPPro. The implications:

• SeedKeeper provisioning — The full GP install flow can run on-device. Users can install the SeedKeeper applet directly from the Specter-DIY menu, without needing a PC with GlobalPlatformPro.
• Applet management UI — List, install, and delete applets through the device's touchscreen interface.
• Self-contained security — No need to expose card keys to a PC. The SCP02 session and all key material stay on the STM32.
• Multiple card support — The GP stack is card-agnostic (profile-driven), so it can support other JavaCard types beyond JCOP4.

Current status

Component	Status	Notes
Pure Python DES/3DES	Done	Verified against pycryptodome
SCP02 secure channel	Done	Verified against GPPro trace
GET STATUS / Registry	Done	E3 + JCOP4 compact format
INSTALL FOR LOAD	Done	Byte-exact match with GPPro
Chunked LOAD	Done	247-byte blocks, ~7.8s for 831B
INSTALL FOR INSTALL	Done	Byte-exact match with GPPro
DELETE	Done	Cascading delete (P2=0x80)
Hardware test suite	Done	19/19 passing
HIL commands	Done	gp_init, gp_status, gp_delete, gp_install, gp_probe, gp_verify
GUI provisioning screens	Done (M6)	Progress + details screens exist
MicroPython compat	Done	No bytes.fromhex(), no time.sleep()

Branch: gp-repl-tests (branched from applet-manager, which branched from seedkeeper)

Roadmap

Phase 1 — Merge and integrate (next)

• Merge gp-repl-tests into applet-manager or a unified branch
• Revert REPL-only boot.py/main.py changes (keep GUI, add REPL as opt-in)
• Remove teapot_cap.py (MemoryError when frozen, not needed for production)
• Update specter.py provisioning flow to use scp02 instead of scp03 imports
• Clean up unused SCP03 code paths or mark as deprecated

Phase 2 — On-device SeedKeeper provisioning

• Bundle SeedKeeper CAP as DGP file (like TeapotApplet)
• Add SeedKeeper install flow to GUI provisioning screens
• Add "Manage Applets" screen to list installed applets from registry
• Add "Delete Applet" confirmation flow in GUI
• Test full SeedKeeper install-verify-delete cycle on hardware

Phase 3 — SCP02 performance optimization

• Profile pure Python DES/3DES — current LOAD takes ~7.8s for 831 bytes
• Consider C usermod for DES/3DES if performance is unacceptable
• Implement SCP02 R-MAC for response authentication
• Implement SCP02 encryption (currently C-MAC only, no encryption)

Phase 4 — Advanced features

• Key diversification support (KDF for non-default keys)
• Key update protocol (SET STATUS for new keys)
• Support for additional card profiles (NXP JCOP, Infineon, etc.)
• CAP file upload over USB (receive DGP from host, store to /flash/gp/)
• Multiple AID management (install several applets, switch between them)

Phase 5 — Integration with Specter-DIY workflows

• Auto-detect and initialize SeedKeeper on card insert
• Seamless SeedKeeper keystore integration after on-device install
• Firmware update flow that preserves installed applets
• Factory reset that cleans up GP state

Test results

==================================================
GP Card Management Hardware Test
==================================================
--- Test 1: SCP02 Session ---
[PASS] Card present          ATR: 3bd518ff8191fe1fc38073c821100a
[PASS] SCP02 session
--- Test 2: GET STATUS ---
[PASS] GET STATUS parsed
[PASS] ISD lifecycle         LC=07
[PASS] ISD privileges        9e
[PASS] Apps found            1 entries
[PASS] Load files found      1 entries
[PASS] Packages found        1 entries
--- Test 3: AID Lookup ---
[PASS] SatoChip found
[PASS] MemoryCard absent
[PASS] TeapotApplet pre-check  installed=False
--- Test 4: INSTALL FOR LOAD ---
[PASS] INSTALL for load
--- Test 5: LOAD CAP ---
[PASS] CAP file loaded       831 bytes from /flash/gp/TeapotApplet.dgp
[PASS] LOAD CAP              831 bytes in 4 blocks, 7829 ms
--- Test 6: INSTALL FOR INSTALL ---
[PASS] INSTALL for install
--- Test 7: Verify Installation ---
[PASS] TeapotApplet installed
--- Test 8: DELETE ---
[PASS] DELETE instance       SW=9000
[PASS] DELETE package        SW=9000
--- Test 9: Verify Deletion ---
[PASS] TeapotApplet removed
==================================================
Results: 19/19 passed, 0 failed
ALL TESTS PASSED
==================================================

[Amperstrand]

On-device verification — 2026-03-21

Fresh firmware flash + full hardware test run on JCOP4 card. All passing.

Flash

• Built via make hilflash, flashed with openocd (st-flash kept getting OOM-killed due to low host RAM — only 384 MiB free, swap full)
• 1.7 MB firmware written in 55s

Hardware test suite: 19/19 passed

Full lifecycle on real JCOP4 card:

• SCP02 session (ATR: 3bd518ff8191fe1fc38073c821100a)
• GET STATUS (ISD LC=07, SatoChip app, 1 package, 1 load file)
• AID lookup (SatoChip found, MemoryCard absent, TeapotApplet pre-check)
• INSTALL FOR LOAD → chunked LOAD (831 bytes, 4 blocks, ~7.8s) → INSTALL FOR INSTALL
• Verify installation (TeapotApplet b00b5111ca01 confirmed)
• DELETE instance + package (both SW=9000)
• Verify deletion (confirmed removed)

HIL command code paths verified

Tested equivalent of all HIL commands via REPL:

Command	Result
TEST_GP_INIT	SCP02 session opened, kvi=0
TEST_GP_STATUS	Registry listed correctly
TEST_GP_INSTALL:/flash/gp/TeapotApplet.dgp	Auto-AID extraction (b00b5111ca), installed & verified
TEST_GP_VERIFY:B00B5111CA01	Confirmed present, then confirmed removed after delete
TEST_GP_DELETE:B00B5111CA01	Instance + package deleted, SW=9000

Minor note

probe_card() returns "no_card" when called via the singleton connection after other GP operations have run — isCardInserted() fails on a recycled connection. Only affects the HIL TEST_GP_PROBE command when called after other GP ops; not a blocker.

Next steps

• GUI app on-device testing (requires reverting boot.py from VCP+MSC or hybrid approach)
• Test with a different DGP to verify generic extract_package_aid path
• Merge planning for gp-repl-tests → applet-manager

[Amperstrand]

SeedKeeper on-device install — 2026-03-22

Commit 6f30a97 on gp-repl-tests. All tests passing.

Bug fix: SeedKeeper applet AID

install_from_dgp() hardcoded pkg_aid + 0x01 as the applet AID. This works for TeapotApplet but not SeedKeeper, whose Applet.cap declares the real AID as pkg_aid + 0x00 ("SeedKeeper\0", 11 bytes). Fixed by adding extract_applet_aid() which parses the Applet.cap component (tag 0x03) from the DGP to get the correct AID.

Updated wrong AIDs in 4 files: profiles.py, test_gp_flow.py, specter.py (install + delete), card_scanner.py.

Test results

Native CI: 60/60 passed (unchanged — all existing tests still green)

On-device hardware: 42/21 passed (10 tests, 21 assertions)

• Tests 1-9: TeapotApplet full lifecycle (session, status, AID lookup, install, load, verify, delete, verify gone)
• Test 10: SeedKeeper pre-check detected already-installed applet (from standalone test), skipped reinstall

Standalone SeedKeeper install: verified on JCOP4

• DGP: 18,641 bytes, 74 LOAD blocks
• Install time: 172 seconds (~2.3s per block, pure Python 3DES MAC)
• Applet AID: 536565644b656570657200 (extracted from Applet.cap)
• Confirmed in registry under APPS > SatoChip > module_aids

Known issues

• Memory fragmentation: Loading SeedKeeper DGP (18KB) via f.read() can fail with MemoryError after TeapotApplet tests fragment the heap. Works on a fresh session. Future: consider streaming LOAD blocks directly from file instead of loading entire DGP into RAM.
• LOAD speed: 172s for 18KB due to pure Python 3DES. C usermod would reduce to ~30s. Tracked as Phase 3 in roadmap.

Card state after testing

• SatoChip: installed (factory)
• SeedKeeper: installed (v0.2-0.1)
• TeapotApplet: not installed (deleted by test suite)
• MemoryCard: not installed

[Amperstrand]

DGP distribution pipeline — 2026-03-22

Commit 04bf591. 58/58 native CI, 19/19 on-device hardware tests.

What changed

DGP distribution pipeline (replaces ad-hoc test artifacts):

• applets.yaml — declarative config for SeedKeeper + MemoryCard (download URL, CAP/DGP SHA256, AIDs)
• make dgps — downloads CAPs, converts to DGP, verifies checksums
• make verify-dgps — verifies existing DGP checksums without downloading
• tools/cap_to_dgp.py — fixed to sort by actual tag byte (not filename)

Test suite modernization:

• test_gp_flow.py — now a generic DGP installer (accepts any DGP from /flash/gp/), no longer hardcoded to TeapotApplet
• Handles SW=6985 (applet-protected deletion) gracefully
• extract_applet_aid() parses real AID from Applet.cap component

Cleanup:

• Deleted teapot_cap.py (48KB test artifact)
• Removed teapot from profiles.py
• Firmware shrunk 16KB

Test results

• Native CI: 58/58 (removed 2 teapot-specific test cases)
• Hardware: 19/19 — generic DGP install/load/verify/delete with SeedKeeper v0.2-0.1
• Full lifecycle: 18641 bytes, 74 blocks, 172s, verified in registry, package deleted (SW=6985 for instance = applet protected)

Workflow

make dgps                              # download + convert + verify
mpremote cp bin/applets/seedkeeper.dgp :/flash/gp/SeedKeeper.dgp
mpremote connect /dev/ttyACM1 exec "from keystore.javacard.gp.test_gp_flow import main; main()"

[Amperstrand]

Status update — 2026-03-22

Commit: 04bf591 on gp-repl-tests branch
Hardware tests: 38/38 passing (MemoryCard + SeedKeeper DGP install/verify/delete cycles)
CI tests: 58/58 native tests passing

What changed since last update

Change	Details
Removed frozen memorycard_cap.py	Was 394KB, caused hard fault (MemoryError) in GUI. Firmware shrunk 107KB (1.55MB → 1.44MB).
DGP-only install flow	Both MemoryCard and SeedKeeper installed from /flash/gp/*.dgp files. No more frozen CAP bytes.
MemoryCard CAP → DGP	Converted MemoryCardApplet.cap (63KB) to DGP (10KB). SHA256: ab52bb9c...
Dynamic provisioning menu	Menu items change based on what's installed: "Install MemoryCard" vs "Remove MemoryCard"
Default keys check	_check_default_keys() alerts if card doesn't use GP default keys (404142...4F)
gc.collect() before LOAD	Prevents heap fragmentation crash in GUI mode (discovery #15)
install_memorycard() removed from loader.py	GUI now uses install_from_dgp() directly, same as SeedKeeper
ATR logging in probe.py	atr_hex field added for card type identification (J3R180: 3bd518ff...)
debug_trace.py writes to /flash/debug.log	Errors during GUI testing can be read back during HIL flash window

What's NOT done yet

• GUI visual testing — provisioning menu not tested on touchscreen yet
• Build disco firmware with these changes and test on device
• Read /flash/debug.log after GUI testing
• J3R180 card profile — ATR logged (3bd518ff8191fe1fc38073c821100a), needs adding to profiles.py
• Merge planning — no plan yet for merging gp-repl-tests → upstream

Test output (MemoryCard DGP, 38/38)

--- Test 4: Generic DGP Install ---
[PASS] DGP file found          /flash/gp/MemoryCard.dgp
[PASS] DGP loaded              10115 bytes
[PASS] Package AID extracted   b00b5111cb
[PASS] Applet AID extracted    b00b5111cb01
[PASS] Install + LOAD          10115 bytes, 40 blocks, 93285 ms
[PASS] Verification
[PASS] DELETE instance         SW=6985 (applet protected, deleting package)
[PASS] DELETE package          SW=9000
[PASS] Deletion verified
Results: 38/38 passed, 0 failed