Difference between revisions of "PurpleRestore"

From The iPhone Wiki
Jump to: navigation, search
(Grammar fix, completed sentence)
(attempt to address inaccuracies)
(48 intermediate revisions by 15 users not shown)
Line 1: Line 1:
  +
{{internal software}}
{{internalsw}}
 
 
{{Infobox software
 
{{Infobox software
 
| name = PurpleRestore
 
| name = PurpleRestore
| title =
+
| title = PurpleRestore
| logo = [[File:PurpleRestore logo.png]]
+
| logo = [[File:PurpleRestore3_logo.png|150px]]
| screenshot = [[File:PurpleRestore11A437.png|300px]]
+
| screenshot = [[File:PurpleRestore3.png|300px]]
| caption = PurpleRestore 106.00 (11A437)
+
| caption = PurpleRestore 3.0 (313.1.5.1.1)(14A83432a)
 
| collapsible =
 
| collapsible =
 
| author = Apple Inc.
 
| author = Apple Inc.
Line 11: Line 11:
 
| released =
 
| released =
 
| discontinued =
 
| discontinued =
| latest release version = 106.00<br /><small>(latest ''known'' version)</small>
+
| latest release version = 3.0 (313.1.5.1.1) (14A83432a)<br /><small>(latest ''known'' version)</small>
 
| latest release date =
 
| latest release date =
 
| latest preview version =
 
| latest preview version =
 
| latest preview date =
 
| latest preview date =
 
| programming language =
 
| programming language =
| operating system = [[wikipedia:OS X|OS X]]
+
| operating system = [[wikipedia:macOS|macOS]]
 
| platform =
 
| platform =
| size = 4,096,348 bytes [APP] <small>(106.00)</small>
+
| size =
 
| language = [[wikipedia:English language|English]]
 
| language = [[wikipedia:English language|English]]
 
| status =
 
| status =
| genre = ?
+
| genre = Firmware flasher
 
| license = [[wikipedia:Proprietary software|Closed source]]
 
| license = [[wikipedia:Proprietary software|Closed source]]
 
| website =
 
| website =
 
}}
 
}}
 
{{float toc|left}}
 
{{float toc|left}}
'''PurpleRestore''' is a tool made by Apple and is used for flashing [[iDevice]]s. It provides far more customization than [[iTunes]], and it is usually used to flash internal firmware to [[Prototypes|prototypes]]. PurpleRestore-106.00 (build 11A437) is the latest known version which is capable of detecting devices running the latest iOS 7 beta. Little is currently known about which versions it "supports" for restoring as such. A command line version of PurpleRestore exists as well, and it is installed by [[RestoreTools]].pkg.
+
'''PurpleRestore''' is a tool made by Apple and is used for flashing [[iDevice]]s. It provides far more customization than [[iTunes]], and is known to be used to flash internal firmware to [[prototypes]]. Little is currently known about which versions it "supports" for restoring as such. PurpleRestore is installed by [[RestoreTools.pkg]] or Home Diagnostics. A CLI version of PurpleRestore is included.
   
This tool can (and is meant) to handle multiple restores. When performing restores PurpleRestore color coordinates the device in the table and when the device is about to receive the AppleLogo (See iPhone 5 undergoing a PurpleRestore) it will turn the background color of the screen purple.
+
This tool can (and is meant to) handle multiple restores. When performing restores, PurpleRestore color coordinates the device in the table and when the device is about to receive the AppleLogo it will turn the background color of the screen to the color assigned to the device. Like [[iTunes]], PurpleRestore communicates with devices using a [[usbmux]] connection.
Like [[iTunes]], [[PurpleRestore]] communicates with iDevices using a [[usbmux]] connection.
 
   
== Restore Bundles==
+
== Restore Bundles ==
Unlike iTunes, PurpleRestore doesn't use [[IPSW File Format|IPSW]] files to restore devices. It uses "Restore Bundles" which can be obtained from a server specific to a version of iOS, such as <code>afp://fieldgoal.apple.com/RestoreImages/</code> and <code>afp://endzone.apple.com/OldRestoreImages/</code> (among many others) . Unfortunately, the <code>afp</code> protocol can only be accessed through Apple's internal VPN.
+
PurpleRestore uses "Restore Bundles" which can be obtained from a server specific to versions of iOS, such as <code>afp://fieldgoal.apple.com/RestoreImages/</code> and <code>afp://endzone.apple.com/OldRestoreImages/</code> (among many others) . Unfortunately, these <code>afp</code> servers can only be accessed through Apple's internal VPN. PurpleRestore is essentially useless to the general public, because it can only install currently signed iOS versions without having Apple VPN access.
   
