aboutsummaryrefslogtreecommitdiffstats
path: root/docs/shell.rst
blob: fcc171bddd463cc680fc9eda5b986b236a666af9 (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
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
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

Running pySim-shell
-------------------

pySim-shell has a variety of command line arguments to control

* which transport to use (how to use a reader to talk to the SIM card)
* whether to automatically verify an ADM pin (and in which format)
* whether to execute a start-up script

.. argparse::
   :module: pySim-shell
   :func: option_parser



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": {
          "file_descriptor_byte": {
              "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 specified file.  This used to be called REHABILITATE in TS 11.11.
You need to specify the name or FID of the file to activate.

.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.activate_file_parser

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

close_channel
~~~~~~~~~~~~~
.. argparse::
   :module: pySim-shell
   :func: Iso7816Commands.close_chan_parser


suspend_uicc
~~~~~~~~~~~~
This command allows you to perform the SUSPEND UICC command on the card.  This is a relatively
recent power-saving addition to the UICC specifications, allowing for suspend/resume while maintaining
state, as opposed to a full power-off (deactivate) and power-on (activate) of the card.

The pySim command just sends that SUSPEND UICC command and doesn't perform the full related sequence
including the electrical power down.

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


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.


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

Run a script for bulk-provisioning of multiple cards.


echo
~~~~
.. argparse::
   :module: pySim-shell
   :func: PysimApp.echo_parser



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.



BER-TLV EF commands
-------------------

BER-TLV EFs are files that contain BER-TLV structured data.  Every file can contain any number
of variable-length IEs (DOs).  The tag within a BER-TLV EF must be unique within the file.

The commands below become enabled only when your currently selected file is of *BER-TLV EF* type.

retrieve_tags
~~~~~~~~~~~~~

Retrieve a list of all tags present in the currently selected file.


retrieve_data
~~~~~~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: BerTlvEF.ShellCommands.retrieve_data_parser


set_data
~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: BerTlvEF.ShellCommands.set_data_parser


del_data
~~~~~~~~
.. argparse::
   :module: pySim.filesystem
   :func: BerTlvEF.ShellCommands.del_data_parser



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

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


ARA-M commands
--------------

The ARA-M commands exist to manage the access rules stored in an ARA-M applet on the card.

ARA-M in the context of SIM cards is primarily used to enable Android UICC Carrier Privileges,
please see https://source.android.com/devices/tech/config/uicc for more details on the background.


aram_get_all
~~~~~~~~~~~~

Obtain and decode all access rules from the ARA-M applet on the card.

NOTE: if the total size of the access rules exceeds 255 bytes, this command will fail, as
it doesn't yet implement fragmentation/reassembly on rule retrieval. YMMV

::

  pySIM-shell (MF/ADF.ARA-M)> aram_get_all
  [
      {
          "ResponseAllRefArDO": [
              {
                  "RefArDO": [
                      {
                          "RefDO": [
                              {
                                  "AidRefDO": "ffffffffffff"
                              },
                              {
                                  "DevAppIdRefDO": "e46872f28b350b7e1f140de535c2a8d5804f0be3"
                              }
                          ]
                      },
                      {
                          "ArDO": [
                              {
                                  "ApduArDO": {
                                      "generic_access_rule": "always"
                                  }
                              },
                              {
                                  "PermArDO": {
                                      "permissions": "0000000000000001"
                                  }
                              }
                          ]
                      }
                  ]
              }
          ]
      }
  ]

aram_get_config
~~~~~~~~~~~~~~~
Perform Config handshake with ARA-M applet: Tell it our version and retrieve its version.

NOTE: Not supported in all ARA-M implementations.

.. argparse::
   :module: pySim.ara_m
   :func: ADF_ARAM.AddlShellCommands.get_config_parser


aram_store_ref_ar_do
~~~~~~~~~~~~~~~~~~~~
Store a [new] access rule on the ARA-M applet.

.. argparse::
   :module: pySim.ara_m
   :func: ADF_ARAM.AddlShellCommands.store_ref_ar_do_parse

For example, to store an Android UICC carrier privilege rule for the SHA1 hash of the certificate used to sign the CoIMS android app of Supreeth Herle (https://github.com/herlesupreeth/CoIMS_Wiki) you can use the following command:

::

  pySIM-shell (MF/ADF.ARA-M)> aram_store_ref_ar_do --aid FFFFFFFFFFFF --device-app-id E46872F28B350B7E1F140DE535C2A8D5804F0BE3 --android-permissions 0000000000000001 --apdu-always


aram_delete_all
~~~~~~~~~~~~~~~
This command will request deletion of all access rules stored within the
ARA-M applet.  Use it with caution, there is no undo.  Any rules later
intended must be manually inserted again using `aram_store_ref_ar_do`



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