xref: /freebsd/contrib/capsicum-test/README.md (revision b856b51d149811d68ab9e72daa609f00e13c2ec3)
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