Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 6665

SIP-Specific Event Notification

Pages: 53
Proposed Standard
Obsoletes:  3265
Updates:  32614660
Updated by:  7621
Part 4 of 4 – Pages 42 to 53
First   Prev   None

Top   ToC   RFC6665 - Page 42   prevText

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].
Top   ToC   RFC6665 - Page 43
      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.
Top   ToC   RFC6665 - Page 44
   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 = %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.
Top   ToC   RFC6665 - Page 45
   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.
Top   ToC   RFC6665 - Page 46
   [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.
Top   ToC   RFC6665 - Page 47
   [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>.
Top   ToC   RFC6665 - Page 48

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.
Top   ToC   RFC6665 - Page 49

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 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.
Top   ToC   RFC6665 - Page 50

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 4.2.1.1 and 4.2.1.4, 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.
Top   ToC   RFC6665 - Page 51

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
Top   ToC   RFC6665 - Page 52
   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.
Top   ToC   RFC6665 - Page 53
   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: adam@nostrum.com