--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Admin-write-commands	Wed Mar 10 06:56:32 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.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/GrcardSIM2-programming	Wed Mar 10 06:56:32 2021 +0000
@@ -0,0 +1,82 @@
+The card model which we call GrcardSIM2 is one of the many smart card models
+made and sold by Grcard in China.  As of this writing (2021-03) and going back
+to somewhere around 2013, it is the card model they sell when a customer asks
+for a GSM-only SIM card, as opposed to USIM cards for UMTS/LTE/etc.  This card
+model was once resold by Sysmocom as sysmoSIM-GR2, and we are hoping to get a
+batch of our own FreeCalypso-branded version which we call FCSIM1.
+
+Our fc-simtool supports full programming of these cards: you can take a card
+whose initial state is "blank" or unprogrammed, or a card with some previous
+programming, and you can program it to your own liking using fc-simtool.  For
+the purpose of programming this particular card model (as opposed to USIM/ISIM
+cards), our fc-simtool offers the following advantages over well-known
+competitor pySim-prog:
+
+* These cards support all 3 versions of COMP128 algorithm (v1, v2 and v3), but
+  pySim-prog unconditionally selects COMP128v1.  Our grcard2-set-comp128 command
+  allows any of the 3 algorithm versions to be selected, and in the Mother's
+  opinion it makes no sense to select any version other than COMP128v3 for new
+  GSM network deployments.
+
+* These cards have a fairly sophisticated security model with two different ADM
+  access levels: see GrcardSIM2-security-model article for the details.
+  pySim-prog support for this security model is fundamentally broken: it
+  authenticates with ADM11 as required for writing Ki, but does not support any
+  option of changing this key to a secure one, as would be required in any
+  application where traditional SIM security is desired.  OTOH, pySim-prog
+  needlessly resets ADM5, even though they could have left it alone - ADM11 by
+  itself is sufficient for writing to all files.
+
+* Further on the security model, GrcardSIM2 cards allow admins to reset
+  PIN1/PIN2/PUK1/PUK2 secret codes after authenticating with ADM5 or ADM11 -
+  this mechanism is the only way to reset PUK1 and PUK2 if the previous codes
+  are unknown.  pySim-prog provides no support for setting PIN/PUK codes.
+
+* fc-simtool allows every single file in the card file system to be written as
+  you like.  Absolutely any file can be read and written in raw hex, and we also
+  provide high-level read and write commands for most files.  In contrast,
+  pySim-prog implements a rigid and inflexible programming model, writing only
+  a few files and only in one very limited way.
+
+Using fc-simtool to program GrcardSIM2 cards
+============================================
+
+To begin with, you must know the ADM11 (aka SUPER ADM) secret code for your
+card.  If you got your card directly from Grcard factory or from a reseller such
+as FreeCalypso who leaves this default ADM11 key unchanged, your ADM11 key is
+ASCII-decimal 88888888, and you need to authenticate as follows:
+
+verify-ext 11 88888888
+
+If the previous owner of your card changed this ADM11 key to something else, or
+if you had Grcard factory program cards for you with different ADM keys, then
+you need to know what the ADM11 secret is - if it is lost, there is no recovery,
+and you have to get a new card.  If you have a non-default ADM11 key, you need
+to enter it using either verify-ext 11 or verify-hex 11 command, depending on
+whether the key falls into the restricted ASCII-decimal subset or not.  In any
+case, this verify-ext 11 or verify-hex 11 command should ideally be the first
+command in your fc-simtool session; if it is not the first command in the
+session, then it needs to be preceded with select MF.
+
+Once you have authenticated with ADM11, you are ready to run your programming
+scripts.  Because fc-simtool is not a "one size fits all" tool like pySim-prog,
+but rather a fully generalized command shell that allows you to poke at whatever
+files you like in whatever order and manner you like, practical SIM programming
+should be done with customized command scripts.  Furthermore, we recommend that
+you split your custom programming scripts into two levels:
+
+1) You should have one command script which you install under
+   /opt/freecalypso/sim-scripts that programs SIMs appropriately for your GSM
+   network.  This script should be the same for all of your cards, programming
+   SST, PLMN selection (PLMNsel and FPLMN) and branding files SPN, PNN and OPL.
+   See our fcsim1-defprog script for a starting point.
+
+2) Per-card settings like ICCID, IMSI, ACC and Ki can only be set either
+   manually (OK for one or two cards, but doesn't scale), or by way of custom
+   front end or wrapper programs that generate and execute one-time fc-simtool
+   command scripts.  We plan on implementing one such front end tool once we
+   get our FCSIM1 card batch made.
+
+Please refer to Admin-write-commands, GrcardSIM2-WEKI-file and
+GrcardSIM2-security-model articles for commands to be used in crafting your
+custom programming scripts.