From owner-p4-projects@FreeBSD.ORG Sun Jun 14 17:49:25 2009 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 432141065672; Sun, 14 Jun 2009 17:49:24 +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 EF634106564A for ; Sun, 14 Jun 2009 17:49:23 +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 DA1B18FC19 for ; Sun, 14 Jun 2009 17:49:23 +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 n5EHnNIH054229 for ; Sun, 14 Jun 2009 17:49:23 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 n5EHnNXH054227 for perforce@freebsd.org; Sun, 14 Jun 2009 17:49:23 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Date: Sun, 14 Jun 2009 17:49:23 GMT Message-Id: <200906141749.n5EHnNXH054227@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 164358 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: Sun, 14 Jun 2009 17:49:25 -0000 http://perforce.freebsd.org/chv.cgi?CH=164358 Change 164358 by rwatson@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