18ac5aef8SEnji Cooper# Capsicum User Space Tests 28ac5aef8SEnji Cooper 38ac5aef8SEnji CooperThis directory holds unit tests for [Capsicum](http://www.cl.cam.ac.uk/research/security/capsicum/) 48ac5aef8SEnji Cooperobject-capabilities. The tests exercise the syscall interface to a Capsicum-enabled operating system, 58ac5aef8SEnji Coopercurrently either [FreeBSD >=10.x](http://www.freebsd.org) or a modified Linux kernel (the 68ac5aef8SEnji Cooper[capsicum-linux](http://github.com/google/capsicum-linux) project). 78ac5aef8SEnji Cooper 8*b856b51dSMark JohnstonThe tests are written in C++11 and use the [Google Test](https://code.google.com/p/googletest/) 98ac5aef8SEnji Cooperframework, with some additions to fork off particular tests (because a process that enters capability 108ac5aef8SEnji Coopermode cannot leave it again). 118ac5aef8SEnji Cooper 128ac5aef8SEnji Cooper## Provenance 138ac5aef8SEnji Cooper 148ac5aef8SEnji CooperThe original basis for these tests was: 158ac5aef8SEnji Cooper 168ac5aef8SEnji Cooper - [unit tests](https://github.com/freebsd/freebsd/tree/master/tools/regression/security/cap_test) 178ac5aef8SEnji Cooper written by Robert Watson and Jonathan Anderson for the original FreeBSD 9.x Capsicum implementation 188ac5aef8SEnji Cooper - [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. 198ac5aef8SEnji Cooper 208ac5aef8SEnji CooperThese tests were coalesced and moved into an independent repository to enable 218ac5aef8SEnji Coopercomparative testing across multiple OSes, and then substantially extended. 228ac5aef8SEnji Cooper 238ac5aef8SEnji Cooper## OS Configuration 248ac5aef8SEnji Cooper 258ac5aef8SEnji Cooper### Linux 268ac5aef8SEnji Cooper 278ac5aef8SEnji CooperThe following kernel configuration options are needed to run the tests: 288ac5aef8SEnji Cooper 298ac5aef8SEnji Cooper - `CONFIG_SECURITY_CAPSICUM`: enable the Capsicum framework 308ac5aef8SEnji Cooper - `CONFIG_PROCDESC`: enable Capsicum process-descriptor functionality 318ac5aef8SEnji Cooper - `CONFIG_DEBUG_FS`: enable debug filesystem 328ac5aef8SEnji Cooper - `CONFIG_IP_SCTP`: enable SCTP support 338ac5aef8SEnji Cooper 348ac5aef8SEnji Cooper### FreeBSD (>= 10.x) 358ac5aef8SEnji Cooper 368ac5aef8SEnji CooperThe following kernel configuration options are needed so that all tests can run: 378ac5aef8SEnji Cooper 388ac5aef8SEnji Cooper - `options P1003_1B_MQUEUE`: Enable POSIX message queues (or `kldload mqueuefs`) 398ac5aef8SEnji Cooper 408ac5aef8SEnji Cooper## Other Dependencies 418ac5aef8SEnji Cooper 428ac5aef8SEnji Cooper### Linux 438ac5aef8SEnji Cooper 448ac5aef8SEnji CooperThe following additional development packages are needed to build the full test suite on Linux. 458ac5aef8SEnji Cooper 468ac5aef8SEnji Cooper - `libcaprights`: See below 478ac5aef8SEnji Cooper - `libcap-dev`: Provides headers for POSIX.1e capabilities. 488ac5aef8SEnji Cooper - `libsctp1`: Provides SCTP library functions. 498ac5aef8SEnji Cooper - `libsctp-dev`: Provides headers for SCTP library functions. 508ac5aef8SEnji Cooper 518ac5aef8SEnji Cooper 528ac5aef8SEnji Cooper## Linux libcaprights 538ac5aef8SEnji Cooper 548ac5aef8SEnji CooperThe Capsicum userspace library is held in the `libcaprights/` subdirectory. Ideally, this 558ac5aef8SEnji Cooperlibrary should be built (with `./configure; make` or `dpkg-buildpackage -uc -us`) and 568ac5aef8SEnji Cooperinstalled (with `make install` or `dpkg -i libcaprights*.deb`) so that the tests will 578ac5aef8SEnji Cooperuse behave like a normal Capsicum-aware application. 588ac5aef8SEnji Cooper 598ac5aef8SEnji CooperHowever, if no installed copy of the library is found, the `GNUmakefile` will attempt 608ac5aef8SEnji Cooperto use the local `libcaprights/*.c` source; this requires `./configure` to have been 618ac5aef8SEnji Cooperperformed in the `libcaprights` subdirectory. The local code is also used for 628ac5aef8SEnji Coopercross-compiled builds of the test suite (e.g. `make ARCH=32` or `make ARCH=x32`). 63