--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/GrcardSIM2-WEKI-file	Sun Mar 14 07:57:09 2021 +0000
@@ -0,0 +1,63 @@
+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.
+
+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.  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 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,
+    but the "blank" unprogrammed cards we got from Grcard have this byte set to
+    0x20.  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.
+
+* 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 for immediate use:
+
+* Our grcard2-set-comp128 command takes a single argument of 1, 2 or 3,
+  selecting COMP128 algorithm version.  The implementation of this command
+  selects EF.WEKI, 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.  If we ever learn the meaning of other bits,
+  we'll be able to add new orthogonal commands that manipulate those other bits,
+  but leave COMP128 selection unchanged.
+
+* Our grcard2-set-ki command writes 16 bytes at offset 3, leaving all other
+  bytes untouched.