xref: /freebsd/lib/libc/posix1e/acl.3 (revision a889d1fb766450bff9b27c3bccfe18fc39cd753d)
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
32a889d1fbSRobert Watson.Nm acl \- introduction to the POSIX.1e ACL security API
33a889d1fbSRobert Watson.Sh SYNOPSIS
34a889d1fbSRobert Watson.Fd #include <sys/types.h>
35a889d1fbSRobert Watson.Fd #include <sys/acl.h>
36a889d1fbSRobert Watson.Sh DESCRIPTION
37a889d1fbSRobert WatsonAs shipped, FreeBSD 4.0 permits file systems to export
38a889d1fbSRobert WatsonAccess Control Lists via the VFS, and provides a library for userland
39a889d1fbSRobert Watsonaccess to and manipulation of these ACLs, but support for ACLs is not
40a889d1fbSRobert Watsonprovided by any file systems shipped in the base operating system.
41a889d1fbSRobert WatsonThe library calls shipped with 4.0 include routines to allocate,
42a889d1fbSRobert Watsonduplicate, retrieve, set, and validate ACLs associated with file objects.
43a889d1fbSRobert WatsonAs well as the POSIX.1e routines, there are a number of non-portable
44a889d1fbSRobert Watsonextensions defined that allow for alternative ACL semantics than the
45a889d1fbSRobert WatsonPOSIX.1e semantics, such as AFS, NTFS, Coda, and NWFS semantics.  Where
46a889d1fbSRobert Watsonroutines are non-standard, they are suffixed with _np to indicate that
47a889d1fbSRobert Watsonthey are not portable.
48a889d1fbSRobert Watson
49a889d1fbSRobert WatsonPOSIX.1e describes a set of ACL manipulation routines to manage the
50a889d1fbSRobert Watsoncontents of ACLs, as well as their relationships with files.  This
51a889d1fbSRobert Watsonmanipulation library is not currently implemented in FreeBSD, although
52a889d1fbSRobert Watsona third party library was under development at the time this document
53a889d1fbSRobert Watsonwas written.  There is a general concensus that the POSIX.1e manipulation
54a889d1fbSRobert Watsonroutines are ambiguously defined in the specification, and don't meet the
55a889d1fbSRobert Watsonneeds of most applications.  For the time being, applications may
56a889d1fbSRobert Watsondirectly manipulate the ACL structures, defined in acl.h, although the
57a889d1fbSRobert Watsonrecommended usage is to only ever handle text-form ACLs in applications,
58a889d1fbSRobert Watsongenerated and maintained using
59a889d1fbSRobert Watson.Fn acl_from_text
60a889d1fbSRobert Watsonand
61a889d1fbSRobert Watson.Fn acl_to_text ,
62a889d1fbSRobert Watsonpassed directly to and from the management routines.  In this manner,
63a889d1fbSRobert Watsonan application can remain safely unaware of the contents of ACLs.
64a889d1fbSRobert Watson
65a889d1fbSRobert WatsonAvailable functions, sorted by behavior, include:
66a889d1fbSRobert Watson
67a889d1fbSRobert Watson.Fn acl_delete_def_file ,
68a889d1fbSRobert Watson.Fn acl_delete_file_np ,
69a889d1fbSRobert Watson.Fn acl_delete_fd_np
70a889d1fbSRobert Watson
71a889d1fbSRobert WatsonThese functions are described in
72a889d1fbSRobert Watson.Xr acl_delete 3 ,
73a889d1fbSRobert Watsonand may be used to delete ACLs from file system objects.
74a889d1fbSRobert Watson
75a889d1fbSRobert Watson.Fn acl_free
76a889d1fbSRobert Watson
77a889d1fbSRobert WatsonThis function is described in
78a889d1fbSRobert Watson.Xr acl_free 3 ,
79a889d1fbSRobert Watsonand may be used to free userland working ACL storage.
80a889d1fbSRobert Watson
81a889d1fbSRobert Watson.Fn acl_from_text
82a889d1fbSRobert Watson
83a889d1fbSRobert WatsonThis function is described in
84a889d1fbSRobert Watson.Xr acl_from_text 3 ,
85a889d1fbSRobert Watsonand may be used to convert a text-form ACL into working ACL state, if
86a889d1fbSRobert Watsonthe ACL has POSIX.1e semantics.
87a889d1fbSRobert Watson
88a889d1fbSRobert Watson.Fn acl_get_file ,
89a889d1fbSRobert Watson.Fn acl_get_fd ,
90a889d1fbSRobert Watson.Fn acl_get_fd_np
91a889d1fbSRobert Watson
92a889d1fbSRobert WatsonThese functions are described in
93a889d1fbSRobert Watson.Xr acl_get 3 ,
94a889d1fbSRobert Watsonand may be used to retrieve ACLs from file system objects.
95a889d1fbSRobert Watson
96a889d1fbSRobert Watson.Fn acl_init
97a889d1fbSRobert Watson
98a889d1fbSRobert WatsonThis function is described in
99a889d1fbSRobert Watson.Xr acl_init 3 ,
100a889d1fbSRobert Watsonand may be used to allocate a fresh (empty) ACL structure.
101a889d1fbSRobert Watson
102a889d1fbSRobert Watson.Fn acl_dup
103a889d1fbSRobert Watson
104a889d1fbSRobert WatsonThis function is described in
105a889d1fbSRobert Watson.Xr acl_dup 3 ,
106a889d1fbSRobert Watsonand may be used to duplicate an ACL structure.
107a889d1fbSRobert Watson
108a889d1fbSRobert Watson.Fn acl_set_file ,
109a889d1fbSRobert Watson.Fn acl_set_fd ,
110a889d1fbSRobert Watson.Fn acl_set_fd_np
111a889d1fbSRobert Watson
112a889d1fbSRobert WatsonThese funtions are described in
113a889d1fbSRobert Watson.Xr acl_set 3 ,
114a889d1fbSRobert Watsonand may be used to assign an ACL to a file system object.
115a889d1fbSRobert Watson
116a889d1fbSRobert Watson.Fn acl_to_text
117a889d1fbSRobert Watson
118a889d1fbSRobert WatsonThis function is described in
119a889d1fbSRobert Watson.Xr acl_to_text 3 ,
120a889d1fbSRobert Watsonand may be used to generate a text-form of a POSIX.1e semantics ACL.
121a889d1fbSRobert Watson
122a889d1fbSRobert Watson.Fn acl_valid ,
123a889d1fbSRobert Watson.Fn acl_valid_file_np ,
124a889d1fbSRobert Watson.Fn acl_valid_fd_np
125a889d1fbSRobert Watson
126a889d1fbSRobert WatsonThee functions are described in
127a889d1fbSRobert Watson.Xr acl_valid 3 ,
128a889d1fbSRobert Watsonand may be used to validate an ACL as correct POSIX.1e-semantics, or
129a889d1fbSRobert Watsonas appropriate for a particular file system object regardless of semantics.
130a889d1fbSRobert Watson
131a889d1fbSRobert WatsonDocumentation of the internal kernel interfaces backing these calls may
132a889d1fbSRobert Watsonbe found in
133a889d1fbSRobert Watson.Xr acl 9 .
134a889d1fbSRobert WatsonThe syscalls between the internal interfaces and the public library
135a889d1fbSRobert Watsonroutines may change over time, and as such are not documented.  They are
136a889d1fbSRobert Watsonnot intended to be called directly without going through the library.
137a889d1fbSRobert Watson.Sh IMPLEMENTATION NOTES
138a889d1fbSRobert WatsonFreeBSD's support for POSIX.1e interfaces and features is still under
139a889d1fbSRobert Watsondevelopment at this time.
140a889d1fbSRobert Watson.Sh ENVIRONMENT
141a889d1fbSRobert WatsonPOSIX.1e assigns security labels to all objects, extending the security
142a889d1fbSRobert Watsonfunctionality described in POSIX.1.  These additional labels provide
143a889d1fbSRobert Watsonfine-grained discretionary access control, fine-grained capabilities,
144a889d1fbSRobert Watsonand labels necessary for mandatory access control.  POSIX.2c describes
145a889d1fbSRobert Watsona set of userland utilities for manipulating these labels.  These userland
146a889d1fbSRobert Watsonutilities are not bundled with FreeBSD 4.0 so as to discourage their
147a889d1fbSRobert Watsonuse in the short term.
148a889d1fbSRobert Watson.Sh FILES
149a889d1fbSRobert Watson.Sh SEE ALSO
150a889d1fbSRobert Watson.Xr acl 3 ,
151a889d1fbSRobert Watson.Xr acl_dup 3 ,
152a889d1fbSRobert Watson.Xr acl_free 3 ,
153a889d1fbSRobert Watson.Xr acl_from_text 3 ,
154a889d1fbSRobert Watson.Xr acl_get 3 ,
155a889d1fbSRobert Watson.Xr acl_set 3 ,
156a889d1fbSRobert Watson.Xr acl_to_text 3 ,
157a889d1fbSRobert Watson.Xr acl_valid 3 ,
158a889d1fbSRobert Watson.Xr acl 9
159a889d1fbSRobert Watson.Sh STANDARDS
160a889d1fbSRobert WatsonPOSIX.1e is described in IEEE POSIX.1e draft 17.  Discussion
161a889d1fbSRobert Watsonof the draft continues on the cross-platform POSIX.1e implementation
162a889d1fbSRobert Watsonmailing list.  To join this list, see the FreeBSD POSIX.1e implementation
163a889d1fbSRobert Watsonpage for more information.
164a889d1fbSRobert Watson.Sh HISTORY
165a889d1fbSRobert WatsonPOSIX.1e support was introduced in FreeBSD 4.0, and development continues.
166a889d1fbSRobert Watson.Sh AUTHORS
167a889d1fbSRobert WatsonRobert N M Watson
168a889d1fbSRobert Watson.Sh BUGS
169a889d1fbSRobert WatsonThese features are not yet fully implemented.  In particular, the shipped
170a889d1fbSRobert Watsonversion of UFS/FFS does not support storage of additional security labels,
171a889d1fbSRobert Watsonand so is unable to (easily) provide support for most of these features.
172