The Path of a Remote Notification

APNs transports and routes remote notifications from your provider to your app on user devices. Figure 3-1 shows the path. When your provider determines a notification should be sent, your provider sends the notification, along with a token to identify the destination device, to APNs. The APNs servers route the notification and the device’s operating system delivers it to your app.

The device token you must provide to APNs, for each notification you send, is one that you originally obtain from APNs. It is analogous to a private phone number because it enables APNs to uniquely identify a device and can be used by your app only. The token is opaque and persistent, changing only if a device’s data and settings are erased. Only APNs can decode and read a device token.

Your app obtains the device token via the application:didRegisterForRemoteNotificationsWithDeviceToken: delegate method, which the system calls after your app successfully registers with APNs. The device token serves not only to identify a device but also to authenticate the routing of the push notifications sent to the device.

A push notification payload is a JSON dictionary containing the data you want sent to a device. The payload includes information about how you want to notify the user, such as using an alert, badge, or sound. It can also contain custom data that you define, and can be encrypted.

Figure 3-2 depicts the sort of virtual network that APNs enables among multiple providers and devices. The device-facing and provider-facing sides of APNs each allow multiple points of connection. On the provider-facing side, the connections are called gateways. To handle the notification load for your app, you would typically employ multiple providers, each making one or more persistent, secure connections with APNs through these gateways.

Read more about getting device tokens in Device Token Generation and Dispersal, and more about notification payloads in The Remote Notification Payload.

Quality of Service, Store-and-Forward, and Coalesced Notifications

Apple Push Notification service includes a default Quality of Service (QoS) component that performs a store-and-forward function. If APNs attempts to deliver a notification but the destination device is offline, APNs stores the notification for a limited period of time and delivers it to the device when the device becomes available.

This mechanism stores only one recent notification per device, per app: If you send multiple notifications while a device is offline, a new notification causes the previous notification to be discarded.

If a device remains offline for a long time, all notifications that were being stored for it are discarded; when the device goes back online, none of the notifications are displayed.

When a device is online, all the notifications you send are delivered and available to the user. However, you can avoid showing duplicate notifications by employing a collapse identifier across multiple, identical notifications. The APNs request header key for the collapse identifier is apns-collapse-id and is defined in Table 6-2.

For example, a news service that sends the same headline twice in a row could employ the same collapse identifier for both push notification requests. APNs would then take care of coalescing these requests into a single notification for delivery to a device.

Security Architecture

To ensure secure communication, APNs servers employ connection certificates, certification authority (CA) certificates, and cryptographic keys (private and public) to validate connections to, and identities of, providers and devices. APNs regulates the entry points between providers and devices using two levels of trust: connection trust and device token trust.

Connection trust establishes certainty that APNs is connected to an authorized provider, owned by a company that Apple has agreed to deliver notifications for. You must take steps to ensure connection trust exists between your provider servers and APNs, as described in this section. APNs also uses connection trust with each device to ensure the legitimacy of the device. Connection trust with the device is handled automatically by APNs.

Device token trust ensures that notifications are routed only between legitimate start and end points. A device token is an opaque, unique identifier assigned to a specific app on a specific device. Each app instance receives its unique token when it registers with APNs. The app must share this token with its provider, to allow the provider to employ the token when communicating with APNs. Each notification that your provider sends to APNs must include the device token, which ensures that the notification is delivered only to the app-device combination for which it is intended.

Provider-to-APNs Connection Trust

There are two schemes available for negotiating connection trust between your provider servers and Apple Push Notification service:

• Token-based connection trust A provider using the HTTP/2-based APNs Provider API can use JSON web tokens (JWT) to validate the provider’s connection with APNs. In this scheme, the provider does not require a certificate-plus-private key to establish connection. Instead, you provision a public key to be retained by Apple, and a private key which you retain and protect. Your providers then use your private key to generate and sign JWT authentication tokens. Each of your push requests must include an authentication token.

• Certificate-based connection trust A provider can, alternatively, employ a unique provider certificate and private cryptographic key. The provider certificate, provisioned by Apple when you establish your push service in your online developer account, identifies the topics supported by the provider. Each topic is the bundle ID associated with one of your apps.

Token-Based Provider-to-APNs Trust

Figure 3-3 illustrates using the HTTP/2-based APNs provider API to establish trust, and using JWT provider authentication tokens for sending notifications. It works as follows:

