Network Working Group Marius Aamodt Eriksen Internet Draft J. Bruce Fields Document:draft-ietf-nfsv4-acl-mapping-02.txt October 2004draft-ietf-nfsv4-acl-mapping-03.txt February 2005 Mapping Between NFSv4 and Posix Draft ACLs Status of this Memo By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be dis- closed, in accordance with RFC 3668. This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 mate- rial or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. "Copyright (C) The Internet Society (2002-2004). All Rights Reserved." Abstract NFS version 4 [rfc3530] (NFSv4) specifies a flavor of Access Control Lists (ACLs) resembling Windows NT ACLs. A number of operating sys- tems use a different flavor of ACL based on a withdrawn POSIX draft. NFSv4 clients and servers on such operating systems may wish to map Mapping NFSv4 ACLsOctober 2004February 2005 between NFSv4 ACLs and their native ACLs. To this end, we describe a mapping from POSIX draft ACLs to a subset of NFSv4 ACLs. Mapping NFSv4 ACLsOctober 2004February 2005 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. NFSv4 ACLs . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. POSIX ACLs . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. MappingPosixPOSIX ACLs to NFSv4 ACLs . . . . . . . . . . . . . . 6 5. Using the Mapping in NFSv4 Implementations . . . . . . . . .89 6. Security Considerations . . . . . . . . . . . . . . . . .1011 7. Bibliography . . . . . . . . . . . . . . . . . . . . . . .1112 8. Author's Address . . . . . . . . . . . . . . . . . . . . .1213 9. Copyright . . . . . . . . . . . . . . . . . . . . . . . .1213 Mapping NFSv4 ACLsOctober 2004February 2005 1. Introduction Access Control Lists (ACLs) are used to specify fine-grained access rights to file system objects. An ACLconsists ofis anumberlist of Access Control Entries (ACEs), each specifyingsome level of access foranentity. The entity may be a user, a group, or a specialentity (such as"everyone"). The level of access is described using an access mask, which is a bitmask with each bit corresponding toatypeuser) and some level of access(such as "read" or "append").for that entity. In the following sections we describe two ACL models: NFSv4 ACLs, and ACLs based on a withdrawn POSIXdraft, which wedraft. We will refer to the latter as "POSIX ACLs". Since NFSv4 ACLs aremuch finer-grainedmore fine-grained than POSIX ACLs, it is not possible in general to map an arbitrary NFSv4 ACL to a POSIX ACL with the same semantics.It does, however, turn out to beHowever, it is possible to map any POSIX ACL to a NFSv4 ACLthat haswith nearlyiden- ticalidentical semantics. We will describe such a mapping, and discusshow it might be usedits use in NFSv4clientclients andserver implementations.servers. 2. NFSv4 ACLs An NFSv4 ACL is an ordered sequence of ACEs, each having an entity, a type, some flags, and an access mask. The entity may be the name of a user or group, or mayalsobe one of a small set of special entities. Among the special entities are"OWNER""OWNER@" (the current owner of the file),"GROUP""GROUP@" (the groupassociatedassoci- ated with the file), and"EVERYONE". The access mask includes bits for access types that are more fine- grained than the traditional "read", "write", and "execute" permis- sions used in UNIX mode bits."EVERYONE@". The type may be ALLOW or DENY. (AUDIT or ALARM are also allowed, but they are not relevant to our discussion). TheNFSv4 ACL permission-checking algorithm is straightforward. Given an ACL and a requestor asking for a set of permissions speci- fied by anaccessmask: 1) Walk through the list of ACEs from themask has 14 separate bits, including bits to control read, write, execute, append, ACLin order. 2) Ignore any ACEmodification, file owner modification, etc.; consult [rfc3530] forwith an entity not matching requestor. Mapping NFSv4 ACLs October 2004 3) Process all ACEs until all the bits intherequested access mask have been ALLOWed by an ALLOW ace with that bit set. Once a par- ticular bit has been ALLOWed by an ACE, it is no longer considered in further processing. 4) If a bit infull list. Of therequested access maskflags, four are relevant here. The ACE4_IDENTIFIER_GROUP flag isDENYed (whileused to indicate thatbit is still under consideration),therequestentity name isdenied. 5) If all bits have been ALLOWed,theaccess is granted. Otherwise behavior is undefined. There are also a numbername offlags that can be applied to an NFSv4 ACE. Three flags that we will need to use in the following discussion apply to ACEs inadirectory ACL. They are: ACE4_DIREC- TORY_INHERIT_ACE, whichgroup. The other three concern inheritance: ACE4_DIRECTORY_INHERIT_ACE indicates that the ACE should be added to new subdirectories of the directory;ACE4_FILE_INHERIT_ACE, whichACE4_FILE_INHERIT_ACE does the same for new files; andACE4_INHERIT_ONLY, whichACE4_INHERIT_ONLY indicates that the ACE should be ignored when determining access to the directory itself.We refer theThe NFSv4 ACL permission-checking algorithm is straightforward. Assume a a requester asks for access, as specified by a single bit in Mapping NFSv4 ACLs February 2005 the access bitmask. We allow the access if the first ACE in the ACL that matches the requester and that has that bit set is an ALLOW ACE, and we deny the access if the first such ACE is a DENY ACE. If no matching ACE has the bit in question set, behaviour is undefined. If an access mask consisting of more than one bit is requested, it suc- ceeds if and only if each bit in the mask is allowed. We refer the reader to [rfc3530] for further details. 3. POSIX ACLs A number of operatingsystems, including Linux and FreeBSD,systems implement ACLs based on the withdrawn POSIX 1003.1e/1003.2c Draft Standard 17 [posixacl]. We will refer to such ACLs as "POSIX ACLs". POSIX ACLs use access masks with only the traditional "read", "write", and "execute" bits. Each ACE in a POSIX ACL is one of five types: ACL_USER_OBJ, ACL_USER, ACL_GROUP_OBJ, ACL_GROUP, ACL_MASK, and ACL_OTHER. Each ACL_USER ACE has a uid associated with it, and each ACL_GROUP ACE has a gid associated with it. Every POSIX ACL must have exactly one ACL_USER_OBJ, ACL_GROUP, and ACL_OTHER ACE, and at most one ACL_MASKace.ACE. The ACL_MASKaceACE is required if the ACL has any ACL_USER or ACL_GROUPaces.ACEs. There may not be two ACL_USERacesACEs with the same uid, and there may not be two ACL_GROUPacesACEs with the same gid. Given a POSIX ACL and arequestorrequester asking for access, permission is determined as follows: 1) If therequestorrequester is the file owner, then allow or deny access depending on whether the ACL_USER_OBJ ACE allows or denies it.Mapping NFSv4 ACLs October 2004Otherwise, 2) if therequestor'srequester's uid matches the uid of one of the ACL_USERACE's,ACEs, then allow or deny access depending on whether the ACL_USER_OBJ ACE allows or denies it. Otherwise, 3) Consider the set of all ACL_GROUPACE'sACEs whose gid therequestorrequester is a member of. Add to that set the ACL_GROUP_OBJ ACE, if therequestorrequester is also a member ofthatthe file's group. Allow access ifone of the ACE'sany ACE in the resulting set allows access. If the set ofmatchingmatch- ing ACEs is nonempty, and none allow access, then deny access. Otherwise, ifnonethe set ofthesematching ACEsmatch,is empty, Mapping NFSv4 ACLs February 2005 4) if the requester's access mask is allowed by the ACL_OTHER ACE, then grant access. Otherwise, deny access.StepsThe above description omits one detail: in steps (2) and(3) have an additional criteria; in addition to check- ing whether the requested access mask is allowed by the access mask in the ACE,(3), the requested bitsalso have tomust bein the access mask ofgranted both by thespecialmatching ACEwithand by the ACL_MASKentity. This allows file owners to specify aACE. The ACL_MASK ACE thus limits the maximumlevel of access allowedpermissions which may be granted by anyother userACL_USER orgroup that has any access to the file system object. In addition to a regular POSIX ACL, a directory inACL_GROUP ACE, or by the ACL_GROUP_OBJ ACE. Each filesystemmayalsohaveassociated with itadefault ACL. This defaultsingle POSIX ACLdoes not affect permissionsassociated with it, used to determine access to that file. Directories, however, may have two ACLs: one, thedirectory itself. Instead, it governs"access ACL", used to determine access to the direc- tory, and one, the "default ACL", used only as the ACLa file system object willto beassigned initially when it isinher- ited by newly createdas a child ofobjects in theparticulardirectory. 4. MappingPosixPOSIX ACLs to NFSv4 ACLsGiven the differences between POSIX and NFSv4 ACLs, any conversion between the two is difficult. However, POSIX ACLs are a subset of NFSv4 ACLs, andWe now describe an algorithm which maps any POSIX ACLcan be emulated withto an NFSv4 ACLusingwith thefollowing mapping.same semantics. First, translate the uid's and gid's on the ACL_USER and ACL_GROUP ACEsmust be translatedinto NFSv4names--a system-dependent process, which, on UNIXnames. This is an implementation-dependent process. It might be done, for example,may be donebylookups to /etc/passwd.consulting a directory service or a password file. Also, the special ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER ACEs must be translated to NFSv4 ACEs with the special entities"OWNER", "GROUP","OWNER@", "GROUP@", and"EVERYONE","EVERYONE@", respectively.TheNext, map each POSIX ACEaccess(excepting any maskis translatedACE) in the given POSIX ACL to an NFSv4 ALLOW ACE with an entity determined asfollows. The read bit ofabove, and with a bitmask determined from the permission bits on the POSIXaccess maskACE as follows: 1) If the read bit istranslated toset in thelogical OR ofPOSIX ACE, then set ACE4_READ_DATA. 2) If theMapping NFSv4 ACLs October 2004 ACE4_READ_DATA and ACE4_READ_NAMED_ATTRS NFSv4 access mask fields. Thewrite bitofis set in the POSIXaccess mask is translated toACE, then set ACE4_WRITE_DATA and ACE4_APPEND_DATA. If thelogical OR ofobject carrying the ACL is a direc- tory, set ACE4_DELETE_CHILD as well. 3) If theACE4_WRITE_DATA, ACE4_WRITE_NAMED_ATTRS and ACE4_APPEND_DATA NFSv4 access mask fields. Theexecute bitofis set in the POSIXaccess maskACE, then set ACE4_EXECUTE. 4) Set ACE4_READ_ACL, ACE4_READ_ATTRIBUTES, and ACE4_SYNCHRONIZE unconditionally. 5) If the ACE istranslated intofor theACE4_EXECUTEspecial "OWNER@" entity, set ACE4_WRITE_ACL andACE4_READ_DATAACE4_WRITE_ATTRIBUTES. Mapping NFSv4acess mask fields. Note thatACLs February 2005 6) Clear all other bits in the NFSv4defines ACE4_READ_DATA, ACE4_WRITE_DATA, and ACE4_APPEND_DATA to be equal to ACE4_LIST_DIRECTORY, ACE4_ADD_FILE, and ACE4_ADD_SUBDIRECTORY, respectively, so this translation makes sense for directories as well. However, on directoriesbitmask. In addition, we set theACE4_DELETE_CHILD field must be includedGROUP flag in each ACE which corresponds to a named group (but not in thetranslationGROUP@ ACE, or any of thePOSIX write bit. In addition toother special entity ACEs). At this point, we've replaced theabove,POSIX ACL by an NFSv4 ACL with theOWNER entity must always be given ACE4_WRITE_ACL and ACE4_WRITE_ATTRIBUTES, and all entities must be given ACE4_READ_ACL, ACE4_READ_ATTRIBUTES, and ACE4_SYNCHRONIZE. The ACE4_DELETE bit should be neither allowed nor denied bysame number of ACEs (ignoring anyACE. The ACE flag field also has a simple translation. If the file system object is a directory, andmask ACE). To emulate the POSIXACE belongsACL permission-checking algorithm, we need toa default ACL, the ACE4_INHERIT_ONLY_ACE, ACE4_DIRECTORY_INHERIT, and ACE4_FILE_INHERIT flags are set inmod- ify theNFSv4 ACE. IfACL further, as follows: 1) Order theentity inACL so that thePOSIXOWNER@ ACErefers to a group, the "ACE4_IDENTIFIER_GROUP" flagisset intheNFSv4 ACE. The POSIX ACL_USER_OBJfirst ACEis also always givenof thepermission bits "ACE4_READ_ACL" and "ACE4_WRITE_ACL." CompletingACL, followed by any user ACEs, followed by themapping reduces to being able to emulate an ACL_MASKGROUP@ ACE, followed by any group ACEs, andcompensate for some differences in the permission-checking algo- rithms ofending finally with thetwo ACL implementations.EVERYONE@ ACE. 2) Thedifference in permission-checking algorithms is handledPOSIX algorithm stops as soon asfol- lows: Every user ACE inthePOSIX ACL maps into 2 NFSv4 ACEs; onerequester matches an ACL_USER_OBJ, ACL_OTHER, or ACL_USER ACE. To emulate this behaviour, add a single DENY ACE after each ALLOW ACEwhich is translatedfor OWNER@, EVERYONE@, or any named user. The DENY ACE should have the same entity and flags asspecified bytheabove scheme, then a comple- mentingcorresponding ALLOW ACE. The bitmask on the DENY ACEwhich is also translated as specified byshould be theabove scheme, withbitwise NOT of theexception thatbitmask on theaccess mask is inverted. NoteALLOW ACE, except that theACL_USER_OBJ ACE is placed first in this list. Every group ACEACE4_WRITE_OWNER and ACE4_DELETE bits should be cleared, and the ACE4_DELETE_CHILD bit should be cleared on non-directories. (Also, in thePOSIXxdr-encoded ACLproduces a similar pair, but instead of beingthat is transmit- ted, all bits not defined in the protocol should be cleared.) 3) Unlike the other ACEs insequence,step 2, all of theALLOWACL_GROUP_OBJ and ACL_GROUP ACEs areall in sequence, fol- lowedconsulted byalltheDENY ACEs. The ACL_GROUP_OBJ ACE is placed firstPOSIX algorithm before deter- mining permissions. However, if the requester matches any one of them, then it must deny any permissions they do not allow. To emulate this behaviour, instead of adding a single DENY after each corresponding GROUP@ or named group ACE, we insert a list of DENY ACEs at the end of the list of GROUP@ and named group ACEs. Each DENY ACE is determined from its corresponding ALLOW ACE exactly as inboth lists. Lastly,step 2, and should occur in the inserted list in the same posi- tion as the corresponding ALLOW ACE occurs in the list of ALLOW ACEs. 4) Finally, we enforce the POSIXACL_OTHERmask ACEis translated intoby prepending each ALLOW ACE for apairnamed user, GROUP@, or named group, with a single DENY ACE whose entity and flags are the same as those for the corre- sponding ALLOW ACE, but whose bitmask is the inverse ofACEsthe bit- mask determined from the mask ACE, with the inverse calculated as described in step 2. As an example, take a POSIX ACL with two named users (u1 and u2) and two named groups (g1 and g2), in addition to theuser ACE case.required ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER, and ACL_MASK ACEs. Such an ACL will map to an NFSv4 ACL of the form Mapping NFSv4 ACLsOctober 2004 With this done,February 2005 ALLOW OWNER@ DENY OWNER@ DENY u1 (mask) ALLOW u1 DENY u1 DENY u2 (mask) ALLOW u2 DENY u2 DENY GROUP@ (mask) ALLOW GROUP@ DENY g1 (mask) ALLOW g1 DENY g2 (mask) ALLOW g2 DENY GROUP@ DENY g1 DENY g2 ALLOW EVERYONE@ DENY EVERYONE@ where theNFSv4 permission-checking algorithm applied toACEs marked with (mask) are those whose bitmask are deter- mined from theresulting NFSv4ACL_MASK ACE as described in step 4 above. In general, a POSIX ACL with m named users and n named groups willproducemap to an NFSv4 ACL with (3*(m + n) + 7) ACLs, unless m and n are both zero, in which case thesameresult will have either 6 or 7 ACLs, depending on whether the original ACL had an ACL_MASK ACE. On directories with default ACLs, we translate the default ACL as above, but set thePOSIX permission-checking algorithm didACE4_INHERIT_ONLY_ACE, ACE4_DIRECTORY_INHERIT_ACE, and ACE4_FILE_INHERIT_ACE flags on every ACE in the resulting ACL. On directories with both default and access ACLs, we translate the two ACLs and then concatenate them. The order of the concatenation is unimportant. There is one extremely minor inaccuracy in this mapping: if a requester that is a member of more than one group listed in theoriginal POSIX ACL. To handleACL requests multiple bits simultaneously, thespecialPOSIXentity ACL_MASK, we slightly modify the above translation: With the exceptionalgorithm requires all of the"OWNER" and "EVERYONE" ACEs, another ACE is prependedbits to be granted simultaneously by one of theACE. The prepended ACE isgroup ACEs. Thus aDENY ACE with the same entityPOSIX ACL such asthe following ALLOW ACE, but withACL_USER_OBJ: --- ACL_GROUP_OBJ: --- g1: r-- g2: -w- ACL_MASK: rw- ACL_OTHER: --- Mapping NFSv4 ACLs February 2005 will prevent apermission mask set to the complementuser that is a member of groups g1 and g2 from opening a file for both read and write, even though read and write would be individually permitted. The NFSv4 ACL permission-checking algorithm has thePOSIX ACL_MASK. This method allows us to preserve the real permission bitsproperty that it permits a group of bits whenever it would permit eachACE should the ACL_MASK be changed.bit individu- ally, so it is impossible to mimic this behaviour with an NFSv4 ACL. 5. Using the Mapping in NFSv4 ImplementationsNote thatExamination of the algorithm described in the previous sectionnot only provides a way to map anyshows that no information is lost; the original POSIX ACLtocan be recon- structed from the mappedto anNFSv4ACL with similar semantics, butACL. Thus we alsoprovides the reverse mappinghave a way to map NFSv4 ACLs to POSIX ACLs in the case where the NFSv4 ACL is precisely in the format of an ACL produced by the algorithm above. The algorithm can therefore be used to implement a subset of the NFSv4 ACL model. This may be useful to NFSv4 clients and servers with preexisting system interfaces that support POSIX ACLs and that cannot be modified to support NFSv4 ACLs. A server, for example, that wishes to export via NFSv4 a filesystem that supports only POSIX ACLs, may use this mapping to answer client requests for existing ACLs by translating POSIX ACLs on its filesys- tem to NFSv4 ACLs to send to the client. However, when a client attempts to set an ACL, the server faces a problem. If the given ACLhappens to beis not in precisely the format of an ACL produced by thismap- ping (as would happen if, for example, the client was performing the same translation),mapping, then the servercan map it to a POSIX ACLmay be required tostore on the filesystem. But for any other NFSv4 ACL, the server shouldreturn an error to avoidany chance of inaccuratelyinaccu- rately representing the client's intention. The correct error to return in this case is NFS4ERR_ATTRNOTSUPP. In the case where a client sets an ACL that leaves certain bits nei- ther allowed nor denied, the server may choose to allow or deny those bits as necessary to make mapping possible. In some situations it may also be possible for a server to map the ACL if it adds a DENY ACE or denies a few additional bits. The language of [rfc3530] allows a server some flexibility inhan- dlinghandling ACLs that it cannot enforce completely accurately, as long as it adheres to "the guiding principle... that the server must not accept ACLs that appear to make [a file] more secure than it really is." Given the choice, as long as the "guiding principle" is not violated, servers should opt to be forgiving. The complexity of the POSIX<->NFSv4 mapping makes difficult the task of generating ACLs Mapping NFSv4 ACLsOctober 2004 It may therefore be possible forFebruary 2005 that will satisfy a serverto accept a wider range of NFSv4 ACLs, as long as itusing the mapping. By making the mapping more forgiving, the server canensuresimplify thatin every case the resulting POSIX ACL denies at least all accesstask, improving interop- erability. Servers that implement theoriginalfull NFSv4ACLprotocol should also handle carefully ACLs that leave bits neither allowed nor denied.The results of such a mapping may, however, be somewhat unexpected, and itIt ispreferable simplybetter torefuse all NFSv4 ACLs that dofall back on some reasonable default rather than to always allow or always deny. A client that, for example, sets ACE4_WRITE_DATA but leaves unspecified ACE4_APPEND_DATA probably does so because its system interfaces are incapable of independently rep- resenting ACE4_APPEND_DATA, notmap accurately, andbecause it intends to deny ACE4_APPEND_DATA. By leaving the bit unspecified, the client leaves the server the opportunity to provideclients with softwarethe reasonable default of set- ting it tohelp gen- erate POSIX-mappable NFSv4 ACLs if necessary. Similarly,match ACE4_WRITE_DATA. Similar issues exist when a clientthatuses NFSv4ACLSACLs to implement user interfaces that only deal in POSIX ACLs. When the client translates ACLsmay handle user requestsreceived from the server toset ACLs easily enough,POSIX ACLs, some flexibility may help interopability, butshould return errors whentheuser requestsclient must take care not to represent any ACLsthat, on consultingas stricter than they really are. Clients that provide access to theserver, turn outfull set of NFSv4 ACLs may also wish tonot be mappableprovide users with utilities to generate and interpret POSIX-mapped NFSv4 ACLs, to aid users working with servers using the POSIXACLs.mapping. Mapping NFSv4 ACLsOctober 2004February 2005 6. Security Considerations Any automatic mapping from one ACL model to another must provide guaranteesthatas to how the mappingpreserves semantics,affects the meaning of ACLs, or risk misleading users about the permissions set on filesystem objects. For thisrea- son, we recommend performingreason, caution is recommended when implementing this map- ping. It is better to return errors than to break any such guaran- tees. Note also that this ACL mappingonly when it can be done accurately,requires mapping between NFSv4 user- names andreturning errors in all other cases.local id's. When the mapping of id's depends on remote services, the method used for the mapping must be at least as secure as the method used to set or get ACLs. Mapping NFSv4 ACLsOctober 2004February 2005 7. Bibliography [rfc3530] Shepler, S. et. al., "NFS version 4 Protocol", April 2003. http://www.ietf.org/rfc/rfc3530.txt [posixacl] IEEE, "IEEE Draft P1003.1e", October 1997 (last draft). http://wt.xpilot.org/publications/posix.1e/download.html Mapping NFSv4 ACLsOctober 2004February 2005 8. Author's Address Address comments related to this memorandum to: marius@umich.edu bfields@umich.edu Marius Aamodt Eriksen J. Bruce Fields University of Michigan / CITI 535 West William Ann Arbor, Michigan E-mail: marius@umich.edu E-mail: bfields@umich.edu 9. Copyright Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFOR- MATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.