SIP J. Urpalainen Internet-Draft Nokia Intended status: Standards Track December 18, 2007 Expires: June 20, 2008 An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Diff Event Package draft-ietf-sip-xcapevent-00 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 June 20, 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 June 20, 2008 [Page 1] Internet-Draft xcap diff event December 2007 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. XCAP-Diff Event Package . . . . . . . . . . . . . . . . . . . 4 4.1. XCAP-Diff Processing Model . . . . . . . . . . . . . . . . 4 4.2. Event Package Name . . . . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . . . . . . . . 9 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 June 20, 2008 [Page 2] Internet-Draft xcap diff event December 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 on an XCAP server. While the XCAP protocol 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 a server and a 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 [RFC4918], the notifier provides then the 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 can contain patches to these documents. Some clients might need to retrieve only some specific element or attribute content from these XCAP documents without using the HTTP protocol. All of these use-cases can be indicated 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 June 20, 2008 [Page 3] Internet-Draft xcap diff event December 2007 XCAP Component: An XML element or an attribute, which can be updated or retrieved with the XCAP protocol. Aggregating: While XCAP clients update only a single XCAP component 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 Model When a client starts an "xcap-diff" subscription it may not be aware of all the individual XCAP documents it is subscribing to. This can, for instance happen when a user subscribes to his/her collection of a given XCAP Application Usage where several different clients update the same XCAP documents. The initial notification can give the list of these documents which the authenticated user is allowed to read. The references and the strong ETag values of these documents are shown so that a client can separately fetch the actual document contents with the HTTP protocol. After these document retrievals, the subsequent SIP notifications can contain patches to these documents by using XML-Patch-Ops [I-D.ietf-simple-xml-patch-ops] semantics. While the initial document synchronization is based on separate HTTP retrievals of full documents, XML elements or attributes can be received "in-band", that is straight within the notification format. For example, an XCAP element content can be requested without the need of a separate HTTP GET request by providing a request URI with an XCAP Element Node Selector within the subscription body. If the requested node can not be found with the aid of this XCAP Node Selector value, the node content isn't naturally shown in the notification. Once these nodes will be created, the notification bodies will indicate their content. And similarly, the removals of subscribed XCAP components will be reported, for example after a successful HTTP DELETE request. In yet another usage scenario, a subscriber to the "xcap-diff" event might not need XML-Patch-Ops conventions 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 of the document(s). The XCAP-Diff [I-D.ietf-simple-xcap-diff] format will then only indicate document creations, updates and removals. Urpalainen Expires June 20, 2008 [Page 4] Internet-Draft xcap diff event December 2007 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]. 4.3. 'diff-processing' Event Package Parameter The optional "diff-processing" event header parameter directs 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 along with the 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] of the "diff-processing" parameter: diff-processing = "diff-processing" EQUALS "aggregate" / "no-patching" / "xcap-patching" / token 4.4. SUBSCRIBE Bodies When generating a 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 is described with the XCAP resource list [RFC4826] document format. Only a simple subset of that format is needed here, that is a flat list of XCAP R-URIs. The usage of hierarchical lists and references, etc. can thus be omitted. However, using this format allows adding some future semantics to these subscriptions. As it is anticipated that the XCAP server will be collocated with the SIP notifier, the subscriber MAY use relative XCAP URIs. Although the node-selector of XCAP allows requesting all in-scope namespaces of an element, it is disallowed to subscribe to them with this event package. Urpalainen Expires June 20, 2008 [Page 5] Internet-Draft xcap diff event December 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 When collections are 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. If a subscribed collection contains sub- collections, the notifications will contain also the sub-collection documents for which the user has read privilege. 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] which can indicate the full element and attribute content of XML documents, and for documents the corresponding URIs, the ETag values and patching instructions from version "a" to "b". Also the removals of documents, elements and attributes can be shown. 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 Urpalainen Expires June 20, 2008 [Page 6] Internet-Draft xcap diff event December 2007 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 a "pending" state, 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 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 the 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 whole request or body will be suppressed with the SubNot-Etags [I-D.ietf-sip-subnot-etags] semantics by using the header Suppress- If-Match: [ETag value]. The notifier SHOULD then start to aggregate different individual patches together. The notifiers MAY decide the appropriate aggregation semantics themselves, for example how long to wait for subsequent patches if there's already something to signal. It can 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 is RECOMMENDED to implement the XML-Patch-Ops processing on a server. However, the notifier MUST support XCAP component subscriptions. If for example, the subscriber has selected too many elements to subscribe, so that the notification body would become impractically large, the notifier MAY discard the element content. The existence of elements is then 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 transferred 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 Urpalainen Expires June 20, 2008 [Page 7] Internet-Draft xcap diff event December 2007 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. 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 the subscriber MAY also receive patches to these documents (notifications) if the documents are changing frequently. It can thus 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 NOTIFY requests. These values can easily be used to detect missing "xcap-diff" events if there are no multiple usages in the current dialog. Also failing patches or inconsistent ETag value changes can be due to missing events. Once a client detects an error it MUST renew the subscription. If a diff format can not be applied because of some patch processing and/or programming errors, look Section 5.1 of [I-D.ietf-simple-xml-patch-ops], the subscriber SHOULD renew the subscription and disable the usage of "diff-processing". 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 Urpalainen Expires June 20, 2008 [Page 8] Internet-Draft xcap diff event December 2007 five seconds. 4.11. State Agents State agents play no role in this package. 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 can 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. Urpalainen Expires June 20, 2008 [Page 9] Internet-Draft xcap diff event December 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 June 20, 2008 [Page 10] Internet-Draft xcap diff event December 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[[NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this specification.]] 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 apply. The configuration data can contain sensitive information, and both the client and the server need to authenticate each other. XCAP [RFC4825] provides basic authorization policy for resources and as the notifications will contain similar fragment content of XCAP resources the security considerations of XCAP also apply. 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, Sofie Lassborn and Keith Drage 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, Urpalainen Expires June 20, 2008 [Page 11] Internet-Draft xcap diff event December 2007 June 2002. [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. [I-D.ietf-simple-xcap-diff] Rosenberg, J. and J. Urpalainen, "An Extensible Markup Language (XML) Document Format for Indicating A Change in XML Configuration Access Protocol (XCAP) Resources", draft-ietf-simple-xcap-diff-07 (work in progress), November 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-04 (work in progress), November 2007. [I-D.ietf-sip-subnot-etags] Niemi, A., "An Extension to Session Initiation Protocol (SIP) Events for Conditional Event Notification", draft-ietf-sip-subnot-etags-01 (work in progress), August 2007. 9.2. Informative References [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, . [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007. Urpalainen Expires June 20, 2008 [Page 12] Internet-Draft xcap diff event December 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. Author's Address Jari Urpalainen Nokia Itamerenkatu 11-13 Helsinki 00180 Finland Phone: +358 7180 37686 Email: jari.urpalainen@nokia.com Urpalainen Expires June 20, 2008 [Page 13] Internet-Draft xcap diff event December 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 June 20, 2008 [Page 14]