# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1615259621 0
# Node ID 8c151bb01d283199a896a9d574e3dcd35c7b7bf1
# Parent  e3059d58ec93a2a306a1ba6f5c2c9de0751d0922
doc/GrcardSIM2-WEKI-file: update for partial understanding
and implementation

diff -r e3059d58ec93 -r 8c151bb01d28 doc/GrcardSIM2-WEKI-file
--- a/doc/GrcardSIM2-WEKI-file	Tue Mar 09 02:23:00 2021 +0000
+++ b/doc/GrcardSIM2-WEKI-file	Tue Mar 09 03:13:41 2021 +0000
@@ -20,23 +20,44 @@
 * 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:
+  - The low 2 bits of this byte select COMP128 algorithm version as follows:
 
-    0 = COMP128v1
-    1 = COMP128v2
-    2 = COMP128v3
+    0b00 = COMP128v1
+    0b01 = COMP128v2
+    0b10 = 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.)
+    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 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 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.