Network Working Group                              Marius Aamodt Eriksen
Internet Draft                                           J. Bruce Fields
Document: draft-ietf-nfsv4-acl-mapping-02.txt               October 2004 draft-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-

   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

   The list of Internet-Draft Shadow Directories can be accessed at

   "Copyright (C) The Internet Society (2002-2004).  All Rights


   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 ACLs                                          October 2004                                         February 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 ACLs                                          October 2004                                         February 2005

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
   2.  NFSv4 ACLs . . . . . . . . . . . . . . . . . . . . . . . . . 4
   3.  POSIX ACLs . . . . . . . . . . . . . . . . . . . . . . . . . 5
   4.  Mapping Posix POSIX ACLs to NFSv4 ACLs . . . . . . . . . . . . . . 6
   5.  Using the Mapping in NFSv4 Implementations . . . . . . . . . 8 9
   6.  Security Considerations  . . . . . . . . . . . . . . . . .  10  11
   7.  Bibliography . . . . . . . . . . . . . . . . . . . . . . .  11  12
   8.  Author's Address . . . . . . . . . . . . . . . . . . . . .  12  13
   9.  Copyright  . . . . . . . . . . . . . . . . . . . . . . . .  12  13

Mapping NFSv4 ACLs                                          October 2004                                         February 2005

1.  Introduction

   Access Control Lists (ACLs) are used to specify fine-grained access
   rights to file system objects.  An ACL consists of is a number list of Access Control
   Entries (ACEs), each specifying some level of access for an
   entity.  The entity may be a user, a group, or a special entity (such as "everyone").  The level of access is described using an access
   mask, which is a bitmask with each bit corresponding to a type user) 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 POSIX draft, which we draft.  We will refer to the latter
   as "POSIX ACLs".  Since NFSv4 ACLs are much finer-grained more 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
   be  However, it is possible to map
   any POSIX ACL to a NFSv4 ACL that has with nearly iden-
   tical identical semantics.  We
   will describe such a mapping, and discuss how it
   might be used its use in NFSv4 client clients
   and server 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 may also be one of a
   small set of special entities.  Among the special entities are "OWNER"
   "OWNER@" (the current owner of the file),
   "GROUP" "GROUP@" (the group associated associ-
   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).

   The NFSv4 ACL permission-checking algorithm is straightforward.
   Given an ACL and a requestor asking for a set of permissions speci-
   fied by an access mask:

   1) Walk through the list of ACEs from the mask has 14 separate bits, including bits to control read,
   write, execute, append, ACL in order.

   2) Ignore any ACE modification, file owner modification,
   etc.; consult [rfc3530] for with an entity not matching requestor.

Mapping NFSv4 ACLs                                          October 2004

   3) Process all ACEs until all the bits in the requested 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 in full list.

   Of the requested access mask flags, four are relevant here. The ACE4_IDENTIFIER_GROUP flag
   is DENYed (while used to indicate that bit is
      still under consideration), the request entity name is denied.

   5) If all bits have been ALLOWed, the access is granted.  Otherwise
      behavior is undefined.

   There are also a number name of flags that can be applied to an NFSv4 ACE.
   Three flags that we will need to use in the following discussion
   apply to ACEs in a directory ACL.  They are: ACE4_DIREC-
   TORY_INHERIT_ACE, which group.  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, which
   ACE4_FILE_INHERIT_ACE does the same for new files; and ACE4_INHERIT_ONLY, which
   ACE4_INHERIT_ONLY indicates that the ACE should be ignored when
   determining access to the directory itself.

   We refer the

   The 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.


   A number of operating systems, 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
   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_MASK ace. ACE.  The ACL_MASK ace ACE is required if the ACL
   has any ACL_USER or ACL_GROUP aces. ACEs.  There may not be two ACL_USER
   ACEs with the same uid, and there may not be two ACL_GROUP aces ACEs with
   the same gid.

   Given a POSIX ACL and a requestor requester asking for access, permission is
   determined as follows:

   1) If the requestor requester 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 2004

   2) if the requestor's requester's uid matches the uid of one of the ACL_USER
      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_GROUP ACE's ACEs whose gid the requestor requester is
      a member of.  Add to that set the ACL_GROUP_OBJ ACE, if the
      requester is also a member of that the file's group.  Allow access if one of
      the ACE's
      any ACE in the resulting set allows access.  If the set of
      matching match-
      ing ACEs is nonempty, and none allow access, then deny access.
      Otherwise, if none the set of these matching ACEs match, 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.


   The 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 bits also have to must be in the access mask of granted both by the special matching ACE with and by the
   ACL_MASK entity.  This allows file owners to
   specify a ACE.  The ACL_MASK ACE thus limits the maximum level of access allowed permissions
   which may be granted by any other user ACL_USER or group
   that has any access to the file system object.

   In addition to a regular POSIX ACL, a directory in ACL_GROUP ACE, or by the

   Each file system may also have associated with it a default ACL.  This default single POSIX ACL
   does not affect permissions associated with it, used to
   determine access to that file.  Directories, however, may have two
   ACLs: one, the directory itself.  Instead, it
   governs "access ACL", used to determine access to the direc-
   tory, and one, the "default ACL", used only as the ACL a file system object will to be assigned initially when
   it is inher-
   ited by newly created as a child of objects in the particular directory.

