1*670b568eSEd Maste# Capsicum User Space Tests 2*670b568eSEd Maste 3*670b568eSEd MasteThis directory holds unit tests for [Capsicum](http://www.cl.cam.ac.uk/research/security/capsicum/) 4*670b568eSEd Masteobject-capabilities. The tests exercise the syscall interface to a Capsicum-enabled operating system, 5*670b568eSEd Mastecurrently either [FreeBSD >=10.x](http://www.freebsd.org) or a modified Linux kernel (the 6*670b568eSEd Maste[capsicum-linux](http://github.com/google/capsicum-linux) project). 7*670b568eSEd Maste 8*670b568eSEd MasteThe tests are written in C++11 and use the [Google Test](https://code.google.com/p/googletest/) 9*670b568eSEd Masteframework, with some additions to fork off particular tests (because a process that enters capability 10*670b568eSEd Mastemode cannot leave it again). 11*670b568eSEd Maste 12*670b568eSEd Maste## Provenance 13*670b568eSEd Maste 14*670b568eSEd MasteThe original basis for these tests was: 15*670b568eSEd Maste 16*670b568eSEd Maste - [unit tests](https://github.com/freebsd/freebsd/tree/master/tools/regression/security/cap_test) 17*670b568eSEd Maste written by Robert Watson and Jonathan Anderson for the original FreeBSD 9.x Capsicum implementation 18*670b568eSEd Maste - [unit tests](http://git.chromium.org/gitweb/?p=chromiumos/third_party/kernel-capsicum.git;a=tree;f=tools/testing/capsicum_tests;hb=refs/heads/capsicum) written by Meredydd Luff for the original Capsicum-Linux port. 19*670b568eSEd Maste 20*670b568eSEd MasteThese tests were coalesced and moved into an independent repository to enable 21*670b568eSEd Mastecomparative testing across multiple OSes, and then substantially extended. 22*670b568eSEd Maste 23*670b568eSEd Maste## OS Configuration 24*670b568eSEd Maste 25*670b568eSEd Maste### Linux 26*670b568eSEd Maste 27*670b568eSEd MasteThe following kernel configuration options are needed to run the tests: 28*670b568eSEd Maste 29*670b568eSEd Maste - `CONFIG_SECURITY_CAPSICUM`: enable the Capsicum framework 30*670b568eSEd Maste - `CONFIG_PROCDESC`: enable Capsicum process-descriptor functionality 31*670b568eSEd Maste - `CONFIG_DEBUG_FS`: enable debug filesystem 32*670b568eSEd Maste - `CONFIG_IP_SCTP`: enable SCTP support 33*670b568eSEd Maste 34*670b568eSEd Maste### FreeBSD (>= 10.x) 35*670b568eSEd Maste 36*670b568eSEd MasteThe following kernel configuration options are needed so that all tests can run: 37*670b568eSEd Maste 38*670b568eSEd Maste - `options P1003_1B_MQUEUE`: Enable POSIX message queues (or `kldload mqueuefs`) 39*670b568eSEd Maste 40*670b568eSEd Maste## Other Dependencies 41*670b568eSEd Maste 42*670b568eSEd Maste### Linux 43*670b568eSEd Maste 44*670b568eSEd MasteThe following additional development packages are needed to build the full test suite on Linux. 45*670b568eSEd Maste 46*670b568eSEd Maste - `libcaprights`: See below 47*670b568eSEd Maste - `libcap-dev`: Provides headers for POSIX.1e capabilities. 48*670b568eSEd Maste - `libsctp1`: Provides SCTP library functions. 49*670b568eSEd Maste - `libsctp-dev`: Provides headers for SCTP library functions. 50*670b568eSEd Maste 51*670b568eSEd Maste 52*670b568eSEd Maste## Linux libcaprights 53*670b568eSEd Maste 54*670b568eSEd MasteThe Capsicum userspace library is held in the `libcaprights/` subdirectory. Ideally, this 55*670b568eSEd Mastelibrary should be built (with `./configure; make` or `dpkg-buildpackage -uc -us`) and 56*670b568eSEd Masteinstalled (with `make install` or `dpkg -i libcaprights*.deb`) so that the tests will 57*670b568eSEd Masteuse behave like a normal Capsicum-aware application. 58*670b568eSEd Maste 59*670b568eSEd MasteHowever, if no installed copy of the library is found, the `GNUmakefile` will attempt 60*670b568eSEd Masteto use the local `libcaprights/*.c` source; this requires `./configure` to have been 61*670b568eSEd Masteperformed in the `libcaprights` subdirectory. The local code is also used for 62*670b568eSEd Mastecross-compiled builds of the test suite (e.g. `make ARCH=32` or `make ARCH=x32`). 63