Skip to content
YggdraSIM

APDU Dissector

Tools/ApduDissector/ is a Wireshark and tshark dissector that decodes the GSMTAP SIM frames the HIL bridge mirrors on UDP 4729, all the way down into the APDU payload.

On this page

Wireshark ships a gsm_sim dissector, and it stops at the command header. What it leaves behind, measured against a capture written by the HIL bridge's own writer on TShark 4.2.2:

Frame Stock output With this dissector
GET RESPONSE returning an FCP template [Malformed Packet] File type, EF structure, file identifier resolved to a path, life-cycle status
STORE DATA to the ISD-R carrying an ES10c request ETSI TS 102.221 e2 STORE DATA, then the BER-TLV tree naming ProfileInfoList and its contents
READ BINARY of EF.ICCID Offset=0, bytes undecoded The ICCID
ATR frame Mis-parsed as an APDU, Unknown status word: 4ba9 Convention, interface bytes, historical bytes, verified check byte

What it decodes

  • ISO/IEC 7816-4 header -- the class byte split into logical channel, secure-messaging mode and chaining; the instruction resolved class-first, so 80 E2 is STORE DATA rather than the ETSI reading of E2; case classification across all seven forms including extended lengths.
  • Status words -- from the same table the MCP server uses, plus the families whose SW2 is a count rather than a code. 61 2B reads as "43 bytes available", 63 C2 as "2 retries left".
  • Risk class -- from yggdrasim_common/apdu_risk.py, so yapdu.risk == 3 is a display filter for every irreversible command in a capture, and each one carries an expert warning saying why.
  • BER-TLV and COMPREHENSION-TLV -- recursive, with multi-byte tags, long-form and indefinite lengths, and tag names from the same tables Tools/Asn1TlvDecode uses.
  • RSP structures by ASN.1 field name -- an ES10 response is walked with the structure it belongs to, so '81' inside a BF22 is baseProfilePackageVersion and a profile listing reads profileInfoListOk / ProfileInfo / iccid / isdpAid / profileState. The structure travels with the walk rather than the parent tag alone, which is what lets BF22 be EUICCInfo2 at the top of a response and serviceSpecificDataStoredInEuicc inside a ProfileInfo.
  • File control templates -- FCP, FCI and FMD with their TS 102 221 clause 11.1.1.3 sub-tags.
  • Elementary files -- EF.ICCID, EF.IMSI, EF.UST and EF.AD, attributed to the file selected in an earlier frame.
  • Command bodies -- SELECT control bytes and target, the SFI form of READ/UPDATE BINARY, record number and mode, PIN key references, MANAGE CHANNEL operations, GET/PUT DATA tags.
  • ATR frames, which the stock dissector reads as APDUs and gets wrong.

Entry points

yggdrasim-apdu-dissect decode --pcap capture.pcap --verbose
yggdrasim-apdu-dissect install          # for the Wireshark GUI
yggdrasim-apdu-dissect path             # print the .lua path
yggdrasim-apdu-dissect probe --pcap capture.pcap
python -m Tools.ApduDissector decode --pcap capture.pcap \
    --fields frame.number,yapdu.command_name,yapdu.sw,yapdu.risk
tshark -X lua_script:$(yggdrasim-apdu-dissect path) -r capture.pcap -V

When it loads

The dissector is not loaded by every tshark or Wireshark invocation by default. It is loaded automatically on the YggdraSIM-driven paths, and becomes global for your account after a one-time install.

How you start Loaded?
HIL-bridge terminal decode view, live or --open-pcap Yes, automatically
Wireshark launched from the HIL menu ([B] -> [1] -> start mode [2]) Yes, automatically
yggdrasim-apdu-dissect decode Yes, automatically
yggdrasim-eum-diag Yes, automatically
A bare tshark -r capture.pcap you type yourself Only after install
Wireshark started from the desktop or app menu Only after install

YGGDRASIM_APDU_DISSECTOR=0 opts the automatic paths out.

Making it global

tshark takes the script as a path; the GUI has no equivalent. install copies the Lua tree into the personal plugin folder Wireshark reports for itself, which both Wireshark and tshark read at startup. After this, every invocation under your account loads it with no flags at all:

yggdrasim-apdu-dissect install --dry-run   # show what would be copied
yggdrasim-apdu-dissect install
yggdrasim-apdu-dissect uninstall           # and back out again

In a running Wireshark, pick up the change with Analyze > Reload Lua Plugins (Ctrl+Shift+L).

Installing and passing -X lua_script: at the same time is harmless: the entry point carries a load guard, because Proto() raises on a duplicate name and Wireshark would otherwise refuse the whole plugin.

Why each module bootstraps its own package.path

