SIMPLE Working Group M. Garcia-Martin Internet-Draft Nokia Expires: December 8, 2004 June 9, 2004 An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Usage for XML Documents Directory draft-garcia-simple-xcap-directory-00.txt Status of this Memo By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. 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 8, 2004. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract The general assumption of XCAP is that a client selects a document in a XCAP server in order to manipulate data. This requires the XCAP client to know the path of the XCAP-manipulatable XML document stored in the XCAP server. This specification allows an XCAP client to retrieve its directory of XCAP-manipulatable XML documents from an XCAP server. Garcia-Martin Expires December 8, 2004 [Page 1] Internet-Draft XCAP directory June 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Overview of operation . . . . . . . . . . . . . . . . . . . 5 6. The XCAP Directory . . . . . . . . . . . . . . . . . . . . . 6 7. Example Document . . . . . . . . . . . . . . . . . . . . . . 7 8. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . 7 9. Usage with XCAP . . . . . . . . . . . . . . . . . . . . . . 8 9.1 Application Unique ID . . . . . . . . . . . . . . . . . . 9 9.2 MIME Type . . . . . . . . . . . . . . . . . . . . . . . . 9 9.3 XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 9 9.4 Additional Constraints . . . . . . . . . . . . . . . . . . 9 9.5 Data Semantics . . . . . . . . . . . . . . . . . . . . . . 9 9.6 Naming Conventions . . . . . . . . . . . . . . . . . . . . 9 9.7 Data Interdependencies . . . . . . . . . . . . . . . . . . 10 9.8 Authorization Policies . . . . . . . . . . . . . . . . . . 10 10. Example of operation . . . . . . . . . . . . . . . . . . . . 10 11. Security Considerations . . . . . . . . . . . . . . . . . . 11 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . 11 12.1 XCAP Application Usage ID . . . . . . . . . . . . . . . 11 12.2 application/directory+xml MIME Type . . . . . . . . . . 12 12.3 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:xcap-directory . . . . . . . . . 12 12.4 XCAP Directory Schema Registration . . . . . . . . . . . 13 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 14.1 Normative References . . . . . . . . . . . . . . . . . . . 14 14.2 Informational References . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . 15 Intellectual Property and Copyright Statements . . . . . . . 16 Garcia-Martin Expires December 8, 2004 [Page 2] Internet-Draft XCAP directory June 2004 1. Introduction XCAP [7] defines a model whereby an XCAP client can create, read, write and modify application configuration data stored in XML format on an XCAP server. XCAP is a modular protocol that allows a particular XCAP application usage to define the way in which a particular application makes usage of XCAP. XCAP operates on a single XML document basis: XCAP selects a document or an XML element within a document and operates on it. Each XCAP application typically allows XCAP operations to take place in a number of different XML documents. For instance, the XML Resource List [9] allows an XCAP client to create one or more resource lists. A watcher may classify their contacts by their relation to the watcher, so the watcher may create a resource list that includes their list of friends, another resource list that includes their list of coworkers and another resource list that includes the members of their family. This approach allows the watcher to subscribe to each of these lists individually. In another scenario it is envisioned that a user might be able to manipulate a number of XML documents stored in the XCAP server and pertaining to different XCAP application usages. For example, a user may be manipulating XML resource list documents [9], a PIDF manipulation documents [10], a presence authorization rules documents [11], etc. Each of those constitute a different XCAP application usage. While XCAP allows the XCAP to manipulate the documents, giving that the XCAP client is provisioned with the URI that points to the XML document, XCAP is not able to provide a directory of the documents that the XCAP client is able to manipulate. This specification provides a solution that allows XCAP clients to find out the list of XML documents stored in the XCAP server that the user can manipulate with XCAP. 2. Motivation XCAP assumes that an XCAP client that is willing to manipulate an XML document is provisioned with a URI that points to the XCAP document or element that the user wants to manipulate. XCAP defines rules to build the URI that points to a specific XML document or node within a document. This XCAP URI is created from the concatenation of the following elements: the XCAP services root URI, (which includes the HTTP URI of the XCAP server), the XCAP Application Usage ID (AUID), the "global" or "users" directory for that application, the name of the XML document to be manipulated, and a node selector within that document. Garcia-Martin Expires December 8, 2004 [Page 3] Internet-Draft XCAP directory June 2004 XCAP does not define how to provision the above portions of the XCAP URI. In particular, it is assumed that the XCAP root services URI (including the HTTP URI of the XCAP server) is provisioned in the XCAP client or learnt by some means outside the scope of the XCAP specification. XCAP also assumes that the AUID is configured or known by the XCAP client, so is the name of the XML document that the user wants to manipulate. Specifically, XCAP does not provide the means for an XCAP client to find out the name of the XML documents that the user owns for a particular application usage, nor it provides the means for the XCAP client to find a list of XML documents belonging to other XCAP application usages. While we recognize that all these elements can be configured or provisioned in a particular XCAP client, however, factors such as the increasing number of XCAP application usages or the multiplicity of resource lists may create a burden for the users. The issue is significant when a user tries to manipulate data from an XCAP client that is not their usual XCAP client. For instance, a user may be logged in terminal at an airport or just using a friend's mobile device. In all these cases the user should provide the full URI to each of the documents he is willing to manipulate. This requires the user to remember the name of the XML documents (e.g., resource lists) stored in the XCAP server. 3. Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 [1] and indicate requirement levels for compliant implementations. 4. Requirements What is required is a mechanism that minimizes the configuration of XCAP clients and allows users to get the URI of XCAP-manipulatable XML documents stored in a XCAP server. The formal expression of the requirements is: REQ-1: An XCAP client MUST be able to retrieve the directory of XCAP-manipulatable XML documents stored in an XCAP server. REQ-2: The mechanism SHOULD require a minimum configuration in the XCAP client. Garcia-Martin Expires December 8, 2004 [Page 4] Internet-Draft XCAP directory June 2004 REQ-3: The response from the server MUST contain all the required information that allows the XCAP client to manipulate XML document listed in the directory. REQ-4: The response from the server MUST contain all the required information that allows the user to decide whether to it is needed to retrieve a fresh copy of any of the documents is up to date. REQ-5: It MUST be possible to return the list of XCAP-manipulatable documents pertaining to different XCAP application usages. REQ-6: The XCAP client MUST be able to search for the directory of documents pertaining to a specific XCAP application usage. 5. Overview of operation We define a new XCAP application usage named "directory". The "directory" XCAP application usage has its own namespace identifier, XML schema, XCAP AUID and MIME-type. We also define the conventions to access the XCAP hierarchy. An XCAP client that wants to retrieve the directory of XML documents that are stored in the server for the user does an XCAP Fetch operation (HTTP GET method) on the directory document. The XCAP server returns an XCAP directory document built according to the XML schema defined in this specification. The directory XML document contains a list of all the other XML documents under the user's path hierarchy stored in that XCAP server. A user can typically read their own XCAP directory document. We disallow user operations to manipulate the XCAP directory document since the kind of information included in an XCAP directory document is meant to be read by the user rather than written by the user. We define a model where the XCAP directory document of a user changes whenever another user-related XML document changes in the XCAP server. We model the XCAP server as being authorized to do write operations on the XCAP directory documents of its users. Of course, we don't intend to mandate any specific implementation, but just try to define the logical model. For example, an implementation may decide to create XCAP directory documents "on the fly", e.g., at the time an XCAP fetch operation of the XCAP directory document is invoked. Other implementations may decide to keep a static document that is updated whenever other documents are created, deleted, or updated. Both implementations are possible and in both cases the result is the same: the directory of XCAP-manipulatable documents that a user can manipulated in an XCAP server is sent to the user. Garcia-Martin Expires December 8, 2004 [Page 5] Internet-Draft XCAP directory June 2004 6. The XCAP Directory An XCAP-directory is an XML [8] document that MUST be well-formed and SHOULD be valid. XCAP directory documents MUST be based on XML 1.0 and MUST be encoded using UTF-8. This specification makes use of XML namespaces for identifying XCAP directory documents and document fragments. The namespace URI for elements defined by this specification is a URN [2], using the namespace identifier 'ietf' defined by RFC 2648 [4] and extended by RFC 3688 [6]. This URN is: urn:ietf:params:xml:ns:xcap-directory An XCAP directory document begins with the root element tag . It contains an optional element (required by and defined in XCAP [7]) followed by a number of elements, each of which identifies an XCAP-manipulatable XML document. There are three attributes associated to the element: uri: contains a URI pointing to the document stored in the XCAP server. This URI MUST be an HTTP URI identifying an XCAP resource. auid: contains the XCAP Application Usage ID of the XML document. etag: contains the server computed etag of the current instance of the XML document. This allows the XCAP client to determine whether the local cached copy of a document is up-to-date. last-modified: this optional attribute contains the date and time when the document was last modified. This allows the user to determine whether a document has changed recently or not. size: this optional attribute contains the size, expressed in octets, of the XML document. This allows the user to determine whether it wants to refresh a copy or not based on the length of the document (for instance, the user might be connected to a low bandwidth link). id: this optional attribute contains a unique identifier generated by the XCAP server. The 'id' attribute MUST be unique amongst all the other 'id' elements of the same parent. For extensibility purposes, the element can contain attributes imported from other namespaces. The element can contain a element. This Garcia-Martin Expires December 8, 2004 [Page 6] Internet-Draft XCAP directory June 2004 element provides a UTF-8 encoded string, meant for consumption by the user, that describes the resource. For extensibility purposes, other elements from other namespaces MAY be included. 7. Example Document The following is an example of an document that shows three XCAP-manipulatable XML documents. Two are presence lists, the last one is a presence authorization rules. The two presence lists indicate the size of the document and date and time when the last modification took place. My list of friends My list of family members 8. XML Schema 9. Usage with XCAP XCAP-directory documents can be manipulated with XCAP. Note, however, that we don't expect other type of manipulation that XCAP fetch operations executed on the whole document or a selection of elements. Especially, it is not intended that XCAP clients modify or delete other XML documents by doing XCAP delete or modify operations on the XCAP-directory document. It is RECOMMENDED that XCAP servers implement policy to disallow delete and modify operations on the XCAP directory document. The rest of this section provides the details for the XCAP usage of XCAP-directory documents. Garcia-Martin Expires December 8, 2004 [Page 8] Internet-Draft XCAP directory June 2004 9.1 Application Unique ID XCAP requires application usages to define a unique application usage ID (AUID) in either the IETF tree or vendor tree. This specifications defines the "directory" AUID within the IETF tree via the IANA registration in Section 12. 9.2 MIME Type The MIME type for this document is "application/directory+xml". 9.3 XML Schema The XML Schema for this document is defined as the sole content of Section 8. 9.4 Additional Constraints None. 9.5 Data Semantics Semantics for the document content are provided in Section 6. 9.6 Naming Conventions This XCAP application tries to minimize the configuration of XCAP clients. Still, the XCAP services root URI has to be configured in the XCAP client and we don't provide a mechanism to get around this configuration. Without further intervention, the name of the XCAP-directory document still has to be configured, since XCAP requires to select a particular document before it can be retrieved. Since there is only one XCAP-directory document per user we can easily minimize the configuration in XCAP clients by defining a convention for naming the XCAP-directory document. An XCAP server SHOULD assign XCAP-directory documents the name "directory.xml". OPEN ISSUE: or shall we define an empty document or the "/" name and leave at the discretion of the XCAP server to return the appropriate document? This will be similar to HTTP servers that return the "index.html" file when "/" is the file name specified in the GET request. Therefore, an XCAP client that tries to find the user's XCAP directory will send an HTTP GET request to http://[xcap root services uri]/directory/users/[username]/directory.xml. Garcia-Martin Expires December 8, 2004 [Page 9] Internet-Draft XCAP directory June 2004 9.7 Data Interdependencies None. 9.8 Authorization Policies An XCAP-Directory document is meant to be created and modified by an XCAP server itself. The XCAP server does write operations whenever any other XCAP-manipulatable XML document is created or deleted. However, it is not the intention of this XCAP application to allow users itself to do any other than fetch operations on this document. Therefore, XCAP servers SHOULD NOT allow the user to modify and SHOULD allow the user to fetch their own XCAP-directory documents. By default, only the user is able to read their own XCAP-directory document. A user may provide permissions for other users to fetch the XCAP-directory document or part of it. A future application usage will define which users are allowed to read the XCAP-directory document of a particular user. 10. Example of operation The following is an example of an XCAP fetch operation for the whole XCAP directory document invoked on a user by name "bill". GET http://xcap.example.com/services/directory/users/ bill/directory.xml HTTP/1.1 and as a result it gets the following response: Garcia-Martin Expires December 8, 2004 [Page 10] Internet-Draft XCAP directory June 2004 HTTP/1.1 200 OK Etag: "79se2dmb" Content-Type: application/directory+xml My presence list Then Bill's XCAP client may decide to fetch any of the listed documents based on the HTTP URI of the XCAP resource. The 'etag' attribute may play a role to help Bill's XCAP client to decide whether a locally cached copy is up-to-date or not. Additionally, Bill may not have a local cached copy of his presence resource list, but since it has not changed for long time, he may decide not to fetch it. 11. Security Considerations The configuration data defined by this application may be sensitive. As indicated by the XCAP specification [7] clients SHOULD use TLS [3] when communicating with XCAP servers. 12. IANA Considerations This specification has the following IANA considerations. 12.1 XCAP Application Usage ID According to the procedures defined in the XCAP specification [7], this specification register a new XCAP Application Usage ID (AUID). Garcia-Martin Expires December 8, 2004 [Page 11] Internet-Draft XCAP directory June 2004 Name of the AUID: directory Description: An XCAP directory is an application that allows an XCAP client to fetch the list of XCAP-manipulatable XML documents stored in the XCAP server. 12.2 application/directory+xml MIME Type MIME media type name: application MIME subtype name: directory+xml Optional parameters: Same as charset parameter application/xml as specified in RFC 3023 [5]. Encoding considerations: Same as encoding considerations of application/xml as specified in RFC 3023 [5]. Security considerations: See Section 10 of RFC 3023 [5] and Section 11 of this specification. Interoperability considerations: none. Published specification: this document. Applications which use this media type: this document type is used to support the directory of XCAP-manipulatable documents. Magic Number: none File Extension: .xml Macintosh file type code: "TEXT" Personal and e-mail address for further information: Miguel Garcia, miguel.an.garcia@nokia.com Author/Change controller: the IETF. 12.3 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:xcap-directory This section registers a new XML namespace, as per the guidelines in RFC 3688 [6]. Garcia-Martin Expires December 8, 2004 [Page 12] Internet-Draft XCAP directory June 2004 URI: urn:ietf:params:xml:ns:xcap-directory Registrant contact: IETF, SIMPLE working group, (simple@ietf.org), Miguel Garcia (miguel.an.garcia@nokia.com). XML BEGIN XCAP directory Namespace

