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.

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.

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.

   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.

   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.

5.4.  Event Package Responsibilities

   Event packages are not required to reiterate any of the behavior
   described in this document, although they may choose to do so for
   clarity or emphasis.  In general, though, such packages are expected
   to describe only the behavior that extends or modifies the behavior
   described in this document.

   Note that any behavior designated with "SHOULD" or "MUST" in this
   document is not allowed to be weakened by extension documents;
   however, such documents may elect to strengthen "SHOULD" requirements
   to "MUST" requirements if required by their application.

   In addition to the normal sections expected in Standards Track RFCs
   and SIP extension documents, authors of event packages need to
   address each of the issues detailed in the following subsections.
   For clarity: well-formed event package definitions contain sections
   addressing each of these issues, ideally in the same order and with
   the same titles as these subsections.

5.4.1.  Event Package Name

   This section, which MUST be present, defines the token name to be
   used to designate the event package.  It MUST include the information
   that appears in the IANA registration of the token.  For information
   on registering such types, see Section 7.

5.4.2.  Event Package Parameters

   If parameters are to be used on the "Event" header field to modify
   the behavior of the event package, the syntax and semantics of such
   header fields MUST be clearly defined.

   Any "Event" header field parameters defined by an event package 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
   specifications MAY define "Event" header field parameters that apply
   across all event packages (with emphasis on "all", as opposed to
   "several"), such as the "id" parameter defined in this document.  The
   restriction of a parameter to use with a single event package only
   applies to parameters that are defined in conjunction with an event
   package.

5.4.3.  SUBSCRIBE Request Bodies

   It is expected that most, but not all, event packages will define
   syntax and semantics for SUBSCRIBE request bodies; these bodies will
   typically modify, expand, filter, throttle, and/or set thresholds for
   the class of events being requested.  Designers of event packages are
   strongly encouraged to reuse existing media types for message bodies
   where practical.  See [RFC4288] for information on media type
   specification and registration.

   This mandatory section of an event package defines what type or types
   of event bodies are expected in SUBSCRIBE requests (or specify 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 used to report state on the resource being
   monitored.  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
   associated with such event bodies.

   Event packages also MUST define which media type is to be 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 the processing to be performed by the notifier
   upon receipt of a SUBSCRIBE request.  Such a section is required.

   Information in this section includes details of how to authenticate
   subscribers and authorization issues for the package.

5.4.7.  Notifier generation of NOTIFY requests

   This section of an event package describes the process by which the
   notifier generates and sends a NOTIFY request.  This includes
   detailed information about what events cause a NOTIFY request to be
   sent, how to compute the state information in the NOTIFY, how to
   generate neutral or fake state information to hide authorization
   delays and decisions from users, and whether state information 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 of an event package describes the process followed by
   the subscriber upon receipt of a NOTIFY request, including any logic
   required 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 such behavior is not allowed, the first potential dialog-
   establishing message will create a dialog.  All subsequent NOTIFY
   requests that correspond to the SUBSCRIBE request (i.e., have

   matching "To", "From", "Call-ID", and "Event" header fields, as well
   as "From" header field "tag" parameter and "Event" header field "id"
   parameter) but that do not match the dialog would be rejected with a
   481 response.  Note that the 200-class response to the SUBSCRIBE
   request can arrive after a matching NOTIFY request has been received;
   such responses might not correlate to the same dialog established by
   the NOTIFY request.  Except as required to complete the SUBSCRIBE
   transaction, such non-matching 200-class responses are ignored.

   If installing of multiple subscriptions by way of a single forked
   SUBSCRIBE request is allowed, the subscriber establishes a new dialog
   towards each notifier by returning a 200-class response to each
   NOTIFY request.  Each dialog is then handled as its own entity and is
   refreshed independently of the other dialogs.

   In the case that multiple subscriptions are allowed, the event
   package MUST specify whether merging of the notifications to form a
   single state is required, and how such merging is to be performed.
   Note that it is possible that some event packages may be defined in
   such a way that each dialog is tied to a mutually exclusive state
   that is unaffected by the other dialogs; this MUST be clearly stated
   if it is the case.

5.4.10.  Rate of Notifications

   Each event package is expected to define a requirement ("SHOULD" or
   "MUST" strength) that defines an absolute maximum on the rate at
   which notifications are allowed to be generated by a single notifier.

   Each package MAY further define a throttle mechanism that allows
   subscribers to further limit the rate of notification.

5.4.11.  State Aggregation

   Many event packages inherently work by collecting information about a
   resource from a number of other sources -- either through the use of
   PUBLISH [RFC3903], by subscribing to state information, or through
   other state-gathering mechanisms.

   Event packages that involve retrieval of state information for a
   single resource from more than one source need to consider how
   notifiers aggregate information into a single, 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
   indicate that such examples are informative and not normative, with
   instructions that implementors refer to the main text of the document
   for exact protocol details.

5.4.13.  Use of URIs to Retrieve State

   Some types of event packages may define state information that is
   potentially too large to reasonably send in a SIP message.  To
   alleviate this problem, event packages may include the ability to
   convey a URI instead of state information; this URI will then be used
   to retrieve the actual state information.

   [RFC4483] defines a mechanism that can be used by event packages to
   convey information in such a fashion.

6.  Security Considerations

6.1.  Access Control

   The ability to accept subscriptions should be under the direct
   control of the notifier's user, since many types of events may be
   considered private.  Similarly, the notifier should have the ability
   to selectively reject subscriptions based on the subscriber identity
   (based on access control lists), using standard SIP authentication
   mechanisms.  The methods for creation and distribution of such access
   control lists are 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 information.  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 point of view
   of the subscriber, indistinguishable from a valid response.
   Information 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 documents for which such a mode
   of operation makes sense can further describe how and why to generate
   such potentially correct data.  For example, such a mode of operation
   is mandated by [RFC2779] 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, the creation of state upon receipt of a SUBSCRIBE request can
   be used by attackers to consume resources on a victim's machine,
   rendering it unusable.

   To reduce the chances of such an attack, implementations of notifiers
   SHOULD require authentication.  Authentication issues are discussed
   in [RFC3261].

6.4.  Replay Attacks

   Replaying of either SUBSCRIBE or NOTIFY requests can have detrimental
   effects.

   In the case of SUBSCRIBE requests, an attacker may be able to install
   any arbitrary subscription that it witnessed being installed at some
   point in the past.  Replaying of 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 such an attack).  Note
   that the prohibition on sending NOTIFY requests to nodes that have
   not subscribed to an event also aids in mitigating 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

   Even with authentication, man-in-the-middle attacks using SUBSCRIBE
   requests may be used to install arbitrary subscriptions, hijack
   existing subscriptions, terminate outstanding subscriptions, or
   modify the resource to which a subscription is being made.  To
   prevent such attacks, implementations SHOULD provide integrity
   protection across "Contact", "Route", "Expires", "Event", and "To"
   header fields (at a minimum) of SUBSCRIBE requests.  If SUBSCRIBE

   request bodies are used to define further information about the state
   of the call, they SHOULD be included in the integrity protection
   scheme.

   Man-in-the-middle attacks may also attempt to use NOTIFY requests to
   spoof arbitrary state information and/or terminate outstanding
   subscriptions.  To prevent such attacks, implementations SHOULD
   provide integrity protection across the "Call-ID", "CSeq", and
   "Subscription-State" header fields and the bodies of NOTIFY requests.

   Integrity protection of message header fields and bodies is discussed
   in [RFC3261].

