# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1615082162 0
# Node ID c804f2f8c1382869ce59d3348a8f452f1010c491
# Parent  810ea92d9f4706ded75e3d84c9c23c1b9901dcd9
doc/GrcardSIM2-WEKI-file article written

diff -r 810ea92d9f47 -r c804f2f8c138 doc/GrcardSIM2-WEKI-file
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/GrcardSIM2-WEKI-file	Sun Mar 07 01:56:02 2021 +0000
@@ -0,0 +1,42 @@
+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 nibble of this byte selects COMP128 algorithm version as follows:
+
+    0 = COMP128v1
+    1 = COMP128v2
+    2 = COMP128v3
+
+    Note that the Osmocom wiki page is wrong in its description of this nibble:
+    setting this nibble to 3 ends up selecting COMP128v2 rather than v3.
+    (pySim-prog is unaffected because it always writes 0 for COMP128v1.)
+
+  - The high nibble of this byte is not understood.  Osmocom wiki page tells
+    people to write 0 into this nibble and so does pySim-prog, but the "blank"
+    unprogrammed cards we got from Grcard have it set to 2.  Setting this 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.