However, you can create your own bundles by extracting an IPSW into a folder. The downside is that you don't get access to any internal/debugging stuff since it is a public firmware.
+
You can create your own bundles by extracting an IPSW into a folder, and restore them if they are being signed; or if you have SHSH blobs saved for an A4 device (and below) then you can either stitch or use [[TinyUmbrella]] to assist in a downgrade without the need for iTunes; you will still need to put your device into pwned DFU Mode. This will not give you any internal debugging abilities nor jailbreak your device.
  +
  +
As of PurpleRestore 3, an IPSW may be used in place of a restore bundle.
   
 
== Restore Components ==
 
== Restore Components ==
 
Restore Components has several options:
 
Restore Components has several options:
 
* '''Restore Bundle''': Specify the bundle to use in restoring
 
* '''Restore Bundle''': Specify the bundle to use in restoring
* '''Firmware Directory''': Specify the folder where the [[LLB]], [[iBoot (Bootloader)|iBoot]], etc. [[IMG3 File Format|IMG3]] files are located.
+
* '''Firmware Directory''': Specify the folder where the [[LLB]], [[iBoot (Bootloader)|iBoot]], etc. [[IMG3 File Format|IMG3]]/[[IMG4 File Format|IMG4]] files are located.
 
* '''Ramdisk Image''': Specify a [[ramdisk]] to be used (i.e. [[Restore Ramdisk|restore]] or [[Update Ramdisk|update]] ramdisk)
 
* '''Ramdisk Image''': Specify a [[ramdisk]] to be used (i.e. [[Restore Ramdisk|restore]] or [[Update Ramdisk|update]] ramdisk)
 
* '''DFU''': Specify what tools to upload based on a selection of "Debug", "Development", or "Release". A specific file can also be selected.
 
* '''DFU''': Specify what tools to upload based on a selection of "Debug", "Development", or "Release". A specific file can also be selected.
   
 
== Restore Operations ==
 
== Restore Operations ==
  +
[[File:IPhoneDuringPurpleRestore.jpeg|250px|thumb|right|iPhone 5 undergoing a PurpleRestore]]
 
Restore Operations contains the most options to configure. These may also be the most useful ones.
 
Restore Operations contains the most options to configure. These may also be the most useful ones.
   
 
* '''Hardware Readiness'''
 
* '''Hardware Readiness'''
** '''Minimum Battery Charge (mV)''': This value controls the minimum charge level at which the restore will be allowed to continue. Below this threshold, we either wait to charge (if we're charging) or fail (if we're not charging). If this option is not specified, a default value is used (currently 3.8V). Setting this option to 0 bypasses all battery level checks.
+
** '''Minimum Battery Charge (mV)''': This value controls the minimum charge level at which the restore will be allowed to continue. Below this threshold, we either wait to charge (if we're charging) or fail (if we're not charging). If this option is not specified, a default value is used (currently 3.8&nbsp;V). Setting this option to 0 bypasses all battery level checks.
 
** '''Wait for Minimum Charge''': If the current voltage is below the minimum level, then the default behavior is to let the device charge and then continue. This option overrides that behavior when false.
 
** '''Wait for Minimum Charge''': If the current voltage is below the minimum level, then the default behavior is to let the device charge and then continue. This option overrides that behavior when false.
 
** '''Wait for Storage Device''': Controls whether the restore waits for the storage device /dev/disk0 to be available before the restore is initiated.
 
