PurpleRestore

From The iPhone Wiki
Revision as of 15:07, 20 July 2016 by AS967 (talk | contribs)
Jump to: navigation, search

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
File:PurpleRestore logo.png
300px
PurpleRestore 5.0.1 (14GC54)
Original author(s) Apple Inc.
Developer(s) Apple Inc.
Stable release 5.0.1 (14GC54)
(latest known version)
Operating system OS X
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. PurpleRestore 5.0.1 (build 14GC54) 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. 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 jailbreak 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.

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 device 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.

Another issue is that the current publicly leaked version of PurpleRestore does not support A7+ devices, due to many changes in the A7+ architecture, BootROM, etc.

See Also