FreeCalypso > hg > fc-pcsc-tools

annotate doc/Low-level-commands @ 214:8b1eecb56cb5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
simtool code: select_ef_pnn() factored out
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 07 Mar 2021 08:07:07 +0000
parents fc0ab2b0c56e
children
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
174
cc6a4b48dc2a doc/Low-level-commands: readef extended
Mychaela Falconia <falcon@freecalypso.org>
parents: 128
diff changeset
76 the content of EFs, combining select and readbin or readrec operations. The
cc6a4b48dc2a doc/Low-level-commands: readef extended
Mychaela Falconia <falcon@freecalypso.org>
parents: 128
diff changeset
77 sole File_ID argument is the same as for the low-level select command; the SIM
cc6a4b48dc2a doc/Low-level-commands: readef extended
Mychaela Falconia <falcon@freecalypso.org>
parents: 128
diff changeset
78 response to SELECT is then parsed to decide what to do next. Transparent EFs
cc6a4b48dc2a doc/Low-level-commands: readef extended
Mychaela Falconia <falcon@freecalypso.org>
parents: 128
diff changeset
79 are read using as many READ BINARY commands as necessary (up to 256 bytes can
cc6a4b48dc2a doc/Low-level-commands: readef extended
Mychaela Falconia <falcon@freecalypso.org>
parents: 128
diff changeset
80 be read in one APDU exchange) and displayed as a continuous hex dump. For
cc6a4b48dc2a doc/Low-level-commands: readef extended
Mychaela Falconia <falcon@freecalypso.org>
parents: 128
diff changeset
81 record-based EFs (linear fixed and cyclic), readef reads and separately
cc6a4b48dc2a doc/Low-level-commands: readef extended
Mychaela Falconia <falcon@freecalypso.org>
parents: 128
diff changeset
82 hex-dumps every record.
92
9c3155221b0e doc/Low-level-commands: readef command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 91
diff changeset
83
93
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
84 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
85 selection.
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
86
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
87 savebin File_ID out-bin-file
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
88
1743802e494e doc/Low-level-commands: savebin command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 92
diff changeset
89 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
90 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
91 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
92 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
93 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
94 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
95 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
96
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 Writing commands
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 ================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99
94
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
100 update-bin offset hexfile
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
101
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
102 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
103 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
104 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
105 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
106 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
107 file.
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
108
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
109 update-bin-imm offset hex-string
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
110
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
111 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
112 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
113 rather than via a hex data file.
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
114
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
115 update-rec record-index hexfile
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
116
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
117 This fc-simtool command reads a hex data file (just like update-bin) and sends
205
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
118 this byte content to the SIM in an UPDATE RECORD command, using either absolute
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
119 or PREVIOUS addressing mode. The record-index argument is the same as in the
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
120 readrec command for the absolute addressing mode, or 'prev' keyword to use the
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
121 PREVIOUS addressing mode for writing to cyclic EFs. The number of bytes in the
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
122 hex data file must equal the EF record length.
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
123
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
124 update-rec-imm record-index hex-string
94
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
125
205
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
126 This command works like update-rec, but the bytes to be written are given as a
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
127 hex string direct argument (like an immediate operand in assembly languages),
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
128 rather than via a hex data file.
94
285fb9555530 doc/Low-level-commands: update-* commands documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 93
diff changeset
129
205
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
130 update-rec-fill record-index fill-byte
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
131
fc82f0464480 doc/Low-level-commands: update for update-rec-*
Mychaela Falconia <falcon@freecalypso.org>
parents: 194
diff changeset
132 This fc-simtool command sends an UPDATE RECORD command to the SIM with payload
207
fc0ab2b0c56e doc/Low-level-commands: fill byte argument is always hex
Mychaela Falconia <falcon@freecalypso.org>
parents: 205
diff changeset
133 equal to the specified fill byte, replicated to the record length. The fill
fc0ab2b0c56e doc/Low-level-commands: fill byte argument is always hex
Mychaela Falconia <falcon@freecalypso.org>
parents: 205
diff changeset
134 byte argument is always interpreted as hexadecimal.
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135
95
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
136 restore-file File_ID host-bin-file
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
137
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
138 This command restores a binary backup previously made with savebin back to the
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
139 SIM, or writes new bits into the EF if you can construct the necessary binary
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
140 image with tools like xxd. The arguments are the same as for the savebin
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
141 command. This command supports all 3 types of EF (transparent, linear fixed
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
142 and cyclic) and uses the correct UPDATE BINARY or UPDATE RECORD commands based
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
143 on the SELECT response. Cyclic files are restored by writing every record in
7412cdd505b3 doc/Low-level-commands: restore-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 94
diff changeset
144 the reverse order from the last index to the first.
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145
194
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
146 erase-file File_ID [fill-byte]
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
147
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
148 This command erases the specified EF by overwriting its content with the
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
149 specified fill byte, which defaults to 0xFF if the second argument is omitted.
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
150 All 3 EF types (transparent, linear fixed and cyclic) are supported: for
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
151 transparent EFs fc-simtool issues as many UPDATE BINARY commands as needed to
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
152 overwrite the whole file, whereas for record-based EFs every record is
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
153 overwritten with UPDATE RECORD.
a5fee308b699 doc/Low-level-commands: erase-file documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 174
diff changeset
154
127
08ba6a5d8a3f doc/Low-level-commands: INVALIDATE and REHABILITATE documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
155 INVALIDATE and REHABILITATE
08ba6a5d8a3f doc/Low-level-commands: INVALIDATE and REHABILITATE documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
156 ===========================
08ba6a5d8a3f doc/Low-level-commands: INVALIDATE and REHABILITATE documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
157
08ba6a5d8a3f doc/Low-level-commands: INVALIDATE and REHABILITATE documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
158 cur-ef-inval will send an INVALIDATE command to the SIM; cur-ef-rehab will send
08ba6a5d8a3f doc/Low-level-commands: INVALIDATE and REHABILITATE documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
159 a REHABILITATE command. The naming of these low-level fc-simtool commands
08ba6a5d8a3f doc/Low-level-commands: INVALIDATE and REHABILITATE documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
160 reflects the fact that you have to manually select the EF of interest first.
08ba6a5d8a3f doc/Low-level-commands: INVALIDATE and REHABILITATE documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 96
diff changeset
161
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 GSM authentication testing
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163 ==========================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164
96
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
165 a38 RAND
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
166
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
167 This fc-simtool command exercises the SIM card's RUN GSM ALGORITHM command.
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
168 The user-specified RAND value (a hex string of 16 bytes) is sent to the SIM,
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
169 and the SIM response is parsed to display SRES and Kc.
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
170
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
171 Per SIM specs GSM TS 11.11 and 3GPP TS 51.011, RUN GSM ALGORITHM can only be
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
172 executed when DF_GSM is selected. fc-simtool a38 command does NOT include a
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
173 built-in SELECT of DF_GSM, hence you need to manually issue 'select DF_GSM'
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
174 first.
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
175
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
176 This a38 command can be used to verify if the SIM card's Ki and A38 algorithm
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
177 match what you expect them to be. To perform this test, issue an a38 command
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
178 to the SIM with some made-up RAND and note the SRES and Kc response. Then use
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
179 the osmo-auc-gen utility from Osmocom to run the expected algorithm with the
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
180 expected Ki (and the expected OPc if MILENAGE is used) and the same RAND, and
3bce899bcf78 doc/Low-level-commands: a38 command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 95
diff changeset
181 see if SRES and Kc match.
128
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
182
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
183 Exploring proprietary APDUs
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
184 ===========================
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
185
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
186 If the SIM you are working with is known or suspected to implement some
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
187 non-standard or proprietary APDUs for which there is no explicit support in
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
188 fc-simtool, you can use this low-level debug command to send arbitrary APDUs:
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
189
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
190 apdu "xx xx xx xx xx ..."
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
191
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
192 The sole argument is a raw string of bytes (quotes are needed if there are
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
193 spaces between bytes), and the APDU needs to be given exactly as it is sent in
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
194 the T=0 protocol: 5 bytes of header (including the length byte) followed by
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
195 data bytes, if any. After executing the APDU exchange, the apdu command simply
01aed8d0685a doc/Low-level-commands: raw apdu command documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 127
diff changeset
196 prints the SW response code from the SIM.