FreeCalypso > hg > fc-sim-tools
view doc/GrcardSIM2-programming @ 83:3055d5c9e7a3
fc-simtool update-rec* commands: check curfile_record_len
and error out if it is not set
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 11 Apr 2021 02:38:31 +0000 |
parents | 8c23d2a9c013 |
children |
line wrap: on
line source
The card model which we call GrcardSIM2 is one of the many smart card models made and sold by Grcard in China. Our FreeCalypso-branded version of this card is called FCSIM1 (batch of 200 cards made in 2021-04), but the same card model was previously sold by Sysmocom as sysmoSIM-GR2, going back to some time around 2013. Our fc-simtool supports full programming of these cards: you can take a card whose initial state is "blank" or unprogrammed, or a card with some previous programming, and you can program it to your own liking using fc-simtool. For the purpose of programming this particular card model (as opposed to USIM/ISIM cards), our fc-simtool offers the following advantages over well-known competitor pySim-prog: * These cards support all 3 versions of COMP128 algorithm (v1, v2 and v3), but pySim-prog unconditionally selects COMP128v1. Our grcard2-set-comp128 command allows any of the 3 algorithm versions to be selected, and in the Mother's opinion it makes no sense to select any version other than COMP128v3 for new GSM network deployments. * These cards have a fairly sophisticated security model with two different ADM access levels: see GrcardSIM2-security-model article for the details. pySim-prog support for this security model is fundamentally broken: it authenticates with ADM11 as required for writing Ki, but it always sends the default ADM11 key, i.e., pySim-prog -a or -A options have no effect on the key that actually matters. Instead of supporting changeable ADM11 keys, pySim-prog needlessly resets ADM5, even though they could have left it alone (ADM11 by itself is sufficient for writing to all files), and the effect of -a or -A options is only on this unnecessary ADM5 setting. * Further on the security model, GrcardSIM2 cards allow admins to reset PIN1/PIN2/PUK1/PUK2 secret codes after authenticating with ADM5 or ADM11 - this mechanism is the only way to reset PUK1 and PUK2 if the previous codes are unknown. pySim-prog provides no support for setting PIN/PUK codes. * fc-simtool allows every single file in the card file system to be written as you like. Absolutely any file can be read and written in raw hex, and we also provide high-level read and write commands for most files. In contrast, pySim-prog implements a rigid and inflexible programming model, writing only a few files and only in one very limited way. Using fc-simtool to program GrcardSIM2 cards ============================================ To begin with, you must know the ADM11 (aka SUPER ADM) secret code for your card. If you got your card directly from Grcard factory or from a reseller such as FreeCalypso who leaves this default ADM11 key unchanged, your ADM11 key is ASCII-decimal 88888888, and you need to authenticate as follows: verify-ext 11 88888888 If the previous owner of your card changed this ADM11 key to something else, or if you had Grcard factory program cards for you with different ADM keys, then you need to know what the ADM11 secret is - if it is lost, there is no recovery, and you have to get a new card. If you have a non-default ADM11 key, you need to enter it using either verify-ext 11 or verify-hex 11 command, depending on whether the key falls into the restricted ASCII-decimal subset or not. In any case, this verify-ext 11 or verify-hex 11 command should ideally be the first command in your fc-simtool session; if it is not the first command in the session, then it needs to be preceded with select MF. Once you have authenticated with ADM11, you are ready to run your programming scripts. Because fc-simtool is not a "one size fits all" tool like pySim-prog, but rather a fully generalized command shell that allows you to poke at whatever files you like in whatever order and manner you like, practical SIM programming should be done with customized command scripts. Furthermore, we recommend that you split your custom programming scripts into two levels: 1) You should have one command script which you install under /opt/freecalypso/sim-scripts that programs SIMs appropriately for your GSM network. This script should be the same for all of your cards, programming SST, PLMN selection (PLMNsel and FPLMN) and branding files SPN, PNN and OPL. See our fcsim1-defprog script for a starting point. 2) Per-card settings like ICCID, IMSI, ACC and Ki can only be set either manually (OK for one or two cards, but doesn't scale), or by way of custom front end or wrapper programs that generate and execute one-time fc-simtool command scripts. See FCSIM1-programming article for the solution which we have implemented. Please refer to Admin-write-commands, GrcardSIM2-WEKI-file and GrcardSIM2-security-model articles for commands to be used in crafting your custom programming scripts.