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