fc-sim-tools: doc/User-oriented-commands annotate

annotate doc/User-oriented-commands @ 93:6041c601304d

fcsim1-mkprov: revert OTA key addition It appears that GrcardSIM2 cards (which is what we got for FCSIM1) do not support OTA after all, contrary to what we were previously led to believe by some tech support emails from Grcard - apparently those support emails and OTA descriptions referred to some other card model(s).

author	Mychaela Falconia <falcon@freecalypso.org>
date	Wed, 21 Apr 2021 05:38:39 +0000
parents	969f9b7863f0
children

rev	line source
18 da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 This document describes those commands and functions of fc-simtool which can be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 exercised by end users on any regular operator-issued SIM, without requiring a
20 969f9b7863f0 doc/User-oriented-commands: fc-simint is not going to be a subset tool Mychaela Falconia <falcon@freecalypso.org> parents: 18 diff changeset	3 special programmable SIM with admin privileges.
18 da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5 Understanding SIM PIN1
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 ======================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 Every standard SIM card has a secret code called PIN1; this secret code can be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9 anywhere between 4 and 8 digits in length, with 4-digit PINs being most common.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 In terms of persistent non-volatile state, SIM PIN1 can be enabled or disabled.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11 When SIM PIN1 is disabled, all regular functions of the card are enabled, as in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12 being able to power up the phone with the SIM in it and connect to the GSM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13 network with your subscriber identity, and being able to read and write SIM user
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14 data content like phonebooks and stored messages - all of these functions are
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15 enabled from the moment you turn on the phone with the SIM in it (or power the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16 SIM up by itself in a smart card "reader" driven by fc-simtool), without the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 user ever being asked for a PIN, such that you can forget that the PIN even
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 exists - this situation in very common nowadays. But when SIM PIN1 is enabled,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19 the smart chip in the SIM will not allow you access to any of the data stored
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 on the card and will not allow any GSM authentication operations until and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21 unless you send the correct PIN to the SIM in the VERIFY CHV command.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 If you forgot your PIN1, the only way to reset it is to enter another secret
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 code (always 8 digits in length) called PUK1. If the SIM is made according to
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25 standards, then its PUK1 is set to a random number during either physical
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26 manufacturing or administrative programming of the card and then remains
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27 unchangeable afterward. Therefore, in an ideal world if someone forgot their
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28 PIN1 and don't have their PUK1 either, they should be able to obtain PUK1 from
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29 the cellular operator who issued the SIM - but whether or not today's operators
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 will actually help such hapless users (without forcing them to get a new SIM)
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 is another question altogether. PUK1 is often printed on the big (credit-card-
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32 sized) plastic piece on which SIM cards are initially delivered - but it doesn't
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33 help if you originally got your SIM many ages ago and no longer have that
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34 souvenir plastic piece.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 The standard protocol for communicating with SIM cards provides 5 special
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37 commands that are dedicated to working with PIN1, and so does fc-simtool:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 verify-pin1 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41 This command tells the SIM that you are attempting to prove knowledge
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	42 of PIN1, presenting a string of digits. If the PIN digits you specify match
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	43 the PIN1 secret code stored inside the SIM, the card unlocks access to its
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44 primary functions. If the digits you send are wrong, the SIM decrements its
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	45 non-volatile attempt counter, giving you a total of 3 attempts (irrespective of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	46 card power-downs between attempts) to enter the correct PIN. If PIN1 is entered
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	47 incorrectly 3 times in a row, this PIN is blocked, and the only way to unblock
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	48 it is via PUK1.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	49
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	50 enable-pin1 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	51
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	52 This command changes the non-volatile state of the PIN1 enable/disable flag,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	53 such that from now on the SIM will require PIN1 to be provided on every card
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54 power-up before it will allow GSM authentication and access to user data. The
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 enable-pin1 operation itself requires correct PIN1 digits to be provided.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57 disable-pin1 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 This command changes the non-volatile state of the PIN1 enable/disable flag,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60 such that from now on the SIM will NOT require PIN1 to be provided on every
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61 card power-up, and will instead be live immediately without needing proof of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	62 card owner's identity. The disable-pin1 operation itself requires correct PIN1
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	63 digits to be provided.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	64
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	65 change-pin1 old-PIN new-PIN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	66
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67 This command tells the SIM that you wish to change PIN1 secret code to some new
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	68 digits. Knowledge of the old PIN1 is required for this operation to succeed.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	69
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	70 unblock-pin1 PUK1-secret-code new-PIN1
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 This command tells the SIM that you are attempting to prove knowledge
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73 of PUK1 and to set new PIN1. If PUK1 is given correctly, the new PIN1 will be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74 set. If you enter wrong PUK1, the SIM decrements its non-volatile attempt
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	75 counter, giving you a total of 10 attempts (irrespective of card power-downs
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76 between attempts) to enter the correct code. If PUK1 is entered incorrectly 10
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77 times in a row, it is blocked and the card should be considered bricked beyond
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78 recovery.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 Understanding SIM PIN2
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81 ======================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 GSM standards provide support for a very rarely used feature that works in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84 spirit of "parental controls": if you authenticate to the SIM with PIN2 secret
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	85 code (which has to be different from PIN1 for meaningful security), you can
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	86 edit a SIM-resident list of so-called Fixed Dialing Numbers (FDN), and then all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87 standard phones that implement this feature per the spec will refuse to allow
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88 ordinary users (authenticated with PIN1 or with no PIN at all) to call any
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	89 numbers other than those programmed in FDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	90
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	91 This whole "parental control" feature is totally silly and is not expected to be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92 of any practical use, but the whole purpose of fc-simtool is to allow every
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93 feature of SIM cards to be exercised, hence we provide the necessary support.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94 The following commands work just like their PIN1 counterparts:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	95
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	96 verify-pin2 XXXX
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	97 change-pin2 old-PIN new-PIN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	98 unblock-pin2 PUK2-secret-code new-PIN2
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	99
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100 Unlike PIN1, PIN2 cannot be disabled per traditional SIM card standards.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102 Getting basic info from the SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 ===============================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105 The following commands are available for retrieving basic info from the SIM:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107 iccid
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109 This command retrieves the ICCID (Integrated Circuit Card ID) record from the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110 SIM - it is a number of up to 20 digits (although 19-digit ICCIDs are most
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 common) that identifies the SIM card as a physical artifact. If your SIM is of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	112 the traditional operator-issued kind, as opposed to a developer-oriented
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	113 programmable SIM from vendors like Sysmocom who have different ideas, this ICCID
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	114 will usually be the SIM card ID number printed on the physical plastic, along
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115 with a barcode representation of the same number.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117 imsi
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119 This command retrieves the IMSI (International Mobile Subscriber Identity) from
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 the SIM - it is the most fundamental ID token by which GSM phones present
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121 themselves to networks, and they even use the first 5 or 6 digits of the IMSI
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	122 to decide which network they should try connecting to first.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	123
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	124 It should also be noted that if your SIM has FDN (Fixed Dialing Numbers) enabled
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	125 and the card implements GSM SIM specs to the letter, including the idiotic
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	126 parts, then you will need to issue a rehab-imsi command before you can read the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	127 IMSI record - see the FDN section further in this document.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	128
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	129 sst
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	130
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	131 Every SIM card is required to have an essential data record (an EF in technical
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	132 terms) called the SIM Service Table, or SST. This SST indicates which services
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	133 are allocated and activated on the given SIM. Our sst command lists all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	134 allocated service numbers, listing just a plain number if the service is both
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	135 allocated and activated (the usual case), or a number with a '^' suffix if the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	136 service is allocated but not activated. You will need to look in the 3GPP TS
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	137 51.011 spec to make sense of these service numbers.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	139 user-sum
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	140
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141 This command displays a user-friendly summary of user-oriented services present
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 on the SIM. It reads SST to get the list of available and activated services,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	143 but it considers only user-oriented ones (as opposed to SIM services dealing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144 with GSM network functions or serving operators' interests rather than users'),
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	145 and it displays them in a user-friendly manner. For each present SIM phonebook
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	146 (ADN, FDN, SDN) and for the SMS store, user-sum displays the storage capacity
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	147 provided by the SIM (number of phonebook entries or messages), and for each of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148 the various phonebooks, the allocated number of alpha tag bytes is also
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149 displayed.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	150
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	151 The number of bytes allocated for the alpha tag in SIM phonebooks determines
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	152 the maximum length of the name field in each phonebook entry. These name fields
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	153 can be written either in GSM7 encoding (GSM 03.38 aka 3GPP 23.038) or in UCS-2;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	154 when GSM7 encoding is used, no SMS-style septet packing is applied - instead the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155 high bit of each byte is simply cleared. Therefore, the maximum number of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156 characters in a phonebook entry name field usually equals the number of bytes
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157 allocated for the alpha tag on the SIM, except for names containing ASCII
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158 characters [\]^ and {\|}~ which get expanded to 2-character escape sequences in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 GSM7 encoding.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	160
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	161 uicc-dir
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	162
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	163 If your SIM card functions not only as a classic GSM 11.11 SIM, but also as a
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	164 UICC with USIM/ISIM or other UICC-based applications, it will have a file named
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	165 EF_DIR in its file system, listing those applications. fc-simtool uicc-dir
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	166 command dumps the content of this file in a human-readable form - but please
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	167 note that fc-simtool only speaks the classic GSM 11.11 protocol to the SIM, and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	168 not the UICC protocol. EF_DIR does not officially exist in the classic GSM SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	169 spec, hence the dir command in fc-uicc-tool (speaking the UICC protocol) is the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	170 official way to read and dump the content of EF_DIR.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	171
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	172 Manipulating SIM phonebooks
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	173 ===========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	174
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	175 GSM SIM specs allow for several different phonebooks to be present on the card:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	177 * ADN (Abbreviated Dialing Numbers) is the main SIM phonebook. Each SIM card
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	178 issuer decides how much storage space they allocate to ADN (how many records);
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	179 the SIM spec maximum is 254 records, and many issuers' SIMs do provide this
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180 many records or close to this limit.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	181
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	182 * FDN (Fixed Dialing Numbers) is the "parental control" phonebook. The FDN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	183 phonebook can only be written to after authenticating with PIN2, and when it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	184 is enabled (enabling FDN is done by "invalidating" ADN, an operation which
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	185 also requires PIN2), spec-compliant phones allow only numbers in FDN to be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	186 called.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	187
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	188 * SDN (Service Dialing Numbers) is a service-provider-controlled phonebook: it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	189 can only be written if you have special admin privileges (ADM authentication
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	190 method is card-vendor-dependent), and it is read-only to ordinary users.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	191
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	192 * MBDN (Mailbox Dialing Numbers) is a late addition to GSM SIM specs - it is a
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	193 special phonebook that stores the number for Voice Mail and other related
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	194 esoteric services.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	195
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	196 * MSISDN is a phonebook-like file that stores the subscriber's own phone
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	197 number(s). Most classic GSM phones have a menu command for showing your own
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	198 number, usually called "My number" or something like that; this menu command
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	199 displays the first record stored in the MSISDN phonebook. Most network
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	200 operators update this MSISDN record over the air (using special SMS-encoded
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	201 commands) when you activate service or get a new phone number without changing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	202 your SIM, but this MSISDN store in the SIM also has some interesting
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	203 properties:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	204
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	205 + Per the spec the MSISDN phonebook is writable by ordinary users, not just
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	206 admins, and the Mother's experience with real T-Mobile SIMs is that they do
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	207 indeed allow the user to write anything into MSISDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	208
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	209 + Most SIM card issuers allocate multiple records for MSISDN, not just one.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	210 It is not clear if ordinary end user phones would do anything useful with
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	211 the extra records if one were to write something there.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	212
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	213 fc-simtool provides a unified set of commands and data formats for working with
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	214 all SIM phonebooks: all pb-* commands take the name of the phonebook to be
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	215 operated on as their first argument. The following commands are available:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	216
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	217 pb-dump PBNAME
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	218
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	219 This command dumps the full content of the selected phonebook on the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	220 The data format for representing SIM phonebook content in UNIX-based text files
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	221 and dumps is described in the SIM-data-formats document in the freecalypso-docs
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	222 repository.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	223
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	224 pb-dump PBNAME > outfile
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	225
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	226 This form of the pb-dump command dumps the full content of the selected
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	227 phonebook, but saves it in the named file instead of sending it to the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	228 This form is ideal for making backups of large SIM phonebooks.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	229
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	230 pb-dump-rec PBNAME rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	231
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	232 This command dumps a single record from a potentially large phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	233
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	234 pb-dump-rec PBNAME start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	235
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	236 This command dumps the specified range of records from a potentially large
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	237 phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	238
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	239 pb-restore PBNAME filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	240
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	241 This command reads a phonebook data file in the format described in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	242 SIM-data-formats document and uploads it into the named SIM phonebook. Every
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	243 record in the SIM phonebook is overwritten with an UPDATE RECORD command; those
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	244 record indices which do not appear in the data file being restored get blank
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	245 records (0xFF in every byte) written into them.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	246
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	247 pb-update PBNAME filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	248
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	249 This command reads a phonebook data file in the format described in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	250 SIM-data-formats document and uploads it into the named SIM phonebook, writing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	251 only those record indices which appear in the data file - each record from the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	252 data file gets written into the SIM with an UPDATE RECORD command, while all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	253 other record locations remain untouched.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	254
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	255 pb-update-imm PBNAME rec phone-number [alpha-tag]
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	256
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	257 This command writes a single phonebook entry directly from the command line,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	258 without going through a data file. The specific record index to write into must
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	259 always be specified (there is no built-in "find first empty record" function),
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	260 and the entry format for both the phone number and the alpha tag is more relaxed
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	261 compared to the very strict format required in data files:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	262
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	263 * The phone number can begin with a '+' character for international format;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	264
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	265 * The comma-separated TON/NPI byte is optional and will usually be omitted in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	266 ordinary usage - this byte will default to 0x91 if the number begins with '+'
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	267 or to 0x81 otherwise;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	268
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	269 * Double-quotes around the alpha tag argument are required only if it contains
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	270 spaces or other problematic characters, and can be omitted otherwise;
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	271
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	272 * If the alpha tag is empty, the last argument can be omitted altogether.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	273
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	274 pb-update-imm-hex PBNAME rec phone-number alpha-tag-hex
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	275
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	276 This command is like pb-update-imm, but the alpha tag argument (required for
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	277 this command) is given in hex - intended for creating phonebook entries with
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	278 UCS-2 alpha tags.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	279
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	280 pb-erase PBNAME
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	281
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	282 This command fully erases the named phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	283
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	284 pb-erase-one PBNAME rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	285
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	286 This command erases the specified individual record in the named phonebook.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	287
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	288 pb-erase-range PBNAME start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	289
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	290 This command erases the specified range of records in the named phonebook. The
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	291 starting record must be identified by number (SIM record numbers are 1-based);
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	292 the ending record argument may be either a number or the "end" keyword.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	293
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	294 Enabling and disabling FDN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	295 ==========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	296
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	297 The Fixed Dialing Numbers (FDN) mechanism is normally disabled. The protocol
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	298 prescribed by GSM SIM specs is that FDN is enabled when the regular ADN
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	299 phonebook is invalidated, and is disabled (unrestricted dialing allowed)
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	300 otherwise. fc-simtool provides commands for invalidating and rehabilitating
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	301 ADN, thereby enabling and disabling FDN:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	302
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	303 inval-adn
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	304
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	305 This command invalidates ADN and thereby enables FDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	306
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	307 rehab-adn
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	308
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	309 This command rehabilitates ADN and thereby disables FDN.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	310
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	311 The SIM will only allow inval-adn and rehab-adn operations after you have
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	312 successfully authenticated with PIN2 - see verify-pin2 command description.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	313
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	314 GSM SIM specs also stipulate a certain hack to prevent FDN-ignorant phones from
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	315 making "forbidden" unrestricted calls: the specs stipulate that when a SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	316 powers up in an FDN-enabled state (ADN is invalidated), the "smart" logic in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	317 the SIM invalidates two essential files EF_IMSI and EF_LOCI (needed for GSM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	318 operation), requiring the phone (ME) to rehabilitate these two files at the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	319 beginning of every SIM session when FDN is in use. The thinking must have been
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	320 that if a given ME knows how to do these extra rehab-imsi, rehab-loci steps,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	321 then it also knows about FDN and will honor it. Our answer: OK, whatever - but
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	322 we do provide rehab-imsi and rehab-loci commands in fc-simtool. These
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	323 operations require only CHV1 access, thus PIN1 or no PIN at all depending on
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	324 whether or not PIN1 is enabled - no need for PIN2.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	325
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	326 Last Number Dialed (LND)
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	327 ========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	328
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	329 Traditional SIMs include a cyclic file that is intended to be updated whenever
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	330 an outgoing call is dialed - but it is up to individual phone designs whether
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	331 they actually update this LND cyclic store or not. This SIM LND store has the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	332 same record format as phonebooks, carrying only phone numbers and optional alpha
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	333 tags - there are no fields for date & time, call duration or status as in call
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	334 answered or not. Because of the limitations of this SIM LND store, most phone
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	335 designs do not use it, and instead go with their own implementation of call
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	336 history lists.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	337
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	338 Because this LND store is a cyclic file, not linear fixed like phonebooks, it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	339 does not allow random access writes: it allows random access reads like all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	340 regular record-based files, but the only write operation allowed by the SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	341 interface protocol and the SIM file system architecture is writing a new record
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	342 that becomes the new #1, shifting all previous records down and losing the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	343 oldest one. Because of this write access limitation, we do not provide the same
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	344 set of operations on LND as for regular phonebooks - but we still provide good
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	345 tinkering ability. The following commands are available:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	346
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	347 lnd-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	348
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	349 This command dumps the content of the LND store on the terminal, in the same
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	350 format as pb-dump for regular phonebooks.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	351
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	352 If you have had your SIM for a very long time, having used it in different
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	353 phones with different firmwares, it may be interesting to look at the output of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	354 lnd-dump - you may have LND records that were generated ages ago by other
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	355 phones if your current one does not write into SIM LND.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	356
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	357 lnd-dump > outfile
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	358
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	359 This form of the lnd-dump command produces the same dump format, but saves it
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	360 in the named file instead of sending it to the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	361
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	362 lnd-restore filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	363
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	364 This command reads the named phonebook data file (presumably written previously
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	365 with lnd-dump) and writes it into EF_LND on the SIM. This command works by
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	366 first constructing a full binary image of the desired EF_LND content, then
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	367 writing every record in the reverse order from the last index to the first.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	368
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	369 lnd-write phone-number [alpha-tag]
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	370
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	371 This command writes a new record into the LND cyclic store just like a standard
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	372 phone would do when making a record of a new outgoing call. The two arguments
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	373 (one required and one optional) are the same as for pb-update-imm.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	374
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	375 lnd-erase
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	376
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	377 This command erases the EF_LND cyclic store, making it appear as if no outgoing
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	378 calls have ever been recorded. It works by writing a blank record (0xFF in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	379 every byte) N times, where N is the size of the cyclic store in records.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	380
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	381 Manipulating stored SMS
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	382 =======================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	383
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	384 The fundamental operating model of all message stores for SMS (whether SIM or
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	385 phone-based) is that received messages accumulate (and possibly sent ones too,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	386 if they are stored in this manner), the limited available memory fills up, and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	387 then the user needs to clean out the accumulated messages, preferably also
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	388 archiving them by transferring to a larger computer for longer-term storage.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	389 Given this fundamental operating model, we only need to provide commands for
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	390 dumping the content of the message store and for cleaning it out - there is no
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	391 real need to implement commands for writing messages into the store.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	392
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	393 The extent of special support for the SIM SMS store in fc-simtool is rather
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	394 minimal because it just so happened that we already have external tools that do
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	395 a major part of the work. Some phone firmwares, particularly that of the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	396 Pirelli DP-L10 phone currently used by the Mother, implement their on-the-phone
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	397 SMS storage by way of a file in their local flash file system whose binary
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	398 format just happens to be exactly the same as the binary format of SIM-based
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	399 EF_SMS if all 176-byte records are simply abutted together in the host-based
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	400 binary representation. A few release cycles ago we added a new utility named
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	401 pcm-sms-decode to our FreeCalypso host tools suite; this utility reads a binary
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	402 file in this "EF_SMS records concat" format and performs the quite involved job
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	403 of fully decoding all messages into human-readable form. Given that we have
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	404 this external pcm-sms-decode utility, all we need to do in fc-simtool is save
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	405 all records of EF_SMS into a single concatenated binary file, and let
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	406 pcm-sms-decode do the rest.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	407
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	408 Our dedicated commands for working with the SIM SMS store are as follows:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	409
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	410 save-sms-bin host-filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	411
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	412 This command saves the full content of EF_SMS in the named file in the host file
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	413 system in binary format, suitable for further decoding with pcm-sms-decode.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	414
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	415 sms-erase-all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	416
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	417 This command erases every record entry in EF_SMS.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	418
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	419 sms-erase-one rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	420
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	421 This command erases the specified individual record in EF_SMS.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	422
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	423 sms-erase-range start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	424
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	425 This command erases the specified range of records in EF_SMS. The starting
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	426 record must be identified by number (SIM record numbers are 1-based); the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	427 ending record argument may be either a number or the "end" keyword.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	428
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	429 Manipulating SMS parameters
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	430 ===========================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	431
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	432 SIM cards have an SMS parameter store in the form of record-based file EF_SMSP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	433 Its most essential function is to specify the Service Centre Address for
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	434 outgoing SMS, but it can also be put to a few other uses:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	435
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	436 * The primary SMSP record that gives the SC address also typically includes PID
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	437 and DCS parameters. The only sensible settings that can function as a
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	438 general-purpose default are PID=0x00 and DCS=0x00, but some SIMs have been
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	439 seen in the field that set bogus PID and DCS via their SMSP. It appears that
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	440 most end user phones ignore these settings, and they have no effect when
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	441 outgoing SMS are submitted to an AT command modem in PDU mode, but these
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	442 settings do affect our TI-based AT command modem in text mode - if they are
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	443 bogus on the SIM, they need to be fixed, either with fc-simtool or in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	444 actual AT modem session with AT+CSMP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	445
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	446 * The same primary SMSP record can also specify a default validity period in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	447 one-byte relative VP format.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	448
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	449 * Just like the situation with MSISDN, even though only the first record of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	450 EF_SMSP is used in practice, most SIM issuers allocate room for a few records.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	451 These extra SMSP records are almost always blank,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	452
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	453 fc-simtool provides the following commands for working with EF_SMSP:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	454
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	455 smsp-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	456
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	457 This command dumps the full content of EF_SMSP (all records) on the terminal,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	458 using a lossless text-based format similar to the one we use for phonebooks.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	459 To illustrate our smsp format by way of examples, here is the output of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	460 smsp-dump from old T-Mobile USA SIMs that have classic GSM 11.11 SIM
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	461 functionality:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	462
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	463 #1: SC=12063130004,0x91 PID=0x00 DCS=0x00 "T-Mobile"
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	464 #2: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	465 #3: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	466 #4: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	467
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	468 Here is the output from an Austrian S-Budget Mobile SIM from circa-2017:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	469
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	470 #1: SC=4365009000000,0x91 PID=0xFF DCS=0xFF VP=173 ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	471 #2: ""
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	472
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	473 As one can see from these examples, T-Mobile allocated 4 records for their
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	474 EF_SMSP, whereas S-Budget Mobile allocated only 2 records for theirs.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	475 (Sysmocom webshop SIMs sysmoUSIM-SJS1 and sysmoISIM-SJA2 also have 2 records in
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	476 their EF_SMSP.) Yet only the first record is actually used, and the remaining
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	477 ones are blank. Note that unlike pb-dump, smsp-dump does not skip blank
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	478 records: it displays every record (the design rationale is that the total number
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	479 of EF_SMSP records is expected to be small), and a blank record is simply one
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	480 that has no parameters present and has an empty alpha tag.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	481
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	482 The following parameters may be present in each SMSP record, appearing in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	483 smsp-dump output in the same order in which they appear in the SIM binary
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	484 record:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	485
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	486 DA= TP-Destination_Address
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	487 SC= TS-Service_Centre_Address
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	488 PID= TP-Protocol_Identifier
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	489 DCS= TP-Data_Coding_Scheme
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	490 VP= TP-Validity_Period
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	491
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	492 The phone numbers in DA= and SC= parameters are emitted in the same format as
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	493 in pb-dump, PID= and DCS= are emitted in hexadecimal with a 0x prefix, and VP=
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	494 is emitted in decimal. The alpha tag is always emitted at the end of the ASCII
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	495 line, just like in pb-dump.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	496
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	497 smsp-dump > outfile
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	498
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	499 This form of the smsp-dump command produces the same dump of EF_SMSP, but saves
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	500 it in the named file instead of sending it to the terminal.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	501
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	502 smsp-restore filename
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	503
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	504 This command reads a file written by smsp-dump and writes it back to the SIM.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	505 Both decimal and 0x-prefixed hexadecimal forms are accepted for all 3 of PID=,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	506 DCS= and VP= parameters.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	507
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	508 smsp-set rec params
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	509
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	510 This command writes a single record into SMSP directly from the command line,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	511 without going through a data file. The record index to write to must be given,
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	512 followed by one or more parameters as in DA=, SC=, PID=, DCS= or VP=. DA= and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	513 SC= phone numbers can be entered in the same relaxed form as in the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	514 pb-update-imm command, and the remaining 3 parameters can be either decimal or
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	515 0x-prefixed hexadecimal. This command leaves the alpha tag field blank.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	516
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	517 smsp-set-tag rec alpha-tag params
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	518
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	519 This command is just like smsp-set, but adds an alpha tag argument.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	520
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	521 smsp-erase-all
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	522
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	523 This command erases every record entry in EF_SMSP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	524
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	525 smsp-erase-one rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	526
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	527 This command erases the specified individual record in EF_SMSP.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	528
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	529 smsp-erase-range start-rec end-rec
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	530
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	531 This command erases the specified range of records in EF_SMSP. The starting
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	532 record must be identified by number (SIM record numbers are 1-based); the
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	533 ending record argument may be either a number or the "end" keyword.
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	534
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	535 Identifying MVNO SIMs
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	536 =====================
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	537
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	538 Many SIMs, particularly those from MVNOs, are programmed by their issuers to
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	539 cause phones to display the name of the MVNO or some other party rather than
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	540 the standard PLMN name decoded from the connected network's MCC-MNC. This
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	541 "personalization" programming can appear in EF_SPN (old style) or in EF_PNN and
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	542 EF_OPL (newer style). fc-simtool provides commands to display the content of
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	543 these SIM files in human-readable form:
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	544
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	545 spn
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	546 pnn-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	547 opl-dump
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	548
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	549 These commands take no arguments, and their human-readable output is not
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	550 explained in detail here. If you need to understand the meaning of various
da6e9d0b2ee6 data, doc, scripts: import from previous fc-pcsc-tools repo Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	551 fields in detail, please refer to 3GPP TS 51.011.

FreeCalypso > hg > fc-sim-tools

annotate doc/User-oriented-commands @ 93:6041c601304d