contrib/capsicum-test/README.md

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