FreeCalypso > hg > fc-pcsc-tools

comparison doc/Admin-write-commands @ 224:80fc2b2f83c2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: admin programming articles added
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 10 Mar 2021 06:56:32 +0000
parents
children
comparison
equal deleted inserted replaced
223:74d4246d6c45 224:80fc2b2f83c2
1 Using fc-simtool for admin-level SIM card programming
2 =====================================================
3
4 fc-simtool is a layered tool, and its repertoire of available commands needs to
5 be viewed as consisting of 3 primary conceptual layers:
6
7 * At the bottom layer there are low-level commands that correspond directly to
8 GSM 11.11 protocol operations of first SELECTing files, then reading or
9 writing those files in whole or in part with READ BINARY, READ RECORD, UPDATE
10 BINARY and UPDATE RECORD protocol commands. This functional layer of
11 fc-simtool is documented in the Low-level-commands article.
12
13 * As the next layer up, we implement higher-level commands for ordinary users
14 without special admin privileges. SIM card specs GSM 11.11 and 3GPP TS 51.011
15 define many files such as phonebooks which ordinary users can both read and
16 write, and we provide high-level user-friendly commands for reading and
17 writing many of these files. The same specs also define many files which
18 ordinary users can read but not write, giving ICCID, IMSI, SST and so forth -
19 we provide high-level user-friendly commands for reading many of these files.
20 These commands are documented in the User-oriented-commands article, plus a
21 few additional ones in the PLMN-list-commands article.
22
23 * As the most advanced layer, we implement some high-level write commands that
24 can only work if you have admin-level access to your card, i.e., if you have
25 authenticated with the appropriate ADM key in a card-vendor-dependent manner.
26 The present article describes these advanced commands.
27
28 Authentication with ADM credentials
29 ===================================
30
31 Before you can write to any of the admin-write-only files, you first need to
32 authenticate with the right credentials. The commands for doing so are card-
33 vendor-dependent, but most cards implement a non-standard extension to the
34 standard VERIFY CHV command, presenting various kinds of ADM keys instead of
35 basic PIN1 or PIN2. fc-simtool verify-ext and verify-chv commands provide
36 access to these extended forms of VERIFY CHV in our command shell environment;
37 they are defined as follows:
38
39 verify-ext P2 XXXXXXXX
40 verify-hex P2 xxxxxxxxxxxxxxxx
41
42 The first argument to both commands is the value to be put into the P2 field of
43 the VERIFY CHV command APDU; numbers are interpreted as decimal by default
44 unless preceded with 0x for hex. verify-ext should be used if the key material
45 takes the same ASCII-decimal form as is used for standard PINs and PUKs, whereas
46 verify-hex allows arbitrary 64-bit keys to be given as a hex string of 8 bytes.
47
48 If your card is FCSIM1 or any other branded variant of GrcardSIM2 and the
49 default ADM11 (aka SUPER ADM) key hasn't been changed, you need to authenticate
50 as follows:
51
52 select MF
53 verify-ext 11 88888888
54
55 (select MF can be omitted if verify-ext 11 is the very first command in your
56 fc-simtool session.)
57
58 If your card is sysmoISIM-SJA2, you need to look up the right ADM1 key in the
59 key material email from Sysmocom webshop, and then authenticate as follows:
60
61 verify-ext 10 XXXXXXXX
62
63 If your card is sysmoUSIM-SJS1, you need to use the following special command,
64 and it must be the very first command in your fc-simtool session:
65
66 verify-sjs1-adm1 XXXXXXXX
67
68 Actual admin file writes
69 ========================
70
71 The few specific admin write commands implemented in fc-simtool are listed
72 below. However, please keep the following points in mind:
73
74 * If there is no specific high-level write command for the file you are
75 interested in, you can always use low-level select, update-bin and update-rec
76 commands to write any file - see the Low-level-commands article.
77
78 * Some files that need to be written as part of provision-time programming
79 procedures are actually writable by ordinary users, hence those write commands
80 are documented in the User-oriented-commands article. This situation applies
81 to EF_MSISDN and EF_SMSP. Commands for writing EF_PLMNsel and EF_FPLMN (also
82 writable by ordinary users) are documented in the PLMN-list-commands article.
83
84 Finally, here are the dedicated commands for writing a few specific
85 admin-write-only files:
86
87 write-acc XXXX
88
89 This command writes EF_ACC. The argument must be a 4-digit hexadecimal number.
90
91 write-iccid full_digits
92
93 This command programs EF_ICCID with whatever string of digits you specify. This
94 fc-simtool command provides mechanism rather than policy, hence it does not
95 enforce any particular number of digits (the record is padded with 'F' hex
96 digits per the spec if the number string is shorter than 20 digits), nor is the
97 number required to end in a matching Luhn check digit.
98
99 write-iccid-sh18 shorthand-digits
100
101 This command provides a higher-level user-friendly way to write ICCIDs of the
102 most commonly used 18+1 format, meaning 18 content digits plus Luhn check digit.
103 The shorthand entry form allows any number of 0 digits in the middle to be
104 replaced with a single dash - for example, the following command:
105
106 write-iccid-sh18 8988211-3
107
108 will set ICCID to:
109
110 8988211000000000037
111
112 As the first step, the shorthand entry is expanded to 18 digits, and as the
113 next step, the correct Luhn check digit is appended.
114
115 write-iccid-sh19 shorthand-digits
116
117 This command is similar to write-iccid-sh18, but it takes shorthand ICCIDs that
118 already include the Luhn check digit at the end. The previous example ICCID
119 would be entered as:
120
121 write-iccid-sh19 8988211-37
122
123 After the shorthand entry is expanded to 19 digits, the Luhn formula is checked,
124 and mismatching entries are rejected. This command is intended for use cases
125 where the ICCID to be programmed is printed on the plastic and needs to be
126 entered as-is, but the pain of entering all those zeros in the middle is
127 eliminated.
128
129 write-imsi full_digits
130
131 This command programs EF_IMSI with any arbitrary IMSI, which by spec may be 15
132 digits or shorter. 15-digit IMSIs are most common, but shorter ones are allowed
133 too, and this fc-simtool command provides mechanism rather than policy.
134
135 write-imsi-sh shorthand-digits
136
137 This command programs EF_IMSI with a 15-digit IMSI that can be entered in
138 shorthand. For example, the following command:
139
140 write-imsi-sh 90170-001
141
142 is equivalent to:
143
144 write-imsi 901700000000001
145
146 write-spn display_cond name
147
148 The display condition code is given in hex, the name field is given in the
149 FreeCalypso standard ASCII representation for GSM7 strings defined in the
150 SIM-data-formats document in the freecalypso-docs repository.
151
152 write-sst sst-file
153
154 This command writes the SIM Service Table (SST) from the specified data file.
155 The data file needs to contain service numbers separated by white space, either
156 one per line or multiple numbers per line; '#' character introduces comments
157 which continue to the end of the line. If a service number is given with '^'
158 suffix, that service is indicated as allocated but not activated.
159
160 pnn-write rec long-name [short-name]
161
162 This command writes a single EF_PNN record. The record index and the long name
163 must always be specified, the short name is optional. Network name fields are
164 given in the FreeCalypso standard ASCII representation for GSM7 strings.
165
166 pnn-erase start-rec [end-rec]
167
168 This command erases (fills with all FF bytes) either a single record or a range
169 of records in EF_PNN. If only one argument is specified, only one record is
170 erased. To erase a range of records, the second argument may be either a number
171 or the "end" keyword. Use 'pnn-erase 1 end' to erase the entire EF_PNN.
172
173 opl-write rec mcc-mnc start-lac end-lac pnn-index
174
175 This command writes a single EF_OPL record. rec is the EF_OPL record index to
176 write into, the remaining arguments give the content of the record exactly per
177 3GPP TS 51.011.
178
179 opl-erase start-rec [end-rec]
180
181 This command erases (fills with all FF bytes) either a single record or a range
182 of records in EF_OPL. If only one argument is specified, only one record is
183 erased. To erase a range of records, the second argument may be either a number
184 or the "end" keyword. Use 'opl-erase 1 end' to erase the entire EF_OPL.