SIP WG J. Urpalainen Internet-Draft Nokia Expires: June 10, 2007 December 7, 2006 An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Diff Event Package draft-urpalainen-sip-xcap-diff-event-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 10, 2007. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document describes an "xcap-diff" SIP event package with the aid of which the clients can receive partial changes of the Extensible Markup Language (XML) Configuration Access Protocol (XCAP) resources. The initial synchronization and document updates are based on using the XCAP-Diff format. This document extends this format by allowing subscriptions also to XCAP components. Urpalainen Expires June 10, 2007 [Page 1] Internet-Draft xcap diff event December 2006 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. XCAP Diff Event Package . . . . . . . . . . . . . . . . . . . 3 4.1. XCAP Diff Processing . . . . . . . . . . . . . . . . . . . 3 4.2. Event Package Name . . . . . . . . . . . . . . . . . . . . 4 4.3. Event Package Parameters . . . . . . . . . . . . . . . . . 4 4.3.1. Path parameter . . . . . . . . . . . . . . . . . . . . 4 4.3.2. Diff-processing parameter . . . . . . . . . . . . . . 6 4.4. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 6 4.5. Subscription Duration . . . . . . . . . . . . . . . . . . 6 4.6. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 6 4.6.1. XML Schema for element . . . . . . . . . . 6 4.6.2. 'node-sel' attribute . . . . . . . . . . . . . . . . . 7 4.6.3. 'exists' attribute . . . . . . . . . . . . . . . . . . 7 4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 7 4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 8 4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 9 4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 9 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 6.2. URN sub-namespace registration for 'urn:ietf:params:xml:ns:xcap-component' . . . . . . . . . 11 6.3. XML Schema Registration . . . . . . . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 9.1. Normative References . . . . . . . . . . . . . . . . . . . 12 9.2. Informative References . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 Intellectual Property and Copyright Statements . . . . . . . . . . 15 Urpalainen Expires June 10, 2007 [Page 2] Internet-Draft xcap diff event December 2006 1. Introduction The SIP Events framework [2] describes subscription and notification conventions for the SIP [1] protocol. The Extensible Markup Language (XML) [10] Configuration Access Protocol (XCAP) [6] allows a client to read, write and modify application usage data, stored with the XML format on an HTTP/XCAP server. This document describes an "xcap-diff" SIP event package where the clients can receive partial changes of the XCAP resources. The initial synchronization and document updates are based on using the XCAP-Diff [7] format. The initial retrieval of documents is done with the HTTP protocol and the "xcap-diff" event package will report only the document or XCAP component changes. In other words, the contents of documents between the client and XCAP server can then efficiently be kept in-sync. This document also extends the XCAP- Diff format by allowing subscriptions also to XCAP components. 2. Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119, BCP 14 [5] and indicate requirement levels for compliant implementations. 3. Definitions The following terms are used in this document: 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 of some XCAP Application Usage. The initial notification will then contain references to full documents the user is authorized to or in Urpalainen Expires June 10, 2007 [Page 3] Internet-Draft xcap diff event December 2006 other words, has privilege to them. After receiving those documents and resolving the initial synchronization stage, the client continues applying the patches of documents the server has sent. While the initial document synchronization is based on separate HTTP retrievals of full documents, the XCAP components may be received "in-band", that is within the notification format. This document defines an extension element to XCAP Diff [7] where the content of, for example, an XML element can be fetched. This new element has different semantics than XML-Patch-Ops [8] elements, because these are not used for patching an XML document into another new document but instead getting only the content of an XCAP component without the need of a separate HTTP GET request. In addition, this XCAP component is shown with its full content, there's no conventions for patching this component. Therefore the only state information about these components is whether a single node exist in the source document or not. If during the initial subscription stage the requested node can not be found, there is not any result element either. Once it will be created, the notify will contain this new component. And similarly, when the element is deleted it will be signaled as well. The subscriber will request this component with the aid of the XCAP Node Selector. The result format follows XCAP and XML-Patch-Ops conventions shown later in this document. Furthermore, the "xcap-diff" subscriber MAY also not need XML- Patching at all. Indeed, they just want to be informed whenever some document changes. XCAP Diff [7] format will then only report 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 [2]. 4.3. Event Package Parameters 4.3.1. Path parameter The "path" parameter is used to select the set of XCAP resources involved. The value is enclosed within double quotes and it can contain several path values separated with a whitespace character. The single value is usually a relative reference without the XCAP Root URI as it is anticipated that subscription will be routed to an XCAP server. An example of a subscription to the changes of a resource-list document of a user: Event: xcap-diff; Urpalainen Expires June 10, 2007 [Page 4] Internet-Draft xcap diff event December 2006 path="resource-lists/users/sip:joe@example.com/index" Another example of a subscription to several resources: Event: xcap-diff; path="resource-lists/global/index resource-lists/users/sip:joe@example.com/" The conventions applied here follow the WebDAV [11] semantics when collections are being selected, i.e. the client MUST add the forward slash "/" character to the end of the collection path. Then an example about a subscription to an XCAP component, or more precisely to an XML element: Event: xcap-diff; path="resource-lists/users/sip:joe@example.com/ index/~~/resource-lists/list%5b@name='list'%5d" The notification will include the result: the element within the element if it exists in the source document. It should be noted that the path parameter value is in percent encoded form. As the result XML element is typically namespace qualified, all needed namespace declarations MUST exist within the document. If there are local namespace declarations within the result element they appear in the result element as they do exist in the original document. Other namespace references MUST be resolved from the context of the or its parent elements. QName prefixes [9] also remain as they exist originally in the source document. The last example is about subscription to an XCAP component, or actually to an XML attribute: Event: xcap-diff; path="resource-lists/users/sip:joe@example.com/ index/~~/resource-lists/list%5b1%5d/@name" The notification will include the result (if the 'name' attribute exists): the 'name' attribute value within the child text node content of the element. In summary, the formal grammar (RFC 4234 [4]) of the "path" parameter: xcap-res = URI-reference *1("/~~/" node-selector) ; URI-reference from RFC3986 and node-selector from XCAP path = "path" EQUALS DQUOTE xcap-res *(WSP xcap-res) DQUOTE Although the node-selector of XCAP allows requesting all in-scope Urpalainen Expires June 10, 2007 [Page 5] Internet-Draft xcap diff event December 2006 namespaces of an element, it is disallowed to subscribe them with this package. 4.3.2. Diff-processing parameter The optional "diff-processing" parameter will tell the notifier how to apply the "XML diffing process". The possible values are "no-xml- patching", "aggregate". The "no-xml-patching" value means that the client does not want XML-patching at all, i.e. only document or XCAP component changes are being reported. The "aggregate" value means that the notifier is free to aggregate individual XCAP component updates into a single one. If the subscription does not contain this additional "diff-processing" parameter, the notifier MUST send all individual changes so that client receives all ETag changes of a document. An example for requesting of all document changes the user is authorized to, or has privilege: Event: xcap-diff; path="/"; diff-processing="aggregate" In summary, the formal grammar (RFC4234 [4]) of the "diff-processing" parameter: diff-processing = "diff-processing" EQUALS DQUOTE ("aggregate" / "no-xml-patching") DQUOTE 4.4. SUBSCRIBE Bodies Subscriptions to this event package will not contain bodies. 4.5. Subscription Duration The default expiration time for subscriptions within this package is 3600 seconds. As per RFC 3265 [2], the subscriber MAY specify an alternate expiration in the Expires header field. 4.6. NOTIFY Bodies The NOTIFY bodies will follow the conventions of the XCAP Diff format [7] with the addition element when the subscriber is requesting the state or "value" of XCAP components. 4.6.1. XML Schema for element The XML schema for the element. This element is included within the element of the XCAP Diff format [7]. Urpalainen Expires June 10, 2007 [Page 6] Internet-Draft xcap diff event December 2006 4.6.2. 'node-sel' attribute The value of this 'node-sel' attribute is the percent encoded XCAP Node Selector. 4.6.3. 'exists' attribute Just like in XCAP the 'node-sel' MUST always select a single node. If the node can not be located or the selector locates several nodes, the 'exists' value MUST be false. 4.7. Notifier Generation of NOTIFY Requests During the initial subscription the notifier must first resolve the XCAP resources the subscriber has requested. The XCAP-Diff format will include only those resources where the authenticated user has privilege and what resources it has found. Note that for example, an XCAP component which could not be located with XCAP Urpalainen Expires June 10, 2007 [Page 7] Internet-Draft xcap diff event December 2006 semantics, does not produce an error. Instead, the request remains in "pending" state, that is, waiting for this resource to be created. Subscriptions to collections have similar feature: once a new document is created into the subscribed collection, the creation of a new resource is notified with the next response. Depending on the "diff-processing" parameter the notifier will generate then the first full response. At this time the notifier typically starts also the follow-up of XCAP component updates and unless otherwise directed, it reports all individual XCAP component updates to subscribed clients. If the notifier process receives then a re-subscription with diff- processing="aggregate" it MUST re-send the current full XML-Diff content unless the content can be suppressed with SubNot-Etags [13] semantics. The server will continue in this "aggregate" mode, however. It MAY happen in some corner cases that the notifier can not provide patches with the XML-Patch-Ops [8] semantics. One example of this is when the diff format produces 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 sending all component changes again for this 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 highly RECOMMENDED to implement XML-diffing. Support for XCAP component subscriptions is mandatory, however. Event packages like this require in practice a reliable transfer of events as otherwise patching will typically fail. RFC 3265 [2] proposes utilization of the "version" attribute information to state deltas in chapter 4.4. Partial-PIDF-Notify [12] 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 is the proposed model for the "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 initial NOTIFY will typically contain references to HTTP resources including their strong ETag values. If the client does not have similar locally cached versions, it will start an unconditional HTTP GET request for those resources. During this retrieval time it may receive also patches to these with the XCAP-Diff format. Once all resources have been received, the subscriber can compare all the ETag values and resolve this initial synchronization stage. After that the subscriber MAY send a re-subscription to start the diff Urpalainen Expires June 10, 2007 [Page 8] Internet-Draft xcap diff event December 2006 "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. 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. 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. 5. An Initial Example NOTIFY document An example initial XCAP-Diff document provided by the initial NOTIFY. The user has subscribed to a full resource-list document and a service component. Event: xcap-diff; path="resource-lists/users/sip:joe@example.com/index rls-services/ users/sip:joe@example.com/index/~~/*/ service%5b@uri='sip:marketing@example.com'%5d" Urpalainen Expires June 10, 2007 [Page 9] Internet-Draft xcap diff event December 2006 presence Note that the resource-list index document included equal previous and new ETag values, as the document existed during the subscription time. The ETags of rls-services index document were not reported, however. 6. IANA Considerations This memo calls for IANA to: o register a new package name per [2]. o register a new XML namespace URN per [3]. o register a new XML Schema URN per [3]. Urpalainen Expires June 10, 2007 [Page 10] Internet-Draft xcap diff event December 2006 6.1. Registration of the "xcap-diff" Event Package This specification registers an event package, based on the registration procedures defined in RFC 3265 [2]. 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 6.2. URN sub-namespace registration for 'urn:ietf:params:xml:ns:xcap-component' URI: urn:ietf:params:xml:ns:xcap-component Description: This is the XML namespace for an extension XML element defined by [[[RFCXXXX]]] to the 'application/xcap-diff+xml' content type. Registrant Contact: IETF, SIP working group, Jari Urpalainen, XML: BEGIN Extension element for xcap-diff

