diff options
Diffstat (limited to 'doc/rfc/rfc5874.txt')
| -rw-r--r-- | doc/rfc/rfc5874.txt | 1347 |
1 files changed, 1347 insertions, 0 deletions
diff --git a/doc/rfc/rfc5874.txt b/doc/rfc/rfc5874.txt new file mode 100644 index 0000000..a5e46f7 --- /dev/null +++ b/doc/rfc/rfc5874.txt @@ -0,0 +1,1347 @@ + + + + + + +Internet Engineering Task Force (IETF) J. Rosenberg +Request for Comments: 5874 jdrosen.net +Category: Standards Track J. Urpalainen +ISSN: 2070-1721 Nokia + May 2010 + + + An Extensible Markup Language (XML) Document Format for + Indicating a Change in + XML Configuration Access Protocol (XCAP) Resources + +Abstract + + This specification defines a document format that can be used to + indicate that a change has occurred in a document managed by the + Extensible Markup Language (XML) Configuration Access Protocol + (XCAP). This format reports which document has changed and its + former and new entity tags. It can report the differences between + versions of the document, using an XML patch format. It can report + existing element and attribute content when versions of an XCAP + server document change. XCAP diff documents can be delivered to diff + clients using a number of means, including a Session Initiation + Protocol (SIP) event package. + +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/rfc5874. + +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 + + + +Rosenberg & Urpalainen Standards Track [Page 1] + +RFC 5874 XCAP Diff Format May 2010 + + + 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. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 5 + 4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5. Example Document . . . . . . . . . . . . . . . . . . . . . . . 11 + 6. Basic Requirements for a System Exchanging XCAP Diff + Documents . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 + 8.1. application/xcap-diff+xml MIME Type . . . . . . . . . . . 14 + 8.2. URN Sub-Namespace Registration for + urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 15 + 8.3. Schema Registration . . . . . . . . . . . . . . . . . . . 15 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 16 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 17 + Appendix A. Informative Examples . . . . . . . . . . . . . . . . 18 + A.1. Indicating Existing, Changed, or Removed Documents . . . . 18 + A.2. Indicating Actual Changes of Documents . . . . . . . . . . 21 + A.3. Indicating XCAP Component Contents . . . . . . . . . . . . 23 + + + + + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 2] + +RFC 5874 XCAP Diff Format May 2010 + + +1. Introduction + + The Extensible Markup Language (XML) Configuration Access Protocol + (XCAP) [RFC4825] is a protocol that allows XCAP clients to manipulate + XML documents stored on a server. These XML documents serve as + configuration information for application protocols. As an example, + resource list [RFC4662] subscriptions (also known as presence lists) + allow a SIP 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 for those users and report it back to the SIP client. + This application requires the server, called a Resource List Server + (RLS), to have access to the list of presentities [RFC2778]. This + list needs to be manipulated by XCAP clients so they can add and + remove their friends as they desire. + + Complexities arise when multiple XCAP clients attempt to + simultaneously manipulate a document, such as a presence list. + Frequently, an XCAP client will keep a copy of the current list in + memory, so it can render it to users. However, if another XCAP + client modifies the document, the cached version becomes stale. This + modification event must be made known to all clients that have cached + copies of the document, so that they can fetch the most recent one. + + To deal with this problem, clients can use a Session Initiation + Protocol (SIP) [RFC3261] event package [RFC3265] to subscribe to + change events [RFC5875] in XCAP documents. This notification needs + to indicate the specific resource that changed and how it changed. + One solution for the format of such a change notification would be a + content indirection object [RFC4483]. Though content indirection can + tell a client that a document has changed, it provides it with a MIME + Content-ID indicating the new version of the document. The MIME + Content-ID is not the same as the entity tag, which is used by XCAP + for document versioning. As such, a client cannot easily ascertain + whether an indication of a change in a document is due to a change it + just made or due to a change another XCAP client made at around the + same time. Furthermore, content indirections don't indicate how a + document changed; they are only able to indicate that it did change. + + To resolve these problems, this document defines a data format that + can convey the fact that an XML document managed by XCAP has changed. + This data format is an XML document format, called an XCAP diff + document. This format reports which document has changed and its + former and new entity tags. It can report the differences between + versions of the document, using an XML patch format [RFC5261], which + indicate how to transform the locally cached XCAP document from the + version prior to the change to the version after it. Its intent is + to reduce the required overall bandwidth and the number of separate + + + + +Rosenberg & Urpalainen Standards Track [Page 3] + +RFC 5874 XCAP Diff Format May 2010 + + + transmissions. It can also report existing element and attribute + content when versions of an XML document change at an XCAP server. + + XML documents that are equivalent for the purposes of many + applications may differ in their physical representation. Similar to + XCAP, the canonical form with comments [W3C.REC-xml-c14n-20010315] of + an XML document determines the logical equivalence when this format + is used to patch locally cached XCAP documents. + +2. Terminology + + 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 RFC 2119 [RFC2119] and + indicate requirement levels for compliant implementations. + + This specification also defines the following additional terms: + + Document: When the term document is used without the "(XCAP) diff" + in front of it, it refers to the XCAP document resource about + which the XCAP diff document is reporting a change. + + Diff document: The XML document defined by this specification that + reports on a set of changes in an XCAP document resource. It is + delivered from a server to a diff client by a transport that is + not defined by this specification. + + XCAP server: A protocol entity that manages XCAP documents and their + entity tags. It usually contains an integrated diff notifier. + + Diff notifier: This is the entity of a server that generates XCAP + diff documents based on its knowledge of a set of XCAP documents + and their changes, and it transmits the generated diff documents + to a diff client within a session. + + Diff client: A client that consumes XCAP diff documents in order to + construct a locally cached document that is equivalent to a + specific version of a document resource stored at an XCAP server. + It is typically a SIP User Agent (UA) and an XCAP client. + + XCAP Client: A client that updates and retrieves documents stored at + an XCAP server. It can also patch element and attribute content + of XCAP documents located at an XCAP server. + + Locally cached resource: A resource that has typically been + downloaded by HTTP from an XCAP server to a diff client. It may + have been patched locally by a diff client based on the XCAP diff + document information. It is equivalent to a single version in its + + + +Rosenberg & Urpalainen Standards Track [Page 4] + +RFC 5874 XCAP Diff Format May 2010 + + + change history at an XCAP server. Version history of XCAP + documents is indicated by HTTP entity tags (ETags). + + ETag: A strong HTTP entity tag whose value is set by an XCAP server. + Documents at an XCAP server are updated by XCAP clients. The XCAP + server assigns a new ETag value to each document version according + to the HTTP specification. + +3. Structure of an XCAP Diff Document + + An XCAP diff document is an XML [W3C.REC-xml-20060816] document that + MUST be well-formed and SHOULD be valid. XCAP diff documents MUST be + based on XML 1.0 and MUST be encoded using UTF-8. This specification + makes use of XML namespaces for identifying XCAP diff documents and + document fragments. The namespace URI for elements defined by this + specification is a URN [RFC2141], using the namespace identifier + 'ietf' defined by [RFC2648] and extended by [RFC3688]. This URN is: + + urn:ietf:params:xml:ns:xcap-diff + + An XCAP diff document begins with the root element tag <xcap-diff>. + This element has a single mandatory attribute, "xcap-root". The + value of this attribute is the XCAP root URI for the documents 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>, + <element>, and <attribute> elements followed by any number of + elements from other namespaces for the purposes of extensibility. + Wherever the XML schema (see Section 4) allows extension elements or + attributes, any such unknown content MUST be ignored by the diff + client. + + Each <document> element specifies changes in a specific document + within the XCAP root. If several <document> elements pinpoint the + same specific document, i.e., for example, the full entity tag (ETag) + change history is indicated, the corresponding patches MUST be able + to be applied in the given XCAP diff document order. + + Note: This requirement simplifies applications that process XCAP + diff documents since there's no need to sort patch instructions + when applying them. + + The <document> element has one mandatory attribute, "sel", and two + optional attributes, "new-etag" and "previous-etag". The "sel" + attribute of the <document> element identifies the specific document + within the XCAP root for which changes are indicated. Its content + MUST be a relative path reference, with the base URI being equal to + the XCAP root URI. The "new-etag" attribute provides the entity tag + + + +Rosenberg & Urpalainen Standards Track [Page 5] + +RFC 5874 XCAP Diff Format May 2010 + + + (ETag) for the document after the application of the changes, + assuming the document exists after those changes. The "previous- + etag" attribute provides an identifier for the document instance + prior to the change. If the change being reported is the removal of + a document, only the "previous-etag" MUST be included and the "new- + etag" attribute MUST NOT be present. The "new-etag" attribute MUST + only exist alone when the document either exists or it was just + created (no patch included). Both attributes are present when a + patch (or series of XCAP operations) has been applied to the + resource. Also, both attributes MAY be used to indicate an ETag + change without any document modifications (patches). + + The "previous-etag" and "new-etag" need not have been sequentially + assigned ETags at the server. An XCAP diff document can indicate + changes that have occurred over a series of XCAP operations. The + only requirement then is that the sequence of events, when executed + serially, will result in the transformation of the document with the + ETag "previous-etag" to the one whose ETag is "new-etag". Also, the + series of operations do not have to be the same exact series of + operations that occurred at the server. + + Each <document> element contains either a sequence of patching + instructions or an indication that the body hasn't semantically + changed. The latter means that the document has been assigned a new + ETag but its content is unchanged and it is indicated by the <body- + not-changed> element. Patching instructions are described by the + <add>, <replace>, and <remove> elements. These elements use the + corresponding add, replace, and remove types defined in [RFC5261], + and define a set of patch operations that can be applied to transform + the locally cached document. See [RFC5261] for instructions on how + this transformation is effected. The <document> element can also + contain elements from other namespaces for the purposes of + extensibility. The <add>, <replace>, and <remove> elements allow + extension attributes from any namespace. + + Figure 1 shows <document> element content and how the corresponding + resource or metadata changes. In practice, an external document + retrieval means HTTP GET requests for target resources. The asterisk + character '*' means that a <document> element has child element(s): + <add>, <replace>, or <remove>, or alternatively only a <body-not- + changed> element. The hyphen character '-' means that the + corresponding content (attribute or element) doesn't exist in a + <document> element. The 'xxx' and 'yyy' are values of entity tags + (ETag) of an XCAP document. + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 6] + +RFC 5874 XCAP Diff Format May 2010 + + + +-----------+----------+-----------+----------+-------------------+ + | previous- | new- | <add> | <body- | locally cached | + | etag | etag | <replace> | not- | XCAP resource/ | + | | | <remove> | changed> | metadata change | + +-----------+----------+-----------+----------+-------------------+ + | xxx | yyy | * | - | resource patched, | + | | | | | patch included | + +-----------+----------+-----------+----------+-------------------+ + | xxx | yyy | - | - | resource patched, | + | | | | | external document | + | | | | | retrieval | + +-----------+----------+-----------+----------+-------------------+ + | xxx | yyy | - | * | only ETag changed | + +-----------+----------+-----------+----------+-------------------+ + | - | yyy | - | - | resource created | + | | | | | or exists, | + | | | | | external document | + | | | | | retrieval | + +-----------+----------+-----------+----------+-------------------+ + | xxx | - | - | - | resource removed | + +-----------+----------+-----------+----------+-------------------+ + + Figure 1: <document> element content / corresponding resource changes + + Each <element> element indicates the existing element content of an + XCAP document. It has one mandatory attribute, "sel", and + optionally, an "exists" attribute and extension attributes from any + namespace. The "sel" attribute of the <element> element identifies + an XML element of an XCAP document. It is a percent-encoded relative + URI following XCAP conventions when selecting elements. The XCAP + Node Selector MUST always locate a unique node, the "exists" + attribute thus shows whether an element exists or not in the XCAP + document. When the "exists" attribute is absent from the <element> + element, the indicated element still exists in the XCAP document. + The located element exists as a child element of the <element> + element. In a corner case where the content of this element cannot + be presented for some reason (e.g., the payload is too large) + although it exists in the XCAP document, the <element> element MUST + NOT have any child nodes. + + As the located XML element is typically namespace qualified, all + needed namespace declarations MUST exist within the <xml-diff> + document. The possible local namespace declarations within the + located element exist unmodified as in the source document, similar + to XCAP conventions. Other namespace references MUST be resolved + from the context of the <element> or its parent elements. The + + + + + +Rosenberg & Urpalainen Standards Track [Page 7] + +RFC 5874 XCAP Diff Format May 2010 + + + prefixes of qualified names (QNames) [W3C.REC-xml-names-20060816] of + XML nodes also remain as they originally exist in the source XCAP + document. + + Each <attribute> element indicates the existing attribute content of + an XCAP document. It has one mandatory attribute, "sel", and + optionally, an "exists" attribute and extension attributes from any + namespace. The "sel" attribute of the <attribute> element identifies + an XML attribute of an XCAP document. It is a percent-encoded + relative URI following XCAP conventions when selecting attributes. + The "exists" attribute indicates whether or not an attribute exists + in the XCAP document. When the "exists" attribute is absent from the + <attribute> element, the indicated attribute still exists in the XCAP + document. The child text node of the <attribute> element indicates + the value of the located attribute. Note that if the attribute is + namespace qualified, the query parameter of the XCAP URI indicates + the attached namespace URI and the prefix in the XCAP source + document. + + Namespaces of the "sel" attribute of the <attribute> and <element> + elements MUST also be resolved properly. Section 6.4. of [RFC4825] + describes the rules when using namespace prefixes in XCAP Node + Selectors. Without a namespace prefix in an element selector, an + XCAP Default Document Namespace MUST be applied. The namespace + resolving rules of Patch operation elements: <add>, <replace>, and + <remove> are described in Section 4.2.1 of [RFC5261]. + +4. XML Schema + + The XML Schema for the XCAP diff format. + + <?xml version="1.0" encoding="UTF-8"?> + <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns="urn:ietf:params:xml:ns:xcap-diff" + targetNamespace="urn:ietf:params:xml:ns:xcap-diff" + elementFormDefault="qualified" + attributeFormDefault="unqualified"> + + <!-- include patch-ops --> + <xs:include + schemaLocation="urn:ietf:params:xml:schema:patch-ops"/> + + <!-- document root --> + <xs:element name="xcap-diff"> + <xs:complexType> + <xs:sequence minOccurs="0"> + <xs:sequence minOccurs="0" maxOccurs="unbounded"> + <xs:choice> + + + +Rosenberg & Urpalainen Standards Track [Page 8] + +RFC 5874 XCAP Diff Format May 2010 + + + <xs:element name="document" type="documentType"/> + <xs:element name="element" type="elementType"/> + <xs:element name="attribute" type="attributeType"/> + </xs:choice> + </xs:sequence> + <xs:any namespace="##other" processContents="lax" + minOccurs="0" maxOccurs="unbounded"/> + </xs:sequence> + <xs:attribute name="xcap-root" type="xs:anyURI" use="required"/> + <xs:anyAttribute processContents="lax"/> + </xs:complexType> + </xs:element> + + <!-- xcap document type --> + <xs:complexType name="documentType"> + <xs:choice minOccurs="0"> + <xs:element name="body-not-changed" type="emptyType"/> + <xs:sequence minOccurs="0" maxOccurs="unbounded"> + <xs:choice> + <xs:element name="add"> + <xs:complexType mixed="true"> + <xs:complexContent> + <xs:extension base="add"> + <xs:anyAttribute processContents="lax"/> + </xs:extension> + </xs:complexContent> + </xs:complexType> + </xs:element> + <xs:element name="remove"> + <xs:complexType> + <xs:complexContent> + <xs:extension base="remove"> + <xs:anyAttribute processContents="lax"/> + </xs:extension> + </xs:complexContent> + </xs:complexType> + </xs:element> + <xs:element name="replace"> + <xs:complexType mixed="true"> + <xs:complexContent> + <xs:extension base="replace"> + <xs:anyAttribute processContents="lax"/> + </xs:extension> + </xs:complexContent> + </xs:complexType> + </xs:element> + <xs:any namespace="##other" processContents="lax"/> + </xs:choice> + + + +Rosenberg & Urpalainen Standards Track [Page 9] + +RFC 5874 XCAP Diff Format May 2010 + + + </xs:sequence> + </xs:choice> + <xs:attribute name="sel" type="xs:anyURI" use="required"/> + <xs:attribute name="new-etag" type="xs:string"/> + <xs:attribute name="previous-etag" type="xs:string"/> + <xs:anyAttribute processContents="lax"/> + </xs:complexType> + + <!-- xcap element type --> + <xs:complexType name="elementType"> + <xs:complexContent mixed="true"> + <xs:restriction base="xs:anyType"> + <xs:sequence> + <xs:any processContents="lax" namespace="##any" + minOccurs="0" maxOccurs="1"/> + </xs:sequence> + <xs:attribute name="sel" type="xs:string" + use="required"/> + <xs:attribute name="exists" type="xs:boolean"/> + <xs:anyAttribute processContents="lax"/> + </xs:restriction> + </xs:complexContent> + </xs:complexType> + + <!-- xcap attribute type --> + <xs:complexType name="attributeType"> + <xs:simpleContent> + <xs:extension base="xs:string"> + <xs:attribute name="sel" type="xs:string" + use="required"/> + <xs:attribute name="exists" type="xs:boolean"/> + <xs:anyAttribute processContents="lax"/> + </xs:extension> + </xs:simpleContent> + </xs:complexType> + + <!-- empty type --> + <xs:complexType name="emptyType"/> + </xs:schema> + + + + + + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 10] + +RFC 5874 XCAP Diff Format May 2010 + + +5. Example Document + + The following is an example of a document compliant to the schema. + + <?xml version="1.0" encoding="UTF-8"?> + <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" + xmlns="urn:ietf:params:xml:ns:rls-services" + xcap-root="http://xcap.example.com/root/"> + + <d:document new-etag="7ahggs" + sel="resource-lists/users/sip:joe@example.com/coworkers" + previous-etag="8a77f8d"/> + + <d:element sel="rls-services/users/sip:joe@example.com/index/~~ + /*/service%5b@uri='sip:marketing@example.com'%5d" + xmlns:rl="urn:ietf:params:xml:ns:resource-lists" + ><service uri="sip:marketing@example.com"> + <list name="marketing"> + <rl:entry uri="sip:joe@example.com"/> + <rl:entry uri="sip:sudhir@example.com"/> + </list> + <packages> + <package>presence</package> + </packages> + </service></d:element> + + <d:attribute + sel="rls-services/users/sip:joe@example.com/index/~~/*/service/@uri" + >sip:marketing@example.com</d:attribute> + + </d:xcap-diff> + + This indicates that the document with the URI "http:// + xcap.example.com/root/resource-lists/users/sip:joe@example.com/ + coworkers" has changed. Its previous entity tag is "8a77f8d" and its + new one is "7ahggs", but actual changes are not shown. The <service> + element exists in the rls-services "index" document and its full + content is shown. Note that the <service> element is attached with a + default namespace declaration within the original document. + Similarly, "uri" attribute content is shown from the same "index" + document as an illustrative example. + +6. Basic Requirements for a System Exchanging XCAP Diff Documents + + Documents at an XCAP server are identified by URIs, and updated by + XCAP clients with HTTP (PUT and DELETE) methods. The XCAP server + assigns a new entity tag value for each document version. An entity + tag value is defined by Section 3.11 of RFC 2616 [RFC2616]: "An + + + +Rosenberg & Urpalainen Standards Track [Page 11] + +RFC 5874 XCAP Diff Format May 2010 + + + entity tag MUST be unique across all versions of all entities + associated with a particular resource". These entity tags are used + to protect requests from making overriding changes when multiple XCAP + clients update the same XCAP document. An entity tag value can be + interpreted as a unique identifier to a specific version of an XCAP + document in its change history. + + The entity tag values of XCAP resources also enable a reliable way to + update the locally cached XCAP resource copies in an XCAP diff + implementation. When a diff client applies XCAP diff document + changes, it MUST apply a resource state change only if entity tag + values match with octet-by-octet equivalence according to the table + defined in Figure 1. If a diff client notices inconsistencies and/or + errors when it applies reported resource changes, it SHOULD tear down + the session. + + State changes of an XCAP document MUST be delivered reliably from a + diff notifier to a diff client, and a diff client MUST be able to + apply all changes of an XCAP document in the same chronological order + that occurred at an XCAP server. When using an unreliable transport + with retransmissions, the application protocol used with the XCAP + diff MUST ensure that duplicates are dropped. If an XCAP diff + delivery is lost, the diff session MUST be torn down. Note that a + diff notifier can easily notice a lost notification when a diff + client must respond to each XCAP diff delivery. + + A diff notifier doesn't necessarily report all of these XCAP document + updates with ETags; it MAY skip over some intermediate version of a + document, for example, with rapidly changing resources. However, it + MUST always report changes consistently to a diff client so that it + can properly update the latest state (content and ETag) of its + locally cached resources. + + As an example, an XCAP document is updated by different 'a', 'b', + and 'c' versions identified with the same corresponding ETag + values in a relatively short period. The first reported + notification contains the 'a' "new-tag" information (no "previous- + etag" attribute), and the diff notifier decides to skip the update + notification identified by the 'b' ETag value. The second + notification to a diff client MUST then contain the 'a' "previous- + etag" and 'c' "new-etag" values with optional corresponding + content changes (from version 'a' to 'c'). + + Since XCAP documents are typically confidential, diff notifiers MUST + obey the XCAP authorization rules. In practice, this means following + the read privilege rules of XCAP resources when notifying the + authenticated diff clients of changes. Transport SHOULD be secured + by encryption. + + + +Rosenberg & Urpalainen Standards Track [Page 12] + +RFC 5874 XCAP Diff Format May 2010 + + + Note: This format specification doesn't define how to select the + resources whose differences a diff notifier should report. It + also doesn't define whether actual content changes should be + reported. Typically, however, a diff client starts a session by + sending a resource listing request. Then it compares the remote + resource listings with locally cached ones, and probably downloads + those resources that aren't locally cached or whose entity tags + differ. When a diff client receives an XCAP diff with a + "previous-etag" value that matches its current cached copy of a + document, it can apply the diffs to the cached copy. As it takes + some time to download reference documents, and diff notifications + appear after actual resource state changes, several round trips + may be needed before a full synchronization is achieved, + especially with rapidly changing resources. + +7. Security Considerations + + XCAP diff documents can include changes from one version of a + document to another version. As a consequence, if the document + itself is sensitive and requires confidentiality, integrity, or + authentication, then the same applies to the XCAP diff format. + Therefore, protocols that transport XCAP diff documents must provide + sufficient security capabilities for transporting the document + itself. Confidential XCAP documents are typically transported using + TLS-encrypted (Transport Layer Security) [RFC5246] communication; see + RFC 4825 [RFC4825] for further security details. + + When this format is used to report content changes of XCAP documents, + all security considerations of RFC 5261 [RFC5261] apply. Very + frequent updates of XCAP documents and/or many diff clients per + subscribed resource impose a Denial-of-Service attack possibility to + the servers processing XCAP diff documents. An efficient patch + processing and throttling can, however, decrease the required overall + processings and transactions. + + The SIP event package framework specified in RFC 3265 [RFC3265] is + the most typical use-case for this format. Then, an end-to-end SIP + encryption mechanism, such as Secure/Multipurpose Internet Mail + Extensions (S/MIME) described in Section 26.2.4 of RFC 3261 + [RFC3261], SHOULD be used. If that is not available, it is + RECOMMENDED that TLS [RFC5246] be used between elements to provide + hop-by-hop authentication and encryption mechanisms as described in + Section 26.2.2 ("SIPS URI Scheme") and Section 26.3.2.2 ("Interdomain + Requests") of RFC 3261 [RFC3261]. Event packages MAY also have other + specific threats that MUST be considered on an application-by- + application basis. + + + + + +Rosenberg & Urpalainen Standards Track [Page 13] + +RFC 5874 XCAP Diff Format May 2010 + + +8. IANA Considerations + + There are several IANA considerations associated with this + specification. + +8.1. application/xcap-diff+xml MIME Type + + MIME media type name: application + + MIME subtype name: xcap-diff+xml + + Mandatory parameters: none + + Optional parameters: Same as the charset parameter application/xml as + specified in RFC 3023 [RFC3023]. + + Encoding considerations: Same as the encoding considerations of + application/xml as specified in RFC 3023 [RFC3023]. + + Security considerations: See Section 10 of RFC 3023 [RFC3023] and + Section 7 of RFC 5874. + + Interoperability considerations: none. + + Published specification: This document. + + Applications that use this media type: This document type has been + used to support manipulation of resource lists [RFC4826] using XCAP. + + Additional Information: + + Magic Number: None + + File Extension: .xdf + + Macintosh file type code: "TEXT" + + Personal and email address for further information: Jonathan + Rosenberg, jdrosen@jdrosen.net + + Intended usage: COMMON + + Author/Change controller: The IETF. + + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 14] + +RFC 5874 XCAP Diff Format May 2010 + + +8.2. URN Sub-Namespace Registration for + urn:ietf:params:xml:ns:xcap-diff + + This section registers a new XML namespace, as per the guidelines in + [RFC3688]. + + URI: The URI for this namespace is + urn:ietf:params:xml:ns:xcap-diff. + + Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), + Jonathan Rosenberg (jdrosen@jdrosen.net). + + XML: + + BEGIN + <?xml version="1.0"?> + <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN" + "http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd"> + <html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="content-type" + content="text/html;charset=iso-8859-1"/> + <title>XCAP Diff Namespace</title> + </head> + <body> + <h1>Namespace for XCAP Diff</h1> + <h2>urn:ietf:params:xml:ns:xcap-diff</h2> + <p>See <a + href="http://www.rfc-editor.org/rfc/rfc5874.txt">RFC5874</a>.</p> + </body> + </html> + END + +8.3. Schema Registration + + This section registers a new XML schema per the procedures in + [RFC3688]. + + URI: urn:ietf:params:xml:schema:xcap-diff + + 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 4. + + + + + + +Rosenberg & Urpalainen Standards Track [Page 15] + +RFC 5874 XCAP Diff Format May 2010 + + +9. Acknowledgments + + The authors would like to thank Pavel Dostal, Jeroen van Bemmel, + Martin Hynar, Anders Lindgren, Mary Barnes, Ben Campbell, Francis + Dupont, David Harrington, Alexey Melnikov, Dan Romascanu, and Robert + Sparks for their valuable comments. + +10. References + +10.1. Normative References + + [W3C.REC-xml-20060816] + Paoli, J., Bray, T., Yergeau, F., Maler, E., and C. + Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 + (Fourth Edition)", World Wide Web Consortium + FirstEdition REC-xml- 20060816, August 2006, <http:// + www.w3.org/TR/2006/REC-xml-20060816>. + + [W3C.REC-xml-c14n-20010315] + Boyer, J., "Canonical XML Version 1.0", World Wide Web + Consortium Recommendation REC-xml-c14n-20010315, + March 2001, <http://www.w3.org/TR/2001/ + REC-xml-c14n-20010315>. + + [W3C.REC-xml-names-20060816] + Hollander, D., Layman, A., and T. Bray, "Namespaces in XML + 1.0 (Second Edition)", World Wide Web Consortium + FirstEdition REC-xml-names-20060816, August 2006, + <http://www.w3.org/TR/ 2006/REC-xml-names-20060816>. + + [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. + + [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. + + [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media + Types", RFC 3023, January 2001. + + [RFC2648] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, + August 1999. + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + + + +Rosenberg & Urpalainen Standards Track [Page 16] + +RFC 5874 XCAP Diff Format May 2010 + + + [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) + Configuration Access Protocol (XCAP)", RFC 4825, May 2007. + + [RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch + Operations Framework Utilizing XML Path Language (XPath) + Selectors", RFC 5261, September 2008. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + +10.2. Informative References + + [RFC5875] Urpalainen, J. and D. Willis, "An Extensible Markup + Language (XML) Configuration Access Protocol (XCAP) Diff + Event Package", RFC 5875, May 2010. + + [RFC2778] Day, M., Rosenberg, J., and H. Sugano, "A Model for + Presence and Instant Messaging", RFC 2778, February 2000. + + [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. + + [RFC4662] Roach, A., Campbell, B., and J. Rosenberg, "A Session + Initiation Protocol (SIP) Event Notification Extension for + Resource Lists", RFC 4662, August 2006. + + [RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats + for Representing Resource Lists", RFC 4826, May 2007. + + [RFC4483] Burger, E., "A Mechanism for Content Indirection in Session + Initiation Protocol (SIP) Messages", RFC 4483, May 2006. + + + + + + + + + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 17] + +RFC 5874 XCAP Diff Format May 2010 + + +Appendix A. Informative Examples + + These informative examples illustrate basic features of XCAP diff + format. + + The following documents exist at an XCAP server (xcap.example.com) + with an imaginary "tests" application usage (there's no default + document namespace defined in this imaginary application usage). + + http://xcap.example.com/tests/users/sip:joe@example.com/index: + + <?xml version="1.0" encoding="UTF-8"?> + <doc id="bar"> + <note>This is a sample document</note> + </doc> + + and then + + http://xcap.example.com/tests/users/sip:john@example.com/index: + + <?xml version="1.0" encoding="UTF-8"?> + <doc> + <note>This is another sample document</note> + </doc> + +A.1. Indicating Existing, Changed, or Removed Documents + + Firstly, an XCAP diff document can indicate what documents exist in a + collection. An XCAP diff document may then be: + + <?xml version="1.0" encoding="UTF-8"?> + <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <document new-etag="7ahggs" + sel="tests/users/sip:joe@example.com/index"/> + + <document new-etag="terteer" + sel="tests/users/sip:john@example.com/index"/> + + </xcap-diff> + + This listing indicates current ETags of existing documents and their + relative URIs. + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 18] + +RFC 5874 XCAP Diff Format May 2010 + + + Let's say that Joe adds a new document to his collection: + + PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1 + Host: xcap.example.com + .... + Content-Type: application/xml + Content-Length: [XXX] + + <?xml version="1.0" encoding="UTF-8"?> + <doc> + <note>This is another sample document</note> + </doc> + + The requests result header has an HTTP ETag "terteer" for this new + document. + + Then an XCAP diff document may then indicate only the creation of + this single new document: + + <?xml version="1.0" encoding="UTF-8"?> + <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <document new-etag="terteer" + sel="tests/users/sip:joe@example.com/another_document"/> + + </xcap-diff> + + A "new-etag" without a "previous-etag" attribute indicates a creation + of a new document. + + Then Joe decides to modify an existing resource: + + PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1 + Host: xcap.example.com + .... + Content-Type: application/xml + Content-Length: [XXX] + + <?xml version="1.0" encoding="UTF-8"?> + <doc> + <note>This is a modified document</note> + </doc> + + The reported new HTTP ETag is "huwiias". + + + + + + +Rosenberg & Urpalainen Standards Track [Page 19] + +RFC 5874 XCAP Diff Format May 2010 + + + Then an XCAP diff document may be: + + <?xml version="1.0" encoding="UTF-8"?> + <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <document previous-etag="terteer" new-etag="huwiias" + sel="tests/users/sip:joe@example.com/another_document"/> + + </xcap-diff> + + Both "previous-etag" and "new-etag" attributes signal that a + modification has happened to a resource, but actual changes are not + shown. + + Let's say that Joe then removes a document from his collection: + + DELETE /tests/users/sip:joe@example.com/another_document HTTP/1.1 + Host: xcap.example.com + + This HTTP DELETE request results in the unlinking of the resource, + and the XCAP diff may be: + + <?xml version="1.0" encoding="UTF-8"?> + <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <document previous-etag="huwiias" + sel="tests/users/sip:joe@example.com/another_document"/> + + </xcap-diff> + + Thus, a "previous-etag" without a "new-etag" attribute indicates the + removal of a resource. + + + + + + + + + + + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 20] + +RFC 5874 XCAP Diff Format May 2010 + + +A.2. Indicating Actual Changes of Documents + + Secondly, XCAP diff documents are capable of showing actual changes + to documents with [RFC5261] patching semantics. + + Now Joe's XCAP client utilizes the XCAP patching capability to add a + new element to a document: + + PUT /tests/users/sip:joe@example.com/index/~~/doc/foo HTTP/1.1 + Host: xcap.example.com + .... + Content-Type: application/xcap-el+xml + Content-Length: [XXX] + + <foo>this is a new element</foo> + + Since the insertion of the element is successful, Joe's XCAP client + receives the new HTTP ETag "fgherhryt3" of the updated "index" + document. + + Immediately thereafter, Joe's XCAP client issues another HTTP request + (this request could even be pipelined): + + PUT /tests/users/sip:joe@example.com/index/~~/doc/bar HTTP/1.1 + Host: xcap.example.com + .... + Content-Type: application/xcap-el+xml + Content-Length: [XXX] + + <bar>this is a bar element + </bar> + + The reported new HTTP ETag of "index" is now "dgdgdfgrrr". + + And then Joe's XCAP client issues yet another HTTP request: + + PUT /tests/users/sip:joe@example.com/index/~~/doc/foobar HTTP/1.1 + Host: xcap.example.com + .... + Content-Type: application/xcap-el+xml + Content-Length: [XXX] + + <foobar>this is a foobar element</foobar> + + The reported new ETag of "index" is now "63hjjsll". + + + + + + +Rosenberg & Urpalainen Standards Track [Page 21] + +RFC 5874 XCAP Diff Format May 2010 + + + XCAP diff format document may then indicate these XCAP component + changes by: + + <?xml version="1.0" encoding="UTF-8"?> + <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <d:document previous-etag="7ahggs3" + sel="tests/users/sip:joe@example.com/index" + new-etag="63hjjsll"> + <d:add sel="*" + ><foo>this is a new element</foo><bar>this is a bar element + </bar><foobar>this is a foobar element</foobar></d:add> + </d:document> + + </d:xcap-diff> + + Note how several XCAP component modifications were aggregated + together, and full history information got lost. + + Alternatively, the content could have been: + + <?xml version="1.0" encoding="UTF-8"?> + <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <d:document previous-etag="7ahggs" + sel="tests/users/sip:joe@example.com/index" + new-etag="fgherhryt3"> + <d:add sel="*" + ><foo>this is a new element</foo></d:add></d:document> + + <d:document previous-etag="fgherhryt3" + sel="tests/users/sip:joe@example.com/index" + new-etag="dgdgdfgrrr"> + <d:add sel="*" + ><bar>this is a bar element + </bar></d:add></d:document> + + <d:document previous-etag="dgdgdfgrrr" + sel="tests/users/sip:joe@example.com/index" + new-etag="63hjjsll"> + <d:add sel="*" + ><foobar>this is a foobar element</foobar></d:add></d:document> + + </d:xcap-diff> + + + + + +Rosenberg & Urpalainen Standards Track [Page 22] + +RFC 5874 XCAP Diff Format May 2010 + + + This shows the full ETag change history of a document, and ETags + change chronologically in the reported XML document order. + +A.3. Indicating XCAP Component Contents + + Lastly, the XCAP diff format can also indicate the existing full + contents of XCAP components, i.e., elements or attributes: + + <?xml version="1.0" encoding="UTF-8"?> + <d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <d:attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id" + >bar</d:attribute> + + <d:element sel="tests/users/sip:joe@example.com/index/~~/*/foo" + ><foo>this is a new element</foo></d:element> + + </d:xcap-diff> + + Note that the HTTP ETag value of the new document is not shown as it + is irrelevant for this use-case. + + Then Joe's XCAP client removes the "id" attribute: + + DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1 + Host: xcap.example.com + .... + Content-Length: 0 + + And the XCAP diff document may then be: + + <?xml version="1.0" encoding="UTF-8"?> + <xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff" + xcap-root="http://xcap.example.com/"> + + <attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id" + exists="0"/> + + </xcap-diff> + + This indicates that the subscribed attribute was removed from the + document. The element content in this use-case may be discarded from + the XCAP diff document, for example, when the size of XCAP diff + document would be impractically large to the transport layer. + + + + + + +Rosenberg & Urpalainen Standards Track [Page 23] + +RFC 5874 XCAP Diff Format May 2010 + + +Authors' Addresses + + Jonathan Rosenberg + jdrosen.net + Monmouth, NJ + US + + EMail: jdrosen@jdrosen.net + URI: http://www.jdrosen.net + + + Jari Urpalainen + Nokia + Itamerenkatu 11-13 + Helsinki 00180 + Finland + + Phone: +358 7180 37686 + EMail: jari.urpalainen@nokia.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rosenberg & Urpalainen Standards Track [Page 24] + |