mirror of https://gerrit.osmocom.org/pysim
doc: Improve documentation in various places
* don't duplicate information between .rst files and docstrings * if there's more than a trivial single-line documentation, put it as docstring into the python source and use ".. argparse" to pul it into the manual * add documentation for some commands for which it was missing * show one level deeper in the navigation table, listing the commands Change-Id: Ib88bb7d12faaac7d149ee1f6379bc128b83bbdd5
This commit is contained in:
parent
d01bd3632c
commit
12af793d4b
|
@ -18,7 +18,7 @@ sys.path.insert(0, os.path.abspath('..'))
|
||||||
# -- Project information -----------------------------------------------------
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
project = 'osmopysim-usermanual'
|
project = 'osmopysim-usermanual'
|
||||||
copyright = '2009-2021 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
|
copyright = '2009-2022 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
|
||||||
author = 'Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
|
author = 'Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -34,7 +34,7 @@ pySim consists of several parts:
|
||||||
* the [legacy] :ref:`pySim-prog and pySim-read tools<Legacy tools>`
|
* the [legacy] :ref:`pySim-prog and pySim-read tools<Legacy tools>`
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 3
|
||||||
:caption: Contents:
|
:caption: Contents:
|
||||||
|
|
||||||
shell
|
shell
|
||||||
|
|
|
@ -164,9 +164,6 @@ unblock_chv
|
||||||
|
|
||||||
verify_chv
|
verify_chv
|
||||||
~~~~~~~~~~
|
~~~~~~~~~~
|
||||||
This command allows you to verify a CHV (PIN), which is how the specifications call
|
|
||||||
it if you authenticate yourself with the said CHV/PIN.
|
|
||||||
|
|
||||||
.. argparse::
|
.. argparse::
|
||||||
:module: pySim-shell
|
:module: pySim-shell
|
||||||
:func: Iso7816Commands.verify_chv_parser
|
:func: Iso7816Commands.verify_chv_parser
|
||||||
|
@ -178,9 +175,6 @@ Deactivate the currently selected file. This used to be called INVALIDATE in TS
|
||||||
|
|
||||||
activate_file
|
activate_file
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
Activate the specified file. This used to be called REHABILITATE in TS 11.11.
|
|
||||||
You need to specify the name or FID of the file to activate.
|
|
||||||
|
|
||||||
.. argparse::
|
.. argparse::
|
||||||
:module: pySim-shell
|
:module: pySim-shell
|
||||||
:func: Iso7816Commands.activate_file_parser
|
:func: Iso7816Commands.activate_file_parser
|
||||||
|
@ -212,6 +206,7 @@ including the electrical power down.
|
||||||
:func: Iso7816Commands.suspend_uicc_parser
|
:func: Iso7816Commands.suspend_uicc_parser
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
pySim commands
|
pySim commands
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
|
@ -221,7 +216,6 @@ a complex sequence of card-commands.
|
||||||
|
|
||||||
desc
|
desc
|
||||||
~~~~
|
~~~~
|
||||||
|
|
||||||
Display human readable file description for the currently selected file.
|
Display human readable file description for the currently selected file.
|
||||||
|
|
||||||
|
|
||||||
|
@ -231,6 +225,17 @@ dir
|
||||||
:module: pySim-shell
|
:module: pySim-shell
|
||||||
:func: PySimCommands.dir_parser
|
:func: PySimCommands.dir_parser
|
||||||
|
|
||||||
|
Example:
|
||||||
|
::
|
||||||
|
|
||||||
|
pySIM-shell (MF)> dir
|
||||||
|
MF
|
||||||
|
3f00
|
||||||
|
.. ADF.USIM DF.SYSTEM EF.DIR EF.UMPC
|
||||||
|
ADF.ARA-M DF.EIRENE DF.TELECOM EF.ICCID MF
|
||||||
|
ADF.ISIM DF.GSM EF.ARR EF.PL
|
||||||
|
14 files
|
||||||
|
|
||||||
|
|
||||||
export
|
export
|
||||||
~~~~~~
|
~~~~~~
|
||||||
|
@ -250,15 +255,27 @@ all/most files.
|
||||||
|
|
||||||
tree
|
tree
|
||||||
~~~~
|
~~~~
|
||||||
|
|
||||||
Display a tree of the card filesystem. It is important to note that this displays a tree
|
Display a tree of the card filesystem. It is important to note that this displays a tree
|
||||||
of files that might potentially exist (based on the card profile). In order to determine if
|
of files that might potentially exist (based on the card profile). In order to determine if
|
||||||
a given file really exists on a given card, you have to try to select that file.
|
a given file really exists on a given card, you have to try to select that file.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
::
|
||||||
|
|
||||||
|
pySIM-shell (MF)> tree --help
|
||||||
|
EF.DIR 2f00 Application Directory
|
||||||
|
EF.ICCID 2fe2 ICC Identification
|
||||||
|
EF.PL 2f05 Preferred Languages
|
||||||
|
EF.ARR 2f06 Access Rule Reference
|
||||||
|
EF.UMPC 2f08 UICC Maximum Power Consumption
|
||||||
|
DF.TELECOM 7f10 None
|
||||||
|
EF.ADN 6f3a Abbreviated Dialing Numbers
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
verify_adm
|
verify_adm
|
||||||
~~~~~~~~~~
|
~~~~~~~~~~
|
||||||
|
|
||||||
Verify the ADM (Administrator) PIN specified as argument. This is typically needed in order
|
Verify the ADM (Administrator) PIN specified as argument. This is typically needed in order
|
||||||
to get write/update permissions to most of the files on SIM cards.
|
to get write/update permissions to most of the files on SIM cards.
|
||||||
|
|
||||||
|
@ -286,8 +303,6 @@ bulk_script
|
||||||
:module: pySim-shell
|
:module: pySim-shell
|
||||||
:func: PysimApp.bulk_script_parser
|
:func: PysimApp.bulk_script_parser
|
||||||
|
|
||||||
Run a script for bulk-provisioning of multiple cards.
|
|
||||||
|
|
||||||
|
|
||||||
echo
|
echo
|
||||||
~~~~
|
~~~~
|
||||||
|
@ -296,6 +311,13 @@ echo
|
||||||
:func: PysimApp.echo_parser
|
:func: PysimApp.echo_parser
|
||||||
|
|
||||||
|
|
||||||
|
apdu
|
||||||
|
~~~~
|
||||||
|
.. argparse::
|
||||||
|
:module: pySim-shell
|
||||||
|
:func: PySimCommands.apdu_cmd_parser
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Linear Fixed EF commands
|
Linear Fixed EF commands
|
||||||
------------------------
|
------------------------
|
||||||
|
@ -484,6 +506,26 @@ authenticate
|
||||||
:module: pySim.ts_31_102
|
:module: pySim.ts_31_102
|
||||||
:func: ADF_USIM.AddlShellCommands.authenticate_parser
|
:func: ADF_USIM.AddlShellCommands.authenticate_parser
|
||||||
|
|
||||||
|
terminal_profile
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
.. argparse::
|
||||||
|
:module: pySim.ts_31_102
|
||||||
|
:func: ADF_USIM.AddlShellCommands.term_prof_parser
|
||||||
|
|
||||||
|
envelope
|
||||||
|
~~~~~~~~
|
||||||
|
.. argparse::
|
||||||
|
:module: pySim.ts_31_102
|
||||||
|
:func: ADF_USIM.AddlShellCommands.envelope_parser
|
||||||
|
|
||||||
|
envelope_sms
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
.. argparse::
|
||||||
|
:module: pySim.ts_31_102
|
||||||
|
:func: ADF_USIM.AddlShellCommands.envelope_sms_parser
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
ARA-M commands
|
ARA-M commands
|
||||||
--------------
|
--------------
|
||||||
|
@ -546,21 +588,14 @@ Perform Config handshake with ARA-M applet: Tell it our version and retrieve its
|
||||||
|
|
||||||
NOTE: Not supported in all ARA-M implementations.
|
NOTE: Not supported in all ARA-M implementations.
|
||||||
|
|
||||||
.. argparse::
|
|
||||||
:module: pySim.ara_m
|
|
||||||
:func: ADF_ARAM.AddlShellCommands.get_config_parser
|
|
||||||
|
|
||||||
|
|
||||||
aram_store_ref_ar_do
|
aram_store_ref_ar_do
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
Store a [new] access rule on the ARA-M applet.
|
|
||||||
|
|
||||||
.. argparse::
|
.. argparse::
|
||||||
:module: pySim.ara_m
|
:module: pySim.ara_m
|
||||||
:func: ADF_ARAM.AddlShellCommands.store_ref_ar_do_parse
|
:func: ADF_ARAM.AddlShellCommands.store_ref_ar_do_parse
|
||||||
|
|
||||||
For example, to store an Android UICC carrier privilege rule for the SHA1 hash of the certificate used to sign the CoIMS android app of Supreeth Herle (https://github.com/herlesupreeth/CoIMS_Wiki) you can use the following command:
|
For example, to store an Android UICC carrier privilege rule for the SHA1 hash of the certificate used to sign the CoIMS android app of Supreeth Herle (https://github.com/herlesupreeth/CoIMS_Wiki) you can use the following command:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
pySIM-shell (MF/ADF.ARA-M)> aram_store_ref_ar_do --aid FFFFFFFFFFFF --device-app-id E46872F28B350B7E1F140DE535C2A8D5804F0BE3 --android-permissions 0000000000000001 --apdu-always
|
pySIM-shell (MF/ADF.ARA-M)> aram_store_ref_ar_do --aid FFFFFFFFFFFF --device-app-id E46872F28B350B7E1F140DE535C2A8D5804F0BE3 --android-permissions 0000000000000001 --apdu-always
|
||||||
|
|
|
@ -683,7 +683,8 @@ class PySimCommands(CommandSet):
|
||||||
def do_apdu(self, opts):
|
def do_apdu(self, opts):
|
||||||
"""Send a raw APDU to the card, and print SW + Response.
|
"""Send a raw APDU to the card, and print SW + Response.
|
||||||
DANGEROUS: pySim-shell will not know any card state changes, and
|
DANGEROUS: pySim-shell will not know any card state changes, and
|
||||||
not continue to work as expected if you e.g. select a different file."""
|
not continue to work as expected if you e.g. select a different
|
||||||
|
file."""
|
||||||
data, sw = self._cmd.card._scc._tp.send_apdu(opts.APDU)
|
data, sw = self._cmd.card._scc._tp.send_apdu(opts.APDU)
|
||||||
self._cmd.poutput("SW: %s %s, RESP: %s" % (sw, self._cmd.rs.interpret_sw(sw), data))
|
self._cmd.poutput("SW: %s %s, RESP: %s" % (sw, self._cmd.rs.interpret_sw(sw), data))
|
||||||
|
|
||||||
|
@ -739,7 +740,9 @@ class Iso7816Commands(CommandSet):
|
||||||
|
|
||||||
@cmd2.with_argparser(verify_chv_parser)
|
@cmd2.with_argparser(verify_chv_parser)
|
||||||
def do_verify_chv(self, opts):
|
def do_verify_chv(self, opts):
|
||||||
"""Verify (authenticate) using specified PIN code"""
|
"""Verify (authenticate) using specified CHV (PIN) code, which is how the specifications
|
||||||
|
call it if you authenticate yourself using the specified PIN. There usually is at least PIN1 and
|
||||||
|
PIN2."""
|
||||||
pin = self.get_code(opts.pin_code)
|
pin = self.get_code(opts.pin_code)
|
||||||
(data, sw) = self._cmd.card._scc.verify_chv(opts.pin_nr, h2b(pin))
|
(data, sw) = self._cmd.card._scc.verify_chv(opts.pin_nr, h2b(pin))
|
||||||
self._cmd.poutput("CHV verification successful")
|
self._cmd.poutput("CHV verification successful")
|
||||||
|
@ -812,7 +815,8 @@ class Iso7816Commands(CommandSet):
|
||||||
activate_file_parser.add_argument('NAME', type=str, help='File name or FID of file to activate')
|
activate_file_parser.add_argument('NAME', type=str, help='File name or FID of file to activate')
|
||||||
@cmd2.with_argparser(activate_file_parser)
|
@cmd2.with_argparser(activate_file_parser)
|
||||||
def do_activate_file(self, opts):
|
def do_activate_file(self, opts):
|
||||||
"""Activate the specified EF"""
|
"""Activate the specified EF. This used to be called REHABILITATE in TS 11.11 for classic
|
||||||
|
SIM. You need to specify the name or FID of the file to activate."""
|
||||||
(data, sw) = self._cmd.rs.activate_file(opts.NAME)
|
(data, sw) = self._cmd.rs.activate_file(opts.NAME)
|
||||||
|
|
||||||
def complete_activate_file(self, text, line, begidx, endidx) -> List[str]:
|
def complete_activate_file(self, text, line, begidx, endidx) -> List[str]:
|
||||||
|
|
|
@ -311,7 +311,7 @@ class ADF_ARAM(CardADF):
|
||||||
self._cmd.poutput_json(res_do.to_dict())
|
self._cmd.poutput_json(res_do.to_dict())
|
||||||
|
|
||||||
def do_aram_get_config(self, opts):
|
def do_aram_get_config(self, opts):
|
||||||
"""GET DATA [Config] on the ARA-M Applet"""
|
"""Perform GET DATA [Config] on the ARA-M Applet: Tell it our version and retrieve its version."""
|
||||||
res_do = ADF_ARAM.get_config(self._cmd.card._scc._tp)
|
res_do = ADF_ARAM.get_config(self._cmd.card._scc._tp)
|
||||||
if res_do:
|
if res_do:
|
||||||
self._cmd.poutput_json(res_do.to_dict())
|
self._cmd.poutput_json(res_do.to_dict())
|
||||||
|
@ -345,7 +345,7 @@ class ADF_ARAM(CardADF):
|
||||||
|
|
||||||
@cmd2.with_argparser(store_ref_ar_do_parse)
|
@cmd2.with_argparser(store_ref_ar_do_parse)
|
||||||
def do_aram_store_ref_ar_do(self, opts):
|
def do_aram_store_ref_ar_do(self, opts):
|
||||||
"""Perform STORE DATA [Command-Store-REF-AR-DO] to store a new access rule."""
|
"""Perform STORE DATA [Command-Store-REF-AR-DO] to store a (new) access rule."""
|
||||||
# REF
|
# REF
|
||||||
ref_do_content = []
|
ref_do_content = []
|
||||||
if opts.aid:
|
if opts.aid:
|
||||||
|
|
|
@ -1310,18 +1310,42 @@ class ADF_USIM(CardADF):
|
||||||
(data, sw) = self._cmd.card._scc.authenticate(opts.rand, opts.autn)
|
(data, sw) = self._cmd.card._scc.authenticate(opts.rand, opts.autn)
|
||||||
self._cmd.poutput_json(data)
|
self._cmd.poutput_json(data)
|
||||||
|
|
||||||
|
term_prof_parser = argparse.ArgumentParser()
|
||||||
|
term_prof_parser.add_argument('PROFILE', help='Hexstring of encoded terminal profile')
|
||||||
|
|
||||||
|
@cmd2.with_argparser(term_prof_parser)
|
||||||
def do_terminal_profile(self, arg):
|
def do_terminal_profile(self, arg):
|
||||||
"""Send a TERMINAL PROFILE command to the card."""
|
"""Send a TERMINAL PROFILE command to the card.
|
||||||
|
This is used to inform the card about which optional
|
||||||
|
features the terminal (modem/phone) supports, particularly
|
||||||
|
in the context of SIM Toolkit, Proactive SIM and OTA. You
|
||||||
|
must specify a hex-string with the encoded terminal profile
|
||||||
|
you want to send to the card."""
|
||||||
(data, sw) = self._cmd.card._scc.terminal_profile(arg)
|
(data, sw) = self._cmd.card._scc.terminal_profile(arg)
|
||||||
self._cmd.poutput('SW: %s, data: %s' % (sw, data))
|
self._cmd.poutput('SW: %s, data: %s' % (sw, data))
|
||||||
|
|
||||||
|
envelope_parser = argparse.ArgumentParser()
|
||||||
|
envelope_parser.add_argument('PAYLOAD', help='Hexstring of encoded payload to ENVELOPE')
|
||||||
|
|
||||||
|
@cmd2.with_argparser(envelope_parser)
|
||||||
def do_envelope(self, arg):
|
def do_envelope(self, arg):
|
||||||
"""Send an ENVELOPE command to the card."""
|
"""Send an ENVELOPE command to the card. This is how a
|
||||||
|
variety of information is communicated from the terminal
|
||||||
|
(modem/phone) to the card, particularly in the context of
|
||||||
|
SIM Toolkit, Proactive SIM and OTA."""
|
||||||
(data, sw) = self._cmd.card._scc.envelope(arg)
|
(data, sw) = self._cmd.card._scc.envelope(arg)
|
||||||
self._cmd.poutput('SW: %s, data: %s' % (sw, data))
|
self._cmd.poutput('SW: %s, data: %s' % (sw, data))
|
||||||
|
|
||||||
|
envelope_sms_parser = argparse.ArgumentParser()
|
||||||
|
envelope_sms_parser.add_argument('TPDU', help='Hexstring of encoded SMS TPDU')
|
||||||
|
|
||||||
|
@cmd2.with_argparser(envelope_sms_parser)
|
||||||
def do_envelope_sms(self, arg):
|
def do_envelope_sms(self, arg):
|
||||||
"""Send an ENVELOPE command to the card."""
|
"""Send an ENVELOPE(SMS-PP-Download) command to the card.
|
||||||
|
This emulates a terminal (modem/phone) having received a SMS
|
||||||
|
with a PID of 'SMS for the SIM card'. You can use this
|
||||||
|
command in the context of testing OTA related features
|
||||||
|
without a modem/phone or a cellular netwokr."""
|
||||||
tpdu_ie = SMS_TPDU()
|
tpdu_ie = SMS_TPDU()
|
||||||
tpdu_ie.from_bytes(h2b(arg))
|
tpdu_ie.from_bytes(h2b(arg))
|
||||||
dev_ids = DeviceIdentities(
|
dev_ids = DeviceIdentities(
|
||||||
|
|
Loading…
Reference in New Issue