Wireshark's plugin loader executes every .lua file in the plugin directory standalone, in alphabetical order, so cat.lua runs before the entry point that is supposed to require it. Each module therefore puts its own directory on package.path before its first require. Without that the whole plugin is refused at startup with module 'yggdrasim_apdu.util' not found.

Wireshark refuses Lua scripts when running as root

It does so silently: no error, no warning, the script simply never loads and you get a stock decode that looks like a broken dissector. Run as a normal user. The CLI prints a warning when it detects this.

How the tree reads

The layout follows Wireshark's gsm_sim: a byte appears once, and what the instruction makes of it is on that byte's own line rather than repeated below it as a second field.

  • Bit fields are rendered as bit fields. The class and constructed bits of a BER tag show their masks -- ..1. .... = Constructed: True -- the way Wireshark's own BER dissector renders them.
  • A reading hangs off the byte it decodes. P1: 0x91 (last block, BER-TLV format), not a P1 line followed by three more naming the same byte. A COMPREHENSION-TLV's meaning sits under that TLV, not in a block collected after the run.
  • Framing is one collapsed node. How the payload was cut into a command and a response is dissector bookkeeping, so it lives under Framing rather than above the APDU.
  • A field that only restates the line above it is filterable but not printed. yapdu.sw_meaning, yapdu.detail, yapdu.command_name, yapdu.tlv.name, yapdu.tlv.uint, yapdu.frame_kind, yapdu.case, yapdu.command_source, yapdu.split.command_len, yapdu.split.response_len, yapdu.split.method, yapdu.cla.type, yapdu.tlv.comprehension_required, yapdu.cat.type, yapdu.cat.type_name, yapdu.cat.source, yapdu.cat.destination and yapdu.cat.result all still resolve in a display filter, a custom column and -T fields; they no longer each cost a line in every frame of a capture.
  • A default value is not a finding. The class-byte breakdown prints Logical channel, Secure messaging and Command chaining only where one of them departs from channel 0, no secure messaging and no chaining -- which is also where the CLA line itself names it. Split confidence and Cross-frame context available print when they carry a warning and stay filter-only when they do not.

Those last two points matter when a field seems missing from the detail pane: query it rather than looking for it.

Display filters worth knowing

yapdu.risk == 3                     every irreversible command in the capture
yapdu.sw != 0x9000                  every exchange the card did not accept
yapdu.command_name == "STORE_DATA"  eUICC traffic
yapdu.split.ambiguous == 1          exchanges the decoder could not resolve
yapdu.ef.iccid                      frames that revealed an ICCID
yapdu.cla.secure_messaging > 0      SCP-wrapped traffic
yapdu.command_source contains "GlobalPlatform"
                                    commands the GlobalPlatform card
                                    specification defines

How it attaches

The dissector registers against Wireshark's gsmtap.type dissector table for GSMTAP_TYPE_SIM (0x04). That table hands it the payload with the GSMTAP header already stripped, and it behaves the same whether or not the caller passes -d udp.port==4729,gsmtap, which is what the HIL bridge does.

The stock gsm_sim dissector is chained, not displaced, so its 242 fields stay filterable alongside yapdu.*. The exception is ATR frames, which gsm_sim reads as APDUs and invents a status word from; those are withheld from it.

Because the HIL-Bridge decode view renders tshark -V and PDML output, it inherits the deeper tree with no change of its own. Set YGGDRASIM_APDU_DISSECTOR=0 to keep the dissector out of those calls.

Command and response splitting

A SIMtrace SIM-APDU record puts the command APDU and the response APDU in one frame, and ISO 7816-4 does not always say where the boundary is: a body of 05 AA BB CC DD EE reads equally well as case 3S or case 4S.

The dissector enumerates every structurally valid split, scores each against the status word, the case the instruction normally uses, and the relationship between Le and the response length, then reports which evidence decided it (yapdu.split.method) and how confident it is (yapdu.split.confidence). Where two readings genuinely tie, yapdu.split.ambiguous is set rather than the ambiguity being hidden.

This replaces the instruction allowlist in Tools/HilBridge/live_decode_state.py, which returns nothing for an instruction it does not recognise -- so an unfamiliar command disappears from the trace entirely.

Secure messaging

An SCP03 or SCP11c wrapped command is broken out with no keys at all: the C-MAC, the ciphertext, and whether the body is merely authenticated or also encrypted. yapdu.cla.secure_messaging > 0 finds every wrapped exchange.

Plaintext needs keys, and Wireshark's Lua binding has no AES, no CMAC and no hash, so no Lua dissector can decrypt anything regardless of what it is handed. The recovery therefore happens in Python, using the same engine the terminal decode view uses, and the result is written to a sidecar the dissector reads:

