Subject: [nfsv4] ACL section revisions

From: "J. Bruce Fields" <[email-masked]>
Date: Thu, 11 Oct 2007 18:36:17 -0400

The following acl section revisions are leftover from the acl review.
There's no substantive change to the ACL model, and nothing particularly
contraversial--the goal is just to make the section easier to read,
provide some better guidance here and there, and fix some minor bugs.

I've also incorporated feedback from Sam, who reviewed this.  (Thanks!)

A summary:

    - Fix the DELETE/DELETE_CHILD algorithm to take into account
      traditional variations in the "sticky bit" behavior, and rewrite
      for conciseness.

    - Encourage more strongly that servers support the full ACL model
      instead of requiring client software to be aware of complex
      mapping.  Provide some more guidance and an additional example.

    - Consistently use "nine low-order mode bits" rather than "bits that
      control permissions".

    - Fix an example in the "ACE Access Mask" section which suggests
      rejecting an acl in a case where it would be preferable to
      silently turn off allow bits.

    - Fix some ommissions from the "operations affected" lists: EXECUTE
      may affect any operation that takes a path (hence may require a
      lookup), and VERIFY, NVERIFY, and READDIR may be affected by
      READ_ATTRIBUTES.

    - miscellaneous copyediting: fix some typos, correct minor grammar
      and style problems, revise for conciseness, etc.  On balance I'm
      removing language where possible (it's a long section) but only
      where I believe the result is text that is more helpful rather
      than less.

(Gory details with detailed justifications for each change are available
from

	git://linux-nfs.org/~bfields/nfsv41.git aclwork

or by request--I could mail them out to the alias individually if
preferred.  Just let me know what you need.)

--b.

---

 nfsv41_middle_fileattributes_acls.xml |  359 +++++++++++++--------------------
 1 files changed, 145 insertions(+), 214 deletions(-)

diff --git a/nfsv41_middle_fileattributes_acls.xml b/nfsv41_middle_fileattributes_acls.xml
index 7ac7bd3..7ac55ab 100755
--- a/nfsv41_middle_fileattributes_acls.xml
+++ b/nfsv41_middle_fileattributes_acls.xml
@@ -15,7 +15,7 @@
     
     <section title="Goals">
         <t>
-            ACLs and modes represent two well established but different models
+            ACLs and modes represent two well established models
             for specifying permissions. This chapter specifies requirements
             that attempt to meet the following goals:
 
@@ -51,7 +51,7 @@
                             Setting only the mode attribute should provide
                             reasonable security. For example, setting a mode
                             of 000 should be enough to ensure that future
-                            opens for read or write by any principal should
+                            opens for read or write by any principal
                             fail, regardless of a previously existing or
                             inherited ACL.
                         </t>
@@ -66,27 +66,15 @@
             implementations and discussions around them.
                 </t>
                 <t>
-            If a server supports ACL attributes (any of
-            &quot;acl&quot;, &quot;dacl&quot; and
-            &quot;sacl&quot;), then at any time, the server can
-            provide the supported ACL attributes when
-            requested.  The ACL attributes will describe all
-            permissions on the file object, except for the
-            three high-order bits of the mode attribute
-            (described in <xref target="modeattr" />).  The ACL
-            attributes will not conflict with the mode
-            attribute, on servers that support the mode
-            attribute.  Briefly, &quot;will not conflict&quot;
-            means that applying the algorithm in <xref
-            target="computemode" /> to the ACL yields the nine
-            low-order bits of the mode.  See <xref
-            target="setattr" /> for exact requirements.
-                </t>
-                <t>
-                    If a server supports the mode attribute, then at any time,
-                    the server can provide a mode attribute when requested.
-                    The mode attribute will not conflict with the ACL
-                    attributes, on servers that support the ACL attributes.
+                    On servers that support both the mode and the acl or
+                    dacl attributes, the server must keep the two consistent
+                    with each other.  The value of the mode attribute (with
+                    the exception of the three high order bits described in
+                    <xref target="modeattr" />), must be determined entirely
+                    by the value of the ACL, so that use of the mode is
+                    never required for anything other than setting the
+                    three high order bits.  See <xref target="setattr" />
+                    for exact requirements.
                 </t>
                 <t>
                     When a mode attribute is set on an object, the ACL
@@ -156,10 +144,26 @@
                 The NFS version 4 ACL model is quite rich. Some server
                 platforms may provide access control functionality that goes
                 beyond the UNIX-style mode attribute, but which is not as rich
-                as the NFS ACL model. So that users can take advantage of this
-                more limited functionality, the server may indicate that it
-                supports ACLs as long as it follows the guidelines for mapping
-                between its ACL model and the NFS version 4 ACL model.
+                as the NFS ACL model.  So that users can take advantage of this
+                more limited functionality, the server may support the acl
+                attributes by mapping between its ACL model and the NFS version
+                4 ACL model.  Servers must ensure that the ACL they
+                actually store or enforce is at least as strict as the NFSv4
+                ACL that was set.  It is tempting to accomplish this by
+                rejecting any ACL that falls outside the small set that
+                can be represented accurately.  However, such an approach
+                can render ACLs unusable without special client-side
+                knowledge of the server's mapping, which defeats the
+                purpose of having a common NFSv4 ACL protocol.
+                Therefore servers should accept every ACL that they can
+                without compromising security.  To help accomplish this,
+                servers may make a special exception, in the case of
+                unsupported permission bits, to the rule that bits not
+                ALLOWED or DENIED by an ACL must be denied.  For example, a
+                UNIX-style server might choose to silently allow read
+                attribute permissions even though an ACL does not explicitly
+                allow those permissions.  (An ACL that explicitly denies
+                permission to read attributes should still be rejected.)
             </t>
             <t>
         The situation is complicated by the fact that a server
@@ -216,9 +220,9 @@
                     <c>ACE4_SYSTEM_AUDIT_ACE_TYPE</c>
                     <c>AUDIT</c>
                     <c>
-                        LOG (system dependent) any access attempt to a file or
-                        directory which uses any of the access methods
-                        specified in acemask4.
+                        LOG (in a system dependent way) any access attempt to
+                        a file or directory which uses any of the access
+                        methods specified in acemask4.
                     </c>
                     <c>ACE4_SYSTEM_ALARM_ACE_TYPE</c>
                     <c>ALARM</c>
@@ -230,7 +234,7 @@
                     <postamble>
                         The &quot;Abbreviation&quot; column denotes how the
                         types will be referred to throughout the rest of this
-                        document.
+                        chapter.
                     </postamble>
                 </texttable>
             </section>
@@ -407,6 +411,10 @@
      Operation(s) affected:
          READ
          OPEN
+         REMOVE
+         RENAME
+         LINK
+         CREATE
      Discussion:
          Permission to execute a file.
 
@@ -450,6 +458,8 @@
  ACE4_READ_ATTRIBUTES
      Operation(s) affected:
          GETATTR of file system object attributes
+         VERIFY
+         NVERIFY
          READDIR
      Discussion:
          The ability to read basic attributes (non-ACLs) of a file.
@@ -548,76 +558,55 @@
                         and read. For example, suppose a server cannot
                         distinguish overwriting data from appending new
                         data, as described in the previous paragraph.
-                        If a client submits an ACE where
+                        If a client submits an ALLOW ACE where
                         ACE4_APPEND_DATA is set but ACE4_WRITE_DATA is
-                        not (or vice versa), the server should reject
-                        the request with NFS4ERR_ATTRNOTSUPP.
-                        Nonetheless, if the ACE has type DENY, the
-                        server may silently turn on the other bit, so
-                        that both ACE4_APPEND_DATA and ACE4_WRITE_DATA
-                        are denied.
+                        not (or vice versa), the server should either turn
+                        off ACE4_APPEND DATA or reject the request with
+                        NFS4ERR_ATTRNOTSUPP.
                     </t>
                 </section>
 
                 <section anchor="delete-delete_child" title="ACE4_DELETE vs. ACE4_DELETE_CHILD">
                     <t>
                         Two access mask bits govern the ability to delete a
-                        file or directory object: ACE4_DELETE on the object
-                        itself, and ACE4_DELETE_CHILD on the object's parent
-                        directory.
+                        directory entry: ACE4_DELETE on the object
+                        itself (the "target"), and ACE4_DELETE_CHILD on
+                        the containing directory (the "parent").
+                    </t>
+
+                    <t>
+                        Many systems also take the "sticky bit" (MODE4_SVTX)
+                        on a directory to allow unlink only to a user that
+                        owns either the target or the parent; on some
+                        such systems the decision also depends on
+                        whether the target is writeable.
                     </t>
-                    <t>           
-                        Many systems also consult the "sticky bit"
-                        (MODE4_SVTX) and write mode bit on the parent
-                        directory when determining whether to allow a file to
-                        be deleted. The mode bit for write corresponds to
-                        ACE4_WRITE_DATA, which is the same physical bit as
-                        ACE4_ADD_FILE. Therefore, ACE4_WRITE_DATA can come into
-                        play when determining permission to delete.
+
+                    <t>
+                        Servers SHOULD allow unlink if either ACE4_DELETE
+                        is permitted on the target, or ACE4_DELETE_CHILD is
+                        permitted on the parent.  (Note that this is
+                        true even if the parent or target explicitly
+                        denies one of these permissions.)
                     </t>
 
                     <t>
-                        In the algorithm below, the strategy is that
-                        ACE4_DELETE and ACE4_DELETE_CHILD take precedence over
-                        the sticky bit, and the sticky bit takes precedence
-                        over the "write" mode bits (reflected in
-                        ACE4_ADD_FILE). </t>
+                       If the ACLs in question neither explicitly ALLOW
+                       nor DENY either of the above, and if MODE4_SVTX is
+                       not set on the parent, then the server SHOULD allow
+                       the removal if and only if ACE4_ADD_FILE is permitted.
+                       In the case where MODE4_SVTX is set, the server
+                       may also require the remover to own either the parent
+                       or the target, or may require the target to be
+                       writeable.
+                    </t>
 
                     <t>
-                        Server implementations SHOULD grant or deny permission
-                        to delete based on the following algorithm.
+                        This allows servers to support something close to
+                        traditional unix-like semantics, with ACE4_ADD_FILE
+                        taking the place of the write bit.
                     </t>
 
-                    <figure>
-                        <artwork>
-    if ACE4_TRAVERSE is denied by the parent directory ACL {
-        deny delete
-    } else if ACE4_DELETE is allowed by the target object ACL {
-        allow delete
-    } else if ACE4_DELETE_CHILD is allowed by the parent
-    directory ACL {
-        allow delete
-    } else if ACE4_DELETE_CHILD is denied by the
-    parent directory ACL {
-        deny delete
-    } else if ACE4_ADD_FILE is allowed by the parent directory ACL {
-        if MODE4_SVTX is set for the parent directory {
-            if the principal owns the parent directory OR
-                the principal owns the target object OR
-                ACE4_WRITE_DATA is allowed by the target
-                object ACL {
-                    allow delete
-                } else {
-                    deny delete
-                }
-        } else {
-            allow delete
-        }
-    } else {
-        deny delete
-    }
-                        </artwork>
-                    </figure>
                 </section>
             </section>
             <section anchor="aceflag" title="ACE flag">
@@ -730,7 +719,7 @@
                                     <vspace />
                                     The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG
                                     (SUCCESS) and ACE4_FAILED_ACCESS_ACE_FLAG
-                                    (FAILED) flag bits relate only to
+                                    (FAILED) flag bits may be set only on
                                     ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and
                                     ACE4_SYSTEM_ALARM_ACE_TYPE (ALARM) ACE
                                     types. If during the processing of the
@@ -757,14 +746,12 @@
 
                                 <t hangText="">
                                     The previously described processing
-                                    applies to that of the ACCESS operation as
-                                    well, the difference being that "success"
-                                    or "failure" does not mean whether ACCESS
-                                    returns NFS4_OK or not. Success means
-                                    whether ACCESS returns all requested and
-                                    supported bits. Failure means whether
-                                    ACCESS failed to return at least one
-                                    bit that was requested and supported.
+                                    applies to ACCESS operations even when
+                                    they return NFS4_OK.  For the purposes of
+                                    AUDIT and ALARM, we consider an ACCESS
+                                    operation to be a "failure" if it fails
+                                    to return a bit that was requested and
+                                    supported.
                                 </t>
 
                                 <t hangText="ACE4_IDENTIFIER_GROUP">
@@ -846,8 +833,8 @@
                 </texttable>
                 <t>
                     To avoid conflict, these special identifiers are
-                    distinguish by an appended "@" and should appear in the
-                    form "xxxx@" (note: no domain name after the "@"). For
+                    distinguished by an appended "@" and should appear in the
+                    form "xxxx@" (with no domain name after the "@"). For
                     example: ANONYMOUS@.
                 </t>
                 <t>
@@ -1051,109 +1038,62 @@
                 The following method can be used to calculate the MODE4_R*,
                 MODE4_W* and MODE4_X* bits of a mode attribute, based upon
                 an ACL.
-                
+            </t>
+
+            <t>
+                First, for each of the special identifiers ONWER@, GROUP@, and
+                EVERYONE@, evaluate the ACL in order, considering only ALLOW
+                and DENY ACEs for the identifier EVERYONE@ and for the
+                identifier under consideration.  The result of the evaulation
+                will be an NFSv4 ACL mask showing exactly which bits are
+                permitted to that identifier.
+            </t>
+
+            <t>
+                Then translate the calculated mask for OWNER@, GROUP@, and
+                EVERYONE@ into mode bits for, respectively, the user, group,
+                and other, as follows:
+
                 <list style="numbers">
                     <t>
-                        To determine MODE4_ROTH, MODE4_WOTH, and MODE4_XOTH:
-                        <list style="letters">
-                            <t>
-                                If the special identifier EVERYONE@ is granted
-                                ACE4_READ_DATA, then
-                                the bit MODE4_ROTH SHOULD be set.  Otherwise,
-                                MODE4_ROTH SHOULD NOT be set.
-                            </t>
-                            <t>
-                                If the special identifier EVERYONE@
-                                is granted ACE4_WRITE_DATA or
-                                ACE4_APPEND_DATA, then the bit
-                                MODE4_WOTH SHOULD be set.  Otherwise,
-                                MODE4_WOTH SHOULD NOT be set.
-                            </t>
-                            <t>
-                                If the special identifier EVERYONE@
-                                is granted ACE4_EXECUTE, then
-                                the bit MODE4_XOTH SHOULD be set.  Otherwise,
-                                MODE4_XOTH SHOULD NOT be set.
-                            </t>
-                        </list>
+                        Set the read bit (MODE4_RUSR, MODE4_RGRP, or
+                        MODE4_ROTH) if and only if ACE4_READ_DATA is set in
+                        the corresponding mask.
                     </t>
+
                     <t>
-                        To determine MODE4_RGRP, MODE4_WGRP, and MODE4_XGRP,
-                        note that the EVERYONE@ special identifier SHOULD be
-                        taken into account.  In other words, when determining
-                        if the GROUP@ special identifier is granted a
-                        permission, ACEs with the identifier EVERYONE@ should
-                        take effect just as ACEs with the special identifier
-                        GROUP@ would.
-                        <list style="letters">
-                            <t>
-                                If the special identifier GROUP@ is granted
-                                ACE4_READ_DATA, then the bit MODE4_RGRP SHOULD
-                                be set. Otherwise, MODE4_RGRP SHOULD NOT be set.
-                            </t>
-                            <t>
-                                If the special identifier GROUP@ is granted
-                               ACE4_WRITE_DATA or ACE4_APPEND_DATA, then the
-                               bit MODE4_WGRP SHOULD be set. Otherwise,
-                               MODE4_WGRP SHOULD NOT be set.
-                            </t>
-                            <t>
-                                If the special identifier GROUP@ is granted
-                                ACE4_EXECUTE, then the bit MODE4_XGRP SHOULD
-                                be set. Otherwise, MODE4_XGRP SHOULD NOT be
-                                set.
-                            </t>
-                        </list>
+                        Set the write bit (MODE4_WUSR, MODE4_WGRP, or
+                        MODE4_WOTH) if and only if ACE4_WRITE_DATA and
+                        ACE4_APPEND_DATA are both set in the corresponding
+                        mask.
                     </t>
+
                     <t>
-                        To determine MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR,
-                        note that the EVERYONE@ special identifier SHOULD be
-                        taken into account.  In other words, when determining
-                        if the OWNER@ special identifier is granted a
-                        permission, ACEs with the identifier EVERYONE@ should
-                        take effect just as ACEs with the special identifer
-                        OWNER@ would.
-                        <list style="letters">
-                            <t>
-                                If the special identifier OWNER@ is granted
-                                ACE4_READ_DATA, then the bit MODE4_RUSR SHOULD
-                                be set. Otherwise, MODE4_RUSR SHOULD NOT be
-                                set.
-                            </t>
-                            <t>
-                                If the special identifier OWNER@ is granted
-                                ACE4_WRITE_DATA or ACE4_APPEND_DATA, then the
-                                bit MODE4_WUSR SHOULD be set. Otherwise,
-                                MODE4_WUSR SHOULD NOT be set.
-                            </t>
-                            <t>
-                                If the special identifier OWNER@ is granted
-                                ACE4_EXECUTE, then the bit MODE4_XUSR SHOULD
-                                be set. Otherwise, MODE4_XUSR SHOULD NOT be
-                                set.
-                            </t>
-                        </list>
+                        Set the execute bit (MODE4_XUSR, MODE4_XGRP, or
+                        MODE4_XOTH), if and only if ACE4_EXECUTE is set in the
+                        corresponding mask.
                     </t>
                 </list>
             </t>
             <section title="Discussion">
                 <t>
-                    The nine low-order mode bits (MODE4_R*, MODE4_W*, MODE4_X*)
-                    correspond to ACE4_READ_DATA,
-                    ACE4_WRITE_DATA/ACE4_APPEND_DATA, and ACE4_EXECUTE for
-                    OWNER@, GROUP@, and EVERYONE@. On some implementations,
-                    mode bits may represent a superset of these permissions,
-                    e.g. if a specific user is granted ACE4_WRITE_DATA, then
-                    MODE4_WGRP will be set, even though the file's owner_group
-                    is not granted ACE4_WRITE_DATA.
+                    Some server implementations also add bits permitted to
+                    named users and groups to the group bits (MODE4_RGRP,
+                    MODE4_WGRP, and MODE4_XGRP).
+                </t>
+                <t>
+                    Implementations are discouraged from doing this, because
+                    it has been found to cause confusion for users who see
+                    members of a file's group denied access that the mode
+                    bits appear to allow.  (The presence of DENY ACEs may also
+                    lead to such behavior, but DENY ACEs are expected to be
+                    more rarely used.)
                 </t>
                 <t>
-                    Server implementations are discouraged from doing this, as
-                    experience has shown that this is confusing and annoying
-                    to end users. The specifications above also discourage
-                    this practice to enforce the semantic that setting the
-                    mode attribute effectively specifies read, write, and
-                    execute for owner, group, and other.
+                    The same user confusion seen when fetching the mode also
+                    results if setting the mode does not effectively control
+                    permissions for the owner, group, and other users; this
+                    motivates some of the requirements that follow.
                 </t>
             </section>
         </section>
@@ -1188,17 +1128,17 @@
         </t>
             <section title="Setting mode and not ACL" anchor="setmode">
                 <t>
-            When any of the nine low-order mode permission bits
+            When any of the nine low-order mode bits
             are subject to change, either because the mode
             attribute was set or because the mode_set_masked
             attribute was set and the mask included one or more
-            bits from the low-order nine mode bits that control
-            permissions, and no ACL attribute is explicitly
+            bits from the nine low-order mode bits,
+            and no ACL attribute is explicitly
             set, the acl and dacl attributes must be modified
-            in accordance with the updated value of the
-            permissions bits within the mode.  This must happen
-            even if the value of the permission bits within the
-            mode is the same after the mode is set as before.
+            in accordance with the updated value of those bits.
+            This must happen
+            even if the value of the low-order bits
+            is the same after the mode is set as before.
                 </t>
         <t>
             Note that any AUDIT or ALARM ACEs (hence any ACEs in the
@@ -1393,26 +1333,17 @@
                     from being affected by ACEs meant for non-directories.
                 </t>
                 <t>
-            If when a new directory is created and it inherits
-            ACEs from its parent, for each inheritable ACE
-            which affects the directory's permissions, a server
-            MAY create two ACEs on the directory being created;
-            one effective and one which is only inheritable
-            (i.e. has ACE4_INHERIT_ONLY_ACE flag set).  In the
-            case of a dacl or sacl attribute, both of these
-            ACEs SHOULD have the ACE4_INHERITED_ACE flag set.
-            This gives the user and the server, in the cases
-            which it must mask certain permissions upon
-            creation, the ability to modify the effective
-            permissions without modifying the ACE which is to
-            be inherited to the new directory's children.
-                </t>
-                <t>
-                    When a newly created object is created with attributes,
-                    and those attributes contain an ACL attribute and/or a
-                    mode attribute, the server MUST apply those attributes to
-                    the newly created object, as described in <xref
-                    target="setattr" />.
+            When a new directory is created, the server MAY split
+            any inherited ACE which is both inheritable and effective
+            (in other words, which has neither ACE4_INHERIT_ONLY_ACE
+            nor ACE4_NO_PROPAGATE_INHERIT_ACE set), into two ACEs,
+            one with no inheritance flags, and one with
+            ACE4_INHERIT_ONLY_ACE set.  (In the case of a dacl or
+            sacl attribute, both of those ACEs SHOULD also have the
+            ACE4_IHERITED_ACE flag set.)  This makes it simpler to
+            modify the effective permissions on the directory
+            without modifying the ACE which is to be inherited to the
+            new directory's children.
                 </t>
             </section>

----- End forwarded message -----

_______________________________________________
nfsv4 mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/nfsv4

---

From: Spencer Shepler <[email-masked]>
Date: Tue, 23 Oct 2007 21:50:51 -0500

> I've also incorporated feedback from Sam, who reviewed this.   

Thank you for the updates and the work that went into them.

Seeing no discussion, I am assuming we have consensus on these
changes and they have been incorporated into the I-D and will
arrive in draft 15.

Spencer

---

From: "J. Bruce Fields" <[email-masked]>
Date: Tue, 23 Oct 2007 22:54:17 -0400

> changes and they have been incorporated into the I-D and will

OK; thanks!--b.