doc: Add RFC documents

1 files changed, 675 insertions, 0 deletions

diff --git a/doc/rfc/rfc5995.txt b/doc/rfc/rfc5995.txt
new file mode 100644
index 0000000..ba039cc
--- /dev/null
+++ b/doc/rfc/rfc5995.txt
@@ -0,0 +1,675 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                        J. Reschke
+Request for Comments: 5995                                    greenbytes
+Category: Standards Track                                 September 2010
+ISSN: 2070-1721
+
+
+ Using POST to Add Members to Web Distributed Authoring and Versioning
+                          (WebDAV) Collections
+
+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.  In fact,
+   the Atom Publishing Protocol (AtomPub) uses POST exactly for that
+   purpose.  On the other hand, WebDAV-based protocols, such as the
+   Calendaring 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.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc5995.
+
+
+
+
+
+
+
+Reschke                      Standards Track                    [Page 1]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+Copyright Notice
+
+   Copyright (c) 2010 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (http://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+Table of Contents
+
+   1. Introduction ....................................................2
+   2. Terminology .....................................................4
+   3. Protocol Extension ..............................................4
+      3.1. Definition of "Add-Member" URI .............................5
+      3.2. Discovery ..................................................6
+           3.2.1. DAV:add-member Property (Protected) .................6
+           3.2.2. Example .............................................6
+      3.3. Relation to AtomPub's "Slug" Header Field ..................7
+      3.4. Example Operation ..........................................7
+   4. Additional Semantics for Existing Methods .......................8
+      4.1. Additional Preconditions ...................................8
+      4.2. Example: Failed PUT Request ................................8
+   5. Relationship to WebDAV Access Control Protocol ..................9
+   6. Internationalization Considerations .............................9
+   7. Security Considerations .........................................9
+   8. Acknowledgements ...............................................10
+   9. References .....................................................10
+      9.1. Normative References ......................................10
+      9.2. Informative References ....................................11
+   Index .............................................................11
+
+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":
+
+
+
+
+
+
+Reschke                      Standards Track                    [Page 2]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+      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.  In 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.
+      (...)
+
+   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
+   Universally Unique Identifier (UUID) or a primary key).
+
+      Note: The vCard Extensions to WebDAV (CardDAV) ([CARDDAV]) suffer
+      from the same issue, and may be able to take advantage of this
+      specification.
+
+
+
+
+
+
+Reschke                      Standards Track                    [Page 3]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+   This specification defines a discovery mechanism through which
+   servers can advertise support for POST requests with the
+   aforementioned "add collection member" semantics.
+
+   This specification deliberately only addresses the use case of
+   creating new non-collection resources.  It was not a goal for this
+   specification to supply the same functionality for creating
+   collection resources (MKCOL) or for other operations that require the
+   client to specify a new URL (LOCK, MOVE, or COPY).
+
+      Note: The author previously proposed a new HTTP method for exactly
+      this purpose ([ADDMEMBER]), but quite a few reviewers pointed out
+      that this would duplicate the original semantics of POST.  Thus,
+      this proposal, which 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 cannot 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.
+
+
+
+
+Reschke                      Standards Track                    [Page 4]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+   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 preconditions related to creating a resource in the
+   collection using a PUT request, then those same preconditions apply
+   to the new POST request behavior, and the same HTTP response body
+   will be returned on failure.
+
+   The URI of the newly created resource is returned in the HTTP
+   Location response header field ([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 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/
+
+      any 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/
+
+
+
+
+
+
+Reschke                      Standards Track                    [Page 5]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+      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 (Protected)
+
+   DAV:add-member is a protected property (see [RFC4918], Section 15)
+   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.
+
+3.2.2.  Example
+
+   >>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                      Standards Track                    [Page 6]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+   >>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>
+
+   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 Field
+
+   In the AtomPub protocol, clients can use the entity header field
+   "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 makes sense to generate the new URI.
+
+   The same applies to the extension defined here: clients can use the
+   "Slug" header field, as by definition it is a generic HTTP header
+   field.  Servers should process it exactly in 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 Title
+   Content-Length: 12
+
+   Sample text.
+
+
+
+
+Reschke                      Standards Track                    [Page 7]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+   >>Response
+
+   HTTP/1.1 201 Created
+   Location: http://example.com/collection/sample%20title
+
+4.  Additional Semantics for Existing Methods
+
+   One important use case for this specification is 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 regarding exactly why the request failed.
+
+      Note: Although the precondition defined below can be used for
+      methods other than PUT, the "Add-Member" mechanism defined by this
+      specification deliberately is restricted to PUT.
+
+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 an 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                      Standards Track                    [Page 8]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+   >>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 Access Control Protocol specification requires the DAV:
+   bind privilege to be granted on a collection for the client to be
+   able to 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 principal executing the
+   request 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 19 of [RFC4918].
+
+7.  Security Considerations
+
+   Security considerations applicable to HTTP [RFC2616], WebDAV
+   [RFC4918], and XML [XML] apply for this specification as well,
+   namely, Section 20 of [RFC4918] and Section 7 of [RFC3470].
+
+   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.
+
+
+
+
+
+
+
+Reschke                      Standards Track                    [Page 9]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+   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).
+
+8.  Acknowledgements
+
+   This document has benefited from thoughtful discussion by Cyrus Daboo
+   and Bernard Desruisseaux.
+
+9.  References
+
+9.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 (Web
+               Distributed Authoring and Versioning)", 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
+               Edition)", W3C REC-xml-20081126, November 2008,
+               <http://www.w3.org/TR/2008/REC-xml-20081126/>.
+
+
+
+
+
+
+Reschke                      Standards Track                   [Page 10]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+9.2.  Informative References
+
+   [ADDMEMBER] Reschke, J., "The HTTP ADDMEMBER Method", Work
+               in Progress, February 2005.
+
+   [CARDDAV]   Daboo, C., "vCard Extensions to WebDAV (CardDAV)", Work
+               in Progress, November 2009.
+
+   [RFC3470]   Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines
+               for the Use of Extensible Markup Language (XML) within
+               IETF Protocols", BCP 70, RFC 3470, January 2003.
+
+   [RFC4791]   Daboo, C., Desruisseaux, B., and L. Dusseault,
+               "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
+               March 2007.
+
+   [RFC5023]   Gregorio, J., Ed. and B. de hOra, Ed., "The Atom
+               Publishing Protocol", RFC 5023, October 2007.
+
+Index
+
+   A
+      Add-Member URI  5
+
+   C
+      Condition Names
+         DAV:allow-client-defined-URI (pre)  8
+      COPY method
+         Additional Preconditions  8
+
+   D
+      DAV:allow-client-defined-URI  8
+
+   L
+      LOCK method
+         Additional Preconditions  8
+
+   M
+      MKCOL method
+         Additional Preconditions  8
+      MOVE method
+         Additional Preconditions  8
+
+   P
+      PUT method
+         Additional Preconditions  8
+
+
+
+
+
+Reschke                      Standards Track                   [Page 11]
+
+RFC 5995            POST to Add to WebDAV Collections     September 2010
+
+
+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                      Standards Track                   [Page 12]
+