** '''Wait for Storage Device''': Controls whether the restore waits for the storage device /dev/disk0 to be available before the restore is initiated.
Line 63: Line 65:
 
** '''Update Baseband''': Controls whether the [[baseband]] and baseband bootloader are updated as part of the restore.
 
** '''Update Baseband''': Controls whether the [[baseband]] and baseband bootloader are updated as part of the restore.
 
** '''Force Update''': The baseband update is skipped when the existing firmware matches the available firmware. In some cases, it is desirable to force the firmware update to occur, regardless of what is currently on there. This option, when set to true, forces the update to be attempted.
 
** '''Force Update''': The baseband update is skipped when the existing firmware matches the available firmware. In some cases, it is desirable to force the firmware update to occur, regardless of what is currently on there. This option, when set to true, forces the update to be attempted.
[[File:IPhoneDuringPurpleRestore.jpeg|250px|thumb|right|iPhone 5 undergoing a PurpleRestore]]
 
 
   
 
== Restore OS ==
 
== Restore OS ==
Line 73: Line 73:
 
* '''Boot Kernel Cache:''' Specify whether the "Production" or "Development" kernel cache should be used.
 
* '''Boot Kernel Cache:''' Specify whether the "Production" or "Development" kernel cache should be used.
   
==Personalization Settings==
+
== Personalization Settings ==
 
As with iTunes, PurpleRestore can personalize builds for iOS devices (since recent Bootroms expect a valid APTicket). The tooltip for the "Personalized Restore" checkbox reads "Your ticket to the Orwellian cloud." This may suggest that Apple developed TSS in part to control access to internal build variants (i.e. prevent leaks of "interesting" builds of iOS), in addition to preventing production users from downgrading.
 
As with iTunes, PurpleRestore can personalize builds for iOS devices (since recent Bootroms expect a valid APTicket). The tooltip for the "Personalized Restore" checkbox reads "Your ticket to the Orwellian cloud." This may suggest that Apple developed TSS in part to control access to internal build variants (i.e. prevent leaks of "interesting" builds of iOS), in addition to preventing production users from downgrading.
 
* '''Variants''': "A predefined combination of restore pieces." The options are: "Customer Install", "Internal Debug", "Internal Development", "Internal Install", "Internal Qualification", and "Vendor install."
 
* '''Variants''': "A predefined combination of restore pieces." The options are: "Customer Install", "Internal Debug", "Internal Development", "Internal Install", "Internal Qualification", and "Vendor install."
Line 79: Line 79:
   
 
== Restore Settings ==
 
== Restore Settings ==
  +
[[File:PurpleRestoreOptions.png|250px|thumb|right|PurpleRestore configuration screen]]
By default, PurpleRestore comes with two pre-made restore settings. "Erase Install" and "Update Install". Those restore settings are [[PList File Format|plist]] files that define the options PurpleRestore will use when restoring a device.
 
  +
By default, PurpleRestore comes with two pre-made restore settings. "Erase Install" and "Update Install". Those restore settings are [[wikipedia:property list|property list]]s that define the options PurpleRestore will use when restoring a device.
 
* '''Erase Install''': Repartition the media and erase all data before restoring. Includes all internal development tools and updates flash and the baseband by default.
 
* '''Erase Install''': Repartition the media and erase all data before restoring. Includes all internal development tools and updates flash and the baseband by default.
 
* '''Update Install''': Includes all internal development tools and updates flash and the baseband by default.
 
* '''Update Install''': Includes all internal development tools and updates flash and the baseband by default.
  +
{{clear}}
   
  +
== PurpleRestore 3 ==
[[File:PurpleRestoreOptions.png |250px|thumb|right|PurpleRestore configuration screen]]
 
  +
