mirror of https://gerrit.osmocom.org/pysim
docs: Add section on pySim-trace to user manual
Change-Id: I5edb222818f00e36ed5b067e0f8d5786f39ae887
This commit is contained in:
parent
e345e1126d
commit
7e55569f3a
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
@ -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')
|
||||
|
|
|
|||
Loading…
Reference in New Issue