INTERNET-DRAFT P. J. Leach Expires: April 1998 Y. Y. Goland Standards Track Microsoft Corporation WebDAV Working Group November 10, 1997 WebDAV ACL Protocol draft-ietf-webdav-acl-00.txt Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Abstract This memo specifies the format and manipulation mechanisms for access control lists (ACLs) for WebDAV objects. Contents Status of this Memo................................................1 Abstract...........................................................1 Contents...........................................................1 1. Introduction....................................................2 2. Principals Identifiers..........................................2 3. Granting and Denying Rights.....................................3 4. ACL Inheritance.................................................4 5. Properties and ACLs.............................................4 6. Rights Definitions..............................................5 7. Default Principal Types.........................................7 8. ACL Method......................................................7 9. Examples.......................................................11 10.Authors' Addresses.............................................13 11.Bibliography...................................................14 Leach and Goland [Page 1] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 1. Introduction The basic model for access control, informally expressed, is that who you are determines how you can access a resource. The "who you are" is defined by a principal identifier; users, client software, servers and groups of the previous have principal identifiers. The "how" is determined by an "access control list" (ACL) associated with a resource. An ACL contains Access Control Elements (ACE). An ACE specifies a set of principals, a set of granted rights, and a set of denied rights. Rights may be generic, such as "read", "write", or "delete", or they might be specific to the kind of resource protected by that ACL, such as (perhaps) "send-to", "unsubscribe", and "administer" for mailing lists. When a resource is created it inherits a set of default ACL properties from a designated resource, referred to as an ACL source. The inheritance can be "static", so that subsequent changes to the ACL source do not effect the new resources ACL properties; or it can be "dynamic", so that subsequent changes are reflected in the new resource's ACL properties. Properties on a resource, by default, dynamically inherit from the ACL on the resource. In other words, the resource is the ACL source for the properties. However individual properties can be given their own ACL. 2. Principals Identifiers A principal identifier can identify a single principal or a compound principal. A single principal identifier refers to a single principal, such as a person or a program. A compound principal identifier specifies one or more principals. A compound principal may not necessarily just be a list of other principals. It may in fact be a program that accepts a principal identifier as input and output true or false to indicate membership. This specification relies upon the underlying authentication mechanism(s) to provide the syntax of principal identifiers. Thus, for the purposes of this specification, principal identifiers are opaque. Leach and Goland [Page 2] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 3. Granting and Denying Rights An ACL can both grant and deny rights. The reason both types of grants are required is because of compound principals. The consequence of the existence of compound principals is that there are times when a compound principal may be granted a right but a particular member of the compound principal may need to be denied access. In order to make this possible an ACL must be able to list principals both allowed and denied a right. By default all rights for a principal MUST be denied. Rights MAY only be granted to a principal by an explicit listing of that principal in a "grant" section of an ACL. Additionally it is possible for access rights to collide in scope. For example, a container may have an access right which specifies the ability of principals to delete the children of that container. This would affect a principal's ability to use the DELETE method. However a particular internal child may have granted access rights to DELETE. As such, the two rights could collide. The following rules, processed in order, MUST be used to resolve scope conflicts between rights. 1) In a conflict between a right granted by a parent and a right granted by a child, the right specified by the child MUST override. 2) In a conflict between a right granted or denied to a compound principal and a right granted or denied to a member of the compound principal, the reference to the member of the compound principal MUST override. Note that rule 2 is conceptually identical to rule 1. The concept represented by rules 1 and 2, stated generally, is that a specific references always overrides a more general reference. 3.1. Examples The following examples demonstrate a situation where the specified conflict resolution rule would be applied. 3.1.1. Rule 1 A resource specifies that principal A is granted the right to delete the resource. A property on the resource specifies that principal A is denied the right to delete the property. The conflict is resolved by rule 1, the resource is the parent and the property is the child. As such the child's declaration overrides and principal A is denied the right to delete the resource. Leach and Goland [Page 3] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 Note, however, that if other properties do not deny principal A the right to delete them then principal A could delete all properties but the one mentioned above and could PUT an empty body to the resource. However it could not successfully execute a DELETE on the resource, as this would have the effect of deleting the property along with the resource. 3.1.2. Rule 2 A resource specifies that principal A is denied the read right. The same resource also specifies that principal B is granted the read right. Principal A, however, is a compound principal of which Principal B is a member. Rule 1 does not apply because the rights in question are defined on the same resource. The conflict is resolved by rule 2 as the conflict is between a compound principal and one of its members. In that case principal B has the right to read the resource. 4. ACL Inheritance When a new resource is created it may inherit its ACL from its containing resource. If no inheritance method is specified then the resource has no ACL. Note, however, that the owner value is automatically set when a resource is created, so even without inheritance, there will always be an owner. An inherited ACL MUST be applied to the resource before it is available for manipulation. Thus, if inheritance is used, the resource will never be in a state where it does not have access control protection. Inheritance can either be static or dynamic. Static inheritance means that the ACL specified by the parent will be used to define the ACL for the child. Any subsequent changes made to the parent will not cause the child's ACL to be altered. Dynamic inheritance means that the ACL specified by the parent is used to define the ACL for the child but any changes on the parent's ACL MUST automatically be made to any inheriting children. The child is still allowed to define its own ACL values that MUST override any conflicting inherited ACL. 5. Properties and ACLs Properties MAY have their own ACL independent of the associated resource. By default a property's ACL MUST be dynamically inherited from the associated resource. Note that properties can only inherit from their associated resource. It is legal for a property to carry a setting for what sort of inheritance its children will have. Currently this value has no Leach and Goland [Page 4] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 meaning as properties can not have children, but it is expected in the future that hierarchical properties will be adopted, so this setting will then have meaning. For now compliant resources MUST record this value but do not have to do anything with it. For purposes of applying scoping conflict resolution rules the resource is the parent and the property is the child. Compliant resources are not required to support setting ACLs directly on properties. 6. Rights Definitions The following define a variety of rights. A compliant resource MUST support all of the rights contained herein. 6.1. all Right Name: all Namespace: http://www.ietf.org/standards/acl/ Purpose: The all right provides all rights. Values: None Description: In a conflict between the "all" right and other rights, the "all" right is considered a parent and the other rights a "child." Thus one ACE could provide the ALL right for a particular principal but another ACE in the same ACL could deny the same principal a particular right. The conflict would be resolved by denying the specified principal the more specific right. 6.2. read Right Name: read Namespace: http://www.ietf.org/standards/acl/ Purpose: The read right provides and restricts access to information regarding the state of the resource, including the resource's properties. Effected methods are GET, INDEX, and PROPFIND. OPTIONS is not covered by a Read ACL as it reflects capabilities rather than state. Values: None 6.3. write Right Name: write Namespace: http://www.ietf.org/standards/acl/ Purpose: The Write right affects the same methods as the Write Lock. Please refer to [WEBDAV] section 5.3 for the list of affected methods. Note however, that a write lock is a different mechanism than a write access change, although they affect the same methods, they have independent methods to set them and independent error codes. Values: None Leach and Goland [Page 5] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 6.4. delete Right Name: delete Namespace: http://www.ietf.org/standards/acl/ Purpose: The delete right controls access to the DELETE method. This method does not affect the ability to remove properties. Values: None 6.5. createchild Right Name: createchild Namespace: http://www.ietf.org/standards/acl/ Purpose: This right controls the ability to PUT internal members of a collection and ADDREF external members of a collection. This ACL has no affect if set on non-collections. Values: None 6.6. deletechild Right Name: deletechild Namespace: http://www.ietf.org/standards/acl/ Purpose: The deletechild right controls the ability to the DELETE internal members of a collection and DELREF external members of a collection. This ACL has no affect if set on non-collections. Values: None 6.7. writeowner Right Name: writeowner Namespace: http://www.ietf.org/standards/acl/ Purpose: The writeowner right controls the ability to change the value of the owner right. Values: None 6.8. readacl Right Name: readacl Namespace: http://www.ietf.org/standards/acl/ Purpose: The readacl right controls the ability to read the ACL property. Values: None 6.9. writeacl Right Name: writeacl Namespace: http://www.ietf.org/standards/acl/ Purpose: The writeacl right controls the ability to alter the ACL property. Values: None Leach and Goland [Page 6] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 7. Default Principal Types The following two XML elements are defined principal types. 7.1. allprincipals XML Element Name: allprincipals Namespace: http://www.ietf.org/standards/acl/ Purpose: The allprincipals XML element represents all principals. It is used to specify rights belonging to all principals, regardless of authentication. Values: None 7.2. allauthprincipals XML Element Name: allauthprincipals Namespace: http://www.ietf.org/standards/acl/ Purpose: The allauthprincipals XML element represents all authenticated principals. It is used to specify rights belonging to all authenticated principals. Values: None 8. ACL Method The ACL Method serves two distinct purposes. Its request body is used to define alterations to the ACL of the resource and its properties. The response contains the ACL for the associated resource and its properties. The Request-URI of the ACL method identifies the resource whose ACL information is to be retrieved and possibly altered. Change requests through the ACL method MUST be atomic, additionally changes are all or nothing. If any part of the change request fails then all changes MUST fail. 8.1. Request The request may contain up to four XML elements, owner, aclinheritance, and ACL. The presence of an element, except as otherwise specified, in the request body causes the associated value to change. The presence of an empty ACL causes all ACEs in the ACL, including ACEs for associated properties, to be deleted. If an ACE is specified in a request it completely replaces the ACE currently use for the same principal, if it exists. If an ACE is submitted with empty grant and deny lists then the ACE is deleted. It is a syntax error for two ACEs to reference the same principal. Additionally, although an ACE can be submitted which references multiple principals, this is primarily a convenience feature. Leach and Goland [Page 7] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 Strictly speaking, what the user has done is specify an ACE for every principal specified. The same logic applies to results that aggregate principals into a single ACE. It is illegal to delete any value, ACE, owner, aclinheritance, etc. with a redundant value. For example, if one ACE grants all principals read rights and another ACE grants a single principal read rights, both ACEs MUST be maintained. The reason being that in the future all principals may have their read rights removed but the single principal will retain the read right because the more specific ACE will override the more general ACE. Additionally if the currently inherited value of owner is "someuser" and the principal explicitly requests that the owner by set to "someuser", the information MUST be recorded on the resource. That way if owner on the source ACL is changed, the proper value as requested by the client will remain on the inheriting ACL. An empty request body will cause no change to the ACL or associated values. 8.2. Response If the request body was empty or if the changes were successful a 200 Success response MUST be returned with a response body containing the owner, aclinheritance, and the acl XML elements with values for all properties. [Ed Note - I am not dealing with error conditions yet as the error reporting format is going to have to be pretty complex and I want to get buy off on the ACL model and the request format before I write up a couple of pages on how to do errors for that format.] 8.3. acl XML element Name: acl Namespace: http://www.ietf.org/standards/acl/ Purpose: Defines an ACL. Parent: Any Values= (inheritance [owner] [aclinheritance] *ACE *property) Description: An empty ACL element will delete all ACEs contained in an ACL, including the ACEs of any properties. Note, however, that there MUST always be an ACL value defined on a resource, even if it is empty. Leach and Goland [Page 8] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 8.4. owner XML Element Name: owner Namespace: http://www.ietf.org/standards/acl/ Purpose: Specifies the owner of the resource. Parent= acl Values= Principal Description: The owner XML element specifies the principal who owns the resource. The default value for owner MUST be the principal who created the resource. The owner always retains the right to alter the ACL. So, for example, an owner who was not granted the right to read the resource could not read the resource. However the owner could alter the ACL so as to grant the read right to themselves. A principal MUST have the writeowner right to change the owner property's value. An empty Owner element submitted in a request will not cause a change in the Onwer value. Owner MUST always have a value. All compliant resources MUST support the owner value. 8.5. aclinheritance XML Element Name: aclinheritance Namespace: http://www.ietf.org/standards/acl/ Parent= acl Purpose: The aclinheritance XML element identifies the type of inheritance to be used with children of the associated resource. The AclInheritance value MUST default to Dynamic. An empty AclInheritance submitted in a request will not cause a change in the AclInheritance value. This element has no meaning on non- collections. However, collections MUST provide this property. Values= ("Dynamic" | "Static" | "None" | Extension) ;Extension is defined, somewhere in DAV. URL is defined, someplace, somewhere. Description: Although this element has no meaning when defined on a property, resources MUST record its value. 8.6. inheritance XML Element Name: inheritance Namespace: http://www.ietf.org/standards/acl/ Purpose: Defines the inheritance used for a particular ACL. Parent: acl Values= ("Dynamic" | "None" | Extension) Description: Specifies if the ACL is inheriting its value dynamically or not at all. Static is not an option since static inheritance can only occur when the ACL was created and so was controlled by the ACL source. Leach and Goland [Page 9] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 8.7. principal XML Element Name: principal Namespace: http://www.ietf.org/standards/acl/ Purpose: To identify a principal. Parent: any Values= *cdata 8.8. ace XML Element Name: ace Namespace: http://www.ietf.org/standards/acl/ Purpose: Contains access right information associated with one or more principals. Parent: acl Values= Principal Allow Deny Description: A principal MUST NOT be directly referred to in more than one ACE on a resource. That is, each principal has a particular ACE which specifies all of its directly granted rights. Thus specifying two ACEs which directly reference the same principal in a request is a syntax error. 8.9. grant XML Element Name: grant Namespace: http://www.ietf.org/standards/acl/ Purpose: Identifies the rights the associated principals are granted. Parent: ACE Values: Right Identifiers 8.10. deny XML Element Name: deny Namespace: http://www.ietf.org/standards/acl/ Purpose: Identifies the rights the associated principals are denied. Parent: ACE Values: Right Identifiers 8.11. property XML Element Name: property Namespace: http://www.ietf.org/standards/acl/ Purpose: Provides ACL for properties. Parent: ACL Values= Prop ACL Description: The properties in the Prop XML element MUST be empty. Leach and Goland [Page 10] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 9. Examples 9.1. Example 1 - Retrieving ACL information ACL /top/container/ HTTP/1.1 Host: www.foo.bar Content-Length: xxxx Content-Type: text/xml HTTP/1.1 200 Success Content-Type: text/xml Content-Length: xxxxx dynamic someonesomewhere domain/joebob dynamic blah domain/joebob dynamic The request was empty so no changes will be made, rather the response will just contain all the relevant values. The resource gets its own ACL dynamically from its parent, top. However this Leach and Goland [Page 11] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 resource does override the inherited ACL. Specifically, it defines its owner, someonesomewhere, rather than inheriting it. However, the absence of an aclinheritance element indicates that the resource inherits that value. Additional the principal domain/joebob is denied all rights. So regardless of what rights domain/joebob may have been granted in top's ACL, all those rights are denied in relation to top/container. While the ACL for creationdate is also inherited it has its own owner, blah, and has an additional ACE for joebob. All the rest of the properties have their ACLs inherited from the resource. Therefore the denial of all rights to domain/joebob would also apply to the resource's properties but creationdate.. 9.2. Example 2 - Setting ACLs ACL /top/container.html HTTP/1.1 Host: www.foo.com Content-Type: text/xml Content-Length: xxxx none domain/joebob Leach and Goland [Page 12] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 HTTP/1.1 200 Success Content-Type: text/xml Content-Length: xxxxx dynamic someonesomewhere none domain/joebob dynamic blah dynamic This example assumes the state left from example 1. In the request the user asks that the aclinheritance value be set to none and that the ACE on the property creationdate for the principal domain/joebob be removed. Even if the inherited aclinheritance value is none, the resource MUST still record the redundant value as the value on the source ACL may change. 10. Authors' Addresses Paul J. Leach Yaron Y. Goland Microsoft 1 Microsoft Way Redmond, WA 98052 Phone: (425)936-4765 Email: {paulle, yarong}@microsoft.com Leach and Goland [Page 13] INTERNET-DRAFT WEBDav ACL Protocol November 10, 1997 11. Bibliography [RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners- Lee, 'Hypertext Transfer Protocol -- HTTP/1.1', RFC 2068, January 1997, [WebDAV] Y. Goland, E. J. Whitehead, Jr., Asad Faizi, Stephen R. Carter, Del Jensen 'Extensions for Distributed Authoring and Versioning on the World Wide Web -- WEBDAV', October 1997, WORK IN PROGRESS, [XML] W3C, 'Extensible Markup Language - Part1. Syntax', March 1997 Leach and Goland [Page 14]