From owner-p4-projects@FreeBSD.ORG Thu Jun 11 11:28:29 2009 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 838AC10656C8; Thu, 11 Jun 2009 11:28:29 +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 3F16E10656C6 for ; Thu, 11 Jun 2009 11:28:29 +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 2A8BE8FC1E for ; Thu, 11 Jun 2009 11:28:29 +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 n5BBST1N043199 for ; Thu, 11 Jun 2009 11:28:29 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 n5BBSS9t043197 for perforce@freebsd.org; Thu, 11 Jun 2009 11:28:28 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Date: Thu, 11 Jun 2009 11:28:28 GMT Message-Id: <200906111128.n5BBSS9t043197@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 164092 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: Thu, 11 Jun 2009 11:28:30 -0000 http://perforce.freebsd.org/chv.cgi?CH=164092 Change 164092 by rwatson@rwatson_freebsd_capabilities on 2009/06/11 11:28:10 Document RPC functions, as well as their rather serious limitations. Affected files ... .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#12 edit Differences ... ==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#12 (text+ko) ==== @@ -60,6 +60,8 @@ .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 @@ -68,13 +70,22 @@ .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 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. .Sh HOST API The .Nm @@ -130,6 +141,31 @@ .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 . .Sh SANDBOX API The .Nm @@ -154,6 +190,36 @@ 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 +.Xr 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 . .Sh SEE ALSO .Xr cap_enter 2 , .Xr cap_new 2 @@ -164,6 +230,16 @@ .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"