FreeCalypso > hg > fc-pcsc-tools

annotate doc/Low-level-commands @ 89:629be330f92b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/User-oriented-commands: pb-restore documented
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 17 Feb 2021 17:39:26 +0000
parents f661ad7eb126
children 5f3b16fd4321
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
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 readrec record-index [len]
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 readef
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 savebin
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 Writing commands
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 ================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 update-bin
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 update-bin-imm
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 update-rec
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 restore-file
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 GSM authentication testing
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 ==========================
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71
f661ad7eb126 doc/Low-level-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 a38