FreeCalypso > hg > fc-sim-tools

annotate doc/GrcardSIM2-WEKI-file @ 100:dc772132b5c9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/GrcardSIM2-WEKI-file: document mechanism and policy changes regarding the upper 6 bits of the mystery byte
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 05 May 2021 05:22:28 +0000
parents 526193acfb3f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 GrcardSIM2 cards have a proprietary EF under DF_GSM with file ID 0x0001;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 Osmocom wiki page for this card model gives EF.WEKI as the name for this
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 proprietary file. We (FreeCalypso) have no idea as to where this name came
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 from, and where and how the people who wrote that wiki page (Sysmocom staff or
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 not - unknown) got this knowledge. This file is important because it stores Ki
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 and the selection of COMP128 algorithm version, but the same file also appears
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 to have other fields serving other purposes which are not currently understood.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
76
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
9 When we (FreeCalypso) asked Grcard about this proprietary file, they sent us a
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
10 "personalization" command script which we have archived in this code repository
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
11 under doc/vendor/grcard2-person-script; this script is a sequence of command
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
12 APDUs (raw hex with minimal comments) for an example card programming. The
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
13 proprietary file in question is named GSM_KI in this script; the origin of the
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
14 name EF.WEKI that appears in the Osmocom wiki page is still unknown.
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
15
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 The total length of this transparent EF is 35 bytes, out of which only the first
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 19 bytes are documented in the Osmocom wiki page and written by their pySim-prog
76
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
18 tool. Interestingly enough, Grcard's "personalization" command script also
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
19 writes only the first 19 bytes. Let us now break down this file according to
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
20 our currently available limited understanding:
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 * The first two bytes are always 00 10 - these byte values appear in "blank"
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 unprogrammed cards as shipped by Grcard, they also appear in the Osmocom wiki
76
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
24 page, and are programmed by pySim-prog. The "personalization" script we got
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
25 from Grcard also programs the same 00 10 in these two bytes. The purpose and
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
26 meaning of these two bytes are completely unknown, and we have never tried
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
27 writing anything different into them.
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 * The next byte gives COMP128 algorithm selection plus something else that is
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 not understood:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 - The low 2 bits of this byte select COMP128 algorithm version as follows:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 0b00 = COMP128v1
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 0b01 = COMP128v2
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 0b10 = COMP128v3
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 Note that the Osmocom wiki page is wrong in its description of these bits:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 setting these two bits to 0b11 ends up selecting COMP128v2 rather than v3.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 (pySim-prog is unaffected because it always writes 00 into the whole byte,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 selecting COMP128v1.)
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 - The remaining 6 bits of this byte are not understood. Osmocom wiki page
76
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
44 tells people to write zeros into the upper 6 bits and so does pySim-prog;
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
45 the "personalization" command script we got from Grcard also writes zeros
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
46 into these upper 6 bits. However, if one orders "blank" or unprogrammed
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
47 cards from Grcard like we do, the initial "unprogrammed" state of this byte
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
48 is 0x20, as one can see in the data/grcard2-blank-state dump.
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
49
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
50 Setting the upper nibble to either 0 or 2 does not seem to affect the
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
51 result of RUN GSM ALGORITHM operations, thus it probably controls something
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
52 else - or perhaps that bit controls nothing at all, and the "unprogrammed"
526193acfb3f doc/GrcardSIM2-WEKI-file: update with knowledge from
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
53 state is merely a bogon - we have no way of knowing.
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 * The next 16 bytes store Ki - this part is straightforward.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 * The last 16 bytes are not understood; our "blank" unprogrammed cards from
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 Grcard have all FFs in these bytes.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 fc-simtool support for programming Ki and COMP128 algorithm selection
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 =====================================================================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 Even if we never learn the function of the other mysterious fields of EF.WEKI,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 we must be able to program our own Ki and make our own selection of COMP128
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 algorithm version in order to use these programmable SIM cards with our own GSM
100
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
66 networks. The following solution has been implemented in the absence of better
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
67 documentation:
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
100
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
69 * Our grcard2-set-comp128 command takes one or two arguments; the first argument
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
70 must be 1, 2 or 3, selecting COMP128 algorithm version, whereas the second
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
71 optional argument gives the value to be written into the upper 6 bits of the
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
72 mystery byte. The operation of this command always begins with selecting
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
73 EF.WEKI, but then differs depending on whether or not the optional second
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
74 argument was given. If only the COMP128 version argument was given, our
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
75 command reads the previous content of the magic byte at offset 2, keeps the
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
76 upper 6 bits unchanged, and writes the new COMP128 algorithm selection into
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
77 the low 2 bits. OTOH, if two arguments are given, then our command writes
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
78 the whole byte without reading its previous value; the first argument sets
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
79 the COMP128 algorithm version and the second argument sets the non-understood
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
80 upper 6 bits. The second argument is always interpreted as hex and must be
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
81 in the range between 00 and FC, with the low 2 bits clear.
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 * Our grcard2-set-ki command writes 16 bytes at offset 3, leaving all other
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 bytes untouched.
100
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
85
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
86 Practical choice for the upper 6 bits of the mystery byte
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
87 =========================================================
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
88
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
89 Following the principle of separation of mechanism and policy, our
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
90 grcard2-set-comp128 command allows the upper 6 bits of the mystery byte to be
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
91 either set explicitly or left unchanged. However, for actual operational use
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
92 of our FCSIM1 cards with our own GSM networks with COMP128v3, should we set the
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
93 complete byte to 0x02 or to 0x22? Based on the official "personalization"
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
94 script from Grcard, I (Mother Mychaela) have decided to write zeros into the
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
95 non-understood upper 6 bits, and this policy choice is embodied in our
dc772132b5c9 doc/GrcardSIM2-WEKI-file: document mechanism and policy changes
Mychaela Falconia <falcon@freecalypso.org>
parents: 76
diff changeset
96 fcsim1-defprog command script.