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": { "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