FreeCalypso > hg > fc-sim-tools

annotate doc/GrcardSIM2-WEKI-file @ 96:a5cfe5135701

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
simtool: grcard2.c split into grcard2ki.c and grcard2pins.c
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 05 May 2021 03:55:23 +0000
parents 526193acfb3f
children dc772132b5c9
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
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 networks. The following solution has been implemented for immediate use:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 * Our grcard2-set-comp128 command takes a single argument of 1, 2 or 3,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 selecting COMP128 algorithm version. The implementation of this command
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 selects EF.WEKI, reads the previous content of the magic byte at offset 2,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 keeps the upper 6 bits unchanged, and writes the new COMP128 algorithm
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 selection into the low 2 bits. If we ever learn the meaning of other bits,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 we'll be able to add new orthogonal commands that manipulate those other bits,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 but leave COMP128 selection unchanged.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 * 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
77 bytes untouched.