idnits 2.17.1 draft-reschke-webdav-post-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- 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 (November 22, 2009) is 5262 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Reschke 3 Internet-Draft greenbytes 4 Intended status: Standards Track November 22, 2009 5 Expires: May 26, 2010 7 Using POST to add Members to Web Distributed Authoring and Versioning 8 (WebDAV) Collections 9 draft-reschke-webdav-post-05 11 Abstract 13 The Hypertext Transfer Protocol (HTTP) Extensions for the Web 14 Distributed Authoring and Versioning (WebDAV) do not define the 15 behavior for the "POST" method when applied to collections, as the 16 base specification (HTTP) leaves implementers lots of freedom for the 17 semantics of "POST". 19 This has led to a situation where many WebDAV servers do not 20 implement POST for collections at all, although it is well suited to 21 be used for the purpose of adding new members to a collection, where 22 the server remains in control of the newly assigned URL. As a matter 23 of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for 24 that purpose. On the other hand, WebDAV-based protocols such as the 25 Calendar Extensions to WebDAV (CalDAV) frequently require clients to 26 pick a unique URL, although the server could easily perform that 27 task. 29 This specification defines a discovery mechanism through which 30 servers can advertise support for POST requests with the 31 aforementioned "add collection member" semantics. 33 Editorial Note (To be removed by RFC Editor before publication) 35 Please send comments to the Distributed Authoring and Versioning 36 (WebDAV) working group at , which may be 37 joined by sending a message with subject "subscribe" to 38 . Discussions of the WEBDAV 39 working group are archived at 40 . 42 Note that although discussion takes place on the WebDAV working 43 group's mailing list, this is not a working group document. 45 XML versions, latest edits and the issues list for this document are 46 available from 47 . 49 Status of this Memo 51 This Internet-Draft is submitted to IETF in full conformance with the 52 provisions of BCP 78 and BCP 79. 54 Internet-Drafts are working documents of the Internet Engineering 55 Task Force (IETF), its areas, and its working groups. Note that 56 other groups may also distribute working documents as Internet- 57 Drafts. 59 Internet-Drafts are draft documents valid for a maximum of six months 60 and may be updated, replaced, or obsoleted by other documents at any 61 time. It is inappropriate to use Internet-Drafts as reference 62 material or to cite them other than as "work in progress." 64 The list of current Internet-Drafts can be accessed at 65 http://www.ietf.org/ietf/1id-abstracts.txt. 67 The list of Internet-Draft Shadow Directories can be accessed at 68 http://www.ietf.org/shadow.html. 70 This Internet-Draft will expire on May 26, 2010. 72 Copyright Notice 74 Copyright (c) 2009 IETF Trust and the persons identified as the 75 document authors. All rights reserved. 77 This document is subject to BCP 78 and the IETF Trust's Legal 78 Provisions Relating to IETF Documents 79 (http://trustee.ietf.org/license-info) in effect on the date of 80 publication of this document. Please review these documents 81 carefully, as they describe your rights and restrictions with respect 82 to this document. Code Components extracted from this document must 83 include Simplified BSD License text as described in Section 4.e of 84 the Trust Legal Provisions and are provided without warranty as 85 described in the BSD License. 87 Table of Contents 89 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 90 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 91 3. Protocol Extension . . . . . . . . . . . . . . . . . . . . . . 6 92 3.1. Definition of 'Add-Member' URI . . . . . . . . . . . . . . 6 93 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 7 94 3.2.1. DAV:add-member Property (protected) . . . . . . . . . 7 95 3.2.2. Example . . . . . . . . . . . . . . . . . . . . . . . 7 96 3.3. Relation to AtomPub's 'Slug' Header Field . . . . . . . . 8 97 3.4. Example Operation . . . . . . . . . . . . . . . . . . . . 9 98 4. Additional Semantics for existing Methods . . . . . . . . . . 9 99 4.1. Additional Preconditions . . . . . . . . . . . . . . . . . 9 100 4.2. Example: Failed PUT Request . . . . . . . . . . . . . . . 10 101 5. Relationship to WebDAV Access Control Protocol . . . . . . . . 10 102 6. Internationalization Considerations . . . . . . . . . . . . . 10 103 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 104 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 105 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 106 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 107 10.1. Normative References . . . . . . . . . . . . . . . . . . . 11 108 10.2. Informative References . . . . . . . . . . . . . . . . . . 12 109 Appendix A. Change Log (to be removed by RFC Editor before 110 publication) . . . . . . . . . . . . . . . . . . . . 12 111 A.1. since draft-reschke-webdav-post-00 . . . . . . . . . . . . 12 112 A.2. since draft-reschke-webdav-post-01 . . . . . . . . . . . . 13 113 A.3. since draft-reschke-webdav-post-02 . . . . . . . . . . . . 13 114 A.4. since draft-reschke-webdav-post-03 . . . . . . . . . . . . 13 115 A.5. since draft-reschke-webdav-post-04 . . . . . . . . . . . . 13 116 Appendix B. Open issues (to be removed by RFC Editor prior to 117 publication) . . . . . . . . . . . . . . . . . . . . 13 118 B.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 119 B.2. collection . . . . . . . . . . . . . . . . . . . . . . . . 13 120 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 121 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 123 1. Introduction 125 The Hypertext Transfer Protocol (HTTP) Extensions for the Web 126 Distributed Authoring and Versioning (WebDAV) ([RFC4918], Section 127 9.5) do not define the behavior for the "POST" method when applied to 128 collections, as the base specification (HTTP) leaves implementers 129 lots of freedom for the semantics of "POST": 131 9.5 POST for Collections 133 Since by definition the actual function performed by POST is 134 determined by the server and often depends on the particular 135 resource, the behavior of POST when applied to collections cannot 136 be meaningfully modified because it is largely undefined. Thus, 137 the semantics of POST are unmodified when applied to a collection. 139 This has led to a situation where many WebDAV servers do not 140 implement POST for collections at all, although it is well suited to 141 be used for the purpose of adding new members to a collection, where 142 the server remains in control of the newly assigned URL. As a matter 143 of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for 144 that purpose ([RFC5023], Section 9.2): 146 9.2 Creating Resources with POST 148 To add members to a Collection, clients send POST requests to the 149 URI of the Collection. 151 On the other hand, WebDAV-based protocols such as Calendaring 152 Extensions to WebDAV (CalDAV) frequently require clients to pick a 153 unique URL, although the server could easily perform that task 154 ([RFC4791], Section 5.3.2): 156 5.3.2 Creating Calendar Object Resources 158 ... 160 When servers create new resources, it's not hard for the server to 161 choose an unmapped URI. It's slightly tougher for clients, 162 because a client might not want to examine all resources in the 163 collection and might not want to lock the entire collection to 164 ensure that a new resource isn't created with a name collision. 165 (...) 167 As a matter of fact, letting the server choose the member URI not 168 only is a simplification for certain types of clients, but can also 169 reduce the complexity of the server (in that it doesn't need to 170 persist an additional client-supplied identifier where it already has 171 an internal one like a UUID or a primary key). 173 Note: the vCard Extensions to WebDAV (CardDAV) 174 ([draft-ietf-vcarddav-carddav]) suffer from the same issue, and 175 may be able to take advantage of this specification. 177 This specification defines a discovery mechanism through which 178 servers can advertise support for POST requests with the 179 aforementioned "add collection member" semantics. 181 Note that this specification deliberately only adresses the use case 182 of creating new non-collection resources, and that it was not a goal 183 to supply the same functionality for creating collection resources 184 (MKCOL), or for other operations that require the client to specify a 185 new URL (LOCK, MOVE, or COPY). 187 Note: the author previously proposed a new HTTP method for exactly 188 this purpose ([draft-reschke-http-addmember]), but quite a few 189 reviewers pointed out that this would duplicate the original 190 semantics of POST. Thus this proposal that avoids adding a new 191 HTTP method is made. 193 2. Terminology 195 The terminology used here follows that in the WebDAV specification 196 ([RFC4918]). 198 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 199 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 200 document are to be interpreted as described in [RFC2119]. 202 This document uses XML DTD fragments ([XML]) as a purely notational 203 convention. In particular: 205 o Element ordering is irrelevant. 207 o Extension elements/attributes (elements/attributes not already 208 defined as valid child elements) may be added anywhere, except 209 when explicitly stated otherwise. 211 Note: this specification defines new properties and precondition 212 names in the "DAV:" namespace, which the WebDAV specification 213 reserves for use by the IETF ([RFC4918], Section 21.1). However, 214 there was rough consensus in the WebDAV community that the 215 specification is of general applicability to other WebDAV related 216 standards efforts, and thus deserves inclusion into the base 217 namespace. 219 3. Protocol Extension 221 Due to the reasons stated in Section 1, clients can not rely on a 222 specific server behavior when POST is applied to a collection. This 223 problem is addressed by this specification by allowing servers to 224 advertise a URI that has the desired "add member" semantics. 226 Note that servers that already use POST for a different purpose can 227 just expose a separate URI. Other servers can just advertise the 228 collection's own URI, thus avoiding minting another URI for a limited 229 purpose. 231 3.1. Definition of 'Add-Member' URI 233 The "Add-Member" URI of a WebDAV collection is a URI that will accept 234 HTTP POST requests, and will interpret these as requests to store the 235 enclosed entity as a new internal member of the collection (see 236 Section 3 of [RFC4918] for the definition of "internal member"). It 237 MUST identify a resource on the same server as the WebDAV collection 238 (the host and port components ([RFC2616], Section 3.2.2) of the URIs 239 must match). 241 If there are pre-conditions related to creating a resource in the 242 collection using a PUT request, then those same pre-conditions apply 243 to the new POST request behavior, and the same HTTP response body 244 will returned on failure. 246 The URI of the newly created resource is returned in the HTTP 247 Location response header field ([RFC2616], Section 14.30). 249 Note: the fact that a server advertises an "Add-Member" URI does 250 not imply any special semantics of the collection itself. For 251 instance, member URIs assigned by the server are not necessarily 252 unique over time (a member URI may be assigned again to a new 253 resource when it previously was removed). 255 Note: the "Add-Member" URI can be the identical to the 256 collection's URI (in which case the server just advertises the 257 fact that POST to the WebDAV collection's URI is supported as 258 defined within this specification). But it can also be different 259 from it, in which case it doesn't need to have any relation to the 260 collection's URI. 262 Given a collection URI of 264 /docs/collection/ 265 all of the URIs below might occur as "Add-Member" URIs: 267 /docs/collection/ 268 /docs/collection/;post 269 /docs/collection;post/ 270 /docs/collection/&post 271 /post-service?path=/collection/ 273 The remainder of the document uses the same format just for 274 reasons of consistency; any other HTTP URI on the same server 275 would do as well. 277 3.2. Discovery 279 3.2.1. DAV:add-member Property (protected) 281 DAV:add-member is a protected property (see [RFC4918], Section 15) 282 defined on WebDAV collections, and contains the "Add-Member" URI for 283 that collection (embedded inside a DAV:href element). 285 286 288 A PROPFIND/allprop request SHOULD NOT return this property (see 289 [RFC4918], Section 9.1). Servers MUST implement the DAV:supported- 290 live-property-set property defined in Section 3.1.4 of [RFC3253], and 291 report the property DAV:add-member as a supported live property. 293 3.2.2. Example 295 >>Request 297 PROPFIND /collection/ HTTP/1.1 298 Host: example.com 299 Content-Type: application/xml; charset="utf-8" 300 Content-Length: 118 302 303 304 305 306 307 308 >>Response 310 HTTP/1.1 207 Multi-Status 311 Content-Type: application/xml; charset="utf-8" 312 Content-Length: 340 314 315 316 317 /collection/ 318 319 320 321 /collection;add-member/ 322 323 324 HTTP/1.1 200 OK 325 326 327 329 Note that in this case, the server has minted a separate URI for the 330 purpose of adding new content. 332 3.3. Relation to AtomPub's 'Slug' Header Field 334 In the AtomPub protocol, clients can use the entity header field 335 "Slug" to suggest parts of the URI to be created (see [RFC5023], 336 Section 9.7). Note that servers are free to ignore this suggestion, 337 or to use whatever algorithm that makes sense to generate the new 338 URI. 340 The same applies to the extension defined here: clients can use the 341 "Slug" header field as by its definition of a generic HTTP header 342 field. Servers should process it exactly in the way defined by 343 AtomPub. 345 3.4. Example Operation 347 >>Request 349 POST /collection;add-member/ HTTP/1.1 350 Host: example.com 351 Content-Type: text/plain 352 Slug: Sample Title 353 Content-Length: 12 355 Sample text. 357 >>Response 359 HTTP/1.1 201 Created 360 Location: http://example.com/collection/sample%20title 362 4. Additional Semantics for existing Methods 364 One important use case for this specification are collections that 365 act as WebDAV collections for the purpose of read access (PROPFIND 366 Depth 1/Infinity), but which only support internal member URIs 367 assigned by the server. These collections will not allow a client to 368 create a new member using methods like PUT, MKCOL, LOCK, COPY or 369 MOVE. Therefore, this specification defines a new precondition name 370 ([RFC4918], Section 16) that can be used to provide the client with 371 additional information about why exactly the request failed. 373 Note: although the precondition defined below can be used for 374 methods other than PUT, the "Add-Member" mechanism defined by this 375 specification deliberately is restricted to PUT. 377 4.1. Additional Preconditions 379 (DAV:allow-client-defined-URI): the server allows clients to specify 380 the last path segment for newly created resources. 382 The precondition element MAY contain a add-member-uri XML element 383 specifying the "Add-Member" URI associated with the collection, on 384 which the creation of a new child resource was attempted: 386 388 4.2. Example: Failed PUT Request 390 In this example, the client tries to use PUT to create a new internal 391 member of /collection/. 393 >>Request 395 PUT /collection/new.txt HTTP/1.1 396 Host: example.com 397 Content-Type: text/plain 398 Content-Length: 12 400 Sample text. 402 >>Response 404 HTTP/1.1 405 Method Not Allowed 405 Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE 406 Content-Type: application/xml; charset=UTF-8 407 Content-Length: 172 409 410 411 412 /collection;add-member/ 413 414 415 417 The request fails with a 405 (Method Not Allowed) status, but also 418 provides the reason, and a pointer to the "Add-Member" URI in the 419 response body. 421 5. Relationship to WebDAV Access Control Protocol 423 The WebDAV ACL specification requires the DAV:bind privilege to be 424 granted on a collection for the client to be able add new collection 425 members ([RFC3744], Section 3.9). Consistent with that, a server 426 MUST reject a POST request to the Add-Member URI of a collection 427 unless the principal executing the request is granted DAV:bind 428 privilege on the associated WebDAV collection resource. 430 6. Internationalization Considerations 432 This document does not introduce any new internationalization 433 considerations beyond those discussed in Section 20 of [RFC4918]. 435 7. IANA Considerations 437 This specification does not require any actions from IANA. 439 8. Security Considerations 441 All security considerations connected to HTTP/WebDAV and XML apply 442 for this specification as well, namely, [RFC4918] (Section 20) and 443 [RFC3470] (Section 7). 445 Furthermore, servers should be aware that deriving the member path 446 from the data being stored in the resource could potentially expose 447 confidential information. This could even be the case when only a 448 hash code of the content is used. 450 In addition, on servers that do not support this specification, a 451 malevolent user could set the DAV:add-member URI as a custom 452 property, tricking other users to post content to an entirely 453 different URI. Clients can protect themselves against this scenario 454 by 456 o not following DAV:add-member URIs to different servers, and/or 458 o verifying that the DAV:add-member property is indeed a live 459 property (this can be achieved by testing the DAV:supported-live- 460 property-set property, or by checking whether DAV:add-member is 461 returned upon PROPFIND/allprop) 463 9. Acknowledgements 465 This document has benefited from thoughtful discussion by Cyrus Daboo 466 and Bernard Desruissaux. 468 10. References 470 10.1. Normative References 472 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 473 Requirement Levels", BCP 14, RFC 2119, March 1997. 475 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 476 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 477 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 479 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 481 Whitehead, "Versioning Extensions to WebDAV", RFC 3253, 482 March 2002. 484 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web 485 Distributed Authoring and Versioning (WebDAV) Access 486 Control Protocol", RFC 3744, May 2004. 488 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 489 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 491 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 492 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 493 Edition)", W3C REC-xml-20081126, November 2008, 494 . 496 10.2. Informative References 498 [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for 499 the Use of Extensible Markup Language (XML) within IETF 500 Protocols", RFC 3470, BCP 70, January 2003. 502 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 503 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 504 March 2007. 506 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 507 Protocol", RFC 5023, October 2007. 509 [draft-ietf-vcarddav-carddav] 510 Daboo, C., "vCard Extensions to WebDAV (CardDAV)", 511 draft-ietf-vcarddav-carddav-10 (work in progress), 512 November 2009. 514 [draft-reschke-http-addmember] 515 Reschke, J., "The HTTP ADDMEMBER Method", 516 draft-reschke-http-addmember-00 (work in progress), 517 February 2005. 519 Appendix A. Change Log (to be removed by RFC Editor before publication) 521 A.1. since draft-reschke-webdav-post-00 523 Added Acknowledgements. 525 Added and resolved issues "acl", "forbidden-put", "member-uri- 526 content", "post-error-semantics", "property-trust", "rational-server- 527 uri", ""remote-uri", "uri-format" and "uri-uniqueness". 529 A.2. since draft-reschke-webdav-post-01 531 Add and resolve issue "containment". 533 Update draft-ietf-vcarddav-carddav reference. 535 A.3. since draft-reschke-webdav-post-02 537 Update XML, draft-ietf-vcarddav-carddav and 538 draft-nottingham-http-link-header references. 540 Add and resolve issues "link-header" and "ns". 542 A.4. since draft-reschke-webdav-post-03 544 Add and resolve issues "put-only" and "protected". 546 A.5. since draft-reschke-webdav-post-04 548 Update vcarddav reference. In the example, do not use the same 549 content for Slug header field and request body. Add issue 550 "collection". 552 Appendix B. Open issues (to be removed by RFC Editor prior to 553 publication) 555 B.1. edit 557 Type: edit 559 julian.reschke@greenbytes.de (2008-09-22): Umbrella issue for 560 editorial fixes/enhancements. 562 B.2. collection 564 Type: change 566 cyrus@daboo.name (2009-11-05): I have heard from some implementors 567 that they would like collection creation to also be part of this 568 draft. In particular, CalDAV and/or CardDAV clients creating 569 calendars or address books would prefer to leave specification of the 570 resource name to the client. 571 Proposal: 572 - Add a DAV:add-collection property containing a URI (which must be 573 different than DAV:add-member) 574 - A POST on that URI creates a collection within the parent 575 collection, with a server chosen resource name 576 - If the POST contains an XML body with DAV:mkcol as the root 577 element, then that body is interpreted the same way as MKCOL ext. 579 Index 581 A 582 Add-Member URI 6 584 C 585 Condition Names 586 DAV:allow-client-defined-URI (pre) 9 587 COPY method 588 Additional Preconditions 9 590 D 591 DAV:allow-client-defined-URI 9 593 L 594 LOCK method 595 Additional Preconditions 9 597 M 598 MKCOL method 599 Additional Preconditions 9 600 MOVE method 601 Additional Preconditions 9 603 P 604 PUT method 605 Additional Preconditions 9 607 Author's Address 609 Julian F. Reschke 610 greenbytes GmbH 611 Hafenweg 16 612 Muenster, NW 48155 613 Germany 615 Phone: +49 251 2807760 616 Email: julian.reschke@greenbytes.de 617 URI: http://greenbytes.de/tech/webdav/