FreeCalypso > hg > fc-sim-tools

annotate doc/GrcardSIM2-programming @ 93:6041c601304d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fcsim1-mkprov: revert OTA key addition It appears that GrcardSIM2 cards (which is what we got for FCSIM1) do not support OTA after all, contrary to what we were previously led to believe by some tech support emails from Grcard - apparently those support emails and OTA descriptions referred to some other card model(s).
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 21 Apr 2021 05:38:39 +0000
parents 8c23d2a9c013
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 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
81
8c23d2a9c013 doc/GrcardSIM2-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
77 command scripts. See FCSIM1-programming article for the solution which we
8c23d2a9c013 doc/GrcardSIM2-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
78 have implemented.
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.