Using fc-simtool for admin-level SIM card programming
=====================================================

fc-simtool is a layered tool, and its repertoire of available commands needs to
be viewed as consisting of 3 primary conceptual layers:

* At the bottom layer there are low-level commands that correspond directly to
  GSM 11.11 protocol operations of first SELECTing files, then reading or
  writing those files in whole or in part with READ BINARY, READ RECORD, UPDATE
  BINARY and UPDATE RECORD protocol commands.  This functional layer of
  fc-simtool is documented in the Low-level-commands article.

* As the next layer up, we implement higher-level commands for ordinary users
  without special admin privileges.  SIM card specs GSM 11.11 and 3GPP TS 51.011
  define many files such as phonebooks which ordinary users can both read and
  write, and we provide high-level user-friendly commands for reading and
  writing many of these files.  The same specs also define many files which
  ordinary users can read but not write, giving ICCID, IMSI, SST and so forth -
  we provide high-level user-friendly commands for reading many of these files.
  These commands are documented in the User-oriented-commands article, plus a
  few additional ones in the PLMN-list-commands article.

* As the most advanced layer, we implement some high-level write commands that
  can only work if you have admin-level access to your card, i.e., if you have
  authenticated with the appropriate ADM key in a card-vendor-dependent manner.
  The present article describes these advanced commands.

Authentication with ADM credentials
===================================

Before you can write to any of the admin-write-only files, you first need to
authenticate with the right credentials.  The commands for doing so are card-
vendor-dependent, but most cards implement a non-standard extension to the
standard VERIFY CHV command, presenting various kinds of ADM keys instead of
basic PIN1 or PIN2.  fc-simtool verify-ext and verify-hex commands provide
access to these extended forms of VERIFY CHV in our command shell environment;
they are defined as follows:

verify-ext P2 XXXXXXXX
verify-hex P2 xxxxxxxxxxxxxxxx

The first argument to both commands is the value to be put into the P2 field of
the VERIFY CHV command APDU; numbers are interpreted as decimal by default
unless preceded with 0x for hex.  verify-ext should be used if the key material
takes the same ASCII-decimal form as is used for standard PINs and PUKs, whereas
verify-hex allows arbitrary 64-bit keys to be given as a hex string of 8 bytes.

If your card is FCSIM1 or any other branded variant of GrcardSIM2 and the
default ADM11 (aka SUPER ADM) key hasn't been changed, you need to authenticate
as follows:

select MF
verify-ext 11 88888888

(select MF can be omitted if verify-ext 11 is the very first command in your
 fc-simtool session.)

If your card is sysmoISIM-SJA2, you need to look up the right ADM1 key in the
key material email from Sysmocom webshop, and then authenticate as follows:

verify-ext 10 XXXXXXXX

If your card is sysmoUSIM-SJS1, you need to use the following special command,
and it must be the very first command in your fc-simtool session:

verify-sjs1-adm1 XXXXXXXX

Actual admin file writes
========================

The few specific admin write commands implemented in fc-simtool are listed
below.  However, please keep the following points in mind:

* If there is no specific high-level write command for the file you are
  interested in, you can always use low-level select, update-bin and update-rec
  commands to write any file - see the Low-level-commands article.

* Some files that need to be written as part of provision-time programming
  procedures are actually writable by ordinary users, hence those write commands
  are documented in the User-oriented-commands article.  This situation applies
  to EF_MSISDN and EF_SMSP.  Commands for writing EF_PLMNsel and EF_FPLMN (also
  writable by ordinary users) are documented in the PLMN-list-commands article.

Finally, here are the dedicated commands for writing a few specific
admin-write-only files:

write-acc XXXX

This command writes EF_ACC.  The argument must be a 4-digit hexadecimal number.

write-iccid full_digits

This command programs EF_ICCID with whatever string of digits you specify.  This
fc-simtool command provides mechanism rather than policy, hence it does not
enforce any particular number of digits (the record is padded with 'F' hex
digits per the spec if the number string is shorter than 20 digits), nor is the
number required to end in a matching Luhn check digit.

write-iccid-sh18 shorthand-digits

This command provides a higher-level user-friendly way to write ICCIDs of the
most commonly used 18+1 format, meaning 18 content digits plus Luhn check digit.
The shorthand entry form allows any number of 0 digits in the middle to be
replaced with a single dash - for example, the following command:

write-iccid-sh18 8988211-3

will set ICCID to:

8988211000000000037

As the first step, the shorthand entry is expanded to 18 digits, and as the
next step, the correct Luhn check digit is appended.

write-iccid-sh19 shorthand-digits

This command is similar to write-iccid-sh18, but it takes shorthand ICCIDs that
already include the Luhn check digit at the end.  The previous example ICCID
would be entered as:

write-iccid-sh19 8988211-37

After the shorthand entry is expanded to 19 digits, the Luhn formula is checked,
and mismatching entries are rejected.  This command is intended for use cases
where the ICCID to be programmed is printed on the plastic and needs to be
entered as-is, but the pain of entering all those zeros in the middle is
eliminated.

write-imsi full_digits

This command programs EF_IMSI with any arbitrary IMSI, which by spec may be 15
digits or shorter.  15-digit IMSIs are most common, but shorter ones are allowed
too, and this fc-simtool command provides mechanism rather than policy.

write-imsi-sh shorthand-digits

This command programs EF_IMSI with a 15-digit IMSI that can be entered in
shorthand.  For example, the following command:

write-imsi-sh 90170-001

is equivalent to:

write-imsi 901700000000001

write-spn display_cond name

The display condition code is given in hex, the name field is given in the
FreeCalypso standard ASCII representation for GSM7 strings defined in the
SIM-data-formats document in the freecalypso-docs repository.

write-sst sst-file

This command writes the SIM Service Table (SST) from the specified data file.
The data file needs to contain service numbers separated by white space, either
one per line or multiple numbers per line; '#' character introduces comments
which continue to the end of the line.  If a service number is given with '^'
suffix, that service is indicated as allocated but not activated.

pnn-write rec long-name [short-name]

This command writes a single EF_PNN record.  The record index and the long name
must always be specified, the short name is optional.  Network name fields are
given in the FreeCalypso standard ASCII representation for GSM7 strings.

pnn-erase start-rec [end-rec]

This command erases (fills with all FF bytes) either a single record or a range
of records in EF_PNN.  If only one argument is specified, only one record is
erased.  To erase a range of records, the second argument may be either a number
or the "end" keyword.  Use 'pnn-erase 1 end' to erase the entire EF_PNN.

opl-write rec mcc-mnc start-lac end-lac pnn-index

This command writes a single EF_OPL record.  rec is the EF_OPL record index to
write into, the remaining arguments give the content of the record exactly per
3GPP TS 51.011.

opl-erase start-rec [end-rec]

This command erases (fills with all FF bytes) either a single record or a range
of records in EF_OPL.  If only one argument is specified, only one record is
erased.  To erase a range of records, the second argument may be either a number
or the "end" keyword.  Use 'opl-erase 1 end' to erase the entire EF_OPL.