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

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.