PurpleRestore

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.

File:PurpleRestore logo.png
300px PurpleRestore 4.0.0b (11D903)
Original author(s)	Apple Inc.
Developer(s)	Apple Inc.
Stable release	4.0.0b (11D903) (latest known version)
Operating system	OS X
Size	?
Available in	English
Type	?
License	Closed source

PurpleRestore is a tool made by Apple and is used for flashing iDevices. It provides far more customization than iTunes, and it is usually used to flash internal firmware to prototypes. PurpleRestore 4.0.0b (beta build 11D903) is the latest known version which is capable of detecting devices running/flashing the latest restore bundles (Betas/Stock/NonUI/etc.). Little is currently known about which versions it "supports" for restoring as such. PurpleRestore is installed by RestoreTools.pkg. A CLI version of PurpleRestore exists too.

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 (Purple or Green). Like iTunes, PurpleRestore communicates with iDevices using a usbmux connection.

Restore Bundles

Unlike iTunes, PurpleRestore doesn't use IPSW files to restore devices. It uses "Restore Bundles" which can be obtained from a server specific to a version of iOS, such as afp://fieldgoal.apple.com/RestoreImages/ and afp://endzone.apple.com/OldRestoreImages/ (among many others) . Unfortunately, the afp protocol can only be accessed through Apple's internal VPN which means that the tool is essentially useless, because it can only install currently signed iOS.

However, you can create your own bundles by extracting an IPSW into a folder, this only applies to firmwares that 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 need to put your device into Pwned DFU still. This will not give you any internal debugging abilities nor root your device.

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 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 plist files 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.

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.

Off   Virt Adr  Instruction     Disassembly            Comment

+354  003d7808  c70424bc01d700  mov [esp], 0x00d701bc  ; CFSTR("com.apple.PurpleRestore")
+361  003d780f  e80c65c3ff      call 0x10000dd20       ; is specified bundle running
+366  003d7814  84c0            test al, al
+368  003d7816  7409            jz short 0x003d7821    ; if so, PurpleRestore is running
+370  003d7818  c704246c8ba400  mov [esp], 0x00a48b6c  ; so ignore device,
+377  003d781f  ebd3            jmp short 0x003d77f4   ; and jump back above loop for next device
+379  003d7821  8d5de0          lea ebx, [ebp + 0xe0]
+382  003d7824  895c2404        mov [esp + 4], ebx

Problems

There are some problems with the leaked versions, because they almost always aren't the latest version.

Stuck on Executing iBEC

One problem (common) is getting stuck at "Executing iBEC to bootstrap update". This is likely is a signing error, the device may have rejected the iBEC image.

Another problem, when trying from DFU mode, the tool will send the DFU image, then the device will disconnect, reconnect, and repeat the process indefinitely.

See Also

• iTunes
• Video of process