Network Working GroupJ. Reschke
Internet-Draftgreenbytes
Intended status: Standards TrackOctober 2, 2008
Expires: April 5, 2009

Using POST to add  I Members to Web Distributed Authoring and Versioning (WebDAV) Collections
draft-reschke-webdav-post-01

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on April 5, 2009.

Abstract

The Hypertext Transfer Protocol (HTTP) Extensions for the Web Distributed Authoring and Versioning (WebDAV) do not define the behavior for the "POST" method when applied to collections, as the base specification (HTTP) leaves implementers lots of freedom for the semantics of "POST".

This has lead to a situation where many WebDAV servers do not implement POST for collections at all, although it is well suited to be used for the purpose of adding new members to a collection, where the server remains in control of the newly assigned URL. As a matter of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose. On the other hand, WebDAV-based protocols such as the Calendar Extensions to WebDAV (CalDAV) frequently require clients to pick a unique URL, although the server could easily perform that task.

This specification defines a discovery mechanism through which servers can advertise support for POST requests with the aforementioned "add collection member" semantics.

Editorial Note (To be removed by RFC Editor before publication)

Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at <mailto:w3c-dist-auth@w3.org>, which may be joined by sending a message with subject "subscribe" to <mailto:w3c-dist-auth-request@w3.org>. Discussions of the WEBDAV working group are archived at <http://lists.w3.org/Archives/Public/w3c-dist-auth/>.

Note that although discussion takes place on the WebDAV working group's mailing list, this is not a working group document.

XML versions, latest edits and the issues list for this document are available from <http://greenbytes.de/tech/webdav/#draft-reschke-webdav-post>.


Table of Contents

Issues list

IdTypeStatusDateRaised By
aclchangeclosed2008-09-23cyrus@daboo.name
forbidden-putchangeclosed2008-09-23cyrus@daboo.name
member-uri-contentchangeclosed2008-09-22cyrus@daboo.name
post-error-semanticschangeclosed2008-09-22cyrus@daboo.name
property-trustchangeclosed2008-10-01julian.reschke@greenbytes.de
rational-server-urichangeclosed2008-09-22cyrus@daboo.name
remote-urichangeclosed2008-09-30julian.reschke@greenbytes.de
uri-formatchangeclosed2008-09-23cyrus@daboo.name
uri-uniquenesschangeclosed2008-09-22cyrus@daboo.name
editeditopen2008-09-22julian.reschke@greenbytes.de
 I  edit   (type: edit, status: open)
julian.reschke@greenbytes.de2008-09-22 Umbrella issue for editorial fixes/enhancements.
Associated changes in this document: <#rfc.change.edit.1>, 3, 3, 3.1, 3.1, 3.2.2, 3.2.3, 3.2.3, 3.2.3, 3.4, <#rfc.change.edit.11>, <#rfc.change.edit.12>.

1. Introduction

The Hypertext Transfer Protocol (HTTP) Extensions for the Web Distributed Authoring and Versioning (WebDAV) ([RFC4918], Section 9.5) do not define the behavior for the "POST" method when applied to collections, as the base specification (HTTP) leaves implementers lots of freedom for the semantics of "POST":

9.5 POST for Collections

Since by definition the actual function performed by POST is determined by the server and often depends on the particular resource, the behavior of POST when applied to collections cannot be meaningfully modified because it is largely undefined. Thus, the semantics of POST are unmodified when applied to a collection.

This has lead to a situation where many WebDAV servers do not implement POST for collections at all, although it is well suited to be used for the purpose of adding new members to a collection, where the server remains in control of the newly assigned URL. As a matter of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose ([RFC5023], Section 9.2):

9.2 Creating Resources with POST

To add members to a Collection, clients send POST requests to the URI of the Collection.

On the other hand, WebDAV-based protocols such as Calendaring Extensions to WebDAV (CalDAV) frequently require clients to pick a unique URL, although the server could easily perform that task ([RFC4791], Section 5.3.2):

5.3.2 Creating Calendar Object Resources

...

