FreeCalypso > hg > fc-sim-tools
view doc/Admin-write-commands @ 59:10bfdee30a68
simtool/chvext.c: missing #include <stdlib.h>
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Tue, 23 Mar 2021 05:25:12 +0000 |
parents | da6e9d0b2ee6 |
children | f4eb486aab40 |
line wrap: on
line source
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.