Computer Laboratory

Capsicum: practical capabilities for UNIX

logo Capsicum for FreeBSD

The FreeBSD implementation of Capsicum, developed by Robert Watson and Jonathan Anderson, ships out of the box in FreeBSD 10.0 (and as an optionally compiled feature in FreeBSD 9.0, 9.1, and 9.2). Capsicum for FreeBSD is the reference implementation, and serves not only as a reference for Capsicum APIs and semantics, but also provides starting-point source code for ports to other platforms (e.g., Capsicum for Linux and Capsicum for DragonFlyBSD).

Implementation status

Capsicum for FreeBSD was implemented by Robert Watson and Jonathan Anderson. Capsicum first appeared in FreeBSD 9.0 as an experimental feature, compiled out of the kernel by default. As of FreeBSD 10.0, Capsicum capability mode, capabilities, and process descriptors are compiled into the kernel by default, and available for use by both base-system and third-party applications.

Significant KPI and API changes were made in FreeBSD 10.0 following several years' experience deploying Capsicum in experimental applications and the FreeBSD base system. In FreeBSD 10.0, a number of base-system applications use Capsicum "out of the box" including tcpdump, auditdistd, hastd, dhclient, kdump, rwhod, ctld, iscsid, and even uniq.

Capsicum in FreeBSD applications

ApplicationDescriptionUse
dhclient(8) DHCP client
  • The unprivileged process can now only read from the routing socket.
  • It is no longer possible for the unprivileged process to send UDP packets to arbitrary destinations.
  • Unprivileged process can now only read from /dev/bpf and send SIOCGIFFLAGS and SIOCGIFMEDIA ioctls.
  • The unprivileged process can only overwrite lease file, it cannot read from it.
hastd(8) High-availability storage daemon The worker process is now sandboxed using capability mode. Access to local provider is limited to pread(2), pwrite(2), flock(2) and DIOCGDELETE and DIOCGFLUSH ioctls. Access to GEOM Gate device is limited to G_GATE_CMD_MODIFY, G_GATE_CMD_START, G_GATE_CMD_DONE and G_GATE_CMD_DESTROY ioctls (for primary node).
hastctl(8) HAST control utility It is now sandboxed using capability mode.
rwhod(8) RWho daemon The receiver functionality is now running is separate process, which is sandboxed using capability mode and has write-only access to one directory.
uniq(1) Uniq command-line tool It is now sandboxed using capability mode
kdump(1) kernel process tracing tool It is now sandboxed using capability mode. It is not sandboxed when -r option is used, which instructs kdump(1) to convert numeric UIDs and GIDs into user and group names. With the casperd daemon and system.pwd and system.grp services kdump(1) can be sandboxed even if -r option is used.
rwho(1) RWho client tool It is now sandboxed using capability mode and has read-only access to one directory
auditdist(8) Audit-trail distribution daemon Worker processes are sandboxed using capability mode. The receiver process has append-only access to one directory. It can create newer files and append data to them. It cannot modify already stored audit records. It cannot read or modify audit trail files from other hosts.
tcpdump(8) Packet capture tool It is now sandboxed using capability mode if -n option is used and -z and -V options are not used. With casperd's system.dns service support it enter sandbox even without -n option.

Casper daemon

Casper is a daemon that (a) provides services to sandboxed components that, themselves, do not have the rights necessary to implement those services, and (b) runs those services themselves in sandboxes. For example, capability-mode processes may not have the necessary privileges to perform network I/O, but can be delegated access to query the Casper DNS service to perform the DNS lookup on their behalf. DNS service may then, itself, be performed in a sandbox, isolating DNS processing from failures of applications, applications from failures in DNS, and the system as a whole from failures in either.

Casperd daemon is committed to FreeBSD 11-CURRENT and comes with the following services:

  • system.dns - provides API compatible to:
    • gethostbyname(3)
    • gethostbyname2(3)
    • gethostbyaddr(3)
    • getaddrinfo(3)
    • getnameinfo(3)
  • system.grp - provides getgrent(3)-compatible API
  • system.pwd - provides getpwent(3)-compatible API
  • system.random - allows to obtain entropy from /dev/random
  • system.sysctl - provides sysctlbyname(3)-compatible API

As the next step Pawel will be committing:

  • tcpdump(8) changes to use system.dns service, which will allow to use capability mode sandbox even if -n option was not given.
  • kdump(1) changes to use system.pwd and system.grp services, which will allow to use capability mode sandbox even if -r option is given.

Getting Capsicum for FreeBSD

Install FreeBSD 10.0 as will be released in late 2013/early 2014; in the interim, consider installing a FreeBSD 10.0 BETA release.

Alternatively, install FreeBSD 9.0, 9.1, or 9.2; however, be aware that you will need to compile a custom kernel, and that several Capsicum APIs have changed between FreeBSD 9.x and FreeBSD 10.x. New applications should be written against the FreeBSD 10.x API.