FreeCalypso > hg > fc-sim-tools

annotate doc/FCSIM1-programming @ 37:4e5586c7f275

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FCSIM1-programming: initial basics
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 17 Mar 2021 06:44:12 +0000
parents
children 711f1641b19c
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
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 (2FF) piece. The rationale is that we need to able to distinguish one card
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
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 Once the desired provisioning data have been captured in fcsim1-prov-db, this
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 database can be used in two ways:
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 1) There will be an fcsim1-program utility for programming individual FCSIM1
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 cards. This program will be a wrapper around fc-simtool: it will take an
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 ICCID on the command line (you will need to read and enter the number printed
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 on the plastic), it will retrieve the right record from fcsim1-prov-db, it
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 will construct a one-time (under /tmp, automatically deleted when done)
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 command script for fc-simtool based on the per-card data, and it will exec
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 fc-simtool with this command script.
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 2) Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 software up and running on a server, I will produce appropriate tools for
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever
4e5586c7f275 doc/FCSIM1-programming: initial basics
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 format is needed for import into OsmoHLR subscriber database.