mirror of https://gerrit.osmocom.org/pysim
65 lines
2.3 KiB
ReStructuredText
65 lines
2.3 KiB
ReStructuredText
pySim-trace
|
|
===========
|
|
|
|
pySim-trace is a utility for high-level decode of APDU protocol traces such as those obtained with
|
|
`Osmocom SIMtrace2 <https://osmocom.org/projects/simtrace2/wiki>`_ or `osmo-qcdiag <https://osmocom.org/projects/osmo-qcdiag/wiki>`_.
|
|
|
|
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 <https://media.ccc.de/v/osmodevcall-20221019-laforge-simtrace2-tutorial#t=2134>`_.
|
|
|
|
|
|
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
|
|
----------------------------------
|
|
|
|
.. argparse::
|
|
:module: pySim-trace
|
|
:func: option_parser
|
|
:prog: pySim-trace.py
|
|
|
|
|
|
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.
|
|
|
|
|