Internet Engineering Task Force (IETF)                        A.B. Roach
Request for Comments: 6665                                       Tekelec
Obsoletes: 3265                                                July 2012
Updates: 3261, 4660
Category: Standards Track
ISSN: 2070-1721


                    SIP-Specific Event Notification

Abstract

   This document describes an extension to the Session Initiation
   Protocol (SIP) defined by RFC 3261.  The purpose of this extension is
   to provide an extensible framework by which SIP nodes can request
   notification from remote nodes indicating that certain events have
   occurred.

   Note that the event notification mechanisms defined herein are NOT
   intended to be a general-purpose infrastructure for all classes of
   event subscription and notification.

   This document represents a backwards-compatible improvement on the
   original mechanism described by RFC 3265, taking into account several
   years of implementation experience.  Accordingly, this document
   obsoletes RFC 3265.  This document also updates RFC 4660 slightly to
   accommodate some small changes to the mechanism that were discussed
   in that document.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc6665.

Copyright Notice

   Copyright (c) 2012 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

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  . . . . . . . . . . . . . . . . . . 52

1.  Introduction

   The ability to request asynchronous notification of events proves
   useful in many types of SIP services for which cooperation between
   end-nodes is required.  Examples of such services include automatic
   callback services (based on terminal state events), buddy lists
   (based on user presence events), message waiting indications (based
   on mailbox state change events), and PSTN and Internet
   Internetworking (PINT) [RFC2848] status (based on call state events).

   The methods described in this document provide a framework by which
   notification of these events can be ordered.

   The event notification mechanisms defined herein are NOT intended to
   be a general-purpose infrastructure for all classes of event
   subscription and notification.  Meeting requirements for the general
   problem set of subscription and notification is far too complex for a
   single protocol.  Our goal is to provide a SIP-specific framework for
   event notification that is not so complex as to be unusable for
   simple features, but that is still flexible enough to provide
   powerful services.  Note, however, that event packages based on this
   framework may define arbitrarily elaborate rules that govern the
   subscription and notification for the events or classes of events
   they describe.

   This document does not describe an extension that may be used
   directly; it must be extended by other documents (herein referred to
   as "event packages").  In object-oriented design terminology, it may
   be thought of as an abstract base class that must be derived into an
   instantiable class by further extensions.  Guidelines for creating
   these extensions are described in Section 5.

1.1.  Overview of Operation

   The general concept is that entities in the network can subscribe to
   resource or call state for various resources or calls in the network,
   and those entities (or entities acting on their behalf) can send
   notifications when those states change.

   A typical flow of messages would be:

   Subscriber          Notifier
       |-----SUBSCRIBE---->|     Request state subscription
       |<-------200--------|     Acknowledge subscription
       |<------NOTIFY----- |     Return current state information
       |--------200------->|
       |<------NOTIFY----- |     Return current state information
       |--------200------->|

   Subscriptions are expired and must be refreshed by subsequent
   SUBSCRIBE requests.

1.2.  Documentation Conventions

   There are several paragraphs throughout this document that provide
   motivational or clarifying text.  Such passages are non-normative and
   are provided only to assist with reader comprehension.  These
   passages are set off from the remainder of the text by being indented
   thus:

      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].

   In particular, implementors need to take careful note of the meaning
   of "SHOULD" defined in RFC 2119.  To rephrase: violation of "SHOULD"-
   strength requirements requires careful analysis and clearly
   enumerable reasons.  It is a protocol violation to fail to comply
   with "SHOULD"-strength requirements whimsically or for ease of
   implementation.

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 that are based on the framework defined by this document
      and are required to convey such state information.

   Event Template-Package:  An event template-package is a special kind
      of event package that 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 inform the subscriber of the state of a
      resource.

   Notifier:  A notifier is a user agent that generates NOTIFY requests
      for the purpose of notifying subscribers of 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; these NOTIFY requests contain information
      about the state of a resource in which the subscriber is
      interested.  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.  This 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 indicates the duration of the
   subscription.  In order to keep subscriptions effective beyond the
   duration communicated in the "Expires" header field, subscribers need
   to refresh subscriptions on a periodic basis using 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 specified in the request.  The
   notifier is explicitly allowed to shorten the duration to zero.  The
   period of time in the response is the one that defines the duration
   of the subscription.

   An "expires" parameter on the "Contact" header field has no semantics
   for the SUBSCRIBE method and is explicitly not equivalent to an
   "Expires" header field in a SUBSCRIBE request or response.

   A natural consequence of this scheme is that a SUBSCRIBE request with
   an "Expires" of 0 constitutes 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 wish to cancel subscriptions to events; this is
   useful, for example, when the resource to which a subscription refers
   is no longer available.  Further details on this mechanism are
   discussed in Section 4.2.2.

3.1.2.  Identification of Subscribed Events and Event Classes

   Identification of events is provided by three pieces of information:
   Request URI, Event Type, and (optionally) message body.

   The Request URI of a SUBSCRIBE request, most importantly, contains
   enough information to route the request to the appropriate entity per
   the request routing procedures outlined in [RFC3261].  It also
   contains enough information to identify the resource for which event
   notification is desired, but not necessarily enough information to
   uniquely identify the nature of the event (e.g.,
   "sip:adam@example.com" would be an appropriate URI to subscribe to
   for my presence state; it would also be an appropriate URI to
   subscribe to the state of my voice mailbox).

   Subscribers MUST include exactly one "Event" header field in
   SUBSCRIBE requests, indicating to which event or class of events they
   are subscribing.  The "Event" header field will contain a token that
   indicates the type of state for which a subscription is being
   requested.  This token will be registered with the IANA and will
   correspond to an event package that further describes the semantics
   of the event or event class.

   If the event package to which the event token corresponds defines
   behavior associated with the body of its SUBSCRIBE requests, those
   semantics apply.

   Event packages may also define parameters for the "Event" header
   field; if they do so, they must define the semantics for such
   parameters.

3.1.3.  Additional SUBSCRIBE Header Field Values

   Because SUBSCRIBE requests create a dialog usage as defined in
   [RFC3261], they MAY contain an "Accept" header field.  This header
   field, if present, indicates the body formats allowed in subsequent
   NOTIFY requests.  Event packages MUST define the behavior for
   SUBSCRIBE requests without "Accept" header fields; usually, this will
   connote 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 inform subscribers of changes in state to
   which the subscriber has a subscription.  Subscriptions are created
   using the SUBSCRIBE method.  In legacy implementations, it is
   possible that other means of subscription creation have been used.
   However, this specification does not allow the creation of
   subscriptions 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 may trigger several NOTIFY
   requests.

3.2.1.  Identification of Reported Events, Event Classes, and Current
        State

   Identification of events being reported in a notification is very
   similar to that described for subscription to events (see
   Section 3.1.2).

   As in SUBSCRIBE requests, NOTIFY request "Event" header fields 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.

   Event packages may define semantics associated with the body of their
   NOTIFY requests; if they do so, those semantics apply.  NOTIFY
   request bodies are expected to provide additional details about the
   nature of the event that has occurred and the resultant resource
   state.

   When 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 (or the default type according to the
   event package description, if no "Accept" header field was
   specified).  This body will contain either the state of the
   subscribed resource or a pointer to such state in the form of a URI
   (see Section 5.4.13).