SIP WG J. Urpalainen Internet-Draft Nokia Intended status: Standards Track March 5, 2007 Expires: September 6, 2007 An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Diff Event Package draft-urpalainen-sip-xcap-diff-event-01 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 September 6, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). 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 September 6, 2007 [Page 1] Internet-Draft xcap diff event March 2007 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 . . . . . . . . . . 7 4.6.2. The 'node-sel' attribute . . . . . . . . . . . . . . . 7 4.6.3. The 'exists' attribute . . . . . . . . . . . . . . . . 8 4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 8 4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 9 4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 9 4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 9 4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 9 5. An Initial Example NOTIFY document . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 9.1. Normative References . . . . . . . . . . . . . . . . . . . 13 9.2. Informative References . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 Intellectual Property and Copyright Statements . . . . . . . . . . 15 Urpalainen Expires September 6, 2007 [Page 2] Internet-Draft xcap diff event March 2007 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 clients can receive references to XCAP documents and also the partial changes of XCAP resources. 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. The notification information is based on using the XCAP-Diff [7] format which is extended by this document to allow 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 September 6, 2007 [Page 3] Internet-Draft xcap diff event March 2007 other words, has privilege to them. After receiving those documents and resolving the initial synchronization stage, the client starts applying the patches of documents received from the server. While the initial document synchronization is based on separate HTTP retrievals of full documents, 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 is no conventions for patching this XCAP component. Therefore the useful state information is whether a single, unique node exist in the source document or not. With XML elements multiple nodes could be found, which is an error case in XCAP and consequently also in this event package. The notifier SHOULD signal this error with 'exists' attribute semantics described in Section 4.6.3. If during the initial subscription stage the requested node can not be found, there is not need for a result element either. Once it will be created, the notify will contain this new component. And similarly, the component removal will be reported for example after a successful HTTP DELETE request. 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 not need XML-Patching at all. Indeed, the subscriber just wants to be informed whenever some document changes. The XCAP-Diff [7] format will then only report document creations, updates and removals. The usage of this use-case is described in Section 4.3.2. 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 mandatory "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 Urpalainen Expires September 6, 2007 [Page 4] Internet-Draft xcap diff event March 2007 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; 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 path segment. An example about a subscription 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 once a unique node exists in the source document. It should be noted that the path parameter value is in the percent encoded form. As the result XML element is typically namespace qualified, all needed namespace declarations MUST exist within the document. The possible local namespace declarations within the result element exist unmodified as in the source document, similar to XCAP conventions. Other namespace references MUST be resolved from the context of the or its parent elements. The prefixes of qualified names (QName) [9] of XML nodes also remain as they exist originally in the source document. The last example is about subscription 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 (once the 'name' attribute exists): the 'name' attribute value within the child text node content of the element without attribute value separation characters. The formal grammar (RFC 4234 [4]) of the "path" parameter: Urpalainen Expires September 6, 2007 [Page 5] Internet-Draft xcap diff event March 2007 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 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 only document or XCAP component changes MUST be reported. The "aggregate" value means that the notifier is free to aggregate several 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 the client receives the full ETag change history of a document. In other words, "XML-Patching" is the default mode but the notifier MUST not aggregate individual XCAP component updates together. An example for requesting of all document changes the user is authorized to, or has privilege: Event: xcap-diff; path=""; diff-processing="aggregate" 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 of the element when the subscriber is requesting the state or "value" of XCAP components. Urpalainen Expires September 6, 2007 [Page 6] Internet-Draft xcap diff event March 2007 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]. 4.6.2. The 'node-sel' attribute The value of the mandatory 'node-sel' attribute is the percent encoded XCAP Node Selector. Urpalainen Expires September 6, 2007 [Page 7] Internet-Draft xcap diff event March 2007 4.6.3. The 'exists' attribute This optional attribute is used to signal the removal of an XCAP component, i.e. if the notifier has provided before an XCAP component within the subscription, the removal of such a component from the XCAP source document is notified to the client by adding this attribute with the value "none" into the element. In an error case where the selector value locates several elements, this attribute value MUST be "multiple". The content of the element MUST be empty whenever it contains the 'exists' attribute. 4.7. Notifier Generation of NOTIFY Requests During the initial subscription the notifier must first resolve the requested XCAP resources. 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 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 notify response. After the accessible XCAP resources are known, the notifier will generate then the first full response. 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 to the subscribed client. 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 it. Support for XCAP component subscriptions is mandatory in the server, however. Event packages like this require in practice a reliable transfer of events as otherwise patching will typically fail. RFC 3265 [2] Urpalainen Expires September 6, 2007 [Page 8] Internet-Draft xcap diff event March 2007 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 with the HTTP protocol, the subscriber can compare all the ETag values and resolve this initial synchronization stage properly. Once each XCAP-Diff notification contains both previous and new ETags of a resource, it is easy to chain the notify list and possibly omit some of the patches based on the received ETag (with HTTP) of a resource. 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. 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. Urpalainen Expires September 6, 2007 [Page 9] Internet-Draft xcap diff event March 2007 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" 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. Urpalainen Expires September 6, 2007 [Page 10] Internet-Draft xcap diff event March 2007 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]. 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: Urpalainen Expires September 6, 2007 [Page 11] Internet-Draft xcap diff event March 2007 BEGIN Extension element for xcap-diff

Namespace for an extension element of xcap-diff

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

See RFCXXXX.

END 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 and Pavel Dostal and Krisztian Kiss for their valuable comments. Urpalainen Expires September 6, 2007 [Page 12] Internet-Draft xcap diff event March 2007 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. [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", Urpalainen Expires September 6, 2007 [Page 13] Internet-Draft xcap diff event March 2007 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-03, March 2007. Author's Address Jari Urpalainen Nokia Itamerenkatu 11-13 Helsinki 00180 Finland Phone: +358 7180 37686 Email: jari.urpalainen@nokia.com Urpalainen Expires September 6, 2007 [Page 14] Internet-Draft xcap diff event March 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 September 6, 2007 [Page 15]