blob: f24dc93b37564374c1957a53527ed57a6ab1d98a [file] [log] [blame]
Harald Welte94e87352021-04-02 13:38:00 +02001pySim-shell
2===========
Harald Weltebe9516f2021-04-03 11:30:10 +02003
4pySim-shell is an interactive command line shell for all kind of interactions with SIM cards.
5
6The interactive shell provides command for
7
8* navigating the on-card filesystem hierarchy
9* authenticating with PINs such as ADM1
10* CHV/PIN management (VERIFY, ENABLE, DISABLE, UNBLOCK)
11* decoding of SELECT response (file control parameters)
12* reading and writing of files and records in raw, hex-encoded binary format
13* for some files where related support has been developed:
14
15 * decoded reading (display file data in JSON format)
16 * decoded writing (encode from JSON to binary format, then write)
17
18By means of using the python ``cmd2`` module, various useful features improve usability:
19
20* history of commands (persistent across restarts)
21* output re-direction to files on your computer
22* output piping through external tools like 'grep'
23* tab completion of commands and SELECT-able files/directories
24* interactive help for all commands
25
Harald Weltef2e761c2021-04-11 11:56:44 +020026Running pySim-shell
27-------------------
28
29pySim-shell has a variety of command line arguments to control
30
31* which transport to use (how to use a reader to talk to the SIM card)
32* whether to automatically verify an ADM pin (and in which format)
33* whether to execute a start-up script
34
35.. argparse::
36 :module: pySim-shell
37 :func: option_parser
38
39
Harald Weltebe9516f2021-04-03 11:30:10 +020040
41cmd2 basics
42-----------
43
44FIXME
45
46
47
48ISO7816 commands
49----------------
50
51This category of commands relates to commands that originate in the ISO 7861-4 specifications,
52most of them have a 1:1 resemblance in the specification.
53
54select
55~~~~~~
56
57The ``select`` command is used to select a file, either by its FID, AID or by its symbolic name.
58
59Try ``select`` with tab-completion to get a list of all current selectable items:
60
61::
62
63 pySIM-shell (MF)> select
64 .. 2fe2 a0000000871004 EF.ARR MF
65 2f00 3f00 ADF.ISIM EF.DIR
66 2f05 7f10 ADF.USIM EF.ICCID
67 2f06 7f20 DF.GSM EF.PL
68 2f08 a0000000871002 DF.TELECOM EF.UMPC
69
70Use ``select`` with a specific FID or name to select the new file.
71
72This will
73
74* output the [JSON decoded, if possible] select response
75* change the prompt to the newly selected file
76* enable any commands specific to the newly-selected file
77
78::
79
80 pySIM-shell (MF)> select ADF.USIM
81 {
82 "file_descriptor": {
Harald Welte747a9782022-02-13 17:52:28 +010083 "file_descriptor_byte": {
84 "shareable": true,
85 "file_type": "df",
86 "structure": "no_info_given"
87 }
Harald Weltebe9516f2021-04-03 11:30:10 +020088 },
89 "df_name": "A0000000871002FFFFFFFF8907090000",
90 "proprietary_info": {
91 "uicc_characteristics": "71",
92 "available_memory": 101640
93 },
94 "life_cycle_status_int": "operational_activated",
95 "security_attrib_compact": "00",
96 "pin_status_template_do": "90017083010183018183010A83010B"
97 }
98 pySIM-shell (MF/ADF.USIM)>
99
100
Harald Welted01bd362022-02-15 15:56:48 +0100101status
102~~~~~~
103
104The ``status`` command [re-]obtains the File Control Template of the
105currently-selected file and print its decoded output.
106
107Example:
108
109::
110
111 pySIM-shell (MF/ADF.ISIM)> status
112 {
113 "file_descriptor": {
114 "file_descriptor_byte": {
115 "shareable": true,
116 "file_type": "df",
117 "structure": "no_info_given"
118 },
119 "record_len": null,
120 "num_of_rec": null
121 },
122 "file_identifier": "ff01",
123 "df_name": "a0000000871004ffffffff8907090000",
124 "proprietary_information": {
125 "uicc_characteristics": "71",
126 "available_memory": 101640
127 },
128 "life_cycle_status_integer": "operational_activated",
129 "security_attrib_compact": "00",
130 "pin_status_template_do": {
131 "ps_do": "70",
132 "key_reference": 11
133 }
134 }
135
Harald Weltebe9516f2021-04-03 11:30:10 +0200136
137change_chv
138~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200139.. argparse::
140 :module: pySim-shell
141 :func: Iso7816Commands.change_chv_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200142
143
144disable_chv
145~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200146.. argparse::
147 :module: pySim-shell
148 :func: Iso7816Commands.disable_chv_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200149
Harald Weltebe9516f2021-04-03 11:30:10 +0200150
151enable_chv
152~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200153.. argparse::
154 :module: pySim-shell
155 :func: Iso7816Commands.enable_chv_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200156
157
158unblock_chv
159~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200160.. argparse::
161 :module: pySim-shell
162 :func: Iso7816Commands.unblock_chv_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200163
Harald Weltebe9516f2021-04-03 11:30:10 +0200164
165verify_chv
166~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200167.. argparse::
168 :module: pySim-shell
169 :func: Iso7816Commands.verify_chv_parser
170
Harald Weltea4631612021-04-10 18:17:55 +0200171deactivate_file
172~~~~~~~~~~~~~~~
173Deactivate the currently selected file. This used to be called INVALIDATE in TS 11.11.
174
175
176activate_file
177~~~~~~~~~~~~~
Harald Welte799c3542022-02-15 15:56:28 +0100178.. argparse::
179 :module: pySim-shell
180 :func: Iso7816Commands.activate_file_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200181
Harald Welte703f9332021-04-10 18:39:32 +0200182open_channel
183~~~~~~~~~~~~
184.. argparse::
185 :module: pySim-shell
186 :func: Iso7816Commands.open_chan_parser
187
188close_channel
189~~~~~~~~~~~~~
190.. argparse::
191 :module: pySim-shell
192 :func: Iso7816Commands.close_chan_parser
193
Harald Weltebe9516f2021-04-03 11:30:10 +0200194
Harald Welteec950532021-10-20 13:09:00 +0200195suspend_uicc
196~~~~~~~~~~~~
197This command allows you to perform the SUSPEND UICC command on the card. This is a relatively
198recent power-saving addition to the UICC specifications, allowing for suspend/resume while maintaining
199state, as opposed to a full power-off (deactivate) and power-on (activate) of the card.
200
201The pySim command just sends that SUSPEND UICC command and doesn't perform the full related sequence
202including the electrical power down.
203
204.. argparse::
205 :module: pySim-shell
206 :func: Iso7816Commands.suspend_uicc_parser
207
208
Harald Welte12af7932022-02-15 16:39:08 +0100209
Harald Weltebe9516f2021-04-03 11:30:10 +0200210pySim commands
211--------------
212
213Commands in this category are pySim specific; they do not have a 1:1 correspondence to ISO 7816
214or 3GPP commands. Mostly they will operate either only on local (in-memory) state, or execute
215a complex sequence of card-commands.
216
217desc
218~~~~
Harald Weltebe9516f2021-04-03 11:30:10 +0200219Display human readable file description for the currently selected file.
220
221
222dir
223~~~
Harald Welted36f6942021-04-04 14:37:55 +0200224.. argparse::
225 :module: pySim-shell
226 :func: PySimCommands.dir_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200227
Harald Welte12af7932022-02-15 16:39:08 +0100228Example:
229::
230
231 pySIM-shell (MF)> dir
232 MF
233 3f00
234 .. ADF.USIM DF.SYSTEM EF.DIR EF.UMPC
235 ADF.ARA-M DF.EIRENE DF.TELECOM EF.ICCID MF
236 ADF.ISIM DF.GSM EF.ARR EF.PL
237 14 files
238
Harald Weltebe9516f2021-04-03 11:30:10 +0200239
240export
241~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200242.. argparse::
243 :module: pySim-shell
244 :func: PySimCommands.export_parser
245
Harald Weltebd02f842021-10-21 14:40:39 +0200246Please note that `export` works relative to the current working
247directory, so if you are in `MF`, then the export will contain all known
248files on the card. However, if you are in `ADF.ISIM`, only files below
249that ADF will be part of the export.
250
251Furthermore, it is strongly advised to first enter the ADM1 pin
252(`verify_adm`) to maximize the chance of having permission to read
253all/most files.
254
Harald Weltebe9516f2021-04-03 11:30:10 +0200255
256tree
257~~~~
Harald Welte7743c202021-05-03 23:30:11 +0200258Display a tree of the card filesystem. It is important to note that this displays a tree
259of files that might potentially exist (based on the card profile). In order to determine if
260a given file really exists on a given card, you have to try to select that file.
Harald Welted36f6942021-04-04 14:37:55 +0200261
Harald Welte12af7932022-02-15 16:39:08 +0100262Example:
263::
264
265 pySIM-shell (MF)> tree --help
266 EF.DIR 2f00 Application Directory
267 EF.ICCID 2fe2 ICC Identification
268 EF.PL 2f05 Preferred Languages
269 EF.ARR 2f06 Access Rule Reference
270 EF.UMPC 2f08 UICC Maximum Power Consumption
271 DF.TELECOM 7f10 None
272 EF.ADN 6f3a Abbreviated Dialing Numbers
273 ...
274
275
Harald Weltebe9516f2021-04-03 11:30:10 +0200276
277verify_adm
278~~~~~~~~~~
Harald Welte7743c202021-05-03 23:30:11 +0200279Verify the ADM (Administrator) PIN specified as argument. This is typically needed in order
280to get write/update permissions to most of the files on SIM cards.
281
282Currently only ADM1 is supported.
Harald Weltebe9516f2021-04-03 11:30:10 +0200283
284
Harald Weltedaf2b392021-05-03 23:17:29 +0200285reset
286~~~~~
Harald Weltedaf2b392021-05-03 23:17:29 +0200287Perform card reset and display the card ATR.
288
Harald Weltebd02f842021-10-21 14:40:39 +0200289intro
290~~~~~
291[Re-]Display the introductory banner
292
293
294equip
295~~~~~
296Equip pySim-shell with a card; particularly useful if the program was
297started before a card was present, or after a card has been replaced by
298the user while pySim-shell was kept running.
299
300bulk_script
301~~~~~~~~~~~
302.. argparse::
303 :module: pySim-shell
304 :func: PysimApp.bulk_script_parser
305
Harald Weltebd02f842021-10-21 14:40:39 +0200306
307echo
308~~~~
309.. argparse::
310 :module: pySim-shell
311 :func: PysimApp.echo_parser
312
313
Harald Welte12af7932022-02-15 16:39:08 +0100314apdu
315~~~~
316.. argparse::
317 :module: pySim-shell
318 :func: PySimCommands.apdu_cmd_parser
319
320
Harald Weltedaf2b392021-05-03 23:17:29 +0200321
Harald Weltebe9516f2021-04-03 11:30:10 +0200322Linear Fixed EF commands
323------------------------
324
325These commands become enabled only when your currently selected file is of *Linear Fixed EF* type.
326
327read_record
328~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200329.. argparse::
330 :module: pySim.filesystem
331 :func: LinFixedEF.ShellCommands.read_rec_parser
332
Harald Weltebe9516f2021-04-03 11:30:10 +0200333
334read_record_decoded
335~~~~~~~~~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200336.. argparse::
337 :module: pySim.filesystem
338 :func: LinFixedEF.ShellCommands.read_rec_dec_parser
339
Harald Weltebe9516f2021-04-03 11:30:10 +0200340
Harald Welte850b72a2021-04-07 09:33:03 +0200341read_records
342~~~~~~~~~~~~
343.. argparse::
344 :module: pySim.filesystem
345 :func: LinFixedEF.ShellCommands.read_recs_parser
346
347
348read_records_decoded
349~~~~~~~~~~~~~~~~~~~~
350.. argparse::
351 :module: pySim.filesystem
352 :func: LinFixedEF.ShellCommands.read_recs_dec_parser
353
354
Harald Weltebe9516f2021-04-03 11:30:10 +0200355update_record
356~~~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200357.. argparse::
358 :module: pySim.filesystem
359 :func: LinFixedEF.ShellCommands.upd_rec_parser
360
Harald Weltebe9516f2021-04-03 11:30:10 +0200361
362update_record_decoded
363~~~~~~~~~~~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200364.. argparse::
365 :module: pySim.filesystem
366 :func: LinFixedEF.ShellCommands.upd_rec_dec_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200367
368
Harald Welte4145d3c2021-04-08 20:34:13 +0200369edit_record_decoded
370~~~~~~~~~~~~~~~~~~~
371.. argparse::
372 :module: pySim.filesystem
373 :func: LinFixedEF.ShellCommands.edit_rec_dec_parser
374
375This command will read the selected record, decode it to its JSON representation, save
376that JSON to a temporary file on your computer, and launch your configured text editor.
377
378You may then perform whatever modifications to the JSON representation, save + leave your
379text editor.
380
381Afterwards, the modified JSON will be re-encoded to the binary format, and the result written
382back to the record on the SIM card.
383
384This allows for easy interactive modification of records.
385
386
Harald Weltebe9516f2021-04-03 11:30:10 +0200387
388Transparent EF commands
389-----------------------
390
391These commands become enabled only when your currently selected file is of *Transparent EF* type.
392
393
394read_binary
395~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200396.. argparse::
397 :module: pySim.filesystem
398 :func: TransparentEF.ShellCommands.read_bin_parser
399
Harald Weltebe9516f2021-04-03 11:30:10 +0200400
401read_binary_decoded
402~~~~~~~~~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200403.. argparse::
404 :module: pySim.filesystem
405 :func: TransparentEF.ShellCommands.read_bin_dec_parser
406
Harald Weltebe9516f2021-04-03 11:30:10 +0200407
408update_binary
409~~~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200410.. argparse::
411 :module: pySim.filesystem
412 :func: TransparentEF.ShellCommands.upd_bin_parser
413
Harald Weltebe9516f2021-04-03 11:30:10 +0200414
415update_binary_decoded
416~~~~~~~~~~~~~~~~~~~~~
Harald Welted36f6942021-04-04 14:37:55 +0200417.. argparse::
418 :module: pySim.filesystem
419 :func: TransparentEF.ShellCommands.upd_bin_dec_parser
Harald Weltebe9516f2021-04-03 11:30:10 +0200420
Harald Welte0d4e98a2021-04-07 00:14:40 +0200421In normal operation, update_binary_decoded needs a JSON document representing the entire file contents as
422input. This can be inconvenient if you want to keep 99% of the content but just toggle one specific
423parameter. That's where the JSONpath support comes in handy: You can specify a JSONpath to an element
424inside the document as well as a new value for tat field:
425
426Th below example demonstrates this by modifying the ofm field within EF.AD:
427
428::
429
430 pySIM-shell (MF/ADF.USIM/EF.AD)> read_binary_decoded
431 {
432 "ms_operation_mode": "normal",
433 "specific_facilities": {
434 "ofm": true
435 },
436 "len_of_mnc_in_imsi": 2
437 }
438 pySIM-shell (MF/ADF.USIM/EF.AD)> update_binary_decoded --json-path specific_facilities.ofm false
439 pySIM-shell (MF/ADF.USIM/EF.AD)> read_binary_decoded
440 {
441 "ms_operation_mode": "normal",
442 "specific_facilities": {
443 "ofm": false
444 },
445 "len_of_mnc_in_imsi": 2
446 }
447
Harald Weltebe9516f2021-04-03 11:30:10 +0200448
Harald Welte4145d3c2021-04-08 20:34:13 +0200449edit_binary_decoded
450~~~~~~~~~~~~~~~~~~~
451This command will read the selected binary EF, decode it to its JSON representation, save
452that JSON to a temporary file on your computer, and launch your configured text editor.
453
454You may then perform whatever modifications to the JSON representation, save + leave your
455text editor.
456
457Afterwards, the modified JSON will be re-encoded to the binary format, and the result written
458to the SIM card.
459
460This allows for easy interactive modification of file contents.
461
Harald Weltebe9516f2021-04-03 11:30:10 +0200462
Harald Welte917d98c2021-04-21 11:51:25 +0200463
464BER-TLV EF commands
465-------------------
466
467BER-TLV EFs are files that contain BER-TLV structured data. Every file can contain any number
468of variable-length IEs (DOs). The tag within a BER-TLV EF must be unique within the file.
469
470The commands below become enabled only when your currently selected file is of *BER-TLV EF* type.
471
472retrieve_tags
473~~~~~~~~~~~~~
474
475Retrieve a list of all tags present in the currently selected file.
476
477
478retrieve_data
479~~~~~~~~~~~~~
480.. argparse::
481 :module: pySim.filesystem
482 :func: BerTlvEF.ShellCommands.retrieve_data_parser
483
484
485set_data
486~~~~~~~~
487.. argparse::
488 :module: pySim.filesystem
489 :func: BerTlvEF.ShellCommands.set_data_parser
490
491
492del_data
493~~~~~~~~
494.. argparse::
495 :module: pySim.filesystem
496 :func: BerTlvEF.ShellCommands.del_data_parser
497
498
499
Harald Welte15fae982021-04-10 10:22:27 +0200500USIM commands
501-------------
502
503authenticate
504~~~~~~~~~~~~
505.. argparse::
506 :module: pySim.ts_31_102
507 :func: ADF_USIM.AddlShellCommands.authenticate_parser
508
Harald Welte12af7932022-02-15 16:39:08 +0100509terminal_profile
510~~~~~~~~~~~~~~~~
511.. argparse::
512 :module: pySim.ts_31_102
513 :func: ADF_USIM.AddlShellCommands.term_prof_parser
514
515envelope
516~~~~~~~~
517.. argparse::
518 :module: pySim.ts_31_102
519 :func: ADF_USIM.AddlShellCommands.envelope_parser
520
521envelope_sms
522~~~~~~~~~~~~
523.. argparse::
524 :module: pySim.ts_31_102
525 :func: ADF_USIM.AddlShellCommands.envelope_sms_parser
526
527
528
Harald Welte15fae982021-04-10 10:22:27 +0200529
Harald Welte95ce6b12021-10-20 18:40:54 +0200530ARA-M commands
531--------------
532
533The ARA-M commands exist to manage the access rules stored in an ARA-M applet on the card.
534
535ARA-M in the context of SIM cards is primarily used to enable Android UICC Carrier Privileges,
536please see https://source.android.com/devices/tech/config/uicc for more details on the background.
537
538
539aram_get_all
540~~~~~~~~~~~~
541
542Obtain and decode all access rules from the ARA-M applet on the card.
543
544NOTE: if the total size of the access rules exceeds 255 bytes, this command will fail, as
545it doesn't yet implement fragmentation/reassembly on rule retrieval. YMMV
546
547::
548
549 pySIM-shell (MF/ADF.ARA-M)> aram_get_all
550 [
551 {
552 "ResponseAllRefArDO": [
553 {
554 "RefArDO": [
555 {
556 "RefDO": [
557 {
558 "AidRefDO": "ffffffffffff"
559 },
560 {
561 "DevAppIdRefDO": "e46872f28b350b7e1f140de535c2a8d5804f0be3"
562 }
563 ]
564 },
565 {
566 "ArDO": [
567 {
568 "ApduArDO": {
569 "generic_access_rule": "always"
570 }
571 },
572 {
573 "PermArDO": {
574 "permissions": "0000000000000001"
575 }
576 }
577 ]
578 }
579 ]
580 }
581 ]
582 }
583 ]
584
585aram_get_config
586~~~~~~~~~~~~~~~
587Perform Config handshake with ARA-M applet: Tell it our version and retrieve its version.
588
589NOTE: Not supported in all ARA-M implementations.
590
Harald Welte95ce6b12021-10-20 18:40:54 +0200591
592aram_store_ref_ar_do
593~~~~~~~~~~~~~~~~~~~~
Harald Welte95ce6b12021-10-20 18:40:54 +0200594.. argparse::
595 :module: pySim.ara_m
596 :func: ADF_ARAM.AddlShellCommands.store_ref_ar_do_parse
597
598For 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:
Harald Welte95ce6b12021-10-20 18:40:54 +0200599::
600
601 pySIM-shell (MF/ADF.ARA-M)> aram_store_ref_ar_do --aid FFFFFFFFFFFF --device-app-id E46872F28B350B7E1F140DE535C2A8D5804F0BE3 --android-permissions 0000000000000001 --apdu-always
602
603
604aram_delete_all
605~~~~~~~~~~~~~~~
606This command will request deletion of all access rules stored within the
607ARA-M applet. Use it with caution, there is no undo. Any rules later
608intended must be manually inserted again using `aram_store_ref_ar_do`
609
610
Harald Welte15fae982021-04-10 10:22:27 +0200611
Harald Weltebe9516f2021-04-03 11:30:10 +0200612cmd2 settable parameters
613------------------------
614
615``cmd2`` has the concept of *settable parameters* which act a bit like environment variables in an OS-level
616shell: They can be read and set, and they will influence the behavior somehow.
617
618conserve_write
619~~~~~~~~~~~~~~
620
621If enabled, pySim will (when asked to write to a card) always first read the respective file/record and
622verify if the to-be-written value differs from the current on-card value. If not, the write will be skipped.
623Writes will only be performed if the new value is different from the current on-card value.
624
625If disabled, pySim will always write irrespective of the current/new value.
626
Harald Welte1748b932021-04-06 21:12:25 +0200627json_pretty_print
628~~~~~~~~~~~~~~~~~
629
630This parameter determines if generated JSON output should (by default) be pretty-printed (multi-line
631output with indent level of 4 spaces) or not.
632
633The default value of this parameter is 'true'.
634
Harald Weltebe9516f2021-04-03 11:30:10 +0200635debug
636~~~~~
637
638If enabled, full python back-traces will be displayed in case of exceptions
639
Harald Welte7829d8a2021-04-10 11:28:53 +0200640apdu_trace
641~~~~~~~~~~
642
643Boolean variable that determines if a hex-dump of the command + response APDU shall be printed.
644
Harald Weltebe9516f2021-04-03 11:30:10 +0200645numeric_path
646~~~~~~~~~~~~
647
648Boolean variable that determines if path (e.g. in prompt) is displayed with numeric FIDs or string names.
649
650::
651
652 pySIM-shell (MF/EF.ICCID)> set numeric_path True
653 numeric_path - was: False
654 now: True
655 pySIM-shell (3f00/2fe2)> set numeric_path False
656 numeric_path - was: True
657 now: False
658 pySIM-shell (MF/EF.ICCID)> help set