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.