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