PurpleRestore 3 is the latest known version of PurpleRestore. It was initially leaked on Twitter in October 2016. The update sports a redesigned user interface and icon, support for IPSW files, and revealed the existence of an internal PurpleRestore wiki, which most likely requires access to Apple's internal VPN. The boot screen on the device doesn't turn purple when restoring with the tool without a debug UART cable, unlike previous versions of the tool. PurpleRestore 3 also has full macOS Sierra support, which was broken in most of the previous builds.
   
  +
The updated utility also allows you to flash a custom boot logo, but it likely requires it to be decrypted. It is currently believed that it makes a new IMG3 container for the image, and discards the old one before flashing to the correct place in NAND/NOR.
== Reverse Engineering ==
 
This specific code is from [[iTunes]] for OS X. It detects if PurpleRestore is running so that it does not interfere with any operations that PurpleRestore is performing.
 
   
  +
== Problems ==
Off Virt Adr Instruction AT&T Syntax Intel Syntax Comment
 
  +
There are some problems with the leaked versions, because they may not support current devices or iOS versions.
 
+354 003d7808 c70424bc01d700 movl $0x00d701bc, (%esp) mov [esp], 0x00d701bc ; CFSTR("com.apple.PurpleRestore")
 
+361 003d780f e80c65c3ff calll 0x10000dd20 call 0x10000dd20 ; is specified bundle running
 
+366 003d7814 84c0 testb %al,%al test al, al
 
+368 003d7816 7409 jz 0x003d7821 jz short 0x003d7821 ; if so, PurpleRestore is running
 
+370 003d7818 c704246c8ba400 movl $0x00a48b6c, (%esp) mov [esp], 0x00a48b6c ; so ignore device,
 
+377 003d781f ebd3 jmp 0x003d77f4 jmp short 0x003d77f4 ; and jump back above loop for next device
 
+379 003d7821 8d5de0 leal 0xe0(%ebp), %ebx lea ebx, [ebp + 0xe0]
 
+382 003d7824 895c2404 movl %ebx, 0x04(%esp) mov [esp + 4], ebx
 
   
==Problems==
 
Those people who have their hands on it (by some way unknown) don't always have the best luck. There are some problems with the leaked versions, because they can't be current, Apple surely tracks the builds on the internet.
 
 
One problem (common) is getting stuck at "Executing iBEC to bootstrap update". My guess is that this is a signing error, the device may have rejected the iBEC image.
 
 
[[File:IBECStuck.png|250px|thumb|right|Stuck on Executing iBEC]]
 
[[File:IBECStuck.png|250px|thumb|right|Stuck on Executing iBEC]]
  +
One problem (common) is getting stuck at "Executing iBEC to bootstrap update". This is likely a signing error; the device may have rejected the iBEC image due to an invalid or missing APTicket, trying to use AppleConnect, the TSS server is no longer accepting signatures for the version you are installing, or the nonce has been mismatched.
Another problem, when trying from DFU mode, the tool will send the DFU image, then the device will disconnect, reconnect, and repeat the process indefinately.
 
  +
  +
Another problem can be encountered when a device is in [[DFU Mode]]; the tool will send the DFU image, and the iDevice will repeatedly disconnect and reconnect.
  +
  +
If you check "Allow baseband roll-backs", disable "Allow AppleConnect", and uncheck using of LwVM under Editor, selecting Personalized IPSW will cause PurpleRestore to freeze on "Waiting for device" and creates another session with "IDLE" status. If you then try to select that new session and try the same settings, it starts the restore process and successfully restore the IPSW to device.
  +
  +
Versions older than PurpleRestore 3 do not support A7+ devices, due to many changes in newer architectures, BootROM, etc.
  +
  +
PurpleRestore 3 also is supposed to have icons for each device plugged in, but many devices (including iPhones) don't have icons; they are replaced with a grey question mark.
   
 
== See Also ==
 
== See Also ==

Revision as of 00:23, 18 November 2017

This article discusses software internally used by Apple.

Acquiring a copy without Apple's consent is illegal and may result in being scammed.
Engaging in illegal activity is not condoned. This information is provided for educational purposes only.

