lib/libposix1e/acl.3

   1 .\"-
   2 .\" Copyright (c) 2000 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/lib/libposix1e/acl.3,v 1.2.2.5 2001/12/20 16:27:06 ru Exp $
  27 .\" $DragonFly: src/lib/libposix1e/acl.3,v 1.6 2006/08/19 01:36:39 swildner Exp $
  28 .\"
  29 .Dd January 28, 2000
  30 .Dt ACL 3
  31 .Os
  32 .Sh NAME
  33 .Nm acl
  34 .Nd introduction to the POSIX.1e ACL security API
  35 .Sh LIBRARY
  36 .Lb libposix1e
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/acl.h
  40 .Sh DESCRIPTION
  41 As shipped,
  42 .Dx
  43 permits file systems to export
  44 Access Control Lists via the VFS, and provides a library for userland
  45 access to and manipulation of these ACLs, but support for ACLs is not
  46 provided by any file systems shipped in the base operating system.
  47 The library calls shipped with 4.0 include routines to allocate,
  48 duplicate, retrieve, set, and validate ACLs associated with file objects.
  49 As well as the POSIX.1e routines, there are a number of non-portable
  50 extensions defined that allow for alternative ACL semantics than the
  51 POSIX.1e semantics, such as AFS, NTFS, and NWFS semantics.  Where
  52 routines are non-standard, they are suffixed with _np to indicate that
  53 they are not portable.
  54 .Pp
  55 POSIX.1e describes a set of ACL manipulation routines to manage the
  56 contents of ACLs, as well as their relationships with files.  This
  57 manipulation library is not currently implemented in
  58 .Dx ,
  59 although
  60 a third party library was under development at the time this document
  61 was written.  There is a general consensus that the POSIX.1e manipulation
  62 routines are ambiguously defined in the specification, and don't meet the
  63 needs of most applications.  For the time being, applications may
  64 directly manipulate the ACL structures, defined in
  65 .In sys/acl.h ,
  66 although the
  67 recommended usage is to only ever handle text-form ACLs in applications,
  68 generated and maintained using
  69 .Fn acl_from_text
  70 and
  71 .Fn acl_to_text ,
  72 passed directly to and from the management routines.  In this manner,
  73 an application can remain safely unaware of the contents of ACLs.
  74 .Pp
  75 Available functions, sorted by behavior, include:
  76 .Pp
  77 .Fn acl_delete_def_file ,
  78 .Fn acl_delete_file_np ,
  79 .Fn acl_delete_fd_np
  80 .Pp
  81 These functions are described in
  82 .Xr acl_delete 3 ,
  83 and may be used to delete ACLs from file system objects.
  84 .Pp
  85 .Fn acl_free
  86 .Pp
  87 This function is described in
  88 .Xr acl_free 3 ,
  89 and may be used to free userland working ACL storage.
  90 .Pp
  91 .Fn acl_from_text
  92 .Pp
  93 This function is described in
  94 .Xr acl_from_text 3 ,
  95 and may be used to convert a text-form ACL into working ACL state, if
  96 the ACL has POSIX.1e semantics.
  97 .Pp
  98 .Fn acl_get_file ,
  99 .Fn acl_get_fd ,
 100 .Fn acl_get_fd_np
 101 .Pp
 102 These functions are described in
 103 .Xr acl_get 3 ,
 104 and may be used to retrieve ACLs from file system objects.
 105 .Pp
 106 .Fn acl_init
 107 .Pp
 108 This function is described in
 109 .Xr acl_init 3 ,
 110 and may be used to allocate a fresh (empty) ACL structure.
 111 .Pp
 112 .Fn acl_dup
 113 .Pp
 114 This function is described in
 115 .Xr acl_dup 3 ,
 116 and may be used to duplicate an ACL structure.
 117 .Pp
 118 .Fn acl_set_file ,
 119 .Fn acl_set_fd ,
 120 .Fn acl_set_fd_np
 121 .Pp
 122 These functions are described in
 123 .Xr acl_set 3 ,
 124 and may be used to assign an ACL to a file system object.
 125 .Pp
 126 .Fn acl_to_text
 127 .Pp
 128 This function is described in
 129 .Xr acl_to_text 3 ,
 130 and may be used to generate a text-form of a POSIX.1e semantics ACL.
 131 .Pp
 132 .Fn acl_valid ,
 133 .Fn acl_valid_file_np ,
 134 .Fn acl_valid_fd_np
 135 .Pp
 136 Thee functions are described in
 137 .Xr acl_valid 3 ,
 138 and may be used to validate an ACL as correct POSIX.1e-semantics, or
 139 as appropriate for a particular file system object regardless of semantics.
 140 .Pp
 141 Documentation of the internal kernel interfaces backing these calls may
 142 be found in
 143 .Xr acl 9 .
 144 The syscalls between the internal interfaces and the public library
 145 routines may change over time, and as such are not documented.  They are
 146 not intended to be called directly without going through the library.
 147 .Sh IMPLEMENTATION NOTES
 148 .Dx Ns 's
 149 support for POSIX.1e interfaces and features is still under
 150 development at this time.
 151 .Sh ENVIRONMENT
 152 POSIX.1e assigns security labels to all objects, extending the security
 153 functionality described in POSIX.1.  These additional labels provide
 154 fine-grained discretionary access control, fine-grained capabilities,
 155 and labels necessary for mandatory access control.  POSIX.2c describes
 156 a set of userland utilities for manipulating these labels.  These userland
 157 utilities are not bundled with
 158 .Dx
 159 so as to discourage their
 160 use in the short term.
 161 .\" .Sh FILES
 162 .Sh SEE ALSO
 163 .Xr acl 3 ,
 164 .Xr acl_dup 3 ,
 165 .Xr acl_free 3 ,
 166 .Xr acl_from_text 3 ,
 167 .Xr acl_get 3 ,
 168 .Xr acl_set 3 ,
 169 .Xr acl_to_text 3 ,
 170 .Xr acl_valid 3 ,
 171 .Xr acl 9
 172 .Sh STANDARDS
 173 POSIX.1e is described in IEEE POSIX.1e draft 17.  Discussion
 174 of the draft continues on the cross-platform POSIX.1e implementation
 175 mailing list.  To join this list, see the
 176 .Fx
 177 POSIX.1e implementation
 178 page for more information.
 179 .Sh HISTORY
 180 POSIX.1e support was introduced in
 181 .Fx 4.0 ,
 182 and development continues.
 183 .Sh AUTHORS
 184 .An Robert N M Watson
 185 .Sh BUGS
 186 These features are not yet fully implemented.  In particular, the shipped
 187 version of UFS/FFS does not support storage of additional security labels,
 188 and so is unable to (easily) provide support for most of these features.