Network Working Group J. Reschke
Internet-Draft greenbytes
Intended status: Standards Track December 7, 2008
Expires: June 10, 2009
Using POST to add Members to Web Distributed Authoring and Versioning
(WebDAV) Collections
draft-reschke-webdav-post-03
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 June 10, 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 led 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
Reschke Expires June 10, 2009 [Page 1]
Internet-Draft POST to add to WebDAV Collections December 2008
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>.
Reschke Expires June 10, 2009 [Page 2]
Internet-Draft POST to add to WebDAV Collections December 2008
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Protocol Extension . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Definition of 'Add-Member' URI . . . . . . . . . . . . . . 6
3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.1. DAV:add-member property . . . . . . . . . . . . . . . 7
3.2.2. Example . . . . . . . . . . . . . . . . . . . . . . . 7
3.3. Relation to AtomPub's 'Slug' Header . . . . . . . . . . . 8
3.4. Example Operation . . . . . . . . . . . . . . . . . . . . 8
4. Additional Semantics for existing Methods . . . . . . . . . . 9
4.1. Additional Preconditions . . . . . . . . . . . . . . . . . 9
4.2. Example: Failed PUT Request . . . . . . . . . . . . . . . 9
5. Relationship to WebDAV Access Control Protocol . . . . . . . . 10
6. Internationalization Considerations . . . . . . . . . . . . . 10
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8. Security Considerations . . . . . . . . . . . . . . . . . . . 10
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
10.1. Normative References . . . . . . . . . . . . . . . . . . . 11
10.2. Informative References . . . . . . . . . . . . . . . . . . 12
Appendix A. Change Log (to be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 12
A.1. since draft-reschke-webdav-post-00 . . . . . . . . . . . . 12
A.2. since draft-reschke-webdav-post-01 . . . . . . . . . . . . 12
A.3. since draft-reschke-webdav-post-02 . . . . . . . . . . . . 12
Appendix B. Resolved issues (to be removed by RFC Editor
before publication) . . . . . . . . . . . . . . . . . 13
B.1. link-header . . . . . . . . . . . . . . . . . . . . . . . 13
B.2. ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Appendix C. Open issues (to be removed by RFC Editor prior to
publication) . . . . . . . . . . . . . . . . . . . . 13
C.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14
Intellectual Property and Copyright Statements . . . . . . . . . . 15
Reschke Expires June 10, 2009 [Page 3]
Internet-Draft POST to add to WebDAV Collections December 2008
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 led 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.
(...)
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
Reschke Expires June 10, 2009 [Page 4]
Internet-Draft POST to add to WebDAV Collections December 2008
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 is made.
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:
o Element ordering is irrelevant.
o Extension elements/attributes (elements/attributes not already
defined as valid child elements) may be added anywhere, except
when explicitly stated otherwise.
Note: this specification defines new properties and precondition
names in the "DAV:" namespace, which the WebDAV specification
reserves for use by the IETF ([RFC4918], Section 21.1). However,
there was rough consensus in the WebDAV community that the
specification is of general applicability to other WebDAV related
standards efforts, and thus deserves inclusion into the base
namespace.
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
Reschke Expires June 10, 2009 [Page 5]
Internet-Draft POST to add to WebDAV Collections December 2008
problem is addressed by this specification by allowing servers to
advertise a URI that has the desired "add member" semantics.
Note that servers that already use POST for a different purpose can
just expose a separate URI. Other servers can just advertise the
collection's own URI, thus avoiding minting another URI for a limited
purpose.
3.1. Definition of 'Add-Member' URI
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 (see
Section 3 of [RFC4918] for the definition of "internal member"). 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).
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).
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).
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/
Reschke Expires June 10, 2009 [Page 6]
Internet-Draft POST to add to WebDAV Collections December 2008
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 on the same server
would do as well.
3.2. Discovery
3.2.1. DAV:add-member property
The DAV:add-member property is defined on WebDAV collections, and
contains the "Add-Member" URI for that collection (embedded inside a
DAV:href element).
<!ELEMENT add-member (href)>
<!-- href: defined in [RFC4918], Section 14.7 -->
A PROPFIND/allprop request SHOULD NOT return this property (see
[RFC4918], Section 9.1). Servers MUST implement the DAV:supported-
live-property-set property defined in Section 3.1.4 of [RFC3253], and
report the property DAV:add-member as a supported live property.
>>Request
PROPFIND /collection/ HTTP/1.1
Host: example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: 118
<?xml version="1.0" encoding="utf-8" ?>
<propfind xmlns="DAV:">
<prop>
<add-member/>
</prop>
</propfind>
Reschke Expires June 10, 2009 [Page 7]
Internet-Draft POST to add to WebDAV Collections December 2008
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset="utf-8"
Content-Length: 340
<?xml version="1.0" encoding="utf-8" ?>
<multistatus xmlns="DAV:">
<response>
<href>/collection/</href>
<propstat>
<prop>
<add-member>
<href>/collection;add-member/</href>
</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.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;add-member/ HTTP/1.1
Host: example.com
Content-Type: text/plain
Slug: Sample Text
Content-Length: 12
Sample text.
Reschke Expires June 10, 2009 [Page 8]
Internet-Draft POST to add to WebDAV Collections December 2008
>>Response
HTTP/1.1 201 Created
Location: http://example.com/collection/sample%20text
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
(DAV:allow-client-defined-URI): the server allows clients to specify
the last path segment for newly created resources.
The precondition element MAY contain a 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 allow-client-defined-uri (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.
Reschke Expires June 10, 2009 [Page 9]
Internet-Draft POST to add to WebDAV Collections December 2008
>>Response
HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE
Content-Type: application/xml; charset=UTF-8
Content-Length: 172
<error xmlns="DAV:">
<allow-client-defined-uri>
<add-member>
<href>/collection;add-member/</href>
</add-member>
</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.
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
All security considerations connected to HTTP/WebDAV and XML apply
for this specification as well, namely, [RFC4918] (Section 20) and
[RFC3470] (Section 7).
Furthermore, servers should be aware that deriving the member path
Reschke Expires June 10, 2009 [Page 10]
Internet-Draft POST to add to WebDAV Collections December 2008
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.
In addition, on servers that do not support this specification, a
malevolent user could set the DAV: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
o not following DAV:add-member URIs to different servers, and/or
o verifying that the DAV:add-member property is indeed a live
property (this can be achieved by testing the DAV:supported-live-
property-set property, or by checking whether DAV:add-member is
returned upon PROPFIND/allprop)
9. Acknowledgements
This document has benefited from thoughtful discussion by Cyrus Daboo
and Bernard Desruissaux.
10. References
10.1. Normative References
[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 (Fifth
Reschke Expires June 10, 2009 [Page 11]
Internet-Draft POST to add to WebDAV Collections December 2008
Edition)", W3C REC-xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126/>.
10.2. Informative References
[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.
[draft-ietf-vcarddav-carddav]
Daboo, C., "vCard Extensions to WebDAV (CardDAV)",
draft-ietf-vcarddav-carddav-03 (work in progress),
November 2008.
[draft-reschke-http-addmember]
Reschke, J., "The HTTP ADDMEMBER Method",
draft-reschke-http-addmember-00 (work in progress),
February 2005.
Appendix A. Change Log (to be removed by RFC Editor before publication)
Added Acknowledgements.
Added and resolved issues "acl", "forbidden-put", "member-uri-
content", "post-error-semantics", "property-trust", "rational-server-
uri", ""remote-uri", "uri-format" and "uri-uniqueness".
Add and resolve issue "containment".
Update draft-ietf-vcarddav-carddav reference.
Update XML, draft-ietf-vcarddav-carddav and
draft-nottingham-http-link-header references.
Reschke Expires June 10, 2009 [Page 12]
Internet-Draft POST to add to WebDAV Collections December 2008
Add and resolve issues "link-header" and "ns".
Appendix B. Resolved issues (to be removed by RFC Editor before
publication)
Issues that were either rejected or resolved in this version of this
document.
B.1. link-header
Type: edit
julian.reschke@greenbytes.de (2008-12-01): Restructure text so that
link header reference becomes informative.
Resolution (2008-12-06): Change of plan: leave out discussion of the
Link header for now. See http://lists.w3.org/Archives/Public/
w3c-dist-auth/2008OctDec/0038.html.
Type: change
julian.reschke@greenbytes.de (2008-12-01): Put elements into DAV:
namespace. See http://lists.w3.org/Archives/Public/w3c-dist-auth/
2008OctDec/0035.html.
Resolution (2008-12-04): Done.
Appendix C. Open issues (to be removed by RFC Editor prior to
publication)
Type: edit
julian.reschke@greenbytes.de (2008-09-22): Umbrella issue for
editorial fixes/enhancements.
Index
A
Add-Member URI 6
C
Reschke Expires June 10, 2009 [Page 13]
Internet-Draft POST to add to WebDAV Collections December 2008
Condition Names
DAV:allow-client-defined-URI (pre) 9
COPY method
Additional Preconditions 9
D
DAV:allow-client-defined-URI 9
L
LOCK method
Additional Preconditions 9
M
MKCOL method
Additional Preconditions 9
MOVE method
Additional Preconditions 9
P
PUT method
Additional Preconditions 9
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/
Reschke Expires June 10, 2009 [Page 14]
Internet-Draft POST to add to WebDAV Collections December 2008
Full Copyright Statement
Copyright (C) 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.
Reschke Expires June 10, 2009 [Page 15]
