SHSH Protocol

Here is a description about the protocol that is used when iTunes requests the SHSH certificate from Apple. For details about what this is used for, please see the main article SHSH.

This is a simple HTTP (POST) request and answer. You can retry this via a Telnet session or similar. The destination host is gs.apple.com (IP 17.171.36.30 [previously 17.112.176.11]) and runs on the common port 80. The data is plaintext and not encoded in any way. For details about the HTTP protocol itself, please see RFC2616.

Sending data (request)
The request is actually a single XML encoded poperty list. It contains a dictionary which describes the target iOS version, restore behavior etc. Some of the required information can be taken from the BuildManifest.plist. BuildManifest contains some info about the firmware version and "BuildIdentities" dictionary. Inside it you can find two (or more?) build identities. Each of them contains the information which depends on every type of restore ("Erase" or "Update"). Some information is device-dependent (ECID, nonce) and is received from the device.

Request property list should have these properties:


 * @APTicket: Optional boolean value. If true, the server adds an APTicket to the request.
 * @BBTicket: The same for the BBTicket.
 * @UDID: Optional string value. Just request UDID. (ex. D9C1F33D-62E0-4D25-8068-F5F46FE80057).
 * @HostPlatformInfo: Optional(?) string value. "mac" for OS X client, "windows" for windows client (can be everything you want).
 * @Locality: Optional(?) string value. Language used for the error response (ex. "en_US");
 * @VersionInfo: Optional(?) string value. The version of 'libauthinstall' used (ex. "libauthinstall-391.0.0.1.3"). You can pass any string here.
 * ApBoardID: Integer value. Board ID of the target device. You can take this value from build manifest.
 * ApChipID: Integer value. Chip ID of the target device. You can take this value from build manifest.
 * ApECID: Integer value. ECID of the target device.
 * ApNonce: Data value. The nonce generated by your device.
 * ApProductionMode: Boolean value. Always true.
 * ApSecurityDomain: Integer value. The use is unknown. You can take this value from build manifest.
 * UniqueBuildID: Data value. This is a unique identifier for every build (different even for "Erase" and "Update" types of restore). You can take this value from build manifest.

The SHSH request also contains information about files from the IPSW (or restore bundle for PurpleRestore). They can be obtained from the 'build identity' you've chosen in the previous step. Each 'build identity' contains a "Manifest" dictionary. It's entries look like BatteryCharging0 Digest Info ...  	 Trusted They are just copied to the SHSH request, but the "Info" dictionary is removed. Example of a SHSH request (... values are identical, *** values are different per device): <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  @APTicket @BBTicket @HostPlatformInfo mac @Locality en_US @UUID D9C1F33D-62E0-4D25-8068-F5F46FE80057 @VersionInfo libauthinstall-391.0.0.1.3 ApBoardID 10 	 ApChipID 35152 	 ApECID *** 	 ApNonce ApProductionMode ApSecurityDomain 1 	 UniqueBuildID AppleLogo Digest Trusted BatteryCharging0 ... See AppleLogo dictionary. BatteryCharging1 ... 	 BatteryFull ... 	 BatteryLow0 ... 	 BatteryLow1 ... 	 BatteryPlugin ... 	 DeviceTree ... 	 KernelCache ... 	 LLB BuildString iBoot-2817.0.0.1.2~2 PartialDigest ... 	 RecoveryMode ... 	 RestoreDeviceTree ... 	 RestoreKernelCache ... 	 RestoreLogo ... 	 RestoreRamDisk ... 	 iBEC BuildString iBoot-2817.0.0.1.2~2 ... 	 iBSS BuildString iBoot-2817.0.0.1.2~2 PartialDigest ... 	 iBoot ...

Receiving data (answer)
The response is a simple HTTP POST response, containing 3 values: STATUS, MESSAGE (a description string) and REQUEST_STRING (only if the request was successful). STATUS contains numeric status, MESSAGE contains an error message on error and "SUCCESS" string on success and REQUEST_STRING contains response property list encoded as XML.

Status responses

 * STATUS=0&MESSAGE=SUCCESS
 * STATUS=94&MESSAGE=This device isn't eligible for the requested build.
 * STATUS=100&MESSAGE=An internal error occurred.
 * STATUS=511&MESSAGE=No data in the request
 * STATUS=551&MESSAGE=Error occured while importing config packet with cpsn:
 * STATUS=5000&MESSAGE=Invalid Option!

Other parameters / open questions
Some parameters could have other values. Not all details are known.
 * action=2 in the request. What other values exist and what is their meaning?
 * ApProductionMode What does this mean? Is there a test environment?
 * ApSecurityDomain Meaning?
 * Trusted What is this for?
 * Full description of the above values for UniqueBuildID, Digest, PartialDigest and BuildString.