Skip to content
YggdraSIM

EUM Diagnostics

Tools/EumDiag/ is the server-side diagnostic toolbox for ES8+ / Bound Profile Package (BPP) work. Its purpose is to take ShS-ENC / ShS-MAC / DEK session material — which an EUM or SM-DP+ operator already has in its session database — and turn an otherwise opaque BF36 capture into an analysable one through a Wireshark/tshark Lua dissector.

On this page

When to use it

  • post-mortem analysis of a failed provisioning on a server you operate
  • reproducing an ES8+ flow inside Wireshark / tshark during integration testing
  • offline BPP decode (requires the optional pySim checkout)

Not a decryptor

The dissector annotates BPP TLVs with the provided key bundle. Full plaintext recovery still requires a downstream decode step; that is what the decode-bpp subcommand is for.

Entry points

yggdrasim-eum-diag --help
yggdrasim-eum-diag inject-keys --help
yggdrasim-eum-diag store-keys --help
yggdrasim-eum-diag decode-bpp --help

python -m Tools.EumDiag

Subcommands

inject-keys

Writes a JSON key repository (atomic, 0o600 on POSIX) and launches tshark with the Lua dissector attached to the capture.

yggdrasim-eum-diag inject-keys \
    --iccid 89000012345678901234 \
    --shs-enc <32 hex chars> \
    --shs-mac <32 hex chars> \
    --dek     <32 hex chars> \
    --pcap    /captures/provisioning.pcapng

store-keys

Writes the key repository only. Useful when a separate wireshark / tshark process already has the dissector loaded and just needs the key file to be created.

yggdrasim-eum-diag store-keys \
    --iccid 89000012345678901234 \
    --shs-enc ... --shs-mac ... \
    --keys-out /tmp/session-keys.json

decode-bpp

Offline decode of a BPP binary through the optional pySim checkout. Skips cleanly with a clear message if pySim is not available.

yggdrasim-eum-diag decode-bpp --bpp /path/to/bpp.bin

Key repository on disk

{
    "format": "yggdrasim-eum-session-keys/v1",
    "entries": {
        "89000012345678901234": {
            "iccid": "89000012345678901234",
            "shs_enc_hex": "...",
            "shs_mac_hex": "...",
            "dek_hex": "...",
            "comment": "case-id"
        }
    }
}

The Lua dissector picks the path up from YGGDRASIM_EUM_SESSION_KEYS. The tshark runner sets that variable for you when using inject-keys.

Runtime dependencies

  • tshark on PATH for inject-keys
  • the shipped Tools/EumDiag/dissector.lua (part of the wheel's package-data)
  • optional pySim checkout for decode-bpp