FreeCalypso > hg > fc-pcsc-tools
view doc/Low-level-commands @ 99:d2e800abd257
fc-simtool plmnsel-write command implemented
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Wed, 17 Feb 2021 22:43:18 +0000 |
parents | 3bce899bcf78 |
children | 08ba6a5d8a3f |
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 transparent EFs, combining select and readbin operations. The sole File_ID argument is the same as for the low-level select command; if the SIM response to this SELECT indicates a transparent EF (it is an error otherwise), readef follows up with a READ BINARY command to read the entire file (or the first 256 bytes if the file is longer) and displays the read content in raw hex. 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 absolute addressing mode. The record-index argument is the same as in the readrec command. The number of bytes in the hex data file must equal the EF record length. update-rec-prev hexfile This fc-simtool command is like update-rec, but the UPDATE RECORD command sent to the SIM uses the PREVIOUS addressing mode, and there is no record number. This form is needed in order to write to cyclic EFs. 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. 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.