FreeCalypso > hg > freecalypso-tools

annotate doc/IMEI @ 416:30f6d1c32c6f

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