Date: Mon, 15 Jun 2009 11:38:49 GMT From: Robert Watson <rwatson@FreeBSD.org> To: Perforce Change Reviews <perforce@freebsd.org> Subject: PERFORCE change 164418 for review Message-ID: <200906151138.n5FBcnkt079072@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
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"
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200906151138.n5FBcnkt079072>