laforge has uploaded this change for review. (
https://gerrit.osmocom.org/c/pysim/+/34942?usp=email )
Change subject: docs: shell: Various documentation updates/extensions
......................................................................
docs: shell: Various documentation updates/extensions
* examples for export, verify_adm, reset, apdu
* explain CSV option for verify_adm
* fix 'tree' example (--help shouldn't be there)
Change-Id: I6ed8d8c5cf268ad3534e988eff9501f388b8d80f
---
M docs/shell.rst
1 file changed, 90 insertions(+), 1 deletion(-)
git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/42/34942/1
diff --git a/docs/shell.rst b/docs/shell.rst
index 2f99cf5..97a1829 100644
--- a/docs/shell.rst
+++ b/docs/shell.rst
@@ -101,6 +101,19 @@
all/most files.
+Example:
+::
+
+ pySIM-shell (00:MF)> export --json > /tmp/export.json
+ EXCEPTION of type 'RuntimeError' occurred with message: 'unable to export 50
elementary file(s) and 2 dedicated file(s), also had to stop early due to
exception:6e00: ARA-M - Invalid class'
+ To enable full traceback, run the following command: 'set debug true'
+ pySIM-shell (00:MF)>
+
+The exception above is more or less expected. It just means that 50 files
which are defined (most likely as
+optional files in some later 3GPP release) were not found on the card, or were
invalidated/disabled when
+trying to SELECT them.
+
+
tree
~~~~
Display a tree of the card filesystem. It is important to note that this
displays a tree
@@ -110,7 +123,7 @@
Example:
::
- pySIM-shell (00:MF)> tree --help
+ pySIM-shell (00:MF)> tree
EF.DIR 2f00 Application Directory
EF.ICCID 2fe2 ICC Identification
EF.PL 2f05 Preferred Languages
@@ -129,11 +142,62 @@
Currently only ADM1 is supported.
+Example (successful):
+::
+
+ pySIM-shell (00:MF)> verify_adm 11111111
+ pySIM-shell (00:MF)>
+
+In the above case, the ADM was successfully verified. Please make always sure
to use the correct ADM1 for the
+specific card you have inserted! If you present a wrong ADM1 value several
times consecutively, your card
+ADM1 will likely be permanently locked, meaning you will never be able to
reach ADM1 privilege level.
+For sysmoUSIM/ISIM products, three consecutive wrong ADM1 values will lock the
ADM1.
+
+Example (erroneous):
+::
+
+ pySIM-shell (00:MF)> verify_adm 1
+ EXCEPTION of type 'RuntimeError' occurred with message: 'Failed to verify
chv_no 0x0A with code 0x31FFFFFFFFFFFFFF, 2 tries left.'
+ To enable full traceback, run the following command: 'set debug true'
+
+If you frequently work with the same set of cards that you need to modify
using their ADM1, you can put a CSV
+file with those cards ICCID + ADM1 values into a CSV (comma separated value)
file at ``~/.osmocom/pysim/card_data.csv``. In this case,
+you can use the ``verify_adm`` command *without specifying an ADM1 value*.
+
+Example (successful):
+
+::
+
+ pySIM-shell (00:MF)> verify_adm
+ found ADM-PIN '11111111' for ICCID '898821190000000512'
+ pySIM-shell (00:MF)>
+
+In this case, the CSV file contained a record for the ICCID of the card
(11111111) and that value was used to
+successfully verify ADM1.
+
+
+Example (erroneous):
+::
+
+ pySIM-shell (00:MF)> verify_adm
+ EXCEPTION of type 'ValueError' occurred with message: 'cannot find ADM-PIN
for ICCID '898821190000000512''
+ To enable full traceback, run the following command: 'set debug true'
+
+In this case there was no record for the ICCID of the card in the CSV file.
+
reset
~~~~~
Perform card reset and display the card ATR.
+Example:
+::
+
+ pySIM-shell (00:MF)> reset
+ Card ATR: 3b9f96801f878031e073fe211b674a357530350259c4
+ pySIM-shell (00:MF)> reset
+
+
intro
~~~~~
[Re-]Display the introductory banner
@@ -165,6 +229,18 @@
:module: pySim-shell
:func: PysimApp.apdu_cmd_parser
+Example:
+
+::
+
+ pySIM-shell (00:MF)> apdu 00a40400023f00
+ SW: 6700
+
+In the above case the raw APDU hex-string ``00a40400023f00`` was sent to the
card, to which it responded with
+status word ``6700``. Keep in mind that pySim-shell has no idea what kind of
raw commands you are sending to the
+card, and it hence is unable to synchronize its internal state (such as the
currently selected file) with the
+card. The use of this command should hence be constrained to commands that do
not have any high-level support
+in pySim-shell yet.
ISO7816 commands
--
To view, visit https://gerrit.osmocom.org/c/pysim/+/34942?usp=email
To unsubscribe, or for help writing mail filters, visit
https://gerrit.osmocom.org/settings
Gerrit-Project: pysim
Gerrit-Branch: master
Gerrit-Change-Id: I6ed8d8c5cf268ad3534e988eff9501f388b8d80f
Gerrit-Change-Number: 34942
Gerrit-PatchSet: 1
Gerrit-Owner: laforge <[email protected]>
Gerrit-MessageType: newchange
