FreeCalypso > hg > fc-sim-tools

comparison doc/FCSIM1-programming @ 80:711f1641b19c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FCSIM1-programming: update for fcsim1-program
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 09 Apr 2021 08:19:31 +0000
parents 4e5586c7f275
children
comparison
equal deleted inserted replaced
79:2a24e94400e8 80:711f1641b19c
28 instead all PINs and IMSIs are freely assigned and programmed by downstream 28 instead all PINs and IMSIs are freely assigned and programmed by downstream
29 owners of each individual card. 29 owners of each individual card.
30 30
31 * We did pick a squatted range of ICCID numbers, and our cards have these ICCIDs 31 * We did pick a squatted range of ICCID numbers, and our cards have these ICCIDs
32 printed on the plastic, both on the ID-1 carrier and on the little plug-in SIM 32 printed on the plastic, both on the ID-1 carrier and on the little plug-in SIM
33 (2FF) piece. The rationale is that we need to able to distinguish one card 33 (2FF) piece. The rationale is that we need to be able to distinguish one card
34 from another visually, and because the whole purpose of ICCID is to identify 34 from another visually, and because the whole purpose of ICCID is to identify
35 each card as a physical artifact irrespective of logical function, this ID 35 each card as a physical artifact irrespective of logical function, this ID
36 number is perfect for the job. It is never transmitted over any air 36 number is perfect for the job. It is never transmitted over any air
37 interfaces, hence no one outside of our community needs to know or care that 37 interfaces, hence no one outside of our community needs to know or care that
38 we use squatted ICCIDs rather than officially allocated ones. 38 we use squatted ICCIDs rather than officially allocated ones.
63 is read directly from /dev/urandom, or from /dev/random if desired. Suggestions 63 is read directly from /dev/urandom, or from /dev/random if desired. Suggestions
64 for improvement are welcome.) fcsim1-mkprov emits its output to stdout, hence 64 for improvement are welcome.) fcsim1-mkprov emits its output to stdout, hence
65 it will typically need to be run with output append-redirected ('>>') to 65 it will typically need to be run with output append-redirected ('>>') to
66 /opt/freecalypso/sim-data/fcsim1-prov-db. 66 /opt/freecalypso/sim-data/fcsim1-prov-db.
67 67
68 Once the desired provisioning data have been captured in fcsim1-prov-db, this 68 fcsim1-mkprov usage details
69 database can be used in two ways: 69 ===========================
70 70
71 1) There will be an fcsim1-program utility for programming individual FCSIM1 71 The canonical way to run fcsim1-mkprov is as follows:
72 cards. This program will be a wrapper around fc-simtool: it will take an 72
73 ICCID on the command line (you will need to read and enter the number printed 73 fcsim1-mkprov -n num start-iccid start-imsi >> /opt/freecalypso/sim-data/fcsim1-prov-db
74 on the plastic), it will retrieve the right record from fcsim1-prov-db, it 74
75 will construct a one-time (under /tmp, automatically deleted when done) 75 -n option specifies the number of card entries to generate; if this option is
76 command script for fc-simtool based on the per-card data, and it will exec 76 omitted, only one card entry will be generated. The starting ICCID needs to be
77 fc-simtool with this command script. 77 given in 18-digit form _without_ the Luhn check digit - fcsim1-mkprov will
78 78 increment this ICCID for the number of card entries to be generated (we will
79 2) Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI 79 always supply consecutively-numbered cards to anyone buying a small batch from
80 software up and running on a server, I will produce appropriate tools for 80 us), and it will generate the correct Luhn check digit for each ICCID. However,
81 extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever 81 you can use our FC SIM tools shorthand notation for the starting ICCID: for
82 format is needed for import into OsmoHLR subscriber database. 82 example, if you enter 8901557-100, that entry will be automatically expanded to
83 18-digit 890155700000000100. IMSIs are expected to always be 15 digits long,
84 but the same shorthand notation can be used here too.
85
86 The following additional options are accepted:
87
88 -a [0-9]
89
90 The argument for this option is a single digit from '0' to '9'; the
91 effect is to set ACC for the first card entry to be generated: -a 0
92 corresponds to ACC=0001, -a 1 corresponds to ACC=0002, and so forth
93 through -a 9 corresponding to ACC=0200. When many card entries are
94 generated (-n option), subsequent card ACCs will automatically increment
95 and circle, i.e., bit-shift to the left until ACC=0200 is reached, then
96 circle back to ACC=0001 and so on.
97
98 -m start-msisdn
99
100 By default (in the absence of -m option) each fcsim1-prov-db record
101 contains only ICCID, IMSI, ACC and Ki as shown above. Running
102 fcsim1-mkprov with -m start-msisdn causes incrementing MSISDN numbers
103 to be generated as well, appearing as an extra MSISDN=xxx field in each
104 fcsim1-prov-db record.
105
106 -r /dev/random
107
108 Read random bytes for Ki from /dev/random instead of /dev/urandom.
109
110 Programming cards with fcsim1-program and fc-simtool
111 ====================================================
112
113 Once the desired provisioning data have been captured in fcsim1-prov-db, the
114 following procedure is envisioned for actual card programming:
115
116 1) You pick the card to be programmed from the unprogrammed bin;
117
118 2) While holding the card in your hand and looking at the ICCID printed on the
119 plastic, you enter a command line similar to this example:
120
121 fcsim1-program -c fcsim1-defprog 8901557-0008 | fc-simtool -p0
122
123 Type in the needed command line, but don't press Enter yet...
124
125 3) Insert the card into your reader stand (assuming that you will be using a
126 stand-type card programming station such as HID Omnikey 3121), at which
127 point the ICCID printed on the card is no longer visible.
128
129 4) Press Enter to execute the command you typed in step 2 above.
130
131 Now the explanation: fcsim1-program is a utility that generates per-card
132 programming command scripts to be fed to fc-simtool. It requires the ICCID
133 (read from the plastic with human eyeballs) to be entered on the command line,
134 and this time the ICCID being entered needs to include the Luhn check digit:
135 after all, you are simply entering the number from the plastic, and the printed
136 ICCID does include the Luhn check digit. Our FC SIM tools shorthand notation
137 for skipping the long string of zeros in the middle still works though!
138
139 After verifying the Luhn check digit, fcsim1-program will look up the entered
140 ICCID in fcsim1-prov-db (if there is no entry for this ICCID, it is an error),
141 and it will retrieve all per-card provisioning parameters from there. The
142 programming command script generated by fcsim1-program (intended to be piped
143 directly into fc-simtool) has the following structure:
144
145 verify-ext 11 88888888 # ADM11 authentication
146 exec fcsim1-defprog # common command script specified with -c
147 write-iccid XXXX # programming per-card ICCID
148 write-imsi XXXX # programming per-card IMSI
149 write-acc XXXX # programming per-card ACC
150 grcard2-set-ki XXXX # programming per-card Ki
151
152 If the card record in fcsim1-prov-db includes the optional MSISDN= field
153 (generated with fcsim1-mkprov -m option), the script generated by fcsim1-program
154 will also include a pb-update-imm command to write the MSISDN record.
155
156 Common command scripts: only ICCID, IMSI, ACC, Ki and optional MSISDN are
157 expected to be different for each individual card, whereas all other SIM card
158 programming is expected to be the same for all cards in a given fiefdom.
159 Therefore, each tribal chieftain who is going to run his or her own GSM network
160 will need to create their own custom common command script based on
161 fcsim1-defprog: for example, for our own Themyscira Wireless operation we have
162 our own private themwi-prog script that is based on fcsim1-defprog and takes
163 its place.
164
165 Philosophy regarding ICCID
166 ==========================
167
168 Our workflow is set up so that whenever you program or reprogram a card, you
169 have to read the ICCID from the plastic with your eyeballs and enter it on the
170 command line. Our fcsim1-program | fc-simtool pipeline programs the EF_ICCID
171 record, but nowhere in our current workflow do we read it back for further
172 database lookups.
173
174 We have considered an alternative approach of programming EF_ICCID (to match
175 the number printed on the plastic) on all of our FCSIM1 cards at FreeCalypso HQ,
176 and then expecting downstream card users to run tools that read EF_ICCID from
177 the card. However, this approach has been rejected because unlike
178 sysmoISIM-SJA2, GrcardSIM2 cards allow EF_ICCID to be freely rewritten like any
179 other admin-write file, thus even if we program it correctly at FreeCalypso HQ,
180 it is always possible for EF_ICCID to become messed up further downstream. But
181 the laser marking of ICCID on the plastic is truly immutable, hence the most
182 reliable workflow for unconditionally bringing each card to the desired correct
183 state irrespective of prior programming state is to read the ICCID from the
184 plastic with human eyeballs, enter it on the command line, and have the tools
185 unconditionally program it.
186
187 Philosophy regarding ADM keys
188 =============================
189
190 The idea is similar to the one for ICCID: let's eliminate any dependencies on
191 prior state of each card as much as possible. Based on this philosophy, we
192 currently leave the ADM11 key (SUPER ADM which supersedes ADM5 and all lower
193 PINs) at the factory default of 88888888, and we discourage changing it. If
194 someone desires the traditional security model where an operator programs SIMs
195 and then prevents subscribers from being able to read their Ki, then you will
196 have to change your ADM11 key (and ADM5 too, for good measure) to true per-card
197 secrets - but then you won't be able to freely rerun programming scripts without
198 caring about prior state.
199
200 For those who wish to change their ADM11 key, we provide low-level
201 grcard2-set-super and grcard2-set-super-hex commands that do the deed, but our
202 higher-level fcsim1-mkprov + fcsim1-program suite does not currently have any
203 sensible support for secure ADM11 (or ADM5) keys. If someone desires such
204 functionality, we can implement it as paid feature development, but probably
205 not otherwise.
206
207 OsmoHLR integration
208 ===================
209
210 Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI
211 software up and running on a server, I will produce appropriate tools for
212 extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever
213 format is needed for import into OsmoHLR subscriber database.