FreeCalypso > hg > fc-pcsc-tools

annotate doc/Low-level-commands @ 91:5f3b16fd4321

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Low-level-commands: readbin and readrec documented
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 17 Feb 2021 19:04:00 +0000
parents f661ad7eb126
children 9c3155221b0e
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
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 readef
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 savebin
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 Writing commands
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 ================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 update-bin
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 update-bin-imm
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 update-rec
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 restore-file
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 GSM authentication testing
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 ==========================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 a38