--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/User-oriented-commands	Sun Feb 14 19:01:04 2021 +0000
@@ -0,0 +1,103 @@
+This document describes those commands and functions of fc-simtool which can be
+exercised by end users on any regular operator-issued SIM, without requiring a
+special programmable SIM with admin privileges.  The Mother's plans for future
+development include a companion fc-simint utility that will operate on SIM cards
+inside Calypso phones; the intent is that all of the end-user-oriented commands
+of fc-simtool described in this document will also be replicated in fc-simint.
+
+Understanding SIM PIN1
+======================
+
+Every standard SIM card has a secret code called PIN1; this secret code can be
+anywhere between 4 and 8 digits in length, with 4-digit PINs being most common.
+In terms of persistent non-volatile state, SIM PIN1 can be enabled or disabled.
+When SIM PIN1 is disabled, all regular functions of the card are enabled, as in
+being able to power up the phone with the SIM in it and connect to the GSM
+network with your subscriber identity, and being able to read and write SIM user
+data content like phonebooks and stored messages - all of these functions are
+enabled from the moment you turn on the phone with the SIM in it (or power the
+SIM up by itself in a smart card "reader" driven by fc-simtool), without the
+user ever being asked for a PIN, such that you can forget that the PIN even
+exists - this situation in very common nowadays.  But when SIM PIN1 is enabled,
+the smart chip in the SIM will not allow you access to any of the data stored
+on the card and will not allow any GSM authentication operations until and
+unless you send the correct PIN to the SIM in the VERIFY CHV command.
+
+If you forgot your PIN1, the only way to reset it is to enter another secret
+code (always 8 digits in length) called PUK1.  If the SIM is made according to
+standards, then its PUK1 is set to a random number during either physical
+manufacturing or administrative programming of the card and then remains
+unchangeable afterward.  Therefore, in an ideal world if someone forgot their
+PIN1 and don't have their PUK1 either, they should be able to obtain PUK1 from
+the cellular operator who issued the SIM - but whether or not today's operators
+will actually help such hapless users (without forcing them to get a new SIM)
+is another question altogether.  PUK1 is often printed on the big (credit-card-
+sized) plastic piece on which SIM cards are initially delivered - but it doesn't
+help if you originally got your SIM many ages ago and no longer have that
+souvenir plastic piece.
+
+The standard protocol for communicating with SIM cards provides 5 special
+commands that are dedicated to working with PIN1, and so does fc-simtool:
+
+verify-pin1 XXXX
+
+This command tells the SIM that you are attempting to prove knowledge
+of PIN1, presenting a string of digits.  If the PIN digits you specify match
+the PIN1 secret code stored inside the SIM, the card unlocks access to its
+primary functions.  If the digits you send are wrong, the SIM decrements its
+non-volatile attempt counter, giving you a total of 3 attempts (irrespective of
+card power-downs between attempts) to enter the correct PIN.  If PIN1 is entered
+incorrectly 3 times in a row, this PIN is blocked, and the only way to unblock
+it is via PUK1.
+
+enable-pin1 XXXX
+
+This command changes the non-volatile state of the PIN1 enable/disable flag,
+such that from now on the SIM will require PIN1 to be provided on every card
+power-up before it will allow GSM authentication and access to user data.  The
+enable-pin1 operation itself requires correct PIN1 digits to be provided.
+
+disable-pin1 XXXX
+
+This command changes the non-volatile state of the PIN1 enable/disable flag,
+such that from now on the SIM will NOT require PIN1 to be provided on every
+card power-up, and will instead be live immediately without needing proof of
+card owner's identity.  The disable-pin1 operation itself requires correct PIN1
+digits to be provided.
+
+change-pin1 old-PIN new-PIN
+
+This command tells the SIM that you wish to change PIN1 secret code to some new
+digits.  Knowledge of the old PIN1 is required for this operation to succeed.
+
+unblock-pin1 PUK1-secret-code new-PIN1
+
+This command tells the SIM that you are attempting to prove knowledge
+of PUK1 and to set new PIN1.  If PUK1 is given correctly, the new PIN1 will be
+set.  If you enter wrong PUK1, the SIM decrements its non-volatile attempt
+counter, giving you a total of 10 attempts (irrespective of card power-downs
+between attempts) to enter the correct code.  If PUK1 is entered incorrectly 10
+times in a row, it is blocked and the card should be considered bricked beyond
+recovery.
+
+Understanding SIM PIN2
+======================
+
+GSM standards provide support for a very rarely used feature that works in the
+spirit of "parental controls": if you authenticate to the SIM with PIN2 secret
+code (which has to be different from PIN1 for meaningful security), you can
+edit a SIM-resident list of so-called Fixed Dialing Numbers (FDN), and then all
+standard phones that implement this feature per the spec will refuse to allow
+ordinary users (authenticated with PIN1 or with no PIN at all) to call any
+numbers other than those programmed in FDN.
+
+This whole "parental control" feature is totally silly and is not expected to be
+of any practical use, but the whole purpose of fc-simtool is to allow every
+feature of SIM cards to be exercised, hence we provide the necessary support.
+The following commands work just like their PIN1 counterparts:
+
+verify-pin2 XXXX
+change-pin2 old-PIN new-PIN
+unblock-pin2 PUK2-secret-code new-PIN2
+
+Unlike PIN1, PIN2 cannot be disabled per traditional SIM card standards.