<p>laforge has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/pysim/+/23600">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">docs: Initial documentation for pySim-shell<br><br>Many bits and pieces are still missing, but it's better than nothing...<br><br>Change-Id: I19fd56aed251d064f3e5d37ffad39c1e3e39989e<br>---<br>M docs/shell.rst<br>1 file changed, 227 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/00/23600/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/docs/shell.rst b/docs/shell.rst</span><br><span>index f9a2c82..314f633 100644</span><br><span>--- a/docs/shell.rst</span><br><span>+++ b/docs/shell.rst</span><br><span>@@ -1,2 +1,229 @@</span><br><span> pySim-shell</span><br><span> ===========</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+pySim-shell is an interactive command line shell for all kind of interactions with SIM cards.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The interactive shell provides command for</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* navigating the on-card filesystem hierarchy</span><br><span style="color: hsl(120, 100%, 40%);">+* authenticating with PINs such as ADM1</span><br><span style="color: hsl(120, 100%, 40%);">+* CHV/PIN management (VERIFY, ENABLE, DISABLE, UNBLOCK)</span><br><span style="color: hsl(120, 100%, 40%);">+* decoding of SELECT response (file control parameters)</span><br><span style="color: hsl(120, 100%, 40%);">+* reading and writing of files and records in raw, hex-encoded binary format</span><br><span style="color: hsl(120, 100%, 40%);">+* for some files where related support has been developed:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ * decoded reading (display file data in JSON format)</span><br><span style="color: hsl(120, 100%, 40%);">+ * decoded writing (encode from JSON to binary format, then write)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+By means of using the python ``cmd2`` module, various useful features improve usability:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* history of commands (persistent across restarts)</span><br><span style="color: hsl(120, 100%, 40%);">+* output re-direction to files on your computer</span><br><span style="color: hsl(120, 100%, 40%);">+* output piping through external tools like 'grep'</span><br><span style="color: hsl(120, 100%, 40%);">+* tab completion of commands and SELECT-able files/directories</span><br><span style="color: hsl(120, 100%, 40%);">+* interactive help for all commands</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+cmd2 basics</span><br><span style="color: hsl(120, 100%, 40%);">+-----------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+FIXME</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ISO7816 commands</span><br><span style="color: hsl(120, 100%, 40%);">+----------------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This category of commands relates to commands that originate in the ISO 7861-4 specifications,</span><br><span style="color: hsl(120, 100%, 40%);">+most of them have a 1:1 resemblance in the specification.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+select</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The ``select`` command is used to select a file, either by its FID, AID or by its symbolic name.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Try ``select`` with tab-completion to get a list of all current selectable items:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+::</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+  pySIM-shell (MF)> select</span><br><span style="color: hsl(120, 100%, 40%);">+  ..                2fe2              a0000000871004    EF.ARR            MF</span><br><span style="color: hsl(120, 100%, 40%);">+  2f00              3f00              ADF.ISIM          EF.DIR</span><br><span style="color: hsl(120, 100%, 40%);">+  2f05              7f10              ADF.USIM          EF.ICCID</span><br><span style="color: hsl(120, 100%, 40%);">+  2f06              7f20              DF.GSM            EF.PL</span><br><span style="color: hsl(120, 100%, 40%);">+  2f08              a0000000871002    DF.TELECOM        EF.UMPC</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Use ``select`` with a specific FID or name to select the new file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This will</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* output the [JSON decoded, if possible] select response</span><br><span style="color: hsl(120, 100%, 40%);">+* change the prompt to the newly selected file</span><br><span style="color: hsl(120, 100%, 40%);">+* enable any commands specific to the newly-selected file</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+::</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+  pySIM-shell (MF)> select ADF.USIM</span><br><span style="color: hsl(120, 100%, 40%);">+  {</span><br><span style="color: hsl(120, 100%, 40%);">+      "file_descriptor": {</span><br><span style="color: hsl(120, 100%, 40%);">+          "shareable": true,</span><br><span style="color: hsl(120, 100%, 40%);">+          "file_type": "df",</span><br><span style="color: hsl(120, 100%, 40%);">+          "structure": "no_info_given"</span><br><span style="color: hsl(120, 100%, 40%);">+      },</span><br><span style="color: hsl(120, 100%, 40%);">+      "df_name": "A0000000871002FFFFFFFF8907090000",</span><br><span style="color: hsl(120, 100%, 40%);">+      "proprietary_info": {</span><br><span style="color: hsl(120, 100%, 40%);">+          "uicc_characteristics": "71",</span><br><span style="color: hsl(120, 100%, 40%);">+          "available_memory": 101640</span><br><span style="color: hsl(120, 100%, 40%);">+      },</span><br><span style="color: hsl(120, 100%, 40%);">+      "life_cycle_status_int": "operational_activated",</span><br><span style="color: hsl(120, 100%, 40%);">+      "security_attrib_compact": "00",</span><br><span style="color: hsl(120, 100%, 40%);">+      "pin_status_template_do": "90017083010183018183010A83010B"</span><br><span style="color: hsl(120, 100%, 40%);">+  }</span><br><span style="color: hsl(120, 100%, 40%);">+  pySIM-shell (MF/ADF.USIM)></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+change_chv</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This command allows you to change a CHV (PIN).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+disable_chv</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This command allows you to disable a CHV (PIN).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+enable_chv</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This command allows you to enable a CHV (PIN).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+unblock_chv</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This command allows you to unblock a CHV (PIN) using the PUK.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+verify_chv</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This command allows you to verify a CHV (PIN), which is how the specifications call</span><br><span style="color: hsl(120, 100%, 40%);">+it if you authenticate yourself with the said CHV/PIN.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+pySim commands</span><br><span style="color: hsl(120, 100%, 40%);">+--------------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Commands in this category are pySim specific; they do not have a 1:1 correspondence to ISO 7816</span><br><span style="color: hsl(120, 100%, 40%);">+or 3GPP commands. Mostly they will operate either only on local (in-memory) state, or execute</span><br><span style="color: hsl(120, 100%, 40%);">+a complex sequence of card-commands.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+desc</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Display human readable file description for the currently selected file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+dir</span><br><span style="color: hsl(120, 100%, 40%);">+~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+::</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+  usage: dir [-h] [--fids] [--names] [--apps] [--all]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+  Show a listing of files available in currently selected DF or MF</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+  optional arguments:</span><br><span style="color: hsl(120, 100%, 40%);">+    -h, --help  show this help message and exit</span><br><span style="color: hsl(120, 100%, 40%);">+    --fids      Show file identifiers</span><br><span style="color: hsl(120, 100%, 40%);">+    --names     Show file names</span><br><span style="color: hsl(120, 100%, 40%);">+    --apps      Show applications</span><br><span style="color: hsl(120, 100%, 40%);">+    --all       Show all selectable identifiers and names</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+export</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+tree</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+verify_adm</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Linear Fixed EF commands</span><br><span style="color: hsl(120, 100%, 40%);">+------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These commands become enabled only when your currently selected file is of *Linear Fixed EF* type.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+read_record</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+read_record_decoded</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+update_record</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+update_record_decoded</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Transparent EF commands</span><br><span style="color: hsl(120, 100%, 40%);">+-----------------------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These commands become enabled only when your currently selected file is of *Transparent EF* type.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+read_binary</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+read_binary_decoded</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+update_binary</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+update_binary_decoded</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+cmd2 settable parameters</span><br><span style="color: hsl(120, 100%, 40%);">+------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+``cmd2`` has the concept of *settable parameters* which act a bit like environment variables in an OS-level</span><br><span style="color: hsl(120, 100%, 40%);">+shell: They can be read and set, and they will influence the behavior somehow.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+conserve_write</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If enabled, pySim will (when asked to write to a card) always first read the respective file/record and</span><br><span style="color: hsl(120, 100%, 40%);">+verify if the to-be-written value differs from the current on-card value.  If not, the write will be skipped.</span><br><span style="color: hsl(120, 100%, 40%);">+Writes will only be performed if the new value is different from the current on-card value.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If disabled, pySim will always write irrespective of the current/new value.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+debug</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If enabled, full python back-traces will be displayed in case of exceptions</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+numeric_path</span><br><span style="color: hsl(120, 100%, 40%);">+~~~~~~~~~~~~</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Boolean variable that determines if path (e.g. in prompt) is displayed with numeric FIDs or string names.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+::</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+  pySIM-shell (MF/EF.ICCID)> set numeric_path True</span><br><span style="color: hsl(120, 100%, 40%);">+  numeric_path - was: False</span><br><span style="color: hsl(120, 100%, 40%);">+  now: True</span><br><span style="color: hsl(120, 100%, 40%);">+  pySIM-shell (3f00/2fe2)> set numeric_path False</span><br><span style="color: hsl(120, 100%, 40%);">+  numeric_path - was: True</span><br><span style="color: hsl(120, 100%, 40%);">+  now: False</span><br><span style="color: hsl(120, 100%, 40%);">+  pySIM-shell (MF/EF.ICCID)> help set</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/pysim/+/23600">change 23600</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/pysim/+/23600"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: pysim </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I19fd56aed251d064f3e5d37ffad39c1e3e39989e </div>
<div style="display:none"> Gerrit-Change-Number: 23600 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>