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.4 2005/08/01 01:49:16 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, Coda, 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 acl.h, although the
  65 recommended usage is to only ever handle text-form ACLs in applications,
  66 generated and maintained using
  67 .Fn acl_from_text
  68 and
  69 .Fn acl_to_text ,
  70 passed directly to and from the management routines.  In this manner,
  71 an application can remain safely unaware of the contents of ACLs.
  72 .Pp
  73 Available functions, sorted by behavior, include:
  74 .Pp
  75 .Fn acl_delete_def_file ,
  76 .Fn acl_delete_file_np ,
  77 .Fn acl_delete_fd_np
  78 .Pp
  79 These functions are described in
  80 .Xr acl_delete 3 ,
  81 and may be used to delete ACLs from file system objects.
  82 .Pp
  83 .Fn acl_free
  84 .Pp
  85 This function is described in
  86 .Xr acl_free 3 ,
  87 and may be used to free userland working ACL storage.
  88 .Pp
  89 .Fn acl_from_text
  90 .Pp
  91 This function is described in
  92 .Xr acl_from_text 3 ,
  93 and may be used to convert a text-form ACL into working ACL state, if
  94 the ACL has POSIX.1e semantics.
  95 .Pp
  96 .Fn acl_get_file ,
  97 .Fn acl_get_fd ,
  98 .Fn acl_get_fd_np
  99 .Pp
 100 These functions are described in
 101 .Xr acl_get 3 ,
 102 and may be used to retrieve ACLs from file system objects.
 103 .Pp
 104 .Fn acl_init
 105 .Pp
 106 This function is described in
 107 .Xr acl_init 3 ,
 108 and may be used to allocate a fresh (empty) ACL structure.
 109 .Pp
 110 .Fn acl_dup
 111 .Pp
 112 This function is described in
 113 .Xr acl_dup 3 ,
 114 and may be used to duplicate an ACL structure.
 115 .Pp
 116 .Fn acl_set_file ,
 117 .Fn acl_set_fd ,
 118 .Fn acl_set_fd_np
 119 .Pp
 120 These functions are described in
 121 .Xr acl_set 3 ,
 122 and may be used to assign an ACL to a file system object.
 123 .Pp
 124 .Fn acl_to_text
 125 .Pp
 126 This function is described in
 127 .Xr acl_to_text 3 ,
 128 and may be used to generate a text-form of a POSIX.1e semantics ACL.
 129 .Pp
 130 .Fn acl_valid ,
 131 .Fn acl_valid_file_np ,
 132 .Fn acl_valid_fd_np
 133 .Pp
 134 Thee functions are described in
 135 .Xr acl_valid 3 ,
 136 and may be used to validate an ACL as correct POSIX.1e-semantics, or
 137 as appropriate for a particular file system object regardless of semantics.
 138 .Pp
 139 Documentation of the internal kernel interfaces backing these calls may
 140 be found in
 141 .Xr acl 9 .
 142 The syscalls between the internal interfaces and the public library
 143 routines may change over time, and as such are not documented.  They are
 144 not intended to be called directly without going through the library.
 145 .Sh IMPLEMENTATION NOTES
 146 .Dx Ns 's
 147 support for POSIX.1e interfaces and features is still under
 148 development at this time.
 149 .Sh ENVIRONMENT
 150 POSIX.1e assigns security labels to all objects, extending the security
 151 functionality described in POSIX.1.  These additional labels provide
 152 fine-grained discretionary access control, fine-grained capabilities,
 153 and labels necessary for mandatory access control.  POSIX.2c describes
 154 a set of userland utilities for manipulating these labels.  These userland
 155 utilities are not bundled with
 156 .Dx
 157 so as to discourage their
 158 use in the short term.
 159 .\" .Sh FILES
 160 .Sh SEE ALSO
 161 .Xr acl 3 ,
 162 .Xr acl_dup 3 ,
 163 .Xr acl_free 3 ,
 164 .Xr acl_from_text 3 ,
 165 .Xr acl_get 3 ,
 166 .Xr acl_set 3 ,
 167 .Xr acl_to_text 3 ,
 168 .Xr acl_valid 3 ,
 169 .Xr acl 9
 170 .Sh STANDARDS
 171 POSIX.1e is described in IEEE POSIX.1e draft 17.  Discussion
 172 of the draft continues on the cross-platform POSIX.1e implementation
 173 mailing list.  To join this list, see the
 174 .Fx
 175 POSIX.1e implementation
 176 page for more information.
 177 .Sh HISTORY
 178 POSIX.1e support was introduced in
 179 .Fx 4.0 ,
 180 and development continues.
 181 .Sh AUTHORS
 182 .An Robert N M Watson
 183 .Sh BUGS
 184 These features are not yet fully implemented.  In particular, the shipped
 185 version of UFS/FFS does not support storage of additional security labels,
 186 and so is unable to (easily) provide support for most of these features.