laforge has uploaded this change for review. ( 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(-) 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 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: 1 Gerrit-Owner: laforge &lt;laforge(a)osmocom.org&gt; Gerrit-MessageType: newchange