Subject: [nfsv4] Proposed spec changes for issue 121

From: "Noveck, Dave" <[email-masked]>
Date: Wed, 6 Dec 2006 10:15:05 -0500

This addresses a way to set or reset the non-permission bits of a 
mode without perturbing the permission bits.

These are in the form of context diffs for the changed .xml and .x
files in the CVS repository for the spec.  The base revision for 
all three files is the same as went into draft-08.

Index: nfsv41_middle_fileattributes.xml
===================================================================
RCS file: /cvs/stdk/NFSv41/nfsv41_middle_fileattributes.xml,v
retrieving revision 1.11
diff -C5 -r1.11 nfsv41_middle_fileattributes.xml
*** nfsv41_middle_fileattributes.xml	19 Oct 2006 15:46:18 -0000
1.11
--- nfsv41_middle_fileattributes.xml	6 Dec 2006 14:45:13 -0000
***************
*** 456,466 ****
  	MIME body type/subtype of this object.
        </c>
  
        <c>mode</c><c>33</c><c>mode4</c><c>R/W</c>
        <c>
! 	UNIX-style mode and permission bits for this object.
        </c>
  
        <c>mounted_on_fileid</c><c>55</c><c>uint64</c><c>READ</c>
        <c>
  	Like fileid, but if the target filehandle is the root of a
--- 456,472 ----
  	MIME body type/subtype of this object.
        </c>
  
        <c>mode</c><c>33</c><c>mode4</c><c>R/W</c>
        <c>
! 	UNIX-style mode including permission bits for this object.
!       </c>
! 
!       <c>mode_set_masked</c><c>74</c><c>mode_masked4</c><c>WRITE</c>
!       <c>
! 	Allows setting or resetting a subset of the bits in a
!         UNIX-style mode
        </c>
  
        <c>mounted_on_fileid</c><c>55</c><c>uint64</c><c>READ</c>
        <c>
  	Like fileid, but if the target filehandle is the root of a
Index: nfsv41_middle_fileattributes_acls.xml
===================================================================
RCS file: /cvs/stdk/NFSv41/nfsv41_middle_fileattributes_acls.xml,v
retrieving revision 1.7
diff -C5 -r1.7 nfsv41_middle_fileattributes_acls.xml
*** nfsv41_middle_fileattributes_acls.xml	19 Oct 2006 06:22:10
-0000	1.7
--- nfsv41_middle_fileattributes_acls.xml	6 Dec 2006 14:45:21
-0000
***************
*** 2,12 ****
  <!-- Copyright (C) The Internet Society (2006) -->
  <section title="Access Control Lists" anchor="acl">
      <t>
          Access Control Lists (ACLs) are a file attribute that specify
fine
          grained access control. This chapter covers the
&quot;acl&quot;,
!         &quot;aclsupport&quot;, and &quot;mode&quot; file attributes,
and
          their interactions.
      </t>
      
      <section title="Goals">
          <t>
--- 2,13 ----
  <!-- Copyright (C) The Internet Society (2006) -->
  <section title="Access Control Lists" anchor="acl">
      <t>
          Access Control Lists (ACLs) are a file attribute that specify
fine
          grained access control. This chapter covers the
&quot;acl&quot;,
!         &quot;aclsupport&quot;, &quot;mode&quot;,
!         &quot;mode_set_masked&quot; file attributes, and
          their interactions.
      </t>
      
      <section title="Goals">
          <t>
***************
*** 817,833 ****
                  to any principal that does not match that in the owner
                  attribute, and does not have a group matching that of
the
                  owner_group attribute.
              </t>
              <t>
!                 The remaining bits are not defined by this protocol. A
server
                  MUST NOT return bits other than those defined above in
a
                  GETATTR or READDIR operation, and it MUST return
NFS4ERR_INVAL
                  if bits other than those defined above are set in a
SETATTR,
                  CREATE, or OPEN operation.
              </t>
          </section>
      </section>
      
      <section title="Common Methods">
          <t>
              The requirements in this section will be referred to in
future
--- 818,871 ----
                  to any principal that does not match that in the owner
                  attribute, and does not have a group matching that of
the
                  owner_group attribute.
              </t>
              <t>
!                 Bits within the mode other than those specified above
!                 are not defined by this protocol. A server
                  MUST NOT return bits other than those defined above in
a
                  GETATTR or READDIR operation, and it MUST return
NFS4ERR_INVAL
                  if bits other than those defined above are set in a
SETATTR,
                  CREATE, or OPEN operation.
              </t>
          </section>
