From owner-p4-projects@FreeBSD.ORG Wed Jun 10 10:18:07 2009 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 721471065675; Wed, 10 Jun 2009 10:18:07 +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 2D8F31065670 for ; Wed, 10 Jun 2009 10:18:07 +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 108048FC08 for ; Wed, 10 Jun 2009 10:18:07 +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 n5AAI6J4035780 for ; Wed, 10 Jun 2009 10:18:06 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 n5AAI60V035778 for perforce@freebsd.org; Wed, 10 Jun 2009 10:18:06 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Date: Wed, 10 Jun 2009 10:18:06 GMT Message-Id: <200906101018.n5AAI60V035778@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 163962 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: Wed, 10 Jun 2009 10:18:08 -0000 http://perforce.freebsd.org/chv.cgi?CH=163962 Change 163962 by rwatson@rwatson_freebsd_capabilities on 2009/06/10 10:17:27 Significantly revise the libcapability API so that it does something, namely, support the creation of "agent" capability mode processes from a "host". Currently, this API isn't appropriate for nested sandboxes, as it relies on access to the global file system namespace to create agents. The agent portion of the API is not yet implemented. Affected files ... .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/Makefile#2 edit .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/capability.c#3 delete .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcap_consumer.c#2 delete .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#2 edit .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.c#1 add .. //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.h#4 edit Differences ... ==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/Makefile#2 (text+ko) ==== @@ -3,7 +3,7 @@ LIB= capability SRCS= \ - capability.c + libcapability.c INCS= libcapability.h ==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.3#2 (text+ko) ==== @@ -43,12 +43,71 @@ .Sh SYNOPSIS .In sys/types.h .In sys/capability.h -.In libcap.h +.In libcapability.h +.Ft int +.Fn lc_limitfd "int fd" "cap_rights_t rights" +.Ft int +.Fn lch_agent_start "const char *agent" "struct lc_agent **lcap" +.Ft void +.Fn lch_agent_stop "struct lc_agent *lcap" +.Ft int +.Fn lch_agent_getsock "struct lc_agent *lcap" "int *fdp" +.Ft int +.Fn lch_agent_getpid "struct lc_agent *lcap" "pid_t *pidp" +.Ft int +.Fn lch_agent_getprocdesc "struct lc_agent *lcap" "int *fdp" +.Ft ssize_t +.Fn lch_agent_recv "struct lc_agent *lcap, void *buf" "size_t len" "int flags" +.Ft ssize_t +.Fn lch_agent_send "struct lc_agent *lcap" "const void *msg" "size_t len" "int flags" .Sh DESCRIPTION The .Nm library routines provide services for processes hosting or running in capability mode. +.Sh HOST API +The +.Nm +host API allows processes to start, stop, and manage agents running in +capability mode. +Host API functions can be identified by their function name prefix, +.Dv lch_ . +.Pp +Each executing agent instance is described by an opaque +.Dt "struct lc_agent" , +which is returned by +.Fn lch_agent_start +for successfully started agents, and passed into other APIs to indicate which +agent should be acted on. +.Fn lch_agent_start +creates a new executing agent, given the name of the agent binary via +.Va agent . +Executing agents may be stopped (and state freed) using +.Fn lch_agent_stop . +.Pp +Properties of the agent, such as the socket used to communicate with it, +the proces descriptor for the agent process, and the pid, may be queried +using +.Fn lch_agent_getsock , +.Fn lch_agent_getprocdesc , +and +.Fn lch_agent_getpid . +.Pp +.Fn lch_agent_recv +and +.Fn lch_agent_send +provide simple wrappers around +.Xr recv 2 +and +.Xr send 2 +to avoid agent consumers from having to query agent socket file descriptors +before use. +.Sh AGENT API +The +.Nm +agent API allows agent processes to interact with their host process. +Agent API functions can be identified by their function name prefix, +.Dv lca_ . .Sh SEE ALSO .Xr cap_enter 2 .Xr cap_new 2 ==== //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.h#4 (text+ko) ==== @@ -30,71 +30,38 @@ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * - * $P4: //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.h#3 $ + * $P4: //depot/projects/trustedbsd/capabilities/src/lib/libcapability/libcapability.h#4 $ */ #ifndef _LIBCAPABILITY_H_ #define _LIBCAPABILITY_H_ -/* - * libcapability operation types are negative; positive request types are - * reserved for application use. - */ -#define LIBCAP_REQ_SHUTDOWN -1 +struct lc_agent; -struct lc_consumer { - void *lc_private; /* Private data. */ -}; - -struct lc_producer { - void *lp_private; /* Private data. */ -}; - /* - * Version of the header seen on the wire. + * Capability interfaces. */ -struct lc_wire_message { - uint32_t lwm_magic; /* Magic number. */ - uint32_t lwm_hdrlen; /* Length of this header. */ - uint64_t lwm_opseqnum; /* Unique ID of request. */ - int64_t lwm_optype; /* Operation type to perform. */ - uint64_t lwm_flags; /* Flags. */ - uint64_t lwm_immlen; /* Immediates length. */ - uint64_t lwm_datalen; /* Data length. */ -}; +int lc_limitfd(int fd, cap_rights_t rights); /* - * Version of the header exposed to applications. + * Interfaces to start and stop capability mode agents. */ -struct lc_message { - uint64_t lm_opseqnum; /* Unique ID of request. */ - int64_t lm_optype; /* Operation type to perform. */ - uint64_t lm_flags; /* Flags. */ - uint64_t lm_immlen; /* Immediates length. */ - uint64_t lm_datalen; /* Data length. */ - u_char *lm_immp; /* Immediates pointer. */ - u_char *l_datap; /* Data pointer. */ -}; +int lch_agent_start(const char *agent, struct lc_agent **lcap); +void lch_agent_stop(struct lc_agent *lcap); /* - * Allow a libcapability "consumer" to initialize its consumer state. + * Interfaces to query state about capability mode agents. */ -void lc_consumer_destroy(struct lc_consumer *lccp); -struct lc_consumer *lc_consumer_new(const char *service_name, - const char *library_name); -int lc_consumer_start(struct lc_consumer *lccp); +int lch_agent_getsock(struct lc_agent *lcap, int *fdp); +int lch_agent_getpid(struct lc_agent *lcap, pid_t *pidp); +int lch_agent_getprocdesc(struct lc_agent *lcap, int *fdp); /* - * Allow a libcapability "producer" to initialize its producer state. A - * service name is passed, and will be validated. + * I/O interfaces for capability mode agents. */ -struct lc_producer *lc_producer_register(const char *service_name); -void lc_producer_destroy(struct lc_producer *lcpp); - -struct lc_message *lc_producer_recvmessage(struct lc_producer *lcpp); -struct lc_message *lc_producer_allocmessage(struct lc_producer *lcpp); -void lc_producer_freemessage(struct lc_producer *lcpp, - struct lc_message *lmp); -int lc_producer_sendmessage(struct lc_producer *lcpp); +ssize_t lch_agent_recv(struct lc_agent *lcap, void *buf, size_t len, + int flags); +ssize_t lch_agent_send(struct lc_agent *lcap, const void *msg, size_t len, + int flags); #endif /* !_LIBCAPABILITY_H_ */