annotate doc/User-oriented-commands @ 88:49b7e02787c1

simtool/readef.c: rm unused local variable
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 11 Apr 2021 04:01:21 +0000
parents 969f9b7863f0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 This document describes those commands and functions of fc-simtool which can be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 exercised by end users on any regular operator-issued SIM, without requiring a
20
969f9b7863f0 doc/User-oriented-commands: fc-simint is not going to be a subset tool
Mychaela Falconia <falcon@freecalypso.org>
parents: 18
diff changeset
3 special programmable SIM with admin privileges.
18
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 Understanding SIM PIN1
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 ======================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 Every standard SIM card has a secret code called PIN1; this secret code can be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 anywhere between 4 and 8 digits in length, with 4-digit PINs being most common.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 In terms of persistent non-volatile state, SIM PIN1 can be enabled or disabled.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 When SIM PIN1 is disabled, all regular functions of the card are enabled, as in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 being able to power up the phone with the SIM in it and connect to the GSM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 network with your subscriber identity, and being able to read and write SIM user
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 data content like phonebooks and stored messages - all of these functions are
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 enabled from the moment you turn on the phone with the SIM in it (or power the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 SIM up by itself in a smart card "reader" driven by fc-simtool), without the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 user ever being asked for a PIN, such that you can forget that the PIN even
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 exists - this situation in very common nowadays. But when SIM PIN1 is enabled,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 the smart chip in the SIM will not allow you access to any of the data stored
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 on the card and will not allow any GSM authentication operations until and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 unless you send the correct PIN to the SIM in the VERIFY CHV command.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 If you forgot your PIN1, the only way to reset it is to enter another secret
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 code (always 8 digits in length) called PUK1. If the SIM is made according to
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 standards, then its PUK1 is set to a random number during either physical
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 manufacturing or administrative programming of the card and then remains
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 unchangeable afterward. Therefore, in an ideal world if someone forgot their
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 PIN1 and don't have their PUK1 either, they should be able to obtain PUK1 from
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 the cellular operator who issued the SIM - but whether or not today's operators
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 will actually help such hapless users (without forcing them to get a new SIM)
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 is another question altogether. PUK1 is often printed on the big (credit-card-
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 sized) plastic piece on which SIM cards are initially delivered - but it doesn't
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 help if you originally got your SIM many ages ago and no longer have that
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 souvenir plastic piece.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 The standard protocol for communicating with SIM cards provides 5 special
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 commands that are dedicated to working with PIN1, and so does fc-simtool:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 verify-pin1 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 This command tells the SIM that you are attempting to prove knowledge
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 of PIN1, presenting a string of digits. If the PIN digits you specify match
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 the PIN1 secret code stored inside the SIM, the card unlocks access to its
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 primary functions. If the digits you send are wrong, the SIM decrements its
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 non-volatile attempt counter, giving you a total of 3 attempts (irrespective of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 card power-downs between attempts) to enter the correct PIN. If PIN1 is entered
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 incorrectly 3 times in a row, this PIN is blocked, and the only way to unblock
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 it is via PUK1.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 enable-pin1 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 This command changes the non-volatile state of the PIN1 enable/disable flag,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 such that from now on the SIM will require PIN1 to be provided on every card
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 power-up before it will allow GSM authentication and access to user data. The
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 enable-pin1 operation itself requires correct PIN1 digits to be provided.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 disable-pin1 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 This command changes the non-volatile state of the PIN1 enable/disable flag,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 such that from now on the SIM will NOT require PIN1 to be provided on every
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 card power-up, and will instead be live immediately without needing proof of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 card owner's identity. The disable-pin1 operation itself requires correct PIN1
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 digits to be provided.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 change-pin1 old-PIN new-PIN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 This command tells the SIM that you wish to change PIN1 secret code to some new
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 digits. Knowledge of the old PIN1 is required for this operation to succeed.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 unblock-pin1 PUK1-secret-code new-PIN1
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 This command tells the SIM that you are attempting to prove knowledge
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 of PUK1 and to set new PIN1. If PUK1 is given correctly, the new PIN1 will be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 set. If you enter wrong PUK1, the SIM decrements its non-volatile attempt
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 counter, giving you a total of 10 attempts (irrespective of card power-downs
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 between attempts) to enter the correct code. If PUK1 is entered incorrectly 10
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 times in a row, it is blocked and the card should be considered bricked beyond
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 recovery.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 Understanding SIM PIN2
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 ======================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 GSM standards provide support for a very rarely used feature that works in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 spirit of "parental controls": if you authenticate to the SIM with PIN2 secret
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 code (which has to be different from PIN1 for meaningful security), you can
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 edit a SIM-resident list of so-called Fixed Dialing Numbers (FDN), and then all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 standard phones that implement this feature per the spec will refuse to allow
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 ordinary users (authenticated with PIN1 or with no PIN at all) to call any
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 numbers other than those programmed in FDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 This whole "parental control" feature is totally silly and is not expected to be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 of any practical use, but the whole purpose of fc-simtool is to allow every
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 feature of SIM cards to be exercised, hence we provide the necessary support.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 The following commands work just like their PIN1 counterparts:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 verify-pin2 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 change-pin2 old-PIN new-PIN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 unblock-pin2 PUK2-secret-code new-PIN2
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 Unlike PIN1, PIN2 cannot be disabled per traditional SIM card standards.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 Getting basic info from the SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 ===============================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 The following commands are available for retrieving basic info from the SIM:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 iccid
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 This command retrieves the ICCID (Integrated Circuit Card ID) record from the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 SIM - it is a number of up to 20 digits (although 19-digit ICCIDs are most
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 common) that identifies the SIM card as a physical artifact. If your SIM is of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 the traditional operator-issued kind, as opposed to a developer-oriented
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 programmable SIM from vendors like Sysmocom who have different ideas, this ICCID
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 will usually be the SIM card ID number printed on the physical plastic, along
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 with a barcode representation of the same number.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 imsi
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 This command retrieves the IMSI (International Mobile Subscriber Identity) from
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 the SIM - it is the most fundamental ID token by which GSM phones present
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 themselves to networks, and they even use the first 5 or 6 digits of the IMSI
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 to decide which network they should try connecting to first.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 It should also be noted that if your SIM has FDN (Fixed Dialing Numbers) enabled
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 and the card implements GSM SIM specs to the letter, including the idiotic
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 parts, then you will need to issue a rehab-imsi command before you can read the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 IMSI record - see the FDN section further in this document.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 sst
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 Every SIM card is required to have an essential data record (an EF in technical
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 terms) called the SIM Service Table, or SST. This SST indicates which services
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 are allocated and activated on the given SIM. Our sst command lists all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 allocated service numbers, listing just a plain number if the service is both
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 allocated and activated (the usual case), or a number with a '^' suffix if the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 service is allocated but not activated. You will need to look in the 3GPP TS
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 51.011 spec to make sense of these service numbers.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 user-sum
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 This command displays a user-friendly summary of user-oriented services present
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 on the SIM. It reads SST to get the list of available and activated services,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143 but it considers only user-oriented ones (as opposed to SIM services dealing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 with GSM network functions or serving operators' interests rather than users'),
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 and it displays them in a user-friendly manner. For each present SIM phonebook
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 (ADN, FDN, SDN) and for the SMS store, user-sum displays the storage capacity
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 provided by the SIM (number of phonebook entries or messages), and for each of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 the various phonebooks, the allocated number of alpha tag bytes is also
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 displayed.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 The number of bytes allocated for the alpha tag in SIM phonebooks determines
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 the maximum length of the name field in each phonebook entry. These name fields
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 can be written either in GSM7 encoding (GSM 03.38 aka 3GPP 23.038) or in UCS-2;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 when GSM7 encoding is used, no SMS-style septet packing is applied - instead the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 high bit of each byte is simply cleared. Therefore, the maximum number of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 characters in a phonebook entry name field usually equals the number of bytes
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 allocated for the alpha tag on the SIM, except for names containing ASCII
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 characters [\]^ and {|}~ which get expanded to 2-character escape sequences in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 GSM7 encoding.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 uicc-dir
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163 If your SIM card functions not only as a classic GSM 11.11 SIM, but also as a
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 UICC with USIM/ISIM or other UICC-based applications, it will have a file named
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 EF_DIR in its file system, listing those applications. fc-simtool uicc-dir
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166 command dumps the content of this file in a human-readable form - but please
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 note that fc-simtool only speaks the classic GSM 11.11 protocol to the SIM, and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 not the UICC protocol. EF_DIR does not officially exist in the classic GSM SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169 spec, hence the dir command in fc-uicc-tool (speaking the UICC protocol) is the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 official way to read and dump the content of EF_DIR.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 Manipulating SIM phonebooks
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 ===========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 GSM SIM specs allow for several different phonebooks to be present on the card:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 * ADN (Abbreviated Dialing Numbers) is the main SIM phonebook. Each SIM card
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178 issuer decides how much storage space they allocate to ADN (how many records);
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 the SIM spec maximum is 254 records, and many issuers' SIMs do provide this
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180 many records or close to this limit.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 * FDN (Fixed Dialing Numbers) is the "parental control" phonebook. The FDN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183 phonebook can only be written to after authenticating with PIN2, and when it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 is enabled (enabling FDN is done by "invalidating" ADN, an operation which
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 also requires PIN2), spec-compliant phones allow only numbers in FDN to be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 called.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188 * SDN (Service Dialing Numbers) is a service-provider-controlled phonebook: it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189 can only be written if you have special admin privileges (ADM authentication
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190 method is card-vendor-dependent), and it is read-only to ordinary users.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 * MBDN (Mailbox Dialing Numbers) is a late addition to GSM SIM specs - it is a
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 special phonebook that stores the number for Voice Mail and other related
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 esoteric services.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 * MSISDN is a phonebook-like file that stores the subscriber's own phone
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 number(s). Most classic GSM phones have a menu command for showing your own
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198 number, usually called "My number" or something like that; this menu command
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199 displays the first record stored in the MSISDN phonebook. Most network
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 operators update this MSISDN record over the air (using special SMS-encoded
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201 commands) when you activate service or get a new phone number without changing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 your SIM, but this MSISDN store in the SIM also has some interesting
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 properties:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 + Per the spec the MSISDN phonebook is writable by ordinary users, not just
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206 admins, and the Mother's experience with real T-Mobile SIMs is that they do
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207 indeed allow the user to write anything into MSISDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 + Most SIM card issuers allocate multiple records for MSISDN, not just one.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210 It is not clear if ordinary end user phones would do anything useful with
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211 the extra records if one were to write something there.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 fc-simtool provides a unified set of commands and data formats for working with
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 all SIM phonebooks: all pb-* commands take the name of the phonebook to be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215 operated on as their first argument. The following commands are available:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217 pb-dump PBNAME
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
218
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
219 This command dumps the full content of the selected phonebook on the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
220 The data format for representing SIM phonebook content in UNIX-based text files
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
221 and dumps is described in the SIM-data-formats document in the freecalypso-docs
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
222 repository.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
223
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
224 pb-dump PBNAME > outfile
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
225
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
226 This form of the pb-dump command dumps the full content of the selected
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
227 phonebook, but saves it in the named file instead of sending it to the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
228 This form is ideal for making backups of large SIM phonebooks.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
229
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
230 pb-dump-rec PBNAME rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
231
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
232 This command dumps a single record from a potentially large phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
233
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
234 pb-dump-rec PBNAME start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
235
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
236 This command dumps the specified range of records from a potentially large
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
237 phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
238
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
239 pb-restore PBNAME filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
240
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
241 This command reads a phonebook data file in the format described in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
242 SIM-data-formats document and uploads it into the named SIM phonebook. Every
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
243 record in the SIM phonebook is overwritten with an UPDATE RECORD command; those
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
244 record indices which do not appear in the data file being restored get blank
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
245 records (0xFF in every byte) written into them.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
246
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
247 pb-update PBNAME filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
248
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
249 This command reads a phonebook data file in the format described in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
250 SIM-data-formats document and uploads it into the named SIM phonebook, writing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
251 only those record indices which appear in the data file - each record from the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
252 data file gets written into the SIM with an UPDATE RECORD command, while all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
253 other record locations remain untouched.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
254
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
255 pb-update-imm PBNAME rec phone-number [alpha-tag]
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
256
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
257 This command writes a single phonebook entry directly from the command line,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
258 without going through a data file. The specific record index to write into must
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
259 always be specified (there is no built-in "find first empty record" function),
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
260 and the entry format for both the phone number and the alpha tag is more relaxed
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
261 compared to the very strict format required in data files:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
262
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
263 * The phone number can begin with a '+' character for international format;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
264
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
265 * The comma-separated TON/NPI byte is optional and will usually be omitted in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
266 ordinary usage - this byte will default to 0x91 if the number begins with '+'
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
267 or to 0x81 otherwise;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
268
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
269 * Double-quotes around the alpha tag argument are required only if it contains
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
270 spaces or other problematic characters, and can be omitted otherwise;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
271
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
272 * If the alpha tag is empty, the last argument can be omitted altogether.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
273
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
274 pb-update-imm-hex PBNAME rec phone-number alpha-tag-hex
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
275
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
276 This command is like pb-update-imm, but the alpha tag argument (required for
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
277 this command) is given in hex - intended for creating phonebook entries with
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
278 UCS-2 alpha tags.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
279
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
280 pb-erase PBNAME
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
281
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
282 This command fully erases the named phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
283
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
284 pb-erase-one PBNAME rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
285
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
286 This command erases the specified individual record in the named phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
287
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
288 pb-erase-range PBNAME start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
289
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
290 This command erases the specified range of records in the named phonebook. The
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
291 starting record must be identified by number (SIM record numbers are 1-based);
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
292 the ending record argument may be either a number or the "end" keyword.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
293
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
294 Enabling and disabling FDN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
295 ==========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
296
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
297 The Fixed Dialing Numbers (FDN) mechanism is normally disabled. The protocol
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
298 prescribed by GSM SIM specs is that FDN is enabled when the regular ADN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
299 phonebook is invalidated, and is disabled (unrestricted dialing allowed)
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
300 otherwise. fc-simtool provides commands for invalidating and rehabilitating
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
301 ADN, thereby enabling and disabling FDN:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
302
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
303 inval-adn
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
304
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
305 This command invalidates ADN and thereby enables FDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
306
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
307 rehab-adn
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
308
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
309 This command rehabilitates ADN and thereby disables FDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
310
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
311 The SIM will only allow inval-adn and rehab-adn operations after you have
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
312 successfully authenticated with PIN2 - see verify-pin2 command description.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
313
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
314 GSM SIM specs also stipulate a certain hack to prevent FDN-ignorant phones from
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
315 making "forbidden" unrestricted calls: the specs stipulate that when a SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
316 powers up in an FDN-enabled state (ADN is invalidated), the "smart" logic in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
317 the SIM invalidates two essential files EF_IMSI and EF_LOCI (needed for GSM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
318 operation), requiring the phone (ME) to rehabilitate these two files at the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
319 beginning of every SIM session when FDN is in use. The thinking must have been
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
320 that if a given ME knows how to do these extra rehab-imsi, rehab-loci steps,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
321 then it also knows about FDN and will honor it. Our answer: OK, whatever - but
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
322 we do provide rehab-imsi and rehab-loci commands in fc-simtool. These
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
323 operations require only CHV1 access, thus PIN1 or no PIN at all depending on
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
324 whether or not PIN1 is enabled - no need for PIN2.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
325
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
326 Last Number Dialed (LND)
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
327 ========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
328
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
329 Traditional SIMs include a cyclic file that is intended to be updated whenever
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
330 an outgoing call is dialed - but it is up to individual phone designs whether
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
331 they actually update this LND cyclic store or not. This SIM LND store has the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
332 same record format as phonebooks, carrying only phone numbers and optional alpha
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
333 tags - there are no fields for date & time, call duration or status as in call
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
334 answered or not. Because of the limitations of this SIM LND store, most phone
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
335 designs do not use it, and instead go with their own implementation of call
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
336 history lists.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
337
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
338 Because this LND store is a cyclic file, not linear fixed like phonebooks, it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
339 does not allow random access writes: it allows random access reads like all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
340 regular record-based files, but the only write operation allowed by the SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
341 interface protocol and the SIM file system architecture is writing a new record
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
342 that becomes the new #1, shifting all previous records down and losing the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
343 oldest one. Because of this write access limitation, we do not provide the same
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
344 set of operations on LND as for regular phonebooks - but we still provide good
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
345 tinkering ability. The following commands are available:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
346
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
347 lnd-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
348
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
349 This command dumps the content of the LND store on the terminal, in the same
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
350 format as pb-dump for regular phonebooks.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
351
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
352 If you have had your SIM for a very long time, having used it in different
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
353 phones with different firmwares, it may be interesting to look at the output of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
354 lnd-dump - you may have LND records that were generated ages ago by other
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
355 phones if your current one does not write into SIM LND.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
356
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
357 lnd-dump > outfile
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
358
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
359 This form of the lnd-dump command produces the same dump format, but saves it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
360 in the named file instead of sending it to the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
361
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
362 lnd-restore filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
363
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
364 This command reads the named phonebook data file (presumably written previously
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
365 with lnd-dump) and writes it into EF_LND on the SIM. This command works by
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
366 first constructing a full binary image of the desired EF_LND content, then
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
367 writing every record in the reverse order from the last index to the first.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
368
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
369 lnd-write phone-number [alpha-tag]
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
370
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
371 This command writes a new record into the LND cyclic store just like a standard
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
372 phone would do when making a record of a new outgoing call. The two arguments
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
373 (one required and one optional) are the same as for pb-update-imm.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
374
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
375 lnd-erase
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
376
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
377 This command erases the EF_LND cyclic store, making it appear as if no outgoing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
378 calls have ever been recorded. It works by writing a blank record (0xFF in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
379 every byte) N times, where N is the size of the cyclic store in records.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
380
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
381 Manipulating stored SMS
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
382 =======================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
383
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
384 The fundamental operating model of all message stores for SMS (whether SIM or
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
385 phone-based) is that received messages accumulate (and possibly sent ones too,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
386 if they are stored in this manner), the limited available memory fills up, and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
387 then the user needs to clean out the accumulated messages, preferably also
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
388 archiving them by transferring to a larger computer for longer-term storage.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
389 Given this fundamental operating model, we only need to provide commands for
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
390 dumping the content of the message store and for cleaning it out - there is no
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
391 real need to implement commands for writing messages into the store.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
392
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
393 The extent of special support for the SIM SMS store in fc-simtool is rather
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
394 minimal because it just so happened that we already have external tools that do
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
395 a major part of the work. Some phone firmwares, particularly that of the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
396 Pirelli DP-L10 phone currently used by the Mother, implement their on-the-phone
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
397 SMS storage by way of a file in their local flash file system whose binary
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
398 format just happens to be exactly the same as the binary format of SIM-based
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
399 EF_SMS if all 176-byte records are simply abutted together in the host-based
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
400 binary representation. A few release cycles ago we added a new utility named
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
401 pcm-sms-decode to our FreeCalypso host tools suite; this utility reads a binary
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
402 file in this "EF_SMS records concat" format and performs the quite involved job
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
403 of fully decoding all messages into human-readable form. Given that we have
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
404 this external pcm-sms-decode utility, all we need to do in fc-simtool is save
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
405 all records of EF_SMS into a single concatenated binary file, and let
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
406 pcm-sms-decode do the rest.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
407
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
408 Our dedicated commands for working with the SIM SMS store are as follows:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
409
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
410 save-sms-bin host-filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
411
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
412 This command saves the full content of EF_SMS in the named file in the host file
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
413 system in binary format, suitable for further decoding with pcm-sms-decode.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
414
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
415 sms-erase-all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
416
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
417 This command erases every record entry in EF_SMS.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
418
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
419 sms-erase-one rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
420
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
421 This command erases the specified individual record in EF_SMS.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
422
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
423 sms-erase-range start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
424
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
425 This command erases the specified range of records in EF_SMS. The starting
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
426 record must be identified by number (SIM record numbers are 1-based); the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
427 ending record argument may be either a number or the "end" keyword.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
428
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
429 Manipulating SMS parameters
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
430 ===========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
431
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
432 SIM cards have an SMS parameter store in the form of record-based file EF_SMSP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
433 Its most essential function is to specify the Service Centre Address for
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
434 outgoing SMS, but it can also be put to a few other uses:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
435
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
436 * The primary SMSP record that gives the SC address also typically includes PID
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
437 and DCS parameters. The only sensible settings that can function as a
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
438 general-purpose default are PID=0x00 and DCS=0x00, but some SIMs have been
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
439 seen in the field that set bogus PID and DCS via their SMSP. It appears that
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
440 most end user phones ignore these settings, and they have no effect when
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
441 outgoing SMS are submitted to an AT command modem in PDU mode, but these
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
442 settings do affect our TI-based AT command modem in text mode - if they are
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
443 bogus on the SIM, they need to be fixed, either with fc-simtool or in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
444 actual AT modem session with AT+CSMP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
445
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
446 * The same primary SMSP record can also specify a default validity period in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
447 one-byte relative VP format.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
448
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
449 * Just like the situation with MSISDN, even though only the first record of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
450 EF_SMSP is used in practice, most SIM issuers allocate room for a few records.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
451 These extra SMSP records are almost always blank,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
452
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
453 fc-simtool provides the following commands for working with EF_SMSP:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
454
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
455 smsp-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
456
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
457 This command dumps the full content of EF_SMSP (all records) on the terminal,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
458 using a lossless text-based format similar to the one we use for phonebooks.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
459 To illustrate our smsp format by way of examples, here is the output of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
460 smsp-dump from old T-Mobile USA SIMs that have classic GSM 11.11 SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
461 functionality:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
462
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
463 #1: SC=12063130004,0x91 PID=0x00 DCS=0x00 "T-Mobile"
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
464 #2: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
465 #3: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
466 #4: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
467
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
468 Here is the output from an Austrian S-Budget Mobile SIM from circa-2017:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
469
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
470 #1: SC=4365009000000,0x91 PID=0xFF DCS=0xFF VP=173 ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
471 #2: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
472
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
473 As one can see from these examples, T-Mobile allocated 4 records for their
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
474 EF_SMSP, whereas S-Budget Mobile allocated only 2 records for theirs.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
475 (Sysmocom webshop SIMs sysmoUSIM-SJS1 and sysmoISIM-SJA2 also have 2 records in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
476 their EF_SMSP.) Yet only the first record is actually used, and the remaining
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
477 ones are blank. Note that unlike pb-dump, smsp-dump does not skip blank
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
478 records: it displays every record (the design rationale is that the total number
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
479 of EF_SMSP records is expected to be small), and a blank record is simply one
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
480 that has no parameters present and has an empty alpha tag.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
481
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
482 The following parameters may be present in each SMSP record, appearing in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
483 smsp-dump output in the same order in which they appear in the SIM binary
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
484 record:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
485
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
486 DA= TP-Destination_Address
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
487 SC= TS-Service_Centre_Address
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
488 PID= TP-Protocol_Identifier
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
489 DCS= TP-Data_Coding_Scheme
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
490 VP= TP-Validity_Period
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
491
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
492 The phone numbers in DA= and SC= parameters are emitted in the same format as
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
493 in pb-dump, PID= and DCS= are emitted in hexadecimal with a 0x prefix, and VP=
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
494 is emitted in decimal. The alpha tag is always emitted at the end of the ASCII
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
495 line, just like in pb-dump.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
496
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
497 smsp-dump > outfile
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
498
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
499 This form of the smsp-dump command produces the same dump of EF_SMSP, but saves
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
500 it in the named file instead of sending it to the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
501
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
502 smsp-restore filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
503
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
504 This command reads a file written by smsp-dump and writes it back to the SIM.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
505 Both decimal and 0x-prefixed hexadecimal forms are accepted for all 3 of PID=,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
506 DCS= and VP= parameters.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
507
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
508 smsp-set rec params
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
509
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
510 This command writes a single record into SMSP directly from the command line,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
511 without going through a data file. The record index to write to must be given,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
512 followed by one or more parameters as in DA=, SC=, PID=, DCS= or VP=. DA= and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
513 SC= phone numbers can be entered in the same relaxed form as in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
514 pb-update-imm command, and the remaining 3 parameters can be either decimal or
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
515 0x-prefixed hexadecimal. This command leaves the alpha tag field blank.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
516
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
517 smsp-set-tag rec alpha-tag params
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
518
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
519 This command is just like smsp-set, but adds an alpha tag argument.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
520
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
521 smsp-erase-all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
522
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
523 This command erases every record entry in EF_SMSP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
524
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
525 smsp-erase-one rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
526
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
527 This command erases the specified individual record in EF_SMSP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
528
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
529 smsp-erase-range start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
530
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
531 This command erases the specified range of records in EF_SMSP. The starting
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
532 record must be identified by number (SIM record numbers are 1-based); the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
533 ending record argument may be either a number or the "end" keyword.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
534
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
535 Identifying MVNO SIMs
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
536 =====================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
537
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
538 Many SIMs, particularly those from MVNOs, are programmed by their issuers to
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
539 cause phones to display the name of the MVNO or some other party rather than
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
540 the standard PLMN name decoded from the connected network's MCC-MNC. This
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
541 "personalization" programming can appear in EF_SPN (old style) or in EF_PNN and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
542 EF_OPL (newer style). fc-simtool provides commands to display the content of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
543 these SIM files in human-readable form:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
544
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
545 spn
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
546 pnn-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
547 opl-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
548
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
549 These commands take no arguments, and their human-readable output is not
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
550 explained in detail here. If you need to understand the meaning of various
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
551 fields in detail, please refer to 3GPP TS 51.011.