+         <section title="mode_set_masked Attribute"
anchor="modesetmaskedattr">
+             <t>
+                 The mode_set_masked attribute is a write-only atribute
+                 that allows individual bits in the mode attribute to
be
+                 set or reset, without changing others.  It allows, for
+                 example, the bits MODE4_SUID, MODE4_SGID, and
MODE4_SVTX
+                 to be modified while leaving unmodified any of the 
+                 nine low-order mode bits devoted to permissions.
+             </t>
+             <t>
+                 The mode_set_masked attribute consists of two words
+                 each in the form of a mode4.  The first consists of
the
+                 value to be applied to the current mode value and the
+                 second is a mask.  Only bits set to one in the mask
word
+                 are changed (set or reset) in the file's mode.  All 
+                 other bits in the mode remain unchanged.  Bits in the
+                 first word that correspond to bits which are zero in
+                 the mask are ignored, except that undefined bits are
+                 checked for validity and can result in NFSERR_INVAL as
+                 described below.
+             </t> 
+             <t>
+                 The mode_set_masked attrbute is only valid in a
SETATTR
+                 operation.  If it is used in a CREATE or OPEN
operation, the
+                 server MUST return NFS4ERR_INVAL.
+             </t>
+             <t>
+                 Bits not defined as valid in the mode attribute are
not
+                 valid in either word of the mode_set_masked attribute.
+                 The server MUST return NFS4ERR_INVAL
+                 if any of those are on in a SETATTR.  If the mode and
+                 mode_set_masked attributes are both specified in the
+                 same SETATTR, the server MUST also return
NFS4ERR_INVAL.
+             </t>
+         </section>
+ 
      </section>
      
      <section title="Common Methods">
          <t>
              The requirements in this section will be referred to in
future
***************
*** 1034,1050 ****
          </t>
          <section title="Setting the mode and/or ACL Attributes"
              anchor="setattr">
              <section title="Setting mode and not ACL"
anchor="setmode">
                  <t>
!                     When setting a mode attribute and not an ACL
attribute,
!                     the mode attribute MUST be set as given. The ACL
attribute
                      MUST be modified such that the mode computed via
the
                      method in
                      <xref target="computemode" />
                      yields the low-order nine bits (MODE4_R*,
MODE4_W*,
!                     MODE4_X*) of the newly set mode attribute.  The
ACL
                      SHOULD also be modified such that:
                      <list style="numbers">
                          <t>
                              If MODE4_RGRP is not set, entities
explicitly
                              listed in the ACL other than OWNER@ and
EVERYONE@
--- 1072,1102 ----
          </t>
          <section title="Setting the mode and/or ACL Attributes"
              anchor="setattr">
              <section title="Setting mode and not ACL"
anchor="setmode">
                  <t>
!                     When any mode permission 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 the ACL
!                     attribute is not explicitly set, the ACL
!                     attribute 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.
!                 </t>
!                 <t>
!                     In cases in which the permissions bits are subject
to
!                     change, the ACL attribute
                      MUST be modified such that the mode computed via
the
                      method in
                      <xref target="computemode" />
                      yields the low-order nine bits (MODE4_R*,
MODE4_W*,
!                     MODE4_X*) of the mode attribute as modified by the
!                     attribute change.  The ACL
                      SHOULD also be modified such that:
                      <list style="numbers">
                          <t>
                              If MODE4_RGRP is not set, entities
explicitly
                              listed in the ACL other than OWNER@ and
EVERYONE@
***************
*** 1084,1107 ****
                  </t>
              </section>
              <section title="Setting ACL and not mode"
                  anchor="settingacl">
                  <t>
!                     When setting an ACL attribute and not a mode
attribute,
                      the ACL attribute SHOULD be set as given. The nine
                      low-order bits of the mode attribute (MODE4_R*,
MODE4_W*,
                      MODE4_X*) MUST be modified to match the result of
the method 
                      <xref target="computemode" />. The three
high-order bits of
                      the mode (MODE4_SUID, MODE4_SGID, MODE4_SVTX)
SHOULD remain
                      unchanged.
                  </t>
              </section>
              <section title="Setting both ACL and mode"
anchor="setboth">
                  <t>
!                     When setting both the mode and the ACL attribute
in the
                      same operation, the attributes MUST be applied in
this
!                     order: mode, then ACL. The mode attribute is set
as given,
                      then the ACL attribute is set as given, possibly
changing
                      the final mode, as described above in
                      <xref target="settingacl" />.
                  </t>
              </section>
--- 1136,1166 ----
                  </t>
              </section>
              <section title="Setting ACL and not mode"
                  anchor="settingacl">
                  <t>
