acl.3 revision 59514
-
Copyright (c) 2000 Robert N. M. Watson
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
$FreeBSD: head/lib/libc/posix1e/acl.3 59514 2000-04-22 16:13:36Z phantom $
.Dd January 28, 2000 .Dt ACL 3 .Os FreeBSD 4.0 .Sh NAME .Nm acl .Nd introduction to the POSIX.1e ACL security API .Sh LIBRARY .Lb libposix1e .Sh SYNOPSIS .Fd #include <sys/types.h> .Fd #include <sys/acl.h> .Sh DESCRIPTION As shipped, .Fx 4.0 permits file systems to export Access Control Lists via the VFS, and provides a library for userland access to and manipulation of these ACLs, but support for ACLs is not provided by any file systems shipped in the base operating system. The library calls shipped with 4.0 include routines to allocate, duplicate, retrieve, set, and validate ACLs associated with file objects. As well as the POSIX.1e routines, there are a number of non-portable extensions defined that allow for alternative ACL semantics than the POSIX.1e semantics, such as AFS, NTFS, Coda, and NWFS semantics. Where routines are non-standard, they are suffixed with _np to indicate that they are not portable. POSIX.1e describes a set of ACL manipulation routines to manage the contents of ACLs, as well as their relationships with files. This manipulation library is not currently implemented in FreeBSD, although a third party library was under development at the time this document was written. There is a general consensus that the POSIX.1e manipulation routines are ambiguously defined in the specification, and don't meet the needs of most applications. For the time being, applications may directly manipulate the ACL structures, defined in acl.h, although the recommended usage is to only ever handle text-form ACLs in applications, generated and maintained using .Fn acl_from_text and .Fn acl_to_text , passed directly to and from the management routines. In this manner, an application can remain safely unaware of the contents of ACLs. Available functions, sorted by behavior, include: .Fn acl_delete_def_file , .Fn acl_delete_file_np , .Fn acl_delete_fd_np These functions are described in .Xr acl_delete 3 , and may be used to delete ACLs from file system objects. .Fn acl_free This function is described in .Xr acl_free 3 , and may be used to free userland working ACL storage. .Fn acl_from_text This function is described in .Xr acl_from_text 3 , and may be used to convert a text-form ACL into working ACL state, if the ACL has POSIX.1e semantics. .Fn acl_get_file , .Fn acl_get_fd , .Fn acl_get_fd_np These functions are described in .Xr acl_get 3 , and may be used to retrieve ACLs from file system objects. .Fn acl_init This function is described in .Xr acl_init 3 , and may be used to allocate a fresh (empty) ACL structure. .Fn acl_dup This function is described in .Xr acl_dup 3 , and may be used to duplicate an ACL structure. .Fn acl_set_file , .Fn acl_set_fd , .Fn acl_set_fd_np These functions are described in .Xr acl_set 3 , and may be used to assign an ACL to a file system object. .Fn acl_to_text This function is described in .Xr acl_to_text 3 , and may be used to generate a text-form of a POSIX.1e semantics ACL. .Fn acl_valid , .Fn acl_valid_file_np , .Fn acl_valid_fd_np Thee functions are described in .Xr acl_valid 3 , and may be used to validate an ACL as correct POSIX.1e-semantics, or as appropriate for a particular file system object regardless of semantics. Documentation of the internal kernel interfaces backing these calls may be found in .Xr acl 9 . The syscalls between the internal interfaces and the public library routines may change over time, and as such are not documented. They are not intended to be called directly without going through the library. .Sh IMPLEMENTATION NOTES FreeBSD's support for POSIX.1e interfaces and features is still under development at this time. .Sh ENVIRONMENT POSIX.1e assigns security labels to all objects, extending the security functionality described in POSIX.1. These additional labels provide fine-grained discretionary access control, fine-grained capabilities, and labels necessary for mandatory access control. POSIX.2c describes a set of userland utilities for manipulating these labels. These userland utilities are not bundled with .Fx 4.0 so as to discourage their use in the short term. .Sh FILES
.Sh SEE ALSO .Xr acl 3 , .Xr acl_dup 3 , .Xr acl_free 3 , .Xr acl_from_text 3 , .Xr acl_get 3 , .Xr acl_set 3 , .Xr acl_to_text 3 , .Xr acl_valid 3 , .Xr acl 9 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion of the draft continues on the cross-platform POSIX.1e implementation mailing list. To join this list, see the .Fx POSIX.1e implementation page for more information. .Sh HISTORY POSIX.1e support was introduced in .Fx 4.0 , and development continues. .Sh AUTHORS .An Robert N M Watson .Sh BUGS These features are not yet fully implemented. In particular, the shipped version of UFS/FFS does not support storage of additional security labels, and so is unable to (easily) provide support for most of these features.
Copyright (c) 2000 Robert N. M. Watson
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
$FreeBSD: head/lib/libc/posix1e/acl.3 59514 2000-04-22 16:13:36Z phantom $
.Dd January 28, 2000 .Dt ACL 3 .Os FreeBSD 4.0 .Sh NAME .Nm acl .Nd introduction to the POSIX.1e ACL security API .Sh LIBRARY .Lb libposix1e .Sh SYNOPSIS .Fd #include <sys/types.h> .Fd #include <sys/acl.h> .Sh DESCRIPTION As shipped, .Fx 4.0 permits file systems to export Access Control Lists via the VFS, and provides a library for userland access to and manipulation of these ACLs, but support for ACLs is not provided by any file systems shipped in the base operating system. The library calls shipped with 4.0 include routines to allocate, duplicate, retrieve, set, and validate ACLs associated with file objects. As well as the POSIX.1e routines, there are a number of non-portable extensions defined that allow for alternative ACL semantics than the POSIX.1e semantics, such as AFS, NTFS, Coda, and NWFS semantics. Where routines are non-standard, they are suffixed with _np to indicate that they are not portable. POSIX.1e describes a set of ACL manipulation routines to manage the contents of ACLs, as well as their relationships with files. This manipulation library is not currently implemented in FreeBSD, although a third party library was under development at the time this document was written. There is a general consensus that the POSIX.1e manipulation routines are ambiguously defined in the specification, and don't meet the needs of most applications. For the time being, applications may directly manipulate the ACL structures, defined in acl.h, although the recommended usage is to only ever handle text-form ACLs in applications, generated and maintained using .Fn acl_from_text and .Fn acl_to_text , passed directly to and from the management routines. In this manner, an application can remain safely unaware of the contents of ACLs. Available functions, sorted by behavior, include: .Fn acl_delete_def_file , .Fn acl_delete_file_np , .Fn acl_delete_fd_np These functions are described in .Xr acl_delete 3 , and may be used to delete ACLs from file system objects. .Fn acl_free This function is described in .Xr acl_free 3 , and may be used to free userland working ACL storage. .Fn acl_from_text This function is described in .Xr acl_from_text 3 , and may be used to convert a text-form ACL into working ACL state, if the ACL has POSIX.1e semantics. .Fn acl_get_file , .Fn acl_get_fd , .Fn acl_get_fd_np These functions are described in .Xr acl_get 3 , and may be used to retrieve ACLs from file system objects. .Fn acl_init This function is described in .Xr acl_init 3 , and may be used to allocate a fresh (empty) ACL structure. .Fn acl_dup This function is described in .Xr acl_dup 3 , and may be used to duplicate an ACL structure. .Fn acl_set_file , .Fn acl_set_fd , .Fn acl_set_fd_np These functions are described in .Xr acl_set 3 , and may be used to assign an ACL to a file system object. .Fn acl_to_text This function is described in .Xr acl_to_text 3 , and may be used to generate a text-form of a POSIX.1e semantics ACL. .Fn acl_valid , .Fn acl_valid_file_np , .Fn acl_valid_fd_np Thee functions are described in .Xr acl_valid 3 , and may be used to validate an ACL as correct POSIX.1e-semantics, or as appropriate for a particular file system object regardless of semantics. Documentation of the internal kernel interfaces backing these calls may be found in .Xr acl 9 . The syscalls between the internal interfaces and the public library routines may change over time, and as such are not documented. They are not intended to be called directly without going through the library. .Sh IMPLEMENTATION NOTES FreeBSD's support for POSIX.1e interfaces and features is still under development at this time. .Sh ENVIRONMENT POSIX.1e assigns security labels to all objects, extending the security functionality described in POSIX.1. These additional labels provide fine-grained discretionary access control, fine-grained capabilities, and labels necessary for mandatory access control. POSIX.2c describes a set of userland utilities for manipulating these labels. These userland utilities are not bundled with .Fx 4.0 so as to discourage their use in the short term. .Sh FILES
.Sh SEE ALSO .Xr acl 3 , .Xr acl_dup 3 , .Xr acl_free 3 , .Xr acl_from_text 3 , .Xr acl_get 3 , .Xr acl_set 3 , .Xr acl_to_text 3 , .Xr acl_valid 3 , .Xr acl 9 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion of the draft continues on the cross-platform POSIX.1e implementation mailing list. To join this list, see the .Fx POSIX.1e implementation page for more information. .Sh HISTORY POSIX.1e support was introduced in .Fx 4.0 , and development continues. .Sh AUTHORS .An Robert N M Watson .Sh BUGS These features are not yet fully implemented. In particular, the shipped version of UFS/FFS does not support storage of additional security labels, and so is unable to (easily) provide support for most of these features.