Request for Comments: 3903 Nokia
Category: Standards Track October 2004
Session Initiation Protocol (SIP) Extension
for Event State Publication
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2004).
Abstract
This document describes an extension to the Session Initiation
Protocol (SIP) for publishing event state used within the SIP Events
framework. The first application of this extension is for the
publication of presence information.
The mechanism described in this document can be extended to support
publication of any event state for which there exists an appropriate
event package. It is not intended to be a general-purpose mechanism
for transport of arbitrary data, as there are better-suited
mechanisms for this purpose.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Definitions and Document Conventions . . . . . . . . . . . . 3
3. Overall Operation . . . . . . . . . . . . . . . . . . . . . 4
4. Constructing PUBLISH Requests . . . . . . . . . . . . . . . 5
4.1. Identification of Published Event State. . . . . . . . 6
4.2. Creating Initial Publication . . . . . . . . . . . . . 7
4.3. Refreshing Event State . . . . . . . . . . . . . . . . 8
4.4. Modifying Event State . . . . . . . . . . . . . . . . 9
4.5. Removing Event State . . . . . . . . . . . . . . . . . 9
5. Processing PUBLISH Responses . . . . . . . . . . . . . . . . 10
6. Processing PUBLISH Requests . . . . . . . . . . . . . . . . 10
7. Processing OPTIONS Requests . . . . . . . . . . . . . . . . 13
8. Use of Entity-tags in PUBLISH . . . . . . . . . . . . . . . 13
8.1. General Notes. . . . . . . . . . . . . . . . . . . . . 13
8.2. Client Usage . . . . . . . . . . . . . . . . . . . . . 14
8.3. Server Usage . . . . . . . . . . . . . . . . . . . . . 14
9. Controlling the Rate of Publication . . . . . . . . . . . . 15
10. Considerations for Event Packages using PUBLISH . . . . . . 15
10.1. PUBLISH Bodies . . . . . . . . . . . . . . . . . . . . 16
10.2. PUBLISH Response Bodies. . . . . . . . . . . . . . . . 16
10.3. Multiple Sources for Event State . . . . . . . . . . . 16
10.4. Event State Segmentation . . . . . . . . . . . . . . . 17
10.5. Rate of Publication. . . . . . . . . . . . . . . . . . 17
11. Protocol Element Definitions . . . . . . . . . . . . . . . . 17
11.1. New Methods. . . . . . . . . . . . . . . . . . . . . . 17
11.1.1. PUBLISH Method . . . . . . . . . . . . . . . . 17
11.2. New Response Codes . . . . . . . . . . . . . . . . . . 19
11.2.1. "412 Conditional Request Failed" Response Code 19
11.3. New Header Fields . . . . . . . . . . . . . . . . . . 20
11.3.1. "SIP-ETag" Header Field . . . . . . . . . . . 20
11.3.2. "SIP-If-Match" Header Field . . . . . . . . . 20
12. Augmented BNF Definitions . . . . . . . . . . . . . . . . . 21
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . 21
13.1. Methods . . . . . . . . . . . . . . . . . . . . . . . 21
13.2. Response Codes . . . . . . . . . . . . . . . . . . . . 21
13.3. Header Field Names . . . . . . . . . . . . . . . . . . 21
14. Security Considerations . . . . . . . . . . . . . . . . . . 22
14.1. Access Control . . . . . . . . . . . . . . . . . . . . 22
14.2. Denial of Service Attacks . . . . . . . . . . . . . . 22
14.3. Replay Attacks . . . . . . . . . . . . . . . . . . . . 22
14.4. Man in the Middle Attacks . . . . . . . . . . . . . . 23
14.5. Confidentiality . . . . . . . . . . . . . . . . . . . 23
15. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 24
16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 29
17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30
18. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
18.1. Normative References . . . . . . . . . . . . . . . . . 30
18.2. Informative References . . . . . . . . . . . . . . . . 31
Author’s Address. . . . . . . . . . . . . . . . . . . . . . . . . 31
Full Copyright Statement. . . . . . . . . . . . . . . . . . . . . 32
1. Introduction
This specification provides a framework for the publication of event
state from a user agent to an entity that is responsible for
compositing this event state and distributing it to interested
parties through the SIP Events [1] framework.
In addition to defining an event publication framework, this
specification defines a concrete usage of that framework for the
publication of presence state [2] by a presence user agent [3] to a
presence compositor, which has a tightly coupled relationship with
the presence agent [1].
The requirements and model for presence publication are documented in
[10]. This specification will address each of those requirements.
The mechanism described in this document can be extended to support
publication of any event state for which there exists an appropriate
event package as defined in [1]. For instance, an application of SIP
events for message waiting indications [11] might choose to collect
the statuses of voice-mail boxes across a set of user agents using
the PUBLISH mechanism. The compositor in such an application would
then be responsible for collecting and distributing this state to the
subscribers of the event package.
Each application that makes use of the PUBLISH mechanism in the
publication of event state will need to adhere to the guidelines set
in Section 10. The mechanism described in this document is not
intended to be a general-purpose mechanism for transport of arbitrary
data, as there are better-suited mechanisms for this purpose.
2. Definitions and Document Conventions
In addition to the definitions of RFC 2778 [3], RFC 3265 [1], and RFC
3261 [4], this document introduces some new concepts:
Event State: State information for a resource, associated with an
event package and an address-of-record.
Event Publication Agent (EPA): The User Agent Client (UAC) that
issues PUBLISH requests to publish event state.
Event State Compositor (ESC): The User Agent Server (UAS) that
processes PUBLISH requests, and is responsible for compositing
event state into a complete, composite event state of a resource.
Presence Compositor: A type of Event State Compositor that is
responsible for compositing presence state for a presentity.
Publication: The act of an EPA sending a PUBLISH request to an ESC to
publish event state.
Event Hard State: The steady-state or default event state of a
resource, which the ESC may use in the absence of, or in addition
to, soft state publications.
Event Soft State: Event state published by an EPA using the PUBLISH
mechanism. A protocol element (i.e., an entity-tag) is used to
identify a specific soft state entity at the ESC. Soft state has
a defined lifetime and will expire after a negotiated amount of
time.
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 [5]
and indicate requirement levels for compliant implementations.
Indented passages such as this one are used in this document to
provide additional information and clarifying text. They do not
contain descriptions of normative protocol behavior.
3. Overall Operation
This document defines a new SIP method, PUBLISH, for publishing event
state. PUBLISH is similar to REGISTER in that it allows a user to
create, modify, and remove state in another entity which manages this
state on behalf of the user. Addressing a PUBLISH request is
identical to addressing a SUBSCRIBE request. The Request-URI of a
PUBLISH request is populated with the address of the resource for
which the user wishes to publish event state. The user may in turn
have multiple User Agents or endpoints that publish event state.
Each endpoint may publish its own unique state, out of which the
event state compositor generates the composite event state of the
resource. In addition to a particular resource, all published event
state is associated with a specific event package. Through a
subscription to that event package, the user is able to discover the
composite event state of all of the active publications.
A User Agent Client (UAC) that publishes event state is labeled an
Event Publication Agent (EPA). For presence, this is the familiar
Presence User Agent (PUA) role as defined in [2]. The entity that
processes the PUBLISH request is known as an Event State Compositor
(ESC). For presence, this is the familiar Presence Agent (PA) role
as defined in [2].
PUBLISH requests create soft state in the ESC. This event soft state
has a defined lifetime and will expire after a negotiated amount of
time, requiring the publication to be refreshed by subsequent PUBLISH
requests. There may also be event hard state provisioned for each
resource for a particular event package. This event state represents
the resource state that is present at all times, and does not expire.
The ESC may use event hard state in the absence of, or in addition
to, event soft state provided through the PUBLISH mechanism. Setting
this event hard state or configuring the ESC policy regarding the
aggregation of different event state is out of the scope of this
specification.
The body of a PUBLISH request carries the published event state. In
response to every successful PUBLISH request, the ESC assigns an
identifier to the publication in the form of an entity-tag. This
identifier is then used by the EPA in any subsequent PUBLISH request
that modifies, refreshes or removes the event state of that
publication. When event state expires or is explicitly removed, the
entity-tag associated with it becomes invalid. A publication for an
invalid entity-tag will naturally fail, and the EPA needs to start
anew and resend its event state without referencing a previous
entity-tag.
4. Constructing PUBLISH Requests
PUBLISH requests create, modify, and remove event state associated
with an address-of-record. A suitably authorized third party may
also perform publication on behalf of a particular address-of-record.
Except as noted, the construction of the PUBLISH request and the
behavior of clients sending a PUBLISH request are identical to the
general UAC behavior described in Section 8.1 and Section 17.1 of RFC
3261 [4].
If necessary, clients may probe for the support of PUBLISH using the
OPTIONS request defined in SIP [4]. The presence of "PUBLISH" in the
"Allow" header field in a response to an OPTIONS request indicates
support for the PUBLISH method. In addition, the "Allow-Events"
header field indicates the supported event packages.
Note that it is possible for the OPTIONS request to fork, and
consequently return a response from a User Agent other than the
ESC. In that case, support for the PUBLISH method may not be
appropriately represented for that particular Request-URI.
A PUBLISH request does not establish a dialog. A UAC MAY include a
Route header field in a PUBLISH request based on a pre-existing route
set as described in Section 8.1 of RFC 3261 [4]. The Record-Route
header field has no meaning in PUBLISH requests or responses, and
MUST be ignored if present. In particular, the UAC MUST NOT create a
new route set based on the presence or absence of a Record-Route
header field in any response to a PUBLISH request.
The PUBLISH request MAY contain a Contact header field, but including
one in a PUBLISH request has no meaning in the event publication
context and will be ignored by the ESC. An EPA MAY send a PUBLISH
request within an existing dialog. In that case, the request is
received in the context of any media session or sessions associated
with that dialog.
Note that while sending a PUBLISH request within an existing
dialog is not prohibited, it will typically not result in the
expected behavior. Unless the other end of the dialog is also an
ESC, it will probably reject the request.
EPAs MUST NOT send a new PUBLISH request (not a re-transmission) for
the same Request-URI, until they have received a final response from
the ESC for the previous one or the previous PUBLISH request has
timed out.
4.1. Identification of Published Event State
Identification of published event state is provided by three pieces
of information: Request-URI, event type, and (optionally) an entity-
tag.
The Request-URI of a PUBLISH request contains enough information to
route the request to the appropriate entity per the request routing
procedures outlined in RFC 3261 [4]. It also contains enough
information to identify the resource whose event state is to be
published, but not enough information to determine the type of the
published event state.
For determining the type of the published event state, the EPA MUST
include a single Event header field in PUBLISH requests. The value
of this header field indicates the event package for which this
request is publishing event state.
For each successful PUBLISH request, the ESC will generate and assign
an entity-tag and return it in the SIP-ETag header field of the 2xx
response.
When updating previously published event state, PUBLISH requests MUST
contain a single SIP-If-Match header field identifying the specific
event state that the request is refreshing, modifying or removing.
This header field MUST contain a single entity-tag that was returned
by the ESC in the SIP-ETag header field of the response to a previous
publication.
The PUBLISH request MAY contain a body, which contains event state
that the client wishes to publish. The content format and semantics
are dependent on the event package identified in the Event header
field.
The presence of a body and the SIP-If-Match header field determine
the specific operation that the request is performing, as described
in Table 1.
+-----------+-------+---------------+---------------+
| Operation | Body? | SIP-If-Match? | Expires Value |
+-----------+-------+---------------+---------------+
| Initial | yes | no | > 0 |
| Refresh | no | yes | > 0 |
| Modify | yes | yes | > 0 |
| Remove | no | yes | 0 |
+-----------+-------+---------------+---------------+
Table 1: Publication Operations
An ’Initial’ publication sets the initial event state for a
particular EPA. There may, of course, already be event state
published by other EPAs (for the same address-of-record). That state
is unaffected by an initial publication. A ’Refresh’ publication
refreshes the lifetime of a previous publication, whereas a ’Modify’
publication modifies the event state of a previous publication. A
’Remove’ publication requests immediate removal of event state.
These operations are described in more detail in the following
sections.
4.2. Creating Initial Publication
An initial publication is a PUBLISH request created by the EPA and
sent to the ESC that establishes soft state for the event package
indicated in the Event header field of the request, and bound to the
address in the Request-URI of the request.
An initial PUBLISH request MUST NOT contain a SIP-If-Match header
field. However, if the EPA expects an appropriate, locally stored
entity-tag to still be valid, it SHOULD first try to modify that
event state as described in Section 4.4, instead of submitting an
initial publication.
An initial PUBLISH request MUST contain a body that contains the
published event state.
An initial PUBLISH request MAY contain a single Expires header field.
This value indicates the suggested lifetime of the event state
publication.
The ESC may lower the suggested lifetime of the publication, but it
will never extend it. If an Expires header field is not present, the
EPA is indicating its desire for the ESC to choose. The Expires
header field in a 2xx response to the initial PUBLISH indicates the
actual duration for which the publication will remain active. Unless
refreshed before this lifetime is exceeded, the publication will
expire.
4.3. Refreshing Event State
An EPA is responsible for refreshing its previously established
publications before their expiration interval has elapsed. To
refresh a publication, the EPA MUST create a PUBLISH request that
includes in a SIP-If-Match header field the entity-tag of the
publication to be refreshed.
The SIP-If-Match header field containing an entity-tag conditions the
PUBLISH request to refresh a specific event state established by a
prior publication. If the entity-tag matches previously published
event state at the ESC, the refresh succeeds, and the EPA receives a
2xx response.
Like the 2xx response to an initial PUBLISH request, the 2xx response
to a refresh PUBLISH request will contain a SIP-ETag header field
with an entity-tag. The EPA MUST store this entity-tag, replacing
any existing entity-tag for the refreshed event state. See Section
8.2 for more information on the EPA handling of entity-tags.
If there is no matching event state, e.g., the event state to be
refreshed has already expired, the EPA receives a 412 (Conditional
Request Failed) response to the PUBLISH request.
A publication refresh MAY contain a single Expires header field.
This value indicates the suggested lifetime of the event state.
The ESC may lower the suggested lifetime of the publication refresh,
but it will never extend it. If an Expires header field is not
present, the EPA is indicating its desire for the ESC to choose. The
Expires header field in a 2xx response to the publication refresh
indicates the actual duration for which the publication will remain
active.
A publication refresh only extends the expiration time of already
existing event state. It does not affect that event state in any
other way. Therefore, a PUBLISH request that refreshes event state
MUST NOT have a body.
4.4. Modifying Event State
Modifying event state closely resembles the creation of initial event
state. However, instead of establishing completely new event state
at the ESC, already existing event state is updated with modified
event state. The nature of this update depends on the content of the
body, and the semantics associated with the format of that body.
To modify event state, the EPA MUST construct a PUBLISH request that
includes in a SIP-If-Match header field the entity-tag of the event
state publication to be modified. A PUBLISH request that modifies
event state MUST contain a body that includes the modified event
state.
The SIP-If-Match header field conditions the PUBLISH request to
modify a specific event state established by a prior publication, and
identified by the entity-tag. If the entity-tag matches previously
published event state at the ESC, that event state is replaced by the
event state carried in the PUBLISH request, and the EPA receives a
2xx response.
Like the 2xx response to an initial PUBLISH request, the 2xx response
to a modifying PUBLISH request will contain a SIP-ETag header field
with an entity-tag. The EPA MUST store this entity-tag, replacing
any existing entity-tag for the modified event state. See Section
8.2 for more information on the EPA handling of entity-tags.
If there is no matching event state at the ESC, e.g., the event state
to be modified has already expired, the EPA receives a 412
(Conditional Request Failed) response to the PUBLISH request.
A modifying PUBLISH request MAY contain a single Expires header
field. This value indicates the suggested lifetime of the event
state publication.
The ESC may lower the suggested lifetime of the publication, but it
will never extend it. If an Expires header field is not present, the
EPA is indicating its desire for the ESC to choose. The Expires
header field in a 2xx response to the modifying PUBLISH request
indicates the actual duration for which the publication will remain
active. Unless refreshed before this lifetime is exceeded, the
publication will expire.
4.5. Removing Event State
Event state established by a prior publication may also be explicitly
removed.
To request the immediate removal of event state, an EPA MUST create a
PUBLISH request with an Expires value of "0", and set the SIP-If-
Match header field to contain the entity-tag of the event state
publication to be removed.
Note that removing event state is effectively a publication
refresh suggesting an infinitesimal expiration interval.
Consequently, the refreshed event state expires immediately after
being refreshed.
Similar to an event state refresh, the removal of event state only
affects the expiry of the event state. Therefore, a PUBLISH request
that removes event state MUST NOT contain a body.
5. Processing PUBLISH Responses
When processing responses to PUBLISH requests, the steps in Section
8.1.2 of RFC 3261 [4] apply.
If an EPA receives a 412 (Conditional Request Failed) response, it
MUST NOT reattempt the PUBLISH request. Instead, to publish event