SHSH Protocol

Here is a description of 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 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.

Communication
Reliable communication to the TSS server is best achieved with the following HTTP header configuration:



The following curl command demonstrates a command-line request to the server:

curl -i -s -m 1.0 -X POST -A "InetURL/1.0" -H "Proxy-Connection: Keep=Alive" -H "Pragma: no-cache" -H "Content-Type: text/xml; charset=\"utf-8\"" -d @/location/to/TSSRequest.xml gs.apple.com/TSS/controller?action=2

Action types
Attached to the http://gs.apple.com/TSS/controller URL is commonly, which can be discovered when performing an iTunes restore and observing packets sent with a packet sniffer such as Wireshark. However, values other than 2 may produce different server responses, of which all known value/response pairs have been listed below.


 * : Performs a "Tatsu Signing Server HealthCheck", returning an HTML body of "Server not ready". This may be a general ping protocol for ensuring the TSS service is online.
 * : Common SHSH protocol. See for all known server responses.
 * : Functionally the same as.
 * : Generates  and  . This response syntax differs slightly from the SHSH protocol. The name "cpsn" is referenced.

All unlisted action types appear to respond without HTML content, only status.

Sending data (request)
The request is actually a single XML-encoded property 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: Optional boolean value. 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 (unless your SOC is PROD 0 - Apple only).
 * ApSecurityDomain: Integer value. The use is unknown. You can take this value from build manifest.
 * UniqueBuildID: Optional 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
 * The request was sent successfully, and a response was returned.'''
 * STATUS=8&MESSAGE=An internal error occurred.
 * A key contained an unknown name.
 * STATUS=69&MESSAGE=This device isn't eligible for the requested build.
 * STATUS=83&MESSAGE=An internal error occurred.
 * A key was assigned an invalid value type.
 * STATUS=92&MESSAGE=An internal error occurred.
 * The request contained more than 65536 bytes.
 * STATUS=93&MESSAGE=An internal error occurred.
 * The request contained less than 10 bytes.
 * STATUS=94&MESSAGE=This device isn't eligible for the requested build.
 * The specified build is either unsigned or nonexistent.
 * STATUS=98&MESSAGE=An internal error occurred.
 * The XML/PList identification tag is missing or the start of the tag is malformed.
 * STATUS=100&MESSAGE=An internal error occurred.
 * A general XML error was found: the XML/PList version is nonexistent or not "1.0", the end of the XML/PList identification tag is malformed, an unknown or empty tag was found, the root  tag is missing, no keys were found, a value tag contained an invalid type, an unescaped ampersand character was found, two consecutive dash characters were found in a comment, or a tag was found without its counterpart.
 * STATUS=103&MESSAGE=An internal error occurred.
 * Multiple '@' characters were found at the beginning of a key name.
 * STATUS=128&MESSAGE=An internal error occurred.
 * STATUS=131&MESSAGE=An internal error occurred.
 * TBD: Something to do with ?
 * STATUS=132&MESSAGE=An internal error occurred.
 * STATUS=133&MESSAGE=An internal error occurred.
 * The  key is missing in a Baseband install.
 * 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.
 * ApSecurityDomain: Meaning? (Related to SDOM tag)
 * Trusted: What is this for?
 * Full description of the above values for UniqueBuildID, Digest, PartialDigest and BuildString.

PartialDigest
The PartialDigest is structured like so:

typedef struct PartialDigest { uint32_t transformSize;    // Always 0x40. uint32_t img3DataSize;     // data size of the img3. uint8_t hash[SHA1HashSize]; // Result of SHA1ResultPartial from the stripped img3. };

The img3 is first stripped of it's code signature (if present) and then passed through SHA1Update. SHA1ResultPartial is then performed. It is purposely not the final resulting SHA1. The reason for this being, when TSS processes the PartialDigest, it performs one more SHA1Update on the hash to include the ECID before doing SHA1Final and creating the SHSH blob.

Code for SHA1ResultPartial: int SHA1ResultPartial(SHA1Context* ctx, unsigned char* buf) { // Do we have valid buffer and context pointers? if(ctx && buf) { // Is the Context in good shape? if(!ctx->Corrupted && !ctx->Computed && !ctx->Message_Block_Index) { for(int i = 0; i < SHA1HashSize; i++) { buf[i] = ctx->Intermediate_Hash[i >> 2] >> 8 * (3 - (i & 0x3)); } 			return 0; } 	} 	return 1; } Code for tss_strip_img3_signature: int tss_strip_img3_signature(img3Header* img3, int* len) { // Do we have a non-null ptr? if(!img3) { return 10004; } 	// Does the buffer start with the img3 magic? if(img3->magic != IMG3_MAGIC) { printf("tss_strip_img3_signature: bad magic 0x%08x expecting 0x%08x\n", img3->magic, IMG3_MAGIC); return 10004; } 	// Sanity checks if(img3->shshOffset > img3->dataSize) { printf("tss_strip_img3_signature: signed length %u too large for buffer length %u\n", img3->shshOffset, img3->dataSize); return 10004; } 	// Trim the image by adjusting the header. if(img3->shshOffset) { *len += img3->shshOffset - img3->dataSize; img3->dataSize = img3->shshOffset; img3->fullSize = *len; } 	return 0; }

Digest
Digest is the SHA1 of the stripped img3. They are used instead of PartialDigests for the APTicket since the ticket is already personalized for the ECID and all other tags.