RFC 6665
SIP-Specific Event Notification
RFC 6665: SIP-Specific Event Notification 🎀
Part 1 of 11 💖
Okay bestie, let's start with the title block so you know who made this and where it fits 🧚. It's from the Internet Engineering Task Force (IETF) and it's Request for Comments 6665, the official ID card for this spec. A.B. Roach from Tekelec wrote it, it was published in July 2012, and it's on the Standards Track 💅, which means it's a real Internet standard. Its ISSN is 2070-1721.
The drama here is that it obsoletes RFC 3265, so it fully replaces that older spec 💀. It also updates RFC 3261 and RFC 4660, meaning it changes some things in those documents too, with the RFC 4660 part being pretty small 🌸.
Abstract 📝
Okay so this doc is an extension to the Session Initiation Protocol (SIP), which is defined by RFC 3261 🦋. The whole point is to give SIP nodes an extensible framework so they can ask remote nodes to tell them when certain events have happened ✨.
Heads up though: the event notification mechanisms in here are NOT meant to be a general-purpose infrastructure for every class of event subscription and notification 🙅♀️. Know your lane, babe.
This document is a backwards-compatible glow-up of the original mechanism from RFC 3265, built on several years of real implementation experience 💜. That's why it obsoletes RFC 3265. It also updates RFC 4660 a little, to fit in some small changes that got discussed in that document 🎀.
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 5741 📚.
For the latest status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc6665 🔍.
Copyright Notice ©️
Copyright belongs to the IETF Trust and the people listed as the document's authors, 2012, and all rights are reserved 🔒.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can find at http://trustee.ietf.org/license-info, as they stood on the publication date 📜. Please actually read those, bestie, because they spell out your rights and restrictions for this document 👀.
One more thing: any Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come with no warranty, as the Simplified BSD License explains 🧾.
Table of Contents 🗺️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Overview of Operation . . . . . . . . . . . . . . . . . . 5
1.2. Documentation Conventions . . . . . . . . . . . . . . . . 6
2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. SIP Methods for Event Notification . . . . . . . . . . . . . . 7
3.1. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.1. Subscription Duration . . . . . . . . . . . . . . . . 7
3.1.2. Identification of Subscribed Events and Event
Classes . . . . . . . . . . . . . . . . . . . . . . . 8
3.1.3. Additional SUBSCRIBE Header Field Values . . . . . . . 9
3.2. NOTIFY . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.1. Identification of Reported Events, Event Classes,
and Current State . . . . . . . . . . . . . . . . . . 9
4. Node Behavior . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1. Subscriber Behavior . . . . . . . . . . . . . . . . . . . 10
4.1.1. Detecting Support for SIP Events . . . . . . . . . . . 10
4.1.2. Creating and Maintaining Subscriptions . . . . . . . . 10
4.1.3. Receiving and Processing State Information . . . . . . 14
4.1.4. Forking of SUBSCRIBE Requests . . . . . . . . . . . . 16
4.2. Notifier Behavior . . . . . . . . . . . . . . . . . . . . 17
4.2.1. Subscription Establishment and Maintenance . . . . . . 17
4.2.2. Sending State Information to Subscribers . . . . . . . 20
4.2.3. PSTN/Internet Interworking (PINT) Compatibility . . . 23
4.3. Proxy Behavior . . . . . . . . . . . . . . . . . . . . . . 23
4.4. Common Behavior . . . . . . . . . . . . . . . . . . . . . 24
4.4.1. Dialog Creation and Termination . . . . . . . . . . . 24
4.4.2. Notifier Migration . . . . . . . . . . . . . . . . . . 24
4.4.3. Polling Resource State . . . . . . . . . . . . . . . . 25
4.4.4. "Allow-Events" Header Field Usage . . . . . . . . . . 26
4.5. Targeting Subscriptions at Devices . . . . . . . . . . . . 26
4.5.1. Using GRUUs to Route to Devices . . . . . . . . . . . 27
4.5.2. Sharing Dialogs . . . . . . . . . . . . . . . . . . . 27
4.6. CANCEL Requests for SUBSCRIBE and NOTIFY Transactions . . 29
5. Event Packages . . . . . . . . . . . . . . . . . . . . . . . . 29
5.1. Appropriateness of Usage . . . . . . . . . . . . . . . . . 29
5.2. Event Template-Packages . . . . . . . . . . . . . . . . . 30
5.3. Amount of State to Be Conveyed . . . . . . . . . . . . . . 31
5.3.1. Complete State Information . . . . . . . . . . . . . . 31
5.3.2. State Deltas . . . . . . . . . . . . . . . . . . . . . 32
5.4. Event Package Responsibilities . . . . . . . . . . . . . . 32
5.4.1. Event Package Name . . . . . . . . . . . . . . . . . . 33
5.4.2. Event Package Parameters . . . . . . . . . . . . . . . 33
5.4.3. SUBSCRIBE Request Bodies . . . . . . . . . . . . . . . 33
5.4.4. Subscription Duration . . . . . . . . . . . . . . . . 33
5.4.5. NOTIFY Request Bodies . . . . . . . . . . . . . . . . 34
5.4.6. Notifier Processing of SUBSCRIBE Requests . . . . . . 34
5.4.7. Notifier generation of NOTIFY requests . . . . . . . . 34
5.4.8. Subscriber Processing of NOTIFY Requests . . . . . . . 34
5.4.9. Handling of Forked Requests . . . . . . . . . . . . . 34
5.4.10. Rate of Notifications . . . . . . . . . . . . . . . . 35
5.4.11. State Aggregation . . . . . . . . . . . . . . . . . . 35
5.4.12. Examples . . . . . . . . . . . . . . . . . . . . . . . 36
5.4.13. Use of URIs to Retrieve State . . . . . . . . . . . . 36
6. Security Considerations . . . . . . . . . . . . . . . . . . . 36
6.1. Access Control . . . . . . . . . . . . . . . . . . . . . . 36
6.2. Notifier Privacy Mechanism . . . . . . . . . . . . . . . . 36
6.3. Denial-of-Service Attacks . . . . . . . . . . . . . . . . 37
6.4. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 37
6.5. Man-in-the-Middle Attacks . . . . . . . . . . . . . . . . 37
6.6. Confidentiality . . . . . . . . . . . . . . . . . . . . . 38
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
7.1. Event Packages . . . . . . . . . . . . . . . . . . . . . . 38
7.1.1. Registration Information . . . . . . . . . . . . . . . 39
7.1.2. Registration Template . . . . . . . . . . . . . . . . 40
7.2. Reason Codes . . . . . . . . . . . . . . . . . . . . . . . 40
7.3. Header Field Names . . . . . . . . . . . . . . . . . . . . 41
7.4. Response Codes . . . . . . . . . . . . . . . . . . . . . . 41
8. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.1. New Methods . . . . . . . . . . . . . . . . . . . . . . . 42
8.1.1. SUBSCRIBE Method . . . . . . . . . . . . . . . . . . . 42
8.1.2. NOTIFY Method . . . . . . . . . . . . . . . . . . . . 42
8.2. New Header Fields . . . . . . . . . . . . . . . . . . . . 42
8.2.1. "Event" Header Field . . . . . . . . . . . . . . . . . 42
8.2.2. "Allow-Events" Header Field . . . . . . . . . . . . . 43
8.2.3. "Subscription-State" Header Field . . . . . . . . . . 43
8.3. New Response Codes . . . . . . . . . . . . . . . . . . . . 43
8.3.1. 202 (Accepted) Response Code . . . . . . . . . . . . . 43
8.3.2. 489 (Bad Event) Response Code . . . . . . . . . . . . 44
8.4. Augmented BNF Definitions . . . . . . . . . . . . . . . . 44
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45
9.1. Normative References . . . . . . . . . . . . . . . . . . . 45
9.2. Informative References . . . . . . . . . . . . . . . . . . 46
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 48
Appendix B. Changes from RFC 3265 . . . . . . . . . . . . . . . . 48
B.1. Bug 666: Clarify use of "expires=xxx" with "terminated" . 48
B.2. Bug 667: Reason code for unsub/poll not clearly
spelled out . . . . . . . . . . . . . . . . . . . . . . . 48
B.3. Bug 669: Clarify: SUBSCRIBE for a duration might be
answered with a NOTIFY/expires=0 . . . . . . . . . . . . . 48
B.4. Bug 670: Dialog State Machine needs clarification . . . . 49
B.5. Bug 671: Clarify timeout-based removal of subscriptions . 49
B.6. Bug 672: Mandate "expires" in NOTIFY . . . . . . . . . . . 49
B.7. Bug 673: INVITE 481 response effect clarification . . . . 49
B.8. Bug 677: SUBSCRIBE response matching text in error . . . . 49
B.9. Bug 695: Document is not explicit about response to
NOTIFY at subscription termination . . . . . . . . . . . . 49
B.10. Bug 696: Subscription state machine needs clarification . 49
B.11. Bug 697: Unsubscription behavior could be clarified . . . 49
B.12. Bug 699: NOTIFY and SUBSCRIBE are target refresh
requests . . . . . . . . . . . . . . . . . . . . . . . . . 50
B.13. Bug 722: Inconsistent 423 reason phrase text . . . . . . . 50
B.14. Bug 741: Guidance needed on when to not include
"Allow-Events" . . . . . . . . . . . . . . . . . . . . . . 50
B.15. Bug 744: 5xx to NOTIFY terminates a subscription, but
should not . . . . . . . . . . . . . . . . . . . . . . . . 50
B.16. Bug 752: Detection of forked requests is incorrect . . . . 50
B.17. Bug 773: Reason code needs IANA registry . . . . . . . . . 50
B.18. Bug 774: Need new reason for terminating subscriptions
to resources that never change . . . . . . . . . . . . . . 50
B.19. Clarify Handling of "Route"/"Record-Route" in NOTIFY . . . 50
B.20. Eliminate Implicit Subscriptions . . . . . . . . . . . . . 51
B.21. Deprecate Dialog Reuse . . . . . . . . . . . . . . . . . . 51
B.22. Rationalize Dialog Creation . . . . . . . . . . . . . . . 51
B.23. Refactor Behavior Sections . . . . . . . . . . . . . . . . 51
B.24. Clarify Sections That Need to Be Present in Event
Packages . . . . . . . . . . . . . . . . . . . . . . . . . 51
B.25. Make CANCEL Handling More Explicit . . . . . . . . . . . . 51
B.26. Remove "State Agent" Terminology . . . . . . . . . . . . . 51
B.27. Miscellaneous Changes . . . . . . . . . . . . . . . . . . 52That's part 1 of 11 wrapped up, bestie! 🧚💜 Part 2 is coming up next, so stay tuned for Section 1, Introduction 🦋✨
1. Introduction ✨
Okay so, asynchronous notifications are a huge deal in lots of SIP services where both end-nodes have to work together. Think automatic callback services (triggered by terminal state events), buddy lists (triggered by user presence events), message waiting indications (triggered by mailbox state changes), and PSTN and Internet Internetworking (PINT) [RFC2848] status (triggered by call state events). 🌸
This document gives you a framework for ordering how those notifications get delivered. 💅
Now, the event notification mechanisms here are NOT meant to be a general-purpose infrastructure for every kind of subscription and notification. Solving the general problem is way too complex for one protocol, bestie. 😭 The goal is a SIP-specific framework that isn't so complicated it's unusable for simple features, but is still flexible enough to power some seriously cool services. ✨ Event packages built on this framework can still define super elaborate rules for how the events they describe get subscribed to and notified, so the complexity can live there if it needs to. 🦋
This document doesn't describe something you can use directly. It has to be extended by other documents (called "event packages" here). Think of it like an abstract base class in object-oriented design: it can't be instantiated on its own, and it needs further extensions to become a real, usable class. 🧚 Guidelines for making those extensions are in Section 5.
1.1. Overview of Operation
The big idea is that entities in the network can subscribe to resource or call state for various resources or calls, and then those entities (or entities acting on their behalf) can send notifications whenever that state changes. 🔥
Here's what a typical flow looks like:
Subscriber Notifier
|-----SUBSCRIBE---->| Request state subscription
|<-------200--------| Acknowledge subscription
|<------NOTIFY----- | Return current state information
|--------200------->|
|<------NOTIFY----- | Return current state information
|--------200------->|Subscriptions expire, so they have to be refreshed with new SUBSCRIBE requests. Keep that in mind, it's a whole thing 💖
1.2. Documentation Conventions
Throughout the doc there are paragraphs that give motivation or extra clarification. These are non-normative, which just means they're there to help you understand and don't count as part of the actual spec. 🎀 They're set off by being indented, like this:
This is an example of non-normative explanatory text. It does not form part of the specification and is used only for clarification.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 🌈
Implementors, pay attention to "SHOULD" here, especially. It's defined in RFC 2119, and it's not a suggestion you can ignore whenever it's inconvenient. 💀 To put it plainly: if you're going to break a "SHOULD"-strength requirement, you need careful analysis and clearly enumerable reasons. Failing to comply with "SHOULD"-strength requirements whimsically or just because it's easier to implement is a protocol violation. Not cute. 🙈
2. Definitions
Event Package: An event package is an additional specification that defines a set of state information to be reported by a notifier to a subscriber. Event packages also define further syntax and semantics based on the framework in this document, and those are required to convey that state information. 📦
Event Template-Package: An event template-package is a special kind of event package. It defines a set of states that may be applied to all possible event packages, including itself. 🪄
Notification: Notification is the act of a notifier sending a NOTIFY request to a subscriber to tell the subscriber about the state of a resource. 🔔
Notifier: A notifier is a user agent that generates NOTIFY requests so it can tell subscribers about the state of a resource. Notifiers typically also accept SUBSCRIBE requests to create subscriptions. 👑
Subscriber: A subscriber is a user agent that receives NOTIFY requests from notifiers. Those NOTIFY requests carry information about the state of a resource the subscriber cares about. Subscribers typically also generate SUBSCRIBE requests and send them to notifiers to create subscriptions. 🫶
Subscription: A subscription is a set of application state associated with a dialog. That application state includes a pointer to the associated dialog, the event package name, and possibly an identification token. Event packages will define additional subscription state information. By definition, subscriptions exist in both a subscriber and a notifier. 🧩
Subscription Migration: Subscription migration is the act of moving a subscription from one notifier to another notifier. 🦋
3. SIP Methods for Event Notification
3.1. SUBSCRIBE
The SUBSCRIBE method is used to request current state and state updates from a remote node. SUBSCRIBE requests are target refresh requests, as that term is defined in [RFC3261]. ✨
3.1.1. Subscription Duration
SUBSCRIBE requests SHOULD contain an Expires header field (defined in [RFC3261]). This expires value tells you how long the subscription lasts. To keep a subscription effective past the duration in the Expires header field, subscribers need to refresh it on a periodic basis with a new SUBSCRIBE request on the same dialog, as defined in [RFC3261]. 🔁
If no Expires header field is present in a SUBSCRIBE request, the implied default MUST be defined by the event package being used. 📋
200-class responses to SUBSCRIBE requests also MUST contain an Expires header field. The period of time in the response MAY be shorter but MUST NOT be longer than what was specified in the request. The notifier is explicitly allowed to shorten the duration all the way to zero. The period of time in the response is the one that defines how long the subscription lasts. 💅
An expires parameter on the Contact header field has no semantics for the SUBSCRIBE method. It is explicitly not equivalent to an Expires header field in a SUBSCRIBE request or response. Don't mix those up, bestie 🙅♀️
Here's the natural consequence of all this: a SUBSCRIBE request with an Expires of 0 is a request to unsubscribe from the matching subscription. 🥀
In addition to being a request to unsubscribe, a SUBSCRIBE request with Expires of 0 also causes a fetch of state; see Section 4.4.3.
Notifiers may also want to cancel subscriptions to events. This is useful when, for example, the resource a subscription refers to is no longer available. More details on that mechanism are in Section 4.2.2. 🍓
3.1.2. Identification of Subscribed Events and Event Classes
Events are identified by three pieces of information: the Request URI, the Event Type, and (optionally) the message body. 🪪
The Request URI of a SUBSCRIBE request is the most important one, because it contains enough info to route the request to the right entity, following the request routing procedures in [RFC3261]. It also contains enough info to identify the resource you want event notifications for, but not necessarily enough to uniquely identify the nature of the event. For example, "sip:adam@example.com" would be a perfectly fine URI to subscribe to for my presence state, and it would also be fine for subscribing to the state of my voice mailbox. Same URI, different vibes 📞
Subscribers MUST include exactly one Event header field in SUBSCRIBE requests, to say which event or class of events they're subscribing to. The Event header field carries a token that indicates the type of state the subscription is for. This token will be registered with IANA and will correspond to an event package that spells out the semantics of the event or event class. 🗂️
If the event package that the event token corresponds to defines behavior for the body of its SUBSCRIBE requests, those semantics apply. 🎯
Event packages may also define parameters for the Event header field. If they do, they must define the semantics for those parameters too. 🧾
3.1.3. Additional SUBSCRIBE Header Field Values
SUBSCRIBE requests create a dialog usage, as defined in [RFC3261], so they MAY contain an Accept header field. If it's present, that header field indicates which body formats are allowed in subsequent NOTIFY requests. Event packages MUST define the behavior for SUBSCRIBE requests without Accept header fields. Usually, that will mean a single, default body type. 🎀
Header values not described in this document are to be interpreted as described in [RFC3261]. 📖
3.2. NOTIFY
NOTIFY requests are sent to tell subscribers about changes in the state of something they have a subscription to. Subscriptions are created using the SUBSCRIBE method. Legacy implementations might have used other ways to create subscriptions, but this specification does not allow subscriptions to be created except through SUBSCRIBE requests and (for backwards-compatibility) REFER requests [RFC3515]. 🕰️
NOTIFY is a target refresh request, as that term is defined in [RFC3261]. 🔄
A NOTIFY request does not terminate its corresponding subscription. In other words, a single SUBSCRIBE request can trigger several NOTIFY requests. Lots of notifications, one subscription, so iconic 🤭
3.2.1. Identification of Reported Events, Event Classes, and Current State
Identifying the events reported in a notification is very similar to how subscribed events are identified (see Section 3.1.2). 🔍
Just like in SUBSCRIBE requests, the Event header fields in NOTIFY requests MUST contain a single event package name for which a notification is being generated. The package name in the Event header field MUST match the Event header field in the corresponding SUBSCRIBE request. Consistency is everything here 💜
Event packages may define semantics for the body of their NOTIFY requests, and if they do, those semantics apply. NOTIFY request bodies are expected to give additional details about the nature of the event that happened and the resulting resource state. ✨
When a body is present, the body of the NOTIFY request MUST be formatted into one of the body formats specified in the Accept header field of the corresponding SUBSCRIBE request. If no Accept header field was specified, it has to be the default type according to the event package description. Either way, the body will contain either the state of the subscribed resource or a pointer to that state in the form of a URI (see Section 5.4.13). 🌷
4. Node Behavior ✨
4.1. Subscriber Behavior
4.1.1. Detecting Support for SIP Events ✨
okay so this extension doesn't use the Require or Proxy-Require header fields 💅, and there's no token defined for Supported header fields either 🙈. If you're a potential subscriber and want to check whether someone supports SIP events, you can probe with an OPTIONS request, which is defined in [RFC3261] 🦋.
The presence of SUBSCRIBE in the Allow header field of any request or response means the sender supports SIP events 🔥. And if there's no Allow header field at all, just having an Allow-Events header field is enough to show that the sender can act as a notifier (see Section 4.4.4) 🫶.
Themethodsparameter for Contact can also be used to specifically announce support for SUBSCRIBE and NOTIFY requests when registering. (See [RFC3840] for details on themethodsparameter.) 🎀
4.1.2. Creating and Maintaining Subscriptions 🌈
bestie, this part is the main character of the whole subscriber story 👑. From the subscriber's point of view, a subscription moves through the states in the diagram below. Any event that just loops back to the same state isn't drawn in here, so don't go looking for it 🙈.
+-------------+
| init |<-----------------------+
+-------------+ |
| Retry-after
Send SUBSCRIBE expires
| |
V Timer N Fires; |
+-------------+ SUBSCRIBE failure |
+------------| notify_wait |-- response; --------+ |
| +-------------+ or NOTIFY, | |
| | state=terminated | |
| | | |
++========|===================|============================|==|====++
|| | | V | ||
|| Receive NOTIFY, Receive NOTIFY, +-------------+ ||
|| state=active state=pending | terminated | ||
|| | | +-------------+ ||
|| | | Re-subscription A A ||
|| | V times out; | | ||
|| | +-------------+ Receive NOTIFY, | | ||
|| | | pending |-- state=terminated; --+ | ||
|| | +-------------+ or 481 response | ||
|| | | to SUBSCRIBE | ||
|| | Receive NOTIFY, refresh | ||
|| | state=active | ||
|| | | Re-subscription | ||
|| | V times out; | ||
|| | +-------------+ Receive NOTIFY, | ||
|| +----------->| active |-- state=terminated; -----+ ||
|| +-------------+ or 481 response ||
|| to SUBSCRIBE ||
|| Subscription refresh ||
++=================================================================++so in the diagram, "Re-subscription times out" means that an attempt to refresh or update the subscription with a new SUBSCRIBE request doesn't get a NOTIFY request back before the matching Timer N expires ⏰.
Any move from notify_wait into a pending or active state creates a new subscription 🦋. Heads up: one SUBSCRIBE request can end up generating multiple subscriptions (see Section 4.4.1) 🌸. Each of these new subscriptions lives in its own independent state machine and runs its own set of timers ✨.
4.1.2.1. Requesting a Subscription 💖
SUBSCRIBE is a dialog-creating method, as described in [RFC3261] 🧚.
When a subscriber wants to subscribe to a particular state for a resource, it builds a SUBSCRIBE request 💌. If the initial SUBSCRIBE request is sent outside of a dialog (which it usually will be), it gets built following the procedures in [RFC3261] for User Agent Client (UAC) request generation outside of a dialog 🍓.
A final response will confirm this SUBSCRIBE request. 200-class responses mean the subscription was accepted and a NOTIFY request will be sent right away 🎉.
The Expires header field in a 200-class response to a SUBSCRIBE request tells you how long the subscription will actually stay active (unless it gets refreshed) ⏳. The value you get back might be smaller than the one in the SUBSCRIBE request, but it can never be larger. See Section 4.2.1 for the details 💜.
Non-200-class final responses mean no subscription or new dialog usage was created, and no NOTIFY request will follow 🙅♀️. All non-200-class responses (except for 489 (Bad Event), which is described here) mean the same thing and get handled the same way as in [RFC3261] 💅. Just to be super clear: if a SUBSCRIBE request has an Accept header field but that field doesn't name a media type the notifier can generate in its NOTIFY requests, the right error response is 406 (Not Acceptable) 🙃.
4.1.2.2. Refreshing of Subscriptions 🔄
Before a subscription expires, the subscriber can refresh the timer on it at any time by sending another SUBSCRIBE request on the same dialog as the existing subscription 🫧. Handling for this kind of request is the same as for creating the subscription in the first place, except for what's described below 💫.
If a SUBSCRIBE request to refresh a subscription gets a 404, 405, 410, 416, 480-485, 489, 501, or 604 response, the subscriber MUST consider the subscription terminated 🚫. (See [RFC5057] for more details and notes about how error codes affect dialogs and usages within dialogs, such as subscriptions 📚.) If the subscriber wants to re-subscribe to the state, they do that by building an unrelated initial SUBSCRIBE request with a freshly generated Call-ID and a new, unique From tag (see Section 4.1.2.1) 🔁.
If a SUBSCRIBE request to refresh a subscription fails with any error code that isn't in the list above, the original subscription is still considered valid for the duration of the most recently known Expires value. That value was either negotiated by the latest successful SUBSCRIBE transaction, or communicated by a NOTIFY request in the expires parameter of its Subscription-State header field 🧘♀️.
Note that many of these errors mean there may be a problem with the network or the notifier, so no further NOTIFY requests will be received 😭.
When refreshing a subscription, the subscriber starts Timer N, set to 64*T1, when it sends the SUBSCRIBE request ⏱️. If Timer N expires before a NOTIFY request arrives, the subscriber considers the subscription terminated 💀. If the subscriber gets a success response to the SUBSCRIBE request that says no NOTIFY request will be generated (like the 204 response defined for use with the optional extension in [RFC5839]), then it MUST cancel Timer N ✨.
4.1.2.3. Unsubscribing 👋
Unsubscribing is handled the same way as refreshing a subscription, except the Expires header field is set to 0 🫠. Keep in mind that a successful unsubscription will also trigger a final NOTIFY request 🔔.
The final NOTIFY request may or may not include information about the state of the resource 🤷♀️. Subscribers need to be ready to receive final NOTIFY requests both with and without state 🌸.
4.1.2.4. Confirmation of Subscription Creation 🥹
The subscriber can expect a NOTIFY request from each node that processed a successful subscription or subscription refresh 💌. To make sure subscribers don't wait forever for a subscription to be set up, the subscriber starts a Timer N, set to 64*T1, when it sends a SUBSCRIBE request ⏰. If Timer N expires before a NOTIFY request arrives, the subscriber considers the subscription failed and cleans up any state linked to that subscription attempt 🧹.
Until Timer N expires, several NOTIFY requests might arrive from different destinations (see Section 4.4.1) 👯. Each of these requests sets up a new dialog usage and a new subscription 🦋. After Timer N expires, the subscriber SHOULD reject any such NOTIFY requests that would otherwise set up a new dialog usage, using a 481 (Subscription does not exist) response code 🚫.
Until the first NOTIFY request arrives, the subscriber should consider the state of the subscribed resource to be in a neutral state 🌙. Event package specifications MUST define this "neutral state" in a way that makes sense for their application (see Section 5.4.7) 💜.
Because messages can arrive out of order, get lost, or fork, the subscriber MUST be prepared to receive NOTIFY requests before the SUBSCRIBE transaction has completed 🌀.
Apart from what's noted above, processing this NOTIFY request is the same as in Section 4.1.3 🫶.
4.1.3. Receiving and Processing State Information ✨
okay so subscribers get the tea on a resource's state through NOTIFY requests 🔔💖
When a NOTIFY request lands, the subscriber should check that it matches at least one of its outstanding subscriptions. If it doesn't, the subscriber MUST return a 481 (Subscription does not exist) response, unless a different 400- or 500-class response is more appropriate 🙈. NOTIFYs that belong to subscriptions which create a new dialog usage get matched by the rules in Section 4.4.1. Notifications for subscriptions created inside an existing dialog match when they're in the same dialog and their Event header fields match (see Section 8.2.1) 🧚
If the event package named in the Event header field of the NOTIFY isn't supported for some reason, the subscriber will respond with a 489 (Bad Event) response 💀
To stop anyone from faking events, NOTIFY requests SHOULD be authenticated using any defined SIP authentication mechanism, like the ones in Sections 22.2 and 23 of [RFC3261] 🔐
NOTIFY requests MUST contain Subscription-State header fields that tell you the status of the subscription 📋
If the Subscription-State header field value is active, that means the subscription was accepted and (in general) authorized ✨ If the header field also has an expires parameter, the subscriber SHOULD treat it as the authoritative subscription duration and adjust to match. The retry-after and reason parameters have no semantics for active, so they don't mean anything here 🤷♀️
If the Subscription-State value is pending, the notifier got the subscription but doesn't have enough policy info to grant or deny it yet ⏳ If the header field also has an expires parameter, the subscriber SHOULD treat it as the authoritative subscription duration and adjust accordingly. Nothing else is needed from the subscriber here. The retry-after and reason parameters have no semantics for pending 🌸
If the Subscription-State value is terminated, the subscriber MUST consider the subscription terminated 🛑 The expires parameter has no semantics for terminated. Notifiers SHOULD NOT include an expires parameter on a Subscription-State header field with a value of terminated, and subscribers MUST ignore any such parameter if it shows up anyway 🙃 If a reason code is present, the client should behave as described below. If there's no reason code, or an unknown one, the client MAY try to re-subscribe at any time. The exception is when a retry-after parameter is present: then the client SHOULD NOT try to re-subscribe until after the number of seconds that parameter says 🕰️ These are the reason codes this document defines:
- deactivated: The subscription got terminated, but the subscriber SHOULD retry right away with a new subscription. One main reason for this status code is letting subscriptions migrate between nodes 🦋 The
retry-afterparameter has no semantics fordeactivated. - probation: The subscription got terminated, but the client SHOULD retry later (as long as the resource's state still matters to the client at that point) 🌈 If a
retry-afterparameter is also there, the client SHOULD wait at least that many seconds before trying to re-subscribe. - rejected: The subscription got terminated because the authorization policy changed. Clients SHOULD NOT try to re-subscribe 🚫 The
retry-afterparameter has no semantics forrejected. - timeout: The subscription got terminated because nobody refreshed it before it expired ⏰ Clients MAY re-subscribe right away. The
retry-afterparameter has no semantics fortimeout. This reason code is also tied to polling of resource state, which Section 4.4.3 covers 🔁 - giveup: The subscription got terminated because the notifier couldn't get authorization in a timely way 😮💨 If a
retry-afterparameter is also present, the client SHOULD wait at least that many seconds before re-subscribing. Otherwise, the client MAY retry immediately, but it'll likely get put back into pending state 🙄 - noresource: The subscription got terminated because the resource state being watched doesn't exist anymore 🫥 Clients SHOULD NOT try to re-subscribe. The
retry-afterparameter has no semantics fornoresource. - invariant: The subscription got terminated because the resource state is guaranteed not to change for the foreseeable future 🧊 An example is subscribing to the location info of a fixed-location land-line telephone. When using this reason code, notifiers are advised to include a
retry-afterparameter with a big value (for example, 31536000, or one year) so older clients that are RFC 3265 compliant don't keep re-subscribing every so often 🗓️ Clients SHOULD NOT try to re-subscribe after getting a reason code ofinvariant, no matter whether aretry-afterparameter shows up or what its value is 🙅♀️
Other specifications may define new reason codes for use with the Subscription-State header field 🧩
Once the notification is deemed acceptable to the subscriber, the subscriber SHOULD return a 200 response 💅 Generally, NOTIFY responses aren't expected to have bodies. However, they MAY have one if the NOTIFY request contained an Accept header field 📎
Other responses defined in [RFC3261] may also be returned, as they fit 🎀 A NOTIFY transaction should never run any longer than the time automated processing takes, no cap. Subscribers MUST NOT wait for a user response before sending a final response to a NOTIFY request 🫶
4.1.4. Forking of SUBSCRIBE Requests
okay this part is giving multiverse 🌌 Following the proxying rules for non-INVITE requests in [RFC3261], a successful SUBSCRIBE request only gets one 200-class response. BUT because of forking, the subscription might have been accepted by multiple nodes at once 😱 So the subscriber MUST be ready to get NOTIFY requests whose From: tags are different from the To: tag in the 200-class response to SUBSCRIBE 🧚♀️
If you get multiple NOTIFY requests in different dialogs in response to a single SUBSCRIBE request, each dialog stands for a different place the SUBSCRIBE got forked to 🌿 How the subscriber handles this depends on the event package. See Section 5.4.9 for the details 💜
4.2. Notifier Behavior
4.2.1. Subscription Establishment and Maintenance
notifiers find out about subscription requests by receiving SUBSCRIBE requests from people who are interested 👀 Notifiers MUST NOT create subscriptions except when they receive a SUBSCRIBE request. Still, for historical reasons, the implicit creation of subscriptions defined in [RFC3515] is still allowed 🕰️
Quick aside: [RFC3265] let people create subscriptions using methods other than SUBSCRIBE. The only standardized use of that is the REFER method [RFC3515]. Experience with REFER showed that implicitly creating a subscription causes a bunch of unwanted effects 😩 For example, you can't signal that a REFER request succeeded while also signaling a problem with the subscription, and it's hard to do one action without the other. Also, swapping dialog identifiers properly is tough without dialog reuse, which has its own set of problems (see Section 4.5) 🙃
4.2.1.1. Initial SUBSCRIBE Transaction Processing
in no case should a SUBSCRIBE transaction run any longer than automated processing takes. Notifiers MUST NOT wait for a user response before sending a final response to a SUBSCRIBE request ⏱️
This requirement is mainly there so the non-INVITE transaction timeout timer F (see [RFC3261]) doesn't go off during the SUBSCRIBE transaction, because waiting on a user would often take longer than 64*T1 seconds 🙈
The notifier SHOULD check that it understands the event package named in the Event header field. If it doesn't, the notifier SHOULD return a 489 (Bad Event) response to show that the specified event/event class isn't understood 🫠
The notifier SHOULD also do any necessary authentication and authorization based on its local policy. See Section 4.2.1.3 🔑
The notifier MAY also check that the duration in the Expires header field isn't too small 📏 If and only if the expiration interval is greater than zero AND smaller than one hour AND less than a notifier-configured minimum, the notifier MAY return a 423 (Interval Too Brief) error that includes a Min-Expires header field. The Min-Expires header field is described in [RFC3261] 🧐
Once the notifier decides it has enough info to create the subscription (so it understands the event package, the subscription is about a known resource, and there are no other barriers), it creates the subscription and a dialog usage, then returns a 200 (OK) response 🎉
When a subscription gets created in the notifier, it stores the event package name as part of the subscription info 🗂️
The Expires values in SUBSCRIBE 200-class responses work the same way they do in REGISTER responses: the server MAY shorten the interval but MUST NOT lengthen it 📉
If the duration in a SUBSCRIBE request is unacceptably short, the notifier may be able to send a 423 response, like we talked about earlier in this section 💌
200-class responses to SUBSCRIBE requests usually won't have any useful info beyond the subscription duration 🤍 Their main job is to act as a reliability mechanism. The state info comes through a later NOTIFY request from the notifier 📨
The other response codes defined in [RFC3261] may be used in response to SUBSCRIBE requests, as they fit 🌸
4.2.1.2. Confirmation of Subscription Creation/Refreshing
Once a subscription is successfully accepted or refreshed, notifiers MUST send a NOTIFY request immediately to share the current resource state with the subscriber 🦋 This NOTIFY goes out on the same dialog that the SUBSCRIBE response created. If the resource doesn't have any meaningful state when the SUBSCRIBE request gets processed, this NOTIFY MAY have an empty or neutral body 🫧 See Section 4.2.2 for more details on how NOTIFY requests get generated 📝
Heads up: a NOTIFY request is always sent right after any 200-class response to a SUBSCRIBE request, no matter whether the subscription was already authorized 🥹✨
4.2.1.3. Authentication/Authorization of SUBSCRIBE Requests ✨
okay so notifiers might need to check whether a subscriber is actually allowed to subscribe to certain events, bc privacy is a whole thing 🔒 That check can come from things like access control lists or a real human clicking "yes" or "no." Ngl, checking authorization before authentication is not really useful 🙃
SIP authentication is covered in [RFC3261]. Even when the notifier node is acting as a proxy, authentication for SUBSCRIBE requests is ALWAYS done with a 401 (Unauthorized) response, never a 407 (Proxy Authentication Required) 💅 Notifiers always act as user agents when they accept subscriptions and send notifications, so that's the vibe.
Of course, when a node is acting as a proxy, it does normal proxy authentication (using 407). This is just a reminder that notifiers are always user agents and, as such, do user agent authentication. 🫶
If authorization fails because of an access list or some other automated mechanism (aka it can be automatically and authoritatively decided that the subscriber is not authorized to subscribe), the notifier SHOULD reply with a 403 (Forbidden) or 603 (Decline) response. The exception is if doing that might reveal info that should stay private, so check out Section 6.2 for that 👀
If the notifier owner gets interactively asked whether a subscription is allowed, a 200 (OK) response is returned right away. A NOTIFY request still gets formed and sent in this case, as described in the previous section 📨
If subscription authorization got delayed and the notifier wants to say "nope, declined," it can send a NOTIFY request with a Subscription-State header field set to terminated and a reason parameter of rejected 💀
4.2.1.4. Refreshing of Subscriptions
When a notifier gets a subscription refresh and the subscriber is still authorized, the notifier updates the expiration time for the subscription 🔄 Just like with the initial subscription, the server MAY shorten the time until expiration but MUST NOT increase it. The final expiration time goes in the Expires header field in the response. If the duration in a SUBSCRIBE request is unacceptably short, the notifier SHOULD respond with a 423 (Interval Too Brief) response ⏱️
If no refresh for a notification address comes in before its expiration time, the subscription gets removed 👋 When removing a subscription, the notifier SHOULD send a NOTIFY request with a Subscription-State value of terminated to let the subscriber know it's being removed. If that request is sent, the Subscription-State header field SHOULD contain a reason=timeout parameter.
Clients can also end a subscription immediately by sending a SUBSCRIBE request with an Expires header field set to '0' 🧹 Notifiers mostly treat this like any other subscription expiration: they send a NOTIFY request with Subscription-State set to terminated, with a reason code of timeout. For consistency with state polling (see Section 4.4.3) and subscription refreshes, the notifier may choose to include resource state in this final NOTIFY request. But sometimes including state makes zero sense, so in those cases the notifier may choose to leave state info out of the terminal NOTIFY request 🙈
The sending of a NOTIFY request when a subscription expires lets the corresponding dialog usage get terminated, if that's appropriate. 🧚
4.2.2. Sending State Information to Subscribers
Notifiers use the NOTIFY method to send info about a resource's state to subscribers 📣 The notifier's view of a subscription is shown in the state diagram below. Events that lead back to the same state aren't drawn in this diagram.
+-------------+
| init |
+-------------+
|
Receive SUBSCRIBE,
Send NOTIFY
|
V NOTIFY failure,
+-------------+ subscription expires,
+------------| resp_wait |-- or terminated ----+
| +-------------+ per local policy |
| | |
| | |
| | V
Policy grants Policy needed +-------------+
permission | | terminated |
| | +-------------+
| | A A
| V NOTIFY failure, | |
| +-------------+ subscription expires,| |
| | pending |-- or terminated -------+ |
| +-------------+ per local policy |
| | |
| Policy changed to |
| grant permission |
| | |
| V NOTIFY failure, |
| +-------------+ subscription expires, |
+----------->| active |-- or terminated ---------+
+-------------+ per local policyWhen a SUBSCRIBE request gets answered with a 200-class response, the notifier MUST immediately build and send a NOTIFY request to the subscriber 🚀 When the subscribed state changes, the notifier SHOULD immediately build and send a NOTIFY request, unless the state transition is caused by a NOTIFY transaction failure. Sending this NOTIFY is also subject to authorization, local policy, and throttling considerations 🚦
If the NOTIFY request fails because SIP Timer F (transaction timeout) expires, the notifier SHOULD remove the subscription ⏳
This behaviour stops unnecessary state info from being sent to subscribers who have crashed or vanished from the network. Those transmissions get sent multiple times, per the retransmission algorithm in [RFC3261] (instead of the usual single transmission for working clients), so continuing to serve clients that can't acknowledge anything could put undue strain on a network 😭 When a client restarts or reestablishes its network connection, it's expected to send SUBSCRIBE requests to refresh potentially stale state, and those requests reinstall subscriptions in all the relevant nodes 🔁
If the NOTIFY transaction fails because the NOTIFY request got a 404, 405, 410, 416, 480-485, 489, 501, or 604 response, the notifier MUST remove the corresponding subscription 🗑️ See [RFC5057] for more details and notes about how error codes affect dialogs and usages within dialogs (like subscriptions).
A NOTIFY error response usually means something went wrong with the subscriber or with some proxy on the way to the subscriber. If the subscriber is the problem, it makes the most sense to let it fix things and re-subscribe once the error is handled 🙌 If a proxy is the problem, the periodic SUBSCRIBE refreshes will reinstall subscription state once the network issue is resolved.
NOTIFY requests MUST contain a Subscription-State header field with a value of active, pending, or terminated. The active value means the subscription has been accepted and authorized (in most cases; see Section 6.2) ✅ The pending value means the subscription has been received, but policy info isn't enough to accept or deny it yet 🕰️ The terminated value means the subscription isn't active 🛑
If the Subscription-State header field value is active or pending, the notifier MUST also include an expires parameter in the Subscription-State header field that shows the time remaining on the subscription. The notifier MAY use this mechanism to shorten a subscription, but this mechanism MUST NOT be used to lengthen a subscription ⏪
Including expiration info for active and pending subscriptions is necessary in case the SUBSCRIBE request forks, since the subscriber might not receive the response to a forked SUBSCRIBE request 🍴 [RFC3265] let the notifier decide whether to include this parameter, so subscriber implementations get a warning to handle a missingexpiresparameter gracefully 🫠 Note well that thisexpiresvalue is a parameter on theSubscription-Stateheader field, NOT theExpiresheader field 📌
The notifier can shorten a subscription's period all the way to zero 🫥 So it's perfectly valid for a SUBSCRIBE request with a non-zero expires to get answered with a NOTIFY request containing Subscription-Status: terminated;reason=expired. That just means the notifier cut the subscription timeout to zero, so the subscription expired instantly. The body may contain valid state, or it may contain a neutral state (see Section 5.4.7) 🌙
If the Subscription-State header field value is terminated, the notifier SHOULD also include a reason parameter. The notifier MAY also include a retry-after parameter where appropriate. For the details on the value and meaning of the reason and retry-after parameters, see Section 4.1.3 🧠
4.2.3. PSTN/Internet Interworking (PINT) Compatibility
The Event header field is considered mandatory for this document 📋 However, to stay compatible with PINT (see [RFC2848]), notifiers MAY interpret a SUBSCRIBE request with no Event header field as a request for a subscription to PINT events 🎀 If a notifier doesn't support PINT, it SHOULD return 489 (Bad Event) to any SUBSCRIBE requests without an Event header field 🙅♀️
4.3. Proxy Behavior 🎀
Okay so proxies don't need any extra behavior beyond what [RFC3261] already describes to handle SUBSCRIBE and NOTIFY transactions. Main character energy, honestly 💅. If a proxy wants to see all of the SUBSCRIBE and NOTIFY requests for a given dialog, it MUST add a Record-Route header field to the initial SUBSCRIBE request and all NOTIFY requests. It MAY choose to include Record-Route in subsequent SUBSCRIBE requests, but these requests cannot cause the dialog's route set to be modified 🦋.
Proxies that did not add a Record-Route header field to the initial SUBSCRIBE request MUST NOT add a Record-Route header field to any of the associated NOTIFY requests 🙈.
Note that subscribers and notifiers may elect to use Secure/Multipurpose Internet Mail Extensions (S/MIME) encryption of SUBSCRIBE and NOTIFY requests. So proxies cannot rely on being able to access any information that is not explicitly required to be proxy-readable by [RFC3261] 🔐✨
4.4. Common Behavior 🌸
4.4.1. Dialog Creation and Termination
Dialog usages are created upon completion of a NOTIFY transaction for a new subscription, unless the NOTIFY request contains a Subscription-State of "terminated" 🍓.
Because the dialog usage is established by the NOTIFY request, the route set at the subscriber is taken from the NOTIFY request itself. It is NOT taken from the route set in the 200-class response to the SUBSCRIBE request. Literally the NOTIFY is the one that gets to decide 👑.
NOTIFY requests are matched to such SUBSCRIBE requests if they contain the same Call-ID, a To header field tag parameter that matches the From header field tag parameter of the SUBSCRIBE request, and the same Event header field. The rules for comparing Event header fields are described in Section 8.2.1 🧩.
A subscription is destroyed after a notifier sends a NOTIFY request with a Subscription-State of "terminated", or in certain error situations described elsewhere in this document. The subscriber will generally answer such final requests with a 200 (OK) response, unless a condition warranting an alternate response has come up 💀. Except when the mechanism described in Section 4.5.2 is used, destroying a subscription also terminates its associated dialog.
A subscriber may send a SUBSCRIBE request with an "Expires" header field of 0 in order to trigger the sending of such a NOTIFY request. However, for the purposes of subscription and dialog lifetime, the subscription is not considered terminated until the NOTIFY transaction with a "Subscription-State" of "terminated" completes ⏳
4.4.2. Notifier Migration
It is often useful to allow subscriptions to migrate between notifiers 🦋. Migration may be effected by sending a NOTIFY request with a Subscription-State header field of "terminated" and a reason parameter of "deactivated". This NOTIFY request is otherwise normal and is formed as described in Section 4.2.2.
Upon receipt of this NOTIFY request, the subscriber SHOULD attempt to re-subscribe (as described in the preceding sections). Note that this subscription is established on a new dialog, and it does not reuse the route set from the previous subscription dialog 🧚
The actual migration is effected by changing the policy (such as routing decisions) of one or more servers that the SUBSCRIBE request will be sent to, in such a way that a different node ends up responding to the SUBSCRIBE request. This can be as simple as changing the local policy in the notifier that the subscription is migrating away from, so that it serves as a proxy or redirect server instead of a notifier 🔄
Whether, when, and why to perform notifier migrations may be described in individual event packages. Otherwise, those decisions are a matter of local notifier policy and are left up to individual implementations 💜
4.4.3. Polling Resource State
A natural consequence of the behavior described in the preceding sections is that an immediate fetch without a persistent subscription may be effected by sending a SUBSCRIBE with an "Expires" of 0 🌈.
Of course, an immediate fetch while a subscription is active may be effected by sending a SUBSCRIBE request with an "Expires" equal to the number of seconds remaining in the subscription ⭐.
Upon receipt of this SUBSCRIBE request, the notifier (or notifiers, if the SUBSCRIBE request was forked) will send a NOTIFY request containing resource state in the same dialog 📬.
Note that the NOTIFY requests triggered by SUBSCRIBE requests with "Expires" header fields of 0 will contain a Subscription-State value of "terminated" and a "reason" parameter of "timeout" ⏰.
Polling of event state can cause significant increases in load on the network and on notifiers, so it should be used only sparingly 🫶. In particular, polling SHOULD NOT be used in circumstances where it will typically result in more network messages than long-running subscriptions 🚫.
When polling is used, subscribers SHOULD attempt to cache authentication credentials between polls so as to reduce the number of messages sent 🔐.
Due to the requirement on notifiers to send a NOTIFY request immediately upon receipt of a SUBSCRIBE request, the state provided by polling is limited to the information that the notifier has immediate local access to when it receives the SUBSCRIBE request. If, for example, the notifier generally needs to retrieve state from another network server, then that state will be absent from the NOTIFY request that results from polling 🙃
4.4.4. "Allow-Events" Header Field Usage
The "Allow-Events" header field, if present, MUST include a comprehensive and inclusive list of tokens that indicates the event packages for which the user agent can act as a notifier. In other words, a user agent sending an "Allow-Events" header field is advertising that it can process SUBSCRIBE requests and generate NOTIFY requests for all of the event packages listed in that header field 📣.
Any user agent that can act as a notifier for one or more event packages SHOULD include an appropriate "Allow-Events" header field indicating all supported events in all methods that initiate dialogs and their responses (such as INVITE), as well as OPTIONS responses 🎀.
This information is super useful. For example, it lets user agents render particular interface elements appropriately, depending on whether the events needed to implement those features are supported by the right nodes ✨
On the other hand, it doesn't really make sense to indicate supported events inside a dialog established by a NOTIFY request if the only event package supported is the one associated with that subscription 🤷♀️
Note that "Allow-Events" header fields MUST NOT be inserted by proxies 🚫🍓.
The "Allow-Events" header field does not include a list of the event template-packages supported by an implementation. If a subscriber wants to know which event template-packages a notifier supports, it can probe for that support by attempting to subscribe to the event template-packages it wants to use 🔍.
For example: to check for support for the templatized package "presence.winfo", a client may attempt to subscribe to that event package for a known resource, using an "Expires" header value of 0. If the response is a 489 error code, then the client can deduce that "presence.winfo" is unsupported 💅
4.5. Targeting Subscriptions at Devices 🦄
[RFC3265] defined a mechanism that let subscriptions share dialogs with INVITE usages and with other subscriptions. The point of this was to make sure a subscription landed on the same device as an established dialog. Unfortunately, reusing dialogs has proven to be extremely confusing 😭. [RFC5057] tried to clarify the proper behavior in a bunch of different situations, but the rules that came out of it are still confusing and easy to mess up. Meanwhile, the mechanism described in [RFC5627] now gives us a much more elegant and unambiguous way to reach the same goal ✨.
So, the dialog reuse technique described in RFC 3265 is now deprecated 🥀.
This dialog-sharing technique has also historically been used to target an event package at a dialog. You can see this in certain applications of the REFER method [RFC3515], for example. Now that dialog reuse is gone, a different and more explicit way of targeting dialogs has to be used for this kind of correlation 🎯. Which approach fits is left up to the actual event packages. Candidates include the "Target-Dialog" header field [RFC4538], the "Join" header field [RFC3911], and the "Replaces" header field [RFC3891], depending on the semantics you want. Alternatively, if the semantics of those header fields don't match an event package's purpose for correlation, event packages can come up with their own way of identifying dialogs. For an example of that approach, check out the Dialog Event Package [RFC4235] 🧚.
4.5.1. Using GRUUs to Route to Devices
Notifiers MUST implement the Globally Routable User Agent URI (GRUU) extension defined in [RFC5627], and MUST use a GRUU as their local target. This lets subscribers explicitly target the devices they want 🎯💖.
If a subscriber wants to subscribe to a resource on the same device as an established dialog, it should check whether the remote contact in that dialog is a GRUU (i.e., whether it contains a "gr" URI parameter). If it is, the subscriber creates a new dialog, using the GRUU as the Request URI for the new SUBSCRIBE request 🫶.
Because GRUUs are guaranteed to route to a specific device, this ensures that the subscription gets routed to the same place as the established dialog. Iconic, honestly 👑🌈
4.5.2. Sharing Dialogs ✨
okay bestie, so for older clients, subscriber and notifier implementations may choose to allow dialog sharing 🫶. The way multiple usages live inside one dialog is described in [RFC5057] 💅
Subscribers MUST NOT attempt to reuse dialogs whose remote target is a GRUU. no cap, this one is a hard rule 🚫
Note that the techniques in this section are included for backwards-compatibility purposes only 🎀 Because subscribers cannot reuse dialogs with a GRUU for their remote target, and because notifiers must use GRUUs as their local target, any two implementations that conform to this specification will automatically use the mechanism described in Section 4.5.1. it's giving clean design 😭 Further note that the prohibition on reusing dialogs does not exempt implicit subscriptions created by the REFER method. This means that implementations complying with this specification are required to use the "Target-Dialog" mechanism described in [RFC4538] when the remote target is a GRUU. not me forgetting this detail 💀
If a subscriber wants to subscribe to a resource on the same device as an established dialog and the remote contact is not a GRUU, it MAY revert to dialog-sharing behavior 🦋. Alternately, it MAY choose to treat the remote party as incapable of servicing the subscription (i.e., the same way it would behave if the remote party did not support SIP events at all). 🥲
If a notifier receives a SUBSCRIBE request for a new subscription on an existing dialog, it MAY choose to implement dialog sharing behavior 🌸. Alternately, it may choose to fail the SUBSCRIBE request with a 403 (Forbidden) response. The error text of such 403 responses SHOULD indicate that dialog sharing is not supported 🍓.
To implement dialog sharing, subscribers and notifiers do the following extra processing 🧚:
- When subscriptions exist in dialogs associated with INVITE-created application state and/or other subscriptions, these sets of application state do not interact beyond the behavior described for a dialog (e.g., route set handling). In particular, multiple subscriptions within a dialog expire independently and require independent subscription refreshes. main character energy, each one lives its own life ✨
- If a subscription's destruction leaves no other application state associated with the dialog, the dialog terminates. The destruction of other application state (such as that created by an INVITE) will not terminate the dialog if a subscription is still associated with that dialog. This means that, when dialogs are reused, a dialog created with an INVITE does not necessarily terminate upon receipt of a BYE. Similarly, in the case that several subscriptions are associated with a single dialog, the dialog does not terminate until all the subscriptions in it are destroyed. 👑
- Subscribers MAY include an
"id"parameter in a SUBSCRIBE request's"Event"header field to allow differentiation between multiple subscriptions in the same dialog. This"id"parameter, if present, contains an opaque token that identifies the specific subscription within a dialog. An"id"parameter is only valid within the scope of a single dialog. 🔥 - If an
"id"parameter is present in the SUBSCRIBE request used to establish a subscription, that"id"parameter MUST also be present in all corresponding NOTIFY requests. 🫶 - When a subscriber refreshes the subscription timer, the SUBSCRIBE request MUST contain the same
"Event"header field"id"parameter as was present in the SUBSCRIBE request that created the subscription. (Otherwise, the notifier will interpret the SUBSCRIBE request as a request for a new subscription in the same dialog.) bestie, match the id or you get a whole new subscription 😭 - When a subscription is created in the notifier, it stores any
"Event"header field"id"parameter as part of the subscription information (along with the event package name). 📝 - If an initial SUBSCRIBE request is sent on a pre-existing dialog, a matching NOTIFY request merely creates a new subscription associated with that dialog. 🦋
4.6. CANCEL Requests for SUBSCRIBE and NOTIFY Transactions
Neither SUBSCRIBE nor NOTIFY requests can be canceled. 🚫 If a User Agent Server (UAS) receives a CANCEL request that matches a known SUBSCRIBE or NOTIFY transaction, it MUST respond to the CANCEL request, but otherwise ignore it. In particular, the CANCEL request MUST NOT affect processing of the SUBSCRIBE or NOTIFY request in any way. it's giving "reply but don't touch" 💅
UACs SHOULD NOT send CANCEL requests for SUBSCRIBE or NOTIFY transactions. 🙈
5. Event Packages
This section covers several issues that should be taken into consideration when event packages based on the SUBSCRIBE and NOTIFY methods are proposed. okay so this is the checklist before you build one 📋✨
5.1. Appropriateness of Usage
When designing an event package using the methods described in this document for event notification, it is important to consider: is SIP an appropriate mechanism for the problem set? Is SIP being selected because of some unique feature provided by the protocol (e.g., user mobility) or merely because "it can be done"? If you find yourself defining event packages for notifications related to, for example, network management or the temperature inside your car's engine, you may want to reconsider your selection of protocols. 🤨🚗
Those interested in extending the mechanism defined in this document are urged to follow the development of "Guidelines for Authors of SIP Extensions" [RFC4485] for further guidance regarding appropriate uses of SIP. 🎀
Further, it is expected that this mechanism is not to be used in applications where the frequency of reportable events is excessively rapid (e.g., more than about once per second). A SIP network is generally going to be provisioned for a reasonable signaling volume; sending a notification every time a user's GPS position changes by one hundredth of a second could easily overload such a network. 😭📍 bestie, that's a lot of NOTIFYs 💀
5.2. Event Template-Packages
Normal event packages define a set of state applied to a specific type of resource, such as user presence, call state, and messaging mailbox state. 🌈
Event template-packages are a special type of package that define a set of state applied to other packages, such as statistics, access policy, and subscriber lists. Event template-packages may even be applied to other event template-packages. ✨
To extend the object-oriented analogy made earlier, event template-packages can be thought of as templatized C++ packages that must be applied to other packages to be useful. 🧚
The name of an event template-package as applied to a package is formed by appending a period followed by the event template-package name to the end of the package. For example, if a template-package called "winfo" were being applied to a package called "presence", the event token used in the "Event" header field would be "presence.winfo". 💜
This scheme may be arbitrarily extended. For example, application of the "winfo" package to the"presence.winfo"state of a resource would be represented by the name"presence.winfo.winfo". It naturally follows from this syntax that the order in which templates are specified is significant. 🌀 For example: consider a theoretical event template-package called "list". The event"presence.winfo.list"would be the application of the "list" template to"presence.winfo", which would presumably be a list of winfo state associated with presence. On the other hand, the event"presence.list.winfo"would represent the application of winfo to"presence.list", which would be represent the winfo state of a list of presence information. order matters, the way it's giving grammar 😭
Event template-packages must be defined so that they can be applied to any arbitrary package. In other words, event template-packages cannot be specifically tied to one or a few "parent" packages in such a way that they will not work with other packages. 🫶
5.3. Amount of State to Be Conveyed
When designing event packages, it is important to consider the type of information that will be conveyed during a notification. 🧠
A natural temptation is to convey merely the event (e.g., "a new voice message just arrived") without accompanying state (e.g., "7 total voice messages"). This complicates implementation of subscribing entities (since they have to maintain complete state for the entity to which they have subscribed), and also is particularly susceptible to synchronization problems. 🙃 we've all been there
This problem has two possible solutions that event packages may choose to implement. 💅
5.3.1. Complete State Information
In general, event packages need to be able to convey a well-defined and complete state, rather than just a stream of events. If it is not possible to describe complete system state for transmission in NOTIFY requests, then the problem set is not a good candidate for an event package. 🚫
For packages that typically convey state information that is reasonably small (on the order of 1 KB or so), it is suggested that event packages are designed so as to send complete state information whenever an event occurs. 🌸
In some circumstances, conveying the current state alone may be insufficient for a particular class of events. In these cases, the event packages should include complete state information along with the event that occurred. For example, conveying "no customer service representatives available" may not be as useful as conveying "no customer service representatives available; representative sip:46@cs.xyz.int just logged off". 🥹
5.3.2. State Deltas
In the case that the state information to be conveyed is large, the event package may choose to detail a scheme by which NOTIFY requests contain state deltas instead of complete state. 🍓
Such a scheme would work as follows: any NOTIFY request sent in immediate response to a SUBSCRIBE request contains full state information. NOTIFY requests sent because of a state change will contain only the state information that has changed; the subscriber will then merge this information into its current knowledge about the state of the resource. 🧩
Any event package that supports delta changes to states MUST include a version number that increases by exactly one for each NOTIFY transaction in a subscription. Note that the state version number appears in the body of the message, not in a SIP header field. 🔢✨
If a NOTIFY request arrives that has a version number that is incremented by more than one, the subscriber knows that a state delta has been missed; it ignores the NOTIFY request containing the state delta (except for the version number, which it retains to detect message loss), and re-sends a SUBSCRIBE request to force a NOTIFY request containing a complete state snapshot. 😱 missed one delta, so we start fresh, no drama 🫶
5.4. Event Package Responsibilities ✨
Okay so event packages don't have to repeat everything in this doc 💅 they're allowed to, for clarity or emphasis, but mostly they should only describe the stuff that extends or modifies what's already here 🫶
Btw, any behavior marked with "SHOULD" or "MUST" in this document is not allowed to be weakened by extension docs 😤 but those docs can totally level a "SHOULD" up to a "MUST" if their app needs it 🔥
On top of the normal sections you'd expect in Standards Track RFCs and SIP extension docs, event package authors need to cover each of the issues in the subsections below 📋 For clarity: well-formed event package definitions have a section for each of these, ideally in the same order and with the same titles 🎀
5.4.1. Event Package Name 🌸
This section, which MUST be present, defines the token name used to designate the event package 🏷️ It MUST include the info that appears in the IANA registration of the token 📝 For info on registering those, see Section 7 💖
5.4.2. Event Package Parameters 🧁
If parameters are going to be used on the "Event" header field to modify the behavior of the event package, the syntax and semantics of those header fields MUST be clearly defined ✨
Any "Event" header field parameters an event package defines MUST be registered in the "Header Field Parameters and Parameter Values" registry defined by [RFC3968] 📚 An "Event" header field parameter, once registered in conjunction with an event package, MUST NOT be reused with any other event package 🙅♀️ Non-event-package specs MAY define "Event" header field parameters that apply across all event packages (emphasis on "all", not "several" 👑), like the "id" parameter defined in this document 🧚 The single-package restriction only applies to parameters defined alongside an event package 🦋
5.4.3. SUBSCRIBE Request Bodies 🎀
It's expected that most (but not all) event packages will define syntax and semantics for SUBSCRIBE request bodies 💅 These bodies usually modify, expand, filter, throttle, and/or set thresholds for the class of events being requested 🔍 Package designers are strongly encouraged to reuse existing media types for message bodies where practical 💖 See [RFC4288] for media type specification and registration 📖
This mandatory section of an event package says what type or types of event bodies are expected in SUBSCRIBE requests (or says that no event bodies are expected) 📋 It should point to detailed definitions of syntax and semantics for all referenced body types 🫶
5.4.4. Subscription Duration ⏰
It is RECOMMENDED that event packages give a suggested range of times considered reasonable for the duration of a subscription 🕰️ Such packages MUST also define a default "Expires" value to be used if none is specified ✨
5.4.5. NOTIFY Request Bodies 📣
The NOTIFY request body is how state on the monitored resource gets reported 📨 Each package MUST define what type or types of event bodies are expected in NOTIFY requests 💅 Such packages MUST specify or cite detailed specifications for the syntax and semantics of those bodies 🧠
Event packages also MUST define which media type is assumed if none are specified in the "Accept" header field of the SUBSCRIBE request 🙈
5.4.6. Notifier Processing of SUBSCRIBE Requests 👑
This section describes what the notifier does when a SUBSCRIBE request shows up 🚪 Such a section is required 🔥 Info here includes how to authenticate subscribers and any authorization issues for the package 🔐
5.4.7. Notifier generation of NOTIFY requests 🌈
This section is where the package explains how the notifier generates and sends a NOTIFY request 📬 It covers what events trigger a NOTIFY, how to compute the state inside it, and how to generate neutral or fake state information to hide authorization delays and decisions from users 🙈 It also covers whether the state is complete or what the deltas are for notifications (see Section 5.3) 💖 Such a section is required 😤
This section may optionally describe the behavior used to process the subsequent response 🦋
5.4.8. Subscriber Processing of NOTIFY Requests 🧩
This section describes what the subscriber does when a NOTIFY request lands, including any logic needed to form a coherent resource state (if applicable) 💜
5.4.9. Handling of Forked Requests 🍴
Each event package MUST specify whether forked SUBSCRIBE requests are allowed to install multiple subscriptions 🤔
If that's not allowed, the first potential dialog-establishing message creates a dialog ✨ Every later NOTIFY request that corresponds to the SUBSCRIBE request (matching "To", "From", "Call-ID", and "Event" header fields, plus the "tag" parameter of the "From" header field and the "id" parameter of the "Event" header field) but doesn't match the dialog gets rejected with a 481 response 🚫 Also, the 200-class response to the SUBSCRIBE can arrive after a matching NOTIFY has already been received 👀 Those responses might not line up with the dialog the NOTIFY established, so apart from what's needed to complete the SUBSCRIBE transaction, those non-matching 200-class responses get ignored 🙅♀️
If installing multiple subscriptions from a single forked SUBSCRIBE request is allowed, the subscriber establishes a new dialog toward each notifier by returning a 200-class response to each NOTIFY request 🦋 Each dialog is then handled as its own entity and gets refreshed independently of the others 🌸
In the case that multiple subscriptions are allowed, the event package MUST specify whether merging the notifications into a single state is required, and how that merging is done 🧪 Some packages might be defined so each dialog is tied to a mutually exclusive state that's unaffected by the other dialogs; if that's the case, this MUST be clearly stated 📣
5.4.10. Rate of Notifications 🚦
Each event package is expected to define a requirement ("SHOULD" or "MUST" strength) setting an absolute maximum on how fast a single notifier is allowed to generate notifications 🐢 Each package MAY further define a throttle mechanism that lets subscribers limit the rate even more 🫧
5.4.11. State Aggregation 🧺
Lots of event packages work by collecting info about a resource from a bunch of other sources 🕸️ That might be through PUBLISH [RFC3903], by subscribing to state info, or through other state-gathering mechanisms 📡
Event packages that retrieve state for a single resource from more than one source need to think about how notifiers aggregate everything into one coherent state 🧩 Such packages MUST specify how notifiers aggregate information and how they provide authentication and authorization 🔐
5.4.12. Examples 📸
Event packages SHOULD include several demonstrative message flow diagrams paired with several typical, syntactically correct, and complete messages 🖼️
It is RECOMMENDED that documents describing event packages clearly say these examples are informative and not normative 📖 with a note that implementors should check the main text for exact protocol details 🤓
5.4.13. Use of URIs to Retrieve State 🔗
Some event packages may define state that's potentially too big to reasonably send in a SIP message 🐘 To fix that, packages may convey a URI instead of the state itself, and that URI is then used to fetch the actual state info 📦
[RFC4483] defines a mechanism that event packages can use to convey information in this fashion 🎁
6. Security Considerations 🔐
6.1. Access Control 🚪
Accepting subscriptions should be under the direct control of the notifier's user, since lots of event types can be private 🤫 Similarly, the notifier should be able to selectively reject subscriptions based on the subscriber's identity (using access control lists), with standard SIP authentication mechanisms 🔑 How those access control lists get created and distributed is outside the scope of this document 📜
6.2. Notifier Privacy Mechanism 🎭
The mere act of returning certain 400- and 600-class responses to SUBSCRIBE requests may, under certain circumstances, create privacy concerns by revealing sensitive policy info 😬 In these cases, the notifier SHOULD always return a 200 (OK) response 🛡️ While the subsequent NOTIFY request may not convey true state, it MUST appear to contain a potentially correct piece of data from the subscriber's point of view, indistinguishable from a valid response 🫣 Info about whether a user is authorized to subscribe to the requested state is never conveyed back to the original user under these circumstances 🤐
Individual packages and their related docs where this mode of operation makes sense can further describe how and why to generate that potentially correct data 🧁 For example, [RFC2779] mandates this mode of operation for user presence information 💡
6.3. Denial-of-Service Attacks 😱
The current model (one SUBSCRIBE request triggers a SUBSCRIBE response and one or more NOTIFY requests) is a classic setup for an amplifier node to be used in a smurf attack [CERT1998a] 💀
Also, creating state when a SUBSCRIBE request arrives can be used by attackers to eat up resources on a victim's machine until it's totally unusable 🫠
To reduce the chances of this kind of attack, implementations of notifiers SHOULD require authentication 🔒 Authentication issues are discussed in [RFC3261] 📖
6.4. Replay Attacks 🔁
Replaying either SUBSCRIBE or NOTIFY requests can have detrimental effects 🙀
With SUBSCRIBE requests, an attacker may be able to install any arbitrary subscription that they witnessed being installed at some point in the past 🕵️ Replaying NOTIFY requests may be used to spoof old state information (although a good versioning mechanism in the body of the NOTIFY requests may help mitigate that) 🫤 Also, the prohibition on sending NOTIFY requests to nodes that haven't subscribed to an event also helps mitigate the effects of such an attack 🙅♀️
To prevent such attacks, implementations SHOULD require authentication with anti-replay protection 🛡️ Authentication issues are discussed in [RFC3261] 💜
6.5. Man-in-the-Middle Attacks 🕵️♀️
okay so even WITH authentication, man-in-the-middle attacks using SUBSCRIBE requests can still be used to install arbitrary subscriptions, hijack existing subscriptions, terminate outstanding subscriptions, or modify the resource that a subscription is being made to. not okay 😤 so to stop this, implementations SHOULD provide integrity protection across the Contact, Route, Expires, Event, and To header fields (at a minimum) of SUBSCRIBE requests. and if SUBSCRIBE request bodies are used to define more info about the state of the call, they SHOULD be included in the integrity protection scheme too 🔐
man-in-the-middle attacks can also try to use NOTIFY requests to spoof random state info and/or terminate outstanding subscriptions 💀 to block that, implementations SHOULD provide integrity protection across the Call-ID, CSeq, and Subscription-State header fields and the bodies of NOTIFY requests 🫶
integrity protection for header fields and bodies is discussed in [RFC3261]. go read that one, it's the main source 📖✨
6.6. Confidentiality 🤫
the state info inside a NOTIFY request could easily have sensitive stuff in it 👀 so implementations MAY encrypt that info to keep it confidential 🔒
it's less likely, but the info inside a SUBSCRIBE request could also contain stuff users wouldn't want revealed 🙈 implementations MAY encrypt that too for confidentiality 💜
and so the remote party can hide anything it considers sensitive, all implementations SHOULD be able to handle encrypted SUBSCRIBE and NOTIFY requests 🧚
the mechanisms for providing confidentiality are detailed in [RFC3261] 🎀
7. IANA Considerations ✨
except for Section 7.2, the subsections here are just for current reference, carried over from the original spec (RFC 3265) 📜 IANA has updated all the registry references that pointed to RFC 3265 so they point to this document now, and they also made the brand new "reason code" registry described in Section 7.2 🎀
7.1. Event Packages 📦
this document defines an event-type namespace that needs a central coordinating body, and the body chosen for that job is the Internet Assigned Numbers Authority (IANA) 👑
there are two types of event-types: normal event packages and event template-packages (see Section 5.2) 🦋 to avoid confusion, template-package names and package names share the same namespace. so an event template-package is forbidden from sharing a name with a package 🚫
the policies for registering SIP event packages and SIP event package templates are defined in Section 4.1 of [RFC5727] 💅
registrations with IANA have to include the token being registered and whether that token is a package or a template-package. packages also need contact info for the party responsible for the registration and/or a published document that describes the event package. event template-package token registrations also need a pointer to the published RFC that defines the event template-package 🌸
and registered tokens for packages and template-packages are NOT allowed to contain the character ".", because that's what separates template-packages from packages 🙅♀️
7.1.1. Registration Information 📝
this document doesn't specify any package or template-package names, because all the entries in this table are added by other documents 🙈 the rest of this section is just an example of the kind of info IANA maintains, and it shows all four possible combos of package type, contact, and reference ✨ the table below lists the event packages and template-packages defined for use with the "SIP-Specific Event Notification" mechanism [RFC 6665]. each name is marked as a package or a template-package under "Type" 🌈
Package Name Type Contact Reference
------------ ---- ------- ---------
example1 package [Doe] [RFCnnnn]
example2 package [RFCnnnn]
example3 template [Doe] [RFCnnnn]
example4 template [RFCnnnn]
PEOPLE
------
[Doe] John Doe <john.doe@example.com>
REFERENCES
----------
[RFCnnnn] Doe, J., "Sample Document", RFC nnnn, Month YYYY.7.1.2. Registration Template 💌
To: ietf-sip-events@iana.org
Subject: Registration of new SIP event package
Package name:
(Package names must conform to the syntax described in
Section 8.2.1.)
Is this registration for a Template-Package:
(indicate yes or no)
Published specification(s):
(Template-packages require a published RFC. Other packages may
reference a specification when appropriate.)
Person & email address to contact for further information:
(self-explanatory)7.2. Reason Codes 🚦
this document goes further and defines "reason" codes for use in the Subscription-State header field (see Section 4.1.3) 💖
following the policies in "Guidelines for Writing an IANA Considerations Section in RFCs" [RFC5226], new reason codes need a Standards Action 📜 registrations with IANA include the reason code being registered and a reference to a published document that describes the event package. adding these values happens as part of the RFC publication process, or as the result of liaison activity between standards development organizations (SDOs), which ends with an associated RFC being published 🤝 new reason codes must conform to the syntax of the ABNF "token" element defined in [RFC3261] ✨
[RFC4660] defined a new reason code before there was an IANA registry for them. we include its reason code ("badfilter") in the starter list of reason codes so the registry is complete 🧩
the IANA registry for reason codes has been set up with these values:
Reason Code Reference
----------- ---------
deactivated [RFC6665]
probation [RFC6665]
rejected [RFC6665]
timeout [RFC6665]
giveup [RFC6665]
noresource [RFC6665]
invariant [RFC6665]
badfilter [RFC4660]
REFERENCES
----------
[RFC6665] A.B. Roach, "SIP-Specific Event Notification", RFC 6665,
July 2012.
[RFC4660] Khartabil, H., Leppanen, E., Lonnfors, M., and
J. Costa-Requena, "Functional Description of Event
Notification Filtering", September 2006.7.3. Header Field Names 🎀
this document registers three new header field names, which are described elsewhere in the doc 💅 they get added to the header field sub-registry under http://www.iana.org/assignments/sip-parameters 🌐
Header Name: Allow-Events
Compact Form: u
Header Name: Subscription-State
Compact Form: (none)
Header Name: Event
Compact Form: o7.4. Response Codes 🧁
this document registers two new response codes 👑 they get added to the method and response-code sub-registry under http://www.iana.org/assignments/sip-parameters 🌸
Response Code Number: 202
Default Reason Phrase: Accepted
Response Code Number: 489
Default Reason Phrase: Bad Event8. Syntax 🧠
this section describes the syntax extensions needed for event notification in SIP. the semantics are in Section 4 💜 also, the formal syntax definitions here are written in the ABNF format used in [RFC3261] and they reference elements defined in there, so you'll need that one too 📖🫶
8.1. New Methods 🦋
this document describes two new SIP methods: SUBSCRIBE and NOTIFY ✨
8.1.1. SUBSCRIBE Method 📨
SUBSCRIBE gets added to the definition of the element "Method" in the SIP message grammar 🎀
like all SIP method names, the SUBSCRIBE method name is case sensitive 🙅♀️ the SUBSCRIBE method is used to request asynchronous notification of an event or set of events at a later time ⏰
8.1.2. NOTIFY Method 🔔
NOTIFY gets added to the definition of the element "Method" in the SIP message grammar 💖
the NOTIFY method is used to tell a SIP node that an event requested by an earlier SUBSCRIBE method has happened 🎉 it can also give further details about the event 🌈
8.2. New Header Fields 💌
8.2.1. "Event" Header Field 🏷️
Event gets added to the definition of the element "message-header field" in the SIP message grammar 🧚
to match NOTIFY requests with SUBSCRIBE requests, the event-type portion of the Event header field is compared byte by byte, and so is the "id" parameter token (if one is there) 🔍 an Event header field with an "id" parameter NEVER matches one without an "id" parameter. no other parameters get considered in the comparison 🙅♀️ SUBSCRIBE responses are matched using the transaction handling rules in [RFC3261] 📜
Note that the stuff above meansEvent: foo; id=1234would matchEvent: foo; param=abcd; id=1234, but NOTEvent: foo("id" does not match) orEvent: Foo; id=1234("Event" portion does not match). iykyk, case matters 💀
this document doesn't define values for event-types. those get defined by the individual event packages, and they MUST be registered with IANA 👑
there MUST be exactly one event type listed per Event header field. multiple events per message are NOT allowed 🚫
the Event header field is only defined for use in SUBSCRIBE and NOTIFY requests, plus any other requests whose definition explicitly calls for it 🦋 it MUST NOT appear in any other SIP requests, and it MUST NOT appear in responses either 🙈
8.2.2. "Allow-Events" Header Field 🌸
Allow-Events gets added to the definition of the element "general-header field" in the SIP message grammar. its usage is described in Section 4.4.4 🧁
user agents MAY include the Allow-Events header field in any request or response, as long as its contents follow the behavior described in Section 4.4.4 🫶
8.2.3. "Subscription-State" Header Field 🔄
Subscription-State gets added to the definition of the element "request-header" field in the SIP message grammar. its usage is described in Section 4.1.3 ✨ Subscription-State header fields are defined for use in NOTIFY requests ONLY. they MUST NOT appear in other SIP requests or responses 🙅♀️💅
8.3. New Response Codes 🎀
8.3.1. 202 (Accepted) Response Code ✨
Okay so, for historical purposes 📜, the 202 (Accepted) response code gets added to the "Success" header field definition.
This doc does not specify how the 202 response code works with the SUBSCRIBE or NOTIFY methods 🙅. Older versions of the SIP Events Framework actually gave 202 a specific meaning, so heads up 👀.
Here's the drama 🍴. Because of how responses get handled in forking cases, any 202 response to a SUBSCRIBE request may be absorbed by a proxy. That means it can never be guaranteed to reach the UAC 😬. Also, a 202 doesn't actually process any differently from a 200. A NOTIFY request gets sent after the subscription is processed, and it carries the correct state either way. SIP interoperability tests found that implementations were treating 202 differently from 200, and that caused incompatibilities 💀. So 202 is being deprecated to make it crystal clear there's no difference, and 202 should not be handled differently than 200 💅.
Implementations that conform to this spec MUST treat an incoming 202 response as identical to a 200 response, and they MUST NOT generate 202 response codes to SUBSCRIBE or NOTIFY requests 🫶.
This doc also updates [RFC4660], which repeats the 202-based behavior in several places 🙄. Implementations compliant with this document MUST NOT send a 202 response to a SUBSCRIBE request. They'll send an alternate success response (such as 200) in its place instead 🎀.
8.3.2. 489 (Bad Event) Response Code 🌸
The 489 event response gets added to the "Client-Error" header field definition. 489 (Bad Event) is how a server says it didn't understand the event package specified in an "Event" header field 🙈.
8.4. Augmented BNF Definitions 🧩
Okay, here's the grammar. It uses the Augmented BNF [RFC5234] definitions for all the new and modified syntax elements. The notation is the same as in [RFC3261], and any elements not defined in this section are defined in SIP and the documents it refers to 💖.
SUBSCRIBEm = %x53.55.42.53.43.52.49.42.45 ; SUBSCRIBE in caps
NOTIFYm = %x4E.4F.54.49.46.59 ; NOTIFY in caps
extension-method = SUBSCRIBEm / NOTIFYm / token
Event = ( "Event" / "o" ) HCOLON event-type
*( SEMI event-param )
event-type = event-package *( "." event-template )
event-package = token-nodot
event-template = token-nodot
token-nodot = 1*( alphanum / "-" / "!" / "%" / "*"
/ "_" / "+" / "`" / "'" / "~" )
; The use of the "id" parameter is deprecated; it is included
; for backwards-compatibility purposes only.
event-param = generic-param / ( "id" EQUAL token )
Allow-Events = ( "Allow-Events" / "u" ) HCOLON event-type
*(COMMA event-type)
Subscription-State = "Subscription-State" HCOLON substate-value
*( SEMI subexp-params )
substate-value = "active" / "pending" / "terminated"
/ extension-substate
extension-substate = token
subexp-params = ("reason" EQUAL event-reason-value)
/ ("expires" EQUAL delta-seconds)
/ ("retry-after" EQUAL delta-seconds)
/ generic-param
event-reason-value = "deactivated"
/ "probation"
/ "rejected"
/ "timeout"
/ "giveup"
/ "noresource"
/ "invariant"
/ event-reason-extension
event-reason-extension = token9. References 📚
9.1. Normative References 💜
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC2848] Petrack, S. and L. Conroy, "The PINT Service Protocol: Extensions to SIP and SDP for IP Access to Telephone Call Services", RFC 2848, June 2000.
- [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002.
- [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002.
- [RFC3968] Camarillo, G., "The Internet Assigned Number Authority (IANA) Header Field Parameter Registry for the Session Initiation Protocol (SIP)", BCP 98, RFC 3968, December 2004.
- [RFC4483] Burger, E., "A Mechanism for Content Indirection in Session Initiation Protocol (SIP) Messages", RFC 4483, May 2006.
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
- [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.
- [RFC5627] Rosenberg, J., "Obtaining and Using Globally Routable User Agent URIs (GRUUs) in the Session Initiation Protocol (SIP)", RFC 5627, October 2009.
- [RFC5727] Peterson, J., Jennings, C., and R. Sparks, "Change Process for the Session Initiation Protocol (SIP) and the Real-time Applications and Infrastructure Area", BCP 67, RFC 5727, March 2010.
9.2. Informative References 🦋
- [RFC2779] Day, M., Aggarwal, S., Mohr, G., and J. Vincent, "Instant Messaging / Presence Protocol Requirements", RFC 2779, February 2000.
- [RFC3515] Sparks, R., "The Session Initiation Protocol (SIP) Refer Method", RFC 3515, April 2003.
- [RFC3840] Rosenberg, J., Schulzrinne, H., and P. Kyzivat, "Indicating User Agent Capabilities in the Session Initiation Protocol (SIP)", RFC 3840, August 2004.
- [RFC3891] Mahy, R., Biggs, B., and R. Dean, "The Session Initiation Protocol (SIP) "Replaces" Header", RFC 3891, September 2004.
- [RFC3903] Niemi, A., "Session Initiation Protocol (SIP) Extension for Event State Publication", RFC 3903, October 2004.
- [RFC3911] Mahy, R. and D. Petrie, "The Session Initiation Protocol (SIP) "Join" Header", RFC 3911, October 2004.
- [RFC4235] Rosenberg, J., Schulzrinne, H., and R. Mahy, "An INVITE-Initiated Dialog Event Package for the Session Initiation Protocol (SIP)", RFC 4235, November 2005.
- [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and Registration Procedures", BCP 13, RFC 4288, December 2005.
- [RFC4485] Rosenberg, J. and H. Schulzrinne, "Guidelines for Authors of Extensions to the Session Initiation Protocol (SIP)", RFC 4485, May 2006.
- [RFC4538] Rosenberg, J., "Request Authorization through Dialog Identification in the Session Initiation Protocol (SIP)", RFC 4538, June 2006.
- [RFC4660] Khartabil, H., Leppanen, E., Lonnfors, M., and J. Costa-Requena, "Functional Description of Event Notification Filtering", RFC 4660, September 2006.
- [RFC5057] Sparks, R., "Multiple Dialog Usages in the Session Initiation Protocol", RFC 5057, November 2007.
- [RFC5839] Niemi, A. and D. Willis, "An Extension to Session Initiation Protocol (SIP) Events for Conditional Event Notification", RFC 5839, May 2010.
- [CERT1998a] CERT, "CERT Advisory CA-1998-01: Smurf IP Denial-of-Service Attacks", 1998,
http://www.cert.org/advisories/CA-1998-01.html.
Appendix A. Acknowledgements 🙏
Huge thank yous to everyone in the Events BOF at the 48th IETF meeting in Pittsburgh, plus everyone who dropped ideas and suggestions on the SIP Events mailing list 💌. Special shoutouts go to Henning Schulzrinne of Columbia University for coming up with the final three-tiered event identification scheme 👑, Sean Olson for miscellaneous guidance, Jonathan Rosenberg for a thorough scrubbing of the first draft version, and the authors of the "SIP Extensions for Presence" document for their input to SUBSCRIBE and NOTIFY request semantics 🫶.
We also owe so much to all the implementors who gave feedback on confusing or difficult areas of the original specification 💖. In particular, Robert Sparks' Herculean efforts organizing, running, and collecting data from the SIPit events were super invaluable for shaking out specification bugs 🔥. Robert Sparks is also responsible for untangling the dialog usage mess, in the form of RFC 5057 [RFC5057] 😭.
Appendix B. Changes from RFC 3265 🎀
This document has several changes from the mechanism originally described in RFC 3265. This section sums those changes up 📝. Bug numbers refer to the identifiers for the bug reports kept on file at http://bugs.sipit.net/.
B.1. Bug 666: Clarify use of "expires=xxx" with "terminated"
Strengthened language in Section 4.1.3 to clarify that "expires" should not be sent with "terminated", and must be ignored if received ⏰.
B.2. Bug 667: Reason code for unsub/poll not clearly spelled out
Clarified description of "timeout" in Section 4.1.3. (n.b., the text in Section 4.4.3 is actually pretty clear about this) 🙃.
B.3. Bug 669: Clarify: SUBSCRIBE for a duration might be answered with a NOTIFY/expires=0
Added clarifying text to Section 4.2.2 explaining that shortening a subscription to zero seconds is valid. Also added a sentence to Section 3.1.1 explicitly allowing shortening to zero 🧚.
B.4. Bug 670: Dialog State Machine needs clarification
The issues with this bug deal exclusively with handling multiple usages within a dialog. That behavior has been deprecated and moved to Section 4.5.2. This section, in turn, cites [RFC5057], which addresses all of the issues in Bug 670 🌈.
B.5. Bug 671: Clarify timeout-based removal of subscriptions
Changed Section 4.2.2 to specifically cite Timer F (so as to avoid ambiguity between transaction timeouts and retransmission timeouts) ⭐.
B.6. Bug 672: Mandate "expires" in NOTIFY
Changed strength of including of "expires" in a NOTIFY from "SHOULD" to "MUST" in Section 4.2.2 💪.
B.7. Bug 673: INVITE 481 response effect clarification
This bug was addressed in [RFC5057] 🍓.
B.8. Bug 677: SUBSCRIBE response matching text in error
Fixed Section 8.2.1 to remove incorrect "...responses and..." -- explicitly pointed to SIP for transaction response handling 🛠️.
B.9. Bug 695: Document is not explicit about response to NOTIFY at subscription termination
Added text to Section 4.4.1 indicating that the typical response to a terminal NOTIFY is a 200 (OK) ✅.
B.10. Bug 696: Subscription state machine needs clarification
Added state machine diagram to Section 4.1.2 with explicit handling of what to do when a SUBSCRIBE never shows up. Added definition of and handling for new Timer N to Section 4.1.2.4. Added state machine to Section 4.2.2 to reinforce text 🦋.
B.11. Bug 697: Unsubscription behavior could be clarified
Added text to Section 4.2.1.4 encouraging (but not requiring) full state in final NOTIFY request. Also added text to Section 4.1.2.3 warning subscribers that full state may or may not be present in the final NOTIFY 💜.
B.12. Bug 699: NOTIFY and SUBSCRIBE are target refresh requests 🎀
Okay so bug 699 was about making things super clear: they added text to both Sections 3.1 and 3.2 that says straight up that SUBSCRIBE and NOTIFY are target refresh methods. No more guessing, bestie 💅
B.13. Bug 722: Inconsistent 423 reason phrase text ✨
The 423 reason phrase was giving mixed signals, so they changed it to Interval Too Brief in Sections 4.2.1.1 and 4.2.1.4. Now it matches the 423 reason phrase in SIP [RFC3261]. Everything lines up, periodt 🫶
B.14. Bug 741: Guidance needed on when to not include "Allow-Events" 🦋
This one got a non-normative clarification in Section 4.4.4 about when to include Allow-Events in a NOTIFY for the one-and-only package the notifier supports. It's extra guidance, not a rule, so it's a lowkey helpful little note 🌸
B.15. Bug 744: 5xx to NOTIFY terminates a subscription, but should not 💀
Ngl this one is a whole saga. Ending a subscription (usage) and ending a dialog are two different things, and that distinction is handled in [RFC5057]. The text in Section 4.2.2 now summarizes the behavior described by RFC 5057 and points to it for more detail and rationale. Go read RFC 5057 if you want the full tea ☕
B.16. Bug 752: Detection of forked requests is incorrect 🍓
They removed "CSeq" from the list of matching criteria in Section 5.4.9, because it was wrong there. Bye bye, erroneous CSeq 👋
B.17. Bug 773: Reason code needs IANA registry 👑
Section 7.2 was added to create and populate an IANA registry for reason codes. Registry energy is so iconic 🌈
B.18. Bug 774: Need new reason for terminating subscriptions to resources that never change 🧚
A new invariant reason code was added to Section 4.1.3, and it also shows up in the ABNF syntax in Section 8.4. Perfect for resources that literally never change, no cap 💜
B.19. Clarify Handling of "Route"/"Record-Route" in NOTIFY 🌸
Section 4.3 got updated to mandate Record-Route in the initial SUBSCRIBE and in all NOTIFY requests. It also adds "MAY"-level statements for subsequent SUBSCRIBE requests. So the rules for Record-Route are way clearer now ✨
B.20. Eliminate Implicit Subscriptions 🚫
Section 4.2.1 got new text explaining some of the problems with implicit subscriptions, plus normative language that prohibits them. Section 3.2 lost its language about "non-SUBSCRIBE" mechanisms for creating subscriptions. And Section 4.2.2 got simplified, because the soft-state/non-soft-state distinction isn't needed anymore. Clean and tidy, bestie 🧹
B.21. Deprecate Dialog Reuse 🍂
Handling of dialog reuse and "id" handling moved to Section 4.5.2. It's documented only for backwards-compatibility purposes, so it's kind of a retired-but-still-here situation 🫠
B.22. Rationalize Dialog Creation 🎀
Section 4.4.1 now says dialogs should be created when the NOTIFY arrives. Before, the dialog got established by the SUBSCRIBE 200 or by the NOTIFY transaction. That was unnecessarily complicated, so the newer rules are way easier to implement. The good news is it ends up being effectively the same behavior on the wire 💖
B.23. Refactor Behavior Sections 🧩
Section 4 got reorganized so behavior is grouped by role (subscriber/notifier/proxy) instead of by method. Organization queen behavior 👑
B.24. Clarify Sections That Need to Be Present in Event Packages 📋
Section 5 got a sentence clarifying that event packages are expected to include explicit sections covering the issues discussed in that section. So package authors, take notes 📝
B.25. Make CANCEL Handling More Explicit 🛑
Section 4.6 now clearly calls out what happens when a CANCEL is received. They also echo the "...SHOULD NOT send..." requirement from [RFC3261], so it's repeated for emphasis 🫶
B.26. Remove "State Agent" Terminology 🫧
Okay, the story here is that they originally expected a bunch of event packages to move back and forth between end-user devices and servers in the network. That didn't really happen. Dialog state is inherently hosted on end-user devices, while things like presence are almost always hosted in the network because of composition and delivering info when user devices are offline. Also, "State Agent" was the most misunderstood concept by event package authors. In the expert review, the author couldn't find a single event package that got it completely right, and most started out with it backwards from how RFC 3265 described it 😭
So instead of removing the abilities that came with that term, they just dropped the term itself. Now they talk about the behaviors needed to create state agents (state aggregation, subscription notification) without defining a formal name for the servers doing it. It's an editorial change to make life easier for package authors. The actual protocol does not change at all.
The definition of "State Agent" was removed from Section 2. Section 4.4.2 was retooled to talk about migration of subscriptions in general, without calling out state agents specifically. Section 5.4.11 now focuses on state aggregation by itself, rather than as an aspect of state agents.
B.27. Miscellaneous Changes 🌈
These are relatively minor revisions that came mostly from working group and IESG review, not from implementation reports. Here's the list:
- Clarified scope of "Event" header field parameters. In RFC 3265, the scope is ambiguous, which causes problems with the registry in RFC 3968. The new text ensures that "Event" header field parameters are unique across all event packages.
- Removed obsoleted language around IANA registration policies for event packages. Instead, we now cite RFC 5727, which updates RFC 3265, and is authoritative on event package registration policy.
- Several editorial updates after input from working group, including proper designation of "dialog usage" rather than "dialog" where needed.
- Clarified two normative statements about subscription termination by changing from plain English prose to RFC2119 language.
- Removed "Table 2" expansions, per WG consensus on how SIP Table 2 is to be handled.
- Removed 202 response code.
- Clarified that "Allow-Events" does not list event template-packages.
- Added clarification about proper response when the SUBSCRIBE indicates an unknown media type in its "Accept" header field.
- Minor clarifications to "Route" and "Record-Route" behavior.
- Added non-normative warning about the limitations of state polling.
- Added information about targeting subscriptions at specific dialogs.
- Added RFC 3261 to list of documents updated by this one (rather than the "2543" indicated by RFC 3265).
- Clarified text in Section 3.1.1 explaining the meaning of
Expires: 0. - Changed text in definition of "probation" reason code to indicate that subscribers don't need to re-subscribe if the associated state is no longer of use to them.
- Specified that the termination of a subscription due to a NOTIFY transaction failure does not require sending another NOTIFY message.
- Clarified how order of template application affects the meaning of an "Event" header field value (e.g., "foo.bar.baz" is different than "foo.baz.bar").
Author's Address 💌
Adam Roach
Tekelec
17210 Campbell Rd.
Suite 250
Dallas, TX 75252
US
EMail: adam@nostrum.com📦 where this page comes from
- ietf: rfc6665 2012-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms