FreeCalypso > hg > fc-sim-tools

annotate doc/GrcardSIM2-programming @ 75:42229bec887b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/GrcardSIM2-programming: a few updates
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 07 Apr 2021 07:17:12 +0000
parents da6e9d0b2ee6
children 8c23d2a9c013
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 The card model which we call GrcardSIM2 is one of the many smart card models
75
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
2 made and sold by Grcard in China. Our FreeCalypso-branded version of this card
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
3 is called FCSIM1 (batch of 200 cards made in 2021-04), but the same card model
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
4 was previously sold by Sysmocom as sysmoSIM-GR2, going back to some time around
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
5 2013.
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 Our fc-simtool supports full programming of these cards: you can take a card
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 whose initial state is "blank" or unprogrammed, or a card with some previous
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 programming, and you can program it to your own liking using fc-simtool. For
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 the purpose of programming this particular card model (as opposed to USIM/ISIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 cards), our fc-simtool offers the following advantages over well-known
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 competitor pySim-prog:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 * These cards support all 3 versions of COMP128 algorithm (v1, v2 and v3), but
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 pySim-prog unconditionally selects COMP128v1. Our grcard2-set-comp128 command
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 allows any of the 3 algorithm versions to be selected, and in the Mother's
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 opinion it makes no sense to select any version other than COMP128v3 for new
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 GSM network deployments.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 * These cards have a fairly sophisticated security model with two different ADM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 access levels: see GrcardSIM2-security-model article for the details.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 pySim-prog support for this security model is fundamentally broken: it
75
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
23 authenticates with ADM11 as required for writing Ki, but it always sends the
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
24 default ADM11 key, i.e., pySim-prog -a or -A options have no effect on the key
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
25 that actually matters. Instead of supporting changeable ADM11 keys,
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
26 pySim-prog needlessly resets ADM5, even though they could have left it alone
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
27 (ADM11 by itself is sufficient for writing to all files), and the effect of
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
28 -a or -A options is only on this unnecessary ADM5 setting.
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 * Further on the security model, GrcardSIM2 cards allow admins to reset
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 PIN1/PIN2/PUK1/PUK2 secret codes after authenticating with ADM5 or ADM11 -
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 this mechanism is the only way to reset PUK1 and PUK2 if the previous codes
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 are unknown. pySim-prog provides no support for setting PIN/PUK codes.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 * fc-simtool allows every single file in the card file system to be written as
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 you like. Absolutely any file can be read and written in raw hex, and we also
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 provide high-level read and write commands for most files. In contrast,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 pySim-prog implements a rigid and inflexible programming model, writing only
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 a few files and only in one very limited way.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 Using fc-simtool to program GrcardSIM2 cards
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
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 To begin with, you must know the ADM11 (aka SUPER ADM) secret code for your
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 card. If you got your card directly from Grcard factory or from a reseller such
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 as FreeCalypso who leaves this default ADM11 key unchanged, your ADM11 key is
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 ASCII-decimal 88888888, and you need to authenticate as follows:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 verify-ext 11 88888888
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 If the previous owner of your card changed this ADM11 key to something else, or
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 if you had Grcard factory program cards for you with different ADM keys, then
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 you need to know what the ADM11 secret is - if it is lost, there is no recovery,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 and you have to get a new card. If you have a non-default ADM11 key, you need
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 to enter it using either verify-ext 11 or verify-hex 11 command, depending on
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 whether the key falls into the restricted ASCII-decimal subset or not. In any
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 case, this verify-ext 11 or verify-hex 11 command should ideally be the first
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 command in your fc-simtool session; if it is not the first command in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 session, then it needs to be preceded with select MF.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 Once you have authenticated with ADM11, you are ready to run your programming
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 scripts. Because fc-simtool is not a "one size fits all" tool like pySim-prog,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 but rather a fully generalized command shell that allows you to poke at whatever
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 files you like in whatever order and manner you like, practical SIM programming
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 should be done with customized command scripts. Furthermore, we recommend that
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 you split your custom programming scripts into two levels:
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 1) You should have one command script which you install under
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 /opt/freecalypso/sim-scripts that programs SIMs appropriately for your GSM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 network. This script should be the same for all of your cards, programming
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 SST, PLMN selection (PLMNsel and FPLMN) and branding files SPN, PNN and OPL.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 See our fcsim1-defprog script for a starting point.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 2) Per-card settings like ICCID, IMSI, ACC and Ki can only be set either
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 manually (OK for one or two cards, but doesn't scale), or by way of custom
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 front end or wrapper programs that generate and execute one-time fc-simtool
75
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
77 command scripts. Now that our FCSIM1 cards are here, we plan on implementing
42229bec887b doc/GrcardSIM2-programming: a few updates
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
78 the necessary front end tool soon - see FCSIM1-programming article.
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 Please refer to Admin-write-commands, GrcardSIM2-WEKI-file and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 GrcardSIM2-security-model articles for commands to be used in crafting your
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 custom programming scripts.