idnits 2.17.1 draft-ietf-webdav-rfc2518bis-10.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 5457. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 5434. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 5441. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 5447. ** 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 : ---------------------------------------------------------------------------- == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. -- 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 563 has weird spacing: '... 483 The value of a property appears inside the property name element. 484 The value may be any kind of well-formed XML content, including both 485 text-only and mixed content. In the latter case, servers MUST 486 preserve certain aspects of the content (described using the 487 terminology from [W3C.REC-xml-infoset-20040204]). 489 For the property name Element Information Item itself: 491 [namespace name] 493 [local name] 495 [attributes] named "xml:lang" or any such attribute in scope 497 [children] of type element or character 499 On all Element Information Items in the value: 501 [namespace name] 503 [local name] 505 [attributes] 507 [children] of type element or character 509 On Attribute Information Items in the value: 511 [namespace name] 513 [local name] 515 [normalized value] 517 On Character Information Items in the value: 519 [character code] 521 Since prefixes are used in some XML query/handling tools, servers 522 SHOULD preserve, for any Information Item in the value: 524 [prefix] 526 In dead properties (considered as content, like document bodies) 527 servers are encouraged to (MAY) preserve, for any Comment Information 528 Item in the value: 530 [content] 532 XML Infoset attributes not listed above MAY be preserved by the 533 server, but clients MUST NOT rely on them being preserved. 535 The XML attribute xml:space MUST NOT be used to change white space 536 handling. White space in property values is significant. 538 4.4.1. Example - Property with Mixed Content 540 Consider a dead property 'author' created by the client as follows: 542 543 544 Jane Doe 545 546 mailto:jane.doe@example.com 548 http://www.example.com 550 551 Jane has been working way too long on the 552 long-awaited revision of ]]>. 553 554 555 557 When this property is requested, a server might return: 559 562 Jane Doe 563 mailto:jane.doe@example.com 565 http://www.example.com 567 568 Jane has been working way too long on the 569 long-awaited revision of <RFC2518>. 570 571 573 575 Note in this example: 577 o The [prefix] for the property name itself was not preserved, being 578 non-significant 580 o attribute values have been rewritten with double quotes instead of 581 single quotes (quoting style is not significant), and attribute 582 order has not been preserved, 584 o the xml:lang attribute has been returned on the property name 585 element itself (it was in scope when the property was set, but the 586 exact position in the response is not considered significant as 587 long as it is in scope), 589 o whitespace between tags has been preserved everywhere (whitespace 590 between attributes not so), 592 o CDATA encapsulation was replaced with character escaping (the 593 reverse would also be legal), 595 o the comment item was stripped (as would have been a processing 596 instruction item). 598 Implementation note: there are cases such as editing scenarios where 599 clients may require that XML content is preserved character-by- 600 character (such as attribute ordering or quoting style). In this 601 case, clients should consider using a text-only property value by 602 escaping all characters that have a special meaning in XML parsing. 604 4.5. Property Names 606 A property name is a universally unique identifier that is associated 607 with a schema that provides information about the syntax and 608 semantics of the property. 610 Because a property's name is universally unique, clients can depend 611 upon consistent behavior for a particular property across multiple 612 resources, on the same and across different servers, so long as that 613 property is "live" on the resources in question, and the 614 implementation of the live property is faithful to its definition. 616 The XML namespace mechanism, which is based on URIs ([RFC3986]), is 617 used to name properties because it prevents namespace collisions and 618 provides for varying degrees of administrative control. 620 The property namespace is flat; that is, no hierarchy of properties 621 is explicitly recognized. Thus, if a property A and a property A/B 622 exist on a resource, there is no recognition of any relationship 623 between the two properties. It is expected that a separate 624 specification will eventually be produced which will address issues 625 relating to hierarchical properties. 627 Finally, it is not possible to define the same property twice on a 628 single resource, as this would cause a collision in the resource's 629 property namespace. 631 4.6. Source Resources and Output Resources 633 Some HTTP resources are dynamically generated by the server. For 634 these resources, there presumably exists source code somewhere 635 governing how that resource is generated. The relationship of source 636 files to output HTTP resources may be one to one, one to many, many 637 to one or many to many. There is no mechanism in HTTP to determine 638 whether a resource is even dynamic, let alone where its source files 639 exist or how to author them. Although this problem would usefully be 640 solved, interoperable WebDAV implementations have been widely 641 deployed without actually solving this problem, by dealing only with 642 static resources. Thus, the source vs. output problem is not solved 643 in this specification and has been deferred to a separate document. 645 5. Collections of Web Resources 647 This section provides a description of a new type of Web resource, 648 the collection, and discusses its interactions with the HTTP URL 649 namespace. The purpose of a collection resource is to model 650 collection-like objects (e.g., file system directories) within a 651 server's namespace. 653 All DAV compliant resources MUST support the HTTP URL namespace model 654 specified herein. 656 5.1. HTTP URL Namespace Model 658 The HTTP URL namespace is a hierarchical namespace where the 659 hierarchy is delimited with the "/" character. 661 An HTTP URL namespace is said to be consistent if it meets the 662 following conditions: for every URL in the HTTP hierarchy there 663 exists a collection that contains that URL as an internal member. 664 The root, or top-level collection of the namespace under 665 consideration is exempt from the previous rule. The top-level 666 collection of the namespace under consideration is not necessarily 667 the collection identified by the absolute path '/', it may be 668 identified by one or more path segments (e.g. /servlets/webdav/...) 670 Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL 671 namespace be consistent -- a WebDAV-compatible resource may not have 672 a parent collection. However, certain WebDAV methods are prohibited 673 from producing results that cause namespace inconsistencies. 675 Although implicit in [RFC2616] and [RFC3986], any resource, including 676 collection resources, MAY be identified by more than one URI. For 677 example, a resource could be identified by multiple HTTP URLs. 679 5.2. Collection Resources 681 A collection is a resource whose state consists of at least a list of 682 internal member URLs and a set of properties, but which may have 683 additional state such as entity bodies returned by GET. An internal 684 member URL MUST be immediately relative to a base URL of the 685 collection. That is, the internal member URL is equal to a 686 containing collection's URL plus an additional segment for non- 687 collection resources, or additional segment plus trailing slash "/" 688 for collection resources, where segment is defined in section 3.3 of 689 [RFC3986]. 691 Any given internal member URL MUST only belong to the collection 692 once, i.e., it is illegal to have multiple instances of the same URL 693 in a collection. Properties defined on collections behave exactly as 694 do properties on non-collection resources. 696 For all WebDAV compliant resources A and B, identified by URLs U and 697 V, for which U is immediately relative to V, B MUST be a collection 698 that has U as an internal member URL. So, if the resource with URL 699 http://example.com/bar/blah is WebDAV compliant and if the resource 700 with URL http://example.com/bar/ is WebDAV compliant then the 701 resource with URL http://example.com/bar/ must be a collection and 702 must contain URL http://example.com/bar/blah as an internal member. 704 Collection resources MAY list the URLs of non-WebDAV compliant 705 children in the HTTP URL namespace hierarchy as internal members but 706 are not required to do so. For example, if the resource with URL 707 http://example.com/bar/blah is not WebDAV compliant and the URL 708 http://example.com/bar/ identifies a collection then URL 709 http://example.com/bar/blah may or may not be an internal member of 710 the collection with URL http://example.com/bar/. 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 6. Locking 741 The ability to lock a resource provides a mechanism for serializing 742 access to that resource. Using a lock, an authoring client can 743 provide a reasonable guarantee that another principal will not modify 744 a resource while it is being edited. In this way, a client can 745 prevent the "lost update" problem. 747 This specification allows locks to vary over two client-specified 748 parameters, the number of principals involved (exclusive vs. shared) 749 and the type of access to be granted. This document defines locking 750 for only one access type, write. However, the syntax is extensible, 751 and permits the eventual specification of locking for other access 752 types. 754 6.1. Exclusive Vs. Shared Locks 756 The most basic form of lock is an exclusive lock. Only one exclusive 757 lock may exist on any resource, whether it is directly or indirectly 758 locked (Section 7.7). Exclusive locks avoid having to merge results, 759 without requiring any coordination other than the methods described 760 in this specification. 762 However, there are times when the goal of a lock is not to exclude 763 others from exercising an access right but rather to provide a 764 mechanism for principals to indicate that they intend to exercise 765 their access rights. Shared locks are provided for this case. A 766 shared lock allows multiple principals to receive a lock. Hence any 767 principal with appropriate access can use the lock. 769 With shared locks there are two trust sets that affect a resource. 770 The first trust set is created by access permissions. Principals who 771 are trusted, for example, may have permission to write to the 772 resource. Among those who have access permission to write to the 773 resource, the set of principals who have taken out a shared lock also 774 must trust each other, creating a (typically) smaller trust set 775 within the access permission write set. 777 Starting with every possible principal on the Internet, in most 778 situations the vast majority of these principals will not have write 779 access to a given resource. Of the small number who do have write 780 access, some principals may decide to guarantee their edits are free 781 from overwrite conflicts by using exclusive write locks. Others may 782 decide they trust their collaborators will not overwrite their work 783 (the potential set of collaborators being the set of principals who 784 have write permission) and use a shared lock, which informs their 785 collaborators that a principal may be working on the resource. 787 The WebDAV extensions to HTTP do not need to provide all of the 788 communications paths necessary for principals to coordinate their 789 activities. When using shared locks, principals may use any out of 790 band communication channel to coordinate their work (e.g., face-to- 791 face interaction, written notes, post-it notes on the screen, 792 telephone conversation, Email, etc.) The intent of a shared lock is 793 to let collaborators know who else may be working on a resource. 795 Shared locks are included because experience from web distributed 796 authoring systems has indicated that exclusive locks are often too 797 rigid. An exclusive lock is used to enforce a particular editing 798 process: take out an exclusive lock, read the resource, perform 799 edits, write the resource, release the lock. This editing process 800 has the problem that locks are not always properly released, for 801 example when a program crashes, or when a lock owner leaves without 802 unlocking a resource. While both timeouts and administrative action 803 can be used to remove an offending lock, neither mechanism may be 804 available when needed; the timeout may be long or the administrator 805 may not be available. 807 6.2. Required Support 809 A WebDAV compliant resource is not required to support locking in any 810 form. If the resource does support locking it may choose to support 811 any combination of exclusive and shared locks for any access types. 813 The reason for this flexibility is that locking policy strikes to the 814 very heart of the resource management and versioning systems employed 815 by various storage repositories. These repositories require control 816 over what sort of locking will be made available. For example, some 817 repositories only support shared write locks while others only 818 provide support for exclusive write locks while yet others use no 819 locking at all. As each system is sufficiently different to merit 820 exclusion of certain locking features, this specification leaves 821 locking as the sole axis of negotiation within WebDAV. 823 6.3. Lock Tokens 825 A lock token is a type of state token, represented as a URI, which 826 identifies a particular lock. Each lock has exactly one unique lock 827 token generated by the server. Clients MUST NOT attempt to interpret 828 lock tokens in any way. 830 Lock token URIs MUST be unique across all resources for all time. 831 This uniqueness constraint allows lock tokens to be submitted across 832 resources and servers without fear of confusion. Since lock tokens 833 are unique, a client MAY submit a lock token in an If header on a 834 resource other than the one that returned it. 836 When a LOCK operation creates a new lock, the new lock token is 837 returned in the Lock-Token response header defined in Section 9.5, 838 and also in the body of the response. 840 Submitting a lock token does not confer full privilege to use the 841 lock token or modify the locked resource. Write access and other 842 privileges MUST be enforced through normal privilege or 843 authentication mechanisms, not based on the possible obscurity of 844 lock token values. 846 Servers MAY make lock tokens publicly readable (e.g. in the DAV: 847 lockdiscovery property). One use case for making lock tokens 848 readable is so that a long-lived lock can be removed by the resource 849 owner (the client that obtained the lock might have crashed or 850 disconnected before cleaning up the lock). Except for the case of 851 using UNLOCK under user guidance, a client SHOULD NOT use a lock 852 tokens created by another client instance. 854 This specification encourages servers to create UUIDs for lock 855 tokens, and to use the URI form defined by "A Universally Unique 856 Identifier (UUID) URN Namespace" ([RFC4122]). However servers are 857 free to use any URI (e.g. from another scheme) so long as it meets 858 the uniqueness requirements. For example, a valid lock token might 859 be constructed using the "opaquelocktoken" scheme defined in 860 Appendix C. 862 Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" 864 6.4. Lock Capability Discovery 866 Since server lock support is optional, a client trying to lock a 867 resource on a server can either try the lock and hope for the best, 868 or perform some form of discovery to determine what lock capabilities 869 the server supports. This is known as lock capability discovery. A 870 client can determine what lock types the server supports by 871 retrieving the DAV:supportedlock property. 873 Any DAV compliant resource that supports the LOCK method MUST support 874 the DAV:supportedlock property. 876 6.5. Active Lock Discovery 878 If another principal locks a resource that a principal wishes to 879 access, it is useful for the second principal to be able to find out 880 who the first principal is. For this purpose the DAV:lockdiscovery 881 property is provided. This property lists all outstanding locks, 882 describes their type, and MAY even provide the lock tokens. 884 Any DAV compliant resource that supports the LOCK method MUST support 885 the DAV:lockdiscovery property. 887 6.6. Locks and Multiple Bindings 889 A resource may be made available through more than one URI. A lock 890 MUST cover the resource as well as the URI to which the LOCK request 891 was addressed. The lock MAY cover other URIs mapped to the same 892 resource as well. 894 7. Write Lock 896 This section describes the semantics specific to the write lock type. 897 The write lock is a specific instance of a lock type, and is the only 898 lock type described in this specification. 900 An exclusive write lock will prevent parallel changes to a resource 901 by any principal other than the write lock holder. In general terms, 902 changes affected by write locks include changes to: 904 o the content of the resource 906 o any dead property of the resource 908 o any live property defined to be lockable (all properties defined 909 in this specification are lockable) 911 o the direct membership of the resource, if it is a collection 913 o the URL/location of a resource 915 The next few sections describe in more specific terms how write locks 916 interact with various operations. 918 7.1. Lock Owner 920 The creator of the lock is the lock owner. The server MUST restrict 921 the usage of the lock token to the lock owner (both for shared and 922 exclusive locks -- for multi-user shared lock cases, each 923 authenticated principal MUST obtain its own shared lock). 925 The server MAY allow privileged users other than the lock owner to 926 destroy a lock (for example, the resource owner or an administrator) 927 as a special case of lock usage. 929 If an anonymous user requests a lock, the server MAY refuse the 930 request. 932 7.2. Methods Restricted by Write Locks 934 A server MUST reject any write request that alters a write-locked 935 resource unless a valid lock token is provided. The write operations 936 defined in HTTP and WebDAV are PUT, POST, PROPPATCH, LOCK, UNLOCK, 937 MOVE, COPY (for the destination resource), DELETE, and MKCOL. All 938 other HTTP/WebDAV methods, GET in particular, function independently 939 of the lock. A shared write lock prevents the same operations 940 (except additional requests for shared write locks), however it also 941 allows access by any principal that has a shared write lock on the 942 same resource. 944 Note, however, that as new methods are created it will be necessary 945 to specify how they interact with a write lock. 947 7.3. Write Locks and Lock Tokens 949 A successful request for an exclusive or shared write lock MUST 950 result in the generation of a unique lock token associated with the 951 requesting principal. Thus if five principals have a shared write 952 lock on the same resource there will be five lock tokens, one for 953 each principal. 955 7.4. Write Locks and Properties 957 While those without a write lock may not alter a property on a 958 resource it is still possible for the values of live properties to 959 change, even while locked, due to the requirements of their schemas. 960 Only dead properties and live properties defined to respect locks are 961 guaranteed not to change while write locked. 963 7.5. Avoiding Lost Updates 965 Although the write locks provide some help in preventing lost 966 updates, they cannot guarantee that updates will never be lost. 967 Consider the following scenario: 969 Two clients A and B are interested in editing the resource 970 'index.html'. Client A is an HTTP client rather than a WebDAV 971 client, and so does not know how to perform locking. 973 Client A doesn't lock the document, but does a GET and begins 974 editing. 976 Client B does LOCK, performs a GET and begins editing. 978 Client B finishes editing, performs a PUT, then an UNLOCK. 980 Client A performs a PUT, overwriting and losing all of B's changes. 982 There are several reasons why the WebDAV protocol itself cannot 983 prevent this situation. First, it cannot force all clients to use 984 locking because it must be compatible with HTTP clients that do not 985 comprehend locking. Second, it cannot require servers to support 986 locking because of the variety of repository implementations, some of 987 which rely on reservations and merging rather than on locking. 988 Finally, being stateless, it cannot enforce a sequence of operations 989 like LOCK / GET / PUT / UNLOCK. 991 WebDAV servers that support locking can reduce the likelihood that 992 clients will accidentally overwrite each other's changes by requiring 993 clients to lock resources before modifying them. Such servers would 994 effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying 995 resources. 997 WebDAV clients can be good citizens by using a lock / retrieve / 998 write /unlock sequence of operations (at least by default) whenever 999 they interact with a WebDAV server that supports locking. 1001 HTTP 1.1 clients can be good citizens, avoiding overwriting other 1002 clients' changes, by using entity tags in If-Match headers with any 1003 requests that would modify resources. 1005 Information managers may attempt to prevent overwrites by 1006 implementing client-side procedures requiring locking before 1007 modifying WebDAV resources. 1009 7.6. Write Locks and Unmapped URLs 1011 WebDAV provides the ability to lock an unmapped URL in order to 1012 reserve the name for use. This is a simple way to avoid the lost- 1013 update problem on the creation of a new resource (another way is to 1014 use If-None-Match header specified in HTTP 1.1). It has the side 1015 benefit of locking the new resource immediately for use of the 1016 creator. 1018 Note that the lost-update problem is not an issue for collections 1019 because MKCOL can only be used to create a collection, not to 1020 overwrite an existing collection. When trying to lock a collection 1021 upon creation, clients may attempt to increase the likelihood of 1022 getting the lock by pipelining the MKCOL and LOCK requests together 1023 (but because this doesn't convert two separate operations into one 1024 atomic operation there's no guarantee this will work). 1026 A successful lock request to an unmapped URL MUST result in the 1027 creation of an locked resource with empty content. Subsequently, a 1028 successful PUT request (with the correct lock token) provides the 1029 content for the resource, and the server MUST also use the content- 1030 type and content-language information from this request. 1032 The original WebDAV model for locking unmapped URLs created "lock- 1033 null resources". This model was over-complicated and some 1034 interoperability and implementation problems were discovered. The 1035 new WebDAV model for locking unmapped URLs creates "locked empty 1036 resources". Servers MUST implement either lock-null resources or 1037 locked empty resources, but servers SHOULD implement locked empty 1038 resources. This section discusses the original model briefly and the 1039 new model more completely, because clients MUST be able to handle 1040 either model. 1042 In the original "lock-null resource" model, which is no longer 1043 recommended for implementation: 1045 o A lock-null resource sometimes appeared as "Not Found". The 1046 server responds with a 404 or 405 to any method except for PUT, 1047 MKCOL, OPTIONS, PROPFIND, LOCK, UNLOCK. 1049 o A lock-null resource does however show up as a member of its 1050 parent collection. 1052 o The server removes the lock-null resource entirely (its URI 1053 becomes unmapped) if its lock goes away before it is converted to 1054 a regular resource. Recall that locks go away not only when they 1055 expire or are unlcoked, but are also removed if a resource is 1056 renamed or moved, or if any parent collection is renamed or moved. 1058 o The server converts the lock-null resource into a regular resource 1059 if a PUT request to the URL is successful. 1061 o The server converts the lock-null resource into a collection if a 1062 MKCOL request to the URL is successful (though interoperability 1063 experience showed that not all servers followed this requirement). 1065 o Property values were defined for DAV:lockdiscovery and DAV: 1066 supportedlock properties but not necessarily for other properties 1067 like DAV:getcontenttype. 1069 In the "locked empty resource" model, which is now the recommended 1070 implementation, a resource created with a LOCK is empty but otherwise 1071 behaves in every way as a normal resource. A locked empty resource: 1073 o Can be read, deleted, moved, copied, and in all ways behave as a 1074 regular resource, not a lock-null resource. 1076 o Appears as a member of its parent collection. 1078 o SHOULD NOT disappear when its lock goes away (clients must 1079 therefore be responsible for cleaning up their own mess, as with 1080 any other operation or any non-empty resource) 1082 o SHOULD default to having no content type. 1084 o MAY NOT have values for properties like DAV:getcontentlanguage 1085 which haven't been specified yet by the client. 1087 o Can be updated (have content added) with a PUT request. The 1088 server MUST be able to set the content type as specified in the 1089 PUT request. 1091 o MUST NOT be converted into a collection. The server MUST fail a 1092 MKCOL request (as it would with a MKCOL request to any existing 1093 non-collection resource). 1095 o MUST have defined values for DAV:lockdiscovery and DAV: 1096 supportedlock properties. 1098 o The response MUST indicate that a resource was created, by use of 1099 the "201 Created" response code (a LOCK request to an existing 1100 resource instead will result in 200 OK). The body must still 1101 include the DAV:lockdiscovery property, as with a LOCK request to 1102 an existing resource. 1104 The client is expected to update the locked empty resource shortly 1105 after locking it, using PUT and possibly PROPPATCH. When the client 1106 uses PUT to overwrite a locked empty resource the client MUST supply 1107 a Content-Type if any is known. If the client supplies a Content- 1108 Type value the server MUST set that value (this requirement actually 1109 applies to any resource that is overwritten but is particularly 1110 necessary for locked empty resources which are initially created with 1111 no Content-Type). 1113 Clients can easily interoperate both with servers that support the 1114 old model "lock-null resources" and the recommended model of "locked 1115 empty resources" by only attempting PUT after a LOCK to an unmapped 1116 URL, not MKCOL or GET. 1118 7.7. Write Locks and Collections 1120 A write lock on a collection, whether created by a "Depth: 0" or 1121 "Depth: infinity" lock request, prevents the addition or removal of 1122 member URLs of the collection by non-lock owners. 1124 A zero-depth lock on a collection affects changes to the direct 1125 membership of that collection. When a principal issues a write 1126 request to create a new resource in a write locked collection, or 1127 isses a DELETE, MOVE or other request that would remove an existing 1128 internal member URL of a write locked collection or change the 1129 binding name, this request MUST fail if the principal does not 1130 provide the correct lock token for the locked collection. 1132 This means that if a collection is locked (depth 0 or infinity), its 1133 lock-token is required in all these cases: 1135 o DELETE a collection's direct internal member 1137 o MOVE a member out of the collection 1139 o MOVE a member into the collection 1141 o MOVE to rename a member within a collection 1143 o COPY a member into a collection 1145 o PUT or MKCOL request which would create a new member. 1147 The collection's lock token is required in addition to the lock token 1148 on the internal member itself, if it is locked separately. 1150 In addition, a depth-infinity lock affects all write operations to 1151 all descendents of the locked collection. With a depth-infinity 1152 lock, the root of the lock is directly locked, and all its 1153 descendants are indirectly locked. 1155 o Any new resource added as a descendent of a depth-infinity locked 1156 collection becomes indirectly locked. 1158 o Any indirectly locked resource moved out of the locked collection 1159 into an unlocked collection is thereafter unlocked. 1161 o Any indirectly locked resource moved out of a locked source 1162 collection into a depth-infinity locked target collection remains 1163 indirectly locked but is now within the scope of the lock on the 1164 target collection (the target collection's lock token will 1165 thereafter be required to make further changes). 1167 If a depth-infinity write LOCK request is issued to a collection 1168 containing member URLs identifying resources that are currently 1169 locked in a manner which conflicts with the write lock, the request 1170 MUST fail with a 423 (Locked) status code, and the response SHOULD 1171 contain the 'lock-token-present' precondition. 1173 If a lock owner causes the URL of a resource to be added as an 1174 internal member URL of a depth-infinity locked collection then the 1175 new resource MUST be automatically added to the lock. This is the 1176 only mechanism that allows a resource to be added to a write lock. 1177 Thus, for example, if the collection /a/b/ is write locked and the 1178 resource /c is moved to /a/b/c then resource /a/b/c will be added to 1179 the write lock. 1181 7.8. Write Locks and the If Request Header 1183 If a user agent is not required to have knowledge about a lock when 1184 requesting an operation on a locked resource, the following scenario 1185 might occur. Program A, run by User A, takes out a write lock on a 1186 resource. Program B, also run by User A, has no knowledge of the 1187 lock taken out by Program A, yet performs a PUT to the locked 1188 resource. In this scenario, the PUT succeeds because locks are 1189 associated with a principal, not a program, and thus program B, 1190 because it is acting with principal A's credential, is allowed to 1191 perform the PUT. However, had program B known about the lock, it 1192 would not have overwritten the resource, preferring instead to 1193 present a dialog box describing the conflict to the user. Due to 1194 this scenario, a mechanism is needed to prevent different programs 1195 from accidentally ignoring locks taken out by other programs with the 1196 same authorization. 1198 In order to prevent these collisions a lock token MUST be submitted 1199 by an authorized principal for all locked resources that a method may 1200 change or the method MUST fail. A lock token is submitted when it 1201 appears in an If header. For example, if a resource is to be moved 1202 and both the source and destination are locked then two lock tokens 1203 must be submitted in the if header, one for the source and the other 1204 for the destination. 1206 7.8.1. Example - Write Lock 1208 >>Request 1210 COPY /~fielding/index.html HTTP/1.1 1211 Host: www.ics.uci.edu 1212 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1213 If: 1214 () 1216 >>Response 1218 HTTP/1.1 204 No Content 1220 In this example, even though both the source and destination are 1221 locked, only one lock token must be submitted, for the lock on the 1222 destination. This is because the source resource is not modified by 1223 a COPY, and hence unaffected by the write lock. In this example, 1224 user agent authentication has previously occurred via a mechanism 1225 outside the scope of the HTTP protocol, in the underlying transport 1226 layer. 1228 7.9. Write Locks and COPY/MOVE 1230 A COPY method invocation MUST NOT duplicate any write locks active on 1231 the source. However, as previously noted, if the COPY copies the 1232 resource into a collection that is locked with "Depth: infinity", 1233 then the resource will be added to the lock. 1235 A successful MOVE request on a write locked resource MUST NOT move 1236 the write lock with the resource. However, if there is an existing 1237 lock at the destination, the server MUST add the moved resource to 1238 the destination lock scope. For example, if the MOVE makes the 1239 resource a child of a collection that is locked with "Depth: 1240 infinity", then the resource will be added to that collection's lock. 1241 Additionally, if a resource locked with "Depth: infinity" is moved to 1242 a destination that is within the scope of the same lock (e.g., within 1243 the URL namespace tree covered by the lock), the moved resource will 1244 again be a added to the lock. In both these examples, as specified 1245 in Section 7.8, an If header must be submitted containing a lock 1246 token for both the source and destination. 1248 7.10. Refreshing Write Locks 1250 A client MUST NOT submit the same write lock request twice. Note 1251 that a client is always aware it is resubmitting the same lock 1252 request because it must include the lock token in the If header in 1253 order to make the request for a resource that is already locked. 1255 However, a client may submit a LOCK method with an If header but 1256 without a body. This form of LOCK MUST only be used to "refresh" a 1257 lock. Meaning, at minimum, that any timers associated with the lock 1258 MUST be re-set. 1260 A server may return a Timeout header with a lock refresh that is 1261 different than the Timeout header returned when the lock was 1262 originally requested. Additionally clients may submit Timeout 1263 headers of arbitrary value with their lock refresh requests. 1264 Servers, as always, may ignore Timeout headers submitted by the 1265 client. Note that timeout is measured in seconds remaining until 1266 expiration. 1268 If an error is received in response to a refresh LOCK request the 1269 client MUST NOT assume that the lock was refreshed. 1271 8. HTTP Methods for Distributed Authoring 1273 8.1. General Request and Response Handling 1275 8.1.1. Use of XML 1277 Some of the following new HTTP methods use XML as a request and 1278 response format. All DAV compliant clients and resources MUST use 1279 XML parsers that are compliant with [XML] and XML Namespaces 1280 [W3C.REC-xml-names-19990114]. All XML used in either requests or 1281 responses MUST be, at minimum, well formed and use namespaces 1282 correctly. If a server receives XML that is not well-formed then the 1283 server MUST reject the entire request with a 400 (Bad Request). If a 1284 client receives XML that is not well-formed in a response then the 1285 client MUST NOT assume anything about the outcome of the executed 1286 method and SHOULD treat the server as malfunctioning. 1288 Note that processing XML submitted by an untrusted source may cause 1289 risks connected to privacy, security, and service quality (see 1290 Section 19). Servers MAY reject questionable requests (even though 1291 they consist of well-formed XML), for instance with a 400 (Bad 1292 Request) status code and an optional response body explaining the 1293 problem. 1295 8.1.2. Required Bodies in Requests 1297 Some of these new methods do not define bodies. Servers MUST examine 1298 all requests for a body, even when a body was not expected. In cases 1299 where a request body is present but would be ignored by a server, the 1300 server MUST reject the request with 415 (Unsupported Media Type). 1301 This informs the client (which may have been attempting to use an 1302 extension) that the body could not be processed as they intended. 1304 8.1.3. HTTP Headers for use in WebDAV 1306 HTTP defines many headers that can be used in WebDAV requests and 1307 responses. Not all of these are appropriate in all situations and 1308 some interactions may be undefined. Note that HTTP 1.1 requires the 1309 Date header in all responses if possible (see section 14.18, 1310 [RFC2616]). 1312 The server MUST do authorization checks before checking any HTTP 1313 conditional header. 1315 8.1.4. ETag 1317 HTTP 1.1 recommends the use of the ETag header in responses to GET 1318 and PUT requests. Correct use of ETags is even more important in a 1319 distributed authoring environment, because ETags are necessary along 1320 with locks to avoid the lost-update problem. A client might fail to 1321 renew a lock, for example when the lock times out and the client is 1322 accidentally offline or in the middle of a long upload. When a 1323 client fails to renew the lock, it's quite possible the resource can 1324 still be relocked and the user can go on editing, as long as no 1325 changes were made in the meantime. ETags are required for the client 1326 to be able to distinguish this case. Otherwise, the client is forced 1327 to ask the user whether to overwrite the resource on the server 1328 without even being able to tell the user whether it has changed. 1329 Timestamps do not solve this problem nearly as well as ETags. 1331 WebDAV servers SHOULD support strong ETags for all resources that may 1332 be PUT. If ETags are supported for a resource, the server MUST 1333 return the ETag header in all PUT and GET responses to that resource. 1335 Because clients may be forced to prompt users or throw away changed 1336 content if the ETag changes, a WebDAV server SHOULD NOT change the 1337 ETag (or the Last-Modified time) for a resource that has an unchanged 1338 body and location. The ETag represents the state of the body or 1339 contents of the resource. There is no similar way to tell if 1340 properties have changed. 1342 8.1.5. Including error response bodies 1344 HTTP and WebDAV did not use the bodies of most error responses for 1345 machine-parsable information until DeltaV introduced a mechanism to 1346 include more specific information in the body of an error response 1347 (section 1.6 of [RFC3253]). The error body mechanism is appropriate 1348 to use with any error response that may take a body but does not 1349 already have a body defined. The mechanism is particularly 1350 appropriate when a status code can mean many things (for example, 400 1351 Bad Request can mean required headers are missing, headers are 1352 incorrectly formatted, or much more). This error body mechanism is 1353 covered in Section 15 1355 8.2. PROPFIND 1357 The PROPFIND method retrieves properties defined on the resource 1358 identified by the Request-URI, if the resource does not have any 1359 internal members, or on the resource identified by the Request-URI 1360 and potentially its member resources, if the resource is a collection 1361 that has internal member URLs. All DAV compliant resources MUST 1362 support the PROPFIND method and the propfind XML element 1363 (Section 13.20) along with all XML elements defined for use with that 1364 element. 1366 A client may submit a Depth header with a value of "0", "1", or 1367 "infinity" with a PROPFIND on a collection resource. Servers MUST 1368 support the "0", "1" and "infinity" behaviors on WebDAV-compliant 1369 resources. By default, the PROPFIND method without a Depth header 1370 MUST act as if a "Depth: infinity" header was included. 1372 A client may submit a 'propfind' XML element in the body of the 1373 request method describing what information is being requested. It is 1374 possible to: 1376 o Request particular property values, by naming the properties 1377 desired within the 'prop' element (the ordering of properties in 1378 here MAY be ignored by server) 1380 o Request all dead property values, by using 'dead-props' element. 1381 This can be combined with retrieving specific live properties 1382 named as above. Servers advertising support for this 1383 specification MUST support this feature. 1385 o Request property values for those properties defined in this 1386 specification plus dead properties, by using 'allprop' element 1388 o Request a list of names of all the properties defined on the 1389 resource, by using the 'propname' element. 1391 A client may choose not to submit a request body. An empty PROPFIND 1392 request body MUST be treated as if it were an 'allprop' request. 1394 Note that 'allprop' does not return values for all live properties. 1395 WebDAV servers increasingly have expensively-calculated or lengthy 1396 properties (see [RFC3253] and [RFC3744]) and do not return all 1397 properties already. Instead, WebDAV clients can use propname 1398 requests to discover what live properties exist, and request named 1399 properties when retrieving values. A WebDAV server MAY omit certain 1400 live properties from other specifications when responding to an 1401 'allprop' request from an older client, and MAY return only custom 1402 (dead) properties and those defined in this specification. 1404 All servers MUST support returning a response of content type text/ 1405 xml or application/xml that contains a multistatus XML element that 1406 describes the results of the attempts to retrieve the various 1407 properties. 1409 If there is an error retrieving a property then a proper error result 1410 MUST be included in the response. A request to retrieve the value of 1411 a property which does not exist is an error and MUST be noted, if the 1412 response uses a 'multistatus' XML element, with a 'response' XML 1413 element which contains a 404 (Not Found) status value. 1415 Consequently, the 'multistatus' XML element for a collection resource 1416 with member URLs MUST include a 'response' XML element for each 1417 member URL of the collection, to whatever depth was requested. Each 1418 'response' XML element MUST contain an 'href' XML element that 1419 contains the URL of the resource on which the properties in the prop 1420 XML element are defined. Results for a PROPFIND on a collection 1421 resource with internal member URLs are returned as a flat list whose 1422 order of entries is not significant. 1424 Properties may be subject to access control. In the case of 1425 'allprop' and 'propname' requests, if a principal does not have the 1426 right to know whether a particular property exists then the property 1427 MAY be silently excluded from the response. 1429 The results of this method SHOULD NOT be cached. 1431 8.2.1. PROPFIND status codes 1433 This section, as with similar sections for other methods, provides 1434 some guidance on error codes and preconditions or postconditions 1435 (defined in Section 15) that might be particularly useful with 1436 PROPFIND. 1438 403 Forbidden - A server MAY reject all PROPFIND requests on 1439 collections with depth header of "Infinity", in which case it SHOULD 1440 use this error with the precondition code 'propfind-finite-depth' 1441 inside the error body. 1443 8.2.2. Status codes for use with 207 (Multi-Status) 1445 The following status codes are defined for use within the PROPFIND 1446 Multi-Status response: 1448 200 OK - A property exists and/or its value is successfully 1449 returned. 1451 401 Unauthorized - The property cannot be viewed without 1452 appropriate authorization. 1454 403 Forbidden - The property cannot be viewed regardless of 1455 authentication. 1457 404 Not Found - The property does not exist. 1459 8.2.3. Example - Retrieving Named Properties 1461 >>Request 1463 PROPFIND /file HTTP/1.1 1464 Host: www.example.com 1465 Content-type: application/xml; charset="utf-8" 1466 Content-Length: xxxx 1468 1469 1470 1471 1472 1473 1474 1475 1476 1478 >>Response 1480 HTTP/1.1 207 Multi-Status 1481 Content-Type: application/xml; charset="utf-8" 1482 Content-Length: xxxx 1484 1485 1486 1487 http://www.example.com/file 1488 1489 1490 1491 Box type A 1492 1493 1494 J.J. Johnson 1495 1496 1497 HTTP/1.1 200 OK 1498 1499 1500 1501 HTTP/1.1 403 Forbidden 1502 The user does not have access to the 1503 DingALing property. 1504 1505 1506 1507 There has been an access violation error. 1508 1509 1511 In this example, PROPFIND is executed on a non-collection resource 1512 http://www.example.com/file. The propfind XML element specifies the 1513 name of four properties whose values are being requested. In this 1514 case only two properties were returned, since the principal issuing 1515 the request did not have sufficient access rights to see the third 1516 and fourth properties. 1518 8.2.4. Example - Retrieving Named and Dead Properties 1520 >>Request 1522 PROPFIND /mycol/ HTTP/1.1 1523 Host: www.example.com 1524 Depth: 1 1525 Content-type: application/xml; charset="utf-8" 1526 Content-Length: xxxx 1528 1529 1530 1531 1532 1533 1534 1535 1537 In this example, PROPFIND is executed on a collection resource 1538 http://www.example.com/mycol/. The client requests the values of two 1539 specific live properties plus all dead properties (names and values). 1540 The response is not shown. 1542 8.2.5. Example - Using 'propname' to Retrieve all Property Names 1544 >>Request 1546 PROPFIND /container/ HTTP/1.1 1547 Host: www.example.com 1548 Content-Type: application/xml; charset="utf-8" 1549 Content-Length: xxxx 1551 1552 1553 1554 1556 >>Response 1558 HTTP/1.1 207 Multi-Status 1559 Content-Type: application/xml; charset="utf-8" 1560 Content-Length: xxxx 1562 1563 1564 1565 http://www.example.com/container/ 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 HTTP/1.1 200 OK 1576 1577 1578 1579 http://www.example.com/container/front.html 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 HTTP/1.1 200 OK 1593 1594 1595 1597 In this example, PROPFIND is invoked on the collection resource 1598 http://www.example.com/container/, with a propfind XML element 1599 containing the propname XML element, meaning the name of all 1600 properties should be returned. Since no Depth header is present, it 1601 assumes its default value of "infinity", meaning the name of the 1602 properties on the collection and all its descendents should be 1603 returned. 1605 Consistent with the previous example, resource 1606 http://www.example.com/container/ has six properties defined on it: 1607 bigbox and author in the "http://www.example.com/boxschema/" 1608 namespace, and creationdate, displayname, resourcetype, and 1609 supportedlock in the "DAV:" namespace. 1611 The resource http://www.example.com/container/index.html, a member of 1612 the "container" collection, has nine properties defined on it, bigbox 1613 in the "http://www.example.com/boxschema/" namespace and, 1614 creationdate, displayname, getcontentlength, getcontenttype, getetag, 1615 getlastmodified, resourcetype, and supportedlock in the "DAV:" 1616 namespace. 1618 This example also demonstrates the use of XML namespace scoping and 1619 the default namespace. Since the "xmlns" attribute does not contain 1620 a prefix, the namespace applies by default to all enclosed elements. 1621 Hence, all elements which do not explicitly state the namespace to 1622 which they belong are members of the "DAV:" namespace. 1624 8.2.6. Example - Using 'allprop' 1626 Note that 'allprop', despite its name which remains for backward- 1627 compatibility, does not return every property, but only dead 1628 properties and the live properties defined in this specification. 1630 >>Request 1632 PROPFIND /container/ HTTP/1.1 1633 Host: www.example.com 1634 Depth: 1 1635 Content-Type: application/xml; charset="utf-8" 1636 Content-Length: xxxx 1638 1639 1640 1641 1643 >>Response 1645 HTTP/1.1 207 Multi-Status 1646 Content-Type: application/xml; charset="utf-8" 1647 Content-Length: xxxx 1649 1650 1651 1652 /container/ 1653 1654 1655 Box type A 1656 Hadrian 1657 1997-12-01T17:42:21-08:00 1658 Example collection 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 HTTP/1.1 200 OK 1672 1673 1674 1675 /container/front.html 1676 1677 1678 Box type B 1679 1680 1997-12-01T18:27:21-08:00 1681 Example HTML resource 1682 4525 1683 text/html 1684 "zzyzx" 1685 Monday, 12-Jan-98 09:25:56 GMT 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 HTTP/1.1 200 OK 1701 1702 1703 1705 In this example, PROPFIND was invoked on the resource 1706 http://www.foo.bar/container/ with a Depth header of 1, meaning the 1707 request applies to the resource and its children, and a propfind XML 1708 element containing the allprop XML element, meaning the request 1709 should return the name and value of all the dead properties defined 1710 on the resources, plus the name and value of all the properties 1711 defined in this specification. This example illustrates the use of 1712 relative references in the 'href' elements of the response. 1714 The resource http://www.foo.bar/container/ has six properties defined 1715 on it: 'bigbox' and 'author in the "http://www.foo.bar/boxschema/" 1716 namespace, DAV:creationdate, DAV:displayname, DAV:resourcetype, and 1717 DAV:supportedlock. 1719 The last four properties are WebDAV-specific, defined in Section 14. 1720 Since GET is not supported on this resource, the get* properties 1721 (e.g., DAV:getcontentlength) are not defined on this resource. The 1722 WebDAV-specific properties assert that "container" was created on 1723 December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT 1724 (DAV:creationdate), has a name of "Example collection" (DAV: 1725 displayname), a collection resource type (DAV:resourcetype), and 1726 supports exclusive write and shared write locks (DAV:supportedlock). 1728 The resource http://www.foo.bar/container/front.html has nine 1729 properties defined on it: 1731 'bigbox' in the "http://www.foo.bar/boxschema/" namespace (another 1732 instance of the "bigbox" property type), DAV:creationdate, DAV: 1733 displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag, 1734 DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. 1736 The DAV-specific properties assert that "front.html" was created on 1737 December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT 1738 (DAV:creationdate), has a name of "Example HTML resource" (DAV: 1739 displayname), a content length of 4525 bytes (DAV:getcontentlength), 1740 a MIME type of "text/html" (DAV:getcontenttype), an entity tag of 1741 "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998, 1742 at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type, 1743 meaning that it is not a collection (DAV:resourcetype), and supports 1744 both exclusive write and shared write locks (DAV:supportedlock). 1746 8.3. PROPPATCH 1748 The PROPPATCH method processes instructions specified in the request 1749 body to set and/or remove properties defined on the resource 1750 identified by the Request-URI. 1752 All DAV compliant resources MUST support the PROPPATCH method and 1753 MUST process instructions that are specified using the 1754 propertyupdate, set, and remove XML elements. Execution of the 1755 directives in this method is, of course, subject to access control 1756 constraints. DAV compliant resources SHOULD support the setting of 1757 arbitrary dead properties. 1759 The request message body of a PROPPATCH method MUST contain the 1760 propertyupdate XML element. Instruction processing MUST occur in 1761 document order (an exception to the normal rule that ordering is 1762 irrelevant). Instructions MUST either all be executed or none 1763 executed. Thus if any error occurs during processing all executed 1764 instructions MUST be undone and a proper error result returned. 1765 Instruction processing details can be found in the definition of the 1766 set and remove instructions in Section 13.23 and Section 13.26. 1768 8.3.1. Status Codes for use in 207 (Multi-Status) 1770 The following are examples of response codes one would expect to be 1771 used in a 207 (Multi-Status) response for this method. Note, 1772 however, that unless explicitly prohibited any 2/3/4/5xx series 1773 response code may be used in a 207 (Multi-Status) response. 1775 200 (OK) - The property set or change succeeded. Note that if this 1776 appears for one property, it appears for every property in the 1777 response, due to the atomicity of PROPPATCH. 1779 403 (Forbidden) - The client, for reasons the server chooses not to 1780 specify, cannot alter one of the properties. 1782 403 (Forbidden): The client has attempted to set a read-only 1783 property, such as DAV:getetag. If returning this error, the server 1784 SHOULD use the precondition code 'writable-property' inside the 1785 response body. 1787 409 (Conflict) - The client has provided a value whose semantics are 1788 not appropriate for the property. 1790 424 (Failed Dependency) - The property change could not be made 1791 because of another property change that failed. 1793 507 (Insufficient Storage) - The server did not have sufficient space 1794 to record the property. 1796 8.3.2. Example - PROPPATCH 1798 >>Request 1800 PROPPATCH /bar.html HTTP/1.1 1801 Host: www.example.com 1802 Content-Type: application/xml; charset="utf-8" 1803 Content-Length: xxxx 1805 1806 1808 1809 1810 1811 Jim Whitehead 1812 Roy Fielding 1813 1814 1815 1816 1817 1818 1819 1821 >>Response 1823 HTTP/1.1 207 Multi-Status 1824 Content-Type: application/xml; charset="utf-8" 1825 Content-Length: xxxx 1827 1828 1830 1831 http://www.example.com/bar.html 1832 1833 1834 HTTP/1.1 424 Failed Dependency 1835 1836 1837 1838 HTTP/1.1 409 Conflict 1839 1840 Copyright Owner can not be deleted or 1841 altered. 1842 1843 1845 In this example, the client requests the server to set the value of 1846 the "Authors" property in the "http://www.w3.com/standards/z39.50/" 1847 namespace, and to remove the property "Copyright-Owner" in the 1848 "http://www.w3.com/standards/z39.50/" namespace. Since the 1849 Copyright-Owner property could not be removed, no property 1850 modifications occur. The 424 (Failed Dependency) status code for the 1851 Authors property indicates this action would have succeeded if it 1852 were not for the conflict with removing the Copyright-Owner property. 1854 8.4. MKCOL Method 1856 The MKCOL method is used to create a new collection. All WebDAV 1857 compliant resources MUST support the MKCOL method. 1859 MKCOL creates a new collection resource at the location specified by 1860 the Request-URI. If the Request-URI is already mapped to a resource 1861 then the MKCOL MUST fail. During MKCOL processing, a server MUST 1862 make the Request-URI a member of its parent collection, unless the 1863 Request-URI is "/". If no such ancestor exists, the method MUST 1864 fail. When the MKCOL operation creates a new collection resource, 1865 all ancestors MUST already exist, or the method MUST fail with a 409 1866 (Conflict) status code. For example, if a request to create 1867 collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the request 1868 must fail. 1870 When MKCOL is invoked without a request body, the newly created 1871 collection SHOULD have no members. 1873 A MKCOL request message may contain a message body. The precise 1874 behavior of a MKCOL request when the body is present is undefined, 1875 but limited to creating collections, members of a collection, bodies 1876 of members and properties on the collections or members. If the 1877 server receives a MKCOL request entity type it does not support or 1878 understand it MUST respond with a 415 (Unsupported Media Type) status 1879 code. If the server decides to reject the request based on the 1880 presence of an entity or the type of an entity, it should use the 415 1881 (Unsupported Media Type) status code. 1883 8.4.1. MKCOL Status Codes 1885 Responses from a MKCOL request MUST NOT be cached as MKCOL has non- 1886 idempotent semantics. In addition to the general status codes 1887 possible, the following status codes have specific applicability to 1888 MKCOL: 1890 201 (Created) - The collection was created. 1892 403 (Forbidden) - This indicates at least one of two conditions: 1) 1893 the server does not allow the creation of collections at the given 1894 location in its URL namespace, or 2) the parent collection of the 1895 Request-URI exists but cannot accept members. 1897 405 (Method Not Allowed) - MKCOL can only be executed on an unmapped 1898 URL. 1900 409 (Conflict) - A collection cannot be made at the Request-URI until 1901 one or more intermediate collections have been created. The server 1902 MUST NOT create those intermediate collections automatically. 1904 415 (Unsupported Media Type) - The server does not support the 1905 request body type (since this specification does not define any body 1906 for MKCOL requests). 1908 507 (Insufficient Storage) - The resource does not have sufficient 1909 space to record the state of the resource after the execution of this 1910 method. 1912 8.4.2. Example - MKCOL 1914 This example creates a collection called /webdisc/xfiles/ on the 1915 server www.example.com. 1917 >>Request 1919 MKCOL /webdisc/xfiles/ HTTP/1.1 1920 Host: www.example.com 1922 >>Response 1924 HTTP/1.1 201 Created 1926 8.5. GET, HEAD for Collections 1928 The semantics of GET are unchanged when applied to a collection, 1929 since GET is defined as, "retrieve whatever information (in the form 1930 of an entity) is identified by the Request-URI" [RFC2616]. GET when 1931 applied to a collection may return the contents of an "index.html" 1932 resource, a human-readable view of the contents of the collection, or 1933 something else altogether. Hence it is possible that the result of a 1934 GET on a collection will bear no correlation to the membership of the 1935 collection. 1937 Similarly, since the definition of HEAD is a GET without a response 1938 message body, the semantics of HEAD are unmodified when applied to 1939 collection resources. 1941 8.6. POST for Collections 1943 Since by definition the actual function performed by POST is 1944 determined by the server and often depends on the particular 1945 resource, the behavior of POST when applied to collections cannot be 1946 meaningfully modified because it is largely undefined. Thus the 1947 semantics of POST are unmodified when applied to a collection. 1949 8.7. DELETE 1951 DELETE is defined in [RFC2616], section 9.7, to "delete the resource 1952 identified by the Request-URI". However, WebDAV changes some DELETE 1953 handling requirements. 1955 A server processing a successful DELETE request: 1957 MUST destroy locks rooted on the deleted resource 1959 MUST remove the mapping from the Request-URI to any resource. 1961 Thus, after a successful DELETE operation (and in the absence of 1962 other actions) a subsequent GET/HEAD/PROPFIND request to the target 1963 Request-URI MUST return 404 (Not Found). 1965 8.7.1. DELETE for Collections 1967 The DELETE method on a collection MUST act as if a "Depth: infinity" 1968 header was used on it. A client MUST NOT submit a Depth header with 1969 a DELETE on a collection with any value but infinity. 1971 DELETE instructs that the collection specified in the Request-URI and 1972 all resources identified by its internal member URLs are to be 1973 deleted. 1975 If any resource identified by a member URL cannot be deleted then all 1976 of the member's ancestors MUST NOT be deleted, so as to maintain URL 1977 namespace consistency. 1979 Any headers included with DELETE MUST be applied in processing every 1980 resource to be deleted. 1982 When the DELETE method has completed processing it MUST result in a 1983 consistent URL namespace. 1985 If an error occurs deleting an internal resource (a resource other 1986 than the resource identified in the Request-URI) then the response 1987 can be a 207 (Multi-Status). Multi-Status is used here to indicate 1988 which internal resources could NOT be deleted, including an error 1989 code which should help the client understand which resources caused 1990 the failure. For example, the Multi-Status body could include a 1991 response with status 423 (Locked) if an internal resource was locked. 1993 The server MAY return a 4xx status response, rather than a 207, if 1994 the request failed completely. 1996 424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi- 1997 Status) response for DELETE. They can be safely left out because the 1998 client will know that the ancestors of a resource could not be 1999 deleted when the client receives an error for the ancestor's progeny. 2000 Additionally 204 (No Content) errors SHOULD NOT be returned in the 2001 207 (Multi-Status). The reason for this prohibition is that 204 (No 2002 Content) is the default success code. 2004 8.7.2. Example - DELETE 2006 >>Request 2008 DELETE /container/ HTTP/1.1 2009 Host: www.example.com 2011 >>Response 2013 HTTP/1.1 207 Multi-Status 2014 Content-Type: application/xml; charset="utf-8" 2015 Content-Length: xxxx 2017 2018 2019 2020 http://www.example.com/container/resource3 2021 HTTP/1.1 423 Locked 2022 2023 2025 In this example the attempt to delete 2026 http://www.example.com/container/resource3 failed because it is 2027 locked, and no lock token was submitted with the request. 2028 Consequently, the attempt to delete http://www.example.com/container/ 2029 also failed. Thus the client knows that the attempt to delete 2030 http://www.example.com/container/ must have also failed since the 2031 parent can not be deleted unless its child has also been deleted. 2032 Even though a Depth header has not been included, a depth of infinity 2033 is assumed because the method is on a collection. 2035 8.8. PUT 2037 8.8.1. PUT for Non-Collection Resources 2039 A PUT performed on an existing resource replaces the GET response 2040 entity of the resource. Properties defined on the resource may be 2041 recomputed during PUT processing but are not otherwise affected. For 2042 example, if a server recognizes the content type of the request body, 2043 it may be able to automatically extract information that could be 2044 profitably exposed as properties. 2046 A PUT that would result in the creation of a resource without an 2047 appropriately scoped parent collection MUST fail with a 409 2048 (Conflict). 2050 8.8.2. PUT for Collections 2052 This specification does not define the behavior of the PUT method for 2053 existing collections. A PUT request to an existing collection MAY be 2054 treated as an error (405 Method Not Allowed). 2056 The MKCOL method is defined to create collections. 2058 8.9. COPY 2060 The COPY method creates a duplicate of the source resource identified 2061 by the Request-URI, in the destination resource identified by the URI 2062 in the Destination header. The Destination header MUST be present. 2063 The exact behavior of the COPY method depends on the type of the 2064 source resource. 2066 All WebDAV compliant resources MUST support the COPY method. 2067 However, support for the COPY method does not guarantee the ability 2068 to copy a resource. For example, separate programs may control 2069 resources on the same server. As a result, it may not be possible to 2070 copy a resource to a location that appears to be on the same server. 2072 8.9.1. COPY for Non-collection Resources 2074 When the source resource is not a collection the result of the COPY 2075 method is the creation of a new resource at the destination whose 2076 state and behavior match that of the source resource as closely as 2077 possible. Since the environment at the destination may be different 2078 than at the source due to factors outside the scope of control of the 2079 server, such as the absence of resources required for correct 2080 operation, it may not be possible to completely duplicate the 2081 behavior of the resource at the destination. Subsequent alterations 2082 to the destination resource will not modify the source resource. 2083 Subsequent alterations to the source resource will not modify the 2084 destination resource. 2086 8.9.2. COPY for Properties 2088 After a successful COPY invocation, all dead properties on the source 2089 resource MUST be duplicated on the destination resource, along with 2090 all properties as appropriate. Live properties described in this 2091 document SHOULD be duplicated as identically behaving live properties 2092 at the destination resource, but not necessarily with the same 2093 values. Servers SHOULD NOT convert live properties into dead 2094 properties on the destination resource, because clients may then draw 2095 incorrect conclusions about the state or functionality of a resource. 2096 Note that some live properties are defined such that the absence of 2097 the property has a specific meaning (e.g. a flag with one meaning if 2098 present and the opposite if absent), and in these cases, a successful 2099 COPY might result in the property being reported as "Not Found" in 2100 subsequent requests. 2102 A COPY operation creates a new resource, much like a PUT operation 2103 does. Live properties which are related to resource creation (such 2104 as DAV:creationdate) should have their values set accordingly. 2106 8.9.3. COPY for Collections 2108 The COPY method on a collection without a Depth header MUST act as if 2109 a Depth header with value "infinity" was included. A client may 2110 submit a Depth header on a COPY on a collection with a value of "0" 2111 or "infinity". Servers MUST support the "0" and "infinity" Depth 2112 header behaviors on WebDAV-compliant resources. 2114 A COPY of depth infinity instructs that the collection resource 2115 identified by the Request-URI is to be copied to the location 2116 identified by the URI in the Destination header, and all its internal 2117 member resources are to be copied to a location relative to it, 2118 recursively through all levels of the collection hierarchy. Note 2119 that a depth infinity COPY of /A/ into /A/B/ could lead to infinite 2120 recursion if not handled correctly. 2122 A COPY of "Depth: 0" only instructs that the collection and its 2123 properties but not resources identified by its internal member URLs, 2124 are to be copied. 2126 Any headers included with a COPY MUST be applied in processing every 2127 resource to be copied with the exception of the Destination header. 2129 The Destination header only specifies the destination URI for the 2130 Request-URI. When applied to members of the collection identified by 2131 the Request-URI the value of Destination is to be modified to reflect 2132 the current location in the hierarchy. So, if the Request-URI is /a/ 2133 with Host header value http://example.com/ and the Destination is 2134 http://example.com/b/ then when http://example.com/a/c/d is processed 2135 it must use a Destination of http://example.com/b/c/d. 2137 When the COPY method has completed processing it MUST have created a 2138 consistent URL namespace at the destination (see Section 5.1 for the 2139 definition of namespace consistency). However, if an error occurs 2140 while copying an internal collection, the server MUST NOT copy any 2141 resources identified by members of this collection (i.e., the server 2142 must skip this subtree), as this would create an inconsistent 2143 namespace. After detecting an error, the COPY operation SHOULD try 2144 to finish as much of the original copy operation as possible (i.e., 2145 the server should still attempt to copy other subtrees and their 2146 members, that are not descendents of an error-causing collection). 2148 So, for example, if an infinite depth copy operation is performed on 2149 collection /a/, which contains collections /a/b/ and /a/c/, and an 2150 error occurs copying /a/b/, an attempt should still be made to copy 2151 /a/c/. Similarly, after encountering an error copying a non- 2152 collection resource as part of an infinite depth copy, the server 2153 SHOULD try to finish as much of the original copy operation as 2154 possible. 2156 If an error in executing the COPY method occurs with a resource other 2157 than the resource identified in the Request-URI then the response 2158 MUST be a 207 (Multi-Status), and the URL of the resource causing the 2159 failure MUST appear with the specific error. 2161 The 424 (Failed Dependency) status code SHOULD NOT be returned in the 2162 207 (Multi-Status) response from a COPY method. These responses can 2163 be safely omitted because the client will know that the progeny of a 2164 resource could not be copied when the client receives an error for 2165 the parent. Additionally 201 (Created)/204 (No Content) status codes 2166 SHOULD NOT be returned as values in 207 (Multi-Status) responses from 2167 COPY methods. They, too, can be safely omitted because they are the 2168 default success codes. 2170 8.9.4. COPY and Overwriting Destination Resources 2172 If a COPY request has an Overwrite header with a value of "F", and a 2173 resource exists at the Destination URL, the server MUST fail the 2174 request. 2176 When a server executes a COPY request and overwrites a destination 2177 resource, the exact behavior MAY depend on many factors, including 2178 WebDAV extension capabilities (see particularly [RFC3253]). For 2179 example, when an ordinary resource is overwritten, the server could 2180 delete the target resource before doing the copy, or could do an in- 2181 place overwrite to preserve live properties. 2183 When a collection is overwritten, the membership of the destination 2184 collection after the successful COPY request MUST be the same 2185 membership as the source collection immediately before the COPY. 2186 Thus, merging the membership of the source and destination 2187 collections together in the destination is not a compliant behavior. 2189 In general, if clients require the state of the destination URL to be 2190 wiped out prior to a COPY (e.g. to force live properties to be 2191 reset), then the client could send a DELETE to the destination before 2192 the COPY request to ensure this reset. 2194 8.9.5. Status Codes 2196 In addition to the general status codes possible, the following 2197 status codes have specific applicability to COPY: 2199 201 (Created) - The source resource was successfully copied. The 2200 COPY operation resulted in the creation of a new resource. 2202 204 (No Content) - The source resource was successfully copied to a 2203 pre-existing destination resource. 2205 207 (Multi-Status) - Multiple resources were to be affected by the 2206 COPY, but errors on some of them prevented the operation from taking 2207 place. Specific error messages, together with the most appropriate 2208 of the source and destination URLs, appear in the body of the multi- 2209 status response. E.g. if a destination resource was locked and could 2210 not be overwritten, then the destination resource URL appears with 2211 the 423 (Locked) status. 2213 403 (Forbidden) - The operation is forbidden. A special case for 2214 COPY could be that the source and destination resources are the same 2215 resource. 2217 409 (Conflict) - A resource cannot be created at the destination 2218 until one or more intermediate collections have been created. The 2219 server MUST NOT create those intermediate collections automatically. 2221 412 (Precondition Failed) - A precondition header check failed, e.g. 2222 the Overwrite header is "F" and the destination URL is already mapped 2223 to a resource. 2225 423 (Locked) - The destination resource, or resource within the 2226 destination collection, was locked. This response SHOULD contain the 2227 'lock-token-present' precondition element. 2229 502 (Bad Gateway) - This may occur when the destination is on another 2230 server, repository or URL namespace. Either the source namespace 2231 does not support copying to the destination namespace, or the 2232 destination namespace refuses to accept the resource. The client may 2233 wish to try GET/PUT and PROPFIND/PROPPATCH instead. 2235 507 (Insufficient Storage) - The destination resource does not have 2236 sufficient space to record the state of the resource after the 2237 execution of this method. 2239 8.9.6. Example - COPY with Overwrite 2241 This example shows resource 2242 http://www.ics.uci.edu/~fielding/index.html being copied to the 2243 location http://www.ics.uci.edu/users/f/fielding/index.html. The 204 2244 (No Content) status code indicates the existing resource at the 2245 destination was overwritten. 2247 >>Request 2249 COPY /~fielding/index.html HTTP/1.1 2250 Host: www.ics.uci.edu 2251 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 2253 >>Response 2255 HTTP/1.1 204 No Content 2257 8.9.7. Example - COPY with No Overwrite 2259 The following example shows the same copy operation being performed, 2260 but with the Overwrite header set to "F." A response of 412 2261 (Precondition Failed) is returned because the destination URL is 2262 already mapped to a resource. 2264 >>Request 2266 COPY /~fielding/index.html HTTP/1.1 2267 Host: www.ics.uci.edu 2268 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 2269 Overwrite: F 2271 >>Response 2273 HTTP/1.1 412 Precondition Failed 2275 8.9.8. Example - COPY of a Collection 2277 >>Request 2279 COPY /container/ HTTP/1.1 2280 Host: www.example.com 2281 Destination: http://www.example.com/othercontainer/ 2282 Depth: infinity 2284 >>Response 2286 HTTP/1.1 207 Multi-Status 2287 Content-Type: application/xml; charset="utf-8" 2288 Content-Length: xxxx 2290 2292 2293 2294 http://www.example.com/othercontainer/R2/ 2295 HTTP/1.1 423 Locked 2296 2297 2299 The Depth header is unnecessary as the default behavior of COPY on a 2300 collection is to act as if a "Depth: infinity" header had been 2301 submitted. In this example most of the resources, along with the 2302 collection, were copied successfully. However the collection R2 2303 failed because the destination R2 is locked. Because there was an 2304 error copying R2, none of R2's members were copied. However no 2305 errors were listed for those members due to the error minimization 2306 rules. 2308 8.10. MOVE 2310 The MOVE operation on a non-collection resource is the logical 2311 equivalent of a copy (COPY), followed by consistency maintenance 2312 processing, followed by a delete of the source, where all three 2313 actions are performed atomically. The consistency maintenance step 2314 allows the server to perform updates caused by the move, such as 2315 updating all URLs other than the Request-URI which identify the 2316 source resource, to point to the new destination resource. 2317 Consequently, the Destination header MUST be present on all MOVE 2318 methods and MUST follow all COPY requirements for the COPY part of 2319 the MOVE method. All WebDAV compliant resources MUST support the 2320 MOVE method. However, support for the MOVE method does not guarantee 2321 the ability to move a resource to a particular destination. 2323 For example, separate programs may actually control different sets of 2324 resources on the same server. Therefore, it may not be possible to 2325 move a resource within a namespace that appears to belong to the same 2326 server. 2328 If a resource exists at the destination, the destination resource 2329 will be deleted as a side-effect of the MOVE operation, subject to 2330 the restrictions of the Overwrite header. 2332 8.10.1. MOVE for Properties 2334 Live properties described in this document SHOULD be moved along with 2335 the resource, such that the resource has identically behaving live 2336 properties at the destination resource, but not necessarily with the 2337 same values. Note that some live properties are defined such that 2338 the absence of the property has a specific meaning (e.g. a flag with 2339 one meaning if present and the opposite if absent), and in these 2340 cases, a successful MOVE might result in the property being reported 2341 as "Not Found" in subsequent requests. If the live properties will 2342 not work the same way at the destination, the server MAY fail the 2343 request. 2345 MOVE is frequently used by clients to rename a file without changing 2346 its parent collection, so it's not appropriate to reset all live 2347 properties which are set at resource creation. For example, the DAV: 2348 creationdate property value SHOULD remain the same after a MOVE. 2350 Dead properties MUST be moved along with the resource. 2352 8.10.2. MOVE for Collections 2354 A MOVE with "Depth: infinity" instructs that the collection 2355 identified by the Request-URI be moved to the address specified in 2356 the Destination header, and all resources identified by its internal 2357 member URLs are to be moved to locations relative to it, recursively 2358 through all levels of the collection hierarchy. 2360 The MOVE method on a collection MUST act as if a "Depth: infinity" 2361 header was used on it. A client MUST NOT submit a Depth header on a 2362 MOVE on a collection with any value but "infinity". 2364 Any headers included with MOVE MUST be applied in processing every 2365 resource to be moved with the exception of the Destination header. 2366 The behavior of the Destination header is the same as given for COPY 2367 on collections. 2369 When the MOVE method has completed processing it MUST have created a 2370 consistent URL namespace at both the source and destination (see 2371 section 5.1 for the definition of namespace consistency). However, 2372 if an error occurs while moving an internal collection, the server 2373 MUST NOT move any resources identified by members of the failed 2374 collection (i.e., the server must skip the error-causing subtree), as 2375 this would create an inconsistent namespace. In this case, after 2376 detecting the error, the move operation SHOULD try to finish as much 2377 of the original move as possible (i.e., the server should still 2378 attempt to move other subtrees and the resources identified by their 2379 members, that are not descendents of an error-causing collection). 2381 So, for example, if an infinite depth move is performed on collection 2382 /a/, which contains collections /a/b/ and /a/c/, and an error occurs 2383 moving /a/b/, an attempt should still be made to try moving /a/c/. 2384 Similarly, after encountering an error moving a non-collection 2385 resource as part of an infinite depth move, the server SHOULD try to 2386 finish as much of the original move operation as possible. 2388 If an error occurs with a resource other than the resource identified 2389 in the Request-URI then the response MUST be a 207 (Multi-Status), 2390 and the errored resource's URL MUST appear with the specific error. 2392 The 424 (Failed Dependency) status code SHOULD NOT be returned in the 2393 207 (Multi-Status) response from a MOVE method. These errors can be 2394 safely omitted because the client will know that the progeny of a 2395 resource could not be moved when the client receives an error for the 2396 parent. Additionally 201 (Created)/204 (No Content) responses SHOULD 2397 NOT be returned as values in 207 (Multi-Status) responses from a 2398 MOVE. These responses can be safely omitted because they are the 2399 default success codes. 2401 8.10.3. MOVE and the Overwrite Header 2403 If a resource exists at the destination and the Overwrite header is 2404 "T" then prior to performing the move the server MUST perform a 2405 DELETE with "Depth: infinity" on the destination resource. If the 2406 Overwrite header is set to "F" then the operation will fail. 2408 8.10.4. Status Codes 2410 In addition to the general status codes possible, the following 2411 status codes have specific applicability to MOVE: 2413 201 (Created) - The source resource was successfully moved, and a new 2414 URL mapping was created at the destination. 2416 204 (No Content) - The source resource was successfully moved to a 2417 URL that was already mapped. 2419 207 (Multi-Status) - Multiple resources were to be affected by the 2420 MOVE, but errors on some of them prevented the operation from taking 2421 place. Specific error messages, together with the most appropriate 2422 of the source and destination URLs, appear in the body of the multi- 2423 status response. E.g. if a source resource was locked and could not 2424 be moved, then the source resource URL appears with the 423 (Locked) 2425 status. 2427 403 (Forbidden) - Among many possible reasons for forbidding a MOVE 2428 operation, this status code is recommended for use when the source 2429 and destination resources are the same. 2431 409 (Conflict) - A resource cannot be created at the destination 2432 until one or more intermediate collections have been created. The 2433 server MUST NOT create those intermediate collections automatically. 2434 Or, the server was unable to preserve the behavior of the live 2435 properties and still move the resource to the destination (see 2436 'preserved-live-properties' postcondition). 2438 412 (Precondition Failed) - A condition header failed. Specific to 2439 MOVE, this could mean that the Overwrite header is "F" and the state 2440 of the destination URL is already mapped to a resource. 2442 423 (Locked) - The source or the destination resource, the source or 2443 destination resource parent, or some resource within the source or 2444 destination collection, was locked. This response SHOULD contain the 2445 'lock-token-present' precondition element. 2447 502 (Bad Gateway) - This may occur when the destination is on another 2448 server and the destination server refuses to accept the resource. 2449 This could also occur when the destination is on another sub-section 2450 of the same server namespace. 2452 8.10.5. Example - MOVE of a Non-Collection 2454 This example shows resource 2455 http://www.ics.uci.edu/~fielding/index.html being moved to the 2456 location http://www.ics.uci.edu/users/f/fielding/index.html. The 2457 contents of the destination resource would have been overwritten if 2458 the destination URL was already mapped to a resource. In this case, 2459 since there was nothing at the destination resource, the response 2460 code is 201 (Created). 2462 >>Request 2464 MOVE /~fielding/index.html HTTP/1.1 2465 Host: www.ics.uci.edu 2466 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 2468 >>Response 2470 HTTP/1.1 201 Created 2471 Location: http://www.ics.uci.edu/users/f/fielding/index.html 2473 8.10.6. Example - MOVE of a Collection 2475 >>Request 2477 MOVE /container/ HTTP/1.1 2478 Host: www.example.com 2479 Destination: http://www.example.com/othercontainer/ 2480 Overwrite: F 2481 If: () 2482 () 2484 >>Response 2486 HTTP/1.1 207 Multi-Status 2487 Content-Type: application/xml; charset="utf-8" 2488 Content-Length: xxxx 2490 2491 2492 2493 http://www.example.com/othercontainer/C2/ 2494 HTTP/1.1 423 Locked 2495 2496 2498 In this example the client has submitted a number of lock tokens with 2499 the request. A lock token will need to be submitted for every 2500 resource, both source and destination, anywhere in the scope of the 2501 method, that is locked. In this case the proper lock token was not 2502 submitted for the destination 2503 http://www.example.com/othercontainer/C2/. This means that the 2504 resource /container/C2/ could not be moved. Because there was an 2505 error moving /container/C2/, none of /container/C2's members were 2506 moved. However no errors were listed for those members due to the 2507 error minimization rules. User agent authentication has previously 2508 occurred via a mechanism outside the scope of the HTTP protocol, in 2509 an underlying transport layer. 2511 8.11. LOCK Method 2513 The following sections describe the LOCK method, which is used to 2514 take out a lock of any access type and to refresh an existing lock. 2515 These sections on the LOCK method describe only those semantics that 2516 are specific to the LOCK method and are independent of the access 2517 type of the lock being requested. 2519 Any resource which supports the LOCK method MUST, at minimum, support 2520 the XML request and response formats defined herein. 2522 A LOCK method invocation to an unlocked resource creates a lock on 2523 the resource identified by the Request-URI, which becomes the root of 2524 the lock. Lock method requests to create a new lock MUST have a XML 2525 request body which contains an owner XML element and other 2526 information for this lock request. The server MUST preserve the 2527 information provided by the client in the 'owner' field when the lock 2528 information is requested. The LOCK request MAY have a Timeout 2529 header. 2531 Clients MUST assume that locks may arbitrarily disappear at any time, 2532 regardless of the value given in the Timeout header. The Timeout 2533 header only indicates the behavior of the server if extraordinary 2534 circumstances do not occur. For example, a sufficiently privileged 2535 user may remove a lock at any time or the system may crash in such a 2536 way that it loses the record of the lock's existence. 2538 When a new lock is created, the LOCK response: 2540 o MUST contain a body with the value of the DAV:lockdiscovery 2541 property in a prop XML element. This MUST contain the full 2542 information about the lock just granted, while information about 2543 other (shared) locks is OPTIONAL. 2545 o MUST include the Lock-Token response header with the token 2546 associated with the new lock. 2548 8.11.1. Refreshing Locks 2550 A lock is refreshed by sending a LOCK request without a request body 2551 to the URL of a resource within the scope of the lock. This request 2552 MUST specify which lock to refresh by using the 'Lock-Token' header 2553 with a single lock token (only one lock may be refreshed at a time). 2554 It MAY contain a Timeout header, which a server MAY accept to change 2555 the duration remaining on the lock to the new value. A server MUST 2556 ignore the Depth header on a LOCK refresh. 2558 If the resource has other (shared) locks, those locks are unaffected 2559 by a lock refresh. Additionally, those locks do not prevent the 2560 named lock from being refreshed. 2562 Note that in RFC2518, clients were indicated through the example in 2563 the text to use the If header to specify what lock to refresh (rather 2564 than the Lock-Token header). Servers are encouraged to continue to 2565 support this as well as the Lock-Token header. 2567 Note that the Lock-Token header is not be returned in the response 2568 for a successful refresh LOCK request, but the LOCK response body 2569 MUST contain the new value for the DAV:lockdiscovery body. 2571 8.11.2. Depth and Locking 2573 The Depth header may be used with the LOCK method. Values other than 2574 0 or infinity MUST NOT be used with the Depth header on a LOCK 2575 method. All resources that support the LOCK method MUST support the 2576 Depth header. 2578 A Depth header of value 0 means to just lock the resource specified 2579 by the Request-URI. 2581 If the Depth header is set to infinity then the resource specified in 2582 the Request-URI along with all its internal members, all the way down 2583 the hierarchy, are to be locked. A successful result MUST return a 2584 single lock token which represents all the resources that have been 2585 locked. If an UNLOCK is successfully executed on this token, all 2586 associated resources are unlocked. Hence, partial success is not an 2587 option. Either the entire hierarchy is locked or no resources are 2588 locked. 2590 If the lock cannot be granted to all resources, the server MUST 2591 return a Multi-Status response with a 'response' element for at least 2592 one resource which prevented the lock from being granted, along with 2593 a suitable status code for that failure (e.g. 403 (Forbidden) or 423 2594 (Locked)). Additionally, if the resource causing the failure was not 2595 the resource requested, then the server MUST include a 'response' 2596 element for the Request-URI as well, with a 'status' element 2597 containing 424 Failed Dependency. 2599 If no Depth header is submitted on a LOCK request then the request 2600 MUST act as if a "Depth:infinity" had been submitted. 2602 8.11.3. Locking Unmapped URLs 2604 A successful LOCK method MUST result in the creation of an empty 2605 resource which is locked (and which is not a collection), when a 2606 resource did not previously exist at that URL. Later on, the lock 2607 may go away but the empty resource remains. Empty resources MUST 2608 then appear in PROPFIND responses including that URL in the response 2609 scope. A server MUST respond successfully to a GET request to an 2610 empty resource, either by using a 204 No Content response, or by 2611 using 200 OK with a Content-Length header indicating zero length and 2612 no Content-Type. 2614 8.11.4. Lock Compatibility Table 2616 The table below describes the behavior that occurs when a lock 2617 request is made on a resource. 2619 +--------------------------+----------------+-------------------+ 2620 | Current State | Shared Lock OK | Exclusive Lock OK | 2621 +--------------------------+----------------+-------------------+ 2622 | None | True | True | 2623 | | | | 2624 | Shared Lock | True | False | 2625 | | | | 2626 | Exclusive Lock | False | False* | 2627 +--------------------------+----------------+-------------------+ 2629 Legend: True = lock may be granted. False = lock MUST NOT be 2630 granted. *=It is illegal for a principal to request the same lock 2631 twice. 2633 The current lock state of a resource is given in the leftmost column, 2634 and lock requests are listed in the first row. The intersection of a 2635 row and column gives the result of a lock request. For example, if a 2636 shared lock is held on a resource, and an exclusive lock is 2637 requested, the table entry is "false", indicating the lock must not 2638 be granted. 2640 8.11.5. LOCK Responses 2642 In addition to the general status codes possible, the following 2643 status codes have specific applicability to LOCK: 2645 200 (OK) - The LOCK request succeeded and the value of the DAV: 2646 lockdiscovery property is included in the response body. 2648 201 (Created) - The LOCK request was to an unmapped URL, the request 2649 succeeded and resulted in the creation of a new resource, and the 2650 value of the DAV:lockdiscovery property is included in the response 2651 body. 2653 409 (Conflict) - A resource cannot be created at the destination 2654 until one or more intermediate collections have been created. The 2655 server MUST NOT create those intermediate collections automatically. 2657 423 (Locked) - The resource is locked already. 2659 400 (Bad Request), with 'lock-token-matches-request-uri' precondition 2660 code - The LOCK request was made with a Lock-Token header, indicating 2661 that the client wishes to refresh the given lock. However, the 2662 Request-URI did not fall within the scope of the lock identified by 2663 the token. The lock may have a scope that does not include the 2664 Request-URI, or the lock could have disappeared, or the token may be 2665 invalid. 2667 8.11.6. Example - Simple Lock Request 2669 >>Request 2671 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2672 Host: example.com 2673 Timeout: Infinite, Second-4100000000 2674 Content-Type: application/xml; charset="utf-8" 2675 Content-Length: xxxx 2676 Authorization: Digest username="ejw", 2677 realm="ejw@example.com", nonce="...", 2678 uri="/workspace/webdav/proposal.doc", 2679 response="...", opaque="..." 2681 2682 2683 2684 2685 2686 http://www.ics.uci.edu/~ejw/contact.html 2687 2688 2690 >>Response 2692 HTTP/1.1 200 OK 2693 Lock-Token: 2694 Content-Type: application/xml; charset="utf-8" 2695 Content-Length: xxxx 2697 2698 2699 2700 2701 2702 2703 infinity 2704 2705 http://www.ics.uci.edu/~ejw/contact.html 2706 2707 Second-604800 2708 2709 urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2711 2712 2713 http://example.com/workspace/webdav/proposal.doc 2715 2716 2717 2718 2720 This example shows the successful creation of an exclusive write lock 2721 on resource http://example.com/workspace/webdav/proposal.doc. The 2722 resource http://www.ics.uci.edu/~ejw/contact.html contains contact 2723 information for the owner of the lock. The server has an activity- 2724 based timeout policy in place on this resource, which causes the lock 2725 to automatically be removed after 1 week (604800 seconds). Note that 2726 the nonce, response, and opaque fields have not been calculated in 2727 the Authorization request header. 2729 8.11.7. Example - Refreshing a Write Lock 2731 >>Request 2733 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2734 Host: example.com 2735 Timeout: Infinite, Second-4100000000 2736 Lock-Token: 2737 Authorization: Digest username="ejw", 2738 realm="ejw@example.com", nonce="...", 2739 uri="/workspace/webdav/proposal.doc", 2740 response="...", opaque="..." 2742 >>Response 2744 HTTP/1.1 200 OK 2745 Content-Type: application/xml; charset="utf-8" 2746 Content-Length: xxxx 2748 2749 2750 2751 2752 2753 2754 infinity 2755 2756 http://www.ics.uci.edu/~ejw/contact.html 2757 2758 Second-604800 2759 2760 urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2762 2763 2764 http://example.com/workspace/webdav/proposal.doc 2766 2767 2768 2769 2771 This request would refresh the lock, attempting to reset the timeout 2772 to the new value specified in the timeout header. Notice that the 2773 client asked for an infinite time out but the server choose to ignore 2774 the request. In this example, the nonce, response, and opaque fields 2775 have not been calculated in the Authorization request header. 2777 8.11.8. Example - Multi-Resource Lock Request 2779 >>Request 2781 LOCK /webdav/ HTTP/1.1 2782 Host: example.com 2783 Timeout: Infinite, Second-4100000000 2784 Depth: infinity 2785 Content-Type: application/xml; charset="utf-8" 2786 Content-Length: xxxx 2787 Authorization: Digest username="ejw", 2788 realm="ejw@example.com", nonce="...", 2789 uri="/workspace/webdav/proposal.doc", 2790 response="...", opaque="..." 2792 2793 2794 2795 2796 2797 http://www.ics.uci.edu/~ejw/contact.html 2798 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://example.com/webdav/secret 2811 HTTP/1.1 403 Forbidden 2812 2813 2814 http://example.com/webdav/ 2815 HTTP/1.1 424 Failed Dependency 2816 2817 2819 This example shows a request for an exclusive write lock on a 2820 collection and all its children. In this request, the client has 2821 specified that it desires an infinite length lock, if available, 2822 otherwise a timeout of 4.1 billion seconds, if available. The 2823 request entity body contains the contact information for the 2824 principal taking out the lock, in this case a web page URL. 2826 The error is a 403 (Forbidden) response on the resource 2827 http://example.com/webdav/secret. Because this resource could not be 2828 locked, none of the resources were locked. Note also that the a 2829 'response' element for the Request-URI itself has been included as 2830 required. 2832 In this example, the nonce, response, and opaque fields have not been 2833 calculated in the Authorization request header. 2835 8.12. UNLOCK Method 2837 The UNLOCK method removes the lock identified by the lock token in 2838 the Lock-Token request header. The Request-URI MUST identify a 2839 resource within the scope of the lock. 2841 Note that use of Lock-Token header to provide the lock token is not 2842 consistent with other state-changing methods which all require an If 2843 header with the lock token. Thus, the If header is not needed to 2844 provide the lock token. Naturally when the If header is present it 2845 has its normal meaning as a conditional header. 2847 For a successful response to this method, the server MUST remove the 2848 lock from the resource identified by the Request-URI and from all 2849 other resources included in the lock. 2851 If all resources which have been locked under the submitted lock 2852 token can not be unlocked then the UNLOCK request MUST fail. 2854 A successful response to an UNLOCK method does not mean that the 2855 resource is necessarily unlocked. It means that the specific lock 2856 corresponding to the specified token no longer exists. 2858 Any DAV compliant resource which supports the LOCK method MUST 2859 support the UNLOCK method. 2861 8.12.1. Status Codes 2863 In addition to the general status codes possible, the following 2864 status codes have specific applicability to UNLOCK: 2866 204 (No Content) - Normal success response (rather than 200 OK, since 2867 200 OK would imply a response body, and an UNLOCK success response 2868 does not normally contain a body) 2870 400 (Bad Request) - No lock token was provided (see 'lock-token- 2871 present' precondition), or request was made to a Request-URI that was 2872 not within the scope of the lock (see 'lock-token-matches-request- 2873 uri' precondition). 2875 403 (Forbidden) - The currently authenticated principal does not have 2876 permission to remove the lock. 2878 409 (Conflict) - The resource was not locked and thus could not be 2879 unlocked. 2881 8.12.2. Example - UNLOCK 2883 >>Request 2885 UNLOCK /workspace/webdav/info.doc HTTP/1.1 2886 Host: example.com 2887 Lock-Token: 2888 Authorization: Digest username="ejw" 2889 realm="ejw@example.com", nonce="...", 2890 uri="/workspace/webdav/proposal.doc", 2891 response="...", opaque="..." 2893 >>Response 2895 HTTP/1.1 204 No Content 2897 In this example, the lock identified by the lock token 2898 "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully 2899 removed from the resource 2900 http://example.com/workspace/webdav/info.doc. If this lock included 2901 more than just one resource, the lock is removed from all resources 2902 included in the lock. The 204 (No Content) status code is used 2903 instead of 200 (OK) because there is no response entity body. 2905 In this example, the nonce, response, and opaque fields have not been 2906 calculated in the Authorization request header. 2908 9. HTTP Headers for Distributed Authoring 2910 All DAV headers follow the same basic formatting rules as HTTP 2911 headers. This includes rules like line continuation and how to 2912 combine (or separate) multiple instances of the same header using 2913 commas. WebDAV adds two new conditional headers to the set defined 2914 in HTTP: the If and Overwrite headers. 2916 9.1. DAV Header 2918 DAV = "DAV" ":" #( compliance-class ) 2919 compliance-class = ( "1" | "2" | "bis" | extend ) 2920 extend = Coded-URL | token 2921 Coded-URL = "<" absolute-URI ">" 2922 ; No LWS allowed in Coded-URL 2923 ; absolute-URI is defined in RFC3986 2925 This general-header appearing in the response indicates that the 2926 resource supports the DAV schema and protocol as specified. All DAV 2927 compliant resources MUST return the DAV header with compliance-class 2928 "1" on all OPTIONS responses. 2930 The value is a comma-separated list of all compliance class 2931 identifiers that the resource supports. Class identifiers may be 2932 Coded-URLs or tokens (as defined by [RFC2616]). Identifiers can 2933 appear in any order. Identifiers that are standardized through the 2934 IETF RFC process are tokens, but other identifiers SHOULD be Coded- 2935 URLs to encourage uniqueness. 2937 A resource must show class 1 compliance if it shows class 2 or "bis" 2938 compliance. In general, support for one compliance class does not 2939 entail support for any other. Please refer to section 16 for more 2940 details on compliance classes defined in this specification. 2942 This header must also appear on responses to OPTIONS requests to the 2943 special '*' Request-URI as defined in HTTP/1.1. In this case it 2944 means that the repository supports the named features in at least 2945 some internal URL namespaces. 2947 As a request header, this header allows the client to advertise 2948 compliance with named features when the server needs that 2949 information. Clients SHOULD NOT send this header unless a standards 2950 track specification requires it. Any extension that makes use of 2951 this as a request header will need to carefully consider caching 2952 implications. 2954 9.2. Depth Header 2955 Depth = "Depth" ":" ("0" | "1" | "infinity") 2957 The Depth request header is used with methods executed on resources 2958 which could potentially have internal members to indicate whether the 2959 method is to be applied only to the resource ("Depth: 0"), to the 2960 resource and its immediate children, ("Depth: 1"), or the resource 2961 and all its progeny ("Depth: infinity"). 2963 The Depth header is only supported if a method's definition 2964 explicitly provides for such support. 2966 The following rules are the default behavior for any method that 2967 supports the Depth header. A method may override these defaults by 2968 defining different behavior in its definition. 2970 Methods which support the Depth header may choose not to support all 2971 of the header's values and may define, on a case by case basis, the 2972 behavior of the method if a Depth header is not present. For 2973 example, the MOVE method only supports "Depth: infinity" and if a 2974 Depth header is not present will act as if a "Depth: infinity" header 2975 had been applied. 2977 Clients MUST NOT rely upon methods executing on members of their 2978 hierarchies in any particular order or on the execution being atomic 2979 unless the particular method explicitly provides such guarantees. 2981 Upon execution, a method with a Depth header will perform as much of 2982 its assigned task as possible and then return a response specifying 2983 what it was able to accomplish and what it failed to do. 2985 So, for example, an attempt to COPY a hierarchy may result in some of 2986 the members being copied and some not. 2988 Any headers on a method that has a defined interaction with the Depth 2989 header MUST be applied to all resources in the scope of the method 2990 except where alternative behavior is explicitly defined. For 2991 example, an If-Match header will have its value applied against every 2992 resource in the method's scope and will cause the method to fail if 2993 the header fails to match. 2995 If a resource, source or destination, within the scope of the method 2996 with a Depth header is locked in such a way as to prevent the 2997 successful execution of the method, then the lock token for that 2998 resource MUST be submitted with the request in the If request header. 3000 The Depth header only specifies the behavior of the method with 3001 regards to internal children. If a resource does not have internal 3002 children then the Depth header MUST be ignored. 3004 Please note, however, that it is always an error to submit a value 3005 for the Depth header that is not allowed by the method's definition. 3006 Thus submitting a "Depth: 1" on a COPY, even if the resource does not 3007 have internal members, will result in a 400 (Bad Request). The 3008 method should fail not because the resource doesn't have internal 3009 members, but because of the illegal value in the header. 3011 9.3. Destination Header 3013 Destination = "Destination" ":" ( absolute-URI ) 3015 The Destination request header specifies the URI which identifies a 3016 destination resource for methods such as COPY and MOVE, which take 3017 two URIs as parameters. Note that the absolute-URI production is 3018 defined in [RFC3986]. 3020 If the Destination value is an absolute URI, it may name a different 3021 server (or different port or scheme). If the source server cannot 3022 attempt a copy to the remote server, it MUST fail the request with a 3023 502 (Bad Gateway) response. 3025 9.4. If Header 3027 If = "If" ":" ( 1*No-tag-list | 1*Tagged-list) 3028 No-tag-list = List 3029 Tagged-list = Resource 1*List 3030 Resource = Coded-URL 3031 List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")" 3032 ; No LWS allowed between "[", entity-tag and "]" 3033 State-token = Coded-URL 3035 The If request header is intended to have similar functionality to 3036 the If-Match header defined in section 14.24 of [RFC2616]. However 3037 the If header is intended for use with any URI which represents state 3038 information, referred to as a state token, about a resource as well 3039 as ETags. A typical example of a state token is a lock token, and 3040 lock tokens are the only state tokens defined in this specification. 3041 The state token is an example of a state token that 3042 will never match an actual valid lock token. The purpose of this is 3043 described in Section 9.4.4. 3045 The If header's purpose is to describe a series of state lists. If 3046 the state of the resource to which the header is applied does not 3047 match any of the specified state lists then the request MUST fail 3048 with a 412 (Precondition Failed). If one of the described state 3049 lists matches the state of the resource then the request may succeed. 3051 The server MUST do authorization checks before checking this or any 3052 conditional header. Assuming no other errors, the server MUST parse 3053 the If header when it appears on any request, evaluate all the 3054 clauses, and if the conditional evaluates to false, fail as described 3055 above. 3057 9.4.1. No-tag-list Production 3059 The No-tag-list production describes a series of state tokens and 3060 ETags. If multiple No-tag-list productions are used then one only 3061 needs to match the state of the resource for the method to be allowed 3062 to continue. All untagged tokens apply to the resource identified in 3063 the Request-URI. 3065 Example - no-tag-list production 3067 If: ( 3068 ["I am an ETag"]) (["I am another ETag"]) 3070 The previous header would require that the resource identified in the 3071 Request-URI be locked with the specified lock token and in the state 3072 identified by the "I am an ETag" ETag or in the state identified by 3073 the second ETag "I am another ETag". To put the matter more plainly 3074 one can think of the previous If header as being in the form (or (and 3075 ["I am an ETag"]) 3076 (and ["I am another ETag"])). 3078 9.4.2. Tagged-list Production 3080 The tagged-list production may be used instead of the no-tag-list 3081 production, in order to scope each token to a specific resource. 3082 That is, it specifies that the lists following the resource 3083 specification only apply to the specified resource. The scope of the 3084 resource production begins with the list production immediately 3085 following the resource production and ends with the next resource 3086 production, if any. All clauses must be evaluated. If the state of 3087 the resource named in the tag does not match any of the associated 3088 state lists then the request MUST fail with a 412 (Precondition 3089 Failed). 3091 The same URI MUST NOT appear more than once in a resource production 3092 in an If header. 3094 9.4.3. Example - Tagged List If header in COPY 3096 >>Request 3098 COPY /resource1 HTTP/1.1 3099 Host: www.example.com 3100 Destination: http://www.example.com/resource2 3101 If: 3102 ( 3103 [W/"A weak ETag"]) (["strong ETag"]) 3104 3105 (["another strong ETag"]) 3107 In this example http://www.example.com/resource1 is being copied to 3108 http://www.example.com/resource2. When the method is first applied 3109 to http://www.example.com/resource1, resource1 must be in the state 3110 specified by "( [W/"A 3111 weak ETag"]) (["strong ETag"])", that is, it either must be locked 3112 with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2" 3113 and have a weak entity tag W/"A weak ETag" or it must have a strong 3114 entity tag "strong ETag". 3116 That is the only success condition since the resource 3117 http://www.example.com/random never has the method applied to it (the 3118 only other resource listed in the If header) and 3119 http://www.example.com/resource2 is not listed in the If header. 3121 9.4.4. Not Production 3123 Every state token or ETag is either current, and hence describes the 3124 state of a resource, or is not current, and does not describe the 3125 state of a resource. The boolean operation of matching a state token 3126 or ETag to the current state of a resource thus resolves to a true or 3127 false value. The "Not" production is used to reverse that value. 3128 The scope of the not production is the state-token or entity-tag 3129 immediately following it. 3131 If: (Not 3132 ) 3134 When submitted with a request, this If header requires that all 3135 operand resources must not be locked with 3136 urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked with 3137 urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092. 3139 The Not production is particularly useful with a state token known 3140 not to ever identify a lock, such as the "" state token. 3141 The clause "Not " MUST evaluate to true. Thus, any "OR" 3142 statement containing the clause "Not " MUST also 3143 evaluate to true. 3145 9.4.5. Matching Function 3147 When performing If header processing, the definition of a matching 3148 state token or entity tag is as follows. 3150 Identifying a resource: The resource is identified by the URI along 3151 with the token, in tagged list production, or by the Request-URI in 3152 untagged list production. 3154 Matching entity tag: Where the entity tag matches an entity tag 3155 associated with the identified resource. 3157 Matching state token: Where there is an exact match between the state 3158 token in the If header and any state token on the identified 3159 resource. A lock state token is considered to match if the resource 3160 is anywhere in the scope of the lock. 3162 Example - Matching lock tokens with collection locks 3164 DELETE /specs/rfc2518.txt HTTP/1.1 3165 Host: www.example.com 3166 If: 3167 () 3169 For this example, the lock token must be compared to the identified 3170 resource, which is the 'specs' collection identified by the URL in 3171 the tagged list production. If the 'specs' collection is not locked 3172 or has a lock with a different token, the request MUST fail. If the 3173 'specs' collection is locked (depth infinity) with that lock token, 3174 then this request could succeed, both because the If header evaluates 3175 to true, and because the lock token for the lock affecting the 3176 affected resource has been provided. Alternatively, a request where 3177 the 'rfc2518.txt' URL is associated with the lock token in the If 3178 header could also succeed. 3180 9.4.6. If Header and Non-DAV Aware Proxies 3182 Non-DAV aware proxies will not honor the If header, since they will 3183 not understand the If header, and HTTP requires non-understood 3184 headers to be ignored. When communicating with HTTP/1.1 proxies, the 3185 "Cache-Control: no-cache" request header MUST be used so as to 3186 prevent the proxy from improperly trying to service the request from 3187 its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache" 3188 request header MUST be used for the same reason. 3190 9.5. Lock-Token Header 3192 Lock-Token = "Lock-Token" ":" Coded-URL 3194 The Lock-Token request header is used with the UNLOCK method to 3195 identify the lock to be removed. The lock token in the Lock-Token 3196 request header MUST identify a lock that contains the resource 3197 identified by Request-URI as a member. 3199 The Lock-Token response header is used with the LOCK method to 3200 indicate the lock token created as a result of a successful LOCK 3201 request to create a new lock. 3203 9.6. Overwrite Header 3205 Overwrite = "Overwrite" ":" ("T" | "F") 3207 The Overwrite request header specifies whether the server should 3208 overwrite a resource mapped to the destination URL during a COPY or 3209 MOVE. A value of "F" states that the server must not perform the 3210 COPY or MOVE operation if the state of the destination URL does map 3211 to a resource. If the overwrite header is not included in a COPY or 3212 MOVE request then the resource MUST treat the request as if it has an 3213 overwrite header of value "T". While the Overwrite header appears to 3214 duplicate the functionality of the If-Match: * header of HTTP/1.1, 3215 If-Match applies only to the Request-URI, and not to the Destination 3216 of a COPY or MOVE. 3218 If a COPY or MOVE is not performed due to the value of the Overwrite 3219 header, the method MUST fail with a 412 (Precondition Failed) status 3220 code. The server MUST do authorization checks before checking this 3221 or any conditional header. 3223 All DAV compliant resources MUST support the Overwrite header. 3225 9.7. Timeout Request Header 3227 TimeOut = "Timeout" ":" 1#TimeType 3228 TimeType = ("Second-" DAVTimeOutVal | "Infinite") 3229 ; No LWS allowed within TimeType 3230 DAVTimeOutVal = 1*DIGIT 3232 Clients may include Timeout request headers in their LOCK requests. 3233 However, the server is not required to honor or even consider these 3234 requests. Clients MUST NOT submit a Timeout request header with any 3235 method other than a LOCK method. 3237 Timeout response values MUST use a Second value or Infinite. 3239 The "Second" TimeType specifies the number of seconds that will 3240 elapse between granting of the lock at the server, and the automatic 3241 removal of the lock. The timeout value for TimeType "Second" MUST 3242 NOT be greater than 2^32-1. 3244 The timeout counter MUST be restarted if a refresh LOCK request is 3245 successful. The timeout counter SHOULD NOT be restarted at any other 3246 time. 3248 If the timeout expires then the lock may be lost. Specifically, if 3249 the server wishes to harvest the lock upon time-out, the server 3250 SHOULD act as if an UNLOCK method was executed by the server on the 3251 resource using the lock token of the timed-out lock, performed with 3252 its override authority. Thus logs should be updated with the 3253 disposition of the lock, notifications should be sent, etc., just as 3254 they would be for an UNLOCK request. 3256 Servers are advised to pay close attention to the values submitted by 3257 clients, as they will be indicative of the type of activity the 3258 client intends to perform. For example, an applet running in a 3259 browser may need to lock a resource, but because of the instability 3260 of the environment within which the applet is running, the applet may 3261 be turned off without warning. As a result, the applet is likely to 3262 ask for a relatively small timeout value so that if the applet dies, 3263 the lock can be quickly harvested. However, a document management 3264 system is likely to ask for an extremely long timeout because its 3265 user may be planning on going off-line. 3267 A client MUST NOT assume that just because the time-out has expired 3268 the lock has been lost. Likewise, a client MUST NOT assume that just 3269 because the time-out has not expired, the lock still exists (and for 3270 this reason, clients are strongly advised to use ETags as well). 3272 10. Status Code Extensions to HTTP/1.1 3274 The following status codes are added to those defined in HTTP/1.1 3275 [RFC2616]. 3277 10.1. 207 Multi-Status 3279 The 207 (Multi-Status) status code provides status for multiple 3280 independent operations (see Section 12 for more information). 3282 10.2. 422 Unprocessable Entity 3284 The 422 (Unprocessable Entity) status code means the server 3285 understands the content type of the request entity (hence a 3286 415(Unsupported Media Type) status code is inappropriate), and the 3287 syntax of the request entity is correct (thus a 400 (Bad Request) 3288 status code is inappropriate) but was unable to process the contained 3289 instructions. For example, this error condition may occur if an XML 3290 request body contains well-formed (i.e., syntactically correct), but 3291 semantically erroneous XML instructions. 3293 10.3. 423 Locked 3295 The 423 (Locked) status code means the source or destination resource 3296 of a method is locked. This response SHOULD contain the 'lock-token- 3297 present' precondition element and corresponding 'href' in the error 3298 body. 3300 10.4. 424 Failed Dependency 3302 The 424 (Failed Dependency) status code means that the method could 3303 not be performed on the resource because the requested action 3304 depended on another action and that action failed. For example, if a 3305 command in a PROPPATCH method fails then, at minimum, the rest of the 3306 commands will also fail with 424 (Failed Dependency). 3308 10.5. 507 Insufficient Storage 3310 The 507 (Insufficient Storage) status code means the method could not 3311 be performed on the resource because the server is unable to store 3312 the representation needed to successfully complete the request. This 3313 condition is considered to be temporary. If the request which 3314 received this status code was the result of a user action, the 3315 request MUST NOT be repeated until it is requested by a separate user 3316 action. 3318 11. Use of HTTP Status Codes 3320 These HTTP codes are not redefined, but their use is somewhat 3321 extended by WebDAV methods and requirements. In general, many HTTP 3322 status codes can be used in response to any request, not just in 3323 cases described in this document. Note also that WebDAV servers are 3324 known to use 300-level redirect responses (and early interoperability 3325 tests found clients unprepared to see those responses). A 300-level 3326 request MUST NOT be used when the server has created a new resource 3327 in response to the request. 3329 11.1. 412 Precondition Failed 3331 Any request can contain a conditional header defined in HTTP (If- 3332 Match, If-Modified-Since, etc.) or the "If" or "Overwrite" 3333 conditional headers defined in this specification. If the request 3334 contains a conditional header, and if that condition fails to hold, 3335 then this error code MUST be returned unless some other error is 3336 returned. On the other hand, if the client did not include a 3337 conditional header in the request, then the server MUST NOT use this 3338 error. 3340 11.2. 414 Request-URI Too Long 3342 This status code is used in HTTP 1.1 only for Request-URIs, because 3343 full URIs aren't used in other headers. WebDAV specifies full URLs 3344 in other headers, therefore this error MAY be used if the URI is too 3345 long in other locations as well. 3347 12. Multi-Status Response 3349 A Multi-Status response contains one 'response' element for each 3350 resource in the scope of the request (in no required order) or may be 3351 empty if no resources match the request. The default 207 (Multi- 3352 Status) response body is a text/xml or application/xml HTTP entity 3353 that contains a single XML element called 'multistatus', which 3354 contains a set of XML elements called response which contain 200, 3355 300, 400, and 500 series status codes generated during the method 3356 invocation. 100 series status codes SHOULD NOT be recorded in a 3357 'response' XML element. The 207 status code itself MUST NOT be 3358 considered a success response, it is only completely successful if 3359 all 'response' elements inside contain success status codes. 3361 The body of a 207 Multi-Status response MUST contain a URL associated 3362 with each specific status code, so that the client can tell whether 3363 the error occurred with the source resource, destination resource or 3364 some other resource in the scope of the request. 3366 12.1. Response headers 3368 HTTP defines the Location header to indicate a preferred URL for the 3369 resource that was addressed in the Request-URI (e.g. in response to 3370 successful PUT requests or in redirect responses). However, use of 3371 this header creates ambiguity when there are URLs in the body of the 3372 response, as with Multi-Status. Thus, use of the Location header 3373 with the Multi-Status response is intentionally undefined. 3375 12.2. URL Handling 3377 A Multi-Status body contains one or more 'response' elements. Each 3378 response element describes a resource, and has an 'href' element 3379 identifying the resource. The 'href' element MUST contain an 3380 absolute URI or relative reference. It MUST NOT include "." or ".." 3381 as path elements. 3383 If a 'href' element contains a relative reference, it MUST be 3384 resolved against the Request-URI. A relative reference MUST be an 3385 absolute path (note that clients are not known to support relative 3386 paths). 3388 Identifiers for collections appearing in the results SHOULD end in a 3389 '/' character. 3391 If a server allows resource names to include characters that aren't 3392 legal in HTTP URL paths, these characters must be percent-encoded on 3393 the wire (see [RFC3986], section 2.1). For example, it is illegal to 3394 use a space character or double-quote in a URI. URIs appearing in 3395 PROPFIND or PROPPATCH XML bodies (or other XML marshalling defined in 3396 this specification) are still subject to all URI rules, including 3397 forbidden characters. 3399 12.3. Handling redirected child resources 3401 Redirect responses (300-303, 305 and 307) defined in HTTP 1.1 3402 normally take a Location header to indicate the new URI for the 3403 single resource redirected from the Request-URI. Multi-Status 3404 responses contain many resource addresses, but the original 3405 definition in RFC2518 did not have any place for the server to 3406 provide the new URI for redirected resources. This specification 3407 does define a 'location' element for this information (see 3408 Section 13.9). Servers MUST use this new element with redirect 3409 responses in Multi-Status. 3411 Clients encountering redirected resources in Multi-Status MUST NOT 3412 rely on the 'location' element being present with a new URI. If the 3413 element is not present, the client MAY reissue the request to the 3414 individual redirected resource, because the response to that request 3415 can be redirected with a Location header containing the new URI. 3417 12.4. Internal Status Codes 3419 Section 8.3.1, Section 8.2.2, Section 8.7.1, Section 8.9.3 and 3420 Section 8.10.2 define various status codes used in Multi-Status 3421 responses. This specification does not define the meaning of other 3422 status codes that could appear in these responses. 3424 13. XML Element Definitions 3426 In this section, the final line of each section gives the element 3427 type declaration using the format defined in [XML]. The "Value" 3428 field, where present, specifies further restrictions on the allowable 3429 contents of the XML element using BNF (i.e., to further restrict the 3430 values of a PCDATA element). The "Extensibility" field discusses how 3431 the element may be extended in the future (or in existing extensions 3432 to WebDAV. 3434 All of the elements defined here may be extended by the addition of 3435 attributes and child elements not defined in this specification. All 3436 elements defined here are in the "DAV:" namespace. 3438 13.1. activelock XML Element 3440 Name: activelock 3442 Purpose: Describes a lock on a resource. 3444 Extensibility: MAY be extended with additional child elements or 3445 attributes which SHOULD be ignored if not recognized. 3447 3450 13.2. allprop XML Element 3452 Name: allprop 3454 Purpose: Specifies that all names and values of dead properties and 3455 the live properties defined by this document existing on the 3456 resource are to be returned. 3458 Extensibility: Normally empty, but MAY be extended with additional 3459 child elements or attributes which SHOULD be ignored if not 3460 recognized. 3462 3464 13.3. collection XML Element 3466 Name: collection 3467 Purpose: Identifies the associated resource as a collection. The 3468 DAV:resourcetype property of a collection resource MUST contain 3469 this element. It is normally empty but extensions may add sub- 3470 elements. 3472 Extensibility: MAY be extended with child elements or attributes 3473 which SHOULD be ignored if not recognized. 3475 3477 13.4. dead-props XML Element 3479 Name: dead-props 3481 Purpose: Specifies that all dead properties, names and values, 3482 should be returned in the response. 3484 Extensibility: Normally empty, but MAY be extended with additional 3485 child elements or attributes which SHOULD be ignored if not 3486 recognized. 3488 3490 13.5. depth XML Element 3492 Name: depth 3494 Purpose: The value of the Depth header. 3496 Value: "0" | "1" | "infinity" 3498 Extensibility: MAY be extended with attributes which SHOULD be 3499 ignored. 3501 3503 13.6. error XML Element 3505 Name: error 3507 Purpose: Error responses, particularly 403 Forbidden and 409 3508 Conflict, sometimes need more information to indicate what went 3509 wrong. When an error response contains a body in WebDAV, the body 3510 is in XML with the root element 'error'. The 'error' element 3511 SHOULD include an XML element with the code of a failed 3512 precondition or postcondition. 3514 Description: Contains any XML element 3516 Extensibility: Fully extensible with additional child elements, 3517 attributes or text (possibly mixed content). Unrecognized 3518 information items SHOULD be ignored if not recognized. 3520 3522 13.7. exclusive XML Element 3524 Name: exclusive 3526 Purpose: Specifies an exclusive lock 3528 Extensibility: Normally empty, but MAY be extended with additional 3529 child elements or attributes which SHOULD be ignored if not 3530 recognized. 3532 3534 13.8. href XML Element 3536 Name: href 3538 Purpose: Identifies the content of the element as a URI or a 3539 relative reference. There may be limits on the value of 'href' 3540 depending on the context of its use. Refer to the specification 3541 text where 'href' is used to see what limitations apply in each 3542 case. 3544 Value: URI-reference (See section 4.1 of [RFC3986]) 3546 Extensibility: MAY be extended with attributes which SHOULD be 3547 ignored if not recognized. 3549 3551 13.9. location XML Element 3553 Name: location 3555 Purpose: HTTP defines the "Location" header (see [RFC2616], section 3556 14.30) for use with some status codes (such as 201 and the 300 3557 series codes). When these codes are used inside a Multi-Status 3558 response, the 'location' element can be used to provide the 3559 accompanying 'Location' header. 3561 Description: Contains a single href element with the same value that 3562 would be used in a Location header. 3564 Extensibility: MAY be extended with additional child elements or 3565 attributes which SHOULD be ignored if not recognized. 3567 3569 13.10. lockentry XML Element 3571 Name: lockentry 3573 Purpose: Defines the types of locks that can be used with the 3574 resource. 3576 Extensibility: MAY be extended with additional child elements or 3577 attributes which SHOULD be ignored if not recognized. 3579 3581 13.11. lockinfo XML Element 3583 Name: lockinfo 3585 Purpose: The 'lockinfo' XML element is used with a LOCK method to 3586 specify the type of lock the client wishes to have created. 3588 Extensibility: MAY be extended with additional child elements or 3589 attributes which SHOULD be ignored if not recognized. 3591 3593 13.12. lockroot XML Element 3595 Name: lockroot 3597 Purpose: Contains the root URL of the lock, which is the URL through 3598 which the resource was addressed in the LOCK request. 3600 Description: The href contains a HTTP URL with the address of the 3601 root of the lock. The server SHOULD include this in all DAV: 3602 lockdiscovery property values and the response to LOCK requests. 3604 Extensibility: MAY be extended with additional child elements or 3605 attributes which SHOULD be ignored if not recognized. 3607 3609 13.13. lockscope XML Element 3611 Name: lockscope 3613 Purpose: Specifies whether a lock is an exclusive lock, or a shared 3614 lock. 3616 Extensibility: SHOULD NOT be extended with child elements. MAY be 3617 extended with attributes which SHOULD be ignored. 3619 3621 13.14. locktoken XML Element 3623 Name: locktoken 3625 Purpose: The lock token associated with a lock. 3627 Description: The href contains a single lock token URI which refers 3628 to the lock. 3630 Extensibility: MAY be extended with additional child elements or 3631 attributes which SHOULD be ignored if not recognized. 3633 3635 13.15. locktype XML Element 3637 Name: locktype 3639 Purpose: Specifies the access type of a lock. At present, this 3640 specification only defines one lock type, the write lock. 3642 Extensibility: MAY be extended with additional child elements or 3643 attributes which SHOULD be ignored if not recognized. 3645 3647 13.16. multistatus XML Element 3649 Name: multistatus 3651 Purpose: Contains multiple response messages. 3653 Description The 'responsedescription' element at the top level is 3654 used to provide a general message describing the overarching 3655 nature of the response. If this value is available an application 3656 may use it instead of presenting the individual response 3657 descriptions contained within the responses. 3659 Extensibility: MAY be extended with additional child elements or 3660 attributes which SHOULD be ignored if not recognized. 3662 3664 13.17. owner XML Element 3666 Name: owner 3668 Purpose: Provides information about the principal taking out a lock. 3670 Description Provides information sufficient for either directly 3671 contacting a principal (such as a telephone number or Email URI), 3672 or for discovering the principal (such as the URL of a homepage) 3673 who owns a lock. This information is provided by the client, and 3674 may only be altered by the server if the owner value provided by 3675 the client is empty. 3677 Extensibility MAY be extended with child elements, mixed content, 3678 text content or attributes. Structured content, for example one 3679 or more 'href' child elements containing URIs of any kind, is 3680 RECOMMENDED. 3682 3684 13.18. prop XML element 3686 Name: prop 3688 Purpose: Contains properties related to a resource. 3690 Description A generic container for properties defined on resources. 3691 All elements inside a 'prop' XML element MUST define properties 3692 related to the resource. No other elements may be used inside of 3693 a 'prop' element. 3695 Extensibility MAY be extended with attributes which SHOULD be ignored 3696 if not recognized. Any child element of this element must be 3697 considered to be a property name, however these are not restricted 3698 to the property names defined in this document or other standards. 3700 3702 13.19. propertyupdate XML element 3704 Name: propertyupdate 3706 Purpose: Contains a request to alter the properties on a resource. 3708 Description: This XML element is a container for the information 3709 required to modify the properties on the resource. This XML 3710 element is multi-valued. 3712 Extensibility: MAY be extended with additional child elements or 3713 attributes which SHOULD be ignored if not recognized. 3715 3717 13.20. propfind XML Element 3719 Name: propfind 3721 Purpose: Specifies the properties to be returned from a PROPFIND 3722 method. Four special elements are specified for use with 3723 'propfind': 'prop', 'dead-props', 'allprop' and 'propname'. If 3724 'prop' is used inside 'propfind' it MUST NOT contain property 3725 values. 3727 Extensibility: MAY be extended with additional child elements or 3728 attributes which SHOULD be ignored if not recognized, as long as 3729 it still contains one of the required elements. 3731 3733 13.21. propname XML Element 3734 Name: propname 3736 Purpose: Specifies that only a list of property names on the 3737 resource is to be returned. 3739 Extensibility: Normally empty, but MAY be extended with additional 3740 child elements or attributes which SHOULD be ignored if not 3741 recognized. 3743 3745 13.22. propstat XML Element 3747 Name: propstat 3749 Purpose: Groups together a prop and status element that is 3750 associated with a particular 'href' element. 3752 Description: The propstat XML element MUST contain one prop XML 3753 element and one status XML element. The contents of the prop XML 3754 element MUST only list the names of properties to which the result 3755 in the status element applies. 3757 Extensibility: MAY be extended with additional child elements or 3758 attributes which SHOULD be ignored if not recognized. 3760 3762 13.23. remove XML element 3764 Name: remove 3766 Purpose: Lists the DAV properties to be removed from a resource. 3768 Description: Remove instructs that the properties specified in prop 3769 should be removed. Specifying the removal of a property that does 3770 not exist is not an error. All the XML elements in a 'prop' XML 3771 element inside of a 'remove' XML element MUST be empty, as only 3772 the names of properties to be removed are required. 3774 Extensibility: MAY be extended with additional child elements or 3775 attributes which SHOULD be ignored if not recognized. 3777 3779 13.24. response XML Element 3780 Name: response 3782 Purpose: Holds a single response describing the effect of a method 3783 on resource and/or its properties. 3785 Description: The 'href' element contains a HTTP URL pointing to a 3786 WebDAV resource when used in the 'response' container. A 3787 particular 'href' value MUST NOT appear more than once as the 3788 child of a 'response' XML element under a 'multistatus' XML 3789 element. This requirement is necessary in order to keep 3790 processing costs for a response to linear time. Essentially, this 3791 prevents having to search in order to group together all the 3792 responses by 'href'. There are, however, no requirements 3793 regarding ordering based on 'href' values. 3795 Extensibility: MAY be extended with additional child elements or 3796 attributes which SHOULD be ignored if not recognized. 3798 3801 13.25. responsedescription XML Element 3803 Name: responsedescription 3805 Purpose: Contains information about a status response within a 3806 Multi-Status. 3808 Description: This XML element provides either information suitable 3809 to be presented to a user (PCDATA) or a machine readable error 3810 code. 3812 Extensibility: MAY be extended with additional attributes which 3813 SHOULD be ignored if not recognized. 3815 3817 13.26. set XML element 3819 Name: set 3821 Purpose: Lists the DAV property values to be set for a resource. 3823 Description: The 'set' XML element MUST contain only a prop XML 3824 element. The elements contained by the prop XML element inside 3825 the 'set' XML element MUST specify the name and value of 3826 properties that are set on the resource identified by Request-URI. 3828 If a property already exists then its value is replaced. Language 3829 tagging information appearing in the scope of the 'prop' element 3830 (in the "xml:lang" attribute, if present) MUST be persistently 3831 stored along with the property, and MUST be subsequently 3832 retrievable using PROPFIND. 3834 Extensibility: MAY be extended with additional child elements or 3835 attributes which SHOULD be ignored if not recognized. 3837 3839 13.27. shared XML Element 3841 Name: shared 3843 Purpose: Specifies a shared lock 3845 Extensibility: Normally empty, but MAY be extended with additional 3846 child elements or attributes which SHOULD be ignored if not 3847 recognized. 3849 3851 13.28. status XML Element 3853 Name: status 3855 Purpose: Holds a single HTTP status-line 3857 Value: status-line (status-line defined in Section 6.1 of [RFC2616]) 3859 Extensibility: MAY be extended with attributes which SHOULD be 3860 ignored. 3862 3864 13.29. timeout XML Element 3866 Name: timeout 3868 Purpose: The number of seconds remaining before a lock expires. 3870 Value: TimeType (defined in Section 9.7). 3872 Extensibility: MAY be extended with attributes which SHOULD be 3873 ignored. 3875 3877 13.30. write XML Element 3879 Name: write 3881 Purpose: Specifies a write lock. 3883 Extensibility: Normally empty, but MAY be extended with additional 3884 child elements or attributes which SHOULD be ignored if not 3885 recognized. 3887 3889 14. DAV Properties 3891 For DAV properties, the name of the property is also the same as the 3892 name of the XML element that contains its value. In the section 3893 below, the final line of each section gives the element type 3894 declaration using the format defined in [XML]. The "Value" field, 3895 where present, specifies further restrictions on the allowable 3896 contents of the XML element using BNF (i.e., to further restrict the 3897 values of a PCDATA element). Note that a resource may have only one 3898 value for a property of a given name, so the property may only show 3899 up once in PROPFIND responses or PROPPATCH requests. 3901 A protected property is one which cannot be changed with a PROPPATCH 3902 request. There may be other requests which would result in a change 3903 to a protected property (as when a PUT request to an existing 3904 resource causes DAV:contentlength to change to a new value). Note 3905 that a given property could be protected on one type of resource, but 3906 not protected on another type of resource. 3908 A computed property is one with a value defined in terms of a 3909 computation (based on the content and other properties of that 3910 resource, or even of some other resource). A computed property is 3911 always a protected property. 3913 COPY and MOVE behavior refers to local COPY and MOVE operations. 3915 For properties defined based on HTTP GET response headers (DAV:get*), 3916 the value could include LWS as defined in [RFC2616], section 4.2. 3917 Server implementors SHOULD NOT include extra LWS in these values, 3918 however client implementors MUST be prepared to handle extra LWS. 3920 14.1. creationdate Property 3922 Name: creationdate 3924 Purpose: Records the time and date the resource was created. 3926 Value: date-time (defined in [RFC3339], see the ABNF in section 3927 5.6.) 3929 Protected: MAY be protected. Some servers allow DAV:creationdate to 3930 be changed to reflect the time the document was created if that is 3931 more meaningful to the user (rather than the time it was 3932 uploaded). Thus, clients SHOULD NOT use this property in 3933 synchronization logic (use DAV:getetag instead). 3935 COPY/MOVE behaviour: This property value SHOULD be kept during a 3936 MOVE operation, but is normally re-initialized when a resource is 3937 created with a COPY. It should not be set in a COPY. 3939 Description: The DAV:creationdate property SHOULD be defined on all 3940 DAV compliant resources. If present, it contains a timestamp of 3941 the moment when the resource was created. Servers that are 3942 incapable of persistently recording the creation date SHOULD 3943 instead leave it undefined (i.e. report "Not Found") 3945 Extensibility: MAY contain attributes which SHOULD be ignored if not 3946 recognized. 3948 3950 14.2. displayname Property 3952 Name: displayname 3954 Purpose: Provides a name for the resource that is suitable for 3955 presentation to a user. 3957 Value: Any text 3959 Protected: SHOULD NOT be protected. Note that servers implementing 3960 RFC2518 might have made this a protected property as this is a new 3961 requirement. 3963 COPY/MOVE behaviour: This property value SHOULD be preserved in COPY 3964 and MOVE operations. 3966 Description: The DAV:displayname property should be defined on all 3967 DAV compliant resources. If present, the property contains a 3968 description of the resource that is suitable for presentation to a 3969 user. This property is defined on the resource, and hence SHOULD 3970 have the same value independent of the Request-URI used to 3971 retrieve it (thus computing this property based on the Request-URI 3972 is deprecated). 3974 Extensibility: MAY contain attributes which SHOULD be ignored if not 3975 recognized. 3977 3979 14.3. getcontentlanguage Property 3980 Name: getcontentlanguage 3982 Purpose: Contains the Content-Language header value (from section 3983 14.12 of [RFC2616]) as it would be returned by a GET without 3984 accept headers. 3986 Value: language-tag (language-tag is defined in section 3.10 of 3987 [RFC2616]). 3989 Protected: SHOULD NOT be protected, so that clients can reset the 3990 language. Note that servers implementing RFC2518 might have made 3991 this a protected property as this is a new requirement. 3993 COPY/MOVE behaviour: This property value SHOULD be preserved in COPY 3994 and MOVE operations. 3996 Description: The DAV:getcontentlanguage property MUST be defined on 3997 any DAV compliant resource that returns the Content-Language 3998 header on a GET. 4000 Extensibility: MAY contain attributes which SHOULD be ignored if not 4001 recognized. 4003 4005 14.4. getcontentlength Property 4007 Name: getcontentlength 4009 Purpose: Contains the Content-Length header returned by a GET 4010 without accept headers. 4012 Value: See section 14.13 of [RFC2616]. 4014 Protected: This property is computed, therefore protected. 4016 Description: The DAV:getcontentlength property MUST be defined on 4017 any DAV compliant resource that returns the Content-Length header 4018 in response to a GET. 4020 COPY/MOVE behaviour: This property value is dependent on the size of 4021 the destination resource, not the value of the property on the 4022 source resource. 4024 Extensibility: MAY contain attributes which SHOULD be ignored if not 4025 recognized. 4027 4029 14.5. getcontenttype Property 4031 Name: getcontenttype 4033 Purpose: Contains the Content-Type header value (from section 14.17 4034 of [RFC2616]) as it would be returned by a GET without accept 4035 headers. 4037 Value: media-type (defined in section 3.7 of [RFC2616]) 4039 Protected: SHOULD NOT be protected, so clients may fix this value. 4040 Note that servers implementing RFC2518 might have made this a 4041 protected property as this is a new requirement. 4043 COPY/MOVE behaviour: This property value SHOULD be preserved in COPY 4044 and MOVE operations. 4046 Description: This property MUST be defined on any DAV compliant 4047 resource that returns the Content-Type header in response to a 4048 GET. 4050 Extensibility: MAY contain attributes which SHOULD be ignored if not 4051 recognized. 4053 4055 14.6. getetag Property 4057 Name: getetag 4059 Purpose: Contains the ETag header value (from section 14.19 of 4060 [RFC2616]) as it would be returned by a GET without accept 4061 headers. 4063 Value: entity-tag (defined in section 3.11 of [RFC2616]) 4065 Protected: MUST be protected because this value is created and 4066 controlled by the server. 4068 COPY/MOVE behaviour: This property value is dependent on the final 4069 state of the destination resource, not the value of the property 4070 on the source resource. 4072 Description: The getetag property MUST be defined on any DAV 4073 compliant resource that returns the Etag header. Refer to RFC2616 4074 for a complete definition of the semantics of an ETag. Note that 4075 changes in properties or lock state MUST not cause a resource's 4076 ETag to change. 4078 Extensibility: MAY contain attributes which SHOULD be ignored if not 4079 recognized. 4081 4083 14.7. getlastmodified Property 4085 Name: getlastmodified 4087 Purpose: Contains the Last-Modified header value (from section 14.29 4088 of [RFC2616]) as it would be returned by a GET method without 4089 accept headers. 4091 Value: rfc1123-date (defined in section 3.3.1 of [RFC2616]) 4093 Protected: SHOULD be protected because some clients may rely on the 4094 value for appropriate caching behavior, or on the value of the 4095 Last-Modified header to which this property is linked. 4097 COPY/MOVE behaviour: This property value is dependent on the last 4098 modified date of the destination resource, not the value of the 4099 property on the source resource. Note that some server 4100 implementations use the file system date modified value for the 4101 DAV:getlastmodified value, and this is preserved in a MOVE even 4102 when the HTTP Last-Modified value SHOULD change. Thus, clients 4103 cannot rely on this value for caching and SHOULD use ETags. 4105 Description: Note that the last-modified date on a resource SHOULD 4106 only reflect changes in the body (the GET responses) of the 4107 resource. A change in a property only SHOULD NOT cause the last- 4108 modified date to change, because clients MAY rely on the last- 4109 modified date to know when to overwrite the existing body. The 4110 DAV:getlastmodified property MUST be defined on any DAV compliant 4111 resource that returns the Last-Modified header in response to a 4112 GET. 4114 Extensibility: MAY contain attributes which SHOULD be ignored if not 4115 recognized. 4117 4119 14.8. lockdiscovery Property 4121 Name: lockdiscovery 4122 Purpose: Describes the active locks on a resource 4124 Protected: MUST be protected. Clients change the list of locks 4125 through LOCK and UNLOCK, not through PROPPATCH. 4127 COPY/MOVE behaviour: The value of this property depends on the lock 4128 state of the destination, not on the locks of the source resource. 4129 Recall that locks are not moved in a MOVE operation. 4131 Description: Returns a listing of who has a lock, what type of lock 4132 he has, the timeout type and the time remaining on the timeout, 4133 and the associated lock token. If there are no locks, but the 4134 server supports locks, the property will be present but contain 4135 zero 'activelock' elements. If there is one or more lock, an 4136 'activelock' element appears for each lock on the resource. 4138 Extensibility: MAY be extended with additional child elements or 4139 attributes which SHOULD be ignored if not recognized. 4141 4143 14.8.1. Example - Retrieving the lockdiscovery Property 4145 >>Request 4147 PROPFIND /container/ HTTP/1.1 4148 Host: www.example.com 4149 Content-Length: xxxx 4150 Content-Type: application/xml; charset="utf-8" 4152 4153 4154 4155 4157 >>Response 4159 HTTP/1.1 207 Multi-Status 4160 Content-Type: application/xml; charset="utf-8" 4161 Content-Length: xxxx 4163 4164 4165 4166 http://www.example.com/container/ 4167 4168 4169 4170 4171 4172 4173 0 4174 Jane Smith 4175 Infinite 4176 4177 urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76 4179 4180 4181 http://www.example.com/container/ 4182 4183 4184 4185 4186 HTTP/1.1 200 OK 4187 4188 4189 4191 This resource has a single exclusive write lock on it, with an 4192 infinite timeout. 4194 14.9. resourcetype Property 4196 Name: resourcetype 4198 Purpose: Specifies the nature of the resource. 4200 Protected: SHOULD be protected. Resource type is generally decided 4201 through the operation creating the resource (MKCOL vs PUT), not by 4202 PROPPATCH. 4204 COPY/MOVE behaviour: Generally a COPY/MOVE of a resource results in 4205 the same type of resource at the destination. 4207 Description: MUST be defined on all DAV compliant resources. Each 4208 child element identifies a specific type the resource belongs to, 4209 such as 'collection', which is the only resource type defined by 4210 this specification (see Section 13.3). If the element contains 4211 the 'collection' child element plus additional unrecognized 4212 elements, it should generally be treated as a collection. If the 4213 element contains no recognized child elements, it should be 4214 treated as a non-collection resource. The default value is empty. 4216 Extensibility: MAY be extended with any child elements or attributes 4217 which SHOULD be ignored if not recognized. 4219 Example: (fictional example to show extensibility) 4221 4222 4223 4224 4226 14.10. supportedlock Property 4228 Name: supportedlock 4230 Purpose: To provide a listing of the lock capabilities supported by 4231 the resource. 4233 Protected: MUST be protected. Servers determine what lock 4234 mechanisms are supported, not clients. 4236 COPY/MOVE behaviour: This property value is dependent on the kind of 4237 locks supported at the destination, not on the value of the 4238 property at the source resource. Servers attempting to COPY to a 4239 destination should not attempt to set this property at the 4240 destination. 4242 Description: Returns a listing of the combinations of scope and 4243 access types which may be specified in a lock request on the 4244 resource. Note that the actual contents are themselves controlled 4245 by access controls so a server is not required to provide 4246 information the client is not authorized to see. 4248 Extensibility: MAY be extended with any child elements or attributes 4249 which SHOULD be ignored if not recognized. 4251 4253 14.10.1. Example - Retrieving the DAV:supportedlock Property 4255 >>Request 4257 PROPFIND /container/ HTTP/1.1 4258 Host: www.example.com 4259 Content-Length: xxxx 4260 Content-Type: application/xml; charset="utf-8" 4262 4263 4264 4265 4267 >>Response 4269 HTTP/1.1 207 Multi-Status 4270 Content-Type: application/xml; charset="utf-8" 4271 Content-Length: xxxx 4273 4274 4275 4276 http://www.example.com/container/ 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 HTTP/1.1 200 OK 4291 4292 4293 4295 15. Precondition/postcondition XML elements 4297 As introduced in section Section 8.1.5, extra information on error 4298 conditions can be included in the body of many status responses. 4299 This section makes requirements on the use of the error body 4300 mechanism and introduces a number of precondition and postcondition 4301 codes. 4303 A "precondition" of a method describes the state of the server that 4304 must be true for that method to be performed. A "postcondition" of a 4305 method describes the state of the server that must be true after that 4306 method has been completed. 4308 Each precondition and postcondition has a unique XML element 4309 associated with it. In a 207 Multi-Status response, the XML element 4310 MUST appear inside a DAV:error element in the appropriate DAV: 4311 responsedescription element. In all other error responses, the XML 4312 element MUST be returned as the child of a top-level DAV:error 4313 element in the response body, unless otherwise negotiated by the 4314 request, along with an appropriate response status. The most common 4315 response status codes are 403 (Forbidden) if the request should not 4316 be repeated because it will always fail, and 409 (Conflict) if it is 4317 expected that the user might be able to resolve the conflict and 4318 resubmit the request. The DAV:error element MAY contain child 4319 elements with specific error information and MAY be extended with 4320 custom child elements and text (mixed content). 4322 This mechanism does not take the place of using a correct numeric 4323 error code as defined here or in HTTP, because the client MUST always 4324 be able to take a reasonable course of action based only on the 4325 numeric error. However, it does remove the need to define new 4326 numeric error codes. The machine-readable codes used for this 4327 purpose are XML elements classified as preconditions and 4328 postconditions, so naturally any group defining a new error code can 4329 use their own namespace. As always, the "DAV:" namespace is reserved 4330 for use by IETF-chartered WebDAV working groups. 4332 A server supporting "bis" SHOULD use the XML error whenever a 4333 precondition or postcondition defined in this document is violated. 4334 For error conditions not specified in this document, the server MAY 4335 simply choose an appropriate numeric status and leave the response 4336 body blank. However, a server MAY instead use a custom error code 4337 and other supporting text, because even when clients do not 4338 automatically recognize error codes they can be quite useful in 4339 interoperability testing and debugging. 4341 15.1. Example - Response with precondition code 4343 >>Response 4345 HTTP/1.1 423 Locked 4346 Content-Type: application/xml; charset="utf-8" 4347 Content-Length: xxxx 4349 4350 4351 4352 /workspace/webdav/ 4353 4354 4356 In this example, a client unaware of a "Depth: infinity" lock on the 4357 parent collection "/workspace/webdav/" attempted to modify the 4358 collection member "/workspace/webdav/proposal.doc". 4360 Some other useful preconditions and postconditions have been defined 4361 in other specifications extending WebDAV, such as [RFC3744] (see 4362 particularly section 7.1.1), [RFC3253], and [RFC3648]. 4364 All these elements are in the "DAV:" namespace. 4366 Name: no-external-entities 4368 Use with: 403 Forbidden 4370 Purpose: (precondition) -- If the server rejects a client request 4371 because the request body contains an external entity, the server 4372 SHOULD use this error. 4374 4376 Name: lock-token-matches-request-uri 4378 Use with: 400 Bad Request 4380 Purpose: (precondition) -- A request may include a Lock-Token header 4381 to identify a lock for the purposes of an operation such as 4382 refresh LOCK or UNLOCK. However, if the Request-URI doe not fall 4383 within the scope of the lock identified by the token, the server 4384 SHOULD use this error. The lock may have a scope that does not 4385 include the Request-URI, or the lock could have disappeared, or 4386 the token may be invalid. 4388 4389 Name: preserved-live-properties 4391 Use with: 409 Conflict 4393 Purpose: (postcondition) -- The server received an otherwise-valid 4394 MOVE or COPY request, but cannot maintain the live properties with 4395 the same behavior at the destination. It may be that the server 4396 only supports some live properties in some parts of the 4397 repository, or simply has an internal error. 4399 4401 Name: writable-property 4403 Use with: 403 Forbidden 4405 Purpose: (precondition) -- The client attempted to set a read-only 4406 property in a PROPPATCH (such as DAV:getetag). 4408 4410 Name: propfind-finite-depth 4412 Use with: 403 Forbidden 4414 Purpose: (precondition) -- This server does not allow infinite-depth 4415 PROPFIND requests on collections. 4417 4419 Name: lock-token-present 4421 Use with: 4xx responses, e.g. 400 Bad Request or 423 Locked 4423 Purpose: (precondition) -- The request could not succeed because a 4424 lock token should have been provided. This element, if present, 4425 MUST contain at least one URL of a locked resource that prevented 4426 the request. In cases of MOVE, COPY and DELETE where collection 4427 locks are involved, it can be difficult for the client to find out 4428 which locked resource made the request fail -- but the server is 4429 only resonsible for returning one such locked resource. The 4430 server MAY return every locked resource that prevented the request 4431 from succeeding if it knows them all. 4433 4435 16. Instructions for Processing XML in DAV 4437 All DAV compliant resources MUST ignore any unknown XML element and 4438 all its children encountered while processing a DAV method that uses 4439 XML as its command language. 4441 This restriction also applies to the processing, by clients, of DAV 4442 property values where unknown XML elements SHOULD be ignored unless 4443 the property's schema declares otherwise. 4445 This restriction does not apply to setting dead DAV properties on the 4446 server where the server MUST record unknown XML elements. 4448 Additionally, this restriction does not apply to the use of XML where 4449 XML happens to be the content type of the entity body, for example, 4450 when used as the body of a PUT. 4452 Since XML can be transported as text/xml or application/xml, a DAV 4453 server MUST accept DAV method requests with XML parameters 4454 transported as either text/xml or application/xml, and a DAV client 4455 MUST accept XML responses using either text/xml or application/xml. 4457 XML DTD fragments are included for all the XML elements defined in 4458 this specification. However, legal XML may not be valid according to 4459 any DTD due to namespace usage and extension rules, so the DTD is 4460 only informational. A recipient of a WebDAV message with an XML body 4461 MUST NOT validate the XML document according to any hard-coded or 4462 dynamically-declared DTD. 4464 17. DAV Compliance Classes 4466 A DAV compliant resource can advertise several classes of compliance. 4467 A client can discover the compliance classes of a resource by 4468 executing OPTIONS on the resource, and examining the "DAV" header 4469 which is returned. Note particularly that resources are spoken of as 4470 being compliant, rather than servers. That is because theoretically 4471 some resources on a server could support different feature sets. 4472 E.g. a server could have a sub-repository where an advanced feature 4473 like server was supported, even if that feature was not supported on 4474 all servers. 4476 Since this document describes extensions to the HTTP/1.1 protocol, 4477 minimally all DAV compliant resources, clients, and proxies MUST be 4478 compliant with [RFC2616]. 4480 A resource that is class 2 compliant must also be class 1 compliant, 4481 and a resource that is compliant with "bis" must also be class 1 4482 compliant. 4484 17.1. Class 1 4486 A class 1 compliant resource MUST meet all "MUST" requirements in all 4487 sections of this document. 4489 Class 1 compliant resources MUST return, at minimum, the value "1" in 4490 the DAV header on all responses to the OPTIONS method. 4492 17.2. Class 2 4494 A class 2 compliant resource MUST meet all class 1 requirements and 4495 support the LOCK method, the DAV:supportedlock property, the DAV: 4496 lockdiscovery property, the Time-Out response header and the Lock- 4497 Token request header. A class "2" compliant resource SHOULD also 4498 support the Time-Out request header and the owner XML element. 4500 Class 2 compliant resources MUST return, at minimum, the values "1" 4501 and "2" in the DAV header on all responses to the OPTIONS method. 4503 17.3. Class 'bis' 4505 A resource can explicitly advertise its support for the revisions to 4506 RFC2518 made in this document. Class 1 must be supported as well. 4507 Class 2 MAY be supported. 4509 Example: 4511 DAV: 1, bis 4513 18. Internationalization Considerations 4515 In the realm of internationalization, this specification complies 4516 with the IETF Character Set Policy [RFC2277]. In this specification, 4517 human-readable fields can be found either in the value of a property, 4518 or in an error message returned in a response entity body. In both 4519 cases, the human-readable content is encoded using XML, which has 4520 explicit provisions for character set tagging and encoding, and 4521 requires that XML processors read XML elements encoded, at minimum, 4522 using the UTF-8 [RFC3629] and UTF-16 encodings of the ISO 10646 4523 multilingual plane. XML examples in this specification demonstrate 4524 use of the charset parameter of the Content-Type header, as defined 4525 in [RFC3023], as well as the XML declarations which provide charset 4526 identification information for MIME and XML processors. 4528 XML also provides a language tagging capability for specifying the 4529 language of the contents of a particular XML element. The "xml:lang" 4530 attribute appears on an XML element to identify the language of its 4531 content and attributes. See [XML] for definitions of values and 4532 scoping. 4534 WebDAV applications MUST support the character set tagging, character 4535 set encoding, and the language tagging functionality of the XML 4536 specification. Implementors of WebDAV applications are strongly 4537 encouraged to read "XML Media Types" [RFC3023] for instruction on 4538 which MIME media type to use for XML transport, and on use of the 4539 charset parameter of the Content-Type header. 4541 Names used within this specification fall into four categories: names 4542 of protocol elements such as methods and headers, names of XML 4543 elements, names of properties, and names of conditions. Naming of 4544 protocol elements follows the precedent of HTTP, using English names 4545 encoded in USASCII for methods and headers. Since these protocol 4546 elements are not visible to users, and are simply long token 4547 identifiers, they do not need to support multiple languages. 4548 Similarly, the names of XML elements used in this specification are 4549 not visible to the user and hence do not need to support multiple 4550 languages. 4552 WebDAV property names are qualified XML names (pairs of XML namespace 4553 name and local name). Although some applications (e.g., a generic 4554 property viewer) will display property names directly to their users, 4555 it is expected that the typical application will use a fixed set of 4556 properties, and will provide a mapping from the property name and 4557 namespace to a human-readable field when displaying the property name 4558 to a user. It is only in the case where the set of properties is not 4559 known ahead of time that an application need display a property name 4560 to a user. We recommend that applications provide human-readable 4561 property names wherever feasible. 4563 For error reporting, we follow the convention of HTTP/1.1 status 4564 codes, including with each status code a short, English description 4565 of the code (e.g., 423 (Locked)). While the possibility exists that 4566 a poorly crafted user agent would display this message to a user, 4567 internationalized applications will ignore this message, and display 4568 an appropriate message in the user's language and character set. 4570 Since interoperation of clients and servers does not require locale 4571 information, this specification does not specify any mechanism for 4572 transmission of this information. 4574 19. Security Considerations 4576 This section is provided to detail issues concerning security 4577 implications of which WebDAV applications need to be aware. 4579 All of the security considerations of HTTP/1.1 (discussed in 4580 [RFC2616]) and XML (discussed in [RFC3023]) also apply to WebDAV. In 4581 addition, the security risks inherent in remote authoring require 4582 stronger authentication technology, introduce several new privacy 4583 concerns, and may increase the hazards from poor server design. 4584 These issues are detailed below. 4586 19.1. Authentication of Clients 4588 Due to their emphasis on authoring, WebDAV servers need to use 4589 authentication technology to protect not just access to a network 4590 resource, but the integrity of the resource as well. Furthermore, 4591 the introduction of locking functionality requires support for 4592 authentication. 4594 A password sent in the clear over an insecure channel is an 4595 inadequate means for protecting the accessibility and integrity of a 4596 resource as the password may be intercepted. Since Basic 4597 authentication for HTTP/1.1 performs essentially clear text 4598 transmission of a password, Basic authentication MUST NOT be used to 4599 authenticate a WebDAV client to a server unless the connection is 4600 secure. Furthermore, a WebDAV server MUST NOT send Basic 4601 authentication credentials in a WWW-Authenticate header unless the 4602 connection is secure. Examples of secure connections include a 4603 Transport Layer Security (TLS) connection employing a strong cipher 4604 suite with mutual authentication of client and server, or a 4605 connection over a network which is physically secure, for example, an 4606 isolated network in a building with restricted access. 4608 WebDAV applications MUST support the Digest authentication scheme 4609 [RFC2617]. Since Digest authentication verifies that both parties to 4610 a communication know a shared secret, a password, without having to 4611 send that secret in the clear, Digest authentication avoids the 4612 security problems inherent in Basic authentication while providing a 4613 level of authentication which is useful in a wide range of scenarios. 4615 19.2. Denial of Service 4617 Denial of service attacks are of special concern to WebDAV servers. 4618 WebDAV plus HTTP enables denial of service attacks on every part of a 4619 system's resources. 4621 o The underlying storage can be attacked by PUTting extremely large 4622 files. 4624 o Asking for recursive operations on large collections can attack 4625 processing time. 4627 o Making multiple pipelined requests on multiple connections can 4628 attack network connections. 4630 WebDAV servers need to be aware of the possibility of a denial of 4631 service attack at all levels. The proper response to such an attack 4632 MAY be to simply drop the connection, or if the server is able to 4633 make a response, the server MAY use a 400-level status request such 4634 as 400 (Bad Request) and indicate why the request was refused (a 500- 4635 level status response would indicate that the problem is with the 4636 server, whereas unintentional DOS attacks are something the client is 4637 capable of remedying). 4639 19.3. Security through Obscurity 4641 WebDAV provides, through the PROPFIND method, a mechanism for listing 4642 the member resources of a collection. This greatly diminishes the 4643 effectiveness of security or privacy techniques that rely only on the 4644 difficulty of discovering the names of network resources. Users of 4645 WebDAV servers are encouraged to use access control techniques to 4646 prevent unwanted access to resources, rather than depending on the 4647 relative obscurity of their resource names. 4649 19.4. Privacy Issues Connected to Locks 4651 When submitting a lock request a user agent may also submit an owner 4652 XML field giving contact information for the person taking out the 4653 lock (for those cases where a person, rather than a robot, is taking 4654 out the lock). This contact information is stored in a DAV: 4655 lockdiscovery property on the resource, and can be used by other 4656 collaborators to begin negotiation over access to the resource. 4657 However, in many cases this contact information can be very private, 4658 and should not be widely disseminated. Servers SHOULD limit read 4659 access to the DAV:lockdiscovery property as appropriate. 4660 Furthermore, user agents SHOULD provide control over whether contact 4661 information is sent at all, and if contact information is sent, 4662 control over exactly what information is sent. 4664 19.5. Privacy Issues Connected to Properties 4666 Since property values are typically used to hold information such as 4667 the author of a document, there is the possibility that privacy 4668 concerns could arise stemming from widespread access to a resource's 4669 property data. To reduce the risk of inadvertent release of private 4670 information via properties, servers are encouraged to develop access 4671 control mechanisms that separate read access to the resource body and 4672 read access to the resource's properties. This allows a user to 4673 control the dissemination of their property data without overly 4674 restricting access to the resource's contents. 4676 19.6. Implications of XML Entities 4678 XML supports a facility known as "external entities", defined in 4679 section 4.2.2 of [XML], which instruct an XML processor to retrieve 4680 and include additional XML. An external XML entity can be used to 4681 append or modify the document type declaration (DTD) associated with 4682 an XML document. An external XML entity can also be used to include 4683 XML within the content of an XML document. For non-validating XML, 4684 such as the XML used in this specification, including an external XML 4685 entity is not required by XML. However, XML does state that an XML 4686 processor may, at its discretion, include the external XML entity. 4688 External XML entities have no inherent trustworthiness and are 4689 subject to all the attacks that are endemic to any HTTP GET request. 4690 Furthermore, it is possible for an external XML entity to modify the 4691 DTD, and hence affect the final form of an XML document, in the worst 4692 case significantly modifying its semantics, or exposing the XML 4693 processor to the security risks discussed in [RFC3023]. Therefore, 4694 implementers must be aware that external XML entities should be 4695 treated as untrustworthy. If a server implementor chooses not to 4696 handle external XML entities, it SHOULD respond to requests 4697 containing external entities with the precondition defined above (no- 4698 external-entities). 4700 There is also the scalability risk that would accompany a widely 4701 deployed application which made use of external XML entities. In 4702 this situation, it is possible that there would be significant 4703 numbers of requests for one external XML entity, potentially 4704 overloading any server which fields requests for the resource 4705 containing the external XML entity. 4707 Furthermore, there's also a risk based on the evaluation of "internal 4708 entities" as defined in section 4.2.2 of [XML]. A small, carefully 4709 crafted request using nested internal entities may require enormous 4710 amounts of memory and/or processing time to process. Server 4711 implementors should be aware of this risk and configure their XML 4712 parsers so that requests like these can be detected and rejected as 4713 early as possible. 4715 19.7. Risks Connected with Lock Tokens 4717 This specification encourages the use of "A Universally Unique 4718 Identifier (UUID) URN Namespace" ([RFC4122]) for lock tokens 4719 Section 6.3, in order to guarantee their uniqueness across space and 4720 time. Variant 1 UUIDs (defined in section 4) MAY contain a "node" 4721 field that "consists of an IEEE 802 MAC address, usually the host 4722 address. For systems with multiple IEEE addresses, any available one 4723 can be used". 4725 There are several risks associated with exposure of IEEE 802 4726 addresses. Using the IEEE 802 address: 4728 o It is possible to track the movement of hardware from subnet to 4729 subnet. 4731 o It may be possible to identify the manufacturer of the hardware 4732 running a WebDAV server. 4734 o It may be possible to determine the number of each type of 4735 computer running WebDAV. 4737 This risk only applies to host address based UUID versions. Section 4738 4 of [RFC4122] describes several other mechanisms for generating 4739 UUIDs that do involve the host address and therefore do not suffer 4740 from this risk. 4742 19.8. Hosting malicious scripts executed on client machines 4744 HTTP has the ability to host scripts which are executed on client 4745 machines. These scripts can be used to read another user's cookies 4746 and therefore may provide an attacker the ability to use another 4747 user's session, assume their identity temporarily and gain access to 4748 their resources. Other attacks are also possible with client- 4749 executed scripts. 4751 WebDAV may worsen this situation only by making it easier for a Web 4752 server to host content provided by many different authors (making it 4753 harder to trust the content providers) and to host content with 4754 restricted access alongside public pages (see particularly RFC3744). 4756 HTTP servers may mitigate some of these threats by filtering content 4757 in areas where many authors contribute pages -- the server could, for 4758 example, remove script from HTML pages. 4760 This vulnerability should provide yet another reason for server 4761 implementors and administrators not to replace authentication 4762 mechanisms with cookie-based session tokens if there's any sensitive 4763 information relying on the authenticated identity. 4765 HTTP and WebDAV client implementors might consider locking down the 4766 use of scripts and cookies based on these considerations. 4768 20. IANA Considerations 4770 This specification defines two URI schemes: 4772 1. the "opaquelocktoken" scheme defined in Appendix C, and 4774 2. the "DAV" URI scheme, which historically was used in RFC2518 to 4775 disambiguate WebDAV property and XML element names and which 4776 continues to be used for that purpose in this specification and 4777 others extending WebDAV. Creation of identifiers in the "DAV:" 4778 namespace is controlled by the IETF. 4780 XML namespaces disambiguate WebDAV property names and XML elements. 4781 Any WebDAV user or application can define a new namespace in order to 4782 create custom properties or extend WebDAV XML syntax. IANA does not 4783 need to manage such namespaces, property names or element names. 4785 21. Acknowledgements 4787 A specification such as this thrives on piercing critical review and 4788 withers from apathetic neglect. The authors gratefully acknowledge 4789 the contributions of the following people, whose insights were so 4790 valuable at every stage of our work. 4792 Contributors to RFC2518 4794 Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan 4795 Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners- 4796 Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith 4797 Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee 4798 Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan 4799 Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis 4800 Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der 4801 Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven 4802 Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten, 4803 Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff, 4804 Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike 4805 Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi, 4806 Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran, 4807 Fabio Vitali, Gregory Woodhouse, and Lauren Wood. 4809 Two from this list deserve special mention. The contributions by 4810 Larry Masinter have been invaluable, both in helping the formation of 4811 the working group and in patiently coaching the authors along the 4812 way. In so many ways he has set high standards we have toiled to 4813 meet. The contributions of Judith Slein in clarifying the 4814 requirements, and in patiently reviewing draft after draft, both 4815 improved this specification and expanded our minds on document 4816 management. 4818 We would also like to thank John Turner for developing the XML DTD. 4820 The authors of RFC2518 were Yaron Goland, Jim Whitehead, A. Faizi, 4821 Steve Carter and D. Jensen. Although their names had to be removed 4822 due to IETF author count restrictions they can take credit for the 4823 majority of the design of WebDAV. 4825 Additional Contributors to This Specification 4827 Valuable contributions to this specification came from some already 4828 named. New and significant contributors to this specification must 4829 also be gratefully acknowledged. Julian Reschke, Geoff Clemm, Joel 4830 Soderberg, and Dan Brotsky hashed out specific text on the list or in 4831 meetings. Joe Hildebrand and Cullen Jennings helped close many 4832 issues. Barry Lind described an additional security consideration. 4834 Jason Crawford tracked issue status for this document for a period of 4835 years, followed by Elias Sinderson. Elias and Jim Whitehead 4836 collaborated on specific document text. 4838 21.1. Previous Authors' Addresses 4840 Y. Y. Goland, Microsoft Corporation, One Microsoft Way, Redmond, WA 4841 98052-6399. Email: yarong@microsoft.com. 4843 E. J. Whitehead, Jr., Dept. Of Information and Computer Science, 4844 University of California, Irvine, Irvine, CA 92697-3425. Email: 4845 ejw@ics.uci.edu. 4847 A. Faizi, Netscape, 685 East Middlefield Road, Mountain View, CA 4848 94043. Email: asad@netscape.com. 4850 S. R. Carter, Novell, 1555 N. Technology Way, M/S ORM F111, Orem, UT 4851 84097-2399. Email: srcarter@novell.com. 4853 D. Jensen, Novell, 1555 N. Technology Way, M/S ORM F111, Orem, UT 4854 84097-2399. Email: dcjensen@novell.com. 4856 22. References 4858 22.1. Normative References 4860 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4861 Requirement Levels", BCP 14, RFC 2119, March 1997. 4863 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 4864 Languages", BCP 18, RFC 2277, January 1998. 4866 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 4867 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 4868 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 4870 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 4871 Leach, P., Luotonen, A., and L. Stewart, "HTTP 4872 Authentication: Basic and Digest Access Authentication", 4873 RFC 2617, June 1999. 4875 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 4876 Timestamps", RFC 3339, July 2002. 4878 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 4879 10646", STD 63, RFC 3629, November 2003. 4881 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4882 Resource Identifier (URI): Generic Syntax", STD 66, 4883 RFC 3986, January 2005. 4885 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 4886 Unique IDentifier (UUID) URN Namespace", RFC 4122, 4887 July 2005. 4889 [W3C.REC-xml-names-19990114] 4890 Hollander, D., Bray, T., and A. Layman, "Namespaces in 4891 XML", W3C REC REC-xml-names-19990114, January 1999. 4893 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 4894 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Third 4895 Edition)", W3C REC-xml-20040204, February 2004, 4896 . 4898 22.2. Informational References 4900 [RFC2291] Slein, J., Vitali, F., Whitehead, E., and D. Durand, 4901 "Requirements for a Distributed Authoring and Versioning 4902 Protocol for the World Wide Web", RFC 2291, February 1998. 4904 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 4905 Jensen, "HTTP Extensions for Distributed Authoring -- 4906 WEBDAV", RFC 2518, February 1999. 4908 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 4909 Types", RFC 3023, January 2001. 4911 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 4912 Whitehead, "Versioning Extensions to WebDAV (Web 4913 Distributed Authoring and Versioning)", RFC 3253, 4914 March 2002. 4916 [RFC3648] Whitehead, J. and J. Reschke, Ed., "Web Distributed 4917 Authoring and Versioning (WebDAV) Ordered Collections 4918 Protocol", RFC 3648, December 2003. 4920 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web 4921 Distributed Authoring and Versioning (WebDAV) Access 4922 Control Protocol", RFC 3744, May 2004. 4924 [W3C.REC-xml-infoset-20040204] 4925 Tobin, R. and J. Cowan, "XML Information Set (Second 4926 Edition)", W3C REC REC-xml-infoset-20040204, 4927 February 2004. 4929 Appendix A. Notes on Processing XML Elements 4931 A.1. Notes on Empty XML Elements 4933 XML supports two mechanisms for indicating that an XML element does 4934 not have any content. The first is to declare an XML element of the 4935 form . The second is to declare an XML element of the form 4936 . The two XML elements are semantically identical. 4938 A.2. Notes on Illegal XML Processing 4940 XML is a flexible data format that makes it easy to submit data that 4941 appears legal but in fact is not. The philosophy of "Be flexible in 4942 what you accept and strict in what you send" still applies, but it 4943 must not be applied inappropriately. XML is extremely flexible in 4944 dealing with issues of white space, element ordering, inserting new 4945 elements, etc. This flexibility does not require extension, 4946 especially not in the area of the meaning of elements. 4948 There is no kindness in accepting illegal combinations of XML 4949 elements. At best it will cause an unwanted result and at worst it 4950 can cause real damage. 4952 A.3. Example - XML Syntax Error 4954 The following request body for a PROPFIND method is illegal. 4956 4957 4958 4959 4960 4962 The definition of the propfind element only allows for the allprop or 4963 the propname element, not both. Thus the above is an error and must 4964 be responded to with a 400 (Bad Request). 4966 Imagine, however, that a server wanted to be "kind" and decided to 4967 pick the allprop element as the true element and respond to it. A 4968 client running over a bandwidth limited line who intended to execute 4969 a propname would be in for a big surprise if the server treated the 4970 command as an allprop. 4972 Additionally, if a server were lenient and decided to reply to this 4973 request, the results would vary randomly from server to server, with 4974 some servers executing the allprop directive, and others executing 4975 the propname directive. This reduces interoperability rather than 4976 increasing it. 4978 A.4. Example - Unknown XML Element 4980 The previous example was illegal because it contained two elements 4981 that were explicitly banned from appearing together in the propfind 4982 element. However, XML is an extensible language, so one can imagine 4983 new elements being defined for use with propfind. Below is the 4984 request body of a PROPFIND and, like the previous example, must be 4985 rejected with a 400 (Bad Request) by a server that does not 4986 understand the expired-props element. 4988 4989 4991 4992 4994 To understand why a 400 (Bad Request) is returned let us look at the 4995 request body as the server unfamiliar with expired-props sees it. 4997 4998 5000 5002 As the server does not understand the 'expired-props' element, 5003 according to the WebDAV-specific XML processing rules specified in 5004 Section 16, it must ignore it. Thus the server sees an empty 5005 propfind, which by the definition of the propfind element is illegal. 5007 Please note that had the extension been additive it would not 5008 necessarily have resulted in a 400 (Bad Request). For example, 5009 imagine the following request body for a PROPFIND: 5011 5012 5014 5015 *boss* 5016 5018 The previous example contains the fictitious element leave-out. Its 5019 purpose is to prevent the return of any property whose name matches 5020 the submitted pattern. If the previous example were submitted to a 5021 server unfamiliar with 'leave-out', the only result would be that the 5022 'leave-out' element would be ignored and a propname would be 5023 executed. 5025 Appendix B. Notes on HTTP Client Compatibility 5027 The PUT and DELETE methods are defined in HTTP and thus may be used 5028 by HTTP clients, but the responses to PUT and DELETE have been 5029 extended in this specification, so some special consideration on 5030 backward compatibility is worthwhile. 5032 First, if a PUT or DELETE request includes a header defined in this 5033 specification (Depth or If), the server can assume the request comes 5034 from a WebDAV-compatible client. The server may even be able to 5035 track a number of requests across a session and know that a client is 5036 a WebDAV client. However, this kind of detection may not be 5037 necessary. 5039 Since any HTTP client ought to handle unrecognized 400-level and 500- 5040 level status codes as errors, the following new status codes should 5041 not present any issues: 422, 423 and 507. 424 is also a new status 5042 code but it appears only in the body of a Multistatus response. So, 5043 for example, if a HTTP client attempted to PUT or DELETE a locked 5044 resource, the 423 Locked response ought to result in a generic error 5045 presented to the user. 5047 The 207 Multistatus response is interesting because a HTTP client 5048 issuing a DELETE request to a collection might interpret a 207 5049 response as a success, even though it does not realize the resource 5050 is a collection and cannot understand that the DELETE operation might 5051 have been a complete or partial failure. Thus, a server MAY choose 5052 to treat a DELETE of a collection as an atomic operation, and use 5053 either 204 No Content in case of success, or some appropriate error 5054 response (400 or 500 level) depending on what the error was. This 5055 approach would maximize backward compatibility. However, since 5056 interoperability tests and working group discussions have not turned 5057 up any instances of HTTP clients issuing a DELETE request against a 5058 WebDAV collection, this concern may be more theoretical than 5059 practical. Thus, servers MAY instead choose to treat any such DELETE 5060 request as a WebDAV request, and send a 207 Multistatus containing 5061 more detail about what resources could not be deleted. 5063 Appendix C. The opaquelocktoken scheme and URIs 5065 The 'opaquelocktoken' URI scheme was defined in RFC2518 (and 5066 registered by IANA) in order to create syntactically correct and 5067 easy-to-generate URIs out of UUIDs, intended to be used as lock 5068 tokens and to be unique across all resources for all time. 5070 An opaquelocktoken URI is constructed by concatenating the 5071 'opaquelocktoken' scheme with a UUID, along with an optional 5072 extension. Servers can create new UUIDs for each new lock token. If 5073 a server wishes to reuse UUIDs the server MUST add an extension and 5074 the algorithm generating the extension MUST guarantee that the same 5075 extension will never be used twice with the associated UUID. 5077 OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] 5078 ; UUID is defined in section 3 of RFC4122. Note that linear white 5079 ; space (LWS) is not allowed between elements of this production. 5081 Extension = path 5082 ; path is defined in section 3.3 of RFC3986 5084 Appendix D. Guidance for Clients Desiring to Authenticate 5086 Many WebDAV clients already implemented have account settings 5087 (similar to the way email clients store IMAP account settings). 5088 Thus, the WebDAV client would be able to authenticate with its first 5089 couple requests to the server, provided it had a way to get the 5090 authentication challenge from the server with realm name, nonce and 5091 other challenge information. Note that the results of some requests 5092 might vary according to whether the client is authenticated or not -- 5093 a PROPFIND might return more visible resources if the client is 5094 authenticated, yet not fail if the client is anonymous. 5096 There are a number of ways the client might be able to trigger the 5097 server do provide an authentication challenge. This appendix 5098 describes a couple approaches that seem particularly likely to work. 5100 The first approach is to perform a request that ought to require 5101 authentication. However, it's possible that a server might handle 5102 any request even without authentication, so to be entirely safe the 5103 client could add a conditional header to ensure that even if the 5104 request passes permissions checks it's not actually handled by the 5105 server. An example of following this approach would be to use a PUT 5106 request with an "If-Match" header with a made-up ETag value. This 5107 approach might fail to result in an authentication challenge if the 5108 server does not test authorization before testing conditionals as is 5109 required (see Section 8.1.3), or if the server does not need to test 5110 authorization. 5112 Example - forcing auth challenge with write request 5114 >>Request 5116 PUT /forceauth.txt HTTP/1.1 5117 Host: www.example.com 5118 If-Match: "xxx" 5119 Content-Type: text/plain 5120 Content-Length: 0 5122 The second approach is to use an Authorization header (defined in 5123 [RFC2617]) which is likely to be rejected by the server but which 5124 will then prompt a proper authentication challenge. For example, the 5125 client could start with a PROPFIND request containing an 5126 Authorization header containing a made-up Basic userid:password 5127 string or with actual plausible credentials. This approach relies on 5128 the server responding with a "401 Unauthorized" along with a 5129 challenge if it receives an Authorization header with an unrecognized 5130 username, invalid password, or if it doesn't even handle Basic 5131 authentication. This seems likely to work because of the 5132 requirements of RFC2617: 5134 "If the origin server does not wish to accept the credentials sent 5135 with a request, it SHOULD return a 401 (Unauthorized) response. The 5136 response MUST include a WWW-Authenticate header field containing at 5137 least one (possibly new) challenge applicable to the requested 5138 resource." 5140 Example - forcing auth challenge with Authorization header 5142 >>Request 5144 PROPFIND /docs/ HTTP/1.1 5145 Host: www.example.com 5146 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 5147 Content-type: application/xml; charset="utf-8" 5148 Content-Length: xxxx 5150 [body omitted] 5152 Appendix E. Summary of changes from RFC2518 5154 This section describes changes that are likely to result in 5155 implementation changes due to tightened requirements or changed 5156 behavior. 5158 E.1. Changes Notable to Server Implementors 5160 Tightened requirements for storing property values (Section 4.4) when 5161 "xml:lang" appears and also when values are XML fragments 5162 (specifically on preserving prefixes, namespaces and whitespace.) 5164 Tightened requirements on which properties are protected and computed 5165 (Section 14). 5167 Several tightened requirements for general response handling 5168 (Section 8.1), including response bodies for use with errors, ETag 5169 and Location header, and reminder to use Date header. 5171 Tightened requirements for URL construction in PROPFIND (Section 8.2) 5172 responses. 5174 Tightened requirements for checking identity of lock owners 5175 (Section 7.1) during operations affected by locks. 5177 Tightened requirements for copying properties (Section 8.9.2) and 5178 moving properties (Section 8.10.1). 5180 Tightened requirements on preserving owner field in locks 5181 (Section 8.11). Added "lockroot" element to lockdiscovery 5182 information. 5184 New value for "DAV:" header (Section 9.1) to advertise support for 5185 this specification. 5187 Tightened requirement for "Destination:" header (Section 9.3) to work 5188 with path values 5190 Some changes for "If:" header (Section 9.4), including "DAV:no-lock" 5191 state token and requirement to evaluate entire header. 5193 Support for UTF-16 now required (ref (Section 18)). 5195 Removed definition of "source" property and special handling for 5196 dynamic resources 5198 Replaced lock-null resources with simpler locked empty resources 5199 (Section 7.6). Lock-null resources are now not compliant with the 5200 requirements in this specification. 5202 Encouraged servers to change ETags (Section 8.1.4) only when body of 5203 resource changes. 5205 The definition of the 102 Processing response was removed and servers 5206 ought to stop sending that response when they implement this 5207 specification. 5209 Previously, servers were encouraged to return 409 status code in 5210 response to a collection LOCK request if some resource could not be 5211 locked. Now servers should use 207 Multi-Status instead. 5213 Only 'rfc1123-date' productions are legal as values for DAV: 5214 getlastmodified. 5216 New explicit requirement to do authorization checks before 5217 conditional checks (Section 8.1.3). 5219 E.2. Changes Notable to Client Implementors 5221 Tightened requirements for supporting WebDAV collections 5222 (Section 5.2) within resources that do not support WebDAV (e.g. 5223 servlet containers). 5225 Redefined 'allprop' PROPFIND requests so that the server does not 5226 have to return all properties. 5228 Required to handle empty multistatus responses in PROPFIND responses 5229 (Section 8.2) 5231 No more "propertybehavior" specification allowed in MOVE and COPY 5232 requests 5234 The change in behavior of LOCK with an unmapped URL might affect 5235 client implementations that counted on lock-null resources 5236 disappearing when the lock expired. Clients can no longer rely on 5237 that cleanup happening. 5239 Support for UTF-16 now required (ref (Section 18)). 5241 Removed definition of "source" property and special handling for 5242 dynamic resources. 5244 The definition of the 102 Processing response was removed and clients 5245 can safely remove code (if any) that deals with this. 5247 Servers may now reject PROPFIND depth "infinity" requests. 5249 Clients use Lock-Token header, not the If header, to provide lock 5250 token when renewing lock. Section 8.11.1 5252 Appendix F. Change Log (to be removed by RFC Editor before publication) 5254 F.1. Changes from -05 to -06 5256 Specified that a successful LOCK request to an unmapped URL creates a 5257 new, empty locked resource. 5259 Resolved UNLOCK_NEEDS_IF_HEADER by clarifying that only Lock-Token 5260 header is needed on UNLOCK. 5262 Added Section 15 on preconditions and postconditions and defined a 5263 number of preconditions and postconditions. The 'lock-token-present' 5264 precondition resolves the REPORT_OTHER_RESOURCE_LOCKED issue. 5266 Added example of matching lock token to URI in the case of a 5267 collection lock in the If header section. 5269 Removed ability for Destination header to take "abs_path" in order to 5270 keep consistent with other places where client provides URLs (If 5271 header, href element in request body) 5273 Clarified the href element - that it generally contains HTTP URIs but 5274 not always. 5276 Attempted to fix the BNF describing the If header to allow commas 5278 Clarified presence of Depth header on LOCK refresh requests. 5280 F.2. Changes in -07 5282 Added text to "COPY and the Overwrite Header" section to resolve 5283 issue OVERWRITE_DELETE_ALL_TOO_STRONG. 5285 Added text to "HTTP URL Namespace Model" section to provide more 5286 clarification and examples on what consistency means and what is not 5287 required, to resolve issue CONSISTENCY. 5289 Resolve DEFINE_PRINCIPAL by importing definition of principal from 5290 RFC3744. 5292 Resolve INTEROP_DELETE_AND_MULTISTATUS by adding appendix 3 5293 discussing backward-compatibility concerns. 5295 Resolve DATE_FORMAT_GETLASTMODIFIED by allowing only rfc1123-date, 5296 not HTTP-date for getlastmodified. 5298 Resolve COPY_INTO_YOURSELF_CLARIFY by adding sentence to first para. 5299 of COPY section. 5301 Confirm that WHEN_TO_MULTISTATUS_FOR_DELETE_1 and 5302 WHEN_TO_MULTISTATUS_FOR_DELETE_2 are resolved and tweak language in 5303 DELETE section slightly to be clearly consistent. 5305 More text clarifications to deal with several of the issues in 5306 LOCK_ISSUES. This may not completely resolve that set but we need 5307 feedback from the originator of the issues at this point. 5309 Resolved COPY_INTO_YOURSELF_CLARIFY with new sentence in Copy For 5310 Collections section. 5312 Double checked that LEVEL_OR_CLASS is resolved by using class, not 5313 level. 5315 Further work to resolve IF_AND_AUTH and LOCK_SEMANTICS, clarifying 5316 text on using locks and being authenticated. 5318 Added notes on use of 503 status response to resolve issue 5319 PROPFIND_INFINITY 5321 Removed section on other uses of Metadata (and associated references) 5323 Added reference to RFC4122 for lock tokens and removed section on 5324 generating UUIDs 5326 Explained that even with language variation, a property has only one 5327 value (section 4.5). 5329 Added section on lock owner (7.1) and what to do if lock requested by 5330 unauthenticated user 5332 Removed section 4.2 -- justification on why to have metadata, not 5333 needed now 5335 Removed paragraph in section 5.2 about collections with resource type 5336 "DAV:collection" but which are non-WebDAV compliant -- not 5337 implemented. 5339 F.3. Changes in -08 5341 Added security considerations section on scripts and cookie sessions, 5342 suggested by Barry Lind 5344 Clarified which error codes are defined and undefined in MultiStatus 5346 Moved opaquelocktoken definition to an appendix and refer to RFC4122 5347 for use of 'urn:uuid:' URI scheme; fix all lock token examples to use 5348 this. 5350 Multi-status responses contain URLs which MUST either be absolute 5351 (and begin with the Request-URI or MUST be relative with new 5352 limitations. (bug 12) 5354 Moved status code sections before example sections within PROPFIND 5355 section for section ordering consistency. 5357 Clarified use of Location header with Multi-Status 5359 Bugzilla issue resolutions: bugs 9, 12, 14, 19, 20, 29, 30, 34, 36, 5360 102 and 172. 5362 F.4. Changes in -09 5364 Bugzilla editorial issues: bugs 30, 57, 63, 68, 88, 89, 168, 180, 5365 182, 185, 187. 5367 More clarity between URL namespaces and XML namespaces, particularly 5368 at the beginning of paragraphs using the word namespace 5370 More consistency in referring to properties with the namespace, as in 5371 "DAV:lockdiscovery", and referring to XML element names in single 5372 quotes, e.g. 'allprop' element. 5374 Figure (example) formatting fixes 5376 Bugzilla issues: bugs 24, 37, 39, 43, 45, 27, 25 5378 Replaced references to "non-null state" of resources with more clear 5379 language about URLs that are mapped to resources, bug 25. Also added 5380 definition of URL/URI mapping. Bug 40. 5382 Bugzilla issues: bug 7, 8, 9, 41, 47, 51, 62, 93, 171, 172. Bugs 28 5383 and 94 were iterated on. 5385 Bugzilla issues: 56, 59, 79, 99, 103, 175, 178. Part of bug 23. 5386 Iteration on bug 10. 5388 Iteration on bugs 10, 46 and 47. Bug 11. 5390 Remove "102 Processing" response 5392 Fix bug 46, 105, 107, 120, 140 and 201. 5394 Another stab at bug 12 - relative v. absolute URLs in Multi-Status 5395 response hrefs 5397 Fix bug 6, 11, 15, 16, 28, 32, 42, 51, 52, 53, 58, 60, 62, 186, 189, 5398 191, 199, 200 5400 Fix bug 96 5402 F.5. Chandles in -10 5404 Clarify lock intro text on when a client might use another client's 5405 lock token - suggestion by Geoff, Nov 15 5407 Removed Force-Authenticate header and instead added an appendix 5408 explaining how existing mechanisms might resolve the need of clients 5409 to get an authentication challenge (bug 18). 5411 Bug 62, 113, 125, 131, 143, 144, 171, 193 5413 Bug 176, 177, 179, 181, 184, 206, 207, 208 5415 Author's Address 5417 Lisa Dusseault 5418 Open Source Application Foundation 5419 2064 Edgewood Dr. 5420 Palo Alto, CA 94303 5421 US 5423 Email: lisa@osafoundation.org 5425 Intellectual Property Statement 5427 The IETF takes no position regarding the validity or scope of any 5428 Intellectual Property Rights or other rights that might be claimed to 5429 pertain to the implementation or use of the technology described in 5430 this document or the extent to which any license under such rights 5431 might or might not be available; nor does it represent that it has 5432 made any independent effort to identify any such rights. Information 5433 on the procedures with respect to rights in RFC documents can be 5434 found in BCP 78 and BCP 79. 5436 Copies of IPR disclosures made to the IETF Secretariat and any 5437 assurances of licenses to be made available, or the result of an 5438 attempt made to obtain a general license or permission for the use of 5439 such proprietary rights by implementers or users of this 5440 specification can be obtained from the IETF on-line IPR repository at 5441 http://www.ietf.org/ipr. 5443 The IETF invites any interested party to bring to its attention any 5444 copyrights, patents or patent applications, or other proprietary 5445 rights that may cover technology that may be required to implement 5446 this standard. Please address the information to the IETF at 5447 ietf-ipr@ietf.org. 5449 Disclaimer of Validity 5451 This document and the information contained herein are provided on an 5452 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 5453 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 5454 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 5455 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 5456 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 5457 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5459 Copyright Statement 5461 Copyright (C) The Internet Society (2005). This document is subject 5462 to the rights, licenses and restrictions contained in BCP 78, and 5463 except as set forth therein, the authors retain all their rights. 5465 Acknowledgment 5467 Funding for the RFC Editor function is currently provided by the 5468 Internet Society.