yggdrasim-apdu-dissect sidecar --pcap live.pcap --keybag live.keys.json
yggdrasim-apdu-dissect decode  --pcap live.pcap \
    --sidecar live.pcap.sidecar.json --verbose

The keybag is the one you already export with EXPORT-KEYBAG in the SCP03 admin shell or SCP11.local_access; a sibling <pcap>*.keys.json is picked up automatically. In the Wireshark GUI, set the sidecar path in the dissector's preferences instead.

Recovered plaintext is not merely displayed. The dissector re-runs its whole decode over it, so a ciphered ES10b STORE DATA renders as a complete ES10b tree rather than a blob with a note attached.

A sidecar is bound to its capture by content, not by frame number. Each entry records the on-wire ciphered command, and an entry is applied only when those bytes match the frame in front of it. A sidecar built from a different capture therefore contributes nothing and sets yapdu.sm.sidecar_mismatch, instead of attributing plaintext to the wrong exchange. Corrupt or foreign-format sidecars collapse to one status line.

Constant tables are generated

Tools/ApduDissector/lua/yggdrasim_apdu/tables.lua is generated from the Python modules the rest of the toolkit already treats as authoritative:

python scripts/generate_apdu_dissector_tables.py --write
python scripts/generate_apdu_dissector_tables.py --check   # CI drift guard

Sources are yggdrasim_common/apdu_risk.py, yggdrasim_common/apdu_tables.py, yggdrasim_common/stk_tables.py, Tools/Asn1TlvDecode/main.py, Tools/YggdraMCP/server.py, Tools/HilBridge/live_decode_state.py, SIMCARD/etsi_fs.py and SIMCARD/gp.py. The generated file is committed so the Lua tree works standalone with no Python present, and tests/test_apdu_dissector_tables.py fails when it drifts.

The RSP member names are read straight from the ASN.1 of the converted specifications under docs/tel-docs/converted/ -- SGP.22 first, then SGP.32 for what SGP.22 does not define. The reader computes each tag from the class and number in the declaration and checks it against the -- Tag 'XX' the document states beside it; a disagreement fails generation rather than producing a name on the wrong tag. Where a body cannot be read unambiguously -- two members landing on one tag -- the type contributes no names at all.

Testing

python -m pytest tests/test_apdu_dissector_*.py
YGGDRASIM_REQUIRE_TSHARK=1 python -m pytest tests/test_apdu_dissector_*.py

Captures are synthesised at test time from Tools/HilBridge/protocol.py helpers, so nothing binary is committed and identifiers stay inside the documented test ranges.

Without YGGDRASIM_REQUIRE_TSHARK=1, the tshark-backed modules skip when tshark is missing -- or when the suite runs as root and Wireshark refuses to load the Lua. Set it in at least one CI job, or the dissector rots without the suite noticing.

Conformance

Every table and bit-field below is read from the clause named, and tests/test_apdu_dissector_*.py pins the readings that are easy to get subtly wrong. The ones worth knowing about, because they are the ones a plausible implementation gets backwards:

Reading Clause The trap
Life-cycle status integer ISO/IEC 7816-4 Table 13 Bit 1 is the activated flag, so '05'/'07' are activated and '04'/'06' are not. '0C'--'0F' is the termination state, not an operational one.
Status word categories ISO/IEC 7816-4 clause 5.1.3 Four categories, not two. '62' and '63' are warnings: 63 CX is a failed verification, so yapdu.sw_success is false for it.
61 00, 6C 00 ISO/IEC 7816-4 clause 5.1 SW2 of zero means 256, following the Le convention.
92 40 GSM 11.11 clause 9.4 '92' '0X' counts internal retries; '92' '40' is a memory problem.
Class byte ISO/IEC 7816-4 clause 5.4.1 '80'--'FE' is proprietary and bits 6--1 mean nothing there. Two blocks are decoded anyway because GlobalPlatform claims them: '8X' (Table 11-1) for logical channels 0--3, and 'C0'--'FE' for channels 4--19, which is the further interindustry shape with bit 8 set. '90'--'BF' reports no channel, secure-messaging level or chaining flag.
Secure messaging ISO/IEC 7816-4 Table 3 Bits 4 and 3 in the first interindustry form, so CLA '08' is secure messaging; a single bit in the further form, so CLA '44' is channel 8 and is not.
Device identities ETSI TS 102 223 clause 8.7 '81' UICC, '82' terminal, '21'--'27' channels 1--7, '10'--'17' card readers.
General result ETSI TS 102 223 clause 8.12 '04' is the icon result and '06' is limited service. The second byte carries the cause for '3A', '20' and '26'.
Bearer type ETSI TS 102 223 clause 8.52 The list starts at '01'; '03' is the default packet bearer.
Channel status ETSI TS 102 223 clause 8.56 Bit 8 of byte 1 is link-established; byte 2 '05' is "link dropped".
Transport level ETSI TS 102 223 clause 8.59 '01'/'02' are remote, '04'/'05' are local.
COMPREHENSION-TLV ETSI TS 101 220 clause 7.1 Not BER. Two tag forms only, no '1F' escape, no class and no constructed bit.
ENVELOPE tags 3GPP TS 31.111 clause 9.1 The run is not gapless: 'D8' is reserved for intra-UICC communication, so USSD download is 'D9', Geographical Location Reporting 'DD' and ProSe Report 'DF'. Numbering straight through the gap shifts every tag from 'D9' up and loses 'DF'.
'DF' ProSe Report ETSI TS 101 220 clause 7.2 A single-byte tag whose low five bits are all set, which is BER's multi-byte introducer. Read as BER it swallows the length byte and the envelope vanishes, so the wrapper byte is matched directly.
BoundProfilePackage GSMA SGP.22 Table 4 Five members: BF23 initialiseSecureChannelRequest, then A0 firstSequenceOf87, A1 sequenceOf88, A2 secondSequenceOf87 and A3 sequenceOf86. Each sequence holds TLVs of the tag its name ends in.

