svn commit: r203243 - in projects/capabilities8: lib lib/libc/sys
lib/libcapability lib/libcapsicum usr.bin/gzip
Robert Watson
rwatson at FreeBSD.org
Sat Jan 30 20:28:39 UTC 2010
Author: rwatson
Date: Sat Jan 30 20:28:39 2010
New Revision: 203243
URL: http://svn.freebsd.org/changeset/base/203243
Log:
Merge c173835 from the p4 TrustedBSD Capabilities branch to capabilities8:
libcapability => libcapsicum
Submitted by: Jonathan Anderson <jonathan.anderson at cl.cam.ac.uk>
Added:
projects/capabilities8/lib/libcapsicum/
projects/capabilities8/lib/libcapsicum/libcapsicum.3
projects/capabilities8/lib/libcapsicum/libcapsicum.c
projects/capabilities8/lib/libcapsicum/libcapsicum.h
projects/capabilities8/lib/libcapsicum/libcapsicum_host.3
projects/capabilities8/lib/libcapsicum/libcapsicum_host.c
projects/capabilities8/lib/libcapsicum/libcapsicum_host_io.c
projects/capabilities8/lib/libcapsicum/libcapsicum_internal.h
projects/capabilities8/lib/libcapsicum/libcapsicum_sandbox.3
projects/capabilities8/lib/libcapsicum/libcapsicum_sandbox.c
projects/capabilities8/lib/libcapsicum/libcapsicum_sandbox_api.h
projects/capabilities8/lib/libcapsicum/libcapsicum_sandbox_io.c
projects/capabilities8/lib/libcapsicum/libscapsicum_sandbox.c
Deleted:
projects/capabilities8/lib/libcapability/
Modified:
projects/capabilities8/lib/Makefile
projects/capabilities8/lib/libc/sys/cap_enter.2
projects/capabilities8/lib/libc/sys/cap_new.2
projects/capabilities8/usr.bin/gzip/Makefile
projects/capabilities8/usr.bin/gzip/gzsandbox.c
Modified: projects/capabilities8/lib/Makefile
==============================================================================
--- projects/capabilities8/lib/Makefile Sat Jan 30 20:06:52 2010 (r203242)
+++ projects/capabilities8/lib/Makefile Sat Jan 30 20:28:39 2010 (r203243)
@@ -32,7 +32,7 @@ SUBDIR= ${_csu} libc libbsm libauditd li
ncurses ${_libnetgraph} libradius librpcsvc libsbuf \
libtacplus libutil ${_libypclnt} libalias libarchive ${_libatm} \
libbegemot ${_libbluetooth} ${_libbsnmp} libbz2 \
- libcalendar libcam libcapability libcompat \
+ libcalendar libcam libcapsicum libcompat \
libdevinfo libdevstat \
libdisk \
libdwarf libedit libexpat libfetch libftpio libgeom ${_libgpib} \
Modified: projects/capabilities8/lib/libc/sys/cap_enter.2
==============================================================================
--- projects/capabilities8/lib/libc/sys/cap_enter.2 Sat Jan 30 20:06:52 2010 (r203242)
+++ projects/capabilities8/lib/libc/sys/cap_enter.2 Sat Jan 30 20:28:39 2010 (r203243)
@@ -68,7 +68,7 @@ When combined with capabilities created
may be used to create kernel-enforced sandboxes in which
appropriately-crafted applications or application components may be run.
Most sandboxes will be created and managed using the
-.Xr libcapability
+.Xr libcapsicum
library, rather than using system calls directly.
.Pp
.Fn cap_getmode
@@ -97,7 +97,7 @@ acquired rights as possible.
.Sh SEE ALSO
.Xr cap_new 2 ,
.Xr fexecve 2 ,
-.Xr libcapability 3
+.Xr libcapsicum 3
.Sh HISTORY
Support for capabilities and capabilities mode was developed as part of the
.Tn TrustedBSD
Modified: projects/capabilities8/lib/libc/sys/cap_new.2
==============================================================================
--- projects/capabilities8/lib/libc/sys/cap_new.2 Sat Jan 30 20:06:52 2010 (r203242)
+++ projects/capabilities8/lib/libc/sys/cap_new.2 Sat Jan 30 20:28:39 2010 (r203243)
@@ -88,7 +88,7 @@ descriptor, including open file flags, b
Many applications will prefer to use the
.Xr cap_limitfd 3
library call, part of
-.Xr libcapability 3 ,
+.Xr libcapsicum 3 ,
as it offers a more convenient interface.
.Pp
.Fn cap_getrights
@@ -455,7 +455,7 @@ argument is not a capability.
.Xr unlinkat 2 ,
.Xr write 2 ,
.Xr cap_limitfd 3 ,
-.Xr libcapability 3 ,
+.Xr libcapsicum 3 ,
.Xr sem_getvalue 3 ,
.Xr sem_post 3 ,
.Xr sem_trywait 3 ,
Added: projects/capabilities8/lib/libcapsicum/libcapsicum.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ projects/capabilities8/lib/libcapsicum/libcapsicum.3 Sat Jan 30 20:28:39 2010 (r203243)
@@ -0,0 +1,116 @@
+.\"
+.\" Copyright (c) 2009 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" This software was developed at the University of Cambridge Computer
+.\" Laboratory with support from a grant from Google, Inc.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 11, 2009
+.Os
+.Dt LIBCAPABILITY 3
+.Sh NAME
+.Nm libcapsicum
+.Nd "library interface to capability-mode services"
+.Sh LIBRARY
+.Lb libcapsicum
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/capability.h
+.In libcapsicum.h
+.Ft int
+.Fn lc_limitfd "int fd" "cap_rights_t rights"
+.Sh DESCRIPTION
+.Nm
+implements APIs that allow applications to create, manage, and interact with
+sandboxed software services running in capability mode, described in
+.Xr cap_enter 2 .
+Applications linked against
+.Nm
+will use one or both of "host" and "sandbox" APIs, depending on whether they
+consume or produce sandboxed services.
+.Nm
+will start sandboxed components using a sandbox-specific run-time linker,
+.Xr rtld-elf-cap 1 ,
+rather than the standard
+.Xr rtld-elf 1 .
+.Pp
+Host processes use the
+.Nm
+host API,
+described in
+.Xr libcapsicum_host 3 ,
+to launch compartmentalized components in sandboxes.
+They may also use
+.Nm
+to communication with the sandboxed service based on socket I/O or remote
+procedure call (RPC).
+.Pp
+Sandbox processes run in capability mode, and are only able to use resources
+either assigned to the sandbox during creation, or later explicitly passed to
+the process.
+Sandbox processes use the
+.Nm
+sandbox API,
+described in
+.Xr libcapsicum_sandbox 3 .
+Sandboxed processes themselves may launch software components in further
+sandboxes, so a single program may use both host and sandbox APIs.
+.Sh CAPABILITY API
+.Fn lc_limitfd
+is a wrapper around
+.Xr cap_new 2 ,
+.Xr dup2 2 ,
+and
+.Xr close 2 .
+which takes an existing file descriptor and replaces it with a capability
+with the requested rights mask.
+.Sh SEE ALSO
+.Xr rpcgen 1 ,
+.Xr rtld-elf 1 ,
+.Xr rtld-elf-cap 1 ,
+.Xr cap_enter 2 ,
+.Xr cap_new 2 ,
+.Xr close 2 ,
+.Xr dup2 2 ,
+.Xr libcapsicum_host 3 ,
+.Xr libcapsicum_sandbox 3 ,
+.Xr unix 4
+.Sh HISTORY
+Support for capabilities and capabilities mode was developed as part of the
+.Tn TrustedBSD
+Project.
+.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.
+.Sh AUTHORS
+These functions and the capability facility were created by
+.An "Robert N. M. Watson"
+at the University of Cambridge Computer Laboratory with support from a grant
+from Google, Inc.
Added: projects/capabilities8/lib/libcapsicum/libcapsicum.c
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ projects/capabilities8/lib/libcapsicum/libcapsicum.c Sat Jan 30 20:28:39 2010 (r203243)
@@ -0,0 +1,268 @@
+/*-
+ * Copyright (c) 2009 Robert N. M. Watson
+ * All rights reserved.
+ *
+ * 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.
+ *
+ * This software was developed at the University of Cambridge Computer
+ * Laboratory with support from a grant from Google, Inc.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $P4: //depot/projects/trustedbsd/capabilities/src/lib/libcapsicum/libcapsicum.c#1 $
+ */
+
+#include <sys/types.h>
+#include <sys/capability.h>
+#include <sys/socket.h>
+
+#include <errno.h>
+#include <string.h>
+#include <unistd.h>
+
+#include "libcapsicum.h"
+#include "libcapsicum_internal.h"
+#include "libcapsicum_sandbox_api.h"
+
+int
+lc_limitfd(int fd, cap_rights_t rights)
+{
+ int fd_cap;
+ int error;
+
+ fd_cap = cap_new(fd, rights);
+ if (fd_cap < 0)
+ return (-1);
+ if (dup2(fd_cap, fd) < 0) {
+ error = errno;
+ close(fd_cap);
+ errno = error;
+ return (-1);
+ }
+ close(fd_cap);
+ return (0);
+}
+
+void
+_lc_dispose_rights(int *fdp, int fdcount)
+{
+ int i;
+
+ for (i = 0; i < fdcount; i++)
+ close(fdp[i]);
+}
+
+/*
+ * Given a 'struct msghdr' returned by a successful call to recvmsg(),
+ * extract up to the desired number of file descriptors (or clean up the
+ * mess if something goes wrong).
+ */
+int
+_lc_receive_rights(struct msghdr *msg, int *fdp, int *fdcountp)
+{
+ int *cmsg_fdp, fdcount, i, scmrightscount;
+ struct cmsghdr *cmsg;
+
+ /*
+ * Walk the complete control message chain to count received control
+ * messages and rights. If there is more than one rights message or
+ * there are too many file descriptors, re-walk and close them all
+ * and return an error.
+ */
+ fdcount = 0;
+ scmrightscount = 0;
+ for (cmsg = CMSG_FIRSTHDR(msg); cmsg != NULL;
+ cmsg = CMSG_NXTHDR(msg, cmsg)) {
+ if (cmsg->cmsg_level != SOL_SOCKET ||
+ cmsg->cmsg_type != SCM_RIGHTS)
+ continue;
+ fdcount += (cmsg->cmsg_len - CMSG_LEN(0)) / sizeof(int);
+ scmrightscount++;
+ }
+ if (scmrightscount > 1 || fdcount > *fdcountp) {
+ for (cmsg = CMSG_FIRSTHDR(msg); cmsg != NULL;
+ cmsg = CMSG_NXTHDR(msg, cmsg)) {
+ if (cmsg->cmsg_level != SOL_SOCKET ||
+ cmsg->cmsg_type != SCM_RIGHTS)
+ continue;
+ cmsg_fdp = (int *)CMSG_DATA(cmsg);
+ fdcount = (cmsg->cmsg_len - CMSG_LEN(0)) /
+ sizeof(int);
+ _lc_dispose_rights(cmsg_fdp, fdcount);
+ }
+ errno = EBADMSG;
+ return (-1);
+ }
+
+ /*
+ * Re-walk the control messages and copy out the file descriptor
+ * numbers, return success. No need to recalculate fdcount.
+ */
+ for (cmsg = CMSG_FIRSTHDR(msg); cmsg != NULL;
+ cmsg = CMSG_NXTHDR(msg, cmsg)) {
+ if (cmsg->cmsg_level != SOL_SOCKET ||
+ cmsg->cmsg_type != SCM_RIGHTS)
+ continue;
+ cmsg_fdp = (int *)CMSG_DATA(cmsg);
+ for (i = 0; i < fdcount; i++)
+ fdp[i] = cmsg_fdp[i];
+ }
+ *fdcountp = fdcount;
+ return (0);
+}
+
+ssize_t
+_lc_send(int fd, const void *msg, size_t len, int flags, int lc_flags)
+{
+ ssize_t retlen;
+
+ if (fd == -1 || fd == 0) {
+ errno = ECHILD;
+ return (-1);
+ }
+ if (lc_flags & LC_IGNOREEINTR) {
+ do {
+ retlen = send(fd, msg, len, flags);
+ } while (retlen < 0 && errno == EINTR);
+ } else
+ retlen = send(fd, msg, len, flags);
+ return (retlen);
+}
+
+ssize_t
+_lc_send_rights(int fd, const void *msg, size_t len, int flags, int lc_flags,
+ int *fdp, int fdcount)
+{
+ char cmsgbuf[CMSG_SPACE(LIBCAPABILITY_SANDBOX_API_MAXRIGHTS *
+ sizeof(int))];
+ struct cmsghdr *cmsg;
+ struct msghdr msghdr;
+ struct iovec iov;
+ ssize_t retlen;
+ int i;
+
+ if (fdcount == 0)
+ return (_lc_send(fd, msg, len, flags, lc_flags));
+
+ if (fd == -1 || fd == 0) {
+ errno = ECHILD;
+ return (-1);
+ }
+
+ if (fdcount > LIBCAPABILITY_SANDBOX_API_MAXRIGHTS) {
+ errno = EMSGSIZE;
+ return (-1);
+ }
+
+ bzero(&iov, sizeof(iov));
+ iov.iov_base = __DECONST(void *, msg);
+ iov.iov_len = len;
+
+ bzero(&cmsgbuf, sizeof(cmsgbuf));
+ cmsg = (struct cmsghdr *)cmsgbuf;
+ cmsg->cmsg_len = CMSG_SPACE(fdcount * sizeof(int));
+ cmsg->cmsg_level = SOL_SOCKET;
+ cmsg->cmsg_type = SCM_RIGHTS;
+ for (i = 0; i < fdcount; i++)
+ ((int *)CMSG_DATA(cmsg))[i] = fdp[i];
+
+ bzero(&msghdr, sizeof(msghdr));
+ msghdr.msg_iov = &iov;
+ msghdr.msg_iovlen = 1;
+ msghdr.msg_control = cmsg;
+ msghdr.msg_controllen = cmsg->cmsg_len;
+
+ if (lc_flags & LC_IGNOREEINTR) {
+ do {
+ retlen = sendmsg(fd, &msghdr, flags);
+ } while (retlen < 0 && errno == EINTR);
+ } else
+ retlen = sendmsg(fd, &msghdr, flags);
+ return (retlen);
+}
+
+ssize_t
+_lc_recv(int fd, void *buf, size_t len, int flags, int lc_flags)
+{
+ ssize_t retlen;
+
+ if (fd == -1 || fd == 0) {
+ errno = ESRCH;
+ return (-1);
+ }
+ if (lc_flags & LC_IGNOREEINTR) {
+ do {
+ retlen = recv(fd, buf, len, flags);
+ } while (retlen < 0 && errno == EINTR);
+ return (retlen);
+ } else
+ return (recv(fd, buf, len, flags));
+}
+
+ssize_t
+_lc_recv_rights(int fd, void *buf, size_t len, int flags, int lc_flags,
+ int *fdp, int *fdcountp)
+{
+ char cmsgbuf[CMSG_SPACE(LIBCAPABILITY_SANDBOX_API_MAXRIGHTS *
+ sizeof(int))];
+ struct msghdr msghdr;
+ struct iovec iov;
+ ssize_t retlen;
+
+ if (*fdcountp == 0)
+ return (_lc_recv(fd, buf, len, flags, lc_flags));
+
+ if (fd == -1 || fd == 0) {
+ errno = ECHILD;
+ return (-1);
+ }
+
+ if (*fdcountp > LIBCAPABILITY_SANDBOX_API_MAXRIGHTS) {
+ errno = EMSGSIZE;
+ return (-1);
+ }
+
+ bzero(&iov, sizeof(iov));
+ iov.iov_base = buf;
+ iov.iov_len = len;
+
+ bzero(cmsgbuf, sizeof(cmsgbuf));
+ bzero(&msghdr, sizeof(msghdr));
+ msghdr.msg_iov = &iov;
+ msghdr.msg_iovlen = 1;
+ msghdr.msg_control = cmsgbuf;
+ msghdr.msg_controllen = sizeof(cmsgbuf);
+
+ if (lc_flags & LC_IGNOREEINTR) {
+ do {
+ retlen = recvmsg(fd, &msghdr, flags);
+ } while (retlen < 0 && errno == EINTR);
+ } else
+ retlen = recvmsg(fd, &msghdr, flags);
+ if (retlen < 0)
+ return (-1);
+ if (_lc_receive_rights(&msghdr, fdp, fdcountp) < 0)
+ return (-1);
+ return (retlen);
+}
Added: projects/capabilities8/lib/libcapsicum/libcapsicum.h
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ projects/capabilities8/lib/libcapsicum/libcapsicum.h Sat Jan 30 20:28:39 2010 (r203243)
@@ -0,0 +1,212 @@
+/*-
+ * Copyright (c) 2009 Robert N. M. Watson
+ * All rights reserved.
+ *
+ * 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.
+ *
+ * This software was developed at the University of Cambridge Computer
+ * Laboratory with support from a grant from Google, Inc.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $P4: //depot/projects/trustedbsd/capabilities/src/lib/libcapsicum/libcapsicum.h#1 $
+ */
+
+#ifndef _LIBCAPABILITY_H_
+#define _LIBCAPABILITY_H_
+
+#include <sys/cdefs.h>
+#include <sys/capability.h>
+
+__BEGIN_DECLS
+
+struct lc_sandbox;
+struct lc_host;
+
+/*
+ * Description of a library passed to lch_start_libs().
+ */
+struct lc_library {
+ const char *lcl_libpath;
+ const char *lcl_libname;
+ int lcl_fd;
+};
+
+
+/* A list of file descriptors, which can be passed around in shared memory */
+struct lc_fdlist;
+
+
+struct lc_fdlist* lc_fdlist_new(void);
+struct lc_fdlist* lc_fdlist_dup(struct lc_fdlist *orig);
+void lc_fdlist_free(struct lc_fdlist *l);
+
+/* Size of an FD list in bytes, including all associated string data */
+int lc_fdlist_size(struct lc_fdlist *l);
+
+
+/*
+ * Add a file descriptor to the list.
+ *
+ * l the list to add to
+ * subsystem a software component name, e.g. "org.freebsd.rtld-elf"
+ * classname a class name, e.g. "libdir" or "library"
+ * name an instance name, e.g. "system library dir" or "libc.so.6"
+ * fd the file descriptor
+ */
+int lc_fdlist_add(struct lc_fdlist **l,
+ const char *subsystem, const char *classname,
+ const char *name, int fd);
+
+/*
+ * Like lc_fdlist_add(), but allows capability rights to be specified. The file
+ * descriptor will be wrapped in a capability with the given rights (so if the
+ * descriptor *is* a capability, its rights will be constrained according to this
+ * rights mask)
+ */
+int lc_fdlist_addcap(struct lc_fdlist **l,
+ const char *subsystem, const char *classname,
+ const char *name, int fd, cap_rights_t rights);
+
+/*
+ * Look up a file descriptor.
+ *
+ * Multiple entries with the same classname are allowed, so iterating through
+ * all instances of a class is done by supplying an integer 'pos' which is used
+ * internally to skip entries which have already been seen. If 'pos' is 0 or NULL,
+ * the first matching entry will be returned.
+ */
+int lc_fdlist_lookup(struct lc_fdlist *l,
+ const char *subsystem, const char *classname,
+ char **name, int *fdp, int *pos);
+
+/*
+ * Capability interfaces.
+ */
+int lc_limitfd(int fd, cap_rights_t rights);
+
+/*
+ * Global policy interface to ask whether we should, in fact, sandbox a
+ * particular optionally sandboxed service, by name.
+ */
+int lch_autosandbox_isenabled(const char *servicename);
+
+/*
+ * Interfaces to start and stop capability mode sandboxs.
+ */
+int lch_start(const char *sandbox, char *const argv[], u_int flags,
+ struct lc_sandbox **lcspp);
+int lch_start_libs(const char *sandbox, char *const argv[], u_int flags,
+ struct lc_library *lclp, u_int lcl_count,
+ struct lc_sandbox **lcspp);
+int lch_startfd(int fd_sandbox, const char *binname, char *const argv[],
+ u_int flags, struct lc_sandbox **lcspp);
+int lch_startfd_libs(int fd_sandbox, const char *binname,
+ char *const argv[], u_int flags, struct lc_library *lclp,
+ u_int lcl_count, struct lc_sandbox **lcspp);
+void lch_stop(struct lc_sandbox *lcsp);
+
+/*
+ * Flags to lch_start_flags:
+ */
+#define LCH_PERMIT_STDERR 0x00000001
+#define LCH_PERMIT_STDOUT 0x00000002
+
+/*
+ * Interfaces to query state about capability mode sandboxs.
+ */
+int lch_getsock(struct lc_sandbox *lcsp, int *fdp);
+int lch_getpid(struct lc_sandbox *lcsp, pid_t *pidp);
+int lch_getprocdesc(struct lc_sandbox *lcsp, int *fdp);
+
+/*
+ * Message-passing APIs for the host environment.
+ */
+struct iovec;
+ssize_t lch_recv(struct lc_sandbox *lcsp, void *buf, size_t len, int flags);
+ssize_t lch_recv_rights(struct lc_sandbox *lcsp, void *buf, size_t len,
+ int flags, int *fdp, int *fdcountp);
+ssize_t lch_send(struct lc_sandbox *lcsp, const void *msg, size_t len,
+ int flags);
+ssize_t lch_send_rights(struct lc_sandbox *lcsp, const void *msg, size_t len,
+ int flags, int *fdp, int fdcount);
+
+/*
+ * RPC APIs for the host environment.
+ */
+int lch_rpc(struct lc_sandbox *lcsp, u_int32_t opno, struct iovec *req,
+ int reqcount, struct iovec *rep, int repcount, size_t *replenp);
+int lch_rpc_rights(struct lc_sandbox *lcsp, u_int32_t opno,
+ struct iovec *req, int reqcount, int *req_fdp, int req_fdcount,
+ struct iovec *rep, int repcount, size_t *replenp, int *rep_fdp,
+ int *rep_fdcountp);
+
+/*
+ * Interfaces to query state from within capability mode sandboxes.
+ */
+int lcs_get(struct lc_host **lchpp);
+int lcs_getsock(struct lc_host *lchp, int *fdp);
+
+/*
+ * Message-passing APIs for the sandbox environment.
+ */
+ssize_t lcs_recv(struct lc_host *lchp, void *buf, size_t len, int flags);
+ssize_t lcs_recv_rights(struct lc_host *lchp, void *buf, size_t len,
+ int flags, int *fdp, int *fdcountp);
+ssize_t lcs_send(struct lc_host *lchp, const void *msg, size_t len,
+ int flags);
+ssize_t lcs_send_rights(struct lc_host *lchp, const void *msg, size_t len,
+ int flags, int *fdp, int fdcount);
+
+/*
+ * RPC APIs for the sandbox environment.
+ */
+int lcs_recvrpc(struct lc_host *lchp, u_int32_t *opnop,
+ u_int32_t *seqnop, u_char **bufferp, size_t *lenp);
+int lcs_recvrpc_rights(struct lc_host *lchp, u_int32_t *opnop,
+ u_int32_t *seqnop, u_char **bufferp, size_t *lenp, int *fdp,
+ int *fdcountp);
+int lcs_sendrpc(struct lc_host *lchp, u_int32_t opno, u_int32_t seqno,
+ struct iovec *rep, int repcount);
+int lcs_sendrpc_rights(struct lc_host *lchp, u_int32_t opno,
+ u_int32_t seqno, struct iovec *rep, int repcount, int *fdp,
+ int fdcount);
+
+/*
+ * Actually an rtld-elf-cap symbol, but declared here so it is available to
+ * applications.
+ */
+int ld_libcache_lookup(const char *libname, int *fdp);
+int ld_insandbox(void);
+
+/*
+ * Applications may declare an alternative entry point to the default ELF
+ * entry point for their binary, which will be used in preference to 'main'
+ * in the sandbox environment.
+ */
+int cap_main(int argc, char *argv[]);
+
+__END_DECLS
+
+#endif /* !_LIBCAPABILITY_H_ */
Added: projects/capabilities8/lib/libcapsicum/libcapsicum_host.3
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ projects/capabilities8/lib/libcapsicum/libcapsicum_host.3 Sat Jan 30 20:28:39 2010 (r203243)
@@ -0,0 +1,236 @@
+.\"
+.\" Copyright (c) 2009 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" This software was developed at the University of Cambridge Computer
+.\" Laboratory with support from a grant from Google, Inc.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 11, 2009
+.Os
+.Dt LIBCAPABILITY_HOST 3
+.Sh NAME
+.Nm libcapsicum
+.Nd "library interface to capability-mode services"
+.Sh LIBRARY
+.Lb libcapsicum
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/capability.h
+.In libcapsicum.h
+.Ft int
+.Fn lch_start "const char *sandbox" "char *const argv[]" "u_int flags" "struct lc_sandbox **lcsp"
+.Ft int
+.Fn lch_startfd "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_autosandbox_isenabled "const char *servicename"
+.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 ssize_t
+.Fn lch_recv_rights "struct lc_sandbox *lcsp" "void *buf" "size_t len" "int flags" "int *fdp" "int *fdcountp"
+.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 int
+.Fn lch_rpc_rights "struct lc_sandbox *lcsp" "u_int32_t opno" "struct iovec *req" "int reqcount" "int *req_fdp" "int req_fdcount" "struct iovec *rep" "int repcount" "size_t *replenp" "int *rep_fdp" "int *rep_fdcountp"
+.Ft ssize_t
+.Fn lch_send "struct lc_sandbox *lcsp" "const void *msg" "size_t len" "int flags"
+.Ft ssize_t
+.Fn lch_send_rights "struct lc_sandbox *lcsp" "const void *msg" "size_t len" "int flags" "int *fdp" "int fdcount"
+.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.
+Applications may also use RPC generators such as
+.Xr rpcgen 1
+to build event handling and marshaling code.
+.Pp
+This man page describes the host API.
+General information on
+.Nm
+may be found in
+.Xr libcapsicum 3 .
+Information on the sandbox API may be found in
+.Xr libcapsicum_sandbox 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
+for successfully started sandboxes, and passed into other APIs to indicate
+which sandbox should be acted on.
+.Fn lch_start
+creates a new executing sandboxes, given the name of the sandbox binary via
+.Va sandbox ,
+and command line arguments
+.Va argv ,
+and optional flags
+.Va flags
+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
+.Fn lch_startfd
+accept a file descriptor argument,
+.Va fd_sandbox ,
+rather than a path, so is appropriate for use within a sandbox.
+.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
+Libraries and tools performing self-compartmentalization can use the
+interface
+.Nm lch_autosandbox_isenabled
+along with a unique string identifying their service to determine whether or
+not a global policy affecting the service requires sandboxing to be enabled
+or not.
+.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
+.Nm
+implements a number of I/O functions as part of the host API, which are
+documented in
+.Xr libcapsicum_host 3 .
+.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_recv_rights
+and
+.Fn lch_send_rights
+are similar, but allow file descriptors to be attached the the messages
+received and sent.
+Both accept a pointer to a file descriptor array,
+.Va fdp .
+Callers to
+.Fn lch_recv_rights
+will pass in the length of the array via
+.Va fdcountp ,
+whose value will be changed to the actual number of file descriptors
+received.
+Callers to
+.Fn lch_send_rights
+will pass in the number of file descriptors in the array via
+.Va fdcount .
+.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 the 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 lch_rpc_rights
+allows the sending and receiving of file descriptors as part of the RPC
+operation.
+.Sh SEE ALSO
+.Xr rpcgen 1 ,
+.Xr recv 2 ,
+.Xr send 2 ,
+.Xr writev 2 ,
+.Xr free 3 ,
+.Xr libcapsicum 3 ,
+.Xr libcapsicum_sandbox 3 ,
+.Xr malloc 3 ,
+.Xr unix 4
+.Sh HISTORY
+Support for capabilities and capabilities mode was developed as part of the
+.Tn TrustedBSD
+Project.
+.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
+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"
+at the University of Cambridge Computer Laboratory with support from a grant
+from Google, Inc.
Added: projects/capabilities8/lib/libcapsicum/libcapsicum_host.c
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ projects/capabilities8/lib/libcapsicum/libcapsicum_host.c Sat Jan 30 20:28:39 2010 (r203243)
@@ -0,0 +1,422 @@
+/*-
+ * Copyright (c) 2009 Robert N. M. Watson
+ * All rights reserved.
+ *
+ * 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.
+ *
+ * This software was developed at the University of Cambridge Computer
+ * Laboratory with support from a grant from Google, Inc.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $P4: //depot/projects/trustedbsd/capabilities/src/lib/libcapsicum/libcapsicum_host.c#1 $
+ */
+
+#include <sys/param.h>
+#include <sys/capability.h>
+#include <sys/procdesc.h>
+#include <sys/sbuf.h>
+#include <sys/socket.h>
+#include <sys/uio.h>
+
+#include <errno.h>
+#include <fcntl.h>
+#include <libgen.h>
+#include <paths.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#include "libcapsicum.h"
+#include "libcapsicum_internal.h"
+#include "libcapsicum_sandbox_api.h"
+
+#define LIBCAPABILITY_CAPMASK_DEVNULL (CAP_EVENT | CAP_READ | CAP_WRITE)
+#define LIBCAPABILITY_CAPMASK_SOCK (CAP_EVENT | CAP_READ | CAP_WRITE)
+#define LIBCAPABILITY_CAPMASK_BIN (CAP_READ | CAP_EVENT | CAP_FSTAT | \
+ CAP_FSTATFS | \
+ CAP_FEXECVE | CAP_MMAP | \
+ CAP_MAPEXEC)
+#define LIBCAPABILITY_CAPMASK_SANDBOX LIBCAPABILITY_CAPMASK_BIN
+#define LIBCAPABILITY_CAPMASK_LDSO LIBCAPABILITY_CAPMASK_BIN
+#define LIBCAPABILITY_CAPMASK_LIB LIBCAPABILITY_CAPMASK_BIN
+
+#define _PATH_LIB "/lib"
+#define _PATH_USR_LIB "/usr/lib"
+#define LIBC_SO "libc.so.7"
+#define LIBCAPABILITY_SO "libcapsicum.so.1"
+#define LIBSBUF_SO "libsbuf.so.5"
+
+extern char **environ;
+
+#define LD_ELF_CAP_SO "ld-elf-cap.so.1"
+#define PATH_LD_ELF_CAP_SO "/libexec"
+char *ldso_argv[] = {
+ __DECONST(char *, PATH_LD_ELF_CAP_SO "/" LD_ELF_CAP_SO),
+ NULL,
+};
+
+int
+lch_autosandbox_isenabled(__unused const char *servicename)
+{
+
+ if (getenv("LIBCAPABILITY_NOAUTOSANDBOX") != NULL)
+ return (0);
+ return (1);
+}
+
+/*
+ * Install an array of file descriptors using the array index of each
+ * descriptor in the array as its destination file descriptor number. All
+ * other existing file descriptors will be closed when this function returns,
+ * leaving a pristine vector. If calls fail, then we return (-1), but there
+ * are no guarantees about the state of the file descriptor array for the
+ * process, so it's a throw-away.
+ *
+ * It would be nice not to shuffle descriptors that already have the right
+ * number.
+ */
+static int
+lch_installfds(u_int fd_count, int *fds)
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-projects
mailing list