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

https://bitbucket.org/freebsd/freebsd-head/ · C++ Header · 178 lines · 25 code · 13 blank · 140 comment · 0 complexity · 91965f540e041913afcca60493ebb98e MD5 · raw file

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