# HG changeset patch # User Mychaela Falconia # Date 1615963452 0 # Node ID 4e5586c7f275291206afe392e692b7ea538a0813 # Parent 38c14fa89937eb0ae84ae2e6dc7567290be8bc5d doc/FCSIM1-programming: initial basics diff -r 38c14fa89937 -r 4e5586c7f275 doc/FCSIM1-programming --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/FCSIM1-programming Wed Mar 17 06:44:12 2021 +0000 @@ -0,0 +1,82 @@ +FreeCalypso Community SIM card model FCSIM1 is our FC-branded version of +GrcardSIM2. We (FreeCalypso) are making these cards for the primary purpose of +bringing back to current availability an exact equivalent of the discontinued +sysmoSIM-GR2 card, but our approach to card provisioning and programming differs +from Sysmocom's: + +* Just like their current USIM/ISIM product, Sysmocom's previous Grcard-based + SIMs were preprogrammed at the factory with default IMSIs from a 901-xx range, + allowing them to be used as-is (without programming by the user) if the user + configures his or her GSM network to use the same MCC-MNC as preprogrammed on + the cards. + + Our approach is different: different members of our community will be running + their own GSM networks with varying degrees of legality or illegality, and + every individual operator of a pirate GSM BTS will have to carefully select + his or her squatted MCC-MNC based on his or her unique geopolitical + circumstances. In this climate it makes no sense to attempt any kind of + generic default MCC-MNC for SIM card preprogramming, hence we get our FCSIM1 + cards from Grcard without any factory programming ("blank"), and if anyone + wishes to get some cards from us, we will supply them in the same "blank" + state. All programming needs to be done by individual downstream card owners, + and fc-simtool plus accompanying utilities are the official tools for this + programming. + +* All Sysmocom cards, both historical Grcard-based SIM products and their + current USIM/ISIM, have their PIN1, PUK1 and IMSI printed on the plastic. We + do not print these numbers because we don't assign any in the first place - + instead all PINs and IMSIs are freely assigned and programmed by downstream + owners of each individual card. + +* We did pick a squatted range of ICCID numbers, and our cards have these ICCIDs + printed on the plastic, both on the ID-1 carrier and on the little plug-in SIM + (2FF) piece. The rationale is that we need to able to distinguish one card + from another visually, and because the whole purpose of ICCID is to identify + each card as a physical artifact irrespective of logical function, this ID + number is perfect for the job. It is never transmitted over any air + interfaces, hence no one outside of our community needs to know or care that + we use squatted ICCIDs rather than officially allocated ones. + +Programming model for FCSIM1 +============================ + +Our programming model is based on the principle of a card provisioning database. +If you are going to get a small batch of FCSIM1 cards from us, or if you are +going to order a larger batch directly from Grcard, but you wish to follow the +same model as ours, as the first step toward programming, you will need to +generate your own card provisioning database. This database is an ASCII text +file with one line per card, and it resides in this standardized location: + +/opt/freecalypso/sim-data/fcsim1-prov-db + +Each line in this card provisioning database takes the following form: + +ICCID=89015570000000xxxxx IMSI=xxxxxxxxxxxxxxx ACC=xxxx Ki=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +While there is nothing to stop you from constructing this card provisioning +database manually in vi, the intent is that it will be generated by our +fcsim1-mkprov utility. This utility takes a starting ICCID, a starting IMSI +and the number of card entries to generate - and it generates the requested +number of database entries with incrementing ICCIDs, incrementing IMSIs, ACC +circling through the standard bit-shifting range from 0001 to 0200, and random +Ki secret keys. (The source of random keys is currently very simple: each Ki +is read directly from /dev/urandom, or from /dev/random if desired. Suggestions +for improvement are welcome.) fcsim1-mkprov emits its output to stdout, hence +it will typically need to be run with output append-redirected ('>>') to +/opt/freecalypso/sim-data/fcsim1-prov-db. + +Once the desired provisioning data have been captured in fcsim1-prov-db, this +database can be used in two ways: + +1) There will be an fcsim1-program utility for programming individual FCSIM1 + cards. This program will be a wrapper around fc-simtool: it will take an + ICCID on the command line (you will need to read and enter the number printed + on the plastic), it will retrieve the right record from fcsim1-prov-db, it + will construct a one-time (under /tmp, automatically deleted when done) + command script for fc-simtool based on the per-card data, and it will exec + fc-simtool with this command script. + +2) Once I (Mother Mychaela) climb the learning curve for getting Osmocom CNI + software up and running on a server, I will produce appropriate tools for + extracting IMSI and Ki from fcsim1-prov-db and turning them into whatever + format is needed for import into OsmoHLR subscriber database.