6.6.  Confidentiality

   The state information contained in a NOTIFY request has the potential
   to contain sensitive information.  Implementations MAY encrypt such
   information to ensure confidentiality.

   While less likely, it is also possible that the information contained
   in a SUBSCRIBE request contains information that users might not want
   to have revealed.  Implementations MAY encrypt such information to
   ensure confidentiality.

   To allow the remote party to hide information 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

   With the exception of Section 7.2, the subsections here are for
   current reference, carried over from the original specification (RFC
   3265).  IANA has updated all registry references that pointed to RFC
   3265 to instead indicate this document and created the new "reason
   code" registry described in Section 7.2.

7.1.  Event Packages

   This document defines an event-type namespace that requires a central
   coordinating body.  The body chosen for this coordination is the
   Internet Assigned Numbers Authority (IANA).

   There are two different 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; in
   other words, an event template-package is forbidden from sharing a
   name with a package.

   Policies for registration of SIP event packages and SIP event package
   templates are defined in Section 4.1 of [RFC5727].

   Registrations with the IANA are required to include the token being
   registered and whether the token is a package or a template-package.
   Further, packages must include contact information for the party
   responsible for the registration and/or a published document that
   describes the event package.  Event template-package token
   registrations are also required to include a pointer to the published
   RFC that defines the event template-package.

   Registered tokens to designate packages and template-packages are
   disallowed from containing the character ".", which is used to
   separate template-packages from packages.

7.1.1.  Registration Information

   This document specifies no package or template-package names.  All
   entries in this table are added by other documents.  The remainder of
   the text in this section gives an example of the type of information
   to be maintained by the IANA; it also demonstrates all four possible
   permutations 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 designated 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 further defines "reason" codes for use in the
   "Subscription-State" header field (see Section 4.1.3).

   Following the policies outlined in "Guidelines for Writing an IANA
   Considerations Section in RFCs" [RFC5226], new reason codes require a
   Standards Action.

   Registrations with the IANA include the reason code being registered
   and a reference to a published document that describes the event
   package.  Insertion of such values takes place as part of the RFC
   publication process or as the result of liaison activity between
   standards development organizations (SDOs), the result of which will
   be publication of an associated RFC.  New reason codes must conform
   to the syntax of the ABNF "token" element defined in [RFC3261].

   [RFC4660] defined a new reason code prior to the establishment of an
   IANA registry.  We include its reason code ("badfilter") in the
   initial list of reason codes to ensure a complete registry.

   The IANA registry for reason codes has been initialized with the
   following 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, described
   elsewhere in this document.  These header fields are defined by the
   following information, which is to be 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:  o

7.4.  Response Codes

   This document registers two new response codes.  These response codes
   are defined by the following information, which is to be 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 Event