aboutsummaryrefslogtreecommitdiffstats
path: root/docs/shell.rst
blob: 30938fe5cd50d3989ace861ecebdc7e19a2bfe3e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
pySim-shell
===========

pySim-shell is an interactive command line shell for all kind of interactions with SIM cards.

The interactive shell provides command for

* navigating the on-card filesystem hierarchy
* authenticating with PINs such as ADM1
* CHV/PIN management (VERIFY, ENABLE, DISABLE, UNBLOCK)
* decoding of SELECT response (file control parameters)
* reading and writing of files and records in raw, hex-encoded binary format
* for some files where related support has been developed:

 * decoded reading (display file data in JSON format)
 * decoded writing (encode from JSON to binary format, then write)

By means of using the python ``cmd2`` module, various useful features improve usability:

* history of commands (persistent across restarts)
* output re-direction to files on your computer
* output piping through external tools like 'grep'
* tab completion of commands and SELECT-able files/directories
* interactive help for all commands


cmd2 basics
-----------

FIXME



ISO7816 commands
----------------

This category of commands relates to commands that originate in the ISO 7861-4 specifications,
most of them have a 1:1 resemblance in the specification.

select
~~~~~~

The ``select`` command is used to select a file, either by its FID, AID or by its symbolic name.

Try ``select`` with tab-completion to get a list of all current selectable items:

::

  pySIM-shell (MF)> select
  ..                2fe2              a0000000871004    EF.ARR            MF
  2f00              3f00              ADF.ISIM          EF.DIR
  2f05              7f10              ADF.USIM          EF.ICCID
  2f06              7f20              DF.GSM            EF.PL
  2f08              a0000000871002    DF.TELECOM        EF.UMPC

Use ``select`` with a specific FID or name to select the new file.

This will

* output the [JSON decoded, if possible] select response
* change the prompt to the newly selected file
* enable any commands specific to the newly-selected file

::

  pySIM-shell (MF)> select ADF.USIM
  {
      "file_descriptor": {
          "shareable": true,
          "file_type": "df",
          "structure": "no_info_given"
      },
      "df_name": "A0000000871002FFFFFFFF8907090000",
      "proprietary_info": {
          "uicc_characteristics": "71",
          "available_memory": 101640
      },
      "life_cycle_status_int": "operational_activated",
      "security_attrib_compact": "00",
      "pin_status_template_do": "90017083010183018183010A83010B"
  }
  pySIM-shell (MF/ADF.USIM)>



change_chv
~~~~~~~~~~
.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.change_chv_parser


disable_chv
~~~~~~~~~~~
.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.disable_chv_parser


enable_chv
~~~~~~~~~~
.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.enable_chv_parser


unblock_chv
~~~~~~~~~~~
.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.unblock_chv_parser


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

deactivate_file
~~~~~~~~~~~~~~~
Deactivate the currently selected file.  This used to be called INVALIDATE in TS 11.11.


activate_file
~~~~~~~~~~~~~
Activate the currently selected file.  This used to be called REHABILITATE in TS 11.11.

open_channel
~~~~~~~~~~~~
.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.open_chan_parser

close_channel
~~~~~~~~~~~~~
.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.close_chan_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


export
~~~~~~
.. argparse::
   :module: pySim-shell
   :func: PySimCommands.export_parser


tree
~~~~
FIXME


verify_adm
~~~~~~~~~~
FIXME


Linear Fixed EF commands
------------------------

These commands become enabled only when your currently selected file is of *Linear Fixed EF* type.

read_record
~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: LinFixedEF.ShellCommands.read_rec_parser


read_record_decoded
~~~~~~~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: LinFixedEF.ShellCommands.read_rec_dec_parser


read_records
~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: LinFixedEF.ShellCommands.read_recs_parser


read_records_decoded
~~~~~~~~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: LinFixedEF.ShellCommands.read_recs_dec_parser


update_record
~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: LinFixedEF.ShellCommands.upd_rec_parser


