"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/isc/include/isc/fsaccess.h" (7 Sep 2020, 7441 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "fsaccess.h" see the Fossies "Dox" file reference documentation.

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