1. Your provider asks for a secure connection with APNs using transport layer security (TLS), represented as the arrow labeled “TLS initiation” in the figure.

2. APNs then gives your provider an APNs certificate, represented by the next arrow in the figure (labeled “APNs certificate”), which your provider then validates.

   At this point, connection trust is established and your provider server is enabled to send push notifications to APNs.

3. Each push that your provider sends must be accompanied by a JWT authentication token, represented in the figure as the arrow labeled “Notification push.”

4. APNs replies to each push, represented in the figure as the arrow labeled “HTTP/2 response.”

   For specifics on the responses your provider can receive for this step, see HTTP/2 Response from APNs.

The HTTP/2-based provider connection is valid for delivery to one specific app, identified by the topic (the app bundle ID) specified in the certificate. Depending on how you configure and provision your APNs Transport Layer Security (TLS) certificate, the trusted connection can also be valid for delivery of remote notifications to other items associated with your app, including Apple Watch complications and voice-over-Internet Protocol (VoIP) services. APNs delivers these notifications even when those items are running in the background. See APNs Provider API for details, and see Voice Over IP (VoIP) Best Practices in Energy Efficiency Guide for iOS Apps.

APNs maintains a certificate revocation list; if a provider’s certificate is on the revocation list, APNs can revoke provider trust (that is, APNs can refuse the TLS initiation connection).

Certificate-Based Provider-to-APNs Trust

Figure 3-4 illustrates using an Apple-issued certificate for establishing trust between a provider and APNs. Unlike Figure 3-3, this figure does not show a notification push itself, but stops at the establishment of a Transport Layer Security (TLS) connection. In the certificate-based trust scheme, there is 1) no per-push validation performed, and 2) no HTTP/2 response available to you for each notification push request.

Certificate-based provider-to-APNs trust works as follows:

1. Your provider asks for a secure connection with APNs using transport layer security (TLS), represented as the arrow labeled “TLS initiation” in the figure.

2. APNs then gives your provider an APNs certificate, represented by the next arrow in the figure (labeled “APNs certificate”), which your provider then validates.

3. Your provider must then send its Apple-provisioned provider certificate back to APNs, represented as the arrow labeled “Provider certificate.”

4. APNs then validates your provider certificate, thereby confirming that the connection request originated from a legitimate provider, and establishes your TLS connection.

   At this point, connection trust is established and your provider server is enabled to send push notifications to APNs.

As with token-based trust, a certificate-based provider-to-APNs connection is valid for delivery to only one specific app. That app is identified by the topic (bundle ID) specified in the provider certificate.

APNs maintains a certificate revocation list; if a provider’s certificate is on the revocation list, APNs can revoke provider trust (that is, APNs can refuse the TLS initiation connection).

APNs-to-Device Connection Trust

Trust between APNs and each device is established automatically by iOS upon initial device activation (and without participation by your app), as described in this section.

Each device has a cryptographic certificate and a private cryptographic key, obtained at initial device activation and stored in the device’s keychain. During activation, APNs uses the certificate and key to validate the device’s connection using peer-to-peer authentication, as shown in Figure 3-5.

Trust negotiation begins when the device operating system initiates a TLS connection with APNs, which returns its server certificate. The operating system validates this certificate and then sends the device certificate. Finally, APNs validates the device certificate, establishing trust.

With a TLS connection established between the device and APNs, APNs can then provide an app-specific device token to each app that registers for remote notifications.

Device Token Generation and Dispersal

An app must register with the system to receive remote notifications, as described in Registering for Remote Notifications. Upon receiving a registration request, the system forwards the request to APNs, which generates a unique device–app token, using information contained in the device’s certificate. It then encrypts the token using a token key and returns it to the device, as shown in Figure 3-6. The system delivers the device token to your app as an NSData object. Upon receiving this token, your app must forward it to your provider in either binary or hexadecimal format. Your provider cannot send notifications to the device without this token.

Device Token Trust for Notifications

Every notification that your provider sends to APNs must be accompanied by the token associated with the device for which the notification is intended. APNs decrypts the device token using its token key to ensure the validity of the notification source—that is, your provider. APNs uses the device ID contained in the device token to determine the identity of the target device. It then sends the notification to that device, as shown in Figure 3-7.