!                     When setting an ACL attribute and not setting the
!                     mode or mode_set_masked attributes, 
!                     the permission bits of the mode need to be
!                     derived from the ACL.  
!                     In this case,
                      the ACL attribute SHOULD be set as given. The nine
                      low-order bits of the mode attribute (MODE4_R*,
MODE4_W*,
                      MODE4_X*) MUST be modified to match the result of
the method 
                      <xref target="computemode" />. The three
high-order bits of
                      the mode (MODE4_SUID, MODE4_SGID, MODE4_SVTX)
SHOULD remain
                      unchanged.
                  </t>
              </section>
              <section title="Setting both ACL and mode"
anchor="setboth">
                  <t>
!                     When setting both the mode (includes use of either
the
!                     mode attribute or the mode_set_masked atribute) 
!                     and the ACL attribute in the
                      same operation, the attributes MUST be applied in
this
!                     order: mode (or mode_set_masked), then ACL.  The 
!                     mode-related attribute is set as given,
                      then the ACL attribute is set as given, possibly
changing
                      the final mode, as described above in
                      <xref target="settingacl" />.
                  </t>
              </section>
Index: dotx.d/head.x
===================================================================
RCS file: /cvs/stdk/NFSv41/dotx.d/head.x,v
retrieving revision 1.3
diff -C5 -r1.3 head.x
*** dotx.d/head.x	19 Oct 2006 06:22:15 -0000	1.3
--- dotx.d/head.x	6 Dec 2006 14:45:32 -0000
***************
*** 338,348 ****
  	acemask4	access_mask;
  	utf8str_mixed	who;
  };
  
  /*
!  * Field definitions for the fattr4_mode attribute
   */
  const MODE4_SUID = 0x800;  /* set user id on execution */
  const MODE4_SGID = 0x400;  /* set group id on execution */
  const MODE4_SVTX = 0x200;  /* save text even after use */
  const MODE4_RUSR = 0x100;  /* read permission: owner */
--- 338,349 ----
  	acemask4	access_mask;
  	utf8str_mixed	who;
  };
  
  /*
!  * Field definitions for the fattr4_mode and fattr4_mode_set_masked 
!  * attributes.
   */
  const MODE4_SUID = 0x800;  /* set user id on execution */
  const MODE4_SGID = 0x400;  /* set group id on execution */
  const MODE4_SVTX = 0x200;  /* save text even after use */
  const MODE4_RUSR = 0x100;  /* read permission: owner */
***************
*** 354,363 ****
--- 355,374 ----
  const MODE4_ROTH = 0x004;  /* read permission: other */
  const MODE4_WOTH = 0x002;  /* write permission: other */
  const MODE4_XOTH = 0x001;  /* execute permission: other */
  
  /*
+  * Masked mode for the mode_set_masked attribute.
+  */
+ struct mode_masked4 {
+         mode4		value_to_set;	/* Values of bits to set or
reset
+                                            in mode. */
+         mode4           mask_bits;      /* Mask of bits to set or
reset 
+                                            in mode. */
+ };
+ 
+ /*
   * Special data/attribute associated with
   * file types NF4BLK and NF4CHR.
   */
  struct specdata4 {
  	uint32_t	specdata1;	/* major device number */
***************
*** 572,581 ****
--- 583,593 ----
  typedef uint32_t	fattr4_maxname;
  typedef uint64_t	fattr4_maxread;
  typedef uint64_t	fattr4_maxwrite;
  typedef utf8str_cs	fattr4_mimetype;
  typedef mode4		fattr4_mode;
+ typedef mode_masked4	fattr4_mode_set_masked;
  typedef uint64_t	fattr4_mounted_on_fileid;
  typedef bool		fattr4_no_trunc;
  typedef uint32_t	fattr4_numlinks;
  typedef utf8str_mixed	fattr4_owner;
  typedef utf8str_mixed	fattr4_owner_group;
***************
*** 699,708 ****
--- 711,721 ----
  const FATTR4_RETENTION_GET	= 69;
  const FATTR4_RETENTION_SET	= 70;
  const FATTR4_RETENTEVT_GET	= 71;
  const FATTR4_RETENTEVT_SET	= 72;
  const FATTR4_RETENTION_HOLD	= 73;
+ const FATTR4_MODE_SET_MASKED	= 74;
  
  typedef opaque	attrlist4<>;
  
  /*
   * File attribute container

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

---

From: Spencer Shepler <[email-masked]>
Date: Thu, 7 Dec 2006 11:35:49 -0600

Changes look appropriate, Dave.

---

From: "J. Bruce Fields" <[email-masked]>
Date: Thu, 7 Dec 2006 13:03:27 -0500

> mode without perturbing the permission bits.

Looks good to me.  Will be interesting to see whether and how clients
actually adopt it, though....

--b.