2 * Copyright (c) 2008-2011 Robert N. M. Watson
3 * Copyright (c) 2010-2011 Jonathan Anderson
6 * This software was developed at the University of Cambridge Computer
7 * Laboratory with support from a grant from Google, Inc.
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in the
16 * documentation and/or other materials provided with the distribution.
18 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 * FreeBSD kernel capability facility.
34 * Two kernel features are implemented here: capability mode, a sandboxed mode
35 * of execution for processes, and capabilities, a refinement on file
36 * descriptors that allows fine-grained control over operations on the file
37 * descriptor. Collectively, these allow processes to run in the style of a
38 * historic "capability system" in which they can use only resources
39 * explicitly delegated to them. This model is enforced by restricting access
40 * to global namespaces in capability mode.
42 * Capabilities wrap other file descriptor types, binding them to a constant
43 * rights mask set when the capability is created. New capabilities may be
44 * derived from existing capabilities, but only if they have the same or a
45 * strict subset of the rights on the original capability.
47 * System calls permitted in capability mode are defined in capabilities.conf;
48 * calls must be carefully audited for safety to ensure that they don't allow
49 * escape from a sandbox. Some calls permit only a subset of operations in
50 * capability mode -- for example, shm_open(2) is limited to creating
51 * anonymous, rather than named, POSIX shared memory objects.
54 #include <sys/cdefs.h>
55 __FBSDID("$FreeBSD$");
57 #include "opt_capsicum.h"
58 #include "opt_ktrace.h"
60 #include <sys/param.h>
61 #include <sys/capability.h>
63 #include <sys/filedesc.h>
64 #include <sys/kernel.h>
66 #include <sys/mutex.h>
68 #include <sys/sysproto.h>
69 #include <sys/sysctl.h>
70 #include <sys/systm.h>
71 #include <sys/ucred.h>
73 #include <sys/ktrace.h>
75 #include <security/audit/audit.h>
80 #ifdef CAPABILITY_MODE
82 FEATURE(security_capability_mode, "Capsicum Capability Mode");
85 * System call to enter capability mode for the process.
88 sys_cap_enter(struct thread *td, struct cap_enter_args *uap)
90 struct ucred *newcred, *oldcred;
93 if (IN_CAPABILITY_MODE(td))
100 crcopy(newcred, oldcred);
101 newcred->cr_flags |= CRED_FLAG_CAPMODE;
102 p->p_ucred = newcred;
109 * System call to query whether the process is in capability mode.
112 sys_cap_getmode(struct thread *td, struct cap_getmode_args *uap)
116 i = (IN_CAPABILITY_MODE(td)) ? 1 : 0;
117 return (copyout(&i, uap->modep, sizeof(i)));
120 #else /* !CAPABILITY_MODE */
123 sys_cap_enter(struct thread *td, struct cap_enter_args *uap)
130 sys_cap_getmode(struct thread *td, struct cap_getmode_args *uap)
136 #endif /* CAPABILITY_MODE */
140 FEATURE(security_capabilities, "Capsicum Capabilities");
143 * struct capability describes a capability, and is hung off of its struct
144 * file f_data field. cap_file and cap_rightss are static once hooked up, as
145 * neither the object it references nor the rights it encapsulates are
146 * permitted to change.
149 struct file *cap_object; /* Underlying object's file. */
150 struct file *cap_file; /* Back-pointer to cap's file. */
151 cap_rights_t cap_rights; /* Mask of rights on object. */
155 * Capabilities have a fileops vector, but in practice none should ever be
156 * called except for fo_close, as the capability will normally not be
157 * returned during a file descriptor lookup in the system call code.
159 static fo_rdwr_t capability_read;
160 static fo_rdwr_t capability_write;
161 static fo_truncate_t capability_truncate;
162 static fo_ioctl_t capability_ioctl;
163 static fo_poll_t capability_poll;
164 static fo_kqfilter_t capability_kqfilter;
165 static fo_stat_t capability_stat;
166 static fo_close_t capability_close;
167 static fo_chmod_t capability_chmod;
168 static fo_chown_t capability_chown;
170 static struct fileops capability_ops = {
171 .fo_read = capability_read,
172 .fo_write = capability_write,
173 .fo_truncate = capability_truncate,
174 .fo_ioctl = capability_ioctl,
175 .fo_poll = capability_poll,
176 .fo_kqfilter = capability_kqfilter,
177 .fo_stat = capability_stat,
178 .fo_close = capability_close,
179 .fo_chmod = capability_chmod,
180 .fo_chown = capability_chown,
181 .fo_flags = DFLAG_PASSABLE,
184 static struct fileops capability_ops_unpassable = {
185 .fo_read = capability_read,
186 .fo_write = capability_write,
187 .fo_truncate = capability_truncate,
188 .fo_ioctl = capability_ioctl,
189 .fo_poll = capability_poll,
190 .fo_kqfilter = capability_kqfilter,
191 .fo_stat = capability_stat,
192 .fo_close = capability_close,
193 .fo_chmod = capability_chmod,
194 .fo_chown = capability_chown,
198 static uma_zone_t capability_zone;
201 capability_init(void *dummy __unused)
204 capability_zone = uma_zcreate("capability", sizeof(struct capability),
205 NULL, NULL, NULL, NULL, UMA_ALIGN_PTR, 0);
206 if (capability_zone == NULL)
207 panic("capability_init: capability_zone not initialized");
209 SYSINIT(vfs, SI_SUB_VFS, SI_ORDER_ANY, capability_init, NULL);
212 * Test whether a capability grants the requested rights.
215 cap_check(struct capability *c, cap_rights_t rights)
218 if ((c->cap_rights | rights) != c->cap_rights) {
220 if (KTRPOINT(curthread, KTR_CAPFAIL))
221 ktrcapfail(CAPFAIL_NOTCAPABLE, rights, c->cap_rights);
223 return (ENOTCAPABLE);
229 * Extract rights from a capability for monitoring purposes -- not for use in
230 * any other way, as we want to keep all capability permission evaluation in
234 cap_rights(struct file *fp_cap)
236 struct capability *c;
238 KASSERT(fp_cap->f_type == DTYPE_CAPABILITY,
239 ("cap_rights: !capability"));
242 return (c->cap_rights);
246 * System call to create a new capability reference to either an existing
247 * file object or an an existing capability.
250 sys_cap_new(struct thread *td, struct cap_new_args *uap)
255 cap_rights_t rights = uap->rights;
258 AUDIT_ARG_RIGHTS(rights);
259 error = fget(td, fd, rights, &fp);
262 AUDIT_ARG_FILE(td->td_proc, fp);
263 error = kern_capwrap(td, fp, rights, &capfd);
265 * Release our reference to the file (kern_capwrap has held a reference
266 * for the filedesc array).
270 td->td_retval[0] = capfd;
275 * System call to query the rights mask associated with a capability.
278 sys_cap_getrights(struct thread *td, struct cap_getrights_args *uap)
280 struct capability *cp;
284 AUDIT_ARG_FD(uap->fd);
285 error = fgetcap(td, uap->fd, &fp);
289 error = copyout(&cp->cap_rights, uap->rightsp, sizeof(*uap->rightsp));
295 * Create a capability to wrap around an existing file.
298 kern_capwrap(struct thread *td, struct file *fp, cap_rights_t rights,
301 struct capability *cp, *cp_old;
302 struct file *fp_object, *fcapp;
305 if ((rights | CAP_MASK_VALID) != CAP_MASK_VALID)
309 * If a new capability is being derived from an existing capability,
310 * then the new capability rights must be a subset of the existing
313 if (fp->f_type == DTYPE_CAPABILITY) {
315 if ((cp_old->cap_rights | rights) != cp_old->cap_rights) {
317 if (KTRPOINT(curthread, KTR_CAPFAIL))
318 ktrcapfail(CAPFAIL_INCREASE,
319 rights, cp_old->cap_rights);
321 return (ENOTCAPABLE);
326 * Allocate a new file descriptor to hang the capability off of.
328 error = falloc(td, &fcapp, capfdp, fp->f_flag);
333 * Rather than nesting capabilities, directly reference the object an
334 * existing capability references. There's nothing else interesting
335 * to preserve for future use, as we've incorporated the previous
336 * rights mask into the new one. This prevents us from having to
337 * deal with capability chains.
339 if (fp->f_type == DTYPE_CAPABILITY)
340 fp_object = ((struct capability *)fp->f_data)->cap_object;
344 cp = uma_zalloc(capability_zone, M_WAITOK | M_ZERO);
345 cp->cap_rights = rights;
346 cp->cap_object = fp_object;
347 cp->cap_file = fcapp;
348 if (fp->f_flag & DFLAG_PASSABLE)
349 finit(fcapp, fp->f_flag, DTYPE_CAPABILITY, cp,
352 finit(fcapp, fp->f_flag, DTYPE_CAPABILITY, cp,
353 &capability_ops_unpassable);
356 * Release our private reference (the proc filedesc still has one).
363 * Given a file descriptor, test it against a capability rights mask and then
364 * return the file descriptor on which to actually perform the requested
365 * operation. As long as the reference to fp_cap remains valid, the returned
366 * pointer in *fp will remain valid, so no extra reference management is
367 * required, and the caller should fdrop() fp_cap as normal when done with
371 cap_funwrap(struct file *fp_cap, cap_rights_t rights, struct file **fpp)
373 struct capability *c;
376 if (fp_cap->f_type != DTYPE_CAPABILITY) {
381 error = cap_check(c, rights);
384 *fpp = c->cap_object;
389 * Slightly different routine for memory mapping file descriptors: unwrap the
390 * capability and check CAP_MMAP, but also return a bitmask representing the
391 * maximum mapping rights the capability allows on the object.
394 cap_funwrap_mmap(struct file *fp_cap, cap_rights_t rights, u_char *maxprotp,
397 struct capability *c;
401 if (fp_cap->f_type != DTYPE_CAPABILITY) {
403 *maxprotp = VM_PROT_ALL;
407 error = cap_check(c, rights | CAP_MMAP);
410 *fpp = c->cap_object;
412 if (c->cap_rights & CAP_READ)
413 maxprot |= VM_PROT_READ;
414 if (c->cap_rights & CAP_WRITE)
415 maxprot |= VM_PROT_WRITE;
416 if (c->cap_rights & CAP_MAPEXEC)
417 maxprot |= VM_PROT_EXECUTE;
423 * When a capability is closed, simply drop the reference on the underlying
424 * object and free the capability. fdrop() will handle the case where the
425 * underlying object also needs to close, and the caller will have already
426 * performed any object-specific lock or mqueue handling.
429 capability_close(struct file *fp, struct thread *td)
431 struct capability *c;
432 struct file *fp_object;
434 KASSERT(fp->f_type == DTYPE_CAPABILITY,
435 ("capability_close: !capability"));
438 fp->f_ops = &badfileops;
440 fp_object = c->cap_object;
441 uma_zfree(capability_zone, c);
442 return (fdrop(fp_object, td));
446 * In general, file descriptor operations should never make it to the
447 * capability, only the underlying file descriptor operation vector, so panic
448 * if we do turn up here.
451 capability_read(struct file *fp, struct uio *uio, struct ucred *active_cred,
452 int flags, struct thread *td)
455 panic("capability_read");
459 capability_write(struct file *fp, struct uio *uio, struct ucred *active_cred,
460 int flags, struct thread *td)
463 panic("capability_write");
467 capability_truncate(struct file *fp, off_t length, struct ucred *active_cred,
471 panic("capability_truncate");
475 capability_ioctl(struct file *fp, u_long com, void *data,
476 struct ucred *active_cred, struct thread *td)
479 panic("capability_ioctl");
483 capability_poll(struct file *fp, int events, struct ucred *active_cred,
487 panic("capability_poll");
491 capability_kqfilter(struct file *fp, struct knote *kn)
494 panic("capability_kqfilter");
498 capability_stat(struct file *fp, struct stat *sb, struct ucred *active_cred,
502 panic("capability_stat");
506 capability_chmod(struct file *fp, mode_t mode, struct ucred *active_cred,
510 panic("capability_chmod");
514 capability_chown(struct file *fp, uid_t uid, gid_t gid,
515 struct ucred *active_cred, struct thread *td)
518 panic("capability_chown");
521 #else /* !CAPABILITIES */
524 * Stub Capability functions for when options CAPABILITIES isn't compiled
528 sys_cap_new(struct thread *td, struct cap_new_args *uap)
535 sys_cap_getrights(struct thread *td, struct cap_getrights_args *uap)
542 cap_funwrap(struct file *fp_cap, cap_rights_t rights, struct file **fpp)
545 KASSERT(fp_cap->f_type != DTYPE_CAPABILITY,
546 ("cap_funwrap: saw capability"));
553 cap_funwrap_mmap(struct file *fp_cap, cap_rights_t rights, u_char *maxprotp,
557 KASSERT(fp_cap->f_type != DTYPE_CAPABILITY,
558 ("cap_funwrap_mmap: saw capability"));
561 *maxprotp = VM_PROT_ALL;
565 #endif /* CAPABILITIES */