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:firstname.lastname@example.org 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 <email@example.com> REFERENCES ---------- [RFCnnnn] Doe, J., "Sample Document", RFC nnnn, Month YYYY.
7.1.2. Registration Template To: firstname.lastname@example.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