diff --git a/lib/libc/posix1e/acl.3 b/lib/libc/posix1e/acl.3 index c74b92028c6d..4c5f232a2e6a 100644 --- a/lib/libc/posix1e/acl.3 +++ b/lib/libc/posix1e/acl.3 @@ -1,310 +1,305 @@ .\"- .\" Copyright (c) 2000, 2001, 2002 Robert N. M. Watson .\" All rights reserved. .\" .\" This software was developed by Robert Watson for the TrustedBSD Project. .\" .\" 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. .\" -.Dd May 8, 2023 +.Dd September 21, 2023 .Dt ACL 3 .Os .Sh NAME .Nm acl .Nd introduction to the POSIX.1e/NFSv4 ACL security API .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/acl.h .Sh DESCRIPTION .Fx permits file systems to export Access Control Lists via the VFS, and provides a library for userland access to and manipulation of these ACLs. .Fx supports POSIX.1e and NFSv4 ACLs, but not all file systems provide support for ACLs, and some may require that ACL support be explicitly enabled by the administrator. The library calls 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 ACL semantics alternative to POSIX.1e, such as NFSv4. Where routines are non-standard, they are suffixed with _np to indicate that they are not portable. .Pp POSIX.1e describes a set of ACL manipulation routines to manage the contents of ACLs, as well as their relationships with files; almost all of these support routines are implemented in .Fx . .Pp Available functions, sorted by behavior, include: .Bl -tag -width indent .It Fn acl_add_flag_np This function is described in .Xr acl_add_flag_np 3 , and may be used to add flags to a flagset. .It Fn acl_add_perm This function is described in .Xr acl_add_perm 3 , and may be used to add permissions to a permission set. .It Fn acl_calc_mask This function is described in .Xr acl_calc_mask 3 , and may be used to calculate and set the permissions associated with the .Dv ACL_MASK entry. .It Fn acl_clear_flags_np This function is described in .Xr acl_clear_flags_np 3 , and may be used to clear all flags from a flagset. .It Fn acl_clear_perms This function is described in .Xr acl_clear_perms 3 , and may be used to clear all permissions from a permission set. .It Fn acl_copy_entry This function is described in .Xr acl_copy_entry 3 , and may be used to copy the contents of an ACL entry. .It Xo .Fn acl_create_entry , .Fn acl_create_entry_np .Xc These functions are described in .Xr acl_create_entry 3 , and may be used to create an empty entry in an ACL. .It Xo .Fn acl_delete_def_file , .Fn acl_delete_def_link_np , .Fn acl_delete_fd_np , .Fn acl_delete_file_np , .Fn acl_delete_link_np .Xc These functions are described in .Xr acl_delete 3 , and may be used to delete ACLs from file system objects. .It Xo .Fn acl_delete_entry , .Fn acl_delete_entry_np , .Xc This functions are described in .Xr acl_delete_entry 3 , and may be used to delete an entry from an ACL. .It Fn acl_delete_flag_np This function is described in .Xr acl_delete_flag_np 3 , and may be used to delete flags from a flagset. .It Fn acl_delete_perm This function is described in .Xr acl_delete_perm 3 , and may be used to delete permissions from a permset. .It Fn acl_dup This function is described in .Xr acl_dup 3 , and may be used to duplicate an ACL structure. .It Fn acl_free This function is described in .Xr acl_free 3 , and may be used to free userland working ACL storage. .It 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 or NFSv4 semantics. .It Fn acl_get_brand_np This function is described in .Xr acl_get_brand_np 3 and may be used to determine whether the ACL has POSIX.1e or NFSv4 semantics. .It Fn acl_get_entry This function is described in .Xr acl_get_entry 3 , and may be used to retrieve a designated ACL entry from an ACL. .It Xo .Fn acl_get_fd , .Fn acl_get_fd_np , .Fn acl_get_file , .Fn acl_get_link_np .Xc These functions are described in .Xr acl_get 3 , and may be used to retrieve ACLs from file system objects. .It Fn acl_get_entry_type_np This function is described in .Xr acl_get_entry_type_np 3 , and may be used to retrieve an ACL type from an ACL entry. .It Fn acl_get_flagset_np This function is described in .Xr acl_get_flagset_np 3 , and may be used to retrieve a flagset from an ACL entry. .It Fn acl_get_perm_np This function is described in .Xr acl_get_perm_np 3 , and may be used to check if a permission is set in a permset. .It Fn acl_get_permset This function is described in .Xr acl_get_permset 3 , and may be used to retrieve a permset from an ACL entry. .It Fn acl_get_qualifier This function is described in .Xr acl_get_qualifier 3 , and may be used to retrieve the qualifier from an ACL entry. .It Fn acl_get_tag_type This function is described in .Xr acl_get_tag_type 3 , and may be used to retrieve the tag type from an ACL entry. .It Fn acl_init This function is described in .Xr acl_init 3 , and may be used to allocate a fresh (empty) ACL structure. .It Fn acl_is_trivial_np This function is described in .Xr acl_is_trivial_np 3 , and may be used to find out whether ACL is trivial. .It Xo .Fn acl_set_fd , .Fn acl_set_fd_np , .Fn acl_set_file , .Fn acl_set_link_np .Xc These functions are described in .Xr acl_set 3 , and may be used to assign an ACL to a file system object. .It Fn acl_set_entry_type_np This function is described in .Xr acl_set_entry_type_np 3 , and may be used to set the ACL type of an ACL entry. .It Fn acl_set_flagset_np This function is described in .Xr acl_set_flagset_np 3 , and may be used to set the flags of an ACL entry from a flagset. .It Fn acl_set_permset This function is described in .Xr acl_set_permset 3 , and may be used to set the permissions of an ACL entry from a permset. .It Fn acl_set_qualifier This function is described in .Xr acl_set_qualifier 3 , and may be used to set the qualifier of an ACL. .It Fn acl_set_tag_type This function is described in .Xr acl_set_tag_type 3 , and may be used to set the tag type of an ACL. .It Fn acl_strip_np This function is described in .Xr acl_strip_np 3 , and may be used to remove extended entries from an ACL. .It Xo .Fn acl_to_text , .Fn acl_to_text_np .Xc These functions are described in .Xr acl_to_text 3 , and may be used to generate a text-form of a POSIX.1e or NFSv4 semantics ACL. .It Xo .Fn acl_valid , .Fn acl_valid_fd_np , .Fn acl_valid_file_np , .Fn acl_valid_link_np .Xc These 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. .El .Pp 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 SEE ALSO .Xr getfacl 1 , .Xr setfacl 1 , .Xr acl_add_flag_np 3 , .Xr acl_add_perm 3 , .Xr acl_calc_mask 3 , .Xr acl_clear_flags_np 3 , .Xr acl_clear_perms 3 , .Xr acl_copy_entry 3 , .Xr acl_create_entry 3 , .Xr acl_delete_entry 3 , .Xr acl_delete_flag_np 3 , .Xr acl_delete_perm 3 , .Xr acl_dup 3 , .Xr acl_free 3 , .Xr acl_from_text 3 , .Xr acl_get 3 , .Xr acl_get_brand_np 3 , .Xr acl_get_entry_type_np 3 , .Xr acl_get_flagset_np 3 , .Xr acl_get_perm_np 3 , .Xr acl_get_permset 3 , .Xr acl_get_qualifier 3 , .Xr acl_get_tag_type 3 , .Xr acl_init 3 , .Xr acl_is_trivial_np 3 , .Xr acl_set 3 , .Xr acl_set_entry_type_np 3 , .Xr acl_set_flagset_np 3 , .Xr acl_set_permset 3 , .Xr acl_set_qualifier 3 , .Xr acl_set_tag_type 3 , .Xr acl_strip_np 3 , .Xr acl_to_text 3 , .Xr acl_valid 3 , .Xr posix1e 3 , .Xr acl 9 .Sh STANDARDS 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. .Pp 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 ; .Fx 5.0 was the first version to include a complete ACL implementation based on extended attributes for the UFS and UFS2 file systems. NFSv4 ACL support was introduced in .Fx 8.0 . .Pp The .Xr getfacl 1 and .Xr setfacl 1 utilities describe the user tools that permit direct manipulation of complete file ACLs. .Sh AUTHORS .An Robert N M Watson diff --git a/lib/libc/posix1e/acl_get.3 b/lib/libc/posix1e/acl_get.3 index 1908f0d0d97b..91a3626ada72 100644 --- a/lib/libc/posix1e/acl_get.3 +++ b/lib/libc/posix1e/acl_get.3 @@ -1,166 +1,158 @@ .\"- .\" Copyright (c) 2000, 2002 Robert N. M. Watson .\" All rights reserved. .\" .\" This software was developed by Robert Watson for the TrustedBSD Project. .\" .\" 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. .\" -.Dd June 25, 2009 +.Dd September 21, 2023 .Dt ACL_GET 3 .Os .Sh NAME .Nm acl_get_fd , .Nm acl_get_fd_np , .Nm acl_get_file , .Nm acl_get_link_np .Nd get an ACL for a file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/acl.h .Ft acl_t .Fn acl_get_fd "int fd" .Ft acl_t .Fn acl_get_fd_np "int fd" "acl_type_t type" .Ft acl_t .Fn acl_get_file "const char *path_p" "acl_type_t type" .Ft acl_t .Fn acl_get_link_np "const char *path_p" "acl_type_t type" .Sh DESCRIPTION The .Fn acl_get_fd , .Fn acl_get_file , .Fn acl_get_link_np , and .Fn acl_get_fd_np each allow the retrieval of an ACL from a file. The .Fn acl_get_fd is a POSIX.1e call that allows the retrieval of an ACL of type ACL_TYPE_ACCESS from a file descriptor. The .Fn acl_get_fd_np function is a non-portable form of .Fn acl_get_fd that allows the retrieval of any type of ACL from a file descriptor. The .Fn acl_get_file function is a POSIX.1e call that allows the retrieval of a specified type of ACL from a file by name; .Fn acl_get_link_np is a non-portable variation on .Fn acl_get_file which does not follow a symlink if the target of the call is a symlink. .Pp These functions may cause memory to be allocated. The caller should free any releasable memory, when the new ACL is no longer required, by calling .Xr acl_free 3 with the .Va (void *)acl_t as an argument. .Pp The ACL in the working storage is an independent copy of the ACL associated with the object referred to by .Va fd . The ACL in the working storage shall not participate in any access control decisions. .Pp Valid values for the .Va type argument are: .Bl -column -offset 3n "ACL_TYPE_DEFAULT" .It ACL_TYPE_ACCESS POSIX.1e access ACL .It ACL_TYPE_DEFAULT POSIX.1e default ACL .It ACL_TYPE_NFS4 NFSv4 ACL .El .Pp The ACL returned will be branded accordingly. .Sh IMPLEMENTATION NOTES .Fx Ns 's support for POSIX.1e interfaces and features is still under development at this time. .Sh RETURN VALUES Upon successful completion, the function shall return a pointer to the ACL that was retrieved. Otherwise, a value of .Va (acl_t)NULL shall be returned, and .Va errno shall be set to indicate the error. .Sh ERRORS If any of the following conditions occur, the .Fn acl_get_fd function shall return a value of .Va (acl_t)NULL and set .Va errno to the corresponding value: .Bl -tag -width Er .It Bq Er EACCES Search permission is denied for a component of the path prefix, or the object exists and the process does not have appropriate access rights. .It Bq Er EBADF The .Va fd argument is not a valid file descriptor. .It Bq Er EINVAL The ACL type passed is invalid for this file object. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOENT The named object does not exist, or the .Va path_p argument points to an empty string. .It Bq Er ENOMEM Insufficient memory available to fulfill request. .It Bq Er EOPNOTSUPP The file system does not support ACL retrieval. .El .Sh SEE ALSO .Xr acl 3 , .Xr acl_free 3 , .Xr acl_get 3 , .Xr acl_get_brand_np 3 , .Xr acl_set 3 , .Xr posix1e 3 .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. +.Fx 4.0 . .Sh AUTHORS .An Robert N M Watson diff --git a/lib/libc/posix1e/acl_get_entry.3 b/lib/libc/posix1e/acl_get_entry.3 index 1c6126334fa3..94a95b5412b7 100644 --- a/lib/libc/posix1e/acl_get_entry.3 +++ b/lib/libc/posix1e/acl_get_entry.3 @@ -1,143 +1,143 @@ .\"- .\" Copyright (c) 2001 Chris D. Faulhaber .\" 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 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. .\" -.Dd April 13, 2001 +.Dd September 21, 2023 .Dt ACL_GET_ENTRY 3 .Os .Sh NAME .Nm acl_get_entry .Nd retrieve an ACL entry from an ACL .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/acl.h .Ft int .Fn acl_get_entry "acl_t acl" "int entry_id" "acl_entry_t *entry_p" .Sh DESCRIPTION The .Fn acl_get_entry function is a POSIX.1e call that retrieves a descriptor for an ACL entry specified by the argument -.Fa entry_d +.Fa entry_id within the ACL indicated by the argument .Fa acl . .Pp If the value of .Fa entry_id is .Dv ACL_FIRST_ENTRY , then the function will return in .Fa entry_p a descriptor for the first ACL entry within .Fa acl . If a call is made to .Fn acl_get_entry with .Fa entry_id set to .Dv ACL_NEXT_ENTRY when there has not been either an initial successful call to .Fn acl_get_entry , or a previous successful call to .Fn acl_create_entry , .Fn acl_delete_entry , .Fn acl_dup , .Fn acl_from_text , .Fn acl_get_fd , .Fn acl_get_file , .Fn acl_set_fd , .Fn acl_set_file , or .Fn acl_valid , then the result is unspecified. .Sh RETURN VALUES If the .Fn acl_get_entry function successfully obtains an ACL entry, a value of 1 is returned. If the ACL has no ACL entries, the .Fn acl_get_entry returns a value of 0. If the value of .Fa entry_id is .Dv ACL_NEXT_ENTRY and the last ACL entry in the ACL has already been returned by a previous call to .Fn acl_get_entry , a value of 0 will be returned until a successful call with .Fa entry_id of .Dv ACL_FIRST_ENTRY is made. Otherwise, a value of -1 will be returned and the global variable .Va errno will be set to indicate the error. .Sh ERRORS The .Fn acl_get_entry -fails if: +function fails if: .Bl -tag -width Er .It Bq Er EINVAL Argument .Fa acl does not point to a valid ACL. Argument .Fa entry_id is neither .Dv ACL_FIRST_ENTRY nor .Dv ACL_NEXT_ENTRY . .El .Sh SEE ALSO .Xr acl 3 , .Xr acl_calc_mask 3 , .Xr acl_create_entry 3 , .Xr acl_delete_entry 3 , .Xr acl_dup 3 , .Xr acl_from_text 3 , .Xr acl_get_fd 3 , .Xr acl_get_file 3 , .Xr acl_init 3 , .Xr acl_set_fd 3 , .Xr acl_set_file 3 , .Xr acl_valid 3 , .Xr posix1e 3 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. .Sh HISTORY POSIX.1e support was introduced in .Fx 4.0 . The .Fn acl_get_entry function was added in .Fx 5.0 . .Sh AUTHORS The .Fn acl_get_entry function was written by .An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/lib/libc/posix1e/mac_free.3 b/lib/libc/posix1e/mac_free.3 index 987bd9966564..4ed68b70f3a3 100644 --- a/lib/libc/posix1e/mac_free.3 +++ b/lib/libc/posix1e/mac_free.3 @@ -1,97 +1,91 @@ .\" Copyright (c) 2001, 2002 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris .\" Costello at Safeport Network Services and NAI Labs, the Security .\" Research Division of Network Associates, Inc. under DARPA/SPAWAR .\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS .\" research program. .\" .\" 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. .\" 3. The name of the author may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS 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 AUTHORS 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. .\" -.Dd December 21, 2001 +.Dd September 21, 2023 .Dt MAC_FREE 3 .Os .Sh NAME .Nm mac_free .Nd free MAC label .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/mac.h .Ft int .Fn mac_free "mac_t label" .Sh DESCRIPTION The .Fn mac_free function frees the storage allocated to contain a .Vt mac_t . .Sh RETURN VALUES The .Fn mac_free function always returns 0. WARNING: see the notes in the .Sx BUGS section regarding the use of this function. .Sh SEE ALSO .Xr mac 3 , .Xr mac_get 3 , .Xr mac_prepare 3 , .Xr mac_set 3 , .Xr mac_text 3 , .Xr posix1e 3 , .Xr mac 4 , .Xr mac 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 Support for Mandatory Access Control was introduced in .Fx 5.0 as part of the .Tn TrustedBSD Project. .Sh BUGS POSIX.1e specifies that .Fn mac_free will be used to free text strings created using .Xr mac_to_text 3 . Because .Vt mac_t is a complex structure in the .Tn TrustedBSD implementation, .Fn mac_free is specific to .Vt mac_3 , and must not be used to free the character strings returned from .Fn mac_to_text . Doing so may result in undefined behavior. diff --git a/lib/libc/posix1e/mac_get.3 b/lib/libc/posix1e/mac_get.3 index 45045977fb32..171f7cd91aaf 100644 --- a/lib/libc/posix1e/mac_get.3 +++ b/lib/libc/posix1e/mac_get.3 @@ -1,150 +1,144 @@ .\" Copyright (c) 2001, 2004 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris .\" Costello at Safeport Network Services and NAI Labs, the Security .\" Research Division of Network Associates, Inc. under DARPA/SPAWAR .\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS .\" research program. .\" .\" 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 AUTHORS 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 AUTHORS 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. .\" -.Dd December 21, 2001 +.Dd September 21, 2023 .Dt MAC_GET 3 .Os .Sh NAME .Nm mac_get_file , .Nm mac_get_link , .Nm mac_get_fd , .Nm mac_get_peer , .Nm mac_get_pid , .Nm mac_get_proc .Nd get the label of a file, socket, socket peer or process .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/mac.h .Ft int .Fn mac_get_file "const char *path" "mac_t label" .Ft int .Fn mac_get_link "const char *path" "mac_t label" .Ft int .Fn mac_get_fd "int fd" "mac_t label" .Ft int .Fn mac_get_peer "int fd" "mac_t label" .Ft int .Fn mac_get_pid "pid_t pid" "mac_t label" .Ft int .Fn mac_get_proc "mac_t label" .Sh DESCRIPTION The .Fn mac_get_file system call returns the label associated with a file specified by pathname. The .Fn mac_get_link function is the same as .Fn mac_get_file , except that it does not follow symlinks. .Pp The .Fn mac_get_fd system call returns the label associated with an object referenced by the specified file descriptor. Note that in the case of a file system socket, the label returned will be the socket label, which may be different from the label of the on-disk node acting as a rendezvous for the socket. The .Fn mac_get_peer system call returns the label associated with the remote endpoint of a socket; the exact semantics of this call will depend on the protocol domain, communications type, and endpoint; typically this label will be cached when a connection-oriented protocol instance is first set up, and is undefined for datagram protocols. .Pp The .Fn mac_get_pid and .Fn mac_get_proc system calls return the process label associated with an arbitrary process ID, or the current process. .Pp Label storage for use with these calls must first be allocated and prepared using the .Xr mac_prepare 3 functions. When an application is done using a label, the memory may be returned using .Xr mac_free 3 . .Sh ERRORS .Bl -tag -width Er .It Bq Er EACCES A component of .Fa path is not searchable, or MAC read access to the file is denied. .It Bq Er EINVAL The requested label operation is not valid for the object referenced by .Fa fd . .It Bq Er ENAMETOOLONG The pathname pointed to by .Fa path exceeds .Dv PATH_MAX , or a component of the pathname exceeds .Dv NAME_MAX . .It Bq Er ENOENT A component of .Fa path does not exist. .It Bq Er ENOMEM Insufficient memory is available to allocate a new MAC label structure. .It Bq Er ENOTDIR A component of .Fa path is not a directory. .El .Sh SEE ALSO .Xr mac 3 , .Xr mac_free 3 , .Xr mac_prepare 3 , .Xr mac_set 3 , .Xr mac_text 3 , .Xr posix1e 3 , .Xr mac 4 , .Xr mac 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 Support for Mandatory Access Control was introduced in .Fx 5.0 as part of the .Tn TrustedBSD Project. diff --git a/lib/libc/posix1e/mac_prepare.3 b/lib/libc/posix1e/mac_prepare.3 index 58493e988a0b..50dfa1c28d2d 100644 --- a/lib/libc/posix1e/mac_prepare.3 +++ b/lib/libc/posix1e/mac_prepare.3 @@ -1,124 +1,118 @@ .\" Copyright (c) 2002, 2003 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris .\" Costello at Safeport Network Services and Network Associates Labs, .\" the Security Research Division of Network Associates, Inc. under .\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the .\" DARPA CHATS research program. .\" .\" 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 AUTHORS 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 AUTHORS 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. .\" -.Dd August 22, 2003 +.Dd September 21, 2023 .Dt MAC_PREPARE 3 .Os .Sh NAME .Nm mac_prepare , mac_prepare_type , mac_prepare_file_label , .Nm mac_prepare_ifnet_label , mac_prepare_process_label .Nd allocate appropriate storage for .Vt mac_t .Sh SYNOPSIS .In sys/mac.h .Ft int .Fn mac_prepare "mac_t *mac" "const char *elements" .Ft int .Fn mac_prepare_type "mac_t *mac" "const char *name" .Ft int .Fn mac_prepare_file_label "mac_t *mac" .Ft int .Fn mac_prepare_ifnet_label "mac_t *mac" .Ft int .Fn mac_prepare_process_label "mac_t *mac" .Sh DESCRIPTION The .Nm family of functions allocates the appropriate amount of storage and initializes .Fa *mac for use by .Xr mac_get 3 . When the resulting label is passed into the .Xr mac_get 3 functions, the kernel will attempt to fill in the label elements specified when the label was prepared. Elements are specified in a nul-terminated string, using commas to delimit fields. Element names may be prefixed with the .Ql \&? character to indicate that a failure by the kernel to retrieve that element should not be considered fatal. .Pp The .Fn mac_prepare function accepts a list of policy names as a parameter, and allocates the storage to fit those label elements accordingly. The remaining functions in the family make use of system defaults defined in .Xr mac.conf 5 instead of an explicit .Va elements argument, deriving the default from the specified object type. .Pp .Fn mac_prepare_type allocates the storage to fit an object label of the type specified by the .Va name argument. The .Fn mac_prepare_file_label , .Fn mac_prepare_ifnet_label , and .Fn mac_prepare_process_label functions are equivalent to invocations of .Fn mac_prepare_type with arguments of .Qq file , .Qq ifnet , and .Qq process respectively. .Sh RETURN VALUES .Rv -std .Sh SEE ALSO .Xr mac 3 , .Xr mac_free 3 , .Xr mac_get 3 , .Xr mac_is_present 3 , .Xr mac_set 3 , .Xr mac 4 , .Xr mac.conf 5 , .Xr maclabel 7 .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 Support for Mandatory Access Control was introduced in .Fx 5.0 as part of the .Tn TrustedBSD Project. Support for generic object types first appeared in .Fx 5.2 . diff --git a/lib/libc/posix1e/mac_text.3 b/lib/libc/posix1e/mac_text.3 index 88131f0bf611..29c1aacca485 100644 --- a/lib/libc/posix1e/mac_text.3 +++ b/lib/libc/posix1e/mac_text.3 @@ -1,115 +1,109 @@ .\" Copyright (c) 2001 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris .\" Costello at Safeport Network Services and NAI Labs, the Security .\" Research Division of Network Associates, Inc. under DARPA/SPAWAR .\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS .\" research program. .\" .\" 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 AUTHORS 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 AUTHORS 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. .\" -.Dd December 21, 2001 +.Dd September 21, 2023 .Dt MAC_TEXT 3 .Os .Sh NAME .Nm mac_from_text , .Nm mac_to_text .Nd convert MAC label to/from text representation .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/mac.h .Ft int .Fn mac_from_text "mac_t *mac" "const char *text" .Ft int .Fn mac_to_text "mac_t label" "char **text" .Sh DESCRIPTION The .Fn mac_from_text function converts the text representation of a label into the internal policy label format .Pq Vt mac_t and places it in .Fa *mac , which must later be freed with .Xr free 3 . .Pp The .Fn mac_to_text function allocates storage for .Fa *text , which will be set to the text representation of .Fa label . .Pp Refer to .Xr maclabel 7 for the MAC label format. .Sh RETURN VALUES .Rv -std mac_from_text mac_to_text .Sh COMPATIBILITY POSIX.1e does not define a format for text representations of MAC labels. .Pp POSIX.1e requires that text strings allocated using .Fn mac_to_text be freed using .Xr mac_free 3 ; in the .Fx implementation, they must be freed using .Xr free 3 , as .Xr mac_free 3 is used only to free memory used for type .Vt mac_t . .Sh ERRORS .Bl -tag -width Er .It Bq Er ENOMEM Insufficient memory was available to allocate internal storage. .El .Sh SEE ALSO .Xr free 3 , .Xr mac 3 , .Xr mac_get 3 , .Xr mac_is_present 3 , .Xr mac_prepare 3 , .Xr mac_set 3 , .Xr posix1e 3 , .Xr mac 4 , .Xr maclabel 7 .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 Support for Mandatory Access Control was introduced in .Fx 5.0 as part of the .Tn TrustedBSD Project.