2. Transport Layer

A single persistent TLS connection carries every frame in both directions.

TLS Connection

All TCP communication runs over a TLS connection. The server uses a self-signed X.509 certificate, and the client obtains it out of band (see Certificate Provisioning) and uses certificate pinning, so only that pinned certificate is trusted.

• Protocol: TLS 1.2+ (SSLv2, SSLv3, TLS 1.0, and TLS 1.1 are explicitly disabled)
• Certificate validation: Pinned server certificate only; the system CA store is not consulted
• Pinning mechanism: OpenSSL verification is turned off (SSL_VERIFY_NONE) and replaced by a direct comparison. The leaf certificate the server presents is DER-encoded and must be byte-for-byte identical to the pinned PEM
• Connection model: Single persistent long-lived connection; client reconnects with exponential backoff on failure
• TCP_NODELAY: Enabled on the socket
• Socket timeouts: 10 seconds for both send and receive
• SIGPIPE: Must be ignored (SIG_IGN) to prevent process termination

Frame Format

All messages in both directions use identical binary framing:

Header size: 8 bytes fixed. Maximum payload: 4096 bytes (SGP_MAX_PAYLOAD_LEN). The one exception to this framing is the optional legacy compatibility hello a v1 server may send as the first frame of a connection. See Legacy (v1) Hello.

Byte Order

All multi-byte integers in payloads are encoded in big-endian (network byte order). This applies to the 4-byte payload length in the header, all int64_t timestamps and sequence numbers (8 bytes), all uint32_t version numbers and data lengths (4 bytes), and all uint16_t string lengths (2 bytes).

3. Message Types

Each frame's type byte identifies one of these messages.

One client frame falls outside the 0x2_ block: C_UPGRADE (0x00), sent only in reply to a legacy v1 compatibility hello.

53 02 00 00 00 00 00 00       Magic=0x53, Version=0x02, Type=C_UPGRADE(0x00), Reserved=0x00, PayloadLen=0

4. Device Registration

Before a device can authenticate it has to register with the server to get an identity. This happens once.

The server assigns the device address. The client never picks its own identifier. It sends only a freshly generated RSA keypair and waits for the server to return an address in S_REGISTER_OK. That keeps addresses unique across the namespace, and lets the server encode routing information into the address itself (e.g. <hex>@<server-id>).

C_REGISTER (0x28) Payload

The client generates an RSA-2048 keypair: the public key is sent to the server, the private key is stored locally and never transmitted. The device address field is absent, since the server assigns it.

S_REGISTER_OK (0x18) Payload

The address is opaque to the client. The reference server issues <32 hex chars>@<server-id>, but clients MUST NOT parse this format. Max length 255 bytes. Address charset: clients MUST reject any address outside [A-Za-z0-9._@-].

S_REGISTER_FAIL (0x19) Payload

Optional Registration Client Certificate

Registration can be gated by mutual TLS. A profile may be provisioned out of band with a PEM bundle (client certificate + private key). When present, the daemon presents it as its TLS client certificate on the registration connection.

Used only while unregistered, and authorizes exactly one successful registration. Committing S_REGISTER_OK deletes the PEM and zeros the in-memory copy in the same step. Independent of the RSA identity used for login (Authentication Flow).

5. Authentication

Authentication is an RSA-PSS challenge-response. The client holds an RSA-2048 private key, and the server holds the matching public key it got during registration.

S_HELLO (0x10) / C_LOGIN (0x20)

S_HELLO is sent immediately after the TLS handshake completes.

S_CHALLENGE / Response Payloads

Shared by both the login and registration flows.

S_AUTH_OK & Clock Skew

S_AUTH_OK (0x12) has an empty payload (0 bytes) and confirms the client has authenticated.

The server may only send S_TIME_SYNC (0x1B) after authentication completes. It carries an 8-byte big-endian Unix timestamp. The client computes offset = server_time - local_time and applies it to later login and register timestamps. Offsets beyond +/-172 800 seconds (2 days) are rejected as a protocol error.

Protocol Phase Gating

To guard against unsolicited server frames, the client runs a strict phase machine and rejects any message outside its allowed phase.

S_DISCONNECT is accepted in any phase. S_PING/S_PONG only in Authenticated. Any frame outside its allowed phase triggers SGP_ERR_PROTO and a clean teardown (soft error -> backoff + reconnect). Servers MUST NOT rely on sending frames out of phase for any side-effect.

