The card model which we call GrcardSIM2 is one of the many smart card models
made and sold by Grcard in China.  Our FreeCalypso-branded version of this card
is called FCSIM1 (batch of 200 cards made in 2021-04), but the same card model
was previously sold by Sysmocom as sysmoSIM-GR2, going back to some time around
2013.

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 it always sends the
  default ADM11 key, i.e., pySim-prog -a or -A options have no effect on the key
  that actually matters.  Instead of supporting changeable ADM11 keys,
  pySim-prog needlessly resets ADM5, even though they could have left it alone
  (ADM11 by itself is sufficient for writing to all files), and the effect of
  -a or -A options is only on this unnecessary ADM5 setting.

* 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.  Now that our FCSIM1 cards are here, we plan on implementing
   the necessary front end tool soon - see FCSIM1-programming article.

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.