FreeCalypso > hg > fc-pcsc-tools

annotate doc/Low-level-commands @ 93:1743802e494e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Low-level-commands: savebin command documented
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 17 Feb 2021 19:35:56 +0000
parents 9c3155221b0e
children 285fb9555530
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
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 update-bin
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 update-bin-imm
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 update-rec
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 restore-file
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 GSM authentication testing
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 ==========================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 a38