FreeCalypso > hg > fc-pcsc-tools

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