Author: rwatson Date: Sun Nov 27 19:44:15 2011 New Revision: 228039 URL: http://svn.freebsd.org/changeset/base/228039
Log: 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. Added: head/share/man/man4/capsicum.4 (contents, props changed) Modified: head/share/man/man4/Makefile Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Sun Nov 27 19:36:36 2011 (r228038) +++ head/share/man/man4/Makefile Sun Nov 27 19:44:15 2011 (r228039) @@ -67,6 +67,7 @@ MAN= aac.4 \ bt.4 \ bwi.4 \ bwn.4 \ + capsicum.4 \ cardbus.4 \ carp.4 \ cas.4 \ Added: head/share/man/man4/capsicum.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/capsicum.4 Sun Nov 27 19:44:15 2011 (r228039) @@ -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 rwat...@freebsd.org +and +.An "Jonathan Anderson" Aq jonat...@freebsd.org +at the University of Cambridge, and +.An "Ben Laurie" Aq b...@freebsd.org +and +.An "Kris Kennaway" Aq k...@freebsd.org +at Google, Inc. +.Sh BUGS +.Nm +is considered experimental in +.Fx . _______________________________________________ svn-src-head@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-head To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"