iPhone Protocol Document

This is a document containing all of the knowledge the iFuse project currently has about the communication protocols utilized between iTunes and the iPhone (and other such devices such as the iPod Touch). This document may or may not pertain to the iPhone 3G as well -- this hasn't been tested yet, to my knowledge.

This document has been entirely rewritten by FxChiP -- if you need the old one for any reason, here it is.

The USBMux protocol

The USBMux protocol is a TCP-like protocol over which all communications between device and program are done. The format of its headers is such:

Packet Length - the length of the entire packet, including header

Src Port and Dst Port - just like in TCP, the src port indicates what port a client is connecting from, and the dst port indicates the port the client is connecting to, i.e. 0xf27e for lockdownd.

SCnt - Self count. The count of how many bytes the sending client has sent, minus the sizes of USBMux headers.

OCnt - The count of how many bytes the client has received, minus the sizes of USBMux headers.

Offset -- the first four bits (i.e. first digit in the hexadecimal number) indicate how many 32-bit segments exist in the header. They only count the bytes AFTER the USBMux type and length (i.e. the only part that can be loosely considered TCP).

The interesting part of this is that the second digit (second 4 bits), which are marked as "Reserved" by the TCP spec, can be set to something other than 0... but never seems to get interpreted by iTunes or the iPhone.

TCP flags -- identical to how TCP/IP does flags. The three-way TCP connection handshake, SYN->SYN/ACK->ACK, is followed here down to the hex numbers used for each step, and it uses RST to close connections. SYN is 0x10, SYN/ACK is 0x12, ACK is 0x02, RST is 0x04.

Window -- Window, in the TCP spec, is how many bytes the client expects to receive. It's almost universally 0x0200. This would seem ridiculous given that bytes larger than 512 bytes in size come down the line regularly, until you consider that iTunes shifts this value left by 8 bits in a 32-bit integer and gets a value of 131072 or so.

The next two bytes after window are almost always (if not always) 0x0000 if sent by iTunes, and sometimes some other value if sent by the phone -- I'm not sure what it means coming from the phone, but it doesn't seem to be too terribly important just yet.

Length/reserved -- when iTunes is sending, this field is a 16-bit copy of the earlier 32-bit field. When the device is sending, this could be anything and doesn't seem to matter all that much either....

---

When the iPhone or iPod Touch receives a USBMux header, it takes the information from it and bridges that into a connection to a service running on whichever device it is, unless there's no service running (in which case it sends you an RST packet). That's when you get into other protocols, such as the lockdownd protocol, which will be discussed here.

The lockdownd protocol

Lockdownd is the service that is responsible for pairing the device, validating device pairings, starting services, and a lot of other things. Its protocol is fairly basic -- you send PropertyList XML packets back and forth, like so:

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
<key>Request</key> 
<string>QueryType</string> 
</dict> 
</plist>

And you get a response like:

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
<key>Request</key> 
<string>QueryType</string> 
<key>Result</key> 
<string>Success</string> 
<key>Type</key> 
<string>com.apple.mobile.lockdown</string> 
</dict> 
</plist>

Those are, coincidentally, the first couple of messages between an iPhone and iTunes -- but it's not necessary. In fact, validating pairings and pairing isn't exactly necessary either, but you do have to have a valid HostID -- and you get one of those by pairing, ironically enough. Validating is just a way to make sure everything's operating okay and that the iPhone remembers iTunes.

When you want to start a session, you send one of these:

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
<key>HostID</key> 
<string>[HostID]</string> 
<key>Request</key> 
<string>StartSession</string> 
</dict> 
</plist>

And if you receive one of these, you're golden:

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
<key>EnableSessionSSL</key> 
<true/> 
<key>Request</key> 
<string>StartSession</string> 
<key>Result</key> 
<string>Success</string> 
<key>SessionID</key> 
<string>2AAD5ED1-CE2D-435D-9B8E-3FBA7E332DB7</string> 
</dict> 
</plist>

But now your client needs to begin an SSL handshake, so it can start services. Probably the easiest way to do this is through GnuTLS.

For more details, there is a full lockdownd protocol dump available.

AFC protocol

AFC is a service that must be started through lockdownd (see above). It has a distinctive signature, and intersperses lengths about. There's honestly probably a lot more information on its format over at the Old Protocol Documentation, but it's all raw and un-interpreted. Just strip the first 28 bytes out of it and it's the entire packet.

This is the service that allows you to do file and directory operations without SSH or FTP over USB. Still not sure on all the specifics. Someone with more information should write here!

SSL Traffic

The SSL traffic is version 3.0.

Reading a File

This request follows a request for information for "/iTunes_Control/iTunes/iTunesDB". Since the file name is not present in the request it seems to make sense that the position of the command in relation to the other commands in the stream is used to determine which file to send.

Request

