Harald Welte | 94e8735 | 2021-04-02 13:38:00 +0200 | [diff] [blame] | 1 | pySim-shell |
| 2 | =========== |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 3 | |
| 4 | pySim-shell is an interactive command line shell for all kind of interactions with SIM cards. |
| 5 | |
| 6 | The 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 | |
| 18 | By 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 | |
| 26 | |
| 27 | cmd2 basics |
| 28 | ----------- |
| 29 | |
| 30 | FIXME |
| 31 | |
| 32 | |
| 33 | |
| 34 | ISO7816 commands |
| 35 | ---------------- |
| 36 | |
| 37 | This category of commands relates to commands that originate in the ISO 7861-4 specifications, |
| 38 | most of them have a 1:1 resemblance in the specification. |
| 39 | |
| 40 | select |
| 41 | ~~~~~~ |
| 42 | |
| 43 | The ``select`` command is used to select a file, either by its FID, AID or by its symbolic name. |
| 44 | |
| 45 | Try ``select`` with tab-completion to get a list of all current selectable items: |
| 46 | |
| 47 | :: |
| 48 | |
| 49 | pySIM-shell (MF)> select |
| 50 | .. 2fe2 a0000000871004 EF.ARR MF |
| 51 | 2f00 3f00 ADF.ISIM EF.DIR |
| 52 | 2f05 7f10 ADF.USIM EF.ICCID |
| 53 | 2f06 7f20 DF.GSM EF.PL |
| 54 | 2f08 a0000000871002 DF.TELECOM EF.UMPC |
| 55 | |
| 56 | Use ``select`` with a specific FID or name to select the new file. |
| 57 | |
| 58 | This will |
| 59 | |
| 60 | * output the [JSON decoded, if possible] select response |
| 61 | * change the prompt to the newly selected file |
| 62 | * enable any commands specific to the newly-selected file |
| 63 | |
| 64 | :: |
| 65 | |
| 66 | pySIM-shell (MF)> select ADF.USIM |
| 67 | { |
| 68 | "file_descriptor": { |
| 69 | "shareable": true, |
| 70 | "file_type": "df", |
| 71 | "structure": "no_info_given" |
| 72 | }, |
| 73 | "df_name": "A0000000871002FFFFFFFF8907090000", |
| 74 | "proprietary_info": { |
| 75 | "uicc_characteristics": "71", |
| 76 | "available_memory": 101640 |
| 77 | }, |
| 78 | "life_cycle_status_int": "operational_activated", |
| 79 | "security_attrib_compact": "00", |
| 80 | "pin_status_template_do": "90017083010183018183010A83010B" |
| 81 | } |
| 82 | pySIM-shell (MF/ADF.USIM)> |
| 83 | |
| 84 | |
| 85 | |
| 86 | change_chv |
| 87 | ~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 88 | .. argparse:: |
| 89 | :module: pySim-shell |
| 90 | :func: Iso7816Commands.change_chv_parser |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 91 | |
| 92 | |
| 93 | disable_chv |
| 94 | ~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 95 | .. argparse:: |
| 96 | :module: pySim-shell |
| 97 | :func: Iso7816Commands.disable_chv_parser |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 98 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 99 | |
| 100 | enable_chv |
| 101 | ~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 102 | .. argparse:: |
| 103 | :module: pySim-shell |
| 104 | :func: Iso7816Commands.enable_chv_parser |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 105 | |
| 106 | |
| 107 | unblock_chv |
| 108 | ~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 109 | .. argparse:: |
| 110 | :module: pySim-shell |
| 111 | :func: Iso7816Commands.unblock_chv_parser |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 112 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 113 | |
| 114 | verify_chv |
| 115 | ~~~~~~~~~~ |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 116 | This command allows you to verify a CHV (PIN), which is how the specifications call |
| 117 | it if you authenticate yourself with the said CHV/PIN. |
| 118 | |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 119 | .. argparse:: |
| 120 | :module: pySim-shell |
| 121 | :func: Iso7816Commands.verify_chv_parser |
| 122 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 123 | |
| 124 | |
| 125 | pySim commands |
| 126 | -------------- |
| 127 | |
| 128 | Commands in this category are pySim specific; they do not have a 1:1 correspondence to ISO 7816 |
| 129 | or 3GPP commands. Mostly they will operate either only on local (in-memory) state, or execute |
| 130 | a complex sequence of card-commands. |
| 131 | |
| 132 | desc |
| 133 | ~~~~ |
| 134 | |
| 135 | Display human readable file description for the currently selected file. |
| 136 | |
| 137 | |
| 138 | dir |
| 139 | ~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 140 | .. argparse:: |
| 141 | :module: pySim-shell |
| 142 | :func: PySimCommands.dir_parser |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 143 | |
| 144 | |
| 145 | export |
| 146 | ~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 147 | .. argparse:: |
| 148 | :module: pySim-shell |
| 149 | :func: PySimCommands.export_parser |
| 150 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 151 | |
| 152 | tree |
| 153 | ~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 154 | FIXME |
| 155 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 156 | |
| 157 | verify_adm |
| 158 | ~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 159 | FIXME |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 160 | |
| 161 | |
| 162 | Linear Fixed EF commands |
| 163 | ------------------------ |
| 164 | |
| 165 | These commands become enabled only when your currently selected file is of *Linear Fixed EF* type. |
| 166 | |
| 167 | read_record |
| 168 | ~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 169 | .. argparse:: |
| 170 | :module: pySim.filesystem |
| 171 | :func: LinFixedEF.ShellCommands.read_rec_parser |
| 172 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 173 | |
| 174 | read_record_decoded |
| 175 | ~~~~~~~~~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 176 | .. argparse:: |
| 177 | :module: pySim.filesystem |
| 178 | :func: LinFixedEF.ShellCommands.read_rec_dec_parser |
| 179 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 180 | |
| 181 | update_record |
| 182 | ~~~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 183 | .. argparse:: |
| 184 | :module: pySim.filesystem |
| 185 | :func: LinFixedEF.ShellCommands.upd_rec_parser |
| 186 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 187 | |
| 188 | update_record_decoded |
| 189 | ~~~~~~~~~~~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 190 | .. argparse:: |
| 191 | :module: pySim.filesystem |
| 192 | :func: LinFixedEF.ShellCommands.upd_rec_dec_parser |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 193 | |
| 194 | |
| 195 | |
| 196 | Transparent EF commands |
| 197 | ----------------------- |
| 198 | |
| 199 | These commands become enabled only when your currently selected file is of *Transparent EF* type. |
| 200 | |
| 201 | |
| 202 | read_binary |
| 203 | ~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 204 | .. argparse:: |
| 205 | :module: pySim.filesystem |
| 206 | :func: TransparentEF.ShellCommands.read_bin_parser |
| 207 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 208 | |
| 209 | read_binary_decoded |
| 210 | ~~~~~~~~~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 211 | .. argparse:: |
| 212 | :module: pySim.filesystem |
| 213 | :func: TransparentEF.ShellCommands.read_bin_dec_parser |
| 214 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 215 | |
| 216 | update_binary |
| 217 | ~~~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 218 | .. argparse:: |
| 219 | :module: pySim.filesystem |
| 220 | :func: TransparentEF.ShellCommands.upd_bin_parser |
| 221 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 222 | |
| 223 | update_binary_decoded |
| 224 | ~~~~~~~~~~~~~~~~~~~~~ |
Harald Welte | d36f694 | 2021-04-04 14:37:55 +0200 | [diff] [blame^] | 225 | .. argparse:: |
| 226 | :module: pySim.filesystem |
| 227 | :func: TransparentEF.ShellCommands.upd_bin_dec_parser |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 228 | |
| 229 | |
| 230 | |
| 231 | cmd2 settable parameters |
| 232 | ------------------------ |
| 233 | |
| 234 | ``cmd2`` has the concept of *settable parameters* which act a bit like environment variables in an OS-level |
| 235 | shell: They can be read and set, and they will influence the behavior somehow. |
| 236 | |
| 237 | conserve_write |
| 238 | ~~~~~~~~~~~~~~ |
| 239 | |
| 240 | If enabled, pySim will (when asked to write to a card) always first read the respective file/record and |
| 241 | verify if the to-be-written value differs from the current on-card value. If not, the write will be skipped. |
| 242 | Writes will only be performed if the new value is different from the current on-card value. |
| 243 | |
| 244 | If disabled, pySim will always write irrespective of the current/new value. |
| 245 | |
Harald Welte | 1748b93 | 2021-04-06 21:12:25 +0200 | [diff] [blame] | 246 | json_pretty_print |
| 247 | ~~~~~~~~~~~~~~~~~ |
| 248 | |
| 249 | This parameter determines if generated JSON output should (by default) be pretty-printed (multi-line |
| 250 | output with indent level of 4 spaces) or not. |
| 251 | |
| 252 | The default value of this parameter is 'true'. |
| 253 | |
Harald Welte | be9516f | 2021-04-03 11:30:10 +0200 | [diff] [blame] | 254 | debug |
| 255 | ~~~~~ |
| 256 | |
| 257 | If enabled, full python back-traces will be displayed in case of exceptions |
| 258 | |
| 259 | numeric_path |
| 260 | ~~~~~~~~~~~~ |
| 261 | |
| 262 | Boolean variable that determines if path (e.g. in prompt) is displayed with numeric FIDs or string names. |
| 263 | |
| 264 | :: |
| 265 | |
| 266 | pySIM-shell (MF/EF.ICCID)> set numeric_path True |
| 267 | numeric_path - was: False |
| 268 | now: True |
| 269 | pySIM-shell (3f00/2fe2)> set numeric_path False |
| 270 | numeric_path - was: True |
| 271 | now: False |
| 272 | pySIM-shell (MF/EF.ICCID)> help set |