docs: Add section on pySim-trace to user manual

Change-Id: I5edb222818f00e36ed5b067e0f8d5786f39ae887

docs/index.rst

@@ -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
 

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.
+
+

pySim-trace.py

@@ -114,36 +114,45 @@ class Tracer:
             #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')