FreeCalypso > hg > fc-sim-tools

annotate doc/FCSIM1-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 711f1641b19c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
37
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 FreeCalypso Community SIM card model FCSIM1 is our FC-branded version of
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 GrcardSIM2. We (FreeCalypso) are making these cards for the primary purpose of
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 bringing back to current availability an exact equivalent of the discontinued
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 sysmoSIM-GR2 card, but our approach to card provisioning and programming differs
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 from Sysmocom's:
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 * Just like their current USIM/ISIM product, Sysmocom's previous Grcard-based
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 SIMs were preprogrammed at the factory with default IMSIs from a 901-xx range,
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 allowing them to be used as-is (without programming by the user) if the user
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 configures his or her GSM network to use the same MCC-MNC as preprogrammed on
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 the cards.
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 Our approach is different: different members of our community will be running
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 their own GSM networks with varying degrees of legality or illegality, and
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 every individual operator of a pirate GSM BTS will have to carefully select
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 his or her squatted MCC-MNC based on his or her unique geopolitical
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 circumstances. In this climate it makes no sense to attempt any kind of
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 generic default MCC-MNC for SIM card preprogramming, hence we get our FCSIM1
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 cards from Grcard without any factory programming ("blank"), and if anyone
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 wishes to get some cards from us, we will supply them in the same "blank"
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 state. All programming needs to be done by individual downstream card owners,
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 and fc-simtool plus accompanying utilities are the official tools for this
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 programming.
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 * All Sysmocom cards, both historical Grcard-based SIM products and their
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 current USIM/ISIM, have their PIN1, PUK1 and IMSI printed on the plastic. We
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 do not print these numbers because we don't assign any in the first place -
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 instead all PINs and IMSIs are freely assigned and programmed by downstream
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 owners of each individual card.
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 * We did pick a squatted range of ICCID numbers, and our cards have these ICCIDs
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 printed on the plastic, both on the ID-1 carrier and on the little plug-in SIM
80
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
33 (2FF) piece. The rationale is that we need to be able to distinguish one card
37
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 from another visually, and because the whole purpose of ICCID is to identify
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 each card as a physical artifact irrespective of logical function, this ID
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 number is perfect for the job. It is never transmitted over any air
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 interfaces, hence no one outside of our community needs to know or care that
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 we use squatted ICCIDs rather than officially allocated ones.
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 Programming model for FCSIM1
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 ============================
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 Our programming model is based on the principle of a card provisioning database.
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 If you are going to get a small batch of FCSIM1 cards from us, or if you are
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 going to order a larger batch directly from Grcard, but you wish to follow the
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 same model as ours, as the first step toward programming, you will need to
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 generate your own card provisioning database. This database is an ASCII text
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 file with one line per card, and it resides in this standardized location:
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 /opt/freecalypso/sim-data/fcsim1-prov-db
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 Each line in this card provisioning database takes the following form:
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 ICCID=89015570000000xxxxx IMSI=xxxxxxxxxxxxxxx ACC=xxxx Ki=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 While there is nothing to stop you from constructing this card provisioning
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 database manually in vi, the intent is that it will be generated by our
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 fcsim1-mkprov utility. This utility takes a starting ICCID, a starting IMSI
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 and the number of card entries to generate - and it generates the requested
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 number of database entries with incrementing ICCIDs, incrementing IMSIs, ACC
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 circling through the standard bit-shifting range from 0001 to 0200, and random
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 Ki secret keys. (The source of random keys is currently very simple: each Ki
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 is read directly from /dev/urandom, or from /dev/random if desired. Suggestions
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 for improvement are welcome.) fcsim1-mkprov emits its output to stdout, hence
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 it will typically need to be run with output append-redirected ('>>') to
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 /opt/freecalypso/sim-data/fcsim1-prov-db.
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67
80
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
68 fcsim1-mkprov usage details
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
69 ===========================
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
70
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
71 The canonical way to run fcsim1-mkprov is as follows:
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
72
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
73 fcsim1-mkprov -n num start-iccid start-imsi >> /opt/freecalypso/sim-data/fcsim1-prov-db
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
74
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
75 -n option specifies the number of card entries to generate; if this option is
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
76 omitted, only one card entry will be generated. The starting ICCID needs to be
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
77 given in 18-digit form _without_ the Luhn check digit - fcsim1-mkprov will
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
78 increment this ICCID for the number of card entries to be generated (we will
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
79 always supply consecutively-numbered cards to anyone buying a small batch from
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
80 us), and it will generate the correct Luhn check digit for each ICCID. However,
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
81 you can use our FC SIM tools shorthand notation for the starting ICCID: for
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
82 example, if you enter 8901557-100, that entry will be automatically expanded to
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
83 18-digit 890155700000000100. IMSIs are expected to always be 15 digits long,
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
84 but the same shorthand notation can be used here too.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
85
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
86 The following additional options are accepted:
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
87
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
88 -a [0-9]
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
89
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
90 The argument for this option is a single digit from '0' to '9'; the
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
91 effect is to set ACC for the first card entry to be generated: -a 0
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
92 corresponds to ACC=0001, -a 1 corresponds to ACC=0002, and so forth
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
93 through -a 9 corresponding to ACC=0200. When many card entries are
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
94 generated (-n option), subsequent card ACCs will automatically increment
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
95 and circle, i.e., bit-shift to the left until ACC=0200 is reached, then
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
96 circle back to ACC=0001 and so on.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
97
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
98 -m start-msisdn
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
99
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
100 By default (in the absence of -m option) each fcsim1-prov-db record
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
101 contains only ICCID, IMSI, ACC and Ki as shown above. Running
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
102 fcsim1-mkprov with -m start-msisdn causes incrementing MSISDN numbers
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
103 to be generated as well, appearing as an extra MSISDN=xxx field in each
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
104 fcsim1-prov-db record.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
105
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
106 -r /dev/random
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
107
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
108 Read random bytes for Ki from /dev/random instead of /dev/urandom.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
109
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
110 Programming cards with fcsim1-program and fc-simtool
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
111 ====================================================
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
112
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
113 Once the desired provisioning data have been captured in fcsim1-prov-db, the
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
114 following procedure is envisioned for actual card programming:
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
115
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
116 1) You pick the card to be programmed from the unprogrammed bin;
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
117
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
118 2) While holding the card in your hand and looking at the ICCID printed on the
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
119 plastic, you enter a command line similar to this example:
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
120
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
121 fcsim1-program -c fcsim1-defprog 8901557-0008 | fc-simtool -p0
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
122
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
123 Type in the needed command line, but don't press Enter yet...
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
124
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
125 3) Insert the card into your reader stand (assuming that you will be using a
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
126 stand-type card programming station such as HID Omnikey 3121), at which
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
127 point the ICCID printed on the card is no longer visible.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
128
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
129 4) Press Enter to execute the command you typed in step 2 above.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
130
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
131 Now the explanation: fcsim1-program is a utility that generates per-card
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
132 programming command scripts to be fed to fc-simtool. It requires the ICCID
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
133 (read from the plastic with human eyeballs) to be entered on the command line,
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
134 and this time the ICCID being entered needs to include the Luhn check digit:
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
135 after all, you are simply entering the number from the plastic, and the printed
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
136 ICCID does include the Luhn check digit. Our FC SIM tools shorthand notation
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
137 for skipping the long string of zeros in the middle still works though!
37
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138
80
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
139 After verifying the Luhn check digit, fcsim1-program will look up the entered
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
140 ICCID in fcsim1-prov-db (if there is no entry for this ICCID, it is an error),
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
141 and it will retrieve all per-card provisioning parameters from there. The
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
142 programming command script generated by fcsim1-program (intended to be piped
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
143 directly into fc-simtool) has the following structure:
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
144
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
145 verify-ext 11 88888888 # ADM11 authentication
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
146 exec fcsim1-defprog # common command script specified with -c
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
147 write-iccid XXXX # programming per-card ICCID
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
148 write-imsi XXXX # programming per-card IMSI
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
149 write-acc XXXX # programming per-card ACC
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
150 grcard2-set-ki XXXX # programming per-card Ki
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
151
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
152 If the card record in fcsim1-prov-db includes the optional MSISDN= field
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
153 (generated with fcsim1-mkprov -m option), the script generated by fcsim1-program
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
154 will also include a pb-update-imm command to write the MSISDN record.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
155
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
156 Common command scripts: only ICCID, IMSI, ACC, Ki and optional MSISDN are
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
157 expected to be different for each individual card, whereas all other SIM card
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
158 programming is expected to be the same for all cards in a given fiefdom.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
159 Therefore, each tribal chieftain who is going to run his or her own GSM network
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
160 will need to create their own custom common command script based on
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
161 fcsim1-defprog: for example, for our own Themyscira Wireless operation we have
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
162 our own private themwi-prog script that is based on fcsim1-defprog and takes
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
163 its place.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
164
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
165 Philosophy regarding ICCID
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
166 ==========================
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
167
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
168 Our workflow is set up so that whenever you program or reprogram a card, you
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
169 have to read the ICCID from the plastic with your eyeballs and enter it on the
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
170 command line. Our fcsim1-program | fc-simtool pipeline programs the EF_ICCID
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
171 record, but nowhere in our current workflow do we read it back for further
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
172 database lookups.
37
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173
80
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
174 We have considered an alternative approach of programming EF_ICCID (to match
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
175 the number printed on the plastic) on all of our FCSIM1 cards at FreeCalypso HQ,
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
176 and then expecting downstream card users to run tools that read EF_ICCID from
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
177 the card. However, this approach has been rejected because unlike
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
178 sysmoISIM-SJA2, GrcardSIM2 cards allow EF_ICCID to be freely rewritten like any
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
179 other admin-write file, thus even if we program it correctly at FreeCalypso HQ,
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
180 it is always possible for EF_ICCID to become messed up further downstream. But
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
181 the laser marking of ICCID on the plastic is truly immutable, hence the most
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
182 reliable workflow for unconditionally bringing each card to the desired correct
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
183 state irrespective of prior programming state is to read the ICCID from the
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
184 plastic with human eyeballs, enter it on the command line, and have the tools
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
185 unconditionally program it.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
186
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
187 Philosophy regarding ADM keys
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
188 =============================
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
189
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
190 The idea is similar to the one for ICCID: let's eliminate any dependencies on
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
191 prior state of each card as much as possible. Based on this philosophy, we
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
192 currently leave the ADM11 key (SUPER ADM which supersedes ADM5 and all lower
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
193 PINs) at the factory default of 88888888, and we discourage changing it. If
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
194 someone desires the traditional security model where an operator programs SIMs
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
195 and then prevents subscribers from being able to read their Ki, then you will
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
196 have to change your ADM11 key (and ADM5 too, for good measure) to true per-card
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
197 secrets - but then you won't be able to freely rerun programming scripts without
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
198 caring about prior state.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
199
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
200 For those who wish to change their ADM11 key, we provide low-level
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
201 grcard2-set-super and grcard2-set-super-hex commands that do the deed, but our
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
202 higher-level fcsim1-mkprov + fcsim1-program suite does not currently have any
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
203 sensible support for secure ADM11 (or ADM5) keys. If someone desires such
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
204 functionality, we can implement it as paid feature development, but probably
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
205 not otherwise.
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
206
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
207 OsmoHLR integration
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
208 ===================
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
209
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
210 Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
211 software up and running on a server, I will produce appropriate tools for
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
212 extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever
711f1641b19c doc/FCSIM1-programming: update for fcsim1-program
Mychaela Falconia <falcon@freecalypso.org>
parents: 37
diff changeset
213 format is needed for import into OsmoHLR subscriber database.