1.\" 2.\" Copyright (c) 2011, 2013 Robert N. M. Watson 3.\" Copyright (c) 2011 Jonathan Anderson 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd January 3, 2024 28.Dt CAPSICUM 4 29.Os 30.Sh NAME 31.Nm Capsicum 32.Nd lightweight OS capability and sandbox framework 33.Sh SYNOPSIS 34.Cd "options CAPABILITY_MODE" 35.Cd "options CAPABILITIES" 36.Sh DESCRIPTION 37.Nm 38is a lightweight OS capability and sandbox framework implementing a hybrid 39capability system model. 40Capabilities are unforgeable tokens of authority that can be delegated and must 41be presented to perform an action. 42.Nm 43makes file descriptors into capabilities. 44.Pp 45.Nm 46can be used for application and library compartmentalisation, the 47decomposition of larger bodies of software into isolated (sandboxed) 48components in order to implement security policies and limit the impact of 49software vulnerabilities. 50.Pp 51.Nm 52provides two core kernel primitives: 53.Bl -tag -width indent 54.It capability mode 55A process mode, entered by invoking 56.Xr cap_enter 2 , 57in which access to global OS namespaces (such as the file system and PID 58namespaces) is restricted; only explicitly delegated rights, referenced by 59memory mappings or file descriptors, may be used. 60Once set, the flag is inherited by future children processes, and may not be 61cleared. 62.It capabilities 63Limit operations that can be called on file descriptors. 64For example, a file descriptor returned by 65.Xr open 2 66may be refined using 67.Xr cap_rights_limit 2 68so that only 69.Xr read 2 70and 71.Xr write 2 72can be called, but not 73.Xr fchmod 2 . 74The complete list of the capability rights can be found in the 75.Xr rights 4 76manual page. 77.El 78.Pp 79In some cases, 80.Nm 81requires use of alternatives to traditional POSIX APIs in order to name 82objects using capabilities rather than global namespaces: 83.Bl -tag -width indent 84.It process descriptors 85File descriptors representing processes, allowing parent processes to manage 86child processes without requiring access to the PID namespace; described in 87greater detail in 88.Xr procdesc 4 . 89.It anonymous shared memory 90An extension to the POSIX shared memory API to support anonymous swap objects 91associated with file descriptors; described in greater detail in 92.Xr shm_open 2 . 93.El 94.Pp 95In some cases, 96.Nm 97limits the valid values of some parameters to traditional APIs in order to 98restrict access to global namespaces: 99.Bl -tag -width indent 100.It process IDs 101Processes can only act upon their own process ID with syscalls such as 102.Xr cpuset_setaffinity 2 . 103.El 104.Sh SEE ALSO 105.Xr cap_enter 2 , 106.Xr cap_fcntls_limit 2 , 107.Xr cap_getmode 2 , 108.Xr cap_ioctls_limit 2 , 109.Xr cap_rights_limit 2 , 110.Xr fchmod 2 , 111.Xr open 2 , 112.Xr pdfork 2 , 113.Xr pdgetpid 2 , 114.Xr pdkill 2 , 115.Xr pdwait4 2 , 116.Xr read 2 , 117.Xr shm_open 2 , 118.Xr write 2 , 119.Xr cap_rights_get 3 , 120.Xr capsicum_helpers 3 , 121.Xr libcasper 3 , 122.Xr procdesc 4 123.Sh HISTORY 124.Nm 125first appeared in 126.Fx 9.0 , 127and was developed at the University of Cambridge. 128.Sh AUTHORS 129.Nm 130was developed by 131.An -nosplit 132.An Robert Watson Aq Mt rwatson@FreeBSD.org 133and 134.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org 135at the University of Cambridge, and 136.An Ben Laurie Aq Mt benl@FreeBSD.org 137and 138.An Kris Kennaway Aq Mt kris@FreeBSD.org 139at Google, Inc., and 140.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net . 141