FreeCalypso > hg > fc-pcsc-tools

annotate doc/GrcardSIM2-programming @ 229:ed8cb3c0d312 default tip

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