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.