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