--- a/doc/FCSIM1-programming	Fri Apr 09 03:25:40 2021 +0000
+++ b/doc/FCSIM1-programming	Fri Apr 09 08:19:31 2021 +0000
@@ -30,7 +30,7 @@
 
 * We did pick a squatted range of ICCID numbers, and our cards have these ICCIDs
   printed on the plastic, both on the ID-1 carrier and on the little plug-in SIM
-  (2FF) piece.  The rationale is that we need to able to distinguish one card
+  (2FF) piece.  The rationale is that we need to be able to distinguish one card
   from another visually, and because the whole purpose of ICCID is to identify
   each card as a physical artifact irrespective of logical function, this ID
   number is perfect for the job.  It is never transmitted over any air
@@ -65,18 +65,149 @@
 it will typically need to be run with output append-redirected ('>>') to
 /opt/freecalypso/sim-data/fcsim1-prov-db.
 
-Once the desired provisioning data have been captured in fcsim1-prov-db, this
-database can be used in two ways:
+fcsim1-mkprov usage details
+===========================
+
+The canonical way to run fcsim1-mkprov is as follows:
+
+fcsim1-mkprov -n num start-iccid start-imsi >> /opt/freecalypso/sim-data/fcsim1-prov-db
+
+-n option specifies the number of card entries to generate; if this option is
+omitted, only one card entry will be generated.  The starting ICCID needs to be
+given in 18-digit form _without_ the Luhn check digit - fcsim1-mkprov will
+increment this ICCID for the number of card entries to be generated (we will
+always supply consecutively-numbered cards to anyone buying a small batch from
+us), and it will generate the correct Luhn check digit for each ICCID.  However,
+you can use our FC SIM tools shorthand notation for the starting ICCID: for
+example, if you enter 8901557-100, that entry will be automatically expanded to
+18-digit 890155700000000100.  IMSIs are expected to always be 15 digits long,
+but the same shorthand notation can be used here too.
+
+The following additional options are accepted:
+
+-a [0-9]
+
+	The argument for this option is a single digit from '0' to '9'; the
+	effect is to set ACC for the first card entry to be generated: -a 0
+	corresponds to ACC=0001, -a 1 corresponds to ACC=0002, and so forth
+	through -a 9 corresponding to ACC=0200.  When many card entries are
+	generated (-n option), subsequent card ACCs will automatically increment
+	and circle, i.e., bit-shift to the left until ACC=0200 is reached, then
+	circle back to ACC=0001 and so on.
+
+-m start-msisdn
+
+	By default (in the absence of -m option) each fcsim1-prov-db record
+	contains only ICCID, IMSI, ACC and Ki as shown above.  Running
+	fcsim1-mkprov with -m start-msisdn causes incrementing MSISDN numbers
+	to be generated as well, appearing as an extra MSISDN=xxx field in each
+	fcsim1-prov-db record.
+
+-r /dev/random
+
+	Read random bytes for Ki from /dev/random instead of /dev/urandom.
+
+Programming cards with fcsim1-program and fc-simtool
+====================================================
+
+Once the desired provisioning data have been captured in fcsim1-prov-db, the
+following procedure is envisioned for actual card programming:
+
+1) You pick the card to be programmed from the unprogrammed bin;
+
+2) While holding the card in your hand and looking at the ICCID printed on the
+   plastic, you enter a command line similar to this example:
+
+   fcsim1-program -c fcsim1-defprog 8901557-0008 | fc-simtool -p0
+
+   Type in the needed command line, but don't press Enter yet...
+
+3) Insert the card into your reader stand (assuming that you will be using a
+   stand-type card programming station such as HID Omnikey 3121), at which
+   point the ICCID printed on the card is no longer visible.
+
+4) Press Enter to execute the command you typed in step 2 above.
+
+Now the explanation: fcsim1-program is a utility that generates per-card
+programming command scripts to be fed to fc-simtool.  It requires the ICCID
+(read from the plastic with human eyeballs) to be entered on the command line,
+and this time the ICCID being entered needs to include the Luhn check digit:
+after all, you are simply entering the number from the plastic, and the printed
+ICCID does include the Luhn check digit.  Our FC SIM tools shorthand notation
+for skipping the long string of zeros in the middle still works though!
 
