PurpleRestore

From The iPhone Wiki
Jump to: navigation, search

This is one of Apple's internally used programs.
Acquiring it without Apple's consent is illegal, and may result in being scammed.

The iPhone Wiki does not encourage or promote illegal activities. This article is provided for educational purposes only.

PurpleRestore
PurpleRestore3 logo.png
PurpleRestore3.png
PurpleRestore 3.0 (251)(13A165)
Original author(s) Apple Inc.
Developer(s) Apple Inc.
Stable release 3.0 (251) (13A165)
(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 it is usually 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. 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. 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 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 still need to put your device into a 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 that was 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 does'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 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 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