FreeCalypso > hg > fc-pcsc-tools

annotate doc/User-oriented-commands @ 64:8cd4771bdd79

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/User-oriented-commands: document started
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 14 Feb 2021 19:01:04 +0000
parents
children cc48ac3b151c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
64
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 This document describes those commands and functions of fc-simtool which can be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 exercised by end users on any regular operator-issued SIM, without requiring a
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 special programmable SIM with admin privileges. The Mother's plans for future
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 development include a companion fc-simint utility that will operate on SIM cards
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 inside Calypso phones; the intent is that all of the end-user-oriented commands
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 of fc-simtool described in this document will also be replicated in fc-simint.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 Understanding SIM PIN1
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 ======================
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 Every standard SIM card has a secret code called PIN1; this secret code can be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 anywhere between 4 and 8 digits in length, with 4-digit PINs being most common.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 In terms of persistent non-volatile state, SIM PIN1 can be enabled or disabled.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 When SIM PIN1 is disabled, all regular functions of the card are enabled, as in
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 being able to power up the phone with the SIM in it and connect to the GSM
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 network with your subscriber identity, and being able to read and write SIM user
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 data content like phonebooks and stored messages - all of these functions are
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 enabled from the moment you turn on the phone with the SIM in it (or power the
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 SIM up by itself in a smart card "reader" driven by fc-simtool), without the
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 user ever being asked for a PIN, such that you can forget that the PIN even
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 exists - this situation in very common nowadays. But when SIM PIN1 is enabled,
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 the smart chip in the SIM will not allow you access to any of the data stored
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 on the card and will not allow any GSM authentication operations until and
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 unless you send the correct PIN to the SIM in the VERIFY CHV command.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 If you forgot your PIN1, the only way to reset it is to enter another secret
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 code (always 8 digits in length) called PUK1. If the SIM is made according to
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 standards, then its PUK1 is set to a random number during either physical
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 manufacturing or administrative programming of the card and then remains
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 unchangeable afterward. Therefore, in an ideal world if someone forgot their
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 PIN1 and don't have their PUK1 either, they should be able to obtain PUK1 from
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 the cellular operator who issued the SIM - but whether or not today's operators
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 will actually help such hapless users (without forcing them to get a new SIM)
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 is another question altogether. PUK1 is often printed on the big (credit-card-
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 sized) plastic piece on which SIM cards are initially delivered - but it doesn't
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 help if you originally got your SIM many ages ago and no longer have that
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 souvenir plastic piece.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 The standard protocol for communicating with SIM cards provides 5 special
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 commands that are dedicated to working with PIN1, and so does fc-simtool:
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 verify-pin1 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 This command tells the SIM that you are attempting to prove knowledge
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 of PIN1, presenting a string of digits. If the PIN digits you specify match
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 the PIN1 secret code stored inside the SIM, the card unlocks access to its
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 primary functions. If the digits you send are wrong, the SIM decrements its
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 non-volatile attempt counter, giving you a total of 3 attempts (irrespective of
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 card power-downs between attempts) to enter the correct PIN. If PIN1 is entered
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 incorrectly 3 times in a row, this PIN is blocked, and the only way to unblock
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 it is via PUK1.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 enable-pin1 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 This command changes the non-volatile state of the PIN1 enable/disable flag,
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 such that from now on the SIM will require PIN1 to be provided on every card
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 power-up before it will allow GSM authentication and access to user data. The
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 enable-pin1 operation itself requires correct PIN1 digits to be provided.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 disable-pin1 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 This command changes the non-volatile state of the PIN1 enable/disable flag,
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 such that from now on the SIM will NOT require PIN1 to be provided on every
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 card power-up, and will instead be live immediately without needing proof of
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 card owner's identity. The disable-pin1 operation itself requires correct PIN1
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 digits to be provided.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 change-pin1 old-PIN new-PIN
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 This command tells the SIM that you wish to change PIN1 secret code to some new
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 digits. Knowledge of the old PIN1 is required for this operation to succeed.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 unblock-pin1 PUK1-secret-code new-PIN1
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 This command tells the SIM that you are attempting to prove knowledge
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 of PUK1 and to set new PIN1. If PUK1 is given correctly, the new PIN1 will be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 set. If you enter wrong PUK1, the SIM decrements its non-volatile attempt
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 counter, giving you a total of 10 attempts (irrespective of card power-downs
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 between attempts) to enter the correct code. If PUK1 is entered incorrectly 10
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 times in a row, it is blocked and the card should be considered bricked beyond
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 recovery.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 Understanding SIM PIN2
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 ======================
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 GSM standards provide support for a very rarely used feature that works in the
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 spirit of "parental controls": if you authenticate to the SIM with PIN2 secret
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 code (which has to be different from PIN1 for meaningful security), you can
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 edit a SIM-resident list of so-called Fixed Dialing Numbers (FDN), and then all
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 standard phones that implement this feature per the spec will refuse to allow
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 ordinary users (authenticated with PIN1 or with no PIN at all) to call any
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 numbers other than those programmed in FDN.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 This whole "parental control" feature is totally silly and is not expected to be
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 of any practical use, but the whole purpose of fc-simtool is to allow every
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 feature of SIM cards to be exercised, hence we provide the necessary support.
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 The following commands work just like their PIN1 counterparts:
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 verify-pin2 XXXX
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 change-pin2 old-PIN new-PIN
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 unblock-pin2 PUK2-secret-code new-PIN2
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102
8cd4771bdd79 doc/User-oriented-commands: document started
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 Unlike PIN1, PIN2 cannot be disabled per traditional SIM card standards.