PERFORCE change 164418 for review

[Robert Watson]

http://perforce.freebsd.org/chv.cgi?CH=164418

Change 164418 by rwatson at 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"