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.

A different form of the raw APDU command is provided for use in custom command
scripts:

apdu-checksw "xx xx xx xx xx ..." YYZZ

This command takes two arguments at the argv level: the first is the same string
of bytes as in the basic apdu command (will need to be quoted if it contains
spaces between bytes), and the second argument is the expected SW response from
the SIM.  If the SW response from the SIM is exactly as expected, the execution
of the command is considered to be successful; if the SW response is different,
an error is reported and script execution is stopped.