sim-card
/
pysim
mirror of https://gerrit.osmocom.org/pysim
10
0
Fork 0
Code Issues Releases Wiki Activity

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
changes/37/27237/1
Harald Welte 2022-02-15 16:39:08 +01:00
parent d01bd3632c
commit 12af793d4b
6 changed files with 91 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/conf.py
View File

@ -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'

2
docs/index.rst
View File

@ -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

71
docs/shell.rst
View File

@ -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

10
pySim-shell.py
View File

@ -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]:

4
pySim/ara_m.py
View File

@ -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:

30
pySim/ts_31_102.py
View File

@ -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(