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