PERFORCE change 163962 for review

[Robert Watson]

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

Change 163962 by rwatson at 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_ */