Namespace for XCAP directory

application/directory+xml

See RFCXXXX.

END 12.4 XCAP Directory Schema Registration This section registers an XML schema per the procedures in RFC 3688 [6]. URI: [please assign] Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), Miguel Garcia (miguel.an.garcia@nokia.com). The XML for this schema can be found as the sole content of Section 8. 13. Acknowledgements The author would like to thank Jari Urpalainen for his advice in the schema design. 14. References Garcia-Martin Expires December 8, 2004 [Page 13] Internet-Draft XCAP directory June 2004 14.1 Normative References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] Moats, R., "URN Syntax", RFC 2141, May 1997. [3] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. [4] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, August 1999. [5] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC 3023, January 2001. [6] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [7] Rosenberg, J., "The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)", draft-ietf-simple-xcap-02 (work in progress), February 2004. [8] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C FirstEdition REC-xml-20001006, October 2000. 14.2 Informational References [9] Rosenberg, J., "An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Usage for Presence Lists", draft-ietf-simple-xcap-list-usage-02 (work in progress), February 2004. [10] Isomaki, M., "An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Usage for Manipulating Presence Document Contents", draft-ietf-simple-xcap-pidf-manipulation-usage-00 (work in progress), May 2004. [11] Rosenberg, J., "Presence Authorization Rules", draft-ietf-simple-presence-rules-00 (work in progress), May 2004. Garcia-Martin Expires December 8, 2004 [Page 14] Internet-Draft XCAP directory June 2004 Author's Address Miguel A. Garcia-Martin Nokia P.O.Box 407 NOKIA GROUP, FIN 00045 Finland EMail: miguel.an.garcia@nokia.com Garcia-Martin Expires December 8, 2004 [Page 15] Internet-Draft XCAP directory June 2004 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 (2004). 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. Garcia-Martin Expires December 8, 2004 [Page 16]