annotate doc/GrcardSIM2-WEKI-file @ 222:8c151bb01d28

doc/GrcardSIM2-WEKI-file: update for partial understanding and implementation
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 09 Mar 2021 03:13:41 +0000
parents c804f2f8c138
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
196
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 GrcardSIM2 cards have a proprietary EF under DF_GSM with file ID 0x0001;
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 Osmocom wiki page for this card model gives EF.WEKI as the name for this
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 proprietary file. We (FreeCalypso) have no idea as to where this name came
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 from, and where and how the people who wrote that wiki page (Sysmocom staff or
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 not - unknown) got this knowledge. This file is important because it stores Ki
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 and the selection of COMP128 algorithm version, but the same file also appears
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 to have other fields serving other purposes which are not currently understood.
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 The total length of this transparent EF is 35 bytes, out of which only the first
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 19 bytes are documented in the Osmocom wiki page and written by their pySim-prog
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 tool. Let us now break down this file according to our currently available
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 limited understanding:
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 * The first two bytes are always 00 10 - these byte values appear in "blank"
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 unprogrammed cards as shipped by Grcard, they also appear in the Osmocom wiki
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 page, and are programmed by pySim-prog. The purpose and meaning of these two
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 bytes are completely unknown, and we have never tried writing anything
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 different into them.
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 * The next byte gives COMP128 algorithm selection plus something else that is
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 not understood:
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
222
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
23 - The low 2 bits of this byte select COMP128 algorithm version as follows:
196
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24
222
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
25 0b00 = COMP128v1
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
26 0b01 = COMP128v2
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
27 0b10 = COMP128v3
196
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28
222
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
29 Note that the Osmocom wiki page is wrong in its description of these bits:
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
30 setting these two bits to 0b11 ends up selecting COMP128v2 rather than v3.
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
31 (pySim-prog is unaffected because it always writes 00 into the whole byte,
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
32 selecting COMP128v1.)
196
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
222
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
34 - The remaining 6 bits of this byte are not understood. Osmocom wiki page
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
35 tells people to write zeros into the upper 6 bits and so does pySim-prog,
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
36 but the "blank" unprogrammed cards we got from Grcard have this byte set to
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
37 0x20. Setting the upper nibble to either 0 or 2 does not seem to affect
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
38 the result of RUN GSM ALGORITHM operations, thus it probably controls
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
39 something else.
196
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 * The next 16 bytes store Ki - this part is straightforward.
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 * The last 16 bytes are not understood; our "blank" unprogrammed cards from
c804f2f8c138 doc/GrcardSIM2-WEKI-file article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 Grcard have all FFs in these bytes.
222
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
45
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
46 fc-simtool support for programming Ki and COMP128 algorithm selection
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
47 =====================================================================
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
48
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
49 Even if we never learn the function of the other mysterious fields of EF.WEKI,
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
50 we must be able to program our own Ki and make our own selection of COMP128
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
51 algorithm version in order to use these programmable SIM cards with our own GSM
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
52 networks. The following solution has been implemented for immediate use:
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
53
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
54 * Our grcard2-set-comp128 command takes a single argument of 1, 2 or 3,
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
55 selecting COMP128 algorithm version. The implementation of this command
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
56 selects EF.WEKI, reads the previous content of the magic byte at offset 2,
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
57 keeps the upper 6 bits unchanged, and writes the new COMP128 algorithm
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
58 selection into the low 2 bits. If we ever learn the meaning of other bits,
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
59 we'll be able to add new orthogonal commands that manipulate those other bits,
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
60 but leave COMP128 selection unchanged.
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
61
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
62 * Our grcard2-set-ki command writes 16 bytes at offset 3, leaving all other
8c151bb01d28 doc/GrcardSIM2-WEKI-file: update for partial understanding
Mychaela Falconia <falcon@freecalypso.org>
parents: 196
diff changeset
63 bytes untouched.