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.