RFC 8599
Push Notification with the Session Initiation Protocol (SIP)
Push Notification with the Session Initiation Protocol (SIP) 🎀
Okay bestie, this one is RFC 8599, and it's a Standards Track doc, so it's a real IETF spec 💅. It was written by C. Holmberg from Ericsson and M. Arnold from Metaswitch Networks, and it's dated May 2019. Its ISSN is 2070-1721. The title block doesn't list anything it obsoletes or updates, so there's no earlier RFC it replaces or patches 🦋.
Abstract ✨
Okay so, the big idea is this: a Push Notification Service (PNS) can wake up a SIP User Agent (UA) that's been suspended, using push notifications 🔔. Then the UA can send its binding-refresh REGISTER requests and still catch incoming SIP requests, even though it might be asleep for a while 😴. The doc defines new SIP URI parameters so the UA and the SIP entity can swap PNS info, and the SIP entity is the one that asks for push notifications to get sent to the UA 💌. It also defines the parameters that trigger those push requests, plus some new feature-capability indicators so everyone can tell who supports this mechanism 🧚.
Status of This Memo 🌸
This is an Internet Standards Track document 👑.
It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 7841 📚.
Info about this doc's current status, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8599 🔗.
Copyright Notice 💜
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved 🌈.
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please actually read these, because they spell out your rights and restrictions for this doc 🫶. Any Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, same as that license says 💖.
Table of Contents 🍓
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. Push Resource ID (PRID) . . . . . . . . . . . . . . . . . . . 8
4. SIP User Agent (UA) Behavior . . . . . . . . . . . . . . . . 9
4.1. REGISTER . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1.1. Request Push Notifications . . . . . . . . . . . . . 9
4.1.2. Disable Push Notifications . . . . . . . . . . . . . 11
4.1.3. Receive Push Notifications . . . . . . . . . . . . . 11
4.1.4. Sending Binding-Refresh Requests Using Non-push
Mechanism . . . . . . . . . . . . . . . . . . . . . . 11
4.1.5. Query Network PNS Capabilities . . . . . . . . . . . 13
5. SIP Proxy Behavior . . . . . . . . . . . . . . . . . . . . . 14
5.1. PNS Provider . . . . . . . . . . . . . . . . . . . . . . 14
5.2. SIP Request Push Bucket . . . . . . . . . . . . . . . . . 15
5.3. SIP URI Comparison Rules . . . . . . . . . . . . . . . . 15
5.4. Indicate Support of Type of PNS . . . . . . . . . . . . . 15
5.5. Trigger Periodic Binding Refresh . . . . . . . . . . . . 16
5.6. SIP Requests . . . . . . . . . . . . . . . . . . . . . . 17
5.6.1. REGISTER . . . . . . . . . . . . . . . . . . . . . . 17
5.6.2. Initial Request for Dialog or Standalone Request . . 20
6. Support of Long-Lived SIP Dialogs . . . . . . . . . . . . . . 23
6.1. SIP UA Behavior . . . . . . . . . . . . . . . . . . . . . 25
6.1.1. Initial Request for Dialog . . . . . . . . . . . . . 25
6.2. SIP Proxy Behavior . . . . . . . . . . . . . . . . . . . 25
6.2.1. REGISTER . . . . . . . . . . . . . . . . . . . . . . 25
6.2.2. Initial Request for Dialog . . . . . . . . . . . . . 26
6.2.3. Mid-dialog Request . . . . . . . . . . . . . . . . . 26
7. Support of SIP Replaces . . . . . . . . . . . . . . . . . . . 27
8. Grammar . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.1. 555 (Push Notification Service Not Supported) Response
Code . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.2. 'sip.pns' Feature-Capability Indicator . . . . . . . . . 28
8.3. 'sip.vapid' Feature-Capability Indicator . . . . . . . . 28
8.4. 'sip.pnsreg' Feature-Capability Indicator . . . . . . . . 28
8.5. 'sip.pnsreg' Media Feature Tag . . . . . . . . . . . . . 29
8.6. 'sip.pnspurr' Feature-Capability Indicator . . . . . . . 29
8.7. SIP URI Parameters . . . . . . . . . . . . . . . . . . . 29
9. PNS Registration Requirements . . . . . . . . . . . . . . . . 30
10. 'pn-provider', 'pn-param', and 'pn-prid' URI Parameters for
Apple Push Notification service . . . . . . . . . . . . . . . 30
11. 'pn-provider', 'pn-param', and 'pn-prid' URI Parameters for
Google Firebase Cloud Messaging (FCM) Push Notification
Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
12. 'pn-provider', 'pn-param', and 'pn-prid' URI Parameters for
RFC 8030 (Generic Event Delivery Using HTTP Push) . . . . . . 31
13. Security Considerations . . . . . . . . . . . . . . . . . . . 32
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33
14.1. SIP URI Parameters . . . . . . . . . . . . . . . . . . . 33
14.1.1. pn-provider . . . . . . . . . . . . . . . . . . . . 33
14.1.2. pn-param . . . . . . . . . . . . . . . . . . . . . . 33
14.1.3. pn-prid . . . . . . . . . . . . . . . . . . . . . . 33
14.1.4. pn-purr . . . . . . . . . . . . . . . . . . . . . . 33
14.2. SIP Response Codes . . . . . . . . . . . . . . . . . . . 34
14.2.1. 555 (Push Notification Service Not Supported) . . . 34
14.3. SIP Global Feature-Capability Indicator . . . . . . . . 34
14.3.1. sip.pns . . . . . . . . . . . . . . . . . . . . . . 34
14.3.2. sip.vapid . . . . . . . . . . . . . . . . . . . . . 34
14.3.3. sip.pnsreg . . . . . . . . . . . . . . . . . . . . . 35
14.3.4. sip.pnspurr . . . . . . . . . . . . . . . . . . . . 35
14.4. SIP Media Feature Tag . . . . . . . . . . . . . . . . . 36
14.4.1. sip.pnsreg . . . . . . . . . . . . . . . . . . . . . 36
14.5. PNS Subregistry Establishment . . . . . . . . . . . . . 36
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 37
15.1. Normative References . . . . . . . . . . . . . . . . . . 37
15.2. Informative References . . . . . . . . . . . . . . . . . 39
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40Part 1 of 10 is done, bestie 🦋 Part 2 (the Introduction and Conventions) is coming next, so stay tuned 💖🌈
1. Introduction ✨
okay bestie, phones and tablets are obsessed with saving battery 🔋💖. So when an app isn't being used, the device or OS will just suspend it 😴. The catch is that a suspended app can't wake itself up with its own internal timers, and it might not wake up for incoming network traffic either 😭. So something else has to poke it awake. That's where a Push Notification Service (PNS) comes in 🧚. A PNS is a service that delivers messages other apps asked for to a user application, just to wake it up. Those messages are called push notifications, and depending on the app they might carry payload data 🎀. An app can ask for a push notification to go to a single user application or to multiple user applications 🦋.
Typically, each operating system has its own dedicated PNS 🌈, and there are a bunch of them out there. Some are based on the standardized mechanism in [RFC8030], and others are proprietary. For example, Apple iOS devices use the Apple Push Notification service (APNs), while Android devices use the Firebase Cloud Messaging (FCM) service. Each PNS has its own lingo and function names, so this document keeps its terminology PNS-independent 💅. If the PNS is based on [RFC8030], the SIP proxy takes on the role of the application server 👑.
When a Session Initiation Protocol (SIP) User Agent (UA) [RFC3261] is suspended, it's stuck. It can't send binding-refresh SIP REGISTER requests, it can't receive incoming SIP requests, and it might not be able to use internal timers to wake itself 💀. A suspended UA also can't keep its connections alive with the SIP Outbound Mechanism [RFC5626], because it can't send periodic keep-alive messages 🙈. So a PNS is needed to wake the SIP UA up so it can do all of those things 🫶.
This document explains how a PNS can wake a suspended UA using push notifications, so the UA can send binding-refresh REGISTER requests and receive incoming SIP requests ✨. It defines new SIP URI parameters and new feature-capability indicators [RFC6809] that can be used to:
- indicate support for the mechanism defined in this document;
- exchange PNS information between the UA and the SIP entity (realized as a SIP proxy in this document) that will request that push notifications are sent to the UA; and
- request such push notification requests.
NOTE: Even if a UA is able to be awakened by means other than receiving push notifications (e.g., by using internal timers) in order to send periodic binding-refresh REGISTER requests, it might still be useful to suspend the UA between the sending of binding-refresh requests (as it will save battery life) and use push notifications to wake the UA when an incoming SIP request UA arrives.
Here's the registration flow 🎀. When a UA registers with a PNS (Figure 1), it gets a unique Push Resource ID (PRID) tied to that push notification registration. The UA then uses a REGISTER request to hand the PRID over to the SIP proxy, and the proxy requests that push notifications be sent to the UA 🦋.
When the SIP proxy gets a SIP request for a new dialog or a standalone SIP request addressed towards a UA, or when it decides the UA needs to send a binding-refresh REGISTER request, the proxy sends a push request containing the UA's PRID to the PNS. The PNS then sends a push notification to the UA 🔥. Once the UA gets that push notification, it can send a binding-refresh REGISTER request. The proxy receives that REGISTER from the UA and forwards it to the SIP registrar [RFC3261]. After accepting the REGISTER request, the SIP registrar sends a 2xx response to the proxy, which forwards the response to the UA. If the push notification request was triggered by a SIP request addressed towards the UA, the proxy can then forward that SIP request to the UA using normal SIP routing procedures 🌸. In some cases, the proxy can forward the SIP request without waiting for the SIP 2xx response to the REGISTER request from the SIP registrar. Just note that this mechanism necessarily adds delay to responding to requests that require push notification ⏳. The consequences of that delay are discussed in Section 5.6.2.
If there are Network Address Translators (NATs) between the UA and the proxy, the REGISTER request sent by the UA creates NAT bindings that allow the incoming SIP request that triggered the push notification to reach the UA 🧚.
NOTE: The lifetime of any NAT binding created by the REGISTER request only needs to be long enough for the SIP request that triggered the push notification to reach the UA.
Figure 1 shows the generic push notification architecture supported by the mechanism in this document 🗺️.
The SIP proxy MUST be in the signaling path of REGISTER requests sent by the UA towards the registrar, and of SIP requests (for a new dialog or a standalone) forwarded by the proxy responsible for the UA's domain (sometimes referred to as home proxy, Serving Call Session Control Function (S-CSCF), etc.) towards the UA. The proxy can also be co-located with the proxy responsible for the UA's domain. This also ensures that the Request-URI of SIP requests (for a new dialog or a standalone) can be matched against contacts in REGISTER requests 💜.
+--------+ +---------+ +-----------+ +-------------+
| | | | | | | SIP |
| SIP UA | | Push | | SIP Proxy | | Registrar / |
| | | Service | | | | Home Proxy |
+--------+ +---------+ +-----------+ +-------------+
| | | |
| Subscribe | | |
|---------------->| | |
| | | |
| PRID | | |
|<----------------| | |
| | | |
| SIP REGISTER (PRID) | |
|===================================>| |
| | |SIP REGISTER (PRID)|
| | |==================>|
| | | |
| | | SIP 200 OK |
| | |<==================|
| SIP 200 OK | | |
|<===================================| |
| | | |
| | | SIP INVITE (PRID) |
| | |<==================|
| | | |
| |Push Request (PRID) |
| |<-----------------| |
|Push Message (PRID) | |
|<----------------| | |
| | | |
| SIP REGISTER (PRID) | |
|===================================>| |
| | |SIP REGISTER (PRID)|
| | |==================>|
| | | |
| | | SIP 200 OK |
| | |<==================|
| SIP 200 OK | | |
|<===================================| |
| | | |
| SIP INVITE | | |
|<===================================| |
| | | |
------- Push Notification API
======= SIP
Figure 1: SIP Push Information FlowHere's an example of a SIP REGISTER request in the flow above 📝:
REGISTER sip:alice@example.com SIP/2.0
Via: SIP/2.0/TCP alicemobile.example.com:5060;branch=z9hG4bKnashds7
Max-Forwards: 70
To: Alice <sip:alice@example.com>
From: Alice <sip:alice@example.com>;tag=456248
Call-ID: 843817637684230@998sdasdh09
CSeq: 1826 REGISTER
Contact: <sip:alice@alicemobile.example.com;
pn-provider=acme;
pn-param=acme-param;
pn-prid=ZTY4ZDJlMzODE1NmUgKi0K>
Expires: 7200
Content-Length: 0
Figure 2: SIP REGISTER Example2. Conventions 📖
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
3. Push Resource ID (PRID) 🎀
When a SIP UA registers with a PNS, it receives a unique Push Resource ID (PRID). That's a value tied to the registration that can be used to generate push notifications 🦋.
The format of the PRID varies depending on the PNS 🌈.
The details about discovering the PNS, and the procedures for push notification registration and maintenance, are outside the scope of this document 🙈. The info needed to contact the PNS is typically preconfigured in the device's operating system 💻.
4. SIP User Agent (UA) Behavior 💅
4.1. REGISTER ✨
okay bestie, this section is all about how a SIP UA sends REGISTER requests 💅 (either a brand-new one for a binding or a binding-refresh one) to ask the SIP network for push notifications, to turn them off, and to find out which PNS types the network supports 🦋. The vibe is "ask nicely, get pinged, be polite about it" 🎀
Unless it says otherwise, the normal SIP UA registration rules [RFC3261] still apply 💖. The extra stuff in this section kicks in when the REGISTER request has a 'pn-provider' SIP URI parameter in the Contact header field URI (Figure 2) ✨.
The procedures here are per binding [RFC3261] 🌸. So if a UA makes multiple bindings (like one for IPv4 and one for IPv6), it has to do the whole routine for each binding 🧚.
NOTE: Since a push notification makes the UA refresh all bindings, if a SIP UA has multiple bindings, it is preferable if they all expire at the same time 🙈. That way some bindings don't get refreshed earlier than they need to be 💅.
okay this part is giving privacy 🔒 For privacy and security reasons, a UA MUST NOT put the SIP URI parameters defined in this spec into non-REGISTER requests, except for 'pn-purr' 🫶. That keeps the PNS info tied to the UA from reaching the remote peer. Like, the UA MUST NOT put 'pn-prid' in the Contact header field URI of an INVITE request 💀. REGISTER requests never reach the remote peer anyway, since the UA's registrar terminates them 🌈. But the registrar MUST still make sure those parameters don't get sent to other users, for example with the SIP event package for registrations mechanism [RFC3680] 👑. See Section 13 for more ✨.
4.1.1. Request Push Notifications 🔥
This part is how a SIP UA asks the SIP network for push notifications 🍓. It assumes the UA already got a PRID from a PNS 🧚. How to get that PRID is PNS-specific and totally outside this spec, so check the PNS-specific docs for the deets 📚.
Heads up: this spec does NOT define a way to explicitly ask for push notifications for other usages besides binding-refresh REGISTER requests (like periodic subscription-refresh SUBSCRIBE requests [RFC6665]) 🙈. It also doesn't say how to tell apart the push notifications for those other usages from the ones that trigger binding-refresh REGISTERs 😭. If a UA wants push for other stuff, it can do those actions (on top of sending a binding-refresh REGISTER) every time it gets a push, using the same refresh interval it uses for the binding refreshes ✨.
To ask for push notifications, the UA MUST put these SIP URI parameters in the SIP Contact header field URI of the REGISTER request: 'pn-provider', 'pn-prid', and 'pn-param' (if the specific PNS needs it) 💖. The 'pn-provider' parameter says which type of PNS to use 🦋.
If the UA gets a 2xx response to that REGISTER with a Feature-Caps header field [RFC6809] that has a 'sip.pns' feature-capability indicator matching the same PNS type as 'pn-provider', that means another SIP Proxy in the network will ask for push notifications to be sent to the UA 🌸. And if that same Feature-Caps header also has a 'sip.vapid' feature-capability indicator, the proxy supports the Voluntary Application Server Identification (VAPID) mechanism [RFC8292] to limit push notifications to the UA 🔐.
NOTE: The VAPID-specific procedures of the SIP UA are outside the scope of this document 🙃.
Now the not-so-fun case 😭 If the UA gets a non-2xx response to the REGISTER, or a 2xx response with no Feature-Caps header field [RFC6809] carrying a 'sip.pns' feature-capability indicator, the UA MUST NOT assume the proxy will ask for push notifications to be sent to it 💀. What the UA does then is outside this spec 🫶.
If the PRID is only good for a limited time, the UA is responsible for getting a fresh PRID from the PNS and sending a binding-refresh REGISTER with the updated 'pn-*' parameters 🌈. And if a PRID stops being valid and the UA can't get a new one, the UA MUST disable the push notifications tied to that PRID (Section 4.1.2) 🙅♀️.
4.1.2. Disable Push Notifications 🧹
When a UA wants to turn off push notifications it asked for before, it SHOULD remove the binding [RFC3261] ✨. The exception is if the UA can't do SIP stuff anymore (like a forced shutdown), in which case the registrar removes the binding once it expires ⏳. When the UA sends the REGISTER to remove the binding, it MUST NOT put the 'pn-prid' SIP URI parameter in the Contact header field URI 💅. No 'pn-prid' is how the SIP network knows the UA doesn't want push notifications for that PRID anymore 👋.
4.1.3. Receive Push Notifications 🔔
When a UA gets a push notification, it MUST send a binding-refresh REGISTER request 💖. That REGISTER MUST carry the same set of 'pn-*' SIP URI parameters in the SIP Contact header field URI that the UA used when it asked for push notifications (Section 4.1.1) 🎀. Heads up though: sometimes the PNS updates the PRID value, and then the UA puts the new value in 'pn-prid' of the binding-refresh REGISTER 🦋.
After the UA gets a 2xx response to that REGISTER, it might receive a SIP request for a new dialog (like a SIP INVITE) or a standalone SIP request (like a SIP MESSAGE), if that request made the proxy ask for the push notification to be sent to the UA 📞. Also, depending on which transport protocol is used, the SIP request could show up before the REGISTER response does 😱.
If the SIP UA has multiple bindings, it MUST send a binding-refresh REGISTER request for each one of them whenever it gets a push notification 🌸.
This spec doesn't define any usage of the push-notification payload 🙈. If a SIP UA gets a push notification with a payload, it can throw the payload away, but it will still send a binding-refresh REGISTER request 🗑️✨.
4.1.4. Sending Binding-Refresh Requests Using Non-push Mechanism ⏰
If a UA can send binding-refresh REGISTER requests without push (like with an internal timer that wakes the UA up every so often), it MUST put a 'sip.pnsreg' media feature tag [RFC3840] in the Contact header field of each REGISTER request 🧚.
If the UA gets a 2xx response to the REGISTER with a Feature-Caps header field carrying a 'sip.pnsreq' feature-capability indicator, the UA MUST send a binding-refresh REGISTER request before the binding expires 🚨. The indicator value is the minimum number of seconds before the binding expiration when the UA needs to send that REGISTER ⏱️.
If the UA gets a 2xx response to the REGISTER with no Feature-Caps header field carrying a 'sip.pnsreq' feature-capability indicator, the UA SHOULD only send a binding-refresh REGISTER when it gets a push notification (even if it could do non-push refreshes) 🔔, or when something needs an immediate REGISTER, like the UA being given new contact parameters because of a network config change 🛠️.
Even if the UA can send binding-refresh REGISTERs without push, it MUST still send a binding-refresh REGISTER whenever it gets a push notification (Section 4.1.3) 💖.
NOTE: If the UA uses a non-push mechanism to wake up and send binding-refresh REGISTERs, those REGISTERs update the binding expiration timer 🕰️, so the proxy doesn't need to ask for a push notification to wake the UA. The proxy will still ask for a push notification whenever it gets a SIP request aimed at the UA (Section 5.6.2) 📬. This means the UA can use timers for binding-refresh REGISTERs but still be suspended (to save battery and stuff) between them, and rely on push to wake it up for incoming calls 🔋✨.
Here's an example of a REGISTER with a 'sip.pnsreg' media feature tag 👇
REGISTER sip:alice@example.com SIP/2.0
Via: SIP/2.0/TCP alicemobile.example.com:5060;branch=z9hG4bKnashds7
Max-Forwards: 70
To: Alice <sip:alice@example.com>
From: Alice <sip:alice@example.com>;tag=456248
Call-ID: 843817637684230@998sdasdh09
CSeq: 1826 REGISTER
Contact: <sip:alice@alicemobile.example.com;
pn-provider=acme;
pn-param=acme-param;
pn-prid=ZTY4ZDJlMzODE1NmUgKi0K>;
+sip.pnsreg
Expires: 7200
Content-Length: 0And here's an example of a REGISTER response with a 'sip.pnsreg' media feature tag and a 'sip.pnsreq' feature-capability indicator 🎀
SIP/2.0 200 OK
Via: SIP/2.0/TCP alicemobile.example.com:5060;branch=z9hG4bKnashds7
To: Alice <sip:alice@example.com>;tag=123987
From: Alice <sip:alice@example.com>;tag=456248
Call-ID: 843817637684230@998sdasdh09
CSeq: 1826 REGISTER
Contact: <sip:alice@alicemobile.example.com;
pn-provider=acme;
pn-param=acme-param;
pn-prid=ZTY4ZDJlMzODE1NmUgKi0K>;
+sip.pnsreg
Feature-Caps: *;+sip.pns="acme";+sip.pnsreg="121"
Expires: 7200
Content-Length: 0Figure 3: SIP REGISTER When Using Non-push Mechanism Example 🦋
4.1.5. Query Network PNS Capabilities 🔍✨
okay bestie, this section is about how a SIP UA can ask the network which types of PNSs it supports 👀, plus other PNS-related capabilities like VAPID support 🔑. when a UA does a query, it is not asking for push notifications, so it can totally do this before it has registered with a PNS and gotten a PRID. no pressure 💅
To perform a query, the UA MUST insert a 'pn-provider' SIP URI parameter in the Contact header field URI of the REGISTER request 📝:
- If the UA inserts a
'pn-provider'parameter value, indicating support of a type of PNS, the SIP network will only tell the UA whether that type of PNS is supported 🎯. - If the UA does not insert a
'pn-provider'parameter value (i.e., it inserts an "empty"'pn-provider'parameter), the SIP network will tell the UA about all types of PNSs supported by the network 🌈. this is useful, e.g., if the UA supports more than one type of PNS. also, it is not possible to insert multiple parameter values in the'pn-provider'parameter, so don't even try 🙈.
The UA MUST NOT insert a 'pn-prid' SIP URI parameter in the Contact header field URI of the REGISTER request 🚫.
If the UA receives a 2xx response to the REGISTER request, the response will contain one or more Feature-Caps header fields with a 'sip.pns' feature-capability indicator 🦋. this tells the UA which types of PNSs the SIP network supports. if the UA inserted a 'pn-provider' SIP URI parameter value in the REGISTER request, the response will only indicate whether the SIP network supports the type of PNS that the UA supports 💜.
If the UA receives a 555 (Push Notification Service Not Supported) response to the REGISTER request, and if the UA inserted a 'pn-provider' SIP URI parameter in the REGISTER request, the response means the network does not support the type of PNS that the UA said it supports 💀. if the UA did not insert a 'pn-provider' parameter in the REGISTER request, the response means the network does not support any type of PNS, but it still supports the 555 (Push Notification Service Not Supported) response 😭.
NOTE: It is optional for a UA to perform a query before it requests push notifications from the SIP network. no vibes-check required 🫶.
5. SIP Proxy Behavior 🛰️
5.1. PNS Provider 🏢
The type of PNS is identified by the 'pn-provider' SIP URI parameter 🏷️. in some cases there might only be one PNS provider for a given type of PNS, while in other cases there might be multiple providers. the 'pn-param' SIP URI parameter gives more details about the actual PNS provider that will be used 🔍.
The protocol and format used for the push notification requests are PNS-specific, and the details for constructing and sending a push notification request are outside the scope of this specification 🙅♀️. that's a different lane, bestie.
5.2. SIP Request Push Bucket 🪣
When a SIP proxy receives a SIP request addressed towards a UA, that will trigger the proxy to request that a push notification be sent to the UA 🔔. the proxy places the request in storage (referred to as the SIP Request Push Bucket 🪣), and the proxy starts a timer (referred to as the Bucket Timer ⏰) associated with the transaction. a SIP request is removed from the bucket when one of the following has happened: the proxy forwards the request towards the UA, the proxy sends an error response to the request, or the Bucket Timer times out ✨. the detailed procedures are in the sections below.
Exactly how the SIP Request Push Bucket is implemented is outside the scope of this document 🤷♀️. one option is to use the PRID as a key to search for SIP requests in the bucket 🔑. note that mid-dialog requests (Section 6) do not carry the PRID in the SIP request itself, so keep that in mind 👀.
5.3. SIP URI Comparison Rules ⚖️
By default, a SIP proxy uses the URI comparison rules defined in [RFC3261] 📜. however, when a SIP proxy compares the Contact header field URI of a 2xx response to a REGISTER request with a Request-URI of a SIP request in the SIP Request Push Bucket (Section 5.2), the proxy uses the URI comparison rules with the following additions: the 'pn-prid', 'pn-provider', and 'pn-param' SIP URI parameters MUST also match 💖. if a 'pn-*' parameter is present in one of the compared URIs but not in the other URI, there is no match 🙅♀️.
If only the 'pn-*' SIP URI parameters listed above match, but other parts of the compared URIs do not match, a proxy MAY still consider the comparison successful based on local policy 🤔. this can happen in a race condition when the proxy compares the Contact header field URI of a 2xx response to a REGISTER request with a Request-URI of a SIP request in the SIP Request Push Bucket (Section 5.2). the UA may have changed some parts of the Contact header field URI in the REGISTER request, but the Request-URI of the SIP request in the bucket still has the old parts 🌀.
5.4. Indicate Support of Type of PNS 📣
A SIP proxy uses feature-capability indicators [RFC6809] to indicate support of types of PNSs and additional features (e.g., VAPID) associated with the type of PNS 🎀. a proxy MUST use a separate Feature-Cap header field for each supported type of PNS 🫧. a feature-capability indicator that indicates support of an additional feature associated with a given type of PNS MUST be inserted in the same Feature-Caps header field that is used to indicate support of the type of PNS 📦.
This specification defines the following feature-capability indicators that a proxy can use to indicate support of additional features associated with a given type of PNS: 'sip.vapid', 'sip.pnsreg', and 'sip.pnspurr' 🌸. these feature-capability indicators MUST only be inserted in a Feature-Caps header field that also contains a 'sip.pns' feature-capability indicator 🙌.
5.5. Trigger Periodic Binding Refresh 🔁
To request that a push notification be sent to a SIP UA, a SIP proxy needs to know when a binding will expire ⏳. the proxy needs to be able to get that information from the registrar using some mechanism, or run its own registration timers 🧠. those mechanisms are outside the scope of this document, but they could be implemented, e.g., by using the SIP event package for registrations mechanism [RFC3680] 🦋.
When the proxy receives an indication that the UA needs to send a binding-refresh REGISTER request, the proxy will request that a push notification be sent to the UA 🔔.
NOTE: the push notification needs to be requested early enough for the associated binding-refresh REGISTER request to reach the registrar before the binding expires. it is RECOMMENDED that the proxy requests the push notification at least 120 seconds before the binding expires ⏰ (timing is everything, periodt).
If the UA has indicated, using the 'sip.pnsreg' media feature tag, that it is able to wake itself using a non-push mechanism in order to send binding-refresh REGISTER requests, and if the proxy does not receive a REGISTER request prior to 120 seconds before the binding expires, the proxy MAY request that a push notification be sent to the UA to trigger the UA to send a binding-refresh REGISTER request 🌙.
NOTE: As described in Section 4.1.5, a UA might send a REGISTER request without including a'pn-prid'SIP URI parameter, in order to retrieve push notification capabilities from the network before the UA expects to receive push notifications from the network 🔍. a proxy will not request that push notifications are sent to a UA that has not provided a'pn-prid'SIP URI parameter (Section 5.6.2) 🙅♀️.
If the proxy receives information that a binding associated with a PRID has expired, or that a binding has been removed, the proxy MUST NOT request that further push notifications are sent to the UA using that PRID 🛑. no more pings for that PRID, bestie.
5.6. SIP Requests 📬
5.6.1. REGISTER 📝
This section describes how a SIP proxy processes SIP REGISTER requests (an initial REGISTER request for a binding, or a binding-refresh REGISTER request) 🎀.
The procedures in this section apply when the REGISTER request contains a 'pn-provider' SIP URI parameter in the Contact header field URI 💅. in other cases, the proxy MUST skip the procedures in this section and process the REGISTER request using normal SIP procedures 🫶.
5.6.1.1. Request Push Notifications ✨
okay so this section is all about what a SIP proxy does when a SIP UA asks the SIP network for push notifications 📲 let's gooo
these procedures kick in when the REGISTER request has a pn-prid SIP URI parameter in the Contact header field URI, on top of the pn-provider SIP URI parameter 💖
when a proxy gets a REGISTER with a Feature-Caps header field that carries the sip.pns feature-capability indicator, it means another proxy sitting between this one and the UA already supports the UA's type of PNS 🦋 and that proxy is the one that'll ask for pushes to be sent to the UA. so this proxy MUST skip the rest of this section and just process the REGISTER with normal SIP procedures. not its job here, bestie 💅
when a proxy gets a REGISTER that does NOT have a Feature-Caps header field with the sip.pns indicator, it goes through these steps:
- if the proxy doesn't support the UA's type of PNS, or the REGISTER doesn't have all the info required for that type of PNS, the proxy SHOULD forward the request towards the registrar and skip the rest of the section. if the proxy knows (through local configuration) that none of the other proxies between itself and the registrar support that type of PNS, it MAY send a SIP 555 (Push Notification Service Not Supported) response instead of forwarding. 🙈
- if the proxy supports the UA's type of PNS, but thinks the requested binding expiration interval [RFC3261] is too short (more on that below), the proxy MUST either send a 423 (Interval Too Brief) response to the REGISTER request or forward the request towards the registrar and skip the rest of the section. 😭
- if the proxy supports the UA's type of PNS, the proxy MUST indicate support of that type of PNS (Section 5.4) in the REGISTER request before it forwards it towards the registrar. this tells the proxies between it and the registrar that it supports the UA's type of PNS, and that it's going to request that push notifications get sent to the UA. main character energy 👑
okay now the "too short" thing 🥺 a binding expiration interval MUST be considered too short if the binding would expire before the proxy can request that a push notification be sent to the UA, which then triggers the UA to send a binding-refresh REGISTER request. the proxy MAY consider the interval too short based on its own policy, so it can reduce load on the system 🌸
when a proxy gets a 2xx response to the REGISTER request, and it had indicated support of a type of PNS in that REGISTER (see above), it does the following:
- if the proxy considers the binding expiration interval indicated by the registrar too short (see above), the proxy forwards the response towards the UA and MUST skip the rest of the procedures in this section. ⏭️
- the proxy MUST indicate support of the same type of PNS in the REGISTER response. and on top of that:
- if the proxy supports the VAPID mechanism [RFC8292], the proxy MUST indicate support of the mechanism, using the
sip.vapidfeature-capability indicator, in the REGISTER response. the indicator value holds the public key that identifies the proxy 🔑 and the proxy MUST determine whether the PNS provider supports the VAPID mechanism before it indicates support of it. no guessing, bestie 🧚 - if the proxy received a
sip.pnsregmedia feature tag in the REGISTER request, the proxy SHOULD insert asip.pnsregfeature-capability indicator with an indicator value bigger than 120 in the response, unless the proxy always wants to request that push notifications are sent to the UA in order to trigger the UA to send a binding-refresh REGISTER request. 🎀
- if the proxy supports the VAPID mechanism [RFC8292], the proxy MUST indicate support of the mechanism, using the
5.6.1.2. Query Network PNS Capabilities 🔍
this section is the proxy side of the moment a SIP UA asks what push-notification support the SIP network has (Section 4.1.5) 🦋 it's giving "what can you do for me?" energy 💜
these procedures apply when the REGISTER request has a pn-provider SIP URI parameter but NO pn-prid SIP URI parameter in the Contact header field URI of the REGISTER request. 🙃
when a proxy gets a REGISTER with a pn-provider SIP URI parameter that says which type of PNS the UA supports, the proxy MUST perform these actions:
- if the proxy supports the UA's type of PNS, the proxy MUST indicate support of that type of PNS (Section 5.4) in the REGISTER request before it forwards it towards the registrar. this lets any other proxies between it and the registrar know that it supports the UA's type of PNS. 🫶
- if the proxy doesn't support the UA's type of PNS, but the REGISTER has Feature-Caps header fields that indicate support for one or more types of PNSs, the proxy forwards the request towards the registrar. ➡️
- if the proxy doesn't support the UA's type of PNS, and the REGISTER does NOT have Feature-Caps header fields indicating support for one or more types of PNSs, the proxy MUST either forward the request towards the registrar or send a SIP 555 (Push Notification Service Not Supported) response towards the UA. ⚖️ the proxy MUST NOT send a SIP 555 (Push Notification Service Not Supported) response unless it knows (through local configuration) that no other proxy supports any of the types of PNSs the UA supports. > that's a hard no unless the config says otherwise, bestie 🚫
when a proxy gets a REGISTER request and the pn-provider SIP URI parameter has no parameter value, the proxy MUST indicate support of each type of PNS the proxy supports before it forwards the request towards the registrar. 🌈 big "I support everything" moment ✨
when a proxy gets a 2xx response to the REGISTER request, and it had indicated support of one or more types of PNSs in the REGISTER (see above), the proxy MUST indicate support of the same set of types of PNSs in the response. and if the proxy supports the VAPID mechanism for one or more types of PNSs, the proxy MUST indicate support of the mechanism for those PNSs in the response too. 🔐💅
5.6.2. Initial Request for Dialog or Standalone Request 🎀
okay so this part only kicks in once a SIP proxy has said "yep, I'll request push notifications for the SIP UA" 📣
When the proxy gets a SIP request that starts a new dialog (like an INVITE) or a standalone one (like a MESSAGE) aimed at a SIP UA, and the Request-URI has a pn-provider SIP URI parameter, a pn-prid SIP URI parameter, and a pn-param SIP URI parameter (if that particular PNS provider needs one), the proxy asks for a push notification to be sent to the UA using the info in the pn-* SIP URI parameters. Then it parks the SIP request in the SIP Request Push Bucket 🪣. The push notification triggers the UA to send a binding-refresh REGISTER request, which the proxy handles as described in Section 5.6.1. Plus, the proxy MUST store the Contact URI of the REGISTER request for the whole lifetime of the REGISTER transaction 💅
NOTE: If the proxy gets a SIP request that doesn't have those pn-* SIP URI parameters, the proxy's handling is based on local policy 🤷♀️ If the proxy also serves UAs that don't use the SIP push mechanism, it can forward the request towards the UA. Otherwise, it can reject the request. 🦋
When the proxy gets a 2xx response to the REGISTER request, it does the following:
- The proxy processes the
REGISTERresponse as described in Section 5.6.1. - The proxy checks whether the SIP Request Push Bucket has a SIP request linked to the
REGISTERtransaction. It does this by comparing (Section 5.3) the Contact header field URI in theREGISTERresponse with the Request-URIs of the SIP requests in the bucket. If there's a match, the proxy MUST remove the SIP request from the bucket and forward it towards the UA. 🚀
Why wait for the REGISTER response before forwarding anything? 🧐 Because the proxy needs to be sure the registrar accepted the REGISTER request, and that the UA who sent it is actually allowed to receive messages for that Request-URI. Main character behavior, but make it secure 🔐
If the proxy gets a non-2xx response to the REGISTER request, it compares the Contact URI it stored from the REGISTER request (see above) with the Request-URIs of the SIP requests in the SIP Request Push Bucket. If there's a match, the proxy SHOULD remove that request from the bucket and send an error response to it. It is RECOMMENDED that the proxy sends either a 404 (Not Found) response or a 480 (Temporarily Unavailable) response to the SIP request, though other response codes can be used too. 💌 However, if the REGISTER response is expected to trigger a new REGISTER request from the UA (for example, if the registrar wants the UA to do authentication), the proxy MAY keep the SIP request in the bucket. ✨
If the push notification request fails (check the PNS-specific documentation for the details), the proxy MUST remove the SIP request from the bucket and send an error response to it. It is RECOMMENDED that the proxy sends either a 404 (Not Found) response or a 480 (Temporarily Unavailable) response. Other response codes can be used as well. 🙃
After the proxy has requested a push notification for a UA, if it doesn't get a REGISTER response with a Contact URI that matches the Request-URI of the SIP request before the Bucket Timer (Section 5.2) for that SIP request runs out, the proxy MUST remove the SIP request from the SIP Request Push Bucket (Section 5.2) and send a 480 (Temporarily Unavailable) response. The Bucket Timer time-out value is set by local policy, with the guidelines below in mind. ⏰
Heads up, bestie 😭: As discussed in [RFC4320] and [RFC4321], non-INVITE transactions need to complete immediately, or they risk losing a race. That causes stress on intermediaries and state misalignment at the endpoints. The mechanism in this document inherently delays the final response to any non-INVITE request that needs a push notification. So if the proxy forwards the SIP request towards the SIP UA, and the UA accepts it, but the transaction times out at the sender before the successful response arrives, the endpoints end up out of sync: the sender thinks the transaction failed, while the receiver thinks it succeeded. 💀 The SIP proxy has to account for this when it sets the Bucket Timer for the transaction, so the error response (triggered by a Bucket Timer time-out) reaches the sender before the transaction times out. If the accumulated delay from this mechanism combined with any other mechanisms in the path of processing the non-INVITE transaction can't be kept short, this mechanism should not be used. For networks in that situation, an alternative (left for possible future work) would be for the proxy to immediately return a new error code meaning "wait at least the number of seconds specified in this response and retry your request" before starting the push notification. 🫶
NOTE: While this document was being worked on, implementation test results showed that the time from when the proxy requests a push notification until it receives the REGISTER request is typically around 2 seconds. That time might vary depending on the characteristics and load of the SIP network and the PNS. 🌸
Okay, there are also two cases where a proxy can, as an optimization, forward a SIP request towards a UA without waiting for a 2xx response to a REGISTER request or requesting that a push notification be sent to the UA: 👑
- If the proxy can authenticate the sender of the
REGISTERrequest and verify that it's allowed by authorization policy, the proxy doesn't need to wait for the 2xx response before forwarding the SIP request towards the UA. In that case, the proxy compares the Contact URI of theREGISTERrequest against the Request-URIs of the SIP requests in the SIP Request Push Bucket. 🔥 - If the proxy knows the UA is awake, and that the UA can receive the SIP request without first sending a binding-refresh
REGISTERrequest, the proxy doesn't need to request a push notification for the UA (the UA won't send a binding-refreshREGISTERrequest) before forwarding the SIP request towards the UA. How the proxy gets that knowledge might depend on the implementation or deployment architecture, and that's outside the scope of this document. 🧚
Some PNS providers allow payload in push notifications. This specification does not define the use of such payload, beyond any payload the PNS itself might require. 💜
6. Support of Long-Lived SIP Dialogs ✨
Okay so some SIP dialogs can hang around for ages with barely any activity 🥱. When the SIP event notification mechanism [RFC6665] is in use, there can be a super long gap between mid-dialog requests. That means a SIP UA might get suspended, and then it has to be woken up so it can actually receive those mid-dialog requests 💤➡️📲.
SIP requests that start a new dialog, and standalone SIP requests aimed at a UA with 'pn-*' SIP URI parameters, let the proxy ask for a push notification to be sent to the UA (Section 5.6.2). But mid-dialog requests aimed at the UA won't have any 'pn-*' SIP URI parameters 🙈. So the proxy needs a way to stash the information it needs to request a push notification, and then pull it back out when a mid-dialog request for the UA shows up. This section defines that mechanism. The UA and proxy procedures here get layered on top of the generic procedures in this specification, so both sets apply 🫶.
+--------+ +---------+ +-----------+ +-------------+
| | | | | | | SIP |
| SIP UA | | Push | | SIP Proxy | | Registrar / |
| | | Service | | | | Home Proxy |
+--------+ +---------+ +-----------+ +-------------+
| | | |
| PNS Register | | |
|---------------->| | |
| | | |
| PRID | | |
|<----------------| | |
| | | |
| SIP REGISTER (PRID) | |
|===================================>| |
| | |SIP REGISTER (PRID)|
| | |==================>|
| | | |
| | +-----------------------+ |
| | | Store PRID (key=PURR) | |
| | +-----------------------+ |
| | | |
| | | SIP 200 OK |
| | |<==================|
| SIP 200 OK (PURR) | |
|<===================================| |
| | | |
| | | |
| SIP INVITE (PURR) | |
|===================================>| |
| | |SIP INVITE (PURR) |
| | |==================>|
| | | |
| | | SIP 200 OK |
| | |<==================|
| SIP 200 OK | | |
|<===================================| |
| | | |
| | | |
| | | |
| | |SIP UPDATE (PURR) |
| | |<==================|
| | | |
| | +-----------------------+ |
| | | Fetch PRID (key=PURR) | |
| | +-----------------------+ |
| | | |
| |Push Request (PRID) |
| |<-----------------| |
|Push Message (PRID) | |
|<----------------| | |
| | | |
| SIP REGISTER (PRID) | |
|===================================>| |
| | |SIP REGISTER (PRID)|
| | |==================>|
| | | |
| | | SIP 200 OK |
| | |<==================|
| SIP 200 OK (PURR) | |
|<===================================| |
| | | |
| SIP UPDATE | | |
|<===================================| |
| | | |
------- Push Notification API
======= SIP
Figure 4: SIP Push Long-Lived Dialog Flow6.1. SIP UA Behavior 💖
6.1.1. Initial Request for Dialog
If the UA is up for receiving push notifications whenever a proxy gets a mid-dialog request aimed at it, the UA MUST insert a 'pn-purr' SIP URI parameter (Section 6.2.1) into the Contact header field URI of the initial request for a dialog, or into the 2xx response to such requests. The UA MUST use a parameter value identical to the last 'sip.pnspurr' feature-capability indicator (Section 6.2.1) it received in a REGISTER response. If the UA has never received a 'sip.pnspurr' feature-capability indicator, the UA MUST NOT insert a 'pn-purr' SIP URI parameter in any request or response 🚫.
Whether the UA wants push notifications for incoming mid-dialog requests is up to its local policy. That policy might look at the type of SIP dialog, the type of media (if any) negotiated for the dialog [RFC3264], and so on 🎀.
NOTE: Since the 'pn-purr' SIP URI parameter only applies to a given dialog, the UA needs to insert a 'pn-purr' parameter in the Contact header field URI of the request or response for each dialog where it wants to receive push notifications triggered by incoming mid-dialog requests.
6.2. SIP Proxy Behavior 👑
6.2.1. REGISTER
If the proxy supports requesting push notifications triggered by mid-dialog requests sent to the registered UA, the proxy MUST store the information (the 'pn-*' SIP URI parameters) needed to request push notifications for the UA when it receives an initial REGISTER request for a binding from the UA. On top of that, the proxy MUST generate a value that's unique within the context of the proxy, called the PURR (Proxy Unique Registration Reference), which can be used as a key to look up that information later 🔑.
To prevent client fingerprinting 🕵️♀️, the proxy MUST periodically generate a new PURR value, even if the 'pn-*' parameters didn't change. However, as long as there are ongoing dialogs tied to the old value, the proxy MUST keep storing it so it can request push notifications for the UA when a mid-dialog request addressed towards the UA comes in. Also, the PURR value MUST be generated in such a way that it is unforgeable, anonymous, and unlinkable to entities other than the proxy. It must not be possible for an attacker to generate a valid PURR, to associate a PURR with a specific user, or to determine when two PURRs correspond to the same user. It can be generated, for example, by using a cryptographically secure random function with an appropriately large output size.
Whenever the proxy receives a 2xx response to a REGISTER request, the proxy MUST insert a 'sip.pnspurr' feature-capability indicator with the latest PURR value (see above) in the response.
6.2.2. Initial Request for Dialog
When a proxy receives an initial request for a dialog from a UA whose Contact header field URI contains a 'pn-purr' SIP URI parameter with a PURR value the proxy has generated (Section 6.2.1), the proxy MUST add a Record-Route header to the request so it inserts itself into the dialog route [RFC3261] before forwarding the request.
When the proxy receives an initial request for a dialog addressed towards the UA, and the proxy has generated a PURR value associated with the 'pn-*' parameters inserted in the SIP URI of the request (Section 6.2.2), the proxy MUST add a Record-Route header to the request so it inserts itself into the dialog route [RFC3261] before forwarding the request.
6.2.3. Mid-dialog Request
When the proxy receives a mid-dialog SIP request addressed towards the UA that contains a 'pn-purr' SIP URI parameter, and the proxy is able to retrieve the stored information needed to request that a push notification be sent to the UA (Section 6.2.1), the proxy MUST place the SIP request in the SIP Request Push Bucket and request that a push notification be sent to the UA 📦.
NOTE: The 'pn-purr' SIP URI parameter will be carried either in the Request-URI or in a Route header field [RFC3261] of the SIP request, depending on how the route set [RFC3261] of the mid-dialog SIP request was constructed.
When the proxy receives a 2xx response to a REGISTER request, the proxy checks whether the SIP Request Push Bucket contains a mid-dialog SIP request associated with the REGISTER transaction. If the bucket holds such a request, the proxy MUST remove the SIP request from the SIP Request Push Bucket and forward it towards the UA 🚀.
Note that the proxy does not perform a URI comparison (Section 5.3) when processing mid-dialog requests, since a mid-dialog request won't contain the 'pn-prid', 'pn-provider', and 'pn-param' SIP URI parameters. The proxy only looks for a mid-dialog request carrying the PURR value associated with the REGISTER 2xx response.
As described in Section 5.6.2, while waiting for the push notification request to succeed, and then for the associated REGISTER request and 2xx response, the proxy needs to keep in mind that the transaction associated with the mid-dialog request will eventually time out at the sender of the request (User Agent Client), and the sender will consider the transaction a failure ⏳.
When a proxy sends an error response to a mid-dialog request (for example, due to a transaction time out), the proxy SHOULD select a response code that only impacts the transaction associated with the request [RFC5079] 🎯.
7. Support of SIP Replaces ✨
okay so [RFC3891] is the mechanism that lets a SIP UA replace a dialog with another one 💅 when a UA wants to do that, it sends an initial request for the new dialog, and the Request-URI of that request carries the Contact header field URI of the peer 🎀
if a SIP proxy wants to be able to ask for a push notification to be sent to a UA when that UA gets an initial request for a dialog that replaces an existing one (using the [RFC3891] mechanism), the proxy and the UA MUST do the following 🫶
- The proxy MUST provide a PURR to the UA during registration (Section 6.2.1).
- The UA MUST insert a 'pn-purr' SIP URI parameter in the Contact header field URI of either the initial request for a dialog or a 2xx response to such requests (Section 6.1.1). This includes dialogs replacing other dialogs, as those dialogs might also get replaced.
- The proxy MUST apply the mechanism defined in Section 6.2.3 to place and retrieve the request from the SIP Request Push Bucket.
also the operator needs to make sure that initial requests for dialogs, addressed to the UA using the contact of the replaced dialog, get routed to the SIP proxy (so it can ask for a push notification to go to the UA) 🦋 the procedures for that are operator-specific and are outside the scope of this specification, so we're not going there today 🙈
8. Grammar 🧚
8.1. 555 (Push Notification Service Not Supported) Response Code
the 555 response code gets added to the "Server-Error" Status-Code definition 🌸 555 (Push Notification Service Not Supported) means the server doesn't support the push notification service named in a 'pn-provider' SIP URI parameter 💀
the use of the SIP 555 response code is only defined for SIP REGISTER responses ✨
8.2. 'sip.pns' Feature-Capability Indicator
okay this one is so cute 🎀 the sip.pns feature-capability indicator goes in a Feature-Caps header field of a SIP REGISTER request, or in a SIP 2xx response to a REGISTER request. it says the entity supports the SIP push mechanism and which type of push notification service it uses. the values defined for the 'pn-provider' SIP URI parameter are the indicator values 💅
pns-fc = "+sip.pns" EQUAL LDQUOT pns RDQUOT
pns = tag-value
tag-value = <tag-value defined in [RFC3840]>8.3. 'sip.vapid' Feature-Capability Indicator
the sip.vapid feature-capability indicator goes in a SIP 2xx response to a SIP REGISTER request 🦋 it shows the entity supports the Voluntary Application Server Identification (VAPID) [RFC8292] mechanism when the entity asks for a push notification to be sent to a SIP UA. the indicator value is a public key that identifies the entity, and a SIP UA can use it to restrict subscriptions to that entity 🔐 literally so smart
vapid-fc = "+sip.vapid" EQUAL LDQUOT vapid RDQUOT
vapid = tag-value
tag-value = <tag-value defined in [RFC3840]>8.4. 'sip.pnsreg' Feature-Capability Indicator
the sip.pnsreg feature-capability indicator goes in a SIP 2xx response to a SIP REGISTER request 🌈 it says the entity expects binding-refresh REGISTER requests from the SIP UA before the binding expires. this holds even if the entity doesn't ask for a push notification to trigger those refreshes ⭐ the indicator value is the minimum time, in seconds, before the binding expiration when the UA MUST send the REGISTER request 😭
pns-fc = "+sip.pnsreg" EQUAL LDQUOT reg RDQUOT
reg = 1*DIGIT
DIGIT = <DIGIT defined in [RFC3261]>8.5. 'sip.pnsreg' Media Feature Tag
the sip.pnsreg media feature tag goes in the Contact header field of a SIP REGISTER request 🍓 it says the SIP UA can send binding-refresh REGISTER requests for that binding without being woken up by push notifications 🧚 this tag has no values, so it's giving minimalist energy 🤍
pnsreg-mt = "+sip.pnsreg"8.6. 'sip.pnspurr' Feature-Capability Indicator
the sip.pnspurr feature-capability indicator goes in a SIP 2xx response to a SIP REGISTER request 💜 it means the entity will store information that can link a mid-dialog SIP request back to the binding information in the REGISTER request. the whole thing is like a little breadcrumb trail 🍞✨
pnspurr-fc = "+sip.pnspurr" EQUAL LDQUOT pnspurr RDQUOT
pnspurr = tag-value
tag-value = <tag-value defined in [RFC3840]>8.7. SIP URI Parameters
this section adds new SIP URI parameters by extending the grammar for "uri-parameter" from [RFC3261]. here's the ABNF from [RFC5234], bestie 🤓
uri-parameter =/ pn-provider / pn-param / pn-prid / pn-purr
pn-provider = "pn-provider" [EQUAL pvalue]
pn-param = "pn-param" EQUAL pvalue
pn-prid = "pn-prid" EQUAL pvalue
pn-purr = "pn-purr" EQUAL pvalue
pvalue = <pvalue defined in [RFC3261]>
EQUAL = <EQUAL defined in [RFC3261]>the format and meaning of pn-prid and pn-param depend on the pn-provider value 🫶
parameter value characters that aren't part of pvalue need to be escaped, as defined in RFC 3261 🔥
9. PNS Registration Requirements 📋
when a new value gets registered to the PNS subregistry, a reference to a specification describing how to use the PNS for that value has to be included 💅 that specification MUST contain the following info:
- The value of the 'pn-provider' SIP URI parameter.
- How the 'pn-prid' SIP URI parameter value is retrieved and set by the SIP UA.
- How the 'pn-param' SIP URI parameter (if required for the specific PNS provider) value is retrieved and set by the SIP UA.
10. 'pn-provider', 'pn-param', and 'pn-prid' URI Parameters for Apple Push Notification service 🍎
when the Apple Push Notification service (APNs) is used, the PNS-related SIP URI parameters get set like this 🦋
for the full details on the parameter values, check out https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html [pns-apns] 📖
the value of the 'pn-provider' URI parameter is "apns" ✨
Example:
pn-provider=apnsthe value of the 'pn-param' URI parameter is a string made of two values separated by a period (.): Team ID and Topic 🎀 Apple gives you the Team ID, and it's unique to a development team. the Topic is the Bundle ID (which uniquely identifies an app) plus a service value (which names a service tied to that app), separated by a period (.). for Voice over IP (VoIP) apps, the service value is "voip" 📞
Example:
pn-param=DEF123GHIJ.com.example.yourexampleapp.voipNOTE: The Bundle ID might contain one or more periods (.). Hence, within the 'pn-param' value, the first period will be separating the Team ID from the Topic, and within the Topic, the last period will be separating the Bundle ID from the service.
the value of the 'pn-prid' URI parameter is the device token, a unique identifier Apple assigns to a specific app on a specific device 📱
Example:
pn-prid=00fc13adff7851211. 'pn-provider', 'pn-param', and 'pn-prid' URI Parameters for Google Firebase Cloud Messaging (FCM) Push Notification Service 🔥
when Firebase Cloud Messaging (FCM) is used, the PNS-related URI parameters get set like this 💖
for the full details on the parameter values, check out https://firebase.google.com/docs/cloud-messaging/concept-options [pns-fcm] 🌐
the value of the 'pn-provider' URI parameter is "fcm" 🧚
the value of the 'pn-param' URI parameter is the Project ID 🌸
the value of the 'pn-prid' URI parameter is the Registration token, which the FCM SDK generates for each client app instance 🫶
12. 'pn-provider', 'pn-param', and 'pn-prid' URI Parameters for RFC 8030 (Generic Event Delivery Using HTTP Push) 🌈
when Generic Event Delivery Using HTTP Push is used, the PNS-related URI parameters get set like this 💜
the value of the 'pn-provider' URI parameter is "webpush" 🦋
the value of the 'pn-param' URI parameter MUST NOT be used 🙅
the value of the 'pn-prid' URI parameter is the push subscription URI 🍓
see RFC 8030 [RFC8030] for more details 📚
note that encryption for web push [RFC8291] is not used, so parameters for message encryption aren't defined in this specification 🔐 web push does allow sending a push message without a payload and without encryption ✨
13. Security Considerations ✨
Okay bestie, this section is SERIOUS 😭🔒 The security stuff for any particular PNS (how users and devices get authenticated and authorized) is out of scope for this doc, so it's not our problem here 🙅♀️ [RFC8030] covers the security considerations for the PNS defined in that spec, and every other PNS gets its security story in its own spec 💅
Usually the PNS wants the SIP proxy that's asking for push notifications to be authenticated and authorized by the PNS 🛡️ In some cases the PNS also needs the SIP app (or the app developer) to be identified before the app can request push notifications. Here's the scary part 💀 Unless the PNS authenticates and authorizes the PNS, a malicious endpoint or network entity that got its hands on the parameters in the SIP signaling could make push notifications get sent to a UA. Those pushes would drain the UA's battery and trigger unnecessary SIP traffic. Not slay at all 🙃
[RFC8292] has a mechanism where a proxy can identify itself to a PNS by signing a JSON Web Token (JWT) that it sends to the PNS, using a key pair 🔑 The public key acts as the proxy's identifier, and devices can use it to restrict push notifications to the proxy linked to that key ✨
Operators MUST ensure that the SIP signaling is properly secured, e.g., using encryption, from malicious network entities. TLS MUST be used unless the operators know that the signaling is secured using some other mechanism that provides strong crypto properties. 🔐😤
Okay, real talk, this one is a must-do 🚨
Apart from the info a device and the PNS already need to swap in order to set up a push notification subscription, this mechanism doesn't require any extra info to be exchanged between the device and the PNS 🧚
The mechanism also doesn't require a proxy to insert any payload when it requests push notifications, other than whatever payload the PNS itself might use 📦
Operators MUST ensure that the PNS-related SIP URI parameters conveyed by a user in the Contact URI of a REGISTER request are not sent to other users or to non-trusted network entities. One way to convey contact information is by using the SIP event package for registrations mechanism [RFC3680]. [RFC3680] defines generic security considerations for the SIP event package for registrations. As the PNS-related SIP URI parameters conveyed in the REGISTER request contain sensitive information, operators that support the event package MUST ensure that event package subscriptions are properly authenticated and authorized, and that the SIP URI parameters are not inserted in event notifications sent to other users or to non-trusted network entities. 🫣🔒💜
14. IANA Considerations 📝
14.1. SIP URI Parameters
Okay so this section adds brand new SIP URI Parameters, which extend the "SIP/SIPS URI Parameters" subregistry [RFC3969] under the SIP Parameters registry (https://www.iana.org/assignments/sip-parameters) 🗂️✨
14.1.1. pn-provider
Parameter Name: pn-provider
Predefined Values: No
Reference: RFC 859914.1.2. pn-param
Parameter Name: pn-param
Predefined Values: No
Reference: RFC 859914.1.3. pn-prid
Parameter Name: pn-prid
Predefined Values: No
Reference: RFC 859914.1.4. pn-purr
Parameter Name: pn-purr
Predefined Values: No
Reference: RFC 859914.2. SIP Response Codes
14.2.1. 555 (Push Notification Service Not Supported)
This one adds a brand new SIP response code, which extends the "Response Codes" subregistry [RFC3261] under the SIP Parameters registry (https://www.iana.org/assignments/sip-parameters) 🚦 Here are the details 👀
Response Code Number: 555
Default Reason Phrase: Push Notification Service Not Supported14.3. SIP Global Feature-Capability Indicator
14.3.1. sip.pns
This adds a new feature-capability indicator that extends the "SIP Feature-Capability Indicator Registration Tree" subregistry [RFC6809] under the SIP Parameters registry (https://www.iana.org/assignments/sip-parameters) 🦋
Name: sip.pns
Description: This feature-capability indicator, when inserted in a
Feature-Caps header field of a SIP REGISTER request or a SIP 2xx
response to a REGISTER request, denotes that the entity
associated with the indicator supports the SIP push mechanism
and the type of push notification service conveyed by the
indicator value.
Reference: RFC 8599
Contact: IESG (iesg@ietf.org)14.3.2. sip.vapid
Another new feature-capability indicator, extending the same "SIP Feature-Capability Indicator Registration Tree" subregistry [RFC6809] under the SIP Parameters registry (https://www.iana.org/assignments/sip-parameters) 🌸
Name: sip.vapid
Description: This feature-capability indicator, when inserted in a
SIP 2xx response to a SIP REGISTER request, denotes that the
entity associated with the indicator supports the Voluntary
Application Server Identification (VAPID) mechanism when the
entity requests that a push notification be sent to a SIP UA.
The indicator value is a public key identifying the entity,
which can be used by a SIP UA to restrict subscriptions to
that entity.
Reference: RFC 8599
Contact: IESG (iesg@ietf.org)14.3.3. sip.pnsreg
Yet another feature-capability indicator, extending the "SIP Feature-Capability Indicator Registration Tree" subregistry [RFC6809] under the SIP Parameters registry (https://www.iana.org/assignments/sip-parameters) 🔄
Name: sip.pnsreg
Description: This feature-capability indicator, when inserted in a
SIP 2xx response to a SIP REGISTER request, denotes that the
entity associated with the indicator expects to receive
binding-refresh REGISTER requests for the binding from the SIP
UA associated with the binding before the binding expires, even
if the entity does not request that a push notification be sent
to the SIP UA in order to trigger the binding-refresh REGISTER
requests. The indicator value conveys the minimum time
(given in seconds) prior to the binding expiration when the UA
MUST send the REGISTER request.
Reference: RFC 8599
Contact: IESG (iesg@ietf.org)14.3.4. sip.pnspurr
And one more feature-capability indicator, extending the "SIP Feature-Capability Indicator Registration Tree" subregistry [RFC6809] under the SIP Parameters registry (https://www.iana.org/assignments/sip-parameters) 🧚♀️
Name: sip.pnspurr
Description: This feature-capability indicator, when inserted in a
SIP 2xx response to a SIP REGISTER request, conveys that
the entity associated with the indicator will store information
that can be used to associate a mid-dialog SIP request with the
binding information in the REGISTER request. The indicator
value is an identifier that can be used as a key to retrieve
the binding information.
Reference: RFC 8599
Contact: IESG (iesg@ietf.org)14.4. SIP Media Feature Tag
14.4.1. sip.pnsreg
This adds a new media feature tag that extends the "SIP Media Feature Tag Registration Tree" subregistry [RFC3840] under the "Media Feature Tags" registry (https://www.iana.org/assignments/media-feature-tags) 🎀
Media feature tag name: sip.pnsreg
Summary of the media feature indicated by this feature tag: This
media feature tag, when inserted in the Contact header field
of a SIP REGISTER request, conveys that the SIP UA
associated with the tag is able to send binding-refresh
REGISTER requests associated with the registration without
being awakened by push notifications.
Values appropriate for use with this feature tag: none
Related standards or documents: RFC 8599
Security considerations: This media feature tag does not introduce
new security considerations, as it simply indicates support for
a basic SIP feature. If an attacker manages to remove the media
feature tag, push notifications will not be requested to be sent
to the client.
Contact: IESG (iesg@ietf.org)14.5. PNS Subregistry Establishment
Last but not least 🎉 This section creates a brand new subregistry, "PNS", under the SIP Parameters registry (https://www.iana.org/assignments/sip-parameters) 🏆
The whole point of this subregistry is to register SIP URI 'pn-provider' values 💖
When a SIP URI 'pn-provider' value gets registered in the subregistry, it has to meet the "Specification Required" policies defined in [RFC8126] 📜
The subregistry is a table with three columns:
- Value: The token under registration
- Description: The name of the Push Notification Service (PNS)
- Document: A reference to the document defining the registration
This specification registers the following values:
Value Description Document
------- -------------------------------------- ----------
apns Apple Push Notification service RFC 8599
fcm Firebase Cloud Messaging RFC 8599
webpush Generic Event Delivery Using HTTP Push RFC 859915. References 📚
The reference entries aren't in this part, bestie, so they'll pick up in the next one 🧚✨
15.1. Normative References 📚
okay bestie, these are the must-reads 🫶 Everything in here is needed to make sense of the spec, so these are the references you actually have to go check.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, https://www.rfc-editor.org/info/rfc2119.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, DOI 10.17487/RFC3261, June 2002, https://www.rfc-editor.org/info/rfc3261.
[RFC3840] Rosenberg, J., Schulzrinne, H., and P. Kyzivat, "Indicating User Agent Capabilities in the Session Initiation Protocol (SIP)", RFC 3840, DOI 10.17487/RFC3840, August 2004, https://www.rfc-editor.org/info/rfc3840.
[RFC3891] Mahy, R., Biggs, B., and R. Dean, "The Session Initiation Protocol (SIP) "Replaces" Header", RFC 3891, DOI 10.17487/RFC3891, September 2004, https://www.rfc-editor.org/info/rfc3891.
[RFC3969] Camarillo, G., "The Internet Assigned Number Authority (IANA) Uniform Resource Identifier (URI) Parameter Registry for the Session Initiation Protocol (SIP)", BCP 99, RFC 3969, DOI 10.17487/RFC3969, December 2004, https://www.rfc-editor.org/info/rfc3969.
[RFC5079] Rosenberg, J., "Rejecting Anonymous Requests in the Session Initiation Protocol (SIP)", RFC 5079, DOI 10.17487/RFC5079, December 2007, https://www.rfc-editor.org/info/rfc5079.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, https://www.rfc-editor.org/info/rfc5234.
[RFC6809] Holmberg, C., Sedlacek, I., and H. Kaplan, "Mechanism to Indicate Support of Features and Capabilities in the Session Initiation Protocol (SIP)", RFC 6809, DOI 10.17487/RFC6809, November 2012, https://www.rfc-editor.org/info/rfc6809.
[RFC8030] Thomson, M., Damaggio, E., and B. Raymor, Ed., "Generic Event Delivery Using HTTP Push", RFC 8030, DOI 10.17487/RFC8030, December 2016, https://www.rfc-editor.org/info/rfc8030.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, https://www.rfc-editor.org/info/rfc8174.
[RFC8292] Thomson, M. and P. Beverloo, "Voluntary Application Server Identification (VAPID) for Web Push", RFC 8292, DOI 10.17487/RFC8292, November 2017, https://www.rfc-editor.org/info/rfc8292.
[pns-apns] Apple Inc., "Local and Remote Notification Programming Guide: Communicating with APNs", https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html.
[pns-fcm] Google Inc., "Firebase Cloud Messaging", https://firebase.google.com/docs/cloud-messaging/concept-options.
15.2. Informative References 🧠
these ones are the background reading 🌸 not required to get the spec, but super helpful if you want the whole story.
[RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model with Session Description Protocol (SDP)", RFC 3264, DOI 10.17487/RFC3264, June 2002, https://www.rfc-editor.org/info/rfc3264.
[RFC3680] Rosenberg, J., "A Session Initiation Protocol (SIP) Event Package for Registrations", RFC 3680, DOI 10.17487/RFC3680, March 2004, https://www.rfc-editor.org/info/rfc3680.
[RFC4320] Sparks, R., "Actions Addressing Identified Issues with the Session Initiation Protocol's (SIP) Non-INVITE Transaction", RFC 4320, DOI 10.17487/RFC4320, January 2006, https://www.rfc-editor.org/info/rfc4320.
[RFC4321] Sparks, R., "Problems Identified Associated with the Session Initiation Protocol's (SIP) Non-INVITE Transaction", RFC 4321, DOI 10.17487/RFC4321, January 2006, https://www.rfc-editor.org/info/rfc4321.
[RFC5626] Jennings, C., Ed., Mahy, R., Ed., and F. Audet, Ed., "Managing Client-Initiated Connections in the Session Initiation Protocol (SIP)", RFC 5626, DOI 10.17487/RFC5626, October 2009, https://www.rfc-editor.org/info/rfc5626.
[RFC6665] Roach, A., "SIP-Specific Event Notification", RFC 6665, DOI 10.17487/RFC6665, July 2012, https://www.rfc-editor.org/info/rfc6665.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, https://www.rfc-editor.org/info/rfc8126.
[RFC8291] Thomson, M., "Message Encryption for Web Push", RFC 8291, DOI 10.17487/RFC8291, November 2017, https://www.rfc-editor.org/info/rfc8291.
Acknowledgements 🫶
huge thank-yous to everyone who read the text and gave useful feedback, you legends ✨ Thanks to Paul Kyzivat, Dale Worley, Ranjit Avasarala, Martin Thomson, Mikael Klein, Susanna Sjoholm, Kari-Pekka Perttula, Liviu Chircu, Roman Shpount, Yehoshua Gev, and Jean Mahoney for reading the text and providing useful feedback.
Authors' Addresses 💌
the people who wrote this one, and where to find them 🦋
Christer Holmberg
Ericsson
Hirsalantie 11
Jorvas 02420
Finland
Email: christer.holmberg@ericsson.comMichael Arnold
Metaswitch Networks
100 Church Street
Enfield EN2 6BQ
United Kingdom
Email: Michael.Arnold@metaswitch.com📦 where this page comes from
- ietf: rfc8599 2019-05
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms