laforge has submitted this change. ( https://gerrit.osmocom.org/c/pysim/+/33251
)
Change subject: docs: Add section on pySim-trace to user manual
......................................................................
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(-)
Approvals:
laforge: Looks good to me, approved
fixeria: Looks good to me, but someone else must approve
Jenkins Builder: Verified
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 https://gerrit.osmocom.org/c/pysim/+/33251
To unsubscribe, or for help writing mail filters, visit
https://gerrit.osmocom.org/settings
Gerrit-Project: pysim
Gerrit-Branch: master
Gerrit-Change-Id: I5edb222818f00e36ed5b067e0f8d5786f39ae887
Gerrit-Change-Number: 33251
Gerrit-PatchSet: 2
Gerrit-Owner: laforge <[email protected]>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: dexter <[email protected]>
Gerrit-Reviewer: fixeria <[email protected]>
Gerrit-Reviewer: laforge <[email protected]>
Gerrit-MessageType: merged
