< draft-ietf-simple-xcap-package-01.txt   draft-ietf-simple-xcap-package-02.txt >
SIMPLE J. Rosenberg SIMPLE J. Rosenberg
Internet-Draft dynamicsoft Internet-Draft dynamicsoft
Expires: August 16, 2004 February 16, 2004 Expires: January 16, 2005 July 18, 2004
A Session Initiation Protocol (SIP) Event Package for Modification An Extensible Markup Language (XML) Document Format for Indicating
Events for the Extensible Markup Language (XML) Configuration Access Changes in XML Configuration Access Protocol (XCAP) Resources
Protocol (XCAP) Managed Documents draft-ietf-simple-xcap-package-02
draft-ietf-simple-xcap-package-01
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with By submitting this Internet-Draft, I certify that any applicable
all provisions of Section 10 of RFC2026. patent or other IPR claims of which I am aware have been disclosed,
and any of which I become aware will be disclosed, in accordance with
RFC 3668.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other Task Force (IETF), its areas, and its working groups. Note that
groups may also distribute working documents as Internet-Drafts. other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http:// The list of current Internet-Drafts can be accessed at
www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 16, 2004. This Internet-Draft will expire on January 16, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved. Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract Abstract
This specification defines a Session Initiation Protocol (SIP) event This specification defines a document format that can be used to
package for finding out about changes to documents managed by the describe the differences between versions of resources managed by the
Extensible Markup Language (XML) Configuration Access Protocol Extensible Markup Language (XML) Configuration Access Protocol
(XCAP). XCAP allows a client to manipulate XML documents on a server (XCAP). Documents of this format can be delivered to clients using a
which contain configuration information for application protocols. number of means, including the Session Initiation Protocol (SIP)
Multiple clients can potentially access the same document, in which event package for configuration data. By subscribing to this event
case the other clients would like to be notified of a change in the package, clients can learn about document changes made by other
document made by another. This event package allows a client to do clients.
that.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Document Change Event Package . . . . . . . . . . . . . . . 4 2. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 4
2.1 Package Name . . . . . . . . . . . . . . . . . . . . . . . . 4 3. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Event Package Parameters . . . . . . . . . . . . . . . . . . 4 4. Example Document . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . . 5 5. Usage with the Config Framework . . . . . . . . . . . . . . . 9
2.4 Subscription Duration . . . . . . . . . . . . . . . . . . . 5 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12
2.5 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . . 5 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
2.6 Notifier Processing of SUBSCRIBE Requests . . . . . . . . . 6 7.1 application/xcap-diff+xml MIME Type . . . . . . . . . . . 13
2.7 Notifier Generation of NOTIFY Requests . . . . . . . . . . . 7 7.2 URN Sub-Namespace Registration for
2.8 Subscriber Processing of NOTIFY Requests . . . . . . . . . . 7 urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 13
2.9 Handling of Forked Requests . . . . . . . . . . . . . . . . 8 7.3 Schema Registration . . . . . . . . . . . . . . . . . . . 14
2.10 Rate of Notifications . . . . . . . . . . . . . . . . . . . 8 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.11 State Agents . . . . . . . . . . . . . . . . . . . . . . . . 8 8.1 Normative References . . . . . . . . . . . . . . . . . . . . 15
3. application/xml-change+xml Media Type . . . . . . . . . . . 9 8.2 Informative References . . . . . . . . . . . . . . . . . . . 15
3.1 XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 16
3.2 Example Document . . . . . . . . . . . . . . . . . . . . . . 11 Intellectual Property and Copyright Statements . . . . . . . . 17
4. Security Considerations . . . . . . . . . . . . . . . . . . 13
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 14
5.1 SIP Event Package . . . . . . . . . . . . . . . . . . . . . 14
5.2 application/xcap-change+xml MIME Type . . . . . . . . . . . 14
5.3 URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:xcap-change . . . . . . . . . . . . . 15
Normative References . . . . . . . . . . . . . . . . . . . . 17
Informative References . . . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . . 18
Intellectual Property and Copyright Statements . . . . . . . 19
1. Introduction 1. Introduction
The Extensible Markup Language (XML) Configuration Access Protocol The Extensible Markup Language (XML) Configuration Access Protocol
(XCAP) [10] is a protocol that allows clients to manipulate XML (XCAP) [7] is a protocol that allows clients to manipulate XML
documents stored on a server. These XML documents serve as documents stored on a server. These XML documents serve as
configuration information for application protocols. As an example, configuration information for application protocols. As an example,
resource list [11] subscriptions (also known as presence lists) allow resource list [11] subscriptions (also known as presence lists) allow
a client to have a single SIP subscription to a list of users, where a client to have a single SIP subscription to a list of users, where
the list is maintained on a server. The server will obtain presence the list is maintained on a server. The server will obtain presence
for those users and report it back to the client. This application for those users and report it back to the client. This application
requires the server, called a Resource List Server (RLS), to have requires the server, called a Resource List Server (RLS), to have
access to the list of presentities. This list needs to be manipulated access to the list of presentities. This list needs to be
by clients so they can add and remove their friends as they desire. manipulated by clients so they can add and remove their friends as
they desire.
Complexities arise when multiple clients attempt to simultaneously Complexities arise when multiple clients attempt to simultaneously
manipulate a document, such as a presence list. Frequently, a client manipulate a document, such as a presence list. Frequently, a client
will keep a copy of the current list in memory, so it can render it will keep a copy of the current list in memory, so it can render it
to users. However, if another client modifies the document, the to users. However, if another client modifies the document, the
cached version becomes stale. This information must be made known to cached version becomes stale. This information must be made known to
all clients which have cached copies of the document, so that they all clients which have cached copies of the document, so that they
can fetch the most recent one. can fetch the most recent one.
This problem is addressed by this specification, which provides a To deal with this problem, clients can use the Session Initiation
Session Initiation Protocol (SIP) [1]event package [2] for Protocol (SIP) [9]event package [10] for subscribing to changes in
subscribing to changes in documents managed by an XCAP server. This configuration and profile information [8], including application data
package would be used by any client which is retaining a cached copy that resides on an XCAP server. With that package, a user gets
of a document obtained by XCAP, so that it can find out when a change notified that a particular document has changed. This notification
has been made, invalidating its cached copy. In fact, the can include the full content of the new document, or it can be a
notifications generated by this package indicate the specific change content indirection [14]. However, in both cases, the transfer of
which occurred in the document, so the client can decide whether the the entire document is ultimately required. This may require a lot
change is significant enough to warrant a refetch from the XCAP of bandwidth, particularly for wireless devices with large documents
server. (such as a resource list [11] with hundreds of users listed).
2. Document Change Event Package
The SIP event framework [2] defines a SIP extension for subscribing
to, and receiving notifications of, events. It leaves the definition
of many aspects of these events to concrete extensions, known as
event packages. This document qualifies as an event package. This
section fills in the information required for all event packages by
RFC 3265.
2.1 Package Name
The name of this package is "xcap-change". As specified in RFC 3265
[2], this value appears in the Event header field present in
SUBSCRIBE and NOTIFY requests.
2.2 Event Package Parameters
The SIP event framework allows event packages to define additional
parameters carried in the Event header field. This package defines a
single event header parameter, called "doc-component", which
specifies a particular document and document component which is being
to subscribed to. The request-URI specifies the user whose data is
being subscribed to. To subscribe to global data, a user agent would
subscribed to a special user name that is configured into the UA. The
name "global-xcap-user" is RECOMMENDED, and SHOULD be used if no
explicit user name is provisioned. By default, a subscription is for
all XCAP data associated with that user. The header field parameter
allows the subscription to specify a specific document and document
sub-tree.
The format of this header field parameter is a quoted string. The
value of this string is the portion of an XCAP URI to the right of
the directory for the user, in the case of user data, or to the right
of the global directory for global data. The XCAP URI can only refer
to a document or to an element within that document. When the URI
represents a document, the subscription is to changes anywhere in the
document. When it is to an element, the subscription is to changes
that occur in the attributes or content of that element, including
all children. For example, if a user wishes to subscribe to http://
xcap.example.com/services/presence-lists/users/joe/mydir/friends.xml,
the event header parameter would be "mydir/friends.xml".
OPEN ISSUE: There is no way to specify that a subscription is to
multiple documents. Multiple subscriptions would be needed for
that. Is that limitation OK for now? A filter can fix that down
the road.
2.3 SUBSCRIBE Bodies
A SUBSCRIBE request MAY contain a body. The purpose of the body
depends on its type. Subscriptions will normally not contain bodies.
The Request-URI, which identifies the user whose data is being
subscribed to, combined with the event package name and parameter, is
sufficient for this package.
One type of body that can be included in a SUBSCRIBE request is a
filter document. These filters request that only document change
events generate notifications, or would ask for a restriction on the
set of data returned in NOTIFY requests. Filter documents are not
specified in this document, and at the time of writing, are expected
to be the subject of future standardization activity.
Honoring of these filters is at the policy discretion of the
notifier.
If the SUBSCRIBE request does not contain a filter, this tells the
notifier that no filter is to be applied. The notifier SHOULD send
NOTIFY requests at the discretion of its own policy.
2.4 Subscription Duration
Generally speaking, changes to application configuration data are
relatively infrequent. Of course, this depends on the type of
application, but generally configuration data is static. As a result,
notifications are expected infrequently, and subscriptions will
typically be held for long periods of time. This would argue for long
subscription refresh intervals. For this reason, the default
subscription duration is two hours. Of course, a different duration
can be requested by a client, or set by a server, using the Expires
header field, as per RFC 3265 [2].
2.5 NOTIFY Bodies
As described in RFC 3265 [2], the NOTIFY message will contain bodies
that describe the state of the subscribed resource. This body is in a
format listed in the Accept header field of the SUBSCRIBE, or a
package-specific default if the Accept header field was omitted from
the SUBSCRIBE.
In this event package, the body of the notification contains a
document change document. This document describes the current version
of an XML document managed by XCAP, in addition to the changes in
this document from the previous version. Note that a listing of
changes from the previous version is only sent in a NOTIFY triggered
by a change to the document. NOTIFY requests sent in response to an
initial SUBSCRIBE, or a SUBSCRIBE refresh, only indicate the current
version of the XML document. They do not contain the actual full
contents of the XML document. In other words, the resource being
subscribed to is NOT the XML document itself, but rather, the version
history for the document.
OPEN ISSUE: This is the main issue in this specification. There
are three potential scopes. The first is that subscription is to
the document itself, in which case a full state update in a NOTIFY
contains the current document. The second is a subscription to the
revision history, which gives you changes, but not the full state
of the document. The third option is to just subscribe to the
etag, so that you know that something changed, but the
notifications don't tell you anything about what changed. Which do
we need? The latter is the simplest, good for the case where third
party modification of documents is rare.
All subscribers and notifiers MUST support the "application/
xcap-change+xml" data format described in Section 3. The subscribe
request MAY contain an Accept header field. If no such header field
is present, it has a default value of "application/xcap-change+xml".
If the header field is present, it MUST include "application/
xcap-change+xml", and MAY include any other types capable of
representing changes in XCAP documents.
2.6 Notifier Processing of SUBSCRIBE Requests
This subsection defines package-specific processing at the notifier
when it receives a SUBSCRIBE request. General processing rules for
requests are covered in Section 8.2 of RFC 3261 [1], in addition to
general SUBSCRIBE processing in RFC 3265 [2].
A notifier for this package SHOULD authenticate all subscribers.
Generally, subscribers will have a pre-existing relationship with the
notifier. This is because the principle application of this package
is for a client of XCAP (which will have a relationship with the XCAP
server) to find out about changes in cached documents. Therefore, the
HTTP Digest mechanism in SIP is a good match for authentication, and
MUST be supported by all clients and servers. Note that this
authentication mechanism is already mandatory for all SIP-compliant
implementations.
Once authenticated, the server SHOULD authorize the subscriber.
Generally, this authorization policy SHOULD mirror the authorization
policy defined in an XCAP application usage for read access. Thats
because this package provides a form of read-access, and the
permissions should not differ based on whether the read is performed
with XCAP or with a SIP SUBSCRIBE request.
2.7 Notifier Generation of NOTIFY Requests
RFC 3265 details the formatting and structure of NOTIFY messages.
However, packages are mandated to provide detailed information on
when to send a NOTIFY, how to compute the state of the resource, how
to generate neutral or fake state information, and whether state
information is complete or partial. This section describes those
details for the presence event package.
A notifier MAY send a notification at any time. Typically, it will
send one after a document managed by an XCAP server has changed as
the result of an XCAP operation. This notification contains an
application/xcap-change+xml document that specifies the current
version (as a server modification time) for the XML document being
subscribed to. It also contains information about what changed -
whether a new element or attribute was added, whether an existing one
changed, or whether an existing one was deleted, and indicates
against which version those changes were made. The xcap-change
document also contains a hash of the new XML document.
Notifications sent in response to SUBSCRIBE requests (either initial
or refresh), or sent when there is a change in subscription state,
will normally only contain the current version of the XML document
being subscribed to.
The body of the NOTIFY MUST be sent using one of the types listed in
the Accept header field in the most recent SUBSCRIBE request, or
using the type "application/xcap-change+xml" if no Accept header
field was present.
2.8 Subscriber Processing of NOTIFY Requests
RFC 3265 [2] leaves it to event packages to describe the process
followed by the subscriber upon receipt of a NOTIFY request,
including any logic required to form a coherent resource state.
In this package, the notifications can be optionally used by the
client to determine the state of the XML document being subscribed
to. When a client receives a notification, it checks the version
against which the changes are relative. If this is not the same as
the version currently cached by the client, the client SHOULD use
XCAP to fetch the latest version of the document. If it is the same,
the client applies the change to its local cache of the document. To
apply the changes, the client follows the procedures defined by XCAP
[10] as if it were the HTTP server. After applying the changes, the
client applies the mandatory XML canonicalization defined in the
Canonical XML 1.0 [3] specification, and computes an HMAC [12] using
SHA1 over this canonical document, with a key whose value is 0x2238a.
The resulting string is compared with the hash attribute of the
xml-change document. If they match, the client can be sure that it
has the most up to date version. If they don't match, the client
SHOULD fetch the most current version of the document.
Of course, this mechanism for computing the most current document
from the hash is optional. A client can elect to ignore the
information on what changed and simply fetch the most recent document
every time it gets a change indication where the new version is not
the same as the one cached by the client.
2.9 Handling of Forked Requests
RFC 3265 [2] requires each package to describe handling of forked
SUBSCRIBE requests.
This specification only allows a single dialog to be constructed as a
result of emitting an initial SUBSCRIBE request. Section 4.4.9 of RFC
3265 [2] describes the processing that is required to guarantee the
creation of a single dialog in response to a SUBSCRIBE request.
2.10 Rate of Notifications
RFC 3265 [2] requires each package to specify the maximum rate at
which notifications can be sent. A notifier SHOULD NOT generate
notifications at a rate of more than once every five seconds.
2.11 State Agents
RFC 3265 [2] requires each package to consider the role of state
agents in the package, and if they are used, to specify how
authentication and authorization are done.
State agents play no role in this package.
3. application/xml-change+xml Media Type
An xml-change document is an XML [4] document that MUST be
well-formed and SHOULD be valid. XML-change documents MUST be based
on XML 1.0 and MUST be encoded using UTF-8. This specification makes
use of XML namespaces for identifying xml-change documents and
document fragments. The namespace URI for elements defined by this
specification is a URN [5], using the namespace identifier 'ietf'
defined by [7] and extended by [8]. This URN is:
urn:ietf:params:xml:ns:xml-change
An xml-change document begins with the root element tag "documents".
It consists of any number of "document" sub-elements, each of which
conveys information on a particular document. Other elements from
different namespaces MAY be present for the purposes of
extensibility; elements or attributes from unknown namespaces MUST be
ignored.
Each "document" element consists of zero or more "change" elements, To resolve this problem, this document defines a data format which
each of which conveys information about a specific change to the can convey changes in XML documents managed by an XCAP server. This
document. Other elements from different namespaces MAY be present for data format is an XML document format, called an XCAP diff document.
the purposes of extensibility; elements or attributes from unknown This specification also explains how this format is used in
namespaces MUST be ignored. There are four attributes associated with conjunction with the configuration profile framework.
the "document" element:
uri: specifies the HTTP URI that identifies the document. 2. Structure of an XCAP Diff Document
new-etag: specifies the etag of the document after the application of An XCAP diff document is an XML [2] document that MUST be well-formed
the change. This attribute is mandatory. and SHOULD be valid. XML-change documents MUST be based on XML 1.0
and MUST be encoded using UTF-8. This specification makes use of XML
namespaces for identifying xml-change documents and document
fragments. The namespace URI for elements defined by this
specification is a URN [3], using the namespace identifier 'ietf'
defined by [5] and extended by [6]. This URN is:
urn:ietf:params:xml:ns:xcap-diff
previous-etag: specifies the etag of the version of the document An XCAP diff document begins with the root element tag <xcap-diff>.
against which the change was made. This attribute MUST be present This element has a single mandatory attribute, "xcap-root". The
if any change sub-elements are present. value of this attribute is the XCAP root URI in which the changes
have taken place. A single XCAP diff document can only represent
changes in documents within the same XCAP root. The content of the
<xcap-diff> element is a sequence of <document> elements. Each
<document> element specifies changes in a specific document within
the XCAP root. It has three mandatory attributes - "new-etag",
"previous-etag" and "doc-selector", and a single optional attribute,
"hash". The "doc-selector" identifies the specific document within
the XCAP root for which changes are included. Its content MUST be a
relative path reference, with the base URL being equal to the XCAP
root URL. The "previous-etag" and "new-etag" provide indentifiers
for the document instance before the change, and then after the
change. These need not have been sequentially assigned etags at the
server. An XCAP diff document can describe changes that have
occurred over a series of XCAP operations.
hash: specifies an HMAC of the new document, represented in canonical The optional "hash" attribute provides an HMAC of the new document,
form. See Section 2.8 for details on how this value is computed. represented in canonical form. See Section 5 for details on how this
This attribute MUST be present if any change sub-elements are value is computed. This attribute is optional, and a server can
present. elect not to include it.
Each "change" element contains text. This text contains the exact Each <document> element is followed by a series of operations, which
value present in the HTTP request that caused the change in the if followed by the client, will convert the document whose etag is
document. If that content was XML, it is represented in the "previous-etag" into the one whose etag is "new-etag". Each
xml-change document as CDATA. There are two attributes associated operation is specified by an XML element. Six operations are
with this element: defined:
<add-element>: Instructs the recipient of the document to add an
element. The "parent" attribute contains a node-selector which
selects the parent of the new element. The "position" attribute
indicates that the new element is to be inserted as a child such
that it has that position amongst it siblings. The content of
<add-element> MUST be a CDATA section enclosing a single XML
element, which is to be added.
uri: contains the URI that the HTTP request contained in the <add-attribute>: Instructs the recipient of the document to add an
Request-URI. This attribute is mandatory. attribute. The "element" attribute contains a node-selector which
selects the element into which the attribute is to be inserted.
The "att-name" attribute contains the name of the new attribute.
The content of <add-attribute> is the value of the new attribute.
<remove-element>: Instructs the recipient of the document to delete
an element. The "element" attribute contains a node-selector
which selects the element to be removed.
<remove-attribute>: Instructs the recipient of the document to remove
an attribute. The "element" attribute contains a node-selector
which selects the element in which the attribute exists. The
"att-name" attribute indicates the name of the attribute which is
to be removed.
<replace-element>: Instructs the recipient of the document to replace
an element. The "element" attribute contains a node-selector
which selects the element to replace. The content of the
<replace-element> element MUST be a CDATA section containing
single XML element which is to replace the one identified by the
node-selector.
<replace-attribute>: Instructs the recipient of the document to
replace an attribute. The "element" attribute contains a
node-selector which selects the element to replace. The
"att-name" attribute contains the name of the attribute to
replace. The content of the <replace-attribute> element is the
value of the new attribute.
method: contains the method of the HTTP request. This attribute is When the node selector appears as an attribute value, any quotation
mandatory. marks MUST be replaced with &quot;.
OPEN ISSUE: Probably it would be better to describe the changes It is possible for the list of instructions for a <document> to be
more generically, rather than binding them to the specifics of empty. In that case, the entity tag in the "new-etag" may equal the
XCAP. Indeed, if there is any non-determinism in how the server entity tag in the "previous-etag". These entity tags may differ in
computes the document resulting from an XCAP operation, this the event that the document has changed entity tags, but its content
approach will not work. We can either use patch or define a has not been altered.
specific XML patch format.
3.1 XML Schema 3. XML Schema
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:xml-change" <xs:schema targetNamespace="urn:ietf:params:xml:ns:xcap-diff"
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="urn:ietf:params:xml:ns:xcap-diff"
xmlns:tns="urn:ietf:params:xml:ns:xml-change" xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified"> elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="documents"> <xs:element name="xcap-diff">
<xs:complexType> <xs:complexType>
<xs:sequence> <xs:sequence>
<xs:element name="tns:document" maxOccurs="unbounded"> <xs:element name="document" maxOccurs="unbounded">
<xs:complexType> <xs:complexType>
<xs:sequence> <xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:element name="tns:change" type="xs:string" maxOccurs="unbounded"/> <xs:choice>
<xs:any namespace="##other" processContents="lax" minOccurs="0" <xs:element name="add-element">
maxOccurs="unbounded"/> <xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="parent" type="xs:string" use="required"/>
<xs:attribute name="position" type="xs:int" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="add-attribute">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="element" type="xs:string" use="required"/>
<xs:attribute name="att-name" type="xs:string" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="remove-element">
<xs:complexType>
<xs:attribute name="element" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="remove-attribute">
<xs:complexType>
<xs:attribute name="element" type="xs:string" use="required"/>
<xs:attribute name="att-name" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="replace-element">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="element" type="xs:string" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="replace-attribute">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="element" type="xs:string" use="required"/>
<xs:attribute name="att-name" type="xs:string" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:sequence> </xs:sequence>
<xs:attribute name="tns:uri" type="xs:anyURI" use="required"/> <xs:attribute name="doc-selector" type="xs:anyURI" use="required"/>
<xs:attribute name="tns:new-etag" type="xs:string" use="required"/> <xs:attribute name="new-etag" type="xs:string" use="required"/>
<xs:attribute name="tns:previous-etag" type="xs:string" use="optional"/> <xs:attribute name="previous-etag" type="xs:string" use="required"/>
<xs:attribute name="tns:hash" type="xs:string" use="optional"/> <xs:attribute name="hash" type="xs:string" use="optional"/>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence> </xs:sequence>
<xs:attribute name="xcap-root" type="xs:anyURI" use="required"/>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:simpleType name="httpMethod">
<xs:restriction base="xs:string">
<xs:enumeration value="PUT"/>
<xs:enumeration value="DELETE"/>
</xs:restriction>
</xs:simpleType>
</xs:schema> </xs:schema>
3.2 Example Document 4. Example Document
The following is an example of a document compliant to the schema: The following is an example of a document compliant to the schema:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<documents xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
uri="http://xcap.example.com/s/presence-lists/users/bill/foo.xml" <document doc-selector="resource-lists/users/joe/friends"
new-etag="asdnasd9asd8asd7" new-etag="7hahsd" previous-etag="7hahsd"/>
previous-etag="s99s99s9s9sjja" <document doc-selector="resource-lists/users/joe/coworkers"
hash="<hash value>"> new-etag="ffds66a" previous-etag="xkkkaisu">
<change method="DELETE" <add-element parent="resource-lists/list[@name=&quot;l1&quot;]"
uri="http://xcap.example.com/s/presence-lists/ position="1"><![CDATA[<entry uri="sip:new-worker@example.com"/>]
users/bill/foo.xml?presence-lists/entry[@name="bob"]/uri"/> ]></add-element>
</document> </document>
</documents> </xcap-diff>
4. Security Considerations 5. Usage with the Config Framework
The security considerations for this package are similar to those of The framework for user agent profile delivery [8] defines an event
XCAP. The configuration data can contain sensitive information, and package which can be used to subscribe to user, device, application
both the client and the server need to authenticate each other. As or local-network data. This data can be present in an XCAP server.
such, a notifier for this package MUST support HTTP Digest to Normally, content indirection [14] will be used as the NOTIFY body
authenticate subscribers. Notifiers and subscribers MAY use SIPs S/ format, to indicate the specific document that has changed, and
MIME feature to provide authentication and message integrity. should be re-fetched. However, if the client includes an Accept
header field including the MIME type "application/xcap-diff+xml", the
server has the option of returning documents in this format instead.
5. IANA Considerations When the client performs an initial subscription, the rules in [8]
are used to select the set of documents which the subscription
applies to. Upon initial subscription, the server does not know
which instance (where each instance is identified by an etag) the
client currently posessses, if any. Indeed, upon startup, the client
will not have any documents. The initial NOTIFY in this case MUST
include a <document> element for each document associated with the
subscription. The content of each of those <document> elements MUST
be empty. The "previous-etag" and "new-etag" attributes MUST be
identical, and contain the entity tag for the current version of that
resource. An XML diff document structured this way is called a
"reference" XML diff document. It establishes the baseline etags and
document URIs for the documents covered by the subscription.
There are several IANA considerations associated with this Upon receipt of this document, the client can determine whether its
specification. local instance documents, if any, match the etags in the XCAP diff
document. If they do not match, the client SHOULD perform a
conditional GET for each document. The document URI is constructed
by appending the XCAP root in the "xcap-root" attribute of the
<xcap-diff> element to the escape coded "doc-selector" from each
<document> element. The request is made conditional by including an
If-Match header field, with the value of the etag from each
<document> element. So long as the documents haven't changed between
the NOTIFY and the GET, the client will obtain the reference versions
that the server will use for subsequent notifications.
5.1 SIP Event Package If the conditional GET should fail, the client SHOULD generate a
SUBSCRIBE refresh request to trigger a new NOTIFY. The server will
always generate a "reference" XML diff document on receipt of a
SUBSCRIBE refresh. This establish a new set of baseline etags, and
the client can then attempt to do another fetch. It is anticipated
that future extensions to the profile delivery framework will allow a
client to include, in its SUBSCRIBE request, an indicator of the
current version of the documents it holds. That would obviate the
need for a potentially never-ending stream of SUBSCRIBE/GET sequences
should the documents be rapidly changing, for some reason.
This specification registers an event package, based on the Once the client has obtained the versions of the documents identified
registration procedures defined in RFC 3265 [2]. The following is the in the reference XML diff, it can process NOTIFY requests on that
information required for such a registration: subscription. To process the NOTIFY requests, it makes sure that its
current version matches the version in the "previous-etag" attribute
of the <document> element. It then follows the list of instructions,
in order, for that <document>. Specifically:
<add-element>: The "parent" attribute contains a node-selector. The
client applies the node selector to the document according to the
procedures defined in XCAP [7]. If the result is a single
element, the client takes the content of the <add-element> element
and adds it as the position-th child. If the node selector doesnt
select a single element, or the selected element has fewer than
position-1 children already, the result is an error. The client
MUST discard the XCAP-diff document, and MUST flush its current
version of the document from memory. It can then obtain a new XML
diff reference by sending a SUBSCRIBE refresh request on the
dialog.
<add-attribute>: The "element" attribute contains a node-selector.
The client applies the node selector to the document according to
the procedures defined in XCAP [7]. If the result is a single
element, the client takes adds a new attribute to the element,
with the name equal to the content of the "att-name" attribute,
and a value equal to the content of the <add-attribute> element.
If the node selector doesnt select a single element, or the
selected element already has an attribute with that name, the
result is an error. The client MUST discard the XCAP-diff
document, and MUST flush its current version of the document from
memory. It can then obtain a new XML diff reference by sending a
SUBSCRIBE refresh request on the dialog.
<remove-element>: The "element" attribute contains a node-selector.
The client applies the node selector to the document according to
the procedures defined in XCAP [7]. If the result is a single
element, the client removes that element from the document. If
the node selector doesnt select a single element the result is an
error. The client MUST discard the XCAP-diff document, and MUST
flush its current version of the document from memory. It can
then obtain a new XML diff reference by sending a SUBSCRIBE
refresh request on the dialog.
<remove-attribute>: The "element" attribute contains a node-selector.
The client applies the node selector to the document according to
the procedures defined in XCAP [7]. If the result is a single
element, the client removes the attribute whose name is
"att-name". If the node selector doesnt select a single element,
or the selected element doesn't have an attribute with that name,
the result is an error. The client MUST discard the XCAP-diff
document, and MUST flush its current version of the document from
memory. It can then obtain a new XML diff reference by sending a
SUBSCRIBE refresh request on the dialog.
Package Name: xml-change <replace-element>: The "element" attribute contains a node-selector.
The client applies the node selector to the document according to
the procedures defined in XCAP [7]. If the result is a single
element, the client removes that element, and replaces it with the
content of the <add-element> element. If the node selector doesnt
select a single element, the result is an error. The client MUST
discard the XCAP-diff document, and MUST flush its current version
of the document from memory. It can then obtain a new XML diff
reference by sending a SUBSCRIBE refresh request on the dialog.
<replace-attribute>: The "element" attribute contains a
node-selector. The client applies the node selector to the
document according to the procedures defined in XCAP [7]. If the
result is a single element, the client removes the content of the
attribute whose name is "att-name", and replaces it with the
content of the <replace-attribute> element. If the node selector
doesnt select a single element, or the selected element doesn't
have an attribute with that name, the result is an error. The
client MUST discard the XCAP-diff document, and MUST flush its
current version of the document from memory. It can then obtain a
new XML diff reference by sending a SUBSCRIBE refresh request on
the dialog.
Package or Template-Package: This is a package. Once the client has finished applying the instructions to the
document, it should end up with the same document the server has. To
verify this, the client applies the mandatory XML canonicalization
defined in the Canonical XML 1.0 [1] specification, and computes an
HMAC [12] using SHA1 over this canonical document, with a key whose
value is 0x2238a. The resulting string is compared with the "hash"
attribute of the <document> element. If they match, the client can
be sure that it has the most up to date version. If they don't
match, the client MUST flush its current version of the document from
memory. It can then obtain a new XML diff reference by sending a
SUBSCRIBE refresh request on the dialog.
Published Document: RFC XXXX (Note to RFC Editor: Please fill in XXXX Of course, this mechanism for computing the most current document
with the RFC number of this specification). from the hash is optional. A client can elect to ignore the
information on what changed and simply fetch the most recent document
every time it gets a change indication where the new version is not
the same as the one cached by the client. Furthermore, the server
may elect to not send the hash, in which case this check cannot be
made.
Person to Contact: Jonathan Rosenberg, jdrosen@jdrosen.net. 6. Security Considerations
5.2 application/xcap-change+xml MIME Type XCAP diff documents contain the same information in the documents
whose differences they describe. As such, the security
considerations associated with those documents apply to XCAP diff
documents.
MIME media type name: application 7. IANA Considerations
MIME subtype name: xcap-change+xml There are several IANA considerations associated with this
specification.
7.1 application/xcap-diff+xml MIME Type
MIME media type name: application
MIME subtype name: xcap-diff+xml
Mandatory parameters: none Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml as Optional parameters: Same as charset parameter application/xml as
specified in RFC 3023 [6]. specified in RFC 3023 [4].
Encoding considerations: Same as encoding considerations of Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023 [6]. application/xml as specified in RFC 3023 [4].
Security considerations: See Section 10 of RFC 3023 [4] and
Security considerations: See Section 10 of RFC 3023 [6] and Section 6 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace
Section 4 of this specification. XXXX with the RFC number of this specification.]].
Interoperability considerations: none. Interoperability considerations: none.
Published specification: This document. Published specification: This document.
Applications which use this media type: This document type has Applications which use this media type: This document type has
been used to support manipulation of presence lists [13] using been used to support manipulation of resource lists [13] using
XCAP. XCAP.
Additional Information: Additional Information:
Magic Number: None Magic Number: None
File Extension: .xdf or .xml
File Extension: .xcd or .xml
Macintosh file type code: "TEXT" Macintosh file type code: "TEXT"
Personal and email address for further information: Jonathan Personal and email address for further information: Jonathan
Rosenberg, jdrosen@jdrosen.net Rosenberg, jdrosen@jdrosen.net
Intended usage: COMMON Intended usage: COMMON
Author/Change controller: The IETF. Author/Change controller: The IETF.
5.3 URN Sub-Namespace Registration for 7.2 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:xcap-diff
urn:ietf:params:xml:ns:xcap-change
This section registers a new XML namespace, as per the guidelines in This section registers a new XML namespace, as per the guidelines in
[8] [6]
URI: The URI for this namespace is URI: The URI for this namespace is
urn:ietf:params:xml:ns:xcap-change. urn:ietf:params:xml:ns:xcap-diff.
Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org),
Registrant Contact: IETF, SIMPLE working group, Jonathan Rosenberg (jdrosen@jdrosen.net).
(simple@mailman.dynamicsoft.com), Jonathan Rosenberg
(jdrosen@jdrosen.net).
XML: XML:
BEGIN BEGIN
<?xml version="1.0"?> <?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN" <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd"> "http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"> <html xmlns="http://www.w3.org/1999/xhtml">
<head> <head>
<meta http-equiv="content-type" <meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/> content="text/html;charset=iso-8859-1"/>
<title>XCAP Change Namespace</title> <title>XCAP Diff Namespace</title>
</head> </head>
<body> <body>
<h1>Namespace for XCAP Change</h1> <h1>Namespace for XCAP Diff</h1>
<h2>urn:ietf:params:xml:ns:change-xml</h2> <h2>urn:ietf:params:xml:ns:xcap-diff</h2>
<p>See <a href="[[[URL of published RFC]]]">RFCXXXX</a>.</p> <p>See <a href="[URL of published RFC]">RFCXXXX[[NOTE
TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this
specification.]]</a>.</p>
</body> </body>
</html> </html>
END END
Normative References 7.3 Schema Registration
[1] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., This section registers a new XML schema per the procedures in [6].
Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP: URI: urn:ietf:params:xml:schema:xcap-diff
Session Initiation Protocol", RFC 3261, June 2002. Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org),
Jonathan Rosenberg (jdrosen@jdrosen.net).
The XML for this schema can be found as the sole content of
Section 3.
[2] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 8. References
Notification", RFC 3265, June 2002.
[3] Boyer, J., "Canonical XML Version 1.0", W3C REC 8.1 Normative References
REC-xml-c14n-20010315, March 2001.
[4] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, [1] Boyer, J., "Canonical XML Version 1.0", W3C REC
"Extensible Markup Language (XML) 1.0 (Second Edition)", W3C REC-xml-c14n-20010315, March 2001.
FirstEdition REC-xml-20001006, October 2000.
[5] Moats, R., "URN Syntax", RFC 2141, May 1997. [2] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
"Extensible Markup Language (XML) 1.0 (Second Edition)", W3C
FirstEdition REC-xml-20001006, October 2000.
[6] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC [3] Moats, R., "URN Syntax", RFC 2141, May 1997.
3023, January 2001.
[7] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC
August 1999. 3023, January 2001.
[8] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [5] Moats, R., "A URN Namespace for IETF Documents", RFC 2648,
January 2004. August 1999.
[9] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., [6] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- 2004.
HTTP/1.1", RFC 2616, June 1999.
[10] Rosenberg, J., "The Extensible Markup Language (XML) [7] Rosenberg, J., "The Extensible Markup Language (XML)
Configuration Access Protocol (XCAP)", Configuration Access Protocol (XCAP)", draft-ietf-simple-xcap-02
draft-ietf-simple-xcap-01 (work in progress), October 2003. (work in progress), February 2004.
Informative References [8] Petrie, D., "A Framework for Session Initiation Protocol User
Agent Profile Delivery", draft-ietf-sipping-config-framework-03
(work in progress), May 2004.
8.2 Informative References
[9] 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.
[10] Roach, A., "Session Initiation Protocol (SIP)-Specific Event
Notification", RFC 3265, June 2002.
[11] Roach, A., Rosenberg, J. and B. Campbell, "A Session Initiation [11] Roach, A., Rosenberg, J. and B. Campbell, "A Session Initiation
Protocol (SIP) Event Notification Extension for Resource Protocol (SIP) Event Notification Extension for Resource
Lists", draft-ietf-simple-event-list-04 (work in progress), Lists", draft-ietf-simple-event-list-04 (work in progress),
June 2003. June 2003.
[12] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing [12] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing
for Message Authentication", RFC 2104, February 1997. for Message Authentication", RFC 2104, February 1997.
[13] Rosenberg, J., "An Extensible Markup Language (XML) [13] Rosenberg, J., "An Extensible Markup Language (XML)
Configuration Access Protocol (XCAP) Usage for Presence Configuration Access Protocol (XCAP) Usage for Presence
Lists", draft-ietf-simple-xcap-list-usage-01 (work in Lists", draft-ietf-simple-xcap-list-usage-02 (work in
progress), October 2003. progress), February 2004.
[14] Olson, S., "A Mechanism for Content Indirection in Session
Initiation Protocol (SIP) Messages",
draft-ietf-sip-content-indirect-mech-03 (work in progress),
June 2003.
Author's Address Author's Address
Jonathan Rosenberg Jonathan Rosenberg
dynamicsoft dynamicsoft
600 Lanidex Plaza 600 Lanidex Plaza
Parsippany, NJ 07054 Parsippany, NJ 07054
US US
Phone: +1 973 952-5000 Phone: +1 973 952-5000
EMail: jdrosen@dynamicsoft.com EMail: jdrosen@dynamicsoft.com
URI: http://www.jdrosen.net URI: http://www.jdrosen.net
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it might or might not be available; nor does it represent that it has
has made any effort to identify any such rights. Information on the made any independent effort to identify any such rights. Information
IETF's procedures with respect to rights in standards-track and on the procedures with respect to rights in RFC documents can be
standards-related documentation can be found in BCP-11. Copies of found in BCP 78 and BCP 79.
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to Copies of IPR disclosures made to the IETF Secretariat and any
obtain a general license or permission for the use of such assurances of licenses to be made available, or the result of an
proprietary rights by implementors or users of this specification can attempt made to obtain a general license or permission for the use of
be obtained from the IETF Secretariat. such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF Executive this standard. Please address the information to the IETF at
Director. ietf-ipr@ietf.org.
Full Copyright Statement
Copyright (C) The Internet Society (2004). All Rights Reserved. Disclaimer of Validity
This document and translations of it may be copied and furnished to This document and the information contained herein are provided on an
others, and derivative works that comment on or otherwise explain it "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
or assist in its implementation may be prepared, copied, published OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
and distributed, in whole or in part, without restriction of any ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
kind, provided that the above copyright notice and this paragraph are INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
included on all such copies and derivative works. However, this INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
document itself may not be modified in any way, such as by removing WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be Copyright Statement
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an Copyright (C) The Internet Society (2004). This document is subject
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING to the rights, licenses and restrictions contained in BCP 78, and
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING except as set forth therein, the authors retain all their rights.
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgment Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is currently provided by the
Internet Society. Internet Society.
 End of changes. 88 change blocks. 
501 lines changed or deleted 446 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/