7 Push Notification Service

This chapter describes the operations provided by the Push Notification Service (PNS): the creation, update and deletion of a Wallet Instance's push notification account and the delivery of push notifications to a Wallet Instance.

Design Decisions

The PNS reaches the WI out-of-session, e.g. to trigger the Wallet Instance self-locking after a wallet revocation. Push notifications are delivered through the push notification service of the Mobile Platform Provider (MPP) (Firebase Cloud Messaging (FCM) on Android, with FCM acting as a wrapper for APNs on iOS), which addresses the target device by the mpp_registration_token. The PNS is only reachable by other backend services through the push notification queue, which decouples the triggering backend service (e.g. the WB) from the delivery to the external MPP infrastructure. Push notifications are strictly opt-in, as they introduce a dependency on Google/Apple infrastructure and expose metadata to the MPP: only if the user opted in during the wallet activation, the WI requests the Create Account operation to store the initial mpp_registration_token at the PNS. Whenever the MPP rotates the token and once a month during the subsequent start-ups, the WI requests the Update Account operation to refresh the stored mpp_registration_token, so that it does not become stale, while avoiding calls to the MPP and the PNS on every start-up. If the user disables push notifications, the WI requests the Delete Account operation to delete the stored mpp_registration_token.

A push notification itself carries only a minimal instruction and no security-relevant payload: upon reception, the WI attempts a renewal of its mdvm_token (Android or iOS). The MDVM rejects the renewal for a revoked account, which confirms the revocation to the WI and triggers the Wallet Instance self-locking. Users who did not opt in to push notifications learn of a revocation in the same way through the regular mdvm_token renewal, at the latest on the first app launch after the current mdvm_token has expired.

The PNS is a logically separate backend service from the WB, MDVM and RWSCA, connected to them only through the Message Queue. It re-uses the mdvm_wi_id from the mdvm_token instead of maintaining its own account identifiers and re-uses the wi_mdvm_auth_pubk as a possession factor.

7.1 PNS Operations

The PNS offers various operations that are each handled by dedicated endpoints. The operations have different authentication requirements, as listed in table below:

Operation	Authentication	Description
Create Account	possession factor	Create an account for a Wallet Instance by storing the initial mpp_registration_token, e.g. during wallet activation when the user opts in to push notifications.
Update Account	possession factor	Update the mpp_registration_token stored for an existing account, e.g. when the MPP rotates the token or during the monthly renewal.
Delete Account	possession factor	Delete the account and the stored mpp_registration_token, e.g. when the user disables push notifications.
Send Push Notification	internal (push notification queue)	Deliver a push notification to the WI through the MPP upon a push notification event, e.g. to trigger the WI to self-lock.

7.2 PNS Data Flows

This section described the data flow of the Push Notification Service Operations in a sequence diagram and a more detailed table. Artifacts in italics are further explained in the data register chapter.

7.2.1 Create, Update and Delete Account

The sequence diagram contains three flows marked as alternatives when they diverge:

1) In the Create Account operation, the WI registers a new account by storing its initial mpp_registration_token at the PNS, e.g. during wallet activation when the user opts in to push notifications. The green section describes steps that are only relevant for this flow. 2) In the Update Account operation, the WI refreshes the mpp_registration_token stored for an existing account, e.g. when the MPP rotates the token or during the monthly renewal. The green section describes steps that are only relevant for this flow. 3) In the Delete Account operation, the WI requests the PNS to delete its account, e.g. because the user disabled push notifications in the app settings. After this operation, the PNS no longer holds any data for the WI and delivers no further push notifications to it until the WI creates a new account. The grey section describes steps that are only relevant for this flow.

The following table describes the steps of the sequence diagram in more detail:

