idnits 2.17.1 draft-reschke-webdav-post-04.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 (January 12, 2009) is 5583 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 January 12, 2009 5 Expires: July 16, 2009 7 Using POST to add Members to Web Distributed Authoring and Versioning 8 (WebDAV) Collections 9 draft-reschke-webdav-post-04 11 Status of this Memo 13 This Internet-Draft is submitted to IETF in full conformance with the 14 provisions of BCP 78 and BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on July 16, 2009. 34 Copyright Notice 36 Copyright (c) 2009 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. 46 Abstract 48 The Hypertext Transfer Protocol (HTTP) Extensions for the Web 49 Distributed Authoring and Versioning (WebDAV) do not define the 50 behavior for the "POST" method when applied to collections, as the 51 base specification (HTTP) leaves implementers lots of freedom for the 52 semantics of "POST". 54 This has led to a situation where many WebDAV servers do not 55 implement POST for collections at all, although it is well suited to 56 be used for the purpose of adding new members to a collection, where 57 the server remains in control of the newly assigned URL. As a matter 58 of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for 59 that purpose. On the other hand, WebDAV-based protocols such as the 60 Calendar Extensions to WebDAV (CalDAV) frequently require clients to 61 pick a unique URL, although the server could easily perform that 62 task. 64 This specification defines a discovery mechanism through which 65 servers can advertise support for POST requests with the 66 aforementioned "add collection member" semantics. 68 Editorial Note (To be removed by RFC Editor before publication) 70 Please send comments to the Distributed Authoring and Versioning 71 (WebDAV) working group at , which may be 72 joined by sending a message with subject "subscribe" to 73 . Discussions of the WEBDAV 74 working group are archived at 75 . 77 Note that although discussion takes place on the WebDAV working 78 group's mailing list, this is not a working group document. 80 XML versions, latest edits and the issues list for this document are 81 available from 82 . 84 Table of Contents 86 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 87 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 88 3. Protocol Extension . . . . . . . . . . . . . . . . . . . . . . 6 89 3.1. Definition of 'Add-Member' URI . . . . . . . . . . . . . . 6 90 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 7 91 3.2.1. DAV:add-member Property (protected) . . . . . . . . . 7 92 3.2.2. Example . . . . . . . . . . . . . . . . . . . . . . . 7 93 3.3. Relation to AtomPub's 'Slug' Header . . . . . . . . . . . 8 94 3.4. Example Operation . . . . . . . . . . . . . . . . . . . . 8 95 4. Additional Semantics for existing Methods . . . . . . . . . . 9 96 4.1. Additional Preconditions . . . . . . . . . . . . . . . . . 9 97 4.2. Example: Failed PUT Request . . . . . . . . . . . . . . . 9 98 5. Relationship to WebDAV Access Control Protocol . . . . . . . . 10 99 6. Internationalization Considerations . . . . . . . . . . . . . 10 100 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 101 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 102 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 103 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 104 10.1. Normative References . . . . . . . . . . . . . . . . . . . 11 105 10.2. Informative References . . . . . . . . . . . . . . . . . . 12 106 Appendix A. Change Log (to be removed by RFC Editor before 107 publication) . . . . . . . . . . . . . . . . . . . . 12 108 A.1. since draft-reschke-webdav-post-00 . . . . . . . . . . . . 12 109 A.2. since draft-reschke-webdav-post-01 . . . . . . . . . . . . 12 110 A.3. since draft-reschke-webdav-post-02 . . . . . . . . . . . . 12 111 A.4. since draft-reschke-webdav-post-03 . . . . . . . . . . . . 13 112 Appendix B. Resolved issues (to be removed by RFC Editor 113 before publication) . . . . . . . . . . . . . . . . . 13 114 B.1. protected . . . . . . . . . . . . . . . . . . . . . . . . 13 115 B.2. put-only . . . . . . . . . . . . . . . . . . . . . . . . . 13 116 Appendix C. Open issues (to be removed by RFC Editor prior to 117 publication) . . . . . . . . . . . . . . . . . . . . 13 118 C.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 119 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 120 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 122 1. Introduction 124 The Hypertext Transfer Protocol (HTTP) Extensions for the Web 125 Distributed Authoring and Versioning (WebDAV) ([RFC4918], Section 126 9.5) do not define the behavior for the "POST" method when applied to 127 collections, as the base specification (HTTP) leaves implementers 128 lots of freedom for the semantics of "POST": 130 9.5 POST for Collections 132 Since by definition the actual function performed by POST is 133 determined by the server and often depends on the particular 134 resource, the behavior of POST when applied to collections cannot 135 be meaningfully modified because it is largely undefined. Thus, 136 the semantics of POST are unmodified when applied to a collection. 138 This has led to a situation where many WebDAV servers do not 139 implement POST for collections at all, although it is well suited to 140 be used for the purpose of adding new members to a collection, where 141 the server remains in control of the newly assigned URL. As a matter 142 of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for 143 that purpose ([RFC5023], Section 9.2): 145 9.2 Creating Resources with POST 147 To add members to a Collection, clients send POST requests to the 148 URI of the Collection. 150 On the other hand, WebDAV-based protocols such as Calendaring 151 Extensions to WebDAV (CalDAV) frequently require clients to pick a 152 unique URL, although the server could easily perform that task 153 ([RFC4791], Section 5.3.2): 155 5.3.2 Creating Calendar Object Resources 157 ... 159 When servers create new resources, it's not hard for the server to 160 choose an unmapped URI. It's slightly tougher for clients, 161 because a client might not want to examine all resources in the 162 collection and might not want to lock the entire collection to 163 ensure that a new resource isn't created with a name collision. 164 (...) 166 As a matter of fact, letting the server choose the member URI not 167 only is a simplification for certain types of clients, but can also 168 reduce the complexity of the server (in that it doesn't need to 169 persist an additional client-supplied identifier where it already has 170 an internal one like a UUID or a primary key). 172 Note: the vCard Extensions to WebDAV (CardDAV) 173 ([draft-ietf-vcarddav-carddav]) suffer from the same issue, and 174 may be able to take advantage of this specification. 176 This specification defines a discovery mechanism through which 177 servers can advertise support for POST requests with the 178 aforementioned "add collection member" semantics. 180 Note that this specification deliberately only adresses the use case 181 of creating new non-collection resources, and that it was not a goal 182 to supply the same functionality for creating collection resources 183 (MKCOL), or for other operations that require the client to specify a 184 new URL (LOCK, MOVE, or COPY). 186 Note: the author previously proposed a new HTTP method for exactly 187 this purpose ([draft-reschke-http-addmember]), but quite a few 188 reviewers pointed out that this would duplicate the original 189 semantics of POST. Thus this proposal that avoids adding a new 190 HTTP method is made. 192 2. Terminology 194 The terminology used here follows that in the WebDAV specification 195 ([RFC4918]). 197 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 198 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 199 document are to be interpreted as described in [RFC2119]. 201 This document uses XML DTD fragments ([XML]) as a purely notational 202 convention. In particular: 204 o Element ordering is irrelevant. 206 o Extension elements/attributes (elements/attributes not already 207 defined as valid child elements) may be added anywhere, except 208 when explicitly stated otherwise. 210 Note: this specification defines new properties and precondition 211 names in the "DAV:" namespace, which the WebDAV specification 212 reserves for use by the IETF ([RFC4918], Section 21.1). However, 213 there was rough consensus in the WebDAV community that the 214 specification is of general applicability to other WebDAV related 215 standards efforts, and thus deserves inclusion into the base 216 namespace. 218 3. Protocol Extension 220 Due to the reasons stated in Section 1, clients can not rely on a 221 specific server behavior when POST is applied to a collection. This 222 problem is addressed by this specification by allowing servers to 223 advertise a URI that has the desired "add member" semantics. 225 Note that servers that already use POST for a different purpose can 226 just expose a separate URI. Other servers can just advertise the 227 collection's own URI, thus avoiding minting another URI for a limited 228 purpose. 230 3.1. Definition of 'Add-Member' URI 232 The "Add-Member" URI of a WebDAV collection is a URI that will accept 233 HTTP POST requests, and will interpret these as requests to store the 234 enclosed entity as a new internal member of the collection (see 235 Section 3 of [RFC4918] for the definition of "internal member"). It 236 MUST identify a resource on the same server as the WebDAV collection 237 (the host and port components ([RFC2616], Section 3.2.2) of the URIs 238 must match). 240 If there are pre-conditions related to creating a resource in the 241 collection using a PUT request, then those same pre-conditions apply 242 to the new POST request behavior, and the same HTTP response body 243 will returned on failure. 245 The URI of the newly created resource is returned in the HTTP 246 Location response header ([RFC2616], Section 14.30). 248 Note: the fact that a server advertises an "Add-Member" URI does 249 not imply any special semantics of the collection itself. For 250 instance, member URIs assigned by the server are not necessarily 251 unique over time (a member URI may be assigned again to a new 252 resource when it previously was removed). 254 Note: the "Add-Member" URI can be the identical to the 255 collection's URI (in which case the server just advertises the 256 fact that POST to the WebDAV collection's URI is supported as 257 defined within this specification). But it can also be different 258 from it, in which case it doesn't need to have any relation to the 259 collection's URI. 261 Given a collection URI of 263 /docs/collection/ 264 all of the URIs below might occur as "Add-Member" URIs: 266 /docs/collection/ 267 /docs/collection/;post 268 /docs/collection;post/ 269 /docs/collection/&post 270 /post-service?path=/collection/ 272 The remainder of the document uses the same format just for 273 reasons of consistency; any other HTTP URI on the same server 274 would do as well. 276 3.2. Discovery 278 3.2.1. DAV:add-member Property (protected) 280 DAV:add-member is a protected property (see [RFC4918], Section 15) 281 defined on WebDAV collections, and contains the "Add-Member" URI for 282 that collection (embedded inside a DAV:href element). 284 285 287 A PROPFIND/allprop request SHOULD NOT return this property (see 288 [RFC4918], Section 9.1). Servers MUST implement the DAV:supported- 289 live-property-set property defined in Section 3.1.4 of [RFC3253], and 290 report the property DAV:add-member as a supported live property. 292 3.2.2. Example 294 >>Request 296 PROPFIND /collection/ HTTP/1.1 297 Host: example.com 298 Content-Type: application/xml; charset="utf-8" 299 Content-Length: 118 301 302 303 304 305 306 307 >>Response 309 HTTP/1.1 207 Multi-Status 310 Content-Type: application/xml; charset="utf-8" 311 Content-Length: 340 313 314 315 316 /collection/ 317 318 319 320 /collection;add-member/ 321 322 323 HTTP/1.1 200 OK 324 325 326 328 Note that in this case, the server has minted a separate URI for the 329 purpose of adding new content. 331 3.3. Relation to AtomPub's 'Slug' Header 333 In the AtomPub protocol, clients can use the entity header "Slug" to 334 suggest parts of the URI to be created (see [RFC5023], Section 9.7). 335 Note that servers are free to ignore this suggestion, or to use 336 whatever algorithm that makes sense to generate the new URI. 338 The same applies to the extension defined here: clients can use the 339 "Slug" header as by its definition of a generic HTTP header. Servers 340 should process it exactly the way defined by AtomPub. 342 3.4. Example Operation 344 >>Request 346 POST /collection;add-member/ HTTP/1.1 347 Host: example.com 348 Content-Type: text/plain 349 Slug: Sample Text 350 Content-Length: 12 352 Sample text. 354 >>Response 356 HTTP/1.1 201 Created 357 Location: http://example.com/collection/sample%20text 359 4. Additional Semantics for existing Methods 361 One important use case for this specification are collections that 362 act as WebDAV collections for the purpose of read access (PROPFIND 363 Depth 1/Infinity), but which only support internal member URIs 364 assigned by the server. These collections will not allow a client to 365 create a new member using methods like PUT, MKCOL, LOCK, COPY or 366 MOVE. Therefore, this specification defines a new precondition name 367 ([RFC4918], Section 16) that can be used to provide the client with 368 additional information about why exactly the request failed. 370 Note: although the precondition defined below can be used for 371 methods other than PUT, the "Add-Member" mechanism defined by this 372 specification deliberately is restricted to PUT. 374 4.1. Additional Preconditions 376 (DAV:allow-client-defined-URI): the server allows clients to specify 377 the last path segment for newly created resources. 379 The precondition element MAY contain a add-member-uri XML element 380 specifying the "Add-Member" URI associated with the collection, on 381 which the creation of a new child resource was attempted: 383 385 4.2. Example: Failed PUT Request 387 In this example, the client tries to use PUT to create a new internal 388 member of /collection/. 390 >>Request 392 PUT /collection/new.txt HTTP/1.1 393 Host: example.com 394 Content-Type: text/plain 395 Content-Length: 12 397 Sample text. 399 >>Response 401 HTTP/1.1 405 Method Not Allowed 402 Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE 403 Content-Type: application/xml; charset=UTF-8 404 Content-Length: 172 406 407 408 409 /collection;add-member/ 410 411 412 414 The request fails with a 405 (Method Not Allowed) status, but also 415 provides the reason, and a pointer to the "Add-Member" URI in the 416 response body. 418 5. Relationship to WebDAV Access Control Protocol 420 The WebDAV ACL specification requires the DAV:bind privilege to be 421 granted on a collection for the client to be able add new collection 422 members ([RFC3744], Section 3.9). Consistent with that, a server 423 MUST reject a POST request to the Add-Member URI of a collection 424 unless the principal executing the request is granted DAV:bind 425 privilege on the associated WebDAV collection resource. 427 6. Internationalization Considerations 429 This document does not introduce any new internationalization 430 considerations beyond those discussed in Section 20 of [RFC4918]. 432 7. IANA Considerations 434 This specification does not require any actions from IANA. 436 8. Security Considerations 438 All security considerations connected to HTTP/WebDAV and XML apply 439 for this specification as well, namely, [RFC4918] (Section 20) and 440 [RFC3470] (Section 7). 442 Furthermore, servers should be aware that deriving the member path 443 from the data being stored in the resource could potentially expose 444 confidential information. This could even be the case when only a 445 hash code of the content is used. 447 In addition, on servers that do not support this specification, a 448 malevolent user could set the DAV:add-member URI as a custom 449 property, tricking other users to post content to an entirely 450 different URI. Clients can protect themselves against this scenario 451 by 453 o not following DAV:add-member URIs to different servers, and/or 455 o verifying that the DAV:add-member property is indeed a live 456 property (this can be achieved by testing the DAV:supported-live- 457 property-set property, or by checking whether DAV:add-member is 458 returned upon PROPFIND/allprop) 460 9. Acknowledgements 462 This document has benefited from thoughtful discussion by Cyrus Daboo 463 and Bernard Desruissaux. 465 10. References 467 10.1. Normative References 469 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 470 Requirement Levels", BCP 14, RFC 2119, March 1997. 472 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 473 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 474 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 476 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 477 Whitehead, "Versioning Extensions to WebDAV", RFC 3253, 478 March 2002. 480 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web 481 Distributed Authoring and Versioning (WebDAV) Access 482 Control Protocol", RFC 3744, May 2004. 484 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 485 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 487 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 488 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 489 Edition)", W3C REC-xml-20081126, November 2008, 490 . 492 10.2. Informative References 494 [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for 495 the Use of Extensible Markup Language (XML) within IETF 496 Protocols", RFC 3470, BCP 70, January 2003. 498 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 499 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 500 March 2007. 502 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 503 Protocol", RFC 5023, October 2007. 505 [draft-ietf-vcarddav-carddav] 506 Daboo, C., "vCard Extensions to WebDAV (CardDAV)", 507 draft-ietf-vcarddav-carddav-03 (work in progress), 508 November 2008. 510 [draft-reschke-http-addmember] 511 Reschke, J., "The HTTP ADDMEMBER Method", 512 draft-reschke-http-addmember-00 (work in progress), 513 February 2005. 515 Appendix A. Change Log (to be removed by RFC Editor before publication) 517 A.1. since draft-reschke-webdav-post-00 519 Added Acknowledgements. 521 Added and resolved issues "acl", "forbidden-put", "member-uri- 522 content", "post-error-semantics", "property-trust", "rational-server- 523 uri", ""remote-uri", "uri-format" and "uri-uniqueness". 525 A.2. since draft-reschke-webdav-post-01 527 Add and resolve issue "containment". 529 Update draft-ietf-vcarddav-carddav reference. 531 A.3. since draft-reschke-webdav-post-02 533 Update XML, draft-ietf-vcarddav-carddav and 534 draft-nottingham-http-link-header references. 536 Add and resolve issues "link-header" and "ns". 538 A.4. since draft-reschke-webdav-post-03 540 Add and resolve issues "put-only" and "protected". 542 Appendix B. Resolved issues (to be removed by RFC Editor before 543 publication) 545 Issues that were either rejected or resolved in this version of this 546 document. 548 B.1. protected 550 Type: change 552 julian.reschke@greenbytes.de (2009-01-08): State that the property is 553 protected. 555 Resolution: Done. 557 B.2. put-only 559 Type: edit 561 julian.reschke@greenbytes.de (2009-01-08): Clarify that this is only 562 for PUT-to-create, not COPY/MOVE/LOCK/MKCOL. 564 Appendix C. Open issues (to be removed by RFC Editor prior to 565 publication) 567 C.1. edit 569 Type: edit 571 julian.reschke@greenbytes.de (2008-09-22): Umbrella issue for 572 editorial fixes/enhancements. 574 Index 576 A 577 Add-Member URI 6 579 C 580 Condition Names 581 DAV:allow-client-defined-URI (pre) 9 582 COPY method 583 Additional Preconditions 9 585 D 586 DAV:allow-client-defined-URI 9 588 L 589 LOCK method 590 Additional Preconditions 9 592 M 593 MKCOL method 594 Additional Preconditions 9 595 MOVE method 596 Additional Preconditions 9 598 P 599 PUT method 600 Additional Preconditions 9 602 Author's Address 604 Julian F. Reschke 605 greenbytes GmbH 606 Hafenweg 16 607 Muenster, NW 48155 608 Germany 610 Phone: +49 251 2807760 611 Email: julian.reschke@greenbytes.de 612 URI: http://greenbytes.de/tech/webdav/