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