8. Syntax This section describes the syntax extensions required for event notification in SIP. Semantics are described in Section 4. Note that the formal syntax definitions described in this document are expressed in the ABNF format used in [RFC3261] and contain references to elements defined therein. 8.1. New Methods This document describes two new SIP methods: SUBSCRIBE and NOTIFY. 8.1.1. SUBSCRIBE Method "SUBSCRIBE" is 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" is added to the definition of the element "Method" in the SIP message grammar. The NOTIFY method is used to notify a SIP node that an event that has been requested by an earlier SUBSCRIBE method has occurred. It may also provide further details about the event. 8.2. New Header Fields 8.2.1. "Event" Header Field Event is added to the definition of the element "message-header field" in the SIP message grammar. For the purposes of matching NOTIFY requests with SUBSCRIBE requests, the event-type portion of the "Event" header field is compared byte by byte, and the "id" parameter token (if present) is compared byte by byte. An "Event" header field containing an "id" parameter never matches an "Event" header field without an "id" parameter. No other parameters are considered when performing a comparison. SUBSCRIBE responses are matched per the transaction handling rules in [RFC3261].
Note that the foregoing text means that "Event: foo; id=1234" would match "Event: foo; param=abcd; id=1234", but not "Event: foo" ("id" does not match) or "Event: Foo; id=1234" ("Event" portion does not match). This document does not define values for event-types. These values will be defined by individual event packages and MUST be registered with the IANA. There MUST be exactly one event type listed per "Event" header field. Multiple events per message are disallowed. The "Event" header field is defined only for use in SUBSCRIBE and NOTIFY requests and other requests whose definition explicitly calls for its use. It MUST NOT appear in any other SIP requests and MUST NOT appear in responses. 8.2.2. "Allow-Events" Header Field "Allow-Events" is 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 comply with the behavior described in Section 4.4.4. 8.2.3. "Subscription-State" Header Field "Subscription-State" is 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 For historical purposes, the 202 (Accepted) response code is added to the "Success" header field definition. This document does not specify the use of the 202 response code in conjunction with the SUBSCRIBE or NOTIFY methods. Previous versions of the SIP Events Framework assigned specific meaning to the 202 response code.
Due to response handling in forking cases, any 202 response to a SUBSCRIBE request may be absorbed by a proxy, and thus it can never be guaranteed to be received by the UAC. Furthermore, there is no actual processing difference for a 202 as compared to a 200; a NOTIFY request is sent after the subscription is processed, and it conveys the correct state. SIP interoperability tests found that implementations were handling 202 differently from 200, leading to incompatibilities. Therefore, the 202 response is being deprecated to make it clear there is no such difference and 202 should not be handled differently than 200. Implementations conformant with the current specification MUST treat an incoming 202 response as identical to a 200 response and MUST NOT generate 202 response codes to SUBSCRIBE or NOTIFY requests. This document also updates [RFC4660], which reiterates the 202-based behavior in several places. Implementations compliant with the present document MUST NOT send a 202 response to a SUBSCRIBE request and will send an alternate success response (such as 200) in its stead. 8.3.2. 489 (Bad Event) Response Code The 489 event response is added to the "Client-Error" header field definition. 489 (Bad Event) is used to indicate that the server did not understand the event package specified in a "Event" header field. 8.4. Augmented BNF Definitions The Augmented BNF [RFC5234] definitions for the various new and modified syntax elements follows. The notation is as used in [RFC3261], and any elements not defined in this section are as defined in SIP and the documents to which it refers. SUBSCRIBEm = %x22.214.171.124.126.96.36.199.45 ; SUBSCRIBE in caps NOTIFYm = %x4E.4F.188.8.131.52 ; 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 = token 9. 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 Thanks to the participants in the Events BOF at the 48th IETF meeting in Pittsburgh, as well as those who gave ideas and suggestions on the SIP Events mailing list. In particular, I wish to thank 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. I also owe a debt of gratitude to all the implementors who have provided feedback on areas of confusion or difficulty in the original specification. In particular, Robert Sparks' Herculean efforts organizing, running, and collecting data from the SIPit events have proven invaluable in 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 represents several changes from the mechanism originally described in RFC 3265. This section summarizes those changes. 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 sentence to Section 3.1.1 explicitly allowing shortening to zero.
B.4. Bug 670: Dialog State Machine needs clarification The issues associated with the bug deal exclusively with the handling of multiple usages with a dialog. This 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 184.108.40.206. Added state machine to Section 4.2.2 to reinforce text. B.11. Bug 697: Unsubscription behavior could be clarified Added text to Section 220.127.116.11 encouraging (but not requiring) full state in final NOTIFY request. Also added text to Section 18.104.22.168 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 Added text to both Sections 3.1 and 3.2 explicitly indicating that SUBSCRIBE and NOTIFY are target refresh methods. B.13. Bug 722: Inconsistent 423 reason phrase text Changed reason phrase to "Interval Too Brief" in Sections 22.214.171.124 and 126.96.36.199, to match 423 reason phrase in SIP [RFC3261]. B.14. Bug 741: Guidance needed on when to not include "Allow-Events" Added non-normative clarification to Section 4.4.4 regarding inclusion of "Allow-Events" in a NOTIFY for the one-and-only package supported by the notifier. B.15. Bug 744: 5xx to NOTIFY terminates a subscription, but should not Issue of subscription (usage) termination versus dialog termination is handled in [RFC5057]. The text in Section 4.2.2 has been updated to summarize the behavior described by RFC 5057, and cites it for additional detail and rationale. B.16. Bug 752: Detection of forked requests is incorrect Removed erroneous "CSeq" from list of matching criteria in Section 5.4.9. B.17. Bug 773: Reason code needs IANA registry Added Section 7.2 to create and populate IANA registry. B.18. Bug 774: Need new reason for terminating subscriptions to resources that never change Added new "invariant" reason code to Section 4.1.3 and to ABNF syntax in Section 8.4. B.19. Clarify Handling of "Route"/"Record-Route" in NOTIFY Changed text in Section 4.3 in order to mandate "Record-Route" in initial SUBSCRIBE and all NOTIFY requests, and add "MAY"-level statements for subsequent SUBSCRIBE requests.
B.20. Eliminate Implicit Subscriptions Added text to Section 4.2.1 explaining some of the problems associated with implicit subscriptions, and added normative language prohibiting them. Removed language from Section 3.2 describing "non- SUBSCRIBE" mechanisms for creating subscriptions. Simplified language in Section 4.2.2, now that the soft-state/non-soft-state distinction is unnecessary. B.21. Deprecate Dialog Reuse Moved handling of dialog reuse and "id" handling to Section 4.5.2. It is documented only for backwards-compatibility purposes. B.22. Rationalize Dialog Creation Section 4.4.1 has been updated to specify that dialogs should be created when the NOTIFY arrives. Previously, the dialog was established by the SUBSCRIBE 200 or by the NOTIFY transaction. This was unnecessarily complicated; the newer rules are easier to implement (and result in effectively the same behavior on the wire). B.23. Refactor Behavior Sections Reorganized Section 4 to consolidate behavior along role lines (subscriber/notifier/proxy) instead of method lines. B.24. Clarify Sections That Need to Be Present in Event Packages Added sentence to Section 5 clarifying that event packages are expected to include explicit sections covering the issues discussed in this section. B.25. Make CANCEL Handling More Explicit Text in Section 4.6 now clearly calls out behavior upon receipt of a CANCEL. We also echo the "...SHOULD NOT send..." requirement from [RFC3261]. B.26. Remove "State Agent" Terminology As originally planned, we anticipated a fairly large number of event packages that would move back and forth between end-user devices and servers in the network. In practice, this has ended up not being the case. Certain events, like dialog state, are inherently hosted at end-user devices; others, like presence, are almost always hosted in the network (due to issues like composition, and the ability to deliver information when user devices are offline). Further, the
concept of State Agents is the most misunderstood by event package authors. In my expert review of event packages, I have yet to find one that got the concept of State Agents completely correct -- and most of them start out with the concept being 100% backwards from the way RFC 3265 described it. Rather than remove the ability to perform the actions previously attributed to the widely misunderstood term "State Agent", we have simply eliminated this term. Instead, we talk about the behaviors required to create state agents (state aggregation, subscription notification) without defining a formal term to describe the servers that exhibit these behaviors. In effect, this is an editorial change to make life easier for event package authors; the actual protocol does not change as a result. The definition of "State Agent" has been removed from Section 2. Section 4.4.2 has been retooled to discuss migration of subscription in general, without calling out the specific example of state agents. Section 5.4.11 has been focused on state aggregation in particular, instead of state aggregation as an aspect of state agents. B.27. Miscellaneous Changes The following changes are relatively minor revisions to the document that resulted primarily from review of this document in the working group and IESG, rather than implementation reports. o 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. o 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. o Several editorial updates after input from working group, including proper designation of "dialog usage" rather than "dialog" where needed. o Clarified two normative statements about subscription termination by changing from plain English prose to RFC2119 language. o Removed "Table 2" expansions, per WG consensus on how SIP Table 2 is to be handled. o Removed 202 response code.
o Clarified that "Allow-Events" does not list event template- packages. o Added clarification about proper response when the SUBSCRIBE indicates an unknown media type in its "Accept" header field. o Minor clarifications to "Route" and "Record-Route" behavior. o Added non-normative warning about the limitations of state polling. o Added information about targeting subscriptions at specific dialogs. o Added RFC 3261 to list of documents updated by this one (rather than the "2543" indicated by RFC 3265). o Clarified text in Section 3.1.1 explaining the meaning of "Expires: 0". o 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. o Specified that the termination of a subscription due to a NOTIFY transaction failure does not require sending another NOTIFY message. o 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: email@example.com