pySim-trace¶
pySim-trace is a utility for high-level decode of APDU protocol traces such as those obtained with Osmocom SIMtrace2 or osmo-qcdiag.
pySim-trace leverages the existing knowledge of pySim-shell on anything related to SIM cards, including the structure/encoding of the various files on SIM/USIM/ISIM/HPSIM cards, and applies this to decoding protocol traces. This means that it shows not only the name of the command (like READ BINARY), but actually understands what the currently selected file is, and how to decode the contents of that file.
pySim-trace also understands the parameters passed to commands and how to decode them, for example of the AUTHENTICATE command within the USIM/ISIM/HPSIM application.
Demo¶
To get an idea how pySim-trace usage looks like, you can watch the relevant part of the 11/2022 SIMtrace2 tutorial whose recording is freely accessible.
Running pySim-trace¶
Running pySim-trace requires you to specify the source of the to-be-decoded APDUs. There are several supported options, each with their own respective parameters (like a file name for PCAP decoding).
See the detailed command line reference below for details.
A typical execution of pySim-trace for doing live decodes of GSMTAP (SIM APDU) e.g. from SIMtrace2 or osmo-qcdiag would look like this:
./pySim-trace.py gsmtap-udp
This binds to the default UDP port 4729 (GSMTAP) on localhost (127.0.0.1), and decodes any APDUs received there.
pySim-trace command line reference¶
Osmocom pySim high-level SIM card trace decoder
usage: pySim-trace.py [-h] [--no-suppress-select] [--no-suppress-status]
[--show-raw-apdu]
{gsmtap-udp,gsmtap-pyshark-pcap,rspro-pyshark-pcap,rspro-pyshark-live,tca-loader-log,stdin-hex} ...
Positional Arguments¶
- source
Possible choices: gsmtap-udp, gsmtap-pyshark-pcap, rspro-pyshark-pcap, rspro-pyshark-live, tca-loader-log, stdin-hex
APDU Source
General Options¶
- --no-suppress-select
Don’t suppress displaying SELECT APDUs. We normally suppress them as they just clutter up the output without giving any useful information. Any subsequent READ/UPDATE/… operations on the selected file will log the file name most recently SELECTed.
Default: True
- --no-suppress-status
Don’t suppress displaying STATUS APDUs. We normally suppress them as they don’t provide any information that was not already received in response to the most recent SEELCT.
Default: True
- --show-raw-apdu
Show the raw APDU in addition to its parsed form.
Default: False
Sub-commands¶
gsmtap-udp¶
Read APDUs from live capture by receiving GSMTAP-SIM packets on specified UDP port. Use this for live capture from SIMtrace2 or osmo-qcdiag.
pySim-trace.py gsmtap-udp [-h] [-i BIND_IP] [-p BIND_PORT]
Named Arguments¶
- -i, --bind-ip
Local IP address to which to bind the UDP port
Default: “127.0.0.1”
- -p, --bind-port
Local UDP port
Default: 4729
gsmtap-pyshark-pcap¶
Read APDUs from PCAP file containing GSMTAP (SIM APDU) communication; processed via pyshark. Use this if you have recorded a PCAP file containing GSMTAP (SIM APDU) e.g. via tcpdump or wireshark/tshark.
pySim-trace.py gsmtap-pyshark-pcap [-h] -f PCAP_FILE
Named Arguments¶
- -f, --pcap-file
Name of the PCAP[ng] file to be read
rspro-pyshark-pcap¶
Read APDUs from PCAP file containing RSPRO (osmo-remsim) communication; processed via pyshark. REQUIRES OSMOCOM PATCHED WIRESHARK!
pySim-trace.py rspro-pyshark-pcap [-h] -f PCAP_FILE
Named Arguments¶
- -f, --pcap-file
Name of the PCAP[ng] file to be read
rspro-pyshark-live¶
Read APDUs from live capture of RSPRO (osmo-remsim) communication; processed via pyshark. REQUIRES OSMOCOM PATCHED WIRESHARK!
pySim-trace.py rspro-pyshark-live [-h] -i INTERFACE
Named Arguments¶
- -i, --interface
Name of the network interface to capture on
tca-loader-log¶
Read APDUs from a TCA Loader log file.
pySim-trace.py tca-loader-log [-h] -f LOG_FILE
Named Arguments¶
- -f, --log-file
Name of the log file to be read
stdin-hex¶
Read APDUs as hex-string from stdin.
pySim-trace.py stdin-hex [-h]
Constraints¶
In order to properly track the current location in the filesystem tree and other state, it is important that the trace you’re decoding includes all of the communication with the SIM, ideally from the very start (power up).
pySim-trace currently only supports ETSI UICC (USIM/ISIM/HPSIM) and doesn’t yet support legacy GSM SIM. This is not a fundamental technical constraint, it’s just simply that nobody got around developing and testing that part. Contributions are most welcome.