idnits 2.17.1 draft-ietf-webdav-acl-07.txt: -(862): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(872): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1030): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1036): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1611): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2059): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2410): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == There are 17 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 15 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 2159 has weird spacing: '...contain a DAV...' == Line 2169 has weird spacing: '...arch of a pro...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 9, 2001) is 8203 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'WEBDAV' is mentioned on line 476, but not defined == Missing Reference: 'RFC2589' is mentioned on line 571, but not defined == Missing Reference: 'REC-XMLINFOSET' is mentioned on line 2180, but not defined == Unused Reference: 'REC-XML-INFOSET' is defined on line 2650, but no explicit reference was found in the text == Unused Reference: 'RFC2368' is defined on line 2669, but no explicit reference was found in the text == Unused Reference: 'RFC2026' is defined on line 2682, but no explicit reference was found in the text == Unused Reference: 'RFC2251' is defined on line 2688, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-XML-NAMES' -- Possible downref: Non-RFC (?) normative reference: ref. 'RFCxxxx' -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-XML-INFOSET' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2518 (Obsoleted by RFC 4918) ** Obsolete normative reference: RFC 2368 (Obsoleted by RFC 6068) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 2279 (ref. 'UTF-8') (Obsoleted by RFC 3629) -- Obsolete informational reference (is this intentional?): RFC 2255 (Obsoleted by RFC 4510, RFC 4516) -- Obsolete informational reference (is this intentional?): RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) Summary: 8 errors (**), 0 flaws (~~), 12 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Geoffrey Clemm, Rational Software 2 draft-ietf-webdav-acl-07 Anne Hopkins, Microsoft Corporation 3 Eric Sedlar, Oracle Corporation 4 Jim Whitehead, U.C. Santa Cruz 6 Expires May 9, 2001 November 9, 2001 8 WebDAV Access Control Protocol 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with all 13 provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering Task 16 Force (IETF), its areas, and its working groups. Note that other groups 17 may also distribute working documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet- Drafts as reference material 22 or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 Abstract 32 This document specifies a set of methods, headers, and message bodies 33 that define Access Control extensions to the WebDAV Distributed 34 Authoring Protocol. This protocol permits a client to read and modify 35 access control lists that instruct a server whether to allow or deny 36 operations upon a resource (such as HTTP method invocations) by a given 37 principal. 39 This document is a product of the Web Distributed Authoring and 40 Versioning (WebDAV) working group of the Internet Engineering Task 41 Force. Comments on this draft are welcomed, and should be addressed to 42 the acl@webdav.org mailing list. Other related documents can be found at 43 http://www.webdav.org/acl/, and http://www.ics.uci.edu/pub/ietf/webdav/. 45 Table of Contents 47 1 INTRODUCTION.......................................................5 48 1.1 Terms............................................................7 49 1.2 Notational Conventions...........................................8 51 2 PRINCIPALS.........................................................8 53 3 PRIVILEGES.........................................................9 54 3.1 DAV:read Privilege..............................................11 55 3.2 DAV:write Privilege.............................................11 56 3.3 DAV:read-acl Privilege..........................................11 57 3.4 DAV:read-current-user-privilege-set Privilege...................11 58 3.5 DAV:write-acl Privilege.........................................12 59 3.6 DAV:all Privilege...............................................12 60 3.7 Aggregation of Predefined Privileges............................12 62 4 PRINCIPAL PROPERTIES..............................................12 63 4.1 DAV:alternate-URI-set...........................................13 65 5 ACCESS CONTROL PROPERTIES.........................................13 66 5.1 DAV:owner.......................................................13 67 5.1.1 Example: Retrieving DAV:owner................................14 68 5.1.2 Example: An Attempt to Set DAV:owner.........................15 69 5.2 DAV:supported-privilege-set.....................................16 70 5.2.1 Example: Retrieving a List of Privileges Supported on a 71 Resource.....................................................16 72 5.3 DAV:current-user-privilege-set..................................18 73 5.3.1 Example: Retrieving the User's Current Set of Assigned 74 Privileges.........................................................19 75 5.4 DAV:acl.........................................................20 76 5.4.1 ACE Principal................................................20 77 5.4.2 ACE Grant and Deny...........................................21 78 5.4.3 ACE Protection...............................................21 79 5.4.4 ACE Inheritance..............................................22 80 5.4.5 Example: Retrieving a Resource's Access Control List......22 81 5.5 DAV:acl-semantics...............................................23 82 5.5.1 Example: Retrieving DAV:acl-semantics........................24 83 5.6 DAV:principal-collection-set....................................25 84 5.6.1 Example: Retrieving DAV:principal-collection-set.............26 85 5.7 Example: PROPFIND to retrieve access control properties.........27 87 6 ACL SEMANTICS.....................................................30 88 6.1 ACE Combination.................................................31 89 6.1.1 DAV:first-match ACE Combination..............................31 90 6.1.2 DAV:all-grant-before-any-deny ACE Combination................31 91 6.1.3 DAV:specific-deny-overrides-grant ACE Combination............31 92 6.2 ACE Ordering....................................................31 93 6.2.1 DAV:deny-before-grant ACE Ordering...........................32 94 6.3 Allowed ACE.....................................................32 95 6.3.1 DAV:principal-only-one-ace ACE Constraint....................32 96 6.3.2 DAV:grant-only ACE Constraint................................32 97 6.4 Required Principals.............................................32 99 7 ACCESS CONTROL AND EXISTING METHODS...............................32 100 7.1 OPTIONS.........................................................33 101 7.1.1 Example - OPTIONS............................................33 102 7.2 MOVE............................................................33 103 7.3 COPY............................................................33 104 7.4 DELETE..........................................................33 105 7.5 LOCK............................................................34 107 8 ACCESS CONTROL METHODS............................................34 108 8.1 ACL.............................................................34 109 8.1.1 ACL Preconditions............................................34 110 8.1.2 Example: the ACL method......................................36 111 8.1.3 Example: ACL method failure due to protected ACE conflict....37 112 8.1.4 Example: ACL method failure due to an inherited ACE conflict 38 113 8.1.5 Example: ACL method failure due to an attempt to set grant 114 and deny in a single ACE.....................................39 116 9 ACCESS CONTROL REPORTS............................................40 117 9.1 REPORT Method...................................................40 118 9.2 DAV:acl-principal-props Report..................................40 119 9.2.1 Example: DAV:acl-principal-props Report......................40 120 9.3 DAV:principal-match REPORT......................................42 121 9.3.1 Example: DAV:principal-match REPORT..........................43 122 9.4 DAV:principal-property-search REPORT............................44 123 9.4.1 Matching.....................................................45 124 9.4.2 Example: successful DAV:principal-property-search REPORT.....46 125 9.4.3 Example: Unsuccessful DAV:principal-property-search REPORT...48 126 9.5 DAV:principal-search-property-set REPORT........................49 127 9.5.1 Example: DAV:principal-search-property-set REPORT............50 129 10 XML PROCESSING..................................................51 131 11 INTERNATIONALIZATION CONSIDERATIONS.............................51 133 12 SECURITY CONSIDERATIONS.........................................52 134 12.1 Increased Risk of Compromised Users...........................52 135 12.2 Risks of the DAV:read-acl and DAV:current-user-privilege-set 136 Privileges....................................................52 137 12.3 No Foreknowledge of Initial ACL...............................53 139 13 AUTHENTICATION..................................................53 141 14 IANA CONSIDERATIONS.............................................53 143 15 INTELLECTUAL PROPERTY...........................................54 145 16 ACKNOWLEDGEMENTS................................................54 146 17 REFERENCES......................................................55 147 17.1 Normative References..........................................55 148 17.2 Informational References......................................56 150 18 AUTHORS' ADDRESSES..............................................56 152 19 APPENDICIES.....................................................57 153 19.1 XML Document Type Definition..................................57 155 20 NOTE TO RFC EDITOR..............................................59 156 1 INTRODUCTION 158 The goal of the WebDAV access control extensions is to provide an 159 interoperable mechanism for handling discretionary access control for 160 content and metadata managed by WebDAV servers. WebDAV access 161 control can be implemented on content repositories with security as 162 simple as that of a UNIX file system, as well as more sophisticated 163 models. The underlying principle of access control is that who you 164 are determines what operations you can perform on a resource. The 165 "who you are" is defined by a "principal" identifier; users, client 166 software, servers, and groups of the previous have principal 167 identifiers. The "operations you can perform" is determined by a 168 single "access control list" (ACL) associated with a resource. An 169 ACL contains a set of "access control entries" (ACEs), where each ACE 170 specifies a principal and a set of privileges that are either granted 171 or denied to that principal. When a principal submits an operation 172 (such as an HTTP or WebDAV method) to a resource for execution, the 173 server evaluates the ACEs in the ACL to determine if the principal 174 has permission for that operation. 176 Since every ACE contains the identifier of a principal, client 177 software operated by a human must provide a mechanism for selecting 178 this principal. This specification uses http(s) scheme URLs to 179 identify principals, which are represented as WebDAV-capable 180 resources. There is no guarantee that the URLs identifying principals 181 will be meaningful to a human. For example, 182 http://www.dav.org/u/256432 and http://www.dav.org/people/Greg.Stein 183 are both valid URLs that could be used to identify the same 184 principal. To remedy this, every principal resource has the 185 DAV:displayname property containing a human-readable name for the 186 principal. 188 Since a principal can be identified by multiple URLs, it raises the 189 problem of determining exactly which principal's operations are being 190 described in a given ACE. It is impossible for a client to determine 191 that an ACE granting the read privilege to 192 http://www.dav.org/people/Greg.Stein also affects the principal at 193 http://www.dav.org/u/256432. That is, a client has no mechanism for 194 determining that two URLs identify the same principal resource. As a 195 result, this specification requires clients to use just one of the 196 many possible URLs for a principal when creating ACEs. A client can 197 discover this URL by retrieving the DAV:principal-URL property 198 (Section 4.2) from a principal resource. No matter which of the 199 principal's URLs is used with PROPFIND, the property always returns 200 the same URL. 202 Once a system has hundreds to thousands of principals, the problem 203 arises of how to allow a human operator of client software to select 204 just one of these principals. One approach is to use broad collection 205 hierarchies to spread the principals over a large number of 206 collections, yielding few principals per collection. An example of 207 this is a two level hierarchy with the first level containing 36 208 collections (a-z, 0-9), and the second level being another 36, 209 creating collections /a/a/, /a/b/, �, /a/z/, such that a principal 210 with last name "Stein" would appear at /s/t/Stein. In effect, this 211 pre-computes a common query, search on last name, and encodes it into 212 a hierarchy. The drawback with this scheme is that it handles only a 213 small set of predefined queries, and drilling down through the 214 collection hierarchy adds unnecessary steps (navigate down/up) when 215 the user already knows the principal's name. While organizing 216 principal URLs into a hierarchy is a valid namespace organization, 217 users should not be forced to navigate this hierarchy to select a 218 principal. 220 This specification provides the capability to perform substring 221 searches on a small set of properties on the resources representing 222 principals. This permits searches based on last name, first name, 223 user name, job title, etc. Two separate searches are supported, via 224 the REPORT method, one to search principal resources, the other to 225 determine which properties may be searched at all. 227 Once a principal has been identified in an ACE, a server evaluating 228 that ACE must know the identity of the principal making a protocol 229 request, and must validate that that principal is who they claim to 230 be, a process known as authentication. This specification 231 intentionally omits discussion of authentication, as the HTTP 232 protocol already has a number of authentication mechanisms [RFC2617]. 233 Some authentication mechanism (such as HTTP Digest Authentication, 234 which all WebDAV compliant implementations are required to support) 235 must be available to validate the identity of a principal. 237 The following issues are out of scope for this document: 239 * Access control that applies only to a particular property on a 240 resource (excepting the access control properties DAV:acl and 241 DAV:current-user-privilege-set), rather than the entire 242 resource, 244 * Role-based security (where a role can be seen as a dynamically 245 defined collection of principals), 247 * Specification of the ways an ACL on a resource is initialized, 249 * Specification of an ACL that applies globally to all 250 resources, rather than to a particular resource. 252 * Creation and maintenance of resources representing people or 253 computational agents (principals), and groups of these. 255 This specification is organized as follows. Section 1.1 defines key 256 concepts used throughout the specification, and is followed by a more 257 in-depth discussion of principals (Section 2), and privileges 258 (Section 3). Properties defined on principals are specified in 259 Section 4, and access control properties for content resources are 260 specified in Section 5. The semantics of access control lists are 261 described in Section 6, including sections on ACE combination 262 (Section 6.1), ACE ordering (Section 6.2), and principals required to 263 be present in an ACE (Section 6.4). Client discovery of access 264 control capability using OPTIONS is described in Section 7.1. 265 Interactions between access control functionality and existing HTTP 266 and WebDAV methods are described in the remainder of Section 7. The 267 access control setting method, ACL, is specified in Section 8. Four 268 reports that provide limited server-side searching capabilities are 269 described in Section 9. A note on XML processing (Section 10), 270 Internationalization considerations (Section 11), security 271 considerations (Section 12), and a note on authentication (Section 272 13) round out the specification. An appendix (Section 19.1) provides 273 an XML Document Type Definition (DTD) for the XML elements defined in 274 the specification. 276 1.1 Terms 278 This draft uses the terms defined in HTTP [RFC2616] and WebDAV 279 [RFC2518]. In addition, the following terms are defined: 281 principal 283 A "principal" is a distinct human or computational actor that 284 initiates access to network resources. In this protocol, a 285 principal is an HTTP resource that represents such an actor. 287 principal collection 289 A "principal collection" is a group of principals, and is 290 represented in this protocol by a WebDAV collection containing HTTP 291 resources that represent principals, and principal collections. 293 privilege 295 A "privilege" controls access to a particular set of HTTP 296 operations on a resource. 298 aggregate privilege 300 An "aggregate privilege" is a privilege that contains a set of 301 other privileges. 303 abstract privilege 305 The modifier "abstract", when applied to a privilege, means the 306 privilege cannot be set in an access control element (ACE). 308 access control list (ACL) 309 An "ACL" is a list of access control elements that define access 310 control to a particular resource. 312 access control element (ACE) 314 An "ACE" either grants or denies a particular set of (non-abstract) 315 privileges for a particular principal. 317 inherited ACE 319 An "inherited ACE" is an ACE that is dynamically shared from the 320 ACL of another resource. When a shared ACE changes on the primary 321 resource, it is also changed on inheriting resources. 323 protected property 325 A "protected property" is one whose value cannot be updated except 326 by a method explicitly defined as updating that specific property. 327 In particular, a protected property cannot be updated with a 328 PROPPATCH request. 330 1.2 Notational Conventions 332 The augmented BNF used by this document to describe protocol elements 333 is described in Section 2.1 of [RFC2616]. Because this augmented BNF 334 uses the basic production rules provided in Section 2.2 of [RFC2616], 335 those rules apply to this document as well. 337 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 338 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 339 document are to be interpreted as described in [RFC2119]. 341 Definitions of XML elements in this document use XML element type 342 declarations (as found in XML Document Type Declarations), described 343 in Section 3.2 of [REC-XML]. When an XML element type in the "DAV:" 344 namespace is referenced in this document outside of the context of an 345 XML fragment, the string "DAV:" will be prefixed to the element type. 347 2 PRINCIPALS 349 A principal is a network resource that represents a distinct human or 350 computational actor that initiates access to network resources. Users 351 and groups are represented as principals in many implementations; 352 other types of principals are also possible. A URI of any scheme MAY 353 be used to identify a principal resource. However, servers 354 implementing this specification MUST expose principal resources at an 355 http(s) URL, which is a privileged scheme that points to resources 356 that have additional properties, as described in Section 4. So, a 357 principal resource can have multiple URIs, one of which has to be an 358 http(s) scheme URL. Although an implementation SHOULD support 359 PROPFIND and MAY support PROPPATCH to access and modify information 360 about a principal, it is not required to do so. 362 A principal resource may or may not be a collection. If a person or 363 computational agent matches a principal resource that is contained by 364 a collection principal, they also match the collection principal. 365 This definition is recursive, and hence if a person or computational 366 agent matches a collection principal that is the child of another 367 collection principal, they also match the parent collection 368 principal. Membership in a collection principal is also recursive, so 369 a principal in a collection principal GRPA contained by collection 370 principal GRPB is a member of both GRPA and GRPB. Implementations not 371 supporting recursive membership in principal collections can return 372 an error if the client attempts to bind collection principals into 373 other collection principals. 375 Servers that support aggregation of principals (e.g. groups of users 376 or other groups) MUST manifest them as collection principals. At 377 minimum, principals and collection principals MUST support the 378 OPTIONS and PROPFIND methods. 380 Implementer's Note: Collection principals are first and foremost 381 WebDAV collections. Therefore they contain resources as members. 382 Since there is no requirement that all members of a collection 383 principal need be principals, it is possible for a collection 384 principal to have non-principals as members. When enumerating the 385 principals-only membership of a collection principal, it is 386 necessary to retrieve the DAV:resourcetype property and check it 387 for the DAV:principal XML element (described in Section 4). If the 388 DAV:principal XML element is not present, the resource is not a 389 principal and may be ignored for the purposes of determining the 390 principals-only membership of the collection principal. 392 For example, the collection principal /FOO/ has two members, Bar 393 and Baz. Bar is a principal but Baz is not. Therefore when 394 determining which principals belong to the collection principal 395 /FOO/, a client would enumerate the membership using PROPFIND 396 while asking for the DAV:resourcetype property, and see that only 397 Bar has the DAV:principal XML element. Therefore, only Bar is the 398 only principal that is a member of the collection principal /FOO/. 400 3 PRIVILEGES 402 Ability to perform a given method on a resource SHOULD be controlled 403 by one or more privileges. Authors of protocol extensions that 404 define new HTTP methods SHOULD specify which privileges (by defining 405 new privileges, or mapping to ones below) are required to perform the 406 method. A principal with no privileges to a resource SHOULD be 407 denied any HTTP access to that resource, unless the principal matches 408 an ACE constructed using the DAV:all, DAV:authenticated, or 409 DAV:unauthenticated pseudo-principals (see Section 5.4.1). 411 Privileges may be containers of other privileges, in which case they 412 are termed aggregate privileges. If a principal is granted or denied 413 an aggregate privilege, it is semantically equivalent to granting or 414 denying each of the aggregated privileges individually. For example, 415 an implementation may define add-member and remove-member privileges 416 that control the ability to add and remove an internal member of a 417 collection. Since these privileges control the ability to update the 418 state of a collection, these privileges would be aggregated by the 419 DAV:write privilege on a collection, and granting the DAV:write 420 privilege on a collection would also grant the add-member and remove- 421 member privileges. 423 Privileges may have the quality of being abstract, in which case they 424 cannot be set in an ACE. Aggregate and non-aggregate privileges are 425 both capable of being abstract. Abstract privileges are useful for 426 modeling privileges that otherwise would not be exposed via the 427 protocol. Abstract privileges also provide server implementations 428 with flexibility in implementing the privileges defined in this 429 specification. For example, if a server is incapable of separating 430 the read resource capability from the read ACL capability, it can 431 still model the DAV:read and DAV:read-acl privileges defined in this 432 specification by declaring them abstract, and containing them within 433 a non-abstract aggregate privilege (say, read-all) that holds 434 DAV:read, and DAV:read-acl. In this way, it is possible to set the 435 aggregate privilege, read-all, thus coupling the setting of DAV:read 436 and DAV:read-acl, but it is not possible to set DAV:read, or 437 DAV:read-acl individually. Since aggregate privileges can be 438 abstract, it is also possible to use abstract privileges to group or 439 organize non-abstract privileges. Privilege containment loops are not 440 allowed, hence a privilege MUST NOT contain itself. For example, 441 DAV:read cannot contain DAV:read. 443 The set of privileges that apply to a particular resource may vary 444 with the DAV:resourcetype of the resource, as well as between 445 different server implementations. To promote interoperability, 446 however, this specification defines a set of well-known privileges 447 (e.g. DAV:read, DAV:write, DAV:read-acl, DAV:write-acl, DAV:read- 448 current-user-privilege-set, and DAV:all), which can at least be used 449 to classify the other privileges defined on a particular resource. 450 The access permissions on null resources (defined in [RFC2518], 451 Section 3) are solely those they inherit (if any), and they are not 452 discoverable (i.e., the access control properties specified in 453 Section 5 are not defined on null resources). On the transition from 454 null to stateful resource, the initial access control list is set by 455 the server's default ACL value policy (if any). 457 Server implementations MAY define new privileges beyond those defined 458 in this specification. Privileges defined by individual 459 implementations MUST NOT use the DAV: namespace, and instead should 460 use a namespace that they control, such as an http scheme URL. 462 3.1 DAV:read Privilege 464 The read privilege controls methods that return information about the 465 state of the resource, including the resource's properties. Affected 466 methods include GET and PROPFIND. Additionally, the read privilege 467 MAY control the OPTIONS method. 469 471 3.2 DAV:write Privilege 473 The write privilege controls methods that modify the content, dead 474 properties, or (in the case of a collection) membership of the 475 resource, such as PUT and PROPPATCH. Note that state modification is 476 also controlled via locking (see section 5.3 of [WEBDAV]), so 477 effective write access requires that both write privileges and write 478 locking requirements are satisfied. 480 482 3.3 DAV:read-acl Privilege 484 The DAV:read-acl privilege controls the use of PROPFIND to retrieve 485 the DAV:acl property of the resource. 487 489 3.4 DAV:read-current-user-privilege-set Privilege 491 The DAV:read-current-user-privilege-set privilege controls the use of 492 PROPFIND to retrieve the DAV:current-user-privilege-set property of 493 the resource. 495 Clients are intended to use this property to visually indicate in 496 their UI items that are dependent on the permissions of a resource, 497 for example, by graying out resources that are not writeable. 499 This privilege is separate from DAV:read-acl because there is a need 500 to allow most users access to the privileges permitted the current 501 user (due to its use in creating the UI), while the full ACL contains 502 information that may not be appropriate for the current authenticated 503 user. As a result, the set of users who can view the full ACL is 504 expected to be much smaller than those who can read the current user 505 privilege set, and hence distinct privileges are needed for each. 507 508 3.5 DAV:write-acl Privilege 510 The DAV:write-acl privilege controls use of the ACL method to modify 511 the DAV:acl property of the resource. 513 515 3.6 DAV:all Privilege 517 DAV:all is an aggregate privilege that contains the entire set of 518 privileges that can be applied to the resource. 520 522 3.7 Aggregation of Predefined Privileges 524 Server implementations are free to aggregate the predefined 525 privileges (defined above in Sections 3.1-3.6) subject to the 526 following limitations: 528 DAV:read-acl MUST NOT contain DAV:read, DAV:write, DAV:write-acl, or 529 DAV:read-current-user-privilege-set. 531 DAV:write-acl MUST NOT contain DAV:write, DAV:read, DAV:read-acl, or 532 DAV:read-current-user-privilege-set. 534 DAV:read-current-user-privilege-set MUST NOT contain DAV:write, 535 DAV:read, DAV:read-acl, or DAV:write-acl. 537 DAV:write MUST NOT contain DAV:read, DAV:read-acl, or DAV:read- 538 current-user-privilege-set. 540 DAV:read MUST NOT contain DAV:write, or DAV:write-acl. 542 4 PRINCIPAL PROPERTIES 544 Principals are manifested to clients as a WebDAV resource, identified 545 by a URL. A principal MUST have a DAV:displayname property (defined 546 in Section 13.2 of [RFC2518]), and a DAV:resourcetype property 547 (defined in Section 13.9 of [RFC2518]). Additionally, a principal 548 MUST report the DAV:principal empty XML element in the value of the 549 DAV:resourcetype property in addition to all other reported elements. 550 For example, a collection principal would report DAV:collection and 551 DAV:principal elements. The element type declaration for 552 DAV:principal is: 554 556 This protocol defines the following additional property for a 557 principal. Since it is expensive, for many servers, to retrieve 558 access control information, the name and value of this property 559 SHOULD NOT be returned by a PROPFIND allprop request (as defined in 560 Section 12.14.1 of [RFC2518]). 562 4.1 DAV:alternate-URI-set 564 This protected property, if non-empty, contains the URIs of network 565 resources with additional descriptive information about the 566 principal. This property identifies additional network resources 567 (i.e., it contains one or more URIs) that may be consulted by a 568 client to gain additional knowledge concerning a principal. One 569 expected use for this property is the storage of an ldap [RFC2255] 570 scheme URL. A user-agent encountering an ldap URL could use LDAP 571 [RFC2589] to retrieve additional machine-readable directory 572 information about the principal, and display that information in its 573 user interface. Support for this property is REQUIRED, and the value 574 is empty if no alternate URI exists for the principal. 576 578 4.2 DAV:principal-URL 580 This protected property contains the URL that MUST be used to 581 identify this principal in an ACL request. 583 585 5 ACCESS CONTROL PROPERTIES 587 This specification defines a number of new properties for WebDAV 588 resources. Access control properties may be retrieved just like 589 other WebDAV properties, using the PROPFIND method. Since it is 590 expensive, for many servers, to retrieve access control information, 591 a PROPFIND allprop request (as defined in Section 12.14.1 of 592 [RFC2518]) SHOULD NOT return the names and values of the properties 593 defined in this section. 595 HTTP resources that support the WebDAV Access Control Protocol MUST 596 contain the following properties. Null resources (described in 597 Section 3 of [RFC2518]) MUST NOT contain the following properties: 599 5.1 DAV:owner 601 This protected property identifies a particular principal as being 602 the "owner" of the resource. Since the owner of a resource often has 603 special access control capabilities (e.g., the owner frequently has 604 permanent DAV:write-acl privilege), clients might display the 605 resource owner in their user interface. 607 608 5.1.1 Example: Retrieving DAV:owner 610 This example shows a client request for the value of the DAV:owner 611 property from a collection resource with URL 612 http://www.webdav.org/papers/. The principal making the request is 613 authenticated using Digest authentication. The value of DAV:owner is 614 the URL http://www.webdav.org/_acl/users/gstein, wrapped in the 615 DAV:href XML element. 617 >> Request << 619 PROPFIND /papers/ HTTP/1.1 620 Host: www.webdav.org 621 Content-type: text/xml; charset="utf-8" 622 Content-Length: xxx 623 Depth: 0 624 Authorization: Digest username="jim", 625 realm="jim@webdav.org", nonce="...", 626 uri="/papers/", response="...", opaque="..." 628 629 630 631 632 633 635 >> Response << 637 HTTP/1.1 207 Multi-Status 638 Content-Type: text/xml; charset="utf-8" 639 Content-Length: xxx 641 642 643 644 http://www.webdav.org/papers/ 645 646 647 648 http://www.webdav.org/_acl/users/gstein 649 650 651 HTTP/1.1 200 OK 652 653 654 655 5.1.2 Example: An Attempt to Set DAV:owner 657 The following example shows a client request to modify the value of 658 the DAV:owner property on the resource with URL 659 http://www.webdav.org/papers/. Since DAV:owner is a protected 660 property, the server responds with a 207 (Multi-Status) response that 661 contains a 403 (Forbidden) status code for the act of setting 662 DAV:owner. Section 8.2.1 of [RFC2518] describes PROPPATCH status code 663 information, and Section 11 of [RFC2518] describes the Multi-Status 664 response. 666 >> Request << 668 PROPPATCH /papers/ HTTP/1.1 669 Host: www.webdav.org 670 Content-type: text/xml; charset="utf-8" 671 Content-Length: xxx 672 Depth: 0 673 Authorization: Digest username="jim", 674 realm="jim@webdav.org", nonce="...", 675 uri="/papers/", response="...", opaque="..." 677 678 679 680 681 682 http://www.webdav.org/_acl/users/jim 683 684 685 686 688 >> Response << 690 HTTP/1.1 207 Multi-Status 691 Content-Type: text/xml; charset="utf-8" 692 Content-Length: xxx 694 695 696 697 http://www.webdav.org/papers/ 698 699 700 HTTP/1.1 403 Forbidden 701 Failure to set protected property 702 (DAV:owner) 703 704 705 706 708 5.2 DAV:supported-privilege-set 710 This is a protected property that identifies the privileges defined 711 for the resource. 712 714 Each privilege appears as an XML element, where aggregate 715 privileges list as sub-elements all of the privileges that they 716 aggregate. 717 719 721 An abstract privilege MUST NOT be used in an ACE for that resource. 722 Servers MUST fail an attempt to set an abstract privilege. 724 726 A description is a human-readable description of what this privilege 727 controls access to. Servers MUST indicate the human language of the 728 description using the xml:lang attribute and SHOULD consider the HTTP 729 Accept-Language request header when selecting one of multiple 730 available languages. 732 734 It is envisioned that a WebDAV ACL-aware administrative client would 735 list the supported privileges in a dialog box, and allow the user to 736 choose non-abstract privileges to apply in an ACE. The privileges 737 tree is useful programmatically to map well-known privileges (defined 738 by WebDAV or other standards groups) into privileges that are 739 supported by any particular server implementation. The privilege 740 tree also serves to hide complexity in implementations allowing large 741 number of privileges to be defined by displaying aggregates to the 742 user. 744 5.2.1 Example: Retrieving a List of Privileges Supported on a Resource 746 This example shows a client request for the DAV:supported-privilege- 747 set property on the resource http://www.webdav.org/papers/. The value 748 of the DAV:supported-privilege-set property is a tree of supported 749 privileges: 751 DAV:all (aggregate, abstract) 752 | 753 +-- DAV:read (aggregate) 754 | 755 +-- DAV:read-acl (abstract) 756 +-- DAV:read-current-user-privilege-set (abstract) 757 +-- DAV:write (aggregate) 758 | 759 +-- DAV:write-acl (abstract) 761 This privilege tree is not normative, and many possible privilege 762 trees are possible. 764 >> Request << 766 PROPFIND /papers/ HTTP/1.1 767 Host: www.webdav.org 768 Content-type: text/xml; charset="utf-8" 769 Content-Length: xxx 770 Depth: 0 771 Authorization: Digest username="gclemm", 772 realm="gclemm@webdav.org", nonce="...", 773 uri="/papers/", response="...", opaque="..." 775 776 777 778 779 780 782 >> Response << 784 HTTP/1.1 207 Multi-Status 785 Content-Type: text/xml; charset="utf-8" 786 Content-Length: xxx 788 789 790 791 http://www.webdav.org/papers/ 792 793 794 795 796 797 798 Any 799 operation 800 801 802 Read any 803 object 804 805 806 807 Read 808 ACL 809 810 811 812 813 814 815 816 Read current user 817 privilege set property 818 819 820 821 Write any 822 object 823 824 825 Write 826 ACL 827 828 829 830 831 832 833 HTTP/1.1 200 OK 834 835 836 838 5.3 DAV:current-user-privilege-set 840 DAV:current-user-privilege-set is a protected property containing the 841 exact set of privileges (as computed by the server) granted to the 842 currently authenticated HTTP user. Aggregate privileges and their 843 contained privileges are listed. A user-agent can use the value of 844 this property to adjust its user interface to make actions 845 inaccessible (e.g., by graying out a menu item or button) for which 846 the current principal does not have permission. This is particularly 847 useful for an access control user interface, which can be constructed 848 without knowing the ACE combining semantics of the server. This 849 property is also useful for determining what operations the current 850 principal can perform, without having to actually execute an 851 operation. 853 854 856 If the current user is granted a specific privilege, that privilege 857 must belong to the set of privileges that may be set on this 858 resource. Therefore, each element in the DAV:current-user-privilege- 859 set property MUST identify a non-abstract privilege from the 860 DAV:supported-privilege-set property. 862 5.3.1 Example: Retrieving the User�s Current Set of Assigned Privileges 864 Continuing the example from Section 5.2.1, this example shows a 865 client requesting the DAV:current-user-privilege-set property from 866 the resource with URL http://www.webdav.org/papers/. The username of 867 the principal making the request is �khare", and Digest 868 authentication is used in the request. The principal with username 869 �khare" has been granted the DAV:read privilege. Since the DAV:read 870 privilege contains the DAV:read-acl and DAV:read-current-user- 871 privilege-set privileges (see Section 5.2.1), the principal with 872 username �khare" can read the ACL property, and the DAV:current-user- 873 privilege-set property. However, the DAV:all, DAV:read-acl, 874 DAV:write-acl and DAV:read-current-user-privilege-set privileges are 875 not listed in the value of DAV:current-user-privilege-set, since (for 876 this example) they are abstract privileges. DAV:write is not listed 877 since the principal with username �khare" is not listed in an ACE 878 granting that principal write permission. 880 >> Request << 882 PROPFIND /papers/ HTTP/1.1 883 Host: www.webdav.org 884 Content-type: text/xml; charset="utf-8" 885 Content-Length: xxx 886 Depth: 0 887 Authorization: Digest username="khare", 888 realm="khare@webdav.org", nonce="...", 889 uri="/papers/", response="...", opaque="..." 891 892 893 894 895 896 898 >> Response << 900 HTTP/1.1 207 Multi-Status 901 Content-Type: text/xml; charset="utf-8" 902 Content-Length: xxx 903 904 905 906 http://www.webdav.org/papers/ 907 908 909 910 911 912 913 HTTP/1.1 200 OK 914 915 916 918 5.4 DAV:acl 920 This is a protected property that specifies the list of access 921 control entries (ACEs), which define what principals are to get what 922 privileges for this resource. 924 926 Each DAV:ace element specifies the set of privileges to be either 927 granted or denied to a single principal. If the DAV:acl property is 928 empty, no principal is granted any privilege. 930 932 5.4.1 ACE Principal 934 The DAV:principal element identifies the principal to which this ACE 935 applies. 937 941 The current user matches DAV:href only if that user is authenticated 942 as being (or being a member of) the principal identified by the URL 943 contained by that DAV:href. 945 The current user always matches DAV:all. 947 949 The current user matches DAV:authenticated only if authenticated. 951 952 The current user matches DAV:unauthenticated only if not 953 authenticated. 955 957 DAV:all is the union of DAV:authenticated, and DAV:unauthenticated. 958 For a given request, the user matches either DAV:authenticated, or 959 DAV:unauthenticated, but not both (that is, DAV:authenticated and 960 DAV:unauthenticated are disjoint sets). 962 The current user matches a DAV:property principal in a DAV:acl 963 property of a resource only if the value of the identified property 964 of that resource contains at most one DAV:href XML element, the URI 965 value of DAV:href identifies a principal, and the current user is 966 authenticated as being (or being a member of) that principal. For 967 example, if the DAV:property element contained , the 968 current user would match the DAV:property principal only if the 969 current user is authenticated as matching the principal identified by 970 the DAV:owner property of the resource. 972 974 The current user matches DAV:self in a DAV:acl property of the 975 resource only if that resource is a principal object and the current 976 user is authenticated as being that principal or a member of that 977 principal collection. 979 981 5.4.2 ACE Grant and Deny 983 Each DAV:grant or DAV:deny element specifies the set of privileges to 984 be either granted or denied to the specified principal. A DAV:grant 985 or DAV:deny element of the DAV:acl of a resource MUST only contain 986 non-abstract elements specified in the DAV:supported-privilege-set of 987 that resource. 989 990 991 993 5.4.3 ACE Protection 995 A server indicates an ACE is protected by including the DAV:protected 996 element in the ACE. If the ACL of a resource contains an ACE with a 997 DAV:protected element, an attempt to remove that ACE from the ACL 998 MUST fail.. 1000 1001 5.4.4 ACE Inheritance 1003 The presence of a DAV:inherited element indicates that this ACE is 1004 inherited from another resource that is identified by the URL 1005 contained in a DAV:href element. An inherited ACE cannot be modified 1006 directly, but instead the ACL on the resource from which it is 1007 inherited must be modified. 1009 Note that ACE inheritance is not the same as ACL initialization. ACL 1010 initialization defines the ACL that a newly created resource will use 1011 (if not specified). ACE inheritance refers to an ACE that is 1012 logically shared - where an update to the resource containing an ACE 1013 will affect the ACE of each resource that inherits that ACE. The 1014 method by which ACLs are initialized or by which ACEs are inherited 1015 is not defined by this document. 1017 1019 5.4.5 Example: Retrieving a Resource�s Access Control List 1021 Continuing the example from Sections 5.2.1 and 5.3.1, this example 1022 shows a client requesting the DAV:acl property from the resource with 1023 URL http://www.webdav.org/papers/. There are two ACEs defined in this 1024 ACL: 1026 ACE #1: The principal collection identified by URL 1027 http://www.webdav.org/_acl/groups/maintainers/ (the group of site 1028 maintainers) is granted DAV:write privilege. Since (for this example) 1029 DAV:write contains the DAV:write-acl privilege (see Section 5.2.1), 1030 this means the �maintainers" group can also modify the access control 1031 list. 1033 ACE #2: All principals (DAV:all) are granted the DAV:read privilege. 1034 Since (for this example) DAV:read contains DAV:read-acl and DAV:read- 1035 current-user-privilege-set, this means all users (including all 1036 members of the �maintainers" group) can read the DAV:acl property and 1037 the DAV:current-user-privilege-set property. 1039 >> Request << 1041 PROPFIND /papers/ HTTP/1.1 1042 Host: www.webdav.org 1043 Content-type: text/xml; charset="utf-8" 1044 Content-Length: xxx 1045 Depth: 0 1046 Authorization: Digest username="masinter", 1047 realm="masinter@webdav.org", nonce="...", 1048 uri="/papers/", response="...", opaque="..." 1050 1051 1052 1053 1054 1055 1057 >> Response << 1059 HTTP/1.1 207 Multi-Status 1060 Content-Type: text/xml; charset="utf-8" 1061 Content-Length: xxx 1063 1064 1065 1066 http://www.webdav.org/papers/ 1067 1069 1070 1071 1072 1073 1074 http://www.webdav.org/_acl/groups/maintainers/ 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 HTTP/1.1 200 OK 1092 1093 1094 1096 5.5 DAV:acl-semantics 1098 This is a protected property that defines the ACL semantics. These 1099 semantics define how multiple ACEs that match the current user are 1100 combined, what are the constraints on how ACEs can be ordered, and 1101 which principals must have an ACE. A client user interface could use 1102 the value of this property to provide feedback to a human operator 1103 concerning the impact of proposed changes to an ACL. Alternately, a 1104 client can use this property to help it determine, before submitting 1105 an ACL method invocation, what ACL changes it needs to make to 1106 accomplish a specific goal (or whether that goal is even achievable 1107 on this server). 1109 Since it is not practical to require all implementations to use the 1110 same ACL semantics, the DAV:acl-semantics property is used to 1111 identify the ACL semantics for a particular resource. The DAV:acl- 1112 semantics element is defined in Section 6. 1114 5.5.1 Example: Retrieving DAV:acl-semantics 1116 In this example, the client requests the value of the DAV:acl- 1117 semantics property. Digest authentication provides credentials for 1118 the principal operating the client. In this example, the ACE 1119 combination semantics are DAV:first-match, described in Section 1120 6.1.1, the ACE ordering semantics are not specified (some value other 1121 than DAV:deny-before-grant, described in Section 6.2.1), the 1122 DAV:allowed-ace element states that only one ACE is permitted for 1123 each principal, and an ACE describing the privileges granted the 1124 DAV:all principal must exist in every ACL. 1126 >> Request << 1128 PROPFIND /papers/ HTTP/1.1 1129 Host: www.webdav.org 1130 Content-type: text/xml; charset="utf-8" 1131 Content-Length: xxx 1132 Depth: 0 1133 Authorization: Digest username="srcarter", 1134 realm="srcarter@webdav.org", nonce="...", 1135 uri="/papers/", response="...", opaque="..." 1137 1138 1139 1140 1141 1142 1144 >> Response << 1146 HTTP/1.1 207 Multi-Status 1147 Content-Type: text/xml; charset="utf-8" 1148 Content-Length: xxx 1150 1151 1152 1153 http://www.webdav.org/papers/ 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 HTTP/1.1 200 OK 1170 1171 1172 1174 5.6 DAV:principal-collection-set 1176 This protected property contains zero, one, or more URLs that 1177 identify a collection principal. It is expected that implementations 1178 of this protocol will typically use a relatively small number of 1179 locations in the URL namespace for principals, and collection 1180 principals. In cases where this assumption holds, the DAV:principal- 1181 collection-set property will contain a small set of URLs identifying 1182 the top of a collection hierarchy containing multiple principals and 1183 collection principals. An access control protocol user agent could 1184 use the contents of DAV:principal-collection-set to retrieve the 1185 DAV:displayname property (specified in Section 13.2 of [RFC2518]) of 1186 all principals on that server, thereby yielding human-readable names 1187 for each principal that could be displayed in a user interface. 1189 1190 Since different servers can control different parts of the URL 1191 namespace, different resources on the same host MAY have different 1192 DAV:principal-collection-set values. The collections specified in the 1193 DAV:principal-collection-set MAY be located on different hosts from 1194 the resource. The URLs in DAV:principal-collection-set SHOULD be http 1195 or https scheme URLs. For security and scalability reasons, a server 1196 MAY report only a subset of the entire set of known collection 1197 principals, and therefore clients should not assume they have 1198 retrieved an exhaustive listing. Additionally, a server MAY elect to 1199 report none of the collection principals it knows about, in which 1200 case the property value would be empty. 1202 The value of DAV:principal-collection-set gives the scope of the 1203 DAV:principal-property-search REPORT (defined in Section 9.4). 1204 Clients use the DAV:principal-property-search REPORT to populate 1205 their user interface with a list of principals. Therefore, servers 1206 that limit a client's ability to obtain principal information will 1207 interfere with the client's ability to manipulate access control 1208 lists, due to the difficulty of getting the URL of a principal for 1209 use in an ACE. 1211 5.6.1 Example: Retrieving DAV:principal-collection-set 1213 In this example, the client requests the value of the DAV:principal- 1214 collection-set property on the collection resource identified by URL 1215 http://www.webdav.org/papers/. The property contains the two URLs, 1216 http://www.webdav.org/_acl/users/ and 1217 http://www.webdav.org/_acl/groups/, both wrapped in XML 1218 elements. Digest authentication provides credentials for the 1219 principal operating the client. 1221 The client might reasonably follow this request with two separate 1222 PROPFIND requests to retrieve the DAV:displayname property of the 1223 members of the two collections (/_acl/users/ and /_acl_groups/). This 1224 information could be used when displaying a user interface for 1225 creating access control entries. 1227 >> Request << 1229 PROPFIND /papers/ HTTP/1.1 1230 Host: www.webdav.org 1231 Content-type: text/xml; charset="utf-8" 1232 Content-Length: xxx 1233 Depth: 0 1234 Authorization: Digest username="yarong", 1235 realm="yarong@webdav.org", nonce="...", 1236 uri="/papers/", response="...", opaque="..." 1238 1239 1240 1241 1242 1243 1245 >> Response << 1246 HTTP/1.1 207 Multi-Status 1247 Content-Type: text/xml; charset="utf-8" 1248 Content-Length: xxx 1250 1251 1252 1253 http://www.webdav.org/papers/ 1254 1255 1256 1257 1258 http://www.webdav.org/_acl/users/ 1259 1260 1261 http://www.webdav.org/_acl/groups/ 1262 1263 1264 1265 HTTP/1.1 200 OK 1266 1267 1268 1270 5.7 Example: PROPFIND to retrieve access control properties 1272 The following example shows how access control information can be 1273 retrieved by using the PROPFIND method to fetch the values of the 1274 DAV:owner, DAV:supported-privilege-set, DAV:current-user-privilege- 1275 set, and DAV:acl properties. 1277 >> Request << 1279 PROPFIND /top/container/ HTTP/1.1 1280 Host: www.foo.org 1281 Content-type: text/xml; charset="utf-8" 1282 Content-Length: xxx 1283 Depth: 0 1284 Authorization: Digest username="ejw", 1285 realm="users@foo.org", nonce="...", 1286 uri="/top/container/", response="...", opaque="..." 1288 1289 1290 1291 1292 1293 1294 1295 1296 1298 >> Response << 1300 HTTP/1.1 207 Multi-Status 1301 Content-Type: text/xml; charset="utf-8" 1302 Content-Length: xxx 1304 1305 1308 http://www.foo.org/top/container/ 1309 1310 1311 1312 http://www.foo.org/users/gclemm 1313 1314 1315 1316 1317 Any operation 1318 1319 1320 Read any 1321 object 1322 1323 1324 1325 1326 Write any 1327 object 1328 1329 1330 Create an 1331 object 1332 1333 1334 1335 Update an 1336 object 1337 1338 1339 1340 Delete an 1341 object 1342 1343 1344 1345 1346 Read the ACL 1347 1348 1349 1350 Write the 1351 ACL 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 http://www.foo.org/users/esedlar 1363 1364 1365 1366 1367 1368 1369 1370 1371 http://www.foo.org/groups/marketing/ 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 http://www.foo.org/top/ 1389 1390 1391 HTTP/1.1 200 OK 1392 1394 The value of the DAV:owner property is a single DAV:href XML element 1395 containing the URL of the principal that owns this resource. 1397 The value of the DAV:supported-privilege-set property is a tree of 1398 supported privileges: 1400 DAV:all (aggregate, abstract) 1401 | 1402 +-- DAV:read 1403 +-- DAV:write (aggregate, abstract) 1404 | 1405 +-- http://www.webdav.org/acl/create 1406 +-- http://www.webdav.org/acl/update 1407 +-- http://www.webdav.org/acl/delete 1408 +-- DAV:read-acl 1409 +-- DAV:write-acl 1411 The DAV:current-user-privilege-set property contains two privileges, 1412 DAV:read, and DAV:read-acl. This indicates that the current 1413 authenticated user only has the ability to read the resource, and 1414 read the DAV:acl property on the resource. 1416 The DAV:acl property contains a set of four ACEs: 1418 ACE #1: The principal identified by the URL 1419 http://www.foo.org/users/esedlar is granted the DAV:read, DAV:write, 1420 and DAV:read-acl privileges. 1422 ACE #2: The principals identified by the URL 1423 http://www.foo.org/groups/marketing/ are denied the DAV:read 1424 privilege. In this example, the principal URL identifies a group, 1425 which is represented by a collection principal. 1427 ACE #3: In this ACE, the principal is a property principal, 1428 specifically the DAV:owner property. When evaluating this ACE, the 1429 value of the DAV:owner property is retrieved, and is examined to see 1430 if it contains a DAV:href XML element. If so, the URL within the 1431 DAV:href element is read, and identifies a principal. In this ACE, 1432 the owner is granted DAV:read-acl, and DAV:write-acl privileges. 1434 ACE #4: This ACE grants the DAV:all principal (all users) the 1435 DAV:read privilege. This ACE is inherited from the resource 1436 http://www.foo.org/top/, the parent collection of this resource. 1438 6 ACL SEMANTICS 1440 The ACL semantics define how multiple ACEs that match the current 1441 user are combined, what are the constraints on how ACEs can be 1442 ordered, and which principals must have an ACE. 1444 1446 6.1 ACE Combination 1448 The DAV:ace-combination element defines how privileges from multiple 1449 ACEs that match the current user will be combined to determine the 1450 access privileges for that user. Multiple ACEs may match the same 1451 user because the same principal can appear in multiple ACEs, because 1452 multiple principals can identify the same user, and because one 1453 principal can be a member of another principal. 1455 1459 6.1.1 DAV:first-match ACE Combination 1461 The ACEs are evaluated in the order in which they appear in the ACL. 1462 If the first ACE that matches the current user does not grant all the 1463 privileges needed for the request, the request MUST fail. 1465 1467 6.1.2 DAV:all-grant-before-any-deny ACE Combination 1469 The ACEs are evaluated in the order in which they appear in the ACL. 1470 If an evaluated ACE denies a privilege needed for the request, the 1471 request MUST fail. If all ACEs have been evaluated without the user 1472 being granted all privileges needed for the request, the request MUST 1473 fail. 1475 1477 6.1.3 DAV:specific-deny-overrides-grant ACE Combination 1479 All ACEs in the ACL are evaluated. An "individual ACE" is one whose 1480 principal identifies the current user. A "group ACE" is one whose 1481 principal is a collection that contains a principal that identifies 1482 the current user. A privilege is granted if it is granted by an 1483 individual ACE and not denied by an individual ACE, or if it is 1484 granted by a group ACE and not denied by an individual or group ACE. 1485 A request MUST fail if any of its needed privileges are not granted. 1487 1489 6.2 ACE Ordering 1491 The DAV:ace-ordering element defines a constraint on how the ACEs can 1492 be ordered in the ACL. 1494 1495 6.2.1 DAV:deny-before-grant ACE Ordering 1497 This element indicates that all deny ACEs must precede all grant 1498 ACEs. 1500 1502 6.3 Allowed ACE 1504 The DAV:allowed-ace XML element specifies constraints on what kinds 1505 of ACEs are allowed in an ACL. 1507 1509 6.3.1 DAV:principal-only-one-ace ACE Constraint 1511 This element indicates that a principal can appear in only one ACE 1512 per resource. 1514 1516 6.3.2 DAV:grant-only ACE Constraint 1518 This element indicates that ACEs with deny clauses are not allowed. 1520 1522 6.4 Required Principals 1524 The required principal elements identify which principals must have 1525 an ACE defined in the ACL. 1527 1531 For example, the following element requires that the ACL contain a 1532 DAV:owner property ACE: 1534 1535 1536 1538 7 ACCESS CONTROL AND EXISTING METHODS 1540 This section defines the impact of access control functionality on 1541 existing methods. 1543 7.1 OPTIONS 1545 If the server supports access control, it MUST return "access- 1546 control" as a field in the DAV response header from an OPTIONS 1547 request on any resource implemented by that server. 1549 7.1.1 Example - OPTIONS 1551 >> Request << 1553 OPTIONS /foo.html HTTP/1.1 1554 Host: www.webdav.org 1555 Content-Length: 0 1557 >> Response << 1559 HTTP/1.1 200 OK 1560 DAV: 1, 2, access-control 1561 Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, ACL 1563 In this example, the OPTIONS response indicates that the server 1564 supports access control and that /foo.html can have its access 1565 control list modified by the ACL method. 1567 7.2 MOVE 1569 When a resource is moved from one location to another due to a MOVE 1570 request, the non-inherited and non-protected ACEs in the DAV:acl 1571 property of the resource MUST NOT be modified, or the MOVE request 1572 fails. Handling of inherited and protected ACEs is intentionally 1573 undefined to give server implementations flexibility in how they 1574 implement ACE inheritance and protection. 1576 7.3 COPY 1578 The DAV:acl property on the resource at the destination of a COPY 1579 MUST be the same as if the resource was created by an individual 1580 resource creation request (e.g. MKCOL, PUT). Clients wishing to 1581 preserve the DAV:acl property across a copy need to read the DAV:acl 1582 property prior to the COPY, then perform an ACL operation on the new 1583 resource at the destination to restore, insofar as this is possible, 1584 the original access control list. 1586 7.4 DELETE 1588 The precise combination of privileges and resources necessary to 1589 permit the DELETE method is intentionally left to the discretion of 1590 each server implementation. It is envisioned that on some servers, 1591 DELETE will require write permission on the collection containing the 1592 resource to be deleted. On other servers, it might also require 1593 write permission on the resource being deleted. 1595 7.5 LOCK 1597 A lock on a resource ensures that only the lock owner can modify ACEs 1598 that are not inherited and not protected (these are the only ACEs 1599 that a client can modify with an ACL request). A lock does not 1600 protect inherited or protected ACEs, since a client cannot modify 1601 them with an ACL request on that resource. 1603 8 ACCESS CONTROL METHODS 1605 8.1 ACL 1607 The ACL method modifies the access control list (which can be read 1608 via the DAV:acl property) of a resource. Specifically, the ACL 1609 method only permits modification to ACEs that are not inherited, and 1610 are not protected. An ACL method invocation modifies all non- 1611 inherited and non-protected ACEs in a resource�s access control list 1612 to exactly match the ACEs contained within in the DAV:acl XML element 1613 (specified in Section 5.4) of the request body. An ACL request body 1614 MUST contain only one DAV:acl XML element. Unless the non-inherited 1615 and non-protected ACEs of the DAV:acl property of the resource can be 1616 updated to be exactly the value specified in the ACL request, the ACL 1617 request MUST fail. 1619 It is possible that the ACEs visible to the current user in the 1620 DAV:acl property may only be a portion of the complete set of ACEs on 1621 that resource. If this is the case, an ACL request only modifies the 1622 set of ACEs visible to the current user, and does not affect any non- 1623 visible ACE. 1625 In order to avoid overwriting DAV:acl changes by another client, a 1626 client SHOULD acquire a WebDAV lock on the resource before retrieving 1627 the DAV:acl property of a resource that it intends on updating. 1629 Implementation Note: Two common operations are to add or remove an 1630 ACE from an existing access control list. To accomplish this, a 1631 client uses the PROPFIND method to retrieve the value of the 1632 DAV:acl property, then parses the returned access control list to 1633 remove all inherited and protected ACEs (these ACEs are tagged 1634 with the DAV:inherited and DAV:protected XML elements). In the 1635 remaining set of non-inherited, non-protected ACEs, the client can 1636 add or remove one or more ACEs before submitting the final ACE set 1637 in the request body of the ACL method. 1639 8.1.1 ACL Preconditions 1641 An implementation MAY enforce one or more of the following 1642 constraints on an ACL request. If the constraint is violated, a 403 1643 (Forbidden) response MUST be returned and the indicated XML element 1644 MUST be returned as the top level element in an XML response body. 1646 : A conflict exists between two or more ACEs 1647 submitted in the ACL request. 1649 : A conflict exists between an ACE in 1650 the ACL request and a protected ACE on the resource. For example, if 1651 the resource has a protected ACE granting DAV:write to a given 1652 principal, then it would be a protected ACE conflict if the ACL 1653 request submitted an ACE denying DAV:write to the same principal. 1655 : A conflict exists between an ACE in 1656 the ACL request and an inherited ACE on the resource. For example, if 1657 the resource inherits an ACE from its parent collection granting 1658 DAV:write to a given principal, then it would be an inherited ACE 1659 conflict if the ACL request submitted an ACE denying DAV:write to the 1660 same principal. Note that reporting of this error will be 1661 implementation-dependent. Implementations have the choice to either 1662 report this error, or to allow the ACE to be set, and then let normal 1663 ACE evaluation rules determine whether the new ACE has any impact on 1664 the privileges available to a specific principal. 1666 : An implementation MAY limit the number of ACEs 1667 in an ACL. However, ACL-compliant servers MUST support at least one 1668 ACE granting privileges to a single principal, and one ACE granting 1669 privileges to a collection principal. 1671 : All non-inherited deny ACEs MUST precede 1672 all non-inherited grant ACEs. 1674 : For implementations that have the 1675 DAV:principal-only-one-ace constraint (defined in Section 6.3.1), 1676 this XML element indicates that fulfilling the ACL request would 1677 result in multiple ACEs for one or more principals. 1679 : For implementations that have the DAV:grant-only 1680 constraint (defined in Section 6.3.2), this XML element indicates the 1681 request contained one or more deny ACEs. 1683 : The ACL request attempts to set an abstract 1684 privilege in an ACE (see Section 5.2). 1686 : One or more of the privileges in the ACL 1687 request is not supported by the resource. 1689 : One or more required principals (see 1690 Section 6.4) would not be present in the access control list after 1691 processing the ACL request. The DAV:required-principal XML element 1692 MUST contain a list of the missing principal(s), following the syntax 1693 specified in Section 6.4. 1695 : One or more of the principal URLs in the 1696 ACL request does not identify a principal resource. 1698 : One or more of the principal URLs in the 1699 ACL request is not allowed in an ACE. For example, a server where 1700 only authenticated principals can access resources would not allow 1701 the DAV:all or DAV:unauthenticated principals to be used in an ACE, 1702 since these would allow unauthenticated access to resources. 1704 8.1.2 Example: the ACL method 1706 In the following example, user "fielding", authenticated by 1707 information in the Authorization header, grants the principal 1708 identified by the URL http://www.foo.org/users/esedlar (i.e., the 1709 user "esedlar") read and write privileges, grants the owner of the 1710 resource read-acl and write-acl privileges, and grants everyone read 1711 privileges. 1713 >> Request << 1715 ACL /top/container/ HTTP/1.1 1716 Host: www.foo.org 1717 Content-Type: text/xml; charset="utf-8" 1718 Content-Length: xxxx 1719 Authorization: Digest username="fielding", 1720 realm="users@foo.org", nonce="...", 1721 uri="/top/container/", response="...", opaque="..." 1723 1724 1725 1726 1727 http://www.foo.org/users/esedlar 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1751 >> Response << 1753 HTTP/1.1 200 OK 1755 8.1.3 Example: ACL method failure due to protected ACE conflict 1757 In the following request, user "fielding", authenticated by 1758 information in the Authorization header, attempts to deny the 1759 principal identified by the URL http://www.foo.org/users/esedlar 1760 (i.e., the user "esedlar") write privileges. Prior to the request, 1761 the DAV:acl property on the resource contained a protected ACE (see 1762 Section 5.4.3) granting DAV:owner the DAV:read and DAV:write 1763 privileges. The principal identified by URL 1764 http://www.foo.org/users/esedlar is the owner of the resource. The 1765 ACL method invocation fails because the submitted ACE conflicts with 1766 the protected ACE, thus violating the semantics of ACE protection. 1768 >> Request << 1770 ACL /top/container/ HTTP/1.1 1771 Host: www.foo.org 1772 Content-Type: text/xml; charset="utf-8" 1773 Content-Length: xxxx 1774 Authorization: Digest username="fielding", 1775 realm="users@foo.org", nonce="...", 1776 uri="/top/container/", response="...", opaque="..." 1778 1779 1780 1781 1782 http://www.foo.org/users/esedlar 1783 1784 1785 1786 1787 1788 1790 >> Response << 1792 HTTP/1.1 403 Forbidden 1793 Content-Type: text/xml; charset="utf-8" 1794 Content-Length: xxx 1796 1797 1798 8.1.4 Example: ACL method failure due to an inherited ACE conflict 1800 In the following request, user "ejw", authenticated by information in 1801 the Authorization header, tries to change the access control list on 1802 the resource http://www.foo.org/top/index.html. This resource has two 1803 inherited ACEs. 1805 Inherited ACE #1 grants the principal identified by URL 1806 http://www.foo.org/users/ejw (i.e., the user "ejw") 1807 http://www.foo.org/privs/write-all and DAV:read-acl privileges. On 1808 this server, http://www.foo.org/privs/write-all is an aggregate 1809 privilege containing DAV:write, and DAV:write-acl. 1811 Inherited ACE #2 grants principal DAV:all the DAV:read privilege. 1813 The request attempts to set a (non-inherited) ACE, denying the 1814 principal identified by the URL http://www.foo.org/users/ejw (i.e., 1815 the user �ejw") DAV:write permission. This conflicts with inherited 1816 ACE #1. Note that the decision to report an inherited ACE conflict is 1817 specific to this server implementation. Another server implementation 1818 could have allowed the new ACE to be set, and then used normal ACE 1819 evaluation rules to determine whether the new ACE has any impact on 1820 the privileges available to a principal. 1822 >> Request << 1824 ACL /top/index.html HTTP/1.1 1825 Host: www.foo.org 1826 Content-Type: text/xml; charset="utf-8" 1827 Content-Length: xxxx 1828 Authorization: Digest username="ejw", 1829 realm="users@foo.org", nonce="...", 1830 uri="/top/index.html", response="...", opaque="..." 1832 1833 1834 1835 1836 http://www.foo.org/users/ejw 1837 1838 1839 1840 1842 >> Response << 1844 HTTP/1.1 403 Forbidden 1845 Content-Type: text/xml; charset="utf-8" 1846 Content-Length: xxx 1848 1849 1851 8.1.5 Example: ACL method failure due to an attempt to set grant and 1852 deny in a single ACE. 1854 In this example, user "ygoland", authenticated by information in the 1855 Authorization header, tries to change the access control list on the 1856 resource http://www.foo.org/diamond/engagement-ring.gif. The ACL 1857 request includes a single, syntactically and semantically incorrect 1858 ACE, which attempts to grant the collection principal identified by 1859 the URL http://www.foo.org/users/friends/ DAV:read privilege and deny 1860 the principal identified by URL http://www.foo.org/users/ygoland-so 1861 (i.e., the user "ygoland-so") DAV:read privilege. However, it is 1862 illegal to have multiple principal elements, as well as both a grant 1863 and deny element in the same ACE, so the request fails due to poor 1864 syntax. 1866 >> Request << 1868 ACL /diamond/engagement-ring.gif HTTP/1.1 1869 Host: www.foo.org 1870 Content-Type: text/xml; charset="utf-8" 1871 Content-Length: xxxx 1872 Authorization: Digest username="ygoland", 1873 realm="users@foo.org", nonce="...", 1874 uri="/diamond/engagement-ring.gif", response="...", opaque="..." 1876 1877 1878 1879 1880 http://www.foo.org/users/friends/ 1881 1882 1883 1884 http://www.foo.org/users/ygoland-so 1885 1886 1887 1888 1890 >> Response << 1892 HTTP/1.1 400 Bad Request 1893 Content-Length: 0 1895 Note that if the request had been divided into two ACEs, one to 1896 grant, and one to deny, the request would have been syntactically 1897 well formed. 1899 9 ACCESS CONTROL REPORTS 1901 9.1 REPORT Method 1903 The REPORT method (defined in Section 3.6 of [RFCxxxx]) provides an 1904 extensible mechanism for obtaining information about a resource. 1905 Unlike the PROPFIND method, which returns the value of one or more 1906 named properties, the REPORT method can involve more complex 1907 processing. REPORT is valuable in cases where the server has access 1908 to all of the information needed to perform the complex request (such 1909 as a query), and where it would require multiple requests for the 1910 client to retrieve the information needed to perform the same 1911 request. 1913 9.2 DAV:acl-principal-props Report 1915 The DAV:acl-principle-props report returns, for all principals in the 1916 DAV:acl property that are identified by http(s) URLs, the value of 1917 the properties specified in the REPORT request body. In the case 1918 where a principal URL appears multiple times, the DAV:acl-principal- 1919 props report MUST return the properties for that principal only once. 1921 Marshalling 1923 The request body MUST be a DAV:acl-principal-props XML element. 1925 1926 ANY value: a sequence of one or more elements, with at most one 1927 DAV:prop element. 1928 prop: see RFC 2518, Section 12.11 1930 The response body for a successful request MUST be a DAV:multistatus 1931 XML element (i.e., the response uses the same format as the response 1932 for PROPFIND). 1934 multistatus: see RFC 2518, Section 12.9 1936 The response body for a successful DAV:acl-principal-props REPORT 1937 request MUST contain a DAV:response element for each principal 1938 identified by an http(s) URL listed in a DAV:principal XML element of 1939 an ACE within the DAV:acl property of the resource identified by the 1940 Request-URI. 1942 9.2.1 Example: DAV:acl-principal-props Report 1944 Resource http://www.webdav.org/index.html has an ACL with three ACEs: 1946 ACE #1: All principals (DAV:all) have DAV:read and DAV:read-current- 1947 user-privilege-set access. 1949 ACE #2: The principal identified by 1950 http://www.webdav.org/people/gstein (the user �gstein") is granted 1951 DAV:write, DAV:write-acl, DAV:read-acl privileges. 1953 ACE #3: The collection principal identified by 1954 http://www.webdav.org/groups/authors/ (the �authors" group) is 1955 granted DAV:write and DAV:read-acl privileges. 1957 The following example shows a DAV:acl-principal-props report 1958 requesting the DAV:displayname property. It returns the value of 1959 DAV:displayname for resources http://www.webdav.org/people/gstein and 1960 http://www.webdav.org/groups/authors/ , but not for DAV:all, since 1961 this is not an http(s) URL. 1963 >> Request << 1965 REPORT /index.html HTTP/1.1 1966 Host: www.webdav.org 1967 Content-Type: text/xml; charset="utf-8" 1968 Content-Length: xxxx 1970 1971 1972 1973 1974 1975 1977 >> Response << 1979 HTTP/1.1 207 Multi-Status 1980 Content-Type: text/xml; charset="utf-8" 1981 Content-Length: xxxx 1983 1984 1985 1986 http://www.webdav.org/people/gstein 1987 1988 1989 Greg Stein 1990 1991 HTTP/1.1 200 OK 1992 1993 1994 1995 http://www.webdav.org/groups/authors/ 1996 1997 1998 Site authors 1999 2000 HTTP/1.1 200 OK 2001 2002 2003 2005 9.3 DAV:principal-match REPORT 2007 The DAV:principal-match REPORT is used to identify all members of a 2008 collection that match the current user. In particular, if the 2009 collection contains principals, the report can be used to identify 2010 all members of the collection that match the current user. 2011 Alternatively, if the collection contains resources that have a 2012 property that identifies a principal (e.g. DAV:owner), then the 2013 report can be used to identify all members of the collection whose 2014 property identifies a principal that matches the current user. For 2015 example, this report can return all of the resources in a collection 2016 hierarchy that are owned by the current user. 2018 The Depth header (defined in Section 9.2 of [RFC2518]), with value 2019 "infinity", can be used with this report. In this case, the report 2020 operates on the collection in the Request-URI, as well as all child 2021 collections, grandchild collections, etc. 2023 Marshalling: 2025 The request body MUST be a DAV:principal-match XML element. 2027 2028 2029 ANY value: an element whose value identifies a property. The 2030 expectation is the value of the named property typically contains 2031 an href element that contains the URI of a principal 2032 2033 prop: see RFC 2518, Section 12.11 2035 The response body for a successful request MUST be a DAV:multistatus 2036 XML element. 2038 multistatus: see RFC 2518, Section 12.9 2040 The response body for a successful DAV:principal-match REPORT request 2041 MUST contain a DAV:response element for each member of the collection 2042 that matches the current user. When the DAV:principal-property 2043 element is used, a match occurs if the current user is the same as 2044 the principal identified by the URI found in the DAV:href element of 2045 the property identified by the DAV:principal-property element. When 2046 the DAV:self element is used in a DAV:principal-match report issued 2047 against a collection principal, it matches a child of the collection 2048 principal if that child (a principal resource) identifies the same 2049 principal as the current user. 2051 If DAV:prop is specified in the request body, the properties 2052 specified in the DAV:prop element MUST be reported in the 2053 DAV:response elements. 2055 9.3.1 Example: DAV:principal-match REPORT 2057 The following example identifies the members of the collection 2058 identified by the URL http://www.webdav.org/doc/ that are owned by 2059 the current user. The current user (�gclemm") is authenticated using 2060 Digest authentication. 2062 >> Request << 2064 REPORT /doc/ HTTP/1.1 2065 Host: www.webdav.org 2066 Authorization: Digest username="gclemm", 2067 realm="gclemm@webdav.org", nonce="...", 2068 uri="/papers/", response="...", opaque="..." 2069 Content-Type: text/xml; charset="utf-8" 2070 Content-Length: xxxx 2071 Depth: infinity 2073 2074 2075 2076 2077 2078 2080 >> Response << 2082 HTTP/1.1 207 Multi-Status 2083 Content-Type: text/xml; charset="utf-8" 2084 Content-Length: xxxx 2086 2087 2088 2089 http://www.webdav.org/doc/foo.html 2090 HTTP/1.1 200 OK 2091 2092 2093 http://www.webdav.org/doc/img/bar.gif 2094 HTTP/1.1 200 OK 2095 2096 2097 9.4 DAV:principal-property-search REPORT 2099 The DAV:principal-property-search REPORT performs a substring search 2100 on the character data value of specified properties. The server MUST 2101 perform caseless matching of substrings. Only properties defined on 2102 principal or collection principal resources are searched. For 2103 implementation efficiency, servers do not typically support substring 2104 searching on all properties. A client can discover the set of 2105 searchable properties by using the principal-search-property-set 2106 REPORT, defined in Section 9.5. 2108 Implementation Note: The value of a WebDAV property is a sequence 2109 of well-formed XML, and hence can include any character in the 2110 Unicode/ISO-10646 standard, that is, most known characters in 2111 human languages. Due to the idiosyncrasies of case mapping across 2112 human languages, implementation of caseless matching is non- 2113 trivial. Implementors are strongly encouraged to consult 2114 [CaseMap], especially Section 2.3 ("Caseless Matching"), for 2115 guidance when implementing their caseless matching algorithms. 2117 Marshalling: 2119 The DAV:principal-collection-set property of the resource identified 2120 by the Request-URI specifies the scope of the DAV:principal-property- 2121 search REPORT, as follows: 2123 - All principal and collection principal resources identified in 2124 DAV:principal-collection-set are searched 2125 - All principal and collection principal resources that are 2126 descendents of a collection principal resource identified in 2127 DAV:principal collection-set are searched. 2129 Servers MUST support the DAV:principal-property-search REPORT on all 2130 principal collections identified in the value of a DAV:principal- 2131 collection-set property. 2133 The request body MUST be a DAV:principal-property-search XML element 2134 containing a search specification and an optional list of properties. 2135 For every principal that matches the search specification, the 2136 response will contain the value of the properties on that principal. 2138 2140 The DAV:property-search element contains a prop element enumerating 2141 the properties to be searched and a caseless-substring element, 2142 containing the search string. 2144 2145 prop: see RFC 2518, Section 12.11 2147 2148 Multiple property-search elements or multiple elements within a 2149 DAV:prop element will be interpreted with a logical AND. An empty 2150 DAV:caseless-substring element will match all properties specified in 2151 its parent DAV:property-search element. 2153 The response body for a successful request MUST be a DAV:multistatus 2154 XML element. 2156 multistatus: see RFC 2518, Section 12.9 2158 The response body for a successful DAV:principal-property-search 2159 REPORT request MUST contain a DAV:response element for each 2160 principal whose property values satisfy the search specification 2161 given in DAV:principal-property-search. 2163 If DAV:prop is specified in the request body, the properties 2164 specified in the DAV:prop element MUST be reported in the 2165 DAV:response elements. 2167 Errors: 2169 If a request specifies a search of a property that is not 2170 searchable, a 403 (Forbidden) response MUST be returned and the 2171 response body MUST be a DAV:non-searchable-property element, 2172 containing the unsearchable properties. 2174 2176 9.4.1 Matching 2178 There are several cases to consider when matching strings. The 2179 easiest case is when a property value is "simple" and has only 2180 character information item content (see [REC-XMLINFOSET]). For 2181 example, the search string "julian" would match the DAV:displayname 2182 property with value "Julian Reschke". Note that the on-the-wire 2183 marshalling of DAV:displayname in this case is: 2185 Julian Reschke 2187 The name of the property is encoded into the XML element information 2188 item, and the character information item content of the property is 2189 "Julian Reschke". 2191 The more complicated case occurred when properties have mixed content 2192 (that is, compound values consisting of multiple child element items, 2193 other types of information items, and character information item 2194 content). Consider the property http://www.webdav.org/props/aprop, 2195 marshalled as: 2197 2198 {cdata 0}{cdata 1} 2199 {cdata 2}{cdata 3} 2200 2202 In this case, substring matching is performed on each individual 2203 contiguous sequence of character information items. In the example 2204 above, a search string would be compared to the four following 2205 strings: 2207 {cdata 0} 2208 {cdata 1} 2209 {cdata 2} 2210 {cdata 3} 2212 That is, four individual caseless substring matches would be 2213 performed, one each for {cdata 0}, {cdata 1}, {cdata 2}, and {cdata 2214 3}. 2216 9.4.2 Example: successful DAV:principal-property-search REPORT 2218 In this example, the client requests the principal URLs of all users 2219 whose DAV:displayname property contains the substring "doE" and whose 2220 http://BigCorp.com/ns/title property (that is, their professional 2221 title) contains "sales". In addition, the client requests five 2222 properties to be returned with the matching principals: 2224 In the DAV: namespace: displayname 2225 In the http://www.BigCorp.com/ns/ namespace: department, phone, 2226 office, salary 2228 The response shows that two principal resources meet the search 2229 specification, "John Doe" and "Zygdoebert Smith". The property 2230 "salary" in namespace "http://www.BigCorp.com/ns/" is not returned, 2231 since the principal making the request does not have sufficient 2232 access permissions to read this property. 2234 >> Request << 2236 REPORT /users/ HTTP/1.1 2237 Host: www.BigCorp.com 2238 Content-Type: text/xml; charset=utf-8 2239 Content-Length: xxxx 2241 2242 2243 2244 2245 2246 2247 doE 2248 2249 2250 2251 2252 2253 sales 2254 2255 2256 2257 2258 2259 2260 2261 2262 2264 >> Response << 2266 HTTP/1.1 207 Multi-Status 2267 Content-Type: text/xml; charset=utf-8 2268 Content-Length: xxxx 2270 2271 2272 2273 http://www.BigCorp.com/users/jdoe 2274 2275 2276 John Doe 2277 Widget Sales 2278 234-4567 2279 209 2280 2281 HTTP/1.1 200 OK 2282 2283 2284 2285 2286 2287 HTTP/1.1 403 Forbidden 2288 2289 2290 2291 http://www.BigCorp.com/users/zsmith 2292 2293 2294 Zygdoebert Smith 2295 Gadget Sales 2296 234-7654 2297 114 2298 2299 HTTP/1.1 200 OK 2300 2301 2302 2303 2304 2305 HTTP/1.1 403 Forbidden 2306 2307 2308 2310 9.4.3 Example: Unsuccessful DAV:principal-property-search REPORT 2312 In this example, the client requests a search on the non-searchable 2313 property "phone" in the namespace "http://www.BigCorp.com/ns/". The 2314 response is a 403 (Forbidden), with a response body containing the 2315 XML element DAV:non-searchable-property listing the non-searchable 2316 property. 2318 >> Request << 2320 REPORT /users/ HTTP/1.1 2321 Host: www.BigCorp.com 2322 Content-Type: text/xml; charset=utf-8 2323 Content-Length: xxxx 2325 2326 2327 2328 2329 2330 2331 232 2332 2333 2335 >> Response << 2337 HTTP/1.1 403 FORBIDDEN 2338 Content-Type: text/xml; charset=utf-8 2339 Content-Length: xxxx 2340 2341 2342 2343 2344 2345 2347 9.5 DAV:principal-search-property-set REPORT 2349 The DAV:principal-search-property-set REPORT identifies those 2350 properties that may be searched using the DAV:principal-property- 2351 search REPORT (defined in Section 9.4). The DAV:principal-collection- 2352 set property of the resource identified by the Request-URI specifies 2353 the scope of the DAV:principal-search-property-set REPORT, as 2354 follows: 2356 - All principal and collection principal resources identified in 2357 DAV:principal-collection-set are in scope 2358 - All principal and collection principal resources that are 2359 descendents of a collection principal resource identified in 2360 DAV:principal collection-set are also in scope. 2362 Principals and collection principals within this scope are examined 2363 for searchable properties. 2365 Servers MUST support the DAV:principal-search-property-set REPORT on 2366 all principal collections identified in the value of a DAV:principal- 2367 collection-set property. 2369 An access control protocol user agent could use the results of the 2370 DAV:principal-search-property-set REPORT to present a query interface 2371 to the user for retrieving principals. 2373 Marshalling: 2375 The request body MUST be an empty DAV:principal-search-property-set 2376 XML element. 2378 The response body MUST be a DAV:principal-search-property-set XML 2379 element, containing a DAV:principal-search-property XML element for 2380 each property that may be searched with the DAV:principal-property- 2381 search REPORT. A server MAY limit its response to just a subset of 2382 the searchable properties, such as those likely to be useful to an 2383 interactive access control client. 2385 2388 Each DAV:principal-search-property XML element contains exactly one 2389 searchable property, and a description of the property. 2391 2393 The DAV:prop element contains one principal property on which the 2394 server is able to perform DAV:principal-property-search REPORTs. 2396 prop: see RFC 2518, Section 12.11 2398 The description element is a human-readable description of what 2399 information this property represents. Servers MUST indicate the human 2400 language of the description using the xml:lang attribute and SHOULD 2401 consider the HTTP Accept-Language request header when selecting one 2402 of multiple available languages. 2404 2406 9.5.1 Example: DAV:principal-search-property-set REPORT 2408 In this example, the client determines the set of searchable 2409 principal properties by requesting the DAV:principal-search-property- 2410 set REPORT on the root of the server�s principal URL collection set, 2411 identified by http://www.BigCorp.com/users/. 2413 >> Request << 2415 REPORT /users/ HTTP/1.1 2416 Host: www.BigCorp.com 2417 Content-Type: text/xml; charset="utf-8" 2418 Content-Length: xxx 2419 Accept-Language: en, de 2420 Authorization: BASIC d2FubmFtYWs6cGFzc3dvcmQ= 2422 2423 2425 >> Response << 2427 HTTP/1.1 200 OK 2428 Content-Type: text/xml; charset="utf-8" 2429 Content-Length: xxx 2431 2432 2433 2434 2435 2436 2437 Full name 2438 2439 2440 2441 2442 2443 Job title 2444 2445 2447 10 XML PROCESSING 2449 Implementations of this specification MUST support the XML element 2450 ignore rule, as specified in Section 23.3.2 of [RFC2518], and the XML 2451 Namespace Recommendation [REC-XML-NAMES]. 2453 Note that use of the DAV namespace is reserved for XML elements and 2454 property names defined in a standards-track or Experimental IETF RFC. 2456 11 INTERNATIONALIZATION CONSIDERATIONS 2458 In this specification, the only human-readable content can be found 2459 in the description XML element, found within the DAV:supported- 2460 privilege-set property. This element contains a human-readable 2461 description of the capabilities controlled by a privilege. As a 2462 result, the description element must be capable of representing 2463 descriptions in multiple character sets. Since the description 2464 element is found within a WebDAV property, it is represented on-the- 2465 wire as XML [REC-XML], and hence can leverage XML's language tagging 2466 and character set encoding capabilities. Specifically, XML processors 2467 must, at minimum, be able to read XML elements encoded using the UTF- 2468 8 [UTF-8] encoding of the ISO 10646 multilingual plane. XML examples 2469 in this specification demonstrate use of the charset parameter of the 2470 Content-Type header, as defined in [RFC3023], as well as the XML 2471 "encoding" attribute, which together provide charset identification 2472 information for MIME and XML processors. Furthermore, this 2473 specification requires server implementations to tag description 2474 fields with the xml:lang attribute (see Section 2.12 of [REC-XML]), 2475 which specifies the human language of the description. Additionally, 2476 server implementations should take into account the value of the 2477 Accept-Language HTTP header to determine which description string to 2478 return. 2480 For XML elements other than the description element, it is expected 2481 that implementations will treat the property names, privilege names, 2482 and values as tokens, and convert these tokens into human-readable 2483 text in the user's language and character set when displayed to a 2484 person. Only a generic WebDAV property display utility would display 2485 these values in their raw form to a human user. 2487 For error reporting, we follow the convention of HTTP/1.1 status 2488 codes, including with each status code a short, English description 2489 of the code (e.g., 200 (OK)). While the possibility exists that a 2490 poorly crafted user agent would display this message to a user, 2491 internationalized applications will ignore this message, and display 2492 an appropriate message in the user's language and character set. 2494 Further internationalization considerations for this protocol are 2495 described in the WebDAV Distributed Authoring protocol specification 2496 [RFC2518]. 2498 12 SECURITY CONSIDERATIONS 2500 Applications and users of this access control protocol should be 2501 aware of several security considerations, detailed below. In addition 2502 to the discussion in this document, the security considerations 2503 detailed in the HTTP/1.1 specification [RFC2616], the WebDAV 2504 Distributed Authoring Protocol specification [RFC2518], and the XML 2505 Media Types specification [RFC3023] should be considered in a 2506 security analysis of this protocol. 2508 12.1 Increased Risk of Compromised Users 2510 In the absence of a mechanism for remotely manipulating access 2511 control lists, if a single user's authentication credentials are 2512 compromised, only those resources for which the user has access 2513 permission can be read, modified, moved, or deleted. With the 2514 introduction of this access control protocol, if a single compromised 2515 user has the ability to change ACLs for a broad range of other users 2516 (e.g., a super-user), the number of resources that could be altered 2517 by a single compromised user increases. This risk can be mitigated by 2518 limiting the number of people who have write-acl privileges across a 2519 broad range of resources. 2521 12.2 Risks of the DAV:read-acl and DAV:current-user-privilege-set 2522 Privileges 2524 The ability to read the access privileges (stored in the DAV:acl 2525 property), or the privileges permitted the currently authenticated 2526 user (stored in the DAV:current-user-privilege-set property) on a 2527 resource may seem innocuous, since reading an ACL cannot possibly 2528 affect the resource's state. However, if all resources have world- 2529 readable ACLs, it is possible to perform an exhaustive search for 2530 those resources that have inadvertently left themselves in a 2531 vulnerable state, such as being world-writeable. In particular, the 2532 property retrieval method PROPFIND, executed with Depth infinity on 2533 an entire hierarchy, is a very efficient way to retrieve the DAV:acl 2534 or DAV:current-user-privilege-set properties. Once found, this 2535 vulnerability can be exploited by a denial of service attack in which 2536 the open resource is repeatedly overwritten. Alternately, writeable 2537 resources can be modified in undesirable ways. 2539 To reduce this risk, read-acl privileges should not be granted to 2540 unauthenticated principals, and restrictions on read-acl and read- 2541 current-user-privilege-set privileges for authenticated principals 2542 should be carefully analyzed when deploying this protocol. Access to 2543 the current-user-privilege-set property will involve a tradeoff of 2544 usability versus security. When the current-user-privilege-set is 2545 visible, user interfaces are expected to provide enhanced information 2546 concerning permitted and restricted operations, yet this information 2547 may also indicate a vulnerability that could be exploited. Deployment 2548 of this protocol will need to evaluate this tradeoff in light of the 2549 requirements of the deployment environment. 2551 12.3 No Foreknowledge of Initial ACL 2553 In an effort to reduce protocol complexity, this protocol 2554 specification intentionally does not address the issue of how to 2555 manage or discover the initial ACL that is placed upon a resource 2556 when it is created. The only way to discover the initial ACL is to 2557 create a new resource, then retrieve the value of the DAV:acl 2558 property. This assumes the principal creating the resource also has 2559 been granted the DAV:read-acl privilege. 2561 As a result, it is possible that a principal could create a resource, 2562 and then discover that its ACL grants privileges that are 2563 undesirable. Furthermore, this protocol makes it possible (though 2564 unlikely) that the creating principal could be unable to modify the 2565 ACL, or even delete the resource. Even when the ACL can be modified, 2566 there will be a short period of time when the resource exists with 2567 the initial ACL before its new ACL can be set. 2569 Several factors mitigate this risk. Human principals are often aware 2570 of the default access permissions in their editing environments and 2571 take this into account when writing information. Furthermore, default 2572 privilege policies are usually very conservative, limiting the 2573 privileges granted by the initial ACL. 2575 13 AUTHENTICATION 2577 Authentication mechanisms defined for use with HTTP and WebDAV also 2578 apply to this WebDAV Access Control Protocol, in particular the Basic 2579 and Digest authentication mechanisms defined in [RFC2617]. 2581 14 IANA CONSIDERATIONS 2583 This document uses the namespace defined by [RFC2518] for XML 2584 elements. All other IANA considerations mentioned in [RFC2518] also 2585 applicable to WebDAV ACL. 2587 15 INTELLECTUAL PROPERTY 2589 The following notice is copied from RFC 2026, section 10.4, and 2590 describes the position of the IETF concerning intellectual property 2591 claims made against this document. 2593 The IETF takes no position regarding the validity or scope of any 2594 intellectual property or other rights that might be claimed to 2595 pertain to the implementation or use other technology described in 2596 this document or the extent to which any license under such rights 2597 might or might not be available; neither does it represent that it 2598 has made any effort to identify any such rights. Information on the 2599 IETF's procedures with respect to rights in standards-track and 2600 standards-related documentation can be found in BCP-11. Copies of 2601 claims of rights made available for publication and any assurances of 2602 licenses to be made available, or the result of an attempt made to 2603 obtain a general license or permission for the use of such 2604 proprietary rights by implementers or users of this specification can 2605 be obtained from the IETF Secretariat. 2607 The IETF invites any interested party to bring to its attention any 2608 copyrights, patents or patent applications, or other proprietary 2609 rights that may cover technology that may be required to practice 2610 this standard. Please address the information to the IETF Executive 2611 Director. 2613 16 ACKNOWLEDGEMENTS 2615 This protocol is the collaborative product of the WebDAV ACL design 2616 team: Bernard Chester, Geoff Clemm, Anne Hopkins, Barry Lind, Sean 2617 Lyndersay, Eric Sedlar, Greg Stein, and Jim Whitehead. The authors 2618 are grateful for the detailed review and comments provided by Jim 2619 Amsden, Gino Basso, Murthy Chintalapati, Dennis Hamilton, Laurie 2620 Harper, Ron Jacobs, Chris Knight, Remy Maucherat, Larry Masinter, 2621 Yaron Goland, Lisa Dusseault, Joe Orton, Stefan Eissing, Julian 2622 Reschke, Keith Wannamaker, Tim Ellison, and Dylan Barrell. We thank 2623 Keith Wannamaker for the initial text of the principal property 2624 search sections. Prior work on WebDAV access control protocols has 2625 been performed by Yaron Goland, Paul Leach, Lisa Dusseault, Howard 2626 Palmer, and Jon Radoff. We would like to acknowledge the foundation 2627 laid for us by the authors of the DeltaV, WebDAV and HTTP protocols 2628 upon which this protocol is layered, and the invaluable feedback from 2629 the WebDAV working group. 2631 17 REFERENCES 2633 17.1 Normative References 2635 [RFC2119] S.Bradner, "Key words for use in RFCs to Indicate 2636 Requirement Levels." RFC 2119, BCP 14, Harvard, March, 1997. 2638 [REC-XML] T. Bray, J. Paoli, C.M. Sperberg-McQueen, "Extensible 2639 Markup Language (XML)." World Wide Web Consortium Recommendation REC- 2640 xml.http://www.w3.org/TR/REC-xml 2642 [REC-XML-NAMES] T. Bray, D. Hollander, A. Layman, �Name Spaces in 2643 XML" World Wide Web Consortium Recommendation REC-xml-names. 2644 http://www.w3.org/TR/REC-xml-names/ 2646 [RFCxxxx] G. Clemm, J. Amsden, T. Ellison, C. Kaler, J. Whitehead, 2647 "Versioning Extensions to WebDAV." RFC xxxx. Rational, IBM, 2648 Microsoft, U.C. Santa Cruz, 2001. 2650 [REC-XML-INFOSET] J. Cowan, R. Tobin, "XML Information Set." World 2651 Wide Web Consortium Recommendation REC-xml-infoset. 2652 http://www.w3.org/TR/xml-infoset/ 2654 [RFC2616] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, L. 2655 Masinter, P. Leach, and T. Berners-Lee, "Hypertext Transfer Protocol 2656 -- HTTP/1.1." RFC 2616. U.C. Irvine, Compaq, Xerox, Microsoft, 2657 MIT/LCS, June, 1999. 2659 [RFC2617] J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. 2660 Leach, A. Luotonen, L. Stewart, "HTTP Authentication: Basic and 2661 Digest Access Authentication." RFC 2617. Northwestern University, 2662 Verisign, AbiSource, Agranat, Microsoft, Netscape, Open Market, June, 2663 1999. 2665 [RFC2518] Y. Goland, E. Whitehead, A. Faizi, S. R. Carter, D. Jensen, 2666 "HTTP Extensions for Distributed Authoring -- WEBDAV." RFC 2518. 2667 Microsoft, U.C. Irvine, Netscape, Novell, February, 1999. 2669 [RFC2368] P. Hoffman, L. Masinter, J. Zawinski, "The mailto URL 2670 scheme." RFC 2368. Internet Mail Consortium, Xerox, Netscape, July, 2671 1998. 2673 [RFC3023] M. Murata, S. St.Laurent, D. Kohn, "XML Media Types." RFC 2674 3023. IBM Tokyo Research Laboratory, simonstl.com, Skymoon Ventures, 2675 January, 2001. 2677 [UTF-8] F. Yergeau, "UTF-8, a transformation format of Unicode and 2678 ISO 10646." RFC 2279. Alis Technologies. January, 1998. 2680 17.2 Informational References 2682 [RFC2026] S.Bradner, "The Internet Standards Process � Revision 3." 2683 RFC 2026, BCP 9. Harvard, October, 1996. 2685 [RFC2255] T. Howes, M. Smith, "The LDAP URL Format." RFC 2255. 2686 Netscape, December, 1997. 2688 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 2689 Protocol (v3)." RFC 2251. Critical Angle, Netscape, Isode, December, 2690 1997. 2692 [CaseMap] M. Davis, "Case Mappings", Unicode Technical Report #21, 2693 2695 18 AUTHORS' ADDRESSES 2697 Geoffrey Clemm 2698 Rational Software 2699 20 Maguire Road 2700 Lexington, MA 02421 2701 Email: geoffrey.clemm@rational.com 2703 Anne Hopkins 2704 Microsoft Corporation 2705 One Microsoft Way 2706 Redmond, WA 98052 2707 Email: annehop@microsoft.com 2709 Eric Sedlar 2710 Oracle Corporation 2711 500 Oracle Parkway 2712 Redwood Shores, CA 94065 2713 Email: esedlar@us.oracle.com 2715 Jim Whitehead 2716 U.C. Santa Cruz 2717 Dept. of Computer Science 2718 Baskin Engineering 2719 1156 High Street 2720 Santa Cruz, CA 95064 2721 Email: ejw@cse.ucsc.edu 2722 19 APPENDICIES 2724 19.1 WebDAV XML Document Type Definition Addendum 2726 All XML elements defined in this Document Type Definition (DTD) 2727 belong to the DAV namespace. This DTD should be viewed as an addendum 2728 to the DTD provided in [RFC2518], section 23.1. 2730 2732 2733 2734 2735 2736 2737 2739 2741 2743 2744 2746 2748 2750 2751 2753 2755 2756 2759 2760 2761 2762 2764 2766 2767 2769 2771 2772 2776 2777 2778 2779 2780 2781 2783 2784 2785 2787 2789 2791 2793 2795 2797 2800 2803 2804 2805 2807 2808 2810 2811 2812 2814 2818 2820 2821 2822 2823 2825 2827 2828 ANY value: a sequence of one or more elements, with at most one 2829 DAV:prop element. 2831 2832 2833 ANY value: an element whose value identifies a property. The 2834 expectation is the value of the named property typically contains 2835 an href element that contains the URI of a principal 2837 2839 2840 2841 2842 2844 2846 2848 20 NOTE TO RFC EDITOR 2850 As of the writing of this specification, the DeltaV protocol, 2851 described in draft-ietf-deltav-versioning-20, has been approved by 2852 the IESG, but not yet published as an RFC. Within this specification, 2853 the DeltaV protocol is referenced as [RFCxxxx]. These references need 2854 to be replaced with the actual RFC number. As well, the citation in 2855 Section 17.1 also needs to be updated with the correct RFC number, 2856 and the month of issue.