PERFORCE change 164358 for review

Sun Jun 14 17:49:25 UTC 2009

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

Change 164358 by rwatson at rwatson_freebsd_capabilities on 2009/06/14 17:49:21

	Distribute contents of original libcapability(3) over that page
	and the new libcapability_io(3).

Affected files ...

.. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#16 edit
.. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability_io.3#2 edit

Differences ...

==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#16 (text+ko) ====

@@ -34,7 +34,7 @@
 .\"
 .Dd June 11, 2009
 .Os
-.Dt LIBCAP 3
+.Dt LIBCAPABILITY 3
 .Sh NAME
 .Nm libcapability
 .Nd "library interface to capability-mode services"
@@ -62,24 +62,10 @@
 .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 int
-.Fn lch_rpc "struct lc_sandbox *lcsp" "u_int32_t opno" "struct iovec *req" "int reqcount" "struct iovec *rep" "int repcount" "size_t *replenp"
-.Ft ssize_t
-.Fn lch_send "struct lc_sandbox *lcsp" "const void *msg" "size_t len" "int flags"
 .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 int
-.Fn lcs_recvrpc "struct lc_host *lchp" "u_int32_t *opnop" "u_int32_t *seqnop" "u_char **bufferp" "size_t *lenp"
-.Ft ssize_t
-.Fn lcs_send "struct lc_host *lchp" "const void *msg" "size_t len" "int flags"
-.Ft int
-.Fn lcs_sendrpc "struct lc_host *lchp" "u_int32_t opno" "u_int32_t seqno" "struct iovec *rep" "int repcount"
 .Sh DESCRIPTION
 The
 .Nm
@@ -116,6 +102,7 @@
 .Fn lch_startfd ,
 and
 .Fn lch_startfd_flags .
+.Pp
 .Sh CAPABILITY API
 .Fn lc_limitfd
 is a wrapper around
@@ -178,40 +165,10 @@
 and
 .Fn lch_getpid .
 .Pp
-.Fn lch_recv
-and
-.Fn lch_send
-provide simple wrappers around
-.Xr recv 2
-and
-.Xr send 2
-to avoid sandbox consumers from having to query sandbox socket file
-descriptors before use.
-.Pp
-.Fn lch_rpc
-provides a simple synchronous RPC facility, and is intended to be used in
-coordination with the
-.Fn lcs_recvrpc
-and
-.Fn lcs_sendrpc
-sandbox APIs.
-The host provides an operation number meaningful to th sandbox,
-.Va opno,
-RPC arguments represented by
-.Va req
-and
-.Va reqcount
-using an
-.Vt iovec
-in the style of
-.Xr writev 2 ,
-and similar receive buffers passed via
-.Va rep
-and
-.Va repcount .
-If the RPC fails, -1 will be returned, or 0 and the size of any reply will be
-returned by reference using
-.Va replenp .
+.Nm
+implements a number of I/O functions as part of the host API, which are
+documented in
+.Xr libcapability_io 3 .
 .Sh SANDBOX API
 The
 .Nm
@@ -228,54 +185,16 @@
 The socket for the host may be queried using
 .Fn lcs_getsock .
 .Pp
-.Fn lcs_recv
-and
-.Fn lcs_send
-provide simple wrappers around
-.Xr recv 2
-and
-.Xr send 2
-to avoid sandboxes having to query host socket file descriptors before use.
-.Pp
-.Fn lcs_recvrpc
-and
-.Fn lcs_sendrpc
-may be used to implement a simple RPC system, in coordination with a host
-using
-.Fn lch_rpc .
-.Fn lcs_recvrpc
-blocks awaiting the receipt of an RPC request, which will be returned in a
-buffer allocated using
-.Xr malloc 3 ,
-.Va bufferp ,
-and with a data size returned via
-.Va lenp .
-The caller will also receive an operation number and a sequence number via
-.Va opnop
-and
-.Va seqnop .
-.Pp
-When an RPC is complete, it should be returned to the host via
-.Fn lcs_sendrpc ,
-which accepts the same operation and sequence number as arguments, as well as
-reply data via the
-.Vt iovec
-.Va rep
-and
-.Va repcount .
-When the sandbox is done with the request data, it should free the memory
-using
-.Xr free 3 .
+.Nm
+implements a number of I/O functions as part of the sandbox API, which are
+documented in
+.Xr libcapability_io 3 .
 .Sh SEE ALSO
 .Xr rpcgen 1 ,
 .Xr cap_enter 2 ,
 .Xr cap_new 2 ,
 .Xr dup2 2 ,
-.Xr recv 2 ,
-.Xr send 2 ,
-.Xr writev 2 ,
-.Xr free 3 ,
-.Xr malloc 3 ,
+.Xr libcapability_io 3 ,
 .Xr unix 4
 .Sh HISTORY
 Support for capabilities and capabilities mode was developed as part of the
@@ -284,16 +203,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
-The socket calls used by the simple RPC system are not robust in the presence
-of signal delivery, which should be fixed.
-.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"

==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability_io.3#2 (text+ko) ====

@@ -34,7 +34,7 @@
 .\"
 .Dd June 11, 2009
 .Os
-.Dt LIBCAP 3
+.Dt LIBCAPABILITY_IO 3
 .Sh NAME
 .Nm libcapability
 .Nd "library interface to capability-mode services"
@@ -44,34 +44,12 @@
 .In sys/types.h
 .In sys/capability.h
 .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 ssize_t
 .Fn lch_recv "struct lc_sandbox *lcsp, void *buf" "size_t len" "int flags"
 .Ft int
 .Fn lch_rpc "struct lc_sandbox *lcsp" "u_int32_t opno" "struct iovec *req" "int reqcount" "struct iovec *rep" "int repcount" "size_t *replenp"
 .Ft ssize_t
 .Fn lch_send "struct lc_sandbox *lcsp" "const void *msg" "size_t len" "int flags"
-.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 int
@@ -93,91 +71,11 @@
 Applications may also use RPC generators such as
 .Xr rpcgen 1
 to build event handling and marshaling code.
-The
-.Nm
-library comes in two variations:
 .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 .
-.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 .
-.Sh CAPABILITY API
-.Fn lc_limitfd
-is a wrapper around
-.Xr cap_new 2
-and
-.Xr dup2 2
-which takes an existing file descriptor and replaces it with a capability
-with the requested rights mask.
+This man page describes these I/O facilities; information on setting up
+and managing sandboxes may be found in
+.Xr libcapability 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
 .Fn lch_recv
 and
 .Fn lch_send
@@ -213,21 +111,6 @@
 returned by reference using
 .Va replenp .
 .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
 .Fn lcs_recv
 and
 .Fn lcs_send
@@ -268,13 +151,11 @@
 .Xr free 3 .
 .Sh SEE ALSO
 .Xr rpcgen 1 ,
-.Xr cap_enter 2 ,
-.Xr cap_new 2 ,
-.Xr dup2 2 ,
 .Xr recv 2 ,
 .Xr send 2 ,
 .Xr writev 2 ,
 .Xr free 3 ,
+.Xr libcapability 3 ,
 .Xr malloc 3 ,
 .Xr unix 4
 .Sh HISTORY
