# HG changeset patch # User Mychaela Falconia # Date 1613329264 0 # Node ID 8cd4771bdd79e150f01fd8f7a37735938b80cb25 # Parent 5f8c06445a40dd932b0a86c6ae267b1fc46cef53 doc/User-oriented-commands: document started diff -r 5f8c06445a40 -r 8cd4771bdd79 doc/User-oriented-commands --- /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.