SIMPLE J. Rosenberg Internet-Draft dynamicsoft Expires: December 22, 2003 June 23, 2003 A Session Initiation Protocol (SIP) Event Package for Modification Events for the Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Managed Documents draft-ietf-simple-xcap-package-00 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 December 22, 2003. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This specification defines a Session Initiation Protocol (SIP) event package for finding out about changes to documents managed by the Extensible Markup Language (XML) Configuration Access Protocol (XCAP). XCAP allows a client to manipulate XML documents on a server which contain configuration information for application protocols. Multiple clients can potentially access the same document, in which case the other clients would like to be notified of a change in the document made by another. This event package allows a client to do that. Rosenberg Expires December 22, 2003 [Page 1] Internet-Draft XCAP Package June 2003 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Document Change Event Package . . . . . . . . . . . . . . . 4 2.1 Package Name . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2 Event Package Parameters . . . . . . . . . . . . . . . . . . 4 2.3 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . . 4 2.4 Subscription Duration . . . . . . . . . . . . . . . . . . . 5 2.5 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . . 5 2.6 Notifier Processing of SUBSCRIBE Requests . . . . . . . . . 6 2.7 Notifier Generation of NOTIFY Requests . . . . . . . . . . . 6 2.8 Subscriber Processing of NOTIFY Requests . . . . . . . . . . 7 2.9 Handling of Forked Requests . . . . . . . . . . . . . . . . 7 2.10 Rate of Notifications . . . . . . . . . . . . . . . . . . . 8 2.11 State Agents . . . . . . . . . . . . . . . . . . . . . . . . 8 3. application/xml-change Media Type . . . . . . . . . . . . . 9 3.1 XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2 Example Document . . . . . . . . . . . . . . . . . . . . . . 10 4. Security Considerations . . . . . . . . . . . . . . . . . . 11 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 12 5.1 SIP Event Package . . . . . . . . . . . . . . . . . . . . . 12 5.2 application/xcap-change+xml MIME Type . . . . . . . . . . . 12 5.3 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:xcap-change . . . . . . . . . . . . . 13 Normative References . . . . . . . . . . . . . . . . . . . . 15 Informative References . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . 16 Intellectual Property and Copyright Statements . . . . . . . 17 Rosenberg Expires December 22, 2003 [Page 2] Internet-Draft XCAP Package June 2003 1. Introduction The Extensible Markup Language (XML) Configuration Access Protocol (XCAP) [10] is a protocol that allows clients to manipulate XML documents stored on a server. These XML documents serve as configuration information for application protocols. As an example, resource list [11] subscriptions (also known as presence lists) allow a client to have a single SIP subscription to a list of users, where the list is maintained on a server. The server will obtain presence for those users and report it back to the client. This application requires the server, called a Resource List Server (RLS), to have access to the list of presentities. This list needs to be manipulated by clients so they can add and remove their friends as they desire. Complexities arise when multiple clients attempt to simultaneously manipulate a document, such as a presence list. Frequently, a client will keep a copy of the current list in memory, so it can render it to users. However, if another client modifies the document, the cached version becomes stale. This information must be made known to all clients which have cached copies of the document, so that they can fetch the most recent one. This problem is addressed by this specification, which provides a Session Initiation Protocol (SIP) [1]event package [2] for subscribing to changes in documents managed by an XCAP server. This package would be used by any client which is retaining a cached copy of a document obtained by XCAP, so that it can find out when a change has been made, invalidating its cached copy. In fact, the notifications generated by this package indicate the specific change which occurred in the document, so the client can decide whether the change is significant enough to warrant a refetch from the XCAP server. Rosenberg Expires December 22, 2003 [Page 3] Internet-Draft XCAP Package June 2003 2. Document Change Event Package The SIP event framework [2] defines a SIP extension for subscribing to, and receiving notifications of, events. It leaves the definition of many aspects of these events to concrete extensions, known as event packages. This document qualifies as an event package. This section fills in the information required for all event packages by RFC 3265. 2.1 Package Name The name of this package is "xcap-change". As specified in RFC 3265 [2], this value appears in the Event header field present in SUBSCRIBE and NOTIFY requests. 2.2 Event Package Parameters The SIP event framework allows event packages to define additional parameters carried in the Event header field. This package defines a single event header parameter, called "doc-component", which specifies a particular document and document component which is being to subscribed to. The request-URI specifies the user whose data is being subscribed to. By default, a subscription is for all XCAP data associated with that user. The header field parameter allows the subscription to specify a specific document and document sub-tree. The format of this header field parameter is a quoted string, whose value is the portion of an XCAP URI to the right of the directory for the user. For example, if a user wishes to subscribe to http:// xcap.example.com/services/presence-lists/users/joe/mydir/friends.xml, the event header parameter would be "mydir/friends.xml". OPEN ISSUE: What does the request URI look like for subscriptions to global data? Should the request URI instead contain the XCAP URI as the user part? Might make sense, but interacts badly with general SIP routing which is user-based. OPEN ISSUE: There is no way to specify that a subscription is to multiple documents. Multiple subscriptions would be needed for that. Is that limitation OK for now? A filter can fix that down the road. 2.3 SUBSCRIBE Bodies A SUBSCRIBE request MAY contain a body. The purpose of the body depends on its type. Subscriptions will normally not contain bodies. The Request-URI, which identifies the user whose data is being Rosenberg Expires December 22, 2003 [Page 4] Internet-Draft XCAP Package June 2003 subscribed to, combined with the event package name and parameter, is sufficient for this package. One type of body that can be included in a SUBSCRIBE request is a filter document. These filters request that only document change events generate notifications, or would ask for a restriction on the set of data returned in NOTIFY requests. Filter documents are not specified in this document, and at the time of writing, are expected to be the subject of future standardization activity. Honoring of these filters is at the policy discretion of the notifier. If the SUBSCRIBE request does not contain a filter, this tells the notifier that no filter is to be applied. The notifier SHOULD send NOTIFY requests at the discretion of its own policy. 2.4 Subscription Duration Generally speaking, changes to application configuration data are relatively infrequent. Of course, this depends on the type of application, but generally configuration data is static. As a result, notifications are expected infrequently, and subscriptions will typically be held for long periods of time. This would argue for long subscription refresh intervals. For this reason, the default subscription duration is two hours. Of course, a different duration can be requested by a client, or set by a server, using the Expires header field, as per RFC 3265 [2]. 2.5 NOTIFY Bodies As described in RFC 3265 [2], the NOTIFY message will contain bodies that describe the state of the subscribed resource. This body is in a format listed in the Accept header field of the SUBSCRIBE, or a package-specific default if the Accept header field was omitted from the SUBSCRIBE. In this event package, the body of the notification contains a document change document. This document describes the current version of an XML document managed by XCAP, in addition to the changes in this document from the previous version. Note that a listing of changes from the previous version is only sent in a NOTIFY triggered by a change to the document. NOTIFY requests sent in response to an initial SUBSCRIBE, or a SUBSCRIBE refresh, only indicate the current version of the XML document. They do not contain the actual full contents of the XML document. In other words, the resource being subscribed to is NOT the XML document itself, but rather, the version history for the document. Rosenberg Expires December 22, 2003 [Page 5] Internet-Draft XCAP Package June 2003 All subscribers and notifiers MUST support the "application/ xcap-change+xml" data format described in Section 3. The subscribe request MAY contain an Accept header field. If no such header field is present, it has a default value of "application/xcap-change+xml". If the header field is present, it MUST include "application/ xcap-change+xml", and MAY include any other types capable of representing changes in XCAP documents. 2.6 Notifier Processing of SUBSCRIBE Requests This subsection defines package-specific processing at the notifier when it receives a SUBSCRIBE request. General processing rules for requests are covered in Section 8.2 of RFC 3261 [1], in addition to general SUBSCRIBE processing in RFC 3265 [2]. A notifier for this package SHOULD authenticate all subscribers. Generally, subscribers will have a pre-existing relationship with the notifier. This is because the principle application of this package is for a client of XCAP (which will have a relationship with the XCAP server) to find out about changes in cached documents. Therefore, the HTTP Digest mechanism in SIP is a good match for authentication, and MUST be supported by all clients and servers. Note that this authentication mechanism is already mandatory for all SIP-compliant implementations. Once authenticated, the server SHOULD authorize the subscriber. Generally, this authorization policy SHOULD mirror the authorization policy defined in an XCAP application usage for read access. Thats because this package provides a form of read-access, and the permissions should not differ based on whether the read is performed with XCAP or with a SIP SUBSCRIBE request. 2.7 Notifier Generation of NOTIFY Requests RFC 3265 details the formatting and structure of NOTIFY messages. However, packages are mandated to provide detailed information on when to send a NOTIFY, how to compute the state of the resource, how to generate neutral or fake state information, and whether state information is complete or partial. This section describes those details for the presence event package. A notifier MAY send a notification at any time. Typically, it will send one after a document managed by an XCAP server has changed as the result of an XCAP operation. This notification contains an application/xcap-change+xml document that specifies the current version (as a server modification time) for the XML document being subscribed to. It also contains information about what changed - whether a new element or attribute was added, whether an existing one Rosenberg Expires December 22, 2003 [Page 6] Internet-Draft XCAP Package June 2003 changed, or whether an existing one was deleted, and indicates against which version those changes were made. The xcap-change document also contains a hash of the new XML document. Notifications sent in response to SUBSCRIBE requests (either initial or refresh), or sent when there is a change in subscription state, will normally only contain the current version of the XML document being subscribed to. The body of the NOTIFY MUST be sent using one of the types listed in the Accept header field in the most recent SUBSCRIBE request, or using the type "application/xcap-change+xml" if no Accept header field was present. 2.8 Subscriber Processing of NOTIFY Requests RFC 3265 [2] leaves it to event packages to describe the process followed by the subscriber upon receipt of a NOTIFY request, including any logic required to form a coherent resource state. In this package, the notifications can be optionally used by the client to determine the state of the XML document being subscribed to. When a client receives a notification, it checks the version against which the changes are relative. If this is not the same as the version currently cached by the client, the client SHOULD use XCAP to fetch the latest version of the document. If it is the same, the client applies the change to its local cache of the document. To apply the changes, the client follows the procedures defined by XCAP [10] as if it were the HTTP server. After applying the changes, the client applies the mandatory XML canonicalization defined in the Canonical XML 1.0 [3] specification, and computes an HMAC [12] using SHA1 over this canonical document, with a key whose value is 0x2238a. The resulting string is compared with the hash attribute of the xml-change document. If they match, the client can be sure that it has the most up to date version. If they don't match, the client SHOULD fetch the most current version of the document. Of course, this mechanism for computing the most current document from the hash is optional. A client can elect to ignore the information on what changed and simply fetch the most recent document every time it gets a change indication where the new version is not the same as the one cached by the client. 2.9 Handling of Forked Requests RFC 3265 [2] requires each package to describe handling of forked SUBSCRIBE requests. Rosenberg Expires December 22, 2003 [Page 7] Internet-Draft XCAP Package June 2003 This specification only allows a single dialog to be constructed as a result of emitting an initial SUBSCRIBE request. Section 4.4.9 of RFC 3265 [2] describes the processing that is required to guarantee the creation of a single dialog in response to a SUBSCRIBE request. 2.10 Rate of Notifications RFC 3265 [2] requires each package to specify the maximum rate at which notifications can be sent. A notifier SHOULD NOT generate notifications at a rate of more than once every five seconds. 2.11 State Agents RFC 3265 [2] requires each package to consider the role of state agents in the package, and if they are used, to specify how authentication and authorization are done. State agents play no role in this package. Rosenberg Expires December 22, 2003 [Page 8] Internet-Draft XCAP Package June 2003 3. application/xml-change Media Type An xml-change document is an XML [4] document that MUST be well-formed and SHOULD be valid. XML-change documents MUST be based on XML 1.0 and MUST be encoded using UTF-8. This specification makes use of XML namespaces for identifying xml-change documents and document fragments. The namespace URI for elements defined by this specification is a URN [5], using the namespace identifier 'ietf' defined by [7] and extended by [8]. This URN is: urn:ietf:params:xml:ns:xml-change An xml-change document begins with the root element tag "documents". It consists of any number of "document" sub-elements, each of which conveys information on a particular document. Other elements from different namespaces MAY be present for the purposes of extensibility; elements or attributes from unknown namespaces MUST be ignored. There is one attribute associated with this element: uri: specifies the HTTP URI that references this document. This attribute is mandatory. Each "document" element consists of zero or more "change" elements, each of which conveys information about a specific change to the document. Other elements from different namespaces MAY be present for the purposes of extensibility; elements or attributes from unknown namespaces MUST be ignored. There are three attributes associated with this element: version: specifies the new version of the document, expressed as an HTTP-Date [9]. This attribute is mandatory. previous: specifies the previous version of the document, expressed as an HTTP-Date, against which the changes are relative. This attribute MUST be present if any change sub-elements are present. hash: specifies an HMAC of the new document, represented in canonical form. See Section 2.8 for details on how this value is computed. This attribute MUST be present if any change sub-elements are present. Each "change" element contains either text, or additional XML content. This content is the same as that which appeared in the body of the HTTP request which caused modification of the document. There are two attributes associated with this element: Rosenberg Expires December 22, 2003 [Page 9] Internet-Draft XCAP Package June 2003 uri: contains the URI that the HTTP request contained in the Request-URI. This attribute is mandatory. method: contains the method of the HTTP request. This attribute is mandatory. OPEN ISSUE: Probably it would be better to describe the changes more generically, rather than binding them to the specifics of XCAP. 3.1 XML Schema TBD. 3.2 Example Document The following is an example of a document compliant to the schema: sip:bob@example.com Rosenberg Expires December 22, 2003 [Page 10] Internet-Draft XCAP Package June 2003 4. Security Considerations The security considerations for this package are similar to those of XCAP. The configuration data can contain sensitive information, and both the client and the server need to authenticate each other. As such, a notifier for this package MUST support HTTP Digest to authenticate subscribers. Notifiers and subscribers MAY use SIPs S/ MIME feature to provide authentication and message integrity. Rosenberg Expires December 22, 2003 [Page 11] Internet-Draft XCAP Package June 2003 5. IANA Considerations There are several IANA considerations associated with this specification. 5.1 SIP 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: presence Package or Template-Package: This is a package. Published Document: RFC XXXX (Note to RFC Editor: Please fill in XXXX with the RFC number of this specification). Person to Contact: Jonathan Rosenberg, jdrosen@jdrosen.net. 5.2 application/xcap-change+xml MIME Type MIME media type name: application MIME subtype name: xcap-change+xml Mandatory parameters: none Optional parameters: Same as charset parameter application/xml as specified in RFC 3023 [6]. Encoding considerations: Same as encoding considerations of application/xml as specified in RFC 3023 [6]. Security considerations: See Section 10 of RFC 3023 [6] and Section 4 of this specification. Interoperability considerations: none. Published specification: This document. Applications which use this media type: This document type has been used to support manipulation of presence lists [13] using XCAP. Rosenberg Expires December 22, 2003 [Page 12] Internet-Draft XCAP Package June 2003 Additional Information: Magic Number: None File Extension: .xcd or .xml Macintosh file type code: "TEXT" Personal and email address for further information: Jonathan Rosenberg, jdrosen@jdrosen.net Intended usage: COMMON Author/Change controller: The IETF. 5.3 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:xcap-change This section registers a new XML namespace, as per the guidelines in [8] URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-change. Registrant Contact: IETF, SIMPLE working group, (simple@mailman.dynamicsoft.com), Jonathan Rosenberg (jdrosen@jdrosen.net). XML: BEGIN XCAP Change Namespace

