1.\"- 2.\" Copyright (c) 2000, 2001, 2002 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" This software was developed by Robert Watson for the TrustedBSD Project. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd October 30, 2014 31.Dt ACL 3 32.Os 33.Sh NAME 34.Nm acl 35.Nd introduction to the POSIX.1e/NFSv4 ACL security API 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In sys/types.h 40.In sys/acl.h 41.Sh DESCRIPTION 42.Fx 43permits file systems to export Access Control Lists via the VFS, and 44provides a library for userland access to and manipulation of these ACLs. 45.Fx 46supports POSIX.1e and NFSv4 ACLs, but 47not all file systems provide support for ACLs, and some may require that 48ACL support be explicitly enabled by the administrator. 49The library calls include routines to allocate, duplicate, retrieve, set, 50and validate ACLs associated with file objects. 51As well as the POSIX.1e routines, there are a number of non-portable 52extensions defined that allow for ACL semantics alternative to 53POSIX.1e, such as NFSv4. 54Where routines are non-standard, they are suffixed with _np to indicate that 55they are not portable. 56.Pp 57POSIX.1e describes a set of ACL manipulation routines to manage the 58contents of ACLs, as well as their relationships with files; almost 59all of these support routines are implemented in 60.Fx . 61.Pp 62Available functions, sorted by behavior, include: 63.Bl -tag -width indent 64.It Fn acl_add_flag_np 65This function is described in 66.Xr acl_add_flag_np 3 , 67and may be used to add flags to a flagset. 68.It Fn acl_add_perm 69This function is described in 70.Xr acl_add_perm 3 , 71and may be used to add permissions to a permission set. 72.It Fn acl_calc_mask 73This function is described in 74.Xr acl_calc_mask 3 , 75and may be used to calculate and set the permissions associated with 76the 77.Dv ACL_MASK 78entry. 79.It Fn acl_clear_flags_np 80This function is described in 81.Xr acl_clear_flags_np 3 , 82and may be used to clear all flags from a flagset. 83.It Fn acl_clear_perms 84This function is described in 85.Xr acl_clear_perms 3 , 86and may be used to clear all permissions from a permission set. 87.It Fn acl_copy_entry 88This function is described in 89.Xr acl_copy_entry 3 , 90and may be used to copy the contents of an ACL entry. 91.It Xo 92.Fn acl_create_entry , 93.Fn acl_create_entry_np 94.Xc 95These functions are described in 96.Xr acl_create_entry 3 , 97and may be used to create an empty entry in an ACL. 98.It Xo 99.Fn acl_delete_def_file , 100.Fn acl_delete_def_link_np , 101.Fn acl_delete_fd_np , 102.Fn acl_delete_file_np , 103.Fn acl_delete_link_np 104.Xc 105These functions are described in 106.Xr acl_delete 3 , 107and may be used to delete ACLs from file system objects. 108.It Xo 109.Fn acl_delete_entry , 110.Fn acl_delete_entry_np , 111.Xc 112This functions are described in 113.Xr acl_delete_entry 3 , 114and may be used to delete an entry from an ACL. 115.It Fn acl_delete_flag_np 116This function is described in 117.Xr acl_delete_flag_np 3 , 118and may be used to delete flags from a flagset. 119.It Fn acl_delete_perm 120This function is described in 121.Xr acl_delete_perm 3 , 122and may be used to delete permissions from a permset. 123.It Fn acl_dup 124This function is described in 125.Xr acl_dup 3 , 126and may be used to duplicate an ACL structure. 127.It Fn acl_free 128This function is described in 129.Xr acl_free 3 , 130and may be used to free userland working ACL storage. 131.It Fn acl_from_text 132This function is described in 133.Xr acl_from_text 3 , 134and may be used to convert a text-form ACL into working ACL state, if 135the ACL has POSIX.1e or NFSv4 semantics. 136.It Fn acl_get_brand_np 137This function is described in 138.Xr acl_get_brand_np 3 139and may be used to determine whether the ACL has POSIX.1e or NFSv4 semantics. 140.It Fn acl_get_entry 141This function is described in 142.Xr acl_get_entry 3 , 143and may be used to retrieve a designated ACL entry from an ACL. 144.It Xo 145.Fn acl_get_fd , 146.Fn acl_get_fd_np , 147.Fn acl_get_file , 148.Fn acl_get_link_np 149.Xc 150These functions are described in 151.Xr acl_get 3 , 152and may be used to retrieve ACLs from file system objects. 153.It Fn acl_get_entry_type_np 154This function is described in 155.Xr acl_get_entry_type_np 3 , 156and may be used to retrieve an ACL type from an ACL entry. 157.It Fn acl_get_flagset_np 158This function is described in 159.Xr acl_get_flagset_np 3 , 160and may be used to retrieve a flagset from an ACL entry. 161.It Fn acl_get_permset 162This function is described in 163.Xr acl_get_permset 3 , 164and may be used to retrieve a permset from an ACL entry. 165.It Fn acl_get_qualifier 166This function is described in 167.Xr acl_get_qualifier 3 , 168and may be used to retrieve the qualifier from an ACL entry. 169.It Fn acl_get_tag_type 170This function is described in 171.Xr acl_get_tag_type 3 , 172and may be used to retrieve the tag type from an ACL entry. 173.It Fn acl_init 174This function is described in 175.Xr acl_init 3 , 176and may be used to allocate a fresh (empty) ACL structure. 177.It Fn acl_is_trivial_np 178This function is described in 179.Xr acl_is_trivial_np 3 , 180and may be used to find out whether ACL is trivial. 181.It Xo 182.Fn acl_set_fd , 183.Fn acl_set_fd_np , 184.Fn acl_set_file , 185.Fn acl_set_link_np 186.Xc 187These functions are described in 188.Xr acl_set 3 , 189and may be used to assign an ACL to a file system object. 190.It Fn acl_set_entry_type_np 191This function is described in 192.Xr acl_set_entry_type_np 3 , 193and may be used to set the ACL type of an ACL entry. 194.It Fn acl_set_flagset_np 195This function is described in 196.Xr acl_set_flagset_np 3 , 197and may be used to set the flags of an ACL entry from a flagset. 198.It Fn acl_set_permset 199This function is described in 200.Xr acl_set_permset 3 , 201and may be used to set the permissions of an ACL entry from a permset. 202.It Fn acl_set_qualifier 203This function is described in 204.Xr acl_set_qualifier 3 , 205and may be used to set the qualifier of an ACL. 206.It Fn acl_set_tag_type 207This function is described in 208.Xr acl_set_tag_type 3 , 209and may be used to set the tag type of an ACL. 210.It Fn acl_strip_np 211This function is described in 212.Xr acl-strip_np 3 , 213and may be used to remove extended entries from an ACL. 214.It Xo 215.Fn acl_to_text , 216.Fn acl_to_text_np 217.Xc 218These functions are described in 219.Xr acl_to_text 3 , 220and may be used to generate a text-form of a POSIX.1e or NFSv4 semantics ACL. 221.It Xo 222.Fn acl_valid , 223.Fn acl_valid_fd_np , 224.Fn acl_valid_file_np , 225.Fn acl_valid_link_np 226.Xc 227These functions are described in 228.Xr acl_valid 3 , 229and may be used to validate an ACL as correct POSIX.1e-semantics, or 230as appropriate for a particular file system object regardless of semantics. 231.El 232.Pp 233Documentation of the internal kernel interfaces backing these calls may 234be found in 235.Xr acl 9 . 236The syscalls between the internal interfaces and the public library 237routines may change over time, and as such are not documented. 238They are not intended to be called directly without going through the 239library. 240.Sh SEE ALSO 241.Xr getfacl 1 , 242.Xr setfacl 1 , 243.Xr acl_add_flag_np 3 , 244.Xr acl_add_perm 3 , 245.Xr acl_calc_mask 3 , 246.Xr acl_clear_flags_np 3 , 247.Xr acl_clear_perms 3 , 248.Xr acl_copy_entry 3 , 249.Xr acl_create_entry 3 , 250.Xr acl_delete_entry 3 , 251.Xr acl_delete_flag_np 3 , 252.Xr acl_delete_perm 3 , 253.Xr acl_dup 3 , 254.Xr acl_free 3 , 255.Xr acl_from_text 3 , 256.Xr acl_get 3 , 257.Xr acl_get_brand_np 3 , 258.Xr acl_get_entry_type_np 3 , 259.Xr acl_get_flagset_np 3 , 260.Xr acl_get_permset 3 , 261.Xr acl_get_qualifier 3 , 262.Xr acl_get_tag_type 3 , 263.Xr acl_init 3 , 264.Xr acl_is_trivial_np 3 , 265.Xr acl_set 3 , 266.Xr acl_set_entry_type_np 3 , 267.Xr acl_set_flagset_np 3 , 268.Xr acl_set_permset 3 , 269.Xr acl_set_qualifier 3 , 270.Xr acl_set_tag_type 3 , 271.Xr acl_strip_np 3 , 272.Xr acl_to_text 3 , 273.Xr acl_valid 3 , 274.Xr posix1e 3 , 275.Xr acl 9 276.Sh STANDARDS 277POSIX.1e assigns security labels to all objects, extending the security 278functionality described in POSIX.1. 279These additional labels provide fine-grained discretionary access control, 280fine-grained capabilities, and labels necessary for mandatory access 281control. 282POSIX.2c describes a set of userland utilities for manipulating these 283labels. 284.Pp 285POSIX.1e is described in IEEE POSIX.1e draft 17. 286Discussion of the draft continues on the cross-platform POSIX.1e 287implementation mailing list. 288To join this list, see the 289.Fx 290POSIX.1e implementation page for more information. 291.Sh HISTORY 292POSIX.1e support was introduced in 293.Fx 4.0 ; 294.Fx 5.0 295was the first version to include a complete ACL implementation based 296on extended attributes for the UFS and UFS2 file systems. 297NFSv4 ACL support was introduced in 298.Fx 8.0 . 299.Pp 300The 301.Xr getfacl 1 302and 303.Xr setfacl 1 304utilities describe the user tools that permit direct manipulation of complete 305file ACLs. 306.Sh AUTHORS 307.An Robert N M Watson 308