17 Feb
2022
17 Feb
'22
12:42 p.m.
laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/pysim/+/27237
)
Change subject: doc: Improve documentation in various places
......................................................................
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
---
M docs/conf.py
M docs/index.rst
M docs/shell.rst
M pySim-shell.py
M pySim/ara_m.py
M pySim/ts_31_102.py
6 files changed, 91 insertions(+), 28 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/37/27237/1
diff --git a/docs/conf.py b/docs/conf.py
index a96b87e..6fea583 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,7 @@
# -- 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'
diff --git a/docs/index.rst b/docs/index.rst
index c647880..471802a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,7 +34,7 @@
* the [legacy] :ref:`pySim-prog and pySim-read tools<Legacy tools>`
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
:caption: Contents:
shell
diff --git a/docs/shell.rst b/docs/shell.rst
index 0f3139f..f24dc93 100644
--- a/docs/shell.rst
+++ b/docs/shell.rst
@@ -164,9 +164,6 @@
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 @@
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 @@
:func: Iso7816Commands.suspend_uicc_parser
+
pySim commands
--------------
@@ -221,7 +216,6 @@
desc
~~~~
-
Display human readable file description for the currently selected file.
@@ -231,6 +225,17 @@
: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 @@
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 @@
:module: pySim-shell
:func: PysimApp.bulk_script_parser
-Run a script for bulk-provisioning of multiple cards.
-
echo
~~~~
@@ -296,6 +311,13 @@
:func: PysimApp.echo_parser
+apdu
+~~~~
+.. argparse::
+ :module: pySim-shell
+ :func: PySimCommands.apdu_cmd_parser
+
+
Linear Fixed EF commands
------------------------
@@ -484,6 +506,26 @@
: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 @@
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
diff --git a/pySim-shell.py b/pySim-shell.py
index ec417c7..0753b10 100755
--- a/pySim-shell.py
+++ b/pySim-shell.py
@@ -683,7 +683,8 @@
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 @@
@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 @@
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]:
diff --git a/pySim/ara_m.py b/pySim/ara_m.py
index 0928f8d..59f205c 100644
--- a/pySim/ara_m.py
+++ b/pySim/ara_m.py
@@ -311,7 +311,7 @@
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 @@
@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:
diff --git a/pySim/ts_31_102.py b/pySim/ts_31_102.py
index 3995dfa..c6bfa2d 100644
--- a/pySim/ts_31_102.py
+++ b/pySim/ts_31_102.py
@@ -1310,18 +1310,42 @@
(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(
--
To view, visit https://gerrit.osmocom.org/c/pysim/+/27237
To unsubscribe, or for help writing mail filters, visit
https://gerrit.osmocom.org/settings
Gerrit-Project: pysim
Gerrit-Branch: master
Gerrit-Change-Id: Ib88bb7d12faaac7d149ee1f6379bc128b83bbdd5
Gerrit-Change-Number: 27237
Gerrit-PatchSet: 1
Gerrit-Owner: laforge <laforge(a)osmocom.org>
Gerrit-MessageType: newchange