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 <laforge(a)osmocom.org> Gerrit-MessageType: newchange