1 .\" Copyright (c) 2010 Joerg Sonnenberger
2 .\" Copyright (c) 2016 Martin Matuska
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
27 .Dt ARCHIVE_ENTRY_ACL 3
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
43 Streaming Archive Library (libarchive, -larchive)
47 .Fo archive_entry_acl_add_entry
48 .Fa "struct archive_entry *a"
53 .Fa "const char *name"
56 .Fo archive_entry_acl_add_entry_w
57 .Fa "struct archive_entry *a"
62 .Fa "const wchar_t *name"
65 .Fn archive_entry_acl_clear "struct archive_entry *a"
67 .Fn archive_entry_acl_count "struct archive_entry *a" "int type"
69 .Fo archive_entry_acl_from_text
70 .Fa "struct archive_entry *a"
71 .Fa "const char *text"
75 .Fo archive_entry_acl_from_text_w
76 .Fa "struct archive_entry *a"
77 .Fa "const wchar_t *text"
81 .Fo archive_entry_acl_next
82 .Fa "struct archive_entry *a"
85 .Fa "int *ret_permset"
88 .Fa "const char **ret_name"
91 .Fn archive_entry_acl_reset "struct archive_entry *a" "int type"
93 .Fo archive_entry_acl_to_text
94 .Fa "struct archive_entry *a"
99 .Fo archive_entry_acl_to_text_w
100 .Fa "struct archive_entry *a"
105 .Fn archive_entry_acl_types "struct archive_entry *a"
109 .Dq Access Control Lists (ACLs)
110 extend the standard Unix permission model.
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
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
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 )
128 The permissions correspond to the normal Unix permissions.
132 specifies the principal to which the permission applies.
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.
150 .Dv ARCHIVE_ENTRY_ACL_USER_OBJ ,
151 .Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ
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.
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
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
182 specifies the principal to which the permission applies.
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.
198 .Dv ARCHIVE_ENTRY_ACL_USER
200 .Dv ARCHIVE_ENTRY_ACL_GROUP
201 tag store the user and group name in the
203 string and optionally the user or group ID in the
207 NFSv4 ACE permissions and flags are stored in the same
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 )
216 .It Dv ARCHIVE_ENTRY_ACL_LIST_DIRECTORY ( Sy r )
217 List entries (directory).
218 .It ARCHIVE_ENTRY_ACL_WRITE_DATA ( Sy w )
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 )
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 )
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.
269 .Fn archive_entry_acl_add_entry
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
275 An archive entry cannot contain both POSIX.1e and NFSv4 ACL entries.
277 .Fn archive_entry_acl_clear
278 removes all ACL entries and resets the enumeration pointer.
280 .Fn archive_entry_acl_count
281 counts the ACL entries that have the given type mask.
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
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
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.
301 .Fn archive_entry_acl_from_text
303 .Fn archive_entry_acl_from_text_w
305 .Pq or merge with existing
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
317 Supports all formats that can be created with
318 .Fn archive_entry_acl_to_text
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
328 .Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
332 .Dv ARCHIVE_ENTRY_ACL_TYPE_NFS4 .
333 Invalid entries, non-parseable ACL entries and entries beginning with
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.
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
354 Otherwise, the function returns the same value as
355 .Fn archive_entry_acl_count .
357 .Fn archive_entry_acl_to_text
359 .Fn archive_entry_acl_to_text_w
360 convert the ACL entries for the given type into a
362 string of ACL entries separated by newline.
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
371 argument is a bitwise-or.
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
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
382 .It Dv ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
383 The mask and other ACLs don not contain a double colon.
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.
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.
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
405 .Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
406 are specified, both access and default entries are returned and default entries
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.
416 .Fn archive_entry_acl_count
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.
425 .Fn archive_entry_acl_from_text
427 .Fn archive_entry_acl_from_text_w
430 if all entries were successfully parsed and
432 if one or more entries were invalid or non-parseable.
434 .Fn archive_entry_acl_next
439 if no more ACL entries exist
443 .Fn archive_entry_acl_reset
444 has not been called first.
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.
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.
454 .Fn archive_entry_acl_types
455 returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries.
457 .Xr archive_entry 3 ,