4.  Mapping Posix POSIX ACLs to NFSv4 ACLs

   Given the differences between POSIX and NFSv4 ACLs, any conversion
   between the two is difficult.  However, POSIX ACLs are a subset of
   NFSv4 ACLs, and

   We now describe an algorithm which maps any POSIX ACL can be emulated with to an NFSv4 ACL using
   with the following mapping. same semantics.

   First, translate the uid's and gid's on the ACL_USER and ACL_GROUP
   ACEs must be
   translated into NFSv4 names--a system-dependent process, which, on
   UNIX names.  This is an implementation-dependent process.
   It might be done, for example, may be done by lookups 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.


   Next, map each POSIX ACE access (excepting any mask is translated ACE) in the given POSIX
   ACL to an NFSv4 ALLOW ACE with an entity determined as follows.  The read bit of above, and
   with a bitmask determined from the permission bits on the POSIX access mask ACE
   as follows:

   1) If the read bit is translated to set in the logical OR of POSIX ACE, then set ACE4_READ_DATA.

   2) If the

Mapping NFSv4 ACLs                                          October 2004

   ACE4_READ_DATA and ACE4_READ_NAMED_ATTRS NFSv4 access mask fields.
   The write bit of is set in the POSIX access mask is translated to ACE, then set ACE4_WRITE_DATA
      and ACE4_APPEND_DATA.  If the logical
   OR of object carrying the ACL is a direc-
      tory, set ACE4_DELETE_CHILD as well.

   ACE4_APPEND_DATA NFSv4 access mask fields.  The execute bit of is set in the POSIX access mask ACE, then set ACE4_EXECUTE.


   5) If the ACE is translated into for the ACE4_EXECUTE special "OWNER@" entity, set ACE4_WRITE_ACL

Mapping NFSv4 acess mask fields.  Note that ACLs                                         February 2005

   6) Clear all other bits in the NFSv4 defines
   respectively, so this translation makes sense for directories as
   well.  However, on directories bitmask.

   In addition, we set the ACE4_DELETE_CHILD field must be
   included GROUP flag in each ACE which corresponds to a
   named group (but not in the translation GROUP@ ACE, or any of the POSIX write bit.

   In addition to other special
   entity ACEs).  At this point, we've replaced the above, POSIX ACL by an
   NFSv4 ACL with the OWNER entity must always be given
   ACE4_WRITE_ACL and ACE4_WRITE_ATTRIBUTES, and all entities must be
   ACE4_DELETE bit should be neither allowed nor denied by same number of ACEs (ignoring any ACE.

   The ACE flag field also has a simple translation.  If the file system
   object is a directory, and mask ACE).  To
   emulate the POSIX ACE belongs ACL permission-checking algorithm, we need to a default ACL,
   ACE4_FILE_INHERIT flags are set in mod-
   ify the NFSv4 ACE.  If ACL further, as follows:

   1) Order the entity in ACL so that the POSIX OWNER@ ACE refers to a group, the "ACE4_IDENTIFIER_GROUP" flag is
   set in the NFSv4 ACE.

   The POSIX ACL_USER_OBJ first ACE is also always given of the permission bits

   Completing ACL,
      followed by any user ACEs, followed by the mapping reduces to being able to emulate an ACL_MASK GROUP@ ACE, followed by
      any group ACEs, and compensate for some differences in the permission-checking algo-
   rithms of ending finally with the two ACL implementations. EVERYONE@ ACE.

   2) The difference in permission-checking algorithms is handled POSIX algorithm stops as soon as fol-

   Every user ACE in the POSIX ACL maps into 2 NFSv4 ACEs; one requester matches an
      ACL_USER_OBJ, ACL_OTHER, or ACL_USER ACE.  To emulate this
      behaviour, add a single DENY ACE after each ALLOW ACE
   which is translated for OWNER@,
      EVERYONE@, or any named user.  The DENY ACE should have the same
      entity and flags as specified by the above scheme, then a comple-
   menting corresponding ALLOW ACE.  The bitmask on
      the DENY ACE which is also translated as specified by should be the above
   scheme, with bitwise NOT of the exception that bitmask on the access mask is inverted.  Note ALLOW
      ACE, except that the ACL_USER_OBJ ACE is placed first in this list.

   Every group ACE ACE4_WRITE_OWNER and ACE4_DELETE bits should
      be cleared, and the ACE4_DELETE_CHILD bit should be cleared on
      non-directories.  (Also, in the POSIX xdr-encoded ACL produces a similar pair, but instead
   of being that is transmit-
      ted, all bits not defined in the protocol should be cleared.)

   3) Unlike the other ACEs in sequence, step 2, all of the ALLOW ACL_GROUP_OBJ and
      ACL_GROUP ACEs are all in sequence, fol-
   lowed consulted by all the DENY ACEs.  The ACL_GROUP_OBJ ACE is placed first POSIX 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
   both 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

   4) Finally, we enforce the POSIX ACL_OTHER mask ACE is translated into by prepending each ALLOW
      ACE for a pair named 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 of ACEs the 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 the user ACE case. required

   Such an ACL will map to an NFSv4 ACL of the form

