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 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
  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.

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!

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.

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.