contrib/libarchive/libarchive/archive_entry_acl.3

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