Load certificates & config
Bring operator-owned material -- certificates, private keys, secure-channel keysets, simulator personality files, identity records, encryption envelopes, and protected diagnostic inputs -- into YggdraSIM without touching any in-tree starter material.
On this page
This page is the task-driven mirror of the canonical operator
guide
guides/CONFIGURATION_AND_CERTIFICATES.md
at the repository root. The schemas, sidecar shapes, fallback rules,
and selection orders are normative there; this page picks the most
common flows and walks through them as numbered recipes.
Bundled Workspace/ material is starter material
Everything that ships under Workspace/, SCP11/SGP.26_test_Certs/,
and the state/inventory_crypto.json defaults is starter material.
It is there so the toolkit can boot, run the unit tests, and execute
a first-light download against the in-tree fake eIM and Local
SM-DP+. Replace, override, or relocate it before any non-test use.
Decision tree
| You have ... | Jump to |
|---|---|
operator DPauth / DPpb cert + key for LOAD-PROFILE against ISD-R |
Recipe 1 |
| operator DPauth / DPpb cert + key for the eIM local profile-loading path | Recipe 2 |
| operator-issued eIM signing certificate | Recipe 3 |
| your own simulated card identity (EID, ATR, AIDs, default DP, CI PKID) | Recipe 4 |
| your own simulated default eIM identity used on first boot | Recipe 5 |
| your own SCP03 / SCP80 keysets | Recipe 6 |
| SUCI Profile A / B home-network keys | Recipe 7 |
| K / OPc / AMF / SQN / MCC / MNC / RID for a 5G AKA test subscriber | Recipe 8 |
| ShS-ENC / ShS-MAC / DEK from an EUM database for a failing PCAP | Recipe 9 |
| a need to encrypt every persisted secret at rest | Recipe 10 |
| a need to relocate or freeze the writable runtime root | Recipe 11 |
Prerequisites
- A working YggdraSIM install (
yggdrasim --doctorexits cleanly). - A directory outside the repository to hold operator-owned material
(the recipes refer to it as
~/yggdra-secrets, but the layout is yours to choose). - For recipes that touch the inventory:
gpgwith at least one recipient available.
Recipe 1: Bring-your-own RSP certs (local-access)
Replace the bundled SGP.26 test fixtures used by LOAD-PROFILE against
ISD-R with operator-owned DPauth / DPpb material.
-
Drop the operator material into the local-access cert zone.
cp ~/yggdra-secrets/op-alpha-auth.cert.der SCP11/local_access/certs/ cp ~/yggdra-secrets/op-alpha-auth.key.pem SCP11/local_access/certs/ cp ~/yggdra-secrets/op-alpha-pb.cert.der SCP11/local_access/certs/ cp ~/yggdra-secrets/op-alpha-pb.key.pem SCP11/local_access/certs/ -
Author a sidecar metadata file beside each certificate. The selector reads either
<certificate>.meta.jsonor<stem>.meta.json.{ "role": "auth", "private_key_path": "op-alpha-auth.key.pem", "root_ci_pkid": "F54172BDF98A95D65CBEB88A38A1C11D800A85C3", "server_address": "local.smdpp.operator.example" } -
Verify the inventory with the local-access shell's
CERTSverb (aliasSMDP-CERTS).yggdrasim-scp11-local-access --cmd "STATUS; CERTS; EXIT"Expected: the new records appear with
source=local_override, they win over the SGP.26 bundle, and the active card'sallowed_ci_pkidsaccept the chosenroot_ci_pkid. Add--jsonor--yamltoCERTSfor a machine-readable inventory dump. -
Run a download against a card.
yggdrasim-scp11-local-access --cmd "LOAD-PROFILE; EXIT"
Reference. Selector code: SCP11/local_access/cert_store.py -- the
full sidecar schema (every field) lives in the canonical operator
guide.
Recipe 2: Bring-your-own RSP certs (eim-local)
Identical drop-in pattern as Recipe 1, but the destination is
SCP11/eim_local/certs/. The eim-local shell mirrors the selected
DPauth server_address into the eIM activation code when the package
does not pin a different smdp_address.
The eim-local shell does not expose a dedicated DPauth/DPpb inventory verb (the selector is exercised silently when the flow runs). Verify functionally:
yggdrasim-scp11-eim-local --cmd "STATUS; LOAD-PROFILE; EXIT"
Recipe 3: Load an operator eIM signing certificate
Replace the bundled fake-eIM signing certificates with operator-issued
material for ADD-INITIAL-EIM / ADD-EIM.
-
Drop the certificate (and matching key, if held in-band) into
SCP11/eim_local/certs/eim/. The mirror atWorkspace/LocalEIM/certs/eim/is consulted by the same selector. -
Author a sidecar metadata file. The eIM cert store classifies files as
signing,tls, orci; spell out the role explicitly so the selector does not have to guess.{ "role": "signing", "private_key_path": "op-alpha-eim.key.pem", "root_ci_pkids": ["F54172BDF98A95D65CBEB88A38A1C11D800A85C3"], "subject_cn": "operator-alpha.eim.example", "curve": "NIST" } -
Verify with the eim-local shell's
EIM-CERTSverb.yggdrasim-scp11-eim-local --cmd "STATUS; EIM-CERTS; EXIT"Expected:
source=local_eim_dir,role=signing, the chosenroot_ci_pkidsintersect the active eIM identity's preferred CI list. Add--jsonor--yamlfor machine-readable output, or pass a package path / cert path positional to preview how the selector would resolve a specific call site.
Reference. Selector code: SCP11/eim_local/eim_cert_store.py.
Recipe 4: Replace the simulator personality
Set the EID, ATR, AIDs, default SM-DP+ address, eUICC-side allowed CI list, and on-card SCP03 / SCP80 keysets used by the simulated card.
-
Author the file outside the repository.
{ "eid": "89...your 32 hex digits...", "atr_hex": "3B9F96801FC78031A073BE21136743200718000001A5", "default_dp_address": "rsp.operator.example", "root_ci_pkid_hex": "F54172BDF98A95D65CBEB88A38A1C11D800A85C3", "isdr": { "aid": "A0000005591010FFFFFFFF8900000100", "label": "ISDR" }, "ecasd": { "aid": "A0000005591010FFFFFFFF8900000200", "label": "ECASD" }, "mno_sd": { "aid": "A000000151000000", "label": "MNO-SD" }, "scp03_keys": { "kenc_hex": "...", "kmac_hex": "...", "dek_hex": "...", "kvn": 48 }, "scp80_security": { "spi": "1621", "kic": "15", "kid": "15", "tar": "B00000", "key_enc_hex": "...", "key_mac_hex": "..." }, "configured_data": { "root_smds_address": "root-smds.example.com", "additional_root_smds_addresses": ["smds2.example", "smds3.example"], "allowed_ci_pkids_hex": ["F54172BDF98A95D65CBEB88A38A1C11D800A85C3"], "ci_list_hex": ["F54172BDF98A95D65CBEB88A38A1C11D800A85C3"] } } -
Point the simulator at it.
export YGGDRASIM_SIM_ISDR_CONFIG=~/yggdra-secrets/operator-isdr.json -
Boot the simulator and confirm the load. The unified launcher's read-only preflight covers the simulator boot path; an SCP03 status probe against the simulator confirms the file is being consumed:
yggdrasim --doctor YGGDRASIM_CARD_BACKEND=sim yggdrasim-scp03 --cmd "STATUS; EXIT"
The original Workspace/SIMCARD/isdr_config.json is untouched. Drop
the env var to fall back to the bundled starter material.
Recipe 5: Replace the simulator default eIM identity
Used on first boot, when the card's BF55 eIM identity has not yet
been programmed. Authoring follows the same pattern as Recipe 4, with
the override env var YGGDRASIM_SIM_EIM_IDENTITY and the schema below:
{
"display_name": "Example lab",
"eim_id": "2.25....",
"eim_id_type": "oid",
"eim_fqdn": "eim.operator.example",
"eim_endpoint": "https://eim.operator.example/gsma/rsp2/asn1",
"euicc_ci_pk_id": "F54172BDF98A95D65CBEB88A38A1C11D800A85C3",
"eim_public_key_cert_path": "/path/to/eim_signing.pem",
"trusted_tls_cert_path": "/path/to/eim_tls.pem"
}
euicc_ci_pk_id must match a CI SKI in the simulator's
configured_data.allowed_ci_pkids_hex.
Recipe 6: Load SCP03 and SCP80 keysets
Two stages: file-based defaults, then the per-card SQLite inventory (authoritative).
-
File-based default (boot). Edit
Workspace/SCP03/keys.ini. The four secret fields are 16-byte hex.[KEYS] enc = ...your 32 hex chars... mac = ...your 32 hex chars... dek = ...your 32 hex chars... kvn = 30 aid = A000000151000000 adm = 3132333435363738kvnmust match the on-card keyset version (the simulated card'sisdr_config.json.scp03_keys.kvn); a mismatch surfaces asINITIALIZE UPDATEreturning6982/6A88. -
Per-card inventory (runtime). Connect the SCP03 admin shell to a card; the shell auto-binds to the active ICCID and seeds a per-card record on first use. To rotate the active card's keyset in place, use the
CONFIGwizard:SCP03> CONFIG ... wizard prompts for ENC / MAC / DEK / KVN / AID / ADM ... SCP03> SHOW SCP03> EXITCONFIGwrites through to both the module-level state and the per-ICCID inventory namespace (iccid/<ICCID>/scp03); on the next connect to the same card, that record is loaded ahead ofkeys.ini. Delete the[KEYS]section inkeys.inionce the per-card record is the source of truth. -
SCP80 OTA parameters. The SCP80 shell follows the same pattern with lowercase verbs:
yggdrasim-scp80 --cmd "iccid <ICCID>; set kic <16-byte-hex>; set kid <16-byte-hex>; set kic_indicator <hex>; set kid_indicator <hex>; show; quit"Slot names follow ETSI TS 102 225 §5.1.1:
kic/kidare the 16-byte ciphering and integrity keys;kic_indicator/kid_indicatorare the 1-byte indicator bytes that select algorithm plus key index in the Command Packet header. Legacykey_enc/key_macand 2-bytekic/kidvalues are auto-migrated on load.setupdates the active SCP80 config;showprints the resolved values. The per-ICCID record is persisted toiccid/<ICCID>/scp80and is preferred over the legacyWorkspace/SCP80/ota_config.inion the next bind. -
Encrypt the inventory at rest. Continue with Recipe 10.
Recipe 7: Load SUCI keys
The SUCI helper holds one active key file at a time. The path is resolved relative to the runtime workspace.
yggdrasim-suci-tool --cmd "USE keys/operator-alpha.key; STATUS; DUMP; EXIT"
secp256r1 (Profile A) and curve25519 (Profile B) are supported.
The TOOL verb prints the active suci-keytool binary path; override
it with TOOL <path> when the binary lives outside the standard
search.
Custodial reminder
SUCI key files are 32 bytes of long-term home-network material. Keep them at 0600, never share across operators, and rotate per the home-network's policy. They never belong inside the inventory encryption envelope -- they are operator key material, not stored application state.
Recipe 8: Seed a YggdraCore subscription
The in-process AUSF / AAnF stub holds subscribers in memory only. There is no on-disk format.
from Tools.YggdraCore.subscription_store import get_default_subscription_store
store = get_default_subscription_store()
store.upsert(
supi="imsi-001010000000001",
k=bytes.fromhex("0123456789ABCDEFFEDCBA9876543210"),
opc=bytes.fromhex("CD63CB71954A155A5DC83A7BFD11A41C"),
amf=b"\x80\x00",
sqn=b"\x00\x00\x00\x00\x00\x01",
mcc="001",
mnc="01",
routing_indicator="0",
akma_enabled=True,
)
K and OPc are exactly 16 bytes; AMF is 2; SQN is 6; MCC is
3 digits; MNC is 2 or 3 digits; RID is 1..4 digits. The store
auto-bumps SQN on every successful authentication (TS 33.102 Annex
C) and refuses overflow.
For BYO Open5GS (YGGDRASIM_5GCORE_MODE=byo), the same record shape
provisions a real subscriber DB through pymongo; pass the Mongo URI
and database name to Open5gsBridge directly.
Recipe 9: Attach EUM session keys to a pcap
Use this to drive the bundled Lua dissector against a stuck profile download.
-
Write the repository.
yggdrasim-eum-diag store-keys \ --iccid 8988000000000000001 \ --shs-enc AABBCCDDEEFF00112233445566778899 \ --shs-mac 00112233445566778899AABBCCDDEEFF \ --dek 0F0E0D0C0B0A09080706050403020100 \ --keys-out ~/secrets/eum-keys.jsonThe writer chmods the file to
0600on POSIX; any group/other-readable mode is reported on load. -
Run the dissector against the failing pcap, reusing the stored repository.
export YGGDRASIM_EUM_SESSION_KEYS=~/secrets/eum-keys.json yggdrasim-eum-diag inject-keys \ --bundle-file ~/secrets/eum-keys.json \ --pcap ~/captures/failing-example.pcapnginject-keysaccepts either the per-bundle CLI flags (--iccid / --shs-enc / --shs-mac / --dek) or--bundle-filepointing at an existing repository JSON. The bundled Lua dissector reads the same file fromYGGDRASIM_EUM_SESSION_KEYS, so exporting the env var lets additionaltshark/ Wireshark sessions decode the same pcap without re-runninginject-keys. -
For an offline BPP decode without the pcap, use:
yggdrasim-eum-diag decode-bpp \ --bpp ~/captures/bf36.der \ --keys ~/secrets/eum-keys.json
The repository is keyed by ICCID, so a single file may carry every session under investigation.
Recipe 10: Turn on inventory encryption
The full step-by-step recipe lives at
enable-inventory-encryption.md. The
short form:
- Identify a recipient:
gpg --list-keys --with-colons | rg '^uid' -
Edit
state/inventory_crypto.json:{ "enabled": true, "provider": "gpg", "gpg": { "binary": "gpg", "recipients": ["YOUR_FPR_HERE"] } } -
Trigger any inventory write (running the SCP03 shell against a card and exiting cleanly is enough -- it will write the per-card
scp03namespace), then confirm the on-disk bytes start with-----BEGIN PGP MESSAGE-----. - Verify with
yggdrasim --doctor(thegpgprobe must reportok); the resulting on-disk bytes are the actual proof the envelope took.
plaintext_fallback_writes is the strict-mode escape hatch -- leave it
false so the writer refuses to drop plaintext on disk while the GPG
provider is ready.
Recipe 11: Relocate the runtime root
export YGGDRASIM_RUNTIME_ROOT=/var/lib/operator-alpha/yggdra
mkdir -p "$YGGDRASIM_RUNTIME_ROOT"
yggdrasim --doctor
The doctor's workspace probe confirms the resolved root and that
plugins/, state/, and Workspace/ exist underneath it.
The override is persisted to ~/.yggdrasim/env_overrides.json so the
choice survives across runs without creating a chicken-and-egg with
the resolver. Source checkouts default to the repository root; frozen
builds default to a sibling YggdraSIM-data directory next to the
executable, falling back to ~/YggdraSIM-data.
Bring-your-own keys checklist
A concise pre-flight list before pushing any operator material into a non-test environment:
- DPauth / DPpb pairs. Drop into
SCP11/<flavor>/certs/with sidecar.meta.json. Verify with the local-access shell'sCERTSverb (or, for eim-local, by runningLOAD-PROFILEand checking the result). - eIM signing certificates. Drop into
SCP11/eim_local/certs/eim/. Verify with the eim-local shell'sEIM-CERTSverb. - Simulator personality. Author externally; point
YGGDRASIM_SIM_ISDR_CONFIG/YGGDRASIM_SIM_EIM_IDENTITYat the files. - SCP03 keysets. Migrate
keys.iniinto the per-card SQLite inventory; turn on inventory crypto; delete the[KEYS]section. - SCP80 keysets. Per-ICCID inventory record; drop legacy
ota_config.ini. - SUCI keys. Author per home-network. Never reuse across operators.
- YggdraCore subscribers. Provision through
upsert(...)or the BYO Open5GS bridge. Stub state is intentionally non-persistent. - EUM session keys. Author with
yggdrasim-eum-diag store-keys, chmod 0600, pointYGGDRASIM_EUM_SESSION_KEYSat the file. - HIL keybags. Drop next to the pcap; auto-discovery picks them up. Delete after use.
- Inventory crypto. Turn on before any non-test card is bound.
- Plugins. Leave disabled unless a local plugin is required. Opt
in with
YGGDRASIM_ALLOW_PLUGINS=1; hard-lock attestation builds withYGGDRASIM_DISALLOW_PLUGINS=1. - Workspace seed material. Treat every committed sample as a test fixture. Replace, override, or relocate before non-test use.
Validation
For each recipe above, the canonical "did it stick?" probes are:
| Surface | Probe |
|---|---|
| SCP11 RSP certs | yggdrasim-scp11-local-access --cmd "STATUS; CERTS; EXIT" |
| eIM signing certs | yggdrasim-scp11-eim-local --cmd "STATUS; EIM-CERTS; EXIT" |
| Simulator personality | YGGDRASIM_CARD_BACKEND=sim yggdrasim-scp03 --cmd "STATUS; EXIT" |
| SCP03 keysets | yggdrasim-scp03 --cmd "SHOW; EXIT" |
| SCP80 keysets | yggdrasim-scp80 --cmd "iccid <ICCID>; show; quit" |
| SUCI keys | yggdrasim-suci-tool --cmd "STATUS; EXIT" |
| Inventory crypto | yggdrasim --doctor (look for the gpg probe row) |
| Runtime root | yggdrasim --doctor (look for the workspace probe row) |