idnits 2.17.00 (12 Aug 2021) /tmp/idnits42087/draft-ietf-simple-xcap-diff-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 547. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 524. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 531. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 537. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 4 instances of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 6, 2006) is 5919 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' ** Obsolete normative reference: RFC 2141 (ref. '3') (Obsoleted by RFC 8141) ** Obsolete normative reference: RFC 3023 (ref. '4') (Obsoleted by RFC 7303) ** Downref: Normative reference to an Informational RFC: RFC 2648 (ref. '5') == Outdated reference: draft-ietf-simple-xcap has been published as RFC 4825 == Outdated reference: draft-ietf-simple-xml-patch-ops has been published as RFC 5261 -- Obsolete informational reference (is this intentional?): RFC 3265 (ref. '11') (Obsoleted by RFC 6665) == Outdated reference: draft-ietf-simple-event-list has been published as RFC 4662 == Outdated reference: draft-ietf-simple-xcap-list-usage has been published as RFC 4826 == Outdated reference: draft-ietf-sip-content-indirect-mech has been published as RFC 4483 Summary: 7 errors (**), 0 flaws (~~), 8 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIMPLE J. Rosenberg 3 Internet-Draft Cisco Systems 4 Expires: September 7, 2006 March 6, 2006 6 An Extensible Markup Language (XML) Document Format for Indicating A 7 Change in XML Configuration Access Protocol (XCAP) Resources 8 draft-ietf-simple-xcap-diff-03 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on September 7, 2006. 35 Copyright Notice 37 Copyright (C) The Internet Society (2006). 39 Abstract 41 This specification defines a document format that can be used to 42 indicate that a change has occurred in a document managed by the 43 Extensible Markup Language (XML) Configuration Access Protocol 44 (XCAP). This format indicates the document that has changed and its 45 former and new entity tags. It also can indicate the specific change 46 that was made in the document, using an XML patch format. XCAP diff 47 documents can be delivered to clients using a number of means, 48 including a Session Initiation Protocol (SIP) event package. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 4 55 4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 7 56 5. Example Document . . . . . . . . . . . . . . . . . . . . . . . 7 57 6. Usage with an Event Package . . . . . . . . . . . . . . . . . 8 58 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 60 8.1 application/xcap-diff+xml MIME Type . . . . . . . . . . . 9 61 8.2 URN Sub-Namespace Registration for 62 urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 10 63 8.3 Schema Registration . . . . . . . . . . . . . . . . . . . 11 64 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 9.1 Normative References . . . . . . . . . . . . . . . . . . . 11 66 9.2 Informative References . . . . . . . . . . . . . . . . . . 12 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 13 68 Intellectual Property and Copyright Statements . . . . . . . . 14 70 1. Introduction 72 The Extensible Markup Language (XML) Configuration Access Protocol 73 (XCAP) [8] is a protocol that allows clients to manipulate XML 74 documents stored on a server. These XML documents serve as 75 configuration information for application protocols. As an example, 76 resource list [12] subscriptions (also known as presence lists) allow 77 a client to have a single SIP subscription to a list of users, where 78 the list is maintained on a server. The server will obtain presence 79 for those users and report it back to the client. This application 80 requires the server, called a Resource List Server (RLS), to have 81 access to the list of presentities. This list needs to be 82 manipulated by clients so they can add and remove their friends as 83 they desire. 85 Complexities arise when multiple clients attempt to simultaneously 86 manipulate a document, such as a presence list. Frequently, a client 87 will keep a copy of the current list in memory, so it can render it 88 to users. However, if another client modifies the document, the 89 cached version becomes stale. This modification event must be made 90 known to all clients which have cached copies of the document, so 91 that they can fetch the most recent one. 93 To deal with this problem, clients can use a Session Initiation 94 Protocol (SIP) [10] event package [11] to subscribe to change events 95 in XCAP documents. This notification needs to indicate the specific 96 resource that changed, and how it changed. One solution for the 97 format of such a change notification would be a content indirection 98 object [15]. Though content indirection can tell a client that a 99 document has changed, it provides it with MIME Content-ID indicating 100 the new version of the document. The MIME Content-ID is not the same 101 as the entity tag, which is used by XCAP for document versioning. As 102 such, a client cannot easily ascertain whether an indication of a 103 change in a document is due to a change it just made, or due to a 104 change another client made at around the same time. Furthermore, 105 content indirections don't indicate how a document changed; they 106 would only be able to indicate that it did change. 108 To resolve these problems, this document defines a data format which 109 can convey the fact that an XML document managed by XCAP has changed. 110 This data format is an XML document format, called an XCAP diff 111 document. This format can indicate that a document has changed, and 112 provide its previous and new entity tags. It can also optionally 113 include a set of patch operations [9], which indicate how to 114 transform the document from the version prior to the change, to the 115 version after it. 117 2. Terminology 119 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 120 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 121 and "OPTIONAL" are to be interpreted as described in RFC 2119 [7] and 122 indicate requirement levels for compliant implementations. 124 This specification also defines the following additional terms: 126 Document: When the term document is used without the "XCAP diff" in 127 front of it, it refers to the XCAP document resource about whom 128 the XCAP diff document is reporting a change. 130 XCAP diff document: The XML document defined by this specification 131 that reports on a set of changes in an XCAP document resource. 133 Server: Typically an XCAP server, this is a protocol entity that 134 generates XCAP diff documents based on its knowledge of a set of 135 XCAP documents. 137 Client: Typically an XCAP client and SIP User Agent (UA), the client 138 consumes XCAP diff documents in order to reconstruct the document 139 stored on the server. 141 3. Structure of an XCAP Diff Document 143 An XCAP diff document is an XML [2] document that MUST be well-formed 144 and SHOULD be valid. XCAP diff documents MUST be based on XML 1.0 145 and MUST be encoded using UTF-8. This specification makes use of XML 146 namespaces for identifying XCAP diff documents and document 147 fragments. The namespace URI for elements defined by this 148 specification is a URN [3], using the namespace identifier 'ietf' 149 defined by [5] and extended by [6]. This URN is: 151 urn:ietf:params:xml:ns:xcap-diff 153 An XCAP diff document begins with the root element tag . 154 This element has a single mandatory attribute, "xcap-root". The 155 value of this attribute is the XCAP root URI for the documents in 156 which the changes have taken place. A single XCAP diff document can 157 only represent changes in documents within the same XCAP root. The 158 content of the element is a sequence of 159 elements. Each element specifies changes in a specific 160 document within the XCAP root. It has one mandatory attribute, "doc- 161 selector", and a three optional attributes, "new-etag", "previous- 162 etag" and "hash". The "doc-selector" identifies the specific 163 document within the XCAP root for which changes are indicated. Its 164 content MUST be a relative path reference, with the base URI being 165 equal to the XCAP root URI. The "new-etag" attribute provides the 166 etag for the document after the application of the changes, assuming 167 the document exists after those changes. If the change being 168 reported is the deletion of the document, the "new-etag" attribute 169 will not be present. A server MUST include the "new-etag" unless the 170 document does not exist subsequent to the changes reported in the 171 XCAP diff document. The "previous-etag" attribute provides an 172 identifier for the document instance prior to the change. If the 173 document did not exist prior to the change (that is, the change was 174 the creation of the document), the "previous-etag" is not present. 176 The "previous-etag" and "new-etag" need not have been sequentially 177 assigned etags at the server. An XCAP diff document can indicate 178 changes that have occurred over a series of XCAP operations. 180 The optional "hash" attribute provides an HMAC of the document 181 instance whose etag is "new-etag", once that document is represented 182 in canonical form. To compute this value, the server MUST apply the 183 mandatory XML canonicalization defined in the Canonical XML 1.0 [1] 184 specification, and then computes an HMAC [13] using SHA1 over this 185 canonical document, with a key whose value is 0x2238a. The result is 186 the value of the "hash" attribute. This attribute is optional, and a 187 server MAY elect not to include it. Even if present, a client MAY 188 elect to ignore it. 190 Each element contains zero or one element, 191 followed by any number of elements from another namespace for the 192 purposes of extensibility. Any such unknown elements MUST be ignored 193 by the client. When present, the element tells the 194 client the specific set of XML patch operations that can be applied 195 to transform the document from the version whose etag was "previous- 196 etag" to the version whose etag is "new-etag". If the "previous- 197 etag" is not present, the element tells the client the 198 specific set of XML patch operations that can be applied to create a 199 document from nothing, and result in the document whose etag is "new- 200 etag". If the "new-etag" attribute is not present, it implies that 201 the document was removed. In that case, the is 202 meaningless and SHOULD be ignored. 204 The series of operations in the do not have to be the 205 same exact series of operations that occurred at the server. The 206 only requirement is that, if the server includes the 207 element, the sequence of events, when executed serially, will result 208 in the transformation of the document with the etag "previous-etag" 209 to the one whose etag is "new-etag". If the element is 210 not present, it means that the document has changed in some way, but 211 the XCAP server has elected not to provide the set of changes. In 212 that case, a client can retrieve the latest document if its cached 213 etag doesn't match the value of "new-etag". 215 It is important to note that a element with no child is not equivalent to a element with a child that is itself empty. The latter means that the document 218 has been assigned a new etag but its content is unchanged. The 219 former means that it has been assigned a new etag as a result of a 220 change, but the specific changes are not being reported in the XCAP 221 diff document. 223 Each element contains a sequence of instructions, each 224 of which can be , and elements. These 225 elements use the corresponding add, replace and remove types defined 226 in [9], and define a set of patch operations that can be applied to 227 transform the document. See [9] for instructions on how this 228 transformation is effected. The element can also 229 contain elements from other namespaces for the purposes of 230 extensibility. Any unknown elements MUST be ignored. 232 4. XML Schema 234 235 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 273 5. Example Document 275 The following is an example of a document compliant to the schema. 277 278 280 283 285 This indicates that the document with URI 286 "http://xcap.example.com/root/resource-lists/users/joe/coworkers" has 287 changed. Its previous entity tag is 8a77f8d and its new one is 288 7ahggs. 290 6. Usage with an Event Package 292 The XCAP diff format was meant to be used with an event package for 293 the purposes of indicating changes in a document. This section 294 provides guidelines for its usage with any event package defined for 295 that purpose. 297 Upon receipt of an initial SUBSCRIBE request, the client may have a 298 cached version of some documents. However, the server does not know 299 which instances of each document (where each instance is identified 300 by an etag) the client currently posessses, if any. Indeed, upon 301 initial startup, the client will not have any documents. The initial 302 NOTIFY in this case MUST include a element for each 303 document associated with the subscription. The "previous-etag" 304 attribute MUST be absent, and the "new-etag" attribute MUST be 305 present and contain the entity tag for the current version of that 306 document resource. An XCAP diff document structured this way is 307 called a "reference" XCAP diff document. It establishes the baseline 308 etags and document URIs for the documents covered by the 309 subscription. 311 Upon receipt of this document, the client can determine whether its 312 local instance documents, if any, match the etags in the XCAP diff 313 document. If they do not match, the client SHOULD perform a 314 conditional GET for each document. The document URI is constructed 315 by appending the XCAP root in the "xcap-root" attribute of the element to the escape coded "doc-selector" from each 317 element. The request is made conditional by including an If-Match 318 header field, with the value of the etag from each 319 element. So long as the documents haven't changed between the NOTIFY 320 and the GET, the client will obtain the reference versions that the 321 server will use for subsequent notifications. 323 If the conditional GET should fail, the client SHOULD generate a 324 SUBSCRIBE refresh request to trigger a new NOTIFY. The server will 325 always generate a "reference" XML diff document on receipt of a 326 SUBSCRIBE refresh. This establishes a new set of baseline etags, and 327 the client can then attempt to do another fetch. [[ISSUE: this is 328 really awful; we should include a parameter in the subscription which 329 allows the client to indicate which version it has. That would 330 obviate the need for a potentially never-ending stream of SUBSCRIBE/ 331 GET sequences should the documents be rapidly changing, for some 332 reason.]] 334 Once the client has obtained the versions of the documents identified 335 in the reference XML diff, it can process NOTIFY requests on that 336 subscription. To process the NOTIFY requests, it makes sure that its 337 current version matches the version in the "previous-etag" attribute 338 of the element. If not, the client can then fetch the 339 updated document from the server. If they do match, the client has 340 the most current version. 342 7. Security Considerations 344 XCAP diff documents can include changes from one document to another. 345 As a consequence, if the document itself is sensitive and requires 346 confidentiality, integrity or authentication, than the same applies 347 to the XCAP diff format. Therefore, protocols which transport XCAP 348 diff documents must provide sufficient security capabilities for 349 transporting the document itself. 351 8. IANA Considerations 353 There are several IANA considerations associated with this 354 specification. 356 8.1 application/xcap-diff+xml MIME Type 358 MIME media type name: application 360 MIME subtype name: xcap-diff+xml 362 Mandatory parameters: none 364 Optional parameters: Same as charset parameter application/xml as 365 specified in RFC 3023 [4]. 367 Encoding considerations: Same as encoding considerations of 368 application/xml as specified in RFC 3023 [4]. 370 Security considerations: See Section 10 of RFC 3023 [4] and 371 Section 7 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace 372 XXXX with the RFC number of this specification.]]. 374 Interoperability considerations: none. 376 Published specification: This document. 378 Applications which use this media type: This document type has 379 been used to support manipulation of resource lists [14] using 380 XCAP. 382 Additional Information: 384 Magic Number: None 386 File Extension: .xdf 388 Macintosh file type code: "TEXT" 390 Personal and email address for further information: Jonathan 391 Rosenberg, jdrosen@jdrosen.net 393 Intended usage: COMMON 395 Author/Change controller: The IETF. 397 8.2 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:xcap-diff 399 This section registers a new XML namespace, as per the guidelines in 400 [6] 402 URI: The URI for this namespace is 403 urn:ietf:params:xml:ns:xcap-diff. 405 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 406 Jonathan Rosenberg (jdrosen@jdrosen.net). 408 XML: 410 BEGIN 411 412 414 415 416 418 XCAP Diff Namespace 419 420 421

