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 E2isSTORE DATArather than the ETSI reading ofE2; 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 2Breads as "43 bytes available",63 C2as "2 retries left". - Risk class -- from
yggdrasim_common/apdu_risk.py, soyapdu.risk == 3is 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/Asn1TlvDecodeuses. - RSP structures by ASN.1 field name -- an ES10 response is walked with
the structure it belongs to, so
'81'inside aBF22isbaseProfilePackageVersionand a profile listing readsprofileInfoListOk/ProfileInfo/iccid/isdpAid/profileState. The structure travels with the walk rather than the parent tag alone, which is what letsBF22beEUICCInfo2at the top of a response andserviceSpecificDataStoredInEuiccinside aProfileInfo. - 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 aP1line 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
Framingrather 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.destinationandyapdu.cat.resultall 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 messagingandCommand chainingonly 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 confidenceandCross-frame context availableprint 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 00inside a value. - A malformed length is clamped and flagged, where
SIMCARD.utils.read_tlvrejects 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_typeof a protected record to23(application_data), so the alert code is inside the ciphertext and the record does not even announce itself as an alert.yapdu.tls.alert_encryptedtherefore covers the TLS 1.2 shape -- analertrecord 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, readyapdu.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 probeon a new floor version. - Wireshark 4.2 exposes no
gsmtap.sub_typefield, andgsmtap.*field extractors return nothing inside agsmtap.typesubdissector, 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_certificatealert 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-diagnow hands its captures to this dissector. Its owndissector.luahas been retired: it byte-scanned for theBF36tag 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_KEYSis 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