Deliberate divergences

  • Indefinite BER lengths are rejected, not resolved. DER prohibits them, SGP.22 and SGP.32 mandate DER, and no conforming card emits one here. Resolving one means scanning for an end-of-contents marker, and a byte scan cannot tell a real terminator from 00 00 inside a value.
  • A malformed length is clamped and flagged, where SIMCARD.utils.read_tlv rejects the object outright. A dissector has to show what is on the wire.
  • 'C6' is walked as constructed although BER calls it primitive, because ETSI TS 102 221 clause 11.1.1.4.10 fills it with TLVs.
  • Naming an alert is a TLS 1.2-and-earlier capability. From the server's first flight onward, TLS 1.3 encrypts every alert and RFC 8446 clause 5.2 sets the outer opaque_type of a protected record to 23 (application_data), so the alert code is inside the ciphertext and the record does not even announce itself as an alert. yapdu.tls.alert_encrypted therefore covers the TLS 1.2 shape -- an alert record whose body is ciphered -- and not the TLS 1.3 one, which is indistinguishable from any other application data without the keys. Under TLS 1.3, read yapdu.tls.content_type == "application_data" as "an alert may be in here", rather than reading the absence of a named alert as "there was none".
  • A reserved class byte, and proprietary '90'--'BF', report no channel. Saying nothing is the honest answer where the specification assigns no meaning. '8X' and 'C0'--'FE' are the exceptions, because GlobalPlatform does assign meaning to both.

Known limits

  • Requires Wireshark 3.4 or newer; measured against 4.2.2. Re-run yggdrasim-apdu-dissect probe on a new floor version.
  • Wireshark 4.2 exposes no gsmtap.sub_type field, and gsmtap.* field extractors return nothing inside a gsmtap.type subdissector, so ATR frames are recognised from their own bytes rather than the GSMTAP subtype. Frame direction is not surfaced; a SIMtrace record carries both halves anyway.
  • PIN blocks and key material are reported by length only.
  • An exchange whose instruction has no case hint and whose bytes fit two readings is decoded and flagged, not resolved. There is no information in the frame that would resolve it.
  • BIP channel data is not reassembled across APDUs. A TLS record split over several SEND DATA blocks has its header and any plaintext alert reported here, but is not handed to the stock dissector, because half a record produces a malformed-packet complaint rather than a tree. In practice this means a bad_certificate alert is visible while the certificate that caused it is not: an SM-DP+ chain runs to several kilobytes across ~236-byte blocks. A DNS message over TCP is de-framed and handed over only when one block carries the whole message; one split across blocks is left as raw channel data for the same reason.
  • The TERMINAL PROFILE body is left as raw bytes. It is a bit field per ETSI TS 102 223 clause 5.2, not TLV.

See also

  • HIL Bridge
  • EUM Diagnostics -- yggdrasim-eum-diag now hands its captures to this dissector. Its own dissector.lua has been retired: it byte-scanned for the BF36 tag with no TLV awareness, rendered the value as one opaque blob, loaded session keys it had no way to apply, and built a TvbRange from half the digit count of an ICCID, which breaks on any real 19-digit one. YGGDRASIM_EUM_SESSION_KEYS is still honoured, and the key bundles are shown for reference with an explicit note that they are not being applied.
  • Tools/ApduDissector/WIRESHARK_ENVIRONMENT.md -- the measured capability matrix behind the design