annotate doc/Low-level-commands @ 94:285fb9555530

doc/Low-level-commands: update-* commands documented
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 17 Feb 2021 19:54:57 +0000
parents 1743802e494e
children 7412cdd505b3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 fc-simtool is a tool built from the bottom up: at the foundation there is a set
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 of low-level commands that provide raw access to the actual SIM protocol APDU
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 commands, these low-level commands can be used to do everything that the SIM
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 protocol allows, and all higher-level commands merely provide user-friendly
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 utilities for the most common particular use cases. This document describes
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 these low-level commands. Readers of this document are expected to know the
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 SIM interface protocol as defined in GSM TS 11.11 and its successor 3GPP TS
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 51.011.
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 Exploring and reading commands
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 ==============================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 atr
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 This command displays the ATR (Answer To Reset) byte string which the SIM sent
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 to the reader when it powered up.
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 select File_ID
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 This fc-simtool command sends a SELECT command to the SIM, follows up with a
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 GET RESPONSE command as expected in the T=0 protocol, and provides some human-
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 readable parsing of the most important fields in the SIM response structure.
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 If a correctly formed response was received from the SIM and this response
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 structure indicates that a record-based EF has been selected, the indicated
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 record length is saved in an internal variable used by readrec and update-rec
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 commands.
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 The file ID can be specified either in hexadecimal (exactly 4 hex digits, *no*
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 0x prefix) or as a symbolic name. fc-simtool knows the following symbolic
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 names:
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 * MF
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 * DF_GSM, DF_DCS1800 and DF_TELECOM
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 * "gsm" and "telecom" as shorthand names for DF_GSM and DF_TELECOM
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 * Some of the most classic EFs, but not all
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 Important note: regardless of whether you specify the file ID in raw hex or
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 symbolically, this low-level select command will send only one SELECT command
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 to the SIM. Per the SIM protocol, in order to successfully select an EF, you
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 have to be in the right directory first, i.e., select MF, DF_GSM or DF_TELECOM
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 as appropriate before the EF of interest. Our low-level select command does
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 NOT do this extra step on its own, you have to do it explicitly, even if you
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 use symbolic names for EFs.
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 sim-resp
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 This command displays in raw hex the content of the internal buffer that holds
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 the last response received from the SIM. This internal buffer is filled by the
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 GET RESPONSE command that follows up after SELECT or RUN GSM ALGORITHM, and by
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 the READ BINARY or READ RECORD commands, whether they are invoked directly as
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 low-level commands (select, readbin, readrec or a38) or internally as part of
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 higher-level fc-simtool commands.
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 readbin offset len
91
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
55
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
56 This fc-simtool command sends a READ BINARY command to the SIM and displays the
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
57 SIM response in raw hex, internally invoking the same function as sim-resp.
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
58 The two arguments are exactly as in the READ BINARY protocol command; each
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
59 number is interpreted as decimal by default or as hex if preceded by 0x.
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
60
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 readrec record-index [len]
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
91
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
63 This fc-simtool command sends a READ RECORD command to the SIM (absolute
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
64 addressing mode) and displays the SIM response in raw hex, internally invoking
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
65 the same function as sim-resp. The arguments are decimal or hex as in the
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
66 readbin command.
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
67
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
68 If no explicit length argument is given, readrec uses the internal variable set
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
69 by the last select operation. This one-argument form is almost always used in
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
70 practice, as the SIM will normally reject any requested length that does not
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
71 match the current EF record length.
5f3b16fd4321 doc/Low-level-commands: readbin and readrec documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 75
diff changeset
72
92
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
73 readef File_ID
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
74
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
75 This fc-simtool command provides a slightly higher-level facility for examining
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
76 the content of transparent EFs, combining select and readbin operations. The
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
77 sole File_ID argument is the same as for the low-level select command; if the
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
78 SIM response to this SELECT indicates a transparent EF (it is an error
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
79 otherwise), readef follows up with a READ BINARY command to read the entire file
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
80 (or the first 256 bytes if the file is longer) and displays the read content in
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
81 raw hex.
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
82
93
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
83 Just like with the low-level select command, there is no built-in MF/DF
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
84 selection.
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
85
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
86 savebin File_ID out-bin-file
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
87
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
88 This command selects the specified EF (just like with low-level select and
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
89 readef, you need to be in the right MF/DF directory) and saves its complete
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
90 content in a raw binary file on the UNIX host file system. This command
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
91 supports all 3 types of EF (transparent, linear fixed and cyclic) and uses the
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
92 correct READ BINARY or READ RECORD commands based on the SELECT response.
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
93 Record-based EFs are read in the order of increasing record number and are saved
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
94 in the host binary file with all records simply abutted together.
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 Writing commands
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 ================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
94
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
99 update-bin offset hexfile
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
100
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
101 This fc-simtool command reads a hex data file (an ASCII text file containing
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
102 only hex byte values and nothing else, with or without white space between
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
103 bytes, newlines treated as any other white space) and sends this byte content
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
104 to the SIM in an UPDATE BINARY command. The offset argument is the same as in
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
105 the readbin command. The length is the number of bytes read from the hex data
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
106 file.
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
107
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
108 update-bin-imm offset hex-string
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
109
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
110 This command works like update-bin, but the bytes to be written are given as a
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
111 hex string direct argument (like an immediate operand in assembly languages),
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
112 rather than via a hex data file.
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
113
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
114 update-rec record-index hexfile
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
115
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
116 This fc-simtool command reads a hex data file (just like update-bin) and sends
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
117 this byte content to the SIM in an UPDATE RECORD command, using absolute
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
118 addressing mode. The record-index argument is the same as in the readrec
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
119 command. The number of bytes in the hex data file must equal the EF record
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
120 length.
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
121
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
122 update-rec-prev hexfile
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
123
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
124 This fc-simtool command is like update-rec, but the UPDATE RECORD command sent
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
125 to the SIM uses the PREVIOUS addressing mode, and there is no record number.
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
126 This form is needed in order to write to cyclic EFs.
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 restore-file
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 GSM authentication testing
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 ==========================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 a38