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.