Mapping NFSv4 ACLs                                          October 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 the NFSv4 permission-checking algorithm applied to ACEs marked with (mask) are those whose bitmask are deter-
   mined from the resulting NFSv4 ACL_MASK ACE as described in step 4 above.

   In general, a POSIX ACL with m named users and n named groups will produce
   map to an NFSv4 ACL with (3*(m + n) + 7) ACLs, unless m and n are
   both zero, in which case the same result 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 the POSIX
   permission-checking algorithm did ACE4_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 the original POSIX ACL.

   To handle ACL
   requests multiple bits simultaneously, the special POSIX entity ACL_MASK, we slightly modify the
   above translation:

   With the exception algorithm requires
   all of the "OWNER" and "EVERYONE" ACEs, another ACE is
   prepended bits to be granted simultaneously by one of the ACE.  The prepended ACE is group
   ACEs.  Thus a DENY ACE with the same
   entity POSIX ACL such as the following ALLOW ACE, but with

        ACL_USER_OBJ: ---
        ACL_GROUP_OBJ: ---
        g1: r--
        g2: -w-
        ACL_MASK: rw-
        ACL_OTHER: ---

Mapping NFSv4 ACLs                                         February 2005

   will prevent a permission mask set to
   the complement user 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 the POSIX ACL_MASK.

   This method allows us to preserve the real permission bits property that it
   permits a group of bits whenever it would permit each
   ACE 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 Implementations

   Note that

   Examination of the algorithm described in the previous section not only
   provides a way to map any shows
   that no information is lost; the original POSIX ACL to can be recon-
   structed from the mapped to an NFSv4 ACL with
   similar semantics, but ACL.  Thus we also provides the reverse mapping have 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 ACL
   happens to be
   is not in precisely the format of an ACL produced by this map-
   ping (as would happen if, for example, the client was performing the
   same translation), mapping,
   then the server can map it to a POSIX ACL may be required to store
   on the filesystem.  But for any other NFSv4 ACL, the server should return an error to avoid any chance of inaccurately inaccu-
   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 in han-
   dling handling 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 ACLs                                          October 2004

   It may therefore be possible for                                         February 2005

   that will satisfy a server to accept a wider range of
   NFSv4 ACLs, as long as it using the mapping.  By making the mapping
   more forgiving, the server can ensure simplify that in every case the resulting
   POSIX ACL denies at least all access task, improving interop-

   Servers that implement the original full NFSv4 ACL protocol should also handle
   carefully ACLs that leave bits neither allowed nor denied.  The results of such a mapping may, however, be somewhat
   unexpected, and it  It is preferable simply
   better to refuse all NFSv4 ACLs that
   do fall 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, not map accurately, and because it intends to deny
   ACE4_APPEND_DATA.  By leaving the bit unspecified, the client leaves
   the server the opportunity to provide clients with software the reasonable default of set-
   ting it to help gen-
   erate POSIX-mappable NFSv4 ACLs if necessary.

   Similarly, match ACE4_WRITE_DATA.

   Similar issues exist when a client that uses NFSv4 ACLS ACLs to implement user
   interfaces that only deal in POSIX ACLs.  When the client translates
   ACLs may handle user requests received from the server to set ACLs
   easily enough, POSIX ACLs, some flexibility may
   help interopability, but should return errors when the user requests client must take care not to represent
   any ACLs
   that, on consulting as stricter than they really are.  Clients that provide
   access to the server, turn out full set of NFSv4 ACLs may also wish to not be mappable provide users
   with utilities to generate and interpret POSIX-mapped NFSv4 ACLs, to
   aid users working with servers using the POSIX
   ACLs. mapping.

Mapping NFSv4 ACLs                                          October 2004                                         February 2005

6.  Security Considerations

   Any automatic mapping from one ACL model to another must provide
   guarantees that as to how the mapping preserves semantics, affects the meaning of ACLs, or risk
   misleading users about the permissions set on filesystem objects.
   For this rea-
   son, we recommend performing reason, caution is recommended when implementing this map-
   ping.  It is better to return errors than to break any such guaran-

   Note also that this ACL mapping only when it can be done
   accurately, requires mapping between NFSv4 user-
   names and returning 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 ACLs                                          October 2004                                         February 2005

7.  Bibliography

   Shepler, S. et. al., "NFS version 4 Protocol", April 2003.

   IEEE, "IEEE Draft P1003.1e", October 1997 (last draft).

Mapping NFSv4 ACLs                                          October 2004                                         February 2005

8.  Author's Address

   Address comments related to this memorandum to:

   Marius Aamodt Eriksen
   J. Bruce Fields
   University of Michigan / CITI
   535 West William
   Ann Arbor, Michigan


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