Annotation of src/external/mpl/bind/dist/lib/isc/include/isc/fsaccess.h, Revision 1.1
1.1 ! christos 1: /* $NetBSD$ */
! 2:
! 3: /*
! 4: * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
! 5: *
! 6: * This Source Code Form is subject to the terms of the Mozilla Public
! 7: * License, v. 2.0. If a copy of the MPL was not distributed with this
! 8: * file, You can obtain one at http://mozilla.org/MPL/2.0/.
! 9: *
! 10: * See the COPYRIGHT file distributed with this work for additional
! 11: * information regarding copyright ownership.
! 12: */
! 13:
! 14:
! 15: #ifndef ISC_FSACCESS_H
! 16: #define ISC_FSACCESS_H 1
! 17:
! 18: /*! \file isc/fsaccess.h
! 19: * \brief The ISC filesystem access module encapsulates the setting of file
! 20: * and directory access permissions into one API that is meant to be
! 21: * portable to multiple operating systems.
! 22: *
! 23: * The two primary operating system flavors that are initially accommodated
! 24: * are POSIX and Windows NT 4.0 and later. The Windows NT access model is
! 25: * considerable more flexible than POSIX's model (as much as I am loathe to
! 26: * admit it), and so the ISC API has a higher degree of complexity than would
! 27: * be needed to simply address POSIX's needs.
! 28: *
! 29: * The full breadth of NT's flexibility is not available either, for the
! 30: * present time. Much of it is to provide compatibility with what Unix
! 31: * programmers are expecting. This is also due to not yet really needing all
! 32: * of the functionality of an NT system (or, for that matter, a POSIX system)
! 33: * in BIND9, and so resolving how to handle the various incompatibilities has
! 34: * been a purely theoretical exercise with no operational experience to
! 35: * indicate how flawed the thinking may be.
! 36: *
! 37: * Some of the more notable dumbing down of NT for this API includes:
! 38: *
! 39: *\li Each of FILE_READ_DATA and FILE_READ_EA are set with #ISC_FSACCESS_READ.
! 40: *
! 41: * \li All of FILE_WRITE_DATA, FILE_WRITE_EA and FILE_APPEND_DATA are
! 42: * set with #ISC_FSACCESS_WRITE. FILE_WRITE_ATTRIBUTES is not set
! 43: * so as to be consistent with Unix, where only the owner of the file
! 44: * or the superuser can change the attributes/mode of a file.
! 45: *
! 46: * \li Both of FILE_ADD_FILE and FILE_ADD_SUBDIRECTORY are set with
! 47: * #ISC_FSACCESS_CREATECHILD. This is similar to setting the WRITE
! 48: * permission on a Unix directory.
! 49: *
! 50: * \li SYNCHRONIZE is always set for files and directories, unless someone
! 51: * can give me a reason why this is a bad idea.
! 52: *
! 53: * \li READ_CONTROL and FILE_READ_ATTRIBUTES are always set; this is
! 54: * consistent with Unix, where any file or directory can be stat()'d
! 55: * unless the directory path disallows complete access somewhere along
! 56: * the way.
! 57: *
! 58: * \li WRITE_DAC is only set for the owner. This too is consistent with
! 59: * Unix, and is tighter security than allowing anyone else to be
! 60: * able to set permissions.
! 61: *
! 62: * \li DELETE is only set for the owner. On Unix the ability to delete
! 63: * a file is controlled by the directory permissions, but it isn't
! 64: * currently clear to me what happens on NT if the directory has
! 65: * FILE_DELETE_CHILD set but a file within it does not have DELETE
! 66: * set. Always setting DELETE on the file/directory for the owner
! 67: * gives maximum flexibility to the owner without exposing the
! 68: * file to deletion by others.
! 69: *
! 70: * \li WRITE_OWNER is never set. This too is consistent with Unix,
! 71: * and is also tighter security than allowing anyone to change the
! 72: * ownership of the file apart from the superu..ahem, Administrator.
! 73: *
! 74: * \li Inheritance is set to NO_INHERITANCE.
! 75: *
! 76: * Unix's dumbing down includes:
! 77: *
! 78: * \li The sticky bit cannot be set.
! 79: *
! 80: * \li setuid and setgid cannot be set.
! 81: *
! 82: * \li Only regular files and directories can be set.
! 83: *
! 84: * The rest of this comment discusses a few of the incompatibilities
! 85: * between the two systems that need more thought if this API is to
! 86: * be extended to accommodate them.
! 87: *
! 88: * The Windows standard access right "DELETE" doesn't have a direct
! 89: * equivalent in the Unix world, so it isn't clear what should be done
! 90: * with it.
! 91: *
! 92: * The Unix sticky bit is not supported. While NT does have a concept
! 93: * of allowing users to create files in a directory but not delete or
! 94: * rename them, it does not have a concept of allowing them to be deleted
! 95: * if they are owned by the user trying to delete/rename. While it is
! 96: * probable that something could be cobbled together in NT 5 with inheritance,
! 97: * it can't really be done in NT 4 as a single property that you could
! 98: * set on a directory. You'd need to coordinate something with file creation
! 99: * so that every file created had DELETE set for the owner but noone else.
! 100: *
! 101: * On Unix systems, setting #ISC_FSACCESS_LISTDIRECTORY sets READ.
! 102: * ... setting either #ISC_FSACCESS_CREATECHILD or #ISC_FSACCESS_DELETECHILD
! 103: * sets WRITE.
! 104: * ... setting #ISC_FSACCESS_ACCESSCHILD sets EXECUTE.
! 105: *
! 106: * On NT systems, setting #ISC_FSACCESS_LISTDIRECTORY sets FILE_LIST_DIRECTORY.
! 107: * ... setting #ISC_FSACCESS_CREATECHILD sets FILE_CREATE_CHILD independently.
! 108: * ... setting #ISC_FSACCESS_DELETECHILD sets FILE_DELETE_CHILD independently.
! 109: * ... setting #ISC_FSACCESS_ACCESSCHILD sets FILE_TRAVERSE.
! 110: *
! 111: * Unresolved: XXXDCL
! 112: * \li What NT access right controls the ability to rename a file?
! 113: * \li How does DELETE work? If a directory has FILE_DELETE_CHILD but a
! 114: * file or directory within it does not have DELETE, is that file
! 115: * or directory deletable?
! 116: * \li To implement isc_fsaccess_get(), mapping an existing Unix permission
! 117: * mode_t back to an isc_fsaccess_t is pretty trivial; however, mapping
! 118: * an NT DACL could be impossible to do in a responsible way.
! 119: * \li Similarly, trying to implement the functionality of being able to
! 120: * say "add group writability to whatever permissions already exist"
! 121: * could be tricky on NT because of the order-of-entry issue combined
! 122: * with possibly having one or more matching ACEs already explicitly
! 123: * granting or denying access. Because this functionality is
! 124: * not yet needed by the ISC, no code has been written to try to
! 125: * solve this problem.
! 126: */
! 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 isc_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 */
CVSweb <webmaster@jp.NetBSD.org>