# HG changeset patch # User Mychaela Falconia # Date 1617956371 0 # Node ID 711f1641b19c23fa16dfb6fb362ae92563c9f434 # Parent 2a24e94400e8dbf28f6ee2515277b62c0f3334be doc/FCSIM1-programming: update for fcsim1-program diff -r 2a24e94400e8 -r 711f1641b19c doc/FCSIM1-programming --- a/doc/FCSIM1-programming Fri Apr 09 03:25:40 2021 +0000 +++ b/doc/FCSIM1-programming Fri Apr 09 08:19:31 2021 +0000 @@ -30,7 +30,7 @@ * 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 + (2FF) piece. The rationale is that we need to be 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 @@ -65,18 +65,149 @@ 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: +fcsim1-mkprov usage details +=========================== + +The canonical way to run fcsim1-mkprov is as follows: + +fcsim1-mkprov -n num start-iccid start-imsi >> /opt/freecalypso/sim-data/fcsim1-prov-db + +-n option specifies the number of card entries to generate; if this option is +omitted, only one card entry will be generated. The starting ICCID needs to be +given in 18-digit form _without_ the Luhn check digit - fcsim1-mkprov will +increment this ICCID for the number of card entries to be generated (we will +always supply consecutively-numbered cards to anyone buying a small batch from +us), and it will generate the correct Luhn check digit for each ICCID. However, +you can use our FC SIM tools shorthand notation for the starting ICCID: for +example, if you enter 8901557-100, that entry will be automatically expanded to +18-digit 890155700000000100. IMSIs are expected to always be 15 digits long, +but the same shorthand notation can be used here too. + +The following additional options are accepted: + +-a [0-9] + + The argument for this option is a single digit from '0' to '9'; the + effect is to set ACC for the first card entry to be generated: -a 0 + corresponds to ACC=0001, -a 1 corresponds to ACC=0002, and so forth + through -a 9 corresponding to ACC=0200. When many card entries are + generated (-n option), subsequent card ACCs will automatically increment + and circle, i.e., bit-shift to the left until ACC=0200 is reached, then + circle back to ACC=0001 and so on. + +-m start-msisdn + + By default (in the absence of -m option) each fcsim1-prov-db record + contains only ICCID, IMSI, ACC and Ki as shown above. Running + fcsim1-mkprov with -m start-msisdn causes incrementing MSISDN numbers + to be generated as well, appearing as an extra MSISDN=xxx field in each + fcsim1-prov-db record. + +-r /dev/random + + Read random bytes for Ki from /dev/random instead of /dev/urandom. + +Programming cards with fcsim1-program and fc-simtool +==================================================== + +Once the desired provisioning data have been captured in fcsim1-prov-db, the +following procedure is envisioned for actual card programming: + +1) You pick the card to be programmed from the unprogrammed bin; + +2) While holding the card in your hand and looking at the ICCID printed on the + plastic, you enter a command line similar to this example: + + fcsim1-program -c fcsim1-defprog 8901557-0008 | fc-simtool -p0 + + Type in the needed command line, but don't press Enter yet... + +3) Insert the card into your reader stand (assuming that you will be using a + stand-type card programming station such as HID Omnikey 3121), at which + point the ICCID printed on the card is no longer visible. + +4) Press Enter to execute the command you typed in step 2 above. + +Now the explanation: fcsim1-program is a utility that generates per-card +programming command scripts to be fed to fc-simtool. It requires the ICCID +(read from the plastic with human eyeballs) to be entered on the command line, +and this time the ICCID being entered needs to include the Luhn check digit: +after all, you are simply entering the number from the plastic, and the printed +ICCID does include the Luhn check digit. Our FC SIM tools shorthand notation +for skipping the long string of zeros in the middle still works though! -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. +After verifying the Luhn check digit, fcsim1-program will look up the entered +ICCID in fcsim1-prov-db (if there is no entry for this ICCID, it is an error), +and it will retrieve all per-card provisioning parameters from there. The +programming command script generated by fcsim1-program (intended to be piped +directly into fc-simtool) has the following structure: + +verify-ext 11 88888888 # ADM11 authentication +exec fcsim1-defprog # common command script specified with -c +write-iccid XXXX # programming per-card ICCID +write-imsi XXXX # programming per-card IMSI +write-acc XXXX # programming per-card ACC +grcard2-set-ki XXXX # programming per-card Ki + +If the card record in fcsim1-prov-db includes the optional MSISDN= field +(generated with fcsim1-mkprov -m option), the script generated by fcsim1-program +will also include a pb-update-imm command to write the MSISDN record. + +Common command scripts: only ICCID, IMSI, ACC, Ki and optional MSISDN are +expected to be different for each individual card, whereas all other SIM card +programming is expected to be the same for all cards in a given fiefdom. +Therefore, each tribal chieftain who is going to run his or her own GSM network +will need to create their own custom common command script based on +fcsim1-defprog: for example, for our own Themyscira Wireless operation we have +our own private themwi-prog script that is based on fcsim1-defprog and takes +its place. + +Philosophy regarding ICCID +========================== + +Our workflow is set up so that whenever you program or reprogram a card, you +have to read the ICCID from the plastic with your eyeballs and enter it on the +command line. Our fcsim1-program | fc-simtool pipeline programs the EF_ICCID +record, but nowhere in our current workflow do we read it back for further +database lookups. -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. +We have considered an alternative approach of programming EF_ICCID (to match +the number printed on the plastic) on all of our FCSIM1 cards at FreeCalypso HQ, +and then expecting downstream card users to run tools that read EF_ICCID from +the card. However, this approach has been rejected because unlike +sysmoISIM-SJA2, GrcardSIM2 cards allow EF_ICCID to be freely rewritten like any +other admin-write file, thus even if we program it correctly at FreeCalypso HQ, +it is always possible for EF_ICCID to become messed up further downstream. But +the laser marking of ICCID on the plastic is truly immutable, hence the most +reliable workflow for unconditionally bringing each card to the desired correct +state irrespective of prior programming state is to read the ICCID from the +plastic with human eyeballs, enter it on the command line, and have the tools +unconditionally program it. + +Philosophy regarding ADM keys +============================= + +The idea is similar to the one for ICCID: let's eliminate any dependencies on +prior state of each card as much as possible. Based on this philosophy, we +currently leave the ADM11 key (SUPER ADM which supersedes ADM5 and all lower +PINs) at the factory default of 88888888, and we discourage changing it. If +someone desires the traditional security model where an operator programs SIMs +and then prevents subscribers from being able to read their Ki, then you will +have to change your ADM11 key (and ADM5 too, for good measure) to true per-card +secrets - but then you won't be able to freely rerun programming scripts without +caring about prior state. + +For those who wish to change their ADM11 key, we provide low-level +grcard2-set-super and grcard2-set-super-hex commands that do the deed, but our +higher-level fcsim1-mkprov + fcsim1-program suite does not currently have any +sensible support for secure ADM11 (or ADM5) keys. If someone desires such +functionality, we can implement it as paid feature development, but probably +not otherwise. + +OsmoHLR integration +=================== + +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.