laforge has submitted this change. ( https://gerrit.osmocom.org/c/pysim/+/34938?usp=email )
Change subject: docs: shell: Re-order the command sections/classes
......................................................................
docs: shell: Re-order the command sections/classes
the generic pysim command should precede those from specs like ISO7816
Change-Id: I11e66757f10cc28fda547244ae09d51dacd70824
---
M docs/shell.rst
1 file changed, 122 insertions(+), 110 deletions(-)
Approvals:
laforge: Looks good to me, approved
Jenkins Builder: Verified
pespin: Looks good to me, but someone else must approve
diff --git a/docs/shell.rst b/docs/shell.rst
index 12c0493..13d71bb 100644
--- a/docs/shell.rst
+++ b/docs/shell.rst
@@ -55,6 +55,117 @@
to learn about those.
+pySim commands
+--------------
+
+Commands in this category are pySim specific; they do not have a 1:1 correspondence to ISO 7816
+or 3GPP commands. Mostly they will operate either only on local (in-memory) state, or execute
+a complex sequence of card-commands.
+
+desc
+~~~~
+Display human readable file description for the currently selected file.
+
+
+dir
+~~~
+.. argparse::
+ :module: pySim-shell
+ :func: PySimCommands.dir_parser
+
+Example:
+::
+
+ pySIM-shell (00: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
+~~~~~~
+.. argparse::
+ :module: pySim-shell
+ :func: PySimCommands.export_parser
+
+Please note that `export` works relative to the current working
+directory, so if you are in `MF`, then the export will contain all known
+files on the card. However, if you are in `ADF.ISIM`, only files below
+that ADF will be part of the export.
+
+Furthermore, it is strongly advised to first enter the ADM1 pin
+(`verify_adm`) to maximize the chance of having permission to read
+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 (00: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.
+
+Currently only ADM1 is supported.
+
+
+reset
+~~~~~
+Perform card reset and display the card ATR.
+
+intro
+~~~~~
+[Re-]Display the introductory banner
+
+
+equip
+~~~~~
+Equip pySim-shell with a card; particularly useful if the program was
+started before a card was present, or after a card has been replaced by
+the user while pySim-shell was kept running.
+
+bulk_script
+~~~~~~~~~~~
+.. argparse::
+ :module: pySim-shell
+ :func: PysimApp.bulk_script_parser
+
+
+echo
+~~~~
+.. argparse::
+ :module: pySim-shell
+ :func: PysimApp.echo_parser
+
+
+apdu
+~~~~
+.. argparse::
+ :module: pySim-shell
+ :func: PysimApp.apdu_cmd_parser
+
+
ISO7816 commands
----------------
@@ -243,116 +354,6 @@
:func: CardProfileUICC.AddlShellCommands.resume_uicc_parser
-pySim commands
---------------
-
-Commands in this category are pySim specific; they do not have a 1:1 correspondence to ISO 7816
-or 3GPP commands. Mostly they will operate either only on local (in-memory) state, or execute
-a complex sequence of card-commands.
-
-desc
-~~~~
-Display human readable file description for the currently selected file.
-
-
-dir
-~~~
-.. argparse::
- :module: pySim-shell
- :func: PySimCommands.dir_parser
-
-Example:
-::
-
- pySIM-shell (00: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
-~~~~~~
-.. argparse::
- :module: pySim-shell
- :func: PySimCommands.export_parser
-
-Please note that `export` works relative to the current working
-directory, so if you are in `MF`, then the export will contain all known
-files on the card. However, if you are in `ADF.ISIM`, only files below
-that ADF will be part of the export.
-
-Furthermore, it is strongly advised to first enter the ADM1 pin
-(`verify_adm`) to maximize the chance of having permission to read
-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 (00: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.
-
-Currently only ADM1 is supported.
-
-
-reset
-~~~~~
-Perform card reset and display the card ATR.
-
-intro
-~~~~~
-[Re-]Display the introductory banner
-
-
-equip
-~~~~~
-Equip pySim-shell with a card; particularly useful if the program was
-started before a card was present, or after a card has been replaced by
-the user while pySim-shell was kept running.
-
-bulk_script
-~~~~~~~~~~~
-.. argparse::
- :module: pySim-shell
- :func: PysimApp.bulk_script_parser
-
-
-echo
-~~~~
-.. argparse::
- :module: pySim-shell
- :func: PysimApp.echo_parser
-
-
-apdu
-~~~~
-.. argparse::
- :module: pySim-shell
- :func: PysimApp.apdu_cmd_parser
-
Linear Fixed EF commands
--
To view, visit https://gerrit.osmocom.org/c/pysim/+/34938?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: I11e66757f10cc28fda547244ae09d51dacd70824
Gerrit-Change-Number: 34938
Gerrit-PatchSet: 2
Gerrit-Owner: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: pespin <pespin(a)sysmocom.de>
Gerrit-MessageType: merged
laforge has submitted this change. ( https://gerrit.osmocom.org/c/pysim/+/34939?usp=email )
Change subject: docs: Fix docstring syntax to avoid warnings
......................................................................
docs: Fix docstring syntax to avoid warnings
pySim/tlv.py:docstring of pySim.tlv.IE.from_bytes:1: ERROR: Unknown target name: "part".
pySim/tlv.py:docstring of pySim.tlv.IE.to_bytes:1: ERROR: Unknown target name: "part".
Change-Id: I170176910c4519005b9276dbe5854aaaecb58efb
---
M pySim/tlv.py
1 file changed, 14 insertions(+), 2 deletions(-)
Approvals:
laforge: Looks good to me, approved
pespin: Looks good to me, but someone else must approve
Jenkins Builder: Verified
diff --git a/pySim/tlv.py b/pySim/tlv.py
index 827972f..7f20559 100644
--- a/pySim/tlv.py
+++ b/pySim/tlv.py
@@ -178,7 +178,7 @@
"""Convert the internal representation to entire IE including IE header."""
def to_bytes(self) -> bytes:
- """Convert the internal representation _of the value part_ to binary bytes."""
+ """Convert the internal representation *of the value part* to binary bytes."""
if self.is_constructed():
# concatenate the encoded IE of all children to form the value part
out = b''
@@ -189,7 +189,7 @@
return super().to_bytes()
def from_bytes(self, do: bytes):
- """Parse _the value part_ from binary bytes to internal representation."""
+ """Parse *the value part* from binary bytes to internal representation."""
if self.nested_collection:
self.children = self.nested_collection.from_bytes(do)
else:
--
To view, visit https://gerrit.osmocom.org/c/pysim/+/34939?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: I170176910c4519005b9276dbe5854aaaecb58efb
Gerrit-Change-Number: 34939
Gerrit-PatchSet: 2
Gerrit-Owner: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: pespin <pespin(a)sysmocom.de>
Gerrit-MessageType: merged
laforge has submitted this change. ( https://gerrit.osmocom.org/c/pysim/+/34944?usp=email )
Change subject: pySim-shell: Use argparser for verify_adm to support --help
......................................................................
pySim-shell: Use argparser for verify_adm to support --help
Let's add a proper argparser instance for the 'verify_adm' command,
avoiding situations where the user types 'verif_adm --help' and then
--help is interpreted as the PIN value, removing one more attempt from
the failed ADM1 counter.
Let's use that opportunity to improve the documentation of the command.
Change-Id: I3321fae66a11efd00c53b66c7890fce84796e658
---
M docs/shell.rst
M pySim-shell.py
2 files changed, 32 insertions(+), 7 deletions(-)
Approvals:
laforge: Looks good to me, approved
Jenkins Builder: Verified
diff --git a/docs/shell.rst b/docs/shell.rst
index f437495..d8c0967 100644
--- a/docs/shell.rst
+++ b/docs/shell.rst
@@ -137,10 +137,11 @@
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.
-Currently only ADM1 is supported.
+.. argparse::
+ :module: pySim-shell
+ :func: PySimCommands.verify_adm_parser
+
Example (successful):
::
diff --git a/pySim-shell.py b/pySim-shell.py
index c02555f..7aaa234 100755
--- a/pySim-shell.py
+++ b/pySim-shell.py
@@ -776,11 +776,19 @@
else:
self._cmd.poutput("no description available")
- def do_verify_adm(self, arg):
- """VERIFY the ADM1 PIN"""
- if arg:
+ verify_adm_parser = argparse.ArgumentParser()
+ verify_adm_parser.add_argument('ADM1', nargs='?', type=str,
+ help='ADM1 pin value. If none given, CSV file will be queried')
+
+ @cmd2.with_argparser(verify_adm_parser)
+ def do_verify_adm(self, opts):
+ """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.
+
+Currently only ADM1 is supported."""
+ if opts.ADM1:
# use specified ADM-PIN
- pin_adm = sanitize_pin_adm(arg)
+ pin_adm = sanitize_pin_adm(opts.ADM1)
else:
# try to find an ADM-PIN if none is specified
result = card_key_provider_get_field(
--
To view, visit https://gerrit.osmocom.org/c/pysim/+/34944?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: I3321fae66a11efd00c53b66c7890fce84796e658
Gerrit-Change-Number: 34944
Gerrit-PatchSet: 3
Gerrit-Owner: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: pespin <pespin(a)sysmocom.de>
Gerrit-MessageType: merged
laforge has submitted this change. ( 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(-)
Approvals:
pespin: Looks good to me, but someone else must approve
Jenkins Builder: Verified
laforge: Looks good to me, approved
diff --git a/docs/shell.rst b/docs/shell.rst
index ab67738..81e84d2 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: 2
Gerrit-Owner: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: pespin <pespin(a)sysmocom.de>
Gerrit-MessageType: merged
Attention is currently required from: pespin.
laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/pysim/+/34944?usp=email )
Change subject: pySim-shell: Use argparser for verify_adm to support --help
......................................................................
Patch Set 3: Code-Review+2
--
To view, visit https://gerrit.osmocom.org/c/pysim/+/34944?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: I3321fae66a11efd00c53b66c7890fce84796e658
Gerrit-Change-Number: 34944
Gerrit-PatchSet: 3
Gerrit-Owner: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: pespin <pespin(a)sysmocom.de>
Gerrit-Attention: pespin <pespin(a)sysmocom.de>
Gerrit-Comment-Date: Thu, 02 Nov 2023 23:42:56 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: Yes
Gerrit-MessageType: comment
laforge has posted comments on this change. ( https://gerrit.osmocom.org/c/pysim/+/34943?usp=email )
Change subject: pySim-shell: Add copyright statement and link to online manual to banner
......................................................................
Patch Set 2: Code-Review+2
--
To view, visit https://gerrit.osmocom.org/c/pysim/+/34943?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: Ie86822e73bccb3c585cecc818d4462d4ca6e43c2
Gerrit-Change-Number: 34943
Gerrit-PatchSet: 2
Gerrit-Owner: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge(a)osmocom.org>
Gerrit-Reviewer: pespin <pespin(a)sysmocom.de>
Gerrit-Comment-Date: Thu, 02 Nov 2023 23:42:48 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: Yes
Gerrit-MessageType: comment