00000000: 00 00 00 06 00 00 00 54 05 00 c0 c3 00 00 cf ac |        T  Àà  Ϭ
00000010: 00 01 1f 93 5c 10 02 00 00 00 00 54 43 46 41 36 |    “\      TCFA6
00000020: 4c 50 41 41 38 00 00 00 00 00 00 00 38 00 00 00 | LPAA8       8   
00000030: 00 00 00 00 1c 03 00 00 00 00 00 00 0f 00 00 00 |                 
00000040: 00 00 00 00 02 00 00 00 00 00 00 00 00 00 02 00 |                 
00000050: 00 00 00 00					  |     

Response

00000000: 00 00 00 06 00 00 00 44 c0 c3 05 00 00 01 1f 93 |        DÀÃ     “
00000010: 00 00 cf e4 5c 10 02 00 97 81 a4 33 43 46 41 36 |   Ïä\   — ¤3CFA6
00000020: 4c 50 41 41 28 00 02 00 00 00 00 00 28 00 00 00 | LPAA(       (   
00000030: 00 00 00 00 1c 03 00 00 00 00 00 00 02 00 00 00 |                 
00000040: 00 00 00 00					  |     

The next packets is the first 4066 bytes of the file with the following header attached to the beginning of them:

00000000: 00 00 00 06 00 00 0f fe c0 c3 05 00 00 01 1f bb |        þÀÃ     »
00000010: 00 00 cf e4 5c 10 02 00 97 81 a4 33 		  |   Ïä\   — ¤3

Since the full contents of the file was not known, it wasn't possible to separate the headers from the payload for the subsequent packets.

List a Directory

This is the initial message from iTunes to the iPhone.

                                                            ----------------
00000000: 00 00 00 06 00 00 00 46 e0 02 cb dc 00 00 00 01 |        F        
00000010: 00 00 00 01 5b 10 02 00 00 00 00 46 43 46 41 36 |     [      FCFA6
00000020: 4c 50 41 41 2a 00 00 00 00 00 00 00 2a 00 00 00 | LPAA*       *   
00000030: 00 00 00 00 01 00 00 00 00 00 00 00 03 00 00 00 |                 
00000040: 00 00 00 00 2f 00                               |     / 

• Byte 44 - Directory to list ( "/" )

These are the responses from the iPhone.

                                                            ----------------
00000000: 00 00 00 06 00 00 00 44 cb dc e0 02 00 00 00 01 |        D        
00000010: 00 00 00 2b 50 10 02 00 00 00 00 00 43 46 41 36 |    +P       CFA6
00000020: 4c 50 41 41 6b 00 00 00 00 00 00 00 28 00 00 00 | LPAAk       (   
00000030: 00 00 00 00 01 00 00 00 00 00 00 00 02 00 00 00 |                 
00000040: 00 00 00 00                                     |     

                                                            ----------------
00000000: 00 00 00 06 00 00 00 5f cb dc e0 02 00 00 00 29 |        _       )
00000010: 00 00 00 2b 50 10 02 00 00 00 00 00 2e 00 2e 2e |    +P       . ..
00000020: 00 44 43 49 4d 00 53 6f 66 74 77 61 72 65 55 70 |  DCIM SoftwareUp
00000030: 64 61 74 65 00 63 6f 6d 2e 61 70 70 6c 65 2e 69 | date com.apple.i
00000040: 74 75 6e 65 73 2e 6c 6f 63 6b 5f 73 79 6e 63 00 | tunes.lock_sync 
00000050: 69 54 75 6e 65 73 5f 43 6f 6e 74 72 6f 6c 00    | iTunes_Control 

• Bytes 1c - 5e - Filenames delimited by '00'

Listing of / results in

• .
• ..
• DCIM
• SoftwareUpdate
• com.apple.itunes.lock_sync
• iTunes_Control

This result would be expected when connecting to AFC, as AFC is jailed to /var/root/Media. The fact of "jailbreaking" is in fact creating a new service AFC2, jailed on / (basically means it's not jailed).

These data could include some of the information (this is really a brainstorm of what to look for in this data)

• Modified/Creation Date
• Permissions
• Length of Filename

Querying a directory for information

Request 1

A request for information about "/"

00000000: 00 00 00 06 00 00 00 46 05 00 c0 c3 00 00 1d 16 |        F  ÀÃ    
00000010: 00 00 22 e3 5c 10 02 00 00 00 00 46 43 46 41 36 |   "ã\      FCFA6
00000020: 4c 50 41 41 2a 00 00 00 00 00 00 00 2a 00 00 00 | LPAA*       *   
00000030: 00 00 00 00 79 00 00 00 00 00 00 00 0a 00 00 00 |     y          
00000040: 00 00 00 00 2f 00				  |     / 

Responses for Request 1

00000000: 00 00 00 06 00 00 00 44 c0 c3 05 00 00 00 22 e3 |        DÀÃ    "ã
00000010: 00 00 1d 40 5c 10 02 00 97 81 a4 33 43 46 41 36 |    @\   — ¤3CFA6
00000020: 4c 50 41 41 50 00 00 00 00 00 00 00 28 00 00 00 | LPAAP       (   
00000030: 00 00 00 00 79 00 00 00 00 00 00 00 02 00 00 00 |     y           
00000040: 00 00 00 00					  |     

00000000: 00 00 00 06 00 00 00 44 c0 c3 05 00 00 00 23 0b |        DÀÃ    # 
00000010: 00 00 1d 40 5c 10 02 00 97 81 a4 33 73 74 5f 73 |    @\   — ¤3st_s
00000020: 69 7a 65 00 32 37 32 00 73 74 5f 62 6c 6f 63 6b | ize 272 st_block
00000030: 73 00 30 00 73 74 5f 69 66 6d 74 00 53 5f 49 46 | s 0 st_ifmt S_IF
00000040: 44 49 52 00					  | DIR 

• st_size - 272 (stored in ASCII, not raw data!)
• st_blocks - 0 (also stored in ASCII)
• st_ifmt - S_IFDIR

Request 2

A request for information about "/DCIM/100APPLE"

00000000: 00 00 00 06 00 00 00 53 05 00 c0 c3 00 00 1f 4e |        S  ÀÃ   N
00000010: 00 00 26 3a 5c 10 02 00 00 00 00 53 43 46 41 36 |   &:\      SCFA6
00000020: 4c 50 41 41 37 00 00 00 00 00 00 00 37 00 00 00 | LPAA7       7   
00000030: 00 00 00 00 84 00 00 00 00 00 00 00 0a 00 00 00 |     „          
00000040: 00 00 00 00 2f 44 43 49 4d 2f 31 30 30 41 50 50 |     /DCIM/100APP
00000050: 4c 45 00					  | LE 

Responses for Request 2

00000000: 00 00 00 06 00 00 00 44 c0 c3 05 00 00 00 26 3a |        DÀÃ    &:
00000010: 00 00 1f 85 5c 10 02 00 97 81 a4 33 43 46 41 36 |    …\   — ¤3CFA6
00000020: 4c 50 41 41 52 00 00 00 00 00 00 00 28 00 00 00 | LPAAR       (   
00000030: 00 00 00 00 84 00 00 00 00 00 00 00 02 00 00 00 |     „           
00000040: 00 00 00 00    

00000000: 00 00 00 06 00 00 00 46 c0 c3 05 00 00 00 26 62 |        FÀÃ    &b
00000010: 00 00 1f 85 5c 10 02 00 97 81 a4 33 73 74 5f 73 |    …\   — ¤3st_s
00000020: 69 7a 65 00 32 32 34 34 30 00 73 74 5f 62 6c 6f | ize 22440 st_blo
00000030: 63 6b 73 00 30 00 73 74 5f 69 66 6d 74 00 53 5f | cks 0 st_ifmt S_
00000040: 49 46 44 49 52 00				  | IFDIR 

• st_size - 22440
• st_blocks - 0
• st_ifmt - S_IFDIR

Querying a File for information

Query "/DCIM/100APPLE/IMG_0001.JPG" for information.

Request

00000000: 00 00 00 06 00 00 00 60 05 00 c0 c3 00 00 1f bc |        `  ÀÃ   ¼
00000010: 00 00 48 23 5c 10 02 00 00 00 00 60 43 46 41 36 |   H#\      `CFA6
00000020: 4c 50 41 41 44 00 00 00 00 00 00 00 44 00 00 00 | LPAAD       D   
00000030: 00 00 00 00 86 00 00 00 00 00 00 00 0a 00 00 00 |     †          
00000040: 00 00 00 00 2f 44 43 49 4d 2f 31 30 30 41 50 50 |     /DCIM/100APP
00000050: 4c 45 2f 49 4d 47 5f 30 30 30 31 2e 4a 50 47 00 | LE/IMG_0001.JPG 

Responses

00000000: 00 00 00 06 00 00 00 44 c0 c3 05 00 00 00 48 23 |        DÀÃ    H#
00000010: 00 00 20 00 5c 10 02 00 97 81 a4 33 43 46 41 36 |     \   — ¤3CFA6
00000020: 4c 50 41 41 55 00 00 00 00 00 00 00 28 00 00 00 | LPAAU       (   
00000030: 00 00 00 00 86 00 00 00 00 00 00 00 02 00 00 00 |     †           
00000040: 00 00 00 00					  |     

00000000: 00 00 00 06 00 00 00 49 c0 c3 05 00 00 00 48 4b |        IÀÃ    HK
00000010: 00 00 20 00 5c 10 02 00 97 81 a4 33 73 74 5f 73 |     \   — ¤3st_s
00000020: 69 7a 65 00 33 34 38 38 31 34 00 73 74 5f 62 6c | ize 348814 st_bl
00000030: 6f 63 6b 73 00 36 38 38 00 73 74 5f 69 66 6d 74 | ocks 688 st_ifmt
00000040: 00 53 5f 49 46 52 45 47 00			  |  S_IFREG 

• st_size - 348814
• st_blocks - 688
• st_ifmt - S_IFREG

Writing a File

No data has been collected for this operation.

If someone is still looking this paper, contact me (truffaut) on #gtkpod @ freenode, I'm doing my best to complete that work.