PurpleRestore
PurpleRestore3 logo.png
PurpleRestore3.png
PurpleRestore 3.0 (313.1.5.1.1)(14A83432a)
Original author(s) Apple Inc.
Developer(s) Apple Inc.
Stable release 3.0 (313.1.5.1.1) (14A83432a)
(latest known version)
Operating system macOS
Available in English
Type Firmware flasher
License Closed source

PurpleRestore is a tool made by Apple and is used for flashing iDevices. It provides far more customization than iTunes, and is known to be used to flash internal firmware to prototypes. Little is currently known about which versions it "supports" for restoring as such. PurpleRestore is installed by RestoreTools.pkg or Home Diagnostics. A CLI version of PurpleRestore is included.

This tool can (and is meant to) handle multiple restores. When performing restores, PurpleRestore color coordinates the device in the table and when the device is about to receive the AppleLogo it will turn the background color of the screen to the color assigned to the device. Like iTunes, PurpleRestore communicates with devices using a usbmux connection.

Restore Bundles

PurpleRestore uses "Restore Bundles" which can be obtained from a server specific to versions of iOS, such as afp://fieldgoal.apple.com/RestoreImages/ and afp://endzone.apple.com/OldRestoreImages/ (among many others) . Unfortunately, these afp servers can only be accessed through Apple's internal VPN. PurpleRestore is essentially useless to the general public, because it can only install currently signed iOS versions without having Apple VPN access.

You can create your own bundles by extracting an IPSW into a folder, and restore them if they are being signed; or if you have SHSH blobs saved for an A4 device (and below) then you can either stitch or use TinyUmbrella to assist in a downgrade without the need for iTunes; you will still need to put your device into pwned DFU Mode. This will not give you any internal debugging abilities nor jailbreak your device.

As of PurpleRestore 3, an IPSW may be used in place of a restore bundle.

Restore Components

Restore Components has several options:

  • Restore Bundle: Specify the bundle to use in restoring
  • Firmware Directory: Specify the folder where the LLB, iBoot, etc. IMG3/IMG4 files are located.
  • Ramdisk Image: Specify a ramdisk to be used (i.e. restore or update ramdisk)
  • DFU: Specify what tools to upload based on a selection of "Debug", "Development", or "Release". A specific file can also be selected.

Restore Operations

iPhone 5 undergoing a PurpleRestore

Restore Operations contains the most options to configure. These may also be the most useful ones.

  • Hardware Readiness
    • Minimum Battery Charge (mV): This value controls the minimum charge level at which the restore will be allowed to continue. Below this threshold, we either wait to charge (if we're charging) or fail (if we're not charging). If this option is not specified, a default value is used (currently 3.8 V). Setting this option to 0 bypasses all battery level checks.
    • Wait for Minimum Charge: If the current voltage is below the minimum level, then the default behavior is to let the device charge and then continue. This option overrides that behavior when false.
    • Wait for Storage Device: Controls whether the restore waits for the storage device /dev/disk0 to be available before the restore is initiated.
    • Allow Untethered Restore: Permit the restore to run untethered (not connected to a host). The result of specifying this option when the restore needs data from the host (for instance, when flashing NOR) is undefined (but probably bad). If this option is specified and the device remains tethered, things should proceed as usual.
  • Storage Media
    • Use LwVM: Controls whether the device is formatted for LwVM (if supported).
    • Repartition: Controls whether a new partition map is created on the device.
    • System Partition Size (MiB): Specifies the size (in mebibytes) that is desired for the system partition. Because the partition size can only be changed when creating a new partition map, this option is only relevant when used in conjunction with repartition. A size of 0 indicates that the restore library should choose a suitable size for you, based on the specific restore bundle and image being used if possible.
    • Content Protection Type: Controls the type of data protection used on the device.
    • Low-Level Erase: Do a low level erase (wipe with null or random data) of the entire storage device prior to restoring.
  • Restore System Partition
    • System Image: Determines which type of system image to restore, or which file to use for the system image.
    • Kernel Cache Type: This option controls the kernel cache that gets installed on the device.
  • Baseband
    • Update Baseband: Controls whether the baseband and baseband bootloader are updated as part of the restore.
    • Force Update: The baseband update is skipped when the existing firmware matches the available firmware. In some cases, it is desirable to force the firmware update to occur, regardless of what is currently on there. This option, when set to true, forces the update to be attempted.

