fsaccess.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 2000, 2001  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 /* $Id: fsaccess.h,v 1.16 2009/01/17 23:47:43 tbox Exp $ */
00019 
00020 #ifndef ISC_FSACCESS_H
00021 #define ISC_FSACCESS_H 1
00022 
00023 /*! \file isc/fsaccess.h
00024  * \brief The ISC filesystem access module encapsulates the setting of file
00025  * and directory access permissions into one API that is meant to be
00026  * portable to multiple operating systems.
00027  *
00028  * The two primary operating system flavors that are initially accommodated
00029  * are POSIX and Windows NT 4.0 and later.  The Windows NT access model is
00030  * considerable more flexible than POSIX's model (as much as I am loathe to
00031  * admit it), and so the ISC API has a higher degree of complexity than would
00032  * be needed to simply address POSIX's needs.
00033  *
00034  * The full breadth of NT's flexibility is not available either, for the
00035  * present time.  Much of it is to provide compatibility with what Unix
00036  * programmers are expecting.  This is also due to not yet really needing all
00037  * of the functionality of an NT system (or, for that matter, a POSIX system)
00038  * in BIND9, and so resolving how to handle the various incompatibilities has
00039  * been a purely theoretical exercise with no operational experience to
00040  * indicate how flawed the thinking may be.
00041  *
00042  * Some of the more notable dumbing down of NT for this API includes:
00043  *
00044  *\li   Each of FILE_READ_DATA and FILE_READ_EA are set with #ISC_FSACCESS_READ.
00045  *
00046  * \li  All of FILE_WRITE_DATA, FILE_WRITE_EA and FILE_APPEND_DATA are
00047  *     set with #ISC_FSACCESS_WRITE.  FILE_WRITE_ATTRIBUTES is not set
00048  *     so as to be consistent with Unix, where only the owner of the file
00049  *     or the superuser can change the attributes/mode of a file.
00050  *
00051  * \li  Both of FILE_ADD_FILE and FILE_ADD_SUBDIRECTORY are set with
00052  *     #ISC_FSACCESS_CREATECHILD.  This is similar to setting the WRITE
00053  *     permission on a Unix directory.
00054  *
00055  * \li  SYNCHRONIZE is always set for files and directories, unless someone
00056  *     can give me a reason why this is a bad idea.
00057  *
00058  * \li  READ_CONTROL and FILE_READ_ATTRIBUTES are always set; this is
00059  *     consistent with Unix, where any file or directory can be stat()'d
00060  *     unless the directory path disallows complete access somewhere along
00061  *     the way.
00062  *
00063  * \li  WRITE_DAC is only set for the owner.  This too is consistent with
00064  *     Unix, and is tighter security than allowing anyone else to be
00065  *     able to set permissions.
00066  *
00067  * \li  DELETE is only set for the owner.  On Unix the ability to delete
00068  *     a file is controlled by the directory permissions, but it isn't
00069  *     currently clear to me what happens on NT if the directory has
00070  *     FILE_DELETE_CHILD set but a file within it does not have DELETE
00071  *     set.  Always setting DELETE on the file/directory for the owner
00072  *     gives maximum flexibility to the owner without exposing the
00073  *     file to deletion by others.
00074  *
00075  * \li  WRITE_OWNER is never set.  This too is consistent with Unix,
00076  *     and is also tighter security than allowing anyone to change the
00077  *     ownership of the file apart from the superu..ahem, Administrator.
00078  *
00079  * \li  Inheritance is set to NO_INHERITANCE.
00080  *
00081  * Unix's dumbing down includes:
00082  *
00083  * \li  The sticky bit cannot be set.
00084  *
00085  * \li  setuid and setgid cannot be set.
00086  *
00087  * \li  Only regular files and directories can be set.
00088  *
00089  * The rest of this comment discusses a few of the incompatibilities
00090  * between the two systems that need more thought if this API is to
00091  * be extended to accommodate them.
00092  *
00093  * The Windows standard access right "DELETE" doesn't have a direct
00094  * equivalent in the Unix world, so it isn't clear what should be done
00095  * with it.
00096  *
00097  * The Unix sticky bit is not supported.  While NT does have a concept
00098  * of allowing users to create files in a directory but not delete or
00099  * rename them, it does not have a concept of allowing them to be deleted
00100  * if they are owned by the user trying to delete/rename.  While it is
00101  * probable that something could be cobbled together in NT 5 with inheritance,
00102  * it can't really be done in NT 4 as a single property that you could
00103  * set on a directory.  You'd need to coordinate something with file creation
00104  * so that every file created had DELETE set for the owner but noone else.
00105  *
00106  * On Unix systems, setting #ISC_FSACCESS_LISTDIRECTORY sets READ.
00107  * ... setting either #ISC_FSACCESS_CREATECHILD or #ISC_FSACCESS_DELETECHILD
00108  *      sets WRITE.
00109  * ... setting #ISC_FSACCESS_ACCESSCHILD sets EXECUTE.
00110  *
00111  * On NT systems, setting #ISC_FSACCESS_LISTDIRECTORY sets FILE_LIST_DIRECTORY.
00112  * ... setting #ISC_FSACCESS_CREATECHILD sets FILE_CREATE_CHILD independently.
00113  * ... setting #ISC_FSACCESS_DELETECHILD sets FILE_DELETE_CHILD independently.
00114  * ... setting #ISC_FSACCESS_ACCESSCHILD sets FILE_TRAVERSE.
00115  *
00116  * Unresolved:                                                  XXXDCL
00117  * \li  What NT access right controls the ability to rename a file?
00118  * \li  How does DELETE work?  If a directory has FILE_DELETE_CHILD but a
00119  *      file or directory within it does not have DELETE, is that file
00120  *      or directory deletable?
00121  * \li  To implement isc_fsaccess_get(), mapping an existing Unix permission
00122  *      mode_t back to an isc_fsaccess_t is pretty trivial; however, mapping
00123  *      an NT DACL could be impossible to do in a responsible way.
00124  * \li  Similarly, trying to implement the functionality of being able to
00125  *      say "add group writability to whatever permissions already exist"
00126  *      could be tricky on NT because of the order-of-entry issue combined
00127  *      with possibly having one or more matching ACEs already explicitly
00128  *      granting or denying access.  Because this functionality is
00129  *      not yet needed by the ISC, no code has been written to try to
00130  *      solve this problem.
00131  */
00132 
00133 #include <isc/lang.h>
00134 #include <isc/types.h>
00135 
00136 /*
00137  * Trustees.
00138  */
00139 #define ISC_FSACCESS_OWNER      0x1 /*%< User account. */
00140 #define ISC_FSACCESS_GROUP      0x2 /*%< Primary group owner. */
00141 #define ISC_FSACCESS_OTHER      0x4 /*%< Not the owner or the group owner. */
00142 #define ISC_FSACCESS_WORLD      0x7 /*%< User, Group, Other. */
00143 
00144 /*
00145  * Types of permission.
00146  */
00147 #define ISC_FSACCESS_READ               0x00000001 /*%< File only. */
00148 #define ISC_FSACCESS_WRITE              0x00000002 /*%< File only. */
00149 #define ISC_FSACCESS_EXECUTE            0x00000004 /*%< File only. */
00150 #define ISC_FSACCESS_CREATECHILD        0x00000008 /*%< Dir only. */
00151 #define ISC_FSACCESS_DELETECHILD        0x00000010 /*%< Dir only. */
00152 #define ISC_FSACCESS_LISTDIRECTORY      0x00000020 /*%< Dir only. */
00153 #define ISC_FSACCESS_ACCESSCHILD        0x00000040 /*%< Dir only. */
00154 
00155 /*%
00156  * Adding any permission bits beyond 0x200 would mean typedef'ing
00157  * isc_fsaccess_t as isc_uint64_t, and redefining this value to
00158  * reflect the new range of permission types, Probably to 21 for
00159  * maximum flexibility.  The number of bits has to accommodate all of
00160  * the permission types, and three full sets of them have to fit
00161  * within an isc_fsaccess_t.
00162  */
00163 #define ISC__FSACCESS_PERMISSIONBITS 10
00164 
00165 ISC_LANG_BEGINDECLS
00166 
00167 void
00168 isc_fsaccess_add(int trustee, int permission, isc_fsaccess_t *access);
00169 
00170 void
00171 isc_fsaccess_remove(int trustee, int permission, isc_fsaccess_t *access);
00172 
00173 isc_result_t
00174 isc_fsaccess_set(const char *path, isc_fsaccess_t access);
00175 
00176 ISC_LANG_ENDDECLS
00177 
00178 #endif /* ISC_FSACCESS_H */

Generated on Tue Apr 28 17:41:04 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha