FreeCalypso > hg > freecalypso-tools
annotate doc/IMEI @ 861:cc621af29b74
CHANGES: document fc-add-ramps
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Sat, 18 Dec 2021 21:36:39 +0000 |
| parents | 232e36a227dd |
| children |
| rev | line source |
|---|---|
| 17 | 1 IMEI vs. IMEISV |
| 2 =============== | |
| 3 | |
| 4 There is a subtle distinction between an IMEI and an IMEISV. The first 14 | |
| 5 digits are the same between the two: the supposedly-world-unique number of a | |
| 6 given piece of hardware. In a traditional IMEI 15-digit number the significant | |
| 7 14 digits are followed by a Luhn check digit, whereas an IMEISV has 16 digits: | |
| 8 the 14 significant digits of the IMEI, *no* Luhn check digit, and two digits of | |
| 9 "software version". | |
| 10 | |
| 11 It is up to device manufacturers and firmware designers to decide whether or | |
| 12 not to store the Luhn check digit in the GSM device's flash or EEPROM or | |
| 13 whatever, but it is not sent over the air: instead the IMEISV is sent. It | |
| 14 appears that the GSM standard authors' intent was that the IMEI part is stored | |
| 15 immutably in each manufactured device whereas the SV digits are added by the | |
| 16 running firmware to indicate its version, but the IMEI handling scheme | |
|
725
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
17 implemented in TI's reference firmware and retained by many TI-based GSM device |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
18 manufacturers (FIC/Openmoko, Foxconn/Pirelli, some module vendors, but notably |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
19 NOT Compal) dispenses away with the IMEI vs. IMEISV distinction. |
| 17 | 20 |
| 21 IMEI storage and retrieval in TI's reference firmware | |
| 22 ===================================================== | |
| 23 | |
| 24 When running on the plain Calypso as opposed to Calypso+, TI's TCS211 reference | |
| 25 firmware supports two ways of storing and retrieving the IMEI: obfuscated and | |
| 26 unobfuscated. In both schemes the IMEI datum is stored as a file in the | |
| 27 device's flash file system (FFS), and even though the FFS filename calls it the | |
| 28 IMEI, the content of this file is really treated as the IMEISV: 16 digits are | |
| 29 stored, the firmware function responsible for reading the IMEI datum out of FFS | |
| 30 and passing it on to the rest of the fw is called cl_get_imeisv(), the code in | |
| 31 this function does not transform the 16 digits in any way, and the downstream | |
| 32 recipients of these digits treat them as the IMEISV. | |
| 33 | |
| 34 The two specific schemes offered by TCS211 fw are as follows: | |
| 35 | |
| 36 In the unobfuscated scheme (FF_PROTECTED_IMEI not defined), the so-called IMEI | |
| 37 but really IMEISV is stored in an FFS file named /pcm/IMEI. The file is 8 bytes | |
| 38 long, each byte stores two IMEISV digits, and the order of the digits within | |
| 39 each byte is reversed relative to the natural order: first the least significant | |
| 40 nibble is used, then the most significant nibble. | |
| 41 | |
| 42 In the obfuscated scheme (FF_PROTECTED_IMEI is defined), the so-called IMEI but | |
| 43 really IMEISV is stored in an FFS file named /gsm/imei.enc. The file is 16 | |
| 44 bytes long: the first 8 bytes store the 16-digit IMEISV encrypted with DES, | |
| 45 using the Calypso die ID as the key, and the last 8 bytes store that Calypso die | |
| 46 ID DES-encrypted with itself. Underneath the obfuscation, the 16 IMEISV digits | |
| 47 are stored in the 8 bytes in the natural order: first the most significant | |
| 48 nibble is used, then the least significant nibble. | |
| 49 | |
| 50 IMEI storage and retrieval schemes implemented by device manufacturers | |
| 51 ====================================================================== | |
| 52 | |
| 53 Openmoko devices use the unobfuscated IMEI storage method unchanged from TI's | |
| 54 reference fw: the factory-assigned IMEI is stored in an FFS file named | |
| 55 /pcm/IMEI, and that is where the original mokoN firmwares look for it. Further | |
| 56 blurring the distinction between the IMEI and the IMEISV, the 16 digits stored | |
| 57 in /pcm/IMEI (which the fw treats as the IMEISV) were factory-programmed as the | |
| 58 15-digit IMEI (with the Luhn check digit) with an appended 0, i.e., the SV | |
|
725
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
59 digits get set to x0 where x is the Luhn check digit. The same scheme has been |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
60 implemented on some Calypso-based packaged modem modules: Huawei GTM900-B and |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
61 one other module we call Tango. |
| 17 | 62 |
| 63 Foxconn, the makers of the Pirelli DP-L10, have used the obfuscated version of | |
| 64 TI's IMEI handling mechanism instead, with an additional twist: instead of | |
| 65 storing the 16-byte encrypted datum in /gsm/imei.enc in FFS, they have moved it | |
| 66 into their own factory data record stored in a non-FFS sector of the flash. | |
| 67 The content of the 16 digits treated as the IMEISV by the G23M component of the | |
| 68 fw is the same as Openmoko's: 15-digit IMEI with the Luhn check digit followed | |
| 69 by a 0 digit. | |
| 70 | |
|
725
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
71 Compal, the makers of Motorola C1xx phones, took a very different approach: they |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
72 completely departed from TI's way and implemented IMEI storage and retrieval |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
73 "by the book" instead - their IMEI is stored in the physically immutable OTP |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
74 cells of their Intel-style flash chip's protection register. Once we have made |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
75 this discovery, our fc-loadtool now offers a new flash compal-imei command for |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
76 reading and saving this factory IMEI. This Compal factory OTP record is a true |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
77 15-digit IMEI with the Luhn check digit at the end, no blurring between IMEI and |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
78 IMEISV here. Compal's firmwares add their own SV digits identifying different |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
79 fw versions - their version is truly done "by the book". |
| 17 | 80 |
| 81 Changing the IMEI | |
| 82 ================= | |
| 83 | |
| 84 When someone says that they wish to change the IMEI on their phone, they need | |
| 85 to be a little clearer as to what they really mean, as there are two possible | |
| 86 interpretations of the just-stated wish: | |
| 87 | |
| 88 1. Transmitting a different IMEISV toward the network by running your own | |
| 89 firmware on the device, | |
| 90 | |
| 91 or | |
| 92 | |
| 93 2. Changing the IMEI seen by the device's original proprietary firmware. | |
| 94 | |
| 95 Interpretation 1 is much easier than interpretation 2: when you are writing your | |
| 96 own firmware for an "alien" GSM device (hardware designed and made by someone | |
| 97 other than you), it is much easier to just set your own IMEISV and be done with | |
| 98 it than to figure out how to retrieve the factory-assigned one. Thus those | |
| 99 device manufacturers who try to make it more difficult to change their IMEIs | |
| 100 are actually creating the opposite effect: people will just set their own IMEISV | |
| 101 when running their own fw on their hw. | |
| 102 | |
| 103 Openmoko devices are a rare exception in that if you write your own IMEISV into | |
| 104 /pcm/IMEI in FFS, your new IMEISV will take effect not only with FreeCalypso | |
| 105 firmware, but also with the legacy mokoN fw versions, because they all look in | |
| 106 /pcm/IMEI. The same does NOT hold with Compal/Motorola or Foxconn/Pirelli | |
| 107 phones, however: if you wish to change their IMEI to be seen by their original | |
| 108 proprietary firmwares, you are on your own, as we do not currently have any | |
|
725
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
109 tools for accomplishing such a feat. Furthermore, changing the IMEI seen by |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
110 Compal's proprietary fw would require locating the IMEI reading code in their |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
111 fw and patching that code, as the IMEI record itself in the flash chip's |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
112 protection register is physically immutable. On the Pirelli DP-L10 the feat |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
113 would be simpler, as their factory data block can be rewritten - but we haven't |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
114 produced a tool for fooling Pirelli IMEIs, as there is no current need for such |
|
232e36a227dd
doc/IMEI: updated for Compal IMEI discovery
Mychaela Falconia <falcon@freecalypso.org>
parents:
17
diff
changeset
|
115 a tool. |
| 17 | 116 |
| 117 IMEI handling in FreeCalypso | |
| 118 ============================ | |
| 119 | |
| 120 The FreeCalypso family of projects has adopted the following IMEI storage and | |
| 121 retrieval scheme both for our own FreeCalypso-made hardware and for FreeCalypso | |
| 122 firmwares running on alien hardware: all of our firmware versions regardless of | |
| 123 target will look first in /etc/IMEISV, then in /pcm/IMEI when needing to obtain | |
| 124 the IMEISV for GSM operation. This is the new unified convention; previously | |
| 125 we used varying IMEISV retrieval schemes depending on the target and in | |
| 126 different FC firmware projects. The new unified convention is backward- | |
| 127 compatible with our previous schemes on every target. | |
| 128 | |
| 129 The /etc/IMEISV file is a FreeCalypso invention. The file is 8 bytes long, and | |
| 130 stores the 16 digits of the IMEISV in the natural order: first the most | |
| 131 significant nibble is used, then the least significant nibble. This nibble | |
| 132 order makes the IMEISV number directly readable in a hex dump of the file, and | |
| 133 the filename /etc/IMEISV makes it clear that the last two digits are the SV and | |
| 134 are not required to be equal to the Luhn check digit and 0. | |
| 135 | |
| 136 Both /etc/IMEISV and /pcm/IMEI can be written with the fc-fsio utility's | |
| 137 set-imeisv command: | |
| 138 | |
| 139 set-imeisv fc XXXXXXXX-YYYYYY-ZZ # write /etc/IMEISV | |
| 140 set-imeisv pcm XXXXXXXX-YYYYYY-ZZ # write /pcm/IMEI | |
| 141 | |
| 142 When working on Openmoko devices, we recommend writing your IMEISV into | |
| 143 /pcm/IMEI (set-imeisv pcm command) and not creating an /etc/IMEISV file: newer | |
| 144 FC firmware versions will look in both locations, but older FC fw versions and | |
| 145 the legacy mokoN ones look only in /pcm/IMEI. On all other targets we recommend | |
| 146 using the new /etc/IMEISV storage format, i.e., you should use the set-imeisv fc | |
| 147 variant. |