contrib/bind-9.3/lib/isc/include/isc/fsaccess.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: fsaccess.h,v 1.7.206.1 2004/03/06 08:14:41 marka Exp $ */
  19
  20 #ifndef ISC_FSACCESS_H
  21 #define ISC_FSACCESS_H 1
  22
  23 /*
  24  * The ISC filesystem access module encapsulates the setting of file
  25  * and directory access permissions into one API that is meant to be
  26  * portable to multiple operating systems.
  27  *
  28  * The two primary operating system flavors that are initially accomodated are
  29  * POSIX and Windows NT 4.0 and later.  The Windows NT access model is
  30  * considerable more flexible than POSIX's model (as much as I am loathe to
  31  * admit it), and so the ISC API has a higher degree of complexity than would
  32  * be needed to simply address POSIX's needs.
  33  *
  34  * The full breadth of NT's flexibility is not available either, for the
  35  * present time.  Much of it is to provide compatibility with what Unix
  36  * programmers are expecting.  This is also due to not yet really needing all
  37  * of the functionality of an NT system (or, for that matter, a POSIX system)
  38  * in BIND9, and so resolving how to handle the various incompatibilities has
  39  * been a purely theoretical exercise with no operational experience to
  40  * indicate how flawed the thinking may be.
  41  *
  42  * Some of the more notable dumbing down of NT for this API includes:
  43  *
  44  *   o Each of FILE_READ_DATA and FILE_READ_EA are set with ISC_FSACCESS_READ.
  45  *
  46  *   o All of FILE_WRITE_DATA, FILE_WRITE_EA and FILE_APPEND_DATA are
  47  *     set with ISC_FSACCESS_WRITE.  FILE_WRITE_ATTRIBUTES is not set
  48  *     so as to be consistent with Unix, where only the owner of the file
  49  *     or the superuser can change the attributes/mode of a file.
  50  *
  51  *   o Both of FILE_ADD_FILE and FILE_ADD_SUBDIRECTORY are set with
  52  *     ISC_FSACCESS_CREATECHILD.  This is similar to setting the WRITE
  53  *     permission on a Unix directory.
  54  *
  55  *   o SYNCHRONIZE is always set for files and directories, unless someone
  56  *     can give me a reason why this is a bad idea.
  57  *
  58  *   o READ_CONTROL and FILE_READ_ATTRIBUTES are always set; this is
  59  *     consistent with Unix, where any file or directory can be stat()'d
  60  *     unless the directory path disallows complete access somewhere along
  61  *     the way.
  62  *
  63  *   o WRITE_DAC is only set for the owner.  This too is consistent with
  64  *     Unix, and is tighter security than allowing anyone else to be
  65  *     able to set permissions.
  66  *
  67  *   o DELETE is only set for the owner.  On Unix the ability to delete
  68  *     a file is controlled by the directory permissions, but it isn't
  69  *     currently clear to me what happens on NT if the directory has
  70  *     FILE_DELETE_CHILD set but a file within it does not have DELETE
  71  *     set.  Always setting DELETE on the file/directory for the owner
  72  *     gives maximum flexibility to the owner without exposing the
  73  *     file to deletion by others.
  74  *
  75  *   o WRITE_OWNER is never set.  This too is consistent with Unix,
  76  *     and is also tighter security than allowing anyone to change the
  77  *     ownership of the file apart from the superu..ahem, Administrator.
  78  *
  79  *   o Inheritance is set to NO_INHERITANCE.
  80  *
  81  * Unix's dumbing down includes:
  82  *
  83  *   o The sticky bit cannot be set.
  84  *
  85  *   o setuid and setgid cannot be set.
  86  *
  87  *   o Only regular files and directories can be set.
  88  *
  89  * The rest of this comment discusses a few of the incompatibilities
  90  * between the two systems that need more thought if this API is to
  91  * be extended to accomodate them.
  92  *
  93  * The Windows standard access right "DELETE" doesn't have a direct
  94  * equivalent in the Unix world, so it isn't clear what should be done
  95  * with it.
  96  *
  97  * The Unix sticky bit is not supported.  While NT does have a concept
  98  * of allowing users to create files in a directory but not delete or
  99  * rename them, it does not have a concept of allowing them to be deleted
 100  * if they are owned by the user trying to delete/rename.  While it is
 101  * probable that something could be cobbled together in NT 5 with inheritence,
 102  * it can't really be done in NT 4 as a single property that you could
 103  * set on a directory.  You'd need to coordinate something with file creation
 104  * so that every file created had DELETE set for the owner but noone else.
 105  *
 106  * On Unix systems, setting ISC_FSACCESS_LISTDIRECTORY sets READ.
 107  * ... setting either of ISC_FSACCESS_(CREATE|DELETE)CHILD sets WRITE.
 108  * ... setting ISC_FSACCESS_ACCESSCHILD sets EXECUTE.
 109  *
 110  * On NT systems, setting ISC_FSACCESS_LISTDIRECTORY sets FILE_LIST_DIRECTORY.
 111  * ... setting ISC_FSACCESS_(CREATE|DELETE)CHILD sets
 112  *      FILE_(CREATE|DELETE)_CHILD independently.
 113  * ... setting ISC_FSACCESS_ACCESSCHILD sets FILE_TRAVERSE.
 114  *
 115  * Unresolved:                                                  XXXDCL
 116  *   What NT access right controls the ability to rename a file?
 117  *   How does DELETE work?  If a directory has FILE_DELETE_CHILD but a
 118  *      file or directory within it does not have DELETE, is that file
 119  *      or directory deletable?
 120  *   To implement isc_fsaccess_get(), mapping an existing Unix permission
 121  *      mode_t back to an isc_fsaccess_t is pretty trivial; however, mapping
 122  *      an NT DACL could be impossible to do in a responsible way.
 123  *   Similarly, trying to implement the functionality of being able to
 124  *      say "add group writability to whatever permissions already exist"
 125  *      could be tricky on NT because of the order-of-entry issue combined
 126  *      with possibly having one or more matching ACEs already explicitly
 127  *      granting or denying access.  Because this functionality is
 128  *      not yet needed by the ISC, no code has been written to try to
 129  *      solve this problem.
 130  */
 131
 132 #include <isc/lang.h>
 133 #include <isc/types.h>
 134
 135 /*
 136  * Trustees.
 137  */
 138 #define ISC_FSACCESS_OWNER      0x1 /* User account. */
 139 #define ISC_FSACCESS_GROUP      0x2 /* Primary group owner. */
 140 #define ISC_FSACCESS_OTHER      0x4 /* Not the owner or the group owner. */
 141 #define ISC_FSACCESS_WORLD      0x7 /* User, Group, Other. */
 142
 143 /*
 144  * Types of permission.
 145  */
 146 #define ISC_FSACCESS_READ               0x00000001 /* File only. */
 147 #define ISC_FSACCESS_WRITE              0x00000002 /* File only. */
 148 #define ISC_FSACCESS_EXECUTE            0x00000004 /* File only. */
 149 #define ISC_FSACCESS_CREATECHILD        0x00000008 /* Dir only. */
 150 #define ISC_FSACCESS_DELETECHILD        0x00000010 /* Dir only. */
 151 #define ISC_FSACCESS_LISTDIRECTORY      0x00000020 /* Dir only. */
 152 #define ISC_FSACCESS_ACCESSCHILD        0x00000040 /* Dir only. */
 153
 154 /*
 155  * Adding any permission bits beyond 0x200 would mean typedef'ing
 156  * isc_fsaccess_t as isc_uint64_t, and redefining this value to
 157  * reflect the new range of permission types, Probably to 21 for
 158  * maximum flexibility.  The number of bits has to accomodate all of
 159  * the permission types, and three full sets of them have to fit
 160  * within an isc_fsaccess_t.
 161  */
 162 #define ISC__FSACCESS_PERMISSIONBITS 10
 163
 164 ISC_LANG_BEGINDECLS
 165
 166 void
 167 isc_fsaccess_add(int trustee, int permission, isc_fsaccess_t *access);
 168
 169 void
 170 isc_fsaccess_remove(int trustee, int permission, isc_fsaccess_t *access);
 171
 172 isc_result_t
 173 isc_fsaccess_set(const char *path, isc_fsaccess_t access);
 174
 175 ISC_LANG_ENDDECLS
 176
 177 #endif /* ISC_FSACCESS_H */