FreeCalypso > hg > fc-sim-tools

annotate doc/FCSIM1-programming @ 94:3d9c50880ae7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fc-simtool fetch command implemented
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 21 Apr 2021 05:50:45 +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.