6. Notification Delivery

How pushes reach the device over the live connection, and how they are acknowledged and re-polled.

S_NOTIFY (0x13) Payload Layout

Minimum payload size: 70 bytes (empty data, unencrypted).

Notification Processing

1. Look up routing_key to find the bundle ID and E2EE key.
2. If is_encrypted: decrypt with AES-256-GCM using the stored key and iv; the last 16 bytes of data are the GCM tag; AAD is empty.
3. If is_compressed: inflate as raw DEFLATE (windowBits = -15), capped at 65536 bytes (SGP_MAX_INFLATED_LEN) as a decompression-bomb guard.
4. Parse the resulting bytes per content_type.
5. Deliver the canonical payload to the target application.
6. Send a C_ACK message.

Ordering when both flags are set: the server compresses first, then encrypts, and the client does the inverse: decrypt, then inflate.

C_ACK (0x23) Payload

Sent right away if connected, otherwise persisted to SQLite and flushed once the connection is back.

C_POLL (0x22) Payload

Requests re-delivery of any notification with a sequence number greater than last_seq. Typically sent immediately after authentication.

S_POLL_DONE (0x17) Payload

Empty payload (0 bytes). Signals that the server has finished delivering all queued offline messages.

7. Payload Formats

What lives inside a notification payload.

Flat TLV (0x00)

The Type/Length/Value unit repeats until the payload is exhausted.

These map to aps.alert.title, aps.alert.body, aps.sound, and a top-level custom_data respectively.

JSON (0x01) and Property List (0x02)

The payload is either a UTF-8 JSON object or an Apple property list (binary bplist0 or XML). Either one is deserialized and canonicalized straight into the userInfo dictionary. Values a property list cannot hold (e.g. JSON null) are stripped so the result survives the binary-plist IPC hop to SpringBoard. Nesting is capped at 32 levels.

Structured TLV (0x03)

A typed, recursive binary encoding of the same object model JSON/plist describe, tuned for size: only variable-length types carry a length, and every length/integer is a varint, so small values cost 1-2 bytes.

Varint is unsigned LEB128: base-128, little-endian groups; each byte holds 7 value bits, high bit 0x80 = "another byte follows". At most 10 bytes; overflow rejected; encoders emit the minimal byte count.

Every VALUE is type: uint8, then [length: varint] (only for MAP, ARRAY, STRING, DATA), then payload:

The top-level VALUE must be a MAP. Container lengths must frame their children exactly. Nesting is capped at 32 levels.

8. Device Tokens

Token Generation Algorithm

1.  K = SecureRandom(16)                     // 16 cryptographically random bytes

2.  routing_key = SHA-256(K)                 // 32 bytes

3.  salt = UTF8(server_address) + "Hello from the Skyglow Notifications developers!"
    e2ee_key = HKDF-SHA256(
        key_material  = K,
        salt          = salt,
        info          = <empty>,
        output_length = 32
    )                                         // 32 bytes

4.  padded_addr = PadRight(UTF8(server_address), 16, 0x00)
    device_token = padded_addr || K           // 32 bytes total

C_FILTER (0x2B) Payload

C_FILTER carries the device's complete (tag, routing_key, bundle_id) registration set. The server treats the multi-chunk transmission as a single atomic full-replace for both the routing filter and the bundle binding table.

Sent right after S_AUTH_OK on every connection, and after any local change to the registration set (add, mute, unmute, delete). When the entries do not fit in one frame they are chunked, and the server accumulates until has_more = 0, then atomically replaces its state. If the connection drops mid-transmission, the server MUST discard the partial buffer.

Tag 0x02 (ignored) is how the toggle-off mute works. The daemon silently ACKs SUCCESS without dispatching, a defensive drop, not a delete. The client packs entries greedily and starts a new chunk when the next one would exceed SGP_MAX_PAYLOAD_LEN (4096). An empty registration set is a single frame with flags=0, count=0 and no entries.

9. Connection Lifecycle

Keeping the connection alive, closing it cleanly, and getting it back.

Keep-Alive Mechanism

The protocol supports bidirectional keep-alive pings, all with an 8-byte BE i64 seq payload: C_PING (0x27), S_PONG (0x16) echoes it, S_PING (0x1A), and C_PONG (0x2A) echoes it.