Namespace for XCAP Diff

422

urn:ietf:params:xml:ns:xcap-diff

423

See RFCXXXX[[NOTE 424 TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this 425 specification.]].

426 427 428 END 430 8.3 Schema Registration 432 This section registers a new XML schema per the procedures in [6]. 434 URI: urn:ietf:params:xml:schema:xcap-diff 436 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 437 Jonathan Rosenberg (jdrosen@jdrosen.net). 439 The XML for this schema can be found as the sole content of 440 Section 4. 442 9. References 444 9.1 Normative References 446 [1] Boyer, J., "Canonical XML Version 1.0", W3C REC REC-xml-c14n- 447 20010315, March 2001. 449 [2] Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, 450 "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C 451 FirstEdition REC-xml-20001006, October 2000. 453 [3] Moats, R., "URN Syntax", RFC 2141, May 1997. 455 [4] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", 456 RFC 3023, January 2001. 458 [5] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, 459 August 1999. 461 [6] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 462 January 2004. 464 [7] Bradner, S., "Key words for use in RFCs to Indicate Requirement 465 Levels", BCP 14, RFC 2119, March 1997. 467 [8] Rosenberg, J., "The Extensible Markup Language (XML) 468 Configuration Access Protocol (XCAP)", draft-ietf-simple-xcap-08 469 (work in progress), October 2005. 471 [9] Urpalainen, J., "An Extensible Markup Language (XML) Patch 472 Operations Framework Utilizing XML Path Language (XPath) 473 Selectors", draft-ietf-simple-xml-patch-ops-01 (work in 474 progress), January 2006. 476 9.2 Informative References 478 [10] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 479 Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: 480 Session Initiation Protocol", RFC 3261, June 2002. 482 [11] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 483 Notification", RFC 3265, June 2002. 485 [12] Roach, A., Rosenberg, J., and B. Campbell, "A Session 486 Initiation Protocol (SIP) Event Notification Extension for 487 Resource Lists", draft-ietf-simple-event-list-07 (work in 488 progress), January 2005. 490 [13] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-Hashing 491 for Message Authentication", RFC 2104, February 1997. 493 [14] Rosenberg, J., "Extensible Markup Language (XML) Formats for 494 Representing Resource Lists", 495 draft-ietf-simple-xcap-list-usage-05 (work in progress), 496 February 2005. 498 [15] Burger, E., "A Mechanism for Content Indirection in Session 499 Initiation Protocol (SIP) Messages", 500 draft-ietf-sip-content-indirect-mech-05 (work in progress), 501 October 2004. 503 Author's Address 505 Jonathan Rosenberg 506 Cisco Systems 507 600 Lanidex Plaza 508 Parsippany, NJ 07054 509 US 511 Phone: +1 973 952-5000 512 Email: jdrosen@cisco.com 513 URI: http://www.jdrosen.net 515 Intellectual Property Statement 517 The IETF takes no position regarding the validity or scope of any 518 Intellectual Property Rights or other rights that might be claimed to 519 pertain to the implementation or use of the technology described in 520 this document or the extent to which any license under such rights 521 might or might not be available; nor does it represent that it has 522 made any independent effort to identify any such rights. Information 523 on the procedures with respect to rights in RFC documents can be 524 found in BCP 78 and BCP 79. 526 Copies of IPR disclosures made to the IETF Secretariat and any 527 assurances of licenses to be made available, or the result of an 528 attempt made to obtain a general license or permission for the use of 529 such proprietary rights by implementers or users of this 530 specification can be obtained from the IETF on-line IPR repository at 531 http://www.ietf.org/ipr. 533 The IETF invites any interested party to bring to its attention any 534 copyrights, patents or patent applications, or other proprietary 535 rights that may cover technology that may be required to implement 536 this standard. Please address the information to the IETF at 537 ietf-ipr@ietf.org. 539 Disclaimer of Validity 541 This document and the information contained herein are provided on an 542 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 543 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 544 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 545 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 546 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 547 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 549 Copyright Statement 551 Copyright (C) The Internet Society (2006). This document is subject 552 to the rights, licenses and restrictions contained in BCP 78, and 553 except as set forth therein, the authors retain all their rights. 555 Acknowledgment 557 Funding for the RFC Editor function is currently provided by the 558 Internet Society.