idnits 2.17.1 draft-reschke-webdav-post-07.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 7, 2010) is 5103 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 7, 2010 5 Expires: November 8, 2010 7 Using POST to add Members to Web Distributed Authoring and Versioning 8 (WebDAV) Collections 9 draft-reschke-webdav-post-07 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 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 8, 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 Appendix B. Resolved issues (to be removed by RFC Editor 113 before publication) . . . . . . . . . . . . . . . . . 13 114 B.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 115 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 117 1. Introduction 119 The Hypertext Transfer Protocol (HTTP) Extensions for the Web 120 Distributed Authoring and Versioning (WebDAV) ([RFC4918], Section 121 9.5) do not define the behavior for the "POST" method when applied to 122 collections, as the base specification (HTTP) leaves implementers 123 lots of freedom for the semantics of "POST": 125 9.5 POST for Collections 127 Since by definition the actual function performed by POST is 128 determined by the server and often depends on the particular 129 resource, the behavior of POST when applied to collections cannot 130 be meaningfully modified because it is largely undefined. Thus, 131 the semantics of POST are unmodified when applied to a collection. 133 This has led to a situation where many WebDAV servers do not 134 implement POST for collections at all, although it is well suited to 135 be used for the purpose of adding new members to a collection, where 136 the server remains in control of the newly assigned URL. As a matter 137 of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for 138 that purpose ([RFC5023], Section 9.2): 140 9.2 Creating Resources with POST 142 To add members to a Collection, clients send POST requests to the 143 URI of the Collection. 145 On the other hand, WebDAV-based protocols such as Calendaring 146 Extensions to WebDAV (CalDAV) frequently require clients to pick a 147 unique URL, although the server could easily perform that task 148 ([RFC4791], Section 5.3.2): 150 5.3.2 Creating Calendar Object Resources 152 ... 154 When servers create new resources, it's not hard for the server to 155 choose an unmapped URI. It's slightly tougher for clients, 156 because a client might not want to examine all resources in the 157 collection and might not want to lock the entire collection to 158 ensure that a new resource isn't created with a name collision. 159 (...) 161 As a matter of fact, letting the server choose the member URI not 162 only is a simplification for certain types of clients, but can also 163 reduce the complexity of the server (in that it doesn't need to 164 persist an additional client-supplied identifier where it already has 165 an internal one like a UUID or a primary key). 167 Note: the vCard Extensions to WebDAV (CardDAV) 168 ([draft-ietf-vcarddav-carddav]) suffer from the same issue, and 169 may be able to take advantage of this specification. 171 This specification defines a discovery mechanism through which 172 servers can advertise support for POST requests with the 173 aforementioned "add collection member" semantics. 175 Note that this specification deliberately only adresses the use case 176 of creating new non-collection resources, and that it was not a goal 177 to supply the same functionality for creating collection resources 178 (MKCOL), or for other operations that require the client to specify a 179 new URL (LOCK, MOVE, or COPY). 181 Note: the author previously proposed a new HTTP method for exactly 182 this purpose ([draft-reschke-http-addmember]), but quite a few 183 reviewers pointed out that this would duplicate the original 184 semantics of POST. Thus this proposal that avoids adding a new 185 HTTP method is made. 187 2. Terminology 189 The terminology used here follows that in the WebDAV specification 190 ([RFC4918]). 192 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 193 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 194 document are to be interpreted as described in [RFC2119]. 196 This document uses XML DTD fragments ([XML]) as a purely notational 197 convention. In particular: 199 o Element ordering is irrelevant. 201 o Extension elements/attributes (elements/attributes not already 202 defined as valid child elements) may be added anywhere, except 203 when explicitly stated otherwise. 205 Note: this specification defines new properties and precondition 206 names in the "DAV:" namespace, which the WebDAV specification 207 reserves for use by the IETF ([RFC4918], Section 21.1). However, 208 there was rough consensus in the WebDAV community that the 209 specification is of general applicability to other WebDAV related 210 standards efforts, and thus deserves inclusion into the base 211 namespace. 213 3. Protocol Extension 215 Due to the reasons stated in Section 1, clients can not rely on a 216 specific server behavior when POST is applied to a collection. This 217 problem is addressed by this specification by allowing servers to 218 advertise a URI that has the desired "add member" semantics. 220 Note that servers that already use POST for a different purpose can 221 just expose a separate URI. Other servers can just advertise the 222 collection's own URI, thus avoiding minting another URI for a limited 223 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 Note that in this case, the server has minted a separate URI for the 323 purpose of 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/WebDAV and XML apply for 435 this specification as well, namely, [RFC4918] (Section 20) and 436 [RFC3470] (Section 7). 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 Appendix B. Resolved issues (to be removed by RFC Editor before 568 publication) 570 Issues that were either rejected or resolved in this version of this 571 document. 573 B.1. edit 575 Type: edit 577 julian.reschke@greenbytes.de (2008-09-22): Umbrella issue for 578 editorial fixes/enhancements. 580 Index 582 A 583 Add-Member URI 6 585 C 586 Condition Names 587 DAV:allow-client-defined-URI (pre) 9 588 COPY method 589 Additional Preconditions 9 591 D 592 DAV:allow-client-defined-URI 9 594 L 595 LOCK method 596 Additional Preconditions 9 598 M 599 MKCOL method 600 Additional Preconditions 9 601 MOVE method 602 Additional Preconditions 9 604 P 605 PUT method 606 Additional Preconditions 9 608 Author's Address 610 Julian F. Reschke 611 greenbytes GmbH 612 Hafenweg 16 613 Muenster, NW 48155 614 Germany 616 Phone: +49 251 2807760 617 EMail: julian.reschke@greenbytes.de 618 URI: http://greenbytes.de/tech/webdav/