-1) There will be an fcsim1-program utility for programming individual FCSIM1
-   cards.  This program will be a wrapper around fc-simtool: it will take an
-   ICCID on the command line (you will need to read and enter the number printed
-   on the plastic), it will retrieve the right record from fcsim1-prov-db, it
-   will construct a one-time (under /tmp, automatically deleted when done)
-   command script for fc-simtool based on the per-card data, and it will exec
-   fc-simtool with this command script.
+After verifying the Luhn check digit, fcsim1-program will look up the entered
+ICCID in fcsim1-prov-db (if there is no entry for this ICCID, it is an error),
+and it will retrieve all per-card provisioning parameters from there.  The
+programming command script generated by fcsim1-program (intended to be piped
+directly into fc-simtool) has the following structure:
+
+verify-ext 11 88888888		# ADM11 authentication
+exec fcsim1-defprog		# common command script specified with -c
+write-iccid XXXX		# programming per-card ICCID
+write-imsi XXXX			# programming per-card IMSI
+write-acc XXXX			# programming per-card ACC
+grcard2-set-ki XXXX		# programming per-card Ki
+
+If the card record in fcsim1-prov-db includes the optional MSISDN= field
+(generated with fcsim1-mkprov -m option), the script generated by fcsim1-program
+will also include a pb-update-imm command to write the MSISDN record.
+
+Common command scripts: only ICCID, IMSI, ACC, Ki and optional MSISDN are
+expected to be different for each individual card, whereas all other SIM card
+programming is expected to be the same for all cards in a given fiefdom.
+Therefore, each tribal chieftain who is going to run his or her own GSM network
+will need to create their own custom common command script based on
+fcsim1-defprog: for example, for our own Themyscira Wireless operation we have
+our own private themwi-prog script that is based on fcsim1-defprog and takes
+its place.
+
+Philosophy regarding ICCID
+==========================
+
+Our workflow is set up so that whenever you program or reprogram a card, you
+have to read the ICCID from the plastic with your eyeballs and enter it on the
+command line.  Our fcsim1-program | fc-simtool pipeline programs the EF_ICCID
+record, but nowhere in our current workflow do we read it back for further
+database lookups.
 
-2) Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI
-   software up and running on a server, I will produce appropriate tools for
-   extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever
-   format is needed for import into OsmoHLR subscriber database.
+We have considered an alternative approach of programming EF_ICCID (to match
+the number printed on the plastic) on all of our FCSIM1 cards at FreeCalypso HQ,
+and then expecting downstream card users to run tools that read EF_ICCID from
+the card.  However, this approach has been rejected because unlike
+sysmoISIM-SJA2, GrcardSIM2 cards allow EF_ICCID to be freely rewritten like any
+other admin-write file, thus even if we program it correctly at FreeCalypso HQ,
+it is always possible for EF_ICCID to become messed up further downstream.  But
+the laser marking of ICCID on the plastic is truly immutable, hence the most
+reliable workflow for unconditionally bringing each card to the desired correct
+state irrespective of prior programming state is to read the ICCID from the
+plastic with human eyeballs, enter it on the command line, and have the tools
+unconditionally program it.
+
+Philosophy regarding ADM keys
+=============================
+
+The idea is similar to the one for ICCID: let's eliminate any dependencies on
+prior state of each card as much as possible.  Based on this philosophy, we
+currently leave the ADM11 key (SUPER ADM which supersedes ADM5 and all lower
+PINs) at the factory default of 88888888, and we discourage changing it.  If
+someone desires the traditional security model where an operator programs SIMs
+and then prevents subscribers from being able to read their Ki, then you will
+have to change your ADM11 key (and ADM5 too, for good measure) to true per-card
+secrets - but then you won't be able to freely rerun programming scripts without
+caring about prior state.
+
+For those who wish to change their ADM11 key, we provide low-level
+grcard2-set-super and grcard2-set-super-hex commands that do the deed, but our
+higher-level fcsim1-mkprov + fcsim1-program suite does not currently have any
+sensible support for secure ADM11 (or ADM5) keys.  If someone desires such
+functionality, we can implement it as paid feature development, but probably
+not otherwise.
+
+OsmoHLR integration
+===================
+
+Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI
+software up and running on a server, I will produce appropriate tools for
+extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever
+format is needed for import into OsmoHLR subscriber database.