1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
<table class="head">
<tr>
<td class="head-ltitle">CAPSICUM(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">CAPSICUM(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">Capsicum</code> —
<span class="Nd">lightweight OS capability and sandbox framework</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">options CAPABILITY_MODE</code>
<br/>
<code class="Cd">options CAPABILITIES</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp"><code class="Nm">Capsicum</code> is a lightweight OS capability
and sandbox framework implementing a hybrid capability system model.
<code class="Nm">Capsicum</code> is designed to blend capabilities with
UNIX. This approach achieves many of the benefits of least-privilege
operation, while preserving existing UNIX APIs and performance, and presents
application authors with an adoption path for capability-oriented
design.</p>
<p class="Pp">Capabilities are unforgeable tokens of authority that can be
delegated and must be presented to perform an action.
<code class="Nm">Capsicum</code> makes file descriptors into
capabilities.</p>
<p class="Pp"><code class="Nm">Capsicum</code> can be used for application and
library compartmentalisation, the decomposition of larger bodies of software
into isolated (sandboxed) components in order to implement security policies
and limit the impact of software vulnerabilities.</p>
<p class="Pp"><code class="Nm">Capsicum</code> provides two core kernel
primitives:</p>
<dl class="Bl-tag">
<dt>capability mode</dt>
<dd>A process mode, entered by invoking <a class="Xr">cap_enter(2)</a>, in
which access to global OS namespaces (such as the file system and PID
namespaces) is restricted; only explicitly delegated rights, referenced by
memory mappings or file descriptors, may be used. Once set, the flag is
inherited by future children processes, and may not be cleared.
<p class="Pp">Access to system calls in capability mode is restricted: some
system calls requiring global namespace access are unavailable, while
others are constrained. For instance, <a class="Xr">sysctl(2)</a> can be
used to query process-local information such as address space layout,
but also to monitor a system's network connections.
<a class="Xr">sysctl(2)</a> is constrained by explicitly marking
≈60 of over 15000 parameters as permitted in capability mode; all
others are denied.</p>
<p class="Pp">The system calls which require constraints are
<a class="Xr">sysctl(2)</a>, <a class="Xr">shm_open(2)</a> (which is
permitted to create anonymous memory objects but not named ones) and the
<a class="Xr">openat(2)</a> family of system calls. The
<a class="Xr">openat(2)</a> calls already accept a file descriptor
argument as the directory to perform the <a class="Xr">open(2)</a>,
<a class="Xr">rename(2)</a>, etc. relative to; in capability mode the
<a class="Xr">openat(2)</a> family of system calls are constrained so
that they can only operate on objects “under” the provided
file descriptor.</p>
</dd>
<dt>capabilities</dt>
<dd>Limit operations that can be called on file descriptors. For example, a
file descriptor returned by <a class="Xr">open(2)</a> may be refined using
<a class="Xr">cap_rights_limit(2)</a> so that only
<a class="Xr">read(2)</a> and <a class="Xr">write(2)</a> can be called,
but not <a class="Xr">fchmod(2)</a>. The complete list of the capability
rights can be found in the <a class="Xr">rights(4)</a> manual page.</dd>
</dl>
<p class="Pp">In some cases, <code class="Nm">Capsicum</code> requires use of
alternatives to traditional POSIX APIs in order to name objects using
capabilities rather than global namespaces:</p>
<dl class="Bl-tag">
<dt>process descriptors</dt>
<dd>File descriptors representing processes, allowing parent processes to
manage child processes without requiring access to the PID namespace;
described in greater detail in <a class="Xr">procdesc(4)</a>.</dd>
<dt>anonymous shared memory</dt>
<dd>An extension to the POSIX shared memory API to support anonymous swap
objects associated with file descriptors; described in greater detail in
<a class="Xr">shm_open(2)</a>.</dd>
</dl>
<p class="Pp">In some cases, <code class="Nm">Capsicum</code> limits the valid
values of some parameters to traditional APIs in order to restrict access to
global namespaces:</p>
<dl class="Bl-tag">
<dt>process IDs</dt>
<dd>Processes can only act upon their own process ID with syscalls such as
<a class="Xr">cpuset_setaffinity(2)</a>.</dd>
</dl>
<p class="Pp"><span class="Ux">FreeBSD</span> provides some additional
functionality to support application sandboxing that is not part of
<code class="Nm">Capsicum</code> itself:</p>
<dl class="Bl-tag">
<dt><a class="Xr">capsicum_helpers(3)</a></dt>
<dd>A set of a inline functions which simplify modifying programs to use
<code class="Nm">Capsicum</code>.</dd>
<dt><a class="Xr">libcasper(3)</a></dt>
<dd>A library that provides services for sandboxed applications, such as
operating on files specified on a command line or establishing network
connections.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">cap_enter(2)</a>,
<a class="Xr">cap_fcntls_limit(2)</a>, <a class="Xr">cap_getmode(2)</a>,
<a class="Xr">cap_ioctls_limit(2)</a>,
<a class="Xr">cap_rights_limit(2)</a>, <a class="Xr">fchmod(2)</a>,
<a class="Xr">open(2)</a>, <a class="Xr">pdfork(2)</a>,
<a class="Xr">pdgetpid(2)</a>, <a class="Xr">pdkill(2)</a>,
<a class="Xr">pdwait4(2)</a>, <a class="Xr">read(2)</a>,
<a class="Xr">shm_open(2)</a>, <a class="Xr">write(2)</a>,
<a class="Xr">cap_rights_get(3)</a>, <a class="Xr">capsicum_helpers(3)</a>,
<a class="Xr">libcasper(3)</a>, <a class="Xr">procdesc(4)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp"><code class="Nm">Capsicum</code> first appeared in
<span class="Ux">FreeBSD 9.0</span>, and was developed at the University of
Cambridge.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><code class="Nm">Capsicum</code> was developed by
<span class="An">Robert Watson</span>
<<a class="Mt" href="mailto:rwatson@FreeBSD.org">rwatson@FreeBSD.org</a>>
and <span class="An">Jonathan Anderson</span>
<<a class="Mt" href="mailto:jonathan@FreeBSD.org">jonathan@FreeBSD.org</a>>
at the University of Cambridge, and <span class="An">Ben Laurie</span>
<<a class="Mt" href="mailto:benl@FreeBSD.org">benl@FreeBSD.org</a>>
and <span class="An">Kris Kennaway</span>
<<a class="Mt" href="mailto:kris@FreeBSD.org">kris@FreeBSD.org</a>> at
Google, Inc., and <span class="An">Pawel Jakub Dawidek</span>
<<a class="Mt" href="mailto:pawel@dawidek.net">pawel@dawidek.net</a>>.
Portions of this manual page are drawn from
<cite class="Rs"><span class="RsA">Robert N. M. Watson</span>,
<span class="RsA">Jonathan Anderson</span>, <span class="RsA">Ben
Laurie</span>, and <span class="RsA">Kris Kennaway</span>,
<span class="RsT">Capsicum: practical capabilities for UNIX</span>,
<i class="RsJ">USENIX Security Symposium</i>, <span class="RsD">August
2010</span>, <span class="RsO">DOI:
10.5555/1929820.1929824</span>.</cite></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 23, 2026</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
