--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FCSIM1-programming	Wed Mar 17 06:44:12 2021 +0000
@@ -0,0 +1,82 @@
+FreeCalypso Community SIM card model FCSIM1 is our FC-branded version of
+GrcardSIM2.  We (FreeCalypso) are making these cards for the primary purpose of
+bringing back to current availability an exact equivalent of the discontinued
+sysmoSIM-GR2 card, but our approach to card provisioning and programming differs
+from Sysmocom's:
+
+* Just like their current USIM/ISIM product, Sysmocom's previous Grcard-based
+  SIMs were preprogrammed at the factory with default IMSIs from a 901-xx range,
+  allowing them to be used as-is (without programming by the user) if the user
+  configures his or her GSM network to use the same MCC-MNC as preprogrammed on
+  the cards.
+
+  Our approach is different: different members of our community will be running
+  their own GSM networks with varying degrees of legality or illegality, and
+  every individual operator of a pirate GSM BTS will have to carefully select
+  his or her squatted MCC-MNC based on his or her unique geopolitical
+  circumstances.  In this climate it makes no sense to attempt any kind of
+  generic default MCC-MNC for SIM card preprogramming, hence we get our FCSIM1
+  cards from Grcard without any factory programming ("blank"), and if anyone
+  wishes to get some cards from us, we will supply them in the same "blank"
+  state.  All programming needs to be done by individual downstream card owners,
+  and fc-simtool plus accompanying utilities are the official tools for this
+  programming.
+
+* All Sysmocom cards, both historical Grcard-based SIM products and their
+  current USIM/ISIM, have their PIN1, PUK1 and IMSI printed on the plastic.  We
+  do not print these numbers because we don't assign any in the first place -
+  instead all PINs and IMSIs are freely assigned and programmed by downstream
+  owners of each individual card.
+
+* 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
+  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
+  interfaces, hence no one outside of our community needs to know or care that
+  we use squatted ICCIDs rather than officially allocated ones.
+
+Programming model for FCSIM1
+============================
+
+Our programming model is based on the principle of a card provisioning database.
+If you are going to get a small batch of FCSIM1 cards from us, or if you are
+going to order a larger batch directly from Grcard, but you wish to follow the
+same model as ours, as the first step toward programming, you will need to
+generate your own card provisioning database.  This database is an ASCII text
+file with one line per card, and it resides in this standardized location:
+
+/opt/freecalypso/sim-data/fcsim1-prov-db
+
+Each line in this card provisioning database takes the following form:
+
+ICCID=89015570000000xxxxx IMSI=xxxxxxxxxxxxxxx ACC=xxxx Ki=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+While there is nothing to stop you from constructing this card provisioning
+database manually in vi, the intent is that it will be generated by our
+fcsim1-mkprov utility.  This utility takes a starting ICCID, a starting IMSI
+and the number of card entries to generate - and it generates the requested
+number of database entries with incrementing ICCIDs, incrementing IMSIs, ACC
+circling through the standard bit-shifting range from 0001 to 0200, and random
+Ki secret keys.  (The source of random keys is currently very simple: each Ki
+is read directly from /dev/urandom, or from /dev/random if desired.  Suggestions
+for improvement are welcome.)  fcsim1-mkprov emits its output to stdout, hence
+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:
+
+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.
+
+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.