From e71dd639f0bdbd24d408a3e53d461a0d4dfad802 Mon Sep 17 00:00:00 2001 From: Robert Watson Date: Sun, 27 Nov 2011 19:44:15 +0000 Subject: [PATCH] Add an introductory Capsicum man page providing a high-level description of its mechanisms, pointing at other pertinent man pages, and cautioning about the experimental status of Capsicum in FreeBSD. MFC after: 3 days Sponsored by: Google, Inc. --- share/man/man4/Makefile | 1 + share/man/man4/capsicum.4 | 120 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 share/man/man4/capsicum.4 diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 91edb5063a2a..07071311ac57 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -67,6 +67,7 @@ MAN= aac.4 \ bt.4 \ bwi.4 \ bwn.4 \ + capsicum.4 \ cardbus.4 \ carp.4 \ cas.4 \ diff --git a/share/man/man4/capsicum.4 b/share/man/man4/capsicum.4 new file mode 100644 index 000000000000..980ab79152ee --- /dev/null +++ b/share/man/man4/capsicum.4 @@ -0,0 +1,120 @@ +.\" +.\" Copyright (c) 2011 Robert N. M. Watson +.\" Copyright (c) 2011 Jonathan Anderson +.\" All rights reserved. +.\" +.\" 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 September 20, 2011 +.Dt CAPSICUM 4 +.Os +.Sh NAME +.Nm Capsicum +.Nd lightweight OS capability and sandbox framework +.Sh SYNOPSIS +.Cd "options CAPABILITY_MODE" +.Cd "options CAPABILITIES" +.Cd "options PROCDESC" +.Sh DESCRIPTION +.Nm +is a lightweight OS capability and sandbox framework implementing a hybrid +capability system model. +.Nm +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. +.Pp +.Nm +provides two core kernel primitives: +.Bl -tag -width indent +.It capability mode +A process mode, entered by invoking +.Xr cap_enter 2 , +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 proceses, and may not be +cleared. +.It capabilities +File descriptors that wrap other file descriptors, masking operations that can +be called on them; for example, a file descriptor returned by +.Xr open 2 +may be refined using +.Xr cap_new 2 +so that only +.Xr read 2 +and +.Xr write 2 +can be called, but not +.Xr fchmod 2 . +.El +.Pp +In some cases, +.Nm +requires use of alternatives to traditional POSIX APIs in order to name +objects using capabilities rather than global namespaces: +.Bl -tag -width indent +.It process descriptors +File descriptors representing processes, allowing parent processes to manage +child processes without requiring access to the PID namespace. +.It anonymous shared memory +An extension to the POSIX shared memory API to support anonymous swap objects +associated with file descriptors. +.El +.Sh SEE ALSO +.Xr cap_enter 2 , +.Xr cap_getmode 2 , +.Xr cap_getrights 2 , +.Xr cap_new 2 , +.Xr fchmod 2 , +.Xr open 2 , +.Xr pdfork 2 , +.Xr pdgetpid 2 , +.Xr pdkill 2 , +.Xr pdwait4 2 , +.Xr read 2 , +.Xr shm_open 2 , +.Xr write 2 +.Sh HISTORY +.Nm +first appeared in +.Fx 9.0 , +and was developed at the University of Cambridge. +.Sh AUTHORS +.Nm +was developed by +.An -nosplit +.An "Robert Watson" Aq rwatson@FreeBSD.org +and +.An "Jonathan Anderson" Aq jonathan@FreeBSD.org +at the University of Cambridge, and +.An "Ben Laurie" Aq benl@FreeBSD.org +and +.An "Kris Kennaway" Aq kris@FreeBSD.org +at Google, Inc. +.Sh BUGS +.Nm +is considered experimental in +.Fx .