1.\" 2.\" Copyright (c) 2008-2009 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" This software was developed at the University of Cambridge Computer 6.\" Laboratory with support from a grant from Google, Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd March 9, 2023 30.Dt CAP_ENTER 2 31.Os 32.Sh NAME 33.Nm cap_enter , 34.Nm cap_getmode 35.Nd Capability mode system calls 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In sys/capsicum.h 40.Ft int 41.Fn cap_enter "void" 42.Ft int 43.Fn cap_getmode "u_int *modep" 44.Sh DESCRIPTION 45.Fn cap_enter 46places the current process into capability mode, a mode of execution in which 47processes may only issue system calls operating on file descriptors or 48reading limited global system state. 49Access to global name spaces, such as file system or IPC name spaces, is 50prevented. 51If the process is already in a capability mode sandbox, the system call is a 52no-op. 53Future process descendants created with 54.Xr fork 2 55or 56.Xr pdfork 2 57will be placed in capability mode from inception. 58.Pp 59When combined with 60.Xr cap_rights_limit 2 , 61.Xr cap_ioctls_limit 2 , 62.Xr cap_fcntls_limit 2 , 63.Fn cap_enter 64may be used to create kernel-enforced sandboxes in which 65appropriately-crafted applications or application components may be run. 66.Pp 67.Fn cap_getmode 68returns a flag indicating whether or not the process is in a capability mode 69sandbox. 70.Sh RUN-TIME SETTINGS 71If the 72.Dv kern.trap_enotcap 73sysctl MIB is set to a non-zero value, then for any process executing in a 74capability mode sandbox, any syscall which results in either an 75.Er ENOTCAPABLE 76or 77.Er ECAPMODE 78error also generates the synchronous 79.Dv SIGTRAP 80signal to the thread on the syscall return. 81On signal delivery, the 82.Va si_errno 83member of the 84.Fa siginfo 85signal handler parameter is set to the syscall error value, 86and the 87.Va si_code 88member is set to 89.Dv TRAP_CAP . 90.Pp 91See also the 92.Dv PROC_TRAPCAP_CTL 93and 94.Dv PROC_TRAPCAP_STATUS 95operations of the 96.Xr procctl 2 97function for similar per-process functionality. 98.Sh RETURN VALUES 99.Rv -std cap_enter cap_getmode 100.Pp 101When the process is in capability mode, 102.Fn cap_getmode 103sets the flag to a non-zero value. 104A zero value means the process is not in capability mode. 105.Sh ERRORS 106The 107.Fn cap_enter 108and 109.Fn cap_getmode 110system calls 111will fail if: 112.Bl -tag -width Er 113.It Bq Er ENOSYS 114The running kernel was compiled without 115.Cd "options CAPABILITY_MODE" . 116.El 117.Pp 118The 119.Fn cap_getmode 120system call may also return the following error: 121.Bl -tag -width Er 122.It Bq Er EFAULT 123Pointer 124.Fa modep 125points outside the process's allocated address space. 126.El 127.Sh SEE ALSO 128.Xr cap_fcntls_limit 2 , 129.Xr cap_ioctls_limit 2 , 130.Xr cap_rights_limit 2 , 131.Xr fexecve 2 , 132.Xr procctl 2 , 133.Xr cap_sandboxed 3 , 134.Xr capsicum 4 , 135.Xr sysctl 9 136.Sh HISTORY 137The 138.Fn cap_getmode 139system call first appeared in 140.Fx 8.3 . 141Support for capabilities and capabilities mode was developed as part of the 142.Tn TrustedBSD 143Project. 144.Sh AUTHORS 145These functions and the capability facility were created by 146.An "Robert N. M. Watson" 147at the University of Cambridge Computer Laboratory with support from a grant 148from Google, Inc. 149.Sh CAVEATS 150Creating effective process sandboxes is a tricky process that involves 151identifying the least possible rights required by the process and then 152passing those rights into the process in a safe manner. 153Consumers of 154.Fn cap_enter 155should also be aware of other inherited rights, such as access to VM 156resources, memory contents, and other process properties that should be 157considered. 158It is advisable to use 159.Xr fexecve 2 160to create a runtime environment inside the sandbox that has as few implicitly 161acquired rights as possible. 162