# HG changeset patch # User Mychaela Falconia # Date 1615359392 0 # Node ID 80fc2b2f83c253dbfb38265c768e6111b01e7532 # Parent 74d4246d6c455fdab852ff1313f3b7d01d6a52fa doc: admin programming articles added diff -r 74d4246d6c45 -r 80fc2b2f83c2 doc/Admin-write-commands --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Admin-write-commands Wed Mar 10 06:56:32 2021 +0000 @@ -0,0 +1,184 @@ +Using fc-simtool for admin-level SIM card programming +===================================================== + +fc-simtool is a layered tool, and its repertoire of available commands needs to +be viewed as consisting of 3 primary conceptual layers: + +* At the bottom layer there are low-level commands that correspond directly to + GSM 11.11 protocol operations of first SELECTing files, then reading or + writing those files in whole or in part with READ BINARY, READ RECORD, UPDATE + BINARY and UPDATE RECORD protocol commands. This functional layer of + fc-simtool is documented in the Low-level-commands article. + +* As the next layer up, we implement higher-level commands for ordinary users + without special admin privileges. SIM card specs GSM 11.11 and 3GPP TS 51.011 + define many files such as phonebooks which ordinary users can both read and + write, and we provide high-level user-friendly commands for reading and + writing many of these files. The same specs also define many files which + ordinary users can read but not write, giving ICCID, IMSI, SST and so forth - + we provide high-level user-friendly commands for reading many of these files. + These commands are documented in the User-oriented-commands article, plus a + few additional ones in the PLMN-list-commands article. + +* As the most advanced layer, we implement some high-level write commands that + can only work if you have admin-level access to your card, i.e., if you have + authenticated with the appropriate ADM key in a card-vendor-dependent manner. + The present article describes these advanced commands. + +Authentication with ADM credentials +=================================== + +Before you can write to any of the admin-write-only files, you first need to +authenticate with the right credentials. The commands for doing so are card- +vendor-dependent, but most cards implement a non-standard extension to the +standard VERIFY CHV command, presenting various kinds of ADM keys instead of +basic PIN1 or PIN2. fc-simtool verify-ext and verify-chv commands provide +access to these extended forms of VERIFY CHV in our command shell environment; +they are defined as follows: + +verify-ext P2 XXXXXXXX +verify-hex P2 xxxxxxxxxxxxxxxx + +The first argument to both commands is the value to be put into the P2 field of +the VERIFY CHV command APDU; numbers are interpreted as decimal by default +unless preceded with 0x for hex. verify-ext should be used if the key material +takes the same ASCII-decimal form as is used for standard PINs and PUKs, whereas +verify-hex allows arbitrary 64-bit keys to be given as a hex string of 8 bytes. + +If your card is FCSIM1 or any other branded variant of GrcardSIM2 and the +default ADM11 (aka SUPER ADM) key hasn't been changed, you need to authenticate +as follows: + +select MF +verify-ext 11 88888888 + +(select MF can be omitted if verify-ext 11 is the very first command in your + fc-simtool session.) + +If your card is sysmoISIM-SJA2, you need to look up the right ADM1 key in the +key material email from Sysmocom webshop, and then authenticate as follows: + +verify-ext 10 XXXXXXXX + +If your card is sysmoUSIM-SJS1, you need to use the following special command, +and it must be the very first command in your fc-simtool session: + +verify-sjs1-adm1 XXXXXXXX + +Actual admin file writes +======================== + +The few specific admin write commands implemented in fc-simtool are listed +below. However, please keep the following points in mind: + +* If there is no specific high-level write command for the file you are + interested in, you can always use low-level select, update-bin and update-rec + commands to write any file - see the Low-level-commands article. + +* Some files that need to be written as part of provision-time programming + procedures are actually writable by ordinary users, hence those write commands + are documented in the User-oriented-commands article. This situation applies + to EF_MSISDN and EF_SMSP. Commands for writing EF_PLMNsel and EF_FPLMN (also + writable by ordinary users) are documented in the PLMN-list-commands article. + +Finally, here are the dedicated commands for writing a few specific +admin-write-only files: + +write-acc XXXX + +This command writes EF_ACC. The argument must be a 4-digit hexadecimal number. + +write-iccid full_digits + +This command programs EF_ICCID with whatever string of digits you specify. This +fc-simtool command provides mechanism rather than policy, hence it does not +enforce any particular number of digits (the record is padded with 'F' hex +digits per the spec if the number string is shorter than 20 digits), nor is the +number required to end in a matching Luhn check digit. + +write-iccid-sh18 shorthand-digits + +This command provides a higher-level user-friendly way to write ICCIDs of the +most commonly used 18+1 format, meaning 18 content digits plus Luhn check digit. +The shorthand entry form allows any number of 0 digits in the middle to be +replaced with a single dash - for example, the following command: + +write-iccid-sh18 8988211-3 + +will set ICCID to: + +8988211000000000037 + +As the first step, the shorthand entry is expanded to 18 digits, and as the +next step, the correct Luhn check digit is appended. + +write-iccid-sh19 shorthand-digits + +This command is similar to write-iccid-sh18, but it takes shorthand ICCIDs that +already include the Luhn check digit at the end. The previous example ICCID +would be entered as: + +write-iccid-sh19 8988211-37 + +After the shorthand entry is expanded to 19 digits, the Luhn formula is checked, +and mismatching entries are rejected. This command is intended for use cases +where the ICCID to be programmed is printed on the plastic and needs to be +entered as-is, but the pain of entering all those zeros in the middle is +eliminated. + +write-imsi full_digits + +This command programs EF_IMSI with any arbitrary IMSI, which by spec may be 15 +digits or shorter. 15-digit IMSIs are most common, but shorter ones are allowed +too, and this fc-simtool command provides mechanism rather than policy. + +write-imsi-sh shorthand-digits + +This command programs EF_IMSI with a 15-digit IMSI that can be entered in +shorthand. For example, the following command: + +write-imsi-sh 90170-001 + +is equivalent to: + +write-imsi 901700000000001 + +write-spn display_cond name + +The display condition code is given in hex, the name field is given in the +FreeCalypso standard ASCII representation for GSM7 strings defined in the +SIM-data-formats document in the freecalypso-docs repository. + +write-sst sst-file + +This command writes the SIM Service Table (SST) from the specified data file. +The data file needs to contain service numbers separated by white space, either +one per line or multiple numbers per line; '#' character introduces comments +which continue to the end of the line. If a service number is given with '^' +suffix, that service is indicated as allocated but not activated. + +pnn-write rec long-name [short-name] + +This command writes a single EF_PNN record. The record index and the long name +must always be specified, the short name is optional. Network name fields are +given in the FreeCalypso standard ASCII representation for GSM7 strings. + +pnn-erase start-rec [end-rec] + +This command erases (fills with all FF bytes) either a single record or a range +of records in EF_PNN. If only one argument is specified, only one record is +erased. To erase a range of records, the second argument may be either a number +or the "end" keyword. Use 'pnn-erase 1 end' to erase the entire EF_PNN. + +opl-write rec mcc-mnc start-lac end-lac pnn-index + +This command writes a single EF_OPL record. rec is the EF_OPL record index to +write into, the remaining arguments give the content of the record exactly per +3GPP TS 51.011. + +opl-erase start-rec [end-rec] + +This command erases (fills with all FF bytes) either a single record or a range +of records in EF_OPL. If only one argument is specified, only one record is +erased. To erase a range of records, the second argument may be either a number +or the "end" keyword. Use 'opl-erase 1 end' to erase the entire EF_OPL. diff -r 74d4246d6c45 -r 80fc2b2f83c2 doc/GrcardSIM2-programming --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/GrcardSIM2-programming Wed Mar 10 06:56:32 2021 +0000 @@ -0,0 +1,82 @@ +The card model which we call GrcardSIM2 is one of the many smart card models +made and sold by Grcard in China. As of this writing (2021-03) and going back +to somewhere around 2013, it is the card model they sell when a customer asks +for a GSM-only SIM card, as opposed to USIM cards for UMTS/LTE/etc. This card +model was once resold by Sysmocom as sysmoSIM-GR2, and we are hoping to get a +batch of our own FreeCalypso-branded version which we call FCSIM1. + +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 does not support any + option of changing this key to a secure one, as would be required in any + application where traditional SIM security is desired. OTOH, pySim-prog + needlessly resets ADM5, even though they could have left it alone - ADM11 by + itself is sufficient for writing to all files. + +* 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. We plan on implementing one such front end tool once we + get our FCSIM1 card batch made. + +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.