Namespace for XCAP Change

application/xcap-change+xml

See RFCXXXX.

Rosenberg Expires December 22, 2003 [Page 13] Internet-Draft XCAP Package June 2003 END Rosenberg Expires December 22, 2003 [Page 14] Internet-Draft XCAP Package June 2003 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] Boyer, J., "Canonical XML Version 1.0", W3C REC REC-xml-c14n-20010315, March 2001. [4] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C REC REC-xml-20001006, October 2000. [5] Moats, R., "URN Syntax", RFC 2141, May 1997. [6] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC 3023, January 2001. [7] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, August 1999. [8] Mealling, M., "The IETF XML Registry", draft-mealling-iana-xmlns-registry-05 (work in progress), June 2003. [9] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [10] Rosenberg, J., "The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)", draft-rosenberg-simple-xcap-00 (work in progress), May 2003. Rosenberg Expires December 22, 2003 [Page 15] Internet-Draft XCAP Package June 2003 Informative References [11] Rosenberg, J., Roach, A. and B. Campbell, "A Session Initiation Protocol (SIP) Event Notification Extension for Resource Lists", draft-ietf-simple-event-list-04 (work in progress), June 2003. [12] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. [13] Rosenberg, J., "An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Usage for Presence Lists", draft-rosenberg-simple-xcap-list-usage-00 (work in progress), May 2003. Author's Address Jonathan Rosenberg dynamicsoft 600 Lanidex Plaza Parsippany, NJ 07054 US Phone: +1 973 952-5000 EMail: jdrosen@dynamicsoft.com URI: http://www.jdrosen.net Rosenberg Expires December 22, 2003 [Page 16] Internet-Draft XCAP Package June 2003 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property 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; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication 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 implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Rosenberg Expires December 22, 2003 [Page 17] Internet-Draft XCAP Package June 2003 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Rosenberg Expires December 22, 2003 [Page 18]