Namespace for an extension element of xcap-diff

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

See RFCXXXX.

END Urpalainen Expires June 10, 2007 [Page 11] Internet-Draft xcap diff event December 2006 6.3. XML Schema Registration This section registers a new XML Schema. URI: urn:ietf:params:xml:schema:xcap-component Registrant Contact: IETF, SIP working group, Jari Urpalainen, 7. Security Considerations The security considerations for this package are similar to those of XCAP and any event package. 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 [1]. 8. Acknowledgments The author would like to thank Jonathan Rosenberg for his valuable comments and providing the initial event package. 9. References 9.1. Normative References [1] 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. [2] Roach, A., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002. [3] Mealling, M., "The IETF XML Registry", RFC 3688, BCP 81, January 2004. [4] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Urpalainen Expires June 10, 2007 [Page 12] Internet-Draft xcap diff event December 2006 [6] Rosenberg, J., "The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)", draft-ietf-simple-xcap-12, October 2006. [7] Rosenberg, J., "An Extensible Markup Language (XML) Document Format For Indicating Changes in XML Configuration Access Protocol (XCAP) Resources", draft-ietf-simple-xcap-diff-04, October 2006. [8] Urpalainen, J., "An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors", draft-ietf-simple-xml-patch-ops-02, March 2006. [9] "Namespaces in XML (Second Edition)", W3C Recommendation REC- xml-names-20060816 , August 2006. [10] "Extensible Markup Language (XML) 1.0 (Fourth Edition)", W3C Recommendation REC-xml-20060816 , August 2006. 9.2. Informative References [11] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, "HTTP Extensions for Distributed Authoring - WebDAV", RFC 2518, February 1999. [12] Lonnfors, M., Costa-Requena, J., Leppanen, E., and H. Khartabil, "Session Initiation Protocol (SIP) extension for Partial Notification of Presence Information", draft-ietf-simple-partial-notify-08, July 2006. [13] Niemi, A., "An Extension to Session Initiation Protocol (SIP) Events for Issuing Conditional Subscriptions", draft-niemi-sip-subnot-etags-02, October 2006. Urpalainen Expires June 10, 2007 [Page 13] Internet-Draft xcap diff event December 2006 Author's Address Jari Urpalainen Nokia Itamerenkatu 11-13 Helsinki 00180 Finland Phone: +358 7180 37686 Email: jari.urpalainen@nokia.com Urpalainen Expires June 10, 2007 [Page 14] Internet-Draft xcap diff event December 2006 Intellectual Property Statement 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. Disclaimer of Validity 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 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. Copyright Statement Copyright (C) The Internet Society (2006). 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. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Urpalainen Expires June 10, 2007 [Page 15]