FreeCalypso > hg > fc-sim-tools

comparison 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
comparison
equal deleted inserted replaced
36:38c14fa89937 37:4e5586c7f275
1 FreeCalypso Community SIM card model FCSIM1 is our FC-branded version of
2 GrcardSIM2. We (FreeCalypso) are making these cards for the primary purpose of
3 bringing back to current availability an exact equivalent of the discontinued
4 sysmoSIM-GR2 card, but our approach to card provisioning and programming differs
5 from Sysmocom's:
6
7 * Just like their current USIM/ISIM product, Sysmocom's previous Grcard-based
8 SIMs were preprogrammed at the factory with default IMSIs from a 901-xx range,
9 allowing them to be used as-is (without programming by the user) if the user
10 configures his or her GSM network to use the same MCC-MNC as preprogrammed on
11 the cards.
12
13 Our approach is different: different members of our community will be running
14 their own GSM networks with varying degrees of legality or illegality, and
15 every individual operator of a pirate GSM BTS will have to carefully select
16 his or her squatted MCC-MNC based on his or her unique geopolitical
17 circumstances. In this climate it makes no sense to attempt any kind of
18 generic default MCC-MNC for SIM card preprogramming, hence we get our FCSIM1
19 cards from Grcard without any factory programming ("blank"), and if anyone
20 wishes to get some cards from us, we will supply them in the same "blank"
21 state. All programming needs to be done by individual downstream card owners,
22 and fc-simtool plus accompanying utilities are the official tools for this
23 programming.
24
25 * All Sysmocom cards, both historical Grcard-based SIM products and their
26 current USIM/ISIM, have their PIN1, PUK1 and IMSI printed on the plastic. We
27 do not print these numbers because we don't assign any in the first place -
28 instead all PINs and IMSIs are freely assigned and programmed by downstream
29 owners of each individual card.
30
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
33 (2FF) piece. The rationale is that we need to able to distinguish one card
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
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
38 we use squatted ICCIDs rather than officially allocated ones.
39
40 Programming model for FCSIM1
41 ============================
42
43 Our programming model is based on the principle of a card provisioning database.
44 If you are going to get a small batch of FCSIM1 cards from us, or if you are
45 going to order a larger batch directly from Grcard, but you wish to follow the
46 same model as ours, as the first step toward programming, you will need to
47 generate your own card provisioning database. This database is an ASCII text
48 file with one line per card, and it resides in this standardized location:
49
50 /opt/freecalypso/sim-data/fcsim1-prov-db
51
52 Each line in this card provisioning database takes the following form:
53
54 ICCID=89015570000000xxxxx IMSI=xxxxxxxxxxxxxxx ACC=xxxx Ki=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
55
56 While there is nothing to stop you from constructing this card provisioning
57 database manually in vi, the intent is that it will be generated by our
58 fcsim1-mkprov utility. This utility takes a starting ICCID, a starting IMSI
59 and the number of card entries to generate - and it generates the requested
60 number of database entries with incrementing ICCIDs, incrementing IMSIs, ACC
61 circling through the standard bit-shifting range from 0001 to 0200, and random
62 Ki secret keys. (The source of random keys is currently very simple: each Ki
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
65 it will typically need to be run with output append-redirected ('>>') to
66 /opt/freecalypso/sim-data/fcsim1-prov-db.
67
68 Once the desired provisioning data have been captured in fcsim1-prov-db, this
69 database can be used in two ways:
70
71 1) There will be an fcsim1-program utility for programming individual FCSIM1
72 cards. This program will be a wrapper around fc-simtool: it will take an
73 ICCID on the command line (you will need to read and enter the number printed
74 on the plastic), it will retrieve the right record from fcsim1-prov-db, it
75 will construct a one-time (under /tmp, automatically deleted when done)
76 command script for fc-simtool based on the per-card data, and it will exec
77 fc-simtool with this command script.
78
79 2) Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI
80 software up and running on a server, I will produce appropriate tools for
81 extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever
82 format is needed for import into OsmoHLR subscriber database.