diff options
author | rwatson <rwatson@FreeBSD.org> | 2000-06-04 21:15:16 +0000 |
---|---|---|
committer | rwatson <rwatson@FreeBSD.org> | 2000-06-04 21:15:16 +0000 |
commit | 9f516a06e7c6f525411dce748e4dafa561368c02 (patch) | |
tree | 980a9470e933ccb2a79e7e1d8a8f646fb1c4973d /lib/libposix1e | |
parent | a88c20a2394d023b211e87002e1c7fd00d8442ef (diff) | |
download | FreeBSD-src-9f516a06e7c6f525411dce748e4dafa561368c02.zip FreeBSD-src-9f516a06e7c6f525411dce748e4dafa561368c02.tar.gz |
o Introduce man pages for POSIX.1e capability API
- cap.3 describing library interface
- cap_*.3 describing specific API calls
APIs to follow relatively soon, code to follow later.
Obtained from: TrustedBSD Project
Diffstat (limited to 'lib/libposix1e')
-rw-r--r-- | lib/libposix1e/cap.3 | 140 | ||||
-rw-r--r-- | lib/libposix1e/cap_clear.3 | 90 | ||||
-rw-r--r-- | lib/libposix1e/cap_dup.3 | 107 | ||||
-rw-r--r-- | lib/libposix1e/cap_free.3 | 101 | ||||
-rw-r--r-- | lib/libposix1e/cap_get_flag.3 | 96 | ||||
-rw-r--r-- | lib/libposix1e/cap_get_proc.3 | 99 | ||||
-rw-r--r-- | lib/libposix1e/cap_init.3 | 99 | ||||
-rw-r--r-- | lib/libposix1e/cap_set_flag.3 | 110 | ||||
-rw-r--r-- | lib/libposix1e/cap_set_proc.3 | 106 |
9 files changed, 948 insertions, 0 deletions
diff --git a/lib/libposix1e/cap.3 b/lib/libposix1e/cap.3 new file mode 100644 index 0000000..b389c0a --- /dev/null +++ b/lib/libposix1e/cap.3 @@ -0,0 +1,140 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap +.Nd introduction to the POSIX.1e Capability security API +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/cap.h> +.Sh DESCRIPTION +The POSIX.1e Capability interface allows processes to manipulate their +capability set, subject to capability manipulation restrictions imposed +by the kernel. Using the capability API, a process may request a copy +of its capability state, modify the copy of the state, and resubmit the +state for use, if permitted. +.Pp +A variety of functions are provided for manipulating and managing +process capability state and working store state: +.Pp +.Fn cap_init +.Pp +This function is described in +.Xr cap_init 3 , +and may be used to allocate a fresh capability structure with no capability +flags set. +.Pp +.Fn cap_clear +.Pp +This function is described in +.Xr cap_clear 3 , +and clears all capability flags in a capability structure. +.Pp +.Fn cap_dup +.Pp +This function is described in +.Xr cap_dup 3 , +and may be used to duplicate a capability structure. +.Pp +.Fn cap_free +.Pp +This function is described in +.Xr cap_free 3 , +and may be used to free a capability structure. +.Pp +.Fn cap_get_flag , +.Fn cap_get_proc +.Pp +These functions, described in +.Xr cap_get_flag 3 , +and +.Xr cap_get_proc 3 , +allow retrieval of capability flags from a file, and capability state from +the current process. +.Pp +.Fn cap_set_flag , +.Fn cap_set_proc +.Pp +These functions, described in +.Xr cap_set_flag 3 , +and +.Xr cap_set_proc 3 , +allow setting of the capability flags for a file, and capability state for +the current process. + +Documentation of the internal kernel interfaces backing these calls may +be found in +.Xr cap 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 5.0 +so as to discourage their +use in the short term. +.\" .Sh FILES +.Sh SEE ALSO +.Xr cap_clear 3 , +.Xr cap_dup 3 , +.Xr cap_free 3 , +.Xr cap_get_flag 3 , +.Xr cap_get_proc 3 , +.Xr cap_init 3 , +.Xr cap_set_flag 3 , +.Xr cap_set_proc 3 , +.Xr cap 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 POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +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 included in the base FreeBSD distribution. diff --git a/lib/libposix1e/cap_clear.3 b/lib/libposix1e/cap_clear.3 new file mode 100644 index 0000000..0dff3c1 --- /dev/null +++ b/lib/libposix1e/cap_clear.3 @@ -0,0 +1,90 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_CLEAR 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_clear +.Nd Initialize a Capability State in Working Store +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft int +.Fn cap_clear "cap_t cap_p" +.Sh DESCRIPTION +The function +.Fn cap_clear +shall initialize the capability state in working storage identified by +.Ar cap_p +so that all capability flags for all capabilities defined in the +implementation shall be cleared. +.Sh IMPLEMENTATION NOTES +FreeBSD'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 value of zero. +Otherwise, a value of -1 shall be returned and +.Va errno +shall be set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn cap_clear +function shall return -1 and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Va cap_p +argument does not refer to a capability state in the working storage. +Search permission is denied for a component of the path prefix, or the +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_init 3 , +.Xr cap_set_flag 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. diff --git a/lib/libposix1e/cap_dup.3 b/lib/libposix1e/cap_dup.3 new file mode 100644 index 0000000..acc0c47 --- /dev/null +++ b/lib/libposix1e/cap_dup.3 @@ -0,0 +1,107 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_DUP 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_dup +.Nd Duplicate a Capability State in Working Storage +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft cap_t +.Fn cap_dup "cap_t cap_p" +.Sh DESCRIPTION +The +.Fn cap_dup +function returns a duplicate capability state in working storage given the +source object +.Ar cap_p , +allocating any memory necessary, and returning a pointer to the newly +created capability state. +Once duplicated, no operations on the either capability state shall affect +the other in any way. +.Pp +This function may cause memory to be allocated. +The caller should free any releasable memory, when the capability state in +working storage is no longer required, by calling +.Vn cap_free +with the cap_t as an argument. +.Sh IMPLEMENTATION NOTES +FreeBSD's support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, the +.Fn cap_dup +function returns a pointer to the newly created capability state in working +storage. +Otherwise, a value of +.Va (cap_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 cap_dup +function shall return +.Va (cap_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Va cap_p +argument does not refer to a capability state in the working storage. +.It Bq Er ENOMEM +The capability state to be returned requires more memory than is allowed by +the hardware or system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_free 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. diff --git a/lib/libposix1e/cap_free.3 b/lib/libposix1e/cap_free.3 new file mode 100644 index 0000000..28d9ead --- /dev/null +++ b/lib/libposix1e/cap_free.3 @@ -0,0 +1,101 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_FREE 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_free +.Nd Release Memory Allocated to a Capability State in Working Storage +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft int +.Fn cap_free "void *obj_d" +.Sh DESCRIPTION +The function +.Fn cap_free +shall free any releasable memory currently allocated to the capability +state in working storage identified by +.Va obj_d . +The +.Va obj_d +argument may identify either a cap_t entity, or a char * entity allocated +by the +.Fn cap_to_text +function. +.Pp +.Sh IMPLEMENTATION NOTES +FreeBSD'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 value of zero. +Otherwise, a value of -1 shall be returned and +.Va errno +set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn cap_free +function shall return -1 and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Va cap_p +argument does not refer to a capability state in the working storage. +Search permission is denied for a component of the path prefix, or the +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_dup 3 , +.Xr cap_from_text 3 , +.Xr cap_get_fd 3 , +.Xr cap_get_file 3 , +.Xr cap_get_proc 3 , +.Xr cap_init 3 , +.Xr cap_to_text 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. diff --git a/lib/libposix1e/cap_get_flag.3 b/lib/libposix1e/cap_get_flag.3 new file mode 100644 index 0000000..ae95b9c --- /dev/null +++ b/lib/libposix1e/cap_get_flag.3 @@ -0,0 +1,96 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_GET_FLAG 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_get_flag +.Nd Get the Value of a Capability Flag +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft int +.Fn cap_get_flag "cap_t cap_p" "cap_value_t cap" "cap_flag_t flag" "cap_flag_value_t *value_p" +.Sh DESCRIPTION +The function +.Fn cap_get_flag +shall obtain the current value of the capability flag +.Ar flag +of the capability +.Ar cap +from the capability state in working storage identified by +.Ar cap_p +and place it into the location pointed to by +.Ar value_p . +.Sh IMPLEMENTATION NOTES +FreeBSD'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 value of zero. +Otherwise, a value of -1 shall be returned and +.Va errno +set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn cap_get_flag +function shall return -1 and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +At least one of the values of the +.Ar cap_p , +.Ar cap , +.Ar flag +and +.Ar value_p +arguments does not refer to the corresponding entity. +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_set_flag 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. diff --git a/lib/libposix1e/cap_get_proc.3 b/lib/libposix1e/cap_get_proc.3 new file mode 100644 index 0000000..d3dd896 --- /dev/null +++ b/lib/libposix1e/cap_get_proc.3 @@ -0,0 +1,99 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_GET_PROC 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_get_proc +.Nd Obtain the Current Process Capability State +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft cap_t +.Fn cap_get_proc "void" +.Sh DESCRIPTION +The function +.Fn cap_get_proc +shall allocate a capability state in working storage, set its state to that +of the calling process, and return a pointer to the newly created +capability state. +.Pp +This function may cause memory to be allocated. +The caller should free any releasable memory, when the capability state in +the working storage is no longer required, by calling +.Fn cap_free +with the cap_t as an argument. +.Sh IMPLEMENTATION NOTES +FreeBSD's support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, this function shall return a cap_t value. +Otherwise, a value of +.Va (cap_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 cap_get_proc +function shall return +.Va (cap_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOMEM +The capability state to be returned requires more memory than is allowed +by the hardware or system-imposed memory management constrains. +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_free 3 , +.Xr cap_init 3 , +.Xr cap_get_flag 3 , +.Xr cap_set_proc 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. diff --git a/lib/libposix1e/cap_init.3 b/lib/libposix1e/cap_init.3 new file mode 100644 index 0000000..2f8633c --- /dev/null +++ b/lib/libposix1e/cap_init.3 @@ -0,0 +1,99 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_INIT 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_init +.Nd Allocate and Initialize a Capability State in Working Storage +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft cap_t +.Fn cap_init "void" +.Sh DESCRIPTION +The function +.Fn cap_init +shall create a capability state in working storage and return a pointer to +the capability state. +The initial value of all flags for all capabilities defined by the +implementation shall be cleared. +.Pp +This function may cause memory to be allocated. +The caller should free any releasable memory, when the capability state in +working storage is no longer required, by calling +.Vn cap_free +with the cap_t as an argument. +.Sh IMPLEMENTATION NOTES +FreeBSD's support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, the +.Fn cap_init +function returns a non-NULL cap_t value. +Otherwise, a value of +.Va (cap_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 cap_dup +function shall return +.Va (cap_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOMEM +The capability state to be returned requires more memory than is allowed by +the hardware or system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_free 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. diff --git a/lib/libposix1e/cap_set_flag.3 b/lib/libposix1e/cap_set_flag.3 new file mode 100644 index 0000000..36f277d --- /dev/null +++ b/lib/libposix1e/cap_set_flag.3 @@ -0,0 +1,110 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_SET_FLAG 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_set_flag +.Nd Set the Value of a Capability Flag +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft int +.Fn cap_set_flag "cap_t cap_p" "cap_flag_t flag" "int ncap" "cap_value_t caps[]" "cap_flag_value_t value" +.Sh DESCRIPTION +This function shall set the flag +.Ar flag +of each capability in the array +.Ar caps +in the capability state in working storage identified by +.Ar cap_p +to +.Ar value . +The argument +.Ar ncap +is used to specify the number of capabilities in the array +.Ar caps . +Implementations may place restrictions on the setting of the flags in a capability state. +.Sh IMPLEMENTATION NOTES +FreeBSD's support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, this function shall return a value of zero. +Otherwise, a value of -1 shall be returned, and +.Ar errno +shall be set to indicate the error. +The capability state identified by +.Ar cap_p +shall not be affected if the return value is -1. +.Sh ERRORS +If any of the following conditions occur, the +.Fn cap_set_flag +function shall return -1 and set +.Ar errno +to the corresponding value: +.Bl -tag -width Er +.It Bq er EINVAL +At least one of the values of +.Ar cap_p , +.Ar ncap , +.Ar flag +and +.Ar value , +or at least one of the first +.Ar ncap +elements in +.Ar caps , +does not refer to the corresponding entity. +.Pp +The resulting capability state identified by +.Ar cap_p +violates one or more implementation restrictions. +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_get_flag 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. diff --git a/lib/libposix1e/cap_set_proc.3 b/lib/libposix1e/cap_set_proc.3 new file mode 100644 index 0000000..b459260 --- /dev/null +++ b/lib/libposix1e/cap_set_proc.3 @@ -0,0 +1,106 @@ +.\"- +.\" 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$ +.\" +.\" TrustedBSD Project - support for POSIX.1e process capabilities +.\" +.Dd April 1, 2000 +.Dt CAP_SET_PROC 3 +.Os FreeBSD 5.0 +.Sh NAME +.Nm cap_set_proc +.Nd Set the Process Capability State +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/capability.h> +.Ft int +.Fn cap_set_proc "cap_t cap_p" +.Sh DESCRIPTION +The function +.Fn cap_set_proc +shall set the values for all capability flags for all capabilities defined +in the implementation with the capability state identified by +.Ar cap_p . +The new capability state of the process shall be completely determined by +the contents of +.Ar cap_p +upon successful return from this function. +If any flag in +.Ar cap_p +is set for any capability not currently permitted for the calling process, +the function shall fail, and the capability state of teh process shall +remain unchanged. +.Sh IMPLEMENTATION NOTES +FreeBSD's support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, this function shall return a value of zero. +Otherwise, a value of -1 shall be returned and +.Ar errno +shall be set to indicate the error. +Neither the state represented in the object identified by +.Ar cap_p +nor the capability state of the calling process shall be affected if the +return value is -1. +.Sh ERRORS +If any of the following conditions occur, the +.Fn cap_set_proc +function shall return -1 and set +.Ar errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Ar cap_p +argument does not refer to a capability state in working storage. +.It Bq Er EPERM +The caller attempted to set a capability flag of a capability that was not +permitted to the invoking process. +.It Bq Er ENOMEM +This function requires more memory than is allowed by the hardware or +system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr cap 3 , +.Xr cap_get_proc 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 +Support for POSIX.1e Capabilities was developed as part of the TrustedBSD +Project. +POSIX.1e Capability support was introduced in +.Fx 5.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +These features are not yet fully implemented. |