| Harald Welte | 7e55569 | 2023-06-09 11:14:44 +0200 | [diff] [blame] | 1 | pySim-trace |
| 2 | =========== |
| 3 | |
| 4 | pySim-trace is a utility for high-level decode of APDU protocol traces such as those obtained with |
| 5 | `Osmocom SIMtrace2 <https://osmocom.org/projects/simtrace2/wiki>`_ or `osmo-qcdiag <https://osmocom.org/projects/osmo-qcdiag/wiki>`_. |
| 6 | |
| 7 | pySim-trace leverages the existing knowledge of pySim-shell on anything related to SIM cards, |
| 8 | including the structure/encoding of the various files on SIM/USIM/ISIM/HPSIM cards, and applies this |
| 9 | to decoding protocol traces. This means that it shows not only the name of the command (like READ |
| 10 | BINARY), but actually understands what the currently selected file is, and how to decode the |
| 11 | contents of that file. |
| 12 | |
| 13 | pySim-trace also understands the parameters passed to commands and how to decode them, for example |
| 14 | of the AUTHENTICATE command within the USIM/ISIM/HPSIM application. |
| 15 | |
| 16 | |
| 17 | Demo |
| 18 | ---- |
| 19 | |
| 20 | To get an idea how pySim-trace usage looks like, you can watch the relevant part of the 11/2022 |
| 21 | SIMtrace2 tutorial whose `recording is freely accessible <https://media.ccc.de/v/osmodevcall-20221019-laforge-simtrace2-tutorial#t=2134>`_. |
| 22 | |
| 23 | |
| 24 | Running pySim-trace |
| 25 | ------------------- |
| 26 | |
| 27 | Running pySim-trace requires you to specify the *source* of the to-be-decoded APDUs. There are several |
| 28 | supported options, each with their own respective parameters (like a file name for PCAP decoding). |
| 29 | |
| 30 | See the detailed command line reference below for details. |
| 31 | |
| 32 | A typical execution of pySim-trace for doing live decodes of *GSMTAP (SIM APDU)* e.g. from SIMtrace2 or |
| 33 | osmo-qcdiag would look like this: |
| 34 | |
| 35 | :: |
| 36 | |
| 37 | ./pySim-trace.py gsmtap-udp |
| 38 | |
| 39 | This binds to the default UDP port 4729 (GSMTAP) on localhost (127.0.0.1), and decodes any APDUs received |
| 40 | there. |
| 41 | |
| 42 | |
| 43 | |
| 44 | pySim-trace command line reference |
| 45 | ---------------------------------- |
| 46 | |
| 47 | .. argparse:: |
| 48 | :module: pySim-trace |
| 49 | :func: option_parser |
| 50 | :prog: pySim-trace.py |
| 51 | |
| 52 | |
| 53 | Constraints |
| 54 | ----------- |
| 55 | |
| 56 | * In order to properly track the current location in the filesystem tree and other state, it is |
| 57 | important that the trace you're decoding includes all of the communication with the SIM, ideally |
| 58 | from the very start (power up). |
| 59 | |
| 60 | * pySim-trace currently only supports ETSI UICC (USIM/ISIM/HPSIM) and doesn't yet support legacy GSM |
| 61 | SIM. This is not a fundamental technical constraint, it's just simply that nobody got around |
| 62 | developing and testing that part. Contributions are most welcome. |
| 63 | |
| 64 | |