--- /dev/null
+
+
+
+
+
+
+Network Working Group J. Mogul
+Request for Comments: 2227 DECWRL
+Category: Standards Track P. Leach
+ Microsoft
+ October 1997
+
+
+ Simple Hit-Metering and Usage-Limiting for HTTP
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1997). All Rights Reserved.
+
+ABSTRACT
+
+ This document proposes a simple extension to HTTP, using a new
+ "Meter" header, which permits a limited form of demographic
+ information (colloquially called "hit-counts") to be reported by
+ caches to origin servers, in a more efficient manner than the
+ "cache-busting" techniques currently used. It also permits an origin
+ server to control the number of times a cache uses a cached response,
+ and outlines a technique that origin servers can use to capture
+ referral information without "cache-busting."
+
+TABLE OF CONTENTS
+
+ 1 Introduction 2
+ 1.1 Goals, non-goals, and limitations 3
+ 1.2 Brief summary of the design 4
+ 1.3 Terminology 5
+ 2 Overview 5
+ 2.1 Discussion 7
+ 3 Design concepts 8
+ 3.1 Implementation of the "metering subtree" 8
+ 3.2 Format of the Meter header 10
+ 3.3 Negotiation of hit-metering and usage-limiting 10
+ 3.4 Transmission of usage reports 14
+ 3.5 When to send usage reports 15
+ 3.6 Subdivision of usage-limits 16
+
+
+
+
+Mogul & Leach Standards Track [Page 1]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ 4 Analysis 17
+ 4.1 Approximation accuracy for counting users 18
+ 4.2 What about "Network Computers"? 19
+ 4.3 Critical-path delay analysis 19
+ 5 Specification 20
+ 5.1 Specification of Meter header and directives 20
+ 5.2 Abbreviations for Meter directives 23
+ 5.3 Counting rules 24
+ 5.3.1 Counting rules for hit-metering 24
+ 5.3.2 Counting rules for usage-limiting 25
+ 5.3.3 Equivalent algorithms are allowed 26
+ 5.4 Counting rules: interaction with Range requests 27
+ 5.5 Implementation by non-caching proxies 27
+ 5.6 Implementation by cooperating caches 28
+ 6 Examples 28
+ 6.1 Example of a complete set of exchanges 28
+ 6.2 Protecting against HTTP/1.0 proxies 30
+ 6.3 More elaborate examples 30
+ 7 Interactions with content negotiation 31
+ 7.1 Treatment of responses carrying a Vary header 31
+ 7.2 Interaction with Transparent Content Negotiation 32
+ 8 A Note on Capturing Referrals 32
+ 9 Alternative proposals 33
+ 10 Security Considerations 34
+ 11 Acknowledgments 35
+ 12 References 35
+ 13 Authors' Addresses 36
+ 14 Full Copyright Statement 37
+
+1 Introduction
+
+ For a variety of reasons, content providers want to be able to
+ collect information on the frequency with which their content is
+ accessed. This desire leads to some of the "cache-busting" done by
+ existing servers. ("Cache-busting" is the use by servers of
+ techniques intended to prevent caching of responses; it is unknown
+ exactly how common this is.) This kind of cache-busting is done not
+ for the purpose of maintaining transparency or security properties,
+ but simply to collect demographic information. Some cache-busting is
+ also done to provide different advertising images to appear on the
+ same page (i.e., each retrieval of the page sees a different ad).
+
+ This proposal supports a model similar to that of publishers of
+ hard-copy publications: such publishers (try to) report to their
+ advertisers how many people read an issue of a publication at least
+ once; they don't (try to) report how many times a reader re-reads an
+ issue. They do this by counting copies published, and then try to
+ estimate, for their publication, on average how many people read a
+
+
+
+Mogul & Leach Standards Track [Page 2]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ single copy at least once. The key point is that the results aren't
+ exact, but are still useful. Another model is that of coding
+ inquiries in such a way that the advertiser can tell which
+ publication produced the inquiry.
+
+1.1 Goals, non-goals, and limitations
+
+ HTTP/1.1 already allows origin servers to prevent caching of
+ responses, and evidence exists [9] that at least some of the time,
+ this is being done for the sole purpose of collecting counts of the
+ number of accesses of specific pages. Some of this evidence is
+ inferred from the study of proxy traces; some is based on explicit
+ statements of the intention of the operators of Web servers.
+ Information collected this way might or might not be of actual use to
+ the people who collect it; the fact is that they want to collect it,
+ or already do so.
+
+ The goal of this proposal is to provide an optional performance
+ optimization for this use of HTTP/1.1.
+
+ This specification is:
+
+ - Optional: no server or proxy is required to implement it.
+
+ - Proxy-centered: there is no involvement on the part of
+ end-client implementations.
+
+ - Solely a performance optimization: it provides no
+ information or functionality that is not already available
+ in HTTP/1.1. The intent is to improve performance overall,
+ and reduce latency for almost all interactions; latency
+ might be increased for a small fraction of HTTP
+ interactions.
+
+ - Best-efforts: it does not guarantee the accuracy of the
+ reported information, although it does provide accurate
+ results in the absence of persistent network failures or
+ host crashes.
+
+ - Neutral with respect to privacy: it reveals to servers no
+ information about clients that is not already available
+ through the existing features of HTTP/1.1.
+
+ The goals of this specification do not include:
+
+ - Solving the entire problem of efficiently obtaining
+ extensive information about requests made via proxies.
+
+
+
+
+Mogul & Leach Standards Track [Page 3]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ - Improving the protection of user privacy (although our
+ proposal may reduce the transfer of user-specific
+ information to servers, it does not prevent it).
+
+ - Preventing or encouraging the use of log-exchange
+ mechanisms.
+
+ - Avoiding all forms of "cache-busting", or even all
+ cache-busting done for gathering counts.
+
+ This design has certain potential limitations:
+
+ - If it is not deployed widely in both proxies and servers,
+ it will provide little benefit.
+
+ - It may, by partially solving the hit-counting problem,
+ reduce the pressure to adopt more complete solutions, if
+ any become available.
+
+ - Even if widely deployed, it might not be widely used, and
+ so might not significantly improve performance.
+
+ These potential limitations might not be problems in actual practice.
+
+1.2 Brief summary of the design
+
+ This section is included for people not wishing to read the entire
+ document; it is not a specification for the proposed design, and
+ over-simplifies many aspects of the design.
+
+ The goal of this design is to eliminate the need for origin servers
+ to use "cache-busting" techniques, when this is done just for the
+ purpose of counting the number of users of a resource. (Cache-
+ busting includes techniques such as setting immediate Expiration
+ dates, or sending "Cache-control: private" in each response.)
+
+ The design adds a new "Meter" header to HTTP; the header is always
+ protected by the "Connection" header, and so is always hop-by-hop.
+ This mechanism allows the construction of a "metering subtree", which
+ is a connected subtree of proxies, rooted at an origin server. Only
+ those proxies that explicitly volunteer to join in the metering
+ subtree for a resource participate in hit-metering, but those proxies
+ that do volunteer are required to make their best effort to provide
+ accurate counts. When a hit-metered response is forwarded outside of
+ the metering subtree, the forwarding proxy adds "Cache-control: s-
+ maxage=0", so that other proxies (outside the metering subtree) are
+ forced to forward all requests to a server in the metering subtree.
+
+
+
+
+Mogul & Leach Standards Track [Page 4]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ NOTE: the HTTP/1.1 specification does not currently define a "s-
+ maxage" Cache-control directive. The HTTP working group has
+ decided to add such a directive to the next revision of the
+ HTTP/1.1 specification [7].
+
+ The Meter header carries zero or more directives, similar to the way
+ that the Cache-control header carries directives. Proxies may use
+ certain Meter directives to volunteer to do hit-metering for a
+ resource. If a proxy does volunteer, the server may use certain
+ directives to require that a response be hit-metered. Finally,
+ proxies use a "count" Meter directive to report the accumulated hit
+ counts.
+
+ The Meter mechanism can also be used by a server to limit the number
+ of uses that a cache may make of a cached response, before
+ revalidating it.
+
+ The full specification includes complete rules for counting "uses" of
+ a response (e.g., non-conditional GETs) and "reuses" (conditional
+ GETs). These rules ensure that the results are entirely consistent
+ in all cases, except when systems or networks fail.
+
+1.3 Terminology
+
+ This document uses terms defined and explained in the HTTP/1.1
+ specification [4], including "origin server," "resource," "hop-by-
+ hop," "unconditional GET," and "conditional GET." The reader is
+ expected to be familiar with the HTTP/1.1 specification and its
+ terminology.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", SHOULD NOT",
+ "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+ interpreted as described in RFC 2119 [1].
+
+2 Overview
+
+ The design described in this document introduces several new features
+ to HTTP:
+
+ - Hit-metering: allows an origin server to obtain reasonably
+ accurate counts of the number of clients using a resource
+ instance via a proxy cache, or a hierarchy of proxy caches.
+
+ - Usage-limiting: allows an origin server to control the
+ number of times a cached response may be used by a proxy
+ cache, or a hierarchy of proxy caches, before revalidation
+ with the origin server.
+
+
+
+
+Mogul & Leach Standards Track [Page 5]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ These new non-mandatory features require minimal new protocol
+ support, no change in protocol version, relatively little overhead in
+ message headers. The design adds no additional network round-trips
+ in any critical path that directly affects user-perceived latency
+ (see section 4.3 for an analysis).
+
+ The primary goal of hit-metering and usage-limiting is to obviate the
+ need for an origin server to send "Cache-control: s-maxage=0" with
+ responses for resources whose value is not likely to change
+ immediately. In other words, in cases where the only reason for
+ contacting the origin server on every request that might otherwise be
+ satisfied by a proxy cache entry is to allow the server to collect
+ demographic information or to control the number of times a cache
+ entry is used, the extension proposed here will avoid a significant
+ amount of unnecessary network traffic and latency.
+
+ This design introduces one new "Meter" header, which is used both in
+ HTTP request messages and HTTP response messages. The Meter header
+ is used to transmit a number of directives and reports. In
+ particular, all negotiation of the use of hit-metering and usage
+ limits is done using this header. No other changes to the existing
+ HTTP/1.1 specification [4] are proposed in this document.
+
+ This design also introduces several new concepts:
+
+ 1. The concepts of a "use" of a cache entry, which is when a
+ proxy returns its entity-body in response to a conditional
+ or non-conditional request, and the "reuse" of a cache
+ entry, which is when a proxy returns a 304 (Not Modified)
+ response to a conditional request which is satisfied by
+ that cache entry.
+
+ 2. The concept of a hit-metered resource, for which proxy
+ caches make a best-effort attempt to report accurate
+ counts of uses and/or reuses to the origin server.
+
+ 3. The concept of a usage-limited resource, for which the
+ origin server expects proxy caches to limit the number of
+ uses and/or reuses.
+
+ The new Meter directives and reports interact to allow proxy caches
+ and servers to cooperate in the collection of demographic data. The
+ goal is a best-efforts approximation of the true number of uses
+ and/or reuses, not a guaranteed exact count.
+
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 6]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ The new Meter directives also allow a server to bound the inaccuracy
+ of a particular hit-count, by bounding the number of uses between
+ reports. It can also, for example, bound the number of times the
+ same ad is shown because of caching.
+
+ Section 7.1 describes a way to use server-driven content negotiation
+ (the Vary header) that allows an HTTP origin server to flexibly
+ separate requests into categories and count requests by category.
+ Implementation of such a categorized hit counting is likely to be a
+ very small modification to most implementations of Vary; some
+ implementations may not require any modification at all.
+
+2.1 Discussion
+
+ Mapping this onto the publishing model, a proxy cache would increment
+ the use-count for a cache entry once for each unconditional GET done
+ for the entry, and once for each conditional GET that results in
+ sending a copy of the entry to update a client's invalid cached copy.
+ Conditional GETs that result in 304 (Not Modified) are not included
+ in the use-count, because they do not result in a new user seeing the
+ page, but instead signify a repeat view by a user that had seen it
+ before. However, 304 responses are counted in the reuse-count.
+ HEADs are not counted at all, because their responses do not contain
+ an entity-body.
+
+ The Meter directives apply only to shared proxy caches, not to end-
+ client (or other single-user) caches. Single user caches should not
+ use Meter, because their hits will be automatically counted as a
+ result of the unconditional GET with which they first fetch the page,
+ from either the origin-server or from a proxy cache. Their
+ subsequent conditional GETs do not result in a new user seeing the
+ page.
+
+ The mechanism specified here counts GETs; other methods either do not
+ result in a page for the user to read, aren't cached, or are
+ "written-through" and so can be directly counted by the origin
+ server. (If, in the future, a "cachable POST" came into existence,
+ whereby the entity-body in the POST request was used to select a
+ cached response, then such POSTs would have to be treated just like
+ GETs.) The applicability of hit-metering to any new HTTP methods
+ that might be defined in the future is currently unspecifiable.
+
+ In the case of multiple caches along a path, a proxy cache does the
+ obvious summation when it receives a use-count or reuse-count in a
+ request from another cache.
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 7]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+3 Design concepts
+
+ In order to allow the introduction of hit-metering and usage-limiting
+ without requiring a protocol revision, and to ensure a reasonably
+ close approximation of accurate counts, the negotiation of metering
+ and usage-limiting is done hop-by-hop, not end-to-end. If one
+ considers the "tree" of proxies that receive, store, and forward a
+ specific response, the intent of this design is that within some
+ (possibly null) "metering subtree", rooted at the origin server, all
+ proxies are using the hit-metering and/or usage-limiting requested by
+ the origin server.
+
+ Proxies at the leaves of this subtree will insert a "Cache-control:
+ s-maxage=0" directive, which forces all other proxies (below this
+ subtree) to check with a leaf of the metering subtree on every
+ request. However, it does not prevent them from storing and using
+ the response, if the revalidation succeeds.
+
+ No proxy is required to implement hit-metering or usage-limiting.
+ However, any proxy that transmits the Meter header in a request MUST
+ implement every unconditional requirement of this specification,
+ without exception or amendment.
+
+ This is a conservative design, which may sometimes fail to take
+ advantage of hit-metering support in proxies outside the metering
+ subtree. However, it is likely that without the reliability offered
+ by a conservative design, managers of origin servers with
+ requirements for accurate approximations will not take advantage of
+ any hit-metering proposal.
+
+ The hit-metering/usage-limiting mechanism is designed to avoid any
+ extra network round-trips in the critical path of any client request,
+ and (as much as possible) to avoid excessively lengthening HTTP
+ messages.
+
+ The Meter header is used to transmit both negotiation information and
+ numeric information.
+
+ A formal specification for the Meter header appears in section 5; the
+ following discussion uses an informal approach to improve clarity.
+
+3.1 Implementation of the "metering subtree"
+
+ The "metering subtree" approach is implemented in a simple,
+ straightforward way by defining the new "Meter" header as one that
+ MUST always be protected by a Connection header in every request or
+ response. I.e., if the Meter header is present in an HTTP message,
+ that message:
+
+
+
+Mogul & Leach Standards Track [Page 8]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ 1. MUST contain "Connection: meter", and MUST be handled
+ according to the HTTP/1.1 specification of the Connection
+ header.
+
+ 2. MUST NOT be sent in response to a request from a client
+ whose version number is less than HTTP/1.1.
+
+ 3. MUST NOT be accepted from a client whose version number is
+ less than HTTP/1.1.
+
+ The reason for the latter two restrictions is to protect against
+ proxies that might not properly implement the Connection header.
+ Otherwise, a subtree that includes an HTTP/1.0 proxy might
+ erroneously appear to be a metering subtree.
+
+ Note: It appears that for the Connection header mechanism to
+ function correctly, a system receiving an HTTP/1.0 (or lower-
+ version) message that includes a Connection header must act as if
+ this header, and all of the headers it protects, ought to have
+ been removed from the message by an intermediate proxy.
+
+ Although RFC2068 does not specifically require this behavior, it
+ appears to be implied. Otherwise, one could not depend on the
+ stated property (section 14.10) that the protected options "MUST
+ NOT be communicated by proxies over further connections." This
+ should probably be clarified in a subsequent draft of the HTTP/1.1
+ specification.
+
+ This specification does not, in any way, propose a modification of
+ the specification of the Connection header.
+
+ From the point of view of an origin server, the proxies in a metering
+ subtree work together to obey usage limits and to maintain accurate
+ usage counts. When an origin server specifies a usage limit, a proxy
+ in the metering subtree may subdivide this limit among its children
+ in the subtree as it sees fit. Similarly, when a proxy in the
+ subtree receives a usage report, it ensures that the hits represented
+ by this report are summed properly and reported to the origin server.
+
+ When a proxy forwards a hit-metered or usage-limited response to a
+ client (proxy or end-client) not in the metering subtree, it MUST
+ omit the Meter header, and it MUST add "Cache-control: s-maxage=0" to
+ the response.
+
+
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 9]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+3.2 Format of the Meter header
+
+ The Meter header is used to carry zero or more directives. Multiple
+ Meter headers may occur in an HTTP message, but according to the
+ rules in section 4.2 of the HTTP/1.1 specification [4], they may be
+ combined into a single header (and should be so combined, to reduce
+ overhead).
+
+ For example, the following sequence of Meter headers
+
+ Meter: max-uses=3
+ Meter: max-reuses=10
+ Meter: do-report
+
+ may be expressed as
+
+ Meter: max-uses=3, max-reuses=10, do-report
+
+3.3 Negotiation of hit-metering and usage-limiting
+
+ An origin server that wants to collect hit counts for a resource, by
+ simply forcing all requests to bypass any proxy caches, would respond
+ to requests on the resource with "Cache-control: s-maxage=0". (An
+ origin server wishing to prevent HTTP/1.0 proxies from improperly
+ caching the response could also send both "Expires: <now>", to
+ prevent such caching, and "Cache-control: max-age=NNNN", to allow
+ newer proxies to cache the response).
+
+ The purpose of the Meter header is to obviate the need for "Cache-
+ control: s-maxage=0" within a metering subtree. Thus, any proxy may
+ negotiate the use of hit-metering and/or usage-limiting with the
+ next-hop server. If this server is the origin server, or is already
+ part of a metering subtree (rooted at the origin server), then it may
+ complete the negotiation, thereby extending the metering subtree to
+ include the new proxy.
+
+ To start the negotiation, a proxy sends its request with one of the
+ following Meter directives:
+
+ will-report-and-limit
+ indicates that the proxy is willing and able to
+ return usage reports and will obey any usage-limits.
+
+ wont-report indicates that the proxy will obey usage-limits but
+ will not send usage reports.
+
+ wont-limit indicates that the proxy will not obey usage-limits
+ but will send usage reports.
+
+
+
+Mogul & Leach Standards Track [Page 10]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ A proxy willing to neither obey usage-limits nor send usage reports
+ MUST NOT transmit a Meter header in the request.
+
+ By definition, an empty Meter header:
+
+ Meter:
+
+ is equivalent to "Meter: will-report-and-limit", and so, by the
+ definition of the Connection header (see section 14.10 of the
+ HTTP/1.1 specification [4]), a request that contains
+
+ Connection: Meter
+
+ and no explicit Meter header is equivalent to a request that contains
+
+ Connection: Meter
+ Meter: will-report-and-limit
+
+ This makes the default case more efficient.
+
+ An origin server that is not interested in metering or usage-limiting
+ the requested resource simply ignores the Meter header.
+
+ If the server wants the proxy to do hit-metering and/or usage-
+ limiting, its response should include one or more of the following
+ Meter directives:
+
+ For hit-metering:
+
+ do-report specifies that the proxy MUST send usage reports to
+ the server.
+
+ dont-report specifies that the proxy SHOULD NOT send usage
+ reports to the server.
+
+ timeout=NNN sets a metering timeout of NNN minutes, from the time
+ that this response was originated, for the reporting
+ of a hit-count. If the proxy has a non-zero hit
+ count for this response when the timeout expires, it
+ MUST send a report to the server at or before that
+ time. Implies "do-report".
+
+ By definition, an empty Meter header in a response, or any Meter
+ header that does not contain "dont-report", means "Meter: do-report";
+ this makes a common case more efficient.
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 11]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ Note: an origin server using the metering timeout mechanism to
+ bound the collection period over which hit-counts are obtained
+ should adjust the timeout values in the responses it sends so that
+ all responses generated within that period reach their metering
+ timeouts at or before the end of that period.
+
+ If the origin server simply sends a constant metering timeout T
+ with each response for a resource, the reports that it receives
+ will reflect activity over a period whose duration is between T
+ and N*T (in the worst case), where N is the maximum depth of the
+ metering subtree.
+
+ For usage-limiting
+
+ max-uses=NNN sets an upper limit of NNN "uses" of the response,
+ not counting its immediate forwarding to the
+ requesting end-client, for all proxies in the
+ following subtree taken together.
+
+ max-reuses=NNN sets an upper limit of NNN "reuses" of the response
+ for all proxies in the following subtree taken
+ together.
+
+ When a proxy has exhausted its allocation of "uses" or "reuses" for a
+ cache entry, it MUST revalidate the cache entry (using a conditional
+ request) before returning it in a response. (The proxy SHOULD use
+ this revalidation message to send a usage report, if one was
+ requested and it is time to send it. See sections 3.4 and 3.5.)
+
+ These Meter response-directives apply only to the specific response
+ that they are attached to.
+
+ Note that the limit on "uses" set by the max-uses directive does
+ not include the use of the response to satisfy the end-client
+ request that caused the proxy's request to the server. This
+ counting rule supports the notion of a cache-initiated prefetch: a
+ cache may issue a prefetch request, receive a max-uses=0 response,
+ store that response, and then return that response (without
+ revalidation) when a client makes an actual request for the
+ resource. However, each such response may be used at most once in
+ this way, so the origin server maintains precise control over the
+ number of actual uses.
+
+ A server MUST NOT send a Meter header that would require a proxy to
+ do something that it has not yet offered to do. A proxy receiving a
+ Meter response-directive asking the proxy to do something it did not
+ volunteer to do SHOULD ignore that directive.
+
+
+
+
+Mogul & Leach Standards Track [Page 12]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ A proxy receiving a Meter header in a response MUST either obey it,
+ or it MUST revalidate the corresponding cache entry on every access.
+ (I.e., if it chooses not to obey the Meter header in a response, it
+ MUST act as if the response included "Cache-control: s-maxage=0".)
+
+ Note: a proxy that has not sent the Meter header in a request for
+ the given resource, and which has therefore not volunteered to
+ honor Meter directives in a response, is not required to honor
+ them. If, in this situation, the server does send a Meter header
+ in a response, this is a protocol error. However, based on the
+ robustness principle, the proxy may choose to interpret the Meter
+ header as an implicit request to include "Cache-control: s-
+ maxage=0" when it forwards the response, since this preserves the
+ apparent intention of the server.
+
+ A proxy that receives the Meter header in a request may ignore it
+ only to the extent that this is consistent with its own duty to the
+ next-hop server. If the received Meter request header is
+ inconsistent with that duty, or if no Meter request header is
+ received and the response from the next-hop server requests any form
+ of metering or limiting, then the proxy MUST add "Cache-control: s-
+ maxage=0" to any response it forwards for that request. (A proxy
+ SHOULD NOT add or change the Expires header or max-age Cache-control
+ directive.)
+
+ For example, if proxy A receives a GET request from proxy B for
+ URL X with "Connection: Meter", but proxy A's cached response for
+ URL does not include any Meter directives, then proxy A may ignore
+ the metering offer from proxy B.
+
+ However, if proxy A has previously told the origin server "Meter:
+ wont-limit" (implying will-report), and the cached response
+ contains "Meter: do-report", and proxy B's request includes
+ "Meter: wont-report", then proxy B's offer is inconsistent with
+ proxy A's duty to the origin server. Therefore, in this case
+ proxy A must add "Cache-control: s-maxage=0" when it returns the
+ cached response to proxy B, and must not include a Meter header in
+ this response.
+
+ If a server does not want to use the Meter mechanism, and will not
+ want to use it any time soon, it may send this directive:
+
+ wont-ask recommends that the proxy SHOULD NOT send any Meter
+ directives to this server.
+
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 13]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ The proxy SHOULD remember this fact for up to 24 hours. This avoids
+ virtually all unnecessary overheads for servers that do not wish to
+ use or support the Meter header. (This directive also implies
+ "dont-report".)
+
+3.4 Transmission of usage reports
+
+ To transmit a usage report, a proxy sends the following Meter header
+ in a request on the appropriate resource:
+
+ Meter: count=NNN/MMM
+
+ The first integer indicates the count of uses of the cache entry
+ since the last report; the second integer indicates the count of
+ reuses of the entry (see section 5.3 for rules on counting uses and
+ reuses). The transmission of a "count" directive in a request with
+ no other Meter directive is also defined as an implicit transmission
+ of a "will-report-and-limit" directive, to optimize the common case.
+ (A proxy not willing to honor usage-limits would send "Meter:
+ count=NNN/MMM, wont-limit" for its reports.)
+
+ Note that when a proxy forwards a client's request and receives a
+ response, the response that the proxy sends immediately to the
+ requesting client is not counted as a "use". I.e., the reported
+ count is the number of times the cache entry was used, and not the
+ number of times that the response was used.
+
+ A proxy SHOULD NOT transmit "Meter: count=0/0", since this conveys no
+ useful information.
+
+ Usage reports MUST always be transmitted as part of a conditional
+ request (such as a GET or HEAD), since the information in the
+ conditional header (e.g., If-Modified-Since or If-None-Match) is
+ required for the origin server to know which instance of a resource
+ is being counted. Proxys forwarding usage reports up the metering
+ subtree MUST NOT change the contents of the conditional header, since
+ otherwise this would result in incorrect counting.
+
+ A usage report MUST NOT be transmitted as part of a forwarded request
+ that includes multiple entity tags in an If-None-Match or If-Match
+ header.
+
+ Note: a proxy that offers its willingness to do hit-metering
+ (report usage) must count both uses and reuses. It is not
+ possible to negotiate the reporting of one but not the other.
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 14]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+3.5 When to send usage reports
+
+ A proxy that has offered to send usage reports to its parent in the
+ metering subtree MUST send a usage report in each of these
+ situations:
+
+ 1. When it forwards a conditional GET on the resource
+ instance on behalf of one of its clients (if the GET is
+ conditional on at most one entity-tag).
+
+ 2. When it forwards a conditional HEAD on the resource
+ instance on behalf of one of its clients.
+
+ 3. When it must generate a conditional GET to satisfy a
+ client request because the max-uses limit has been
+ exceeded.
+
+ 4. Upon expiration of a metering timeout associated with a
+ cache entry that has a non-zero hit-count.
+
+ 5. When it removes the corresponding non-zero hit-count entry
+ from its storage for any reason including:
+
+ - the proxy needs the storage space for another
+ hit-count entry.
+
+ - the proxy is not able to store more than one response
+ per resource, and a request forwarded on behalf of a
+ client has resulted in the receipt of a new response
+ (one with a different entity-tag or last-modified
+ time).
+
+ Note that a cache might continue to store hit-count information
+ even after having deleted the body of the response, so it is
+ not necessary to report the hit-count when deleting the body;
+ it is only necessary to report it if the proxy is about to
+ "forget" a non-zero value.
+
+ (Section 5.3 explains how hit-counts become zero or non-zero.)
+
+ If the usage report is being sent because the proxy is about to
+ remove the hit-count entry from its storage, or because of an expired
+ metering timeout:
+
+ - The proxy MUST send the report as part of a conditional
+ HEAD request on the resource instance.
+
+
+
+
+
+Mogul & Leach Standards Track [Page 15]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ - The proxy is not required to retry the HEAD request if it
+ fails (this is a best-efforts design). To improve
+ accuracy, however, the proxy SHOULD retry failed HEAD
+ requests, subject to resource constraints.
+
+ - The proxy is not required to serialize any other operation
+ on the completion of this request.
+
+ Note: proxy implementors are strongly encouraged to batch several
+ HEAD-based reports to the same server, when possible, over a
+ single persistent connection, to reduce network overhead as much
+ as possible. This may involve a non-naive algorithm for
+ scheduling the deletion of hit-count entries.
+
+ If the usage count is sent because of an arriving request that also
+ carries a "count" directive, the proxy MUST combine its own (possibly
+ zero) use and reuse counts with the arriving counts, and then attempt
+ to forward the request.
+
+ However, the proxy is not required to forward an arriving request
+ with a "count" directive, provided that:
+
+ - it can reply to the request using a cached response, in
+ compliance with other requirements of the HTTP
+ specification.
+
+ - such a response does not exceed a max-uses limit.
+
+ - it is not required to forward the request because of an
+ expired metering timeout.
+
+ If an arriving request carries a "count" directive, and the proxy no
+ longer has a cache entry for the resource, the proxy MUST forward the
+ "count" directive. (This is, in any case, what a proxy without a
+ suitable cache entry would normally do for any valid request it
+ receives.)
+
+3.6 Subdivision of usage-limits
+
+ When an origin server specifies a usage limit, a proxy in the
+ metering subtree may subdivide this limit among its children in the
+ subtree as it sees fit.
+
+ For example, consider the situation with two proxies P1 and P2, each
+ of which uses proxy P3 as a way to reach origin server S. Imagine
+ that S sends P3 a response with
+
+
+
+
+
+Mogul & Leach Standards Track [Page 16]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ Meter: max-uses=10
+
+ The proxies use that response to satisfy the current requesting end-
+ client. The max-uses directive in this example allows the
+ combination of P1, P2, and P3 together to satisfy 10 additional end-
+ client uses (unconditional GETs) for the resource.
+
+ This specification does not constrain how P3 divides up that
+ allocation among itself and the other proxies. For example, P3 could
+ retain all of max-use allocation for itself. In that case, it would
+ forward the response to P1 and/or P2 with
+
+ Meter: max-uses=0
+
+ P3 might also divide the allocation equally among P1 and P2,
+ retaining none for itself (which may be the right choice if P3 has
+ few or no other clients). In this case, it could send
+
+ Meter: max-uses=5
+
+ to the proxy (P1 or P2) that made the initial request, and then
+ record in some internal data structure that it "owes" the other proxy
+ the rest of the allocation.
+
+ Note that this freedom to choose the max-uses value applies to the
+ origin server, as well. There is no requirement that an origin
+ server send the same max-uses value to all caches. For example, it
+ might make sense to send "max-uses=2" the first time one hears from a
+ cache, and then double the value (up to some maximum limit) each time
+ one gets a "use-count" from that cache. The idea is that the faster
+ a cache is using up its max-use quota, the more likely it will be to
+ report a use-count value before removing the cache entry. Also, high
+ and frequent use-counts imply a corresponding high efficiency benefit
+ from allowing caching.
+
+ Again, the details of such heuristics would be outside the scope of
+ this specification.
+
+4 Analysis
+
+ This section includes informal analyses of several aspects of hit-
+ metering:
+
+ 1. the accuracy of results when applied to counting users
+ (section 4.1).
+
+ 2. the problem of counting users whose browsers do not
+ include caches, such as Network Computers (section 4.2).
+
+
+
+Mogul & Leach Standards Track [Page 17]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ 3. delays imposed on "critical paths" for HTTP operations
+ (section 4.3).
+
+4.1 Approximation accuracy for counting users
+
+ For many (but not all) service operators, the single most important
+ aspect of the request stream is the number of distinct users who have
+ retrieved a particular entity within a given period (e.g., during a
+ given day). The hit-metering mechanism is designed to provide an
+ origin server with an approximation of the number of users that
+ reference a given resource. The intent of the design is that the
+ precision of this approximation is consistent with the goals of
+ simplicity and optional implementation.
+
+ Almost all Web users use client software that maintains local caches,
+ and the state of the art of local-caching technology is quite
+ effective. (Section 4.2 discusses the case where end-client caches
+ are small or non-existent.) Therefore, assuming an effective and
+ persistent end-client cache, each individual user who retrieves an
+ entity does exactly one GET request that results in a 200 or 203
+ response, or a 206 response that includes the first byte of the
+ entity. If a proxy cache maintains and reports an accurate use-count
+ of such retrievals, then its reported use-count will closely
+ approximate the number of distinct users who have retrieved the
+ entity.
+
+ There are some circumstances under which this approximation can break
+ down. For example, if an entity stays in a proxy cache for much
+ longer than it persists in the typical client cache, and users often
+ re-reference the entity, then this scheme will tend to over-count the
+ number of users. Or, if the cache-management policy implemented in
+ typical client caches is biased against retaining certain kinds of
+ frequently re-referenced entities (such as very large images), the
+ use-counts reported will tend to overestimate the user-counts for
+ such entities.
+
+ Browser log analysis has shown that when a user revisits a resource,
+ this is almost always done very soon after the previous visit, almost
+ always with fewer than eight intervening references [11]. Although
+ this result might not apply universally, it implies that almost all
+ reuses will hit in the end-client cache, and will not be seen as
+ unconditional GETs by a proxy cache.
+
+ The existing (HTTP/1.0) "cache-busting" mechanisms for counting
+ distinct users will certainly overestimate the number of users behind
+ a proxy, since it provides no reliable way to distinguish between a
+ user's initial request and subsequent repeat requests that might have
+ been conditional GETs, had not cache-busting been employed. The
+
+
+
+Mogul & Leach Standards Track [Page 18]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ "Cache-control: s-maxage=0" feature of HTTP/1.1 does allow the
+ separation of use-counts and reuse-counts, provided that no HTTP/1.0
+ proxy caches intervene.
+
+ Note that if there is doubt about the validity of the results of
+ hit-metering a given set of resources, the server can employ cache-
+ busting techniques for short periods, to establish a baseline for
+ validating the hit-metering results. Various approaches to this
+ problem are discussed in a paper by James Pitkow [9].
+
+4.2 What about "Network Computers"?
+
+ The analysis in section 4.1 assumed that "almost all Web users" have
+ client caches. If the Network Computers (NC) model becomes popular,
+ however, then this assumption may be faulty: most proposed NCs have
+ no disk storage, and relatively little RAM. Many Personal Digital
+ Assistants (PDAs), which sometimes have network access, have similar
+ constraints. Such client systems may do little or no caching of HTTP
+ responses. This means that a single user might well generate many
+ unconditional GETs that yield the same response from a proxy cache.
+
+ First note that the hit-metering design in this document, even with
+ such clients, provides an approximation no worse than available with
+ unmodified HTTP/1.1: the counts that a proxy would return to an
+ origin server would represent exactly the number of requests that the
+ proxy would forward to the server, if the server simply specifies
+ "Cache-control: s-maxage=0".
+
+ However, it may be possible to improve the accuracy of these hit-
+ counts by use of some heuristics at the proxy. For example, the
+ proxy might note the IP address of the client, and count only one GET
+ per client address per response. This is not perfect: for example,
+ it fails to distinguish between NCs and certain other kinds of hosts.
+ The proxy might also use the heuristic that only those clients that
+ never send a conditional GET should be treated this way, although we
+ are not at all certain that NCs will never send conditional GETs.
+
+ Since the solution to this problem appears to require heuristics
+ based on the actual behavior of NCs (or perhaps a new HTTP protocol
+ feature that allows unambiguous detection of cacheless clients), it
+ appears to be premature to specify a solution.
+
+4.3 Critical-path delay analysis
+
+ In systems (such as the Web) where latency is at issue, there is
+ usually a tree of steps which depend on one another, in such a way
+ that the final result cannot be accomplished until all of its
+ predecessors have been. Since the tree structure admits some
+
+
+
+Mogul & Leach Standards Track [Page 19]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ parallelism, it is not necessary to add up the timings for each step
+ to discover the latency for the entire process. But any single path
+ through this dependency tree cannot be parallelized, and the longest
+ such path is the one whose length (in units of seconds) determines
+ the overall latency. This is the "critical path", because no matter
+ how much shorter one makes any other path, that cannot change the
+ overall latency for the final result.
+
+ If one views the final result, for a Web request, as rendering a page
+ at a browser, or otherwise acting on the result of a request, clearly
+ some network round trips (e.g., exchanging TCP SYN packets if the
+ connection doesn't already exist) are on the critical path. This
+ hit-metering design does add some round-trips for reporting non-zero
+ counts when a cache entry is removed, but, by design, these are off
+ any critical path: they may be done in parallel with any other
+ operation, and require only "best efforts", so a proxy does not have
+ to serialize other operations with their success or failure.
+
+ Clearly, anything that changes network utilization (either increasing
+ or decreasing it) can indirectly affect user-perceived latency. Our
+ expectation is that hit-metering, on average, will reduce loading and
+ so even its indirect effects should not add network round-trips in
+ any critical path. But there might be a few specific instances where
+ the added non-critical-path operations (specifically, usage reports
+ upon cache-entry removal) delay an operation on a critical path.
+ This is an unavoidable problem in datagram networks.
+
+5 Specification
+
+5.1 Specification of Meter header and directives
+
+ The Meter general-header field is used to:
+
+ - Negotiate the use of hit-metering and usage-limiting among
+ origin servers and proxy caches.
+
+ - Report use counts and reuse counts.
+
+ Implementation of the Meter header is optional for both proxies and
+ origin servers. However, any proxy that transmits the Meter header
+ in a request MUST implement every requirement of this specification,
+ without exception or amendment.
+
+ The Meter header MUST always be protected by a Connection header. A
+ proxy that does not implement the Meter header MUST NOT pass it
+ through to another system (see section 5.5 for how a non-caching
+ proxy may comply with this specification). If a Meter header is
+
+
+
+
+Mogul & Leach Standards Track [Page 20]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ received in a message whose version is less than HTTP/1.1, it MUST be
+ ignored (because it has clearly flowed through a proxy that does not
+ implement Meter).
+
+ A proxy that has received a response with a version less than
+ HTTP/1.1, and therefore from a server (or another proxy) that does
+ not implement the Meter header, SHOULD NOT send Meter request
+ directives to that server, because these would simply waste
+ bandwidth. This recommendation does not apply if the proxy is
+ currently hit-metering or usage-limiting any responses from that
+ server. If the proxy receives a HTTP/1.1 or higher response from
+ such a server, it should cease its suppression of the Meter
+ directives.
+
+ All proxies sending the Meter header MUST adhere to the "metering
+ subtree" design described in section 3.
+
+ Meter = "Meter" ":" 0#meter-directive
+
+ meter-directive = meter-request-directive
+ | meter-response-directive
+ | meter-report-directive
+
+ meter-request-directive =
+ "will-report-and-limit"
+ | "wont-report"
+ | "wont-limit"
+
+ meter-report-directive =
+ | "count" "=" 1*DIGIT "/" 1*DIGIT
+
+ meter-response-directive =
+ "max-uses" "=" 1*DIGIT
+ | "max-reuses" "=" 1*DIGIT
+ | "do-report"
+ | "dont-report"
+ | "timeout" "=" 1*DIGIT
+ | "wont-ask"
+
+ A meter-request-directive or meter-report-directive may only appear
+ in an HTTP request message. A meter-response-directive may only
+ appear in an HTTP response directive.
+
+ An empty Meter header in a request means "Meter: will-report-and-
+ limit". An empty Meter header in a response, or any other response
+ including one or more Meter headers without the "dont-report" or
+ "wont-ask" directive, implies "Meter: do-report".
+
+
+
+
+Mogul & Leach Standards Track [Page 21]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ The meaning of the meter-request-directives are as follows:
+
+ will-report-and-limit
+ indicates that the proxy is willing and able to
+ return usage reports and will obey any usage-limits.
+
+ wont-report indicates that the proxy will obey usage-limits but
+ will not send usage reports.
+
+ wont-limit indicates that the proxy will not obey usage-limits
+ but will send usage reports.
+
+ A proxy willing neither to obey usage-limits nor to send usage
+ reports MUST NOT transmit a Meter header in the request.
+
+ The meaning of the meter-report-directives are as follows:
+
+ count "=" 1*DIGIT "/" 1*DIGIT
+ Both digit strings encode decimal integers. The
+ first integer indicates the count of uses of the
+ cache entry since the last report; the second integer
+ indicates the count of reuses of the entry.
+
+ Section 5.3 specifies the counting rules.
+
+ The meaning of the meter-response-directives are as follows:
+
+ max-uses "=" 1*DIGIT
+ sets an upper limit on the number of "uses" of the
+ response, not counting its immediate forwarding to
+ the requesting end-client, for all proxies in the
+ following subtree taken together.
+
+ max-reuses "=" 1*DIGIT
+ sets an upper limit on the number of "reuses" of the
+ response for all proxies in the following subtree
+ taken together.
+
+ do-report specifies that the proxy MUST send usage reports to
+ the server.
+
+ dont-report specifies that the proxy SHOULD NOT send usage
+ reports to the server.
+
+ timeout "=" 1*DIGIT
+ sets a metering timeout of the specified number of
+ minutes (not seconds) after the origination of this
+ response (as indicated by its "Date" header). If the
+
+
+
+Mogul & Leach Standards Track [Page 22]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ proxy has a non-zero hit count for this response when
+ the timeout expires, it MUST send a report to the
+ server at or before that time. Timeouts should be
+ implemented with an accuracy of plus or minus one
+ minute. Implies "do-report".
+
+ wont-ask specifies that the proxy SHOULD NOT send any Meter
+ headers to the server. The proxy should forget this
+ advice after a period of no more than 24 hours.
+
+ Section 5.3 specifies the counting rules, and in particular specifies
+ a somewhat non-obvious interpretation of the max-uses value.
+
+5.2 Abbreviations for Meter directives
+
+ To allow for the most efficient possible encoding of Meter headers,
+ we define abbreviated forms of all Meter directives. These are
+ exactly semantically equivalent to their non-abbreviated
+ counterparts. All systems implementing the Meter header MUST
+ implement both the abbreviated and non-abbreviated forms.
+ Implementations SHOULD use the abbreviated forms in normal use.
+
+ The abbreviated forms of Meter directive are shown below, with the
+ corresponding non-abbreviated literals in the comments:
+
+ Abb-Meter = "Meter" ":" 0#abb-meter-directive
+
+ abb-meter-directive = abb-meter-request-directive
+ | abb-meter-response-directive
+ | abb-meter-report-directive
+
+ abb-meter-request-directive =
+ "w" ; "will-report-and-limit"
+ | "x" ; "wont-report"
+ | "y" ; "wont-limit"
+
+ abb-meter-report-directive =
+ | "c" "=" 1*DIGIT "/" 1*DIGIT ; "count"
+
+ abb-meter-response-directive =
+ "u" "=" 1*DIGIT ; "max-uses"
+ | "r" "=" 1*DIGIT ; "max-reuses"
+ | "d" ; "do-report"
+ | "e" ; "dont-report"
+ | "t" "=" 1*DIGIT ; "timeout"
+ | "n" ; "wont-ask"
+
+
+
+
+
+Mogul & Leach Standards Track [Page 23]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ Note: although the Abb-Meter BNF rule is defined separately from
+ the Meter rule, one may freely mix abbreviated and non-abbreviated
+ Meter directives in the same header.
+
+5.3 Counting rules
+
+ Note: please remember that hit-counts and usage-counts are
+ associated with individual responses, not with resources. A cache
+ entry that, over its lifetime, holds more than one response is
+ also not a "response", in this particular sense.
+
+ Let R be a cached response, and V be the value of the Request-URI and
+ selecting request-headers (if any, see section 14.43 of the HTTP/1.1
+ specification [4]) that would select R if contained in a request. We
+ define a "use" of R as occurring when the proxy returns its stored
+ copy of R in a response with any of the following status codes: a 200
+ (OK) status; a 203 (Non-Authoritative Information) status; or a 206
+ (Partial Content) status when the response contains byte #0 of the
+ entity (see section 5.4 for a discussion of Range requests).
+
+ Note: when a proxy forwards a client's request and receives a
+ response, the response that the proxy sends immediately to the
+ requesting client is not counted as a "use". I.e., the reported
+ count is the number of times the cache entry was used, and not the
+ number of times that the response was used.
+
+ We define a "reuse" of R as as occurring when the proxy responds to a
+ request selecting R with a 304 (Not Modified) status, unless that
+ request is a Range request that does not specify byte #0 of the
+ entity.
+
+5.3.1 Counting rules for hit-metering
+
+ A proxy participating in hit-metering for a cache response R
+ maintains two counters, CU and CR, associated with R. When a proxy
+ first stores R in its cache, it sets both CU and CR to 0 (zero).
+ When a subsequent client request results in a "use" of R, the proxy
+ increments CU. When a subsequent client request results in a "reuse"
+ of R, the proxy increments CR. When a subsequent client request
+ selecting R (i.e., including V) includes a "count" Meter directive,
+ the proxy increments CU and CR using the corresponding values in the
+ directive.
+
+ When the proxy sends a request selecting R (i.e., including V) to the
+ inbound server, it includes a "count" Meter directive with the
+ current CU and CR as the parameter values. If this request was
+ caused by the proxy's receipt of a request from a client, upon
+ receipt of the server's response, the proxy sets CU and CR to the
+
+
+
+Mogul & Leach Standards Track [Page 24]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ number of uses and reuses, respectively, that may have occurred while
+ the request was in progress. (These numbers are likely, but not
+ certain, to be zero.) If the proxy's request was a final HEAD-based
+ report, it need no longer maintain the CU and CR values, but it may
+ also set them to the number of intervening uses and reuses and retain
+ them.
+
+5.3.2 Counting rules for usage-limiting
+
+ A proxy participating in usage-limiting for a response R maintains
+ either or both of two counters TU and TR, as appropriate, for that
+ resource. TU and TR are incremented in just the same way as CU and
+ CR, respectively. However, TU is zeroed only upon receipt of a
+ "max-uses" Meter directive for that response (including the initial
+ receipt). Similarly, TR is zeroed only upon receipt of a "max-
+ reuses" Meter directive for that response.
+
+ A proxy participating in usage-limiting for a response R also stores
+ values MU and/or MR associated with R. When it receives a response
+ including only a max-uses value, it sets MU to that value and MR to
+ infinity. When it receives a response including only a max-reuses
+ value, it sets MR to that value and MU to infinity. When it receives
+ a response including both max-reuses and max-reuses values, it sets
+ MU and MR to those values, respectively. When it receives a
+ subsequent response including neither max-reuses nor max-reuses
+ values, it sets both MU and MR to infinity.
+
+ If a proxy participating in usage-limiting for a response R receives
+ a request that would cause a "use" of R, and TU >= MU, it MUST
+ forward the request to the server. If it receives a request that
+ would cause a "reuse" of R, and TR >= MR, it MUST forward the request
+ to the server. If (in either case) the proxy has already forwarded a
+ previous request to the server and is waiting for the response, it
+ should delay further handling of the new request until the response
+ arrives (or times out); it SHOULD NOT have two revalidation requests
+ pending at once that select the same response, unless these are Range
+ requests selecting different subranges.
+
+ There is a special case of this rule for the "max-uses" directive: if
+ the proxy receives a response with "max-uses=0" and does not forward
+ it to a requesting client, the proxy should set a flag PF associated
+ with R. If R is true, then when a request arrives while if TU >= MU,
+ if the PF flag is set, then the request need not be forwarded to the
+ server (provided that this is not required by other caching rules).
+ However, the PF flag MUST be cleared on any use of the response.
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 25]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ Note: the "PF" flag is so named because this feature is useful
+ only for caches that could issue a "prefetch" request before an
+ actual client request for the response. A proxy not implementing
+ prefetching need not implement the PF flag.
+
+5.3.3 Equivalent algorithms are allowed
+
+ Any other algorithm that exhibits the same external behavior (i.e.,
+ generates exactly the same requests from the proxy to the server) as
+ the one in this section is explicitly allowed.
+
+ Note: in most cases, TU will be equal to CU, and TR will be
+ equal to CR. The only two cases where they could differ are:
+
+ 1. The proxy issues a non-conditional request for the
+ resource using V, while TU and/or TR are non-zero, and
+ the server's response includes a new "max-uses" and/or
+ "max-reuses" directive (thus zeroing TU and/or TR, but
+ not CU and CR).
+
+ 2. The proxy issues a conditional request reporting the
+ hit-counts (and thus zeroing CU and CR, but not TU or
+ TR), but the server's response does not include a new
+ "max-uses" and/or "max-reuses" directive.
+
+ To solve the first case, the proxy has several implementation
+ options
+
+ - Always store TU and TR separately from CU and CR.
+
+ - Create "shadow" copies of TU and TR when this situation
+ arises (analogous to "copy on write").
+
+ - Generate a HEAD-based usage report when the
+ non-conditional request is sent (or when the
+ "max-uses=0" is received), causing CU and CR to be
+ zeroed (analogous in some ways to a "memory barrier"
+ instruction).
+
+ In the second case, the server implicitly has removed the
+ usage-limit(s) on the response (by setting MU and/or MR to
+ infinity), and so the fact that, say, TU is different from CU
+ is not significant.
+
+ Note: It may also be possible to eliminate the PF flag by
+ sending extra HEAD-based usage-report requests, but we
+ recommend against this; it is better to allocate an extra bit
+ per entry than to transmit extra requests.
+
+
+
+Mogul & Leach Standards Track [Page 26]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+5.4 Counting rules: interaction with Range requests
+
+
+ HTTP/1.1 allows a client to request sub-ranges of a resource. A
+ client might end up issuing several requests with the net effect of
+ receiving one copy of the resource. For uniformity of the results
+ seen by origin servers, proxies need to observe a rule for counting
+ these references, although it is not clear that one rule generates
+ accurate results in every case.
+
+ The rule established in this specification is that proxies count as a
+ "use" or "reuse" only those Range requests that result in the return
+ of byte #0 of the resource. The rationale for this rule is that in
+ almost every case, an end-client will retrieve the beginning of any
+ resource that it references at all, and that it will seldom retrieve
+ any portion more than once. Therefore, this rule appears to meet the
+ goal of a "best-efforts" approximation.
+
+5.5 Implementation by non-caching proxies
+
+ A non-caching proxy may participate in the metering subtree; this is
+ strongly recommended.
+
+ A non-caching proxy (HTTP/1.1 or higher) that participates in the
+ metering subtree SHOULD forward Meter headers on both requests and
+ responses, with the appropriate Connection headers.
+
+ If a non-caching proxy forwards Meter headers, it MUST comply with
+ these restrictions:
+
+ 1. If the proxy forwards Meter headers in responses, such a
+ response MUST NOT be returned to any request except the
+ one that elicited it.
+
+ 2. Once a non-caching proxy starts forwarding Meter headers,
+ it should not arbitrarily stop forwarding them (or else
+ reports may be lost).
+
+ A proxy that caches some responses and not others, for whatever
+ reason, may choose to implement the Meter header as a caching proxy
+ for the responses that it caches, and as a non-caching proxy for the
+ responses that it does not cache, as long as its external behavior
+ with respect to any particularly response is fully consistent with
+ this specification.
+
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 27]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+5.6 Implementation by cooperating caches
+
+ Several HTTP cache implementations, most notably the Harvest/Squid
+ cache [2], create cooperative arrangements between several caches.
+ If such caches use a protocol other than HTTP to communicate between
+ themselves, such as the Internet Cache Protocol (ICP) [12], and if
+ they implement the Meter header, then they MUST act to ensure that
+ their cooperation does not violate the intention of this
+ specification.
+
+ In particular, if one member of a group of cooperating caches agrees
+ with a server to hit-meter a particular response, and then passes
+ this response via a non-HTTP protocol to a second cache in the group,
+ the caches MUST ensure that the server which requested the metering
+ receives reports that appropriately account for any uses or resues
+ made by the second cache. Similarly, if the first cache agreed to
+ usage-limit the response, the total number of uses by the group of
+ caches MUST be limited to the agreed-upon number.
+
+6 Examples
+
+6.1 Example of a complete set of exchanges
+
+ This example shows how the protocol is intended to be used most of
+ the time: for hit-metering without usage-limiting. Entity bodies are
+ omitted.
+
+ A client sends request to a proxy:
+
+ GET http://foo.com/bar.html HTTP/1.1
+
+ The proxy forwards request to the origin server:
+
+ GET /bar.html HTTP/1.1
+ Host: foo.com
+ Connection: Meter
+
+ thus offering (implicitly) "will-report-and-limit".
+
+ The server responds to the proxy:
+
+ HTTP/1.1 200 OK
+ Date: Fri, 06 Dec 1996 18:44:29 GMT
+ Cache-control: max-age=3600
+ Connection: meter
+ Etag: "abcde"
+
+
+
+
+
+Mogul & Leach Standards Track [Page 28]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ thus (implicitly) requiring "do-report" (but not requiring
+ usage-limiting).
+
+ The proxy responds to the client:
+
+ HTTP/1.1 200 OK
+ Date: Fri, 06 Dec 1996 18:44:29 GMT
+ Etag: "abcde"
+ Cache-control: max-age=3600, proxy-mustcheck
+ Age: 1
+
+ Since the proxy does not know if its client is an end-system, or a
+ proxy that doesn't do metering, it adds the "proxy-mustcheck"
+ directive.
+
+ Another client soon asks for the resource:
+
+ GET http://foo.com/bar.html HTTP/1.1
+
+ and the proxy sends the same response as it sent to the other client,
+ except (perhaps) for the Age value.
+
+ After an hour has passed, a third client asks for the response:
+
+ GET http://foo.com/bar.html HTTP/1.1
+
+ But now the response's max-age has been exceeded, so the proxy
+ revalidates the response with the origin server:
+
+ GET /bar.html HTTP/1.1
+ If-None-Match: "abcde"
+ Host: foo.com
+ Connection: Meter
+ Meter: count=1/0
+
+ thus simultaneously fulfilling its duties to validate the response
+ and to report the one "use" that wasn't forwarded.
+
+ The origin server responds:
+
+ HTTP/1.1 304 Not Modified
+ Date: Fri, 06 Dec 1996 19:44:29 GMT
+ Cache-control: max-age=3600
+ Etag: "abcde"
+
+ so the proxy can use the original response to reply to the new
+ client; the proxy also zeros the use-count it associates with that
+ response.
+
+
+
+Mogul & Leach Standards Track [Page 29]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ Another client soon asks for the resource:
+
+ GET http://foo.com/bar.html HTTP/1.1
+
+ and the proxy sends the appropriate response.
+
+ After another few hours, the proxy decides to remove the cache entry.
+ When it does so, it sends to the origin server:
+
+ HEAD /bar.html HTTP/1.1
+ If-None-Match: "abcde"
+ Host: foo.com
+ Connection: Meter
+ Meter: count=1/0
+
+ reporting that one more use of the response was satisfied from the
+ cache.
+
+6.2 Protecting against HTTP/1.0 proxies
+
+ An origin server that does not want HTTP/1.0 caches to store the
+ response at all, and is willing to have HTTP/1.0 end-system clients
+ generate excess GETs (which will be forwarded by HTTP/1.0 proxies)
+ could send this for its reply:
+
+ HTTP/1.1 200 OK
+ Cache-control: max-age=3600
+ Connection: meter
+ Etag: "abcde"
+ Expires: Sun, 06 Nov 1994 08:49:37 GMT
+
+ HTTP/1.0 caches will see the ancient Expires header, but HTTP/1.1
+ caches will see the max-age directive and will ignore Expires.
+
+ Note: although most major HTTP/1.0 proxy implementations observe
+ the Expires header, it is possible that some are in use that do
+ not. Use of the Expires header to prevent caching by HTTP/1.0
+ proxies might not be entirely reliable.
+
+6.3 More elaborate examples
+
+ Here is a request from a proxy that is willing to hit-meter but is
+ not willing to usage-limit:
+
+ GET /bar.html HTTP/1.1
+ Host: foo.com
+ Connection: Meter
+ Meter: wont-limit
+
+
+
+Mogul & Leach Standards Track [Page 30]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ Here is a response from an origin server that does not want hit
+ counting, but does want "uses" limited to 3, and "reuses" limited to
+ 6:
+
+ HTTP/1.1 200 OK
+ Cache-control: max-age=3600
+ Connection: meter
+ Etag: "abcde"
+ Expires: Sun, 06 Nov 1994 08:49:37 GMT
+ Meter: max-uses=3, max-reuses=6, dont-report
+
+ Here is the same example with abbreviated Meter directive names:
+
+ HTTP/1.1 200 OK
+ Cache-control: max-age=3600
+ Connection: meter
+ Etag: "abcde"
+ Expires: Sun, 06 Nov 1994 08:49:37 GMT
+ Meter:u=3,r=6,e
+
+7 Interactions with content negotiation
+
+ This section describes two aspects of the interaction between hit-
+ metering and "content-negotiated" resources:
+
+ 1. treatment of responses carrying a Vary header (section
+ 7.1).
+
+ 2. treatment of responses that use the proposed Transparent
+ Content Negotiation mechanism (section 7.2).
+
+7.1 Treatment of responses carrying a Vary header
+
+ Separate counts should be kept for each combination of the headers
+ named in the Vary header for the Request-URI (what [4] calls "the
+ selecting request-headers"), even if they map to the same entity-tag.
+ This rule has the effect of counting hits on each variant, if there
+ are multiple variants of a page available.
+
+ Note: This interaction between Vary and the hit-counting
+ directives allows the origin server a lot of flexibility in
+ specifying how hits should be counted. In essence, the origin
+ server uses the Vary mechanism to divide the requests for a
+ resource into arbitrary categories, based on the request- headers.
+ (We will call these categories "request-patterns".) Since a proxy
+ keeps its hit-counts for each request-pattern, rather than for
+ each resource, the origin server can obtain separate statistics
+ for many aspects of an HTTP request.
+
+
+
+Mogul & Leach Standards Track [Page 31]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ For example, if a page varied based on the value of the User-Agent
+ header in the requests, then hit counts would be kept for each
+ different flavor of browser. But it is in fact more general than
+ that; because multiple header combinations can map to the same
+ variant, it also enables the origin server to count the number of
+ times (e.g.) the Swahili version of a page was requested, even though
+ it is only available in English.
+
+ If a proxy does not support the Vary mechanism, then [4] says that it
+ MUST NOT cache any response that carries a Vary header, and hence
+ need not implement any aspect of this hit-counting or usage-limiting
+ design for varying resources.
+
+ Note: this also implies that if a proxy supports the Vary
+ mechanism but is not willing to maintain independent hit-counts
+ for each variant response in its cache, then it must follow at
+ least one of these rules:
+
+ 1. It must not use the Meter header in a request to offer
+ to hit-meter or usage-limit responses.
+
+ 2. If it does offer to hit-meter or usage-limit responses,
+ and then receives a response that includes both a Vary
+ header and a Meter header with a directive that it
+ cannot satisfy, then the proxy must not cache the
+ response.
+
+ In other words, a proxy is allowed to partially implement the
+ Vary mechanism with respect to hit-metering, as long as this has
+ no externally visible effect on its ability to comply with the
+ Meter specification.
+
+ This approach works for counting almost any aspect of the request
+ stream, without embedding any specific list of countable aspects in
+ the specification or proxy implementation.
+
+7.2 Interaction with Transparent Content Negotiation
+
+ [A description of the interaction between this design and the
+ proposed Transparent Content Negotiation (TCN) design [6] will be
+ made available in a later document.]
+
+8 A Note on Capturing Referrals
+
+ It is alleged that some advertisers want to pay content providers,
+ not by the "hit", but by the "nibble" -- the number of people who
+ actually click on the ad to get more information.
+
+
+
+
+Mogul & Leach Standards Track [Page 32]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ Now, HTTP already has a mechanism for doing this: the "Referer"
+ header. However, perhaps it ought to be disabled for privacy reasons
+ -- according the HTTP/1.1 spec:
+
+ "Because the source of the link may be private information or may
+ reveal an otherwise private information source, it is strongly
+ recommended that the user be able to select whether or not the
+ Referer field is sent."
+
+ However, in the case of ads, the source of the link actually wants to
+ let the referred-to page know where the reference came from.
+
+ This does not require the addition of any extra mechanism, but rather
+ can use schemes that embed the referrer in the URI in a manner
+ similar to this:
+
+ http://www.blah.com/ad-reference?from=site1
+
+ Such a URI should point to a resource (perhaps a CGI script) which
+ returns a 302 redirect to the real page
+
+ http://www.blah.com/ad-reference.html
+
+ Proxies which do not cache 302s will cause one hit on the redirection
+ page per use, but the real page will get cached. Proxies which do
+ cache 302s and report hits on the cached 302s will behave optimally.
+
+ This approach has the advantage that it works whether or not the
+ end-client has disabled the use of Referer. Combined with the rest
+ of the hit-metering proposal in this design, this approach allows,
+ for example, an advertiser to know how often a reference to an
+ advertisement was made from a particular page.
+
+9 Alternative proposals
+
+ There might be a number of other ways of gathering demographic and
+ usage information; other mechanisms might respond to a different set
+ of needs than this proposal does. This proposal certainly does not
+ preclude the proposal or deployment of other such mechanisms, and
+ many of them may be complementary to and compatible with the
+ mechanism proposed here.
+
+ There has been some speculation that statistical sampling methods
+ might be used to gather reasonably accurate data. One such proposal
+ is to manipulate cache expiration times so that selected resources
+ are uncachable for carefully chosen periods, allowing servers to
+ accurately count accesses during those periods. The hit-metering
+ mechanism proposed here is entirely complementary to that approach,
+
+
+
+Mogul & Leach Standards Track [Page 33]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ since it could be used to reduce the cost of gathering those counts.
+ James Pitkow has written a paper comparing an earlier draft of this
+ hit-metering proposal with sampling approaches [9].
+
+ Phillip Hallam-Baker has proposed using a log-exchange protocol [5],
+ by which a server could request a proxy's logs by making an HTTP
+ request to the proxy. This proposal asserts that it is "believed to
+ operate correctly in configurations involving multiple proxies", but
+ it is not clear that this is true if an outer proxy is used as a
+ (one-way) firewall. The proposal also leaves a number of open
+ issues, such as how an origin server can be sure that all of the
+ proxies in the request subtree actually support log-exchange. It is
+ also not clear how this proposal couples a proxy's support of log-
+ exchange to a server's permission to cache a response.
+
+ For general background on the topic of Web measurement standards, see
+ the discussion by Thomas P. Novak and Donna L. Hoffman [8]. Also see
+ the "Privacy and Demographics Overview" page maintained by by the
+ World Wide Web Consortium [10], which includes a pointer to some
+ tentative proposals for gathering consumer demographics (not just
+ counting references) [3].
+
+10 Security Considerations
+
+ Which outbound clients should a server (proxy or origin) trust to
+ report hit counts? A malicious proxy could easily report a large
+ number of hits on some page, and thus perhaps cause a large payment
+ to a content provider from an advertiser. To help avoid this
+ possibility, a proxy may choose to only relay usage counts received
+ from its outbound proxies to its inbound servers when the proxies
+ have authenticated themselves using Proxy-Authorization and/or they
+ are on a list of approved proxies.
+
+ It is not possible to enforce usage limits if a proxy is willing to
+ cheat (i.e., it offers to limit usage but then ignores a server's
+ Meter directive).
+
+ Regarding privacy: it appears that the design in this document does
+ not reveal any more information about individual users than would
+ already be revealed by implementation of the existing HTTP/1.1
+ support for "Cache-control: max-age=0, proxy-revalidate" or "Cache-
+ control: s-maxage=0". It may, in fact, help to conceal certain
+ aspects of the organizational structure on the outbound side of a
+ proxy. In any case, the conflict between user requirements for
+ anonymity and origin server requirements for demographic information
+ cannot be resolved by purely technical means.
+
+
+
+
+
+Mogul & Leach Standards Track [Page 34]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+11 Acknowledgments
+
+ We gratefully acknowledge the constructive comments received from
+ Anselm Baird-Smith, Ted Hardie, Koen Holtman (who suggested the
+ technique described in section 8), Dave Kristol, Ari Luotonen,
+ Patrick R. McManus, Ingrid Melve, and James Pitkow.
+
+12 References
+
+ 1. Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+ 2. Anwat Chankhunthod, Peter B. Danzig, Chuck Neerdaels, Michael
+ F. Schwartz, and Kurt J. Worrell. A Hierarchical Internet Object
+ Cache. Proc. 1996 USENIX Technical Conf., San Diego, January,
+ 1996, pp. 153-163.
+
+ 3. Daniel W. Connolly. Proposals for Gathering Consumer
+ Demographics.
+ http://www.w3.org/pub/WWW/Demographics/Proposals.html.
+
+ 4. Fielding, R., Gettys, J., Mogul, J., Nielsen, H. and T.
+ Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1," RFC 2068,
+ January, 1997.
+
+ 5. Phillip M. Hallam-Baker. Notification for Proxy Caches. W3C
+ Working Draft WD-proxy-960221, World Wide Web Consortium,
+ February, 1996. http://www.w3.org/pub/WWW/TR/WD-proxy.html.
+
+ 6. Holtman, K., and A. Mutz, "Transparent Content Negotiation in
+ HTTP", Work in Progress.
+
+ 7. Mogul, J., "Forcing HTTP/1.1 proxies to revalidate responses",
+ Work in Progress.
+
+ 8. Thomas P. Novak and Donna L. Hoffman. New Metrics for New Media:
+ Toward the Development of Web Measurement Standards. This is a
+ draft paper, currently available at http://
+ www2000.ogsm.vanderbilt.edu/novak/web.standards/webstand.html.
+ Cited by permission of the author; do not quote or cite without
+ permission.
+
+ 9. James Pitkow. In search of reliable usage data on the WWW.
+ Proc. Sixth International World Wide Web Conference, Santa Clara,
+ CA, April, 1997.
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 35]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+ 10. Joseph Reagle, Rohit Khare, Dan Connolly, and Tim Berners-Lee.
+ Privacy and Demographics Overview.
+ http://www.w3.org/pub/WWW/Demographics/.
+
+ 11. Linda Tauscher and Saul Greenberg. Revisitation Patterns in
+ World Wide Web Navigation. Research Report 96/587/07, Department
+ of Computer Science, University of Calgary, March, 1996.
+ http://www.cpsc.ucalgary.ca/projects/grouplab/
+ papers/96WebReuse/TechReport96.html.
+
+ 12. Wessels, D., and K. Claffy "Internet Cache Protocol (ICP),
+ version 2", RFC 2186, September 1997.
+
+13 Authors' Addresses
+
+ Jeffrey C. Mogul
+ Western Research Laboratory
+ Digital Equipment Corporation
+ 250 University Avenue
+ Palo Alto, California, 94305, U.S.A.
+
+ EMail: mogul@wrl.dec.com
+ Phone: 1 415 617 3304 (email preferred)
+
+
+ Paul J. Leach
+ Microsoft
+ 1 Microsoft Way
+ Redmond, Washington, 98052, U.S.A.
+
+ EMail: paulle@microsoft.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 36]
+\f
+RFC 2227 Hit-Metering and Usage-Limiting October 1997
+
+
+14 Full Copyright Statement
+
+ Copyright (C) The Internet Society (1997). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implmentation may be prepared, copied, published
+ andand distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mogul & Leach Standards Track [Page 37]
+\f
--- /dev/null
+
+
+
+
+
+
+Network Working Group Y. Goland
+Request for Comments: 2518 Microsoft
+Category: Standards Track E. Whitehead
+ UC Irvine
+ A. Faizi
+ Netscape
+ S. Carter
+ Novell
+ D. Jensen
+ Novell
+ February 1999
+
+
+ HTTP Extensions for Distributed Authoring -- WEBDAV
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+Abstract
+
+ This document specifies a set of methods, headers, and content-types
+ ancillary to HTTP/1.1 for the management of resource properties,
+ creation and management of resource collections, namespace
+ manipulation, and resource locking (collision avoidance).
+
+Table of Contents
+
+ ABSTRACT............................................................1
+ 1 INTRODUCTION .....................................................5
+ 2 NOTATIONAL CONVENTIONS ...........................................7
+ 3 TERMINOLOGY ......................................................7
+ 4 DATA MODEL FOR RESOURCE PROPERTIES ...............................8
+ 4.1 The Resource Property Model ...................................8
+ 4.2 Existing Metadata Proposals ...................................8
+ 4.3 Properties and HTTP Headers ...................................9
+ 4.4 Property Values ...............................................9
+ 4.5 Property Names ...............................................10
+ 4.6 Media Independent Links ......................................10
+ 5 COLLECTIONS OF WEB RESOURCES ....................................11
+
+
+
+Goland, et al. Standards Track [Page 1]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ 5.1 HTTP URL Namespace Model .....................................11
+ 5.2 Collection Resources .........................................11
+ 5.3 Creation and Retrieval of Collection Resources ...............12
+ 5.4 Source Resources and Output Resources ........................13
+ 6 LOCKING .........................................................14
+ 6.1 Exclusive Vs. Shared Locks ...................................14
+ 6.2 Required Support .............................................16
+ 6.3 Lock Tokens ..................................................16
+ 6.4 opaquelocktoken Lock Token URI Scheme ........................16
+ 6.4.1 Node Field Generation Without the IEEE 802 Address ........17
+ 6.5 Lock Capability Discovery ....................................19
+ 6.6 Active Lock Discovery ........................................19
+ 6.7 Usage Considerations .........................................19
+ 7 WRITE LOCK ......................................................20
+ 7.1 Methods Restricted by Write Locks ............................20
+ 7.2 Write Locks and Lock Tokens ..................................20
+ 7.3 Write Locks and Properties ...................................20
+ 7.4 Write Locks and Null Resources ...............................21
+ 7.5 Write Locks and Collections ..................................21
+ 7.6 Write Locks and the If Request Header ........................22
+ 7.6.1 Example - Write Lock ......................................22
+ 7.7 Write Locks and COPY/MOVE ....................................23
+ 7.8 Refreshing Write Locks .......................................23
+ 8 HTTP METHODS FOR DISTRIBUTED AUTHORING ..........................23
+ 8.1 PROPFIND .....................................................24
+ 8.1.1 Example - Retrieving Named Properties .....................25
+ 8.1.2 Example - Using allprop to Retrieve All Properties ........26
+ 8.1.3 Example - Using propname to Retrieve all Property Names ...29
+ 8.2 PROPPATCH ....................................................31
+ 8.2.1 Status Codes for use with 207 (Multi-Status) ..............31
+ 8.2.2 Example - PROPPATCH .......................................32
+ 8.3 MKCOL Method .................................................33
+ 8.3.1 Request ...................................................33
+ 8.3.2 Status Codes ..............................................33
+ 8.3.3 Example - MKCOL ...........................................34
+ 8.4 GET, HEAD for Collections ....................................34
+ 8.5 POST for Collections .........................................35
+ 8.6 DELETE .......................................................35
+ 8.6.1 DELETE for Non-Collection Resources .......................35
+ 8.6.2 DELETE for Collections ....................................36
+ 8.7 PUT ..........................................................36
+ 8.7.1 PUT for Non-Collection Resources ..........................36
+ 8.7.2 PUT for Collections .......................................37
+ 8.8 COPY Method ..................................................37
+ 8.8.1 COPY for HTTP/1.1 resources ...............................37
+ 8.8.2 COPY for Properties .......................................38
+ 8.8.3 COPY for Collections ......................................38
+ 8.8.4 COPY and the Overwrite Header .............................39
+
+
+
+Goland, et al. Standards Track [Page 2]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ 8.8.5 Status Codes ..............................................39
+ 8.8.6 Example - COPY with Overwrite .............................40
+ 8.8.7 Example - COPY with No Overwrite ..........................40
+ 8.8.8 Example - COPY of a Collection ............................41
+ 8.9 MOVE Method ..................................................42
+ 8.9.1 MOVE for Properties .......................................42
+ 8.9.2 MOVE for Collections ......................................42
+ 8.9.3 MOVE and the Overwrite Header .............................43
+ 8.9.4 Status Codes ..............................................43
+ 8.9.5 Example - MOVE of a Non-Collection ........................44
+ 8.9.6 Example - MOVE of a Collection ............................44
+ 8.10 LOCK Method ..................................................45
+ 8.10.1 Operation .................................................46
+ 8.10.2 The Effect of Locks on Properties and Collections .........46
+ 8.10.3 Locking Replicated Resources ..............................46
+ 8.10.4 Depth and Locking .........................................46
+ 8.10.5 Interaction with other Methods ............................47
+ 8.10.6 Lock Compatibility Table ..................................47
+ 8.10.7 Status Codes ..............................................48
+ 8.10.8 Example - Simple Lock Request .............................48
+ 8.10.9 Example - Refreshing a Write Lock .........................49
+ 8.10.10 Example - Multi-Resource Lock Request ....................50
+ 8.11 UNLOCK Method ................................................51
+ 8.11.1 Example - UNLOCK ..........................................52
+ 9 HTTP HEADERS FOR DISTRIBUTED AUTHORING ..........................52
+ 9.1 DAV Header ...................................................52
+ 9.2 Depth Header .................................................52
+ 9.3 Destination Header ...........................................54
+ 9.4 If Header ....................................................54
+ 9.4.1 No-tag-list Production ....................................55
+ 9.4.2 Tagged-list Production ....................................55
+ 9.4.3 not Production ............................................56
+ 9.4.4 Matching Function .........................................56
+ 9.4.5 If Header and Non-DAV Compliant Proxies ...................57
+ 9.5 Lock-Token Header ............................................57
+ 9.6 Overwrite Header .............................................57
+ 9.7 Status-URI Response Header ...................................57
+ 9.8 Timeout Request Header .......................................58
+ 10 STATUS CODE EXTENSIONS TO HTTP/1.1 ............................59
+ 10.1 102 Processing ...............................................59
+ 10.2 207 Multi-Status .............................................59
+ 10.3 422 Unprocessable Entity .....................................60
+ 10.4 423 Locked ...................................................60
+ 10.5 424 Failed Dependency ........................................60
+ 10.6 507 Insufficient Storage .....................................60
+ 11 MULTI-STATUS RESPONSE .........................................60
+ 12 XML ELEMENT DEFINITIONS .......................................61
+ 12.1 activelock XML Element .......................................61
+
+
+
+Goland, et al. Standards Track [Page 3]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ 12.1.1 depth XML Element .........................................61
+ 12.1.2 locktoken XML Element .....................................61
+ 12.1.3 timeout XML Element .......................................61
+ 12.2 collection XML Element .......................................62
+ 12.3 href XML Element .............................................62
+ 12.4 link XML Element .............................................62
+ 12.4.1 dst XML Element ...........................................62
+ 12.4.2 src XML Element ...........................................62
+ 12.5 lockentry XML Element ........................................63
+ 12.6 lockinfo XML Element .........................................63
+ 12.7 lockscope XML Element ........................................63
+ 12.7.1 exclusive XML Element .....................................63
+ 12.7.2 shared XML Element ........................................63
+ 12.8 locktype XML Element .........................................64
+ 12.8.1 write XML Element .........................................64
+ 12.9 multistatus XML Element ......................................64
+ 12.9.1 response XML Element ......................................64
+ 12.9.2 responsedescription XML Element ...........................65
+ 12.10 owner XML Element ...........................................65
+ 12.11 prop XML element ............................................66
+ 12.12 propertybehavior XML element ................................66
+ 12.12.1 keepalive XML element ....................................66
+ 12.12.2 omit XML element .........................................67
+ 12.13 propertyupdate XML element ..................................67
+ 12.13.1 remove XML element .......................................67
+ 12.13.2 set XML element ..........................................67
+ 12.14 propfind XML Element ........................................68
+ 12.14.1 allprop XML Element ......................................68
+ 12.14.2 propname XML Element .....................................68
+ 13 DAV PROPERTIES ................................................68
+ 13.1 creationdate Property ........................................69
+ 13.2 displayname Property .........................................69
+ 13.3 getcontentlanguage Property ..................................69
+ 13.4 getcontentlength Property ....................................69
+ 13.5 getcontenttype Property ......................................70
+ 13.6 getetag Property .............................................70
+ 13.7 getlastmodified Property .....................................70
+ 13.8 lockdiscovery Property .......................................71
+ 13.8.1 Example - Retrieving the lockdiscovery Property ...........71
+ 13.9 resourcetype Property ........................................72
+ 13.10 source Property .............................................72
+ 13.10.1 Example - A source Property ..............................72
+ 13.11 supportedlock Property ......................................73
+ 13.11.1 Example - Retrieving the supportedlock Property ..........73
+ 14 INSTRUCTIONS FOR PROCESSING XML IN DAV ........................74
+ 15 DAV COMPLIANCE CLASSES ........................................75
+ 15.1 Class 1 ......................................................75
+ 15.2 Class 2 ......................................................75
+
+
+
+Goland, et al. Standards Track [Page 4]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ 16 INTERNATIONALIZATION CONSIDERATIONS ...........................76
+ 17 SECURITY CONSIDERATIONS .......................................77
+ 17.1 Authentication of Clients ....................................77
+ 17.2 Denial of Service ............................................78
+ 17.3 Security through Obscurity ...................................78
+ 17.4 Privacy Issues Connected to Locks ............................78
+ 17.5 Privacy Issues Connected to Properties .......................79
+ 17.6 Reduction of Security due to Source Link .....................79
+ 17.7 Implications of XML External Entities ........................79
+ 17.8 Risks Connected with Lock Tokens .............................80
+ 18 IANA CONSIDERATIONS ...........................................80
+ 19 INTELLECTUAL PROPERTY .........................................81
+ 20 ACKNOWLEDGEMENTS ..............................................82
+ 21 REFERENCES ....................................................82
+ 21.1 Normative References .........................................82
+ 21.2 Informational References .....................................83
+ 22 AUTHORS' ADDRESSES ............................................84
+ 23 APPENDICES ....................................................86
+ 23.1 Appendix 1 - WebDAV Document Type Definition .................86
+ 23.2 Appendix 2 - ISO 8601 Date and Time Profile ..................88
+ 23.3 Appendix 3 - Notes on Processing XML Elements ................89
+ 23.3.1 Notes on Empty XML Elements ...............................89
+ 23.3.2 Notes on Illegal XML Processing ...........................89
+ 23.4 Appendix 4 -- XML Namespaces for WebDAV ......................92
+ 23.4.1 Introduction ..............................................92
+ 23.4.2 Meaning of Qualified Names ................................92
+ 24 FULL COPYRIGHT STATEMENT ......................................94
+
+
+
+1 Introduction
+
+ This document describes an extension to the HTTP/1.1 protocol that
+ allows clients to perform remote web content authoring operations.
+ This extension provides a coherent set of methods, headers, request
+ entity body formats, and response entity body formats that provide
+ operations for:
+
+ Properties: The ability to create, remove, and query information
+ about Web pages, such as their authors, creation dates, etc. Also,
+ the ability to link pages of any media type to related pages.
+
+ Collections: The ability to create sets of documents and to retrieve
+ a hierarchical membership listing (like a directory listing in a file
+ system).
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 5]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Locking: The ability to keep more than one person from working on a
+ document at the same time. This prevents the "lost update problem,"
+ in which modifications are lost as first one author then another
+ writes changes without merging the other author's changes.
+
+ Namespace Operations: The ability to instruct the server to copy and
+ move Web resources.
+
+ Requirements and rationale for these operations are described in a
+ companion document, "Requirements for a Distributed Authoring and
+ Versioning Protocol for the World Wide Web" [RFC2291].
+
+ The sections below provide a detailed introduction to resource
+ properties (section 4), collections of resources (section 5), and
+ locking operations (section 6). These sections introduce the
+ abstractions manipulated by the WebDAV-specific HTTP methods
+ described in section 8, "HTTP Methods for Distributed Authoring".
+
+ In HTTP/1.1, method parameter information was exclusively encoded in
+ HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter
+ information either in an Extensible Markup Language (XML) [REC-XML]
+ request entity body, or in an HTTP header. The use of XML to encode
+ method parameters was motivated by the ability to add extra XML
+ elements to existing structures, providing extensibility; and by
+ XML's ability to encode information in ISO 10646 character sets,
+ providing internationalization support. As a rule of thumb,
+ parameters are encoded in XML entity bodies when they have unbounded
+ length, or when they may be shown to a human user and hence require
+ encoding in an ISO 10646 character set. Otherwise, parameters are
+ encoded within HTTP headers. Section 9 describes the new HTTP
+ headers used with WebDAV methods.
+
+ In addition to encoding method parameters, XML is used in WebDAV to
+ encode the responses from methods, providing the extensibility and
+ internationalization advantages of XML for method output, as well as
+ input.
+
+ XML elements used in this specification are defined in section 12.
+
+ The XML namespace extension (Appendix 4) is also used in this
+ specification in order to allow for new XML elements to be added
+ without fear of colliding with other element names.
+
+ While the status codes provided by HTTP/1.1 are sufficient to
+ describe most error conditions encountered by WebDAV methods, there
+ are some errors that do not fall neatly into the existing categories.
+ New status codes developed for the WebDAV methods are defined in
+ section 10. Since some WebDAV methods may operate over many
+
+
+
+Goland, et al. Standards Track [Page 6]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ resources, the Multi-Status response has been introduced to return
+ status information for multiple resources. The Multi-Status response
+ is described in section 11.
+
+ WebDAV employs the property mechanism to store information about the
+ current state of the resource. For example, when a lock is taken out
+ on a resource, a lock information property describes the current
+ state of the lock. Section 13 defines the properties used within the
+ WebDAV specification.
+
+ Finishing off the specification are sections on what it means to be
+ compliant with this specification (section 15), on
+ internationalization support (section 16), and on security (section
+ 17).
+
+2 Notational Conventions
+
+ Since this document describes a set of extensions to the HTTP/1.1
+ protocol, the augmented BNF used herein to describe protocol elements
+ is exactly the same as described in section 2.1 of [RFC2068]. Since
+ this augmented BNF uses the basic production rules provided in
+ section 2.2 of [RFC2068], these rules apply to this document as well.
+
+ 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 RFC 2119 [RFC2119].
+
+3 Terminology
+
+ URI/URL - A Uniform Resource Identifier and Uniform Resource Locator,
+ respectively. These terms (and the distinction between them) are
+ defined in [RFC2396].
+
+ Collection - A resource that contains a set of URIs, termed member
+ URIs, which identify member resources and meets the requirements in
+ section 5 of this specification.
+
+ Member URI - A URI which is a member of the set of URIs contained by
+ a collection.
+
+ Internal Member URI - A Member URI that is immediately relative to
+ the URI of the collection (the definition of immediately relative is
+ given in section 5.2).
+
+ Property - A name/value pair that contains descriptive information
+ about a resource.
+
+
+
+
+
+Goland, et al. Standards Track [Page 7]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Live Property - A property whose semantics and syntax are enforced by
+ the server. For example, the live "getcontentlength" property has
+ its value, the length of the entity returned by a GET request,
+ automatically calculated by the server.
+
+ Dead Property - A property whose semantics and syntax are not
+ enforced by the server. The server only records the value of a dead
+ property; the client is responsible for maintaining the consistency
+ of the syntax and semantics of a dead property.
+
+ Null Resource - A resource which responds with a 404 (Not Found) to
+ any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK.
+ A NULL resource MUST NOT appear as a member of its parent collection.
+
+4 Data Model for Resource Properties
+
+4.1 The Resource Property Model
+
+ Properties are pieces of data that describe the state of a resource.
+ Properties are data about data.
+
+ Properties are used in distributed authoring environments to provide
+ for efficient discovery and management of resources. For example, a
+ 'subject' property might allow for the indexing of all resources by
+ their subject, and an 'author' property might allow for the discovery
+ of what authors have written which documents.
+
+ The DAV property model consists of name/value pairs. The name of a
+ property identifies the property's syntax and semantics, and provides
+ an address by which to refer to its syntax and semantics.
+
+ There are two categories of properties: "live" and "dead". A live
+ property has its syntax and semantics enforced by the server. Live
+ properties include cases where a) the value of a property is read-
+ only, maintained by the server, and b) the value of the property is
+ maintained by the client, but the server performs syntax checking on
+ submitted values. All instances of a given live property MUST comply
+ with the definition associated with that property name. A dead
+ property has its syntax and semantics enforced by the client; the
+ server merely records the value of the property verbatim.
+
+4.2 Existing Metadata Proposals
+
+ Properties have long played an essential role in the maintenance of
+ large document repositories, and many current proposals contain some
+ notion of a property, or discuss web metadata more generally. These
+ include PICS [REC-PICS], PICS-NG, XML, Web Collections, and several
+ proposals on representing relationships within HTML. Work on PICS-NG
+
+
+
+Goland, et al. Standards Track [Page 8]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ and Web Collections has been subsumed by the Resource Description
+ Framework (RDF) metadata activity of the World Wide Web Consortium.
+ RDF consists of a network-based data model and an XML representation
+ of that model.
+
+ Some proposals come from a digital library perspective. These
+ include the Dublin Core [RFC2413] metadata set and the Warwick
+ Framework [WF], a container architecture for different metadata
+ schemas. The literature includes many examples of metadata,
+ including MARC [USMARC], a bibliographic metadata format, and a
+ technical report bibliographic format employed by the Dienst system
+ [RFC1807]. Additionally, the proceedings from the first IEEE Metadata
+ conference describe many community-specific metadata sets.
+
+ Participants of the 1996 Metadata II Workshop in Warwick, UK [WF],
+ noted that "new metadata sets will develop as the networked
+ infrastructure matures" and "different communities will propose,
+ design, and be responsible for different types of metadata." These
+ observations can be corroborated by noting that many community-
+ specific sets of metadata already exist, and there is significant
+ motivation for the development of new forms of metadata as many
+ communities increasingly make their data available in digital form,
+ requiring a metadata format to assist data location and cataloging.
+
+4.3 Properties and HTTP Headers
+
+ Properties already exist, in a limited sense, in HTTP message
+ headers. However, in distributed authoring environments a relatively
+ large number of properties are needed to describe the state of a
+ resource, and setting/returning them all through HTTP headers is
+ inefficient. Thus a mechanism is needed which allows a principal to
+ identify a set of properties in which the principal is interested and
+ to set or retrieve just those properties.
+
+4.4 Property Values
+
+ The value of a property when expressed in XML MUST be well formed.
+
+ XML has been chosen because it is a flexible, self-describing,
+ structured data format that supports rich schema definitions, and
+ because of its support for multiple character sets. XML's self-
+ describing nature allows any property's value to be extended by
+ adding new elements. Older clients will not break when they
+ encounter extensions because they will still have the data specified
+ in the original schema and will ignore elements they do not
+ understand. XML's support for multiple character sets allows any
+ human-readable property to be encoded and read in a character set
+ familiar to the user. XML's support for multiple human languages,
+
+
+
+Goland, et al. Standards Track [Page 9]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ using the "xml:lang" attribute, handles cases where the same
+ character set is employed by multiple human languages.
+
+4.5 Property Names
+
+ A property name is a universally unique identifier that is associated
+ with a schema that provides information about the syntax and
+ semantics of the property.
+
+ Because a property's name is universally unique, clients can depend
+ upon consistent behavior for a particular property across multiple
+ resources, on the same and across different servers, so long as that
+ property is "live" on the resources in question, and the
+ implementation of the live property is faithful to its definition.
+
+ The XML namespace mechanism, which is based on URIs [RFC2396], is
+ used to name properties because it prevents namespace collisions and
+ provides for varying degrees of administrative control.
+
+ The property namespace is flat; that is, no hierarchy of properties
+ is explicitly recognized. Thus, if a property A and a property A/B
+ exist on a resource, there is no recognition of any relationship
+ between the two properties. It is expected that a separate
+ specification will eventually be produced which will address issues
+ relating to hierarchical properties.
+
+ Finally, it is not possible to define the same property twice on a
+ single resource, as this would cause a collision in the resource's
+ property namespace.
+
+4.6 Media Independent Links
+
+ Although HTML resources support links to other resources, the Web
+ needs more general support for links between resources of any media
+ type (media types are also known as MIME types, or content types).
+ WebDAV provides such links. A WebDAV link is a special type of
+ property value, formally defined in section 12.4, that allows typed
+ connections to be established between resources of any media type.
+ The property value consists of source and destination Uniform
+ Resource Identifiers (URIs); the property name identifies the link
+ type.
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 10]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+5 Collections of Web Resources
+
+ This section provides a description of a new type of Web resource,
+ the collection, and discusses its interactions with the HTTP URL
+ namespace. The purpose of a collection resource is to model
+ collection-like objects (e.g., file system directories) within a
+ server's namespace.
+
+ All DAV compliant resources MUST support the HTTP URL namespace model
+ specified herein.
+
+5.1 HTTP URL Namespace Model
+
+ The HTTP URL namespace is a hierarchical namespace where the
+ hierarchy is delimited with the "/" character.
+
+ An HTTP URL namespace is said to be consistent if it meets the
+ following conditions: for every URL in the HTTP hierarchy there
+ exists a collection that contains that URL as an internal member.
+ The root, or top-level collection of the namespace under
+ consideration is exempt from the previous rule.
+
+ Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL
+ namespace be consistent. However, certain WebDAV methods are
+ prohibited from producing results that cause namespace
+ inconsistencies.
+
+ Although implicit in [RFC2068] and [RFC2396], any resource, including
+ collection resources, MAY be identified by more than one URI. For
+ example, a resource could be identified by multiple HTTP URLs.
+
+5.2 Collection Resources
+
+ A collection is a resource whose state consists of at least a list of
+ internal member URIs and a set of properties, but which may have
+ additional state such as entity bodies returned by GET. An internal
+ member URI MUST be immediately relative to a base URI of the
+ collection. That is, the internal member URI is equal to a
+ containing collection's URI plus an additional segment for non-
+ collection resources, or additional segment plus trailing slash "/"
+ for collection resources, where segment is defined in section 3.3 of
+ [RFC2396].
+
+ Any given internal member URI MUST only belong to the collection
+ once, i.e., it is illegal to have multiple instances of the same URI
+ in a collection. Properties defined on collections behave exactly as
+ do properties on non-collection resources.
+
+
+
+
+Goland, et al. Standards Track [Page 11]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ For all WebDAV compliant resources A and B, identified by URIs U and
+ V, for which U is immediately relative to V, B MUST be a collection
+ that has U as an internal member URI. So, if the resource with URL
+ http://foo.com/bar/blah is WebDAV compliant and if the resource with
+ URL http://foo.com/bar/ is WebDAV compliant then the resource with
+ URL http://foo.com/bar/ must be a collection and must contain URL
+ http://foo.com/bar/blah as an internal member.
+
+ Collection resources MAY list the URLs of non-WebDAV compliant
+ children in the HTTP URL namespace hierarchy as internal members but
+ are not required to do so. For example, if the resource with URL
+ http://foo.com/bar/blah is not WebDAV compliant and the URL
+ http://foo.com/bar/ identifies a collection then URL
+ http://foo.com/bar/blah may or may not be an internal member of the
+ collection with URL http://foo.com/bar/.
+
+ If a WebDAV compliant resource has no WebDAV compliant children in
+ the HTTP URL namespace hierarchy then the WebDAV compliant resource
+ is not required to be a collection.
+
+ There is a standing convention that when a collection is referred to
+ by its name without a trailing slash, the trailing slash is
+ automatically appended. Due to this, a resource may accept a URI
+ without a trailing "/" to point to a collection. In this case it
+ SHOULD return a content-location header in the response pointing to
+ the URI ending with the "/". For example, if a client invokes a
+ method on http://foo.bar/blah (no trailing slash), the resource
+ http://foo.bar/blah/ (trailing slash) may respond as if the operation
+ were invoked on it, and should return a content-location header with
+ http://foo.bar/blah/ in it. In general clients SHOULD use the "/"
+ form of collection names.
+
+ A resource MAY be a collection but not be WebDAV compliant. That is,
+ the resource may comply with all the rules set out in this
+ specification regarding how a collection is to behave without
+ necessarily supporting all methods that a WebDAV compliant resource
+ is required to support. In such a case the resource may return the
+ DAV:resourcetype property with the value DAV:collection but MUST NOT
+ return a DAV header containing the value "1" on an OPTIONS response.
+
+5.3 Creation and Retrieval of Collection Resources
+
+ This document specifies the MKCOL method to create new collection
+ resources, rather than using the existing HTTP/1.1 PUT or POST
+ method, for the following reasons:
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 12]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ In HTTP/1.1, the PUT method is defined to store the request body at
+ the location specified by the Request-URI. While a description
+ format for a collection can readily be constructed for use with PUT,
+ the implications of sending such a description to the server are
+ undesirable. For example, if a description of a collection that
+ omitted some existing resources were PUT to a server, this might be
+ interpreted as a command to remove those members. This would extend
+ PUT to perform DELETE functionality, which is undesirable since it
+ changes the semantics of PUT, and makes it difficult to control
+ DELETE functionality with an access control scheme based on methods.
+
+ While the POST method is sufficiently open-ended that a "create a
+ collection" POST command could be constructed, this is undesirable
+ because it would be difficult to separate access control for
+ collection creation from other uses of POST.
+
+ The exact definition of the behavior of GET and PUT on collections is
+ defined later in this document.
+
+5.4 Source Resources and Output Resources
+
+ For many resources, the entity returned by a GET method exactly
+ matches the persistent state of the resource, for example, a GIF file
+ stored on a disk. For this simple case, the URI at which a resource
+ is accessed is identical to the URI at which the source (the
+ persistent state) of the resource is accessed. This is also the case
+ for HTML source files that are not processed by the server prior to
+ transmission.
+
+ However, the server can sometimes process HTML resources before they
+ are transmitted as a return entity body. For example, a server-
+ side-include directive within an HTML file might instruct a server to
+ replace the directive with another value, such as the current date.
+ In this case, what is returned by GET (HTML plus date) differs from
+ the persistent state of the resource (HTML plus directive).
+ Typically there is no way to access the HTML resource containing the
+ unprocessed directive.
+
+ Sometimes the entity returned by GET is the output of a data-
+ producing process that is described by one or more source resources
+ (that may not even have a location in the URI namespace). A single
+ data-producing process may dynamically generate the state of a
+ potentially large number of output resources. An example of this is
+ a CGI script that describes a "finger" gateway process that maps part
+ of the namespace of a server into finger requests, such as
+ http://www.foo.bar.org/finger_gateway/user@host.
+
+
+
+
+
+Goland, et al. Standards Track [Page 13]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ In the absence of distributed authoring capabilities, it is
+ acceptable to have no mapping of source resource(s) to the URI
+ namespace. In fact, preventing access to the source resource(s) has
+ desirable security benefits. However, if remote editing of the
+ source resource(s) is desired, the source resource(s) should be given
+ a location in the URI namespace. This source location should not be
+ one of the locations at which the generated output is retrievable,
+ since in general it is impossible for the server to differentiate
+ requests for source resources from requests for process output
+ resources. There is often a many-to-many relationship between source
+ resources and output resources.
+
+ On WebDAV compliant servers the URI of the source resource(s) may be
+ stored in a link on the output resource with type DAV:source (see
+ section 13.10 for a description of the source link property).
+ Storing the source URIs in links on the output resources places the
+ burden of discovering the source on the authoring client. Note that
+ the value of a source link is not guaranteed to point to the correct
+ source. Source links may break or incorrect values may be entered.
+ Also note that not all servers will allow the client to set the
+ source link value. For example a server which generates source links
+ on the fly for its CGI files will most likely not allow a client to
+ set the source link value.
+
+6 Locking
+
+ The ability to lock a resource provides a mechanism for serializing
+ access to that resource. Using a lock, an authoring client can
+ provide a reasonable guarantee that another principal will not modify
+ a resource while it is being edited. In this way, a client can
+ prevent the "lost update" problem.
+
+ This specification allows locks to vary over two client-specified
+ parameters, the number of principals involved (exclusive vs. shared)
+ and the type of access to be granted. This document defines locking
+ for only one access type, write. However, the syntax is extensible,
+ and permits the eventual specification of locking for other access
+ types.
+
+6.1 Exclusive Vs. Shared Locks
+
+ The most basic form of lock is an exclusive lock. This is a lock
+ where the access right in question is only granted to a single
+ principal. The need for this arbitration results from a desire to
+ avoid having to merge results.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 14]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ However, there are times when the goal of a lock is not to exclude
+ others from exercising an access right but rather to provide a
+ mechanism for principals to indicate that they intend to exercise
+ their access rights. Shared locks are provided for this case. A
+ shared lock allows multiple principals to receive a lock. Hence any
+ principal with appropriate access can get the lock.
+
+ With shared locks there are two trust sets that affect a resource.
+ The first trust set is created by access permissions. Principals who
+ are trusted, for example, may have permission to write to the
+ resource. Among those who have access permission to write to the
+ resource, the set of principals who have taken out a shared lock also
+ must trust each other, creating a (typically) smaller trust set
+ within the access permission write set.
+
+ Starting with every possible principal on the Internet, in most
+ situations the vast majority of these principals will not have write
+ access to a given resource. Of the small number who do have write
+ access, some principals may decide to guarantee their edits are free
+ from overwrite conflicts by using exclusive write locks. Others may
+ decide they trust their collaborators will not overwrite their work
+ (the potential set of collaborators being the set of principals who
+ have write permission) and use a shared lock, which informs their
+ collaborators that a principal may be working on the resource.
+
+ The WebDAV extensions to HTTP do not need to provide all of the
+ communications paths necessary for principals to coordinate their
+ activities. When using shared locks, principals may use any out of
+ band communication channel to coordinate their work (e.g., face-to-
+ face interaction, written notes, post-it notes on the screen,
+ telephone conversation, Email, etc.) The intent of a shared lock is
+ to let collaborators know who else may be working on a resource.
+
+ Shared locks are included because experience from web distributed
+ authoring systems has indicated that exclusive locks are often too
+ rigid. An exclusive lock is used to enforce a particular editing
+ process: take out an exclusive lock, read the resource, perform
+ edits, write the resource, release the lock. This editing process
+ has the problem that locks are not always properly released, for
+ example when a program crashes, or when a lock owner leaves without
+ unlocking a resource. While both timeouts and administrative action
+ can be used to remove an offending lock, neither mechanism may be
+ available when needed; the timeout may be long or the administrator
+ may not be available.
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 15]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+6.2 Required Support
+
+ A WebDAV compliant server is not required to support locking in any
+ form. If the server does support locking it may choose to support
+ any combination of exclusive and shared locks for any access types.
+
+ The reason for this flexibility is that locking policy strikes to the
+ very heart of the resource management and versioning systems employed
+ by various storage repositories. These repositories require control
+ over what sort of locking will be made available. For example, some
+ repositories only support shared write locks while others only
+ provide support for exclusive write locks while yet others use no
+ locking at all. As each system is sufficiently different to merit
+ exclusion of certain locking features, this specification leaves
+ locking as the sole axis of negotiation within WebDAV.
+
+6.3 Lock Tokens
+
+ A lock token is a type of state token, represented as a URI, which
+ identifies a particular lock. A lock token is returned by every
+ successful LOCK operation in the lockdiscovery property in the
+ response body, and can also be found through lock discovery on a
+ resource.
+
+ Lock token URIs MUST be unique across all resources for all time.
+ This uniqueness constraint allows lock tokens to be submitted across
+ resources and servers without fear of confusion.
+
+ This specification provides a lock token URI scheme called
+ opaquelocktoken that meets the uniqueness requirements. However
+ resources are free to return any URI scheme so long as it meets the
+ uniqueness requirements.
+
+ Having a lock token provides no special access rights. Anyone can
+ find out anyone else's lock token by performing lock discovery.
+ Locks MUST be enforced based upon whatever authentication mechanism
+ is used by the server, not based on the secrecy of the token values.
+
+6.4 opaquelocktoken Lock Token URI Scheme
+
+ The opaquelocktoken URI scheme is designed to be unique across all
+ resources for all time. Due to this uniqueness quality, a client may
+ submit an opaque lock token in an If header on a resource other than
+ the one that returned it.
+
+ All resources MUST recognize the opaquelocktoken scheme and, at
+ minimum, recognize that the lock token does not refer to an
+ outstanding lock on the resource.
+
+
+
+Goland, et al. Standards Track [Page 16]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ In order to guarantee uniqueness across all resources for all time
+ the opaquelocktoken requires the use of the Universal Unique
+ Identifier (UUID) mechanism, as described in [ISO-11578].
+
+ Opaquelocktoken generators, however, have a choice of how they create
+ these tokens. They can either generate a new UUID for every lock
+ token they create or they can create a single UUID and then add
+ extension characters. If the second method is selected then the
+ program generating the extensions MUST guarantee that the same
+ extension will never be used twice with the associated UUID.
+
+ OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The UUID
+ production is the string representation of a UUID, as defined in
+ [ISO-11578]. Note that white space (LWS) is not allowed between
+ elements of this production.
+
+ Extension = path ; path is defined in section 3.2.1 of RFC 2068
+ [RFC2068]
+
+6.4.1 Node Field Generation Without the IEEE 802 Address
+
+ UUIDs, as defined in [ISO-11578], contain a "node" field that
+ contains one of the IEEE 802 addresses for the server machine. As
+ noted in section 17.8, there are several security risks associated
+ with exposing a machine's IEEE 802 address. This section provides an
+ alternate mechanism for generating the "node" field of a UUID which
+ does not employ an IEEE 802 address. WebDAV servers MAY use this
+ algorithm for creating the node field when generating UUIDs. The
+ text in this section is originally from an Internet-Draft by Paul
+ Leach and Rich Salz, who are noted here to properly attribute their
+ work.
+
+ The ideal solution is to obtain a 47 bit cryptographic quality random
+ number, and use it as the low 47 bits of the node ID, with the most
+ significant bit of the first octet of the node ID set to 1. This bit
+ is the unicast/multicast bit, which will never be set in IEEE 802
+ addresses obtained from network cards; hence, there can never be a
+ conflict between UUIDs generated by machines with and without network
+ cards.
+
+ If a system does not have a primitive to generate cryptographic
+ quality random numbers, then in most systems there are usually a
+ fairly large number of sources of randomness available from which one
+ can be generated. Such sources are system specific, but often
+ include:
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 17]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ - the percent of memory in use
+ - the size of main memory in bytes
+ - the amount of free main memory in bytes
+ - the size of the paging or swap file in bytes
+ - free bytes of paging or swap file
+ - the total size of user virtual address space in bytes
+ - the total available user address space bytes
+ - the size of boot disk drive in bytes
+ - the free disk space on boot drive in bytes
+ - the current time
+ - the amount of time since the system booted
+ - the individual sizes of files in various system directories
+ - the creation, last read, and modification times of files in
+ various system directories
+ - the utilization factors of various system resources (heap, etc.)
+ - current mouse cursor position
+ - current caret position
+ - current number of running processes, threads
+ - handles or IDs of the desktop window and the active window
+ - the value of stack pointer of the caller
+ - the process and thread ID of caller
+ - various processor architecture specific performance counters
+ (instructions executed, cache misses, TLB misses)
+
+ (Note that it is precisely the above kinds of sources of randomness
+ that are used to seed cryptographic quality random number generators
+ on systems without special hardware for their construction.)
+
+ In addition, items such as the computer's name and the name of the
+ operating system, while not strictly speaking random, will help
+ differentiate the results from those obtained by other systems.
+
+ The exact algorithm to generate a node ID using these data is system
+ specific, because both the data available and the functions to obtain
+ them are often very system specific. However, assuming that one can
+ concatenate all the values from the randomness sources into a buffer,
+ and that a cryptographic hash function such as MD5 is available, then
+ any 6 bytes of the MD5 hash of the buffer, with the multicast bit
+ (the high bit of the first byte) set will be an appropriately random
+ node ID.
+
+ Other hash functions, such as SHA-1, can also be used. The only
+ requirement is that the result be suitably random _ in the sense that
+ the outputs from a set uniformly distributed inputs are themselves
+ uniformly distributed, and that a single bit change in the input can
+ be expected to cause half of the output bits to change.
+
+
+
+
+
+Goland, et al. Standards Track [Page 18]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+6.5 Lock Capability Discovery
+
+ Since server lock support is optional, a client trying to lock a
+ resource on a server can either try the lock and hope for the best,
+ or perform some form of discovery to determine what lock capabilities
+ the server supports. This is known as lock capability discovery.
+ Lock capability discovery differs from discovery of supported access
+ control types, since there may be access control types without
+ corresponding lock types. A client can determine what lock types the
+ server supports by retrieving the supportedlock property.
+
+ Any DAV compliant resource that supports the LOCK method MUST support
+ the supportedlock property.
+
+6.6 Active Lock Discovery
+
+ If another principal locks a resource that a principal wishes to
+ access, it is useful for the second principal to be able to find out
+ who the first principal is. For this purpose the lockdiscovery
+ property is provided. This property lists all outstanding locks,
+ describes their type, and where available, provides their lock token.
+
+ Any DAV compliant resource that supports the LOCK method MUST support
+ the lockdiscovery property.
+
+6.7 Usage Considerations
+
+ Although the locking mechanisms specified here provide some help in
+ preventing lost updates, they cannot guarantee that updates will
+ never be lost. Consider the following scenario:
+
+ Two clients A and B are interested in editing the resource '
+ index.html'. Client A is an HTTP client rather than a WebDAV client,
+ and so does not know how to perform locking.
+ Client A doesn't lock the document, but does a GET and begins
+ editing.
+ Client B does LOCK, performs a GET and begins editing.
+ Client B finishes editing, performs a PUT, then an UNLOCK.
+ Client A performs a PUT, overwriting and losing all of B's changes.
+
+ There are several reasons why the WebDAV protocol itself cannot
+ prevent this situation. First, it cannot force all clients to use
+ locking because it must be compatible with HTTP clients that do not
+ comprehend locking. Second, it cannot require servers to support
+ locking because of the variety of repository implementations, some of
+ which rely on reservations and merging rather than on locking.
+ Finally, being stateless, it cannot enforce a sequence of operations
+ like LOCK / GET / PUT / UNLOCK.
+
+
+
+Goland, et al. Standards Track [Page 19]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ WebDAV servers that support locking can reduce the likelihood that
+ clients will accidentally overwrite each other's changes by requiring
+ clients to lock resources before modifying them. Such servers would
+ effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying
+ resources.
+
+ WebDAV clients can be good citizens by using a lock / retrieve /
+ write /unlock sequence of operations (at least by default) whenever
+ they interact with a WebDAV server that supports locking.
+
+ HTTP 1.1 clients can be good citizens, avoiding overwriting other
+ clients' changes, by using entity tags in If-Match headers with any
+ requests that would modify resources.
+
+ Information managers may attempt to prevent overwrites by
+ implementing client-side procedures requiring locking before
+ modifying WebDAV resources.
+
+7 Write Lock
+
+ This section describes the semantics specific to the write lock type.
+ The write lock is a specific instance of a lock type, and is the only
+ lock type described in this specification.
+
+7.1 Methods Restricted by Write Locks
+
+ A write lock MUST prevent a principal without the lock from
+ successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE,
+ DELETE, or MKCOL on the locked resource. All other current methods,
+ GET in particular, function independently of the lock.
+
+ Note, however, that as new methods are created it will be necessary
+ to specify how they interact with a write lock.
+
+7.2 Write Locks and Lock Tokens
+
+ A successful request for an exclusive or shared write lock MUST
+ result in the generation of a unique lock token associated with the
+ requesting principal. Thus if five principals have a shared write
+ lock on the same resource there will be five lock tokens, one for
+ each principal.
+
+7.3 Write Locks and Properties
+
+ While those without a write lock may not alter a property on a
+ resource it is still possible for the values of live properties to
+ change, even while locked, due to the requirements of their schemas.
+
+
+
+
+Goland, et al. Standards Track [Page 20]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Only dead properties and live properties defined to respect locks are
+ guaranteed not to change while write locked.
+
+7.4 Write Locks and Null Resources
+
+ It is possible to assert a write lock on a null resource in order to
+ lock the name.
+
+ A write locked null resource, referred to as a lock-null resource,
+ MUST respond with a 404 (Not Found) or 405 (Method Not Allowed) to
+ any HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, PROPFIND,
+ LOCK, and UNLOCK. A lock-null resource MUST appear as a member of
+ its parent collection. Additionally the lock-null resource MUST have
+ defined on it all mandatory DAV properties. Most of these
+ properties, such as all the get* properties, will have no value as a
+ lock-null resource does not support the GET method. Lock-Null
+ resources MUST have defined values for lockdiscovery and
+ supportedlock properties.
+
+ Until a method such as PUT or MKCOL is successfully executed on the
+ lock-null resource the resource MUST stay in the lock-null state.
+ However, once a PUT or MKCOL is successfully executed on a lock-null
+ resource the resource ceases to be in the lock-null state.
+
+ If the resource is unlocked, for any reason, without a PUT, MKCOL, or
+ similar method having been successfully executed upon it then the
+ resource MUST return to the null state.
+
+7.5 Write Locks and Collections
+
+ A write lock on a collection, whether created by a "Depth: 0" or
+ "Depth: infinity" lock request, prevents the addition or removal of
+ member URIs of the collection by non-lock owners. As a consequence,
+ when a principal issues a PUT or POST request to create a new
+ resource under a URI which needs to be an internal member of a write
+ locked collection to maintain HTTP namespace consistency, or issues a
+ DELETE to remove a resource which has a URI which is an existing
+ internal member URI of a write locked collection, this request MUST
+ fail if the principal does not have a write lock on the collection.
+
+ However, if a write lock request is issued to a collection containing
+ member URIs identifying resources that are currently locked in a
+ manner which conflicts with the write lock, the request MUST fail
+ with a 423 (Locked) status code.
+
+ If a lock owner causes the URI of a resource to be added as an
+ internal member URI of a locked collection then the new resource MUST
+ be automatically added to the lock. This is the only mechanism that
+
+
+
+Goland, et al. Standards Track [Page 21]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ allows a resource to be added to a write lock. Thus, for example, if
+ the collection /a/b/ is write locked and the resource /c is moved to
+ /a/b/c then resource /a/b/c will be added to the write lock.
+
+7.6 Write Locks and the If Request Header
+
+ If a user agent is not required to have knowledge about a lock when
+ requesting an operation on a locked resource, the following scenario
+ might occur. Program A, run by User A, takes out a write lock on a
+ resource. Program B, also run by User A, has no knowledge of the
+ lock taken out by Program A, yet performs a PUT to the locked
+ resource. In this scenario, the PUT succeeds because locks are
+ associated with a principal, not a program, and thus program B,
+ because it is acting with principal A's credential, is allowed to
+ perform the PUT. However, had program B known about the lock, it
+ would not have overwritten the resource, preferring instead to
+ present a dialog box describing the conflict to the user. Due to
+ this scenario, a mechanism is needed to prevent different programs
+ from accidentally ignoring locks taken out by other programs with the
+ same authorization.
+
+ In order to prevent these collisions a lock token MUST be submitted
+ by an authorized principal in the If header for all locked resources
+ that a method may interact with or the method MUST fail. For
+ example, if a resource is to be moved and both the source and
+ destination are locked then two lock tokens must be submitted, one
+ for the source and the other for the destination.
+
+7.6.1 Example - Write Lock
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+ If: <http://www.ics.uci.edu/users/f/fielding/index.html>
+ (<opaquelocktoken:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, even though both the source and destination are
+ locked, only one lock token must be submitted, for the lock on the
+ destination. This is because the source resource is not modified by
+ a COPY, and hence unaffected by the write lock. In this example, user
+ agent authentication has previously occurred via a mechanism outside
+ the scope of the HTTP protocol, in the underlying transport layer.
+
+
+
+Goland, et al. Standards Track [Page 22]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+7.7 Write Locks and COPY/MOVE
+
+ A COPY method invocation MUST NOT duplicate any write locks active on
+ the source. However, as previously noted, if the COPY copies the
+ resource into a collection that is locked with "Depth: infinity",
+ then the resource will be added to the lock.
+
+ A successful MOVE request on a write locked resource MUST NOT move
+ the write lock with the resource. However, the resource is subject to
+ being added to an existing lock at the destination, as specified in
+ section 7.5. For example, if the MOVE makes the resource a child of a
+ collection that is locked with "Depth: infinity", then the resource
+ will be added to that collection's lock. Additionally, if a resource
+ locked with "Depth: infinity" is moved to a destination that is
+ within the scope of the same lock (e.g., within the namespace tree
+ covered by the lock), the moved resource will again be a added to the
+ lock. In both these examples, as specified in section 7.6, an If
+ header must be submitted containing a lock token for both the source
+ and destination.
+
+7.8 Refreshing Write Locks
+
+ A client MUST NOT submit the same write lock request twice. Note
+ that a client is always aware it is resubmitting the same lock
+ request because it must include the lock token in the If header in
+ order to make the request for a resource that is already locked.
+
+ However, a client may submit a LOCK method with an If header but
+ without a body. This form of LOCK MUST only be used to "refresh" a
+ lock. Meaning, at minimum, that any timers associated with the lock
+ MUST be re-set.
+
+ A server may return a Timeout header with a lock refresh that is
+ different than the Timeout header returned when the lock was
+ originally requested. Additionally clients may submit Timeout
+ headers of arbitrary value with their lock refresh requests.
+ Servers, as always, may ignore Timeout headers submitted by the
+ client.
+
+ If an error is received in response to a refresh LOCK request the
+ client SHOULD assume that the lock was not refreshed.
+
+8 HTTP Methods for Distributed Authoring
+
+ The following new HTTP methods use XML as a request and response
+ format. All DAV compliant clients and resources MUST use XML parsers
+ that are compliant with [REC-XML]. All XML used in either requests
+ or responses MUST be, at minimum, well formed. If a server receives
+
+
+
+Goland, et al. Standards Track [Page 23]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ ill-formed XML in a request it MUST reject the entire request with a
+ 400 (Bad Request). If a client receives ill-formed XML in a response
+ then it MUST NOT assume anything about the outcome of the executed
+ method and SHOULD treat the server as malfunctioning.
+
+8.1 PROPFIND
+
+ The PROPFIND method retrieves properties defined on the resource
+ identified by the Request-URI, if the resource does not have any
+ internal members, or on the resource identified by the Request-URI
+ and potentially its member resources, if the resource is a collection
+ that has internal member URIs. All DAV compliant resources MUST
+ support the PROPFIND method and the propfind XML element (section
+ 12.14) along with all XML elements defined for use with that element.
+
+ A client may submit a Depth header with a value of "0", "1", or
+ "infinity" with a PROPFIND on a collection resource with internal
+ member URIs. DAV compliant servers MUST support the "0", "1" and
+ "infinity" behaviors. By default, the PROPFIND method without a Depth
+ header MUST act as if a "Depth: infinity" header was included.
+
+ A client may submit a propfind XML element in the body of the request
+ method describing what information is being requested. It is
+ possible to request particular property values, all property values,
+ or a list of the names of the resource's properties. A client may
+ choose not to submit a request body. An empty PROPFIND request body
+ MUST be treated as a request for the names and values of all
+ properties.
+
+ All servers MUST support returning a response of content type
+ text/xml or application/xml that contains a multistatus XML element
+ that describes the results of the attempts to retrieve the various
+ properties.
+
+ If there is an error retrieving a property then a proper error result
+ MUST be included in the response. A request to retrieve the value of
+ a property which does not exist is an error and MUST be noted, if the
+ response uses a multistatus XML element, with a response XML element
+ which contains a 404 (Not Found) status value.
+
+ Consequently, the multistatus XML element for a collection resource
+ with member URIs MUST include a response XML element for each member
+ URI of the collection, to whatever depth was requested. Each response
+ XML element MUST contain an href XML element that gives the URI of
+ the resource on which the properties in the prop XML element are
+ defined. Results for a PROPFIND on a collection resource with
+ internal member URIs are returned as a flat list whose order of
+ entries is not significant.
+
+
+
+Goland, et al. Standards Track [Page 24]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ In the case of allprop and propname, if a principal does not have the
+ right to know whether a particular property exists then the property
+ should be silently excluded from the response.
+
+ The results of this method SHOULD NOT be cached.
+
+8.1.1 Example - Retrieving Named Properties
+
+ >>Request
+
+ PROPFIND /file HTTP/1.1
+ Host: www.foo.bar
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <R:DingALing/>
+ <R:Random/>
+ </D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.foo.bar/file</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox>
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ <R:author>
+ <R:Name>J.J. Johnson</R:Name>
+ </R:author>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><R:DingALing/><R:Random/></D:prop>
+
+
+
+Goland, et al. Standards Track [Page 25]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ <D:responsedescription> The user does not have access to
+ the DingALing property.
+ </D:responsedescription>
+ </D:propstat>
+ </D:response>
+ <D:responsedescription> There has been an access violation error.
+ </D:responsedescription>
+ </D:multistatus>
+
+ In this example, PROPFIND is executed on a non-collection resource
+ http://www.foo.bar/file. The propfind XML element specifies the name
+ of four properties whose values are being requested. In this case
+ only two properties were returned, since the principal issuing the
+ request did not have sufficient access rights to see the third and
+ fourth properties.
+
+8.1.2 Example - Using allprop to Retrieve All Properties
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.foo.bar
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.foo.bar/container/</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox>
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ <R:author>
+
+
+
+Goland, et al. Standards Track [Page 26]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <R:Name>Hadrian</R:Name>
+ </R:author>
+ <D:creationdate>
+ 1997-12-01T17:42:21-08:00
+ </D:creationdate>
+ <D:displayname>
+ Example collection
+ </D:displayname>
+ <D:resourcetype><D:collection/></D:resourcetype>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>http://www.foo.bar/container/front.html</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox>
+ <R:BoxType>Box type B</R:BoxType>
+ </R:bigbox>
+ <D:creationdate>
+ 1997-12-01T18:27:21-08:00
+ </D:creationdate>
+ <D:displayname>
+ Example HTML resource
+ </D:displayname>
+ <D:getcontentlength>
+ 4525
+ </D:getcontentlength>
+ <D:getcontenttype>
+ text/html
+ </D:getcontenttype>
+ <D:getetag>
+ zzyzx
+ </D:getetag>
+ <D:getlastmodified>
+ Monday, 12-Jan-98 09:25:56 GMT
+ </D:getlastmodified>
+
+
+
+Goland, et al. Standards Track [Page 27]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <D:resourcetype/>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ In this example, PROPFIND was invoked on the resource
+ http://www.foo.bar/container/ with a Depth header of 1, meaning the
+ request applies to the resource and its children, and a propfind XML
+ element containing the allprop XML element, meaning the request
+ should return the name and value of all properties defined on each
+ resource.
+
+ The resource http://www.foo.bar/container/ has six properties defined
+ on it:
+
+ http://www.foo.bar/boxschema/bigbox,
+ http://www.foo.bar/boxschema/author, DAV:creationdate,
+ DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
+
+ The last four properties are WebDAV-specific, defined in section 13.
+ Since GET is not supported on this resource, the get* properties
+ (e.g., getcontentlength) are not defined on this resource. The DAV-
+ specific properties assert that "container" was created on December
+ 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
+ (creationdate), has a name of "Example collection" (displayname), a
+ collection resource type (resourcetype), and supports exclusive write
+ and shared write locks (supportedlock).
+
+ The resource http://www.foo.bar/container/front.html has nine
+ properties defined on it:
+
+ http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox"
+ property type), DAV:creationdate, DAV:displayname,
+ DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
+ DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
+
+
+
+
+Goland, et al. Standards Track [Page 28]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ The DAV-specific properties assert that "front.html" was created on
+ December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
+ (creationdate), has a name of "Example HTML resource" (displayname),
+ a content length of 4525 bytes (getcontentlength), a MIME type of
+ "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was
+ last modified on Monday, January 12, 1998, at 09:25:56 GMT
+ (getlastmodified), has an empty resource type, meaning that it is not
+ a collection (resourcetype), and supports both exclusive write and
+ shared write locks (supportedlock).
+
+8.1.3 Example - Using propname to Retrieve all Property Names
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.foo.bar
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <propfind xmlns="DAV:">
+ <propname/>
+ </propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <multistatus xmlns="DAV:">
+ <response>
+ <href>http://www.foo.bar/container/</href>
+ <propstat>
+ <prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <creationdate/>
+ <displayname/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+ </propstat>
+ </response>
+ <response>
+ <href>http://www.foo.bar/container/front.html</href>
+
+
+
+Goland, et al. Standards Track [Page 29]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <propstat>
+ <prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox/>
+ <creationdate/>
+ <displayname/>
+ <getcontentlength/>
+ <getcontenttype/>
+ <getetag/>
+ <getlastmodified/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+ </propstat>
+ </response>
+ </multistatus>
+
+
+ In this example, PROPFIND is invoked on the collection resource
+ http://www.foo.bar/container/, with a propfind XML element containing
+ the propname XML element, meaning the name of all properties should
+ be returned. Since no Depth header is present, it assumes its
+ default value of "infinity", meaning the name of the properties on
+ the collection and all its progeny should be returned.
+
+ Consistent with the previous example, resource
+ http://www.foo.bar/container/ has six properties defined on it,
+ http://www.foo.bar/boxschema/bigbox,
+ http://www.foo.bar/boxschema/author, DAV:creationdate,
+ DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
+
+ The resource http://www.foo.bar/container/index.html, a member of the
+ "container" collection, has nine properties defined on it,
+ http://www.foo.bar/boxschema/bigbox, DAV:creationdate,
+ DAV:displayname, DAV:getcontentlength, DAV:getcontenttype,
+ DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and
+ DAV:supportedlock.
+
+ This example also demonstrates the use of XML namespace scoping, and
+ the default namespace. Since the "xmlns" attribute does not contain
+ an explicit "shorthand name" (prefix) letter, the namespace applies
+ by default to all enclosed elements. Hence, all elements which do
+ not explicitly state the namespace to which they belong are members
+ of the "DAV:" namespace schema.
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 30]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.2 PROPPATCH
+
+ The PROPPATCH method processes instructions specified in the request
+ body to set and/or remove properties defined on the resource
+ identified by the Request-URI.
+
+ All DAV compliant resources MUST support the PROPPATCH method and
+ MUST process instructions that are specified using the
+ propertyupdate, set, and remove XML elements of the DAV schema.
+ Execution of the directives in this method is, of course, subject to
+ access control constraints. DAV compliant resources SHOULD support
+ the setting of arbitrary dead properties.
+
+ The request message body of a PROPPATCH method MUST contain the
+ propertyupdate XML element. Instruction processing MUST occur in the
+ order instructions are received (i.e., from top to bottom).
+ Instructions MUST either all be executed or none executed. Thus if
+ any error occurs during processing all executed instructions MUST be
+ undone and a proper error result returned. Instruction processing
+ details can be found in the definition of the set and remove
+ instructions in section 12.13.
+
+8.2.1 Status Codes for use with 207 (Multi-Status)
+
+ The following are examples of response codes one would expect to be
+ used in a 207 (Multi-Status) response for this method. Note,
+ however, that unless explicitly prohibited any 2/3/4/5xx series
+ response code may be used in a 207 (Multi-Status) response.
+
+ 200 (OK) - The command succeeded. As there can be a mixture of sets
+ and removes in a body, a 201 (Created) seems inappropriate.
+
+ 403 (Forbidden) - The client, for reasons the server chooses not to
+ specify, cannot alter one of the properties.
+
+ 409 (Conflict) - The client has provided a value whose semantics are
+ not appropriate for the property. This includes trying to set read-
+ only properties.
+
+ 423 (Locked) - The specified resource is locked and the client either
+ is not a lock owner or the lock type requires a lock token to be
+ submitted and the client did not submit it.
+
+ 507 (Insufficient Storage) - The server did not have sufficient space
+ to record the property.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 31]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.2.2 Example - PROPPATCH
+
+ >>Request
+
+ PROPPATCH /bar.html HTTP/1.1
+ Host: www.foo.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propertyupdate xmlns:D="DAV:"
+ xmlns:Z="http://www.w3.com/standards/z39.50/">
+ <D:set>
+ <D:prop>
+ <Z:authors>
+ <Z:Author>Jim Whitehead</Z:Author>
+ <Z:Author>Roy Fielding</Z:Author>
+ </Z:authors>
+ </D:prop>
+ </D:set>
+ <D:remove>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ </D:remove>
+ </D:propertyupdate>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:Z="http://www.w3.com/standards/z39.50">
+ <D:response>
+ <D:href>http://www.foo.com/bar.html</D:href>
+ <D:propstat>
+ <D:prop><Z:Authors/></D:prop>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ <D:status>HTTP/1.1 409 Conflict</D:status>
+ </D:propstat>
+ <D:responsedescription> Copyright Owner can not be deleted or
+ altered.</D:responsedescription>
+ </D:response>
+ </D:multistatus>
+
+
+
+Goland, et al. Standards Track [Page 32]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ In this example, the client requests the server to set the value of
+ the http://www.w3.com/standards/z39.50/Authors property, and to
+ remove the property http://www.w3.com/standards/z39.50/Copyright-
+ Owner. Since the Copyright-Owner property could not be removed, no
+ property modifications occur. The 424 (Failed Dependency) status
+ code for the Authors property indicates this action would have
+ succeeded if it were not for the conflict with removing the
+ Copyright-Owner property.
+
+8.3 MKCOL Method
+
+ The MKCOL method is used to create a new collection. All DAV
+ compliant resources MUST support the MKCOL method.
+
+8.3.1 Request
+
+ MKCOL creates a new collection resource at the location specified by
+ the Request-URI. If the resource identified by the Request-URI is
+ non-null then the MKCOL MUST fail. During MKCOL processing, a server
+ MUST make the Request-URI a member of its parent collection, unless
+ the Request-URI is "/". If no such ancestor exists, the method MUST
+ fail. When the MKCOL operation creates a new collection resource,
+ all ancestors MUST already exist, or the method MUST fail with a 409
+ (Conflict) status code. For example, if a request to create
+ collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists,
+ the request must fail.
+
+ When MKCOL is invoked without a request body, the newly created
+ collection SHOULD have no members.
+
+ A MKCOL request message may contain a message body. The behavior of
+ a MKCOL request when the body is present is limited to creating
+ collections, members of a collection, bodies of members and
+ properties on the collections or members. If the server receives a
+ MKCOL request entity type it does not support or understand it MUST
+ respond with a 415 (Unsupported Media Type) status code. The exact
+ behavior of MKCOL for various request media types is undefined in
+ this document, and will be specified in separate documents.
+
+8.3.2 Status Codes
+
+ Responses from a MKCOL request MUST NOT be cached as MKCOL has non-
+ idempotent semantics.
+
+ 201 (Created) - The collection or structured resource was created in
+ its entirety.
+
+
+
+
+
+Goland, et al. Standards Track [Page 33]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ 403 (Forbidden) - This indicates at least one of two conditions: 1)
+ the server does not allow the creation of collections at the given
+ location in its namespace, or 2) the parent collection of the
+ Request-URI exists but cannot accept members.
+
+ 405 (Method Not Allowed) - MKCOL can only be executed on a
+ deleted/non-existent resource.
+
+ 409 (Conflict) - A collection cannot be made at the Request-URI until
+ one or more intermediate collections have been created.
+
+ 415 (Unsupported Media Type)- The server does not support the request
+ type of the body.
+
+ 507 (Insufficient Storage) - The resource does not have sufficient
+ space to record the state of the resource after the execution of this
+ method.
+
+8.3.3 Example - MKCOL
+
+ This example creates a collection called /webdisc/xfiles/ on the
+ server www.server.org.
+
+ >>Request
+
+ MKCOL /webdisc/xfiles/ HTTP/1.1
+ Host: www.server.org
+
+ >>Response
+
+ HTTP/1.1 201 Created
+
+8.4 GET, HEAD for Collections
+
+ The semantics of GET are unchanged when applied to a collection,
+ since GET is defined as, "retrieve whatever information (in the form
+ of an entity) is identified by the Request-URI" [RFC2068]. GET when
+ applied to a collection may return the contents of an "index.html"
+ resource, a human-readable view of the contents of the collection, or
+ something else altogether. Hence it is possible that the result of a
+ GET on a collection will bear no correlation to the membership of the
+ collection.
+
+ Similarly, since the definition of HEAD is a GET without a response
+ message body, the semantics of HEAD are unmodified when applied to
+ collection resources.
+
+
+
+
+
+Goland, et al. Standards Track [Page 34]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.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.
+
+8.6 DELETE
+
+ 8.6.1 DELETE for Non-Collection Resources
+
+ If the DELETE method is issued to a non-collection resource whose
+ URIs are an internal member of one or more collections, then during
+ DELETE processing a server MUST remove any URI for the resource
+ identified by the Request-URI from collections which contain it as a
+ member.
+
+8.6.2 DELETE for Collections
+
+ The DELETE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header with
+ a DELETE on a collection with any value but infinity.
+
+ DELETE instructs that the collection specified in the Request-URI and
+ all resources identified by its internal member URIs are to be
+ deleted.
+
+ If any resource identified by a member URI cannot be deleted then all
+ of the member's ancestors MUST NOT be deleted, so as to maintain
+ namespace consistency.
+
+ Any headers included with DELETE MUST be applied in processing every
+ resource to be deleted.
+
+ When the DELETE method has completed processing it MUST result in a
+ consistent namespace.
+
+ If an error occurs with a resource other than the resource identified
+ in the Request-URI then the response MUST be a 207 (Multi-Status).
+ 424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi-
+ Status). They can be safely left out because the client will know
+ that the ancestors of a resource could not be deleted when the client
+ receives an error for the ancestor's progeny. Additionally 204 (No
+ Content) errors SHOULD NOT be returned in the 207 (Multi-Status).
+ The reason for this prohibition is that 204 (No Content) is the
+ default success code.
+
+
+
+
+Goland, et al. Standards Track [Page 35]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.6.2.1 Example - DELETE
+
+ >>Request
+
+ DELETE /container/ HTTP/1.1
+ Host: www.foo.bar
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>http://www.foo.bar/container/resource3</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ </d:response>
+ </d:multistatus>
+
+ In this example the attempt to delete
+ http://www.foo.bar/container/resource3 failed because it is locked,
+ and no lock token was submitted with the request. Consequently, the
+ attempt to delete http://www.foo.bar/container/ also failed. Thus the
+ client knows that the attempt to delete http://www.foo.bar/container/
+ must have also failed since the parent can not be deleted unless its
+ child has also been deleted. Even though a Depth header has not been
+ included, a depth of infinity is assumed because the method is on a
+ collection.
+
+8.7 PUT
+
+8.7.1 PUT for Non-Collection Resources
+
+ A PUT performed on an existing resource replaces the GET response
+ entity of the resource. Properties defined on the resource may be
+ recomputed during PUT processing but are not otherwise affected. For
+ example, if a server recognizes the content type of the request body,
+ it may be able to automatically extract information that could be
+ profitably exposed as properties.
+
+ A PUT that would result in the creation of a resource without an
+ appropriately scoped parent collection MUST fail with a 409
+ (Conflict).
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 36]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.7.2 PUT for Collections
+
+ As defined in the HTTP/1.1 specification [RFC2068], the "PUT method
+ requests that the enclosed entity be stored under the supplied
+ Request-URI." Since submission of an entity representing a
+ collection would implicitly encode creation and deletion of
+ resources, this specification intentionally does not define a
+ transmission format for creating a collection using PUT. Instead,
+ the MKCOL method is defined to create collections.
+
+ When the PUT operation creates a new non-collection resource all
+ ancestors MUST already exist. If all ancestors do not exist, the
+ method MUST fail with a 409 (Conflict) status code. For example, if
+ resource /a/b/c/d.html is to be created and /a/b/c/ does not exist,
+ then the request must fail.
+
+8.8 COPY Method
+
+ The COPY method creates a duplicate of the source resource,
+ identified by the Request-URI, in the destination resource,
+ identified by the URI in the Destination header. The Destination
+ header MUST be present. The exact behavior of the COPY method
+ depends on the type of the source resource.
+
+ All WebDAV compliant resources MUST support the COPY method.
+ However, support for the COPY method does not guarantee the ability
+ to copy a resource. For example, separate programs may control
+ resources on the same server. As a result, it may not be possible to
+ copy a resource to a location that appears to be on the same server.
+
+8.8.1 COPY for HTTP/1.1 resources
+
+ When the source resource is not a collection the result of the COPY
+ method is the creation of a new resource at the destination whose
+ state and behavior match that of the source resource as closely as
+ possible. After a successful COPY invocation, all properties on the
+ source resource MUST be duplicated on the destination resource,
+ subject to modifying headers and XML elements, following the
+ definition for copying properties. Since the environment at the
+ destination may be different than at the source due to factors
+ outside the scope of control of the server, such as the absence of
+ resources required for correct operation, it may not be possible to
+ completely duplicate the behavior of the resource at the destination.
+ Subsequent alterations to the destination resource will not modify
+ the source resource. Subsequent alterations to the source resource
+ will not modify the destination resource.
+
+
+
+
+
+Goland, et al. Standards Track [Page 37]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.8.2. COPY for Properties
+
+ The following section defines how properties on a resource are
+ handled during a COPY operation.
+
+ Live properties SHOULD be duplicated as identically behaving live
+ properties at the destination resource. If a property cannot be
+ copied live, then its value MUST be duplicated, octet-for-octet, in
+ an identically named, dead property on the destination resource
+ subject to the effects of the propertybehavior XML element.
+
+ The propertybehavior XML element can specify that properties are
+ copied on best effort, that all live properties must be successfully
+ copied or the method must fail, or that a specified list of live
+ properties must be successfully copied or the method must fail. The
+ propertybehavior XML element is defined in section 12.12.
+
+8.8.3 COPY for Collections
+
+ The COPY method on a collection without a Depth header MUST act as if
+ a Depth header with value "infinity" was included. A client may
+ submit a Depth header on a COPY on a collection with a value of "0"
+ or "infinity". DAV compliant servers MUST support the "0" and
+ "infinity" Depth header behaviors.
+
+ A COPY of depth infinity instructs that the collection resource
+ identified by the Request-URI is to be copied to the location
+ identified by the URI in the Destination header, and all its internal
+ member resources are to be copied to a location relative to it,
+ recursively through all levels of the collection hierarchy.
+
+ A COPY of "Depth: 0" only instructs that the collection and its
+ properties but not resources identified by its internal member URIs,
+ are to be copied.
+
+ Any headers included with a COPY MUST be applied in processing every
+ resource to be copied with the exception of the Destination header.
+
+ The Destination header only specifies the destination URI for the
+ Request-URI. When applied to members of the collection identified by
+ the Request-URI the value of Destination is to be modified to reflect
+ the current location in the hierarchy. So, if the Request- URI is
+ /a/ with Host header value http://fun.com/ and the Destination is
+ http://fun.com/b/ then when http://fun.com/a/c/d is processed it must
+ use a Destination of http://fun.com/b/c/d.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 38]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ When the COPY method has completed processing it MUST have created a
+ consistent namespace at the destination (see section 5.1 for the
+ definition of namespace consistency). However, if an error occurs
+ while copying an internal collection, the server MUST NOT copy any
+ resources identified by members of this collection (i.e., the server
+ must skip this subtree), as this would create an inconsistent
+ namespace. After detecting an error, the COPY operation SHOULD try to
+ finish as much of the original copy operation as possible (i.e., the
+ server should still attempt to copy other subtrees and their members,
+ that are not descendents of an error-causing collection). So, for
+ example, if an infinite depth copy operation is performed on
+ collection /a/, which contains collections /a/b/ and /a/c/, and an
+ error occurs copying /a/b/, an attempt should still be made to copy
+ /a/c/. Similarly, after encountering an error copying a non-
+ collection resource as part of an infinite depth copy, the server
+ SHOULD try to finish as much of the original copy operation as
+ possible.
+
+ If an error in executing the COPY method occurs with a resource other
+ than the resource identified in the Request-URI then the response
+ MUST be a 207 (Multi-Status).
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a COPY method. These responses can
+ be safely omitted because the client will know that the progeny of a
+ resource could not be copied when the client receives an error for
+ the parent. Additionally 201 (Created)/204 (No Content) status codes
+ SHOULD NOT be returned as values in 207 (Multi-Status) responses from
+ COPY methods. They, too, can be safely omitted because they are the
+ default success codes.
+
+8.8.4 COPY and the Overwrite Header
+
+ If a resource exists at the destination and the Overwrite header is
+ "T" then prior to performing the copy the server MUST perform a
+ DELETE with "Depth: infinity" on the destination resource. If the
+ Overwrite header is set to "F" then the operation will fail.
+
+8.8.5 Status Codes
+
+ 201 (Created) - The source resource was successfully copied. The
+ copy operation resulted in the creation of a new resource.
+
+ 204 (No Content) - The source resource was successfully copied to a
+ pre-existing destination resource.
+
+ 403 (Forbidden) _ The source and destination URIs are the same.
+
+
+
+
+Goland, et al. Standards Track [Page 39]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ 409 (Conflict) _ A resource cannot be created at the destination
+ until one or more intermediate collections have been created.
+
+ 412 (Precondition Failed) - The server was unable to maintain the
+ liveness of the properties listed in the propertybehavior XML element
+ or the Overwrite header is "F" and the state of the destination
+ resource is non-null.
+
+ 423 (Locked) - The destination resource was locked.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server and the destination server refuses to accept the resource.
+
+ 507 (Insufficient Storage) - The destination resource does not have
+ sufficient space to record the state of the resource after the
+ execution of this method.
+
+8.8.6 Example - COPY with Overwrite
+
+ This example shows resource
+ http://www.ics.uci.edu/~fielding/index.html being copied to the
+ location http://www.ics.uci.edu/users/f/fielding/index.html. The 204
+ (No Content) status code indicates the existing resource at the
+ destination was overwritten.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+8.8.7 Example - COPY with No Overwrite
+
+ The following example shows the same copy operation being performed,
+ but with the Overwrite header set to "F." A response of 412
+ (Precondition Failed) is returned because the destination resource
+ has a non-null state.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+ Overwrite: F
+
+
+
+Goland, et al. Standards Track [Page 40]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ >>Response
+
+ HTTP/1.1 412 Precondition Failed
+
+8.8.8 Example - COPY of a Collection
+
+ >>Request
+
+ COPY /container/ HTTP/1.1
+ Host: www.foo.bar
+ Destination: http://www.foo.bar/othercontainer/
+ Depth: infinity
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:propertybehavior xmlns:d="DAV:">
+ <d:keepalive>*</d:keepalive>
+ </d:propertybehavior>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>http://www.foo.bar/othercontainer/R2/</d:href>
+ <d:status>HTTP/1.1 412 Precondition Failed</d:status>
+ </d:response>
+ </d:multistatus>
+
+ The Depth header is unnecessary as the default behavior of COPY on a
+ collection is to act as if a "Depth: infinity" header had been
+ submitted. In this example most of the resources, along with the
+ collection, were copied successfully. However the collection R2
+ failed, most likely due to a problem with maintaining the liveness of
+ properties (this is specified by the propertybehavior XML element).
+ Because there was an error copying R2, none of R2's members were
+ copied. However no errors were listed for those members due to the
+ error minimization rules given in section 8.8.3.
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 41]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.9 MOVE Method
+
+ The MOVE operation on a non-collection resource is the logical
+ equivalent of a copy (COPY), followed by consistency maintenance
+ processing, followed by a delete of the source, where all three
+ actions are performed atomically. The consistency maintenance step
+ allows the server to perform updates caused by the move, such as
+ updating all URIs other than the Request-URI which identify the
+ source resource, to point to the new destination resource.
+ Consequently, the Destination header MUST be present on all MOVE
+ methods and MUST follow all COPY requirements for the COPY part of
+ the MOVE method. All DAV compliant resources MUST support the MOVE
+ method. However, support for the MOVE method does not guarantee the
+ ability to move a resource to a particular destination.
+
+ For example, separate programs may actually control different sets of
+ resources on the same server. Therefore, it may not be possible to
+ move a resource within a namespace that appears to belong to the same
+ server.
+
+ If a resource exists at the destination, the destination resource
+ will be DELETEd as a side-effect of the MOVE operation, subject to
+ the restrictions of the Overwrite header.
+
+8.9.1 MOVE for Properties
+
+ The behavior of properties on a MOVE, including the effects of the
+ propertybehavior XML element, MUST be the same as specified in
+ section 8.8.2.
+
+8.9.2 MOVE for Collections
+
+ A MOVE with "Depth: infinity" instructs that the collection
+ identified by the Request-URI be moved to the URI specified in the
+ Destination header, and all resources identified by its internal
+ member URIs are to be moved to locations relative to it, recursively
+ through all levels of the collection hierarchy.
+
+ The MOVE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header on a
+ MOVE on a collection with any value but "infinity".
+
+ Any headers included with MOVE MUST be applied in processing every
+ resource to be moved with the exception of the Destination header.
+
+ The behavior of the Destination header is the same as given for COPY
+ on collections.
+
+
+
+
+Goland, et al. Standards Track [Page 42]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ When the MOVE method has completed processing it MUST have created a
+ consistent namespace at both the source and destination (see section
+ 5.1 for the definition of namespace consistency). However, if an
+ error occurs while moving an internal collection, the server MUST NOT
+ move any resources identified by members of the failed collection
+ (i.e., the server must skip the error-causing subtree), as this would
+ create an inconsistent namespace. In this case, after detecting the
+ error, the move operation SHOULD try to finish as much of the
+ original move as possible (i.e., the server should still attempt to
+ move other subtrees and the resources identified by their members,
+ that are not descendents of an error-causing collection). So, for
+ example, if an infinite depth move is performed on collection /a/,
+ which contains collections /a/b/ and /a/c/, and an error occurs
+ moving /a/b/, an attempt should still be made to try moving /a/c/.
+ Similarly, after encountering an error moving a non-collection
+ resource as part of an infinite depth move, the server SHOULD try to
+ finish as much of the original move operation as possible.
+
+ If an error occurs with a resource other than the resource identified
+ in the Request-URI then the response MUST be a 207 (Multi-Status).
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a MOVE method. These errors can be
+ safely omitted because the client will know that the progeny of a
+ resource could not be moved when the client receives an error for the
+ parent. Additionally 201 (Created)/204 (No Content) responses SHOULD
+ NOT be returned as values in 207 (Multi-Status) responses from a
+ MOVE. These responses can be safely omitted because they are the
+ default success codes.
+
+8.9.3 MOVE and the Overwrite Header
+
+ If a resource exists at the destination and the Overwrite header is
+ "T" then prior to performing the move the server MUST perform a
+ DELETE with "Depth: infinity" on the destination resource. If the
+ Overwrite header is set to "F" then the operation will fail.
+
+8.9.4 Status Codes
+
+ 201 (Created) - The source resource was successfully moved, and a new
+ resource was created at the destination.
+
+ 204 (No Content) - The source resource was successfully moved to a
+ pre-existing destination resource.
+
+ 403 (Forbidden) _ The source and destination URIs are the same.
+
+
+
+
+
+Goland, et al. Standards Track [Page 43]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ 409 (Conflict) _ A resource cannot be created at the destination
+ until one or more intermediate collections have been created.
+
+ 412 (Precondition Failed) - The server was unable to maintain the
+ liveness of the properties listed in the propertybehavior XML element
+ or the Overwrite header is "F" and the state of the destination
+ resource is non-null.
+
+ 423 (Locked) - The source or the destination resource was locked.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server and the destination server refuses to accept the resource.
+
+8.9.5 Example - MOVE of a Non-Collection
+
+ This example shows resource
+ http://www.ics.uci.edu/~fielding/index.html being moved to the
+ location http://www.ics.uci.edu/users/f/fielding/index.html. The
+ contents of the destination resource would have been overwritten if
+ the destination resource had been non-null. In this case, since
+ there was nothing at the destination resource, the response code is
+ 201 (Created).
+
+ >>Request
+
+ MOVE /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 201 Created
+ Location: http://www.ics.uci.edu/users/f/fielding/index.html
+
+
+8.9.6 Example - MOVE of a Collection
+
+ >>Request
+
+ MOVE /container/ HTTP/1.1
+ Host: www.foo.bar
+ Destination: http://www.foo.bar/othercontainer/
+ Overwrite: F
+ If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
+ (<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+
+
+
+Goland, et al. Standards Track [Page 44]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:propertybehavior xmlns:d='DAV:'>
+ <d:keepalive>*</d:keepalive>
+ </d:propertybehavior>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d='DAV:'>
+ <d:response>
+ <d:href>http://www.foo.bar/othercontainer/C2/</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ </d:response>
+ </d:multistatus>
+
+ In this example the client has submitted a number of lock tokens with
+ the request. A lock token will need to be submitted for every
+ resource, both source and destination, anywhere in the scope of the
+ method, that is locked. In this case the proper lock token was not
+ submitted for the destination http://www.foo.bar/othercontainer/C2/.
+ This means that the resource /container/C2/ could not be moved.
+ Because there was an error copying /container/C2/, none of
+ /container/C2's members were copied. However no errors were listed
+ for those members due to the error minimization rules given in
+ section 8.8.3. User agent authentication has previously occurred via
+ a mechanism outside the scope of the HTTP protocol, in an underlying
+ transport layer.
+
+8.10 LOCK Method
+
+ The following sections describe the LOCK method, which is used to
+ take out a lock of any access type. These sections on the LOCK
+ method describe only those semantics that are specific to the LOCK
+ method and are independent of the access type of the lock being
+ requested.
+
+ Any resource which supports the LOCK method MUST, at minimum, support
+ the XML request and response formats defined herein.
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 45]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.10.1 Operation
+
+ A LOCK method invocation creates the lock specified by the lockinfo
+ XML element on the Request-URI. Lock method requests SHOULD have a
+ XML request body which contains an owner XML element for this lock
+ request, unless this is a refresh request. The LOCK request may have
+ a Timeout header.
+
+ Clients MUST assume that locks may arbitrarily disappear at any time,
+ regardless of the value given in the Timeout header. The Timeout
+ header only indicates the behavior of the server if "extraordinary"
+ circumstances do not occur. For example, an administrator may remove
+ a lock at any time or the system may crash in such a way that it
+ loses the record of the lock's existence. The response MUST contain
+ the value of the lockdiscovery property in a prop XML element.
+
+ In order to indicate the lock token associated with a newly created
+ lock, a Lock-Token response header MUST be included in the response
+ for every successful LOCK request for a new lock. Note that the
+ Lock-Token header would not be returned in the response for a
+ successful refresh LOCK request because a new lock was not created.
+
+8.10.2 The Effect of Locks on Properties and Collections
+
+ The scope of a lock is the entire state of the resource, including
+ its body and associated properties. As a result, a lock on a
+ resource MUST also lock the resource's properties.
+
+ For collections, a lock also affects the ability to add or remove
+ members. The nature of the effect depends upon the type of access
+ control involved.
+
+8.10.3 Locking Replicated Resources
+
+ A resource may be made available through more than one URI. However
+ locks apply to resources, not URIs. Therefore a LOCK request on a
+ resource MUST NOT succeed if can not be honored by all the URIs
+ through which the resource is addressable.
+
+8.10.4 Depth and Locking
+
+ The Depth header may be used with the LOCK method. Values other than
+ 0 or infinity MUST NOT be used with the Depth header on a LOCK
+ method. All resources that support the LOCK method MUST support the
+ Depth header.
+
+ A Depth header of value 0 means to just lock the resource specified
+ by the Request-URI.
+
+
+
+Goland, et al. Standards Track [Page 46]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ If the Depth header is set to infinity then the resource specified in
+ the Request-URI along with all its internal members, all the way down
+ the hierarchy, are to be locked. A successful result MUST return a
+ single lock token which represents all the resources that have been
+ locked. If an UNLOCK is successfully executed on this token, all
+ associated resources are unlocked. If the lock cannot be granted to
+ all resources, a 409 (Conflict) status code MUST be returned with a
+ response entity body containing a multistatus XML element describing
+ which resource(s) prevented the lock from being granted. Hence,
+ partial success is not an option. Either the entire hierarchy is
+ locked or no resources are locked.
+
+ If no Depth header is submitted on a LOCK request then the request
+ MUST act as if a "Depth:infinity" had been submitted.
+
+8.10.5 Interaction with other Methods
+
+ The interaction of a LOCK with various methods is dependent upon the
+ lock type. However, independent of lock type, a successful DELETE of
+ a resource MUST cause all of its locks to be removed.
+
+8.10.6 Lock Compatibility Table
+
+ The table below describes the behavior that occurs when a lock
+ request is made on a resource.
+
+ Current lock state/ | Shared Lock | Exclusive
+ Lock request | | Lock
+ =====================+=================+==============
+ None | True | True
+ ---------------------+-----------------+--------------
+ Shared Lock | True | False
+ ---------------------+-----------------+--------------
+ Exclusive Lock | False | False*
+ ------------------------------------------------------
+
+ Legend: True = lock may be granted. False = lock MUST NOT be
+ granted. *=It is illegal for a principal to request the same lock
+ twice.
+
+ The current lock state of a resource is given in the leftmost column,
+ and lock requests are listed in the first row. The intersection of a
+ row and column gives the result of a lock request. For example, if a
+ shared lock is held on a resource, and an exclusive lock is
+ requested, the table entry is "false", indicating the lock must not
+ be granted.
+
+
+
+
+
+Goland, et al. Standards Track [Page 47]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.10.7 Status Codes
+
+ 200 (OK) - The lock request succeeded and the value of the
+ lockdiscovery property is included in the body.
+
+ 412 (Precondition Failed) - The included lock token was not
+ enforceable on this resource or the server could not satisfy the
+ request in the lockinfo XML element.
+
+ 423 (Locked) - The resource is locked, so the method has been
+ rejected.
+
+8.10.8 Example - Simple Lock Request
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: webdav.sb.aol.com
+ Timeout: Infinite, Second-4100000000
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw@webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D='DAV:'>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ <D:owner>
+ <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>Infinity</D:depth>
+
+
+
+Goland, et al. Standards Track [Page 48]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <D:owner>
+ <D:href>
+ http://www.ics.uci.edu/~ejw/contact.html
+ </D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href>
+ opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
+ </D:href>
+ </D:locktoken>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+ This example shows the successful creation of an exclusive write lock
+ on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc.
+ The resource http://www.ics.uci.edu/~ejw/contact.html contains
+ contact information for the owner of the lock. The server has an
+ activity-based timeout policy in place on this resource, which causes
+ the lock to automatically be removed after 1 week (604800 seconds).
+ Note that the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+8.10.9 Example - Refreshing a Write Lock
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: webdav.sb.aol.com
+ Timeout: Infinite, Second-4100000000
+ If: (<opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>)
+ Authorization: Digest username="ejw",
+ realm="ejw@webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+
+
+
+Goland, et al. Standards Track [Page 49]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>Infinity</D:depth>
+ <D:owner>
+ <D:href>
+ http://www.ics.uci.edu/~ejw/contact.html
+ </D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href>
+ opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
+ </D:href>
+ </D:locktoken>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+ This request would refresh the lock, resetting any time outs. Notice
+ that the client asked for an infinite time out but the server choose
+ to ignore the request. In this example, the nonce, response, and
+ opaque fields have not been calculated in the Authorization request
+ header.
+
+8.10.10 Example - Multi-Resource Lock Request
+
+ >>Request
+
+ LOCK /webdav/ HTTP/1.1
+ Host: webdav.sb.aol.com
+ Timeout: Infinite, Second-4100000000
+ Depth: infinity
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw@webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D="DAV:">
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:owner>
+ <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+ >>Response
+
+
+
+Goland, et al. Standards Track [Page 50]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://webdav.sb.aol.com/webdav/secret</D:href>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ </D:response>
+ <D:response>
+ <D:href>http://webdav.sb.aol.com/webdav/</D:href>
+ <D:propstat>
+ <D:prop><D:lockdiscovery/></D:prop>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ This example shows a request for an exclusive write lock on a
+ collection and all its children. In this request, the client has
+ specified that it desires an infinite length lock, if available,
+ otherwise a timeout of 4.1 billion seconds, if available. The request
+ entity body contains the contact information for the principal taking
+ out the lock, in this case a web page URL.
+
+ The error is a 403 (Forbidden) response on the resource
+ http://webdav.sb.aol.com/webdav/secret. Because this resource could
+ not be locked, none of the resources were locked. Note also that the
+ lockdiscovery property for the Request-URI has been included as
+ required. In this example the lockdiscovery property is empty which
+ means that there are no outstanding locks on the resource.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+8.11 UNLOCK Method
+
+ The UNLOCK method removes the lock identified by the lock token in
+ the Lock-Token request header from the Request-URI, and all other
+ resources included in the lock. If all resources which have been
+ locked under the submitted lock token can not be unlocked then the
+ UNLOCK request MUST fail.
+
+ Any DAV compliant resource which supports the LOCK method MUST
+ support the UNLOCK method.
+
+
+
+
+
+Goland, et al. Standards Track [Page 51]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+8.11.1 Example - UNLOCK
+
+ >>Request
+
+ UNLOCK /workspace/webdav/info.doc HTTP/1.1
+ Host: webdav.sb.aol.com
+ Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
+ Authorization: Digest username="ejw",
+ realm="ejw@webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, the lock identified by the lock token
+ "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is
+ successfully removed from the resource
+ http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock
+ included more than just one resource, the lock is removed from all
+ resources included in the lock. The 204 (No Content) status code is
+ used instead of 200 (OK) because there is no response entity body.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+9 HTTP Headers for Distributed Authoring
+
+9.1 DAV Header
+
+ DAV = "DAV" ":" "1" ["," "2"] ["," 1#extend]
+
+ This header indicates that the resource supports the DAV schema and
+ protocol as specified. All DAV compliant resources MUST return the
+ DAV header on all OPTIONS responses.
+
+ The value is a list of all compliance classes that the resource
+ supports. Note that above a comma has already been added to the 2.
+ This is because a resource can not be level 2 compliant unless it is
+ also level 1 compliant. Please refer to section 15 for more details.
+ In general, however, support for one compliance class does not entail
+ support for any other.
+
+9.2 Depth Header
+
+ Depth = "Depth" ":" ("0" | "1" | "infinity")
+
+
+
+
+Goland, et al. Standards Track [Page 52]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ The Depth header is used with methods executed on resources which
+ could potentially have internal members to indicate whether the
+ method is to be applied only to the resource ("Depth: 0"), to the
+ resource and its immediate children, ("Depth: 1"), or the resource
+ and all its progeny ("Depth: infinity").
+
+ The Depth header is only supported if a method's definition
+ explicitly provides for such support.
+
+ The following rules are the default behavior for any method that
+ supports the Depth header. A method may override these defaults by
+ defining different behavior in its definition.
+
+ Methods which support the Depth header may choose not to support all
+ of the header's values and may define, on a case by case basis, the
+ behavior of the method if a Depth header is not present. For example,
+ the MOVE method only supports "Depth: infinity" and if a Depth header
+ is not present will act as if a "Depth: infinity" header had been
+ applied.
+
+ Clients MUST NOT rely upon methods executing on members of their
+ hierarchies in any particular order or on the execution being atomic
+ unless the particular method explicitly provides such guarantees.
+
+ Upon execution, a method with a Depth header will perform as much of
+ its assigned task as possible and then return a response specifying
+ what it was able to accomplish and what it failed to do.
+
+ So, for example, an attempt to COPY a hierarchy may result in some of
+ the members being copied and some not.
+
+ Any headers on a method that has a defined interaction with the Depth
+ header MUST be applied to all resources in the scope of the method
+ except where alternative behavior is explicitly defined. For example,
+ an If-Match header will have its value applied against every resource
+ in the method's scope and will cause the method to fail if the header
+ fails to match.
+
+ If a resource, source or destination, within the scope of the method
+ with a Depth header is locked in such a way as to prevent the
+ successful execution of the method, then the lock token for that
+ resource MUST be submitted with the request in the If request header.
+
+ The Depth header only specifies the behavior of the method with
+ regards to internal children. If a resource does not have internal
+ children then the Depth header MUST be ignored.
+
+
+
+
+
+Goland, et al. Standards Track [Page 53]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Please note, however, that it is always an error to submit a value
+ for the Depth header that is not allowed by the method's definition.
+ Thus submitting a "Depth: 1" on a COPY, even if the resource does not
+ have internal members, will result in a 400 (Bad Request). The method
+ should fail not because the resource doesn't have internal members,
+ but because of the illegal value in the header.
+
+9.3 Destination Header
+
+ Destination = "Destination" ":" absoluteURI
+
+ The Destination header specifies the URI which identifies a
+ destination resource for methods such as COPY and MOVE, which take
+ two URIs as parameters. Note that the absoluteURI production is
+ defined in [RFC2396].
+
+9.4 If Header
+
+ If = "If" ":" ( 1*No-tag-list | 1*Tagged-list)
+ No-tag-list = List
+ Tagged-list = Resource 1*List
+ Resource = Coded-URL
+ List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
+ State-token = Coded-URL
+ Coded-URL = "<" absoluteURI ">"
+
+ The If header is intended to have similar functionality to the If-
+ Match header defined in section 14.25 of [RFC2068]. However the If
+ header is intended for use with any URI which represents state
+ information, referred to as a state token, about a resource as well
+ as ETags. A typical example of a state token is a lock token, and
+ lock tokens are the only state tokens defined in this specification.
+
+ All DAV compliant resources MUST honor the If header.
+
+ The If header's purpose is to describe a series of state lists. If
+ the state of the resource to which the header is applied does not
+ match any of the specified state lists then the request MUST fail
+ with a 412 (Precondition Failed). If one of the described state
+ lists matches the state of the resource then the request may succeed.
+
+ Note that the absoluteURI production is defined in [RFC2396].
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 54]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+9.4.1 No-tag-list Production
+
+ The No-tag-list production describes a series of state tokens and
+ ETags. If multiple No-tag-list productions are used then one only
+ needs to match the state of the resource for the method to be allowed
+ to continue.
+
+ If a method, due to the presence of a Depth or Destination header, is
+ applied to multiple resources then the No-tag-list production MUST be
+ applied to each resource the method is applied to.
+
+9.4.1.1 Example - No-tag-list If Header
+
+ If: (<locktoken:a-write-lock-token> ["I am an ETag"]) (["I am another
+ ETag"])
+
+ The previous header would require that any resources within the scope
+ of the method must either be locked with the specified lock token and
+ in the state identified by the "I am an ETag" ETag or in the state
+ identified by the second ETag "I am another ETag". To put the matter
+ more plainly one can think of the previous If header as being in the
+ form (or (and <locktoken:a-write-lock-token> ["I am an ETag"]) (and
+ ["I am another ETag"])).
+
+9.4.2 Tagged-list Production
+
+ The tagged-list production scopes a list production. That is, it
+ specifies that the lists following the resource specification only
+ apply to the specified resource. The scope of the resource
+ production begins with the list production immediately following the
+ resource production and ends with the next resource production, if
+ any.
+
+ When the If header is applied to a particular resource, the Tagged-
+ list productions MUST be searched to determine if any of the listed
+ resources match the operand resource(s) for the current method. If
+ none of the resource productions match the current resource then the
+ header MUST be ignored. If one of the resource productions does
+ match the name of the resource under consideration then the list
+ productions following the resource production MUST be applied to the
+ resource in the manner specified in the previous section.
+
+ The same URI MUST NOT appear more than once in a resource production
+ in an If header.
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 55]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+9.4.2.1 Example - Tagged List If header
+
+ COPY /resource1 HTTP/1.1
+ Host: www.foo.bar
+ Destination: http://www.foo.bar/resource2
+ If: <http://www.foo.bar/resource1> (<locktoken:a-write-lock-token>
+ [W/"A weak ETag"]) (["strong ETag"])
+ <http://www.bar.bar/random>(["another strong ETag"])
+
+ In this example http://www.foo.bar/resource1 is being copied to
+ http://www.foo.bar/resource2. When the method is first applied to
+ http://www.foo.bar/resource1, resource1 must be in the state
+ specified by "(<locktoken:a-write-lock-token> [W/"A weak ETag"])
+ (["strong ETag"])", that is, it either must be locked with a lock
+ token of "locktoken:a-write-lock-token" and have a weak entity tag
+ W/"A weak ETag" or it must have a strong entity tag "strong ETag".
+
+ That is the only success condition since the resource
+ http://www.bar.bar/random never has the method applied to it (the
+ only other resource listed in the If header) and
+ http://www.foo.bar/resource2 is not listed in the If header.
+
+9.4.3 not Production
+
+ Every state token or ETag is either current, and hence describes the
+ state of a resource, or is not current, and does not describe the
+ state of a resource. The boolean operation of matching a state token
+ or ETag to the current state of a resource thus resolves to a true or
+ false value. The not production is used to reverse that value. The
+ scope of the not production is the state-token or entity-tag
+ immediately following it.
+
+ If: (Not <locktoken:write1> <locktoken:write2>)
+
+ When submitted with a request, this If header requires that all
+ operand resources must not be locked with locktoken:write1 and must
+ be locked with locktoken:write2.
+
+9.4.4 Matching Function
+
+ When performing If header processing, the definition of a matching
+ state token or entity tag is as follows.
+
+ Matching entity tag: Where the entity tag matches an entity tag
+ associated with that resource.
+
+ Matching state token: Where there is an exact match between the state
+ token in the If header and any state token on the resource.
+
+
+
+Goland, et al. Standards Track [Page 56]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+9.4.5 If Header and Non-DAV Compliant Proxies
+
+ Non-DAV compliant proxies will not honor the If header, since they
+ will not understand the If header, and HTTP requires non-understood
+ headers to be ignored. When communicating with HTTP/1.1 proxies, the
+ "Cache-Control: no-cache" request header MUST be used so as to
+ prevent the proxy from improperly trying to service the request from
+ its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache"
+ request header MUST be used for the same reason.
+
+9.5 Lock-Token Header
+
+ Lock-Token = "Lock-Token" ":" Coded-URL
+
+ The Lock-Token request header is used with the UNLOCK method to
+ identify the lock to be removed. The lock token in the Lock-Token
+ request header MUST identify a lock that contains the resource
+ identified by Request-URI as a member.
+
+ The Lock-Token response header is used with the LOCK method to
+ indicate the lock token created as a result of a successful LOCK
+ request to create a new lock.
+
+9.6 Overwrite Header
+
+ Overwrite = "Overwrite" ":" ("T" | "F")
+
+ The Overwrite header specifies whether the server should overwrite
+ the state of a non-null destination resource during a COPY or MOVE.
+ A value of "F" states that the server must not perform the COPY or
+ MOVE operation if the state of the destination resource is non-null.
+ If the overwrite header is not included in a COPY or MOVE request
+ then the resource MUST treat the request as if it has an overwrite
+ header of value "T". While the Overwrite header appears to duplicate
+ the functionality of the If-Match: * header of HTTP/1.1, If-Match
+ applies only to the Request-URI, and not to the Destination of a COPY
+ or MOVE.
+
+ If a COPY or MOVE is not performed due to the value of the Overwrite
+ header, the method MUST fail with a 412 (Precondition Failed) status
+ code.
+
+ All DAV compliant resources MUST support the Overwrite header.
+
+9.7 Status-URI Response Header
+
+ The Status-URI response header may be used with the 102 (Processing)
+ status code to inform the client as to the status of a method.
+
+
+
+Goland, et al. Standards Track [Page 57]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Status-URI = "Status-URI" ":" *(Status-Code Coded-URL) ; Status-Code
+ is defined in 6.1.1 of [RFC2068]
+
+ The URIs listed in the header are source resources which have been
+ affected by the outstanding method. The status code indicates the
+ resolution of the method on the identified resource. So, for
+ example, if a MOVE method on a collection is outstanding and a 102
+ (Processing) response with a Status-URI response header is returned,
+ the included URIs will indicate resources that have had move
+ attempted on them and what the result was.
+
+9.8 Timeout Request Header
+
+ TimeOut = "Timeout" ":" 1#TimeType
+ TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other)
+ DAVTimeOutVal = 1*digit
+ Other = "Extend" field-value ; See section 4.2 of [RFC2068]
+
+ Clients may include Timeout headers in their LOCK requests. However,
+ the server is not required to honor or even consider these requests.
+ Clients MUST NOT submit a Timeout request header with any method
+ other than a LOCK method.
+
+ A Timeout request header MUST contain at least one TimeType and may
+ contain multiple TimeType entries. The purpose of listing multiple
+ TimeType entries is to indicate multiple different values and value
+ types that are acceptable to the client. The client lists the
+ TimeType entries in order of preference.
+
+ Timeout response values MUST use a Second value, Infinite, or a
+ TimeType the client has indicated familiarity with. The server may
+ assume a client is familiar with any TimeType submitted in a Timeout
+ header.
+
+ The "Second" TimeType specifies the number of seconds that will
+ elapse between granting of the lock at the server, and the automatic
+ removal of the lock. The timeout value for TimeType "Second" MUST
+ NOT be greater than 2^32-1.
+
+ The timeout counter SHOULD be restarted any time an owner of the lock
+ sends a method to any member of the lock, including unsupported
+ methods, or methods which are unsuccessful. However the lock MUST be
+ refreshed if a refresh LOCK method is successfully received.
+
+ If the timeout expires then the lock may be lost. Specifically, if
+ the server wishes to harvest the lock upon time-out, the server
+ SHOULD act as if an UNLOCK method was executed by the server on the
+ resource using the lock token of the timed-out lock, performed with
+
+
+
+Goland, et al. Standards Track [Page 58]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ its override authority. Thus logs should be updated with the
+ disposition of the lock, notifications should be sent, etc., just as
+ they would be for an UNLOCK request.
+
+ Servers are advised to pay close attention to the values submitted by
+ clients, as they will be indicative of the type of activity the
+ client intends to perform. For example, an applet running in a
+ browser may need to lock a resource, but because of the instability
+ of the environment within which the applet is running, the applet may
+ be turned off without warning. As a result, the applet is likely to
+ ask for a relatively small timeout value so that if the applet dies,
+ the lock can be quickly harvested. However, a document management
+ system is likely to ask for an extremely long timeout because its
+ user may be planning on going off-line.
+
+ A client MUST NOT assume that just because the time-out has expired
+ the lock has been lost.
+
+10 Status Code Extensions to HTTP/1.1
+
+ The following status codes are added to those defined in HTTP/1.1
+ [RFC2068].
+
+10.1 102 Processing
+
+ The 102 (Processing) status code is an interim response used to
+ inform the client that the server has accepted the complete request,
+ but has not yet completed it. This status code SHOULD only be sent
+ when the server has a reasonable expectation that the request will
+ take significant time to complete. As guidance, if a method is taking
+ longer than 20 seconds (a reasonable, but arbitrary value) to process
+ the server SHOULD return a 102 (Processing) response. The server MUST
+ send a final response after the request has been completed.
+
+ Methods can potentially take a long period of time to process,
+ especially methods that support the Depth header. In such cases the
+ client may time-out the connection while waiting for a response. To
+ prevent this the server may return a 102 (Processing) status code to
+ indicate to the client that the server is still processing the
+ method.
+
+10.2 207 Multi-Status
+
+ The 207 (Multi-Status) status code provides status for multiple
+ independent operations (see section 11 for more information).
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 59]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+10.3 422 Unprocessable Entity
+
+ The 422 (Unprocessable Entity) status code means the server
+ understands the content type of the request entity (hence a
+ 415(Unsupported Media Type) status code is inappropriate), and the
+ syntax of the request entity is correct (thus a 400 (Bad Request)
+ status code is inappropriate) but was unable to process the contained
+ instructions. For example, this error condition may occur if an XML
+ request body contains well-formed (i.e., syntactically correct), but
+ semantically erroneous XML instructions.
+
+10.4 423 Locked
+
+ The 423 (Locked) status code means the source or destination resource
+ of a method is locked.
+
+10.5 424 Failed Dependency
+
+ The 424 (Failed Dependency) status code means that the method could
+ not be performed on the resource because the requested action
+ depended on another action and that action failed. For example, if a
+ command in a PROPPATCH method fails then, at minimum, the rest of the
+ commands will also fail with 424 (Failed Dependency).
+
+10.6 507 Insufficient Storage
+
+ The 507 (Insufficient Storage) status code means the method could not
+ be performed on the resource because the server is unable to store
+ the representation needed to successfully complete the request. This
+ condition is considered to be temporary. If the request which
+ received this status code was the result of a user action, the
+ request MUST NOT be repeated until it is requested by a separate user
+ action.
+
+11 Multi-Status Response
+
+ The default 207 (Multi-Status) response body is a text/xml or
+ application/xml HTTP entity that contains a single XML element called
+ multistatus, which contains a set of XML elements called response
+ which contain 200, 300, 400, and 500 series status codes generated
+ during the method invocation. 100 series status codes SHOULD NOT be
+ recorded in a response XML element.
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 60]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+12 XML Element Definitions
+
+ In the section below, the final line of each section gives the
+ element type declaration using the format defined in [REC-XML]. The
+ "Value" field, where present, specifies further restrictions on the
+ allowable contents of the XML element using BNF (i.e., to further
+ restrict the values of a PCDATA element).
+
+12.1 activelock XML Element
+
+ Name: activelock
+ Namespace: DAV:
+ Purpose: Describes a lock on a resource.
+
+ <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
+ locktoken?) >
+
+12.1.1 depth XML Element
+
+ Name: depth
+ Namespace: DAV:
+ Purpose: The value of the Depth header.
+ Value: "0" | "1" | "infinity"
+
+ <!ELEMENT depth (#PCDATA) >
+
+12.1.2 locktoken XML Element
+
+ Name: locktoken
+ Namespace: DAV:
+ Purpose: The lock token associated with a lock.
+ Description: The href contains one or more opaque lock token URIs
+ which all refer to the same lock (i.e., the OpaqueLockToken-URI
+ production in section 6.4).
+
+ <!ELEMENT locktoken (href+) >
+
+12.1.3 timeout XML Element
+
+ Name: timeout
+ Namespace: DAV:
+ Purpose: The timeout associated with a lock
+ Value: TimeType ;Defined in section 9.8
+
+ <!ELEMENT timeout (#PCDATA) >
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 61]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+12.2 collection XML Element
+
+ Name: collection
+ Namespace: DAV:
+ Purpose: Identifies the associated resource as a collection. The
+ resourcetype property of a collection resource MUST have this value.
+
+ <!ELEMENT collection EMPTY >
+
+12.3 href XML Element
+
+ Name: href
+ Namespace: DAV:
+ Purpose: Identifies the content of the element as a URI.
+ Value: URI ; See section 3.2.1 of [RFC2068]
+
+ <!ELEMENT href (#PCDATA)>
+
+12.4 link XML Element
+
+ Name: link
+ Namespace: DAV:
+ Purpose: Identifies the property as a link and contains the source
+ and destination of that link.
+ Description: The link XML element is used to provide the sources and
+ destinations of a link. The name of the property containing the link
+ XML element provides the type of the link. Link is a multi-valued
+ element, so multiple links may be used together to indicate multiple
+ links with the same type. The values in the href XML elements inside
+ the src and dst XML elements of the link XML element MUST NOT be
+ rejected if they point to resources which do not exist.
+
+ <!ELEMENT link (src+, dst+) >
+
+12.4.1 dst XML Element
+
+ Name: dst
+ Namespace: DAV:
+ Purpose: Indicates the destination of a link
+ Value: URI
+
+ <!ELEMENT dst (#PCDATA) >
+
+12.4.2 src XML Element
+
+ Name: src
+ Namespace: DAV:
+ Purpose: Indicates the source of a link.
+
+
+
+Goland, et al. Standards Track [Page 62]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Value: URI
+
+ <!ELEMENT src (#PCDATA) >
+
+12.5 lockentry XML Element
+
+ Name: lockentry
+ Namespace: DAV:
+ Purpose: Defines the types of locks that can be used with the
+ resource.
+
+ <!ELEMENT lockentry (lockscope, locktype) >
+
+12.6 lockinfo XML Element
+
+ Name: lockinfo
+ Namespace: DAV:
+ Purpose: The lockinfo XML element is used with a LOCK method to
+ specify the type of lock the client wishes to have created.
+
+ <!ELEMENT lockinfo (lockscope, locktype, owner?) >
+
+12.7 lockscope XML Element
+
+ Name: lockscope
+ Namespace: DAV:
+ Purpose: Specifies whether a lock is an exclusive lock, or a
+ shared lock.
+
+ <!ELEMENT lockscope (exclusive | shared) >
+
+12.7.1 exclusive XML Element
+
+ Name: exclusive
+ Namespace: DAV:
+ Purpose: Specifies an exclusive lock
+
+ <!ELEMENT exclusive EMPTY >
+
+12.7.2 shared XML Element
+
+ Name: shared
+ Namespace: DAV:
+ Purpose: Specifies a shared lock
+
+ <!ELEMENT shared EMPTY >
+
+
+
+
+
+Goland, et al. Standards Track [Page 63]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+12.8 locktype XML Element
+
+ Name: locktype
+ Namespace: DAV:
+ Purpose: Specifies the access type of a lock. At present, this
+ specification only defines one lock type, the write lock.
+
+ <!ELEMENT locktype (write) >
+
+12.8.1 write XML Element
+
+ Name: write
+ Namespace: DAV:
+ Purpose: Specifies a write lock.
+
+ <!ELEMENT write EMPTY >
+
+12.9 multistatus XML Element
+
+ Name: multistatus
+ Namespace: DAV:
+ Purpose: Contains multiple response messages.
+ Description: The responsedescription at the top level is used to
+ provide a general message describing the overarching nature of the
+ response. If this value is available an application may use it
+ instead of presenting the individual response descriptions contained
+ within the responses.
+
+ <!ELEMENT multistatus (response+, responsedescription?) >
+
+12.9.1 response XML Element
+
+ Name: response
+ Namespace: DAV:
+ Purpose: Holds a single response describing the effect of a
+ method on resource and/or its properties.
+ Description: A particular href MUST NOT appear more than once as the
+ child of a response XML element under a multistatus XML element.
+ This requirement is necessary in order to keep processing costs for a
+ response to linear time. Essentially, this prevents having to search
+ in order to group together all the responses by href. There are,
+ however, no requirements regarding ordering based on href values.
+
+ <!ELEMENT response (href, ((href*, status)|(propstat+)),
+ responsedescription?) >
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 64]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+12.9.1.1 propstat XML Element
+
+ Name: propstat
+ Namespace: DAV:
+ Purpose: Groups together a prop and status element that is
+ associated with a particular href element.
+ Description: The propstat XML element MUST contain one prop XML
+ element and one status XML element. The contents of the prop XML
+ element MUST only list the names of properties to which the result in
+ the status element applies.
+
+ <!ELEMENT propstat (prop, status, responsedescription?) >
+
+12.9.1.2 status XML Element
+
+ Name: status
+ Namespace: DAV:
+ Purpose: Holds a single HTTP status-line
+ Value: status-line ;status-line defined in [RFC2068]
+
+ <!ELEMENT status (#PCDATA) >
+
+12.9.2 responsedescription XML Element
+
+ Name: responsedescription
+ Namespace: DAV:
+ Purpose: Contains a message that can be displayed to the user
+ explaining the nature of the response.
+ Description: This XML element provides information suitable to be
+ presented to a user.
+
+ <!ELEMENT responsedescription (#PCDATA) >
+
+12.10 owner XML Element
+
+ Name: owner
+ Namespace: DAV:
+ Purpose: Provides information about the principal taking out a
+ lock.
+ Description: The owner XML element provides information sufficient
+ for either directly contacting a principal (such as a telephone
+ number or Email URI), or for discovering the principal (such as the
+ URL of a homepage) who owns a lock.
+
+ <!ELEMENT owner ANY>
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 65]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+12.11 prop XML element
+
+ Name: prop
+ Namespace: DAV:
+ Purpose: Contains properties related to a resource.
+ Description: The prop XML element is a generic container for
+ properties defined on resources. All elements inside a prop XML
+ element MUST define properties related to the resource. No other
+ elements may be used inside of a prop element.
+
+ <!ELEMENT prop ANY>
+
+12.12 propertybehavior XML element
+
+ Name: propertybehavior Namespace: DAV: Purpose: Specifies
+ how properties are handled during a COPY or MOVE.
+ Description: The propertybehavior XML element specifies how
+ properties are handled during a COPY or MOVE. If this XML element is
+ not included in the request body then the server is expected to act
+ as defined by the default property handling behavior of the
+ associated method. All WebDAV compliant resources MUST support the
+ propertybehavior XML element.
+
+ <!ELEMENT propertybehavior (omit | keepalive) >
+
+12.12.1 keepalive XML element
+
+ Name: keepalive
+ Namespace: DAV:
+ Purpose: Specifies requirements for the copying/moving of live
+ properties.
+ Description: If a list of URIs is included as the value of keepalive
+ then the named properties MUST be "live" after they are copied
+ (moved) to the destination resource of a COPY (or MOVE). If the
+ value "*" is given for the keepalive XML element, this designates
+ that all live properties on the source resource MUST be live on the
+ destination. If the requirements specified by the keepalive element
+ can not be honored then the method MUST fail with a 412 (Precondition
+ Failed). All DAV compliant resources MUST support the keepalive XML
+ element for use with the COPY and MOVE methods.
+ Value: "*" ; #PCDATA value can only be "*"
+
+ <!ELEMENT keepalive (#PCDATA | href+) >
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 66]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+12.12.2 omit XML element
+
+ Name: omit
+ Namespace: DAV:
+ Purpose: The omit XML element instructs the server that it should
+ use best effort to copy properties but a failure to copy a property
+ MUST NOT cause the method to fail. Description: The default behavior
+ for a COPY or MOVE is to copy/move all properties or fail the method.
+ In certain circumstances, such as when a server copies a resource
+ over another protocol such as FTP, it may not be possible to
+ copy/move the properties associated with the resource. Thus any
+ attempt to copy/move over FTP would always have to fail because
+ properties could not be moved over, even as dead properties. All DAV
+ compliant resources MUST support the omit XML element on COPY/MOVE
+ methods.
+
+ <!ELEMENT omit EMPTY >
+
+12.13 propertyupdate XML element
+
+ Name: propertyupdate
+ Namespace: DAV:
+ Purpose: Contains a request to alter the properties on a
+ resource.
+ Description: This XML element is a container for the information
+ required to modify the properties on the resource. This XML element
+ is multi-valued.
+
+ <!ELEMENT propertyupdate (remove | set)+ >
+
+12.13.1 remove XML element
+
+ Name: remove
+ Namespace: DAV:
+ Purpose: Lists the DAV properties to be removed from a resource.
+ Description: Remove instructs that the properties specified in prop
+ should be removed. Specifying the removal of a property that does
+ not exist is not an error. All the XML elements in a prop XML
+ element inside of a remove XML element MUST be empty, as only the
+ names of properties to be removed are required.
+
+ <!ELEMENT remove (prop) >
+
+12.13.2 set XML element
+
+ Name: set
+ Namespace: DAV:
+ Purpose: Lists the DAV property values to be set for a resource.
+
+
+
+Goland, et al. Standards Track [Page 67]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Description: The set XML element MUST contain only a prop XML
+ element. The elements contained by the prop XML element inside the
+ set XML element MUST specify the name and value of properties that
+ are set on the resource identified by Request-URI. If a property
+ already exists then its value is replaced. Language tagging
+ information in the property's value (in the "xml:lang" attribute, if
+ present) MUST be persistently stored along with the property, and
+ MUST be subsequently retrievable using PROPFIND.
+
+ <!ELEMENT set (prop) >
+
+12.14 propfind XML Element
+
+ Name: propfind
+ Namespace: DAV:
+ Purpose: Specifies the properties to be returned from a PROPFIND
+ method. Two special elements are specified for use with propfind,
+ allprop and propname. If prop is used inside propfind it MUST only
+ contain property names, not values.
+
+ <!ELEMENT propfind (allprop | propname | prop) >
+
+12.14.1 allprop XML Element
+
+ Name: allprop Namespace: DAV: Purpose: The allprop XML
+ element specifies that all property names and values on the resource
+ are to be returned.
+
+ <!ELEMENT allprop EMPTY >
+
+12.14.2 propname XML Element
+
+ Name: propname Namespace: DAV: Purpose: The propname XML
+ element specifies that only a list of property names on the resource
+ is to be returned.
+
+ <!ELEMENT propname EMPTY >
+
+13 DAV Properties
+
+ For DAV properties, the name of the property is also the same as the
+ name of the XML element that contains its value. In the section
+ below, the final line of each section gives the element type
+ declaration using the format defined in [REC-XML]. The "Value" field,
+ where present, specifies further restrictions on the allowable
+ contents of the XML element using BNF (i.e., to further restrict the
+ values of a PCDATA element).
+
+
+
+
+Goland, et al. Standards Track [Page 68]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+13.1 creationdate Property
+
+ Name: creationdate
+ Namespace: DAV:
+ Purpose: Records the time and date the resource was created.
+ Value: date-time ; See Appendix 2
+ Description: The creationdate property should be defined on all DAV
+ compliant resources. If present, it contains a timestamp of the
+ moment when the resource was created (i.e., the moment it had non-
+ null state).
+
+ <!ELEMENT creationdate (#PCDATA) >
+
+13.2 displayname Property
+
+ Name: displayname
+ Namespace: DAV:
+ Purpose: Provides a name for the resource that is suitable for
+ presentation to a user.
+ Description: The displayname property should be defined on all DAV
+ compliant resources. If present, the property contains a description
+ of the resource that is suitable for presentation to a user.
+
+ <!ELEMENT displayname (#PCDATA) >
+
+13.3 getcontentlanguage Property
+
+ Name: getcontentlanguage
+ Namespace: DAV:
+ Purpose: Contains the Content-Language header returned by a GET
+ without accept headers
+ Description: The getcontentlanguage property MUST be defined on any
+ DAV compliant resource that returns the Content-Language header on a
+ GET.
+ Value: language-tag ;language-tag is defined in section 14.13
+ of [RFC2068]
+
+ <!ELEMENT getcontentlanguage (#PCDATA) >
+
+13.4 getcontentlength Property
+
+ Name: getcontentlength
+ Namespace: DAV:
+ Purpose: Contains the Content-Length header returned by a GET
+ without accept headers.
+ Description: The getcontentlength property MUST be defined on any
+ DAV compliant resource that returns the Content-Length header in
+ response to a GET.
+
+
+
+Goland, et al. Standards Track [Page 69]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Value: content-length ; see section 14.14 of [RFC2068]
+
+ <!ELEMENT getcontentlength (#PCDATA) >
+
+13.5 getcontenttype Property
+
+ Name: getcontenttype
+ Namespace: DAV:
+ Purpose: Contains the Content-Type header returned by a GET
+ without accept headers.
+ Description: This getcontenttype property MUST be defined on any DAV
+ compliant resource that returns the Content-Type header in response
+ to a GET.
+ Value: media-type ; defined in section 3.7 of [RFC2068]
+
+ <!ELEMENT getcontenttype (#PCDATA) >
+
+13.6 getetag Property
+
+ Name: getetag
+ Namespace: DAV:
+ Purpose: Contains the ETag header returned by a GET without
+ accept headers.
+ Description: The getetag property MUST be defined on any DAV
+ compliant resource that returns the Etag header.
+ Value: entity-tag ; defined in section 3.11 of [RFC2068]
+
+ <!ELEMENT getetag (#PCDATA) >
+
+13.7 getlastmodified Property
+
+ Name: getlastmodified
+ Namespace: DAV:
+ Purpose: Contains the Last-Modified header returned by a GET
+ method without accept headers.
+ Description: Note that the last-modified date on a resource may
+ reflect changes in any part of the state of the resource, not
+ necessarily just a change to the response to the GET method. For
+ example, a change in a property may cause the last-modified date to
+ change. The getlastmodified property MUST be defined on any DAV
+ compliant resource that returns the Last-Modified header in response
+ to a GET.
+ Value: HTTP-date ; defined in section 3.3.1 of [RFC2068]
+
+ <!ELEMENT getlastmodified (#PCDATA) >
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 70]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+13.8 lockdiscovery Property
+
+ Name: lockdiscovery
+ Namespace: DAV:
+ Purpose: Describes the active locks on a resource
+ Description: The lockdiscovery property returns a listing of who has
+ a lock, what type of lock he has, the timeout type and the time
+ remaining on the timeout, and the associated lock token. The server
+ is free to withhold any or all of this information if the requesting
+ principal does not have sufficient access rights to see the requested
+ data.
+
+ <!ELEMENT lockdiscovery (activelock)* >
+
+13.8.1 Example - Retrieving the lockdiscovery Property
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.foo.bar
+ Content-Length: xxxx
+ Content-Type: text/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D='DAV:'>
+ <D:prop><D:lockdiscovery/></D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D='DAV:'>
+ <D:response>
+ <D:href>http://www.foo.bar/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>0</D:depth>
+ <D:owner>Jane Smith</D:owner>
+ <D:timeout>Infinite</D:timeout>
+ <D:locktoken>
+
+
+
+Goland, et al. Standards Track [Page 71]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <D:href>
+ opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76
+ </D:href>
+ </D:locktoken>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ This resource has a single exclusive write lock on it, with an
+ infinite timeout.
+
+13.9 resourcetype Property
+
+ Name: resourcetype
+ Namespace: DAV:
+ Purpose: Specifies the nature of the resource.
+ Description: The resourcetype property MUST be defined on all DAV
+ compliant resources. The default value is empty.
+
+ <!ELEMENT resourcetype ANY >
+
+13.10 source Property
+
+ Name: source
+ Namespace: DAV:
+ Purpose: The destination of the source link identifies the
+ resource that contains the unprocessed source of the link's source.
+ Description: The source of the link (src) is typically the URI of the
+ output resource on which the link is defined, and there is typically
+ only one destination (dst) of the link, which is the URI where the
+ unprocessed source of the resource may be accessed. When more than
+ one link destination exists, this specification asserts no policy on
+ ordering.
+
+ <!ELEMENT source (link)* >
+
+13.10.1 Example - A source Property
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:" xmlns:F="http://www.foocorp.com/Project/">
+ <D:source>
+ <D:link>
+ <F:projfiles>Source</F:projfiles>
+ <D:src>http://foo.bar/program</D:src>
+
+
+
+Goland, et al. Standards Track [Page 72]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <D:dst>http://foo.bar/src/main.c</D:dst>
+ </D:link>
+ <D:link>
+ <F:projfiles>Library</F:projfiles>
+ <D:src>http://foo.bar/program</D:src>
+ <D:dst>http://foo.bar/src/main.lib</D:dst>
+ </D:link>
+ <D:link>
+ <F:projfiles>Makefile</F:projfiles>
+ <D:src>http://foo.bar/program</D:src>
+ <D:dst>http://foo.bar/src/makefile</D:dst>
+ </D:link>
+ </D:source>
+ </D:prop>
+
+ In this example the resource http://foo.bar/program has a source
+ property that contains three links. Each link contains three
+ elements, two of which, src and dst, are part of the DAV schema
+ defined in this document, and one which is defined by the schema
+ http://www.foocorp.com/project/ (Source, Library, and Makefile). A
+ client which only implements the elements in the DAV spec will not
+ understand the foocorp elements and will ignore them, thus seeing the
+ expected source and destination links. An enhanced client may know
+ about the foocorp elements and be able to present the user with
+ additional information about the links. This example demonstrates
+ the power of XML markup, allowing element values to be enhanced
+ without breaking older clients.
+
+13.11 supportedlock Property
+
+ Name: supportedlock
+ Namespace: DAV:
+ Purpose: To provide a listing of the lock capabilities supported
+ by the resource.
+ Description: The supportedlock property of a resource returns a
+ listing of the combinations of scope and access types which may be
+ specified in a lock request on the resource. Note that the actual
+ contents are themselves controlled by access controls so a server is
+ not required to provide information the client is not authorized to
+ see.
+
+ <!ELEMENT supportedlock (lockentry)* >
+
+13.11.1 Example - Retrieving the supportedlock Property
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+
+
+
+Goland, et al. Standards Track [Page 73]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Host: www.foo.bar
+ Content-Length: xxxx
+ Content-Type: text/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop><D:supportedlock/></D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.foo.bar/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+14 Instructions for Processing XML in DAV
+
+ All DAV compliant resources MUST ignore any unknown XML element and
+ all its children encountered while processing a DAV method that uses
+ XML as its command language.
+
+ This restriction also applies to the processing, by clients, of DAV
+ property values where unknown XML elements SHOULD be ignored unless
+ the property's schema declares otherwise.
+
+
+
+
+
+Goland, et al. Standards Track [Page 74]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ This restriction does not apply to setting dead DAV properties on the
+ server where the server MUST record unknown XML elements.
+
+ Additionally, this restriction does not apply to the use of XML where
+ XML happens to be the content type of the entity body, for example,
+ when used as the body of a PUT.
+
+ Since XML can be transported as text/xml or application/xml, a DAV
+ server MUST accept DAV method requests with XML parameters
+ transported as either text/xml or application/xml, and DAV client
+ MUST accept XML responses using either text/xml or application/xml.
+
+15 DAV Compliance Classes
+
+ A DAV compliant resource can choose from two classes of compliance.
+ A client can discover the compliance classes of a resource by
+ executing OPTIONS on the resource, and examining the "DAV" header
+ which is returned.
+
+ Since this document describes extensions to the HTTP/1.1 protocol,
+ minimally all DAV compliant resources, clients, and proxies MUST be
+ compliant with [RFC2068].
+
+ Compliance classes are not necessarily sequential. A resource that is
+ class 2 compliant must also be class 1 compliant; but if additional
+ compliance classes are defined later, a resource that is class 1, 2,
+ and 4 compliant might not be class 3 compliant. Also note that
+ identifiers other than numbers may be used as compliance class
+ identifiers.
+
+15.1 Class 1
+
+ A class 1 compliant resource MUST meet all "MUST" requirements in all
+ sections of this document.
+
+ Class 1 compliant resources MUST return, at minimum, the value "1" in
+ the DAV header on all responses to the OPTIONS method.
+
+15.2 Class 2
+
+ A class 2 compliant resource MUST meet all class 1 requirements and
+ support the LOCK method, the supportedlock property, the
+ lockdiscovery property, the Time-Out response header and the Lock-
+ Token request header. A class "2" compliant resource SHOULD also
+ support the Time-Out request header and the owner XML element.
+
+ Class 2 compliant resources MUST return, at minimum, the values "1"
+ and "2" in the DAV header on all responses to the OPTIONS method.
+
+
+
+Goland, et al. Standards Track [Page 75]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+16 Internationalization Considerations
+
+ In the realm of internationalization, this specification complies
+ with the IETF Character Set Policy [RFC2277]. In this specification,
+ human-readable fields can be found either in the value of a property,
+ or in an error message returned in a response entity body. In both
+ cases, the human-readable content is encoded using XML, which has
+ explicit provisions for character set tagging and encoding, and
+ requires that XML processors read XML elements encoded, at minimum,
+ using the UTF-8 [UTF-8] encoding of the ISO 10646 multilingual plane.
+ XML examples in this specification demonstrate use of the charset
+ parameter of the Content-Type header, as defined in [RFC2376], as
+ well as the XML "encoding" attribute, which together provide charset
+ identification information for MIME and XML processors.
+
+ XML also provides a language tagging capability for specifying the
+ language of the contents of a particular XML element. XML uses
+ either IANA registered language tags (see [RFC1766]) or ISO 639
+ language tags [ISO-639] in the "xml:lang" attribute of an XML element
+ to identify the language of its content and attributes.
+
+ WebDAV applications MUST support the character set tagging, character
+ set encoding, and the language tagging functionality of the XML
+ specification. Implementors of WebDAV applications are strongly
+ encouraged to read "XML Media Types" [RFC2376] for instruction on
+ which MIME media type to use for XML transport, and on use of the
+ charset parameter of the Content-Type header.
+
+ Names used within this specification fall into three categories:
+ names of protocol elements such as methods and headers, names of XML
+ elements, and names of properties. Naming of protocol elements
+ follows the precedent of HTTP, using English names encoded in USASCII
+ for methods and headers. Since these protocol elements are not
+ visible to users, and are in fact simply long token identifiers, they
+ do not need to support encoding in multiple character sets.
+ Similarly, though the names of XML elements used in this
+ specification are English names encoded in UTF-8, these names are not
+ visible to the user, and hence do not need to support multiple
+ character set encodings.
+
+ The name of a property defined on a resource is a URI. Although some
+ applications (e.g., a generic property viewer) will display property
+ URIs directly to their users, it is expected that the typical
+ application will use a fixed set of properties, and will provide a
+ mapping from the property name URI to a human-readable field when
+ displaying the property name to a user. It is only in the case where
+
+
+
+
+
+Goland, et al. Standards Track [Page 76]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ the set of properties is not known ahead of time that an application
+ need display a property name URI to a user. We recommend that
+ applications provide human-readable property names wherever feasible.
+
+ For error reporting, we follow the convention of HTTP/1.1 status
+ codes, including with each status code a short, English description
+ of the code (e.g., 423 (Locked)). While the possibility exists that
+ a poorly crafted user agent would display this message to a user,
+ internationalized applications will ignore this message, and display
+ an appropriate message in the user's language and character set.
+
+ Since interoperation of clients and servers does not require locale
+ information, this specification does not specify any mechanism for
+ transmission of this information.
+
+17 Security Considerations
+
+ This section is provided to detail issues concerning security
+ implications of which WebDAV applications need to be aware.
+
+ All of the security considerations of HTTP/1.1 (discussed in
+ [RFC2068]) and XML (discussed in [RFC2376]) also apply to WebDAV. In
+ addition, the security risks inherent in remote authoring require
+ stronger authentication technology, introduce several new privacy
+ concerns, and may increase the hazards from poor server design.
+ These issues are detailed below.
+
+17.1 Authentication of Clients
+
+ Due to their emphasis on authoring, WebDAV servers need to use
+ authentication technology to protect not just access to a network
+ resource, but the integrity of the resource as well. Furthermore,
+ the introduction of locking functionality requires support for
+ authentication.
+
+ A password sent in the clear over an insecure channel is an
+ inadequate means for protecting the accessibility and integrity of a
+ resource as the password may be intercepted. Since Basic
+ authentication for HTTP/1.1 performs essentially clear text
+ transmission of a password, Basic authentication MUST NOT be used to
+ authenticate a WebDAV client to a server unless the connection is
+ secure. Furthermore, a WebDAV server MUST NOT send Basic
+ authentication credentials in a WWW-Authenticate header unless the
+ connection is secure. Examples of secure connections include a
+ Transport Layer Security (TLS) connection employing a strong cipher
+ suite with mutual authentication of client and server, or a
+ connection over a network which is physically secure, for example, an
+ isolated network in a building with restricted access.
+
+
+
+Goland, et al. Standards Track [Page 77]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ WebDAV applications MUST support the Digest authentication scheme
+ [RFC2069]. Since Digest authentication verifies that both parties to
+ a communication know a shared secret, a password, without having to
+ send that secret in the clear, Digest authentication avoids the
+ security problems inherent in Basic authentication while providing a
+ level of authentication which is useful in a wide range of scenarios.
+
+17.2 Denial of Service
+
+ Denial of service attacks are of special concern to WebDAV servers.
+ WebDAV plus HTTP enables denial of service attacks on every part of a
+ system's resources.
+
+ The underlying storage can be attacked by PUTting extremely large
+ files.
+
+ Asking for recursive operations on large collections can attack
+ processing time.
+
+ Making multiple pipelined requests on multiple connections can attack
+ network connections.
+
+ WebDAV servers need to be aware of the possibility of a denial of
+ service attack at all levels.
+
+17.3 Security through Obscurity
+
+ WebDAV provides, through the PROPFIND method, a mechanism for listing
+ the member resources of a collection. This greatly diminishes the
+ effectiveness of security or privacy techniques that rely only on the
+ difficulty of discovering the names of network resources. Users of
+ WebDAV servers are encouraged to use access control techniques to
+ prevent unwanted access to resources, rather than depending on the
+ relative obscurity of their resource names.
+
+17.4 Privacy Issues Connected to Locks
+
+ When submitting a lock request a user agent may also submit an owner
+ XML field giving contact information for the person taking out the
+ lock (for those cases where a person, rather than a robot, is taking
+ out the lock). This contact information is stored in a lockdiscovery
+ property on the resource, and can be used by other collaborators to
+ begin negotiation over access to the resource. However, in many
+ cases this contact information can be very private, and should not be
+ widely disseminated. Servers SHOULD limit read access to the
+ lockdiscovery property as appropriate. Furthermore, user agents
+
+
+
+
+
+Goland, et al. Standards Track [Page 78]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ SHOULD provide control over whether contact information is sent at
+ all, and if contact information is sent, control over exactly what
+ information is sent.
+
+17.5 Privacy Issues Connected to Properties
+
+ Since property values are typically used to hold information such as
+ the author of a document, there is the possibility that privacy
+ concerns could arise stemming from widespread access to a resource's
+ property data. To reduce the risk of inadvertent release of private
+ information via properties, servers are encouraged to develop access
+ control mechanisms that separate read access to the resource body and
+ read access to the resource's properties. This allows a user to
+ control the dissemination of their property data without overly
+ restricting access to the resource's contents.
+
+17.6 Reduction of Security due to Source Link
+
+ HTTP/1.1 warns against providing read access to script code because
+ it may contain sensitive information. Yet WebDAV, via its source
+ link facility, can potentially provide a URI for script resources so
+ they may be authored. For HTTP/1.1, a server could reasonably
+ prevent access to source resources due to the predominance of read-
+ only access. WebDAV, with its emphasis on authoring, encourages read
+ and write access to source resources, and provides the source link
+ facility to identify the source. This reduces the security benefits
+ of eliminating access to source resources. Users and administrators
+ of WebDAV servers should be very cautious when allowing remote
+ authoring of scripts, limiting read and write access to the source
+ resources to authorized principals.
+
+17.7 Implications of XML External Entities
+
+ XML supports a facility known as "external entities", defined in
+ section 4.2.2 of [REC-XML], which instruct an XML processor to
+ retrieve and perform an inline include of XML located at a particular
+ URI. An external XML entity can be used to append or modify the
+ document type declaration (DTD) associated with an XML document. An
+ external XML entity can also be used to include XML within the
+ content of an XML document. For non-validating XML, such as the XML
+ used in this specification, including an external XML entity is not
+ required by [REC-XML]. However, [REC-XML] does state that an XML
+ processor may, at its discretion, include the external XML entity.
+
+ External XML entities have no inherent trustworthiness and are
+ subject to all the attacks that are endemic to any HTTP GET request.
+ Furthermore, it is possible for an external XML entity to modify the
+ DTD, and hence affect the final form of an XML document, in the worst
+
+
+
+Goland, et al. Standards Track [Page 79]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ case significantly modifying its semantics, or exposing the XML
+ processor to the security risks discussed in [RFC2376]. Therefore,
+ implementers must be aware that external XML entities should be
+ treated as untrustworthy.
+
+ There is also the scalability risk that would accompany a widely
+ deployed application which made use of external XML entities. In
+ this situation, it is possible that there would be significant
+ numbers of requests for one external XML entity, potentially
+ overloading any server which fields requests for the resource
+ containing the external XML entity.
+
+17.8 Risks Connected with Lock Tokens
+
+ This specification, in section 6.4, requires the use of Universal
+ Unique Identifiers (UUIDs) for lock tokens, in order to guarantee
+ their uniqueness across space and time. UUIDs, as defined in [ISO-
+ 11578], contain a "node" field which "consists of the IEEE address,
+ usually the host address. For systems with multiple IEEE 802 nodes,
+ any available node address can be used." Since a WebDAV server will
+ issue many locks over its lifetime, the implication is that it will
+ also be publicly exposing its IEEE 802 address.
+
+ There are several risks associated with exposure of IEEE 802
+ addresses. Using the IEEE 802 address:
+
+ * It is possible to track the movement of hardware from subnet to
+ subnet.
+
+ * It may be possible to identify the manufacturer of the hardware
+ running a WebDAV server.
+
+ * It may be possible to determine the number of each type of computer
+ running WebDAV.
+
+ Section 6.4.1 of this specification details an alternate mechanism
+ for generating the "node" field of a UUID without using an IEEE 802
+ address, which alleviates the risks associated with exposure of IEEE
+ 802 addresses by using an alternate source of uniqueness.
+
+18 IANA Considerations
+
+ This document defines two namespaces, the namespace of property
+ names, and the namespace of WebDAV-specific XML elements used within
+ property values.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 80]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ URIs are used for both names, for several reasons. Assignment of a
+ URI does not require a request to a central naming authority, and
+ hence allow WebDAV property names and XML elements to be quickly
+ defined by any WebDAV user or application. URIs also provide a
+ unique address space, ensuring that the distributed users of WebDAV
+ will not have collisions among the property names and XML elements
+ they create.
+
+ This specification defines a distinguished set of property names and
+ XML elements that are understood by all WebDAV applications. The
+ property names and XML elements in this specification are all derived
+ from the base URI DAV: by adding a suffix to this URI, for example,
+ DAV:creationdate for the "creationdate" property.
+
+ This specification also defines a URI scheme for the encoding of lock
+ tokens, the opaquelocktoken URI scheme described in section 6.4.
+
+ To ensure correct interoperation based on this specification, IANA
+ must reserve the URI namespaces starting with "DAV:" and with
+ "opaquelocktoken:" for use by this specification, its revisions, and
+ related WebDAV specifications.
+
+19 Intellectual Property
+
+ The following notice is copied from RFC 2026 [RFC2026], section 10.4,
+ and describes the position of the IETF concerning intellectual
+ property claims made against this document.
+
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to
+ pertain to the implementation or use other technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; neither does it represent that it
+ has made any effort to identify any such rights. Information on the
+ IETF's procedures with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication 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 implementors or users of this specification can
+ be obtained from the IETF Secretariat.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights which may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+
+
+
+
+Goland, et al. Standards Track [Page 81]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+20 Acknowledgements
+
+ A specification such as this thrives on piercing critical review and
+ withers from apathetic neglect. The authors gratefully acknowledge
+ the contributions of the following people, whose insights were so
+ valuable at every stage of our work.
+
+ Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan
+ Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners-
+ Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith
+ Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee
+ Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan
+ Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis
+ Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der
+ Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven
+ Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten,
+ Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff,
+ Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike
+ Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi,
+ Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran,
+ Fabio Vitali, Gregory Woodhouse, and Lauren Wood.
+
+ Two from this list deserve special mention. The contributions by
+ Larry Masinter have been invaluable, both in helping the formation of
+ the working group and in patiently coaching the authors along the
+ way. In so many ways he has set high standards we have toiled to
+ meet. The contributions of Judith Slein in clarifying the
+ requirements, and in patiently reviewing draft after draft, both
+ improved this specification and expanded our minds on document
+ management.
+
+ We would also like to thank John Turner for developing the XML DTD.
+
+21 References
+
+21.1 Normative References
+
+ [RFC1766] Alvestrand, H., "Tags for the Identification of
+ Languages", RFC 1766, March 1995.
+
+ [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
+ Languages", BCP 18, RFC 2277, January 1998.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 82]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter,
+ "Uniform Resource Identifiers (URI): Generic Syntax",
+ RFC 2396, August 1998.
+
+ [REC-XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen,
+ "Extensible Markup Language (XML)." World Wide Web
+ Consortium Recommendation REC-xml-19980210.
+ http://www.w3.org/TR/1998/REC-xml-19980210.
+
+ [REC-XML-NAMES] T. Bray, D. Hollander, A. Layman, "Namespaces in
+ XML". World Wide Web Consortium Recommendation REC-
+ xml-names-19990114. http://www.w3.org/TR/1999/REC-
+ xml-names-19990114/
+
+ [RFC2069] Franks, J., Hallam-Baker, P., Hostetler, J., Leach,
+ P, Luotonen, A., Sink, E. and L. Stewart, "An
+ Extension to HTTP : Digest Access Authentication",
+ RFC 2069, January 1997.
+
+ [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and
+ T. Berners-Lee, "Hypertext Transfer Protocol --
+ HTTP/1.1", RFC 2068, January 1997.
+
+ [ISO-639] ISO (International Organization for Standardization).
+ ISO 639:1988. "Code for the representation of names
+ of languages."
+
+ [ISO-8601] ISO (International Organization for Standardization).
+ ISO 8601:1988. "Data elements and interchange formats
+ - Information interchange - Representation of dates
+ and times."
+
+ [ISO-11578] ISO (International Organization for Standardization).
+ ISO/IEC 11578:1996. "Information technology - Open
+ Systems Interconnection - Remote Procedure Call
+ (RPC)"
+
+ [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997.
+
+ [UTF-8] Yergeau, F., "UTF-8, a transformation format of
+ Unicode and ISO 10646", RFC 2279, January 1998.
+
+21.2 Informational References
+
+ [RFC2026] Bradner, S., "The Internet Standards Process - Revision
+ 3", BCP 9, RFC 2026, October 1996.
+
+
+
+
+
+Goland, et al. Standards Track [Page 83]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ [RFC1807] Lasher, R. and D. Cohen, "A Format for Bibliographic
+ Records", RFC 1807, June 1995.
+
+ [WF] C. Lagoze, "The Warwick Framework: A Container
+ Architecture for Diverse Sets of Metadata", D-Lib
+ Magazine, July/August 1996.
+ http://www.dlib.org/dlib/july96/lagoze/07lagoze.html
+
+ [USMARC] Network Development and MARC Standards, Office, ed. 1994.
+ "USMARC Format for Bibliographic Data", 1994. Washington,
+ DC: Cataloging Distribution Service, Library of Congress.
+
+ [REC-PICS] J. Miller, T. Krauskopf, P. Resnick, W. Treese, "PICS
+ Label Distribution Label Syntax and Communication
+ Protocols" Version 1.1, World Wide Web Consortium
+ Recommendation REC-PICS-labels-961031.
+ http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html.
+
+ [RFC2291] Slein, J., Vitali, F., Whitehead, E. and D. Durand,
+ "Requirements for Distributed Authoring and Versioning
+ Protocol for the World Wide Web", RFC 2291, February 1998.
+
+ [RFC2413] Weibel, S., Kunze, J., Lagoze, C. and M. Wolf, "Dublin
+ Core Metadata for Resource Discovery", RFC 2413, September
+ 1998.
+
+ [RFC2376] Whitehead, E. and M. Murata, "XML Media Types", RFC 2376,
+ July 1998.
+
+22 Authors' Addresses
+
+ Y. Y. Goland
+ Microsoft Corporation
+ One Microsoft Way
+ Redmond, WA 98052-6399
+
+ EMail: yarong@microsoft.com
+
+
+ E. J. Whitehead, Jr.
+ Dept. Of Information and Computer Science
+ University of California, Irvine
+ Irvine, CA 92697-3425
+
+ EMail: ejw@ics.uci.edu
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 84]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ A. Faizi
+ Netscape
+ 685 East Middlefield Road
+ Mountain View, CA 94043
+
+ EMail: asad@netscape.com
+
+
+ S. R. Carter
+ Novell
+ 1555 N. Technology Way
+ M/S ORM F111
+ Orem, UT 84097-2399
+
+ EMail: srcarter@novell.com
+
+
+ D. Jensen
+ Novell
+ 1555 N. Technology Way
+ M/S ORM F111
+ Orem, UT 84097-2399
+
+ EMail: dcjensen@novell.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 85]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+23 Appendices
+
+23.1 Appendix 1 - WebDAV Document Type Definition
+
+ This section provides a document type definition, following the rules
+ in [REC-XML], for the XML elements used in the protocol stream and in
+ the values of properties. It collects the element definitions given
+ in sections 12 and 13.
+
+ <!DOCTYPE webdav-1.0 [
+
+ <!--============ XML Elements from Section 12 ==================-->
+
+ <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
+ locktoken?) >
+
+ <!ELEMENT lockentry (lockscope, locktype) >
+ <!ELEMENT lockinfo (lockscope, locktype, owner?) >
+
+ <!ELEMENT locktype (write) >
+ <!ELEMENT write EMPTY >
+
+ <!ELEMENT lockscope (exclusive | shared) >
+ <!ELEMENT exclusive EMPTY >
+ <!ELEMENT shared EMPTY >
+
+ <!ELEMENT depth (#PCDATA) >
+
+ <!ELEMENT owner ANY >
+
+ <!ELEMENT timeout (#PCDATA) >
+
+ <!ELEMENT locktoken (href+) >
+
+ <!ELEMENT href (#PCDATA) >
+
+ <!ELEMENT link (src+, dst+) >
+ <!ELEMENT dst (#PCDATA) >
+ <!ELEMENT src (#PCDATA) >
+
+ <!ELEMENT multistatus (response+, responsedescription?) >
+
+ <!ELEMENT response (href, ((href*, status)|(propstat+)),
+ responsedescription?) >
+ <!ELEMENT status (#PCDATA) >
+ <!ELEMENT propstat (prop, status, responsedescription?) >
+ <!ELEMENT responsedescription (#PCDATA) >
+
+
+
+
+Goland, et al. Standards Track [Page 86]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <!ELEMENT prop ANY >
+
+ <!ELEMENT propertybehavior (omit | keepalive) >
+ <!ELEMENT omit EMPTY >
+
+ <!ELEMENT keepalive (#PCDATA | href+) >
+
+ <!ELEMENT propertyupdate (remove | set)+ >
+ <!ELEMENT remove (prop) >
+ <!ELEMENT set (prop) >
+
+ <!ELEMENT propfind (allprop | propname | prop) >
+ <!ELEMENT allprop EMPTY >
+ <!ELEMENT propname EMPTY >
+
+ <!ELEMENT collection EMPTY >
+
+ <!--=========== Property Elements from Section 13 ===============-->
+ <!ELEMENT creationdate (#PCDATA) >
+ <!ELEMENT displayname (#PCDATA) >
+ <!ELEMENT getcontentlanguage (#PCDATA) >
+ <!ELEMENT getcontentlength (#PCDATA) >
+ <!ELEMENT getcontenttype (#PCDATA) >
+ <!ELEMENT getetag (#PCDATA) >
+ <!ELEMENT getlastmodified (#PCDATA) >
+ <!ELEMENT lockdiscovery (activelock)* >
+ <!ELEMENT resourcetype ANY >
+ <!ELEMENT source (link)* >
+ <!ELEMENT supportedlock (lockentry)* >
+ ]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 87]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+23.2 Appendix 2 - ISO 8601 Date and Time Profile
+
+ The creationdate property specifies the use of the ISO 8601 date
+ format [ISO-8601]. This section defines a profile of the ISO 8601
+ date format for use with this specification. This profile is quoted
+ from an Internet-Draft by Chris Newman, and is mentioned here to
+ properly attribute his work.
+
+ date-time = full-date "T" full-time
+
+ full-date = date-fullyear "-" date-month "-" date-mday
+ full-time = partial-time time-offset
+
+ date-fullyear = 4DIGIT
+ date-month = 2DIGIT ; 01-12
+ date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
+ month/year
+ time-hour = 2DIGIT ; 00-23
+ time-minute = 2DIGIT ; 00-59
+ time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules
+ time-secfrac = "." 1*DIGIT
+ time-numoffset = ("+" / "-") time-hour ":" time-minute
+ time-offset = "Z" / time-numoffset
+
+ partial-time = time-hour ":" time-minute ":" time-second
+ [time-secfrac]
+
+ Numeric offsets are calculated as local time minus UTC (Coordinated
+ Universal Time). So the equivalent time in UTC can be determined by
+ subtracting the offset from the local time. For example, 18:50:00-
+ 04:00 is the same time as 22:58:00Z.
+
+ If the time in UTC is known, but the offset to local time is unknown,
+ this can be represented with an offset of "-00:00". This differs
+ from an offset of "Z" which implies that UTC is the preferred
+ reference point for the specified time.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 88]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+23.3 Appendix 3 - Notes on Processing XML Elements
+
+23.3.1 Notes on Empty XML Elements
+
+ XML supports two mechanisms for indicating that an XML element does
+ not have any content. The first is to declare an XML element of the
+ form <A></A>. The second is to declare an XML element of the form
+ <A/>. The two XML elements are semantically identical.
+
+ It is a violation of the XML specification to use the <A></A> form if
+ the associated DTD declares the element to be EMPTY (e.g., <!ELEMENT
+ A EMPTY>). If such a statement is included, then the empty element
+ format, <A/> must be used. If the element is not declared to be
+ EMPTY, then either form <A></A> or <A/> may be used for empty
+ elements.
+
+ 23.3.2 Notes on Illegal XML Processing
+
+ XML is a flexible data format that makes it easy to submit data that
+ appears legal but in fact is not. The philosophy of "Be flexible in
+ what you accept and strict in what you send" still applies, but it
+ must not be applied inappropriately. XML is extremely flexible in
+ dealing with issues of white space, element ordering, inserting new
+ elements, etc. This flexibility does not require extension,
+ especially not in the area of the meaning of elements.
+
+ There is no kindness in accepting illegal combinations of XML
+ elements. At best it will cause an unwanted result and at worst it
+ can cause real damage.
+
+23.3.2.1 Example - XML Syntax Error
+
+ The following request body for a PROPFIND method is illegal.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ <D:propname/>
+ </D:propfind>
+
+ The definition of the propfind element only allows for the allprop or
+ the propname element, not both. Thus the above is an error and must
+ be responded to with a 400 (Bad Request).
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 89]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ Imagine, however, that a server wanted to be "kind" and decided to
+ pick the allprop element as the true element and respond to it. A
+ client running over a bandwidth limited line who intended to execute
+ a propname would be in for a big surprise if the server treated the
+ command as an allprop.
+
+ Additionally, if a server were lenient and decided to reply to this
+ request, the results would vary randomly from server to server, with
+ some servers executing the allprop directive, and others executing
+ the propname directive. This reduces interoperability rather than
+ increasing it.
+
+23.3.2.2 Example - Unknown XML Element
+
+ The previous example was illegal because it contained two elements
+ that were explicitly banned from appearing together in the propfind
+ element. However, XML is an extensible language, so one can imagine
+ new elements being defined for use with propfind. Below is the
+ request body of a PROPFIND and, like the previous example, must be
+ rejected with a 400 (Bad Request) by a server that does not
+ understand the expired-props element.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.foo.bar/standards/props/">
+ <E:expired-props/>
+ </D:propfind>
+
+ To understand why a 400 (Bad Request) is returned let us look at the
+ request body as the server unfamiliar with expired-props sees it.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.foo.bar/standards/props/">
+ </D:propfind>
+
+ As the server does not understand the expired-props element,
+ according to the WebDAV-specific XML processing rules specified in
+ section 14, it must ignore it. Thus the server sees an empty
+ propfind, which by the definition of the propfind element is illegal.
+
+ Please note that had the extension been additive it would not
+ necessarily have resulted in a 400 (Bad Request). For example,
+ imagine the following request body for a PROPFIND:
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.foo.bar/standards/props/">
+
+
+
+Goland, et al. Standards Track [Page 90]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ <D:propname/>
+ <E:leave-out>*boss*</E:leave-out>
+ </D:propfind>
+
+ The previous example contains the fictitious element leave-out. Its
+ purpose is to prevent the return of any property whose name matches
+ the submitted pattern. If the previous example were submitted to a
+ server unfamiliar with leave-out, the only result would be that the
+ leave-out element would be ignored and a propname would be executed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 91]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+23.4 Appendix 4 -- XML Namespaces for WebDAV
+
+23.4.1 Introduction
+
+ All DAV compliant systems MUST support the XML namespace extensions
+ as specified in [REC-XML-NAMES].
+
+23.4.2 Meaning of Qualified Names
+
+ [Note to the reader: This section does not appear in [REC-XML-NAMES],
+ but is necessary to avoid ambiguity for WebDAV XML processors.]
+
+ WebDAV compliant XML processors MUST interpret a qualified name as a
+ URI constructed by appending the LocalPart to the namespace name URI.
+
+ Example
+
+ <del:glider xmlns:del="http://www.del.jensen.org/">
+ <del:glidername>
+ Johnny Updraft
+ </del:glidername>
+ <del:glideraccidents/>
+ </del:glider>
+
+ In this example, the qualified element name "del:glider" is
+ interpreted as the URL "http://www.del.jensen.org/glider".
+
+ <bar:glider xmlns:del="http://www.del.jensen.org/">
+ <bar:glidername>
+ Johnny Updraft
+ </bar:glidername>
+ <bar:glideraccidents/>
+ </bar:glider>
+
+ Even though this example is syntactically different from the previous
+ example, it is semantically identical. Each instance of the
+ namespace name "bar" is replaced with "http://www.del.jensen.org/"
+ and then appended to the local name for each element tag. The
+ resulting tag names in this example are exactly the same as for the
+ previous example.
+
+ <foo:r xmlns:foo="http://www.del.jensen.org/glide">
+ <foo:rname>
+ Johnny Updraft
+ </foo:rname>
+ <foo:raccidents/>
+ </foo:r>
+
+
+
+
+Goland, et al. Standards Track [Page 92]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+ This example is semantically identical to the two previous ones.
+ Each instance of the namespace name "foo" is replaced with
+ "http://www.del.jensen.org/glide" which is then appended to the local
+ name for each element tag, the resulting tag names are identical to
+ those in the previous examples.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 93]
+\f
+RFC 2518 WEBDAV February 1999
+
+
+24. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 94]
+\f
projects / thirdparty / squid.git / commitdiff
