idnits 2.17.1 draft-reschke-webdav-post-06.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 (April 8, 2010) is 5132 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 April 8, 2010 5 Expires: October 10, 2010 7 Using POST to add Members to Web Distributed Authoring and Versioning 8 (WebDAV) Collections 9 draft-reschke-webdav-post-06 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 October 10, 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 . . . . . . . . . . . . . . . 9 95 5. Relationship to WebDAV Access Control Protocol . . . . . . . . 10 96 6. Internationalization Considerations . . . . . . . . . . . . . 10 97 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 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 Appendix B. Resolved issues (to be removed by RFC Editor 112 before publication) . . . . . . . . . . . . . . . . . 13 113 B.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 114 B.2. collection . . . . . . . . . . . . . . . . . . . . . . . . 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 the identical to the 250 collection's URI (in which case the server just advertises the 251 fact that POST to the WebDAV collection's URI is supported as 252 defined within this specification). But it can also be different 253 from it, in which case it doesn't need to have any relation to the 254 collection's URI. 256 Given a collection URI of 258 /docs/collection/ 259 any of the URIs below might occur as "Add-Member" URIs: 261 /docs/collection/ 262 /docs/collection/;post 263 /docs/collection;post/ 264 /docs/collection/&post 265 /post-service?path=/collection/ 267 The remainder of the document uses the same format just for 268 reasons of consistency; any other HTTP URI on the same server 269 would do as well. 271 3.2. Discovery 273 3.2.1. DAV:add-member Property (protected) 275 DAV:add-member is a protected property (see [RFC4918], Section 15) 276 defined on WebDAV collections, and contains the "Add-Member" URI for 277 that collection (embedded inside a DAV:href element). 279 280 282 A PROPFIND/allprop request SHOULD NOT return this property (see 283 [RFC4918], Section 9.1). Servers MUST implement the DAV:supported- 284 live-property-set property defined in Section 3.1.4 of [RFC3253], and 285 report the property DAV:add-member as a supported live property. 287 3.2.2. Example 289 >>Request 291 PROPFIND /collection/ HTTP/1.1 292 Host: example.com 293 Content-Type: application/xml; charset="utf-8" 294 Content-Length: 118 296 297 298 299 300 301 302 >>Response 304 HTTP/1.1 207 Multi-Status 305 Content-Type: application/xml; charset="utf-8" 306 Content-Length: 340 308 309 310 311 /collection/ 312 313 314 315 /collection;add-member/ 316 317 318 HTTP/1.1 200 OK 319 320 321 323 Note that in this case, the server has minted a separate URI for the 324 purpose of adding new content. 326 3.3. Relation to AtomPub's 'Slug' Header Field 328 In the AtomPub protocol, clients can use the entity header field 329 "Slug" to suggest parts of the URI to be created (see [RFC5023], 330 Section 9.7). Note that servers are free to ignore this suggestion, 331 or to use whatever algorithm that makes sense to generate the new 332 URI. 334 The same applies to the extension defined here: clients can use the 335 "Slug" header field as by its definition of a generic HTTP header 336 field. Servers should process it exactly in the way defined by 337 AtomPub. 339 3.4. Example Operation 341 >>Request 343 POST /collection;add-member/ HTTP/1.1 344 Host: example.com 345 Content-Type: text/plain 346 Slug: Sample Title 347 Content-Length: 12 349 Sample text. 351 >>Response 353 HTTP/1.1 201 Created 354 Location: http://example.com/collection/sample%20title 356 4. Additional Semantics for existing Methods 358 One important use case for this specification are collections that 359 act as WebDAV collections for the purpose of read access (PROPFIND 360 Depth 1/Infinity), but which only support internal member URIs 361 assigned by the server. These collections will not allow a client to 362 create a new member using methods like PUT, MKCOL, LOCK, COPY or 363 MOVE. Therefore, this specification defines a new precondition name 364 ([RFC4918], Section 16) that can be used to provide the client with 365 additional information about why exactly the request failed. 367 Note: although the precondition defined below can be used for 368 methods other than PUT, the "Add-Member" mechanism defined by this 369 specification deliberately is restricted to PUT. 371 4.1. Additional Preconditions 373 (DAV:allow-client-defined-URI): the server allows clients to specify 374 the last path segment for newly created resources. 376 The precondition element MAY contain a add-member-uri XML element 377 specifying the "Add-Member" URI associated with the collection, on 378 which the creation of a new child resource was attempted: 380 382 4.2. Example: Failed PUT Request 384 In this example, the client tries to use PUT to create a new internal 385 member of /collection/. 387 >>Request 389 PUT /collection/new.txt HTTP/1.1 390 Host: example.com 391 Content-Type: text/plain 392 Content-Length: 12 394 Sample text. 396 >>Response 398 HTTP/1.1 405 Method Not Allowed 399 Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE 400 Content-Type: application/xml; charset=UTF-8 401 Content-Length: 172 403 404 405 406 /collection;add-member/ 407 408 409 411 The request fails with a 405 (Method Not Allowed) status, but also 412 provides the reason, and a pointer to the "Add-Member" URI in the 413 response body. 415 5. Relationship to WebDAV Access Control Protocol 417 The WebDAV ACL specification requires the DAV:bind privilege to be 418 granted on a collection for the client to be able add new collection 419 members ([RFC3744], Section 3.9). Consistent with that, a server 420 MUST reject a POST request to the Add-Member URI of a collection 421 unless the principal executing the request is granted DAV:bind 422 privilege on the associated WebDAV collection resource. 424 6. Internationalization Considerations 426 This document does not introduce any new internationalization 427 considerations beyond those discussed in Section 20 of [RFC4918]. 429 7. IANA Considerations 431 This specification does not require any actions from IANA. 433 8. Security Considerations 435 Security considerations applicable to HTTP/WebDAV and XML apply for 436 this specification as well, namely, [RFC4918] (Section 20) and 437 [RFC3470] (Section 7). 439 Furthermore, servers should be aware that deriving the member path 440 from the data being stored in the resource could potentially expose 441 confidential information. This could even be the case when only a 442 hash code of the content is used. 444 In addition, on servers that do not support this specification, a 445 malevolent user could set the DAV:add-member URI as a custom 446 property, tricking other users to post content to an entirely 447 different URI. Clients can protect themselves against this scenario 448 by 450 o not following DAV:add-member URIs to different servers, and/or 452 o verifying that the DAV:add-member property is indeed a live 453 property (this can be achieved by testing the DAV:supported-live- 454 property-set property, or by checking whether DAV:add-member is 455 returned upon PROPFIND/allprop) 457 9. Acknowledgements 459 This document has benefited from thoughtful discussion by Cyrus Daboo 460 and Bernard Desruissaux. 462 10. References 464 10.1. Normative References 466 [RFC2119] Bradner, S., "Key words for use in 467 RFCs to Indicate Requirement Levels", 468 BCP 14, RFC 2119, March 1997. 470 [RFC2616] Fielding, R., Gettys, J., Mogul, J., 471 Frystyk, H., Masinter, L., Leach, P., 472 and T. Berners-Lee, "Hypertext 473 Transfer Protocol -- HTTP/1.1", 474 RFC 2616, June 1999. 476 [RFC3253] Clemm, G., Amsden, J., Ellison, T., 477 Kaler, C., and J. Whitehead, 478 "Versioning Extensions to WebDAV", 479 RFC 3253, March 2002. 481 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., 482 and J. Whitehead, "Web Distributed 483 Authoring and Versioning (WebDAV) 484 Access Control Protocol", RFC 3744, 485 May 2004. 487 [RFC4918] Dusseault, L., Ed., "HTTP Extensions 488 for Web Distributed Authoring and 489 Versioning (WebDAV)", RFC 4918, 490 June 2007. 492 [XML] Bray, T., Paoli, J., Sperberg- 493 McQueen, C., Maler, E., and F. 494 Yergeau, "Extensible Markup Language 495 (XML) 1.0 (Fifth Edition)", W3C REC- 496 xml-20081126, November 2008, . 500 10.2. Informative References 502 [RFC3470] Hollenbeck, S., Rose, M., and L. 503 Masinter, "Guidelines for the Use of 504 Extensible Markup Language (XML) 505 within IETF Protocols", RFC 3470, 506 BCP 70, January 2003. 508 [RFC4791] Daboo, C., Desruisseaux, B., and L. 509 Dusseault, "Calendaring Extensions to 510 WebDAV (CalDAV)", RFC 4791, 511 March 2007. 513 [RFC5023] Gregorio, J. and B. de hOra, "The 514 Atom Publishing Protocol", RFC 5023, 515 October 2007. 517 [draft-ietf-vcarddav-carddav] Daboo, C., "vCard Extensions to 518 WebDAV (CardDAV)", 519 draft-ietf-vcarddav-carddav-10 (work 520 in progress), November 2009. 522 [draft-reschke-http-addmember] Reschke, J., "The HTTP ADDMEMBER 523 Method", 524 draft-reschke-http-addmember-00 (work 525 in progress), February 2005. 527 Appendix A. Change Log (to be removed by RFC Editor before publication) 529 A.1. since draft-reschke-webdav-post-00 531 Added Acknowledgements. 533 Added and resolved issues "acl", "forbidden-put", "member-uri- 534 content", "post-error-semantics", "property-trust", "rational-server- 535 uri", ""remote-uri", "uri-format" and "uri-uniqueness". 537 A.2. since draft-reschke-webdav-post-01 539 Add and resolve issue "containment". 541 Update draft-ietf-vcarddav-carddav reference. 543 A.3. since draft-reschke-webdav-post-02 545 Update XML, draft-ietf-vcarddav-carddav and 546 draft-nottingham-http-link-header references. 548 Add and resolve issues "link-header" and "ns". 550 A.4. since draft-reschke-webdav-post-03 552 Add and resolve issues "put-only" and "protected". 554 A.5. since draft-reschke-webdav-post-04 556 Update vcarddav reference. In the example, do not use the same 557 content for Slug header field and request body. Add issue 558 "collection". 560 A.6. since draft-reschke-webdav-post-05 562 Close issue "collection" (not making the addition). 564 Appendix B. Resolved issues (to be removed by RFC Editor before 565 publication) 567 Issues that were either rejected or resolved in this version of this 568 document. 570 B.1. edit 572 Type: edit 574 julian.reschke@greenbytes.de (2008-09-22): Umbrella issue for 575 editorial fixes/enhancements. 577 B.2. collection 579 Type: change 581 cyrus@daboo.name (2009-11-05): I have heard from some implementors 582 that they would like collection creation to also be part of this 583 draft. In particular, CalDAV and/or CardDAV clients creating 584 calendars or address books would prefer to leave specification of the 585 resource name to the client. 586 Proposal: 587 - Add a DAV:add-collection property containing a URI (which must be 588 different than DAV:add-member) 589 - A POST on that URI creates a collection within the parent 590 collection, with a server chosen resource name 591 - If the POST contains an XML body with DAV:mkcol as the root 592 element, then that body is interpreted the same way as MKCOL ext. 594 Resolution (2010-04-08): There was no sufficient interest for adding 595 this feature at this point. Furthermore, this can be defined in a 596 future extension spec when needed. 598 Index 600 A 601 Add-Member URI 6 603 C 604 Condition Names 605 DAV:allow-client-defined-URI (pre) 9 606 COPY method 607 Additional Preconditions 9 609 D 610 DAV:allow-client-defined-URI 9 612 L 613 LOCK method 614 Additional Preconditions 9 616 M 617 MKCOL method 618 Additional Preconditions 9 619 MOVE method 620 Additional Preconditions 9 622 P 623 PUT method 624 Additional Preconditions 9 626 Author's Address 628 Julian F. Reschke 629 greenbytes GmbH 630 Hafenweg 16 631 Muenster, NW 48155 632 Germany 634 Phone: +49 251 2807760 635 EMail: julian.reschke@greenbytes.de 636 URI: http://greenbytes.de/tech/webdav/