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