laforge has uploaded this change for review.
docs: Add section on pySim-trace to user manual
Change-Id: I5edb222818f00e36ed5b067e0f8d5786f39ae887
---
M docs/index.rst
A docs/trace.rst
M pySim-trace.py
3 files changed, 91 insertions(+), 7 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/51/33251/1
diff --git a/docs/index.rst b/docs/index.rst
index 471802a..a46aee0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -31,6 +31,7 @@
* 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 @@
:caption: Contents:
shell
+ trace
legacy
library
diff --git a/docs/trace.rst b/docs/trace.rst
new file mode 100644
index 0000000..637491a
--- /dev/null
+++ b/docs/trace.rst
@@ -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.
+
+
diff --git a/pySim-trace.py b/pySim-trace.py
index 79069a6..bb1805c 100755
--- a/pySim-trace.py
+++ b/pySim-trace.py
@@ -114,36 +114,45 @@
#print(inst)
self.format_capdu(inst)
-option_parser = argparse.ArgumentParser(prog='pySim-trace', description='Osmocom pySim high-level SIM card trace decoder',
+option_parser = argparse.ArgumentParser(description='Osmocom pySim high-level SIM card trace decoder',
formatter_class=argparse.ArgumentDefaultsHelpFormatter)
global_group = option_parser.add_argument_group('General Options')
global_group.add_argument('--no-suppress-select', action='store_false', dest='suppress_select',
- help="Don't suppress displaying SELECT APDUs")
+ help="""
+ Don't suppress displaying SELECT APDUs. We normally suppress them as they just clutter up
+ the output without giving any useful information. Any subsequent READ/UPDATE/... operations
+ on the selected file will log the file name most recently SELECTed.""")
global_group.add_argument('--no-suppress-status', action='store_false', dest='suppress_status',
- help="Don't suppress displaying STATUS APDUs")
+ help="""
+ Don't suppress displaying STATUS APDUs. We normally suppress them as they don't provide any
+ information that was not already received in resposne to the most recent SEELCT.""")
subparsers = option_parser.add_subparsers(help='APDU Source', dest='source', required=True)
-parser_gsmtap = subparsers.add_parser('gsmtap-udp', help='Live capture of GSMTAP-SIM on UDP port')
+parser_gsmtap = subparsers.add_parser('gsmtap-udp', help="""
+ Read APDUs from live capture by receiving GSMTAP-SIM packets on specified UDP port.
+ Use this for live capture from SIMtrace2 or osmo-qcdiag.""")
parser_gsmtap.add_argument('-i', '--bind-ip', default='127.0.0.1',
help='Local IP address to which to bind the UDP port')
parser_gsmtap.add_argument('-p', '--bind-port', default=4729,
help='Local UDP port')
parser_gsmtap_pyshark_pcap = subparsers.add_parser('gsmtap-pyshark-pcap', help="""
- PCAP file containing GSMTAP (SIM APDU) communication; processed via pyshark.""")
+ Read APDUs from PCAP file containing GSMTAP (SIM APDU) communication; processed via pyshark.
+ Use this if you have recorded a PCAP file containing GSMTAP (SIM APDU) e.g. via tcpdump or
+ wireshark/tshark.""")
parser_gsmtap_pyshark_pcap.add_argument('-f', '--pcap-file', required=True,
help='Name of the PCAP[ng] file to be read')
parser_rspro_pyshark_pcap = subparsers.add_parser('rspro-pyshark-pcap', help="""
- PCAP file containing RSPRO (osmo-remsim) communication; processed via pyshark.
+ Read APDUs from PCAP file containing RSPRO (osmo-remsim) communication; processed via pyshark.
REQUIRES OSMOCOM PATCHED WIRESHARK!""")
parser_rspro_pyshark_pcap.add_argument('-f', '--pcap-file', required=True,
help='Name of the PCAP[ng] file to be read')
parser_rspro_pyshark_live = subparsers.add_parser('rspro-pyshark-live', help="""
- Live capture of RSPRO (osmo-remsim) communication; processed via pyshark.
+ Read APDUs from live capture of RSPRO (osmo-remsim) communication; processed via pyshark.
REQUIRES OSMOCOM PATCHED WIRESHARK!""")
parser_rspro_pyshark_live.add_argument('-i', '--interface', required=True,
help='Name of the network interface to capture on')
To view, visit change 33251. To unsubscribe, or for help writing mail filters, visit settings.