cifs: Update description about ACL permissions

There are some incorrect information about individual SMB permission
constants like WRITE_DAC can change ownership, or incomplete information to
distinguish between ACL types (discretionary vs system) and there is
completely missing information how permissions apply for directory objects
and what is meaning of GENERIC_* bits.

Also there is missing constant for MAXIMUM_ALLOWED permission.

Fix and extend description of all SMB permission constants to match the
reality, how the reference Windows SMB / NTFS implementation handles them.

Links to official Microsoft documentation related to permissions:
https://learn.microsoft.com/en-us/windows/win32/fileio/file-access-rights-constants
https://learn.microsoft.com/en-us/windows/win32/secauthz/access-mask
https://learn.microsoft.com/en-us/windows/win32/secauthz/standard-access-rights
https://learn.microsoft.com/en-us/windows/win32/secauthz/generic-access-rights
https://learn.microsoft.com/en-us/windows/win32/api/winternl/nf-winternl-ntcreatefile
https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntcreatefile

Signed-off-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Steve French <stfrench@microsoft.com>

diff --git a/fs/smb/client/cifspdu.h b/fs/smb/client/cifspdu.h
index c285f0e5ce0f0cc4e51e16d6c4661f97690cd588..84743f3d7c5121ab2568909fe20634c4d8ca0854 100644 (file)
--- a/fs/smb/client/cifspdu.h
+++ b/fs/smb/client/cifspdu.h
@@ -190,42 +190,82 @@
  */
 
 #define FILE_READ_DATA        0x00000001  /* Data can be read from the file   */
+                                         /* or directory child entries can   */
+                                         /* be listed together with the      */
+                                         /* associated child attributes      */
+                                         /* (so the FILE_READ_ATTRIBUTES on  */
+                                         /* the child entry is not needed)   */
 #define FILE_WRITE_DATA       0x00000002  /* Data can be written to the file  */
+                                         /* or new file can be created in    */
+                                         /* the directory                    */
 #define FILE_APPEND_DATA      0x00000004  /* Data can be appended to the file */
+                                         /* (for non-local files over SMB it */
+                                         /* is same as FILE_WRITE_DATA)      */
+                                         /* or new subdirectory can be       */
+                                         /* created in the directory         */
 #define FILE_READ_EA          0x00000008  /* Extended attributes associated   */
                                          /* with the file can be read        */
 #define FILE_WRITE_EA         0x00000010  /* Extended attributes associated   */
                                          /* with the file can be written     */
 #define FILE_EXECUTE          0x00000020  /*Data can be read into memory from */
                                          /* the file using system paging I/O */
-#define FILE_DELETE_CHILD     0x00000040
+                                         /* for executing the file / script  */
+                                         /* or right to traverse directory   */
+                                         /* (but by default all users have   */
+                                         /* directory bypass traverse        */
+                                         /* privilege and do not need this   */
+                                         /* permission on directories at all)*/
+#define FILE_DELETE_CHILD     0x00000040  /* Child entry can be deleted from  */
+                                         /* the directory (so the DELETE on  */
+                                         /* the child entry is not needed)   */
 #define FILE_READ_ATTRIBUTES  0x00000080  /* Attributes associated with the   */
-                                         /* file can be read                 */
+                                         /* file or directory can be read    */
 #define FILE_WRITE_ATTRIBUTES 0x00000100  /* Attributes associated with the   */
-                                         /* file can be written              */
-#define DELETE                0x00010000  /* The file can be deleted          */
-#define READ_CONTROL          0x00020000  /* The access control list and      */
-                                         /* ownership associated with the    */
-                                         /* file can be read                 */
-#define WRITE_DAC             0x00040000  /* The access control list and      */
-                                         /* ownership associated with the    */
-                                         /* file can be written.             */
+                                         /* file or directory can be written */
+#define DELETE                0x00010000  /* The file or dir can be deleted   */
+#define READ_CONTROL          0x00020000  /* The discretionary access control */
+                                         /* list and ownership associated    */
+                                         /* with the file or dir can be read */
+#define WRITE_DAC             0x00040000  /* The discretionary access control */
+                                         /* list associated with the file or */
+                                         /* directory can be written         */
 #define WRITE_OWNER           0x00080000  /* Ownership information associated */
-                                         /* with the file can be written     */
+                                         /* with the file/dir can be written */
 #define SYNCHRONIZE           0x00100000  /* The file handle can waited on to */
                                          /* synchronize with the completion  */
                                          /* of an input/output request       */
 #define SYSTEM_SECURITY       0x01000000  /* The system access control list   */
-                                         /* can be read and changed          */
-#define GENERIC_ALL           0x10000000
-#define GENERIC_EXECUTE       0x20000000
-#define GENERIC_WRITE         0x40000000
-#define GENERIC_READ          0x80000000
-                                        /* In summary - Relevant file       */
-                                        /* access flags from CIFS are       */
-                                        /* file_read_data, file_write_data  */
-                                        /* file_execute, file_read_attributes*/
-                                        /* write_dac, and delete.           */
+                                         /* associated with the file or      */
+                                         /* directory can be read or written */
+                                         /* (cannot be in DACL, can in SACL) */
+#define MAXIMUM_ALLOWED       0x02000000  /* Maximal subset of GENERIC_ALL    */
+                                         /* permissions which can be granted */
+                                         /* (cannot be in DACL nor SACL)     */
+#define GENERIC_ALL           0x10000000  /* Same as: GENERIC_EXECUTE |       */
+                                         /*          GENERIC_WRITE |         */
+                                         /*          GENERIC_READ |          */
+                                         /*          FILE_DELETE_CHILD |     */
+                                         /*          DELETE |                */
+                                         /*          WRITE_DAC |             */
+                                         /*          WRITE_OWNER             */
+                                         /* So GENERIC_ALL contains all bits */
+                                         /* mentioned above except these two */
+                                         /* SYSTEM_SECURITY  MAXIMUM_ALLOWED */
+#define GENERIC_EXECUTE       0x20000000  /* Same as: FILE_EXECUTE |          */
+                                         /*          FILE_READ_ATTRIBUTES |  */
+                                         /*          READ_CONTROL |          */
+                                         /*          SYNCHRONIZE             */
+#define GENERIC_WRITE         0x40000000  /* Same as: FILE_WRITE_DATA |       */
+                                         /*          FILE_APPEND_DATA |      */
+                                         /*          FILE_WRITE_EA |         */
+                                         /*          FILE_WRITE_ATTRIBUTES | */
+                                         /*          READ_CONTROL |          */
+                                         /*          SYNCHRONIZE             */
+#define GENERIC_READ          0x80000000  /* Same as: FILE_READ_DATA |        */
+                                         /*          FILE_READ_EA |          */
+                                         /*          FILE_READ_ATTRIBUTES |  */
+                                         /*          READ_CONTROL |          */
+                                         /*          SYNCHRONIZE             */
 
 #define FILE_READ_RIGHTS (FILE_READ_DATA | FILE_READ_EA | FILE_READ_ATTRIBUTES)
 #define FILE_WRITE_RIGHTS (FILE_WRITE_DATA | FILE_APPEND_DATA \