public/pysim
1
0
Fork 1
mirror of https://gitea.osmocom.org/sim-card/pysim.git synced 2026-03-24 06:18:33 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add section on pySim-trace to user manual

Browse Source 
Change-Id: I5edb222818f00e36ed5b067e0f8d5786f39ae887
This commit is contained in:
Harald Welte
2023-06-09 11:14:44 +02:00
committed by laforge
parent e345e1126d
commit 7e55569f3a
3 changed files with 82 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/index.rst
View File

@@ -31,6 +31,7 @@ pySim consists of several parts:
* a python :ref:`library<pySim library>` containing plenty of objects and methods that can be used for
writing custom programs interfacing with SIM cards.
* the [new] :ref:`interactive pySim-shell command line program<pySim-shell>`
* the [new] :ref:`pySim-trace APDU trace decoder<pySim-trace>`
* the [legacy] :ref:`pySim-prog and pySim-read tools<Legacy tools>`
.. toctree::
@@ -38,6 +39,7 @@ pySim consists of several parts:
:caption: Contents:
shell
trace
legacy
library

64
docs/trace.rst Normal file
View File

@@ -0,0 +1,64 @@
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.