# HG changeset patch # User Mychaela Falconia # Date 1476840372 0 # Node ID 4644799cb51551821fcf5ebf709cc92508a730b2 # Parent cc204f908f322006c97ec3eaf4e2c5ececd49dff doc/IMEI written diff -r cc204f908f32 -r 4644799cb515 doc/IMEI --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/IMEI Wed Oct 19 01:26:12 2016 +0000 @@ -0,0 +1,136 @@ +IMEI vs. IMEISV +=============== + +There is a subtle distinction between an IMEI and an IMEISV. The first 14 +digits are the same between the two: the supposedly-world-unique number of a +given piece of hardware. In a traditional IMEI 15-digit number the significant +14 digits are followed by a Luhn check digit, whereas an IMEISV has 16 digits: +the 14 significant digits of the IMEI, *no* Luhn check digit, and two digits of +"software version". + +It is up to device manufacturers and firmware designers to decide whether or +not to store the Luhn check digit in the GSM device's flash or EEPROM or +whatever, but it is not sent over the air: instead the IMEISV is sent. It +appears that the GSM standard authors' intent was that the IMEI part is stored +immutably in each manufactured device whereas the SV digits are added by the +running firmware to indicate its version, but the IMEI handling scheme +implemented in TI's reference firmware and retained by many of the TI-based GSM +device manufacturers (at least FIC/Openmoko and Foxconn/Pirelli) dispenses away +with the IMEI vs. IMEISV distinction. + +IMEI storage and retrieval in TI's reference firmware +===================================================== + +When running on the plain Calypso as opposed to Calypso+, TI's TCS211 reference +firmware supports two ways of storing and retrieving the IMEI: obfuscated and +unobfuscated. In both schemes the IMEI datum is stored as a file in the +device's flash file system (FFS), and even though the FFS filename calls it the +IMEI, the content of this file is really treated as the IMEISV: 16 digits are +stored, the firmware function responsible for reading the IMEI datum out of FFS +and passing it on to the rest of the fw is called cl_get_imeisv(), the code in +this function does not transform the 16 digits in any way, and the downstream +recipients of these digits treat them as the IMEISV. + +The two specific schemes offered by TCS211 fw are as follows: + +In the unobfuscated scheme (FF_PROTECTED_IMEI not defined), the so-called IMEI +but really IMEISV is stored in an FFS file named /pcm/IMEI. The file is 8 bytes +long, each byte stores two IMEISV digits, and the order of the digits within +each byte is reversed relative to the natural order: first the least significant +nibble is used, then the most significant nibble. + +In the obfuscated scheme (FF_PROTECTED_IMEI is defined), the so-called IMEI but +really IMEISV is stored in an FFS file named /gsm/imei.enc. The file is 16 +bytes long: the first 8 bytes store the 16-digit IMEISV encrypted with DES, +using the Calypso die ID as the key, and the last 8 bytes store that Calypso die +ID DES-encrypted with itself. Underneath the obfuscation, the 16 IMEISV digits +are stored in the 8 bytes in the natural order: first the most significant +nibble is used, then the least significant nibble. + +IMEI storage and retrieval schemes implemented by device manufacturers +====================================================================== + +Openmoko devices use the unobfuscated IMEI storage method unchanged from TI's +reference fw: the factory-assigned IMEI is stored in an FFS file named +/pcm/IMEI, and that is where the original mokoN firmwares look for it. Further +blurring the distinction between the IMEI and the IMEISV, the 16 digits stored +in /pcm/IMEI (which the fw treats as the IMEISV) were factory-programmed as the +15-digit IMEI (with the Luhn check digit) with an appended 0, i.e., the SV +digits get set to x0 where x is the Luhn check digit. + +Foxconn, the makers of the Pirelli DP-L10, have used the obfuscated version of +TI's IMEI handling mechanism instead, with an additional twist: instead of +storing the 16-byte encrypted datum in /gsm/imei.enc in FFS, they have moved it +into their own factory data record stored in a non-FFS sector of the flash. +The content of the 16 digits treated as the IMEISV by the G23M component of the +fw is the same as Openmoko's: 15-digit IMEI with the Luhn check digit followed +by a 0 digit. + +Compal, the makers of Motorola C1xx phones, have similarly moved their IMEI out +of FFS into their own proprietary flash data structures, and we have never +decoded the latter, hence we don't know exactly where and how their IMEI is +stored. If you wish to run FreeCalypso firmware on these phones, you have to +set your own IMEISV for our fw even if you are not seeking to make it different +from the factory-assigned one, as we don't know how to retrieve the latter. + +Changing the IMEI +================= + +When someone says that they wish to change the IMEI on their phone, they need +to be a little clearer as to what they really mean, as there are two possible +interpretations of the just-stated wish: + +1. Transmitting a different IMEISV toward the network by running your own + firmware on the device, + +or + +2. Changing the IMEI seen by the device's original proprietary firmware. + +Interpretation 1 is much easier than interpretation 2: when you are writing your +own firmware for an "alien" GSM device (hardware designed and made by someone +other than you), it is much easier to just set your own IMEISV and be done with +it than to figure out how to retrieve the factory-assigned one. Thus those +device manufacturers who try to make it more difficult to change their IMEIs +are actually creating the opposite effect: people will just set their own IMEISV +when running their own fw on their hw. + +Openmoko devices are a rare exception in that if you write your own IMEISV into +/pcm/IMEI in FFS, your new IMEISV will take effect not only with FreeCalypso +firmware, but also with the legacy mokoN fw versions, because they all look in +/pcm/IMEI. The same does NOT hold with Compal/Motorola or Foxconn/Pirelli +phones, however: if you wish to change their IMEI to be seen by their original +proprietary firmwares, you are on your own, as we do not currently have any +tools for accomplishing such a feat. + +IMEI handling in FreeCalypso +============================ + +The FreeCalypso family of projects has adopted the following IMEI storage and +retrieval scheme both for our own FreeCalypso-made hardware and for FreeCalypso +firmwares running on alien hardware: all of our firmware versions regardless of +target will look first in /etc/IMEISV, then in /pcm/IMEI when needing to obtain +the IMEISV for GSM operation. This is the new unified convention; previously +we used varying IMEISV retrieval schemes depending on the target and in +different FC firmware projects. The new unified convention is backward- +compatible with our previous schemes on every target. + +The /etc/IMEISV file is a FreeCalypso invention. The file is 8 bytes long, and +stores the 16 digits of the IMEISV in the natural order: first the most +significant nibble is used, then the least significant nibble. This nibble +order makes the IMEISV number directly readable in a hex dump of the file, and +the filename /etc/IMEISV makes it clear that the last two digits are the SV and +are not required to be equal to the Luhn check digit and 0. + +Both /etc/IMEISV and /pcm/IMEI can be written with the fc-fsio utility's +set-imeisv command: + +set-imeisv fc XXXXXXXX-YYYYYY-ZZ # write /etc/IMEISV +set-imeisv pcm XXXXXXXX-YYYYYY-ZZ # write /pcm/IMEI + +When working on Openmoko devices, we recommend writing your IMEISV into +/pcm/IMEI (set-imeisv pcm command) and not creating an /etc/IMEISV file: newer +FC firmware versions will look in both locations, but older FC fw versions and +the legacy mokoN ones look only in /pcm/IMEI. On all other targets we recommend +using the new /etc/IMEISV storage format, i.e., you should use the set-imeisv fc +variant.