FreeCalypso > hg > fc-sim-tools

comparison doc/Low-level-commands @ 18:da6e9d0b2ee6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
data, doc, scripts: import from previous fc-pcsc-tools repo
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 14 Mar 2021 07:57:09 +0000
parents
children 871281cb0555
comparison
equal deleted inserted replaced
17:372ecc4aa2c4 18:da6e9d0b2ee6
1 fc-simtool is a tool built from the bottom up: at the foundation there is a set
2 of low-level commands that provide raw access to the actual SIM protocol APDU
3 commands, these low-level commands can be used to do everything that the SIM
4 protocol allows, and all higher-level commands merely provide user-friendly
5 utilities for the most common particular use cases. This document describes
6 these low-level commands. Readers of this document are expected to know the
7 SIM interface protocol as defined in GSM TS 11.11 and its successor 3GPP TS
8 51.011.
9
10 Exploring and reading commands
11 ==============================
12
13 atr
14
15 This command displays the ATR (Answer To Reset) byte string which the SIM sent
16 to the reader when it powered up.
17
18 select File_ID
19
20 This fc-simtool command sends a SELECT command to the SIM, follows up with a
21 GET RESPONSE command as expected in the T=0 protocol, and provides some human-
22 readable parsing of the most important fields in the SIM response structure.
23 If a correctly formed response was received from the SIM and this response
24 structure indicates that a record-based EF has been selected, the indicated
25 record length is saved in an internal variable used by readrec and update-rec
26 commands.
27
28 The file ID can be specified either in hexadecimal (exactly 4 hex digits, *no*
29 0x prefix) or as a symbolic name. fc-simtool knows the following symbolic
30 names:
31
32 * MF
33 * DF_GSM, DF_DCS1800 and DF_TELECOM
34 * "gsm" and "telecom" as shorthand names for DF_GSM and DF_TELECOM
35 * Some of the most classic EFs, but not all
36
37 Important note: regardless of whether you specify the file ID in raw hex or
38 symbolically, this low-level select command will send only one SELECT command
39 to the SIM. Per the SIM protocol, in order to successfully select an EF, you
40 have to be in the right directory first, i.e., select MF, DF_GSM or DF_TELECOM
41 as appropriate before the EF of interest. Our low-level select command does
42 NOT do this extra step on its own, you have to do it explicitly, even if you
43 use symbolic names for EFs.
44
45 sim-resp
46
47 This command displays in raw hex the content of the internal buffer that holds
48 the last response received from the SIM. This internal buffer is filled by the
49 GET RESPONSE command that follows up after SELECT or RUN GSM ALGORITHM, and by
50 the READ BINARY or READ RECORD commands, whether they are invoked directly as
51 low-level commands (select, readbin, readrec or a38) or internally as part of
52 higher-level fc-simtool commands.
53
54 readbin offset len
55
56 This fc-simtool command sends a READ BINARY command to the SIM and displays the
57 SIM response in raw hex, internally invoking the same function as sim-resp.
58 The two arguments are exactly as in the READ BINARY protocol command; each
59 number is interpreted as decimal by default or as hex if preceded by 0x.
60
61 readrec record-index [len]
62
63 This fc-simtool command sends a READ RECORD command to the SIM (absolute
64 addressing mode) and displays the SIM response in raw hex, internally invoking
65 the same function as sim-resp. The arguments are decimal or hex as in the
66 readbin command.
67
68 If no explicit length argument is given, readrec uses the internal variable set
69 by the last select operation. This one-argument form is almost always used in
70 practice, as the SIM will normally reject any requested length that does not
71 match the current EF record length.
72
73 readef File_ID
74
75 This fc-simtool command provides a slightly higher-level facility for examining
76 the content of EFs, combining select and readbin or readrec operations. The
77 sole File_ID argument is the same as for the low-level select command; the SIM
78 response to SELECT is then parsed to decide what to do next. Transparent EFs
79 are read using as many READ BINARY commands as necessary (up to 256 bytes can
80 be read in one APDU exchange) and displayed as a continuous hex dump. For
81 record-based EFs (linear fixed and cyclic), readef reads and separately
82 hex-dumps every record.
83
84 Just like with the low-level select command, there is no built-in MF/DF
85 selection.
86
87 savebin File_ID out-bin-file
88
89 This command selects the specified EF (just like with low-level select and
90 readef, you need to be in the right MF/DF directory) and saves its complete
91 content in a raw binary file on the UNIX host file system. This command
92 supports all 3 types of EF (transparent, linear fixed and cyclic) and uses the
93 correct READ BINARY or READ RECORD commands based on the SELECT response.
94 Record-based EFs are read in the order of increasing record number and are saved
95 in the host binary file with all records simply abutted together.
96
97 Writing commands
98 ================
99
100 update-bin offset hexfile
101
102 This fc-simtool command reads a hex data file (an ASCII text file containing
103 only hex byte values and nothing else, with or without white space between
104 bytes, newlines treated as any other white space) and sends this byte content
105 to the SIM in an UPDATE BINARY command. The offset argument is the same as in
106 the readbin command. The length is the number of bytes read from the hex data
107 file.
108
109 update-bin-imm offset hex-string
110
111 This command works like update-bin, but the bytes to be written are given as a
112 hex string direct argument (like an immediate operand in assembly languages),
113 rather than via a hex data file.
114
115 update-rec record-index hexfile
116
117 This fc-simtool command reads a hex data file (just like update-bin) and sends
118 this byte content to the SIM in an UPDATE RECORD command, using either absolute
119 or PREVIOUS addressing mode. The record-index argument is the same as in the
120 readrec command for the absolute addressing mode, or 'prev' keyword to use the
121 PREVIOUS addressing mode for writing to cyclic EFs. The number of bytes in the
122 hex data file must equal the EF record length.
123
124 update-rec-imm record-index hex-string
125
126 This command works like update-rec, but the bytes to be written are given as a
127 hex string direct argument (like an immediate operand in assembly languages),
128 rather than via a hex data file.
129
130 update-rec-fill record-index fill-byte
131
132 This fc-simtool command sends an UPDATE RECORD command to the SIM with payload
133 equal to the specified fill byte, replicated to the record length. The fill
134 byte argument is always interpreted as hexadecimal.
135
136 restore-file File_ID host-bin-file
137
138 This command restores a binary backup previously made with savebin back to the
139 SIM, or writes new bits into the EF if you can construct the necessary binary
140 image with tools like xxd. The arguments are the same as for the savebin
141 command. This command supports all 3 types of EF (transparent, linear fixed
142 and cyclic) and uses the correct UPDATE BINARY or UPDATE RECORD commands based
143 on the SELECT response. Cyclic files are restored by writing every record in
144 the reverse order from the last index to the first.
145
146 erase-file File_ID [fill-byte]
147
148 This command erases the specified EF by overwriting its content with the
149 specified fill byte, which defaults to 0xFF if the second argument is omitted.
150 All 3 EF types (transparent, linear fixed and cyclic) are supported: for
151 transparent EFs fc-simtool issues as many UPDATE BINARY commands as needed to
152 overwrite the whole file, whereas for record-based EFs every record is
153 overwritten with UPDATE RECORD.
154
155 INVALIDATE and REHABILITATE
156 ===========================
157
158 cur-ef-inval will send an INVALIDATE command to the SIM; cur-ef-rehab will send
159 a REHABILITATE command. The naming of these low-level fc-simtool commands
160 reflects the fact that you have to manually select the EF of interest first.
161
162 GSM authentication testing
163 ==========================
164
165 a38 RAND
166
167 This fc-simtool command exercises the SIM card's RUN GSM ALGORITHM command.
168 The user-specified RAND value (a hex string of 16 bytes) is sent to the SIM,
169 and the SIM response is parsed to display SRES and Kc.
170
171 Per SIM specs GSM TS 11.11 and 3GPP TS 51.011, RUN GSM ALGORITHM can only be
172 executed when DF_GSM is selected. fc-simtool a38 command does NOT include a
173 built-in SELECT of DF_GSM, hence you need to manually issue 'select DF_GSM'
174 first.
175
176 This a38 command can be used to verify if the SIM card's Ki and A38 algorithm
177 match what you expect them to be. To perform this test, issue an a38 command
178 to the SIM with some made-up RAND and note the SRES and Kc response. Then use
179 the osmo-auc-gen utility from Osmocom to run the expected algorithm with the
180 expected Ki (and the expected OPc if MILENAGE is used) and the same RAND, and
181 see if SRES and Kc match.
182
183 Exploring proprietary APDUs
184 ===========================
185
186 If the SIM you are working with is known or suspected to implement some
187 non-standard or proprietary APDUs for which there is no explicit support in
188 fc-simtool, you can use this low-level debug command to send arbitrary APDUs:
189
190 apdu "xx xx xx xx xx ..."
191
192 The sole argument is a raw string of bytes (quotes are needed if there are
193 spaces between bytes), and the APDU needs to be given exactly as it is sent in
194 the T=0 protocol: 5 bytes of header (including the length byte) followed by
195 data bytes, if any. After executing the APDU exchange, the apdu command simply
196 prints the SW response code from the SIM.