From owner-svn-src-stable-9@FreeBSD.ORG Mon Nov 28 14:36:07 2011 Return-Path: Delivered-To: svn-src-stable-9@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 7A7F11065670; Mon, 28 Nov 2011 14:36:07 +0000 (UTC) (envelope-from rwatson@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 687C98FC16; Mon, 28 Nov 2011 14:36:07 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id pASEa7Bg095240; Mon, 28 Nov 2011 14:36:07 GMT (envelope-from rwatson@svn.freebsd.org) Received: (from rwatson@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id pASEa69L095237; Mon, 28 Nov 2011 14:36:06 GMT (envelope-from rwatson@svn.freebsd.org) Message-Id: <201111281436.pASEa69L095237@svn.freebsd.org> From: Robert Watson Date: Mon, 28 Nov 2011 14:36:06 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-9@freebsd.org X-SVN-Group: stable-9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r228069 - stable/9/share/man/man4 X-BeenThere: svn-src-stable-9@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for only the 9-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 28 Nov 2011 14:36:07 -0000 Author: rwatson Date: Mon Nov 28 14:36:06 2011 New Revision: 228069 URL: http://svn.freebsd.org/changeset/base/228069 Log: Merge r228039 from head to stable/9: 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. Sponsored by: Google, Inc. Approved by: re (kib) Added: stable/9/share/man/man4/capsicum.4 - copied unchanged from r228039, head/share/man/man4/capsicum.4 Modified: stable/9/share/man/man4/Makefile Directory Properties: stable/9/share/man/man4/ (props changed) Modified: stable/9/share/man/man4/Makefile ============================================================================== --- stable/9/share/man/man4/Makefile Mon Nov 28 14:23:09 2011 (r228068) +++ stable/9/share/man/man4/Makefile Mon Nov 28 14:36:06 2011 (r228069) @@ -68,6 +68,7 @@ MAN= aac.4 \ bt.4 \ bwi.4 \ bwn.4 \ + capsicum.4 \ cardbus.4 \ carp.4 \ cas.4 \ Copied: stable/9/share/man/man4/capsicum.4 (from r228039, head/share/man/man4/capsicum.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/9/share/man/man4/capsicum.4 Mon Nov 28 14:36:06 2011 (r228069, copy of r228039, head/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 .