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: Ib88bb7d12faaac7d149ee1f6379bc128b83bbdd5changes/37/27237/1
parent
d01bd3632c
commit
12af793d4b
|
@ -18,7 +18,7 @@ sys.path.insert(0, os.path.abspath('..'))
|
|||
# -- Project information -----------------------------------------------------
|
||||
|
||||
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'
|
||||
|
||||
|
||||
|
|
|
@ -34,7 +34,7 @@ pySim consists of several parts:
|
|||
* the [legacy] :ref:`pySim-prog and pySim-read tools<Legacy tools>`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
:caption: Contents:
|
||||
|
||||
shell
|
||||
|
|
|
@ -164,9 +164,6 @@ unblock_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::
|
||||
:module: pySim-shell
|
||||
: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 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::
|
||||
:module: pySim-shell
|
||||
:func: Iso7816Commands.activate_file_parser
|
||||
|
@ -212,6 +206,7 @@ including the electrical power down.
|
|||
:func: Iso7816Commands.suspend_uicc_parser
|
||||
|
||||
|
||||
|
||||
pySim commands
|
||||
--------------
|
||||
|
||||
|
@ -221,7 +216,6 @@ a complex sequence of card-commands.
|
|||
|
||||
desc
|
||||
~~~~
|
||||
|
||||
Display human readable file description for the currently selected file.
|
||||
|
||||
|
||||
|
@ -231,6 +225,17 @@ dir
|
|||
:module: pySim-shell
|
||||
: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
|
||||
~~~~~~
|
||||
|
@ -250,15 +255,27 @@ all/most files.
|
|||
|
||||
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
|
||||
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 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.
|
||||
|
||||
|
@ -286,8 +303,6 @@ bulk_script
|
|||
:module: pySim-shell
|
||||
:func: PysimApp.bulk_script_parser
|
||||
|
||||
Run a script for bulk-provisioning of multiple cards.
|
||||
|
||||
|
||||
echo
|
||||
~~~~
|
||||
|
@ -296,6 +311,13 @@ echo
|
|||
:func: PysimApp.echo_parser
|
||||
|
||||
|
||||
apdu
|
||||
~~~~
|
||||
.. argparse::
|
||||
:module: pySim-shell
|
||||
:func: PySimCommands.apdu_cmd_parser
|
||||
|
||||
|
||||
|
||||
Linear Fixed EF commands
|
||||
------------------------
|
||||
|
@ -484,6 +506,26 @@ authenticate
|
|||
:module: pySim.ts_31_102
|
||||
: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
|
||||
--------------
|
||||
|
@ -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.
|
||||
|
||||
.. argparse::
|
||||
:module: pySim.ara_m
|
||||
:func: ADF_ARAM.AddlShellCommands.get_config_parser
|
||||
|
||||
|
||||
aram_store_ref_ar_do
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
Store a [new] access rule on the ARA-M applet.
|
||||
|
||||
.. argparse::
|
||||
:module: pySim.ara_m
|
||||
: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:
|
||||
|
||||
::
|
||||
|
||||
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):
|
||||
"""Send a raw APDU to the card, and print SW + Response.
|
||||
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)
|
||||
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)
|
||||
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)
|
||||
(data, sw) = self._cmd.card._scc.verify_chv(opts.pin_nr, h2b(pin))
|
||||
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')
|
||||
@cmd2.with_argparser(activate_file_parser)
|
||||
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)
|
||||
|
||||
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())
|
||||
|
||||
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)
|
||||
if res_do:
|
||||
self._cmd.poutput_json(res_do.to_dict())
|
||||
|
@ -345,7 +345,7 @@ class ADF_ARAM(CardADF):
|
|||
|
||||
@cmd2.with_argparser(store_ref_ar_do_parse)
|
||||
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_do_content = []
|
||||
if opts.aid:
|
||||
|
|
|
@ -1310,18 +1310,42 @@ class ADF_USIM(CardADF):
|
|||
(data, sw) = self._cmd.card._scc.authenticate(opts.rand, opts.autn)
|
||||
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):
|
||||
"""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)
|
||||
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):
|
||||
"""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)
|
||||
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):
|
||||
"""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.from_bytes(h2b(arg))
|
||||
dev_ids = DeviceIdentities(
|
||||
|
|
Loading…
Reference in New Issue