summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc5839.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc5839.txt')
-rw-r--r--doc/rfc/rfc5839.txt1403
1 files changed, 1403 insertions, 0 deletions
diff --git a/doc/rfc/rfc5839.txt b/doc/rfc/rfc5839.txt
new file mode 100644
index 0000000..39be6f8
--- /dev/null
+++ b/doc/rfc/rfc5839.txt
@@ -0,0 +1,1403 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) A. Niemi
+Request for Comments: 5839 Nokia
+Category: Standards Track D. Willis, Ed.
+ISSN: 2070-1721 Softarmor Systems
+ May 2010
+
+
+ An Extension to Session Initiation Protocol (SIP) Events
+ for Conditional Event Notification
+
+Abstract
+
+ The Session Initiation Protocol (SIP) events framework enables
+ receiving asynchronous notification of various events from other SIP
+ user agents. This framework defines the procedures for creating,
+ refreshing, and terminating subscriptions, as well as fetching and
+ periodic polling of resource state. These procedures provide no
+ tools to avoid replaying event notifications that have already been
+ received by a user agent. This memo defines an extension to SIP
+ events that allows the subscriber to condition the subscription
+ request to whether the state has changed since the previous
+ notification was received. When such a condition is true, either the
+ body of a resulting event notification or the entire notification
+ message is suppressed.
+
+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/rfc5839.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 1]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+Copyright Notice
+
+ Copyright (c) 2010 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.
+
+ This document may contain material from IETF Documents or IETF
+ Contributions published or made publicly available before November
+ 10, 2008. The person(s) controlling the copyright in some of this
+ material may not have granted the IETF Trust the right to allow
+ modifications of such material outside the IETF Standards Process.
+ Without obtaining an adequate license from the person(s) controlling
+ the copyright in such materials, this document may not be modified
+ outside the IETF Standards Process, and derivative works of it may
+ not be created outside the IETF Standards Process, except to format
+ it for publication as an RFC or to translate it into languages other
+ than English.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 2]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 1.1. Document Conventions . . . . . . . . . . . . . . . . . . . 5
+ 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
+ 2. Motivations and Background . . . . . . . . . . . . . . . . . . 5
+ 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 2.2. Problem Description . . . . . . . . . . . . . . . . . . . 5
+ 2.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6
+ 3. Overview of Operation . . . . . . . . . . . . . . . . . . . . 7
+ 4. Resource Model for Entity-Tags . . . . . . . . . . . . . . . . 10
+ 5. Subscriber Behavior . . . . . . . . . . . . . . . . . . . . . 12
+ 5.1. Detecting Support for Conditional Notification . . . . . . 13
+ 5.2. Generating SUBSCRIBE Requests . . . . . . . . . . . . . . 13
+ 5.3. Receiving NOTIFY Requests . . . . . . . . . . . . . . . . 14
+ 5.4. Polling or Fetching Resource State . . . . . . . . . . . . 15
+ 5.5. Resuming a Subscription . . . . . . . . . . . . . . . . . 17
+ 5.6. Refreshing a Subscription . . . . . . . . . . . . . . . . 18
+ 5.7. Terminating a Subscription . . . . . . . . . . . . . . . . 18
+ 5.8. Handling Transient Errors . . . . . . . . . . . . . . . . 19
+ 6. Notifier Behavior . . . . . . . . . . . . . . . . . . . . . . 20
+ 6.1. Generating Entity-tags . . . . . . . . . . . . . . . . . . 20
+ 6.2. Suppressing NOTIFY Bodies . . . . . . . . . . . . . . . . 20
+ 6.3. Suppressing NOTIFY Requests . . . . . . . . . . . . . . . 21
+ 6.4. State Differentials . . . . . . . . . . . . . . . . . . . 21
+ 6.5. List Subscriptions . . . . . . . . . . . . . . . . . . . . 22
+ 7. Protocol Element Definitions . . . . . . . . . . . . . . . . . 22
+ 7.1. 204 (No Notification) Response Code . . . . . . . . . . . 22
+ 7.2. Suppress-If-Match Header Field . . . . . . . . . . . . . . 22
+ 7.3. Grammar . . . . . . . . . . . . . . . . . . . . . . . . . 22
+ 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
+ 8.1. 204 (No Notification) Response Code . . . . . . . . . . . 23
+ 8.2. Suppress-If-Match Header Field . . . . . . . . . . . . . . 23
+ 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24
+ 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
+ 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24
+ 11.1. Normative References . . . . . . . . . . . . . . . . . . . 24
+ 11.2. Informative References . . . . . . . . . . . . . . . . . . 24
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 3]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+1. Introduction
+
+ The Session Initiation Protocol (SIP) events framework provides an
+ extensible facility for requesting notification of certain events
+ from other SIP user agents. This framework includes procedures for
+ creating, refreshing, and terminating subscriptions, as well as the
+ possibility to fetch or periodically poll the event resource.
+
+ Several instantiations of this framework, called event packages have
+ been defined, e.g., for presence [RFC3856], message waiting
+ indications [RFC3842], and registrations [RFC3680].
+
+ By default, every SUBSCRIBE request generates a NOTIFY request
+ containing the latest event state. Typically, a SUBSCRIBE request is
+ issued by the subscriber whenever it needs a subscription to be
+ installed, periodically refreshed, or terminated. Once the
+ subscription has been installed, the majority of the NOTIFYs
+ generated by the subscription refreshes are superfluous; the
+ subscriber usually is in possession of the event state already,
+ except in the unlikely case where a state change exactly coincides
+ with the periodic subscription refresh. In most cases, the final
+ event state generated upon terminating the subscription similarly
+ contains resource state that the subscriber already has.
+
+ Fetching or polling of resource state behaves in a similarly
+ suboptimal way in cases where the state has not changed since the
+ previous poll occurred. In general, the problem lies with the
+ inability to persist state across a SUBSCRIBE request.
+
+ This memo defines an extension to optimize the SIP events framework.
+ This extension allows a notifier to tag notifications (called entity-
+ tags hereafter) and the subscriber to condition its subsequent
+ SUBSCRIBE requests for actual changes since a notification carrying
+ that entity-tag was issued. The solution is similar to conditional
+ requests defined in the Hypertext Transfer Protocol (HTTP) [RFC2616],
+ and follows the mechanism already defined for the PUBLISH [RFC3903]
+ method for issuing conditional event publications.
+
+ This memo is structured as follows. Section 2 explains the
+ background, motivations, and requirements for the work; Section 3
+ gives a general overview of the mechanism; Section 4 explains the
+ underlying model for resources and entities as they apply to
+ conditional notification; Section 5 defines the subscriber behavior;
+ Section 6 defines the notifier behavior; Section 7 includes the
+ protocol element definitions; Section 8 includes the IANA
+ considerations; and Section 9 includes the security considerations.
+
+
+
+
+
+Niemi & Willis Standards Track [Page 4]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+1.1. Document Conventions
+
+ 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 BCP 14, RFC 2119
+ [RFC2119] and indicate requirement levels for compliant
+ implementations.
+
+1.2. Terminology
+
+ In addition to the terminology introduced in [RFC3261], [RFC3265],
+ and [RFC3903], this specification uses these additional terms to
+ describe the objects of conditional notification:
+
+ resource
+ An object identified by a URI whose resource state can be accessed
+ using the SIP Event Notification framework. There is a single
+ authoritative notifier responsible for communicating the resource
+ state.
+
+ entity
+ The representation of resource state. An entity consists of the
+ state data carried in the body of a NOTIFY message, as well as
+ related meta-data in the message header. There may be many
+ versions of an entity, one current and the others stale. Each
+ version of an entity is identified by an entity-tag, which is
+ guaranteed to be unique across all versions of all entities for a
+ resource and event package.
+
+2. Motivations and Background
+
+2.1. Overview
+
+ A SUBSCRIBE request creates a subscription with a finite lifetime.
+ This lifetime is negotiated using the Expires header field, and
+ unless the subscription is refreshed by the subscriber before the
+ expiration is met, the subscription is terminated. The frequency of
+ these subscription refreshes depends on the event package, and
+ typically ranges from minutes to hours.
+
+2.2. Problem Description
+
+ The SIP events framework does not include different protocol methods
+ for initiating and terminating of subscriptions, subscription
+ refreshes, and fetches inside and outside of the SIP dialog. The
+ SUBSCRIBE method is overloaded to perform all of these functions.
+ The difference between a fetch that does not create a (lasting)
+ subscription and a SUBSCRIBE that creates one is in the Expires
+
+
+
+Niemi & Willis Standards Track [Page 5]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ header field value of the SUBSCRIBE; a zero-expiry SUBSCRIBE only
+ generates a single NOTIFY, after which the subscription immediately
+ terminates. Lasting subscriptions typically have relatively short
+ expiry periods, requiring periodic sending of new SUBSCRIBE requests
+ in order to refresh the subscription.
+
+ Each new SUBSCRIBE request generates a NOTIFY request containing the
+ latest resource state. Even if the state has not changed, it is sent
+ again in response to each poll or subscription refresh. This is very
+ similar to the HTTP [RFC2616] problem of repeated GET operations on a
+ resource. HTTP solves the problem using conditional requests. The
+ server versions each entity with an entity-tag that identifies a
+ specific instance of that entity. Clients making GET requests can
+ then include the entity-tag for the version of the entity that they
+ believe to be current in an "If-None-Match" header field. The server
+ can compare this entity-tag to the entity it believes to be current
+ and suppress resending the entity in the response if the server
+ believes the client's version matches. In other words, the server
+ doesn't resend information that the client has already received.
+
+ The SIP PUBLISH [RFC3903] method uses a similar mechanism, where a
+ refresh of a publication is done by reference to its assigned entity-
+ tag, instead of retransmitting the event state each time the
+ publication expiration is extended.
+
+2.3. Requirements
+
+ As a summary, here is the required functionality to solve the
+ presented issues:
+
+ REQ1: It must be possible to suppress the NOTIFY request (or at a
+ minimum, the event body therein) if the subscriber is already
+ in possession of (or has previously received and discarded)
+ the latest event state of the resource.
+
+ REQ2: This mechanism must apply to initial subscriptions in which
+ the subscriber is attempting to resume an earlier
+ subscription that has been paused.
+
+ REQ3: This mechanism must apply to refreshing a subscription.
+
+ REQ4: This mechanism must apply to terminating a subscription
+ (i.e., an unsubscribe).
+
+ REQ5: This mechanism must apply to fetching or polling of resource
+ state.
+
+
+
+
+
+Niemi & Willis Standards Track [Page 6]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+3. Overview of Operation
+
+ Whenever a subscriber initiates a subscription, it issues a SUBSCRIBE
+ request. The SUBSCRIBE request is sent, routed, and processed by the
+ notifier normally, i.e., according to the Session Initiation Protocol
+ [RFC3261] and SIP-Specific Event Notification [RFC3265].
+
+ If the notifier receiving the SUBSCRIBE request supports conditional
+ subscriptions, it generates an entity-tag for the current entity, and
+ includes it in a SIP-ETag header field of the NOTIFY request. The
+ entity-tag is unique across all versions of all entities for a
+ resource and event package. See Section 4 for more on this.
+
+ Entity-tags are independent of subscriptions. This allows
+ notifications generated to a fetch or a poll to have valid entity-
+ tags even across subsequent fetches or polls.
+
+ The subscriber will store the entity-tag received in the notification
+ along with the resource state. It can then later use this entity-tag
+ to make a SUBSCRIBE contain a condition in the form of a "Suppress-
+ If-Match" header field. Unlike the "If-Match" condition in a PUBLISH
+ [RFC3903] request, which applies to whether the PUBLISH succeeds or
+ returns an error, this condition applies to the stream of
+ notifications that are sent after the SUBSCRIBE request has been
+ processed.
+
+ The Suppress-If-Match header field contains the last entity-tag seen
+ by the subscriber. This condition, if true, instructs the notifier
+ to suppress either the body of a subsequent notification, or the
+ entire notification.
+
+ The condition is evaluated by matching the value of the header field
+ against the entity-tag of the entity that would normally be sent in
+ the associated NOTIFY message. There is also a wildcard entity-tag
+ with a special value of "*" that always matches.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 7]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ Subscriber Notifier
+ ---------- --------
+
+ (1) SUBSCRIBE -------->
+ Expires: 3600
+ <-------- (2) 200 (or 202)
+
+ <-------- (3) NOTIFY
+ Subscription-State: active
+ SIP-ETag: ffee2
+ (4) 200 -------->
+
+ ... time passes ...
+
+ (5) SUBSCRIBE --------> \ if "ffee2"
+ Suppress-If-Match: ffee2 | matches
+ Expires: 3600 | local
+ | entity-tag
+ |
+ <-------- (6) 204 / then
+
+ ... time passes and resource state (entity) changes...
+
+
+ <-------- (7) NOTIFY
+ Subscription-State: active
+ SIP-ETag: ca89a
+ (8) 200 -------->
+
+
+ ... time passes ...
+
+
+ (9) SUBSCRIBE --------> \ if "ca89"
+ Suppress-If-Match: ca89a | matches
+ Expires: 0 | local
+ | entity-tag
+ |
+ <-------- (10) 204 / then
+
+ Figure 1: Example Message Flow
+
+ Figure 1 describes a typical message flow for conditional
+ notification:
+
+ (1) The subscriber initiates a subscription by sending a SUBSCRIBE
+ request for a resource.
+
+
+
+
+Niemi & Willis Standards Track [Page 8]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ (2) After proper authentication and authorization, the notifier
+ accepts the subscription.
+
+ (3) The notifier then immediately sends the initial event
+ notification, including a unique entity-tag in a SIP-ETag
+ header field.
+
+ (4) The subscriber accepts the notification and stores the entity-
+ tag value along with the resource state.
+
+ (5) Later, the subscriber refreshes the subscription, and includes
+ an entity-tag in a Suppress-If-Match header field.
+
+ (6) The notifier evaluates the condition by matching its local
+ entity-tag value for the resource against the value of the
+ Suppress-If-Match header field. If the condition evaluates to
+ true, the notifier informs the subscriber that the notification
+ will not be sent.
+
+ (7) At some point, the state of the resource changes, e.g., the
+ presence status of a user changes from online to busy. This
+ triggers an event notification with a new value in the SIP-ETag
+ header field.
+
+ (8) The subscriber accepts the notification and stores the new
+ entity-tag along with the resource state.
+
+ (9) After a while, the subscriber decides to terminate the
+ subscription. It adds a condition for Suppress-If-Match, and
+ includes the entity-tag it received in the previous NOTIFY.
+
+ (10) The notifier evaluates the condition by matching its entity-tag
+ for the resource against the value of the Suppress-If-Match
+ header field. If the condition evaluates to true, the notifier
+ informs the subscriber that no notification will be sent. This
+ concludes the subscription.
+
+ The benefit of using conditional notification in this example is in
+ the reduction of the number of NOTIFY requests the subscriber can
+ expect to receive. Each event notification that the subscriber has
+ already seen is suppressed by the notifier. This example illustrates
+ only one use case for the mechanism; the same principles can be used
+ to optimize the flow of messages related to other event notification
+ use cases.
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 9]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+4. Resource Model for Entity-Tags
+
+ The key to understanding how conditional notification works is
+ understanding the underlying resource model of event notification.
+ In general, this model is similar to the resource model of HTTP with
+ some key differences. This section explains in detail the model as
+ it applies to SIP events. Figure 2 illustrates the model.
+
+ +-----+
+ ............ | |
+ . . | URI |
+ . Represen . | |
+ . tation . +-----+
+ . . |*
+ ............ |
+ . |
+ . V
+ . +----------+ +---------+
+ composition | |* | Event |
+ +------<>| Resource |----------->| Package |<----.
+ | | | | | |
+ | +----------+ +----.----+ |
+ | /_\ |
+ |* | classification
+ +--------+ | |
+ | | .----------------.------' |
+ | Entity | | | |
+ | | | | |*
+ +--------+ +----------+ +------------+ +----------+
+ ^ | | | | | |
+ | | Presence | | Conference | | Template |
+ | | | | | | |
+ |1..* +----------+ +------------+ +----.-----+
+ +---------+ /_\
+ | | |
+ | Version | |
+ | | +---------+
+ +---------+ | Watcher |
+ |1 | Info |
+ | | |
+ V +---------+
+ +---------+
+ | Entity- |
+ | Tag |
+ | |
+ +---------+
+
+ Figure 2: Resource Model Diagram
+
+
+
+Niemi & Willis Standards Track [Page 10]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ For a given event package, there is a single authoritative agent
+ responsible for zero or more resources. That is, even for a
+ distributed agent, the resource state is uniform across all
+ instances. The resource itself can be a list of resources [RFC4662].
+ Conditional notification for list subscriptions is addressed in
+ Section 6.5.
+
+ A resource is identified by zero or more URIs, which can be SIP URIs,
+ pres URIs [RFC3859], or similar. Subscribers use this URI to
+ subscribe to the resource for certain types of events, identified by
+ the event package.
+
+ With a successful subscription, a subscriber receives event
+ notifications that communicate the resource state and the changes
+ thereto. Each event notification carries a representation of the
+ current resource state. This representation is influenced by many
+ factors, e.g., authorization and filtering rules, and the event
+ composition rules of the notifier.
+
+ This representation is realized in an "entity". Each resource may be
+ associated with zero or more entities. For example, there may be
+ multiple subscribers to the presence information of a single user (a
+ resource), and each subscriber may have a different filtered view of
+ that resource, producing one entity per subscriber. However, each
+ entity is associated with one and only one resource; there is no
+ "compositing" of resources at the entity level. Resources may
+ themselves be made up of information from other resources (be
+ "composite resources"), but this does not change the one-resource-
+ per-entity rule.
+
+ An entity consists of the data carried in the body of a NOTIFY
+ message and related meta-data in the message header. Whenever the
+ data in the body or any of the meta-data changes, the notifier MUST
+ produce a new entity-tag. This meta-data MUST include, but is not
+ limited to the following SIP header fields defined in the Session
+ Initiation Protocol [RFC3261] and SIP Specific Event Notification
+ [RFC3265]:
+
+ 1. Content-Disposition
+
+ 2. Content-Encoding
+
+ 3. Content-Language
+
+ 4. Content-Length
+
+ 5. Content-Type
+
+
+
+
+Niemi & Willis Standards Track [Page 11]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ 6. Event
+
+ Note that the Subscription-State is explicitly not part of the
+ entity. In the future, event packages may define additional fields
+ that implementations need to consider as part of the entity.
+
+ An entity has one or more versions of which only one is current and
+ all others stale. Each version has an entity-tag, which uniquely
+ identifies it across all versions of all entities pertaining to a
+ single resource and event package.
+
+ Note that two entity-tags for different resources being equal does
+ not indicate identical entities. In other words, if an entity-tag
+ received for a subscription to a first resource matches an entity-tag
+ received for a subscription to a second resource, the subscriber
+ cannot assume that the two entity values are equal.
+
+ With partial event notification, the NOTIFY message only carries the
+ delta state, or the set of changes to the previous version of the
+ entity. In that case, implementations MUST consider the full event
+ state as the version of the entity to which the entity-tag in the
+ NOTIFY message applies.
+
+ The conditional notification mechanism is independent of the way in
+ which subscriptions are installed. In other words, the mechanism
+ supports implicit subscriptions, such as those associated with the
+ REFER method [RFC3515].
+
+ It is possible that the same resource is in some shape or form
+ accessible through another mechanism in addition to SIP Event
+ Notification, e.g., HTTP or the SIP PUBLISH method. In general,
+ implementations MUST NOT expect the entity-tags to be shared between
+ the mechanisms, unless event packages or specific applications of SIP
+ events explicitly define such dependencies.
+
+5. Subscriber Behavior
+
+ This section augments the subscriber behavior defined in RFC 3265
+ [RFC3265]. It first discusses general issues related to indicating
+ support for the mechanism (Section 5.1) and creating conditions in
+ SUBSCRIBE requests (Section 5.2). Next, it describes subscriber
+ behavior for receiving NOTIFY requests (Section 5.3), and specific
+ client workflows for polling resource state (Section 5.4), resuming a
+ subscription (Section 5.5), refreshing a subscription (Section 5.6),
+ and terminating a subscription (Section 5.7). Finally, handling of
+ transient errors is discussed (Section 5.8).
+
+
+
+
+
+Niemi & Willis Standards Track [Page 12]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+5.1. Detecting Support for Conditional Notification
+
+ The mechanism defined in this memo is backwards compatible with SIP
+ events [RFC3265] in that a notifier supporting this mechanism will
+ insert a SIP entity-tag in its NOTIFY requests, and a subscriber that
+ understands this mechanism will know how to use it in creating a
+ conditional request.
+
+ Unaware subscribers will simply ignore the entity-tag, make requests
+ without conditions, and receive the default treatment from the
+ notifier. Unaware notifiers will simply ignore the conditional
+ header fields and continue normal operation.
+
+5.2. Generating SUBSCRIBE Requests
+
+ When creating a conditional SUBSCRIBE request, the subscriber MUST
+ include a single conditional header field including an entity-tag in
+ the request. The condition is evaluated by comparing the entity-tag
+ of the subscribed resource with the entity-tag carried in the
+ conditional header field. If they match, the condition evaluates to
+ true.
+
+ Unlike the condition introduced for the SIP PUBLISH [RFC3903] method,
+ these conditions do not apply to the SUBSCRIBE request itself, but to
+ the resulting NOTIFY requests. When true, the condition drives the
+ notifier to change its behavior with regard to sending the
+ notifications after the SUBSCRIBE.
+
+ This specification defines a new header field called Suppress-If-
+ Match. This header field introduces a condition to the SUBSCRIBE
+ request. If true, it instructs the notifier either to omit the body
+ of the resulting NOTIFY message (if the SUBSCRIBE is not sent within
+ an existing dialog) or to suppress (i.e., block) the NOTIFY request
+ that would otherwise be triggered by the SUBSCRIBE (for an
+ established dialog). In the latter case, the SUBSCRIBE message will
+ be answered with a 204 (No Notification) response. As long as the
+ condition remains true, it also instructs the notifier either to
+ suppress any subsequent NOTIFY request or, if there are reportable
+ changes in the NOTIFY header, e.g., the Subscription-State has
+ changed, to suppress the body of any subsequent NOTIFY request.
+
+ If the condition is false, the notifier follows its default behavior.
+
+ If the subscriber receives a 204 (No Notification) response to an in-
+ dialog SUBSCRIBE, the subscriber MUST consider the event state and
+ the subscription state unchanged.
+
+
+
+
+
+Niemi & Willis Standards Track [Page 13]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ The value of the Suppress-If-Match header field is an entity-tag,
+ which is an opaque token that the subscriber simply copies (byte-
+ wise) from a previously received NOTIFY request. Inclusion of an
+ entity-tag in a Suppress-If-Match header field of a SUBSCRIBE request
+ indicates that the client has a copy of, or is capable of recreating
+ a copy of, the entity associated with that entity-tag.
+
+ Example:
+
+ Suppress-If-Match: b4cf7
+
+ The header field can also be wildcarded using the special "*" entity-
+ tag value. Such a condition always evaluates to true regardless of
+ the value of the current entity-tag for the resource.
+
+ Example:
+
+ Suppress-If-Match: *
+
+ Such a wildcard condition effectively quenches a subscription; the
+ only notifications received are those reporting changes to the
+ subscription state and those in response to a SUBSCRIBE message sent
+ outside of an existing dialog. In both cases, the notifications will
+ not contain a body.
+
+ A subscription with a wildcard Suppress-If-Match condition is
+ useful in scenarios where the subscriber wants to temporarily put
+ a subscription in dormant mode. For example, a host may want to
+ conserve bandwidth and power when it detects from screen or input
+ device inactivity that the user isn't actively monitoring the
+ presence statuses of contacts.
+
+5.3. Receiving NOTIFY Requests
+
+ When a subscriber receives a NOTIFY request that contains a SIP-ETag
+ header field, it MUST store the entity-tag if it wishes to make use
+ of the conditional notification mechanism. The subscriber MUST be
+ prepared to receive a NOTIFY with any entity-tag value, including a
+ value that matches any previous value that the subscriber might have
+ seen.
+
+ The subscriber MUST NOT infer any meaning from the value of an
+ entity-tag; specifically, the subscriber MUST NOT assume identical
+ entities (i.e., event state) for NOTIFYs with identical entity-tag
+ values when those NOTIFYs result from subscription to different
+ resources.
+
+
+
+
+
+Niemi & Willis Standards Track [Page 14]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ Note that there are valid cases for which identical entity-tag
+ values on different resources may occur. For example, it is
+ possible to generate entity-tag values using a one-way hash
+ function, resulting in the possibility that two different
+ resources having the same entity-value will also have the same
+ entity-tag. Clients however MUST NOT assume that this is the
+ case, as the algorithm for the generation of entity-tags is
+ notifier-dependent and not negotiated with the subscriber.
+ Consequently, the subscriber cannot differentiate between two
+ entity-tags that have the same value because they are similar
+ hashes of identical entities, or because two notifiers happen to
+ have used the same sequential number as an entity-tag. Entity
+ tags are only required to be unique for a given resource, not
+ globally unique.
+
+5.4. Polling or Fetching Resource State
+
+ Polling with conditional notification allows a user agent to
+ efficiently poll resource state. This is accomplished using the
+ Suppress-If-Match condition:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 15]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ Subscriber Notifier
+ ---------- --------
+
+ (1) SUBSCRIBE -------->
+ Expires: 0
+ <-------- (2) 202
+
+ <-------- (3) NOTIFY
+ Subscription-State: terminated
+ SIP-ETag: f2e45
+ Content-Length: 17539
+
+ (4) 200 -------->
+
+
+ ... poll interval elapses ...
+
+
+ (5) SUBSCRIBE -------->
+ Suppress-If-Match: f2e45
+ Expires: 0
+ <-------- (6) 202
+
+ <-------- (7) NOTIFY
+ Subscription-State: terminated
+ SIP-ETag: f2e45
+ Content-Length: 0
+
+ (8) 200 -------->
+
+ Figure 3: Polling Resource State
+
+ (1) The subscriber polls for resource state by sending a SUBSCRIBE
+ with zero expiry (expires immediately).
+
+ (2) The notifier accepts the SUBSCRIBE with a 202 (Accepted)
+ response.
+
+ (3) The notifier then immediately sends a first (and last) NOTIFY
+ request with the current resource state and the current entity-
+ tag in the SIP-ETag header field.
+
+ (4) The subscriber accepts the notification with a 200 (OK)
+ response.
+
+ (5) After some arbitrary poll interval, the subscriber sends another
+ SUBSCRIBE with a Suppress-If-Match header field that includes
+ the entity-tag received in the previous NOTIFY.
+
+
+
+Niemi & Willis Standards Track [Page 16]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ (6) The notifier accepts the SUBSCRIBE with a 202 (Accepted)
+ response. (202 would be used to indicate that the subscription
+ request was understood without also indicating that it was
+ authorized, as per Section 3.1.6.1 of SIP-Specific Event
+ Notification [RFC3265].)
+
+ (7) Since the resource state has not changed since the previous poll
+ occurred, the notifier sends a NOTIFY message with no body. It
+ also mirrors the current entity-tag of the resource in the SIP-
+ ETag header field.
+
+ (8) The subscriber accepts the notification with a 200 (OK)
+ response.
+
+5.5. Resuming a Subscription
+
+ Resuming a subscription means the ability to continue an earlier
+ subscription that either closed abruptly or was explicitly
+ terminated. When resuming, the subscription is established without
+ transmitting the resource state. This is accomplished with
+ conditional notification and the Suppress-If-Match header field:
+
+ Subscriber Notifier
+ ---------- --------
+
+ (1) SUBSCRIBE -------->
+ Suppress-If-Match: ega23
+ Expires: 3600
+ <-------- (2) 202
+
+ <-------- (3) NOTIFY
+ Subscription-State: active
+ SIP-ETag: ega23
+ Content-Length: 0
+ (4) 200 -------->
+
+ Figure 4: Resuming a Subscription
+
+ (1) The subscriber attempts to resume an earlier subscription by
+ including a Suppress-If-Match header field with the entity-tag
+ it last received.
+
+ (2) The notifier accepts the subscription after proper
+ authentication and authorization, by sending a 202 (Accepted)
+ response.
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 17]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ (3) Since the condition is true, the notifier then immediately sends
+ an initial NOTIFY request that has no body. It also mirrors the
+ current entity-tag of the resource in the SIP-ETag header field.
+
+ (4) The subscriber accepts the NOTIFY and sends a 200 (OK) response.
+
+ Had the entity-tag not been valid any longer, the condition would
+ have evaluated to false, and the NOTIFY would have had a body
+ containing the latest resource state.
+
+5.6. Refreshing a Subscription
+
+ To refresh a subscription using conditional notification, the
+ subscriber creates a subscription refresh before the subscription
+ expires, and uses the Suppress-If-Match header field:
+
+ Subscriber Notifier
+ ---------- --------
+
+ (1) SUBSCRIBE -------->
+ Suppress-If-Match: aba91
+ Expires: 3600
+
+ <-------- (2) 204
+ Expires: 3600
+
+ Figure 5: Refreshing a Subscription
+
+ (1) Before the subscription expires, the subscriber sends a
+ SUBSCRIBE request that includes the Suppress-If-Match header
+ field with the latest entity-tag it has seen.
+
+ (2) If the condition evaluates to true, the notifier sends a 204 (No
+ Notification) response and sends no NOTIFY request. The Expires
+ header field of the 204 (No Notification) response indicates the
+ new expiry time.
+
+5.7. Terminating a Subscription
+
+ To terminate a subscription using conditional notification, the
+ subscriber creates a SUBSCRIBE request with a Suppress-If-Match
+ condition:
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 18]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ Subscriber Notifier
+ ---------- --------
+
+ (1) SUBSCRIBE -------->
+ Suppress-If-Match: ega23
+ Expires: 0
+
+ <-------- (2) 204
+
+ Figure 6: Terminating a Subscription
+
+ (1) The subscriber decides to terminate the subscription and sends a
+ SUBSCRIBE request with the Suppress-If-Match condition with the
+ entity-tag it has last seen.
+
+ (2) If the condition evaluates to true, the notifier sends a 204 (No
+ Notification) response, which concludes the subscription, and
+ the subscriber can clear all state related to the subscription.
+
+5.8. Handling Transient Errors
+
+ This section is non-normative.
+
+ In some deployments, there may be Back-to-Back User Agent (B2BUA)
+ devices that track SIP dialogs such as subscription dialogs. These
+ devices may be unaware of the conditional notification mechanism.
+
+ It is possible that some B2BUA devices may treat a NOTIFY with
+ suppressed body as an error, or may expect all SUBSCRIBE messages to
+ have an associated NOTIFY message.
+
+ In general, there is very little that an endpoint can do to recover
+ from such transient errors. The most that can be done is to try to
+ detect such errors, and define a fallback behavior.
+
+ If subscribers encounter transient errors in conditional
+ notification, they should disable the feature and fall back to normal
+ subscription behavior.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 19]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+6. Notifier Behavior
+
+ This section augments the notifier behavior as specified in RFC 3265
+ [RFC3265].
+
+6.1. Generating Entity-tags
+
+ An entity-tag is a token carried in the SIP-ETag header field, and it
+ is opaque to the client. The notifier is free to decide on any means
+ for generating the entity-tag. It can have any value, except for
+ "*". For example, one possible method is to implement the entity-tag
+ as a simple counter, incrementing it by one for each generated
+ notification per resource.
+
+ A notifier MUST generate entity-tags for event notifications of all
+ resources for which it is responsible. The entity-tag MUST be unique
+ across all versions of all entities for each state of a resource as
+ reported by a given event package. Otherwise said, for any
+ subscription or sequence of subscriptions to a specific resource
+ using a singular event package, each entity-tag produced MUST map to
+ one and only one presentation of resource state (entity). Two
+ identical entities for a specific resource might or might not have
+ identical entity-tags; this decision is left to the notifier.
+
+ An entity-tag is considered valid for as long as the entity exists.
+ An entity becomes stale when its version is no longer the current
+ one. The notifier MUST remember (or be able to recalculate) the
+ entity-tag of an entity as long as the version of the entity is
+ current. The notifier MAY remember the entity-tag longer than this,
+ e.g., for implementing journaled state differentials (Section 6.4).
+
+ The entity-tag values used in publications are not necessarily shared
+ with the entity-tag values used in subscriptions. This is because
+ there may not always be a one-to-one mapping between a publication
+ and a notification of state change; there may be several sources to
+ the event composition process, and a publication into a resource may
+ not affect the resulting entity.
+
+6.2. Suppressing NOTIFY Bodies
+
+ When a condition in a SUBSCRIBE request for suppressing notifications
+ is true (i.e., the local entity-tag for the resource state and the
+ entity-tag in a Suppress-If-Match header field are byte-wise
+ identical) but there are reportable changes in the NOTIFY header
+ (e.g., the Subscription-State has changed), the notifier MUST
+ suppress the body of the NOTIFY request. That is, the resulting
+ NOTIFY contains no Content-Type header field, the Content-Length is
+ set to zero, and no payload is attached to the message.
+
+
+
+Niemi & Willis Standards Track [Page 20]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ Additionally, when a condition in a SUBSCRIBE request for suppressing
+ notifications is true and the SUBSCRIBE message is not sent within an
+ established dialog, the notifier MUST send a NOTIFY request with a
+ suppressed entity body.
+
+ Suppressing the entity body of a NOTIFY does not change the current
+ entity-tag of the resource. Hence, the NOTIFY MUST contain a SIP-
+ ETag header field that contains the unchanged entity-tag of the
+ resource state.
+
+ A Suppress-If-Match header field that includes an entity-tag with the
+ value of "*" MUST always evaluate to true.
+
+6.3. Suppressing NOTIFY Requests
+
+ When a condition in a SUBSCRIBE request to suppress notifications is
+ true (i.e., the local entity-tag of the resource and the entity-tag
+ in a Suppress-If-Match header field match), and the SUBSCRIBE is sent
+ within an established dialog, then the notifier MUST suppress the
+ resulting NOTIFY request, and generate a 204 (No Notification)
+ response. As long as the condition remains true, and there are no
+ reportable changes in the NOTIFY header, all subsequent NOTIFY
+ requests MUST also be suppressed.
+
+ Notifiers MUST NOT suppress a NOTIFY unless the corresponding
+ SUBSCRIBE message was sent in an established dialog.
+
+ A successful conditional SUBSCRIBE request MUST extend the
+ subscription expiry time.
+
+ Suppressing the entire NOTIFY has no effect on the entity-tag of the
+ resource. In other words, it remains unchanged.
+
+ A Suppress-If-Match header field that includes an entity-tag with the
+ value of "*" MUST always evaluate to true.
+
+6.4. State Differentials
+
+ Some event packages support a scheme where notifications contain
+ state differentials, or state deltas [RFC3265], instead of complete
+ resource state.
+
+ Further extensions could define means for notifiers to keep track of
+ the state changes of a resource, e.g., storing the changes in a
+ journal. If a condition fails, the notifier would then send a state
+ differential in the NOTIFY rather than the full state of the event
+ resource. This is only possible if the event package and the
+ subscriber both support a payload format that has this capability.
+
+
+
+Niemi & Willis Standards Track [Page 21]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ When state differentials are sent, the SIP-ETag header field MUST
+ contain an entity-tag that corresponds to the full resource state.
+
+6.5. List Subscriptions
+
+ The Event Notification Extension for Resource Lists [RFC4662] defines
+ a mechanism for subscribing to a homogeneous list of resources using
+ the SIP events framework.
+
+ A list subscription delivers event notifications that contain both
+ Resource List Meta-Information (RLMI) documents as well as the
+ resource state of the individual resources on the list.
+
+ Implementations MUST consider the full resource state of a resource
+ list including RLMI and the entity-header as the entity to which the
+ entity-tag applies.
+
+7. Protocol Element Definitions
+
+ This section describes the protocol extensions required for
+ conditional notification.
+
+7.1. 204 (No Notification) Response Code
+
+ The 204 (No Notification) response code indicates that the request
+ was successful, but the notification associated with the request will
+ not be sent. It is valid only in response to a SUBSCRIBE message
+ sent within an established dialog.
+
+ The response code is added to the "Success" production rule in the
+ SIP [RFC3261] message grammar.
+
+7.2. Suppress-If-Match Header Field
+
+ The Suppress-If-Match header field is added to the definition of the
+ "message-header" rule in the SIP [RFC3261] grammar. Its use is
+ described in Sections 5, 6.3, and 6.2.
+
+ This header field is allowed to appear in any request, but its
+ behavior is only defined for the SUBSCRIBE request.
+
+7.3. Grammar
+
+ This section defines the formal syntax for extensions described in
+ this memo in Augmented BNF (ABNF) [RFC5234]. The rules defined here
+ augment and reference the syntax defined in RFC 3261 [RFC3261] and
+ RFC 3903 [RFC3903].
+
+
+
+
+Niemi & Willis Standards Track [Page 22]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ Success =/ "204" ; No Notification
+
+ ; Success is defined in RFC 3261.
+
+ message-header =/ Suppress-If-Match
+
+ ; message-header is defined in RFC 3261.
+
+ Suppress-If-Match = "Suppress-If-Match" HCOLON ( entity-tag / "*" )
+
+ ; entity-tag is defined in RFC 3903.
+
+8. IANA Considerations
+
+ This document registers a new response code and a new header field
+ name.
+
+8.1. 204 (No Notification) Response Code
+
+ This document registers a new response code. This response code is
+ defined by the following information, which has been added to the
+ methods and response-codes sub-registry available from
+ http://www.iana.org.
+
+ This information has been added under "Successful 2xx" category.
+
+ +---------------------+-----------+
+ | Response Code | Reference |
+ +---------------------+-----------+
+ | 204 No Notification | [RFC5839] |
+ +---------------------+-----------+
+
+8.2. Suppress-If-Match Header Field
+
+ This document registers a new SIP header field called Suppress-If-
+ Match. This header field is defined by the following information,
+ which has been added to the header fields sub-registry available from
+ http://www.iana.org.
+
+ +-------------------+---------+-----------+
+ | Header Name | Compact | Reference |
+ +-------------------+---------+-----------+
+ | Suppress-If-Match | | [RFC5839] |
+ +-------------------+---------+-----------+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 23]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+9. Security Considerations
+
+ The security considerations for SIP event notification are
+ extensively discussed in RFC 3265 [RFC3265]. This specification
+ introduces an optimization to SIP event notification, which in itself
+ does not alter the security properties of the protocol.
+
+10. Acknowledgments
+
+ The following people have contributed corrections and suggestions to
+ this document: Adam Roach, Sean Olson, Johnny Vrancken, Pekka Pessi,
+ Eva Leppanen, Krisztian Kiss, Peili Xu, Avshalom Houri, David
+ Viamonte, Jonathan Rosenberg, Qian Sun, Dale Worley, Tolga Asveren,
+ Brian Stucker, Eric Rescorla, Arun Arunachalam, and the SIP and
+ SIMPLE working groups.
+
+11. References
+
+11.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [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.
+
+ [RFC3903] Niemi, A., "Session Initiation Protocol (SIP) Extension
+ for Event State Publication", RFC 3903, October 2004.
+
+ [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+11.2. Informative References
+
+ [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+ Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+ Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+ [RFC3515] Sparks, R., "The Session Initiation Protocol (SIP) Refer
+ Method", RFC 3515, April 2003.
+
+ [RFC3680] Rosenberg, J., "A Session Initiation Protocol (SIP) Event
+ Package for Registrations", RFC 3680, March 2004.
+
+
+
+Niemi & Willis Standards Track [Page 24]
+
+RFC 5839 Entity-Tags for SIP Events May 2010
+
+
+ [RFC3842] Mahy, R., "A Message Summary and Message Waiting
+ Indication Event Package for the Session Initiation
+ Protocol (SIP)", RFC 3842, August 2004.
+
+ [RFC3856] Rosenberg, J., "A Presence Event Package for the Session
+ Initiation Protocol (SIP)", RFC 3856, August 2004.
+
+ [RFC3859] Peterson, J., "Common Profile for Presence (CPP)",
+ RFC 3859, August 2004.
+
+ [RFC4662] Roach, A., Campbell, B., and J. Rosenberg, "A Session
+ Initiation Protocol (SIP) Event Notification Extension for
+ Resource Lists", RFC 4662, August 2006.
+
+Authors' Addresses
+
+ Aki Niemi
+ Nokia
+ P.O. Box 407
+ NOKIA GROUP, FIN 00045
+ Finland
+
+ Phone: +358 50 389 1644
+ EMail: aki.niemi@nokia.com
+
+
+ Dean Willis (editor)
+ Softarmor Systems
+ 3100 Independence Pkwy #311-164
+ Plano, TX 75075
+ USA
+
+ Phone: +1 214 504 1987
+ EMail: dean.willis@softarmor.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niemi & Willis Standards Track [Page 25]
+