SIP J. Urpalainen Internet-Draft Nokia Intended status: Standards Track November 16, 2007 Expires: May 19, 2008 An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Diff Event Package draft-urpalainen-sip-xcap-diff-event-03 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on May 19, 2008. Copyright Notice Copyright (C) The IETF Trust (2007). Abstract This document describes an "xcap-diff" SIP event package, with the aid of which clients can receive notifications of the partial changes of Extensible Markup Language (XML) Configuration Access Protocol (XCAP) resources. The initial synchronization and document updates are based on using the XCAP-Diff format. Urpalainen Expires May 19, 2008 [Page 1] Internet-Draft xcap diff event November 2007 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. XCAP-Diff Event Package . . . . . . . . . . . . . . . . . . . 4 4.1. XCAP-Diff Processing . . . . . . . . . . . . . . . . . . . 4 4.2. Event Package Name . . . . . . . . . . . . . . . . . . . . 4 4.3. 'diff-processing' Event Package Parameter . . . . . . . . 5 4.4. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 5 4.5. Subscription Duration . . . . . . . . . . . . . . . . . . 6 4.6. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 6 4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 6 4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 8 4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 8 4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 8 4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 8 5. An Initial Example NOTIFY document . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6.1. Registration of the "xcap-diff" Event Package . . . . . . 11 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 9.1. Normative References . . . . . . . . . . . . . . . . . . . 11 9.2. Informative References . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 Intellectual Property and Copyright Statements . . . . . . . . . . 14 Urpalainen Expires May 19, 2008 [Page 2] Internet-Draft xcap diff event November 2007 1. Introduction The SIP Events framework [RFC3265] describes subscription and notification conventions for the SIP [RFC3261] protocol. The Extensible Markup Language (XML) [W3C.REC-xml-20060816] Configuration Access Protocol (XCAP) [RFC4825] allows a client to read, write and modify XML formatted application usage data in an XCAP server. While XCAP allows several authorized users or devices to modify the same XML document, XCAP does not provide an effective synchronization mechanism (except polling) to keep resources equivalent between the server and the client. This memo defines an "xcap-diff" event package that, together with the SIP event notification framework [RFC3265] and the XCAP-diff format [I-D.ietf-simple-xcap-diff], allows a user to subscribe to changes in an XML document, and to receive notifications whenever a change in an XML document takes place. It is also possible to subscribe to documents within some collection, the notifier provides those documents where the user has read privilege. Before being able to apply any patches into documents, a client needs to first retrieve initial reference documents. With XCAP, this is done with the HTTP [RFC2616] protocol. The first "xcap-diff" notification thus contains references to subscribed documents, thereafter notifications MAY contain patches to these documents. Optionally some clients MAY want to retrieve only specific element or attribute content from these XCAP documents. All this information can be transformed with the XCAP-Diff [I-D.ietf-simple-xcap-diff] format. 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, BCP 14 [RFC2119] and indicate requirement levels for compliant implementations. 3. Definitions The following terms are used in this document: Urpalainen Expires May 19, 2008 [Page 3] Internet-Draft xcap diff event November 2007 XCAP Component: An XML element or an attribute, which can be updated with the XCAP protocol. Aggregating: While XCAP clients update only single XCAP components at a time, several of these modifications can be aggregated together with the XML-Patch-Ops semantics. 4. XCAP-Diff Event Package 4.1. XCAP-Diff Processing When a client starts the "xcap-diff" subscription they may not be aware of all the XCAP resources they are subscribing to. This may for instance happen when the user subscribes to his/her collection [RFC4918] of a given XCAP Application Usage. The initial notification will then contain references to documents the user is authorized to read. After receiving these documents and resolving the initial synchronization stage, the subsequent notifications MAY contain patches to these documents. While the initial document synchronization is based on separate HTTP retrievals of full documents, XML elements or attributes may be received "in-band", that is within the notification format. For example, the subscribed element has different semantics than XML-Patch-Ops [I-D.ietf-simple-xml-patch-ops] elements, because the intent is just to get the content of an element without the need of a separate HTTP GET request. If during the initial subscription stage the requested node can not be found, there is not any need for a result element or an attribute either. Once they will be created, the notify will contain their content. And similarly, their removals will be reported, for example after a successful HTTP DELETE request. In another usage scenario, a subscriber to the "xcap-diff" event might not need XML-Patch operations at all. Indeed, the subscriber just wants to be informed that an update has happened, but the subscriber is not interested in learning the actual changes in the document(s). The XCAP-Diff [I-D.ietf-simple-xcap-diff] format will then only indicate document creations, updates and removals. 4.2. Event Package Name The name of this event package is "xcap-diff". This package name is carried in the Event and Allow-Events header, as defined in RFC3265 [RFC3265]. Urpalainen Expires May 19, 2008 [Page 4] Internet-Draft xcap diff event November 2007 4.3. 'diff-processing' Event Package Parameter The optional "diff-processing" parameter will tell the notifier how to apply the "XML diffing process". The possible values are "no- patching", "xcap-patching", "aggregate". The "no-patching" value means that only document or XCAP component existences MUST be indicated. The "xcap-patching" value means that all individual XCAP component updates with entity tag (ETag) changes MUST be indicated. The "aggregate" value means that the notifier is free to aggregate several individual XCAP component updates into a single XCAP-Diff element. If the subscription does not contain this additional "diff-processing" parameter, the notifier MUST send all individual changes so that the client receives the full ETag change history of a document. In other words, "xcap-patching" is the default mode. The formal grammar (RFC4234 [RFC4234]) of the "diff-processing" parameter: diff-processing = "diff-processing" EQUALS "aggregate" / "no-patching" / "xcap-patching" / token 4.4. SUBSCRIBE Bodies When generating the subscribe request, the subscriber needs to define the resources it is interested in getting information. This can be done simply by sending a URI list to the SIP notifier. This list can be described with the XCAP resource list [RFC4826] document format. Only a simple subset of that format is needed here, i.e. a flat list of XCAP URIs. The usage of hierarchical lists and references, etc. can thus be discarded. However, using this format allows adding some future semantics to these subscriptions. Also it is anticipated that the XCAP server will be collocated with the SIP notifier so relative XCAP URIs MAY be used. Note that although the node-selector of XCAP allows requesting all in-scope namespaces of an element, it is disallowed to subscribe to them with this package. Urpalainen Expires May 19, 2008 [Page 5] Internet-Draft xcap diff event November 2007 Figure 1 shows an example to a subscription of several XCAP resources: a "resource-list" document, a specific element in a "rls- services" document and a collection in "pidf-manipulation" Application Usage. For all of these resources the client MUST have read privilege in order to actually receive them in a NOTIFY request. The "Content-Type" header of this SUBSCRIBE request is "application/ resource-lists+xml". Figure 1: Example subscription body Note that when collections are being selected as "pidf-manipulation" in the example, the conventions applied follow the WebDAV [RFC4918] semantics, that is, the subscriber MUST add the forward slash "/" character to the end of the path segment. 4.5. Subscription Duration The default expiration time for subscriptions within this package is 3600 seconds. As per RFC 3265 [RFC3265], the subscriber MAY specify an alternative expiration timer in the Expires header field. 4.6. NOTIFY Bodies The NOTIFY bodies will follow the conventions of the XCAP-Diff format [I-D.ietf-simple-xcap-diff]. 4.7. Notifier Generation of NOTIFY Requests During the initial subscription the notifier must first resolve the requested XCAP resources. Once there are superfluous resource selections in the requested URI list, the notifier SHOULD not provide overlapping similar responses for these resources. Only the resources where the authenticated user has read privilege will be included in the XCAP-Diff format. Note that for example, an XCAP component which could not be located with XCAP semantics, does not produce an error. Instead, the request remains in "pending" state, Urpalainen Expires May 19, 2008 [Page 6] Internet-Draft xcap diff event November 2007 that is, waiting for this resource to be created. Subscriptions to collections have a similar property: once a new document is created into the subscribed collection, the creation of a new resource is notified with the next NOTIFY request. After the authorized XCAP resources are known, the notifier will generate the first full response with the list of found and authorized resources. At this time depending on the "diff-processing" parameter, the notifier typically starts also the follow-up of XCAP component updates and unless otherwise directed, it reports all individual XCAP component updates with ETag changes to the subscriber. If the notifier process receives then a re-subscription with the diff-processing=aggregate value it MUST re-send the current full XML-Diff content unless the request or body can be suppressed with the SubNot-Etags [I-D.ietf-sip-subnot-etags] semantics by using e.g. the header Suppress-Notify-If-Match: xxxx. The notifier SHOULD then start to aggregate "diff-processing". It MAY happen in some corner cases that the notifier can not or will not provide patches with the XML-Patch-Ops [I-D.ietf-simple-xml-patch-ops] semantics. One example of this is when the diff format produces a larger content than the original document is. When this happens, and if the server has been in this diff "aggregation" mode, it MUST fall back to the "xcap-patching" mode for this particular resource. It should be noted that the whole diff-processing is truly implementation specific and in essence, also OPTIONAL. If the server so desires, it MAY elect not to produce XML-diffing at all although it is RECOMMENDED to implement it. Support for XCAP component subscriptions is mandatory in the server, however. Note that if for example, the subscriber has selected too many elements to subscribe, so that the notification body becomes impractically large, the notifier MAY discard the element content. The existence of elements is indicated with an empty element but the content is not shown for those resources. Event packages like this require in practice a reliable transfer of events. This means that all events MUST be successfully transfered as otherwise patching will most likely fail or at least the document content becomes to be different. RFC 3265 [RFC3265] proposes utilization of a "version" attribute information to state deltas in chapter 4.4. Partial-PIDF-Notify [I-D.ietf-simple-partial-notify] requires that notifiers will not send a new request to the same dialog unless a successful response (200 OK) has been received for the last request. The latter applies also to this "xcap-diff" event package. If the NOTIFY request fails due to a timeout condition, the notifier MUST remove the subscription. Urpalainen Expires May 19, 2008 [Page 7] Internet-Draft xcap diff event November 2007 4.8. Subscriber Processing of NOTIFY Requests The first NOTIFY request will typically contain references to HTTP resources including their strong ETag values. If the subscriber does not have similar locally cached versions, it will start an unconditional HTTP GET request for those resources. During this HTTP retrieval time it MAY also receive patches to these documents (notifications) if they are changing frequently. So it MAY happen that the subscriber receives newer versions (with HTTP) than what was indicated in the initial notification. However, once all atomic XCAP modifications are indicated with both previous and new ETags of each resource, it is easy to chain the modification list for a document and possibly omit some of the patches based on the received ETag (with HTTP) of a document. After that the subscriber MAY send a re- subscription to start the diff "aggregation" on the server. The subscriber can use CSeq values to keep track of possible missing requests. These values can be used to detect missing events also if there are no multiple usages in the current "xcap-diff" dialog. The event bodies, i.e. failing patches and especially the consistent ETag value changes MAY also be used to detect possible missing events. Once the client detects an error it MUST renew the subscription. If a diff format can not be applied because of some patching errors, look Section 5.1 of [I-D.ietf-simple-xml-patch-ops], the subscriber SHOULD fall back to not to enable any patching within the subscription. It is hardly reasonable to signal this error to the notifier even if the error exists in the notifier process. 4.9. Handling of Forked Requests This specification only allows a single dialog to be constructed as a result of emitting an initial SUBSCRIBE request. In case a SUBSCRIBE request is forked and the subscriber receives forked responses, the subscriber MUST apply the procedures indicated in Section 4.4.9 of RFC 3265 [RFC3265] for handling non-allowed forked requests. 4.10. Rate of Notifications Notifiers of "xcap-diff" event package SHOULD NOT generate notifications for a single user at a rate of more than once every five seconds. 4.11. State Agents State agents play no role in this package. Urpalainen Expires May 19, 2008 [Page 8] Internet-Draft xcap diff event November 2007 5. An Initial Example NOTIFY document Figure 2 shows an example initial XCAP-Diff document provided by the first NOTIFY request. The subscriber used the list as in the example in Figure 1. An example event header of this SUBSCRIBE request: Event: xcap-diff; diff-processing=aggregate The subscriber requests the notifier to actually "aggregate" XCAP component updates together. It is anticipated that the subsequent notifications would contain aggregated patches to these documents. Note: If these documents are changing frequently during the initial synchronization stage, it may happen that the subscriber can not synchronize the contents of all documents properly. However, the subscriber can always begin with the default "xcap- patching" mode where all individual changes with the full ETag change history are shown and this issue does not occur. Also a future extension to XCAP specification MAY solve this versioning issue in a better way. Urpalainen Expires May 19, 2008 [Page 9] Internet-Draft xcap diff event November 2007 presence Figure 2: An example initial XCAP-Diff document Note that the resource-list "index" document included only the new ETag value, as the document existed during the subscription time (resource was not created, it just exists by the subscription time). In the "pidf-manipulation" collection there was only a single document where the user had read privilege. The element existed within the rls-services "index" document and its content was shown. 6. IANA Considerations This memo calls for IANA to: o register a new package name per [RFC3265]. Urpalainen Expires May 19, 2008 [Page 10] Internet-Draft xcap diff event November 2007 6.1. Registration of the "xcap-diff" Event Package This specification instructs IANA to register an event package in the SIP Event Types Namespace, based on the registration procedures defined in RFC 3265 [RFC3265]. The following is the information required for such a registration: Package Name: xcap-diff Package or Template-Package: This is a package. Published Document: RFCXXXX Person to Contact: Jari Urpalainen, jari.urpalainen@nokia.com 7. Security Considerations This document defines a new SIP event package for the SIP event notification framework specified in RFC 3265 [RFC3265]. As such, all the Security considerations of RFC 3265 [RFC3265] apply. The configuration data can contain sensitive information, and both the client and the server need to authenticate each other. XCAP provides basic authorization policy for resources. Notifiers and subscribers MAY use S/MIME feature to provide authentication and message integrity. This is described in Section 23 of RFC 3261 [RFC3261]. 8. Acknowledgments The author would like to thank Jonathan Rosenberg for his valuable comments and providing the initial event package, and Miguel Garcia, Pavel Dostal, Krisztian Kiss, Anders Lindgren and Sofie Lassborn for their valuable comments. 9. References 9.1. Normative References [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [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. Urpalainen Expires May 19, 2008 [Page 11] Internet-Draft xcap diff event November 2007 [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002. [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)", RFC 4825, May 2007. [RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats for Representing Resource Lists", RFC 4826, May 2007. [W3C.REC-xml-20060816] Maler, E., Paoli, J., Bray, T., Yergeau, F., and C. Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 (Fourth Edition)", World Wide Web Consortium Recommendation REC-xml-20060816, August 2006, . [I-D.ietf-simple-xcap-diff] Urpalainen, J. and J. Rosenberg, "An Extensible Markup Language (XML) Document Format for Indicating A Change in XML Configuration Access Protocol (XCAP) Resources", draft-ietf-simple-xcap-diff-06 (work in progress), August 2007. [I-D.ietf-simple-xml-patch-ops] Urpalainen, J., "An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors", draft-ietf-simple-xml-patch-ops-03 (work in progress), August 2007. 9.2. Informative References [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007. [I-D.ietf-simple-partial-notify] Lonnfors, M., "Session Initiation Protocol (SIP) extension for Partial Notification of Presence Information", draft-ietf-simple-partial-notify-09 (work in progress), February 2007. [I-D.ietf-sip-subnot-etags] Niemi, A., "An Extension to Session Initiation Protocol Urpalainen Expires May 19, 2008 [Page 12] Internet-Draft xcap diff event November 2007 (SIP) Events for Conditional Event Notification", draft-ietf-sip-subnot-etags-01 (work in progress), August 2007. Author's Address Jari Urpalainen Nokia Itamerenkatu 11-13 Helsinki 00180 Finland Phone: +358 7180 37686 Email: jari.urpalainen@nokia.com Urpalainen Expires May 19, 2008 [Page 13] Internet-Draft xcap diff event November 2007 Full Copyright Statement Copyright (C) The IETF Trust (2007). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 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. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of 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 copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Urpalainen Expires May 19, 2008 [Page 14]