FreeCalypso > hg > fc-sim-tools
view doc/Low-level-commands @ 47:b0cf75d0bb2d
doc/Serial-SIM-readers article written
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 21 Mar 2021 04:32:18 +0000 |
parents | da6e9d0b2ee6 |
children | 871281cb0555 |
line wrap: on
line source
fc-simtool is a tool built from the bottom up: at the foundation there is a set of low-level commands that provide raw access to the actual SIM protocol APDU commands, these low-level commands can be used to do everything that the SIM protocol allows, and all higher-level commands merely provide user-friendly utilities for the most common particular use cases. This document describes these low-level commands. Readers of this document are expected to know the SIM interface protocol as defined in GSM TS 11.11 and its successor 3GPP TS 51.011. Exploring and reading commands ============================== atr This command displays the ATR (Answer To Reset) byte string which the SIM sent to the reader when it powered up. select File_ID This fc-simtool command sends a SELECT command to the SIM, follows up with a GET RESPONSE command as expected in the T=0 protocol, and provides some human- readable parsing of the most important fields in the SIM response structure. If a correctly formed response was received from the SIM and this response structure indicates that a record-based EF has been selected, the indicated record length is saved in an internal variable used by readrec and update-rec commands. The file ID can be specified either in hexadecimal (exactly 4 hex digits, *no* 0x prefix) or as a symbolic name. fc-simtool knows the following symbolic names: * MF * DF_GSM, DF_DCS1800 and DF_TELECOM * "gsm" and "telecom" as shorthand names for DF_GSM and DF_TELECOM * Some of the most classic EFs, but not all Important note: regardless of whether you specify the file ID in raw hex or symbolically, this low-level select command will send only one SELECT command to the SIM. Per the SIM protocol, in order to successfully select an EF, you have to be in the right directory first, i.e., select MF, DF_GSM or DF_TELECOM as appropriate before the EF of interest. Our low-level select command does NOT do this extra step on its own, you have to do it explicitly, even if you use symbolic names for EFs. sim-resp This command displays in raw hex the content of the internal buffer that holds the last response received from the SIM. This internal buffer is filled by the GET RESPONSE command that follows up after SELECT or RUN GSM ALGORITHM, and by the READ BINARY or READ RECORD commands, whether they are invoked directly as low-level commands (select, readbin, readrec or a38) or internally as part of higher-level fc-simtool commands. readbin offset len This fc-simtool command sends a READ BINARY command to the SIM and displays the SIM response in raw hex, internally invoking the same function as sim-resp. The two arguments are exactly as in the READ BINARY protocol command; each number is interpreted as decimal by default or as hex if preceded by 0x. readrec record-index [len] This fc-simtool command sends a READ RECORD command to the SIM (absolute addressing mode) and displays the SIM response in raw hex, internally invoking the same function as sim-resp. The arguments are decimal or hex as in the readbin command. If no explicit length argument is given, readrec uses the internal variable set by the last select operation. This one-argument form is almost always used in practice, as the SIM will normally reject any requested length that does not match the current EF record length. readef File_ID This fc-simtool command provides a slightly higher-level facility for examining the content of EFs, combining select and readbin or readrec operations. The sole File_ID argument is the same as for the low-level select command; the SIM response to SELECT is then parsed to decide what to do next. Transparent EFs are read using as many READ BINARY commands as necessary (up to 256 bytes can be read in one APDU exchange) and displayed as a continuous hex dump. For record-based EFs (linear fixed and cyclic), readef reads and separately hex-dumps every record. Just like with the low-level select command, there is no built-in MF/DF selection. savebin File_ID out-bin-file This command selects the specified EF (just like with low-level select and readef, you need to be in the right MF/DF directory) and saves its complete content in a raw binary file on the UNIX host file system. This command supports all 3 types of EF (transparent, linear fixed and cyclic) and uses the correct READ BINARY or READ RECORD commands based on the SELECT response. Record-based EFs are read in the order of increasing record number and are saved in the host binary file with all records simply abutted together. Writing commands ================ update-bin offset hexfile This fc-simtool command reads a hex data file (an ASCII text file containing only hex byte values and nothing else, with or without white space between bytes, newlines treated as any other white space) and sends this byte content to the SIM in an UPDATE BINARY command. The offset argument is the same as in the readbin command. The length is the number of bytes read from the hex data file. update-bin-imm offset hex-string This command works like update-bin, but the bytes to be written are given as a hex string direct argument (like an immediate operand in assembly languages), rather than via a hex data file. update-rec record-index hexfile This fc-simtool command reads a hex data file (just like update-bin) and sends this byte content to the SIM in an UPDATE RECORD command, using either absolute or PREVIOUS addressing mode. The record-index argument is the same as in the readrec command for the absolute addressing mode, or 'prev' keyword to use the PREVIOUS addressing mode for writing to cyclic EFs. The number of bytes in the hex data file must equal the EF record length. update-rec-imm record-index hex-string This command works like update-rec, but the bytes to be written are given as a hex string direct argument (like an immediate operand in assembly languages), rather than via a hex data file. update-rec-fill record-index fill-byte This fc-simtool command sends an UPDATE RECORD command to the SIM with payload equal to the specified fill byte, replicated to the record length. The fill byte argument is always interpreted as hexadecimal. restore-file File_ID host-bin-file This command restores a binary backup previously made with savebin back to the SIM, or writes new bits into the EF if you can construct the necessary binary image with tools like xxd. The arguments are the same as for the savebin command. This command supports all 3 types of EF (transparent, linear fixed and cyclic) and uses the correct UPDATE BINARY or UPDATE RECORD commands based on the SELECT response. Cyclic files are restored by writing every record in the reverse order from the last index to the first. erase-file File_ID [fill-byte] This command erases the specified EF by overwriting its content with the specified fill byte, which defaults to 0xFF if the second argument is omitted. All 3 EF types (transparent, linear fixed and cyclic) are supported: for transparent EFs fc-simtool issues as many UPDATE BINARY commands as needed to overwrite the whole file, whereas for record-based EFs every record is overwritten with UPDATE RECORD. INVALIDATE and REHABILITATE =========================== cur-ef-inval will send an INVALIDATE command to the SIM; cur-ef-rehab will send a REHABILITATE command. The naming of these low-level fc-simtool commands reflects the fact that you have to manually select the EF of interest first. GSM authentication testing ========================== a38 RAND This fc-simtool command exercises the SIM card's RUN GSM ALGORITHM command. The user-specified RAND value (a hex string of 16 bytes) is sent to the SIM, and the SIM response is parsed to display SRES and Kc. Per SIM specs GSM TS 11.11 and 3GPP TS 51.011, RUN GSM ALGORITHM can only be executed when DF_GSM is selected. fc-simtool a38 command does NOT include a built-in SELECT of DF_GSM, hence you need to manually issue 'select DF_GSM' first. This a38 command can be used to verify if the SIM card's Ki and A38 algorithm match what you expect them to be. To perform this test, issue an a38 command to the SIM with some made-up RAND and note the SRES and Kc response. Then use the osmo-auc-gen utility from Osmocom to run the expected algorithm with the expected Ki (and the expected OPc if MILENAGE is used) and the same RAND, and see if SRES and Kc match. Exploring proprietary APDUs =========================== If the SIM you are working with is known or suspected to implement some non-standard or proprietary APDUs for which there is no explicit support in fc-simtool, you can use this low-level debug command to send arbitrary APDUs: apdu "xx xx xx xx xx ..." The sole argument is a raw string of bytes (quotes are needed if there are spaces between bytes), and the APDU needs to be given exactly as it is sent in the T=0 protocol: 5 bytes of header (including the length byte) followed by data bytes, if any. After executing the APDU exchange, the apdu command simply prints the SW response code from the SIM.