Replay HIL PCAP offline

Offline replay reuses the same TUI that drives live captures; the difference is that tshark -r reads the file instead of tshark -i streaming a live FIFO.

Prerequisites

• a saved .pcap or .pcapng captured by the HIL bridge, Wireshark, tshark, or dumpcap — on-wire frames must be either plain APDUs or GSMTAP over UDP 4729
• tshark on PATH
• Python environment with YggdraSIM installed (source checkout or pip install -e .)
• optional: a keybag JSON with SCP03 or SCP11c session keys for any secure-channel traffic that appears in the capture

For how to produce the keybag, see Session key export below and the subsystem pages SCP03 and SCP11 Local Access.

Steps

1. Locate the capture file. Example:

   ls -lh Workspace/hil/captures/
   # session-example.pcapng
   # session-example.pcap.keys.json
   

   If the keybag lives next to the capture as <capture>.pcap.keys.json or <capture>.keys.json, it is auto-discovered.

2. Launch the decoded-APDU TUI in offline mode.

   CLI, automatic keybagCLI, explicit keybagFrom the [B] menu

   python main/main.py \
       --open-pcap Workspace/hil/captures/session-example.pcapng
   

   python main/main.py \
       --open-pcap Workspace/hil/captures/session-example.pcapng \
       --keybag    Workspace/hil/captures/session-example.keys.json
   

   python main/main.py
   [B]   HIL Bridge Session
    [3]  Open saved .pcap (offline review, no bridge)
        pcap path  : Workspace/hil/captures/session-example.pcapng
         keybag path: (blank → auto-discover)
   

3. Navigate the capture.

   The TUI behaves the same as in live capture mode — summary list on the left, detail pane, hex pane, and stateful context rows. Secure-messaging APDUs that match a keybag entry gain an extra "plaintext" context line. Entries that do not match (wrong AID, no keybag, unknown protocol) stay wrapped.

4. Leave the TUI.

   Press Ctrl+Q (or the normal exit keybind). No background processes were started; nothing needs to be torn down.

Session key export

Keybag JSONs are produced by the same shells that build the secure channel. Pick the path that matches how the capture was made:

SCP03 sessions

Inside the SCP03 admin shell, after AUTH-SD:

[APDU] > AUTH-SD
[A0...00] > EXPORT-KEYBAG Workspace/hil/captures/session-example.keys.json case-1234

The handler refuses cleanly if the session is not authenticated.

SCP11 Local Access sessions

Inside SCP11.local_access, after any verb that builds a BSP (for example LOAD-PROFILE, ENABLE-PROFILE, or STORE-METADATA):

[Local SMDPP] > LOAD-PROFILE
[Local SMDPP] > EXPORT-KEYBAG Workspace/hil/captures/session-example.keys.json case-1234

Non-interactively:

python -m SCP11.local_access --dump-keybag \
    Workspace/hil/captures/session-example.keys.json

SCP11 Live sessions

python -m SCP11.live --dump-keybag is a stub. In live mode the SCP11c BSP keys are derived inside the eUICC during BPP processing and never leave the card. The flag prints a clear message and exits with code 2. Use SCP11.local_access or SCP03 if a real keybag is needed for the capture.

Keybag JSON schema

{
  "format": "yggdrasim-hil-keybag/v1",
  "entries": [
    {
      "label": "case-1234",
      "protocol": "SCP03",
      "aid_hex": "A000000151000000",
      "s_enc_hex": "...32 hex chars...",
      "s_mac_hex": "...32 hex chars...",
      "s_rmac_hex": "...32 hex chars...",
      "ssc_hex": "0000000000000000",
      "chaining_value_hex": "",
      "block_nr": 0
    }
  ]
}

Multiple entries are allowed in one file. protocol is "SCP03" or "SCP11c". The replay engine matches entries against the AID in the capture; unmatched entries are skipped silently.

Validation

• TUI banner shows offline review (no bridge, no live FIFO).
• TUI status line reports the resolved keybag path, or a no-keybag note if nothing was supplied or discovered.
• Secure-messaging APDUs (CLA bit 0x04) gain a [plaintext] context row when the keybag entry matches.
• state/hil_bridge_supervisor.json is not touched; the systemd HIL service is left alone.

Common failures

Related pages

• HIL Bridge
• Run a HIL Capture
• SCP03 Admin Shell
• SCP11 Local Access
• guides/HIL_BRIDGE_GUIDE.md