Restore OS

Restore OS options allow you to specify the following:

  • Restore Boot-Args: Boot-Args used when the Restore OS is loaded. By default those arguments are used: "debug=0x14e serial=3 rd=md0 nand-enable-reformat=1 -progress"
  • Firmware Type: Specify the firmware which should be flashed when restoring. This can either be "Debug", "Factory FA", "Factory SA", "Firmware Development" or "Production".
  • Boot Image Type: Can be "Internal", "User or Internal", "User" or "Update".
  • Boot Kernel Cache: Specify whether the "Production" or "Development" kernel cache should be used.

Personalization Settings

As with iTunes, PurpleRestore can personalize builds for iOS devices (since recent Bootroms expect a valid APTicket). The tooltip for the "Personalized Restore" checkbox reads "Your ticket to the Orwellian cloud." This may suggest that Apple developed TSS in part to control access to internal build variants (i.e. prevent leaks of "interesting" builds of iOS), in addition to preventing production users from downgrading.

  • Variants: "A predefined combination of restore pieces." The options are: "Customer Install", "Internal Debug", "Internal Development", "Internal Install", "Internal Qualification", and "Vendor install."
  • AppleConnect: Used to authenticate all restores for personalization. Interestingly, AppleConnect will allow members of the iOS Developer Program (including non-employees) to install public builds of iOS (latest current and beta). It's likely AppleConnect is also used to authenticate signing of internal builds using the public TSS server, should the device be on the whitelist.

Restore Settings

PurpleRestore configuration screen

By default, PurpleRestore comes with two pre-made restore settings. "Erase Install" and "Update Install". Those restore settings are property lists that define the options PurpleRestore will use when restoring a device.

  • Erase Install: Repartition the media and erase all data before restoring. Includes all internal development tools and updates flash and the baseband by default.
  • Update Install: Includes all internal development tools and updates flash and the baseband by default.

PurpleRestore 3

PurpleRestore 3 is the latest known version of PurpleRestore. It was initially leaked on Twitter in October 2016. The update sports a redesigned user interface and icon, support for IPSW files, and revealed the existence of an internal PurpleRestore wiki, which most likely requires access to Apple's internal VPN. The boot screen on the device doesn't turn purple when restoring with the tool without a debug UART cable, unlike previous versions of the tool. PurpleRestore 3 also has full macOS Sierra support, which was broken in most of the previous builds.

The updated utility also allows you to flash a custom boot logo, but it likely requires it to be decrypted. It is currently believed that it makes a new IMG3 container for the image, and discards the old one before flashing to the correct place in NAND/NOR.

Problems

There are some problems with the leaked versions, because they may not support current devices or iOS versions.

Stuck on Executing iBEC

One problem (common) is getting stuck at "Executing iBEC to bootstrap update". This is likely a signing error; the device may have rejected the iBEC image due to an invalid or missing APTicket, trying to use AppleConnect, the TSS server is no longer accepting signatures for the version you are installing, or the nonce has been mismatched.

Another problem can be encountered when a device is in DFU Mode; the tool will send the DFU image, and the iDevice will repeatedly disconnect and reconnect.

If you check "Allow baseband roll-backs", disable "Allow AppleConnect", and uncheck using of LwVM under Editor, selecting Personalized IPSW will cause PurpleRestore to freeze on "Waiting for device" and creates another session with "IDLE" status. If you then try to select that new session and try the same settings, it starts the restore process and successfully restore the IPSW to device.

Versions older than PurpleRestore 3 do not support A7+ devices, due to many changes in newer architectures, BootROM, etc.

PurpleRestore 3 also is supposed to have icons for each device plugged in, but many devices (including iPhones) don't have icons; they are replaced with a grey question mark.

See Also