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