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        = %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 = 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 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

   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.

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: adam@nostrum.com