--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/GrcardSIM2-programming	Wed Mar 10 06:56:32 2021 +0000
@@ -0,0 +1,82 @@
+The card model which we call GrcardSIM2 is one of the many smart card models
+made and sold by Grcard in China.  As of this writing (2021-03) and going back
+to somewhere around 2013, it is the card model they sell when a customer asks
+for a GSM-only SIM card, as opposed to USIM cards for UMTS/LTE/etc.  This card
+model was once resold by Sysmocom as sysmoSIM-GR2, and we are hoping to get a
+batch of our own FreeCalypso-branded version which we call FCSIM1.
+
+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 does not support any
+  option of changing this key to a secure one, as would be required in any
+  application where traditional SIM security is desired.  OTOH, pySim-prog
+  needlessly resets ADM5, even though they could have left it alone - ADM11 by
+  itself is sufficient for writing to all files.
+
+* 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.  We plan on implementing one such front end tool once we
+   get our FCSIM1 card batch made.
+
+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.