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