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
update-bin-imm
update-rec

restore-file

GSM authentication testing
==========================

a38