The client uses an adaptive keep-alive algorithm that searches for the longest interval the network path will hold open, in four stages:

1. Initial growth, where the interval climbs in ~300 s steps (+/-20 s jitter) until a ping fails
2. Refined growth, where after a failure it falls back to the last good interval and creeps up in ~120 s steps
3. Steady state, settled at a sustainable interval, re-probing after max(24 x interval, 3600 s)
4. Backoff, where the interval halves on each failure until pings succeed again

Interval bounds: 600 s minimum, max 3600 s on Wi-Fi or 1680 s on WWAN; learned per network type and restored on the next connection. Entirely client-side. Pong timeout: 15 seconds (SGP_PONG_TIMEOUT_SEC).

Disconnect Messages

Soft errors trigger the reconnect backoff below, honoring retry_after when it is longer than the local delay (clamped to 600 s). Hard errors are terminal, and the client stops reconnecting until a manual configuration change.

Reconnection Strategy

Exponential backoff with jitter, retrying at the maximum interval indefinitely once reached:

initial_delay = 2s, max_delay = 600s, max_jitter = 5s
failures = 0
loop:
  connect_and_authenticate()
  on failure:
    failures += 1
    delay = min(initial_delay * 2^(failures-1)
                 + rand(0..max_jitter), max_delay)
    if retry_after > delay: delay = min(retry_after, max_delay)
    sleep(delay)

Network changes, configuration reloads, and system wakes reset the current backoff and trigger an immediate attempt.

S_TIME_SYNC (0x1B) Payload

The client computes offset = server_time - local_time and applies it to all login/registration timestamps, which handles devices with unreliable NTP (e.g. iOS 3-5 era hardware).

10. Security & Appendices

How notification payloads are protected end to end, plus reference layouts and complete wire examples.

Key Derivation

Both the sender and receiver independently derive the same key from the shared secret K (see Device Token Management):

salt = UTF8(server_address) + "Hello from the Skyglow Notifications developers!"

e2ee_key = HKDF-SHA256(
    key_material  = K,         // 16 bytes, extracted from device_token[16:32]
    salt          = salt,
    info          = <empty>,
    output_length = 32
)

The sender extracts K from the device token (bytes 16-31) and the server address from bytes 0-15 (trimming trailing 0x00 bytes).

Encryption (Sender Side)

iv = SecureRandom(12)

ciphertext, tag = AES-256-GCM-Encrypt(
    key       = e2ee_key,
    iv        = iv,
    plaintext = TLV_serialize(payload),
    aad       = <none>
)

// data  = ciphertext || tag  (tag is 16 bytes)
// iv    = iv                 (12 bytes, after data)
// flags = 0x01                (is_encrypted = true)

Decryption (Client Side)

ciphertext = data[0 .. len-16]
tag        = data[len-16 .. len]

plaintext = AES-256-GCM-Decrypt(
    key        = e2ee_key,  // by routing_key
    iv         = iv,
    ciphertext = ciphertext,
    tag        = tag,
    aad        = <none>
)

If decryption or tag verification fails, the client acknowledges with status code 1.

Appendix A: Device Token Binary Layout

The token is opaque to the receiving application. A sending service: reads bytes 0-15 and trims trailing 0x00 for the server address; resolves that address via DNS TXT (see DNS TXT Resolution); reads bytes 16-31 for secret K; derives routing_key = SHA-256(K); and derives e2ee_key via HKDF-SHA256 if sending encrypted payloads.

Appendix B: Wire Examples

53 02 20 00 00 00 00 32       Magic=0x53, Version=0x02, Type=C_LOGIN(0x20), Reserved=0x00, PayloadLen=50

00 24                          addr_len = 36
61 62 63 64 65 66 ... (36 B)   address = "abcdefgh-1234-5678-9abc-def012345678"
00 00 01 8E 2A 3B 4C 5D        timestamp (BE i64)
00 00 00 02                    version = 2 (BE u32)

[32 bytes routing_key]
[16 bytes msg_id]
[8 bytes seq (BE i64)]
[8 bytes expires_at (BE i64)]
01                             flags: is_encrypted = 1
00                             content_type
00 00 00 40                    data_len = 64 (BE u32)
[64 bytes: ciphertext(48) || GCM tag(16)]
[12 bytes: IV]

[16 bytes msg_id]  00  status = 0 (success)