| < draft-ietf-simple-xcap-00.txt | draft-ietf-simple-xcap-01.txt > | |||
|---|---|---|---|---|
| SIMPLE J. Rosenberg | SIMPLE J. Rosenberg | |||
| Internet-Draft dynamicsoft | Internet-Draft dynamicsoft | |||
| Expires: December 22, 2003 June 23, 2003 | Expires: April 26, 2004 October 27, 2003 | |||
| The Extensible Markup Language (XML) Configuration Access Protocol | The Extensible Markup Language (XML) Configuration Access Protocol | |||
| (XCAP) | (XCAP) | |||
| draft-ietf-simple-xcap-00 | draft-ietf-simple-xcap-01 | |||
| Status of this Memo | Status of this Memo | |||
| This document is an Internet-Draft and is in full conformance with | This document is an Internet-Draft and is in full conformance with | |||
| all provisions of Section 10 of RFC2026. | all provisions of Section 10 of RFC2026. | |||
| Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
| Task Force (IETF), its areas, and its working groups. Note that other | Task Force (IETF), its areas, and its working groups. Note that other | |||
| groups may also distribute working documents as Internet-Drafts. | groups may also distribute working documents as Internet-Drafts. | |||
| skipping to change at page 1, line 31 ¶ | skipping to change at page 1, line 31 ¶ | |||
| and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
| time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
| material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
| The list of current Internet-Drafts can be accessed at http:// | The list of current Internet-Drafts can be accessed at http:// | |||
| www.ietf.org/ietf/1id-abstracts.txt. | www.ietf.org/ietf/1id-abstracts.txt. | |||
| The list of Internet-Draft Shadow Directories can be accessed at | The list of Internet-Draft Shadow Directories can be accessed at | |||
| http://www.ietf.org/shadow.html. | http://www.ietf.org/shadow.html. | |||
| This Internet-Draft will expire on December 22, 2003. | This Internet-Draft will expire on April 26, 2004. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (C) The Internet Society (2003). All Rights Reserved. | Copyright (C) The Internet Society (2003). All Rights Reserved. | |||
| Abstract | Abstract | |||
| This specification defines the Extensible Markup Language (XML) | This specification defines the Extensible Markup Language (XML) | |||
| Configuration Access Protocol (XCAP). XCAP allows a client to read, | Configuration Access Protocol (XCAP). XCAP allows a client to read, | |||
| write and modify application configuration data, stored in XML format | write and modify application configuration data, stored in XML format | |||
| skipping to change at page 2, line 14 ¶ | skipping to change at page 2, line 14 ¶ | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4 | 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4 | |||
| 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 | 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
| 4. Application Usages . . . . . . . . . . . . . . . . . . . . . 6 | 4. Application Usages . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 5. URI Construction . . . . . . . . . . . . . . . . . . . . . . 8 | 5. URI Construction . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| 5.1 Identifying the XML Document . . . . . . . . . . . . . . . . 8 | 5.1 Identifying the XML Document . . . . . . . . . . . . . . . . 8 | |||
| 5.2 Identifying the XML Nodes . . . . . . . . . . . . . . . . . 9 | 5.2 Identifying the XML Nodes . . . . . . . . . . . . . . . . . 9 | |||
| 6. Client Operations . . . . . . . . . . . . . . . . . . . . . 10 | 6. Client Operations . . . . . . . . . . . . . . . . . . . . . 12 | |||
| 6.1 Creating a New Document . . . . . . . . . . . . . . . . . . 10 | 6.1 Creating a New Document . . . . . . . . . . . . . . . . . . 12 | |||
| 6.2 Replace an Existing Document . . . . . . . . . . . . . . . . 10 | 6.2 Replace an Existing Document . . . . . . . . . . . . . . . . 12 | |||
| 6.3 Deleting a Document . . . . . . . . . . . . . . . . . . . . 10 | 6.3 Deleting a Document . . . . . . . . . . . . . . . . . . . . 12 | |||
| 6.4 Fetching a Document . . . . . . . . . . . . . . . . . . . . 10 | 6.4 Fetching a Document . . . . . . . . . . . . . . . . . . . . 12 | |||
| 6.5 Creating a New Element . . . . . . . . . . . . . . . . . . . 10 | 6.5 Creating a New Element . . . . . . . . . . . . . . . . . . . 12 | |||
| 6.6 Replacing an Element in the Document . . . . . . . . . . . . 11 | 6.6 Replacing an Element in the Document . . . . . . . . . . . . 13 | |||
| 6.7 Delete an Element . . . . . . . . . . . . . . . . . . . . . 12 | 6.7 Delete an Element . . . . . . . . . . . . . . . . . . . . . 13 | |||
| 6.8 Fetch an Element . . . . . . . . . . . . . . . . . . . . . . 12 | 6.8 Fetch an Element . . . . . . . . . . . . . . . . . . . . . . 13 | |||
| 6.9 Create an Attribute . . . . . . . . . . . . . . . . . . . . 12 | 6.9 Create an Attribute . . . . . . . . . . . . . . . . . . . . 14 | |||
| 6.10 Replacing Attributes . . . . . . . . . . . . . . . . . . . . 13 | 6.10 Replacing Attributes . . . . . . . . . . . . . . . . . . . . 14 | |||
| 6.11 Deleting Attributes . . . . . . . . . . . . . . . . . . . . 13 | 6.11 Deleting Attributes . . . . . . . . . . . . . . . . . . . . 14 | |||
| 6.12 Fetching Attributes . . . . . . . . . . . . . . . . . . . . 13 | 6.12 Fetching Attributes . . . . . . . . . . . . . . . . . . . . 14 | |||
| 6.13 Fetching Metadata . . . . . . . . . . . . . . . . . . . . . 13 | 6.13 Read/Modify/Write Transactions . . . . . . . . . . . . . . . 15 | |||
| 6.14 Read/Modify/Write Transactions . . . . . . . . . . . . . . . 14 | 7. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 16 | |||
| 7. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 15 | ||||
| 7.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . . 16 | 7.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . . 16 | |||
| 7.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . . 17 | 7.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
| 7.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . . 18 | 7.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
| 7.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . . 18 | 7.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . . 18 | |||
| 7.5 Managing Modification Times . . . . . . . . . . . . . . . . 19 | 7.5 Managing Etags . . . . . . . . . . . . . . . . . . . . . . . 19 | |||
| 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 21 | 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
| 9. Security Considerations . . . . . . . . . . . . . . . . . . 23 | 9. Security Considerations . . . . . . . . . . . . . . . . . . 23 | |||
| 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24 | 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24 | |||
| Normative References . . . . . . . . . . . . . . . . . . . . 25 | Normative References . . . . . . . . . . . . . . . . . . . . 25 | |||
| Informative References . . . . . . . . . . . . . . . . . . . 26 | Informative References . . . . . . . . . . . . . . . . . . . 26 | |||
| Author's Address . . . . . . . . . . . . . . . . . . . . . . 27 | Author's Address . . . . . . . . . . . . . . . . . . . . . . 27 | |||
| Intellectual Property and Copyright Statements . . . . . . . 28 | Intellectual Property and Copyright Statements . . . . . . . 28 | |||
| 1. Introduction | 1. Introduction | |||
| The Session Initiation Protocol for Instant Messaging and Presence | In many communications applications, such as Voice over IP, instant | |||
| Leveraging Extensions (SIMPLE) working group has been developing | messaging, and presence, it is necessary for network servers to | |||
| specifications for subscribing to, and receiving notifications of, | access per-user information in the process of servicing a request. | |||
| user presence [10]. An important aspect of user presence is | This per-user information resides within the network, but is managed | |||
| authorization policy. Indeed, the presence specification requires a | by the end user themselves. Its management can be done through a | |||
| Presence Agent (PA) to both authenticate and authorize all | multiplicity of access points, including the web, a wireless handset, | |||
| subscriptions before accepting them. However, it does not define how | or a PC application. | |||
| the server determines the authorization status of a subscriber. Users | ||||
| can set their authorization policy through web pages or voice | ||||
| response systems. However, there is currently no protocol specified | ||||
| for setting this policy. A protocol for this purpose is called an | ||||
| authorization manipulation protocol. | ||||
| Mechanisms have also been defined to support reactive authorization | ||||
| [11][12]. Reactive authorization allows the user to be informed when | ||||
| someone has attempted to subscribe to their presence when the server | ||||
| is unable to determine an authorization policy. The user can then go | ||||
| and set an authorization policy for the subscriber, using the same | ||||
| unspecified mechanism for setting the policy. | ||||
| Another important aspect of presence systems is the buddy list, also | ||||
| known as the presence list. This is a list of users that a watcher | ||||
| wishes to learn presence state for. This list can be stored in the | ||||
| client, or it can be stored in a centralized server. In the latter | ||||
| case, the client would subscribe to the list as a whole [13]. The | ||||
| presence list can be set by using a web page or voice response | ||||
| application. However, there is no protocol mechanism currently | ||||
| specified to manage the presence list. Such a protocol is called a | ||||
| presence list manipulation protocol. | ||||
| The SIMPLE group has defined requirements for an authorization | Examples of per-user information are presence [12] authorization | |||
| manipulation protocol and a presence list manipulation protocol. | policy and presence lists. Presence lists are lists of users whose | |||
| These protocols have similar requirements, and are captured in [14]. | presence is desired by a watcher. Presence information for the list | |||
| of users can be obtained by subscribing to a resource which | ||||
| represents that list [15]. In this case, the Resource List Server | ||||
| (RLS) requires access to this list in order to process a SIP | ||||
| [11]SUBSCRIBE [20] request for it. Requirements for manipulation of | ||||
| presence lists and authorization policies have been specified by the | ||||
| SIMPLE working group [16]. | ||||
| This document proposes a candidate for the authorization and presence | This specification describes a protocol that can be used to | |||
| manipulation protocol, called the Extensible Markup Language (XML) | manipulate this per-user data. It is called the Extensible Markup | |||
| Configuration Access Protocol (XCAP). XCAP is not actually a new | Language (XML) Configuration Access Protocol (XCAP). XCAP is not a | |||
| protocol. XCAP is a set of conventions for using HTTP to read, write | new protocol. Rather, it is a set of conventions for mapping XML | |||
| and modify XML configuration data. XCAP is based heavily on ideas | documents and document components into HTTP URIs, rules for how the | |||
| modification of one resource affects another, data validation | ||||
| constraints, and authorization policies associated with access to | ||||
| those resources. Because of this structure, normal HTTP primitives | ||||
| can be used to manipulate the data. XCAP is based heavily on ideas | ||||
| borrowed from the Application Configuration Access Protocol (ACAP) | borrowed from the Application Configuration Access Protocol (ACAP) | |||
| [15], but it is not an extension of it, nor does it have any | [18], but it is not an extension of it, nor does it have any | |||
| dependencies on it. Like ACAP, XCAP is meant to support the | dependencies on it. Like ACAP, XCAP is meant to support the | |||
| configuration needs for a multiplicity of applications, rather than | configuration needs for a multiplicity of applications, rather than | |||
| just a single one. | just a single one. | |||
| 2. Overview of Operation | 2. Overview of Operation | |||
| XCAP supports the needs of any application that needs access to data | Each application that makes use of XCAP specifies an application | |||
| defined by clients of the application. Each application that makes | usage (Section 4). This application usage defines the XML schema [1] | |||
| use of XCAP specifies an application usage (Section 4). This | for the data used by the application, along with other key pieces of | |||
| application usage defines the XML schema [1] for the data used by the | information. The principal task of XCAP is to allow clients to read, | |||
| application, along with other key pieces of information. The | write, modify, create and delete pieces of that data. These | |||
| principal task of XCAP is to allow clients to read, write, modify, | operations are supported using HTTP 1.1 [2]. An XCAP server acts as a | |||
| create and delete pieces of that data. These operations are supported | repository for collections of XML documents. There will be documents | |||
| using HTTP 1.1 [2]. An XCAP server acts as a repository for | stored for each application. Within each application, there are | |||
| collections of XML documents. There will be documents stored for each | documents stored for each user. Each user can have a multiplicity of | |||
| application. Within each application, there are documents stored for | documents for a particular application. To access some component of | |||
| each user. Each user can have a multiplicity of documents for a | one of those documents, XCAP defines an algorithm for constructing a | |||
| particular application. To access some component of one of those | URI that can be used to reference that component. Components refer to | |||
| documents, XCAP defines an algorithm for constructing a URI that can | any subtree of the document, or any attribute for any element within | |||
| be used to reference that component. Components refer to any subtree | the document. Thus, the HTTP URIs used by XCAP point to pieces of | |||
| of the document, or any attribute for any element within the | ||||
| document. Thus, the HTTP URIs used by XCAP point to pieces of | ||||
| information that are finer grained than the XML document itself. | information that are finer grained than the XML document itself. | |||
| With a standardized naming convention for components of XML | With a standardized naming convention for mapping components of XML | |||
| documents, the basic operations for accessing the data are simple. | documents to HTTP URIs, the basic operations for accessing the data | |||
| Reading one of the components is just a standard HTTP GET operation. | are provided by existing HTTP primitives. Reading one of the | |||
| Writing, creating or modifying one of the components is a standard | components is accomplished with HTTP GET, creating or modifying one | |||
| HTTP POST or PUT operation. Deleting a component is just a standard | of the components is done with an HTTP PUT, and removing one of the | |||
| DELETE operation. For example, to add a friend to a presence list, a | components is done with an HTTP DELETE. To provide atomic read/ | |||
| client would construct an XML document fragment which contains the | modify/write operations, HTTP entity tags are used. | |||
| information on that friend. The client would then construct a URI | ||||
| that refers to the location in the presence list document where this | ||||
| new fragment is to be added. The client then performs a POST | ||||
| operation against the URI, placing the document fragment into the | ||||
| body of the POST request. To provide atomic read/modify/write | ||||
| operations, the HTTP If-Unmodified-Since header field is used. The | ||||
| HTTP POST operation used by the client would contain the date | ||||
| obtained in the Last-Modified header field from the GET used to read | ||||
| the data. | ||||
| 3. Terminology | 3. Terminology | |||
| In this document, the key words "MUST", "MUST NOT", "REQUIRED", | In this document, the key words "MUST", "MUST NOT", "REQUIRED", | |||
| "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", | "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", | |||
| and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and | and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and | |||
| indicate requirement levels for compliant implementations. | indicate requirement levels for compliant implementations. | |||
| 4. Application Usages | 4. Application Usages | |||
| A central concept in XCAP is that of an application usage. An | A central concept in XCAP is that of an application usage. An | |||
| application usage defines the way in which a specific application | application usage defines the way in which a specific application | |||
| makes use of XCAP. This definition is composed of several pieces of | makes use of XCAP. This definition is composed of several pieces of | |||
| information, such as an XML schema and constraints on values of one | information, such as an XML schema and constraints on values of one | |||
| element given values in another. | element given values in another. | |||
| Application usages are documented in specifications which convey this | Application usages are documented in specifications which convey this | |||
| information. In particular, an application usage specification MUST | information. In particular, an application usage specification MUST | |||
| provide the following information: | provide the following information: | |||
| Application Usage ID (AUID): Each application usage is associated | Application Usage ID (AUID): Each application usage is associated | |||
| with a name, called an AUID. This name uniquely identifies the | with a name, called an AUID. This name uniquely identifies the | |||
| application usage, and is different from all other AUIDs. AUIDs | application usage, and is different from all other AUIDs. AUIDs | |||
| exist in one of two namespaces. The first namespace is the IETF | exist in one of two namespaces. The first namespace is the IETF | |||
| namespace. This namespace contains a set of tokens, each of which | namespace. This namespace contains a set of tokens, each of which | |||
| is registered with IANA. These registrations occur with the | is registered with IANA. These registrations occur with the | |||
| publication of standards track RFCs [16] based on the guidelines | publication of standards track RFCs [19] based on the guidelines | |||
| in Section 10. The second namespace is the vendor-proprietary | in Section 10. The second namespace is the vendor-proprietary | |||
| namespace. Each AUID in that namespace is prefixed with the token | namespace. Each AUID in that namespace is prefixed with the | |||
| "vnd", followed by a period ("."), followed by a valid DNS name, | reverse domain name name of the organization creating the AUID, | |||
| followed by another period, followed by any vendor defined token. | followed by a period, followed by any vendor defined token. As an | |||
| A vendor creating such an AUID MUST only create one using domain | example, the example.com domain can create an AUID with the value | |||
| names for which it is an administrator. As an example, the | "com.example.foo" but cannot create one with the value | |||
| example.com domain can create an AUID with the value | "org.example.foo". AUIDs within the vendor namespace do not need | |||
| "vnd.example.com.foo" but cannot create one with the value | to be registered with IANA. The vendor namespace is also meant to | |||
| "vnd.example.org.bar". AUIDs within the vendor namespace do not | be used in lab environments where no central registry is needed. | |||
| need to be registered with IANA. The vendor namespace is also | The syntax for AUIDs, expressed in ABNF [7] (and using some of the | |||
| meant to be used in lab environments where no central registry is | BNF defined in RFC 2396 [8]) is: | |||
| needed. | ||||
| MIME Type: Each application usage MUST register a MIME type for | AUID = global-auid / vendor-auid | |||
| its XML documents. This is done based on the procedures of RFC | global-auid = auid | |||
| 3023 [4]. | auid = alphanum / mark | |||
| vendor-auid = rev-hostname "." auid | ||||
| rev-hostname = toplabel *( "." domainlabel ) | ||||
| domainlabel = alphanum | ||||
| / alphanum *( alphanum / "-" ) alphanum | ||||
| toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum | ||||
| XML Schema: Each application will have a unique schema which | MIME Type: Each application usage MUST register a MIME type for its | |||
| defines the data needed by the application. In XCAP, this schema | XML documents. This is done based on the procedures of RFC 3023 | |||
| is represented using XML schema. As an example, presence list data | [4]. | |||
| is composed of a list of URIs, each of which represends a member | ||||
| of presence list. [17] defines the XML schema for this data. | ||||
| Additional Constraints: XML schemas can represent a variety of | XML Schema: Each application will have a unique schema which defines | |||
| the data needed by the application. In XCAP, this schema is | ||||
| represented using XML schema [1]. | ||||
| Additional Constraints: XML schemas can represent a variety of | ||||
| constraints about data, such as ranges and types. However, schemas | constraints about data, such as ranges and types. However, schemas | |||
| cannot cover all types of data constraints, including constraints | cannot cover all types of data constraints, including constraints | |||
| introduced by data interdependencies. For example, one XML element | introduced by data interdependencies. For example, one XML element | |||
| may contain an integer which defines the maximum number of | may contain an integer which defines the maximum number of | |||
| instances of another element. The application usage defines these | instances of another element. The application usage defines these | |||
| additional constraints. | additional constraints. | |||
| Data Semantics: The application usage needs to define detailed | Data Semantics: The application usage needs to define detailed | |||
| semantics for each piece of data in the schema. | semantics for each piece of data in the schema. | |||
| Naming Conventions: The data defined by the XML schema will be | Naming Conventions: The data defined by the XML schema will be used | |||
| used by any number of entities participating in the application. | by any number of entities participating in the application. In the | |||
| In the case of presence list, the data is used by the Resource | case of presence list, the data is used by the Resource List | |||
| List Server (RLS), which reads the data, and by the clients, which | Server (RLS), which reads the data, and by the clients, which | |||
| write it. During the execution of the application (i.e., the | write it. During the execution of the application (i.e., the | |||
| processing of the list subscription), specific documents will need | processing of the list subscription), specific documents will need | |||
| to be read or written. In order for the application to function | to be read or written. In order for the application to function | |||
| properly, there needs to be agreement on exactly which documents | properly, there needs to be agreement on exactly which documents | |||
| are read or written by the application. This is an issue of naming | are read or written by the application. This is an issue of naming | |||
| conventions; agreeing on how an application constructs the URI | conventions; agreeing on how an application constructs the URI | |||
| representing the document that is to be read or written. The | representing the document that is to be read or written. The | |||
| application usage spells out this information. | application usage spells out this information. | |||
| Computed Data: Frequently, some of the data defined in the schema | Resource Interdependencies: In many cases, when a user modifies an | |||
| is not independent; that is, its value depends on the values of | XCAP resource, many other resources need to change as well. Such | |||
| other elements in the document. As a result, when a client uses | interdependencies are application usage dependent. As an example, | |||
| XCAP to modify the independent pieces of the document, the server | when a user performs a PUT operation to create a new presence | |||
| needs to compute the dependent ones in order to fully populate the | list, the server may need to fill in the URI associated with that | |||
| document. The application usage needs to define which data | list. These interdependencies need to be specified by the | |||
| components are dependent, and how they are computed. As an | application usage. Note that, if a server needs to modify data | |||
| example, when the URI for a presence list is not specified by a | within a document just PUT by the client, this modification is | |||
| client, a URI is chosen by the server and filled in. This needs to | effectively accomplished as a separate transaction. Concretely, | |||
| be specified by the application usage. | this means that, after the server modifies the data, the entity | |||
| tags are updated as if the client had made the change itself. | ||||
| Authorization Policies: By default, an XCAP server will only allow | Authorization Policies: By default, an XCAP server will only allow a | |||
| a user to access (read, write, delete or modify) their own | user to access (read, write, delete or modify) their own | |||
| documents. The application usage can specify differing default | documents. The application usage can specify differing default | |||
| authorization policies. Of course, the default can always be | authorization policies. An application usage can also specify | |||
| overriden by operator or user-specified policies. | whether another application usage is used to define the | |||
| authorization policies. An application usage for setting | ||||
| authorization policies can also be defined subsequent to the | ||||
| definition of the the main application usage. In such a case, the | ||||
| main application usage needs only to specify that such a usage | ||||
| will be defined in the future. | ||||
| Application usages are similar to dataset classes in ACAP. | Application usages are similar to dataset classes in ACAP. | |||
| 5. URI Construction | 5. URI Construction | |||
| In order to manipulate a piece of configuration data, the data must | In order to manipulate a piece of configuration data, the data must | |||
| be represented by an HTTP URI. XCAP defines a specific naming | be represented by an HTTP URI. XCAP defines a specific naming | |||
| convention for constructing these URIs. This convention is very | convention for constructing these URIs. In particular, the host part | |||
| similar to the naming conventions used for dataset classes in ACAP, | identifies the XCAP server. The abs_path component of the HTTP URI | |||
| and makes use the XPath [5] specification for identifying nodes of an | identifies the specific XML document to be modified. XCAP servers | |||
| XML document. | organize XML documents in a specific hierarchical fashion, as | |||
| described in Section 5.1. The URI MAY contain a query. This query is | ||||
| The HTTP URI consists of two parts: | called a node selector. When present, it contains an XML component | |||
| identifier formatted according to Section 5.2. The node selector | ||||
| XCAP-URI = Document-URI ["?" Node-Selector] | identifies the specific component of the XML document. The HTTP URI | |||
| Document-URI = http_URL ;from RFC2616 | without the query is called the document URI. , and makes use the | |||
| Node-Selector = *uric ;Escape coded LocationPath from XPath | specification for identifying nodes of an XML document. | |||
| The first part, the Document-URI, selects a specific XML document. It | ||||
| is a valid HTTP URL, subject to the constraints described here. The | ||||
| constraints for constructing this URI are discussed below in Section | ||||
| 5.1. Once a document is selected, the remainder of the URI (the | ||||
| Node-Selector) identifies which components of the document are being | ||||
| addressed. The Node-Selector is an XPath [5] LocationPath expression, | ||||
| subject to constraints described below. | ||||
| 5.1 Identifying the XML Document | 5.1 Identifying the XML Document | |||
| XCAP mandates that a server organizes documents according to a | XCAP mandates that a server organizes documents according to a | |||
| defined hierarchy. The root of this hierarchy is an HTTP URI called | defined hierarchy. The root of this hierarchy is an HTTP URI called | |||
| the XCAP services root URI. This URI identifies the root of the tree | the XCAP services root URI. This URI identifies the root of the tree | |||
| within the domain where all XCAP documents are stored. It can be any | within the domain where all XCAP documents are stored. It can be any | |||
| valid HTTP URL, but MUST NOT contain a query string. As an example, | valid HTTP URL, but MUST NOT contain a query string. As an example, | |||
| http://xcap.example.com/services might be used as the XCAP services | http://xcap.example.com/services might be used as the XCAP services | |||
| root URI within the example.com domain. Typically, the XCAP services | root URI within the example.com domain. Typically, the XCAP services | |||
| skipping to change at page 8, line 50 ¶ | skipping to change at page 8, line 42 ¶ | |||
| Beneath the XCAP services root URI is a tree structure for organizing | Beneath the XCAP services root URI is a tree structure for organizing | |||
| documents. The first level of this tree consists of the XCAP AUID. | documents. The first level of this tree consists of the XCAP AUID. | |||
| So, continuing the example above, all of the documents used by the | So, continuing the example above, all of the documents used by the | |||
| presence list application would be under http://xcap.example.com/ | presence list application would be under http://xcap.example.com/ | |||
| services/presence-lists. | services/presence-lists. | |||
| It is assumed that each application will have data that is set by | It is assumed that each application will have data that is set by | |||
| users, and/or it will have global data that applies to all users. As | users, and/or it will have global data that applies to all users. As | |||
| a result, within the directory structure for each application usage, | a result, within the directory structure for each application usage, | |||
| there are two sub-trees. One, called "users", holds the documents | there are two sub-trees. One, called "users", holds the documents | |||
| that are applicable to only specific users, and the other, called | that are applicable to specific users, and the other, called | |||
| "global", holds documents applicable to all users. | "global", holds documents applicable to all users. | |||
| Within the "users" tree are zero or more sub-trees, each of which | Within the "users" tree are zero or more sub-trees, each of which | |||
| identifies a documents that apply to a specific user. XCAP does not | identifies a documents that apply to a specific user. XCAP does not | |||
| itself define what it means for documents to "apply" to a user, | itself define what it means for documents to "apply" to a user, | |||
| beyond specification of a baseline authorization policy. | beyond specification of a baseline authorization policy. | |||
| Specifically, the default authorization policy is that only a user | Specifically, the default authorization policy is that only a user | |||
| who authenticates themself as user X can read, write, or otherwise | who authenticates themself as user X can read, write, or otherwise | |||
| access in any way the documents within sub-tree X. Each application | access in any way the documents within sub-tree X. Each application | |||
| usage can specify additional authorization policies which depend on | usage can specify additional authorization policies which depend on | |||
| data used by the application itself. | data used by the application itself. | |||
| The remainder of the URI (the path following "global" or the specific | The remainder of the URI (the path following "global" or the specific | |||
| user) is not constrained by this specification. The application usage | user) is not constrained by this specification. The application usage | |||
| MAY introduce constraints, or may allow any structure to be used. | MAY introduce constraints, or may allow any structure to be used. | |||
| 5.2 Identifying the XML Nodes | 5.2 Identifying the XML Nodes | |||
| The second component of the XCAP URI specifies specific nodes of the | The second component of the XCAP URI specifies specific nodes of the | |||
| XML document which are to be accessed. Nodes, in this context, refers | XML document which are to be accessed. A node refers to either an XML | |||
| to the definition provided in the XPath specification, and therefore | element or an attribute of an element. The node selector is an | |||
| includes XML elements, attributes, text, namespaces, processing | expression which identifies an element or attribute. Its grammar is: | |||
| instructions, comments, and roots. These nodes are identified by a | ||||
| LocationPath expression, as defined in XPath. Either the abbreviated | ||||
| or unabbreviated form MAY be used. | ||||
| Contraints are imposed on the XPath expression based on the operation | node-selector = element-selector ["/" attribute-selector] | |||
| being performed. These do not constrain the functions or axes that | element-selector = step *( "/" step) | |||
| can be used in the XPath expression, but rather constrain the | step = by-name / by-pos / by-attr | |||
| resulting node set. See Section 6 for details. | by-name = QName ; from XML Namespaces | |||
| by-pos = QName "[" position "]" | ||||
| position = 1*DIGIT | ||||
| by-attr = QName "[" "@" att-name "=" <"> | ||||
| att-value <"> "]" | ||||
| att-name = QName | ||||
| att-value = AttValue ; from XML specification | ||||
| by-pos = QName "[" position "]" | ||||
| position = *DIGIT | ||||
| attribute-selector = "@" att-name | ||||
| The node selector is based on the concepts in XPath [5]. Indeed, the | ||||
| node selector expression happens to be a valid XPath expression. | ||||
| However, XPath provides a set of functionality far richer than is | ||||
| needed here, and its breadth would introduce complexity into XCAP. | ||||
| To determne the XML element or attribute selected by the node | ||||
| selector, processing begins at the root of the XML document. The | ||||
| first step in the element selector is then taken. Each step chooses a | ||||
| specific XML element within the current document context. The | ||||
| document context is the point within the XML document from which a | ||||
| specific step is evaluated. The document context begins at the root | ||||
| of the document. When a step determines an element within that | ||||
| context, that element becomes the new context for evaluation of the | ||||
| next step. Each step can select an element by its name, by a | ||||
| combination of name and attribute value, or by name and position. If | ||||
| the step is attempting selection by name, the server looks for all | ||||
| elements within the current context with that name. Name matching is | ||||
| performed as described below. If there is more than one element with | ||||
| the specified name, the result is considered a no-match. | ||||
| If the step is attempting selection by name and attribute, the server | ||||
| looks for all elements within the current document context with that | ||||
| name. Of those that match, it looks for ones that have the given | ||||
| attribute name, where that attribute has the given value. If there is | ||||
| no match, or if more than one element matches, the result is | ||||
| considered a no-match. | ||||
| If the step is attempting selection by name and position, the server | ||||
| looks for all elements within the current document context with that | ||||
| name. These are then sorted in document order, as defined by Xpath. | ||||
| The position-th element is then selected. If there are fewer than | ||||
| position number of elements with that name, the result is considered | ||||
| a no-match. | ||||
| Once the last step is executed, if there is no attribute selector, | ||||
| the result of the node selection is the last selected element. If | ||||
| there is an attribute selector, the server checks to see if there is | ||||
| an attribute with that name within the currently selectoed element. | ||||
| If there is not, the result is considered a no-match. Otherwise, that | ||||
| attribute is selected. | ||||
| Matching of element names and attributes is performed by expanding | ||||
| them into the expanded name form, as described in XML Namespaces, and | ||||
| then performing the comparison of the results. When evaluating the | ||||
| QNames in the node selector, the default namespace and namespace | ||||
| definitions from the document URI apply. | ||||
| As an example, consider the following XML document: | ||||
| <?xml version="1.0"?> | ||||
| <watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo" | ||||
| version="0" state="full"> | ||||
| <watcher-list resource="sip:professor@example.net" package="presence"> | ||||
| <watcher status="active" | ||||
| id="8ajksjda7s" | ||||
| duration-subscribed="509" | ||||
| event="approved" >sip:userA@example.net</watcher> | ||||
| <watcher status="pending" | ||||
| id="hh8juja87s997-ass7" | ||||
| display-name="Mr. Subscriber" | ||||
| event="subscribe">sip:userB@example.org</watcher> | ||||
| </watcher-list> | ||||
| </watcherinfo> | ||||
| The node selector "watcherinfo/watcher-list/ | ||||
| watcher[@id="8ajksjda7s"]" would select the following XML element: | ||||
| <watcher status="active" | ||||
| id="8ajksjda7s" | ||||
| duration-subscribed="509" | ||||
| event="approved" >sip:userA@example.net</watcher> | ||||
| 6. Client Operations | 6. Client Operations | |||
| An XCAP client is an HTTP 1.1 compliant client. An XCAP client | An XCAP client is an HTTP 1.1 compliant client. Specific data | |||
| performs a set of primitive operations by invoking specific methods | manipulation tasks are accomplished by invoking the right set of HTTP | |||
| against the server, using specific URIs, where the requests contain | methods with the right set of headers on the server. This section | |||
| bodies and headers subject to specific constraints. The set of | describes those in detail | |||
| primitive operations, the methods used to accomplish them, and the | ||||
| header and body constraints are described here. | ||||
| 6.1 Creating a New Document | 6.1 Creating a New Document | |||
| To create a new document, the client constructs a URI that references | To create a new document, the client constructs a URI that references | |||
| the location where the document is to be placed. This URI MUST NOT | the location where the document is to be placed. This URI MUST NOT | |||
| contain a NodeSelector component, and MUST meet the constraints | contain a NodeSelector component. The client then invokes a PUT | |||
| described in Section 5.1. The client then invokes a PUT method on | method on that URI. | |||
| that URI. | ||||
| The content in the request MUST be an XML document compliant to the | The content in the request MUST be an XML document compliant to the | |||
| schema associated with the application usage defined by the URI. For | schema associated with the application usage defined by the URI. For | |||
| example, if the client performs a PUT operation to http:// | example, if the client performs a PUT operation to http:// | |||
| xcap.example.com/services/presence-lists/users/joe/mybuddies, | xcap.example.com/services/presence-lists/users/joe/mybuddies, | |||
| presence-lists is the application unique ID, and the schema defined | presence-lists is the application unique ID, and the schema defined | |||
| by it would dictate the body of the request. | by it would dictate the body of the request. | |||
| 6.2 Replace an Existing Document | 6.2 Replace an Existing Document | |||
| skipping to change at page 10, line 48 ¶ | skipping to change at page 12, line 45 ¶ | |||
| To delete a document, the client constructs a URI that references the | To delete a document, the client constructs a URI that references the | |||
| document to be deleted. By definition this URI will not contain a | document to be deleted. By definition this URI will not contain a | |||
| NodeSelector component. The client then invokes a DELETE operation on | NodeSelector component. The client then invokes a DELETE operation on | |||
| the URI to delete the document. | the URI to delete the document. | |||
| 6.4 Fetching a Document | 6.4 Fetching a Document | |||
| As one would expect, fetching a document is trivially accomplished by | As one would expect, fetching a document is trivially accomplished by | |||
| performing an HTTP GET request with the Request URI set to the | performing an HTTP GET request with the Request URI set to the | |||
| document to be fetched. It is useful for clients to perform | document to be fetched. It is useful for clients to perform | |||
| conditional GETs using the If-Modified-Since header field, in order | conditional GETs using the If-Match header field, in order to check | |||
| to check if a locally cached copy of the document is still valid. | if a locally cached copy of the document is still valid. An HTTP | |||
| server MUST return Etags for entities that represent resources | ||||
| managed by XCAP. | ||||
| 6.5 Creating a New Element | 6.5 Creating a New Element | |||
| To create a new XML element within an existing document, the client | ||||
| constructs a URI whose Document-URI points to the document to be | ||||
| modified. The Node-Selector MUST be present, containing an expression | ||||
| identifying the point in the document where the new element is to be | ||||
| added. The node-set selected by the expression MUST contain only a | ||||
| single XML element. | ||||
| The client then invokes the HTTP POST method. The content in the | ||||
| request MUST be an XML document. That XML document MUST be conformant | ||||
| to the schema associated with the application usage defined by the | ||||
| URI. The server will insert the document such that the first element | ||||
| of the document becomes the next sibling immediately following the | ||||
| element specified by the Request-URI. The client SHOULD be certain, | ||||
| before making the request, that the resulting modified document will | ||||
| also be conformant to the schema. | ||||
| 6.6 Replacing an Element in the Document | ||||
| Replacing an element of the document constitutes storage of a | To create a new XML element within an existing document, the client | |||
| supplied entity under the specified URI, and is therefore | constructs a URI whose document URI points to the document to be | |||
| accomplished with the PUT method (as opposed to POST, which will | modified. The node selector MUST be present in the URI. The node | |||
| insert). The client constructs a URI whose Document-URI points to the | selector is constructed such that it meets two constraints. First, if | |||
| document to be modified. The Node-Selector MUST be present, | evaluated against the current document, the result is a no-match. | |||
| containing an expression identifying the element whose value is to be | Secondly, if the element was added to the document as desired by the | |||
| replaced. The node-set selected by the expression MUST contain only a | client, the node selector would select that element. | |||
| single XML element. | ||||
| The client then invokes the PUT method. The entity of the request | The client then invokes the HTTP PUT method [[OPEN ISSUE: what is the | |||
| MUST be of type text/plain. The server will take the value of the | content type?]]. The content in the request MUST be an XML element. | |||
| element specified by the request URI, and replace it with the content | The server will insert the element into the document such that the | |||
| of the PUT request. Here, value refers to the binary contents of an | node selector, if evaluated by the server, would return the content | |||
| XML document, starting with the beginning tag of the element, and | present in the request. The client SHOULD be certain, before making | |||
| ending with the end tag. This differs from the "string value" defined | the request, that the resulting modified document will also be | |||
| in XPath, which refers only to the values of the text element | ||||
| descendants of an element. The client SHOULD be certain, before | ||||
| making the request, that the resulting modified document will be | ||||
| conformant to the schema. | conformant to the schema. | |||
| The body of the request here is of type text/plain because the value | It is important to note that the element might potentially be | |||
| of an element need not be a valid XML document; frequently, it will | inserted in the document in several different ways, and still meet | |||
| be text or CDATA. Of course, the value of an XML element may be other | the constraints defined above. This is analagous to the case when a | |||
| XML elements, in which case the body of the request will be an XML | new file is PUT into a directory on a server; the location of that | |||
| document fragment, and by itself not compliant to any schema. | file within the directory is not specified, and is up the local file | |||
| system to decide. The only guarantee is that GET(PUT(x)) returns | ||||
| document x. | ||||
| Note that this operation only modifies the value of an element. It | 6.6 Replacing an Element in the Document | |||
| cannot modify the attributes of the element. To do that, the replace | ||||
| attribute operation is performed. | Replacing an element of the document is also accomplished with PUT. | |||
| The only difference with the behavior above for insertion is that the | ||||
| node selector, when evaluated against the current document, is a | ||||
| match for an element in the current document. That element is | ||||
| removed, and replaced with the content of the PUT request. | ||||
| 6.7 Delete an Element | 6.7 Delete an Element | |||
| To delete elements from a document, the client constructs a URI whose | To delete elements from a document, the client constructs a URI whose | |||
| Document-URI points to the document containing the elements to be | document URI points to the document containing the elements to be | |||
| deleted. The Node-Selector MUST be present, containing an expression | deleted. The node selector MUST be present, and identify the specific | |||
| identifying the elements to be deleted. Unlike most of the other | element to be deleted. | |||
| operations, the node-set selected by the expression MAY contain | ||||
| multiple elements. | ||||
| The client then invokes the HTTP DELETE method. All of the elements | The client then invokes the HTTP DELETE method. The server will | |||
| specified by the node set will be deleted by the server. The body of | remove the element from the document. The client SHOULD be certain, | |||
| the request SHOULD be empty. The client SHOULD be certain, before | before making the request, that the resulting modified document will | |||
| making the request, that the resulting modified document will also be | also be conformant to the schema. | |||
| conformant to the schema. | ||||
| 6.8 Fetch an Element | 6.8 Fetch an Element | |||
| To fetch an element of a document, the client constructs a URI whose | To fetch an element of a document, the client constructs a URI whose | |||
| Document-URI points to the document containing the element to be | document URI points to the document containing the element to be | |||
| fetched. The Node-Selector MUST be present, containing an expression | fetched. The node selector MUST be present, and must identify the | |||
| identifying the element whose value is to be fetched. The node-set | element to be fetched. | |||
| selected by the expression MUST contain only a single XML element. | ||||
| The client then invokes the GET method. The response will contain an | ||||
| XML document with the specified element as the one and only child of | ||||
| the document root. | ||||
| OPEN ISSUE: This only allows you to get one element at a time. We | The client then invokes the GET method. The response will contain | |||
| could allow the XPath expression to specify multiple elements, and | that XML element. Specifically, it contains the content of the XML | |||
| then the response contains a document with each of those elements | document, starting with the opening bracket for the begin tag for | |||
| as a child of the document root. However, that document might not | that element, and ending with the closing bracket for the end tag for | |||
| be compliant to the schema, and worse, the document doesnt | that element. | |||
| actually reflect any specific sub-tree of the actual document. | ||||
| 6.9 Create an Attribute | 6.9 Create an Attribute | |||
| To create an attribute in an existing element of a document, the | To create an attribute in an existing element of a document, the | |||
| client constructs a URI whose Document-URI points to the document to | client constructs a URI whose document URI points to the document to | |||
| be modified. The Node-Selector MUST be present, containing an | be modified. The node selector MUST be present. The node selector is | |||
| expression identifying an attribute that is to created. Specifically, | constructed such that it meets two constraints. First, if evaluated | |||
| the last location step of the expression MUST specify an attribute | against the current document, the result is a no-match. Secondly, if | |||
| axis, and the context MUST specify a single element that exists | the attribute was added to the document as desired by the client, the | |||
| within the document. | node selector would select that attribute. | |||
| The client then invokes the HTTP POST method. The content defined by | ||||
| the request MUST be of type text/plain. A new attribute is added to | ||||
| the element defined by the context, with the name specified by the | ||||
| node test in the last location step, with a value specified by the | ||||
| body of the request. If an attribute of this name already exists, it | ||||
| is replaced. The client SHOULD be certain, before making the request, | ||||
| that the resulting modified document will also be conformant to the | ||||
| schema. | ||||
| 6.10 Replacing Attributes | ||||
| To replace an attribute in an existing element of a document, the | ||||
| client constructs a URI whose Document-URI points to the document to | ||||
| be modified. The Node-Selector MUST be present, containing an | ||||
| expression identifying an attribute that is to be replaced. | ||||
| The client then invokes the HTTP PUT method. The content defined by | The client then invokes the HTTP PUT method. The content defined by | |||
| the request MUST be of type text/plain. The value of the attribute | the request MUST be compliant to the grammar for Attribute as defined | |||
| defined by the Node-Selector is replaced by the body of the request. | in XML 1.0 [[OPEN ISSUE: content type?]]. The server will add that | |||
| attribute such that, if the node selector is evaluated on the | ||||
| resulting document, it returns the attribute present in the request. | ||||
| The client SHOULD be certain, before making the request, that the | The client SHOULD be certain, before making the request, that the | |||
| resulting modified document will also be conformant to the schema. | resulting modified document will also be conformant to the schema. | |||
| 6.10 Replacing Attributes | ||||
| Replacing an attribute of the document is also accomplished with PUT. | ||||
| The only difference with the behavior above for insertion is that the | ||||
| node selector, when evaluated against the current document, is a | ||||
| match for an attribute in the current document. That attribute is | ||||
| removed, and replaced with the content of the PUT request. | ||||
| 6.11 Deleting Attributes | 6.11 Deleting Attributes | |||
| To delete attributes from the document, the client constructs a URI | To delete attributes from the document, the client constructs a URI | |||
| whose Document-URI points to the document containing the attributes | whose document URI points to the document containing the attributes | |||
| to be deleted. The Node-Selector MUST be present, containing an | to be deleted. The node selector MUST be present, and evaluate to an | |||
| expression identifying the attributes to be deleted. Unlike most of | attribute in the document to be deleted. | |||
| the other operations, the node-set selected by the expression MAY | ||||
| contain multiple attributes. | ||||
| The client then invokes the HTTP DELETE method. All of the attributes | The client then invokes the HTTP DELETE method. The server will | |||
| specified by the node set will be deleted by the server. The body of | remove the attribute from the document. The client SHOULD be certain, | |||
| the request SHOULD be empty. The client SHOULD be certain, before | before making the request, that the resulting modified document will | |||
| making the request, that the resulting modified document will also be | also be conformant to the schema. | |||
| conformant to the schema. | ||||
| 6.12 Fetching Attributes | 6.12 Fetching Attributes | |||
| To fetch an attribute of a document, the client constructs a URI | To fetch an attribute of a document, the client constructs a URI | |||
| whose Document-URI points to the document containing the attribute to | whose Document-URI points to the document containing the attribute to | |||
| be fetched. The Node-Selector MUST be present, containing an | be fetched. The node selector MUST be present, containing an | |||
| expression identifying the attribute whose value is to be fetched. | expression identifying the attribute whose value is to be fetched. | |||
| The node-set selected by the expression MUST contain only a single | ||||
| XML attribute. | ||||
| The client then invokes the GET method. The response will contain an | ||||
| text/plain document with the value of the specified attribute. | ||||
| 6.13 Fetching Metadata | The client then invokes the GET method. The response will contain | |||
| Elements and attributes in an XML document have various meta-data | document with the specified attribute, formatted according to the | |||
| associated with them. For example, and XML element has a certain | grammar of Attribute as defined in the XML 1.0 specifications. | |||
| number of child elements. That number is a piece of meta-data that | ||||
| describes the element. Currently, there is no way to fetch meta-data | ||||
| for XML elements or attributes. | ||||
| OPEN ISSUE: Is this restriction OK? XPath does specify functions | ||||
| for computing meta-data about node sets. We can't use them since | ||||
| XCAP mandates that the request URI be a location set, which does | ||||
| not include these other functions. We could relax the constraint | ||||
| if this is deemed important. | ||||
| 6.14 Read/Modify/Write Transactions | 6.13 Read/Modify/Write Transactions | |||
| It is anticipated that a common operation will be to read the current | It is anticipated that a common operation will be to read the current | |||
| version of a document or element, modify it on the client, and then | version of a document or element, modify it on the client, and then | |||
| write the change back to the server. In order for the results to be | write the change back to the server. In order for the results to be | |||
| consistent with the client's expectations, the operation must be | consistent with the client's expectations, the operation must be | |||
| atomic. | atomic. | |||
| To accomplish this, the client stores the value of the Last-Modified | To accomplish this, the client makes use of entity tags returned by | |||
| header field from the response to its GET operation used to read the | the server in a GET operation used to read the element, attribute, or | |||
| element, attribute, or document that is to be modified. To guarantee | document that is to be modified. To guarantee atomicity, the PUT | |||
| atomicity, the PUT or POST operation used to write the changes back | operation used to write the changes back to the server MUST contain | |||
| to the server MUST contain an If-Unmodified-Since header field, whose | an If-Match header field, whose value is equal to the entity tag from | |||
| value is equal to the value from the prior GET response. If the | the prior GET response. If the request fails with a 412 response, the | |||
| request fails with a 412 response, the client knows that another | client knows that another update of the data has occurred before it | |||
| update of the data has occurred before it was able to write the | was able to write the results back. The client can then fetch the | |||
| results back. The client can then fetch the most recent version, and | most recent version, and attempt its modification again. | |||
| attempt its modification again. | ||||
| 7. Server Behavior | Because there are no batching operations defined in HTTP, that would | |||
| allow for a number of separate create, modify or delete operations to | ||||
| be performed atomically, designers of application usages should take | ||||
| care to structure their schemas so that operations that need to be | ||||
| performed atomically can be done in a single operation. | ||||
| TODO: Specify an XML body type for the responses that contains | 7. Server Behavior | |||
| error conditions or success results. | ||||
| An XCAP server is an HTTP 1.1 compliant origin server. The behaviors | An XCAP server is an HTTP 1.1 compliant origin server. The behaviors | |||
| mandated by this specification relate to the way in which the HTTP | mandated by this specification relate to the way in which the HTTP | |||
| URI is interpreted and the content is constructed. | URI is interpreted and the content is constructed. | |||
| An XCAP server MUST be explicitly aware of the application usage | An XCAP server MUST be explicitly aware of the application usage | |||
| against which requests are being made. That is, the server must be | against which requests are being made. That is, the server must be | |||
| explicitly configured to handle URIs for each specific application | explicitly configured to handle URIs for each specific application | |||
| usage, and must be aware of the constraints imposed by that | usage, and must be aware of the constraints imposed by that | |||
| application usage. | application usage. Furthermore, an XCAP server MUST be aware of all | |||
| of the XML namespaces present in any documents it manages. This is to | ||||
| OPEN ISSUE: It may be possible to remove this restriction by | ensure that any data constraints or data interdependencies imposed by | |||
| allowing an application usage to define operation in a server that | a future application usage are properly supported by the server. It | |||
| doesnt understand the usage. That may require some capabilities | is also required to ensure that authorization policies are properly | |||
| discovery to be introduced, this constraint didnt seem that | implemented. | |||
| problematic. | ||||
| When the server receives a request, the treatment depends on the URI. | When the server receives a request, the treatment depends on the URI. | |||
| If the URI refers to an application usage not understood by the | If the URI refers to an application usage not understood by the | |||
| server, the server MUST reject the request with a 404 (Not Found) | server, the server MUST reject the request with a 404 (Not Found) | |||
| response. If the URI refers to a user that is not recognized by the | response. If the URI refers to a user that is not recognized by the | |||
| server, it MUST reject the request with a 404 (Not Found). | server, it MUST reject the request with a 404 (Not Found). | |||
| Next, the server authenticates the request. All XCAP servers MUST | Next, the server authenticates the request. All XCAP servers MUST | |||
| support HTTP Digest [6]. Furthermore, servers MUST support HTTP over | support HTTP Digest [6]. Furthermore, servers MUST support HTTP over | |||
| TLS, RFC 2818 [7]. It is RECOMMENDED that administrators use an HTTPS | TLS, RFC 2818 [9]. It is RECOMMENDED that administrators use an HTTPS | |||
| URI as the XCAP root services URI, so that the digest client | URI as the XCAP root services URI, so that the digest client | |||
| authentication occurs over TLS. | authentication occurs over TLS. | |||
| Next, the server determines if the client has authorization to | Next, the server determines if the client has authorization to | |||
| perform the requested operation on the resource. The default | perform the requested operation on the resource. The default | |||
| authorization policy is that only client X can access (create, read, | authorization policy is that only client X can access (create, read, | |||
| write, modify or delete) resources under the "users/X" directory. An | write, modify or delete) resources under the "users/X" directory. An | |||
| application usage can specify an alternate default authorization | application usage can specify an alternate default authorization | |||
| policy specific to that usage. Of course, an administrator or | policy specific to that usage. The server may also know of an | |||
| privileged user can override the default authorization policy, | application usage that itself defines authorization policies for | |||
| although this specification provides no means for doing that. | another application usage. Of course, an administrator or privileged | |||
| Generally, if users need to be able to control authorization for | user can override the default authorization policy, although this | |||
| access to XCAP data, an XCAP application usage should be specified | specification provides no means for doing that. | |||
| which allows the user to set the policies as needed. | ||||
| OPEN ISSUE: This is different from ACAP, where authorization | ||||
| policies are built into the protocol. I think the default | ||||
| generally will suffice, so I would rather not burden the baseline | ||||
| protocol with it. | ||||
| Once authorized, the specific behavior depends on the method and what | Once authorized, the specific behavior depends on the method and what | |||
| the URI refers to. | the URI refers to. | |||
| 7.1 POST Handling | 7.1 POST Handling | |||
| If the URI contains only a Document-URI, the server examines the | Resources managed by XCAP do not represent processing scripts. As a | |||
| entity body of the request. If there is no entity in the body, the | result, POST operations to XCAP URIs is not defined. A server | |||
| server MUST reject the request with a 409 response. If there is an | receiving such a request SHOULD return a 405. | |||
| entity, but it is not well-formed, the server MUST reject the request | ||||
| with a 409 response. If it is well-formed, but not compliant to the | ||||
| schema associated with the application usage, the server MUST reject | ||||
| the request with a 409 response. If it is compliant to the schema, | ||||
| the server MUST store the document at the requested URI. If there is | ||||
| not already a document stored at that URI, a 201 (Created) response | ||||
| code MUST be sent, and it MUST include a Location header field | ||||
| containing the value of the URI for the document (which will be the | ||||
| same as the one in the Request-URI). Otherwise, a 200 OK response is | ||||
| returned, and the document in the body replaces the existing one at | ||||
| that URI. For either a 200 or 201 response, the new document is | ||||
| returned in the body of the response, with a Content-Type equal to | ||||
| the MIME type defined by the application usage. | ||||
| If the Request URI contains a Node-Selector, the server MUST verify | ||||
| that the document defined by the Document-URI exists. If no such | ||||
| document exists on the server, the server MUST reject the request | ||||
| with a 409 response code. If the document does exist, the server | ||||
| evaluates the Node-Selector as an XPath RelativeLocationPath, | ||||
| relative to the root of the document. If the Node-Selector does not | ||||
| comply to the grammar for RelativeLocationPath, the server MUST | ||||
| reject the request with a 400 response code. If the Node-Selector | ||||
| does comply, and it evaluates to anything other than the empty set, a | ||||
| single attribute node or single element node, the server MUST reject | ||||
| the request with a 409 response code. | ||||
| If the Node-Selector evaluates to the empty set, and the last | ||||
| location step is on the attribute axis, and the expression without | ||||
| the last location step evaluates to a single element node, the server | ||||
| adds an attribute to that element. Its name is the name given in the | ||||
| node test of the last location step, and its value is taken from the | ||||
| body of the request. The server then generates a 200 OK response, | ||||
| whose body contains the value of the attribute, with a Content-Type | ||||
| of text/plain. | ||||
| If the Node-Selector evaluates to a single element node, the server | ||||
| takes the content of the request, and inserts it into the document | ||||
| specified by the URI such that the selected element is the immediate | ||||
| sibling of the nodes defined by the content of the request. The | ||||
| server then generates a 200 OK response, whose body contains the | ||||
| parent element of the new elements just inserted. The parent element | ||||
| is represented by extracting the contents of the XML document, | ||||
| starting with, and including, the begin tag of the element, up to, | ||||
| and including, the end tag for the element. The Content-Type of the | ||||
| response is set to application/xml. | ||||
| OPEN ISSUE: We can't use the MIME type for the application usage, | ||||
| since the schema may not allow for the document to start with any | ||||
| element defined by the schema. Is that OK? I think so. | ||||
| If the Node-Selector evaluates to a single attribute node, the server | ||||
| takes the content of the request, and sets it as the value of the | ||||
| attribute specified by the body of the request. The server then | ||||
| generates a 200 OK response, whose body contains the value of the | ||||
| attribute, with a Content-Type of text/plain. | ||||
| If the result of the POST is a document which does not comply with | ||||
| the XML schema for the application usage, the server MUST NOT perform | ||||
| the POST, and MUST reject the request with a 409 (Conflict). | ||||
| 7.2 PUT Handling | 7.2 PUT Handling | |||
| When the Request URI contains only the Document-URI, the semantics of | The behavior of a server in receipt of a PUT request is as specified | |||
| PUT are as defined in HTTP 1.1 Section 9.6 - the content of the | in HTTP 1.1 Section 9.6 - the content of the request is placed at the | |||
| request is placed at the specified location. | specified location. This section serves to define the notion of | |||
| "placement" and "specified location" within the context of XCAP | ||||
| If the Request URI contains a Node-Selector, the server MUST verify | resources. | |||
| that the document defined by the Document-URI exists. If no such | ||||
| document exists on the server, the server MUST reject the request | ||||
| with a 409 response code. If the document does exist, the server | ||||
| evaluates the Node-Selector as an XPath RelativeLocationPath, | ||||
| relative to the root of the document. If the Node-Selector does not | ||||
| comply to the grammar for RelativeLocationPath, the server MUST | ||||
| reject the request with a 400 response code. If the Node-Selector | ||||
| does comply, and it evaluates to anything other than the a single | ||||
| element node or attribute node, the server MUST reject the request | ||||
| with a 409 response code. | ||||
| If the Node-Selector evaluates to a single element node, the server | If the request URI represents a document (i.e., there is no node | |||
| takes the content of the request, and replaces the value of that | selector component), the content of the request MUST be a valid XML | |||
| element (where value is defined as all of the content - elements, | document, and MUST be compliant to the schema associated with the | |||
| text, or CDATA - between the begin and end tags of the element) with | application usage in the URI. If it is not, the request MUST be | |||
| that content. The server then returns a 200 OK response. | rejected with a 409 response. If the request URI matches a document | |||
| that exists on the server, that document is replaced by the content | ||||
| of the request. If the request URI does not match a document that | ||||
| exists on the server, the server adds the document to its repository, | ||||
| and associates it with the URI in the request URI. Note that this may | ||||
| require the creation of one or more "directories" on the server. | ||||
| OPEN ISSUE: PUT is not quite right here, since a subsequent GET on | If the Request URI represents an XML element (i.e., it contains a | |||
| the same URI will not return exactly the same thing - the begin | node selector, but no attribute selector) the server MUST verify that | |||
| and end tags will be present. This may need to be POST, but then, | the document defined by the document URI exists. If no such document | |||
| how to differentiate a replace with an append operation? | exists on the server, the server MUST reject the request with a 409 | |||
| response code. The content of the request MUST be a single XML | ||||
| element and associated content (including children elements). If the | ||||
| request URI matches an element within the document, that element is | ||||
| removed, and replaced with the content of the request. If the request | ||||
| URI does not match an element in the document, the server inserts the | ||||
| content of the request as a new element in the document, such that | ||||
| the resulting document is compliant to the schema, and such that the | ||||
| request URI, when evaluated, would now point to the element which was | ||||
| inserted. There may be more than one way to perform such an | ||||
| insertion; in that case, it is the discretion of the implementor as | ||||
| to how it is done. It may also be possible that the insertion cannot | ||||
| be done without other additional elements being inserted, or cannot | ||||
| be done because the new element is not compliant to the schema. In | ||||
| such a case, the server MUST return a 409 response code. In all | ||||
| cases, the resulting document MUST be compliant to the schema. | ||||
| If the Node-Selector evaluates to a single attribute node, the server | If the Request URI represents an XML attribute (i.e., it contains a | |||
| takes the content of the request, and sets it as the value of the | node selector and an attribute selector) the server MUST verify that | |||
| attribute. It then returns a 200 OK response. | the document defined by the document URI exists. If no such document | |||
| exists on the server, the server MUST reject the request with a 409 | ||||
| response code. The content of the request MUST be a single XML | ||||
| attribute, compliant to the grammar for Attribute as defined in XML | ||||
| 1.0 (i.e., name=value). If the request URI matches an ent within the | ||||
| document, that attribute is removed, and replaced with the content of | ||||
| the request. If the request URI does not match an attribute in the | ||||
| document, the server inserts the content of the request as a new | ||||
| attribute in the document, such that the resulting document is | ||||
| compliant to the schema, and such that the request URI, when | ||||
| evaluated, would now point to the attribute which was inserted. There | ||||
| may be more than one way to perform such an insertion; in that case, | ||||
| it is the discretion of the implementor as to how it is done. It may | ||||
| also be possible that the insertion cannot be done without other | ||||
| additional content being inserted, or cannot be done because the new | ||||
| attribute is not compliant to the schema. In such a case, the server | ||||
| MUST return a 409 response code. In all cases, the resulting document | ||||
| MUST be compliant to the schema. | ||||
| If the result of the PUT is a document which does not comply with the | If the creation or insertion was successful, the server returns a 200 | |||
| XML schema for the application usage, the server MUST NOT perform the | OK or 201 Created, as appropriate. | |||
| PUT, and MUST reject the request with a 409 (Conflict). | ||||
| 7.3 GET Handling | 7.3 GET Handling | |||
| If the request URI contains only a Document-URI, the server returns | The semantics of GET are as specified in RFC 2616. This section | |||
| the document specified by the URI if it exists, else returns a 404 | clarifies the specific content to be returned for a particular URI | |||
| response. | that represents an XCAP resource. | |||
| If the request URI specifies a Node-Selector, the server verifies | ||||
| that the document specified by the Document-URI exists. If it does | ||||
| not exist, the server returns a 404 (Not Found) response. If the | ||||
| document does exist, the server evaluates the Node-Selector as an | ||||
| XPath RelativeLocationPath, relative to the root of the document. If | ||||
| the Node-Selector does not comply to the grammar for | ||||
| RelativeLocationPath, the server MUST reject the request with a 400 | ||||
| response code. If the Node-Selector does comply, and it evaluates to | ||||
| anything other than the a single element node or attribute node, the | ||||
| server MUST reject the request with a 409 response code. | ||||
| If the Node-Selector evaluates to a single element node, the server | ||||
| takes the document text, starting with, and including, the begin tag | ||||
| of the element, up to, and including, the end tag for the element, | ||||
| and places it into the body of a 200 OK response, setting the | ||||
| Content-Type to application/xml. | ||||
| If the Node-Selector evaluates to a single attribute node, the server | ||||
| takes the value of the attribute and returns it as the content of the | ||||
| 200 OK response, setting the Content-Type to text/plain. | ||||
| OPEN ISSUE: Do we need to say anything about HEAD? We havent said | If the request URI contains only a document URI, the server returns | |||
| anything about meta-data so far; most of that is just regular HTTP | the document specified by the URI if it exists, else returns a 404 | |||
| usage, I think. | response. If the request URI contains a node selector, and that node | |||
| selector identifies an XML element in an existing document, that | ||||
| element is returned in the 200 response. The content of the response | ||||
| is the portion of the XML document starting with the left bracket of | ||||
| the begin tag of the element, ending with the right bracket of the | ||||
| end tag of the element. If the request URI contains a node selector, | ||||
| and that node selector contains an attribute selector, and that | ||||
| attribute exists in the specified document, the server returns that | ||||
| attribute, formatted as Attribute in the XML 1.0 specifications. In | ||||
| all cases, if the referenced resource does not exist, a 404 is | ||||
| returned. | ||||
| 7.4 DELETE Handling | 7.4 DELETE Handling | |||
| The semantics of DELETE are as specified in RFC 2616. This section | ||||
| clarifies the specific content to be deleted for a particular URI | ||||
| that represents an XCAP resource. | ||||
| If the request URI contains only a Document-URI, the server deletes | If the request URI contains only a Document-URI, the server deletes | |||
| the document specified by the URI if it exists and returns a 200 OK | the document specified by the URI if it exists and returns a 200 OK | |||
| response, else returns a 404 response. | response, else returns a 404 response. If the request URI specifies a | |||
| Node-Selector, the server verifies that the document specified by the | ||||
| If the request URI specifies a Node-Selector, the server verifies | Document-URI exists. If it does not exist, the server returns a 404 | |||
| that the document specified by the Document-URI exists. If it does | (Not Found) response. If the document does exist, and the node | |||
| not exist, the server returns a 404 (Not Found) response. If the | selector specifies an XML element that exists, that element is | |||
| document does exist, the server evaluates the Node-Selector as an | removed from the document. If the document does exist, and the node | |||
| XPath RelativeLocationPath, relative to the root of the document. If | selector specifies an XML attribute that exists in the document, that | |||
| the Node-Selector does not comply to the grammar for | attribute is removed from the document. If the node selector returns | |||
| RelativeLocationPath, the server MUST reject the request with a 400 | a no-match, a 404 (Not Found) is returned. However, if removal of the | |||
| response code. If the Node-Selector does comply, and it evaluates to | element or attribute would result in a document which does not comply | |||
| the empty set, the server MUST reject the request with a 404 (Not | ||||
| Found). | ||||
| Otherwise, the server removes all of the data defined by the | ||||
| node-set. Specifically, any elements in the node set are removed from | ||||
| the document, and any attributes in the node set are removed from the | ||||
| document. It then returns a 200 OK response. | ||||
| If the result of the deletion is a document which does not comply | ||||
| with the XML schema for the application usage, the server MUST NOT | with the XML schema for the application usage, the server MUST NOT | |||
| perform the deletion, and MUST reject the request with a 409 | perform the deletion, and MUST reject the request with a 409 | |||
| (Conflict). | (Conflict). | |||
| 7.5 Managing Modification Times | 7.5 Managing Etags | |||
| An XCAP server MUST maintain modification times for all resources | ||||
| that can be referenced by a URI. Specifically, this means that each | ||||
| document, and within the document, each element and attribute, MUST | ||||
| be associated with a modification time maintained by the server. | ||||
| These modification times are needed to support condition GET, POST | ||||
| and PUT requests. | ||||
| When a PUT or POST request is made that creates or replaces a | An XCAP server MUST maintain entity tags for all resources that can | |||
| document, the modification time of that document and all elements and | be referenced by a URI. Specifically, this means that each document, | |||
| attributes within is set to the current time. When a PUT request is | and within the document, each element and attribute, MUST be | |||
| made to a URI referencing an XML element, the modification time of | associated with an entity tag maintained by the server. These entity | |||
| that element and all of its enclosed children and their attributes is | tags are needed to support conditional PUT and DELETE requests. | |||
| set to the current time. Furthermore, the modification time of all | ||||
| elements which are ancestors of that element have their modification | ||||
| time set to the current time. However, the modification times of | ||||
| attributes belong to elements that are ancestors of the modified | ||||
| element do not have their modification times changed. | ||||
| When a POST request is made to a URI referencing an XML element, the | When a PUT request is made that creates or replaces a document, the | |||
| modification time of all of the elements and their attributes within | entity tag of that document and all elements and attributes within is | |||
| the document in the body of the request is set to the current time. | updated. | |||
| Furthermore, the modification time of the element which is the new | ||||
| parent of the elements in the request, and all of its ancestors, have | ||||
| their modification time set to the current time. However, the | ||||
| modification times of their attributes are unchanged. | ||||
| When a POST request is made to a URI referencing an XML attribute, | When a PUT request is made to a URI referencing an XML element, the | |||
| the modification time of that attribute, its element, and all | entity tag of that element, its attributes, and all of its enclosed | |||
| elements that are ancestors of that element is set to the current | children and their attributes is updated. For a PUT or DELETE request | |||
| time. | for an XML element, the entity tag of all elements which are | |||
| ancestors of that element are updated. However, the entity tags of | ||||
| attributes belonging to elements that are ancestors of the modified | ||||
| element do not have their entity tags changed, because those | ||||
| resources have not actually changed. | ||||
| When a DELETE request is made to a URI referencing an element, the | When a PUT request is made to a URI referencing an XML attribute, the | |||
| modification time of all ancestors of that element is set to the | entity of that attribute is updated. For a PUT or DELETE request for | |||
| current time. When a DELETE request is made to a URI referencing an | an attribute, the entity tags for its element, and all elements that | |||
| attribute, the modification time of its element, and all ancestors of | are ancestors of that element are updated. | |||
| that element, is set to the current time. | ||||
| 8. Examples | 8. Examples | |||
| This section goes through several examples, making use of the | This section goes through several examples, making use of the | |||
| presence-lists [17] XCAP application usage. | resource-lists [17] XCAP application usage. | |||
| First, a user Bill creates a new presence-list, initially with no | First, a user Bill creates a new resource-list, initially with no | |||
| users in it: | users in it: | |||
| PUT | PUT | |||
| http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1 | http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1 | |||
| Content-Type:application/presence-lists+xml | Content-Type:application/presence-lists+xml | |||
| <?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | |||
| <presence-lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | <resource-lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | |||
| <list name="friends" uri="sip:friends@example.com" subscribable="true"> | <list name="friends" uri="sip:friends@example.com" subscribeable="true"> | |||
| </list> | </list> | |||
| </presence-lists> | </resource-lists> | |||
| Next, Bill adds an entry to the list: | Next, Bill adds an entry to the list: | |||
| PUT | PUT | |||
| http://xcap.example.com/services/presence-lists/users/bill/fr.xml? | http://xcap.example.com/services/presence-lists/users/bill/fr.xml? | |||
| presence-lists/list[@name="friends"] HTTP/1.1 | resource-lists/list[@name="friends"]/entry HTTP/1.1 | |||
| Content-Type:text/plain | Content-Type:text/plain | |||
| <entry name="Bill" uri="sip:bill@example.com"> | <entry name="Bob" uri="sip:bob@example.com"> | |||
| <display-name>Bill Doe</display-name> | <display-name>Bob Jones</display-name> | |||
| </entry> | </entry> | |||
| Note how the URI in the PUT request selects the list element whose | Next, Bill fetches the list: | |||
| name attribute is "friends". The body of that request replaces the | ||||
| existing value of that element, which was empty. | GET | |||
| http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1 | ||||
| And the result is: | ||||
| HTTP/1.1 200 OK | ||||
| Etag: "wwhha" | ||||
| Content-Type: application/xml | ||||
| <?xml version="1.0" encoding="UTF-8"?> | ||||
| <resource-lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | ||||
| <list name="friends" uri="sip:friends@example.com" | ||||
| subscribeable="true"> | ||||
| <entry name="Bob" uri="sip:bob@example.com"> | ||||
| <display-name>Bob Jones</display-name> | ||||
| </entry> | ||||
| </list> | ||||
| </resource-lists> | ||||
| Next, Bill adds another entry to the list, which is another list that | Next, Bill adds another entry to the list, which is another list that | |||
| has three entries: | has three entries: | |||
| POST | PUT | |||
| http://xcap.example.com/services/presence-lists/users/bill/fr.xml? | http://xcap.example.com/services/presence-lists/users/bill/fr.xml? | |||
| presence-lists/list[@name="friends"]/entry[@name="Bill"] HTTP/1.1 | presence-lists/list[@name="friends"]/list[@name="close-friends"] HTTP/1.1 | |||
| Content-Type:text/plain | Content-Type:text/plain | |||
| <list name="close-friends" uri="sip:close-friends@example.com" | <list name="close-friends" uri="sip:close-friends@example.com" | |||
| subscribable="true"> | subscribeable="true"> | |||
| <entry name="Joe" uri="sip:joe@example.com"> | <entry name="Joe" uri="sip:joe@example.com"> | |||
| <display-name>Joe Smith</display-name> | <display-name>Joe Smith</display-name> | |||
| </entry> | </entry> | |||
| <entry name="Nancy" uri="sip:nancy@example.com"> | <entry name="Nancy" uri="sip:nancy@example.com"> | |||
| <display-name>Nancy Gross</display-name> | <display-name>Nancy Gross</display-name> | |||
| </entry> | </entry> | |||
| <entry name="Petri" uri="sip:petri@example.com"> | <entry name="Petri" uri="sip:petri@example.com"> | |||
| <display-name>Petri Aukia</display-name> | <display-name>Petri Aukia</display-name> | |||
| </entry> | </entry> | |||
| </list> | </list> | |||
| skipping to change at page 22, line 39 ¶ | skipping to change at page 22, line 12 ¶ | |||
| Bill decides to check on the URI for Nancy: | Bill decides to check on the URI for Nancy: | |||
| GET | GET | |||
| http://xcap.example.com/services/presence-lists/users/bill/fr.xml? | http://xcap.example.com/services/presence-lists/users/bill/fr.xml? | |||
| presence-lists/list/list/entry[@name="Nancy"]/@uri HTTP/1.1 | presence-lists/list/list/entry[@name="Nancy"]/@uri HTTP/1.1 | |||
| and the server responds: | and the server responds: | |||
| HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
| Etag: "ad88" | ||||
| Content-Type:text/plain | Content-Type:text/plain | |||
| sip:nancy@example.com | uri="sip:nancy@example.com" | |||
| 9. Security Considerations | 9. Security Considerations | |||
| Frequently, the data manipulated by XCAP contains sensitive | Frequently, the data manipulated by XCAP contains sensitive | |||
| information. To avoid eavesdroppers from seeing this information, | information. To avoid eavesdroppers from seeing this information, it | |||
| XCAP RECOMMENDS that an admistrator hand out an https URI as the XCAP | is RECOMMENDED that an admistrator hand out an https URI as the XCAP | |||
| root services URI. This will result in TLS-encrypted communications | root services URI. This will result in TLS-encrypted communications | |||
| between the client and server, preventing any eavesdropping. | between the client and server, preventing any eavesdropping. | |||
| Client and server authentication are also important. A client needs | Client and server authentication are also important. A client needs | |||
| to be sure it is talking to the server it believes it is contacting. | to be sure it is talking to the server it believes it is contacting. | |||
| Otherwise, it may be given false information, which can lead to | Otherwise, it may be given false information, which can lead to | |||
| denial of service attacks against a client. To prevent this, a client | denial of service attacks against a client. To prevent this, a client | |||
| SHOULD attempt to upgrade [8] any connections to TLS. Similarly, | SHOULD attempt to upgrade [10] any connections to TLS. Similarly, | |||
| authorization of read and write operations against the data is | authorization of read and write operations against the data is | |||
| important, and this requires client authentication. As a result, a | important, and this requires client authentication. As a result, a | |||
| server SHOULD challenge a client using HTTP Digest [6] to establish | server SHOULD challenge a client using HTTP Digest [6] to establish | |||
| its identity, and this SHOULD be done over a TLS connection. | its identity, and this SHOULD be done over a TLS connection. | |||
| 10. IANA Considerations | 10. IANA Considerations | |||
| This specification instructs IANA to create a new registry for XCAP | This specification instructs IANA to create a new registry for XCAP | |||
| application usage IDs (AUIDs). | application usage IDs (AUIDs). | |||
| XCAP AUIDs are registered by the IANA when they are published in | XCAP AUIDs are registered by the IANA when they are published in | |||
| standards track RFCs. The IANA Considerations section of the RFC | standards track RFCs. The IANA Considerations section of the RFC | |||
| must include the following information, which appears in the IANA | must include the following information, which appears in the IANA | |||
| registry along with the RFC number of the publication. | registry along with the RFC number of the publication. | |||
| Name of the AUID. The name MAY be of any length, but SHOULD be no | Name of the AUID. The name MAY be of any length, but SHOULD be no | |||
| more than twenty characters long. The name MUST consist of | more than twenty characters long. The name MUST consist of | |||
| alphanum [9] characters only. | alphanum [11] characters only. | |||
| Descriptive text that describes the application usage. | Descriptive text that describes the application usage. | |||
| Normative References | Normative References | |||
| [1] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML | [1] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML | |||
| Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502, | Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502, | |||
| May 2001. | May 2001. | |||
| [2] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., | [2] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., | |||
| Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- | Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- | |||
| HTTP/1.1", RFC 2616, June 1999. | HTTP/1.1", RFC 2616, June 1999. | |||
| [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement | [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement | |||
| Levels", BCP 14, RFC 2119, March 1997. | Levels", BCP 14, RFC 2119, March 1997. | |||
| [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC | [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC | |||
| 3023, January 2001. | 3023, January 2001. | |||
| [5] Clark, J. and S. DeRose, "XML Path Language (XPath) Version | [5] Clark, J. and S. DeRose, "XML Path Language (XPath) Version | |||
| 1.0", W3C REC REC-xpath-19991116, November 1999. | 1.0", W3C REC REC-xpath-19991116, November 1999. | |||
| [6] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., | [6] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., | |||
| Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication: | Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication: | |||
| Basic and Digest Access Authentication", RFC 2617, June 1999. | Basic and Digest Access Authentication", RFC 2617, June 1999. | |||
| [7] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. | [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax | |||
| Specifications: ABNF", RFC 2234, November 1997. | ||||
| [8] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", | [8] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform | |||
| RFC 2817, May 2000. | Resource Identifiers (URI): Generic Syntax", RFC 2396, August | |||
| 1998. | ||||
| [9] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., | [9] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. | |||
| Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP: | ||||
| Session Initiation Protocol", RFC 3261, June 2002. | [10] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", | |||
| RFC 2817, May 2000. | ||||
| [11] 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. | ||||
| Informative References | Informative References | |||
| [10] Rosenberg, J., "A Presence Event Package for the Session | [12] Rosenberg, J., "A Presence Event Package for the Session | |||
| Initiation Protocol (SIP)", draft-ietf-simple-presence-10 (work | Initiation Protocol (SIP)", draft-ietf-simple-presence-10 (work | |||
| in progress), January 2003. | in progress), January 2003. | |||
| [11] Rosenberg, J., "A Watcher Information Event Template-Package | [13] Rosenberg, J., "A Watcher Information Event Template-Package | |||
| for the Session Initiation Protocol (SIP)", | for the Session Initiation Protocol (SIP)", | |||
| draft-ietf-simple-winfo-package-05 (work in progress), January | draft-ietf-simple-winfo-package-05 (work in progress), January | |||
| 2003. | 2003. | |||
| [12] Rosenberg, J., "An Extensible Markup Language (XML) Based | [14] Rosenberg, J., "An Extensible Markup Language (XML) Based | |||
| Format for Watcher Information", | Format for Watcher Information", | |||
| draft-ietf-simple-winfo-format-04 (work in progress), January | draft-ietf-simple-winfo-format-04 (work in progress), January | |||
| 2003. | 2003. | |||
| [13] Rosenberg, J., Roach, A. and B. Campbell, "A Session Initiation | [15] Roach, A., Rosenberg, J. and B. Campbell, "A Session Initiation | |||
| Protocol (SIP) Event Notification Extension for Resource | Protocol (SIP) Event Notification Extension for Resource | |||
| Lists", draft-ietf-simple-event-list-04 (work in progress), | Lists", draft-ietf-simple-event-list-04 (work in progress), | |||
| June 2003. | June 2003. | |||
| [14] Rosenberg, J. and M. Isomaki, "Requirements for Manipulation of | [16] Rosenberg, J. and M. Isomaki, "Requirements for Manipulation of | |||
| Data Elements in Session Initiation Protocol (SIP) for Instant | Data Elements in Session Initiation Protocol (SIP) for Instant | |||
| Messaging and Presence Leveraging Extensions (SIMPLE) Systems", | Messaging and Presence Leveraging Extensions (SIMPLE) Systems", | |||
| draft-ietf-simple-data-req-02 (work in progress), April 2003. | draft-ietf-simple-data-req-03 (work in progress), June 2003. | |||
| [15] Newman, C. and J. Myers, "ACAP -- Application Configuration | [17] Rosenberg, J., "An Extensible Markup Language (XML) | |||
| Configuration Access Protocol (XCAP) Usage for Presence | ||||
| Lists", draft-ietf-simple-xcap-list-usage-00 (work in | ||||
| progress), June 2003. | ||||
| [18] Newman, C. and J. Myers, "ACAP -- Application Configuration | ||||
| Access Protocol", RFC 2244, November 1997. | Access Protocol", RFC 2244, November 1997. | |||
| [16] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA | [19] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA | |||
| Considerations Section in RFCs", BCP 26, RFC 2434, October | Considerations Section in RFCs", BCP 26, RFC 2434, October | |||
| 1998. | 1998. | |||
| [17] Rosenberg, J., "An Extensible Markup Language (XML) | [20] Roach, A., "Session Initiation Protocol (SIP)-Specific Event | |||
| Configuration Access Protocol (XCAP) Usage for Presence Lists", | Notification", RFC 3265, June 2002. | |||
| draft-rosenberg-simple-xcap-list-usage-00 (work in progress), | ||||
| May 2003. | ||||
| Author's Address | Author's Address | |||
| Jonathan Rosenberg | Jonathan Rosenberg | |||
| dynamicsoft | dynamicsoft | |||
| 600 Lanidex Plaza | 600 Lanidex Plaza | |||
| Parsippany, NJ 07054 | Parsippany, NJ 07054 | |||
| US | US | |||
| Phone: +1 973 952-5000 | Phone: +1 973 952-5000 | |||
| End of changes. 102 change blocks. | ||||
| 548 lines changed or deleted | 518 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||