FreeCalypso > hg > fc-pcsc-tools

comparison doc/GrcardSIM2-programming @ 224:80fc2b2f83c2

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