FreeCalypso > hg > fc-pcsc-tools
view doc/User-oriented-commands @ 65:cc48ac3b151c
doc/User-oriented-commands: basic info commands documented
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 14 Feb 2021 23:03:00 +0000 |
parents | 8cd4771bdd79 |
children | d4058ae94749 |
line wrap: on
line source
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. Getting basic info from the SIM =============================== The following commands are available for retrieving basic info from the SIM: iccid This command retrieves the ICCID (Integrated Circuit Card ID) record from the SIM - it is a number of up to 20 digits (although 19-digit ICCIDs are most common) that identifies the SIM card as a physical artifact. If your SIM is of the traditional operator-issued kind, as opposed to a developer-oriented programmable SIM from vendors like Sysmocom who have different ideas, this ICCID will usually be the SIM card ID number printed on the physical plastic, along with a barcode representation of the same number. imsi This command retrieves the IMSI (International Mobile Subscriber Identity) from the SIM - it is the most fundamental ID token by which GSM phones present themselves to networks, and they even use the first 5 or 6 digits of the IMSI to decide which network they should try connecting to first. sst Every SIM card is required to have an essential data record (an EF in technical terms) called the SIM Service Table, or SST. This SST indicates which services are allocated and activated on the given SIM. Our sst command lists all allocated service numbers, listing just a plain number if the service is both allocated and activated (the usual case), or a number with a '^' suffix if the service is allocated but not activated. You will need to look in the 3GPP TS 51.011 spec to make sense of these service numbers. user-sum This command displays a user-friendly summary of user-oriented services present on the SIM. It reads SST to get the list of available and activated services, but it considers only user-oriented ones (as opposed to SIM services dealing with GSM network functions or serving operators' interests rather than users'), and it displays them in a user-friendly manner. For each present SIM phonebook (ADN, FDN, SDN) and for the SMS store, user-sum displays the storage capacity provided by the SIM (number of phonebook entries or messages), and for each of the various phonebooks, the allocated number of alpha tag bytes is also displayed. The number of bytes allocated for the alpha tag in SIM phonebooks determines the maximum length of the name field in each phonebook entry. These name fields can be written either in GSM7 encoding (GSM 03.38 aka 3GPP 23.038) or in UCS-2; when GSM7 encoding is used, no SMS-style septet packing is applied - instead the high bit of each byte is simply cleared. Therefore, the maximum number of characters in a phonebook entry name field usually equals the number of bytes allocated for the alpha tag on the SIM, except for names containing ASCII characters [\]^ and {|}~ which get expanded to 2-character escape sequences in GSM7 encoding. uicc-dir If your SIM card functions not only as a classic GSM 11.11 SIM, but also as a UICC with USIM/ISIM or other UICC-based applications, it will have a file named EF_DIR in its file system, listing those applications. fc-simtool uicc-dir command dumps the content of this file in a human-readable form - but please note that fc-simtool only speaks the classic GSM 11.11 protocol to the SIM, and not the UICC protocol. EF_DIR does not officially exist in the classic GSM SIM spec, hence the dir command in fc-uicc-tool (speaking the UICC protocol) is the official way to read and dump the content of EF_DIR. Manipulating SIM phonebooks =========================== Manipulating stored SMS ======================= Manipulating SMS profiles ========================= Identifying MVNO SIMs =====================