idnits 2.17.1
draft-rosenberg-simple-xcap-00.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 3 instances of too long lines in the document, the longest one
being 5 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 (May 26, 2003) is 7641 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)
-- 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 2818 (ref. '7') (Obsoleted by RFC 9110)
== Outdated reference: A later version (-07) exists of
draft-ietf-simple-event-list-03
== Outdated reference: A later version (-03) exists of
draft-ietf-simple-data-req-02
-- Obsolete informational reference (is this intentional?): RFC 2434 (ref.
'16') (Obsoleted by RFC 5226)
Summary: 6 errors (**), 0 flaws (~~), 5 warnings (==), 5 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 SIMPLE J. Rosenberg
3 Internet-Draft dynamicsoft
4 Expires: November 24, 2003 May 26, 2003
6 The Extensible Markup Language (XML) Configuration Access Protocol
7 (XCAP)
8 draft-rosenberg-simple-xcap-00
10 Status of this Memo
12 This document is an Internet-Draft and is in full conformance with
13 all provisions of Section 10 of RFC2026.
15 Internet-Drafts are working documents of the Internet Engineering
16 Task Force (IETF), its areas, and its working groups. Note that other
17 groups may also distribute working documents as Internet-Drafts.
19 Internet-Drafts are draft documents valid for a maximum of six months
20 and may be updated, replaced, or obsoleted by other documents at any
21 time. It is inappropriate to use Internet-Drafts as reference
22 material or to cite them other than as "work in progress."
24 The list of current Internet-Drafts can be accessed at http://
25 www.ietf.org/ietf/1id-abstracts.txt.
27 The list of Internet-Draft Shadow Directories can be accessed at
28 http://www.ietf.org/shadow.html.
30 This Internet-Draft will expire on November 24, 2003.
32 Copyright Notice
34 Copyright (C) The Internet Society (2003). All Rights Reserved.
36 Abstract
38 This specification defines the Extensible Markup Language (XML)
39 Configuration Access Protocol (XCAP). XCAP allows a client to read,
40 write and modify application configuration data, stored in XML format
41 on a server. XCAP is not a new protocol. XCAP maps XML document
42 sub-trees and element attributes to HTTP URIs, so that these
43 components can be directly accessed by HTTP.
45 Table of Contents
47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
48 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4
49 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5
50 4. Application Usages . . . . . . . . . . . . . . . . . . . . . 6
51 5. URI Construction . . . . . . . . . . . . . . . . . . . . . . 8
52 5.1 Identifying the XML Document . . . . . . . . . . . . . . . . 8
53 5.2 Identifying the XML Nodes . . . . . . . . . . . . . . . . . 9
54 6. Client Operations . . . . . . . . . . . . . . . . . . . . . 10
55 6.1 Creating a New Document . . . . . . . . . . . . . . . . . . 10
56 6.2 Replace an Existing Document . . . . . . . . . . . . . . . . 10
57 6.3 Deleting a Document . . . . . . . . . . . . . . . . . . . . 10
58 6.4 Fetching a Document . . . . . . . . . . . . . . . . . . . . 10
59 6.5 Creating a New Element . . . . . . . . . . . . . . . . . . . 10
60 6.6 Replacing an Element in the Document . . . . . . . . . . . . 11
61 6.7 Delete an Element . . . . . . . . . . . . . . . . . . . . . 12
62 6.8 Fetch an Element . . . . . . . . . . . . . . . . . . . . . . 12
63 6.9 Create an Attribute . . . . . . . . . . . . . . . . . . . . 12
64 6.10 Replacing Attributes . . . . . . . . . . . . . . . . . . . . 13
65 6.11 Deleting Attributes . . . . . . . . . . . . . . . . . . . . 13
66 6.12 Fetching Attributes . . . . . . . . . . . . . . . . . . . . 13
67 6.13 Fetching Metadata . . . . . . . . . . . . . . . . . . . . . 13
68 6.14 Read/Modify/Write Transactions . . . . . . . . . . . . . . . 14
69 7. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 15
70 7.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . . 16
71 7.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . . 17
72 7.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . . 18
73 7.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . . 18
74 7.5 Managing Modification Times . . . . . . . . . . . . . . . . 19
75 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 21
76 9. Security Considerations . . . . . . . . . . . . . . . . . . 23
77 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24
78 Normative References . . . . . . . . . . . . . . . . . . . . 25
79 Informative References . . . . . . . . . . . . . . . . . . . 26
80 Author's Address . . . . . . . . . . . . . . . . . . . . . . 27
81 Intellectual Property and Copyright Statements . . . . . . . 28
83 1. Introduction
85 The Session Initiation Protocol for Instant Messaging and Presence
86 Leveraging Extensions (SIMPLE) working group has been developing
87 specifications for subscribing to, and receiving notifications of,
88 user presence [10]. An important aspect of user presence is
89 authorization policy. Indeed, the presence specification requires a
90 Presence Agent (PA) to both authenticate and authorize all
91 subscriptions before accepting them. However, it does not define how
92 the server determines the authorization status of a subscriber. Users
93 can set their authorization policy through web pages or voice
94 response systems. However, there is currently no protocol specified
95 for setting this policy. A protocol for this purpose is called an
96 authorization manipulation protocol.
98 Mechanisms have also been defined to support reactive authorization
99 [11][12]. Reactive authorization allows the user to be informed when
100 someone has attempted to subscribe to their presence when the server
101 is unable to determine an authorization policy. The user can then go
102 and set an authorization policy for the subscriber, using the same
103 unspecified mechanism for setting the policy.
105 Another important aspect of presence systems is the buddy list, also
106 known as the presence list. This is a list of users that a watcher
107 wishes to learn presence state for. This list can be stored in the
108 client, or it can be stored in a centralized server. In the latter
109 case, the client would subscribe to the list as a whole [13]. The
110 presence list can be set by using a web page or voice response
111 application. However, there is no protocol mechanism currently
112 specified to manage the presence list. Such a protocol is called a
113 presence list manipulation protocol.
115 The SIMPLE group has defined requirements for an authorization
116 manipulation protocol and a presence list manipulation protocol.
117 These protocols have similar requirements, and are captured in [14].
119 This document proposes a candidate for the authorization and presence
120 manipulation protocol, called the Extensible Markup Language (XML)
121 Configuration Access Protocol (XCAP). XCAP is not actually a new
122 protocol. XCAP is a set of conventions for using HTTP to read, write
123 and modify XML configuration data. XCAP is based heavily on ideas
124 borrowed from the Application Configuration Access Protocol (ACAP)
125 [15], but it is not an extension of it, nor does it have any
126 dependencies on it. Like ACAP, XCAP is meant to support the
127 configuration needs for a multiplicity of applications, rather than
128 just a single one.
130 2. Overview of Operation
132 XCAP supports the needs of any application that needs access to data
133 defined by clients of the application. Each application that makes
134 use of XCAP specifies an application usage (Section 4). This
135 application usage defines the XML schema [1] for the data used by the
136 application, along with other key pieces of information. The
137 principal task of XCAP is to allow clients to read, write, modify,
138 create and delete pieces of that data. These operations are supported
139 using HTTP 1.1 [2]. An XCAP server acts as a repository for
140 collections of XML documents. There will be documents stored for each
141 application. Within each application, there are documents stored for
142 each user. Each user can have a multiplicity of documents for a
143 particular application. To access some component of one of those
144 documents, XCAP defines an algorithm for constructing a URI that can
145 be used to reference that component. Components refer to any subtree
146 of the document, or any attribute for any element within the
147 document. Thus, the HTTP URIs used by XCAP point to pieces of
148 information that are finer grained than the XML document itself.
150 With a standardized naming convention for components of XML
151 documents, the basic operations for accessing the data are simple.
152 Reading one of the components is just a standard HTTP GET operation.
153 Writing, creating or modifying one of the components is a standard
154 HTTP POST or PUT operation. Deleting a component is just a standard
155 DELETE operation. For example, to add a friend to a presence list, a
156 client would construct an XML document fragment which contains the
157 information on that friend. The client would then construct a URI
158 that refers to the location in the presence list document where this
159 new fragment is to be added. The client then performs a POST
160 operation against the URI, placing the document fragment into the
161 body of the POST request. To provide atomic read/modify/write
162 operations, the HTTP If-Unmodified-Since header field is used. The
163 HTTP POST operation used by the client would contain the date
164 obtained in the Last-Modified header field from the GET used to read
165 the data.
167 3. Terminology
169 In this document, the key words "MUST", "MUST NOT", "REQUIRED",
170 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
171 and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and
172 indicate requirement levels for compliant implementations.
174 4. Application Usages
176 A central concept in XCAP is that of an application usage. An
177 application usage defines the way in which a specific application
178 makes use of XCAP. This definition is composed of several pieces of
179 information, such as an XML schema and constraints on values of one
180 element given values in another.
182 Application usages are documented in specifications which convey this
183 information. In particular, an application usage specification MUST
184 provide the following information:
186 Application Usage ID (AUID): Each application usage is associated
187 with a name, called an AUID. This name uniquely identifies the
188 application usage, and is different from all other AUIDs. AUIDs
189 exist in one of two namespaces. The first namespace is the IETF
190 namespace. This namespace contains a set of tokens, each of which
191 is registered with IANA. These registrations occur with the
192 publication of standards track RFCs [16] based on the guidelines
193 in Section 10. The second namespace is the vendor-proprietary
194 namespace. Each AUID in that namespace is prefixed with the token
195 "vnd", followed by a period ("."), followed by a valid DNS name,
196 followed by another period, followed by any vendor defined token.
197 A vendor creating such an AUID MUST only create one using domain
198 names for which it is an administrator. As an example, the
199 example.com domain can create an AUID with the value
200 "vnd.example.com.foo" but cannot create one with the value
201 "vnd.example.org.bar". AUIDs within the vendor namespace do not
202 need to be registered with IANA. The vendor namespace is also
203 meant to be used in lab environments where no central registry is
204 needed.
206 MIME Type: Each application usage MUST register a MIME type for
207 its XML documents. This is done based on the procedures of RFC
208 3023 [4].
210 XML Schema: Each application will have a unique schema which
211 defines the data needed by the application. In XCAP, this schema
212 is represented using XML schema. As an example, presence list data
213 is composed of a list of URIs, each of which represends a member
214 of presence list. [17] defines the XML schema for this data.
216 Additional Constraints: XML schemas can represent a variety of
217 constraints about data, such as ranges and types. However, schemas
218 cannot cover all types of data constraints, including constraints
219 introduced by data interdependencies. For example, one XML element
220 may contain an integer which defines the maximum number of
221 instances of another element. The application usage defines these
222 additional constraints.
224 Data Semantics: The application usage needs to define detailed
225 semantics for each piece of data in the schema.
227 Naming Conventions: The data defined by the XML schema will be
228 used by any number of entities participating in the application.
229 In the case of presence list, the data is used by the Resource
230 List Server (RLS), which reads the data, and by the clients, which
231 write it. During the execution of the application (i.e., the
232 processing of the list subscription), specific documents will need
233 to be read or written. In order for the application to function
234 properly, there needs to be agreement on exactly which documents
235 are read or written by the application. This is an issue of naming
236 conventions; agreeing on how an application constructs the URI
237 representing the document that is to be read or written. The
238 application usage spells out this information.
240 Computed Data: Frequently, some of the data defined in the schema
241 is not independent; that is, its value depends on the values of
242 other elements in the document. As a result, when a client uses
243 XCAP to modify the independent pieces of the document, the server
244 needs to compute the dependent ones in order to fully populate the
245 document. The application usage needs to define which data
246 components are dependent, and how they are computed. As an
247 example, when the URI for a presence list is not specified by a
248 client, a URI is chosen by the server and filled in. This needs to
249 be specified by the application usage.
251 Authorization Policies: By default, an XCAP server will only allow
252 a user to access (read, write, delete or modify) their own
253 documents. The application usage can specify differing default
254 authorization policies. Of course, the default can always be
255 overriden by operator or user-specified policies.
257 Application usages are similar to dataset classes in ACAP.
259 5. URI Construction
261 In order to manipulate a piece of configuration data, the data must
262 be represented by an HTTP URI. XCAP defines a specific naming
263 convention for constructing these URIs. This convention is very
264 similar to the naming conventions used for dataset classes in ACAP,
265 and makes use the XPath [5] specification for identifying nodes of an
266 XML document.
268 The HTTP URI consists of two parts:
270 XCAP-URI = Document-URI ["?" Node-Selector]
271 Document-URI = http_URL ;from RFC2616
272 Node-Selector = *uric ;Escape coded LocationPath from XPath
274 The first part, the Document-URI, selects a specific XML document. It
275 is a valid HTTP URL, subject to the constraints described here. The
276 constraints for constructing this URI are discussed below in Section
277 5.1. Once a document is selected, the remainder of the URI (the
278 Node-Selector) identifies which components of the document are being
279 addressed. The Node-Selector is an XPath [5] LocationPath expression,
280 subject to constraints described below.
282 5.1 Identifying the XML Document
284 XCAP mandates that a server organizes documents according to a
285 defined hierarchy. The root of this hierarchy is an HTTP URI called
286 the XCAP services root URI. This URI identifies the root of the tree
287 within the domain where all XCAP documents are stored. It can be any
288 valid HTTP URL, but MUST NOT contain a query string. As an example,
289 http://xcap.example.com/services might be used as the XCAP services
290 root URI within the example.com domain. Typically, the XCAP services
291 root URI is provisioned into client devices for bootstrapping
292 purposes.
294 Beneath the XCAP services root URI is a tree structure for organizing
295 documents. The first level of this tree consists of the XCAP AUID.
296 So, continuing the example above, all of the documents used by the
297 presence list application would be under http://xcap.example.com/
298 services/presence-lists.
300 It is assumed that each application will have data that is set by
301 users, and/or it will have global data that applies to all users. As
302 a result, within the directory structure for each application usage,
303 there are two sub-trees. One, called "users", holds the documents
304 that are applicable to only specific users, and the other, called
305 "global", holds documents applicable to all users.
307 Within the "users" tree are zero or more sub-trees, each of which
308 identifies a documents that apply to a specific user. XCAP does not
309 itself define what it means for documents to "apply" to a user,
310 beyond specification of a baseline authorization policy.
311 Specifically, the default authorization policy is that only a user
312 who authenticates themself as user X can read, write, or otherwise
313 access in any way the documents within sub-tree X. Each application
314 usage can specify additional authorization policies which depend on
315 data used by the application itself.
317 The remainder of the URI (the path following "global" or the specific
318 user) is not constrained by this specification. The application usage
319 MAY introduce constraints, or may allow any structure to be used.
321 5.2 Identifying the XML Nodes
323 The second component of the XCAP URI specifies specific nodes of the
324 XML document which are to be accessed. Nodes, in this context, refers
325 to the definition provided in the XPath specification, and therefore
326 includes XML elements, attributes, text, namespaces, processing
327 instructions, comments, and roots. These nodes are identified by a
328 LocationPath expression, as defined in XPath. Either the abbreviated
329 or unabbreviated form MAY be used.
331 Contraints are imposed on the XPath expression based on the operation
332 being performed. These do not constrain the functions or axes that
333 can be used in the XPath expression, but rather constrain the
334 resulting node set. See Section 6 for details.
336 6. Client Operations
338 An XCAP client is an HTTP 1.1 compliant client. An XCAP client
339 performs a set of primitive operations by invoking specific methods
340 against the server, using specific URIs, where the requests contain
341 bodies and headers subject to specific constraints. The set of
342 primitive operations, the methods used to accomplish them, and the
343 header and body constraints are described here.
345 6.1 Creating a New Document
347 To create a new document, the client constructs a URI that references
348 the location where the document is to be placed. This URI MUST NOT
349 contain a NodeSelector component, and MUST meet the constraints
350 described in Section 5.1. The client then invokes a PUT method on
351 that URI.
353 The content in the request MUST be an XML document compliant to the
354 schema associated with the application usage defined by the URI. For
355 example, if the client performs a PUT operation to http://
356 xcap.example.com/services/presence-lists/users/joe/mybuddies,
357 presence-lists is the application unique ID, and the schema defined
358 by it would dictate the body of the request.
360 6.2 Replace an Existing Document
362 To replace an existing document with a new one, the procedures of
363 Section 6.1 are followed; the Request-URI merely refers to an
364 existing document which is to be replaced with the content of the
365 request.
367 6.3 Deleting a Document
369 To delete a document, the client constructs a URI that references the
370 document to be deleted. By definition this URI will not contain a
371 NodeSelector component. The client then invokes a DELETE operation on
372 the URI to delete the document.
374 6.4 Fetching a Document
376 As one would expect, fetching a document is trivially accomplished by
377 performing an HTTP GET request with the Request URI set to the
378 document to be fetched. It is useful for clients to perform
379 conditional GETs using the If-Modified-Since header field, in order
380 to check if a locally cached copy of the document is still valid.
382 6.5 Creating a New Element
383 To create a new XML element within an existing document, the client
384 constructs a URI whose Document-URI points to the document to be
385 modified. The Node-Selector MUST be present, containing an expression
386 identifying the point in the document where the new element is to be
387 added. The node-set selected by the expression MUST contain only a
388 single XML element.
390 The client then invokes the HTTP POST method. The content in the
391 request MUST be an XML document. That XML document MUST be conformant
392 to the schema associated with the application usage defined by the
393 URI. The server will insert the document such that the first element
394 of the document becomes the next sibling immediately following the
395 element specified by the Request-URI. The client SHOULD be certain,
396 before making the request, that the resulting modified document will
397 also be conformant to the schema.
399 6.6 Replacing an Element in the Document
401 Replacing an element of the document constitutes storage of a
402 supplied entity under the specified URI, and is therefore
403 accomplished with the PUT method (as opposed to POST, which will
404 insert). The client constructs a URI whose Document-URI points to the
405 document to be modified. The Node-Selector MUST be present,
406 containing an expression identifying the element whose value is to be
407 replaced. The node-set selected by the expression MUST contain only a
408 single XML element.
410 The client then invokes the PUT method. The entity of the request
411 MUST be of type text/plain. The server will take the value of the
412 element specified by the request URI, and replace it with the content
413 of the PUT request. Here, value refers to the binary contents of an
414 XML document, starting with the beginning tag of the element, and
415 ending with the end tag. This differs from the "string value" defined
416 in XPath, which refers only to the values of the text element
417 descendants of an element. The client SHOULD be certain, before
418 making the request, that the resulting modified document will be
419 conformant to the schema.
421 The body of the request here is of type text/plain because the value
422 of an element need not be a valid XML document; frequently, it will
423 be text or CDATA. Of course, the value of an XML element may be other
424 XML elements, in which case the body of the request will be an XML
425 document fragment, and by itself not compliant to any schema.
427 Note that this operation only modifies the value of an element. It
428 cannot modify the attributes of the element. To do that, the replace
429 attribute operation is performed.
431 6.7 Delete an Element
433 To delete elements from a document, the client constructs a URI whose
434 Document-URI points to the document containing the elements to be
435 deleted. The Node-Selector MUST be present, containing an expression
436 identifying the elements to be deleted. Unlike most of the other
437 operations, the node-set selected by the expression MAY contain
438 multiple elements.
440 The client then invokes the HTTP DELETE method. All of the elements
441 specified by the node set will be deleted by the server. The body of
442 the request SHOULD be empty. The client SHOULD be certain, before
443 making the request, that the resulting modified document will also be
444 conformant to the schema.
446 6.8 Fetch an Element
448 To fetch an element of a document, the client constructs a URI whose
449 Document-URI points to the document containing the element to be
450 fetched. The Node-Selector MUST be present, containing an expression
451 identifying the element whose value is to be fetched. The node-set
452 selected by the expression MUST contain only a single XML element.
454 The client then invokes the GET method. The response will contain an
455 XML document with the specified element as the one and only child of
456 the document root.
458 OPEN ISSUE: This only allows you to get one element at a time. We
459 could allow the XPath expression to specify multiple elements, and
460 then the response contains a document with each of those elements
461 as a child of the document root. However, that document might not
462 be compliant to the schema, and worse, the document doesnt
463 actually reflect any specific sub-tree of the actual document.
465 6.9 Create an Attribute
467 To create an attribute in an existing element of a document, the
468 client constructs a URI whose Document-URI points to the document to
469 be modified. The Node-Selector MUST be present, containing an
470 expression identifying an attribute that is to created. Specifically,
471 the last location step of the expression MUST specify an attribute
472 axis, and the context MUST specify a single element that exists
473 within the document.
475 The client then invokes the HTTP POST method. The content defined by
476 the request MUST be of type text/plain. A new attribute is added to
477 the element defined by the context, with the name specified by the
478 node test in the last location step, with a value specified by the
479 body of the request. If an attribute of this name already exists, it
480 is replaced. The client SHOULD be certain, before making the request,
481 that the resulting modified document will also be conformant to the
482 schema.
484 6.10 Replacing Attributes
486 To replace an attribute in an existing element of a document, the
487 client constructs a URI whose Document-URI points to the document to
488 be modified. The Node-Selector MUST be present, containing an
489 expression identifying an attribute that is to be replaced.
491 The client then invokes the HTTP PUT method. The content defined by
492 the request MUST be of type text/plain. The value of the attribute
493 defined by the Node-Selector is replaced by the body of the request.
494 The client SHOULD be certain, before making the request, that the
495 resulting modified document will also be conformant to the schema.
497 6.11 Deleting Attributes
499 To delete attributes from the document, the client constructs a URI
500 whose Document-URI points to the document containing the attributes
501 to be deleted. The Node-Selector MUST be present, containing an
502 expression identifying the attributes to be deleted. Unlike most of
503 the other operations, the node-set selected by the expression MAY
504 contain multiple attributes.
506 The client then invokes the HTTP DELETE method. All of the attributes
507 specified by the node set will be deleted by the server. The body of
508 the request SHOULD be empty. The client SHOULD be certain, before
509 making the request, that the resulting modified document will also be
510 conformant to the schema.
512 6.12 Fetching Attributes
514 To fetch an attribute of a document, the client constructs a URI
515 whose Document-URI points to the document containing the attribute to
516 be fetched. The Node-Selector MUST be present, containing an
517 expression identifying the attribute whose value is to be fetched.
518 The node-set selected by the expression MUST contain only a single
519 XML attribute.
521 The client then invokes the GET method. The response will contain an
522 text/plain document with the value of the specified attribute.
524 6.13 Fetching Metadata
525 Elements and attributes in an XML document have various meta-data
526 associated with them. For example, and XML element has a certain
527 number of child elements. That number is a piece of meta-data that
528 describes the element. Currently, there is no way to fetch meta-data
529 for XML elements or attributes.
531 OPEN ISSUE: Is this restriction OK? XPath does specify functions
532 for computing meta-data about node sets. We can't use them since
533 XCAP mandates that the request URI be a location set, which does
534 not include these other functions. We could relax the constraint
535 if this is deemed important.
537 6.14 Read/Modify/Write Transactions
539 It is anticipated that a common operation will be to read the current
540 version of a document or element, modify it on the client, and then
541 write the change back to the server. In order for the results to be
542 consistent with the client's expectations, the operation must be
543 atomic.
545 To accomplish this, the client stores the value of the Last-Modified
546 header field from the response to its GET operation used to read the
547 element, attribute, or document that is to be modified. To guarantee
548 atomicity, the PUT or POST operation used to write the changes back
549 to the server MUST contain an If-Unmodified-Since header field, whose
550 value is equal to the value from the prior GET response. If the
551 request fails with a 412 response, the client knows that another
552 update of the data has occurred before it was able to write the
553 results back. The client can then fetch the most recent version, and
554 attempt its modification again.
556 7. Server Behavior
558 TODO: Specify an XML body type for the responses that contains
559 error conditions or success results.
561 An XCAP server is an HTTP 1.1 compliant origin server. The behaviors
562 mandated by this specification relate to the way in which the HTTP
563 URI is interpreted and the content is constructed.
565 An XCAP server MUST be explicitly aware of the application usage
566 against which requests are being made. That is, the server must be
567 explicitly configured to handle URIs for each specific application
568 usage, and must be aware of the constraints imposed by that
569 application usage.
571 OPEN ISSUE: It may be possible to remove this restriction by
572 allowing an application usage to define operation in a server that
573 doesnt understand the usage. That may require some capabilities
574 discovery to be introduced, this constraint didnt seem that
575 problematic.
577 When the server receives a request, the treatment depends on the URI.
578 If the URI refers to an application usage not understood by the
579 server, the server MUST reject the request with a 404 (Not Found)
580 response. If the URI refers to a user that is not recognized by the
581 server, it MUST reject the request with a 404 (Not Found).
583 Next, the server authenticates the request. All XCAP servers MUST
584 support HTTP Digest [6]. Furthermore, servers MUST support HTTP over
585 TLS, RFC 2818 [7]. It is RECOMMENDED that administrators use an HTTPS
586 URI as the XCAP root services URI, so that the digest client
587 authentication occurs over TLS.
589 Next, the server determines if the client has authorization to
590 perform the requested operation on the resource. The default
591 authorization policy is that only client X can access (create, read,
592 write, modify or delete) resources under the "users/X" directory. An
593 application usage can specify an alternate default authorization
594 policy specific to that usage. Of course, an administrator or
595 privileged user can override the default authorization policy,
596 although this specification provides no means for doing that.
597 Generally, if users need to be able to control authorization for
598 access to XCAP data, an XCAP application usage should be specified
599 which allows the user to set the policies as needed.
601 OPEN ISSUE: This is different from ACAP, where authorization
602 policies are built into the protocol. I think the default
603 generally will suffice, so I would rather not burden the baseline
604 protocol with it.
606 Once authorized, the specific behavior depends on the method and what
607 the URI refers to.
609 7.1 POST Handling
611 If the URI contains only a Document-URI, the server examines the
612 entity body of the request. If there is no entity in the body, the
613 server MUST reject the request with a 409 response. If there is an
614 entity, but it is not well-formed, the server MUST reject the request
615 with a 409 response. If it is well-formed, but not compliant to the
616 schema associated with the application usage, the server MUST reject
617 the request with a 409 response. If it is compliant to the schema,
618 the server MUST store the document at the requested URI. If there is
619 not already a document stored at that URI, a 201 (Created) response
620 code MUST be sent, and it MUST include a Location header field
621 containing the value of the URI for the document (which will be the
622 same as the one in the Request-URI). Otherwise, a 200 OK response is
623 returned, and the document in the body replaces the existing one at
624 that URI. For either a 200 or 201 response, the new document is
625 returned in the body of the response, with a Content-Type equal to
626 the MIME type defined by the application usage.
628 If the Request URI contains a Node-Selector, the server MUST verify
629 that the document defined by the Document-URI exists. If no such
630 document exists on the server, the server MUST reject the request
631 with a 409 response code. If the document does exist, the server
632 evaluates the Node-Selector as an XPath RelativeLocationPath,
633 relative to the root of the document. If the Node-Selector does not
634 comply to the grammar for RelativeLocationPath, the server MUST
635 reject the request with a 400 response code. If the Node-Selector
636 does comply, and it evaluates to anything other than the empty set, a
637 single attribute node or single element node, the server MUST reject
638 the request with a 409 response code.
640 If the Node-Selector evaluates to the empty set, and the last
641 location step is on the attribute axis, and the expression without
642 the last location step evaluates to a single element node, the server
643 adds an attribute to that element. Its name is the name given in the
644 node test of the last location step, and its value is taken from the
645 body of the request. The server then generates a 200 OK response,
646 whose body contains the value of the attribute, with a Content-Type
647 of text/plain.
649 If the Node-Selector evaluates to a single element node, the server
650 takes the content of the request, and inserts it into the document
651 specified by the URI such that the selected element is the immediate
652 sibling of the nodes defined by the content of the request. The
653 server then generates a 200 OK response, whose body contains the
654 parent element of the new elements just inserted. The parent element
655 is represented by extracting the contents of the XML document,
656 starting with, and including, the begin tag of the element, up to,
657 and including, the end tag for the element. The Content-Type of the
658 response is set to application/xml.
660 OPEN ISSUE: We can't use the MIME type for the application usage,
661 since the schema may not allow for the document to start with any
662 element defined by the schema. Is that OK? I think so.
664 If the Node-Selector evaluates to a single attribute node, the server
665 takes the content of the request, and sets it as the value of the
666 attribute specified by the body of the request. The server then
667 generates a 200 OK response, whose body contains the value of the
668 attribute, with a Content-Type of text/plain.
670 If the result of the POST is a document which does not comply with
671 the XML schema for the application usage, the server MUST NOT perform
672 the POST, and MUST reject the request with a 409 (Conflict).
674 7.2 PUT Handling
676 When the Request URI contains only the Document-URI, the semantics of
677 PUT are as defined in HTTP 1.1 Section 9.6 - the content of the
678 request is placed at the specified location.
680 If the Request URI contains a Node-Selector, the server MUST verify
681 that the document defined by the Document-URI exists. If no such
682 document exists on the server, the server MUST reject the request
683 with a 409 response code. If the document does exist, the server
684 evaluates the Node-Selector as an XPath RelativeLocationPath,
685 relative to the root of the document. If the Node-Selector does not
686 comply to the grammar for RelativeLocationPath, the server MUST
687 reject the request with a 400 response code. If the Node-Selector
688 does comply, and it evaluates to anything other than the a single
689 element node or attribute node, the server MUST reject the request
690 with a 409 response code.
692 If the Node-Selector evaluates to a single element node, the server
693 takes the content of the request, and replaces the value of that
694 element (where value is defined as all of the content - elements,
695 text, or CDATA - between the begin and end tags of the element) with
696 that content. The server then returns a 200 OK response.
698 OPEN ISSUE: PUT is not quite right here, since a subsequent GET on
699 the same URI will not return exactly the same thing - the begin
700 and end tags will be present. This may need to be POST, but then,
701 how to differentiate a replace with an append operation?
703 If the Node-Selector evaluates to a single attribute node, the server
704 takes the content of the request, and sets it as the value of the
705 attribute. It then returns a 200 OK response.
707 If the result of the PUT is a document which does not comply with the
708 XML schema for the application usage, the server MUST NOT perform the
709 PUT, and MUST reject the request with a 409 (Conflict).
711 7.3 GET Handling
713 If the request URI contains only a Document-URI, the server returns
714 the document specified by the URI if it exists, else returns a 404
715 response.
717 If the request URI specifies a Node-Selector, the server verifies
718 that the document specified by the Document-URI exists. If it does
719 not exist, the server returns a 404 (Not Found) response. If the
720 document does exist, the server evaluates the Node-Selector as an
721 XPath RelativeLocationPath, relative to the root of the document. If
722 the Node-Selector does not comply to the grammar for
723 RelativeLocationPath, the server MUST reject the request with a 400
724 response code. If the Node-Selector does comply, and it evaluates to
725 anything other than the a single element node or attribute node, the
726 server MUST reject the request with a 409 response code.
728 If the Node-Selector evaluates to a single element node, the server
729 takes the document text, starting with, and including, the begin tag
730 of the element, up to, and including, the end tag for the element,
731 and places it into the body of a 200 OK response, setting the
732 Content-Type to application/xml.
734 If the Node-Selector evaluates to a single attribute node, the server
735 takes the value of the attribute and returns it as the content of the
736 200 OK response, setting the Content-Type to text/plain.
738 OPEN ISSUE: Do we need to say anything about HEAD? We havent said
739 anything about meta-data so far; most of that is just regular HTTP
740 usage, I think.
742 7.4 DELETE Handling
744 If the request URI contains only a Document-URI, the server deletes
745 the document specified by the URI if it exists and returns a 200 OK
746 response, else returns a 404 response.
748 If the request URI specifies a Node-Selector, the server verifies
749 that the document specified by the Document-URI exists. If it does
750 not exist, the server returns a 404 (Not Found) response. If the
751 document does exist, the server evaluates the Node-Selector as an
752 XPath RelativeLocationPath, relative to the root of the document. If
753 the Node-Selector does not comply to the grammar for
754 RelativeLocationPath, the server MUST reject the request with a 400
755 response code. If the Node-Selector does comply, and it evaluates to
756 the empty set, the server MUST reject the request with a 404 (Not
757 Found).
759 Otherwise, the server removes all of the data defined by the
760 node-set. Specifically, any elements in the node set are removed from
761 the document, and any attributes in the node set are removed from the
762 document. It then returns a 200 OK response.
764 If the result of the deletion is a document which does not comply
765 with the XML schema for the application usage, the server MUST NOT
766 perform the deletion, and MUST reject the request with a 409
767 (Conflict).
769 7.5 Managing Modification Times
771 An XCAP server MUST maintain modification times for all resources
772 that can be referenced by a URI. Specifically, this means that each
773 document, and within the document, each element and attribute, MUST
774 be associated with a modification time maintained by the server.
775 These modification times are needed to support condition GET, POST
776 and PUT requests.
778 When a PUT or POST request is made that creates or replaces a
779 document, the modification time of that document and all elements and
780 attributes within is set to the current time. When a PUT request is
781 made to a URI referencing an XML element, the modification time of
782 that element and all of its enclosed children and their attributes is
783 set to the current time. Furthermore, the modification time of all
784 elements which are ancestors of that element have their modification
785 time set to the current time. However, the modification times of
786 attributes belong to elements that are ancestors of the modified
787 element do not have their modification times changed.
789 When a POST request is made to a URI referencing an XML element, the
790 modification time of all of the elements and their attributes within
791 the document in the body of the request is set to the current time.
792 Furthermore, the modification time of the element which is the new
793 parent of the elements in the request, and all of its ancestors, have
794 their modification time set to the current time. However, the
795 modification times of their attributes are unchanged.
797 When a POST request is made to a URI referencing an XML attribute,
798 the modification time of that attribute, its element, and all
799 elements that are ancestors of that element is set to the current
800 time.
802 When a DELETE request is made to a URI referencing an element, the
803 modification time of all ancestors of that element is set to the
804 current time. When a DELETE request is made to a URI referencing an
805 attribute, the modification time of its element, and all ancestors of
806 that element, is set to the current time.
808 8. Examples
810 This section goes through several examples, making use of the
811 presence-lists [17] XCAP application usage.
813 First, a user Bill creates a new presence-list, initially with no
814 users in it:
816 PUT
817 http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1
818 Content-Type:application/presence-lists+xml
820
821
822
823
824
826 Next, Bill adds an entry to the list:
828 PUT
829 http://xcap.example.com/services/presence-lists/users/bill/fr.xml?
830 presence-lists/list[@name="friends"] HTTP/1.1
831 Content-Type:text/plain
833
834 Bill Doe
835
837 Note how the URI in the PUT request selects the list element whose
838 name attribute is "friends". The body of that request replaces the
839 existing value of that element, which was empty.
841 Next, Bill adds another entry to the list, which is another list that
842 has three entries:
844 POST
845 http://xcap.example.com/services/presence-lists/users/bill/fr.xml?
846 presence-lists/list[@name="friends"]/entry[@name="Bill"] HTTP/1.1
847 Content-Type:text/plain
849
851
852 Joe Smith
853
854
855 Nancy Gross
856
857
858 Petri Aukia
859
860
862 Then, Bill decides he doesnt want Petri on the list, so he deletes
863 the entry:
865 DELETE
866 http://xcap.example.com/services/presence-lists/users/bill/fr.xml?
867 presence-lists/list/list/entry[@name="Petri"] HTTP/1.1
869 Bill decides to check on the URI for Nancy:
871 GET
872 http://xcap.example.com/services/presence-lists/users/bill/fr.xml?
873 presence-lists/list/list/entry[@name="Nancy"]/@uri HTTP/1.1
875 and the server responds:
877 HTTP/1.1 200 OK
878 Content-Type:text/plain
880 sip:nancy@example.com
882 9. Security Considerations
884 Frequently, the data manipulated by XCAP contains sensitive
885 information. To avoid eavesdroppers from seeing this information,
886 XCAP RECOMMENDS that an admistrator hand out an https URI as the XCAP
887 root services URI. This will result in TLS-encrypted communications
888 between the client and server, preventing any eavesdropping.
890 Client and server authentication are also important. A client needs
891 to be sure it is talking to the server it believes it is contacting.
892 Otherwise, it may be given false information, which can lead to
893 denial of service attacks against a client. To prevent this, a client
894 SHOULD attempt to upgrade [8] any connections to TLS. Similarly,
895 authorization of read and write operations against the data is
896 important, and this requires client authentication. As a result, a
897 server SHOULD challenge a client using HTTP Digest [6] to establish
898 its identity, and this SHOULD be done over a TLS connection.
900 10. IANA Considerations
902 This specification instructs IANA to create a new registry for XCAP
903 application usage IDs (AUIDs).
905 XCAP AUIDs are registered by the IANA when they are published in
906 standards track RFCs. The IANA Considerations section of the RFC
907 must include the following information, which appears in the IANA
908 registry along with the RFC number of the publication.
910 Name of the AUID. The name MAY be of any length, but SHOULD be no
911 more than twenty characters long. The name MUST consist of
912 alphanum [9] characters only.
914 Descriptive text that describes the application usage.
916 Normative References
918 [1] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML
919 Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502,
920 May 2001.
922 [2] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L.,
923 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
924 HTTP/1.1", RFC 2616, June 1999.
926 [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement
927 Levels", BCP 14, RFC 2119, March 1997.
929 [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC
930 3023, January 2001.
932 [5] Clark, J. and S. DeRose, "XML Path Language (XPath) Version
933 1.0", W3C REC REC-xpath-19991116, November 1999.
935 [6] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
936 Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication:
937 Basic and Digest Access Authentication", RFC 2617, June 1999.
939 [7] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
941 [8] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1",
942 RFC 2817, May 2000.
944 [9] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
945 Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
946 Session Initiation Protocol", RFC 3261, June 2002.
948 Informative References
950 [10] Rosenberg, J., "A Presence Event Package for the Session
951 Initiation Protocol (SIP)", draft-ietf-simple-presence-10 (work
952 in progress), January 2003.
954 [11] Rosenberg, J., "A Watcher Information Event Template-Package
955 for the Session Initiation Protocol (SIP)",
956 draft-ietf-simple-winfo-package-05 (work in progress), January
957 2003.
959 [12] Rosenberg, J., "An Extensible Markup Language (XML) Based
960 Format for Watcher Information",
961 draft-ietf-simple-winfo-format-04 (work in progress), January
962 2003.
964 [13] Rosenberg, J., Roach, A. and B. Campbell, "A Session Initiation
965 Protocol (SIP) Event Notification Extension for Resource
966 Lists", draft-ietf-simple-event-list-03 (work in progress), May
967 2003.
969 [14] Rosenberg, J. and M. Isomaki, "Requirements for Manipulation of
970 Data Elements in Session Initiation Protocol (SIP) for Instant
971 Messaging and Presence Leveraging Extensions (SIMPLE) Systems",
972 draft-ietf-simple-data-req-02 (work in progress), April 2003.
974 [15] Newman, C. and J. Myers, "ACAP -- Application Configuration
975 Access Protocol", RFC 2244, November 1997.
977 [16] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
978 Considerations Section in RFCs", BCP 26, RFC 2434, October
979 1998.
981 [17] Rosenberg, J., "An Extensible Markup Language (XML)
982 Configuration Access Protocol (XCAP) Usage for Presence Lists",
983 draft-rosenberg-simple-xcap-list-usage-00 (work in progress),
984 May 2003.
986 Author's Address
988 Jonathan Rosenberg
989 dynamicsoft
990 600 Lanidex Plaza
991 Parsippany, NJ 07054
992 US
994 Phone: +1 973 952-5000
995 EMail: jdrosen@dynamicsoft.com
996 URI: http://www.jdrosen.net
998 Intellectual Property Statement
1000 The IETF takes no position regarding the validity or scope of any
1001 intellectual property or other rights that might be claimed to
1002 pertain to the implementation or use of the technology described in
1003 this document or the extent to which any license under such rights
1004 might or might not be available; neither does it represent that it
1005 has made any effort to identify any such rights. Information on the
1006 IETF's procedures with respect to rights in standards-track and
1007 standards-related documentation can be found in BCP-11. Copies of
1008 claims of rights made available for publication and any assurances of
1009 licenses to be made available, or the result of an attempt made to
1010 obtain a general license or permission for the use of such
1011 proprietary rights by implementors or users of this specification can
1012 be obtained from the IETF Secretariat.
1014 The IETF invites any interested party to bring to its attention any
1015 copyrights, patents or patent applications, or other proprietary
1016 rights which may cover technology that may be required to practice
1017 this standard. Please address the information to the IETF Executive
1018 Director.
1020 Full Copyright Statement
1022 Copyright (C) The Internet Society (2003). All Rights Reserved.
1024 This document and translations of it may be copied and furnished to
1025 others, and derivative works that comment on or otherwise explain it
1026 or assist in its implementation may be prepared, copied, published
1027 and distributed, in whole or in part, without restriction of any
1028 kind, provided that the above copyright notice and this paragraph are
1029 included on all such copies and derivative works. However, this
1030 document itself may not be modified in any way, such as by removing
1031 the copyright notice or references to the Internet Society or other
1032 Internet organizations, except as needed for the purpose of
1033 developing Internet standards in which case the procedures for
1034 copyrights defined in the Internet Standards process must be
1035 followed, or as required to translate it into languages other than
1036 English.
1038 The limited permissions granted above are perpetual and will not be
1039 revoked by the Internet Society or its successors or assignees.
1041 This document and the information contained herein is provided on an
1042 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1043 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1044 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1045 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1046 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1048 Acknowledgement
1050 Funding for the RFC Editor function is currently provided by the
1051 Internet Society.