Apple Push Service Protocol

From The iPhone Wiki
Revision as of 03:27, 31 July 2021 by Nicolas17 (talk | contribs) (Add documentation about the fields in "connect" and "connected" commands)
Jump to: navigation, search

iOS devices connect to Apple's push servers via port 5223. The protocol is proprietary and has nothing to do with XMPP (which uses the same port to establish SSL-encrypted client connections). The Push service protocol also uses SSL encryption.

As of iOS5, Apple uses a new push protocol. The same protocol is used on the Mac too. With iOS4, the protocol used message types 00 to 06, while the new protocol uses message types 07 to 0f and all fields have a type-length-value encoding.

While every iOS version after that continued adding new message and field types, since iOS 10 there is another new push protocol known as "apnspack", which uses the same message and field types but encodes them in a completely different binary format. The client negotiates use of this new protocol with the protocol name "apns-pack-v1" in ALPN. The apnspack format is not yet documented in this page.

Message Structure

The format of the non-packed APNS protocol is as follows:

  • 1 byte message type
  • 4 byte payload length
  • fields, all with
    • 1 byte type
    • 2 byte length
    • value

Example:

  • 07 message type (Connect)
  • 00 00 00 27 39 byte payload length
  • 01 1st field
    • 00 20 32 byte length
    • 8a 73 82 00 82 ac 91 32 88 b6 aa ef 90 91 65 ce 8a 73 82 00 82 ac 91 32 88 b6 aa ef 90 91 65 cevalue 1 (32-byte push token)
  • 02 2nd field
    • 00 01 1 byte length
    • 01 value

Messages

Note that some fields are optional, either because they're only sent depending on certain conditions, or because they were introduced in a later iOS version and earlier ones don't send it. That will be documented in more detail later.

07 Connect

First command sent after SSL handshake is completed.

When a device is first activated, it doesn't have a push token yet. This command 07 is sent without a token, and the server returns a new token in its command 08 reply. In all future connections, the device sends the token in command 07, and the server doesn't return a token in command 08.

  • Direction: device to server
  • message type: 07
  • fields:
    • 01 32-byte push token
    • 02 1 byte "state" (value 01)
    • 05 4-byte flags, bitfield (example from iOS 12: 00 00 02 6a)
    • 06 1 byte interface (0: cellular, 1: Wi-Fi)
    • 08 cellular carrier name (or the string "WiFi")
    • 09 OS version (example: 12.4.8)
    • 0a OS build (example: 16G201)
    • 0b hardware version (example: iPhone6,1)
    • 0c certificate, contains the X.509 "device certificate" obtained during device activation
    • 0d 17-byte nonce, first 8 bytes are milliseconds since epoch, rest is generated randomly
    • 0e "signature", consisting of bytes 01 01, followed by RSASSA-PKCS1-SHA1 signature of the nonce (0d) using the public key in the certificate (0c)
    • 10 2-byte int, possibly protocol version
    • 11 2-byte int, "redirect count"
    • 13 2-byte int, "DNS resolve time" in milliseconds
    • 14 2-byte int, "TLS handshake time" in milliseconds

08 Connect Response

  • Direction: server to device
  • message type: 08
  • fields:
    • 01 status (00 ok, 02 some error)
    • 03 32-byte push token (unless the device sent one in Connect)
    • 04 2-byte int, max message size (value 10 00)
    • 05 unknown (value 00 02)
    • 06 capabilities (bitfield)
    • 08 2-byte int, large message size
    • 0a 8-byte int, server time, milliseconds since unix epoch
    • 0b 2 bytes, geo region (country code)

The lowest significant bit in 'capabilities' seems to mean "dual channel support" (possibly related to the iPhone proxying Apple Watch notifications).

09 Push Topics

  • Direction: device to server
  • message type: 09
  • fields:
    • 02 20-byte ID for enabled topic (like topic for push-enabled app or a specific iCloud service like Find My iPhone)
    • 03 20-byte ID for disabled topic

0A Push Notification

  • Direction: server to device (for iMessage and possibly others too, also the other way round)
  • message type: 0a
  • fields:
    • 01 recipient push token
    • 02 topic
    • 03 notification payload
    • 04 response token
    • 05 expiry (32-bit UNIX timestamp)
    • 06 timestamp (64-bit UNIX timestamp in nanoseconds)
    • 07 unknown (00)

0B Push Notification Response

  • Direction: server to device (for iMessage and possibly others too, also the other way round)
  • message type: 0b
  • fields:
    • 04 response token
    • 08 status (00 ok, 02 error)

0C Keep-Alive

  • Direction: device to server
  • message type: 0c
  • fields:
    • 01 connection method ("WiFi" or GSM MNC like "31038" for AT&T)
    • 02 iOS version, e.g. "5.0"
    • 03 iOS build number
    • 04 device model, e.g. "iPhone2,1"
    • 05 unknown (values like 10, 15 or 20)

0D Keep-Alive Confirmation

  • Direction: server to device
  • message type: 0d
  • no fields

0E No Storage

  • Direction: server to device
  • message type: 0e
  • fields:
    • 03 32-byte push token

0F Flush

  • Direction: both
  • message type: 0f
  • fields:
    • 2-byte integer indicating length of padding
    • padding: NULL-bytes, typical lengths are 64, 128, 256, 512

References