/contrib/bind9/lib/isc/include/isc/fsaccess.h

  1/*
  2 * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
  3 * Copyright (C) 2000, 2001  Internet Software Consortium.
  4 *
  5 * Permission to use, copy, modify, and/or 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.16 2009/01/17 23:47:43 tbox Exp $ */
 19
 20#ifndef ISC_FSACCESS_H
 21#define ISC_FSACCESS_H 1
 22
 23/*! \file isc/fsaccess.h
 24 * \brief 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 accommodated
 29 * are 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 *\li   Each of FILE_READ_DATA and FILE_READ_EA are set with #ISC_FSACCESS_READ.
 45 *
 46 * \li  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 * \li  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 * \li  SYNCHRONIZE is always set for files and directories, unless someone
 56 *     can give me a reason why this is a bad idea.
 57 *
 58 * \li  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 * \li  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 * \li  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 * \li  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 * \li  Inheritance is set to NO_INHERITANCE.
 80 *
 81 * Unix's dumbing down includes:
 82 *
 83 * \li  The sticky bit cannot be set.
 84 *
 85 * \li  setuid and setgid cannot be set.
 86 *
 87 * \li  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 accommodate 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 inheritance,
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 #ISC_FSACCESS_CREATECHILD or #ISC_FSACCESS_DELETECHILD
108 *      sets WRITE.
109 * ... setting #ISC_FSACCESS_ACCESSCHILD sets EXECUTE.
110 *
111 * On NT systems, setting #ISC_FSACCESS_LISTDIRECTORY sets FILE_LIST_DIRECTORY.
112 * ... setting #ISC_FSACCESS_CREATECHILD sets FILE_CREATE_CHILD independently.
113 * ... setting #ISC_FSACCESS_DELETECHILD sets FILE_DELETE_CHILD independently.
114 * ... setting #ISC_FSACCESS_ACCESSCHILD sets FILE_TRAVERSE.
115 *
116 * Unresolved:							XXXDCL
117 * \li  What NT access right controls the ability to rename a file?
118 * \li  How does DELETE work?  If a directory has FILE_DELETE_CHILD but a
119 *      file or directory within it does not have DELETE, is that file
120 *	or directory deletable?
121 * \li  To implement isc_fsaccess_get(), mapping an existing Unix permission
122 * 	mode_t back to an isc_fsaccess_t is pretty trivial; however, mapping
123 *	an NT DACL could be impossible to do in a responsible way.
124 * \li  Similarly, trying to implement the functionality of being able to
125 *	say "add group writability to whatever permissions already exist"
126 *	could be tricky on NT because of the order-of-entry issue combined
127 *	with possibly having one or more matching ACEs already explicitly
128 *	granting or denying access.  Because this functionality is
129 *	not yet needed by the ISC, no code has been written to try to
130 * 	solve this problem.
131 */
132
133#include <isc/lang.h>
134#include <isc/types.h>
135
136/*
137 * Trustees.
138 */
139#define ISC_FSACCESS_OWNER	0x1 /*%< User account. */
140#define ISC_FSACCESS_GROUP	0x2 /*%< Primary group owner. */
141#define ISC_FSACCESS_OTHER	0x4 /*%< Not the owner or the group owner. */
142#define ISC_FSACCESS_WORLD	0x7 /*%< User, Group, Other. */
143
144/*
145 * Types of permission.
146 */
147#define ISC_FSACCESS_READ		0x00000001 /*%< File only. */
148#define ISC_FSACCESS_WRITE		0x00000002 /*%< File only. */
149#define ISC_FSACCESS_EXECUTE		0x00000004 /*%< File only. */
150#define ISC_FSACCESS_CREATECHILD	0x00000008 /*%< Dir only. */
151#define ISC_FSACCESS_DELETECHILD	0x00000010 /*%< Dir only. */
152#define ISC_FSACCESS_LISTDIRECTORY	0x00000020 /*%< Dir only. */
153#define ISC_FSACCESS_ACCESSCHILD	0x00000040 /*%< Dir only. */
154
155/*%
156 * Adding any permission bits beyond 0x200 would mean typedef'ing
157 * isc_fsaccess_t as isc_uint64_t, and redefining this value to
158 * reflect the new range of permission types, Probably to 21 for
159 * maximum flexibility.  The number of bits has to accommodate all of
160 * the permission types, and three full sets of them have to fit
161 * within an isc_fsaccess_t.
162 */
163#define ISC__FSACCESS_PERMISSIONBITS 10
164
165ISC_LANG_BEGINDECLS
166
167void
168isc_fsaccess_add(int trustee, int permission, isc_fsaccess_t *access);
169
170void
171isc_fsaccess_remove(int trustee, int permission, isc_fsaccess_t *access);
172
173isc_result_t
174isc_fsaccess_set(const char *path, isc_fsaccess_t access);
175
176ISC_LANG_ENDDECLS
177
178#endif /* ISC_FSACCESS_H */