diff --git a/lib/libc/sys/cap_enter.2 b/lib/libc/sys/cap_enter.2 index 428e0b0bcd09..56fc78a4b4f2 100644 --- a/lib/libc/sys/cap_enter.2 +++ b/lib/libc/sys/cap_enter.2 @@ -1,164 +1,163 @@ .\" .\" Copyright (c) 2008-2009 Robert N. M. Watson .\" All rights reserved. .\" .\" This software was developed at the University of Cambridge Computer .\" Laboratory with support from a grant from Google, Inc. .\" .\" 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$ .\" -.Dd May 5, 2020 +.Dd March 9, 2023 .Dt CAP_ENTER 2 .Os .Sh NAME .Nm cap_enter , .Nm cap_getmode .Nd Capability mode system calls .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capsicum.h .Ft int .Fn cap_enter "void" .Ft int .Fn cap_getmode "u_int *modep" .Sh DESCRIPTION .Fn cap_enter places the current process into capability mode, a mode of execution in which processes may only issue system calls operating on file descriptors or reading limited global system state. Access to global name spaces, such as file system or IPC name spaces, is prevented. If the process is already in a capability mode sandbox, the system call is a no-op. Future process descendants created with .Xr fork 2 or .Xr pdfork 2 will be placed in capability mode from inception. .Pp When combined with .Xr cap_rights_limit 2 , .Xr cap_ioctls_limit 2 , .Xr cap_fcntls_limit 2 , .Fn cap_enter may be used to create kernel-enforced sandboxes in which appropriately-crafted applications or application components may be run. .Pp .Fn cap_getmode returns a flag indicating whether or not the process is in a capability mode sandbox. .Sh RUN-TIME SETTINGS If the .Dv kern.trap_enotcap sysctl MIB is set to a non-zero value, then for any process executing in a capability mode sandbox, any syscall which results in either an .Er ENOTCAPABLE or .Er ECAPMODE error also generates the synchronous .Dv SIGTRAP signal to the thread on the syscall return. On signal delivery, the .Va si_errno member of the .Fa siginfo signal handler parameter is set to the syscall error value, and the .Va si_code member is set to .Dv TRAP_CAP . .Pp See also the .Dv PROC_TRAPCAP_CTL and .Dv PROC_TRAPCAP_STATUS operations of the .Xr procctl 2 function for similar per-process functionality. .Sh RETURN VALUES .Rv -std cap_enter cap_getmode .Pp When the process is in capability mode, .Fn cap_getmode sets the flag to a non-zero value. A zero value means the process is not in capability mode. .Sh ERRORS The .Fn cap_enter and .Fn cap_getmode system calls will fail if: .Bl -tag -width Er .It Bq Er ENOSYS -The kernel is compiled without: -.Pp -.Cd "options CAPABILITY_MODE" +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . .El .Pp The .Fn cap_getmode system call may also return the following error: .Bl -tag -width Er .It Bq Er EFAULT Pointer .Fa modep points outside the process's allocated address space. .El .Sh SEE ALSO .Xr cap_fcntls_limit 2 , .Xr cap_ioctls_limit 2 , .Xr cap_rights_limit 2 , .Xr fexecve 2 , .Xr procctl 2 , .Xr cap_sandboxed 3 , .Xr capsicum 4 , .Xr sysctl 9 .Sh HISTORY The .Fn cap_getmode system call first appeared in .Fx 8.3 . Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. .Sh AUTHORS These functions and the capability facility were created by .An "Robert N. M. Watson" at the University of Cambridge Computer Laboratory with support from a grant from Google, Inc. .Sh CAVEATS Creating effective process sandboxes is a tricky process that involves identifying the least possible rights required by the process and then passing those rights into the process in a safe manner. Consumers of .Fn cap_enter should also be aware of other inherited rights, such as access to VM resources, memory contents, and other process properties that should be considered. It is advisable to use .Xr fexecve 2 to create a runtime environment inside the sandbox that has as few implicitly acquired rights as possible. diff --git a/lib/libc/sys/cap_fcntls_limit.2 b/lib/libc/sys/cap_fcntls_limit.2 index eb223ac5d512..f5d64e7a4273 100644 --- a/lib/libc/sys/cap_fcntls_limit.2 +++ b/lib/libc/sys/cap_fcntls_limit.2 @@ -1,131 +1,134 @@ .\" .\" Copyright (c) 2012 The FreeBSD Foundation .\" .\" This documentation was written by Pawel Jakub Dawidek under sponsorship .\" the FreeBSD Foundation. .\" .\" 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$ .\" -.Dd May 5, 2020 +.Dd March 9, 2023 .Dt CAP_FCNTLS_LIMIT 2 .Os .Sh NAME .Nm cap_fcntls_limit , .Nm cap_fcntls_get .Nd manage allowed fcntl commands .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capsicum.h .Ft int .Fn cap_fcntls_limit "int fd" "uint32_t fcntlrights" .Ft int .Fn cap_fcntls_get "int fd" "uint32_t *fcntlrightsp" .Sh DESCRIPTION If a file descriptor is granted the .Dv CAP_FCNTL capability right, the list of allowed .Xr fcntl 2 commands can be selectively reduced (but never expanded) with the .Fn cap_fcntls_limit system call. .Pp A bitmask of allowed fcntls commands for a given file descriptor can be obtained with the .Fn cap_fcntls_get system call. .Sh FLAGS The following flags may be specified in the .Fa fcntlrights argument or returned in the .Fa fcntlrightsp argument: .Bl -tag -width CAP_FCNTL_GETOWN .It Dv CAP_FCNTL_GETFL Permit .Dv F_GETFL command. .It Dv CAP_FCNTL_SETFL Permit .Dv F_SETFL command. .It Dv CAP_FCNTL_GETOWN Permit .Dv F_GETOWN command. .It Dv CAP_FCNTL_SETOWN Permit .Dv F_SETOWN command. .El .Sh RETURN VALUES .Rv -std .Sh ERRORS .Fn cap_fcntls_limit succeeds unless: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid descriptor. .It Bq Er EINVAL An invalid flag has been passed in .Fa fcntlrights . .It Bq Er ENOTCAPABLE .Fa fcntlrights would expand the list of allowed .Xr fcntl 2 commands. .El .Pp .Fn cap_fcntls_get succeeds unless: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid descriptor. .It Bq Er EFAULT The .Fa fcntlrightsp argument points at an invalid address. +.It Bq Er ENOSYS +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . .El .Sh SEE ALSO .Xr cap_ioctls_limit 2 , .Xr cap_rights_limit 2 , .Xr fcntl 2 .Sh HISTORY The .Fn cap_fcntls_get and .Fn cap_fcntls_limit system calls first appeared in .Fx 8.3 . Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. .Sh AUTHORS This function was created by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship of the FreeBSD Foundation. diff --git a/lib/libc/sys/cap_ioctls_limit.2 b/lib/libc/sys/cap_ioctls_limit.2 index 6014db6fb485..06cf13590ff9 100644 --- a/lib/libc/sys/cap_ioctls_limit.2 +++ b/lib/libc/sys/cap_ioctls_limit.2 @@ -1,164 +1,163 @@ .\" .\" Copyright (c) 2012 The FreeBSD Foundation .\" .\" This documentation was written by Pawel Jakub Dawidek under sponsorship .\" the FreeBSD Foundation. .\" .\" 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$ .\" -.Dd May 5, 2020 +.Dd March 9, 2023 .Dt CAP_IOCTLS_LIMIT 2 .Os .Sh NAME .Nm cap_ioctls_limit , .Nm cap_ioctls_get .Nd manage allowed ioctl commands .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capsicum.h .Ft int .Fn cap_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds" .Ft ssize_t .Fn cap_ioctls_get "int fd" "unsigned long *cmds" "size_t maxcmds" .Sh DESCRIPTION If a file descriptor is granted the .Dv CAP_IOCTL capability right, the list of allowed .Xr ioctl 2 commands can be selectively reduced (but never expanded) with the .Fn cap_ioctls_limit system call. The .Fa cmds argument is an array of .Xr ioctl 2 commands and the .Fa ncmds argument specifies the number of elements in the array. There can be up to .Va 256 elements in the array. Including an element that has been previously revoked will generate an error. After a successful call only those listed in the array may be used. .Pp The list of allowed ioctl commands for a given file descriptor can be obtained with the .Fn cap_ioctls_get system call. The .Fa cmds argument points at memory that can hold up to .Fa maxcmds values. The function populates the provided buffer with up to .Fa maxcmds elements, but always returns the total number of ioctl commands allowed for the given file descriptor. The total number of ioctls commands for the given file descriptor can be obtained by passing .Dv NULL as the .Fa cmds argument and .Va 0 as the .Fa maxcmds argument. If all ioctl commands are allowed .Dv ( CAP_IOCTL capability right is assigned to the file descriptor and the .Fn cap_ioctls_limit system call was never called for this file descriptor), the .Fn cap_ioctls_get system call will return .Dv CAP_IOCTLS_ALL and will not modify the buffer pointed to by the .Fa cmds argument. .Sh RETURN VALUES .Rv -std cap_ioctls_limit .Pp The .Fn cap_ioctls_get function, if successful, returns the total number of allowed ioctl commands or the value .Dv CAP_IOCTLS_ALL if all ioctls commands are allowed. On failure the value .Va -1 is returned and the global variable errno is set to indicate the error. .Sh ERRORS +The .Fn cap_ioctls_limit -succeeds unless: +and +.Fn cap_ioctls_get +system calls will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid descriptor. .It Bq Er EFAULT The .Fa cmds argument points at an invalid address. +.It Bq Er ENOSYS +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . +.El +.Pp +The +.Fn cap_ioctls_limit +system call may also return the following errors: +.Bl -tag -width Er .It Bq Er EINVAL The .Fa ncmds argument is greater than .Va 256 . .It Bq Er ENOTCAPABLE .Fa cmds would expand the list of allowed .Xr ioctl 2 commands. .El -.Pp -.Fn cap_ioctls_get -succeeds unless: -.Bl -tag -width Er -.It Bq Er EBADF -The -.Fa fd -argument is not a valid descriptor. -.It Bq Er EFAULT -The -.Fa cmds -argument points at invalid address. -.El .Sh SEE ALSO .Xr cap_fcntls_limit 2 , .Xr cap_rights_limit 2 , .Xr ioctl 2 .Sh HISTORY The .Fn cap_ioctls_get and .Fn cap_ioctls_limit system calls first appeared in .Fx 8.3 . Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. .Sh AUTHORS This function was created by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship of the FreeBSD Foundation. diff --git a/lib/libc/sys/cap_rights_limit.2 b/lib/libc/sys/cap_rights_limit.2 index 37f311143a28..f08d5520b66e 100644 --- a/lib/libc/sys/cap_rights_limit.2 +++ b/lib/libc/sys/cap_rights_limit.2 @@ -1,161 +1,164 @@ .\" .\" Copyright (c) 2008-2010 Robert N. M. Watson .\" Copyright (c) 2012-2013 The FreeBSD Foundation .\" All rights reserved. .\" .\" This software was developed at the University of Cambridge Computer .\" Laboratory with support from a grant from Google, Inc. .\" .\" Portions of this documentation were written by Pawel Jakub Dawidek .\" under sponsorship from the FreeBSD Foundation. .\" .\" 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$ .\" -.Dd May 5, 2020 +.Dd March 9, 2023 .Dt CAP_RIGHTS_LIMIT 2 .Os .Sh NAME .Nm cap_rights_limit .Nd limit capability rights .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capsicum.h .Ft int .Fn cap_rights_limit "int fd" "const cap_rights_t *rights" .Sh DESCRIPTION When a file descriptor is created by a function such as .Xr accept 2 , .Xr accept4 2 , .Xr fhopen 2 , .Xr kqueue 2 , .Xr mq_open 2 , .Xr open 2 , .Xr openat 2 , .Xr pdfork 2 , .Xr pipe 2 , .Xr shm_open 2 , .Xr socket 2 or .Xr socketpair 2 , it is assigned all capability rights. Those rights can be reduced (but never expanded) by using the .Fn cap_rights_limit system call. Once capability rights are reduced, operations on the file descriptor will be limited to those permitted by .Fa rights . .Pp The .Fa rights argument should be prepared using .Xr cap_rights_init 3 family of functions. .Pp Capability rights assigned to a file descriptor can be obtained with the .Xr cap_rights_get 3 function. .Pp The complete list of the capability rights can be found in the .Xr rights 4 manual page. .Sh RETURN VALUES .Rv -std .Sh EXAMPLES The following example demonstrates how to limit file descriptor capability rights to allow reading only. .Bd -literal cap_rights_t setrights; char buf[1]; int fd; fd = open("/tmp/foo", O_RDWR); if (fd < 0) err(1, "open() failed"); if (cap_enter() < 0) err(1, "cap_enter() failed"); cap_rights_init(&setrights, CAP_READ); if (cap_rights_limit(fd, &setrights) < 0) err(1, "cap_rights_limit() failed"); buf[0] = 'X'; if (write(fd, buf, sizeof(buf)) > 0) errx(1, "write() succeeded!"); if (read(fd, buf, sizeof(buf)) < 0) err(1, "read() failed"); .Ed .Sh ERRORS .Fn cap_rights_limit succeeds unless: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid active descriptor. .It Bq Er EINVAL An invalid right has been requested in .Fa rights . +.It Bq Er ENOSYS +The running kernel was compiled without +.Cd "options CAPABILITY_MODE" . .It Bq Er ENOTCAPABLE The .Fa rights argument contains capability rights not present for the given file descriptor. Capability rights list can only be reduced, never expanded. .El .Sh SEE ALSO .Xr accept 2 , .Xr accept4 2 , .Xr cap_enter 2 , .Xr fhopen 2 , .Xr kqueue 2 , .Xr mq_open 2 , .Xr open 2 , .Xr openat 2 , .Xr pdfork 2 , .Xr pipe 2 , .Xr read 2 , .Xr shm_open 2 , .Xr socket 2 , .Xr socketpair 2 , .Xr write 2 , .Xr cap_rights_get 3 , .Xr cap_rights_init 3 , .Xr err 3 , .Xr capsicum 4 , .Xr rights 4 .Sh HISTORY The .Fn cap_rights_limit function first appeared in .Fx 8.3 . Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. .Sh AUTHORS This function was created by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship of the FreeBSD Foundation.