idnits 2.17.1 draft-ietf-webdav-rfc2518bis-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 6003. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 5980. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 5987. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 5993. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC2518, but the abstract doesn't seem to directly say this. It does mention RFC2518 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 569 has weird spacing: '... 489 The value of the property appears inside the property name element. 490 The value may be any kind of well-formed XML content, including both 491 text-only and mixed content. Servers MUST preserve the following XML 492 Information Items (using the terminology from [REC-XML-INFOSET]) in 493 storage and transmission of dead properties: 495 For the property name Element Information Item itself: 497 [namespace name] 499 [local name] 501 [attributes] named "xml:lang" or any such attribute in scope 503 [children] of type element or character 505 On all Element Information Items in the property value: 507 [namespace name] 509 [local name] 511 [attributes] 513 [children] of type element or character 515 On Attribute Information Items in the property value: 517 [namespace name] 519 [local name] 521 [normalized value] 523 On Character Information Items in the property value: 525 [character code] 527 Since prefixes are used in some XML vocabularies (XPath and XML 528 Schema, for example), servers SHOULD preserve, for any Information 529 Item in the value: 531 [prefix] 533 XML Infoset attributes not listed above MAY be preserved by the 534 server, but clients MUST NOT rely on them being preserved. The above 535 rules would also apply by default to live properties, unless defined 536 otherwise. 538 Servers MUST ignore the XML attribute xml:space if present and never 539 use it to change white space handling. White space in property 540 values is significant. 542 4.3.1. Example - Property with Mixed Content 544 Consider a dead property 'author' created by the client as follows: 546 547 548 Jane Doe 549 550 mailto:jane.doe@example.com 552 http://www.example.com 554 555 Jane has been working way too long on the 556 long-awaited revision of ]]>. 557 558 559 561 When this property is requested, a server might return: 563 568 Jane Doe 569 mailto:jane.doe@example.com 571 http://www.example.com 573 574 Jane has been working way too long on the 575 long-awaited revision of <RFC2518>. 576 577 578 580 Note in this example: 582 o The [prefix] for the property name itself was not preserved, being 583 non-significant, all other [prefix] values have been preserved, 585 o attribute values have been rewritten with double quotes instead of 586 single quotes (quoting style is not significant), and attribute 587 order has not been preserved, 589 o the xml:lang attribute has been returned on the property name 590 element itself (it was in scope when the property was set, but the 591 exact position in the response is not considered significant as 592 long as it is in scope), 594 o whitespace between tags has been preserved everywhere (whitespace 595 between attributes not so), 597 o CDATA encapsulation was replaced with character escaping (the 598 reverse would also be legal), 600 o the comment item was stripped (as would have been a processing 601 instruction item). 603 Implementation note: there are cases such as editing scenarios where 604 clients may require that XML content is preserved character-by- 605 character (such as attribute ordering or quoting style). In this 606 case, clients should consider using a text-only property value by 607 escaping all characters that have a special meaning in XML parsing. 609 4.4. Property Names 611 A property name is a universally unique identifier that is associated 612 with a schema that provides information about the syntax and 613 semantics of the property. 615 Because a property's name is universally unique, clients can depend 616 upon consistent behavior for a particular property across multiple 617 resources, on the same and across different servers, so long as that 618 property is "live" on the resources in question, and the 619 implementation of the live property is faithful to its definition. 621 The XML namespace mechanism, which is based on URIs ([RFC3986]), is 622 used to name properties because it prevents namespace collisions and 623 provides for varying degrees of administrative control. 625 The property namespace is flat; that is, no hierarchy of properties 626 is explicitly recognized. Thus, if a property A and a property A/B 627 exist on a resource, there is no recognition of any relationship 628 between the two properties. It is expected that a separate 629 specification will eventually be produced which will address issues 630 relating to hierarchical properties. 632 Finally, it is not possible to define the same property twice on a 633 single resource, as this would cause a collision in the resource's 634 property namespace. 636 4.5. Source Resources and Output Resources 638 Some HTTP resources are dynamically generated by the server. For 639 these resources, there presumably exists source code somewhere 640 governing how that resource is generated. The relationship of source 641 files to output HTTP resources may be one to one, one to many, many 642 to one or many to many. There is no mechanism in HTTP to determine 643 whether a resource is even dynamic, let alone where its source files 644 exist or how to author them. Although this problem would usefully be 645 solved, interoperable WebDAV implementations have been widely 646 deployed without actually solving this problem, by dealing only with 647 static resources. Thus, the source vs. output problem is not solved 648 in this specification and has been deferred to a separate document. 650 5. Collections of Web Resources 652 This section provides a description of a new type of Web resource, 653 the collection, and discusses its interactions with the HTTP URL 654 namespace. The purpose of a collection resource is to model 655 collection-like objects (e.g., file system directories) within a 656 server's namespace. 658 All DAV compliant resources MUST support the HTTP URL namespace model 659 specified herein. 661 5.1. HTTP URL Namespace Model 663 The HTTP URL namespace is a hierarchical namespace where the 664 hierarchy is delimited with the "/" character. 666 An HTTP URL namespace is said to be consistent if it meets the 667 following conditions: for every URL in the HTTP hierarchy there 668 exists a collection that contains that URL as an internal member. 669 The root, or top-level collection of the namespace under 670 consideration is exempt from the previous rule. The top-level 671 collection of the namespace under consideration is not necessarily 672 the collection identified by the absolute path '/', it may be 673 identified by one or more path segments (e.g. /servlets/webdav/...) 675 Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL 676 namespace be consistent -- a WebDAV-compatible resource may not have 677 a parent collection. However, certain WebDAV methods are prohibited 678 from producing results that cause namespace inconsistencies. 680 Although implicit in [RFC2616] and [RFC3986], any resource, including 681 collection resources, MAY be identified by more than one URI. For 682 example, a resource could be identified by multiple HTTP URLs. 684 5.2. Collection Resources 686 Collection resources differ from other resources in that they also 687 act as containers. A collection is a resource whose state consists 688 of at least a set of mappings between path segments and resources, 689 and a set of properties on the collection itself. A collection MAY 690 have additional state such as entity bodies returned by GET. 692 A collection MUST contain at most one mapping for a given path 693 segment, i.e., it is illegal to have the same path segment mapped to 694 more than one resource. Properties defined on collections behave 695 exactly as do properties on non-collection resources. 697 For all WebDAV compliant resources A and B, identified by URLs "U" 698 and "V" respectively, such that "V" is equal to "U/SEGMENT", A MUST 699 be a collection that contains a mapping from "SEGMENT" to B. So, if 700 resource B with URL "http://example.com/bar/blah" is WebDAV compliant 701 and if resource A with URL "http://example.com/bar/" is WebDAV 702 compliant, then resource A must be a collection and must contain at 703 least one mapping from "blah" to B. 705 Collection resources MAY have mappings to non-WebDAV compliant 706 resources in the HTTP URL namespace hierarchy but are not required to 707 do so. For example, if resource X with URL 708 "http://example.com/bar/blah" is not WebDAV compliant and resource A 709 with "URL http://example.com/bar/" identifies a WebDAV collection, 710 then A may or may not have a mapping from "blah" to X. 712 If a WebDAV compliant resource has no WebDAV compliant children in 713 the HTTP URL namespace hierarchy then the WebDAV compliant resource 714 is not required to be a collection. 716 There is a standing convention that when a collection is referred to 717 by its name without a trailing slash, the server MAY handle the 718 request as if the trailing slash were present. In this case it 719 SHOULD return a Content-Location header in the response, pointing to 720 the URL ending with the "/". For example, if a client invokes a 721 method on http://example.com/blah (no trailing slash), the server may 722 respond as if the operation were invoked on http://example.com/blah/ 723 (trailing slash), and should return a Content-Location header with 724 the value http://example.com/blah/. Wherever a server produces a URL 725 referring to a collection, the server SHOULD include the trailing 726 slash. In general clients SHOULD use the trailing slash form of 727 collection names. If clients do not use the trailing slash form the 728 client needs to be prepared to see a redirect response. Clients will 729 find the DAV:resourcetype property more reliable than the URL to find 730 out if a resource is a collection. 732 Clients MUST be able to support the case where WebDAV resources are 733 contained inside non-WebDAV resources. For example, if a OPTIONS 734 response from "http://example.com/servlet/dav/collection" indicates 735 WebDAV support, the client cannot assume that 736 "http://example.com/servlet/dav/" or its parent necessarily are 737 WebDAV collections. 739 A typical scenario in which mapped URLs do not appear as members of 740 their parent collection is the case where a server allows links or 741 redirects to non-WebDAV resources. For instance, "/col/link" might 742 not appear as a member of "/col/", although the server would respond 743 with a 302 status to a GET request to "/col/link", thus the URL 744 "/col/link" would indeed be mapped. Similarly, a dynamically- 745 generated page might have a URL mapping from "/col/index.html", thus 746 this resource might respond with a 200 OK to a GET request yet not 747 appear as a member of "/col/". 749 Some mappings to even WebDAV-compliant resources might not appear in 750 the parent collection. An example for this case are servers that 751 support multiple alias URLs for each WebDAV compliant resource. A 752 server may implement case-insensitive URLs, thus "/col/a" and 753 "/col/A" identify the same resource, yet only either "a" or "A" are 754 reported upon listing the members of "/col". 756 6. Locking 758 The ability to lock a resource provides a mechanism for serializing 759 access to that resource. Using a lock, an authoring client can 760 provide a reasonable guarantee that another principal will not modify 761 a resource while it is being edited. In this way, a client can 762 prevent the "lost update" problem. 764 This specification allows locks to vary over two client-specified 765 parameters, the number of principals involved (exclusive vs. shared) 766 and the type of access to be granted. This document defines locking 767 for only one access type, write. However, the syntax is extensible, 768 and permits the eventual specification of locking for other access 769 types. 771 6.1. Lock Model 773 This section provides a concise model for how locking behaves. Later 774 sections will provide more detail on some of the concepts and refer 775 back to these model statements. Normative statements related to LOCK 776 and UNLOCK handling can be found in the sections on those methods, 777 whereas normative statements that cover any method are gathered here. 779 1. A lock either directly or indirectly locks a resource. 781 2. A resource becomes directly locked when a LOCK request to the URL 782 of that resource creates a new lock. The "lock-root" of the new 783 lock is that URL. If at the time of the request, the URL is not 784 mapped to a resource, a new empty resource is created and 785 directly locked. 787 3. An exclusive lock (Section 6.2) conflicts with any other kind of 788 lock on the same resource, whether either lock is direct or 789 indirect. A server MUST NOT create conflicting locks on a 790 resource. 792 4. For a collection that is locked with an infinite depth lock L, 793 all member resources are indirectly locked. Changes in 794 membership of a such a collection affect the set of indirectly 795 locked resources: 797 * If an internal member resource is added to the collection, and 798 if the new member resource does not already have a conflicting 799 lock, then the resource MUST become indirectly locked by L. 801 * If an internal member resource stops being a member of the 802 collection, then the resource MUST no longer be indirectly 803 locked by L. 805 5. Each lock is identified by a single unique lock token 806 (Section 6.5). 808 6. An UNLOCK request deletes the lock with the specified lock token. 809 After a lock is deleted, no resource is locked by that lock. 811 7. A lock token is "submitted" in a request when it appears in an If 812 header (the Write Lock (Section 7) section discusses when token 813 submission is required for write locks). 815 8. If a request causes the lock-root of any lock to become an 816 unmapped URL, then the lock MUST also be deleted by that request. 818 6.2. Exclusive Vs. Shared Locks 820 The most basic form of lock is an exclusive lock. Exclusive locks 821 avoid having to deal with content change conflicts, without requiring 822 any coordination other than the methods described in this 823 specification. 825 However, there are times when the goal of a lock is not to exclude 826 others from exercising an access right but rather to provide a 827 mechanism for principals to indicate that they intend to exercise 828 their access rights. Shared locks are provided for this case. A 829 shared lock allows multiple principals to receive a lock. Hence any 830 principal with appropriate access can use the lock. 832 With shared locks there are two trust sets that affect a resource. 833 The first trust set is created by access permissions. Principals who 834 are trusted, for example, may have permission to write to the 835 resource. Among those who have access permission to write to the 836 resource, the set of principals who have taken out a shared lock also 837 must trust each other, creating a (typically) smaller trust set 838 within the access permission write set. 840 Starting with every possible principal on the Internet, in most 841 situations the vast majority of these principals will not have write 842 access to a given resource. Of the small number who do have write 843 access, some principals may decide to guarantee their edits are free 844 from overwrite conflicts by using exclusive write locks. Others may 845 decide they trust their collaborators will not overwrite their work 846 (the potential set of collaborators being the set of principals who 847 have write permission) and use a shared lock, which informs their 848 collaborators that a principal may be working on the resource. 850 The WebDAV extensions to HTTP do not need to provide all of the 851 communications paths necessary for principals to coordinate their 852 activities. When using shared locks, principals may use any out of 853 band communication channel to coordinate their work (e.g., face-to- 854 face interaction, written notes, post-it notes on the screen, 855 telephone conversation, Email, etc.) The intent of a shared lock is 856 to let collaborators know who else may be working on a resource. 858 Shared locks are included because experience from web distributed 859 authoring systems has indicated that exclusive locks are often too 860 rigid. An exclusive lock is used to enforce a particular editing 861 process: take out an exclusive lock, read the resource, perform 862 edits, write the resource, release the lock. This editing process 863 has the problem that locks are not always properly released, for 864 example when a program crashes, or when a lock creator leaves without 865 unlocking a resource. While both timeouts (Section 6.6) and 866 administrative action can be used to remove an offending lock, 867 neither mechanism may be available when needed; the timeout may be 868 long or the administrator may not be available. 870 A successful request for a new shared lock MUST result in the 871 generation of a unique lock associated with the requesting principal. 872 Thus if five principals have taken out shared write locks on the same 873 resource there will be five locks and five lock tokens, one for each 874 principal. 876 6.3. Required Support 878 A WebDAV compliant resource is not required to support locking in any 879 form. If the resource does support locking it may choose to support 880 any combination of exclusive and shared locks for any access types. 882 The reason for this flexibility is that locking policy strikes to the 883 very heart of the resource management and versioning systems employed 884 by various storage repositories. These repositories require control 885 over what sort of locking will be made available. For example, some 886 repositories only support shared write locks while others only 887 provide support for exclusive write locks while yet others use no 888 locking at all. As each system is sufficiently different to merit 889 exclusion of certain locking features, this specification leaves 890 locking as the sole axis of negotiation within WebDAV. 892 6.4. Lock Creator and Privileges 894 The creator of a lock has special privileges to use the locked 895 resource. When a locked resource is modified, a server MUST check 896 that the authenticated principal matches the lock creator (in 897 addition to checking for valid lock token submission). For multi- 898 user shared lock cases, each authenticated principal MUST obtain its 899 own shared lock. 901 The server MAY allow privileged users other than the lock creator to 902 destroy a lock (for example, the resource owner or an administrator). 903 The 'unlock' privilege in [RFC3744] was defined to provide that 904 permission. 906 There is no requirement for servers to accept LOCK requests from all 907 users or from anonymous users. 909 Note that having a lock does not confer full privilege to modify the 910 locked resource. Write access and other privileges MUST be enforced 911 through normal privilege or authentication mechanisms, not based on 912 the possible obscurity of lock token values. 914 6.5. Lock Tokens 916 A lock token is a type of state token which identifies a particular 917 lock. Each lock has exactly one unique lock token generated by the 918 server. Clients MUST NOT attempt to interpret lock tokens in any 919 way. 921 Lock token URIs MUST be unique across all resources for all time. 922 This uniqueness constraint allows lock tokens to be submitted across 923 resources and servers without fear of confusion. Since lock tokens 924 are unique, a client MAY submit a lock token in an If header on a 925 resource other than the one that returned it. 927 When a LOCK operation creates a new lock, the new lock token is 928 returned in the Lock-Token response header defined in Section 10.5, 929 and also in the body of the response. 931 Servers MAY make lock tokens publicly readable (e.g. in the DAV: 932 lockdiscovery property). One use case for making lock tokens 933 readable is so that a long-lived lock can be removed by the resource 934 owner (the client that obtained the lock might have crashed or 935 disconnected before cleaning up the lock). Except for the case of 936 using UNLOCK under user guidance, a client SHOULD NOT use a lock 937 tokens created by another client instance. 939 This specification encourages servers to create UUIDs for lock 940 tokens, and to use the URI form defined by "A Universally Unique 941 Identifier (UUID) URN Namespace" ([RFC4122]). However servers are 942 free to use any URI (e.g. from another scheme) so long as it meets 943 the uniqueness requirements. For example, a valid lock token might 944 be constructed using the "opaquelocktoken" scheme defined in 945 Appendix C. 947 Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" 949 6.6. Lock Timeout 951 A lock MAY have a limited lifetime. The lifetime is suggested by the 952 client when creating or refreshing the lock, but the server 953 ultimately chooses the timeout value. Timeout is measured in seconds 954 remaining until lock expiration. 956 The timeout counter MUST be restarted if a refresh lock request is 957 successful (see Section 9.10.2). The timeout counter SHOULD NOT be 958 restarted at any other time. 960 If the timeout expires then the lock SHOULD be removed. In this case 961 the server SHOULD act as if an UNLOCK method was executed by the 962 server on the resource using the lock token of the timed-out lock, 963 performed with its override authority. Thus logs should be updated 964 with the disposition of the lock, notifications should be sent, etc., 965 just as they would be for an UNLOCK request. 967 Servers are advised to pay close attention to the values submitted by 968 clients, as they will be indicative of the type of activity the 969 client intends to perform. For example, an applet running in a 970 browser may need to lock a resource, but because of the instability 971 of the environment within which the applet is running, the applet may 972 be turned off without warning. As a result, the applet is likely to 973 ask for a relatively small timeout value so that if the applet dies, 974 the lock can be quickly harvested. However, a document management 975 system is likely to ask for an extremely long timeout because its 976 user may be planning on going off-line. 978 A client MUST NOT assume that just because the time-out has expired 979 the lock has immediately been cleaned up. 981 Likewise, a client MUST NOT assume that just because the time-out has 982 not expired, the lock still exists. Clients MUST assume that locks 983 can arbitrarily disappear at any time, regardless of the value given 984 in the Timeout header. The Timeout header only indicates the 985 behavior of the server if extraordinary circumstances do not occur. 986 For example, a sufficiently privileged user may remove a lock at any 987 time or the system may crash in such a way that it loses the record 988 of the lock's existence. 990 6.7. Lock Capability Discovery 992 Since server lock support is optional, a client trying to lock a 993 resource on a server can either try the lock and hope for the best, 994 or perform some form of discovery to determine what lock capabilities 995 the server supports. This is known as lock capability discovery. A 996 client can determine what lock types the server supports by 997 retrieving the DAV:supportedlock property. 999 Any DAV compliant resource that supports the LOCK method MUST support 1000 the DAV:supportedlock property. 1002 6.8. Active Lock Discovery 1004 If another principal locks a resource that a principal wishes to 1005 access, it is useful for the second principal to be able to find out 1006 who the first principal is. For this purpose the DAV:lockdiscovery 1007 property is provided. This property lists all outstanding locks, 1008 describes their type, and MAY even provide the lock tokens. 1010 Any DAV compliant resource that supports the LOCK method MUST support 1011 the DAV:lockdiscovery property. 1013 6.9. Locks and Multiple Bindings 1015 A resource may be made available through more than one URI. A lock 1016 MUST cover the resource as well as the URI to which the LOCK request 1017 was addressed. The lock MAY cover other URIs mapped to the same 1018 resource as well. 1020 7. Write Lock 1022 This section describes the semantics specific to the write lock type. 1023 The write lock is a specific instance of a lock type, and is the only 1024 lock type described in this specification. 1026 An exclusive write lock will prevent parallel changes to a resource 1027 by any principal other than the lock creator and in any case where 1028 the lock token is not submitted (e.g. by a client process other than 1029 the one holding the lock). 1031 Clients MUST submit a lock-token they are authorized to use in any 1032 request which modifies a write-locked resource. The list of 1033 modifications covered by a write-lock include: 1035 1. A change to any of the following aspects of any write-locked 1036 resource: 1038 * any variant, 1040 * any dead property, 1042 * any live property which is lockable (a live property is 1043 lockable unless otherwise defined.) 1045 2. For collections, any modification of an internal member URI. An 1046 internal member URI of a collection is considered to be modified 1047 if it is added, removed, or identifies a different resource. 1048 More discussion on write locks and collections is found in 1049 Section 7.4. 1051 3. A modification of the mapping of the root of the write lock, 1052 either to another resource or to no resource (e.g. DELETE). 1054 Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH, 1055 LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and 1056 MKCOL are affected by write locks. All other HTTP/WebDAV methods 1057 defined so far, GET in particular, function independently of a write 1058 lock. 1060 The next few sections describe in more specific terms how write locks 1061 interact with various operations. 1063 7.1. Write Locks and Properties 1065 While those without a write lock may not alter a property on a 1066 resource it is still possible for the values of live properties to 1067 change, even while locked, due to the requirements of their schemas. 1069 Only dead properties and live properties defined to respect locks are 1070 guaranteed not to change while write locked. 1072 7.2. Avoiding Lost Updates 1074 Although the write locks provide some help in preventing lost 1075 updates, they cannot guarantee that updates will never be lost. 1076 Consider the following scenario: 1078 Two clients A and B are interested in editing the resource 1079 'index.html'. Client A is an HTTP client rather than a WebDAV 1080 client, and so does not know how to perform locking. 1082 Client A doesn't lock the document, but does a GET and begins 1083 editing. 1085 Client B does LOCK, performs a GET and begins editing. 1087 Client B finishes editing, performs a PUT, then an UNLOCK. 1089 Client A performs a PUT, overwriting and losing all of B's changes. 1091 There are several reasons why the WebDAV protocol itself cannot 1092 prevent this situation. First, it cannot force all clients to use 1093 locking because it must be compatible with HTTP clients that do not 1094 comprehend locking. Second, it cannot require servers to support 1095 locking because of the variety of repository implementations, some of 1096 which rely on reservations and merging rather than on locking. 1097 Finally, being stateless, it cannot enforce a sequence of operations 1098 like LOCK / GET / PUT / UNLOCK. 1100 WebDAV servers that support locking can reduce the likelihood that 1101 clients will accidentally overwrite each other's changes by requiring 1102 clients to lock resources before modifying them. Such servers would 1103 effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying 1104 resources. 1106 WebDAV clients can be good citizens by using a lock / retrieve / 1107 write /unlock sequence of operations (at least by default) whenever 1108 they interact with a WebDAV server that supports locking. 1110 HTTP 1.1 clients can be good citizens, avoiding overwriting other 1111 clients' changes, by using entity tags in If-Match headers with any 1112 requests that would modify resources. 1114 Information managers may attempt to prevent overwrites by 1115 implementing client-side procedures requiring locking before 1116 modifying WebDAV resources. 1118 7.3. Write Locks and Unmapped URLs 1120 WebDAV provides the ability to lock an unmapped URL in order to 1121 reserve the name for use. This is a simple way to avoid the lost- 1122 update problem on the creation of a new resource (another way is to 1123 use If-None-Match header specified in HTTP 1.1). It has the side 1124 benefit of locking the new resource immediately for use of the 1125 creator. 1127 Note that the lost-update problem is not an issue for collections 1128 because MKCOL can only be used to create a collection, not to 1129 overwrite an existing collection. When trying to lock a collection 1130 upon creation, clients may attempt to increase the likelihood of 1131 getting the lock by pipelining the MKCOL and LOCK requests together 1132 (but because this doesn't convert two separate operations into one 1133 atomic operation there's no guarantee this will work). 1135 A successful lock request to an unmapped URL MUST result in the 1136 creation of an locked resource with empty content. Subsequently, a 1137 successful PUT request (with the correct lock token) provides the 1138 content for the resource. Note that the LOCK request has no 1139 mechanism for the client to provide Content-Type or Content-Language, 1140 thus the server will use defaults or empty values and rely on the 1141 subsequent PUT request for correct values. 1143 The original WebDAV model for locking unmapped URLs created "lock- 1144 null resources". This model was over-complicated and some 1145 interoperability and implementation problems were discovered. The 1146 new WebDAV model for locking unmapped URLs creates "locked empty 1147 resources". Servers MUST implement either lock-null resources or 1148 locked empty resources, but servers SHOULD implement locked empty 1149 resources. This section discusses the original model briefly and the 1150 new model more completely, because clients MUST be able to handle 1151 either model. 1153 In the original "lock-null resource" model, which is no longer 1154 recommended for implementation: 1156 o A lock-null resource sometimes appeared as "Not Found". The 1157 server responds with a 404 or 405 to any method except for PUT, 1158 MKCOL, OPTIONS, PROPFIND, LOCK, UNLOCK. 1160 o A lock-null resource does however show up as a member of its 1161 parent collection. 1163 o The server removes the lock-null resource entirely (its URI 1164 becomes unmapped) if its lock goes away before it is converted to 1165 a regular resource. Recall that locks go away not only when they 1166 expire or are unlcoked, but are also removed if a resource is 1167 renamed or moved, or if any parent collection is renamed or moved. 1169 o The server converts the lock-null resource into a regular resource 1170 if a PUT request to the URL is successful. 1172 o The server converts the lock-null resource into a collection if a 1173 MKCOL request to the URL is successful (though interoperability 1174 experience showed that not all servers followed this requirement). 1176 o Property values were defined for DAV:lockdiscovery and DAV: 1177 supportedlock properties but not necessarily for other properties 1178 like DAV:getcontenttype. 1180 In the "locked empty resource" model, which is now the recommended 1181 implementation, a resource created with a LOCK is empty but otherwise 1182 behaves in every way as a normal resource. It behaves the same way 1183 as a resource created by a PUT request with an empty body (and where 1184 a Content-Type and Content-Language was not specified), followed by a 1185 LOCK request to the same resource. Following from this model, a 1186 locked empty resource: 1188 o Can be read, deleted, moved, copied, and in all ways behave as a 1189 regular resource, not a lock-null resource. 1191 o Appears as a member of its parent collection. 1193 o SHOULD NOT disappear when its lock goes away (clients must 1194 therefore be responsible for cleaning up their own mess, as with 1195 any other operation or any non-empty resource) 1197 o MAY NOT have values for properties like DAV:getcontentlanguage 1198 which haven't been specified yet by the client. 1200 o Can be updated (have content added) with a PUT request. 1202 o MUST NOT be converted into a collection. The server MUST fail a 1203 MKCOL request (as it would with a MKCOL request to any existing 1204 non-collection resource). 1206 o MUST have defined values for DAV:lockdiscovery and DAV: 1207 supportedlock properties. 1209 o The response MUST indicate that a resource was created, by use of 1210 the "201 Created" response code (a LOCK request to an existing 1211 resource instead will result in 200 OK). The body must still 1212 include the DAV:lockdiscovery property, as with a LOCK request to 1213 an existing resource. 1215 The client is expected to update the locked empty resource shortly 1216 after locking it, using PUT and possibly PROPPATCH. 1218 Clients can easily interoperate both with servers that support the 1219 old model "lock-null resources" and the recommended model of "locked 1220 empty resources" by only attempting PUT after a LOCK to an unmapped 1221 URL, not MKCOL or GET. 1223 7.4. Write Locks and Collections 1225 There are two kinds of collection write locks. A "Depth 0" write 1226 lock on a collection protects the collection metadata plus the 1227 internal member URLs of that collection, while not protecting the 1228 content or metadata of child resources. A "Depth: infinity" write 1229 lock on a collection provides the same protection on that collection 1230 and also protects every descendent resource as if that resource were 1231 itself write locked. 1233 Expressed otherwise, a write lock protects any request that would 1234 create a new resource in a write locked collection, any request that 1235 would remove an internal member URL of a write locked collection, and 1236 any request that would change the binding name of a member URL. 1238 Thus, a collection write lock protects all the following actions: 1240 o DELETE a collection's direct internal member, 1242 o MOVE a member out of the collection, 1244 o MOVE a member into the collection, 1246 o MOVE to rename a member within a collection, 1248 o COPY a member into a collection, and 1250 o PUT or MKCOL request which would create a new member. 1252 The collection's lock token is required in addition to the lock token 1253 on the internal member itself, if it is locked separately. 1255 In addition, a depth-infinity lock affects all write operations to 1256 all descendents of the locked collection. With a depth-infinity 1257 lock, the root of the lock is directly locked, and all its 1258 descendants are indirectly locked. 1260 o Any new resource added as a descendent of a depth-infinity locked 1261 collection becomes indirectly locked. 1263 o Any indirectly locked resource moved out of the locked collection 1264 into an unlocked collection is thereafter unlocked. 1266 o Any indirectly locked resource moved out of a locked source 1267 collection into a depth-infinity locked target collection remains 1268 indirectly locked but is now within the scope of the lock on the 1269 target collection (the target collection's lock token will 1270 thereafter be required to make further changes). 1272 If a depth-infinity write LOCK request is issued to a collection 1273 containing member URLs identifying resources that are currently 1274 locked in a manner which conflicts with the new lock (see Section 6.1 1275 point 3), the request MUST fail with a 423 (Locked) status code, and 1276 the response SHOULD contain the 'no-conflicting-lock' precondition. 1278 If a lock request causes the URL of a resource to be added as an 1279 internal member URL of a depth-infinity locked collection then the 1280 new resource MUST be automatically added to the lock. This is the 1281 only mechanism that allows a resource to be added to a write lock. 1282 Thus, for example, if the collection /a/b/ is write locked and the 1283 resource /c is moved to /a/b/c then resource /a/b/c will be added to 1284 the write lock. 1286 7.5. Write Locks and the If Request Header 1288 If a user agent is not required to have knowledge about a lock when 1289 requesting an operation on a locked resource, the following scenario 1290 might occur. Program A, run by User A, takes out a write lock on a 1291 resource. Program B, also run by User A, has no knowledge of the 1292 lock taken out by Program A, yet performs a PUT to the locked 1293 resource. In this scenario, the PUT succeeds because locks are 1294 associated with a principal, not a program, and thus program B, 1295 because it is acting with principal A's credential, is allowed to 1296 perform the PUT. However, had program B known about the lock, it 1297 would not have overwritten the resource, preferring instead to 1298 present a dialog box describing the conflict to the user. Due to 1299 this scenario, a mechanism is needed to prevent different programs 1300 from accidentally ignoring locks taken out by other programs with the 1301 same authorization. 1303 In order to prevent these collisions a lock token MUST be submitted 1304 by an authorized principal for all locked resources that a method may 1305 change or the method MUST fail. A lock token is submitted when it 1306 appears in an If header. For example, if a resource is to be moved 1307 and both the source and destination are locked then two lock tokens 1308 must be submitted in the if header, one for the source and the other 1309 for the destination. 1311 7.5.1. Example - Write Lock and COPY 1313 >>Request 1315 COPY /~fielding/index.html HTTP/1.1 1316 Host: www.example.com 1317 Destination: http://www.example.com/users/f/fielding/index.html 1318 If: 1319 () 1321 >>Response 1323 HTTP/1.1 204 No Content 1325 In this example, even though both the source and destination are 1326 locked, only one lock token must be submitted, for the lock on the 1327 destination. This is because the source resource is not modified by 1328 a COPY, and hence unaffected by the write lock. In this example, 1329 user agent authentication has previously occurred via a mechanism 1330 outside the scope of the HTTP protocol, in the underlying transport 1331 layer. 1333 7.5.2. Example - Deleting a member of a locked collection 1335 Consider a collection "/locked" exclusively write-locked with Depth: 1336 Infinity, and an attempt to delete an internal member "/locked/ 1337 member": 1339 >>Request 1341 DELETE /locked/member HTTP/1.1 1342 Host: example.com 1344 >>Response 1346 HTTP/1.1 423 Locked 1347 Content-Type: application/xml; charset="utf-8" 1348 Content-Length: xxxx 1350 1351 1352 1353 /locked/ 1354 1355 1357 Thus the client would need to submit the lock token with the request 1358 to make it succeed. To do that, various forms of the If header (see 1359 Section 10.4) could be used. 1361 "No-Tag-List" format: 1363 If: () 1365 "Tagged-List" format, for "http://example.com/locked/": 1367 If: 1368 () 1370 "Tagged-List" format, for "http://example.com/locked/member": 1372 If: 1373 () 1375 Note that for the purpose of submitting the lock token the actual 1376 form doesn't matter; what's relevant is that the lock token appears 1377 in the If header, and that the If header itself evaluates to true. 1379 7.6. Write Locks and COPY/MOVE 1381 A COPY method invocation MUST NOT duplicate any write locks active on 1382 the source. However, as previously noted, if the COPY copies the 1383 resource into a collection that is locked with "Depth: infinity", 1384 then the resource will be added to the lock. 1386 A successful MOVE request on a write locked resource MUST NOT move 1387 the write lock with the resource. However, if there is an existing 1388 lock at the destination, the server MUST add the moved resource to 1389 the destination lock scope. For example, if the MOVE makes the 1390 resource a child of a collection that is locked with "Depth: 1391 infinity", then the resource will be added to that collection's lock. 1392 Additionally, if a resource locked with "Depth: infinity" is moved to 1393 a destination that is within the scope of the same lock (e.g., within 1394 the URL namespace tree covered by the lock), the moved resource will 1395 again be a added to the lock. In both these examples, as specified 1396 in Section 7.5, an If header must be submitted containing a lock 1397 token for both the source and destination. 1399 7.7. Refreshing Write Locks 1401 A client MUST NOT submit the same write lock request twice. Note 1402 that a client is always aware it is resubmitting the same lock 1403 request because it must include the lock token in the If header in 1404 order to make the request for a resource that is already locked. 1406 However, a client may submit a LOCK method with an If header but 1407 without a body. This form of LOCK MUST only be used to "refresh" a 1408 lock. Meaning, at minimum, that any timers associated with the lock 1409 MUST be re-set. 1411 Clients may submit Timeout headers of arbitrary value with their lock 1412 refresh requests. Servers, as always, may ignore Timeout headers 1413 submitted by the client, and a server MAY refresh a lock with a 1414 timeout period that is different than the previous timeout period 1415 used for the lock, provided it advertises the new value in the LOCK 1416 refresh response. 1418 If an error is received in response to a refresh LOCK request the 1419 client MUST NOT assume that the lock was refreshed. 1421 8. General Request and Response Handling 1423 8.1. Precedence in Error Handling 1425 Servers MUST return authorization errors in preference to other 1426 errors. This avoids leaking information about protected resources 1427 (e.g. a client that finds that a hidden resource exists by seeing a 1428 423 Locked response to an anonymous request to the resource). 1430 8.2. Use of XML 1432 In HTTP/1.1, method parameter information was exclusively encoded in 1433 HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter 1434 information either in an XML ([REC-XML]) request entity body, or in 1435 an HTTP header. The use of XML to encode method parameters was 1436 motivated by the ability to add extra XML elements to existing 1437 structures, providing extensibility; and by XML's ability to encode 1438 information in ISO 10646 character sets, providing 1439 internationalization support. 1441 In addition to encoding method parameters, XML is used in WebDAV to 1442 encode the responses from methods, providing the extensibility and 1443 internationalization advantages of XML for method output, as well as 1444 input. 1446 When XML is used for a request or response body, the Content-Type 1447 type SHOULD be application/xml. Implementations MUST accept both 1448 text/xml and application/xml in request and response bodies. Use of 1449 text/xml is deprecated. 1451 All DAV compliant clients and resources MUST use XML parsers that are 1452 compliant with [REC-XML] and [REC-XML-NAMES]. All XML used in either 1453 requests or responses MUST be, at minimum, well formed and use 1454 namespaces correctly. If a server receives XML that is not well- 1455 formed then the server MUST reject the entire request with a 400 (Bad 1456 Request). If a client receives XML that is not well-formed in a 1457 response then the client MUST NOT assume anything about the outcome 1458 of the executed method and SHOULD treat the server as malfunctioning. 1460 Note that processing XML submitted by an untrusted source may cause 1461 risks connected to privacy, security, and service quality (see 1462 Section 20). Servers MAY reject questionable requests (even though 1463 they consist of well-formed XML), for instance with a 400 (Bad 1464 Request) status code and an optional response body explaining the 1465 problem. 1467 8.3. URL Handling 1469 URLs appear in many places in requests and responses. 1470 Interoperability experience with [RFC2518] showed that many clients 1471 parsing Multi-Status responses did not fully implement the full 1472 Reference Resolution defined in Section 5 of [RFC3986]. Thus, 1473 servers in particular need to be careful in handling URLs in 1474 responses, to ensure that clients have enough context to be able to 1475 interpret all the URLs. The rules in this section apply not only to 1476 resource URLs in the 'href' element in Multi-Status responses, but 1477 also to the Destination and If header resource URLs. 1479 The sender has a choice between two approaches: using a relative 1480 reference, which is resolved against the Request-URI, or a full URI. 1481 A server MUST ensure that every 'href' value within a Multi-Status 1482 response uses the same format. 1484 WebDAV only uses one form of relative reference in its extensions, 1485 the absolute path. 1487 Simple-ref = absolute-URI | ( path-absolute [ "?" query ] ) 1489 The absolute-URI, path-absolute and query productions are defined in 1490 section 4.3, 3.3 and 3.4 of [RFC3986]. 1492 Within Simple-ref productions, senders MUST NOT: 1494 o use dot-segments ("." or ".."), or 1496 o have prefixes that do not match the Request-URI (using the 1497 comparison rules defined in Section 3.2.3 of [RFC2616]). 1499 Identifiers for collections SHOULD end in a '/' character. 1501 8.3.1. Example - Correct URL Handling 1503 Consider the collection http://example.com/sample/ with the internal 1504 member URL http://example.com/sample/a%20test and the PROPFIND 1505 request below: 1507 >>Request: 1509 PROPFIND /sample/ HTTP/1.1 1510 Host: example.com 1511 Depth: 1 1513 In this case, the server should return two 'href' elements containing 1514 either 1515 o 'http://example.com/sample/' and 1516 'http://example.com/sample/a%20test', or 1518 o '/sample/' and '/sample/a%20test' 1520 Note that even though the server may be storing the member resource 1521 internally as 'a test', it has to be percent-encoded when used inside 1522 a URI reference (see Section 2.1 of [RFC3986]). Also note that a 1523 legal URI may still contain characters that need to be escaped within 1524 XML character data, such as the ampersand character. 1526 8.4. Required Bodies in Requests 1528 Some of these new methods do not define bodies. Servers MUST examine 1529 all requests for a body, even when a body was not expected. In cases 1530 where a request body is present but would be ignored by a server, the 1531 server MUST reject the request with 415 (Unsupported Media Type). 1532 This informs the client (which may have been attempting to use an 1533 extension) that the body could not be processed as they intended. 1535 8.5. HTTP Headers for use in WebDAV 1537 HTTP defines many headers that can be used in WebDAV requests and 1538 responses. Not all of these are appropriate in all situations and 1539 some interactions may be undefined. Note that HTTP 1.1 requires the 1540 Date header in all responses if possible (see section 14.18, 1541 [RFC2616]). 1543 The server MUST do authorization checks before checking any HTTP 1544 conditional header. 1546 8.6. ETag 1548 HTTP 1.1 recommends the use of ETags rather than modification dates, 1549 for cache-control, and there are even stronger reasons to prefer 1550 ETags for authoring. Correct use of ETags is even more important in 1551 a distributed authoring environment, because ETags are necessary 1552 along with locks to avoid the lost-update problem. A client might 1553 fail to renew a lock, for example when the lock times out and the 1554 client is accidentally offline or in the middle of a long upload. 1555 When a client fails to renew the lock, it's quite possible the 1556 resource can still be relocked and the user can go on editing, as 1557 long as no changes were made in the meantime. ETags are required for 1558 the client to be able to distinguish this case. Otherwise, the 1559 client is forced to ask the user whether to overwrite the resource on 1560 the server without even being able to tell the user whether it has 1561 changed. Timestamps do not solve this problem nearly as well as 1562 ETags. 1564 Strong ETags are much more useful for authoring use cases than weak 1565 ETags. Semantic equivalence can be a useful concept but that depends 1566 on the document type and the application type, and interoperability 1567 might require some agreement or standard outside the scope of this 1568 specification and HTTP. Note also that weak ETags have certain 1569 restrictions in HTTP, e.g. these cannot be used in If-Match headers. 1571 Note that the meaning of an ETag in a PUT response is not clearly 1572 defined either in this document or in RFC2616 (i.e., whether the ETag 1573 means that the resource is octet-for-octet equivalent to the body of 1574 the PUT request, or whether the server could have made minor changes 1575 in the formatting or content of the document upon storage). This is 1576 an HTTP issue, not purely a WebDAV issue, and is being addressed in 1577 [I-D.draft-whitehead-http-etag]. 1579 Because clients may be forced to prompt users or throw away changed 1580 content if the ETag changes, a WebDAV server SHOULD NOT change the 1581 ETag (or the Last-Modified time) for a resource that has an unchanged 1582 body and location. The ETag represents the state of the body or 1583 contents of the resource. There is no similar way to tell if 1584 properties have changed. 1586 8.7. Including error response bodies 1588 HTTP and WebDAV did not use the bodies of most error responses for 1589 machine-parsable information until DeltaV introduced a mechanism to 1590 include more specific information in the body of an error response 1591 (section 1.6 of [RFC3253]). The error body mechanism is appropriate 1592 to use with any error response that may take a body but does not 1593 already have a body defined. The mechanism is particularly 1594 appropriate when a status code can mean many things (for example, 400 1595 Bad Request can mean required headers are missing, headers are 1596 incorrectly formatted, or much more). This error body mechanism is 1597 covered in Section 16 1599 8.8. Impact of Namespace Operations on Cache Validators 1601 Note that the HTTP response headers "Etag" and "Last-Modified" (see 1602 [RFC2616], Sections 14.19 and 14.29) are defined per URL (not per 1603 resource), and are used by clients for caching. Therefore servers 1604 must ensure that executing any operation that affects the URL 1605 namespace (such as COPY, MOVE, DELETE, PUT or MKCOL) does preserve 1606 their semantics, in particular: 1608 o For any given URL, the "Last-Modified" value MUST increment every 1609 time the representation returned upon GET changes (within the 1610 limits of timestamp resolution). 1612 o For any given URL, an "ETag" value MUST NOT be re-used for 1613 different representations returned by GET. 1615 In practice this means that servers 1617 o might have to increment "Last-Modified" timestamps for every 1618 resource inside the destination namespace of a namespace operation 1619 unless it can do so more selectively, and 1621 o similarily, might have to re-assign "ETag" values for these 1622 resources (unless the server allocates entity tags in a way so 1623 that they are unique across the whole URL namespace managed by the 1624 server). 1626 Note that these considerations also apply to specific use cases, such 1627 as using PUT to create a new resource at a URL that has been mapped 1628 before, but has been deleted since then. 1630 Finally, WebDAV properties (such as DAV:getetag and DAV: 1631 getlastmodified) that inherit their semantics from HTTP headers must 1632 behave accordingly. 1634 9. HTTP Methods for Distributed Authoring 1636 9.1. PROPFIND Method 1638 The PROPFIND method retrieves properties defined on the resource 1639 identified by the Request-URI, if the resource does not have any 1640 internal members, or on the resource identified by the Request-URI 1641 and potentially its member resources, if the resource is a collection 1642 that has internal member URLs. All DAV compliant resources MUST 1643 support the PROPFIND method and the propfind XML element 1644 (Section 14.20) along with all XML elements defined for use with that 1645 element. 1647 A client MUST submit a Depth header with a value of "0", "1", or 1648 "infinity" with a PROPFIND request. Servers MUST support "0" and "1" 1649 depth requests on WebDAV-compliant resources and SHOULD support 1650 "infinity" requests. In practice, support for depth infinity 1651 requests MAY be disabled, due to the performance and security 1652 concerns associated with this behavior. Since clients weren't 1653 required to include the Depth header in [RFC2518], servers SHOULD 1654 treat such a request as if a "Depth: infinity" header was included. 1656 A client may submit a 'propfind' XML element in the body of the 1657 request method describing what information is being requested. It is 1658 possible to: 1660 o Request particular property values, by naming the properties 1661 desired within the 'prop' element (the ordering of properties in 1662 here MAY be ignored by server), 1664 o Request property values for those properties defined in this 1665 specification plus dead properties, by using the 'allprop' element 1666 (the 'include' element can be used with 'allprop' to instruct the 1667 server to also include additional live properties that may not 1668 have been returned otherwise), 1670 o Request a list of names of all the properties defined on the 1671 resource, by using the 'propname' element. 1673 A client may choose not to submit a request body. An empty PROPFIND 1674 request body MUST be treated as if it were an 'allprop' request. 1676 Note that 'allprop' does not return values for all live properties. 1677 WebDAV servers increasingly have expensively-calculated or lengthy 1678 properties (see [RFC3253] and [RFC3744]) and do not return all 1679 properties already. Instead, WebDAV clients can use propname 1680 requests to discover what live properties exist, and request named 1681 properties when retrieving values. For a live property defined 1682 elsewhere, that definition can specify whether that live property 1683 would be returned in 'allprop' requests or not. 1685 All servers MUST support returning a response of content type text/ 1686 xml or application/xml that contains a multistatus XML element that 1687 describes the results of the attempts to retrieve the various 1688 properties. 1690 If there is an error retrieving a property then a proper error result 1691 MUST be included in the response. A request to retrieve the value of 1692 a property which does not exist is an error and MUST be noted, if the 1693 response uses a 'multistatus' XML element, with a 'response' XML 1694 element which contains a 404 (Not Found) status value. 1696 Consequently, the 'multistatus' XML element for a collection resource 1697 MUST include a 'response' XML element for each member URL of the 1698 collection, to whatever depth was requested. It SHOULD NOT include 1699 any 'response' elements for resources that are not WebDAV-compliant. 1700 Each 'response' element MUST contain an 'href' element that contains 1701 the URL of the resource on which the properties in the prop XML 1702 element are defined. Results for a PROPFIND on a collection resource 1703 are returned as a flat list whose order of entries is not 1704 significant. Note that a resource may have only one value for a 1705 property of a given name, so the property may only show up once in 1706 PROPFIND responses. 1708 Properties may be subject to access control. In the case of 1709 'allprop' and 'propname' requests, if a principal does not have the 1710 right to know whether a particular property exists then the property 1711 MAY be silently excluded from the response. 1713 Some PROPFIND results MAY be cached, with care as there is no cache 1714 validation mechanism for most properties. This method is both safe 1715 and idempotent (see section 9.1 of [RFC2616]). 1717 9.1.1. PROPFIND status codes 1719 This section, as with similar sections for other methods, provides 1720 some guidance on error codes and preconditions or postconditions 1721 (defined in Section 16) that might be particularly useful with 1722 PROPFIND. 1724 403 Forbidden - A server MAY reject PROPFIND requests on collections 1725 with depth header of "Infinity", in which case it SHOULD use this 1726 error with the precondition code 'propfind-finite-depth' inside the 1727 error body. 1729 9.1.2. Status codes for use with 207 (Multi-Status) 1731 The following are examples of response codes one would expect to be 1732 used in a 207 (Multi-Status) response for this method. Note, 1733 however, that unless explicitly prohibited any 2/3/4/5xx series 1734 response code may be used in a 207 (Multi-Status) response. 1736 200 OK - A property exists and/or its value is successfully 1737 returned. 1739 401 Unauthorized - The property cannot be viewed without 1740 appropriate authorization. 1742 403 Forbidden - The property cannot be viewed regardless of 1743 authentication. 1745 404 Not Found - The property does not exist. 1747 9.1.3. Example - Retrieving Named Properties 1749 >>Request 1751 PROPFIND /file HTTP/1.1 1752 Host: www.example.com 1753 Content-type: application/xml; charset="utf-8" 1754 Content-Length: xxxx 1756 1757 1758 1759 1760 1761 1762 1763 1764 1766 >>Response 1768 HTTP/1.1 207 Multi-Status 1769 Content-Type: application/xml; charset="utf-8" 1770 Content-Length: xxxx 1772 1773 1774 1775 http://www.example.com/file 1776 1777 1778 1779 Box type A 1780 1781 1782 J.J. Johnson 1783 1784 1785 HTTP/1.1 200 OK 1786 1787 1788 1789 HTTP/1.1 403 Forbidden 1790 The user does not have access to the 1791 DingALing property. 1792 1793 1794 1795 There has been an access violation error. 1796 1797 1799 In this example, PROPFIND is executed on a non-collection resource 1800 http://www.example.com/file. The propfind XML element specifies the 1801 name of four properties whose values are being requested. In this 1802 case only two properties were returned, since the principal issuing 1803 the request did not have sufficient access rights to see the third 1804 and fourth properties. 1806 9.1.4. Example - Retrieving Named and Dead Properties 1808 >>Request 1810 PROPFIND /mycol/ HTTP/1.1 1811 Host: www.example.com 1812 Depth: 1 1813 Content-type: application/xml; charset="utf-8" 1814 Content-Length: xxxx 1816 1817 1818 1819 1820 1821 1822 1823 1825 In this example, PROPFIND is executed on a collection resource 1826 http://www.example.com/mycol/. The client requests the values of two 1827 specific live properties plus all dead properties (names and values). 1828 The response is not shown. 1830 9.1.5. Example - Using 'propname' to Retrieve all Property Names 1832 >>Request 1834 PROPFIND /container/ HTTP/1.1 1835 Host: www.example.com 1836 Content-Type: application/xml; charset="utf-8" 1837 Content-Length: xxxx 1839 1840 1841 1842 1844 >>Response 1846 HTTP/1.1 207 Multi-Status 1847 Content-Type: application/xml; charset="utf-8" 1848 Content-Length: xxxx 1850 1851 1852 1853 http://www.example.com/container/ 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 HTTP/1.1 200 OK 1864 1865 1866 1867 http://www.example.com/container/front.html 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 HTTP/1.1 200 OK 1881 1882 1883 1885 In this example, PROPFIND is invoked on the collection resource 1886 http://www.example.com/container/, with a propfind XML element 1887 containing the propname XML element, meaning the name of all 1888 properties should be returned. Since no Depth header is present, it 1889 assumes its default value of "infinity", meaning the name of the 1890 properties on the collection and all its descendents should be 1891 returned. 1893 Consistent with the previous example, resource 1894 http://www.example.com/container/ has six properties defined on it: 1895 bigbox and author in the "http://ns.example.com/boxschema/" 1896 namespace, and creationdate, displayname, resourcetype, and 1897 supportedlock in the "DAV:" namespace. 1899 The resource http://www.example.com/container/index.html, a member of 1900 the "container" collection, has nine properties defined on it, bigbox 1901 in the "http://ns.example.com/boxschema/" namespace and, 1902 creationdate, displayname, getcontentlength, getcontenttype, getetag, 1903 getlastmodified, resourcetype, and supportedlock in the "DAV:" 1904 namespace. 1906 This example also demonstrates the use of XML namespace scoping and 1907 the default namespace. Since the "xmlns" attribute does not contain 1908 a prefix, the namespace applies by default to all enclosed elements. 1909 Hence, all elements which do not explicitly state the namespace to 1910 which they belong are members of the "DAV:" namespace. 1912 9.1.6. Example - Using 'allprop' 1914 Note that 'allprop', despite its name which remains for backward- 1915 compatibility, does not return every property, but only dead 1916 properties and the live properties defined in this specification. 1918 >>Request 1920 PROPFIND /container/ HTTP/1.1 1921 Host: www.example.com 1922 Depth: 1 1923 Content-Type: application/xml; charset="utf-8" 1924 Content-Length: xxxx 1926 1927 1928 1929 1931 >>Response 1933 HTTP/1.1 207 Multi-Status 1934 Content-Type: application/xml; charset="utf-8" 1935 Content-Length: xxxx 1937 1938 1939 1940 /container/ 1941 1942 1943 Box type A 1944 Hadrian 1945 1997-12-01T17:42:21-08:00 1946 Example collection 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 HTTP/1.1 200 OK 1960 1961 1962 1963 /container/front.html 1964 1965 1966 Box type B 1967 1968 1997-12-01T18:27:21-08:00 1969 Example HTML resource 1970 4525 1971 text/html 1972 "zzyzx" 1973 Mon, 12 Jan 1998 09:25:56 GMT 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 HTTP/1.1 200 OK 1989 1990 1991 1993 In this example, PROPFIND was invoked on the resource 1994 http://www.example.com/container/ with a Depth header of 1, meaning 1995 the request applies to the resource and its children, and a propfind 1996 XML element containing the allprop XML element, meaning the request 1997 should return the name and value of all the dead properties defined 1998 on the resources, plus the name and value of all the properties 1999 defined in this specification. This example illustrates the use of 2000 relative references in the 'href' elements of the response. 2002 The resource http://www.example.com/container/ has six properties 2003 defined on it: 'bigbox' and 'author in the 2004 "http://ns.example.com/boxschema/" namespace, DAV:creationdate, DAV: 2005 displayname, DAV:resourcetype, and DAV:supportedlock. 2007 The last four properties are WebDAV-specific, defined in Section 15. 2008 Since GET is not supported on this resource, the get* properties 2009 (e.g., DAV:getcontentlength) are not defined on this resource. The 2010 WebDAV-specific properties assert that "container" was created on 2011 December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT 2012 (DAV:creationdate), has a name of "Example collection" (DAV: 2013 displayname), a collection resource type (DAV:resourcetype), and 2014 supports exclusive write and shared write locks (DAV:supportedlock). 2016 The resource http://www.example.com/container/front.html has nine 2017 properties defined on it: 2019 'bigbox' in the "http://ns.example.com/boxschema/" namespace (another 2020 instance of the "bigbox" property type), DAV:creationdate, DAV: 2021 displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag, 2022 DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. 2024 The DAV-specific properties assert that "front.html" was created on 2025 December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT 2026 (DAV:creationdate), has a name of "Example HTML resource" (DAV: 2027 displayname), a content length of 4525 bytes (DAV:getcontentlength), 2028 a MIME type of "text/html" (DAV:getcontenttype), an entity tag of 2029 "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998, 2030 at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type, 2031 meaning that it is not a collection (DAV:resourcetype), and supports 2032 both exclusive write and shared write locks (DAV:supportedlock). 2034 9.2. PROPPATCH Method 2036 The PROPPATCH method processes instructions specified in the request 2037 body to set and/or remove properties defined on the resource 2038 identified by the Request-URI. 2040 All DAV compliant resources MUST support the PROPPATCH method and 2041 MUST process instructions that are specified using the 2042 propertyupdate, set, and remove XML elements. Execution of the 2043 directives in this method is, of course, subject to access control 2044 constraints. DAV compliant resources SHOULD support the setting of 2045 arbitrary dead properties. 2047 The request message body of a PROPPATCH method MUST contain the 2048 propertyupdate XML element. Clients SHOULD NOT alter the same 2049 property more than once in a single PROPPATCH request. 2051 Servers MUST process PROPPATCH instructions in document order (an 2052 exception to the normal rule that ordering is irrelevant). 2053 Instructions MUST either all be executed or none executed. Thus if 2054 any error occurs during processing all executed instructions MUST be 2055 undone and a proper error result returned. Instruction processing 2056 details can be found in the definition of the set and remove 2057 instructions in Section 14.23 and Section 14.26. 2059 This method is idempotent, but not safe (see section 9.1 of 2060 [RFC2616]). Responses to this method MUST NOT be cached. 2062 9.2.1. Status Codes for use in 207 (Multi-Status) 2064 The following are examples of response codes one would expect to be 2065 used in a 207 (Multi-Status) response for this method. Note, 2066 however, that unless explicitly prohibited any 2/3/4/5xx series 2067 response code may be used in a 207 (Multi-Status) response. 2069 200 (OK) - The property set or change succeeded. Note that if this 2070 appears for one property, it appears for every property in the 2071 response, due to the atomicity of PROPPATCH. 2073 403 (Forbidden) - The client, for reasons the server chooses not to 2074 specify, cannot alter one of the properties. 2076 403 (Forbidden): The client has attempted to set a read-only 2077 property, such as DAV:getetag. If returning this error, the server 2078 SHOULD use the precondition code 'cannot-modify-protected-property' 2079 inside the response body. 2081 409 (Conflict) - The client has provided a value whose semantics are 2082 not appropriate for the property. 2084 424 (Failed Dependency) - The property change could not be made 2085 because of another property change that failed. 2087 507 (Insufficient Storage) - The server did not have sufficient space 2088 to record the property. 2090 9.2.2. Example - PROPPATCH 2092 >>Request 2094 PROPPATCH /bar.html HTTP/1.1 2095 Host: www.example.com 2096 Content-Type: application/xml; charset="utf-8" 2097 Content-Length: xxxx 2099 2100 2102 2103 2104 2105 Jim Whitehead 2106 Roy Fielding 2107 2108 2109 2110 2111 2112 2113 2115 >>Response 2117 HTTP/1.1 207 Multi-Status 2118 Content-Type: application/xml; charset="utf-8" 2119 Content-Length: xxxx 2121 2122 2124 2125 http://www.example.com/bar.html 2126 2127 2128 HTTP/1.1 424 Failed Dependency 2129 2130 2131 2132 HTTP/1.1 409 Conflict 2133 2134 Copyright Owner can not be deleted or 2135 altered. 2136 2137 2139 In this example, the client requests the server to set the value of 2140 the "Authors" property in the 2141 "http://ns.example.com/standards/z39.50/" namespace, and to remove 2142 the property "Copyright-Owner" in the same namespace. Since the 2143 Copyright-Owner property could not be removed, no property 2144 modifications occur. The 424 (Failed Dependency) status code for the 2145 Authors property indicates this action would have succeeded if it 2146 were not for the conflict with removing the Copyright-Owner property. 2148 9.3. MKCOL Method 2150 The MKCOL method is used to create a new collection. All WebDAV 2151 compliant resources MUST support the MKCOL method. 2153 MKCOL creates a new collection resource at the location specified by 2154 the Request-URI. If the Request-URI is already mapped to a resource 2155 then the MKCOL MUST fail. During MKCOL processing, a server MUST 2156 make the Request-URI a member of its parent collection, unless the 2157 Request-URI is "/". If no such ancestor exists, the method MUST 2158 fail. When the MKCOL operation creates a new collection resource, 2159 all ancestors MUST already exist, or the method MUST fail with a 409 2160 (Conflict) status code. For example, if a request to create 2161 collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the request 2162 must fail. 2164 When MKCOL is invoked without a request body, the newly created 2165 collection SHOULD have no members. 2167 A MKCOL request message may contain a message body. The precise 2168 behavior of a MKCOL request when the body is present is undefined, 2169 but limited to creating collections, members of a collection, bodies 2170 of members and properties on the collections or members. If the 2171 server receives a MKCOL request entity type it does not support or 2172 understand it MUST respond with a 415 (Unsupported Media Type) status 2173 code. If the server decides to reject the request based on the 2174 presence of an entity or the type of an entity, it should use the 415 2175 (Unsupported Media Type) status code. 2177 This method is idempotent, but not safe (see section 9.1 of 2178 [RFC2616]). Responses to this method MUST NOT be cached. 2180 9.3.1. MKCOL Status Codes 2182 In addition to the general status codes possible, the following 2183 status codes have specific applicability to MKCOL: 2185 201 (Created) - The collection was created. 2187 403 (Forbidden) - This indicates at least one of two conditions: 1) 2188 the server does not allow the creation of collections at the given 2189 location in its URL namespace, or 2) the parent collection of the 2190 Request-URI exists but cannot accept members. 2192 405 (Method Not Allowed) - MKCOL can only be executed on an unmapped 2193 URL. 2195 409 (Conflict) - A collection cannot be made at the Request-URI until 2196 one or more intermediate collections have been created. The server 2197 MUST NOT create those intermediate collections automatically. 2199 415 (Unsupported Media Type) - The server does not support the 2200 request body type (since this specification does not define any body 2201 for MKCOL requests). 2203 507 (Insufficient Storage) - The resource does not have sufficient 2204 space to record the state of the resource after the execution of this 2205 method. 2207 9.3.2. Example - MKCOL 2209 This example creates a collection called /webdisc/xfiles/ on the 2210 server www.example.com. 2212 >>Request 2214 MKCOL /webdisc/xfiles/ HTTP/1.1 2215 Host: www.example.com 2217 >>Response 2219 HTTP/1.1 201 Created 2221 9.4. GET, HEAD for Collections 2223 The semantics of GET are unchanged when applied to a collection, 2224 since GET is defined as, "retrieve whatever information (in the form 2225 of an entity) is identified by the Request-URI" [RFC2616]. GET when 2226 applied to a collection may return the contents of an "index.html" 2227 resource, a human-readable view of the contents of the collection, or 2228 something else altogether. Hence it is possible that the result of a 2229 GET on a collection will bear no correlation to the membership of the 2230 collection. 2232 Similarly, since the definition of HEAD is a GET without a response 2233 message body, the semantics of HEAD are unmodified when applied to 2234 collection resources. 2236 9.5. POST for Collections 2238 Since by definition the actual function performed by POST is 2239 determined by the server and often depends on the particular 2240 resource, the behavior of POST when applied to collections cannot be 2241 meaningfully modified because it is largely undefined. Thus the 2242 semantics of POST are unmodified when applied to a collection. 2244 9.6. DELETE Requirements 2246 DELETE is defined in [RFC2616], section 9.7, to "delete the resource 2247 identified by the Request-URI". However, WebDAV changes some DELETE 2248 handling requirements. 2250 A server processing a successful DELETE request: 2252 MUST destroy locks rooted on the deleted resource 2254 MUST remove the mapping from the Request-URI to any resource. 2256 Thus, after a successful DELETE operation (and in the absence of 2257 other actions) a subsequent GET/HEAD/PROPFIND request to the target 2258 Request-URI MUST return 404 (Not Found). 2260 9.6.1. DELETE for Collections 2262 The DELETE method on a collection MUST act as if a "Depth: infinity" 2263 header was used on it. A client MUST NOT submit a Depth header with 2264 a DELETE on a collection with any value but infinity. 2266 DELETE instructs that the collection specified in the Request-URI and 2267 all resources identified by its internal member URLs are to be 2268 deleted. 2270 If any resource identified by a member URL cannot be deleted then all 2271 of the member's ancestors MUST NOT be deleted, so as to maintain URL 2272 namespace consistency. 2274 Any headers included with DELETE MUST be applied in processing every 2275 resource to be deleted. 2277 When the DELETE method has completed processing it MUST result in a 2278 consistent URL namespace. 2280 If an error occurs deleting an internal resource (a resource other 2281 than the resource identified in the Request-URI) then the response 2282 can be a 207 (Multi-Status). Multi-Status is used here to indicate 2283 which internal resources could NOT be deleted, including an error 2284 code which should help the client understand which resources caused 2285 the failure. For example, the Multi-Status body could include a 2286 response with status 423 (Locked) if an internal resource was locked. 2288 The server MAY return a 4xx status response, rather than a 207, if 2289 the request failed completely. 2291 424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi- 2292 Status) response for DELETE. They can be safely left out because the 2293 client will know that the ancestors of a resource could not be 2294 deleted when the client receives an error for the ancestor's progeny. 2295 Additionally 204 (No Content) errors SHOULD NOT be returned in the 2296 207 (Multi-Status). The reason for this prohibition is that 204 (No 2297 Content) is the default success code. 2299 9.6.2. Example - DELETE 2301 >>Request 2303 DELETE /container/ HTTP/1.1 2304 Host: www.example.com 2306 >>Response 2308 HTTP/1.1 207 Multi-Status 2309 Content-Type: application/xml; charset="utf-8" 2310 Content-Length: xxxx 2312 2313 2314 2315 http://www.example.com/container/resource3 2316 HTTP/1.1 423 Locked 2317 2318 2319 2321 In this example the attempt to delete 2322 http://www.example.com/container/resource3 failed because it is 2323 locked, and no lock token was submitted with the request. 2324 Consequently, the attempt to delete http://www.example.com/container/ 2325 also failed. Thus the client knows that the attempt to delete 2326 http://www.example.com/container/ must have also failed since the 2327 parent can not be deleted unless its child has also been deleted. 2328 Even though a Depth header has not been included, a depth of infinity 2329 is assumed because the method is on a collection. 2331 9.7. PUT Requirements 2333 9.7.1. PUT for Non-Collection Resources 2335 A PUT performed on an existing resource replaces the GET response 2336 entity of the resource. Properties defined on the resource may be 2337 recomputed during PUT processing but are not otherwise affected. For 2338 example, if a server recognizes the content type of the request body, 2339 it may be able to automatically extract information that could be 2340 profitably exposed as properties. 2342 A PUT that would result in the creation of a resource without an 2343 appropriately scoped parent collection MUST fail with a 409 2344 (Conflict). 2346 A PUT request is the only way a client has to indicate to the server 2347 what Content-Type a resource should have, and whether it should 2348 change if the resource is overwritten. Thus, a client SHOULD provide 2349 a Content-Type for a new resource if any is known. If the client 2350 does not provide a Content-Type for a new resource, the server MAY 2351 create a resource with no Content-Type assigned, or it MAY attempt to 2352 assign a reasonable and legal Content-Type. 2354 Note that although a recipient should treat metadata supplied with an 2355 HTTP request as authorative, in practice there's no guarantee that a 2356 server will accept Content- headers. Many servers do not allow 2357 configuring the Content-Type on a per-resource basis in the first 2358 place. Thus, clients should not rely on the ability to directly 2359 influence the content type by including a Content-Type request 2360 header. 2362 9.7.2. PUT for Collections 2364 This specification does not define the behavior of the PUT method for 2365 existing collections. A PUT request to an existing collection MAY be 2366 treated as an error (405 Method Not Allowed). 2368 The MKCOL method is defined to create collections. 2370 9.8. COPY Method 2372 The COPY method creates a duplicate of the source resource identified 2373 by the Request-URI, in the destination resource identified by the URI 2374 in the Destination header. The Destination header MUST be present. 2375 The exact behavior of the COPY method depends on the type of the 2376 source resource. 2378 All WebDAV compliant resources MUST support the COPY method. 2379 However, support for the COPY method does not guarantee the ability 2380 to copy a resource. For example, separate programs may control 2381 resources on the same server. As a result, it may not be possible to 2382 copy a resource to a location that appears to be on the same server. 2384 This method is idempotent, but not safe (see section 9.1 of 2385 [RFC2616]). Responses to this method MUST NOT be cached. 2387 9.8.1. COPY for Non-collection Resources 2389 When the source resource is not a collection the result of the COPY 2390 method is the creation of a new resource at the destination whose 2391 state and behavior match that of the source resource as closely as 2392 possible. Since the environment at the destination may be different 2393 than at the source due to factors outside the scope of control of the 2394 server, such as the absence of resources required for correct 2395 operation, it may not be possible to completely duplicate the 2396 behavior of the resource at the destination. Subsequent alterations 2397 to the destination resource will not modify the source resource. 2398 Subsequent alterations to the source resource will not modify the 2399 destination resource. 2401 9.8.2. COPY for Properties 2403 After a successful COPY invocation, all dead properties on the source 2404 resource MUST be duplicated on the destination resource, along with 2405 all properties as appropriate. Live properties described in this 2406 document SHOULD be duplicated as identically behaving live properties 2407 at the destination resource, but not necessarily with the same 2408 values. Servers SHOULD NOT convert live properties into dead 2409 properties on the destination resource, because clients may then draw 2410 incorrect conclusions about the state or functionality of a resource. 2411 Note that some live properties are defined such that the absence of 2412 the property has a specific meaning (e.g. a flag with one meaning if 2413 present and the opposite if absent), and in these cases, a successful 2414 COPY might result in the property being reported as "Not Found" in 2415 subsequent requests. 2417 A COPY operation creates a new resource, much like a PUT operation 2418 does. Live properties which are related to resource creation (such 2419 as DAV:creationdate) should have their values set accordingly. 2421 9.8.3. COPY for Collections 2423 The COPY method on a collection without a Depth header MUST act as if 2424 a Depth header with value "infinity" was included. A client may 2425 submit a Depth header on a COPY on a collection with a value of "0" 2426 or "infinity". Servers MUST support the "0" and "infinity" Depth 2427 header behaviors on WebDAV-compliant resources. 2429 A COPY of depth infinity instructs that the collection resource 2430 identified by the Request-URI is to be copied to the location 2431 identified by the URI in the Destination header, and all its internal 2432 member resources are to be copied to a location relative to it, 2433 recursively through all levels of the collection hierarchy. Note 2434 that a depth infinity COPY of /A/ into /A/B/ could lead to infinite 2435 recursion if not handled correctly. 2437 A COPY of "Depth: 0" only instructs that the collection and its 2438 properties but not resources identified by its internal member URLs, 2439 are to be copied. 2441 Any headers included with a COPY MUST be applied in processing every 2442 resource to be copied with the exception of the Destination header. 2444 The Destination header only specifies the destination URI for the 2445 Request-URI. When applied to members of the collection identified by 2446 the Request-URI the value of Destination is to be modified to reflect 2447 the current location in the hierarchy. So, if the Request-URI is /a/ 2448 with Host header value http://example.com/ and the Destination is 2449 http://example.com/b/ then when http://example.com/a/c/d is processed 2450 it must use a Destination of http://example.com/b/c/d. 2452 When the COPY method has completed processing it MUST have created a 2453 consistent URL namespace at the destination (see Section 5.1 for the 2454 definition of namespace consistency). However, if an error occurs 2455 while copying an internal collection, the server MUST NOT copy any 2456 resources identified by members of this collection (i.e., the server 2457 must skip this subtree), as this would create an inconsistent 2458 namespace. After detecting an error, the COPY operation SHOULD try 2459 to finish as much of the original copy operation as possible (i.e., 2460 the server should still attempt to copy other subtrees and their 2461 members, that are not descendents of an error-causing collection). 2463 So, for example, if an infinite depth copy operation is performed on 2464 collection /a/, which contains collections /a/b/ and /a/c/, and an 2465 error occurs copying /a/b/, an attempt should still be made to copy 2466 /a/c/. Similarly, after encountering an error copying a non- 2467 collection resource as part of an infinite depth copy, the server 2468 SHOULD try to finish as much of the original copy operation as 2469 possible. 2471 If an error in executing the COPY method occurs with a resource other 2472 than the resource identified in the Request-URI then the response 2473 MUST be a 207 (Multi-Status), and the URL of the resource causing the 2474 failure MUST appear with the specific error. 2476 The 424 (Failed Dependency) status code SHOULD NOT be returned in the 2477 207 (Multi-Status) response from a COPY method. These responses can 2478 be safely omitted because the client will know that the progeny of a 2479 resource could not be copied when the client receives an error for 2480 the parent. Additionally 201 (Created)/204 (No Content) status codes 2481 SHOULD NOT be returned as values in 207 (Multi-Status) responses from 2482 COPY methods. They, too, can be safely omitted because they are the 2483 default success codes. 2485 9.8.4. COPY and Overwriting Destination Resources 2487 If a COPY request has an Overwrite header with a value of "F", and a 2488 resource exists at the Destination URL, the server MUST fail the 2489 request. 2491 When a server executes a COPY request and overwrites a destination 2492 resource, the exact behavior MAY depend on many factors, including 2493 WebDAV extension capabilities (see particularly [RFC3253]). For 2494 example, when an ordinary resource is overwritten, the server could 2495 delete the target resource before doing the copy, or could do an in- 2496 place overwrite to preserve live properties. 2498 When a collection is overwritten, the membership of the destination 2499 collection after the successful COPY request MUST be the same 2500 membership as the source collection immediately before the COPY. 2501 Thus, merging the membership of the source and destination 2502 collections together in the destination is not a compliant behavior. 2504 In general, if clients require the state of the destination URL to be 2505 wiped out prior to a COPY (e.g. to force live properties to be 2506 reset), then the client could send a DELETE to the destination before 2507 the COPY request to ensure this reset. 2509 9.8.5. Status Codes 2511 In addition to the general status codes possible, the following 2512 status codes have specific applicability to COPY: 2514 201 (Created) - The source resource was successfully copied. The 2515 COPY operation resulted in the creation of a new resource. 2517 204 (No Content) - The source resource was successfully copied to a 2518 pre-existing destination resource. 2520 207 (Multi-Status) - Multiple resources were to be affected by the 2521 COPY, but errors on some of them prevented the operation from taking 2522 place. Specific error messages, together with the most appropriate 2523 of the source and destination URLs, appear in the body of the multi- 2524 status response. E.g. if a destination resource was locked and could 2525 not be overwritten, then the destination resource URL appears with 2526 the 423 (Locked) status. 2528 403 (Forbidden) - The operation is forbidden. A special case for 2529 COPY could be that the source and destination resources are the same 2530 resource. 2532 409 (Conflict) - A resource cannot be created at the destination 2533 until one or more intermediate collections have been created. The 2534 server MUST NOT create those intermediate collections automatically. 2536 412 (Precondition Failed) - A precondition header check failed, e.g. 2537 the Overwrite header is "F" and the destination URL is already mapped 2538 to a resource. 2540 423 (Locked) - The destination resource, or resource within the 2541 destination collection, was locked. This response SHOULD contain the 2542 'lock-token-submitted' precondition element. 2544 502 (Bad Gateway) - This may occur when the destination is on another 2545 server, repository or URL namespace. Either the source namespace 2546 does not support copying to the destination namespace, or the 2547 destination namespace refuses to accept the resource. The client may 2548 wish to try GET/PUT and PROPFIND/PROPPATCH instead. 2550 507 (Insufficient Storage) - The destination resource does not have 2551 sufficient space to record the state of the resource after the 2552 execution of this method. 2554 9.8.6. Example - COPY with Overwrite 2556 This example shows resource 2557 http://www.example.com/~fielding/index.html being copied to the 2558 location http://www.example.com/users/f/fielding/index.html. The 204 2559 (No Content) status code indicates the existing resource at the 2560 destination was overwritten. 2562 >>Request 2564 COPY /~fielding/index.html HTTP/1.1 2565 Host: www.example.com 2566 Destination: http://www.example.com/users/f/fielding/index.html 2568 >>Response 2570 HTTP/1.1 204 No Content 2572 9.8.7. Example - COPY with No Overwrite 2574 The following example shows the same copy operation being performed, 2575 but with the Overwrite header set to "F." A response of 412 2576 (Precondition Failed) is returned because the destination URL is 2577 already mapped to a resource. 2579 >>Request 2581 COPY /~fielding/index.html HTTP/1.1 2582 Host: www.example.com 2583 Destination: http://www.example.com/users/f/fielding/index.html 2584 Overwrite: F 2586 >>Response 2588 HTTP/1.1 412 Precondition Failed 2590 9.8.8. Example - COPY of a Collection 2592 >>Request 2594 COPY /container/ HTTP/1.1 2595 Host: www.example.com 2596 Destination: http://www.example.com/othercontainer/ 2597 Depth: infinity 2599 >>Response 2601 HTTP/1.1 207 Multi-Status 2602 Content-Type: application/xml; charset="utf-8" 2603 Content-Length: xxxx 2605 2607 2608 2609 http://www.example.com/othercontainer/R2/ 2610 HTTP/1.1 423 Locked 2611 2612 2614 The Depth header is unnecessary as the default behavior of COPY on a 2615 collection is to act as if a "Depth: infinity" header had been 2616 submitted. In this example most of the resources, along with the 2617 collection, were copied successfully. However the collection R2 2618 failed because the destination R2 is locked. Because there was an 2619 error copying R2, none of R2's members were copied. However no 2620 errors were listed for those members due to the error minimization 2621 rules. 2623 9.9. MOVE Method 2625 The MOVE operation on a non-collection resource is the logical 2626 equivalent of a copy (COPY), followed by consistency maintenance 2627 processing, followed by a delete of the source, where all three 2628 actions are performed atomically. The consistency maintenance step 2629 allows the server to perform updates caused by the move, such as 2630 updating all URLs other than the Request-URI which identify the 2631 source resource, to point to the new destination resource. 2632 Consequently, the Destination header MUST be present on all MOVE 2633 methods and MUST follow all COPY requirements for the COPY part of 2634 the MOVE method. All WebDAV compliant resources MUST support the 2635 MOVE method. However, support for the MOVE method does not guarantee 2636 the ability to move a resource to a particular destination. 2638 For example, separate programs may actually control different sets of 2639 resources on the same server. Therefore, it may not be possible to 2640 move a resource within a namespace that appears to belong to the same 2641 server. 2643 If a resource exists at the destination, the destination resource 2644 will be deleted as a side-effect of the MOVE operation, subject to 2645 the restrictions of the Overwrite header. 2647 This method is idempotent, but not safe (see section 9.1 of 2648 [RFC2616]). Responses to this method MUST NOT be cached. 2650 9.9.1. MOVE for Properties 2652 Live properties described in this document SHOULD be moved along with 2653 the resource, such that the resource has identically behaving live 2654 properties at the destination resource, but not necessarily with the 2655 same values. Note that some live properties are defined such that 2656 the absence of the property has a specific meaning (e.g. a flag with 2657 one meaning if present and the opposite if absent), and in these 2658 cases, a successful MOVE might result in the property being reported 2659 as "Not Found" in subsequent requests. If the live properties will 2660 not work the same way at the destination, the server MAY fail the 2661 request. 2663 MOVE is frequently used by clients to rename a file without changing 2664 its parent collection, so it's not appropriate to reset all live 2665 properties which are set at resource creation. For example, the DAV: 2666 creationdate property value SHOULD remain the same after a MOVE. 2668 Dead properties MUST be moved along with the resource. 2670 9.9.2. MOVE for Collections 2672 A MOVE with "Depth: infinity" instructs that the collection 2673 identified by the Request-URI be moved to the address specified in 2674 the Destination header, and all resources identified by its internal 2675 member URLs are to be moved to locations relative to it, recursively 2676 through all levels of the collection hierarchy. 2678 The MOVE method on a collection MUST act as if a "Depth: infinity" 2679 header was used on it. A client MUST NOT submit a Depth header on a 2680 MOVE on a collection with any value but "infinity". 2682 Any headers included with MOVE MUST be applied in processing every 2683 resource to be moved with the exception of the Destination header. 2684 The behavior of the Destination header is the same as given for COPY 2685 on collections. 2687 When the MOVE method has completed processing it MUST have created a 2688 consistent URL namespace at both the source and destination (see 2689 section 5.1 for the definition of namespace consistency). However, 2690 if an error occurs while moving an internal collection, the server 2691 MUST NOT move any resources identified by members of the failed 2692 collection (i.e., the server must skip the error-causing subtree), as 2693 this would create an inconsistent namespace. In this case, after 2694 detecting the error, the move operation SHOULD try to finish as much 2695 of the original move as possible (i.e., the server should still 2696 attempt to move other subtrees and the resources identified by their 2697 members, that are not descendents of an error-causing collection). 2698 So, for example, if an infinite depth move is performed on collection 2699 /a/, which contains collections /a/b/ and /a/c/, and an error occurs 2700 moving /a/b/, an attempt should still be made to try moving /a/c/. 2701 Similarly, after encountering an error moving a non-collection 2702 resource as part of an infinite depth move, the server SHOULD try to 2703 finish as much of the original move operation as possible. 2705 If an error occurs with a resource other than the resource identified 2706 in the Request-URI then the response MUST be a 207 (Multi-Status), 2707 and the errored resource's URL MUST appear with the specific error. 2709 The 424 (Failed Dependency) status code SHOULD NOT be returned in the 2710 207 (Multi-Status) response from a MOVE method. These errors can be 2711 safely omitted because the client will know that the progeny of a 2712 resource could not be moved when the client receives an error for the 2713 parent. Additionally 201 (Created)/204 (No Content) responses SHOULD 2714 NOT be returned as values in 207 (Multi-Status) responses from a 2715 MOVE. These responses can be safely omitted because they are the 2716 default success codes. 2718 9.9.3. MOVE and the Overwrite Header 2720 If a resource exists at the destination and the Overwrite header is 2721 "T" then prior to performing the move the server MUST perform a 2722 DELETE with "Depth: infinity" on the destination resource. If the 2723 Overwrite header is set to "F" then the operation will fail. 2725 9.9.4. Status Codes 2727 In addition to the general status codes possible, the following 2728 status codes have specific applicability to MOVE: 2730 201 (Created) - The source resource was successfully moved, and a new 2731 URL mapping was created at the destination. 2733 204 (No Content) - The source resource was successfully moved to a 2734 URL that was already mapped. 2736 207 (Multi-Status) - Multiple resources were to be affected by the 2737 MOVE, but errors on some of them prevented the operation from taking 2738 place. Specific error messages, together with the most appropriate 2739 of the source and destination URLs, appear in the body of the multi- 2740 status response. E.g. if a source resource was locked and could not 2741 be moved, then the source resource URL appears with the 423 (Locked) 2742 status. 2744 403 (Forbidden) - Among many possible reasons for forbidding a MOVE 2745 operation, this status code is recommended for use when the source 2746 and destination resources are the same. 2748 409 (Conflict) - A resource cannot be created at the destination 2749 until one or more intermediate collections have been created. The 2750 server MUST NOT create those intermediate collections automatically. 2751 Or, the server was unable to preserve the behavior of the live 2752 properties and still move the resource to the destination (see 2753 'preserved-live-properties' postcondition). 2755 412 (Precondition Failed) - A condition header failed. Specific to 2756 MOVE, this could mean that the Overwrite header is "F" and the state 2757 of the destination URL is already mapped to a resource. 2759 423 (Locked) - The source or the destination resource, the source or 2760 destination resource parent, or some resource within the source or 2761 destination collection, was locked. This response SHOULD contain the 2762 'lock-token-submitted' precondition element. 2764 502 (Bad Gateway) - This may occur when the destination is on another 2765 server and the destination server refuses to accept the resource. 2766 This could also occur when the destination is on another sub-section 2767 of the same server namespace. 2769 9.9.5. Example - MOVE of a Non-Collection 2771 This example shows resource 2772 http://www.example.com/~fielding/index.html being moved to the 2773 location http://www.example.com/users/f/fielding/index.html. The 2774 contents of the destination resource would have been overwritten if 2775 the destination URL was already mapped to a resource. In this case, 2776 since there was nothing at the destination resource, the response 2777 code is 201 (Created). 2779 >>Request 2781 MOVE /~fielding/index.html HTTP/1.1 2782 Host: www.example.com 2783 Destination: http://www.example/users/f/fielding/index.html 2785 >>Response 2787 HTTP/1.1 201 Created 2788 Location: http://www.example.com/users/f/fielding/index.html 2790 9.9.6. Example - MOVE of a Collection 2792 >>Request 2794 MOVE /container/ HTTP/1.1 2795 Host: www.example.com 2796 Destination: http://www.example.com/othercontainer/ 2797 Overwrite: F 2798 If: () 2799 () 2801 >>Response 2803 HTTP/1.1 207 Multi-Status 2804 Content-Type: application/xml; charset="utf-8" 2805 Content-Length: xxxx 2807 2808 2809 2810 http://www.example.com/othercontainer/C2/ 2811 HTTP/1.1 423 Locked 2812 2813 2815 In this example the client has submitted a number of lock tokens with 2816 the request. A lock token will need to be submitted for every 2817 resource, both source and destination, anywhere in the scope of the 2818 method, that is locked. In this case the proper lock token was not 2819 submitted for the destination 2820 http://www.example.com/othercontainer/C2/. This means that the 2821 resource /container/C2/ could not be moved. Because there was an 2822 error moving /container/C2/, none of /container/C2's members were 2823 moved. However no errors were listed for those members due to the 2824 error minimization rules. User agent authentication has previously 2825 occurred via a mechanism outside the scope of the HTTP protocol, in 2826 an underlying transport layer. 2828 9.10. LOCK Method 2830 The following sections describe the LOCK method, which is used to 2831 take out a lock of any access type and to refresh an existing lock. 2832 These sections on the LOCK method describe only those semantics that 2833 are specific to the LOCK method and are independent of the access 2834 type of the lock being requested. 2836 Any resource which supports the LOCK method MUST, at minimum, support 2837 the XML request and response formats defined herein. 2839 This method is neither idempotent nor safe (see section 9.1 of 2840 [RFC2616]). Responses to this method MUST NOT be cached. 2842 9.10.1. Creating a lock on existing resource 2844 A LOCK request to an existing resource will create a lock on the 2845 resource identified by the Request-URI, provided the resource is not 2846 already locked with a conflicting lock. The resource identified in 2847 the Request-URI becomes the root of the lock. Lock method requests 2848 to create a new lock MUST have a XML request body. The server MUST 2849 preserve the information provided by the client in the 'owner' field 2850 in the request body when the lock information is requested. The LOCK 2851 request MAY have a Timeout header. 2853 When a new lock is created, the LOCK response: 2855 o MUST contain a body with the value of the DAV:lockdiscovery 2856 property in a prop XML element. This MUST contain the full 2857 information about the lock just granted, while information about 2858 other (shared) locks is OPTIONAL. 2860 o MUST include the Lock-Token response header with the token 2861 associated with the new lock. 2863 9.10.2. Refreshing Locks 2865 A lock is refreshed by sending a LOCK request to the URL of a 2866 resource within the scope of the lock. This request MUST NOT have a 2867 body and it MUST specify which lock to refresh by using the 'Lock- 2868 Token' header with a single lock token (only one lock may be 2869 refreshed at a time). It MAY contain a Timeout header, which a 2870 server MAY accept to change the duration remaining on the lock to the 2871 new value. A server MUST ignore the Depth header on a LOCK refresh. 2873 If the resource has other (shared) locks, those locks are unaffected 2874 by a lock refresh. Additionally, those locks do not prevent the 2875 named lock from being refreshed. 2877 Note that in [RFC2518], clients were indicated through the example in 2878 the text to use the If header to specify what lock to refresh (rather 2879 than the Lock-Token header). Servers are encouraged to continue to 2880 support this as well as the Lock-Token header. 2882 Note that the Lock-Token header is not returned in the response for a 2883 successful refresh LOCK request, but the LOCK response body MUST 2884 contain the new value for the DAV:lockdiscovery body. 2886 9.10.3. Depth and Locking 2888 The Depth header may be used with the LOCK method. Values other than 2889 0 or infinity MUST NOT be used with the Depth header on a LOCK 2890 method. All resources that support the LOCK method MUST support the 2891 Depth header. 2893 A Depth header of value 0 means to just lock the resource specified 2894 by the Request-URI. 2896 If the Depth header is set to infinity then the resource specified in 2897 the Request-URI along with all its internal members, all the way down 2898 the hierarchy, are to be locked. A successful result MUST return a 2899 single lock token which represents all the resources that have been 2900 locked. If an UNLOCK is successfully executed on this token, all 2901 associated resources are unlocked. Hence, partial success is not an 2902 option. Either the entire hierarchy is locked or no resources are 2903 locked. 2905 If the lock cannot be granted to all resources, the server MUST 2906 return a Multi-Status response with a 'response' element for at least 2907 one resource which prevented the lock from being granted, along with 2908 a suitable status code for that failure (e.g. 403 (Forbidden) or 423 2909 (Locked)). Additionally, if the resource causing the failure was not 2910 the resource requested, then the server SHOULD include a 'response' 2911 element for the Request-URI as well, with a 'status' element 2912 containing 424 Failed Dependency. 2914 If no Depth header is submitted on a LOCK request then the request 2915 MUST act as if a "Depth:infinity" had been submitted. 2917 9.10.4. Locking Unmapped URLs 2919 A successful LOCK method MUST result in the creation of an empty 2920 resource which is locked (and which is not a collection), when a 2921 resource did not previously exist at that URL. Later on, the lock 2922 may go away but the empty resource remains. Empty resources MUST 2923 then appear in PROPFIND responses including that URL in the response 2924 scope. A server MUST respond successfully to a GET request to an 2925 empty resource, either by using a 204 No Content response, or by 2926 using 200 OK with a Content-Length header indicating zero length 2928 9.10.5. Lock Compatibility Table 2930 The table below describes the behavior that occurs when a lock 2931 request is made on a resource. 2933 +--------------------------+----------------+-------------------+ 2934 | Current State | Shared Lock OK | Exclusive Lock OK | 2935 +--------------------------+----------------+-------------------+ 2936 | None | True | True | 2937 | | | | 2938 | Shared Lock | True | False | 2939 | | | | 2940 | Exclusive Lock | False | False* | 2941 +--------------------------+----------------+-------------------+ 2943 Legend: True = lock may be granted. False = lock MUST NOT be 2944 granted. *=It is illegal for a principal to request the same lock 2945 twice. 2947 The current lock state of a resource is given in the leftmost column, 2948 and lock requests are listed in the first row. The intersection of a 2949 row and column gives the result of a lock request. For example, if a 2950 shared lock is held on a resource, and an exclusive lock is 2951 requested, the table entry is "false", indicating the lock must not 2952 be granted. 2954 9.10.6. LOCK Responses 2956 In addition to the general status codes possible, the following 2957 status codes have specific applicability to LOCK: 2959 200 (OK) - The LOCK request succeeded and the value of the DAV: 2960 lockdiscovery property is included in the response body. 2962 201 (Created) - The LOCK request was to an unmapped URL, the request 2963 succeeded and resulted in the creation of a new resource, and the 2964 value of the DAV:lockdiscovery property is included in the response 2965 body. 2967 409 (Conflict) - A resource cannot be created at the destination 2968 until one or more intermediate collections have been created. The 2969 server MUST NOT create those intermediate collections automatically. 2971 423 (Locked), potentially with 'no-conflicting-lock' precondition 2972 code - There is already a lock on the resource which is not 2973 compatible with the requested lock (see lock compatibility table 2974 above). 2976 409 (Conflict), with 'lock-token-matches-request-uri' precondition 2977 code - The LOCK request was made with a Lock-Token header, indicating 2978 that the client wishes to refresh the given lock. However, the 2979 Request-URI did not fall within the scope of the lock identified by 2980 the token. The lock may have a scope that does not include the 2981 Request-URI, or the lock could have disappeared, or the token may be 2982 invalid. 2984 9.10.7. Example - Simple Lock Request 2986 >>Request 2988 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2989 Host: example.com 2990 Timeout: Infinite, Second-4100000000 2991 Content-Type: application/xml; charset="utf-8" 2992 Content-Length: xxxx 2993 Authorization: Digest username="ejw", 2994 realm="ejw@example.com", nonce="...", 2995 uri="/workspace/webdav/proposal.doc", 2996 response="...", opaque="..." 2998 2999 3000 3001 3002 3003 http://example.org/~ejw/contact.html 3004 3005 3007 >>Response 3009 HTTP/1.1 200 OK 3010 Lock-Token: 3011 Content-Type: application/xml; charset="utf-8" 3012 Content-Length: xxxx 3014 3015 3016 3017 3018 3019 3020 infinity 3021 3022 http://example.org/~ejw/contact.html 3023 3024 Second-604800 3025 3026 urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 3028 3029 3030 http://example.com/workspace/webdav/proposal.doc 3032 3033 3034 3035 3037 This example shows the successful creation of an exclusive write lock 3038 on resource http://example.com/workspace/webdav/proposal.doc. The 3039 resource http://example.org/~ejw/contact.html contains contact 3040 information for the creator of the lock. The server has an activity- 3041 based timeout policy in place on this resource, which causes the lock 3042 to automatically be removed after 1 week (604800 seconds). Note that 3043 the nonce, response, and opaque fields have not been calculated in 3044 the Authorization request header. 3046 9.10.8. Example - Refreshing a Write Lock 3048 >>Request 3050 LOCK /workspace/webdav/proposal.doc HTTP/1.1 3051 Host: example.com 3052 Timeout: Infinite, Second-4100000000 3053 Lock-Token: 3054 Authorization: Digest username="ejw", 3055 realm="ejw@example.com", nonce="...", 3056 uri="/workspace/webdav/proposal.doc", 3057 response="...", opaque="..." 3059 >>Response 3061 HTTP/1.1 200 OK 3062 Content-Type: application/xml; charset="utf-8" 3063 Content-Length: xxxx 3065 3066 3067 3068 3069 3070 3071 infinity 3072 3073 http://example.org/~ejw/contact.html 3074 3075 Second-604800 3076 3077 urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 3079 3080 3081 http://example.com/workspace/webdav/proposal.doc 3083 3084 3085 3086 3088 This request would refresh the lock, attempting to reset the timeout 3089 to the new value specified in the timeout header. Notice that the 3090 client asked for an infinite time out but the server choose to ignore 3091 the request. In this example, the nonce, response, and opaque fields 3092 have not been calculated in the Authorization request header. 3094 9.10.9. Example - Multi-Resource Lock Request 3096 >>Request 3098 LOCK /webdav/ HTTP/1.1 3099 Host: example.com 3100 Timeout: Infinite, Second-4100000000 3101 Depth: infinity 3102 Content-Type: application/xml; charset="utf-8" 3103 Content-Length: xxxx 3104 Authorization: Digest username="ejw", 3105 realm="ejw@example.com", nonce="...", 3106 uri="/workspace/webdav/proposal.doc", 3107 response="...", opaque="..." 3109 3110 3111 3112 3113 3114 http://example.org/~ejw/contact.html 3115 3116 3118 >>Response 3120 HTTP/1.1 207 Multi-Status 3121 Content-Type: application/xml; charset="utf-8" 3122 Content-Length: xxxx 3124 3125 3126 3127 http://example.com/webdav/secret 3128 HTTP/1.1 403 Forbidden 3129 3130 3131 http://example.com/webdav/ 3132 HTTP/1.1 424 Failed Dependency 3133 3134 3136 This example shows a request for an exclusive write lock on a 3137 collection and all its children. In this request, the client has 3138 specified that it desires an infinite length lock, if available, 3139 otherwise a timeout of 4.1 billion seconds, if available. The 3140 request entity body contains the contact information for the 3141 principal taking out the lock, in this case a web page URL. 3143 The error is a 403 (Forbidden) response on the resource 3144 http://example.com/webdav/secret. Because this resource could not be 3145 locked, none of the resources were locked. Note also that the a 3146 'response' element for the Request-URI itself has been included as 3147 required. 3149 In this example, the nonce, response, and opaque fields have not been 3150 calculated in the Authorization request header. 3152 9.11. UNLOCK Method 3154 The UNLOCK method removes the lock identified by the lock token in 3155 the Lock-Token request header. The Request-URI MUST identify a 3156 resource within the scope of the lock. 3158 Note that use of Lock-Token header to provide the lock token is not 3159 consistent with other state-changing methods which all require an If 3160 header with the lock token. Thus, the If header is not needed to 3161 provide the lock token. Naturally when the If header is present it 3162 has its normal meaning as a conditional header. 3164 For a successful response to this method, the server MUST remove the 3165 lock from the resource identified by the Request-URI and from all 3166 other resources included in the lock. 3168 If all resources which have been locked under the submitted lock 3169 token can not be unlocked then the UNLOCK request MUST fail. 3171 A successful response to an UNLOCK method does not mean that the 3172 resource is necessarily unlocked. It means that the specific lock 3173 corresponding to the specified token no longer exists. 3175 Any DAV compliant resource which supports the LOCK method MUST 3176 support the UNLOCK method. 3178 This method is idempotent, but not safe (see section 9.1 of 3179 [RFC2616]). Responses to this method MUST NOT be cached. 3181 9.11.1. Status Codes 3183 In addition to the general status codes possible, the following 3184 status codes have specific applicability to UNLOCK: 3186 204 (No Content) - Normal success response (rather than 200 OK, since 3187 200 OK would imply a response body, and an UNLOCK success response 3188 does not normally contain a body) 3189 400 (Bad Request) - No lock token was provided. 3191 403 (Forbidden) - The currently authenticated principal does not have 3192 permission to remove the lock. 3194 409 (Conflict), with 'lock-token-matches-request-uri' precondition - 3195 The resource was not locked, or the request was made to a Request-URI 3196 that was not within the scope of the lock. 3198 9.11.2. Example - UNLOCK 3200 >>Request 3202 UNLOCK /workspace/webdav/info.doc HTTP/1.1 3203 Host: example.com 3204 Lock-Token: 3205 Authorization: Digest username="ejw" 3206 realm="ejw@example.com", nonce="...", 3207 uri="/workspace/webdav/proposal.doc", 3208 response="...", opaque="..." 3210 >>Response 3212 HTTP/1.1 204 No Content 3214 In this example, the lock identified by the lock token 3215 "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully 3216 removed from the resource 3217 http://example.com/workspace/webdav/info.doc. If this lock included 3218 more than just one resource, the lock is removed from all resources 3219 included in the lock. The 204 (No Content) status code is used 3220 instead of 200 (OK) because there is no response entity body. 3222 In this example, the nonce, response, and opaque fields have not been 3223 calculated in the Authorization request header. 3225 10. HTTP Headers for Distributed Authoring 3227 All DAV headers follow the same basic formatting rules as HTTP 3228 headers. This includes rules like line continuation and how to 3229 combine (or separate) multiple instances of the same header using 3230 commas. WebDAV adds two new conditional headers to the set defined 3231 in HTTP: the If and Overwrite headers. 3233 10.1. DAV Header 3235 DAV = "DAV" ":" #( compliance-class ) 3236 compliance-class = ( "1" | "2" | "3" | extend ) 3237 extend = Coded-URL | token 3238 Coded-URL = "<" absolute-URI ">" 3239 ; No LWS allowed in Coded-URL 3240 ; absolute-URI is defined in RFC3986 3242 This general-header appearing in the response indicates that the 3243 resource supports the DAV schema and protocol as specified. All DAV 3244 compliant resources MUST return the DAV header with compliance-class 3245 "1" on all OPTIONS responses. In cases where WebDAV is only 3246 supported in part of the server namespace, an OPTIONS request to non- 3247 WebDAV resources (including "/") SHOULD NOT advertise WebDAV support. 3249 The value is a comma-separated list of all compliance class 3250 identifiers that the resource supports. Class identifiers may be 3251 Coded-URLs or tokens (as defined by [RFC2616]). Identifiers can 3252 appear in any order. Identifiers that are standardized through the 3253 IETF RFC process are tokens, but other identifiers SHOULD be Coded- 3254 URLs to encourage uniqueness. 3256 A resource must show class 1 compliance if it shows class 2 or 3 3257 compliance. In general, support for one compliance class does not 3258 entail support for any other, and in particular, support for 3259 compliance class 3 does not require support for compliance class 2. 3260 Please refer to Section 18 for more details on compliance classes 3261 defined in this specification. 3263 Note that many WebDAV servers do not advertise WebDAV support in 3264 response to "OPTIONS *". 3266 As a request header, this header allows the client to advertise 3267 compliance with named features when the server needs that 3268 information. Clients SHOULD NOT send this header unless a standards 3269 track specification requires it. Any extension that makes use of 3270 this as a request header will need to carefully consider caching 3271 implications. 3273 10.2. Depth Header 3275 Depth = "Depth" ":" ("0" | "1" | "infinity") 3277 The Depth request header is used with methods executed on resources 3278 which could potentially have internal members to indicate whether the 3279 method is to be applied only to the resource ("Depth: 0"), to the 3280 resource and its immediate children, ("Depth: 1"), or the resource 3281 and all its progeny ("Depth: infinity"). 3283 The Depth header is only supported if a method's definition 3284 explicitly provides for such support. 3286 The following rules are the default behavior for any method that 3287 supports the Depth header. A method may override these defaults by 3288 defining different behavior in its definition. 3290 Methods which support the Depth header may choose not to support all 3291 of the header's values and may define, on a case by case basis, the 3292 behavior of the method if a Depth header is not present. For 3293 example, the MOVE method only supports "Depth: infinity" and if a 3294 Depth header is not present will act as if a "Depth: infinity" header 3295 had been applied. 3297 Clients MUST NOT rely upon methods executing on members of their 3298 hierarchies in any particular order or on the execution being atomic 3299 unless the particular method explicitly provides such guarantees. 3301 Upon execution, a method with a Depth header will perform as much of 3302 its assigned task as possible and then return a response specifying 3303 what it was able to accomplish and what it failed to do. 3305 So, for example, an attempt to COPY a hierarchy may result in some of 3306 the members being copied and some not. 3308 By default, the Depth header does not interact with other headers. 3309 That is, each header on a request with a Depth header MUST be applied 3310 only to the Request-URI if it applies to any resource, unless 3311 specific Depth behavior is defined for that header. 3313 If a resource, source or destination, within the scope of the method 3314 with a Depth header is locked in such a way as to prevent the 3315 successful execution of the method, then the lock token for that 3316 resource MUST be submitted with the request in the If request header. 3318 The Depth header only specifies the behavior of the method with 3319 regards to internal children. If a resource does not have internal 3320 children then the Depth header MUST be ignored. 3322 Please note, however, that it is always an error to submit a value 3323 for the Depth header that is not allowed by the method's definition. 3324 Thus submitting a "Depth: 1" on a COPY, even if the resource does not 3325 have internal members, will result in a 400 (Bad Request). The 3326 method should fail not because the resource doesn't have internal 3327 members, but because of the illegal value in the header. 3329 10.3. Destination Header 3331 The Destination request header specifies the URI which identifies a 3332 destination resource for methods such as COPY and MOVE, which take 3333 two URIs as parameters. 3335 Destination = "Destination" ":" Simple-ref 3337 If the Destination value is an absolute URI, it may name a different 3338 server (or different port or scheme). If the source server cannot 3339 attempt a copy to the remote server, it MUST fail the request. Note 3340 that copying and moving resources to remote servers is not fully 3341 defined in this specification (e.g. specific error conditions). 3343 If the Destination value is too long or otherwise unacceptable, the 3344 server SHOULD return 400 (Bad Request), ideally with helpful 3345 information in an error body. 3347 10.4. If Header 3349 The If request header is intended to have similar functionality to 3350 the If-Match header defined in Section 14.24 of [RFC2616]. However 3351 the If header handles any state token as well as ETags. A typical 3352 example of a state token is a lock token, and lock tokens are the 3353 only state tokens defined in this specification. 3355 10.4.1. Purpose 3357 The If header has two distinct purposes: 3359 o The first purpose is to make a request conditional by supplying a 3360 series of state lists with conditions that match tokens and ETags 3361 to specific resource. If this header is evaluated and all state 3362 lists fail, then the request MUST fail with a 412 (Precondition 3363 Failed) status. On the other hand, the request can succeed only 3364 if one of the described state lists succeeds. The success 3365 criteria for state lists and matching functions are defined in 3366 Section 10.4.3 and Section 10.4.4. 3368 o Additionally, the mere fact that a state token appears in an If 3369 header means that is has been "submitted" with the request. In 3370 general, this is used to indicate that the client has knowledge of 3371 that state token. The meaning of submitting a state token depends 3372 on its type (for lock tokens, please refer to Section 6). 3374 Note that these two purposes need to be treated distinctly: a state 3375 token counts as being submitted independently of whether the server 3376 actually has evaluated the state list it appears in, and also 3377 independently of whether the condition it expressed was found to be 3378 true or not. 3380 10.4.2. Syntax 3382 If = "If" ":" ( 1*No-tag-list | 1*Tagged-list ) 3384 No-tag-list = List 3385 Tagged-list = Resource-Tag 1*List 3387 List = "(" 1*Condition ")" 3388 Condition = ["Not"] (State-token | "[" entity-tag "]") 3389 ; entity-tag: see Section 3.11 of [RFC2616] 3390 ; No LWS allowed between "[", entity-tag and "]" 3392 State-token = Coded-URL 3394 Resource-Tag = "<" Simple-ref ">" 3395 ; Simple-ref: see Section 8.3 3396 ; No LWS allowed in Resource-Tag 3398 The syntax distinguishes between untagged lists ("No-tag-list") and 3399 tagged lists ("Tagged-list"). Untagged lists apply to the resource 3400 identified by the Request-URI, while tagged lists apply to the 3401 resource identified by the preceding Resource-Tag. 3403 A Resource-Tag applies to all subsequent Lists, up to the next 3404 Resource-Tag. 3406 Note that the two list types cannot be mixed within an If header. 3407 This is not a functional restriction because the No-tag-list syntax 3408 is just a shorthand notation for a Tagged-list production with a 3409 Resource-Tag referring to the Request-URI. 3411 Each List consists of one or more Conditions. Each Condition is 3412 defined in terms of an entity-tag or state-token, potentially negated 3413 by the prefix "Not". 3415 Note that the If header syntax does not allow multiple instances of 3416 If headers in a single request. However, the HTTP header syntax 3417 allows extending single header values across multiple lines, by 3418 inserting a line break followed by whitespace (see [RFC2616], Section 3419 4.2). 3421 10.4.3. List Evaluation 3423 A Condition that consists of a single entity-tag or state-token 3424 evaluates to true if the resource matches the described state (where 3425 the individual matching functions are defined below in 3426 Section 10.4.4). Prefixing it with "Not" reverses the result of the 3427 evaluation (thus, the "Not" applies only to the subsequent entity-tag 3428 or state-token). 3430 Each List production describes a series of conditions. The whole 3431 list evaluates to true if and only if each condition evaluates to 3432 true (that is, the list represents a logical conjunction of 3433 Conditions). 3435 Each No-tag-list and Tagged-list production may contain one or more 3436 Lists. They evaluate to true if and only if any of the contained 3437 lists evaluates to true (that is, if there's more than one List, that 3438 List sequence represents a logical disjunction of the Lists). 3440 Finally, the whole If header evaluates to true if and only if at 3441 least one of the No-tag-list or Tagged-list productions evaluates to 3442 true. If the header evaluates to false, the server MUST reject the 3443 request with a 412 (Precondition Failed) status. Otherwise, 3444 execution of the request can proceed as if the header wasn't present. 3446 10.4.4. Matching State Tokens and ETags 3448 When performing If header processing, the definition of a matching 3449 state token or entity tag is as follows: 3451 Identifying a resource: The resource is identified by the URI along 3452 with the token, in tagged list production, or by the Request-URI in 3453 untagged list production. 3455 Matching entity tag: Where the entity tag matches an entity tag 3456 associated with the identified resource. Servers MUST use either the 3457 weak or the strong comparison function defined in Section 13.3.3 of 3458 [RFC2616]. 3460 Matching state token: Where there is an exact match between the state 3461 token in the If header and any state token on the identified 3462 resource. A lock state token is considered to match if the resource 3463 is anywhere in the scope of the lock. 3465 Handling unmapped URLs: for both ETags and state tokens, treat as if 3466 the URL identified a resource that exists but does not have the 3467 specified state. 3469 10.4.5. If Header and Non-DAV Aware Proxies 3471 Non-DAV aware proxies will not honor the If header, since they will 3472 not understand the If header, and HTTP requires non-understood 3473 headers to be ignored. When communicating with HTTP/1.1 proxies, the 3474 client MUST use the "Cache-Control: no-cache" request header so as to 3475 prevent the proxy from improperly trying to service the request from 3476 its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache" 3477 request header MUST be used for the same reason. 3479 As in general clients may not be able to reliably detect non-DAV 3480 aware intermediates, they are advised to always prevent caching using 3481 the request directives mentioned above. 3483 10.4.6. Example - No-tag Production 3485 If: ( 3486 ["I am an ETag"]) 3487 (["I am another ETag"]) 3489 The previous header would require that the resource identified in the 3490 Request-URI be locked with the specified lock token and be in the 3491 state identified by the "I am an ETag" ETag or in the state 3492 identified by the second ETag "I am another ETag". 3494 To put the matter more plainly one can think of the previous If 3495 header as expressing the condition below: 3497 ( 3498 is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND 3499 matches-etag("I am an ETag") 3500 ) 3501 OR 3502 ( 3503 matches-etag("I am another ETag") 3504 ) 3506 10.4.7. Example - using "Not" with No-tag Production 3508 If: (Not 3509 ) 3511 This If header requires that the resource must not be locked with a 3512 lock having the lock token 3513 urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a 3514 lock with the lock token 3515 urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092. 3517 10.4.8. Example - causing a Condition to always evaluate to True 3519 There may be cases where a client wishes to submit state tokens, but 3520 doesn't want the request to fail just because the state token isn't 3521 current anymore. One simple way to do this is to include a Condition 3522 that is known to always evaluate to true, such as in: 3524 If: () 3525 (Not ) 3527 "DAV:no-lock" is known to never represent a current lock token, as 3528 lock tokens are assigned by the server, following the uniqueness 3529 requirements described in Section 6.5, therefore in particular 3530 exclude URIs in the "DAV:" scheme. Thus, by applying "Not" to a 3531 known not to be current state token, the Condition always evaluates 3532 to true. Consequently, the whole If header will always evaluate to 3533 true, and the lock token 3534 urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be submitted in 3535 any case. 3537 10.4.9. Example - Tagged List If header in COPY 3539 >>Request 3541 COPY /resource1 HTTP/1.1 3542 Host: www.example.com 3543 Destination: /resource2 3544 If: 3545 ( 3546 [W/"A weak ETag"]) (["strong ETag"]) 3548 In this example http://www.example.com/resource1 is being copied to 3549 http://www.example.com/resource2. When the method is first applied 3550 to http://www.example.com/resource1, resource1 must be in the state 3551 specified by "( [W/"A 3552 weak ETag"]) (["strong ETag"])", that is, it either must be locked 3553 with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2" 3554 and have a weak entity tag W/"A weak ETag" or it must have a strong 3555 entity tag "strong ETag". 3557 10.4.10. Example - Matching lock tokens with collection locks 3559 DELETE /specs/rfc2518.txt HTTP/1.1 3560 Host: www.example.com 3561 If: 3562 () 3564 For this example, the lock token must be compared to the identified 3565 resource, which is the 'specs' collection identified by the URL in 3566 the tagged list production. If the 'specs' collection is not locked 3567 by a lock with the specified lock token, the request MUST fail. 3568 Otherwise, this request could succeed, because the If header 3569 evaluates to true, and because the lock token for the lock affecting 3570 the affected resource has been submitted. 3572 10.4.11. Example - Matching ETags on unmapped URLs 3574 Consider a collection "/specs" that does not contain the member 3575 "/specs/rfc2518.doc". In this case, the If header 3577 If: (["4217"]) 3579 will evaluate to false (the URI isn't mapped, thus the resource 3580 identified by the URI doesn't have an entity matching the ETag 3581 "4217"). 3583 On the other hand, an If header of 3585 If: (Not ["4217"]) 3587 will consequently evaluate to true. 3589 Note that as defined above in Section 10.4.4, the same considerations 3590 apply to matching state tokens. 3592 10.5. Lock-Token Header 3594 Lock-Token = "Lock-Token" ":" Coded-URL 3596 The Lock-Token request header is used with the UNLOCK method to 3597 identify the lock to be removed. The lock token in the Lock-Token 3598 request header MUST identify a lock that contains the resource 3599 identified by Request-URI as a member. 3601 The Lock-Token response header is used with the LOCK method to 3602 indicate the lock token created as a result of a successful LOCK 3603 request to create a new lock. 3605 10.6. Overwrite Header 3607 Overwrite = "Overwrite" ":" ("T" | "F") 3609 The Overwrite request header specifies whether the server should 3610 overwrite a resource mapped to the destination URL during a COPY or 3611 MOVE. A value of "F" states that the server must not perform the 3612 COPY or MOVE operation if the state of the destination URL does map 3613 to a resource. If the overwrite header is not included in a COPY or 3614 MOVE request then the resource MUST treat the request as if it has an 3615 overwrite header of value "T". While the Overwrite header appears to 3616 duplicate the functionality of the If-Match: * header of HTTP/1.1, 3617 If-Match applies only to the Request-URI, and not to the Destination 3618 of a COPY or MOVE. 3620 If a COPY or MOVE is not performed due to the value of the Overwrite 3621 header, the method MUST fail with a 412 (Precondition Failed) status 3622 code. The server MUST do authorization checks before checking this 3623 or any conditional header. 3625 All DAV compliant resources MUST support the Overwrite header. 3627 10.7. Timeout Request Header 3629 TimeOut = "Timeout" ":" 1#TimeType 3630 TimeType = ("Second-" DAVTimeOutVal | "Infinite") 3631 ; No LWS allowed within TimeType 3632 DAVTimeOutVal = 1*DIGIT 3634 Clients MAY include Timeout request headers in their LOCK requests. 3635 However, the server is not required to honor or even consider these 3636 requests. Clients MUST NOT submit a Timeout request header with any 3637 method other than a LOCK method. 3639 The "Second" TimeType specifies the number of seconds that will 3640 elapse between granting of the lock at the server, and the automatic 3641 removal of the lock. The timeout value for TimeType "Second" MUST 3642 NOT be greater than 2^32-1. 3644 See Section 6.6 for a description of lock timeout behavior. 3646 11. Status Code Extensions to HTTP/1.1 3648 The following status codes are added to those defined in HTTP/1.1 3649 [RFC2616]. 3651 11.1. 207 Multi-Status 3653 The 207 (Multi-Status) status code provides status for multiple 3654 independent operations (see Section 13 for more information). 3656 11.2. 422 Unprocessable Entity 3658 The 422 (Unprocessable Entity) status code means the server 3659 understands the content type of the request entity (hence a 3660 415(Unsupported Media Type) status code is inappropriate), and the 3661 syntax of the request entity is correct (thus a 400 (Bad Request) 3662 status code is inappropriate) but was unable to process the contained 3663 instructions. For example, this error condition may occur if an XML 3664 request body contains well-formed (i.e., syntactically correct), but 3665 semantically erroneous XML instructions. 3667 11.3. 423 Locked 3669 The 423 (Locked) status code means the source or destination resource 3670 of a method is locked. This response SHOULD contain an appropriate 3671 precondition or postcondition code, such as 'lock-token-submitted' or 3672 'no-conflicting-lock". 3674 11.4. 424 Failed Dependency 3676 The 424 (Failed Dependency) status code means that the method could 3677 not be performed on the resource because the requested action 3678 depended on another action and that action failed. For example, if a 3679 command in a PROPPATCH method fails then, at minimum, the rest of the 3680 commands will also fail with 424 (Failed Dependency). 3682 11.5. 507 Insufficient Storage 3684 The 507 (Insufficient Storage) status code means the method could not 3685 be performed on the resource because the server is unable to store 3686 the representation needed to successfully complete the request. This 3687 condition is considered to be temporary. If the request which 3688 received this status code was the result of a user action, the 3689 request MUST NOT be repeated until it is requested by a separate user 3690 action. 3692 12. Use of HTTP Status Codes 3694 These HTTP codes are not redefined, but their use is somewhat 3695 extended by WebDAV methods and requirements. In general, many HTTP 3696 status codes can be used in response to any request, not just in 3697 cases described in this document. Note also that WebDAV servers are 3698 known to use 300-level redirect responses (and early interoperability 3699 tests found clients unprepared to see those responses). A 300-level 3700 request MUST NOT be used when the server has created a new resource 3701 in response to the request. 3703 12.1. 412 Precondition Failed 3705 Any request can contain a conditional header defined in HTTP (If- 3706 Match, If-Modified-Since, etc.) or the "If" or "Overwrite" 3707 conditional headers defined in this specification. If the server 3708 evaluates a conditional header, and if that condition fails to hold, 3709 then this error code MUST be returned. On the other hand, if the 3710 client did not include a conditional header in the request, then the 3711 server MUST NOT use this error. 3713 12.2. 414 Request-URI Too Long 3715 This status code is used in HTTP 1.1 only for Request-URIs, not URIs 3716 in other locations. 3718 13. Multi-Status Response 3720 A Multi-Status response contains one 'response' element for each 3721 resource in the scope of the request (in no required order) or MAY be 3722 empty if no resources match the request. The default 207 (Multi- 3723 Status) response body is a text/xml or application/xml HTTP entity 3724 that contains a single XML element called 'multistatus', which 3725 contains a set of XML elements called response which contain 200, 3726 300, 400, and 500 series status codes generated during the method 3727 invocation. 100 series status codes SHOULD NOT be recorded in a 3728 'response' XML element. The 207 status code itself MUST NOT be 3729 considered a success response, it is only completely successful if 3730 all 'response' elements inside contain success status codes. 3732 The body of a 207 Multi-Status response MUST contain a URL associated 3733 with each specific status code, so that the client can tell whether 3734 the error occurred with the source resource, destination resource or 3735 some other resource in the scope of the request. 3737 13.1. Response headers 3739 HTTP defines the Location header to indicate a preferred URL for the 3740 resource that was addressed in the Request-URI (e.g. in response to 3741 successful PUT requests or in redirect responses). However, use of 3742 this header creates ambiguity when there are URLs in the body of the 3743 response, as with Multi-Status. Thus, use of the Location header 3744 with the Multi-Status response is intentionally undefined. 3746 13.2. Handling redirected child resources 3748 Redirect responses (300-303, 305 and 307) defined in HTTP 1.1 3749 normally take a Location header to indicate the new URI for the 3750 single resource redirected from the Request-URI. Multi-Status 3751 responses contain many resource addresses, but the original 3752 definition in [RFC2518] did not have any place for the server to 3753 provide the new URI for redirected resources. This specification 3754 does define a 'location' element for this information (see 3755 Section 14.9). Servers MUST use this new element with redirect 3756 responses in Multi-Status. 3758 Clients encountering redirected resources in Multi-Status MUST NOT 3759 rely on the 'location' element being present with a new URI. If the 3760 element is not present, the client MAY reissue the request to the 3761 individual redirected resource, because the response to that request 3762 can be redirected with a Location header containing the new URI. 3764 13.3. Internal Status Codes 3766 Section 9.2.1, Section 9.1.2, Section 9.6.1, Section 9.8.3 and 3767 Section 9.9.2 define various status codes used in Multi-Status 3768 responses. This specification does not define the meaning of other 3769 status codes that could appear in these responses. 3771 14. XML Element Definitions 3773 In this section, the final line of each section gives the element 3774 type declaration using the format defined in [REC-XML]. The "Value" 3775 field, where present, specifies further restrictions on the allowable 3776 contents of the XML element using BNF (i.e., to further restrict the 3777 values of a PCDATA element). The "Extensibility" field discusses how 3778 the element may be extended in the future (or in existing extensions 3779 to WebDAV. 3781 All of the elements defined here may be extended by the addition of 3782 attributes and child elements not defined in this specification. All 3783 elements defined here are in the "DAV:" namespace. 3785 14.1. activelock XML Element 3787 Name: activelock 3789 Purpose: Describes a lock on a resource. 3791 3794 14.2. allprop XML Element 3796 Name: allprop 3798 Purpose: Specifies that all names and values of dead properties and 3799 the live properties defined by this document existing on the 3800 resource are to be returned. 3802 3804 14.3. collection XML Element 3806 Name: collection 3808 Purpose: Identifies the associated resource as a collection. The 3809 DAV:resourcetype property of a collection resource MUST contain 3810 this element. It is normally empty but extensions may add sub- 3811 elements. 3813 3815 14.4. depth XML Element 3817 Name: depth 3819 Purpose: The value of the Depth header. 3821 Value: "0" | "1" | "infinity" 3823 3825 14.5. error XML Element 3827 Name: error 3829 Purpose: Error responses, particularly 403 Forbidden and 409 3830 Conflict, sometimes need more information to indicate what went 3831 wrong. When an error response contains a body in WebDAV, the body 3832 is in XML with the root element 'error'. The 'error' element 3833 SHOULD include an XML element with the code of a failed 3834 precondition or postcondition. 3836 Description: Contains at least one XML element, and MUST NOT contain 3837 text or mixed content. Any element that is a child of the 'error' 3838 element is considered to be a precondition or postcondition code. 3839 Unrecognized elements SHOULD be ignored. 3841 3843 14.6. exclusive XML Element 3845 Name: exclusive 3847 Purpose: Specifies an exclusive lock 3849 3851 14.7. href XML Element 3853 Name: href 3855 Purpose: MUST contain a URI or a relative reference. 3857 Description: There may be limits on the value of 'href' depending on 3858 the context of its use. Refer to the specification text where 3859 'href' is used to see what limitations apply in each case. 3861 Value: Simple-ref 3863 3865 14.8. include XML Element 3867 Name: include 3869 Purpose: Any child element represents the name of a property to be 3870 included in the PROPFIND response. All elements inside an 3871 'include' XML element MUST define properties related to the 3872 resource, although possible property names are in no way limited 3873 to those property names defined in this document or other 3874 standards. This element MUST NOT contain text or mixed content. 3876 3878 14.9. location XML Element 3880 Name: location 3882 Purpose: HTTP defines the "Location" header (see [RFC2616], section 3883 14.30) for use with some status codes (such as 201 and the 300 3884 series codes). When these codes are used inside a 'multistatus' 3885 element, the 'location' element can be used to provide the 3886 accompanying Location header value. 3888 Description: Contains a single href element with the same value that 3889 would be used in a Location header. 3891 3893 14.10. lockentry XML Element 3895 Name: lockentry 3897 Purpose: Defines the types of locks that can be used with the 3898 resource. 3900 3902 14.11. lockinfo XML Element 3903 Name: lockinfo 3905 Purpose: The 'lockinfo' XML element is used with a LOCK method to 3906 specify the type of lock the client wishes to have created. 3908 3910 14.12. lockroot XML Element 3912 Name: lockroot 3914 Purpose: Contains the root URL of the lock, which is the URL through 3915 which the resource was addressed in the LOCK request. 3917 Description: The href contains a HTTP URL with the address of the 3918 root of the lock. The server SHOULD include this in all DAV: 3919 lockdiscovery property values and the response to LOCK requests. 3921 3923 14.13. lockscope XML Element 3925 Name: lockscope 3927 Purpose: Specifies whether a lock is an exclusive lock, or a shared 3928 lock. 3930 3932 14.14. locktoken XML Element 3934 Name: locktoken 3936 Purpose: The lock token associated with a lock. 3938 Description: The href contains a single lock token URI which refers 3939 to the lock. 3941 3943 14.15. locktype XML Element 3944 Name: locktype 3946 Purpose: Specifies the access type of a lock. At present, this 3947 specification only defines one lock type, the write lock. 3949 3951 14.16. multistatus XML Element 3953 Name: multistatus 3955 Purpose: Contains multiple response messages. 3957 Description: The 'responsedescription' element at the top level is 3958 used to provide a general message describing the overarching 3959 nature of the response. If this value is available an application 3960 may use it instead of presenting the individual response 3961 descriptions contained within the responses. 3963 3965 14.17. owner XML Element 3967 Name: owner 3969 Purpose: Provides information about the creator of a lock. 3971 Description: Allows a client to provide information sufficient for 3972 either directly contacting a principal (such as a telephone number 3973 or Email URI), or for discovering the principal (such as the URL 3974 of a homepage) who created a lock. The value provided MUST be 3975 treated as a dead property in terms of XML Information Item 3976 preservation. The server MUST NOT alter the value unless the 3977 owner value provided by the client is empty. For a certain amount 3978 of interoperability between different client implementations, if 3979 clients have URI-formatted contact information for the lock 3980 creator suitable for user display, then clients SHOULD put those 3981 URIs in 'href' child elements of the 'owner' element. 3983 Extensibility: MAY be extended with child elements, mixed content, 3984 text content or attributes. 3986 3988 14.18. prop XML element 3990 Name: prop 3992 Purpose: Contains properties related to a resource. 3994 Description: A generic container for properties defined on 3995 resources. All elements inside a 'prop' XML element MUST define 3996 properties related to the resource, although possible property 3997 names are in no way limited to those property names defined in 3998 this document or other standards. This element MUST NOT contain 3999 text or mixed content. 4001 4003 14.19. propertyupdate XML element 4005 Name: propertyupdate 4007 Purpose: Contains a request to alter the properties on a resource. 4009 Description: This XML element is a container for the information 4010 required to modify the properties on the resource. This XML 4011 element is multi-valued. 4013 4015 14.20. propfind XML Element 4017 Name: propfind 4019 Purpose: Specifies the properties to be returned from a PROPFIND 4020 method. Four special elements are specified for use with 4021 'propfind': 'prop', 'allprop', 'include' and 'propname'. If 4022 'prop' is used inside 'propfind' it MUST NOT contain property 4023 values. 4025 4027 14.21. propname XML Element 4029 Name: propname 4031 Purpose: Specifies that only a list of property names on the 4032 resource is to be returned. 4034 4036 14.22. propstat XML Element 4038 Name: propstat 4040 Purpose: Groups together a prop and status element that is 4041 associated with a particular 'href' element. 4043 Description: The propstat XML element MUST contain one prop XML 4044 element and one status XML element. The contents of the prop XML 4045 element MUST only list the names of properties to which the result 4046 in the status element applies. The optional precondition/ 4047 postcondition error code and 'responsedescription' text also apply 4048 to the properties named in 'prop'. 4050 4052 14.23. remove XML element 4054 Name: remove 4056 Purpose: Lists the DAV properties to be removed from a resource. 4058 Description: Remove instructs that the properties specified in prop 4059 should be removed. Specifying the removal of a property that does 4060 not exist is not an error. All the XML elements in a 'prop' XML 4061 element inside of a 'remove' XML element MUST be empty, as only 4062 the names of properties to be removed are required. 4064 4066 14.24. response XML Element 4068 Name: response 4070 Purpose: Holds a single response describing the effect of a method 4071 on resource and/or its properties. 4073 Description: The 'href' element contains a HTTP URL pointing to a 4074 WebDAV resource when used in the 'response' container. A 4075 particular 'href' value MUST NOT appear more than once as the 4076 child of a 'response' XML element under a 'multistatus' XML 4077 element. This requirement is necessary in order to keep 4078 processing costs for a response to linear time. Essentially, this 4079 prevents having to search in order to group together all the 4080 responses by 'href'. There are, however, no requirements 4081 regarding ordering based on 'href' values. The optional 4082 precondition/postcondition error code and 'responsedescription' 4083 text can provide additional information about this resource 4084 relative to the request or result. 4086 4089 14.25. responsedescription XML Element 4091 Name: responsedescription 4093 Purpose: Contains information about a status response within a 4094 Multi-Status. 4096 Description: Provides information suitable to be presented to a 4097 user. 4099 4101 14.26. set XML element 4103 Name: set 4105 Purpose: Lists the DAV property values to be set for a resource. 4107 Description: The 'set' XML element MUST contain only a prop XML 4108 element. The elements contained by the prop XML element inside 4109 the 'set' XML element MUST specify the name and value of 4110 properties that are set on the resource identified by Request-URI. 4111 If a property already exists then its value is replaced. Language 4112 tagging information appearing in the scope of the 'prop' element 4113 (in the "xml:lang" attribute, if present) MUST be persistently 4114 stored along with the property, and MUST be subsequently 4115 retrievable using PROPFIND. 4117 4119 14.27. shared XML Element 4121 Name: shared 4123 Purpose: Specifies a shared lock 4125 4127 14.28. status XML Element 4129 Name: status 4131 Purpose: Holds a single HTTP status-line 4133 Value: status-line (status-line defined in Section 6.1 of [RFC2616]) 4135 4137 14.29. timeout XML Element 4139 Name: timeout 4141 Purpose: The number of seconds remaining before a lock expires. 4143 Value: TimeType (defined in Section 10.7). 4145 4147 14.30. write XML Element 4149 Name: write 4151 Purpose: Specifies a write lock. 4153 4155 15. DAV Properties 4157 For DAV properties, the name of the property is also the same as the 4158 name of the XML element that contains its value. In the section 4159 below, the final line of each section gives the element type 4160 declaration using the format defined in [REC-XML]. The "Value" 4161 field, where present, specifies further restrictions on the allowable 4162 contents of the XML element using BNF (i.e., to further restrict the 4163 values of a PCDATA element). 4165 A protected property is one which cannot be changed with a PROPPATCH 4166 request. There may be other requests which would result in a change 4167 to a protected property (as when a LOCK request affects the value of 4168 DAV:lockdiscovery). Note that a given property could be protected on 4169 one type of resource, but not protected on another type of resource. 4171 A computed property is one with a value defined in terms of a 4172 computation (based on the content and other properties of that 4173 resource, or even of some other resource). A computed property is 4174 always a protected property. 4176 COPY and MOVE behavior refers to local COPY and MOVE operations. 4178 For properties defined based on HTTP GET response headers (DAV:get*), 4179 the value could include LWS as defined in [RFC2616], section 4.2. 4180 Server implementors SHOULD NOT include extra LWS in these values, 4181 however client implementors MUST be prepared to handle extra LWS. 4183 15.1. creationdate Property 4185 Name: creationdate 4187 Purpose: Records the time and date the resource was created. 4189 Value: date-time (defined in [RFC3339], see the ABNF in section 4190 5.6.) 4192 Protected: MAY be protected. Some servers allow DAV:creationdate to 4193 be changed to reflect the time the document was created if that is 4194 more meaningful to the user (rather than the time it was 4195 uploaded). Thus, clients SHOULD NOT use this property in 4196 synchronization logic (use DAV:getetag instead). 4198 COPY/MOVE behaviour: This property value SHOULD be kept during a 4199 MOVE operation, but is normally re-initialized when a resource is 4200 created with a COPY. It should not be set in a COPY. 4202 Description: The DAV:creationdate property SHOULD be defined on all 4203 DAV compliant resources. If present, it contains a timestamp of 4204 the moment when the resource was created. Servers that are 4205 incapable of persistently recording the creation date SHOULD 4206 instead leave it undefined (i.e. report "Not Found") 4208 4210 15.2. displayname Property 4212 Name: displayname 4214 Purpose: Provides a name for the resource that is suitable for 4215 presentation to a user. 4217 Value: Any text 4219 Protected: SHOULD NOT be protected. Note that servers implementing 4220 [RFC2518] might have made this a protected property as this is a 4221 new requirement. 4223 COPY/MOVE behaviour: This property value SHOULD be preserved in COPY 4224 and MOVE operations. 4226 Description: The DAV:displayname property should be defined on all 4227 DAV compliant resources. If present, the property contains a 4228 description of the resource that is suitable for presentation to a 4229 user. This property is defined on the resource, and hence SHOULD 4230 have the same value independent of the Request-URI used to 4231 retrieve it (thus computing this property based on the Request-URI 4232 is deprecated). 4234 4236 15.3. getcontentlanguage Property 4238 Name: getcontentlanguage 4240 Purpose: Contains the Content-Language header value (from section 4241 14.12 of [RFC2616]) as it would be returned by a GET without 4242 accept headers. 4244 Value: language-tag (language-tag is defined in section 3.10 of 4245 [RFC2616]). 4247 Protected: SHOULD NOT be protected, so that clients can reset the 4248 language. Note that servers implementing [RFC2518] might have 4249 made this a protected property as this is a new requirement. 4251 COPY/MOVE behaviour: This property value SHOULD be preserved in COPY 4252 and MOVE operations. 4254 Description: The DAV:getcontentlanguage property MUST be defined on 4255 any DAV compliant resource that returns the Content-Language 4256 header on a GET. 4258 4260 15.4. getcontentlength Property 4262 Name: getcontentlength 4264 Purpose: Contains the Content-Length header returned by a GET 4265 without accept headers. 4267 Value: See section 14.13 of [RFC2616]. 4269 Protected: This property is computed, therefore protected. 4271 Description: The DAV:getcontentlength property MUST be defined on 4272 any DAV compliant resource that returns the Content-Length header 4273 in response to a GET. 4275 COPY/MOVE behaviour: This property value is dependent on the size of 4276 the destination resource, not the value of the property on the 4277 source resource. 4279 4281 15.5. getcontenttype Property 4283 Name: getcontenttype 4285 Purpose: Contains the Content-Type header value (from section 14.17 4286 of [RFC2616]) as it would be returned by a GET without accept 4287 headers. 4289 Value: media-type (defined in section 3.7 of [RFC2616]) 4291 Protected: Potentially protected if the server prefers to assign 4292 content types on its own (see also discussion in Section 9.7.1). 4294 COPY/MOVE behaviour: This property value SHOULD be preserved in COPY 4295 and MOVE operations. 4297 Description: This property MUST be defined on any DAV compliant 4298 resource that returns the Content-Type header in response to a 4299 GET. 4301 4303 15.6. getetag Property 4305 Name: getetag 4307 Purpose: Contains the ETag header value (from section 14.19 of 4308 [RFC2616]) as it would be returned by a GET without accept 4309 headers. 4311 Value: entity-tag (defined in section 3.11 of [RFC2616]) 4313 Protected: MUST be protected because this value is created and 4314 controlled by the server. 4316 COPY/MOVE behaviour: This property value is dependent on the final 4317 state of the destination resource, not the value of the property 4318 on the source resource. Also note the considerations in 4319 Section 8.8. 4321 Description: The getetag property MUST be defined on any DAV 4322 compliant resource that returns the Etag header. Refer to RFC2616 4323 for a complete definition of the semantics of an ETag, and to 4324 Section 8.6 for a discussion of ETags in WebDAV. 4326 4328 15.7. getlastmodified Property 4330 Name: getlastmodified 4332 Purpose: Contains the Last-Modified header value (from section 14.29 4333 of [RFC2616]) as it would be returned by a GET method without 4334 accept headers. 4336 Value: rfc1123-date (defined in section 3.3.1 of [RFC2616]) 4338 Protected: SHOULD be protected because some clients may rely on the 4339 value for appropriate caching behavior, or on the value of the 4340 Last-Modified header to which this property is linked. 4342 COPY/MOVE behaviour: This property value is dependent on the last 4343 modified date of the destination resource, not the value of the 4344 property on the source resource. Note that some server 4345 implementations use the file system date modified value for the 4346 DAV:getlastmodified value, and this can be preserved in a MOVE 4347 even when the HTTP Last-Modified value SHOULD change. Note that 4348 since [RFC2616] requires clients to use ETags where provided, a 4349 server implementing ETags can count on clients using a much better 4350 mechanism that modification dates for offline synchronization or 4351 cache control. Also note the considerations in Section 8.8. 4353 Description: Note that the last-modified date on a resource SHOULD 4354 only reflect changes in the body (the GET responses) of the 4355 resource. A change in a property only SHOULD NOT cause the last- 4356 modified date to change, because clients MAY rely on the last- 4357 modified date to know when to overwrite the existing body. The 4358 DAV:getlastmodified property MUST be defined on any DAV compliant 4359 resource that returns the Last-Modified header in response to a 4360 GET. 4362 4364 15.8. lockdiscovery Property 4366 Name: lockdiscovery 4368 Purpose: Describes the active locks on a resource 4370 Protected: MUST be protected. Clients change the list of locks 4371 through LOCK and UNLOCK, not through PROPPATCH. 4373 COPY/MOVE behaviour: The value of this property depends on the lock 4374 state of the destination, not on the locks of the source resource. 4375 Recall that locks are not moved in a MOVE operation. 4377 Description: Returns a listing of who has a lock, what type of lock 4378 he has, the timeout type and the time remaining on the timeout, 4379 and the associated lock token. If there are no locks, but the 4380 server supports locks, the property will be present but contain 4381 zero 'activelock' elements. If there is one or more lock, an 4382 'activelock' element appears for each lock on the resource. This 4383 property is NOT lockable with respect to write locks (Section 7). 4385 4387 15.8.1. Example - Retrieving DAV:lockdiscovery 4389 >>Request 4391 PROPFIND /container/ HTTP/1.1 4392 Host: www.example.com 4393 Content-Length: xxxx 4394 Content-Type: application/xml; charset="utf-8" 4396 4397 4398 4399 4401 >>Response 4403 HTTP/1.1 207 Multi-Status 4404 Content-Type: application/xml; charset="utf-8" 4405 Content-Length: xxxx 4407 4408 4409 4410 http://www.example.com/container/ 4411 4412 4413 4414 4415 4416 4417 0 4418 Jane Smith 4419 Infinite 4420 4421 urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76 4423 4424 4425 http://www.example.com/container/ 4426 4427 4428 4429 4430 HTTP/1.1 200 OK 4431 4432 4433 4435 This resource has a single exclusive write lock on it, with an 4436 infinite timeout. 4438 15.9. resourcetype Property 4440 Name: resourcetype 4442 Purpose: Specifies the nature of the resource. 4444 Protected: SHOULD be protected. Resource type is generally decided 4445 through the operation creating the resource (MKCOL vs PUT), not by 4446 PROPPATCH. 4448 COPY/MOVE behaviour: Generally a COPY/MOVE of a resource results in 4449 the same type of resource at the destination. 4451 Description: MUST be defined on all DAV compliant resources. Each 4452 child element identifies a specific type the resource belongs to, 4453 such as 'collection', which is the only resource type defined by 4454 this specification (see Section 14.3). If the element contains 4455 the 'collection' child element plus additional unrecognized 4456 elements, it should generally be treated as a collection. If the 4457 element contains no recognized child elements, it should be 4458 treated as a non-collection resource. The default value is empty. 4459 This element MUST NOT contain text or mixed content. Any custom 4460 child element is considered to be an identifier for a resource 4461 type. 4463 Example: (fictional example to show extensibility) 4465 4466 4467 4468 4470 15.10. supportedlock Property 4472 Name: supportedlock 4474 Purpose: To provide a listing of the lock capabilities supported by 4475 the resource. 4477 Protected: MUST be protected. Servers determine what lock 4478 mechanisms are supported, not clients. 4480 COPY/MOVE behaviour: This property value is dependent on the kind of 4481 locks supported at the destination, not on the value of the 4482 property at the source resource. Servers attempting to COPY to a 4483 destination should not attempt to set this property at the 4484 destination. 4486 Description: Returns a listing of the combinations of scope and 4487 access types which may be specified in a lock request on the 4488 resource. Note that the actual contents are themselves controlled 4489 by access controls so a server is not required to provide 4490 information the client is not authorized to see. This property is 4491 NOT lockable with respect to write locks (Section 7). 4493 4495 15.10.1. Example - Retrieving DAV:supportedlock 4497 >>Request 4499 PROPFIND /container/ HTTP/1.1 4500 Host: www.example.com 4501 Content-Length: xxxx 4502 Content-Type: application/xml; charset="utf-8" 4504 4505 4506 4507 4509 >>Response 4511 HTTP/1.1 207 Multi-Status 4512 Content-Type: application/xml; charset="utf-8" 4513 Content-Length: xxxx 4515 4516 4517 4518 http://www.example.com/container/ 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 HTTP/1.1 200 OK 4533 4534 4535 4537 16. Precondition/postcondition XML elements 4539 As introduced in section Section 8.7, extra information on error 4540 conditions can be included in the body of many status responses. 4541 This section makes requirements on the use of the error body 4542 mechanism and introduces a number of precondition and postcondition 4543 codes. 4545 A "precondition" of a method describes the state of the server that 4546 must be true for that method to be performed. A "postcondition" of a 4547 method describes the state of the server that must be true after that 4548 method has been completed. 4550 Each precondition and postcondition has a unique XML element 4551 associated with it. In a 207 Multi-Status response, the XML element 4552 MUST appear inside an 'error' element in the appropriate 'propstat or 4553 'response' element depending on whether the condition applies to one 4554 or more properties or the resource as a whole. In all other error 4555 responses, the XML element MUST be returned as the child of a top- 4556 level 'error' element in the response body, unless otherwise 4557 negotiated by the request, along with an appropriate response status. 4558 The most common response status codes are 403 (Forbidden) if the 4559 request should not be repeated because it will always fail, and 409 4560 (Conflict) if it is expected that the user might be able to resolve 4561 the conflict and resubmit the request. The 'error' element MAY 4562 contain child elements with specific error information and MAY be 4563 extended with any custom child elements. 4565 This mechanism does not take the place of using a correct numeric 4566 error code as defined here or in HTTP, because the client MUST always 4567 be able to take a reasonable course of action based only on the 4568 numeric error. However, it does remove the need to define new 4569 numeric error codes. The machine-readable codes used for this 4570 purpose are XML elements classified as preconditions and 4571 postconditions, so naturally any group defining a new error code can 4572 use their own namespace. As always, the "DAV:" namespace is reserved 4573 for use by IETF-chartered WebDAV working groups. 4575 A server supporting this specification SHOULD use the XML error 4576 whenever a precondition or postcondition defined in this document is 4577 violated. For error conditions not specified in this document, the 4578 server MAY simply choose an appropriate numeric status and leave the 4579 response body blank. However, a server MAY instead use a custom 4580 error code and other supporting text, because even when clients do 4581 not automatically recognize error codes they can be quite useful in 4582 interoperability testing and debugging. 4584 Example - Response with precondition code" 4585 >>Response 4587 HTTP/1.1 423 Locked 4588 Content-Type: application/xml; charset="utf-8" 4589 Content-Length: xxxx 4591 4592 4593 4594 /workspace/webdav/ 4595 4596 4598 In this example, a client unaware of a "Depth: infinity" lock on the 4599 parent collection "/workspace/webdav/" attempted to modify the 4600 collection member "/workspace/webdav/proposal.doc". 4602 Some other useful preconditions and postconditions have been defined 4603 in other specifications extending WebDAV, such as [RFC3744] (see 4604 particularly section 7.1.1), [RFC3253], and [RFC3648]. 4606 All these elements are in the "DAV:" namespace. 4608 Name: lock-token-matches-request-uri 4610 Use with: 409 Conflict 4612 Purpose: (precondition) -- A request may include a Lock-Token header 4613 to identify a lock for the purposes of an operation such as 4614 refresh LOCK or UNLOCK. However, if the Request-URI does not fall 4615 within the scope of the lock identified by the token, the server 4616 SHOULD use this error. The lock may have a scope that does not 4617 include the Request-URI, or the lock could have disappeared, or 4618 the token may be invalid. 4620 4622 Name: lock-token-submitted (precondition) 4624 Use with: 423 Locked 4626 Purpose: The request could not succeed because a lock token should 4627 have been submitted. This element, if present, MUST contain at 4628 least one URL of a locked resource that prevented the request. In 4629 cases of MOVE, COPY and DELETE where collection locks are 4630 involved, it can be difficult for the client to find out which 4631 locked resource made the request fail -- but the server is only 4632 resonsible for returning one such locked resource. The server MAY 4633 return every locked resource that prevented the request from 4634 succeeding if it knows them all. 4636 4638 Name: no-conflicting-lock (precondition) 4640 Use with: Typically 423 Locked 4642 Purpose: A LOCK request failed due the presence of an already 4643 existing conflicting lock. Note that a lock can be in conflict 4644 although the resource to which the request was directed is only 4645 indirectly locked. In this case, the precondition code can be 4646 used to inform the client about the resource which is the root of 4647 the conflicting lock, avoiding a separate lookup of the 4648 "lockdiscovery" property. 4650 4652 Name: no-external-entities 4654 Use with: 403 Forbidden 4656 Purpose: (precondition) -- If the server rejects a client request 4657 because the request body contains an external entity, the server 4658 SHOULD use this error. 4660 4662 Name: preserved-live-properties 4664 Use with: 409 Conflict 4666 Purpose: (postcondition) -- The server received an otherwise-valid 4667 MOVE or COPY request, but cannot maintain the live properties with 4668 the same behavior at the destination. It may be that the server 4669 only supports some live properties in some parts of the 4670 repository, or simply has an internal error. 4672 4674 Name: propfind-finite-depth 4676 Use with: 403 Forbidden 4677 Purpose: (precondition) -- This server does not allow infinite-depth 4678 PROPFIND requests on collections. 4680 4682 Name: cannot-modify-protected-property 4684 Use with: 403 Forbidden 4686 Purpose: (precondition) -- The client attempted to set a read-only 4687 property in a PROPPATCH (such as DAV:getetag). 4689 4691 17. XML Extensibility in DAV 4693 The XML namespace extension ([REC-XML-NAMES]) is used in this 4694 specification in order to allow for new XML elements to be added 4695 without fear of colliding with other element names. Although WebDAV 4696 request and response bodies can be extended by arbitrary XML 4697 elements, which can be ignored by the message recipient, an XML 4698 element in the "DAV:" namespace SHOULD NOT be used in the request or 4699 response body unless that XML element is explicitly defined in an 4700 IETF RFC reviewed by a WebDAV working group. 4702 For WebDAV to be both extensibile and backwards-compatible, both 4703 clients and servers need to know how to behave when unexpected or 4704 unrecognized command extensions are received. For XML processing, 4705 this means that clients and servers MUST process received XML 4706 documents as if unexpected elements and attributes (and all children 4707 of unrecognized elements) were not there. An unexpected element or 4708 attribute includes one which may be used in another context but is 4709 not expected here. Ignoring such items for purposes of processing 4710 can of course be consistent with logging all information or 4711 presenting for debugging. 4713 This restriction also applies to the processing, by clients, of DAV 4714 property values where unexpected XML elements SHOULD be ignored 4715 unless the property's schema declares otherwise. 4717 This restriction does not apply to setting dead DAV properties on the 4718 server where the server MUST record all XML elements. 4720 Additionally, this restriction does not apply to the use of XML where 4721 XML happens to be the content type of the entity body, for example, 4722 when used as the body of a PUT. 4724 Processing instructions in XML SHOULD be ignored by recipients. 4725 Thus, specifications extending WebDAV SHOULD NOT use processing 4726 instructions to define normative behavior. 4728 XML DTD fragments are included for all the XML elements defined in 4729 this specification. However, correct XML will not be valid according 4730 to any DTD due to namespace usage and extension rules. In 4731 particular: 4733 o All elements defined in this specification use the "DAV:" 4734 namespace, 4736 o Element ordering is irrelevant unless otherwise stated, 4737 o Extension attributes MAY be added, 4739 o For element type definitions of "ANY", the normative text 4740 definition for that element defines what can be in it and what 4741 that means. 4743 o For element type definitions of "#PCDATA", extension elements MUST 4744 NOT be added. 4746 o For other element type definitions, including "EMPTY", extension 4747 elements MAY be added. 4749 Note that this means that elements containing elements cannot be 4750 extended to contain text, and vice versa. 4752 With DTD validation relaxed by the rules above, the constraints 4753 described by the DTD fragments are normative (see for example 4754 Appendix A A recipient of a WebDAV message with an XML body MUST NOT 4755 validate the XML document according to any hard-coded or dynamically- 4756 declared DTD. 4758 Note that this section describes backwards-compatible extensibility 4759 rules. There might also be times when an extension is designed not 4760 to be backwards-compatible, for example defining an extension that 4761 reuses an XML element defined in this document but omitting one of 4762 the child elements required by the DTDs in this specification. 4764 18. DAV Compliance Classes 4766 A DAV compliant resource can advertise several classes of compliance. 4767 A client can discover the compliance classes of a resource by 4768 executing OPTIONS on the resource, and examining the "DAV" header 4769 which is returned. Note particularly that resources are spoken of as 4770 being compliant, rather than servers. That is because theoretically 4771 some resources on a server could support different feature sets. 4772 E.g. a server could have a sub-repository where an advanced feature 4773 like server was supported, even if that feature was not supported on 4774 all servers. 4776 Since this document describes extensions to the HTTP/1.1 protocol, 4777 minimally all DAV compliant resources, clients, and proxies MUST be 4778 compliant with [RFC2616]. 4780 A resource that is class 2 compliant must also be class 1 compliant, 4781 and a resource that is class 3 compliant must also be class 1 4782 compliant. 4784 18.1. Class 1 4786 A class 1 compliant resource MUST meet all "MUST" requirements in all 4787 sections of this document. 4789 Class 1 compliant resources MUST return, at minimum, the value "1" in 4790 the DAV header on all responses to the OPTIONS method. 4792 18.2. Class 2 4794 A class 2 compliant resource MUST meet all class 1 requirements and 4795 support the LOCK method, the DAV:supportedlock property, the DAV: 4796 lockdiscovery property, the Time-Out response header and the Lock- 4797 Token request header. A class "2" compliant resource SHOULD also 4798 support the Time-Out request header and the 'owner' XML element. 4800 Class 2 compliant resources MUST return, at minimum, the values "1" 4801 and "2" in the DAV header on all responses to the OPTIONS method. 4803 18.3. Class 3 4805 A resource can explicitly advertise its support for the revisions to 4806 [RFC2518] made in this document. Class 1 MUST be supported as well. 4807 Class 2 MAY be supported. Advertising class 3 support in addition to 4808 class 1 and 2 means that the server supports all the requirements in 4809 this specification. Advertising class 3 and class 1 support, but not 4810 class 2, means that the server supports all the requirements in this 4811 specification except possibly those that involve locking support. 4813 Example: 4815 DAV: 1, 3 4817 19. Internationalization Considerations 4819 In the realm of internationalization, this specification complies 4820 with the IETF Character Set Policy [RFC2277]. In this specification, 4821 human-readable fields can be found either in the value of a property, 4822 or in an error message returned in a response entity body. In both 4823 cases, the human-readable content is encoded using XML, which has 4824 explicit provisions for character set tagging and encoding, and 4825 requires that XML processors read XML elements encoded, at minimum, 4826 using the UTF-8 [RFC3629] and UTF-16 encodings of the ISO 10646 4827 multilingual plane. XML examples in this specification demonstrate 4828 use of the charset parameter of the Content-Type header, as defined 4829 in [RFC3023], as well as the XML declarations which provide charset 4830 identification information for MIME and XML processors. 4832 XML also provides a language tagging capability for specifying the 4833 language of the contents of a particular XML element. The "xml:lang" 4834 attribute appears on an XML element to identify the language of its 4835 content and attributes. See [REC-XML] for definitions of values and 4836 scoping. 4838 WebDAV applications MUST support the character set tagging, character 4839 set encoding, and the language tagging functionality of the XML 4840 specification. Implementors of WebDAV applications are strongly 4841 encouraged to read "XML Media Types" [RFC3023] for instruction on 4842 which MIME media type to use for XML transport, and on use of the 4843 charset parameter of the Content-Type header. 4845 Names used within this specification fall into four categories: names 4846 of protocol elements such as methods and headers, names of XML 4847 elements, names of properties, and names of conditions. Naming of 4848 protocol elements follows the precedent of HTTP, using English names 4849 encoded in USASCII for methods and headers. Since these protocol 4850 elements are not visible to users, and are simply long token 4851 identifiers, they do not need to support multiple languages. 4852 Similarly, the names of XML elements used in this specification are 4853 not visible to the user and hence do not need to support multiple 4854 languages. 4856 WebDAV property names are qualified XML names (pairs of XML namespace 4857 name and local name). Although some applications (e.g., a generic 4858 property viewer) will display property names directly to their users, 4859 it is expected that the typical application will use a fixed set of 4860 properties, and will provide a mapping from the property name and 4861 namespace to a human-readable field when displaying the property name 4862 to a user. It is only in the case where the set of properties is not 4863 known ahead of time that an application need display a property name 4864 to a user. We recommend that applications provide human-readable 4865 property names wherever feasible. 4867 For error reporting, we follow the convention of HTTP/1.1 status 4868 codes, including with each status code a short, English description 4869 of the code (e.g., 423 (Locked)). While the possibility exists that 4870 a poorly crafted user agent would display this message to a user, 4871 internationalized applications will ignore this message, and display 4872 an appropriate message in the user's language and character set. 4874 Since interoperation of clients and servers does not require locale 4875 information, this specification does not specify any mechanism for 4876 transmission of this information. 4878 20. Security Considerations 4880 This section is provided to detail issues concerning security 4881 implications of which WebDAV applications need to be aware. 4883 All of the security considerations of HTTP/1.1 (discussed in 4884 [RFC2616]) and XML (discussed in [RFC3023]) also apply to WebDAV. In 4885 addition, the security risks inherent in remote authoring require 4886 stronger authentication technology, introduce several new privacy 4887 concerns, and may increase the hazards from poor server design. 4888 These issues are detailed below. 4890 20.1. Authentication of Clients 4892 Due to their emphasis on authoring, WebDAV servers need to use 4893 authentication technology to protect not just access to a network 4894 resource, but the integrity of the resource as well. Furthermore, 4895 the introduction of locking functionality requires support for 4896 authentication. 4898 A password sent in the clear over an insecure channel is an 4899 inadequate means for protecting the accessibility and integrity of a 4900 resource as the password may be intercepted. Since Basic 4901 authentication for HTTP/1.1 performs essentially clear text 4902 transmission of a password, Basic authentication MUST NOT be used to 4903 authenticate a WebDAV client to a server unless the connection is 4904 secure. Furthermore, a WebDAV server MUST NOT send Basic 4905 authentication credentials in a WWW-Authenticate header unless the 4906 connection is secure. Examples of secure connections include a 4907 Transport Layer Security (TLS) connection employing a strong cipher 4908 suite with mutual authentication of client and server, or a 4909 connection over a network which is physically secure, for example, an 4910 isolated network in a building with restricted access. 4912 WebDAV applications MUST support the Digest authentication scheme 4913 [RFC2617]. Since Digest authentication verifies that both parties to 4914 a communication know a shared secret, a password, without having to 4915 send that secret in the clear, Digest authentication avoids the 4916 security problems inherent in Basic authentication while providing a 4917 level of authentication which is useful in a wide range of scenarios. 4919 20.2. Denial of Service 4921 Denial of service attacks are of special concern to WebDAV servers. 4922 WebDAV plus HTTP enables denial of service attacks on every part of a 4923 system's resources. 4925 o The underlying storage can be attacked by PUTting extremely large 4926 files. 4928 o Asking for recursive operations on large collections can attack 4929 processing time. 4931 o Making multiple pipelined requests on multiple connections can 4932 attack network connections. 4934 WebDAV servers need to be aware of the possibility of a denial of 4935 service attack at all levels. The proper response to such an attack 4936 MAY be to simply drop the connection, or if the server is able to 4937 make a response, the server MAY use a 400-level status request such 4938 as 400 (Bad Request) and indicate why the request was refused (a 500- 4939 level status response would indicate that the problem is with the 4940 server, whereas unintentional DOS attacks are something the client is 4941 capable of remedying). 4943 20.3. Security through Obscurity 4945 WebDAV provides, through the PROPFIND method, a mechanism for listing 4946 the member resources of a collection. This greatly diminishes the 4947 effectiveness of security or privacy techniques that rely only on the 4948 difficulty of discovering the names of network resources. Users of 4949 WebDAV servers are encouraged to use access control techniques to 4950 prevent unwanted access to resources, rather than depending on the 4951 relative obscurity of their resource names. 4953 20.4. Privacy Issues Connected to Locks 4955 When submitting a lock request a user agent may also submit an 4956 'owner' XML field giving contact information for the person taking 4957 out the lock (for those cases where a person, rather than a robot, is 4958 taking out the lock). This contact information is stored in a DAV: 4959 lockdiscovery property on the resource, and can be used by other 4960 collaborators to begin negotiation over access to the resource. 4961 However, in many cases this contact information can be very private, 4962 and should not be widely disseminated. Servers SHOULD limit read 4963 access to the DAV:lockdiscovery property as appropriate. 4964 Furthermore, user agents SHOULD provide control over whether contact 4965 information is sent at all, and if contact information is sent, 4966 control over exactly what information is sent. 4968 20.5. Privacy Issues Connected to Properties 4970 Since property values are typically used to hold information such as 4971 the author of a document, there is the possibility that privacy 4972 concerns could arise stemming from widespread access to a resource's 4973 property data. To reduce the risk of inadvertent release of private 4974 information via properties, servers are encouraged to develop access 4975 control mechanisms that separate read access to the resource body and 4976 read access to the resource's properties. This allows a user to 4977 control the dissemination of their property data without overly 4978 restricting access to the resource's contents. 4980 20.6. Implications of XML Entities 4982 XML supports a facility known as "external entities", defined in 4983 section 4.2.2 of [REC-XML], which instruct an XML processor to 4984 retrieve and include additional XML. An external XML entity can be 4985 used to append or modify the document type declaration (DTD) 4986 associated with an XML document. An external XML entity can also be 4987 used to include XML within the content of an XML document. For non- 4988 validating XML, such as the XML used in this specification, including 4989 an external XML entity is not required by XML. However, XML does 4990 state that an XML processor may, at its discretion, include the 4991 external XML entity. 4993 External XML entities have no inherent trustworthiness and are 4994 subject to all the attacks that are endemic to any HTTP GET request. 4995 Furthermore, it is possible for an external XML entity to modify the 4996 DTD, and hence affect the final form of an XML document, in the worst 4997 case significantly modifying its semantics, or exposing the XML 4998 processor to the security risks discussed in [RFC3023]. Therefore, 4999 implementers must be aware that external XML entities should be 5000 treated as untrustworthy. If a server implementor chooses not to 5001 handle external XML entities, it SHOULD respond to requests 5002 containing external entities with the precondition defined above (no- 5003 external-entities). 5005 There is also the scalability risk that would accompany a widely 5006 deployed application which made use of external XML entities. In 5007 this situation, it is possible that there would be significant 5008 numbers of requests for one external XML entity, potentially 5009 overloading any server which fields requests for the resource 5010 containing the external XML entity. 5012 Furthermore, there's also a risk based on the evaluation of "internal 5013 entities" as defined in section 4.2.2 of [REC-XML]. A small, 5014 carefully crafted request using nested internal entities may require 5015 enormous amounts of memory and/or processing time to process. Server 5016 implementors should be aware of this risk and configure their XML 5017 parsers so that requests like these can be detected and rejected as 5018 early as possible. 5020 20.7. Risks Connected with Lock Tokens 5022 This specification encourages the use of "A Universally Unique 5023 Identifier (UUID) URN Namespace" ([RFC4122]) for lock tokens 5024 Section 6.5, in order to guarantee their uniqueness across space and 5025 time. Version 1 UUIDs (defined in section 4) MAY contain a "node" 5026 field that "consists of an IEEE 802 MAC address, usually the host 5027 address. For systems with multiple IEEE addresses, any available one 5028 can be used". Since a WebDAV server will issue many locks over its 5029 lifetime, the implication is that it may also be publicly exposing 5030 its IEEE 802 address. 5032 There are several risks associated with exposure of IEEE 802 5033 addresses. Using the IEEE 802 address: 5035 o It is possible to track the movement of hardware from subnet to 5036 subnet. 5038 o It may be possible to identify the manufacturer of the hardware 5039 running a WebDAV server. 5041 o It may be possible to determine the number of each type of 5042 computer running WebDAV. 5044 This risk only applies to host address based UUID versions. Section 5045 4 of [RFC4122] describes several other mechanisms for generating 5046 UUIDs that do involve the host address and therefore do not suffer 5047 from this risk. 5049 20.8. Hosting Malicious Content 5051 HTTP has the ability to host programs which are executed on client 5052 machines. These programs can take many forms including web scripts, 5053 executables, plug in modules, and macros in documents. WebDAV does 5054 not change any of the security concerns around these programs yet 5055 often WebDAV is used in contexts where a wide range of users can 5056 publish documents on a server. The server might not have a close 5057 trust relationship with the author that is publishing the document. 5058 Servers that allow clients to publish arbitrary content can usefully 5059 implement precautions to check that content published to the server 5060 is not harmful to other clients. Servers could do this by techniques 5061 such as restricting the types of content that is allowed to be 5062 published and running virus and malware detection software on 5063 published content. Servers can also mitigate the risk by having 5064 appropriate access restriction and authentication of users that are 5065 allowed to publish content to the server. 5067 21. IANA Considerations 5069 21.1. New URI Schemes 5071 This specification defines two URI schemes: 5073 1. the "opaquelocktoken" scheme defined in Appendix C, and 5075 2. the "DAV" URI scheme, which historically was used in [RFC2518] to 5076 disambiguate WebDAV property and XML element names and which 5077 continues to be used for that purpose in this specification and 5078 others extending WebDAV. Creation of identifiers in the "DAV:" 5079 namespace is controlled by the IETF. 5081 Note that defining new URI schemes for XML namespaces is now 5082 discouraged. "DAV:" was defined before standard best practices 5083 emerged. 5085 21.2. XML Namespaces 5087 XML namespaces disambiguate WebDAV property names and XML elements. 5088 Any WebDAV user or application can define a new namespace in order to 5089 create custom properties or extend WebDAV XML syntax. IANA does not 5090 need to manage such namespaces, property names or element names. 5092 21.3. Message Header Fields 5094 The message header fields below should be added to the permanent 5095 registry (see [RFC3864]). 5097 21.3.1. DAV 5099 Header field name: DAV 5101 Applicable protocol: http 5103 Status: standard 5105 Author/Change controller: IETF 5107 Specification document: this specification (Section 10.1) 5109 21.3.2. Depth 5111 Header field name: Depth 5113 Applicable protocol: http 5114 Status: standard 5116 Author/Change controller: IETF 5118 Specification document: this specification (Section 10.2) 5120 21.3.3. Destination 5122 Header field name: Destination 5124 Applicable protocol: http 5126 Status: standard 5128 Author/Change controller: IETF 5130 Specification document: this specification (Section 10.3) 5132 21.3.4. If 5134 Header field name: If 5136 Applicable protocol: http 5138 Status: standard 5140 Author/Change controller: IETF 5142 Specification document: this specification (Section 10.4) 5144 21.3.5. Lock-Token 5146 Header field name: Lock-Token 5148 Applicable protocol: http 5150 Status: standard 5152 Author/Change controller: IETF 5154 Specification document: this specification (Section 10.5) 5156 21.3.6. Overwrite 5158 Header field name: Overwrite 5160 Applicable protocol: http 5161 Status: standard 5163 Author/Change controller: IETF 5165 Specification document: this specification (Section 10.6) 5167 21.3.7. Timeout 5169 Header field name: Timeout 5171 Applicable protocol: http 5173 Status: standard 5175 Author/Change controller: IETF 5177 Specification document: this specification (Section 10.7) 5179 22. Acknowledgements 5181 A specification such as this thrives on piercing critical review and 5182 withers from apathetic neglect. The authors gratefully acknowledge 5183 the contributions of the following people, whose insights were so 5184 valuable at every stage of our work. 5186 Contributors to RFC2518 5188 Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan 5189 Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners- 5190 Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith 5191 Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee 5192 Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan 5193 Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis 5194 Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der 5195 Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven 5196 Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten, 5197 Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff, 5198 Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike 5199 Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi, 5200 Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran, 5201 Fabio Vitali, Gregory Woodhouse, and Lauren Wood. 5203 Two from this list deserve special mention. The contributions by 5204 Larry Masinter have been invaluable, both in helping the formation of 5205 the working group and in patiently coaching the authors along the 5206 way. In so many ways he has set high standards we have toiled to 5207 meet. The contributions of Judith Slein in clarifying the 5208 requirements, and in patiently reviewing draft after draft, both 5209 improved this specification and expanded our minds on document 5210 management. 5212 We would also like to thank John Turner for developing the XML DTD. 5214 The authors of RFC2518 were Yaron Goland, Jim Whitehead, A. Faizi, 5215 Steve Carter and D. Jensen. Although their names had to be removed 5216 due to IETF author count restrictions they can take credit for the 5217 majority of the design of WebDAV. 5219 Additional Acknowledgements for This Specification 5221 Significant contributors of text for this specification are listed as 5222 contributors in the section below. We must also gratefully 5223 acknowledge Geoff Clemm, Joel Soderberg, and Dan Brotsky for hashing 5224 out specific text on the list or in meetings. Joe Hildebrand and 5225 Cullen Jennings helped close many issues. Barry Lind described an 5226 additional security consideration and Cullen Jennings provided text 5227 for that consideration. Jason Crawford tracked issue status for this 5228 document for a period of years, followed by Elias Sinderson. 5230 23. Contributors to This Specification 5232 Julian Reschke, 5233 bytes GmbH, 5234 Hafenweg 16, 48155 Muenster, Germany, 5235 Email: julian.reschke@greenbytes.de 5237 Elias Sinderson 5238 University of California, Santa Cruz 5239 1156 High Street, Santa Cruz, CA 95064 5240 Email: elias@cse.ucsc.edu 5242 Jim Whitehead, 5243 University of California, Santa Cruz 5244 1156 High Street, Santa Cruz, CA 95064 5245 Email: ejw@soe.ucsc.edu 5247 24. Authors of RFC2518 5249 Y. Y. Goland, 5250 Microsoft Corporation, 5251 One Microsoft Way, 5252 Redmond, WA 98052-6399. 5253 Email: yarong@microsoft.com. 5255 E. J. Whitehead, Jr., 5256 Dept. Of Information and Computer Science, 5257 University of California, Irvine, 5258 Irvine, CA 92697-3425. 5259 Email: ejw@ics.uci.edu. 5261 A. Faizi, 5262 Netscape, 5263 685 East Middlefield Road, 5264 Mountain View, CA 94043. 5265 Email: asad@netscape.com. 5267 S. R. Carter, 5268 Novell, 5269 1555 N. Technology Way, 5270 M/S ORM F111, 5271 Orem, UT 84097-2399. 5272 Email: srcarter@novell.com. 5274 D. Jensen, 5275 Novell, 5276 1555 N. Technology Way, 5277 M/S ORM F111, 5278 Orem, UT 84097-2399. 5279 Email: dcjensen@novell.com. 5281 25. References 5283 25.1. Normative References 5285 [REC-XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 5286 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Third 5287 Edition)", W3C REC-xml-20040204, February 2004, 5288 . 5290 [REC-XML-INFOSET] 5291 Cowan, J. and R. Tobin, "XML Information Set (Second 5292 Edition)", W3C REC-xml-infoset-20040204, February 2004, 5293 . 5295 [REC-XML-NAMES] 5296 Bray, T., Hollander, D., and A. Layman, "Namespaces in 5297 XML", W3C REC-xml-names-19990114, January 1999, 5298 . 5300 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5301 Requirement Levels", BCP 14, RFC 2119, March 1997. 5303 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 5304 Languages", BCP 18, RFC 2277, January 1998. 5306 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 5307 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 5308 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 5310 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 5311 Leach, P., Luotonen, A., and L. Stewart, "HTTP 5312 Authentication: Basic and Digest Access Authentication", 5313 RFC 2617, June 1999. 5315 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 5316 Timestamps", RFC 3339, July 2002. 5318 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 5319 10646", STD 63, RFC 3629, November 2003. 5321 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 5322 Resource Identifier (URI): Generic Syntax", STD 66, 5323 RFC 3986, January 2005. 5325 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 5326 Unique IDentifier (UUID) URN Namespace", RFC 4122, 5327 July 2005. 5329 25.2. Informational References 5331 [I-D.draft-whitehead-http-etag] 5332 Whitehead, J., "ETags in HTTP PUT Responses", 5333 draft-whitehead-http-etag-00 (work in progress), 5334 February 2006. 5336 [RFC2291] Slein, J., Vitali, F., Whitehead, E., and D. Durand, 5337 "Requirements for a Distributed Authoring and Versioning 5338 Protocol for the World Wide Web", RFC 2291, February 1998. 5340 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 5341 Jensen, "HTTP Extensions for Distributed Authoring -- 5342 WEBDAV", RFC 2518, February 1999. 5344 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 5345 Types", RFC 3023, January 2001. 5347 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 5348 Whitehead, "Versioning Extensions to WebDAV (Web 5349 Distributed Authoring and Versioning)", RFC 3253, 5350 March 2002. 5352 [RFC3648] Whitehead, J. and J. Reschke, Ed., "Web Distributed 5353 Authoring and Versioning (WebDAV) Ordered Collections 5354 Protocol", RFC 3648, December 2003. 5356 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web 5357 Distributed Authoring and Versioning (WebDAV) Access 5358 Control Protocol", RFC 3744, May 2004. 5360 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 5361 Procedures for Message Header Fields", BCP 90, RFC 3864, 5362 September 2004. 5364 Appendix A. Notes on Processing XML Elements 5366 A.1. Notes on Empty XML Elements 5368 XML supports two mechanisms for indicating that an XML element does 5369 not have any content. The first is to declare an XML element of the 5370 form . The second is to declare an XML element of the form 5371 . The two XML elements are semantically identical. 5373 A.2. Notes on Illegal XML Processing 5375 XML is a flexible data format that makes it easy to submit data that 5376 appears legal but in fact is not. The philosophy of "Be flexible in 5377 what you accept and strict in what you send" still applies, but it 5378 must not be applied inappropriately. XML is extremely flexible in 5379 dealing with issues of white space, element ordering, inserting new 5380 elements, etc. This flexibility does not require extension, 5381 especially not in the area of the meaning of elements. 5383 There is no kindness in accepting illegal combinations of XML 5384 elements. At best it will cause an unwanted result and at worst it 5385 can cause real damage. 5387 A.3. Example - XML Syntax Error 5389 The following request body for a PROPFIND method is illegal. 5391 5392 5393 5394 5395 5397 The definition of the propfind element only allows for the allprop or 5398 the propname element, not both. Thus the above is an error and must 5399 be responded to with a 400 (Bad Request). 5401 Imagine, however, that a server wanted to be "kind" and decided to 5402 pick the allprop element as the true element and respond to it. A 5403 client running over a bandwidth limited line who intended to execute 5404 a propname would be in for a big surprise if the server treated the 5405 command as an allprop. 5407 Additionally, if a server were lenient and decided to reply to this 5408 request, the results would vary randomly from server to server, with 5409 some servers executing the allprop directive, and others executing 5410 the propname directive. This reduces interoperability rather than 5411 increasing it. 5413 A.4. Example - Unexpected XML Element 5415 The previous example was illegal because it contained two elements 5416 that were explicitly banned from appearing together in the propfind 5417 element. However, XML is an extensible language, so one can imagine 5418 new elements being defined for use with propfind. Below is the 5419 request body of a PROPFIND and, like the previous example, must be 5420 rejected with a 400 (Bad Request) by a server that does not 5421 understand the expired-props element. 5423 5424 5426 5427 5429 To understand why a 400 (Bad Request) is returned let us look at the 5430 request body as the server unfamiliar with expired-props sees it. 5432 5433 5435 5437 As the server does not understand the 'expired-props' element, 5438 according to the WebDAV-specific XML processing rules specified in 5439 Section 17, it must process the request as if the element were not 5440 there. Thus the server sees an empty propfind, which by the 5441 definition of the propfind element is illegal. 5443 Please note that had the extension been additive it would not 5444 necessarily have resulted in a 400 (Bad Request). For example, 5445 imagine the following request body for a PROPFIND: 5447 5448 5450 5451 *boss* 5452 5454 The previous example contains the fictitious element leave-out. Its 5455 purpose is to prevent the return of any property whose name matches 5456 the submitted pattern. If the previous example were submitted to a 5457 server unfamiliar with 'leave-out', the only result would be that the 5458 'leave-out' element would be ignored and a propname would be 5459 executed. 5461 Appendix B. Notes on HTTP Client Compatibility 5463 WebDAV was designed to be, and has been found to be, backward- 5464 compatible with HTTP 1.1. The PUT and DELETE methods are defined in 5465 HTTP and thus may be used by HTTP clients as well as WebDAV-aware 5466 clients, but the responses to PUT and DELETE have been extended in 5467 this specification in ways that only a WebDAV client would be 5468 entirely prepared for. Some theoretical concerns were raised about 5469 whether those responses would cause interoperability problems with 5470 HTTP-only clients, and this section addresses those concerns. 5472 Since any HTTP client ought to handle unrecognized 400-level and 500- 5473 level status codes as errors, the following new status codes should 5474 not present any issues: 422, 423 and 507 (424 is also a new status 5475 code but it appears only in the body of a Multistatus response.) So, 5476 for example, if a HTTP client attempted to PUT or DELETE a locked 5477 resource, the 423 Locked response ought to result in a generic error 5478 presented to the user. 5480 The 207 Multistatus response is interesting because a HTTP client 5481 issuing a DELETE request to a collection might interpret a 207 5482 response as a success, even though it does not realize the resource 5483 is a collection and cannot understand that the DELETE operation might 5484 have been a complete or partial failure. That interpretation isn't 5485 entirely justified, because a 200-level response indicates that the 5486 server "received, understood and accepted" the request, not that the 5487 request resulted in complete success. 5489 One option is that a server could treat a DELETE of a collection as 5490 an atomic operation, and use either 204 No Content in case of 5491 success, or some appropriate error response (400 or 500 level) for an 5492 error. This approach would indeed maximize backward compatibility. 5493 However, since interoperability tests and working group discussions 5494 have not turned up any instances of HTTP clients issuing a DELETE 5495 request against a WebDAV collection, this concern is more theoretical 5496 than practical. Thus, servers are likely to be completely successful 5497 at interoperating with HTTP clients even if they treat any collection 5498 DELETE request as a WebDAV request and send a 207 Multistatus 5499 response. 5501 In general server implementations are encouraged to use the detailed 5502 responses and other mechanisms defined in this document rather than 5503 make changes for theoretical interoperability concerns. 5505 Appendix C. The opaquelocktoken scheme and URIs 5507 The 'opaquelocktoken' URI scheme was defined in [RFC2518] (and 5508 registered by IANA) in order to create syntactically correct and 5509 easy-to-generate URIs out of UUIDs, intended to be used as lock 5510 tokens and to be unique across all resources for all time. 5512 An opaquelocktoken URI is constructed by concatenating the 5513 'opaquelocktoken' scheme with a UUID, along with an optional 5514 extension. Servers can create new UUIDs for each new lock token. If 5515 a server wishes to reuse UUIDs the server MUST add an extension and 5516 the algorithm generating the extension MUST guarantee that the same 5517 extension will never be used twice with the associated UUID. 5519 OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] 5520 ; UUID is defined in section 3 of RFC4122. Note that linear white 5521 ; space (LWS) is not allowed between elements of this production. 5523 Extension = path 5524 ; path is defined in section 3.3 of RFC3986 5526 Appendix D. Guidance for Clients Desiring to Authenticate 5528 Many WebDAV clients already implemented have account settings 5529 (similar to the way email clients store IMAP account settings). 5530 Thus, the WebDAV client would be able to authenticate with its first 5531 couple requests to the server, provided it had a way to get the 5532 authentication challenge from the server with realm name, nonce and 5533 other challenge information. Note that the results of some requests 5534 might vary according to whether the client is authenticated or not -- 5535 a PROPFIND might return more visible resources if the client is 5536 authenticated, yet not fail if the client is anonymous. 5538 There are a number of ways the client might be able to trigger the 5539 server do provide an authentication challenge. This appendix 5540 describes a couple approaches that seem particularly likely to work. 5542 The first approach is to perform a request that ought to require 5543 authentication. However, it's possible that a server might handle 5544 any request even without authentication, so to be entirely safe the 5545 client could add a conditional header to ensure that even if the 5546 request passes permissions checks it's not actually handled by the 5547 server. An example of following this approach would be to use a PUT 5548 request with an "If-Match" header with a made-up ETag value. This 5549 approach might fail to result in an authentication challenge if the 5550 server does not test authorization before testing conditionals as is 5551 required (see Section 8.5), or if the server does not need to test 5552 authorization. 5554 Example - forcing auth challenge with write request 5556 >>Request 5558 PUT /forceauth.txt HTTP/1.1 5559 Host: www.example.com 5560 If-Match: "xxx" 5561 Content-Type: text/plain 5562 Content-Length: 0 5564 The second approach is to use an Authorization header (defined in 5565 [RFC2617]) which is likely to be rejected by the server but which 5566 will then prompt a proper authentication challenge. For example, the 5567 client could start with a PROPFIND request containing an 5568 Authorization header containing a made-up Basic userid:password 5569 string or with actual plausible credentials. This approach relies on 5570 the server responding with a "401 Unauthorized" along with a 5571 challenge if it receives an Authorization header with an unrecognized 5572 username, invalid password, or if it doesn't even handle Basic 5573 authentication. This seems likely to work because of the 5574 requirements of RFC2617: 5576 "If the origin server does not wish to accept the credentials sent 5577 with a request, it SHOULD return a 401 (Unauthorized) response. The 5578 response MUST include a WWW-Authenticate header field containing at 5579 least one (possibly new) challenge applicable to the requested 5580 resource." 5582 There's a slight problem with implementing that recommendation in 5583 some cases, because some servers do not even have challenge 5584 information for certain resources. Thus, when there's no way to 5585 authenticate to a resource or the resource is entirely publicly 5586 available over all accepted methods, the server MAY ignore the 5587 Authorization header, and the client presumably try again later. 5589 Example - forcing auth challenge with Authorization header 5591 >>Request 5593 PROPFIND /docs/ HTTP/1.1 5594 Host: www.example.com 5595 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 5596 Content-type: application/xml; charset="utf-8" 5597 Content-Length: xxxx 5599 [body omitted] 5601 Appendix E. Summary of changes from RFC2518 5603 This section lists major changes between this document and RFC2518, 5604 starting with those that are likely to result in implementation 5605 changes. Servers will advertise support for all changes in this 5606 specification by returning the compliance class "3" in the DAV 5607 response header (see Sections 10.1 and 18.3). 5609 E.1. Changes for both Client and Server Implementations 5611 Collections and Namespace Operations 5613 o The semantics of PROPFIND 'allprop' (Section 9.1) have been 5614 relaxed so that servers may leave out live properties defined in 5615 other specifications, such as [RFC3253] and [RFC3744]. Related to 5616 this, 'allprop' requests can now be extended with the 'include' 5617 syntax to include specific named properties, thereby avoiding 5618 additional requests due to changed 'allprop' semantics. 5620 o Servers are now allowed to reject PROPFIND requests with Depth: 5621 Infinity. Clients that used this will need to be able to do a 5622 series of Depth:1 requests instead. 5624 o Multistatus response bodies now can transport the value of HTTP's 5625 Location response header in the new 'location' element. Clients 5626 may use this to avoid additional roundtrips to the server when 5627 there is a 'response' element with a 3xx status (see 5628 Section 14.24). 5630 o The definition of COPY has been relaxed so that it doesn't require 5631 servers to first delete the target resources anymore (this was a 5632 known incompatibility with [RFC3253]). See Section 9.8. 5634 Headers and Marshalling 5636 o The Destination and If request headers now allow absolute paths in 5637 addition to full URIs (see Section 8.3). This may be useful for 5638 clients operating through a reverse proxy that does rewrite the 5639 Host request header, but not WebDAV-specific headers. 5641 o This specification adopts the error marshalling extensions and the 5642 "precondition/postcondition" terminology defined in [RFC3253] (see 5643 Section 16). Related to that, it adds the "error" XML element 5644 inside multistatus response bodies (see Section 14.5, however note 5645 that it uses a format different from the one recommend in 5646 RFC3253). 5648 o Senders and recipients are now required to support the UTF-16 5649 character encoding in XML message bodies (see Section 19). 5651 Locking 5653 o RFC2518's concept of "lock-null resources" (LNRs) has been 5654 replaced by a simplified approach, the "locked empty resources" 5655 (see Section 7.3). There are some aspects of lock-null resources 5656 clients can not rely on anymore, namely the ability to use them to 5657 create a locked collection or the fact that they disappear upon 5658 UNLOCK when no PUT or MKCOL request was issued. Note that servers 5659 are still allowed to implement LNRs as per RFC2518. 5661 o There is no implicit refresh of locks anymore. Locks are only 5662 refreshed upon explicit request. Furthermore, the lock token for 5663 the lock to be refreshed is now specified in the Lock-Token 5664 request header rather than the If header (see Section 9.10.2). 5666 o Clarified that the DAV:owner value supplied in the LOCK request 5667 must be preserved by the server just like a dead property 5668 (Section 14.17). Also added the DAV:lockroot element 5669 (Section 14.12) which allows clients to discover the root of lock. 5671 E.2. Changes for Server Implementations 5673 Collections and Namespace Operations 5675 o Due to interoperability problems, allowable formats for contents 5676 of 'href' elements in multistatus responses have been limited (see 5677 Section 8.3). 5679 o Due to lack of implementation, support for the 'propertybehaviour' 5680 request body for COPY and MOVE has been removed. Instead, 5681 requirements for property preservation have been clarified (see 5682 Sections 9.8 and 9.9). 5684 Properties 5686 o Strengthened server requirements for storage of property values, 5687 in particular persistence of language information (xml:lang), 5688 whitespace, and XML namespace information (see Section 4.3). 5690 o Clarified requirements on which properties should be writeable by 5691 the client; in particular, setting "DAV:displayname" should be 5692 supported by servers (see Section 15). 5694 o Only 'rfc1123-date' productions are legal as values for DAV: 5695 getlastmodified (see Section 15.7). 5697 Headers and Marshalling 5699 o Servers are now required to do authorization checks before 5700 processing conditional headers (see Section 8.5). 5702 Locking 5704 o Strengthened requirement to check identity of lock creator when 5705 accessing locked resources (see Section 6.4). Clients should be 5706 aware that lock tokens returned to other principals can only be 5707 used to break a lock, if at all. 5709 o Section 8.10.4 of [RFC2518] incorrectly required servers to return 5710 a 409 status where a 207 status was really appropriate. This has 5711 been corrected (Section 9.10). 5713 E.3. Other Changes 5715 The definition of collection state has been fixed so it doesn't vary 5716 anymore depending on the Request-URI (see Section 5.2). 5718 The DAV:source property introduced in Section 4.6 of [RFC2518] was 5719 removed due to lack of implementation experience. 5721 The DAV header now allows non-IETF extensions through URIs in 5722 addition to compliance class tokens. It also can now be used in 5723 requests, although this specification does not define any associated 5724 semantics for the compliance classes defined in here (see 5725 Section 10.1). 5727 In RFC2518, the definition of the Depth header (Section 9.2) required 5728 that by default request headers would be applied to each resource in 5729 scope. Based on implementation experience, the default has now been 5730 reversed (see Section 10.2). 5732 The definitions of HTTP status code 102 ([RFC2518], Section 10.1) and 5733 the Status-URI response header (Section 9.7) have been removed due to 5734 lack of implementation. 5736 The TimeType format used in the Timeout request header and the 5737 "timeout" XML element used to be extensible. Now, only the two 5738 formats defined by this specification are allowed (see Section 10.7). 5740 Appendix F. Change Log (to be removed by RFC Editor before publication) 5742 F.1. Changes from -05 to -06 5744 Specified that a successful LOCK request to an unmapped URL creates a 5745 new, empty locked resource. 5747 Resolved UNLOCK_NEEDS_IF_HEADER by clarifying that only Lock-Token 5748 header is needed on UNLOCK. 5750 Added Section 16 on preconditions and postconditions and defined a 5751 number of preconditions and postconditions. The 'lock-token- 5752 submitted' precondition resolves the REPORT_OTHER_RESOURCE_LOCKED 5753 issue. 5755 Added example of matching lock token to URI in the case of a 5756 collection lock in the If header section. 5758 Removed ability for Destination header to take "abs_path" in order to 5759 keep consistent with other places where client provides URLs (If 5760 header, href element in request body) 5762 Clarified the href element - that it generally contains HTTP URIs but 5763 not always. 5765 Attempted to fix the BNF describing the If header to allow commas 5767 Clarified presence of Depth header on LOCK refresh requests. 5769 F.2. Changes in -07 5771 Added text to "COPY and the Overwrite Header" section to resolve 5772 issue OVERWRITE_DELETE_ALL_TOO_STRONG. 5774 Added text to "HTTP URL Namespace Model" section to provide more 5775 clarification and examples on what consistency means and what is not 5776 required, to resolve issue CONSISTENCY. 5778 Resolve DEFINE_PRINCIPAL by importing definition of principal from 5779 RFC3744. 5781 Resolve INTEROP_DELETE_AND_MULTISTATUS by adding appendix 3 5782 discussing backward-compatibility concerns. 5784 Resolve DATE_FORMAT_GETLASTMODIFIED by allowing only rfc1123-date, 5785 not HTTP-date for getlastmodified. 5787 Resolve COPY_INTO_YOURSELF_CLARIFY by adding sentence to first para. 5789 of COPY section. 5791 Confirm that WHEN_TO_MULTISTATUS_FOR_DELETE_1 and 5792 WHEN_TO_MULTISTATUS_FOR_DELETE_2 are resolved and tweak language in 5793 DELETE section slightly to be clearly consistent. 5795 More text clarifications to deal with several of the issues in 5796 LOCK_ISSUES. This may not completely resolve that set but we need 5797 feedback from the originator of the issues at this point. 5799 Resolved COPY_INTO_YOURSELF_CLARIFY with new sentence in Copy For 5800 Collections section. 5802 Double checked that LEVEL_OR_CLASS is resolved by using class, not 5803 level. 5805 Further work to resolve IF_AND_AUTH and LOCK_SEMANTICS, clarifying 5806 text on using locks and being authenticated. 5808 Added notes on use of 503 status response to resolve issue 5809 PROPFIND_INFINITY 5811 Removed section on other uses of Metadata (and associated references) 5813 Added reference to RFC4122 for lock tokens and removed section on 5814 generating UUIDs 5816 Explained that even with language variation, a property has only one 5817 value (section 4.5). 5819 Added section on lock owner (7.1) and what to do if lock requested by 5820 unauthenticated user 5822 Removed section 4.2 -- justification on why to have metadata, not 5823 needed now 5825 Removed paragraph in section 5.2 about collections with resource type 5826 "DAV:collection" but which are non-WebDAV compliant -- not 5827 implemented. 5829 F.3. Changes in -08 5831 Added security considerations section on scripts and cookie sessions, 5832 suggested by Barry Lind 5834 Clarified which error codes are defined and undefined in MultiStatus 5836 Moved opaquelocktoken definition to an appendix and refer to RFC4122 5837 for use of 'urn:uuid:' URI scheme; fix all lock token examples to use 5838 this. 5840 Multi-status responses contain URLs which MUST either be absolute 5841 (and begin with the Request-URI or MUST be relative with new 5842 limitations. (bug 12) 5844 Moved status code sections before example sections within PROPFIND 5845 section for section ordering consistency. 5847 Clarified use of Location header with Multi-Status 5849 Bugzilla issue resolutions: bugs 9, 12, 14, 19, 20, 29, 30, 34, 36, 5850 102 and 172. 5852 F.4. Changes in -09 5854 Bugzilla editorial issues: bugs 30, 57, 63, 68, 88, 89, 168, 180, 5855 182, 185, 187. 5857 More clarity between URL namespaces and XML namespaces, particularly 5858 at the beginning of paragraphs using the word namespace 5860 More consistency in referring to properties with the namespace, as in 5861 "DAV:lockdiscovery", and referring to XML element names in single 5862 quotes, e.g. 'allprop' element. 5864 Figure (example) formatting fixes 5866 Bugzilla issues: bugs 24, 37, 39, 43, 45, 27, 25 5868 Replaced references to "non-null state" of resources with more clear 5869 language about URLs that are mapped to resources, bug 25. Also added 5870 definition of URL/URI mapping. Bug 40. 5872 Bugzilla issues: bug 7, 8, 9, 41, 47, 51, 62, 93, 171, 172. Bugs 28 5873 and 94 were iterated on. 5875 Bugzilla issues: 56, 59, 79, 99, 103, 175, 178. Part of bug 23. 5876 Iteration on bug 10. 5878 Iteration on bugs 10, 46 and 47. Bug 11. 5880 Remove "102 Processing" response 5882 Fix bug 46, 105, 107, 120, 140 and 201. 5884 Another stab at bug 12 - relative v. absolute URLs in Multi-Status 5885 response hrefs 5887 Fix bug 6, 11, 15, 16, 28, 32, 42, 51, 52, 53, 58, 60, 62, 186, 189, 5888 191, 199, 200 5890 Fix bug 96 5892 F.5. Changes in -10 5894 Clarify lock intro text on when a client might use another client's 5895 lock token - suggestion by Geoff, Nov 15 5897 Removed Force-Authenticate header and instead added an appendix 5898 explaining how existing mechanisms might resolve the need of clients 5899 to get an authentication challenge (bug 18). 5901 Bug 62, 113, 125, 131, 143, 144, 171, 193 5903 Bug 176, 177, 179, 181, 184, 206, 207, 208 5905 F.6. Changes in -11 5907 Bug 10, 50, 92, 213, 214, 215 5909 not recommend use of 414 for over-long Destination URI, bug 179 5911 Changes for bug 10, 31, 42, 44, 46, 47, 80, 86, 99, 124, 132, 143, 5912 147, 152, 166, 177, 188, 216, 218 5914 Various changes discussed in conference call, including bug 10, 42, 5915 44, 80, 97, 152. 5917 Bugs 55, 85, 86 5919 F.7. Changes in -12 5921 Incorporated GULP (Lock model) into document, making a fair number of 5922 changes to rationalize the new order of explaining things, keeping 5923 text that explains a lock model concept in more detail but removing 5924 text that is redundant or inconsistent. 5926 Various bugs including 46, 48, 53, 97, 152, 179, 184, 188, 200, 210, 5927 211, and 225. Moved URL Handling from Multi-Status section to 5928 general request and response handling section as it now applies to 5929 Destination and If as well as 'href' in Multi-Status. Moved GR&RH 5930 section up one level to be the new Section 8. 5932 Bug 53, 184, 210, 213, 217, 221 5933 Further rewriting of URL Handling section. Changes resulting from 5934 discussion of empty locked resources and how servers should handle 5935 Content-Type in that situation. Bug 48, 179. 5937 Bug 227, 228 5939 F.8. Changes in -13 5941 Moved the timeout model text and clarified it (bug 229). 5943 Fixed the definition of collection state (bug 227). 5945 Made the depth header required on PROPFIND requests (bug 213). 5947 Fixed inconsistencies in Destination header definition (bug 211). 5949 Improved appendix on HTTP client compatibility (bug 100). 5951 Fixed external references with unwieldy pointers (bug 72). 5953 F.9. Changes in -14 5955 Changes section rewritten, if section rewritten 5957 Collection definition and membership requirements changed (bug 227) 5959 Bug 100 and 229 iterations, smallish editorial changes 5961 Author's Address 5963 Lisa Dusseault (editor) 5964 Open Source Application Foundation 5965 2064 Edgewood Dr. 5966 Palo Alto, CA 94303 5967 US 5969 Email: lisa@osafoundation.org 5971 Intellectual Property Statement 5973 The IETF takes no position regarding the validity or scope of any 5974 Intellectual Property Rights or other rights that might be claimed to 5975 pertain to the implementation or use of the technology described in 5976 this document or the extent to which any license under such rights 5977 might or might not be available; nor does it represent that it has 5978 made any independent effort to identify any such rights. Information 5979 on the procedures with respect to rights in RFC documents can be 5980 found in BCP 78 and BCP 79. 5982 Copies of IPR disclosures made to the IETF Secretariat and any 5983 assurances of licenses to be made available, or the result of an 5984 attempt made to obtain a general license or permission for the use of 5985 such proprietary rights by implementers or users of this 5986 specification can be obtained from the IETF on-line IPR repository at 5987 http://www.ietf.org/ipr. 5989 The IETF invites any interested party to bring to its attention any 5990 copyrights, patents or patent applications, or other proprietary 5991 rights that may cover technology that may be required to implement 5992 this standard. Please address the information to the IETF at 5993 ietf-ipr@ietf.org. 5995 Disclaimer of Validity 5997 This document and the information contained herein are provided on an 5998 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 5999 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 6000 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 6001 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 6002 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 6003 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 6005 Copyright Statement 6007 Copyright (C) The Internet Society (2006). This document is subject 6008 to the rights, licenses and restrictions contained in BCP 78, and 6009 except as set forth therein, the authors retain all their rights. 6011 Acknowledgment 6013 Funding for the RFC Editor function is currently provided by the 6014 Internet Society.