--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Low-level-commands	Sun Mar 14 07:57:09 2021 +0000
@@ -0,0 +1,196 @@
+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.