No	Description
001	The WI determines if its most recent mdvm_token is still valid. If the mdvm_token is not up-to-date, the WI may fetch a fresh one from the MDVM endpoint using the renewal flow for either Android or iOS.
002 - 003	Steps 002 - 003 only occur in the Create Account and Update Account operations The WI registers with the Mobile Platform Provider's (MPP) push notification service and receives an mpp_registration_token that uniquely identifies this WI to the push notification system. The token is generated and managed by the platform and may be rotated by the platform itself, so the WI performs this step not only during wallet activation, but also whenever the platform issues a new token and as part of the monthly renewal during subsequent start-ups.
004 - 006	The WI requests a challenge from the PNS challenge endpoint using an HTTP POST request, the request is unauthenticated. The PNS generates a JSON structure containing a random nonce and a timestamp of the current time and MACs it using a symmetric key (pns_challenge_symk) as a JSON Web Token (JWT), the resulting structure is the pns_auth_challenge. The PNS responds to the WI with the pns_auth_challenge in the HTTP payload. The WI uses the challenge as an opaque string and does not evaluate the JWT claims. The PNS does not store the challenge after creation, thus the operation is stateless.
007	Step 007 only occurs in the Create Account and Update Account operations The WI computes a proof of possession by signing the payload of pns_auth_challenge for freshness and to enable replay protection, the mdvm_token to ensure authenticity and integrity of the WI and to identify it by the mdvm_wi_id it contains, and the mpp_registration_token to bind the new or renewed push notification token to this authenticated request, with the possession factor wi_mdvm_auth_prvk. The resulting structure is called wi_pns_auth_pop.
008	Step 008 only occurs in the Delete Account operation The WI computes a proof of possession by signing the payload of pns_auth_challenge for freshness and to enable replay protection and the mdvm_token to ensure authenticity and integrity of the WI and to identify it by the mdvm_wi_id it contains, with the possession factor wi_mdvm_auth_prvk. The resulting structure is called wi_pns_auth_pop.
009	The WI requests the PNS to create, update or delete the account by sending wi_pns_auth_pop to the operation endpoint, which is shared by all three operations. The request is authenticated.
010	The PNS verifies the self-contained pns_auth_challenge included in the wi_pns_auth_pop using its symmetric key (pns_challenge_symk) and validating that the timestamp is within a valid time interval as specified in the token lifecycle section of the cryptography chapter. This step ensures replay protection beyond the valid time interval of the challenge.
011	The PNS validates the security posture of the WI by verifying the mdvm_token with mdvm_attestation_pubk and checks that it is still valid. The PNS has a trusted, out-of-band mechanism towards the MDVM to fetch the valid mdvm_attestation_pubk. The PNS also extracts the identifier mdvm_wi_id and the public key wi_mdvm_auth_pubk directly from the verified mdvm_token, without a prior database lookup: the MDVM's signature already binds both together.
012	The PNS verifies the signature of the received proof of possession (wi_pns_auth_pop) for the WI's possession factor using the extracted wi_mdvm_auth_pubk.
013	Step 013 only occurs in the Create Account operation The PNS creates a new account with mdvm_wi_id, wi_mdvm_auth_pubk and the mpp_registration_token together with the timestamp of the registration in the PNS account database.
014	Step 014 only occurs in the Update Account operation The PNS updates the mpp_registration_token and the timestamp of the registration for the existing account identified by mdvm_wi_id in the PNS account database.
015	Step 015 only occurs in the Delete Account operation The PNS deletes the account and the stored mpp_registration_token for the authenticated mdvm_wi_id from the PNS account database. If no account was found (e.g. the user never opted in), the operation still responds successfully.
016	The PNS responds to the WI confirming that the operation was successful.
017	Step 017 only occurs in the Create Account and Update Account operations The WI stores the mpp_registration_token and the timestamp of the registration locally, so that it can detect when the platform rotates the token and determine when the monthly renewal is due.
018	Step 018 only occurs in the Delete Account operation The WI deletes the locally stored mpp_registration_token and its registration timestamp.

7.2.2 Send Push Notification

In the Send Push Notification operation, the PNS delivers a push notification to a Wallet Instance through the push notification service of the Mobile Platform Provider (MPP). The operation is not exposed as an endpoint towards the WI; it consumes push notification events that other backend services publish to the push notification queue, e.g. the WB's Revoke Account operation to trigger the Wallet Instance self-locking. This decouples the triggering operation from the delivery to the external MPP infrastructure.

Push notifications for wallet self-lock must be configured to have the highest priority of being delivered to the WI, so that the triggering instruction reaches the WI with the highest probability, e.g. to enforce the Wallet Instance self-locking with the least possible delay. The following settings should be used:

• notification - FCM and APNs are very clear that high priority notifications are meant as user visible content, therefore the push notification should include the notification key and contain a short message to inform the user about the triggering event, e.g. a wallet revocation
• data - custom data containing a machine-readable operation code instructing the WI which action to perform, e.g. to confirm a revocation
• Android:
  • priority - Set priority to high
• iOS:
  • apns-push-type - Set to alert, this results in a user-visible message and ensures high priority
  • apns-priority - Set priority to 10 to ensure the message is sent immediately and bypasses power-saving delays
  • mutable-content - Set to 1 to give the WI can process the request before display through a NotificationServiceExtension

The following table describes the steps of the sequence diagram in more detail:

No	Description
001	The PNS continuously fetches push notification events from the push notification queue. Each event contains the JWK thumbprint of a wi_mdvm_auth_pubk and an instruction for the WI, and triggers the Send Push Notification operation.
002	The PNS looks up the mpp_registration_token stored for the account in the PNS account database using the JWK thumbprint of wi_mdvm_auth_pubk as the indexed lookup key. If the user did not opt in to push notifications, no mpp_registration_token is stored and the PNS acknowledges the event without a delivery.
003	The PNS sends the push notification to the MPP through Firebase Cloud Messaging (FCM) using the mpp_registration_token, configured with the settings described above to maximize delivery priority.
004	The MPP responds indicating whether the push notification was accepted.
005 - 006	Steps 005 - 006 only occur if the MPP responds with ok The PNS acknowledges the push notification event after handing the notification over to the MPP. Events that are not acknowledged are redelivered by the push notification queue and reprocessing them is idempotent, as resending the notification only retriggers the instruction for the WI. The MPP then delivers the push notification to the WI, either directly (Android) or via APNs (iOS). The delivery is best-effort: the notification carries no security-relevant payload and only signals the WI to fetch and confirm actions through authenticated pull requests, e.g. to confirm a revocation through a mdvm_token renewal attempt before self-locking.
007 - 008	Steps 007 - 008 only occur if the MPP responds with an error If the MPP responds with an error message indicating that the mpp_registration_token is invalid or expired, the PNS deletes the account, as the token has permanently ceased to be valid, and acknowledges the push notification event.

7.3 PNS Account Database

The PNS account database stores the necessary information for each Wallet Instance registered for push notifications:

• mdvm_wi_id
• wi_mdvm_auth_pubk
• JWK Thumbprint of wi_mdvm_auth_pubk
• mpp_registration_token & timestamp of the registration

Access to the database is secured by mutual TLS to encrypt and authenticate communication to the PNS. Unlike the other backends, the PNS holds no revocation state: it is entirely stateless with regard to revocation and only holds the data required to deliver push notifications, so records are deleted upon an explicit Delete Account operation.