From 12af793d4be9171c09ed7a31f5a8693e29210bb3 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Tue, 15 Feb 2022 16:39:08 +0100 Subject: [PATCH] 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 --- docs/conf.py | 2 +- docs/index.rst | 2 +- docs/shell.rst | 71 ++++++++++++++++++++++++++++++++++------------ pySim-shell.py | 10 +++++-- pySim/ara_m.py | 4 +-- pySim/ts_31_102.py | 30 ++++++++++++++++++-- 6 files changed, 91 insertions(+), 28 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a96b87e2..6fea583d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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' diff --git a/docs/index.rst b/docs/index.rst index c647880d..471802a7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,7 +34,7 @@ pySim consists of several parts: * the [legacy] :ref:`pySim-prog and pySim-read tools` .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: shell diff --git a/docs/shell.rst b/docs/shell.rst index 0f3139f8..f24dc93b 100644 --- a/docs/shell.rst +++ b/docs/shell.rst @@ -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 diff --git a/pySim-shell.py b/pySim-shell.py index ec417c78..0753b100 100755 --- a/pySim-shell.py +++ b/pySim-shell.py @@ -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]: diff --git a/pySim/ara_m.py b/pySim/ara_m.py index 0928f8dd..59f205c3 100644 --- a/pySim/ara_m.py +++ b/pySim/ara_m.py @@ -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: diff --git a/pySim/ts_31_102.py b/pySim/ts_31_102.py index 3995dfad..c6bfa2dc 100644 --- a/pySim/ts_31_102.py +++ b/pySim/ts_31_102.py @@ -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(