idnits 2.17.1 draft-reschke-webdav-post-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 (May 21, 2010) is 5082 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: 1 error (**), 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 May 21, 2010 5 Expires: November 22, 2010 7 Using POST to add Members to Web Distributed Authoring and Versioning 8 (WebDAV) Collections 9 draft-reschke-webdav-post-08 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. In fact, 23 the Atom Publishing Protocol (AtomPub) uses POST exactly for that 24 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 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). Note that other groups may also distribute 56 working documents as Internet-Drafts. The list of current Internet- 57 Drafts is at http://datatracker.ietf.org/drafts/current/. 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 This Internet-Draft will expire on November 22, 2010. 66 Copyright Notice 68 Copyright (c) 2010 IETF Trust and the persons identified as the 69 document authors. All rights reserved. 71 This document is subject to BCP 78 and the IETF Trust's Legal 72 Provisions Relating to IETF Documents 73 (http://trustee.ietf.org/license-info) in effect on the date of 74 publication of this document. Please review these documents 75 carefully, as they describe your rights and restrictions with respect 76 to this document. Code Components extracted from this document must 77 include Simplified BSD License text as described in Section 4.e of 78 the Trust Legal Provisions and are provided without warranty as 79 described in the Simplified BSD License. 81 Table of Contents 83 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 84 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 85 3. Protocol Extension . . . . . . . . . . . . . . . . . . . . . . 6 86 3.1. Definition of 'Add-Member' URI . . . . . . . . . . . . . . 6 87 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 7 88 3.2.1. DAV:add-member Property (protected) . . . . . . . . . 7 89 3.2.2. Example . . . . . . . . . . . . . . . . . . . . . . . 7 90 3.3. Relation to AtomPub's 'Slug' Header Field . . . . . . . . 8 91 3.4. Example Operation . . . . . . . . . . . . . . . . . . . . 9 92 4. Additional Semantics for existing Methods . . . . . . . . . . 9 93 4.1. Additional Preconditions . . . . . . . . . . . . . . . . . 9 94 4.2. Example: Failed PUT Request . . . . . . . . . . . . . . . 10 95 5. Relationship to WebDAV Access Control Protocol . . . . . . . . 10 96 6. Internationalization Considerations . . . . . . . . . . . . . 10 97 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 98 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 99 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 100 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 101 10.1. Normative References . . . . . . . . . . . . . . . . . . . 11 102 10.2. Informative References . . . . . . . . . . . . . . . . . . 12 103 Appendix A. Change Log (to be removed by RFC Editor before 104 publication) . . . . . . . . . . . . . . . . . . . . 13 105 A.1. since draft-reschke-webdav-post-00 . . . . . . . . . . . . 13 106 A.2. since draft-reschke-webdav-post-01 . . . . . . . . . . . . 13 107 A.3. since draft-reschke-webdav-post-02 . . . . . . . . . . . . 13 108 A.4. since draft-reschke-webdav-post-03 . . . . . . . . . . . . 13 109 A.5. since draft-reschke-webdav-post-04 . . . . . . . . . . . . 13 110 A.6. since draft-reschke-webdav-post-05 . . . . . . . . . . . . 13 111 A.7. since draft-reschke-webdav-post-06 . . . . . . . . . . . . 13 112 A.8. since draft-reschke-webdav-post-07 . . . . . . . . . . . . 13 113 Appendix B. Resolved issues (to be removed by RFC Editor 114 before publication) . . . . . . . . . . . . . . . . . 14 115 B.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 116 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 118 1. Introduction 120 The Hypertext Transfer Protocol (HTTP) Extensions for the Web 121 Distributed Authoring and Versioning (WebDAV) ([RFC4918], Section 122 9.5) do not define the behavior for the "POST" method when applied to 123 collections, as the base specification (HTTP) leaves implementers 124 lots of freedom for the semantics of "POST": 126 9.5 POST for Collections 128 Since by definition the actual function performed by POST is 129 determined by the server and often depends on the particular 130 resource, the behavior of POST when applied to collections cannot 131 be meaningfully modified because it is largely undefined. Thus, 132 the semantics of POST are unmodified when applied to a collection. 134 This has led to a situation where many WebDAV servers do not 135 implement POST for collections at all, although it is well suited to 136 be used for the purpose of adding new members to a collection, where 137 the server remains in control of the newly assigned URL. In fact, 138 the Atom Publishing Protocol (AtomPub) uses POST exactly for that 139 purpose ([RFC5023], Section 9.2): 141 9.2 Creating Resources with POST 143 To add members to a Collection, clients send POST requests to the 144 URI of the Collection. 146 On the other hand, WebDAV-based protocols such as Calendaring 147 Extensions to WebDAV (CalDAV) frequently require clients to pick a 148 unique URL, although the server could easily perform that task 149 ([RFC4791], Section 5.3.2): 151 5.3.2 Creating Calendar Object Resources 153 ... 155 When servers create new resources, it's not hard for the server to 156 choose an unmapped URI. It's slightly tougher for clients, 157 because a client might not want to examine all resources in the 158 collection and might not want to lock the entire collection to 159 ensure that a new resource isn't created with a name collision. 160 (...) 162 Letting the server choose the member URI not only is a simplification 163 for certain types of clients, but can also reduce the complexity of 164 the server (in that it doesn't need to persist an additional client- 165 supplied identifier where it already has an internal one like a UUID 166 or a primary key). 168 Note: the vCard Extensions to WebDAV (CardDAV) 169 ([draft-ietf-vcarddav-carddav]) suffer from the same issue, and 170 may be able to take advantage of this specification. 172 This specification defines a discovery mechanism through which 173 servers can advertise support for POST requests with the 174 aforementioned "add collection member" semantics. 176 This specification deliberately only adresses the use case of 177 creating new non-collection resources, and that it was not a goal to 178 supply the same functionality for creating collection resources 179 (MKCOL), or for other operations that require the client to specify a 180 new URL (LOCK, MOVE, or COPY). 182 Note: the author previously proposed a new HTTP method for exactly 183 this purpose ([draft-reschke-http-addmember]), but quite a few 184 reviewers pointed out that this would duplicate the original 185 semantics of POST. Thus this proposal that avoids adding a new 186 HTTP method is made. 188 2. Terminology 190 The terminology used here follows that in the WebDAV specification 191 ([RFC4918]). 193 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 194 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 195 document are to be interpreted as described in [RFC2119]. 197 This document uses XML DTD fragments ([XML]) as a purely notational 198 convention. In particular: 200 o Element ordering is irrelevant. 202 o Extension elements/attributes (elements/attributes not already 203 defined as valid child elements) may be added anywhere, except 204 when explicitly stated otherwise. 206 Note: this specification defines new properties and precondition 207 names in the "DAV:" namespace, which the WebDAV specification 208 reserves for use by the IETF ([RFC4918], Section 21.1). However, 209 there was rough consensus in the WebDAV community that the 210 specification is of general applicability to other WebDAV related 211 standards efforts, and thus deserves inclusion into the base 212 namespace. 214 3. Protocol Extension 216 Due to the reasons stated in Section 1, clients can not rely on a 217 specific server behavior when POST is applied to a collection. This 218 problem is addressed by this specification by allowing servers to 219 advertise a URI that has the desired "add member" semantics. 221 Servers that already use POST for a different purpose can just expose 222 a separate URI. Other servers can just advertise the collection's 223 own URI, thus avoiding minting another URI for a limited purpose. 225 3.1. Definition of 'Add-Member' URI 227 The "Add-Member" URI of a WebDAV collection is a URI that will accept 228 HTTP POST requests, and will interpret these as requests to store the 229 enclosed entity as a new internal member of the collection (see 230 Section 3 of [RFC4918] for the definition of "internal member"). It 231 MUST identify a resource on the same server as the WebDAV collection 232 (the host and port components ([RFC2616], Section 3.2.2) of the URIs 233 must match). 235 If there are pre-conditions related to creating a resource in the 236 collection using a PUT request, then those same pre-conditions apply 237 to the new POST request behavior, and the same HTTP response body 238 will be returned on failure. 240 The URI of the newly created resource is returned in the HTTP 241 Location response header field ([RFC2616], Section 14.30). 243 Note: the fact that a server advertises an "Add-Member" URI does 244 not imply any special semantics of the collection itself. For 245 instance, member URIs assigned by the server are not necessarily 246 unique over time (a member URI may be assigned again to a new 247 resource when it previously was removed). 249 Note: the "Add-Member" URI can be identical to the collection's 250 URI (in which case the server just advertises the fact that POST 251 to the WebDAV collection's URI is supported as defined within this 252 specification). But it can also be different from it, in which 253 case it doesn't need to have any relation to the collection's URI. 255 Given a collection URI of 257 /docs/collection/ 258 any of the URIs below might occur as "Add-Member" URIs: 260 /docs/collection/ 261 /docs/collection/;post 262 /docs/collection;post/ 263 /docs/collection/&post 264 /post-service?path=/collection/ 266 The remainder of the document uses the same format just for 267 reasons of consistency; any other HTTP URI on the same server 268 would do as well. 270 3.2. Discovery 272 3.2.1. DAV:add-member Property (protected) 274 DAV:add-member is a protected property (see [RFC4918], Section 15) 275 defined on WebDAV collections, and contains the "Add-Member" URI for 276 that collection (embedded inside a DAV:href element). 278 279 281 A PROPFIND/allprop request SHOULD NOT return this property (see 282 [RFC4918], Section 9.1). Servers MUST implement the DAV:supported- 283 live-property-set property defined in Section 3.1.4 of [RFC3253], and 284 report the property DAV:add-member as a supported live property. 286 3.2.2. Example 288 >>Request 290 PROPFIND /collection/ HTTP/1.1 291 Host: example.com 292 Content-Type: application/xml; charset="utf-8" 293 Content-Length: 118 295 296 297 298 299 300 301 >>Response 303 HTTP/1.1 207 Multi-Status 304 Content-Type: application/xml; charset="utf-8" 305 Content-Length: 340 307 308 309 310 /collection/ 311 312 313 314 /collection;add-member/ 315 316 317 HTTP/1.1 200 OK 318 319 320 322 In this case, the server has minted a separate URI for the purpose of 323 adding new content. 325 3.3. Relation to AtomPub's 'Slug' Header Field 327 In the AtomPub protocol, clients can use the entity header field 328 "Slug" to suggest parts of the URI to be created (see [RFC5023], 329 Section 9.7). Note that servers are free to ignore this suggestion, 330 or to use whatever algorithm that makes sense to generate the new 331 URI. 333 The same applies to the extension defined here: clients can use the 334 "Slug" header field, as by definition it is a generic HTTP header 335 field. Servers should process it exactly in the way defined by 336 AtomPub. 338 3.4. Example Operation 340 >>Request 342 POST /collection;add-member/ HTTP/1.1 343 Host: example.com 344 Content-Type: text/plain 345 Slug: Sample Title 346 Content-Length: 12 348 Sample text. 350 >>Response 352 HTTP/1.1 201 Created 353 Location: http://example.com/collection/sample%20title 355 4. Additional Semantics for existing Methods 357 One important use case for this specification are collections that 358 act as WebDAV collections for the purpose of read access (PROPFIND 359 Depth 1/Infinity), but which only support internal member URIs 360 assigned by the server. These collections will not allow a client to 361 create a new member using methods like PUT, MKCOL, LOCK, COPY or 362 MOVE. Therefore, this specification defines a new precondition name 363 ([RFC4918], Section 16) that can be used to provide the client with 364 additional information about why exactly the request failed. 366 Note: although the precondition defined below can be used for 367 methods other than PUT, the "Add-Member" mechanism defined by this 368 specification deliberately is restricted to PUT. 370 4.1. Additional Preconditions 372 (DAV:allow-client-defined-URI): the server allows clients to specify 373 the last path segment for newly created resources. 375 The precondition element MAY contain an add-member-uri XML element 376 specifying the "Add-Member" URI associated with the collection, on 377 which the creation of a new child resource was attempted: 379 381 4.2. Example: Failed PUT Request 383 In this example, the client tries to use PUT to create a new internal 384 member of /collection/. 386 >>Request 388 PUT /collection/new.txt HTTP/1.1 389 Host: example.com 390 Content-Type: text/plain 391 Content-Length: 12 393 Sample text. 395 >>Response 397 HTTP/1.1 405 Method Not Allowed 398 Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE 399 Content-Type: application/xml; charset=UTF-8 400 Content-Length: 172 402 403 404 405 /collection;add-member/ 406 407 408 410 The request fails with a 405 (Method Not Allowed) status, but also 411 provides the reason, and a pointer to the "Add-Member" URI in the 412 response body. 414 5. Relationship to WebDAV Access Control Protocol 416 The WebDAV ACL specification requires the DAV:bind privilege to be 417 granted on a collection for the client to be able to add new 418 collection members ([RFC3744], Section 3.9). Consistent with that, a 419 server MUST reject a POST request to the Add-Member URI of a 420 collection unless the principal executing the request is granted DAV: 421 bind privilege on the associated WebDAV collection resource. 423 6. Internationalization Considerations 425 This document does not introduce any new internationalization 426 considerations beyond those discussed in Section 20 of [RFC4918]. 428 7. IANA Considerations 430 This specification does not require any actions from IANA. 432 8. Security Considerations 434 Security considerations applicable to HTTP [RFC2616], WebDAV 435 [RFC4918], and XML [XML] apply for this specification as well, 436 namely, Section 20 of [RFC4918] and Section 7 of [RFC3470]. 438 Furthermore, servers should be aware that deriving the member path 439 from the data being stored in the resource could potentially expose 440 confidential information. This could even be the case when only a 441 hash code of the content is used. 443 In addition, on servers that do not support this specification, a 444 malevolent user could set the DAV:add-member URI as a custom 445 property, tricking other users to post content to an entirely 446 different URI. Clients can protect themselves against this scenario 447 by 449 o not following DAV:add-member URIs to different servers, and/or 451 o verifying that the DAV:add-member property is indeed a live 452 property (this can be achieved by testing the DAV:supported-live- 453 property-set property, or by checking whether DAV:add-member is 454 returned upon PROPFIND/allprop) 456 9. Acknowledgements 458 This document has benefited from thoughtful discussion by Cyrus Daboo 459 and Bernard Desruisseaux. 461 10. References 463 10.1. Normative References 465 [RFC2119] Bradner, S., "Key words for use in 466 RFCs to Indicate Requirement Levels", 467 BCP 14, RFC 2119, March 1997. 469 [RFC2616] Fielding, R., Gettys, J., Mogul, J., 470 Frystyk, H., Masinter, L., Leach, P., 471 and T. Berners-Lee, "Hypertext 472 Transfer Protocol -- HTTP/1.1", 473 RFC 2616, June 1999. 475 [RFC3253] Clemm, G., Amsden, J., Ellison, T., 476 Kaler, C., and J. Whitehead, 477 "Versioning Extensions to WebDAV", 478 RFC 3253, March 2002. 480 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., 481 and J. Whitehead, "Web Distributed 482 Authoring and Versioning (WebDAV) 483 Access Control Protocol", RFC 3744, 484 May 2004. 486 [RFC4918] Dusseault, L., Ed., "HTTP Extensions 487 for Web Distributed Authoring and 488 Versioning (WebDAV)", RFC 4918, 489 June 2007. 491 [XML] Bray, T., Paoli, J., Sperberg- 492 McQueen, C., Maler, E., and F. 493 Yergeau, "Extensible Markup Language 494 (XML) 1.0 (Fifth Edition)", W3C REC- 495 xml-20081126, November 2008, . 499 10.2. Informative References 501 [RFC3470] Hollenbeck, S., Rose, M., and L. 502 Masinter, "Guidelines for the Use of 503 Extensible Markup Language (XML) 504 within IETF Protocols", RFC 3470, 505 BCP 70, January 2003. 507 [RFC4791] Daboo, C., Desruisseaux, B., and L. 508 Dusseault, "Calendaring Extensions to 509 WebDAV (CalDAV)", RFC 4791, 510 March 2007. 512 [RFC5023] Gregorio, J. and B. de hOra, "The 513 Atom Publishing Protocol", RFC 5023, 514 October 2007. 516 [draft-ietf-vcarddav-carddav] Daboo, C., "vCard Extensions to 517 WebDAV (CardDAV)", 518 draft-ietf-vcarddav-carddav-10 (work 519 in progress), November 2009. 521 [draft-reschke-http-addmember] Reschke, J., "The HTTP ADDMEMBER 522 Method", 523 draft-reschke-http-addmember-00 (work 524 in progress), February 2005. 526 Appendix A. Change Log (to be removed by RFC Editor before publication) 528 A.1. since draft-reschke-webdav-post-00 530 Added Acknowledgements. 532 Added and resolved issues "acl", "forbidden-put", "member-uri- 533 content", "post-error-semantics", "property-trust", "rational-server- 534 uri", ""remote-uri", "uri-format" and "uri-uniqueness". 536 A.2. since draft-reschke-webdav-post-01 538 Add and resolve issue "containment". 540 Update draft-ietf-vcarddav-carddav reference. 542 A.3. since draft-reschke-webdav-post-02 544 Update XML, draft-ietf-vcarddav-carddav and 545 draft-nottingham-http-link-header references. 547 Add and resolve issues "link-header" and "ns". 549 A.4. since draft-reschke-webdav-post-03 551 Add and resolve issues "put-only" and "protected". 553 A.5. since draft-reschke-webdav-post-04 555 Update vcarddav reference. In the example, do not use the same 556 content for Slug header field and request body. Add issue 557 "collection". 559 A.6. since draft-reschke-webdav-post-05 561 Close issue "collection" (not making the addition). 563 A.7. since draft-reschke-webdav-post-06 565 None yet. 567 A.8. since draft-reschke-webdav-post-07 569 Editorial improvements. 571 Appendix B. Resolved issues (to be removed by RFC Editor before 572 publication) 574 Issues that were either rejected or resolved in this version of this 575 document. 577 B.1. edit 579 Type: edit 581 julian.reschke@greenbytes.de (2008-09-22): Umbrella issue for 582 editorial fixes/enhancements. 584 Index 586 A 587 Add-Member URI 6 589 C 590 Condition Names 591 DAV:allow-client-defined-URI (pre) 9 592 COPY method 593 Additional Preconditions 9 595 D 596 DAV:allow-client-defined-URI 9 598 L 599 LOCK method 600 Additional Preconditions 9 602 M 603 MKCOL method 604 Additional Preconditions 9 605 MOVE method 606 Additional Preconditions 9 608 P 609 PUT method 610 Additional Preconditions 9 612 Author's Address 614 Julian F. Reschke 615 greenbytes GmbH 616 Hafenweg 16 617 Muenster, NW 48155 618 Germany 620 Phone: +49 251 2807760 621 EMail: julian.reschke@greenbytes.de 622 URI: http://greenbytes.de/tech/webdav/