GrcardSIM2 cards have a proprietary EF under DF_GSM with file ID 0x0001;
Osmocom wiki page for this card model gives EF.WEKI as the name for this
proprietary file.  We (FreeCalypso) have no idea as to where this name came
from, and where and how the people who wrote that wiki page (Sysmocom staff or
not - unknown) got this knowledge.  This file is important because it stores Ki
and the selection of COMP128 algorithm version, but the same file also appears
to have other fields serving other purposes which are not currently understood.

When we (FreeCalypso) asked Grcard about this proprietary file, they sent us a
"personalization" command script which we have archived in this code repository
under doc/vendor/grcard2-person-script; this script is a sequence of command
APDUs (raw hex with minimal comments) for an example card programming.  The
proprietary file in question is named GSM_KI in this script; the origin of the
name EF.WEKI that appears in the Osmocom wiki page is still unknown.

The total length of this transparent EF is 35 bytes, out of which only the first
19 bytes are documented in the Osmocom wiki page and written by their pySim-prog
tool.  Interestingly enough, Grcard's "personalization" command script also
writes only the first 19 bytes.  Let us now break down this file according to
our currently available limited understanding:

* The first two bytes are always 00 10 - these byte values appear in "blank"
  unprogrammed cards as shipped by Grcard, they also appear in the Osmocom wiki
  page, and are programmed by pySim-prog.  The "personalization" script we got
  from Grcard also programs the same 00 10 in these two bytes.  The purpose and
  meaning of these two bytes are completely unknown, and we have never tried
  writing anything different into them.

* The next byte gives COMP128 algorithm selection plus something else that is
  not understood:

  - The low 2 bits of this byte select COMP128 algorithm version as follows:

    0b00 = COMP128v1
    0b01 = COMP128v2
    0b10 = COMP128v3

    Note that the Osmocom wiki page is wrong in its description of these bits:
    setting these two bits to 0b11 ends up selecting COMP128v2 rather than v3.
    (pySim-prog is unaffected because it always writes 00 into the whole byte,
    selecting COMP128v1.)

  - The remaining 6 bits of this byte are not understood.  Osmocom wiki page
    tells people to write zeros into the upper 6 bits and so does pySim-prog;
    the "personalization" command script we got from Grcard also writes zeros
    into these upper 6 bits.  However, if one orders "blank" or unprogrammed
    cards from Grcard like we do, the initial "unprogrammed" state of this byte
    is 0x20, as one can see in the data/grcard2-blank-state dump.

    Setting the upper nibble to either 0 or 2 does not seem to affect the
    result of RUN GSM ALGORITHM operations, thus it probably controls something
    else - or perhaps that bit controls nothing at all, and the "unprogrammed"
    state is merely a bogon - we have no way of knowing.

* The next 16 bytes store Ki - this part is straightforward.

* The last 16 bytes are not understood; our "blank" unprogrammed cards from
  Grcard have all FFs in these bytes.

fc-simtool support for programming Ki and COMP128 algorithm selection
=====================================================================

Even if we never learn the function of the other mysterious fields of EF.WEKI,
we must be able to program our own Ki and make our own selection of COMP128
algorithm version in order to use these programmable SIM cards with our own GSM
networks.  The following solution has been implemented in the absence of better
documentation:

* Our grcard2-set-comp128 command takes one or two arguments; the first argument
  must be 1, 2 or 3, selecting COMP128 algorithm version, whereas the second
  optional argument gives the value to be written into the upper 6 bits of the
  mystery byte.  The operation of this command always begins with selecting
  EF.WEKI, but then differs depending on whether or not the optional second
  argument was given.  If only the COMP128 version argument was given, our
  command reads the previous content of the magic byte at offset 2, keeps the
  upper 6 bits unchanged, and writes the new COMP128 algorithm selection into
  the low 2 bits.  OTOH, if two arguments are given, then our command writes
  the whole byte without reading its previous value; the first argument sets
  the COMP128 algorithm version and the second argument sets the non-understood
  upper 6 bits.  The second argument is always interpreted as hex and must be
  in the range between 00 and FC, with the low 2 bits clear.

* Our grcard2-set-ki command writes 16 bytes at offset 3, leaving all other
  bytes untouched.

Practical choice for the upper 6 bits of the mystery byte
=========================================================

Following the principle of separation of mechanism and policy, our
grcard2-set-comp128 command allows the upper 6 bits of the mystery byte to be
either set explicitly or left unchanged.  However, for actual operational use
of our FCSIM1 cards with our own GSM networks with COMP128v3, should we set the
complete byte to 0x02 or to 0x22?  Based on the official "personalization"
script from Grcard, I (Mother Mychaela) have decided to write zeros into the
non-understood upper 6 bits, and this policy choice is embodied in our
fcsim1-defprog command script.