When servers create new resources, it's not hard for the server to choose an unmapped URI. It's slightly tougher for clients, because a client might not want to examine all resources in the collection and might not want to lock the entire collection to ensure that a new resource isn't created with a name collision. (...)

 I  rational-server-uri   (type: change, status: closed)
cyrus@daboo.name2008-09-22 One thing this reminds me of: another reason why this POST may be needed is if the server enforces a particular naming scheme on members. e.g., a CalDAV server may require that all member path segments match the UID in the calendar data, or match a record-id in its data store etc. In this case the add-member behavior is required. So its not just the case of "the client doesn't care to name members itself", but also this other one. Probably worth adding a comment on this.
2008-09-23Resolution: Mention that this can simplify the server by not having to persist a client-supplied name.
Associated changes in this document: 1.
 I  

As a matter of fact, letting the server choose the member URI not only is a simplification for certain types of clients, but can also reduce the complexity of the server (in that it doesn't need to persist an additional client-supplied identifier where it already has an internal one like a UUID or a primary key).

Note: the vCard Extensions to WebDAV (CardDAV) ([draft-ietf-vcarddav-carddav]) suffer from the same issue, and may be able to take advantage of this specification.

This specification defines a discovery mechanism through which servers can advertise support for POST requests with the aforementioned "add collection member" semantics.

Note: the author previously proposed a new HTTP method for exactly this purpose ([draft-reschke-http-addmember]), but quite a few reviewers pointed out that this would duplicate the original semantics of POST. Thus this proposal that avoids adding a new HTTP method.

2. Terminology

The terminology used here follows that in the WebDAV specification ([RFC4918]).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

This document uses XML DTD fragments ([XML]) as a purely notational convention. In particular:

3. Protocol Extension

Due to the reasons stated in Section 1, clients can not rely on a specific server behavior when POST is applied to a collection. This problem is addressed by this specification by allowing servers to advertise a URI that has the desired "add member" semantics.

Note that  I servers that already use POST for a different purpose can just expose a different URI for that purpose. Other servers can just advertise the collection's own URI, thus avoiding  I to mintminting another URI for a limited purpose.

3.1 Definition of 'Add-Member' URI

 I  remote-uri   (type: change, status: closed)
julian.reschke@greenbytes.de2008-09-30 Explicitly forbid Add-Member URIs pointing to other servers, mainly for reasons of security (DOS), but also for practical reasons (authentication).
2008-10-01Resolution: Require that the "Add-Member" URI points to the same server.
Associated changes in this document: 3.1.

The "Add-Member" URI of a WebDAV collection is a URI that will accept HTTP POST requests, and will interpret these as requests to store the enclosed entity as a new internal member of the collection. I  The URI of the newly created resource is returned in the HTTP Location response header ([RFC2616], Section 14.30). I  It MUST identify a resource on the same server as the WebDAV collection (the host and port components ([RFC2616], Section 3.2.2) of the URIs must match).

 I  post-error-semantics   (type: change, status: closed)
cyrus@daboo.name2008-09-22 Something needs to be stated about error handling: e.g., "If there are pre-conditions related to creating a resource in the collection using a PUT request, then those same pre-conditions apply to the new POST request behavior, and the same DAV:error response body returned on failure". This would be a "catch-all" to allow protocols such as CalDAV, which restrict certain aspects of the data stored in collections, to simply return the same pre-condition failure information for POST as for PUT.
2008-09-23Resolution: Adopt most of the proposed text, except for saying "HTTP response" to make it more generic (for instance, there may be no DAV:error entity body involved).
Associated changes in this document: 3.1.

If there are pre-conditions related to creating a resource in the collection using a PUT request, then those same pre-conditions apply to the new POST request behavior, and the same HTTP response body will returned on failure.

The URI of the newly created resource is returned in the HTTP Location response header ([RFC2616], Section 14.30).

 I  uri-uniqueness   (type: change, status: closed)
cyrus@daboo.name2008-09-22 Is the server allowed to re-use new member URIs? i.e. /a/b.txt exists at some point, then is deleted. Is the server then allowed to use b.txt as a new member of /a/, or does the new member path segment have to be unique for the entire existence of that collection? If the member path segment is expected to be unique there should be some guidance to servers on how they might implement that (uuid's for instance).
2008-09-23Resolution: Clarified that this specification doesn't make any additional requirements on the collection semantics.
Associated changes in this document: 3.1.

Note: the fact that a server advertises an "Add-Member" URI does not imply any special semantics of the collection itself. For instance, member URIs assigned by the server are not necessarily unique over time (a member URI may be assigned again to a new resource when it previously was removed).

 I  uri-format   (type: change, status: closed)
cyrus@daboo.name2008-09-23 Another question: there is no restriction on what p:add-member URI can be? e.g. if I have the collection "/a/b/" can the p:add-member be another resource entirely, e.g. "/a/use-c-to-create-in-b/"? If this is possible it should be called out, as the behavior might be somewhat unexpected for clients. It might even be the case that the p:add-member URI is on a different server (e.g. new member items in a collection need "approval" from some other service). The interaction with WebDAV ACL in this case would need to be clear - i.e. what privileges are required on the p:add-member URI?
2008-09-30Resolution: Add a set of examples, and use "/collection;add-member/" in subsequent examples.
Associated changes in this document: 3.1, 3.2.2, 3.2.3, 3.2.3, 3.4, 4.2.

Note: the "Add-Member" URI can be the identical to the collection's URI (in which case the server just advertises the fact that POST to the WebDAV collection's URI is supported as defined within this specification). But it can also be different from it, in which case it doesn't need to have any relation to the collection's URI.

Given a collection URI of

    /docs/collection/

all of the URIs below might occur as "Add-Member" URIs:

    /docs/collection/
    /docs/collection/;post
    /docs/collection;post/
    /docs/collection/&post
    /post-service?path=/collection/

The remainder of the document uses the same format just for reasons of consistency; any other HTTP URI would do as well.

3.2 Discovery

3.2.1 p:add-member Property

The p:add-member property is defined on WebDAV collections, and contains the "Add-Member" URI for that collection (embedded inside a DAV:href element).

  <!ELEMENT p:add-member (href)>
  <!-- href: defined in [RFC4918], Section 14.7 -->
 I  property-trust   (type: change, status: closed)
julian.reschke@greenbytes.de2008-10-01 An attacker could set p:add-member as dead property and thus trick clients into POSTing new content somewhere else.
2008-10-01Resolution: (1) Require server support for DAV:supported-live-property-set; (2) mention issue in security considerations.
Associated changes in this document: 3.2.1, 8, 10.1.

A PROPFIND/allprop request SHOULD NOT return this property (see [RFC4918], Section 9.1). I  Servers MUST implement the DAV:supported-live-property-set property defined in Section 3.1.4 of [RFC3253], and report the property p:add-member as a supported live property.

3.2.2 Example

>>Request

PROPFIND /collection/ HTTP/1.1
Host: example.com
Content-Type: application/xml; charset="utf-8"
Content- I LenghtLength: 163

<?xml version="1.0" encoding="utf-8" ?> 
<propfind xmlns="DAV:" xmlns:p="http://purl.org/NET/webdav/post#">
  <prop>
    <p:add-member/>
  </prop>
</propfind>

>>Response

HTTP/1.1 207 Multi-Status 
Content-Type: application/xml; charset="utf-8" 
Content-Length: 402
  
<?xml version="1.0" encoding="utf-8" ?>
<multistatus xmlns="DAV:" xmlns:p="http://purl.org/NET/webdav/post#">
  <response>
    <href>/collection/</href>
    <propstat>
      <prop>
        <p:add-member>
          <href>/collection I /;add-member;add-member/</href>
        </p:add-member>
      </prop>
      <status>HTTP/1.1 200 OK</status>
    </propstat>
  </response>
</multistatus>

Note that in this case, the server has minted a separate URI for the purpose of adding new content.

3.2.3 add-member Link Relation

There may be cases in which it is more efficient to expose the Add-Member URI in HTTP headers or in (X)HTML content. For this use case, this specification defines a new link relation with the name:

  http://purl.org/NET/webdav/post#add-member

It can be use I sd both in HTTP Link headers (see [draft-nottingham-http-link-header]):

 I >>Request

HEAD /collection/ HTTP/1.1
Host: example.com

 I >>Response

HTTP/1.1 200 OK
Link: </collection I /;add-member;add-member/>;
      rel="http://purl.org/NET/webdav/post#add-member"

...and in (X)HTML content:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
  <head>
    <title>Contents of /collection/</title>
    <link rel="http://purl.org/NET/webdav/post#add-member"
          href="/collection I /;add-member;add-member/" />
  </head
  <body>...</body>
</html>

3.3 Relation to AtomPub's 'Slug' Header

In the AtomPub protocol, clients can use the entity header "Slug" to suggest parts of the URI to be created (see [RFC5023], Section 9.7). Note that servers are free to ignore this suggestion, or to use whatever algorithm that makes sense to generate the new URI.

The same applies to the extension defined here: clients can use the "Slug" header as by its definition of a generic HTTP header. Servers should process it exactly the way defined by AtomPub.

3.4 Example Operation

>>Request

POST /collection I /;add-member;add-member/ HTTP/1.1
Host: example.com
Content-Type: text/plain
Slug: Sample Text
Content- I LenghtLength: 12

Sample text.

>>Response

HTTP/1.1 201 Created
Location: http://example.com/collection/sample%20text
 I  forbidden-put   (type: change, status: closed)
cyrus@daboo.name2008-09-23 So one option for the server to enforce its naming scheme would be to require POST by the client to create new resources rather than allowing PUT/COPY/MOVE to do so. However there is no way fort a client to discover that such a restriction might be in place other than getting a 403. How about a new pre-condition code for that so that the server can indicate "DAV:only-post-allowed-to-create-new-members" to the client? With perhaps a more compact name!
2008-09-30Resolution: Mention the use case, define the precondition, add example.
Associated changes in this document: <#rfc.change.forbidden-put.1>.
 I  

4. Additional Semantics for existing Methods

One important use case for this specification are collections that act as WebDAV collections for the purpose of read access (PROPFIND Depth 1/Infinity), but which only support internal member URIs assigned by the server. These collections will not allow a client to create a new member using methods like PUT, MKCOL, LOCK, COPY or MOVE. Therefore, this specification defines a new precondition name ([RFC4918], Section 16) that can be used to provide the client with additional information about why exactly the request failed.

4.1 Additional Preconditions

(p:allow-client-defined-URI): the server allows clients to specify the last path segment for newly created resources.

The precondition element MAY contain a p:add-member-uri XML element specifying the "Add-Member" URI associated with the collection, on which the creation of a new child resource was attempted:

  <!ELEMENT p:allow-client-defined-uri (p:add-member?)>

4.2 Example: Failed PUT Request

In this example, the client tries to use PUT to create a new internal member of /collection/.

>>Request

PUT /collection/new.txt HTTP/1.1
Host: example.com
Content-Type: text/plain
Content-Length: 12

Sample text.

>>Response

HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE
Content-Type: application/xml; charset=UTF-8
Content-Length: 239

<error xmlns="DAV:" xmlns:p="http://purl.org/NET/webdav/post#">
  <p:allow-client-defined-uri>
    <p:add-member>
      <href>/collection I /;add-member;add-member/</href>
    </p:add-member>
  </p:allow-client-defined-uri>
</error>

The request fails with a 405 (Method Not Allowed) status, but also provides the reason, and a pointer to the "Add-Member" URI in the response body.

 I  acl   (type: change, status: closed)
cyrus@daboo.name2008-09-23 This brings up another question: presumably the DAV:bind privilege is required on the collection for the new POST ;add-member behavior to be allowed (just as it would be required for PUT creating a new member). I think we therefore need a statement in Security Considerations: "When a server supports WebDAV ACL [RFC3744], the DAV:bind privilege is required to be granted on the collection resource in which the new member resource is being created. If this privilege is denied or not present, the POST request MUST fail."
2008-09-25Resolution: Add "relation to ACL" section; required DAV:bind privilege on associated WebDAV collection.
Associated changes in this document: <#rfc.change.acl.1>, 10.1.
 I  

5. Relationship to WebDAV Access Control Protocol

The WebDAV ACL specification requires the DAV:bind privilege to be granted on a collection for the client to able add new collection members ([RFC3744], Section 3.9). Consistent with that, a server MUST reject a POST request to the Add-Member URI of a collection unless the authenticated principal is granted DAV:bind privilege on the associated WebDAV collection resource.

6. Internationalization Considerations

This document does not introduce any new internationalization considerations beyond those discussed in Section 20 of [RFC4918].

7. IANA Considerations

This specification does not require any actions from IANA.

8. Security Considerations

 I  member-uri-content   (type: change, status: closed)
cyrus@daboo.name2008-09-22 Security consideration: "Servers MUST NOT derive the member path segment from the data being stored in the resource". This is important because you don't want server's leaking information in the URI that would not otherwise be visible (e.g. a user can PROPFIND the members but cannot read the content of the members - leaking content in the URI would be bad). Note this impacts how the server generates the member path segment. e.g. an md5 hash of the data only may not be appropriate.
2008-09-23Resolution: State the problem, but do not make a requirement (for instance, the server could be entirely public in which case this wouldn't be an issue at all).
Associated changes in this document: 8.

All security considerations connected to HTTP/WebDAV and XML apply for this specification as well, namely, [RFC4918] (Section 20) and [RFC3470] (Section 7).

 I  

Furthermore, servers should be aware that deriving the member path from the data being stored in the resource could potentially expose confidential information. This could even be the case when only a hash code of the content is used.

 I  

In addition, on servers that do not support this specification, a malevolent user could set the p:add-member URI as a custom property, tricking other users to post content to an entirely different URI. Clients can protect themselves against this scenario by

 I  

9. Acknowledgements

This document has benefited from thoughtful discussion by Cyrus Daboo and Bernard Desruissaux.

10. References

10.1 Normative References

[draft-nottingham-http-link-header]Nottingham, M., “HTTP Header Linking”, Internet-Draft draft-nottingham-http-link-header-02 (work in progress), July 2008.
[RFC2119]Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.
[RFC2616]Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1”, RFC 2616, June 1999.
[RFC3253]Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, “Versioning Extensions to WebDAV”, RFC 3253, March 2002.
[RFC3744]Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, “Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol”, RFC 3744, May 2004.
[RFC4918]Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)”, RFC 4918, June 2007.
[XML]Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, “Extensible Markup Language (XML) 1.0 (Fourth Edition)”, W3C REC-xml-20060816, August 2006, <http://www.w3.org/TR/2006/REC-xml-20060816>.

10.2 Informative References

[draft-ietf-vcarddav-carddav]Daboo, C., “vCard Extensions to WebDAV (CardDAV)”, Internet-Draft draft-ietf-vcarddav-carddav-01 (work in progress), July 2008.
[draft-reschke-http-addmember]Reschke, J., “The HTTP ADDMEMBER Method”, Internet-Draft draft-reschke-http-addmember-00 (work in progress), February 2005.
[RFC3470]Hollenbeck, S., Rose, M., and L. Masinter, “Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols”, RFC 3470, BCP 70, January 2003.
[RFC4791]Daboo, C., Desruisseaux, B., and L. Dusseault, “Calendaring Extensions to WebDAV (CalDAV)”, RFC 4791, March 2007.
[RFC5023]Gregorio, J. and B. de hOra, “The Atom Publishing Protocol”, RFC 5023, October 2007.
 I  

A. Change Log (to be removed by RFC Editor before publication)

A.1 since draft-reschke-webdav-post-00

Added Acknowledgements.

Add and resolve issues "acl", "forbidden-put", "member-uri-content", "post-error-semantics", "property-trust", "rational-server-uri", ""remote-uri", "uri-format" and "uri-uniqueness".

Index

A C D L M P R X

Author's Address

Julian F. Reschke
greenbytes GmbH
Hafenweg 16
Muenster, NW 48155
Germany
Phone: +49 251 2807760
EMail: julian.reschke@greenbytes.de
URI: http://greenbytes.de/tech/webdav/

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.