From owner-p4-projects@FreeBSD.ORG Mon Jun 15 11:38:50 2009 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 36DB5106566C; Mon, 15 Jun 2009 11:38:50 +0000 (UTC) Delivered-To: perforce@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id EA8E6106566B for ; Mon, 15 Jun 2009 11:38:49 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id D60118FC13 for ; Mon, 15 Jun 2009 11:38:49 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.3/8.14.3) with ESMTP id n5FBcn3H079074 for ; Mon, 15 Jun 2009 11:38:49 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.3/8.14.3/Submit) id n5FBcnkt079072 for perforce@freebsd.org; Mon, 15 Jun 2009 11:38:49 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Date: Mon, 15 Jun 2009 11:38:49 GMT Message-Id: <200906151138.n5FBcnkt079072@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to bb+lists.freebsd.perforce@cyrus.watson.org using -f From: Robert Watson To: Perforce Change Reviews Cc: Subject: PERFORCE change 164418 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 15 Jun 2009 11:38:51 -0000 http://perforce.freebsd.org/chv.cgi?CH=164418 Change 164418 by rwatson@rwatson_freebsd_capabilities on 2009/06/15 11:38:21 Push API information on creating and managing sandboxes into host and sandbox man pages. Refine the introduction in libcapability.3. Affected files ... .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#19 edit .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability_host.3#3 edit .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability_sandbox.3#4 edit Differences ... ==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#19 (text+ko) ==== @@ -46,63 +46,52 @@ .In libcapability.h .Ft int .Fn lc_limitfd "int fd" "cap_rights_t rights" -.Ft int -.Fn lch_start "const char *sandbox" "char *const argv[]" "struct lc_sandbox **lcsp" -.Ft int -.Fn lch_start_flags "const char *sandbox" "char *const argv[]" "u_int flags" "struct lc_sandbox **lcsp" -.Ft int -.Fn lch_startfd "int fd_sandbox" "char *const argv[]" "struct lc_sandbox **lcsp" -.Ft int -.Fn lch_startfd_flags "int fd_sandbox" "char *const argv[]" "u_int flags" "struct lc_sandbox **lcsp" -.Ft void -.Fn lch_stop "struct lc_sandbox *lcsp" -.Ft int -.Fn lch_getsock "struct lc_sandbox *lcsp" "int *fdp" -.Ft int -.Fn lch_getpid "struct lc_sandbox *lcsp" "pid_t *pidp" -.Ft int -.Fn lch_getprocdesc "struct lc_sandbox *lcsp" "int *fdp" -.Ft int -.Fn lcs_get "struct lc_host **lchpp" -.Ft int -.Fn lcs_getsock "struct lc_host *lchp" "int *fdp" .Sh DESCRIPTION -The +.Nm +implements APIs that allow applications to create, manage, and interact with +sandboxed software services running in capability mode, described in +.Xr cap_enter 2 . +Applications linked against +.Nm +will use one or both of "host" and "sandbox" APIs, depending on whether they +consume or produce sandboxed services. +.Pp +Host processes use the +.Nm +host API, +described in +.Xr libcapability_host 3 , +to launch compartmentalized components in sandboxes. +They may also use .Nm -library routines provide services for processes hosting or running in -capability mode. -Depending on the requirements of the host and sandbox, the API can simply be -used to set up and stop sandboxes, used to manage I/O using a -.Xr unix 4 -domain socket connection to the sandbox, or can provide a basic remote -procedure call (RPC) facility. -Applications may also use RPC generators such as -.Xr rpcgen 1 -to build event handling and marshaling code. -The +to communication with the sandboxed service based on socket I/O or remote +procedure call (RPC). +.Pp +.Pp +Sandbox processes run in capability mode, and are only able to use resources +either assigned to the sandbox during creation, or later explicitly passed to +the process. +Sandbox processes use the .Nm -library comes in two variations: +sandbox API, +described in +.Xr libcapability_sandbox 3 . +Sandboxed processes themselves may launch software components in further +sandboxes, so a single program may use both host and sandbox APIs. +.Pp +Applications will link against one of two versions of the library: .Pp .Nm libcapability -loads binaries, and supporting libraries, for sandboxes from the UNIX -filesystem namespace by path. -It implements four start functions: -.Fn lch_start , -.Fn lch_start_flags , -.Fn lch_startfd , -and -.Fn lch_startfd_flags . +is intended to run in an unsandboxed environment, and is appropriate for use +by application running with full user privileges. +It relies on the UNIX file system namespace to load software components that +will be executed in sandboxes. .Pp .Nm libcapabilitym -loads binaries, and supporting libraries, for sandboxes from the library -descriptor cache maintained by -.Xr rtld-elf-cap 1 -It implements only the two start functions accepting file descriptor -arguments: -.Fn lch_startfd , -and -.Fn lch_startfd_flags . -.Pp +is intended to run in a sandboxed environment, and loads binaries and +supporting libraries for sandboxes from the library descriptor cache +maintained by +.Xr rtld-elf-cap 1 . .Sh CAPABILITY API .Fn lc_limitfd is a wrapper around @@ -112,84 +101,6 @@ .Xr close 2 . which takes an existing file descriptor and replaces it with a capability with the requested rights mask. -.Sh HOST API -The -.Nm -host API allows processes to start, stop, and manage sandboxes running in -capability mode. -Host API functions can be identified by their function name prefix, -.Dv lch_ . -.Pp -Each executing sandbox instance is described by an opaque -.Dt "struct lc_sandbox" , -which is returned by -.Fn lch_start -and -.Fn lch_start_flags -for successfully started sandboxes, and passed into other APIs to indicate -which sandbox should be acted on. -Both calls create new executing sandboxes, given the name of the sandbox -binary via -.Va sandbox , -and command line arguments -.Va argv . -.Pp -.Fn lch_start_flags -accepts an optional flags field to fine-tune aspects of sandbox operation; -the only currently defined flag is -.Dv LCH_PERMIT_STDERR , -which allows the sandbox to write to the current process's -.Dv stderr . -By default, this is not permitted. -.Pp -Two further variations to start sandboxes are also defined, -.Fn lch_startfd -and -.Fn lch_startfd_flags , -which accept a file descriptor argument, -.Va fd_sandbox , -rather than a path. -.Pp -Executing sandboxes may be stopped (and all state freed) using -.Fn lch_stop . -Following a call to -.Fn lch_stop , -the -.Va lchp -argument will no longer be valid. -.Pp -Properties of the sandbox, such as the socket used to communicate with it, -the proces descriptor for the sandbox process, and the pid, may be queried -using -.Fn lch_getsock , -.Fn lch_getprocdesc , -and -.Fn lch_getpid . -.Pp -.Nm -implements a number of I/O functions as part of the host API, which are -documented in -.Xr libcapability_host 3 . -.Sh SANDBOX API -The -.Nm -sandbox API allows sandbox processes to interact with their host process. -Sandbox API functions can be identified by their function name prefix, -.Dv lcs_ . -.Pp -Each executing sandbox will have a single corresponding host instance, -described by an opaque -.Dt "struct lc_host" , -which is returned by -.Fn lcs_get . -.Pp -The socket for the host may be queried using -.Fn lcs_getsock . -.Pp -.Nm -implements a number of I/O functions as part of the sandbox API, which are -documented in -.Xr libcapability_sandbox 3 . .Sh SEE ALSO .Xr rpcgen 1 , .Xr cap_enter 2 , ==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability_host.3#3 (text+ko) ==== @@ -44,6 +44,22 @@ .In sys/types.h .In sys/capability.h .In libcapability.h +.Ft int +.Fn lch_start "const char *sandbox" "char *const argv[]" "struct lc_sandbox **lcsp" +.Ft int +.Fn lch_start_flags "const char *sandbox" "char *const argv[]" "u_int flags" "struct lc_sandbox **lcsp" +.Ft int +.Fn lch_startfd "int fd_sandbox" "char *const argv[]" "struct lc_sandbox **lcsp" +.Ft int +.Fn lch_startfd_flags "int fd_sandbox" "char *const argv[]" "u_int flags" "struct lc_sandbox **lcsp" +.Ft void +.Fn lch_stop "struct lc_sandbox *lcsp" +.Ft int +.Fn lch_getsock "struct lc_sandbox *lcsp" "int *fdp" +.Ft int +.Fn lch_getpid "struct lc_sandbox *lcsp" "pid_t *pidp" +.Ft int +.Fn lch_getprocdesc "struct lc_sandbox *lcsp" "int *fdp" .Ft ssize_t .Fn lch_recv "struct lc_sandbox *lcsp, void *buf" "size_t len" "int flags" .Ft ssize_t @@ -70,12 +86,71 @@ .Xr rpcgen 1 to build event handling and marshaling code. .Pp -This man page describes host I/O facilities; information on setting up -and managing sandboxes may be found in -.Xr libcapability 3 ; -information on sandbox I/O facilities may be found in +This man page describes the host API. +General information on +.Nm +may be found in +.Xr libcapability 3. +Information on the sandbox API may be found in .Xr libcapability_sandbox 3 . .Sh HOST API +The +.Nm +host API allows processes to start, stop, and manage sandboxes running in +capability mode. +Host API functions can be identified by their function name prefix, +.Dv lch_ . +.Pp +Each executing sandbox instance is described by an opaque +.Dt "struct lc_sandbox" , +which is returned by +.Fn lch_start +and +.Fn lch_start_flags +for successfully started sandboxes, and passed into other APIs to indicate +which sandbox should be acted on. +Both calls create new executing sandboxes, given the name of the sandbox +binary via +.Va sandbox , +and command line arguments +.Va argv . +.Pp +.Fn lch_start_flags +accepts an optional flags field to fine-tune aspects of sandbox operation; +the only currently defined flag is +.Dv LCH_PERMIT_STDERR , +which allows the sandbox to write to the current process's +.Dv stderr . +By default, this is not permitted. +.Pp +Two further variations to start sandboxes are also defined, +.Fn lch_startfd +and +.Fn lch_startfd_flags , +which accept a file descriptor argument, +.Va fd_sandbox , +rather than a path. +.Pp +Executing sandboxes may be stopped (and all state freed) using +.Fn lch_stop . +Following a call to +.Fn lch_stop , +the +.Va lchp +argument will no longer be valid. +.Pp +Properties of the sandbox, such as the socket used to communicate with it, +the proces descriptor for the sandbox process, and the pid, may be queried +using +.Fn lch_getsock , +.Fn lch_getprocdesc , +and +.Fn lch_getpid . +.Pp +.Nm +implements a number of I/O functions as part of the host API, which are +documented in +.Xr libcapability_host 3 . .Fn lch_recv and .Fn lch_send ==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability_sandbox.3#4 (text+ko) ==== @@ -44,6 +44,10 @@ .In sys/types.h .In sys/capability.h .In libcapability.h +.Ft int +.Fn lcs_get "struct lc_host **lchpp" +.Ft int +.Fn lcs_getsock "struct lc_host *lchp" "int *fdp" .Ft ssize_t .Fn lcs_recv "struct lc_host *lchp" "void *buf" "size_t len" "int flags" .Ft ssize_t @@ -74,12 +78,31 @@ .Xr rpcgen 1 to build event handling and marshaling code. .Pp -This man page describes sandbox I/O facilities; information on setting up -and managing sandboxes may be found in -.Xr libcapability 3 ; -information on host I/O facilities may be found in -.Xr libcapability_host 3 . +This man page describes the sandbox API. +General information on +.Nm +may be found in +.Xr libcapability 3. .Sh SANDBOX API +The +.Nm +sandbox API allows sandbox processes to interact with their host process. +Sandbox API functions can be identified by their function name prefix, +.Dv lcs_ . +.Pp +Each executing sandbox will have a single corresponding host instance, +described by an opaque +.Dt "struct lc_host" , +which is returned by +.Fn lcs_get . +.Pp +The socket for the host may be queried using +.Fn lcs_getsock . +.Pp +.Nm +implements a number of I/O functions as part of the sandbox API, which are +documented in +.Xr libcapability_sandbox 3 . .Fn lcs_recv and .Fn lcs_send @@ -140,13 +163,6 @@ .Sh BUGS WARNING: THIS IS EXPERIMENTAL SECURITY SOFTWARE THAT MUST NOT BE RELIED ON IN PRODUCTION SYSTEMS. IT WILL BREAK YOUR SOFTWARE IN NEW AND UNEXPECTED WAYS. -.Pp -All sequence numbers will always have the value 0. -This is fine from a retransmission perspective, as generally no -retransmission should be required, but consumers should serialize use of the -RPC service when consuming it from concurrent callers (such as multiple -threads or multiple processes) to prevent I/O interlacing from corrupting the -RPC stream. .Sh AUTHORS These functions and the capability facility were created by .An "Robert N. M. Watson"