idnits 2.17.1 draft-ietf-simple-xcap-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 7 instances of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 27, 2003) is 7481 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '13' is defined on line 920, but no explicit reference was found in the text == Unused Reference: '14' is defined on line 925, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** Obsolete normative reference: RFC 2616 (ref. '2') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3023 (ref. '4') (Obsoleted by RFC 7303) -- Possible downref: Non-RFC (?) normative reference: ref. '5' ** Obsolete normative reference: RFC 2617 (ref. '6') (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2234 (ref. '7') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2396 (ref. '8') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2818 (ref. '9') (Obsoleted by RFC 9110) == Outdated reference: A later version (-07) exists of draft-ietf-simple-event-list-04 == Outdated reference: A later version (-05) exists of draft-ietf-simple-xcap-list-usage-00 -- Obsolete informational reference (is this intentional?): RFC 2434 (ref. '19') (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 3265 (ref. '20') (Obsoleted by RFC 6665) Summary: 8 errors (**), 0 flaws (~~), 7 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 SIMPLE J. Rosenberg 2 Internet-Draft dynamicsoft 3 Expires: April 26, 2004 October 27, 2003 5 The Extensible Markup Language (XML) Configuration Access Protocol 6 (XCAP) 7 draft-ietf-simple-xcap-01 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at http:// 24 www.ietf.org/ietf/1id-abstracts.txt. 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This Internet-Draft will expire on April 26, 2004. 31 Copyright Notice 33 Copyright (C) The Internet Society (2003). All Rights Reserved. 35 Abstract 37 This specification defines the Extensible Markup Language (XML) 38 Configuration Access Protocol (XCAP). XCAP allows a client to read, 39 write and modify application configuration data, stored in XML format 40 on a server. XCAP is not a new protocol. XCAP maps XML document 41 sub-trees and element attributes to HTTP URIs, so that these 42 components can be directly accessed by HTTP. 44 Table of Contents 46 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 47 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4 48 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 49 4. Application Usages . . . . . . . . . . . . . . . . . . . . . 6 50 5. URI Construction . . . . . . . . . . . . . . . . . . . . . . 8 51 5.1 Identifying the XML Document . . . . . . . . . . . . . . . . 8 52 5.2 Identifying the XML Nodes . . . . . . . . . . . . . . . . . 9 53 6. Client Operations . . . . . . . . . . . . . . . . . . . . . 12 54 6.1 Creating a New Document . . . . . . . . . . . . . . . . . . 12 55 6.2 Replace an Existing Document . . . . . . . . . . . . . . . . 12 56 6.3 Deleting a Document . . . . . . . . . . . . . . . . . . . . 12 57 6.4 Fetching a Document . . . . . . . . . . . . . . . . . . . . 12 58 6.5 Creating a New Element . . . . . . . . . . . . . . . . . . . 12 59 6.6 Replacing an Element in the Document . . . . . . . . . . . . 13 60 6.7 Delete an Element . . . . . . . . . . . . . . . . . . . . . 13 61 6.8 Fetch an Element . . . . . . . . . . . . . . . . . . . . . . 13 62 6.9 Create an Attribute . . . . . . . . . . . . . . . . . . . . 14 63 6.10 Replacing Attributes . . . . . . . . . . . . . . . . . . . . 14 64 6.11 Deleting Attributes . . . . . . . . . . . . . . . . . . . . 14 65 6.12 Fetching Attributes . . . . . . . . . . . . . . . . . . . . 14 66 6.13 Read/Modify/Write Transactions . . . . . . . . . . . . . . . 15 67 7. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 16 68 7.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . . 16 69 7.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . . 17 70 7.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . . 18 71 7.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . . 18 72 7.5 Managing Etags . . . . . . . . . . . . . . . . . . . . . . . 19 73 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 20 74 9. Security Considerations . . . . . . . . . . . . . . . . . . 23 75 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24 76 Normative References . . . . . . . . . . . . . . . . . . . . 25 77 Informative References . . . . . . . . . . . . . . . . . . . 26 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . 27 79 Intellectual Property and Copyright Statements . . . . . . . 28 81 1. Introduction 83 In many communications applications, such as Voice over IP, instant 84 messaging, and presence, it is necessary for network servers to 85 access per-user information in the process of servicing a request. 86 This per-user information resides within the network, but is managed 87 by the end user themselves. Its management can be done through a 88 multiplicity of access points, including the web, a wireless handset, 89 or a PC application. 91 Examples of per-user information are presence [12] authorization 92 policy and presence lists. Presence lists are lists of users whose 93 presence is desired by a watcher. Presence information for the list 94 of users can be obtained by subscribing to a resource which 95 represents that list [15]. In this case, the Resource List Server 96 (RLS) requires access to this list in order to process a SIP 97 [11]SUBSCRIBE [20] request for it. Requirements for manipulation of 98 presence lists and authorization policies have been specified by the 99 SIMPLE working group [16]. 101 This specification describes a protocol that can be used to 102 manipulate this per-user data. It is called the Extensible Markup 103 Language (XML) Configuration Access Protocol (XCAP). XCAP is not a 104 new protocol. Rather, it is a set of conventions for mapping XML 105 documents and document components into HTTP URIs, rules for how the 106 modification of one resource affects another, data validation 107 constraints, and authorization policies associated with access to 108 those resources. Because of this structure, normal HTTP primitives 109 can be used to manipulate the data. XCAP is based heavily on ideas 110 borrowed from the Application Configuration Access Protocol (ACAP) 111 [18], but it is not an extension of it, nor does it have any 112 dependencies on it. Like ACAP, XCAP is meant to support the 113 configuration needs for a multiplicity of applications, rather than 114 just a single one. 116 2. Overview of Operation 118 Each application that makes use of XCAP specifies an application 119 usage (Section 4). This application usage defines the XML schema [1] 120 for the data used by the application, along with other key pieces of 121 information. The principal task of XCAP is to allow clients to read, 122 write, modify, create and delete pieces of that data. These 123 operations are supported using HTTP 1.1 [2]. An XCAP server acts as a 124 repository for collections of XML documents. There will be documents 125 stored for each application. Within each application, there are 126 documents stored for each user. Each user can have a multiplicity of 127 documents for a particular application. To access some component of 128 one of those documents, XCAP defines an algorithm for constructing a 129 URI that can be used to reference that component. Components refer to 130 any subtree of the document, or any attribute for any element within 131 the document. Thus, the HTTP URIs used by XCAP point to pieces of 132 information that are finer grained than the XML document itself. 134 With a standardized naming convention for mapping components of XML 135 documents to HTTP URIs, the basic operations for accessing the data 136 are provided by existing HTTP primitives. Reading one of the 137 components is accomplished with HTTP GET, creating or modifying one 138 of the components is done with an HTTP PUT, and removing one of the 139 components is done with an HTTP DELETE. To provide atomic read/ 140 modify/write operations, HTTP entity tags are used. 142 3. Terminology 144 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 145 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 146 and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and 147 indicate requirement levels for compliant implementations. 149 4. Application Usages 151 A central concept in XCAP is that of an application usage. An 152 application usage defines the way in which a specific application 153 makes use of XCAP. This definition is composed of several pieces of 154 information, such as an XML schema and constraints on values of one 155 element given values in another. 157 Application usages are documented in specifications which convey this 158 information. In particular, an application usage specification MUST 159 provide the following information: 161 Application Usage ID (AUID): Each application usage is associated 162 with a name, called an AUID. This name uniquely identifies the 163 application usage, and is different from all other AUIDs. AUIDs 164 exist in one of two namespaces. The first namespace is the IETF 165 namespace. This namespace contains a set of tokens, each of which 166 is registered with IANA. These registrations occur with the 167 publication of standards track RFCs [19] based on the guidelines 168 in Section 10. The second namespace is the vendor-proprietary 169 namespace. Each AUID in that namespace is prefixed with the 170 reverse domain name name of the organization creating the AUID, 171 followed by a period, followed by any vendor defined token. As an 172 example, the example.com domain can create an AUID with the value 173 "com.example.foo" but cannot create one with the value 174 "org.example.foo". AUIDs within the vendor namespace do not need 175 to be registered with IANA. The vendor namespace is also meant to 176 be used in lab environments where no central registry is needed. 177 The syntax for AUIDs, expressed in ABNF [7] (and using some of the 178 BNF defined in RFC 2396 [8]) is: 180 AUID = global-auid / vendor-auid 181 global-auid = auid 182 auid = alphanum / mark 183 vendor-auid = rev-hostname "." auid 184 rev-hostname = toplabel *( "." domainlabel ) 185 domainlabel = alphanum 186 / alphanum *( alphanum / "-" ) alphanum 187 toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum 189 MIME Type: Each application usage MUST register a MIME type for its 190 XML documents. This is done based on the procedures of RFC 3023 191 [4]. 193 XML Schema: Each application will have a unique schema which defines 194 the data needed by the application. In XCAP, this schema is 195 represented using XML schema [1]. 197 Additional Constraints: XML schemas can represent a variety of 198 constraints about data, such as ranges and types. However, schemas 199 cannot cover all types of data constraints, including constraints 200 introduced by data interdependencies. For example, one XML element 201 may contain an integer which defines the maximum number of 202 instances of another element. The application usage defines these 203 additional constraints. 205 Data Semantics: The application usage needs to define detailed 206 semantics for each piece of data in the schema. 208 Naming Conventions: The data defined by the XML schema will be used 209 by any number of entities participating in the application. In the 210 case of presence list, the data is used by the Resource List 211 Server (RLS), which reads the data, and by the clients, which 212 write it. During the execution of the application (i.e., the 213 processing of the list subscription), specific documents will need 214 to be read or written. In order for the application to function 215 properly, there needs to be agreement on exactly which documents 216 are read or written by the application. This is an issue of naming 217 conventions; agreeing on how an application constructs the URI 218 representing the document that is to be read or written. The 219 application usage spells out this information. 221 Resource Interdependencies: In many cases, when a user modifies an 222 XCAP resource, many other resources need to change as well. Such 223 interdependencies are application usage dependent. As an example, 224 when a user performs a PUT operation to create a new presence 225 list, the server may need to fill in the URI associated with that 226 list. These interdependencies need to be specified by the 227 application usage. Note that, if a server needs to modify data 228 within a document just PUT by the client, this modification is 229 effectively accomplished as a separate transaction. Concretely, 230 this means that, after the server modifies the data, the entity 231 tags are updated as if the client had made the change itself. 233 Authorization Policies: By default, an XCAP server will only allow a 234 user to access (read, write, delete or modify) their own 235 documents. The application usage can specify differing default 236 authorization policies. An application usage can also specify 237 whether another application usage is used to define the 238 authorization policies. An application usage for setting 239 authorization policies can also be defined subsequent to the 240 definition of the the main application usage. In such a case, the 241 main application usage needs only to specify that such a usage 242 will be defined in the future. 244 Application usages are similar to dataset classes in ACAP. 246 5. URI Construction 248 In order to manipulate a piece of configuration data, the data must 249 be represented by an HTTP URI. XCAP defines a specific naming 250 convention for constructing these URIs. In particular, the host part 251 identifies the XCAP server. The abs_path component of the HTTP URI 252 identifies the specific XML document to be modified. XCAP servers 253 organize XML documents in a specific hierarchical fashion, as 254 described in Section 5.1. The URI MAY contain a query. This query is 255 called a node selector. When present, it contains an XML component 256 identifier formatted according to Section 5.2. The node selector 257 identifies the specific component of the XML document. The HTTP URI 258 without the query is called the document URI. , and makes use the 259 specification for identifying nodes of an XML document. 261 5.1 Identifying the XML Document 263 XCAP mandates that a server organizes documents according to a 264 defined hierarchy. The root of this hierarchy is an HTTP URI called 265 the XCAP services root URI. This URI identifies the root of the tree 266 within the domain where all XCAP documents are stored. It can be any 267 valid HTTP URL, but MUST NOT contain a query string. As an example, 268 http://xcap.example.com/services might be used as the XCAP services 269 root URI within the example.com domain. Typically, the XCAP services 270 root URI is provisioned into client devices for bootstrapping 271 purposes. 273 Beneath the XCAP services root URI is a tree structure for organizing 274 documents. The first level of this tree consists of the XCAP AUID. 275 So, continuing the example above, all of the documents used by the 276 presence list application would be under http://xcap.example.com/ 277 services/presence-lists. 279 It is assumed that each application will have data that is set by 280 users, and/or it will have global data that applies to all users. As 281 a result, within the directory structure for each application usage, 282 there are two sub-trees. One, called "users", holds the documents 283 that are applicable to specific users, and the other, called 284 "global", holds documents applicable to all users. 286 Within the "users" tree are zero or more sub-trees, each of which 287 identifies a documents that apply to a specific user. XCAP does not 288 itself define what it means for documents to "apply" to a user, 289 beyond specification of a baseline authorization policy. 290 Specifically, the default authorization policy is that only a user 291 who authenticates themself as user X can read, write, or otherwise 292 access in any way the documents within sub-tree X. Each application 293 usage can specify additional authorization policies which depend on 294 data used by the application itself. 296 The remainder of the URI (the path following "global" or the specific 297 user) is not constrained by this specification. The application usage 298 MAY introduce constraints, or may allow any structure to be used. 300 5.2 Identifying the XML Nodes 302 The second component of the XCAP URI specifies specific nodes of the 303 XML document which are to be accessed. A node refers to either an XML 304 element or an attribute of an element. The node selector is an 305 expression which identifies an element or attribute. Its grammar is: 307 node-selector = element-selector ["/" attribute-selector] 308 element-selector = step *( "/" step) 309 step = by-name / by-pos / by-attr 310 by-name = QName ; from XML Namespaces 311 by-pos = QName "[" position "]" 312 position = 1*DIGIT 313 by-attr = QName "[" "@" att-name "=" <"> 314 att-value <"> "]" 315 att-name = QName 316 att-value = AttValue ; from XML specification 317 by-pos = QName "[" position "]" 318 position = *DIGIT 319 attribute-selector = "@" att-name 321 The node selector is based on the concepts in XPath [5]. Indeed, the 322 node selector expression happens to be a valid XPath expression. 323 However, XPath provides a set of functionality far richer than is 324 needed here, and its breadth would introduce complexity into XCAP. 326 To determne the XML element or attribute selected by the node 327 selector, processing begins at the root of the XML document. The 328 first step in the element selector is then taken. Each step chooses a 329 specific XML element within the current document context. The 330 document context is the point within the XML document from which a 331 specific step is evaluated. The document context begins at the root 332 of the document. When a step determines an element within that 333 context, that element becomes the new context for evaluation of the 334 next step. Each step can select an element by its name, by a 335 combination of name and attribute value, or by name and position. If 336 the step is attempting selection by name, the server looks for all 337 elements within the current context with that name. Name matching is 338 performed as described below. If there is more than one element with 339 the specified name, the result is considered a no-match. 341 If the step is attempting selection by name and attribute, the server 342 looks for all elements within the current document context with that 343 name. Of those that match, it looks for ones that have the given 344 attribute name, where that attribute has the given value. If there is 345 no match, or if more than one element matches, the result is 346 considered a no-match. 348 If the step is attempting selection by name and position, the server 349 looks for all elements within the current document context with that 350 name. These are then sorted in document order, as defined by Xpath. 351 The position-th element is then selected. If there are fewer than 352 position number of elements with that name, the result is considered 353 a no-match. 355 Once the last step is executed, if there is no attribute selector, 356 the result of the node selection is the last selected element. If 357 there is an attribute selector, the server checks to see if there is 358 an attribute with that name within the currently selectoed element. 359 If there is not, the result is considered a no-match. Otherwise, that 360 attribute is selected. 362 Matching of element names and attributes is performed by expanding 363 them into the expanded name form, as described in XML Namespaces, and 364 then performing the comparison of the results. When evaluating the 365 QNames in the node selector, the default namespace and namespace 366 definitions from the document URI apply. 368 As an example, consider the following XML document: 370 371 373 374 sip:userA@example.net 378 sip:userB@example.org 382 383 385 The node selector "watcherinfo/watcher-list/ 386 watcher[@id="8ajksjda7s"]" would select the following XML element: 388 sip:userA@example.net 393 6. Client Operations 395 An XCAP client is an HTTP 1.1 compliant client. Specific data 396 manipulation tasks are accomplished by invoking the right set of HTTP 397 methods with the right set of headers on the server. This section 398 describes those in detail 400 6.1 Creating a New Document 402 To create a new document, the client constructs a URI that references 403 the location where the document is to be placed. This URI MUST NOT 404 contain a NodeSelector component. The client then invokes a PUT 405 method on that URI. 407 The content in the request MUST be an XML document compliant to the 408 schema associated with the application usage defined by the URI. For 409 example, if the client performs a PUT operation to http:// 410 xcap.example.com/services/presence-lists/users/joe/mybuddies, 411 presence-lists is the application unique ID, and the schema defined 412 by it would dictate the body of the request. 414 6.2 Replace an Existing Document 416 To replace an existing document with a new one, the procedures of 417 Section 6.1 are followed; the Request-URI merely refers to an 418 existing document which is to be replaced with the content of the 419 request. 421 6.3 Deleting a Document 423 To delete a document, the client constructs a URI that references the 424 document to be deleted. By definition this URI will not contain a 425 NodeSelector component. The client then invokes a DELETE operation on 426 the URI to delete the document. 428 6.4 Fetching a Document 430 As one would expect, fetching a document is trivially accomplished by 431 performing an HTTP GET request with the Request URI set to the 432 document to be fetched. It is useful for clients to perform 433 conditional GETs using the If-Match header field, in order to check 434 if a locally cached copy of the document is still valid. An HTTP 435 server MUST return Etags for entities that represent resources 436 managed by XCAP. 438 6.5 Creating a New Element 440 To create a new XML element within an existing document, the client 441 constructs a URI whose document URI points to the document to be 442 modified. The node selector MUST be present in the URI. The node 443 selector is constructed such that it meets two constraints. First, if 444 evaluated against the current document, the result is a no-match. 445 Secondly, if the element was added to the document as desired by the 446 client, the node selector would select that element. 448 The client then invokes the HTTP PUT method [[OPEN ISSUE: what is the 449 content type?]]. The content in the request MUST be an XML element. 450 The server will insert the element into the document such that the 451 node selector, if evaluated by the server, would return the content 452 present in the request. The client SHOULD be certain, before making 453 the request, that the resulting modified document will also be 454 conformant to the schema. 456 It is important to note that the element might potentially be 457 inserted in the document in several different ways, and still meet 458 the constraints defined above. This is analagous to the case when a 459 new file is PUT into a directory on a server; the location of that 460 file within the directory is not specified, and is up the local file 461 system to decide. The only guarantee is that GET(PUT(x)) returns 462 document x. 464 6.6 Replacing an Element in the Document 466 Replacing an element of the document is also accomplished with PUT. 467 The only difference with the behavior above for insertion is that the 468 node selector, when evaluated against the current document, is a 469 match for an element in the current document. That element is 470 removed, and replaced with the content of the PUT request. 472 6.7 Delete an Element 474 To delete elements from a document, the client constructs a URI whose 475 document URI points to the document containing the elements to be 476 deleted. The node selector MUST be present, and identify the specific 477 element to be deleted. 479 The client then invokes the HTTP DELETE method. The server will 480 remove the element from the document. The client SHOULD be certain, 481 before making the request, that the resulting modified document will 482 also be conformant to the schema. 484 6.8 Fetch an Element 486 To fetch an element of a document, the client constructs a URI whose 487 document URI points to the document containing the element to be 488 fetched. The node selector MUST be present, and must identify the 489 element to be fetched. 491 The client then invokes the GET method. The response will contain 492 that XML element. Specifically, it contains the content of the XML 493 document, starting with the opening bracket for the begin tag for 494 that element, and ending with the closing bracket for the end tag for 495 that element. 497 6.9 Create an Attribute 499 To create an attribute in an existing element of a document, the 500 client constructs a URI whose document URI points to the document to 501 be modified. The node selector MUST be present. The node selector is 502 constructed such that it meets two constraints. First, if evaluated 503 against the current document, the result is a no-match. Secondly, if 504 the attribute was added to the document as desired by the client, the 505 node selector would select that attribute. 507 The client then invokes the HTTP PUT method. The content defined by 508 the request MUST be compliant to the grammar for Attribute as defined 509 in XML 1.0 [[OPEN ISSUE: content type?]]. The server will add that 510 attribute such that, if the node selector is evaluated on the 511 resulting document, it returns the attribute present in the request. 512 The client SHOULD be certain, before making the request, that the 513 resulting modified document will also be conformant to the schema. 515 6.10 Replacing Attributes 517 Replacing an attribute of the document is also accomplished with PUT. 518 The only difference with the behavior above for insertion is that the 519 node selector, when evaluated against the current document, is a 520 match for an attribute in the current document. That attribute is 521 removed, and replaced with the content of the PUT request. 523 6.11 Deleting Attributes 525 To delete attributes from the document, the client constructs a URI 526 whose document URI points to the document containing the attributes 527 to be deleted. The node selector MUST be present, and evaluate to an 528 attribute in the document to be deleted. 530 The client then invokes the HTTP DELETE method. The server will 531 remove the attribute from the document. The client SHOULD be certain, 532 before making the request, that the resulting modified document will 533 also be conformant to the schema. 535 6.12 Fetching Attributes 536 To fetch an attribute of a document, the client constructs a URI 537 whose Document-URI points to the document containing the attribute to 538 be fetched. The node selector MUST be present, containing an 539 expression identifying the attribute whose value is to be fetched. 541 The client then invokes the GET method. The response will contain 542 document with the specified attribute, formatted according to the 543 grammar of Attribute as defined in the XML 1.0 specifications. 545 6.13 Read/Modify/Write Transactions 547 It is anticipated that a common operation will be to read the current 548 version of a document or element, modify it on the client, and then 549 write the change back to the server. In order for the results to be 550 consistent with the client's expectations, the operation must be 551 atomic. 553 To accomplish this, the client makes use of entity tags returned by 554 the server in a GET operation used to read the element, attribute, or 555 document that is to be modified. To guarantee atomicity, the PUT 556 operation used to write the changes back to the server MUST contain 557 an If-Match header field, whose value is equal to the entity tag from 558 the prior GET response. If the request fails with a 412 response, the 559 client knows that another update of the data has occurred before it 560 was able to write the results back. The client can then fetch the 561 most recent version, and attempt its modification again. 563 Because there are no batching operations defined in HTTP, that would 564 allow for a number of separate create, modify or delete operations to 565 be performed atomically, designers of application usages should take 566 care to structure their schemas so that operations that need to be 567 performed atomically can be done in a single operation. 569 7. Server Behavior 571 An XCAP server is an HTTP 1.1 compliant origin server. The behaviors 572 mandated by this specification relate to the way in which the HTTP 573 URI is interpreted and the content is constructed. 575 An XCAP server MUST be explicitly aware of the application usage 576 against which requests are being made. That is, the server must be 577 explicitly configured to handle URIs for each specific application 578 usage, and must be aware of the constraints imposed by that 579 application usage. Furthermore, an XCAP server MUST be aware of all 580 of the XML namespaces present in any documents it manages. This is to 581 ensure that any data constraints or data interdependencies imposed by 582 a future application usage are properly supported by the server. It 583 is also required to ensure that authorization policies are properly 584 implemented. 586 When the server receives a request, the treatment depends on the URI. 587 If the URI refers to an application usage not understood by the 588 server, the server MUST reject the request with a 404 (Not Found) 589 response. If the URI refers to a user that is not recognized by the 590 server, it MUST reject the request with a 404 (Not Found). 592 Next, the server authenticates the request. All XCAP servers MUST 593 support HTTP Digest [6]. Furthermore, servers MUST support HTTP over 594 TLS, RFC 2818 [9]. It is RECOMMENDED that administrators use an HTTPS 595 URI as the XCAP root services URI, so that the digest client 596 authentication occurs over TLS. 598 Next, the server determines if the client has authorization to 599 perform the requested operation on the resource. The default 600 authorization policy is that only client X can access (create, read, 601 write, modify or delete) resources under the "users/X" directory. An 602 application usage can specify an alternate default authorization 603 policy specific to that usage. The server may also know of an 604 application usage that itself defines authorization policies for 605 another application usage. Of course, an administrator or privileged 606 user can override the default authorization policy, although this 607 specification provides no means for doing that. 609 Once authorized, the specific behavior depends on the method and what 610 the URI refers to. 612 7.1 POST Handling 614 Resources managed by XCAP do not represent processing scripts. As a 615 result, POST operations to XCAP URIs is not defined. A server 616 receiving such a request SHOULD return a 405. 618 7.2 PUT Handling 620 The behavior of a server in receipt of a PUT request is as specified 621 in HTTP 1.1 Section 9.6 - the content of the request is placed at the 622 specified location. This section serves to define the notion of 623 "placement" and "specified location" within the context of XCAP 624 resources. 626 If the request URI represents a document (i.e., there is no node 627 selector component), the content of the request MUST be a valid XML 628 document, and MUST be compliant to the schema associated with the 629 application usage in the URI. If it is not, the request MUST be 630 rejected with a 409 response. If the request URI matches a document 631 that exists on the server, that document is replaced by the content 632 of the request. If the request URI does not match a document that 633 exists on the server, the server adds the document to its repository, 634 and associates it with the URI in the request URI. Note that this may 635 require the creation of one or more "directories" on the server. 637 If the Request URI represents an XML element (i.e., it contains a 638 node selector, but no attribute selector) the server MUST verify that 639 the document defined by the document URI exists. If no such document 640 exists on the server, the server MUST reject the request with a 409 641 response code. The content of the request MUST be a single XML 642 element and associated content (including children elements). If the 643 request URI matches an element within the document, that element is 644 removed, and replaced with the content of the request. If the request 645 URI does not match an element in the document, the server inserts the 646 content of the request as a new element in the document, such that 647 the resulting document is compliant to the schema, and such that the 648 request URI, when evaluated, would now point to the element which was 649 inserted. There may be more than one way to perform such an 650 insertion; in that case, it is the discretion of the implementor as 651 to how it is done. It may also be possible that the insertion cannot 652 be done without other additional elements being inserted, or cannot 653 be done because the new element is not compliant to the schema. In 654 such a case, the server MUST return a 409 response code. In all 655 cases, the resulting document MUST be compliant to the schema. 657 If the Request URI represents an XML attribute (i.e., it contains a 658 node selector and an attribute selector) the server MUST verify that 659 the document defined by the document URI exists. If no such document 660 exists on the server, the server MUST reject the request with a 409 661 response code. The content of the request MUST be a single XML 662 attribute, compliant to the grammar for Attribute as defined in XML 663 1.0 (i.e., name=value). If the request URI matches an ent within the 664 document, that attribute is removed, and replaced with the content of 665 the request. If the request URI does not match an attribute in the 666 document, the server inserts the content of the request as a new 667 attribute in the document, such that the resulting document is 668 compliant to the schema, and such that the request URI, when 669 evaluated, would now point to the attribute which was inserted. There 670 may be more than one way to perform such an insertion; in that case, 671 it is the discretion of the implementor as to how it is done. It may 672 also be possible that the insertion cannot be done without other 673 additional content being inserted, or cannot be done because the new 674 attribute is not compliant to the schema. In such a case, the server 675 MUST return a 409 response code. In all cases, the resulting document 676 MUST be compliant to the schema. 678 If the creation or insertion was successful, the server returns a 200 679 OK or 201 Created, as appropriate. 681 7.3 GET Handling 683 The semantics of GET are as specified in RFC 2616. This section 684 clarifies the specific content to be returned for a particular URI 685 that represents an XCAP resource. 687 If the request URI contains only a document URI, the server returns 688 the document specified by the URI if it exists, else returns a 404 689 response. If the request URI contains a node selector, and that node 690 selector identifies an XML element in an existing document, that 691 element is returned in the 200 response. The content of the response 692 is the portion of the XML document starting with the left bracket of 693 the begin tag of the element, ending with the right bracket of the 694 end tag of the element. If the request URI contains a node selector, 695 and that node selector contains an attribute selector, and that 696 attribute exists in the specified document, the server returns that 697 attribute, formatted as Attribute in the XML 1.0 specifications. In 698 all cases, if the referenced resource does not exist, a 404 is 699 returned. 701 7.4 DELETE Handling 703 The semantics of DELETE are as specified in RFC 2616. This section 704 clarifies the specific content to be deleted for a particular URI 705 that represents an XCAP resource. 707 If the request URI contains only a Document-URI, the server deletes 708 the document specified by the URI if it exists and returns a 200 OK 709 response, else returns a 404 response. If the request URI specifies a 710 Node-Selector, the server verifies that the document specified by the 711 Document-URI exists. If it does not exist, the server returns a 404 712 (Not Found) response. If the document does exist, and the node 713 selector specifies an XML element that exists, that element is 714 removed from the document. If the document does exist, and the node 715 selector specifies an XML attribute that exists in the document, that 716 attribute is removed from the document. If the node selector returns 717 a no-match, a 404 (Not Found) is returned. However, if removal of the 718 element or attribute would result in a document which does not comply 719 with the XML schema for the application usage, the server MUST NOT 720 perform the deletion, and MUST reject the request with a 409 721 (Conflict). 723 7.5 Managing Etags 725 An XCAP server MUST maintain entity tags for all resources that can 726 be referenced by a URI. Specifically, this means that each document, 727 and within the document, each element and attribute, MUST be 728 associated with an entity tag maintained by the server. These entity 729 tags are needed to support conditional PUT and DELETE requests. 731 When a PUT request is made that creates or replaces a document, the 732 entity tag of that document and all elements and attributes within is 733 updated. 735 When a PUT request is made to a URI referencing an XML element, the 736 entity tag of that element, its attributes, and all of its enclosed 737 children and their attributes is updated. For a PUT or DELETE request 738 for an XML element, the entity tag of all elements which are 739 ancestors of that element are updated. However, the entity tags of 740 attributes belonging to elements that are ancestors of the modified 741 element do not have their entity tags changed, because those 742 resources have not actually changed. 744 When a PUT request is made to a URI referencing an XML attribute, the 745 entity of that attribute is updated. For a PUT or DELETE request for 746 an attribute, the entity tags for its element, and all elements that 747 are ancestors of that element are updated. 749 8. Examples 751 This section goes through several examples, making use of the 752 resource-lists [17] XCAP application usage. 754 First, a user Bill creates a new resource-list, initially with no 755 users in it: 757 PUT 758 http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1 759 Content-Type:application/presence-lists+xml 761 762 763 764 765 767 Next, Bill adds an entry to the list: 769 PUT 770 http://xcap.example.com/services/presence-lists/users/bill/fr.xml? 771 resource-lists/list[@name="friends"]/entry HTTP/1.1 772 Content-Type:text/plain 774 775 Bob Jones 776 778 Next, Bill fetches the list: 780 GET 781 http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1 783 And the result is: 785 HTTP/1.1 200 OK 786 Etag: "wwhha" 787 Content-Type: application/xml 789 790 791 793 794 Bob Jones 795 796 797 799 Next, Bill adds another entry to the list, which is another list that 800 has three entries: 802 PUT 803 http://xcap.example.com/services/presence-lists/users/bill/fr.xml? 804 presence-lists/list[@name="friends"]/list[@name="close-friends"] HTTP/1.1 805 Content-Type:text/plain 807 809 810 Joe Smith 811 812 813 Nancy Gross 814 815 816 Petri Aukia 817 818 820 Then, Bill decides he doesnt want Petri on the list, so he deletes 821 the entry: 823 DELETE 824 http://xcap.example.com/services/presence-lists/users/bill/fr.xml? 825 presence-lists/list/list/entry[@name="Petri"] HTTP/1.1 827 Bill decides to check on the URI for Nancy: 829 GET 830 http://xcap.example.com/services/presence-lists/users/bill/fr.xml? 831 presence-lists/list/list/entry[@name="Nancy"]/@uri HTTP/1.1 833 and the server responds: 835 HTTP/1.1 200 OK 836 Etag: "ad88" 837 Content-Type:text/plain 839 uri="sip:nancy@example.com" 841 9. Security Considerations 843 Frequently, the data manipulated by XCAP contains sensitive 844 information. To avoid eavesdroppers from seeing this information, it 845 is RECOMMENDED that an admistrator hand out an https URI as the XCAP 846 root services URI. This will result in TLS-encrypted communications 847 between the client and server, preventing any eavesdropping. 849 Client and server authentication are also important. A client needs 850 to be sure it is talking to the server it believes it is contacting. 851 Otherwise, it may be given false information, which can lead to 852 denial of service attacks against a client. To prevent this, a client 853 SHOULD attempt to upgrade [10] any connections to TLS. Similarly, 854 authorization of read and write operations against the data is 855 important, and this requires client authentication. As a result, a 856 server SHOULD challenge a client using HTTP Digest [6] to establish 857 its identity, and this SHOULD be done over a TLS connection. 859 10. IANA Considerations 861 This specification instructs IANA to create a new registry for XCAP 862 application usage IDs (AUIDs). 864 XCAP AUIDs are registered by the IANA when they are published in 865 standards track RFCs. The IANA Considerations section of the RFC 866 must include the following information, which appears in the IANA 867 registry along with the RFC number of the publication. 869 Name of the AUID. The name MAY be of any length, but SHOULD be no 870 more than twenty characters long. The name MUST consist of 871 alphanum [11] characters only. 873 Descriptive text that describes the application usage. 875 Normative References 877 [1] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML 878 Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502, 879 May 2001. 881 [2] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., 882 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- 883 HTTP/1.1", RFC 2616, June 1999. 885 [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement 886 Levels", BCP 14, RFC 2119, March 1997. 888 [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC 889 3023, January 2001. 891 [5] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 892 1.0", W3C REC REC-xpath-19991116, November 1999. 894 [6] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 895 Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication: 896 Basic and Digest Access Authentication", RFC 2617, June 1999. 898 [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax 899 Specifications: ABNF", RFC 2234, November 1997. 901 [8] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 902 Resource Identifiers (URI): Generic Syntax", RFC 2396, August 903 1998. 905 [9] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 907 [10] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", 908 RFC 2817, May 2000. 910 [11] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 911 Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP: 912 Session Initiation Protocol", RFC 3261, June 2002. 914 Informative References 916 [12] Rosenberg, J., "A Presence Event Package for the Session 917 Initiation Protocol (SIP)", draft-ietf-simple-presence-10 (work 918 in progress), January 2003. 920 [13] Rosenberg, J., "A Watcher Information Event Template-Package 921 for the Session Initiation Protocol (SIP)", 922 draft-ietf-simple-winfo-package-05 (work in progress), January 923 2003. 925 [14] Rosenberg, J., "An Extensible Markup Language (XML) Based 926 Format for Watcher Information", 927 draft-ietf-simple-winfo-format-04 (work in progress), January 928 2003. 930 [15] Roach, A., Rosenberg, J. and B. Campbell, "A Session Initiation 931 Protocol (SIP) Event Notification Extension for Resource 932 Lists", draft-ietf-simple-event-list-04 (work in progress), 933 June 2003. 935 [16] Rosenberg, J. and M. Isomaki, "Requirements for Manipulation of 936 Data Elements in Session Initiation Protocol (SIP) for Instant 937 Messaging and Presence Leveraging Extensions (SIMPLE) Systems", 938 draft-ietf-simple-data-req-03 (work in progress), June 2003. 940 [17] Rosenberg, J., "An Extensible Markup Language (XML) 941 Configuration Access Protocol (XCAP) Usage for Presence 942 Lists", draft-ietf-simple-xcap-list-usage-00 (work in 943 progress), June 2003. 945 [18] Newman, C. and J. Myers, "ACAP -- Application Configuration 946 Access Protocol", RFC 2244, November 1997. 948 [19] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA 949 Considerations Section in RFCs", BCP 26, RFC 2434, October 950 1998. 952 [20] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 953 Notification", RFC 3265, June 2002. 955 Author's Address 957 Jonathan Rosenberg 958 dynamicsoft 959 600 Lanidex Plaza 960 Parsippany, NJ 07054 961 US 963 Phone: +1 973 952-5000 964 EMail: jdrosen@dynamicsoft.com 965 URI: http://www.jdrosen.net 967 Intellectual Property Statement 969 The IETF takes no position regarding the validity or scope of any 970 intellectual property or other rights that might be claimed to 971 pertain to the implementation or use of the technology described in 972 this document or the extent to which any license under such rights 973 might or might not be available; neither does it represent that it 974 has made any effort to identify any such rights. Information on the 975 IETF's procedures with respect to rights in standards-track and 976 standards-related documentation can be found in BCP-11. Copies of 977 claims of rights made available for publication and any assurances of 978 licenses to be made available, or the result of an attempt made to 979 obtain a general license or permission for the use of such 980 proprietary rights by implementors or users of this specification can 981 be obtained from the IETF Secretariat. 983 The IETF invites any interested party to bring to its attention any 984 copyrights, patents or patent applications, or other proprietary 985 rights which may cover technology that may be required to practice 986 this standard. Please address the information to the IETF Executive 987 Director. 989 Full Copyright Statement 991 Copyright (C) The Internet Society (2003). All Rights Reserved. 993 This document and translations of it may be copied and furnished to 994 others, and derivative works that comment on or otherwise explain it 995 or assist in its implementation may be prepared, copied, published 996 and distributed, in whole or in part, without restriction of any 997 kind, provided that the above copyright notice and this paragraph are 998 included on all such copies and derivative works. However, this 999 document itself may not be modified in any way, such as by removing 1000 the copyright notice or references to the Internet Society or other 1001 Internet organizations, except as needed for the purpose of 1002 developing Internet standards in which case the procedures for 1003 copyrights defined in the Internet Standards process must be 1004 followed, or as required to translate it into languages other than 1005 English. 1007 The limited permissions granted above are perpetual and will not be 1008 revoked by the Internet Society or its successors or assignees. 1010 This document and the information contained herein is provided on an 1011 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1012 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1013 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1014 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1015 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1017 Acknowledgement 1019 Funding for the RFC Editor function is currently provided by the 1020 Internet Society.