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_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
44 Streaming Archive Library (libarchive, -larchive)
48 .Fo archive_entry_acl_add_entry
49 .Fa "struct archive_entry *a"
54 .Fa "const char *name"
57 .Fo archive_entry_acl_add_entry_w
58 .Fa "struct archive_entry *a"
63 .Fa "const wchar_t *name"
66 .Fn archive_entry_acl_clear "struct archive_entry *a"
68 .Fn archive_entry_acl_count "struct archive_entry *a" "int type"
70 .Fo archive_entry_acl_from_text
71 .Fa "struct archive_entry *a"
72 .Fa "const char *text"
76 .Fo archive_entry_acl_from_text_w
77 .Fa "struct archive_entry *a"
78 .Fa "const wchar_t *text"
82 .Fo archive_entry_acl_next
83 .Fa "struct archive_entry *a"
86 .Fa "int *ret_permset"
89 .Fa "const char **ret_name"
92 .Fo archive_entry_acl_next_w
93 .Fa "struct archive_entry *a"
96 .Fa "int *ret_permset"
99 .Fa "const wchar_t **ret_name"
102 .Fn archive_entry_acl_reset "struct archive_entry *a" "int type"
104 .Fo archive_entry_acl_to_text
105 .Fa "struct archive_entry *a"
110 .Fo archive_entry_acl_to_text_w
111 .Fa "struct archive_entry *a"
116 .Fn archive_entry_acl_types "struct archive_entry *a"
120 .Dq Access Control Lists (ACLs)
121 extend the standard Unix perssion model.
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
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
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 )
138 The permissions correspond to the normal Unix permissions.
142 specifies the principal to which the permission applies.
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.
160 .Dv ARCHIVE_ENTRY_ACL_USER_OBJ ,
161 .Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ
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.
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
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
192 specifies the principal to which the permission applies.
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.
208 .Dv ARCHIVE_ENTRY_ACL_USER
210 .Dv ARCHIVE_ENTRY_ACL_GROUP
211 tag store the user and group name in the
213 string and optionally the user or group ID in the
217 NFSv4 ACE permissions and flags are stored in the same
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 )
225 .It Dv ARCHIVE_ENTRY_ACL_LIST_DIRECTORY ( Sy r )
226 List entries (directory).
227 .It ARCHIVE_ENTRY_ACL_WRITE_DATA ( Sy w )
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 )
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 )
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.
277 .Fn archive_entry_acl_add_entry
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
285 .Fn archive_entry_acl_clear
286 removes all ACL entries and resets the enumeration pointer.
288 .Fn archive_entry_acl_count
289 counts the ACL entries that have the given type mask.
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
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
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.
308 .Fn archive_entry_acl_from_text
310 .Fn archive_entry_acl_from_text_w
312 .Pq or merge with existing
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
323 Supports all formats that can be created with
324 .Fn archive_entry_acl_to_text
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
332 .Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
336 .Dv ARCHIVE_ENTRY_ACL_TYPE_NFS4 .
337 Invalid entries, non-parseable ACL entries and entries beginning with
344 .Fn archive_entry_acl_next
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.
352 .Fn archive_entry_acl_reset
353 prepare reading the list of ACL entries with
354 .Fn archive_entry_acl_next
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
362 Otherwise, the function returns the same value as
363 .Fn archive_entry_acl_count .
365 .Fn archive_entry_acl_to_text
367 .Fn archive_entry_acl_to_text_w
368 convert the ACL entries for the given type into a
370 string of ACL entries separated by newline. If the pointer
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
378 argument is a bitwise-or.
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
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
389 .It Dv ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
390 The mask and other ACLs don not contain a double colon.
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.
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.
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
412 .Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
413 are specified, both access and default entries are returned and default entries
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.
422 .Fn archive_entry_acl_count
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.
431 .Fn archive_entry_acl_from_text
433 .Fn archive_entry_acl_from_text_w
436 if all entries were successfully parsed and
438 if one or more entries were invalid or non-parseable.
440 .Fn archive_entry_acl_next
442 .Fn archive_entry_acl_next_w
447 if no more ACL entries exist
451 .Fn archive_entry_acl_reset
452 has not been called first.
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.
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.
462 .Fn archive_entry_acl_types
463 returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries.
465 .Xr archive_entry 3 ,