SCP03 Admin Shell
SCP03/ is the GlobalPlatform-style admin shell. It is the card-administration
and retrieval surface, not the SCP11 provisioning relay. Use it when the task
is secure-channel authentication, GP registry work, ETSI/3GPP filesystem
navigation, eUICC retrieval, PIN/auth diagnostics, or report/export.
On this page
Underlying concepts
This shell builds on GlobalPlatform, ETSI UICC, and 3GPP NAA.
When to use it
- opening a GP secure channel to an ISD, SSD, or MNO-SD
- listing applications, packages, and security domains
- navigating the MF / DF / ADF / EF tree
- reading, updating, and reporting EF content
- running GSM, USIM, and ISIM
AUTHENTICATEdiagnostics - generating a full filesystem export or YAML-oriented report
- comparing a live card against a stored "gold" profile snapshot
Do not use it as a relay provisioning shell. Relay work lives in SCP11/live.
Direct local ISD-R provisioning lives in
SCP11/local_access.
Entry points
python -m SCP03
python -m SCP03 --cmd "AUTH-SD; APPS; EXIT"
yggdrasim-scp03
yggdrasim-scp03 --cmd "AUTH-SD; APPS; EXIT"
python main/main.py and pick the SCP03 entry.
Command surface, grouped
Secure channel and session
| Command | Purpose |
|---|---|
AUTH-SD |
authenticate the currently selected Security Domain |
AUTH-ISD |
authenticate the Issuer Security Domain |
AUTH-SSD |
authenticate a Supplementary Security Domain |
RESELECT |
reselect the active applet/SD |
Registry and content management
| Command | Purpose |
|---|---|
APPS |
enumerate applications |
LIST |
list contents of the active selection |
SELECT <AID or path> |
select by AID or by ETSI path |
PUT-KEY |
install or rotate a key set on the active SD |
Filesystem
| Command | Purpose |
|---|---|
SELECT <FID or path> |
select an EF, DF, or ADF |
READ |
read the selected EF |
UPDATE |
update the selected EF |
DUMP-FS |
export the entire filesystem |
eUICC retrieval
Under the selected ISD-R, the shell can drive:
GetProfilesInfoGetEuiccConfiguredDataGetEIDGetEuiccInfo1GetEuiccInfo2GetRATRetrieveNotificationsListGetEimConfigurationDataGetCerts
These land under wizarded and direct commands inside the SCP03 shell.
PIN and authentication
| Command | Purpose |
|---|---|
VERIFY, CHANGE, DISABLE, ENABLE, UNBLOCK |
CHV and PUK handling |
AUTH-GSM, AUTH-USIM, AUTH-ISIM |
AUTHENTICATE helpers for each NAA |
Reporting
| Command | Purpose |
|---|---|
| report mode | combined filesystem + eUICC report generation |
DUMP-FS |
full filesystem export |
| gold-snapshot workflow | live-vs-gold diff against a stored snapshot |
Raw APDU entry
A line that matches no command is transmitted as an APDU. A data field longer
than a one-byte Lc can announce is carried as a STORE DATA block sequence
instead of being rejected: P1 marks every block but the last as "more blocks"
and P2 counts the blocks (GlobalPlatform Card Specification v2.3.1 Table
11-89). The same applies to a line read from a RUN / SCRIPT file.
| Input on the line | Sent |
|---|---|
| a command APDU that already fits | unchanged |
a command APDU with an extended Lc over 255 bytes |
one STORE DATA block per 255 bytes |
| a four-byte header followed by over 255 raw bytes | the same, reusing the header's CLA, P1 and starting block number |
| a bare BER-TLV command payload with no header | wrapped as STORE DATA on the logical channel the session last used |
Only STORE DATA and LOAD define a block sequence, so any other instruction carrying an extended length is passed to the card untouched.
HIL / diagnostics
| Command | Purpose |
|---|---|
EXPORT-KEYBAG [Path.keys.json] [Label] |
dump the active SCP03 session keys (S-ENC, S-MAC, S-RMAC, SSC, chaining value) and the active target AID into a keybag JSON for offline HIL pcap decryption |
TRACE START [File] / TRACE STOP / TRACE STATUS |
copy every command from START to STOP, run with debug output, into a log file; the prompt reads TRACE meanwhile |
<command> --log <File> |
the same for one command line (see Capture commands to a file) |
See Session key export below and the HIL Bridge offline replay flow.
Runtime dependencies
- a PC/SC reader with the card inserted
- live GP key material under
Workspace/SCP03/(keyset, AID choices) - the shared SQLite inventory for SCP03 per-card state
- optional
gpgif the inventory crypto envelope is enabled
State the shell writes
| Location | Contents |
|---|---|
state/device_inventory.sqlite3 |
per-ICCID and per-EID SCP03 state |
Workspace/SCP03/aid.txt |
AID choices (plain file for diff review) |
Workspace/SCP03/fids.txt |
FID quick-select list |
Workspace/SCP03/binds.json |
custom bind macros |
Workspace/SCP03/keys.ini |
legacy import source for keysets |
Common recipes
Open an SD, list apps, read IMSI
[APDU] > AUTH-SD
[A0...00] > APPS
[A0...00] > SELECT USIM/IMSI
[A0...00] > READ
One-shot dump of the whole filesystem
python -m SCP03 --cmd "AUTH-SD; DUMP-FS; EXIT"
Authenticate a USIM
[A0...00] > SELECT ADF.USIM
[A0...00] > AUTH-USIM <RAND> <AUTN>
The response carries RES, CK, IK, or an AUTS on SQN mismatch.
Gold-profile diff
After persisting a gold snapshot via the shell:
[APDU] > GOLD-DIFF
The diff surfaces EF-level changes since the stored baseline.
Session key export
EXPORT-KEYBAG snapshots the currently-authenticated SCP03 session
into a keybag JSON compatible with the HIL Bridge offline-replay
decoder.
[APDU] > AUTH-SD
[A0...00] > EXPORT-KEYBAG Workspace/hil/captures/session-2026-04-20.keys.json case-1234
Arguments (both optional):
OutputPath.keys.json-- destination file. Defaults to a timestamped path under the SCP03 workspace when omitted.Label-- free-form identifier written to the entry for operator cross-referencing (ticket id, serial, pcap name, etc.).
The handler refuses cleanly if:
- there is no active card session
- the session exists but has not authenticated (no derived keys yet)
Written fields (per entry):
protocol:"SCP03"aid_hex: current target AID (fromgp_ctrl.target_aid)s_enc_hex/s_mac_hex/s_rmac_hex: session keys at time of exportssc_hex/chaining_value_hex: SCP03 state at time of exportlabel: the operator-provided label
See HIL Bridge -- Keybag JSON schema for the complete file structure and Replay a HIL pcap offline for how the keybag feeds into the decoded-APDU TUI.
Pitfalls
- Wrong keyset returns
6982beforeEXTERNAL AUTHENTICATEcompletes. CheckWorkspace/SCP03/keys.inior the migrated inventory state. - Selecting an EF that is not active returns
6A82. Walk from3F00when in doubt. PUT-KEYwithout a live, authenticated session returns6985.- eUICC retrieval commands require that the selected SD is the
ISD-Ror an SD authorized to issue them. Use the wizard when in doubt.
In-shell documentation
SCP03 has an in-session guide and a grouped help surface.
GUIDEopens the topic menuGUIDE GP,GUIDE ETSI,GUIDE GSMA,GUIDE INSTALL,GUIDE SECURITY,GUIDE OTA,GUIDE CONFIG,GUIDE SAIP,GUIDE SUCI,GUIDE CLIfor per-topic referencesHELPprints the grouped command reference
The same content is mirrored under Shell Guides for reading outside the terminal.