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