idnits 2.17.1 draft-ietf-webdav-properties-extension-00.txt: ** The Abstract section seems to be numbered 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: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == There is 1 instance of lines with non-ascii characters in the document. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 553 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Null Property - A property that responds with 404 (Not Found) to a PROPFIND method. A null property MUST not appear in the list of properties of a resource the PROPFIND is specified with DAV:allprop. -- 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 (September 1999) is 8980 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 13 -- Looks like a reference, but probably isn't: '2' on line 61 == Missing Reference: 'URI' is mentioned on line 67, but not defined == Unused Reference: 'RFC2119' is defined on line 413, but no explicit reference was found in the text == Unused Reference: 'XML' is defined on line 417, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2068 (ref. 'HTTP') (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2518 (ref. 'WebDAV') (Obsoleted by RFC 4918) Summary: 7 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 WebDAV J. Amsden 2 Internet Draft IBM 3 Document: draft-ietf-webdav-properties-extension-00.txt September 1999 4 Category: Informational 5 Expires: March, 2000 7 Proposed Extensions to WebDAV Properties 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 [1]. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet- 17 Drafts. Internet-Drafts are draft documents valid for a maximum of 18 six months and may be updated, replaced, or obsoleted by other 19 documents at any time. It is inappropriate to use Internet- Drafts 20 as reference material or to cite them other than as "work in 21 progress." 23 The list of current Internet-Drafts can be accessed at 24 http://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 1. Abstract 31 The WebDAV protocol defines facilities for adding properties to Web 32 resources. These properties consist of name/value pairs interchanged 33 using XML. The protocol includes the PROPFIND method for accessing 34 properties, and the PROPPATCH method for updating and removing 35 properties. Experience building both WebDAV clients and a WebDAV 36 server indicates the need for three minor extensions to the current 37 properties protocol: 1) allow PROPPATCH to create and initialize the 38 properties of a resource that did not exist, 2) distinguish between 39 adding a new property, and setting the value of an existing property 40 of a resource, and 3) give client applications more control in 41 specifying how PROPPATCH errors should be handled. 43 2. Conventions used in this document 45 Since this document describes a set of extensions to the HTTP/1.1 46 protocol, the augmented BNF used here to describe protocol an element 47 is exactly the same as described in Section 2.1 of [HTTP]. Since 48 this augmented BNF uses the basic production rules provided in 49 Section 2.2 of [HTTP], these rules apply to this document as well. 51 Amsden Informational � Expiration March 2000 1 53 Proposed Extensions to WebDAV Properties September 1999 55 In examples, "C:" and "S:" indicate lines sent by the client and 56 server respectively. 58 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 59 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 60 this document are to be interpreted as described in RFC-2119 [2]. 62 3. Terminology 64 The terminology used here extends that defined in the WebDAV 65 Distributed Authoring Protocol specification [WebDAV]. Definitions of 66 the terms resource, Uniform Resource Identifier (URI), and Uniform 67 Resource Locator (URL) are provided in [URI]. 69 Null Property - A property that responds with 404 (Not Found) to a 70 PROPFIND method. A null property MUST not appear in the list of 71 properties of a resource the PROPFIND is specified with DAV:allprop. 73 4. Introduction 75 This Internet Draft specification introduces three simple extensions 76 or modifications to the handling of WebDAV properties. All are based 77 on experience gained through building a WebDAV class 2 server, and 78 sample client applications. The extensions are all compatible with 79 existing WebDAV property semantics, and all involve property updates 80 through the PROPPATCH method. 82 4.1 PROPPATCH on a Null Resource 84 HTTP and WebDAV do not specify methods for creating resources; they 85 are created as the side effect of other methods. For example, PUT on 86 a null resource (a resource that does not exist) creates the resource 87 and establishes its initial contents. LOCK on a null resource creates 88 a lock-null resource, which has properties, but no content. COPY and 89 MOVE can create resources at the destination URI. It is often 90 necessary to create resources and initialize their state before any 91 other access is allowed in order to ensure the integrity of the 92 operations. WebDAV currently has no protocol for creating and 93 initializing the properties of a resource in a single method. This 94 Internet Draft proposes that PROPPATCH on a null resource creates the 95 resource with empty contents, and initializes its properties based on 96 the propertyupdate elements in the request entity body. 98 The WebDAV spec is currently somewhat silent about PROPPATCH on a 99 null resource. It does say that PROPPATCH on a lock null resource (a 100 resource created by the LOCK method) will fail, but this is 101 inconsistent with PUT which is allowed, and changes the state of the 102 resource from lock null to resource. [HTTP] uses status 404, Not 103 Found, to indicate the server has not found anything matching the 104 Request-URI. It does not say that the server cannot create a resource 106 Category - Expiration 2 108 Proposed Extensions to WebDAV Properties September 1999 110 at the Request-URI. The HTTP and WebDAV PUT method on a null resource 111 is defined to create the resource and set its initial contents. 112 Allowing PROPPATCH on a null resource to create the resource and set 113 its initial properties is consistent with the PUT semantics, and 114 other resource state changing methods that create resources as a side 115 effect. 117 4.2 Adding New Properties 119 Typical database management systems distinguish three kinds of 120 updates; add, remove, and change. It is often necessary to 121 distinguish between add and change in order to ensure a property is 122 added only once, and that its value is not inadvertently changed 123 after it has been initialized. 125 The WebDAV PROPPATCH method updates a resource's properties based on 126 the instructions contained in the DAV:propertyupdate element of the 127 request entity body. The propertyupdate element currently supports 128 setting and removing properties. DAV:set creates a new property if it 129 does not exist, and sets its value. If the property already exists, 130 the value is changed. 132 This Internet Draft proposes the addition of a DAV:add propertyupdate 133 that adds a new property and sets its value, but fails if the 134 property already exists. In addition, this draft proposes that 135 DAV:set on a null property (a property that does not exist) fails 136 instead of creating a new property. This may help prevent erroneous 137 client property updates resulting from setting the values of 138 properties where the property name is incorrectly specified. 140 4.3 Handling PROPPATCH Errors 142 Client applications currently use PROPPATCH to update the properties 143 of a resource. PROPPATCH supports the update of a number of 144 properties in a single method request in order to reduce 145 communication overhead and maintain resource state integrity with 146 atomic updates. 148 Currently, the WebDAV spec dictates that the result of a PROPPATCH is 149 an atomic transaction. That is, either all the updates succeed, or 150 none of them succeed and the updates are rolled back. This can result 151 in excessive client burden. A client application may attempt to make 152 a number of updates with PROPPATCH, and doesn't care if some of them 153 don't succeed. This is often the case when some of the properties are 154 live on the server, but the client has no way to determine which are 155 live without attempting to update their value and getting an error. 156 This situation arises when different servers support different live 157 properties. Updating the desired properties, ignoring the ones that 158 are live requires the client to attempt the update, examine the 159 DAV:multistatus response that is returned, construct a new PROPPATCH 160 entity request body removing the properties that failed, and re- 161 submitting the PROPPATCH request. 163 Category - Expiration 3 165 Proposed Extensions to WebDAV Properties September 1999 167 This Internet Draft proposes that a mechanism be added to the 168 DAV:propertyupdate element that gives client applications more 169 control over updating resource properties by allowing the protocol to 170 specify how to handle errors on each of the updates in the 171 DAV:propertyupdate of a PROPPATCH entity request body. This is 172 similar to the DAV:propertybehavior element of the COPY and MOVE 173 entity request body that is used to specify how properties are copied 174 to the destination resource. 176 By making this change to the PROPPATCH entity request body, it is now 177 possible to completely specify the semantics of COPY and MOVE in 178 terms of the more primitive GET, PUT, PROPFIND, and PROPPATCH 179 methods. This is not currently possible because there is no way to 180 process the DAV:propertybehavior element of the COPY or MOVE entity 181 request body with a PROPPATCH method. 183 5. PROPPATCH Protocol Changes 185 This section specifies changes to section 8.2 PROPPATCH of [WebDAV] 186 and section 12 to support the semantics described above. 188 Update section 8.2 PROPPATCH to indicate that PROPPATCH on a null 189 resource creates the resource at the given Request-URI, and 190 initializes its properties as specified in the DAV:propertyupdate 191 element of the PROPPATCH entity request body. 193 Change section 8.2 PROPPATCH to include simple error processing of 194 PROPPATCH method requests. Update the DAV:set and DAV:remove elements 195 to include information describing how the client wishes to handle 196 errors. Change the semantics of DAV:set to fail on a null property. 198 Change section 12.13.2 set XML element to: 200 12.13.2 set XML element 202 Name: set 203 Namespace: DAV: 204 Purpose: List the DAV property values to be set for a 205 resource. 206 Description: The set XML element MUST contain only a prop XML 207 element. The elements contained by the prop XML element inside the 208 set XML element MUST specify the name and value of properties that 209 are set on the resource identified by the Request-URI. If the 210 property does not exist then a 404 (Not Found) status is returned, 211 and the property update fails. The DAV:updatebehavior element 212 specifies how update failures are to be handled. Language tagging 213 information in the property's value (in the "xml:lang" attribute, if 214 present) MUST be persistently stored along with the property, and 215 MUST be subsequently retrievable using PROPFIND. 217 219 Category - Expiration 4 221 Proposed Extensions to WebDAV Properties September 1999 223 Change section 12.13.1 remove XML element to: 225 12.13.1 remove XML element 227 Name: remove 228 Namespace: DAV: 229 Purpose: List the DAV property values to be removed from a 230 resource. 231 Description: Remove instructs that the properties specified in the 232 prop should be removed. Specifying the removal of a null property is 233 not an error. All the XML elements in a prop XML element inside of a 234 remove XML element MUST be empty, as only the names of properties to 235 be removed are required. The DAV:updatebehavior element specifies how 236 update failures are to be handled. 238 240 Extend the DAV:propertyupdate element of the PROPPATCH entity request 241 body to include element DAV:add. The DAV:add element has the same 242 contents as DAV:set. 244 Adding a property fails with 403 (Forbidden) if the property already 245 exists. Setting a null property results in a 404 (Not Found) status. 247 Change to section 12.13 propertyupdate XML element to: 249 12.13 propertyupdate XML element 251 Name: propertyupdate 252 Namespace: DAV: 253 Purpose: Contains a request to alter the properties on a 254 resource 255 Description: This XML element is a container for the information 256 required to modify the properties on the resource. This XML element 257 is multi-valued to support adding, changing, and/or removing 258 properties. 260 262 Add section 12.13.3, add XML element as follows: 264 12.13.3 add XML element 266 Name: add 267 Namespace: DAV: 268 Purpose: List the DAV property values to be added to a 269 resource. 270 Description: The add XML element MUST contain only a prop XML 271 element. The elements contained by the prop XML element inside the 272 add XML element MUST specify the name and value of properties that 273 are to be added to the resource identified by the Request-URI. If a 274 property already exists then a 403 (Forbidden) status is returned, 275 and the property is not added. The DAV:updatebehavior element 277 Category - Expiration 5 279 Proposed Extensions to WebDAV Properties September 1999 281 specifies how update failures are to be handled. Language tagging 282 information in the property's value (in the "xml:lang" attribute, if 283 present) MUST be persistently stored along with the property, and 284 MUST be subsequently retrievable using PROPFIND. 286 288 Add sections to section 12.13 to specify error processing on property 289 updates. 291 12.13.4 updatebehavior XML element 293 Name: updatebehavior 294 Namespace: DAV: 295 Purpose: Specify how errors on property updates are to be 296 handled. 297 Description: An updatebehavior specifies how errors are to be handled 298 on the corresponding DAV:add, DAV:set, or DAV:remove propertyupdate. 299 The client can specify that the error should be ignored, or that it 300 must succeed. If DAV:mustsucceed is specified, then the PROPPATCH 301 method will fail if any of the updates fail. This is the default 302 behavior. 304 306 12.13.5 ignore XML element 308 Name: ignore 309 Namespace: DAV: 310 Purpose: Causes corresponding property update errors to be 311 ignored 312 Description: The default behavior for a PROPPATCH method is all 313 property updates must succeed, or none of them succeed. If an 314 updatebehavior is not included, it is equivalent to the default 315 behavior or specifying * meaning that all 316 the updates must be successful or none of them are performed. The 317 DAV:ignore element specifies that the server should make best-effort 318 property updates. Any error caused by the associated propertyupdate 319 is ignored. The error is reported in the resulting DAV:multistatus, 320 but the rest of the updates specified in the PROPPATCH entity request 321 body are processed as if this propertyupdate was not specified. 323 325 12.13.6 mustsucceed XML element 327 Name: mustsucceed 328 Namespace: DAV: 329 Purpose: Specifies the corresponding property update must 330 succeed. 331 Description: The default behavior for a PROPPATCH method is all 332 property updates must succeed, or none of them succeed. The 333 DAV:mustsucceed element allows the client to specify a list of named 335 Category - Expiration 6 337 Proposed Extensions to WebDAV Properties September 1999 339 properties whose property update must succeed. Any error caused by 340 the associated propertyupdate causes the PROPPATCH method to fail, 341 and all property updates are rolled back. If a value of "*" is given 342 for the mustsucceed XML element, this designates that all property 343 updates must succeed. "*" is the only PCDATA value that can be 344 specified. 346 348 Note: element DAV:mustsucceed may not be necessary because the 349 default behavior is for the PROPPATCH to fail if any propertyupdate 350 fails. It is really only necessary to specify which errors are to be 351 ignored. I have included it here for completeness, and consistency 352 with the DAV:keepalive XML element. 354 6. Formal Syntax 356 < Commonly used grammar is BNF grammar defined in RFC-2234. 357 Suggested wording.> 359 This section summarizes the changes and additions to the WebDAV DTD 360 given in section 24.1 of [WebDAV]. 362 364 365 366 368 369 370 372 7. Security Considerations 374 This section is provided to detail issues concerning security 375 implications of which WebDAV applications need to be aware. 377 All of the security considerations of HTTP/1.1 and the WebDAV 378 Distributed Authoring Protocol specification also apply to WebDAV 379 collections. 381 These changes may introduce a denial of service security violation 382 through the possibility of a client application exhausting server 383 resources with PROPPATCH methods. However, the same possibility 384 exists with PUT operations, so no new security issues are introduced. 386 8. IANA Considerations 388 Category - Expiration 7 390 Proposed Extensions to WebDAV Properties September 1999 392 This document uses the namespaces defined by [WebDAV] for properties 393 and 394 XML elements. All other IANA considerations mentioned in [WebDAV] also 395 apply to this document. 397 9. Copyright 399 To be supplied by the RFC Editor. 401 10. Intellectual Property 403 To be supplied by the RFC Editor. 405 11. References 407 1 Bradner, S., "The Internet Standards Process -- Revision 3", BCP 408 9, RFC 2026, October 1996. 410 2 Bradner, S., "Key words for use in RFCs to Indicate Requirement 411 Levels", BCP 14, RFC 2119, March 1997 413 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 414 Requirement 415 Levels." RFC 2119, BCP 14. Harvard University. March, 1997. 417 [XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible Markup 418 Language (XML)." World Wide Web Consortium Recommendation REC-xml- 419 19980210. http://www.w3.org/TR/1998/REC-xml-19980210. 421 [HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, 422 "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. UC Irvine, DEC, 423 MIT/LCS. January, 1997. 425 [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, 426 D. 427 Jensen, "HTTP Extensions for Distributed Authoring - WebDAV." RFC 428 2518. 429 Microsoft, U.C. Irvine, Netscape, Novell. February, 1999. 431 11. Acknowledgments 433 This draft has benefited from thoughtful discussion by Jim Whitehead, 434 Geoff Clemm, and others. 436 12. Author's Addresses 438 James Amsden 439 IBM 441 Category - Expiration 8 443 Proposed Extensions to WebDAV Properties September 1999 445 3039 Cornwallis Road 446 RPT, NC 447 Phone: 919-461-3919 448 Email: jamsden@us.ibm.com 450 Category - Expiration 9