update_record_decoded
~~~~~~~~~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: LinFixedEF.ShellCommands.upd_rec_dec_parser


edit_record_decoded
~~~~~~~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: LinFixedEF.ShellCommands.edit_rec_dec_parser

This command will read the selected record, decode it to its JSON representation, save
that JSON to a temporary file on your computer, and launch your configured text editor.

You may then perform whatever modifications to the JSON representation, save + leave your
text editor.

Afterwards, the modified JSON will be re-encoded to the binary format, and the result written
back to the record on the SIM card.

This allows for easy interactive modification of records.



Transparent EF commands
-----------------------

These commands become enabled only when your currently selected file is of *Transparent EF* type.


read_binary
~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: TransparentEF.ShellCommands.read_bin_parser


read_binary_decoded
~~~~~~~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: TransparentEF.ShellCommands.read_bin_dec_parser


update_binary
~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: TransparentEF.ShellCommands.upd_bin_parser


update_binary_decoded
~~~~~~~~~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: TransparentEF.ShellCommands.upd_bin_dec_parser

In normal operation, update_binary_decoded needs a JSON document representing the entire file contents as
input.  This can be inconvenient if you want to keep 99% of the content but just toggle one specific
parameter.   That's where the JSONpath support comes in handy:  You can specify a JSONpath to an element
inside the document as well as a new value for tat field:

Th below example demonstrates this by modifying the ofm field within EF.AD:

::

  pySIM-shell (MF/ADF.USIM/EF.AD)> read_binary_decoded
  {
      "ms_operation_mode": "normal",
      "specific_facilities": {
          "ofm": true
      },
      "len_of_mnc_in_imsi": 2
  }
  pySIM-shell (MF/ADF.USIM/EF.AD)> update_binary_decoded --json-path specific_facilities.ofm false
  pySIM-shell (MF/ADF.USIM/EF.AD)> read_binary_decoded
  {
      "ms_operation_mode": "normal",
      "specific_facilities": {
          "ofm": false
      },
      "len_of_mnc_in_imsi": 2
  }


edit_binary_decoded
~~~~~~~~~~~~~~~~~~~
This command will read the selected binary EF, decode it to its JSON representation, save
that JSON to a temporary file on your computer, and launch your configured text editor.

You may then perform whatever modifications to the JSON representation, save + leave your
text editor.

Afterwards, the modified JSON will be re-encoded to the binary format, and the result written
to the SIM card.

This allows for easy interactive modification of file contents.


USIM commands
-------------

authenticate
~~~~~~~~~~~~
.. argparse::
   :module: pySim.ts_31_102
   :func: ADF_USIM.AddlShellCommands.authenticate_parser



cmd2 settable parameters
------------------------

``cmd2`` has the concept of *settable parameters* which act a bit like environment variables in an OS-level
shell: They can be read and set, and they will influence the behavior somehow.

conserve_write
~~~~~~~~~~~~~~

If enabled, pySim will (when asked to write to a card) always first read the respective file/record and
verify if the to-be-written value differs from the current on-card value.  If not, the write will be skipped.
Writes will only be performed if the new value is different from the current on-card value.

If disabled, pySim will always write irrespective of the current/new value.

json_pretty_print
~~~~~~~~~~~~~~~~~

This parameter determines if generated JSON output should (by default) be pretty-printed (multi-line
output with indent level of 4 spaces) or not.

The default value of this parameter is 'true'.

debug
~~~~~

If enabled, full python back-traces will be displayed in case of exceptions

apdu_trace
~~~~~~~~~~

Boolean variable that determines if a hex-dump of the command + response APDU shall be printed.

numeric_path
~~~~~~~~~~~~

Boolean variable that determines if path (e.g. in prompt) is displayed with numeric FIDs or string names.

::

  pySIM-shell (MF/EF.ICCID)> set numeric_path True
  numeric_path - was: False
  now: True
  pySIM-shell (3f00/2fe2)> set numeric_path False
  numeric_path - was: True
  now: False
  pySIM-shell (MF/EF.ICCID)> help set