1.\" Copyright (c) 2010 Joerg Sonnenberger 2.\" Copyright (c) 2016 Martin Matuska 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd February 15, 2017 27.Dt ARCHIVE_ENTRY_ACL 3 28.Os 29.Sh NAME 30.Nm archive_entry_acl_add_entry , 31.Nm archive_entry_acl_add_entry_w , 32.Nm archive_entry_acl_clear , 33.Nm archive_entry_acl_count , 34.Nm archive_entry_acl_from_text , 35.Nm archive_entry_acl_from_text_w , 36.Nm archive_entry_acl_next , 37.Nm archive_entry_acl_reset , 38.Nm archive_entry_acl_to_text , 39.Nm archive_entry_acl_to_text_w , 40.Nm archive_entry_acl_types 41.Nd functions for manipulating Access Control Lists in archive entry descriptions 42.Sh LIBRARY 43Streaming Archive Library (libarchive, -larchive) 44.Sh SYNOPSIS 45.In archive_entry.h 46.Ft void 47.Fo archive_entry_acl_add_entry 48.Fa "struct archive_entry *a" 49.Fa "int type" 50.Fa "int permset" 51.Fa "int tag" 52.Fa "int qualifier" 53.Fa "const char *name" 54.Fc 55.Ft void 56.Fo archive_entry_acl_add_entry_w 57.Fa "struct archive_entry *a" 58.Fa "int type" 59.Fa "int permset" 60.Fa "int tag" 61.Fa "int qualifier" 62.Fa "const wchar_t *name" 63.Fc 64.Ft void 65.Fn archive_entry_acl_clear "struct archive_entry *a" 66.Ft int 67.Fn archive_entry_acl_count "struct archive_entry *a" "int type" 68.Ft int 69.Fo archive_entry_acl_from_text 70.Fa "struct archive_entry *a" 71.Fa "const char *text" 72.Fa "int type" 73.Fc 74.Ft int 75.Fo archive_entry_acl_from_text_w 76.Fa "struct archive_entry *a" 77.Fa "const wchar_t *text" 78.Fa "int type" 79.Fc 80.Ft int 81.Fo archive_entry_acl_next 82.Fa "struct archive_entry *a" 83.Fa "int type" 84.Fa "int *ret_type" 85.Fa "int *ret_permset" 86.Fa "int *ret_tag" 87.Fa "int *ret_qual" 88.Fa "const char **ret_name" 89.Fc 90.Ft int 91.Fn archive_entry_acl_reset "struct archive_entry *a" "int type" 92.Ft char * 93.Fo archive_entry_acl_to_text 94.Fa "struct archive_entry *a" 95.Fa "ssize_t *len_p" 96.Fa "int flags" 97.Fc 98.Ft wchar_t * 99.Fo archive_entry_acl_to_text_w 100.Fa "struct archive_entry *a" 101.Fa "ssize_t *len_p" 102.Fa "int flags" 103.Fc 104.Ft int 105.Fn archive_entry_acl_types "struct archive_entry *a" 106.\" enum? 107.Sh DESCRIPTION 108The 109.Dq Access Control Lists (ACLs) 110extend the standard Unix permission model. 111The ACL interface of 112.Nm libarchive 113supports both POSIX.1e and NFSv4 style ACLs. 114Use of ACLs is restricted by 115various levels of ACL support in operating systems, file systems and archive 116formats. 117.Ss POSIX.1e Access Control Lists 118A POSIX.1e ACL consists of a number of independent entries. 119Each entry specifies the permission set as a bitmask of basic permissions. 120Valid permissions in the 121.Fa permset 122are: 123.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_EXECUTE" 124.It Dv ARCHIVE_ENTRY_ACL_READ ( Sy r ) 125.It Dv ARCHIVE_ENTRY_ACL_WRITE ( Sy w ) 126.It Dv ARCHIVE_ENTRY_ACL_EXECUTE ( Sy x ) 127.El 128The permissions correspond to the normal Unix permissions. 129.Pp 130The 131.Fa tag 132specifies the principal to which the permission applies. 133Valid values are: 134.Bl -hang -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ" 135.It Dv ARCHIVE_ENTRY_ACL_USER 136The user specified by the name field. 137.It Dv ARCHIVE_ENTRY_ACL_USER_OBJ 138The owner of the file. 139.It Dv ARCHIVE_ENTRY_ACL_GROUP 140The group specified by the name field. 141.It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ 142The group which owns the file. 143.It Dv ARCHIVE_ENTRY_ACL_MASK 144The maximum permissions to be obtained via group permissions. 145.It Dv ARCHIVE_ENTRY_ACL_OTHER 146Any principal who is not the file owner or a member of the owning group. 147.El 148.Pp 149The principals 150.Dv ARCHIVE_ENTRY_ACL_USER_OBJ , 151.Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ 152and 153.Dv ARCHIVE_ENTRY_ACL_OTHER 154are equivalent to user, group and other in the classic Unix permission 155model and specify non-extended ACL entries. 156.Pp 157All files have an access ACL 158.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS . 159This specifies the permissions required for access to the file itself. 160Directories have an additional ACL 161.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT , 162which controls the initial access ACL for newly-created directory entries. 163.Ss NFSv4 Access Control Lists 164A NFSv4 ACL consists of multiple individual entries called Access Control 165Entries (ACEs). 166.Pp 167There are four possible types of a NFSv4 ACE: 168.Bl -hang -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYE_ALLOW" 169.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALLOW 170Allow principal to perform actions requiring given permissions. 171.It Dv ARCHIVE_ENTRY_ACL_TYPE_DENY 172Prevent principal from performing actions requiring given permissions. 173.It Dv ARCHIVE_ENTRY_ACL_TYPE_AUDIT 174Log access attempts by principal which require given permissions. 175.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALARM 176Trigger a system alarm on access attempts by principal which require given 177permissions. 178.El 179.Pp 180The 181.Fa tag 182specifies the principal to which the permission applies. 183Valid values are: 184.Bl -hang -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ" 185.It Dv ARCHIVE_ENTRY_ACL_USER 186The user specified by the name field. 187.It Dv ARCHIVE_ENTRY_ACL_USER_OBJ 188The owner of the file. 189.It Dv ARCHIVE_ENTRY_ACL_GROUP 190The group specified by the name field. 191.It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ 192The group which owns the file. 193.It Dv ARCHIVE_ENTRY_ACL_EVERYONE 194Any principal who is not the file owner or a member of the owning group. 195.El 196.Pp 197Entries with the 198.Dv ARCHIVE_ENTRY_ACL_USER 199or 200.Dv ARCHIVE_ENTRY_ACL_GROUP 201tag store the user and group name in the 202.Fa name 203string and optionally the user or group ID in the 204.Fa qualifier 205integer. 206.Pp 207NFSv4 ACE permissions and flags are stored in the same 208.Fa permset 209bitfield. 210Some permissions share the same constant and permission character 211but have different effect on directories than on files. 212The following ACE permissions are supported: 213.Bl -tag -offset indent -compact -width ARCHIV 214.It Dv ARCHIVE_ENTRY_ACL_READ_DATA ( Sy r ) 215Read data (file). 216.It Dv ARCHIVE_ENTRY_ACL_LIST_DIRECTORY ( Sy r ) 217List entries (directory). 218.It ARCHIVE_ENTRY_ACL_WRITE_DATA ( Sy w ) 219Write data (file). 220.It ARCHIVE_ENTRY_ACL_ADD_FILE ( Sy w ) 221Create files (directory). 222.It Dv ARCHIVE_ENTRY_ACL_EXECUTE ( Sy x ) 223Execute file or change into a directory. 224.It Dv ARCHIVE_ENTRY_ACL_APPEND_DATA ( Sy p ) 225Append data (file). 226.It Dv ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY ( Sy p ) 227Create subdirectories (directory). 228.It Dv ARCHIVE_ENTRY_ACL_DELETE_CHILD ( Sy D ) 229Remove files and subdirectories inside a directory. 230.It Dv ARCHIVE_ENTRY_ACL_DELETE ( Sy d ) 231Remove file or directory. 232.It Dv ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES ( Sy a ) 233Read file or directory attributes. 234.It Dv ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES ( Sy A ) 235Write file or directory attributes. 236.It Dv ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS ( Sy R ) 237Read named file or directory attributes. 238.It Dv ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS ( Sy W ) 239Write named file or directory attributes. 240.It Dv ARCHIVE_ENTRY_ACL_READ_ACL ( Sy c ) 241Read file or directory ACL. 242.It Dv ARCHIVE_ENTRY_ACL_WRITE_ACL ( Sy C ) 243Write file or directory ACL. 244.It Dv ARCHIVE_ENTRY_ACL_WRITE_OWNER ( Sy o ) 245Change owner of a file or directory. 246.It Dv ARCHIVE_ENTRY_ACL_SYNCHRONIZE ( Sy s ) 247Use synchronous I/O. 248.El 249.Pp 250The following NFSv4 ACL inheritance flags are supported: 251.Bl -tag -offset indent -compact -width ARCHIV 252.It Dv ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT ( Sy f ) 253Inherit parent directory ACE to files. 254.It Dv ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT ( Sy d ) 255Inherit parent directory ACE to subdirectories. 256.It Dv ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY ( Sy i ) 257Only inherit, do not apply the permission on the directory itself. 258.It Dv ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT ( Sy n ) 259Do not propagate inherit flags. 260Only first-level entries inherit ACLs. 261.It Dv ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS ( Sy S ) 262Trigger alarm or audit on successful access. 263.It Dv ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS ( Sy F ) 264Trigger alarm or audit on failed access. 265.It Dv ARCHIVE_ENTRY_ACL_ENTRY_INHERITED ( Sy I ) 266Mark that ACE was inherited. 267.El 268.Ss Functions 269.Fn archive_entry_acl_add_entry 270and 271.Fn archive_entry_acl_add_entry_w 272add a single ACL entry. 273For the access ACL and non-extended principals, the classic Unix permissions 274are updated. 275An archive entry cannot contain both POSIX.1e and NFSv4 ACL entries. 276.Pp 277.Fn archive_entry_acl_clear 278removes all ACL entries and resets the enumeration pointer. 279.Pp 280.Fn archive_entry_acl_count 281counts the ACL entries that have the given type mask. 282.Fa type 283can be the bitwise-or of 284.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYPE_DEFAULT" 285.It Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 286.It Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 287.El 288for POSIX.1e ACLs and 289.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYPE_ALLOW" 290.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALLOW 291.It Dv ARCHIVE_ENTRY_ACL_TYPE_DENY 292.It Dv ARCHIVE_ENTRY_ACL_TYPE_AUDIT 293.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALARM 294.El 295for NFSv4 ACLs. 296For POSIX.1e ACLs if 297.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 298is included and at least one extended ACL entry is found, 299the three non-extended ACLs are added. 300.Pp 301.Fn archive_entry_acl_from_text 302and 303.Fn archive_entry_acl_from_text_w 304add new 305.Pq or merge with existing 306ACL entries from 307.Pq wide 308text. 309The argument 310.Fa type 311may take one of the following values: 312.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYPE_DEFAULT" 313.It Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 314.It Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 315.It Dv ARCHIVE_ENTRY_ACL_TYPE_NFS4 316.El 317Supports all formats that can be created with 318.Fn archive_entry_acl_to_text 319or respectively 320.Fn archive_entry_acl_to_text_w . 321Existing ACL entries are preserved. 322To get a clean new ACL from text 323.Fn archive_entry_acl_clear 324must be called first. 325Entries prefixed with 326.Dq default: 327are treated as 328.Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 329unless 330.Fa type 331is 332.Dv ARCHIVE_ENTRY_ACL_TYPE_NFS4 . 333Invalid entries, non-parseable ACL entries and entries beginning with 334the 335.Sq # 336character 337.Pq comments 338are skipped. 339.Pp 340.Fn archive_entry_acl_next 341return the next entry of the ACL list. 342This functions may only be called after 343.Fn archive_entry_acl_reset 344has indicated the presence of extended ACL entries. 345.Pp 346.Fn archive_entry_acl_reset 347prepare reading the list of ACL entries with 348.Fn archive_entry_acl_next . 349The function returns 0 if no non-extended ACLs are found. 350In this case, the access permissions should be obtained by 351.Xr archive_entry_mode 3 352or set using 353.Xr chmod 2 . 354Otherwise, the function returns the same value as 355.Fn archive_entry_acl_count . 356.Pp 357.Fn archive_entry_acl_to_text 358and 359.Fn archive_entry_acl_to_text_w 360convert the ACL entries for the given type into a 361.Pq wide 362string of ACL entries separated by newline. 363If the pointer 364.Fa len_p 365is not NULL, then the function shall return the length of the string 366.Pq not including the NULL terminator 367in the location pointed to by 368.Fa len_p . 369The 370.Fa flag 371argument is a bitwise-or. 372.Pp 373The following flags are effective only on POSIX.1e ACL: 374.Bl -tag -offset indent -compact -width ARCHIV 375.It Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 376Output access ACLs. 377.It Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 378Output POSIX.1e default ACLs. 379.It Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT 380Prefix each default ACL entry with the word 381.Dq default: . 382.It Dv ARCHIVE_ENTRY_ACL_STYLE_SOLARIS 383The mask and other ACLs don not contain a double colon. 384.El 385.Pp 386The following flags are effecive only on NFSv4 ACL: 387.Bl -tag -offset indent -compact -width ARCHIV 388.It Dv ARCHIVE_ENTRY_ACL_STYLE_COMPACT 389Do not output minus characters for unset permissions and flags in NFSv4 ACL 390permission and flag fields. 391.El 392.Pp 393The following flags are effective on both POSIX.1e and NFSv4 ACL: 394.Bl -tag -offset indent -compact -width ARCHIV 395.It Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID 396Add an additional colon-separated field containing the user or group id. 397.It Dv ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA 398Separate ACL entries with comma instead of newline. 399.El 400.Pp 401If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are returned. 402It the entry contains POSIX.1e ACLs and none of the flags 403.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 404or 405.Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT 406are specified, both access and default entries are returned and default entries 407are prefixed with 408.Dq default: . 409.Pp 410.Fn archive_entry_acl_types 411get ACL entry types contained in an archive entry's ACL. 412As POSIX.1e and NFSv4 413ACL entries cannot be mixed, this function is a very efficient way to detect if 414an ACL already contains POSIX.1e or NFSv4 ACL entries. 415.Sh RETURN VALUES 416.Fn archive_entry_acl_count 417and 418.Fn archive_entry_acl_reset 419returns the number of ACL entries that match the given type mask. 420For POSIX.1e ACLS if the type mask includes 421.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS 422and at least one extended ACL entry exists, the three classic Unix 423permissions are counted. 424.Pp 425.Fn archive_entry_acl_from_text 426and 427.Fn archive_entry_acl_from_text_w 428return 429.Dv ARCHIVE_OK 430if all entries were successfully parsed and 431.Dv ARCHIVE_WARN 432if one or more entries were invalid or non-parseable. 433.Pp 434.Fn archive_entry_acl_next 435returns 436.Dv ARCHIVE_OK 437on success, 438.Dv ARCHIVE_EOF 439if no more ACL entries exist 440and 441.Dv ARCHIVE_WARN 442if 443.Fn archive_entry_acl_reset 444has not been called first. 445.Pp 446.Fn archive_entry_acl_to_text 447returns a string representing the ACL entries matching the given type and 448flags on success or NULL on error. 449.Pp 450.Fn archive_entry_acl_to_text_w 451returns a wide string representing the ACL entries matching the given type 452and flags on success or NULL on error. 453.Pp 454.Fn archive_entry_acl_types 455returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries. 456.Sh SEE ALSO 457.Xr archive_entry 3 , 458.Xr libarchive 3 459