capset(2)

Synopsis

#include <linux/capability.h> /* Definition of CAP_* and
                                 _LINUX_CAPABILITY_* constants */
#include <sys/syscall.h>      /* Definition of SYS_* constants */
#include <unistd.h>

int syscall(SYS_capget, cap_user_header_t hdrp,
            cap_user_data_t datap);
int syscall(SYS_capset, cap_user_header_t hdrp,
            const cap_user_data_t datap);

Rod's take

Five per-thread capability sets, and the execve transformation between them is where everybody's mental model falls apart. Permitted is the ceiling, effective is what the kernel actually checks, inheritable and ambient decide what survives exec, and bounding caps what file capabilities can hand out. Don't drive capset(2) by hand; the header versioning has bitten people and libcap's cap_set_proc exists for a reason. Drop what you don't need, clear ambient, lock the securebits so root can't quietly get everything back on the next setuid exec. Kerrisk spends a whole chapter on this. Read it.

Flags and arguments that matter

Errors you will actually hit

Example

/* still root here: lock securebits, switch UID, then drop the rest */
if (prctl(PR_SET_SECUREBITS,
          SECBIT_NOROOT | SECBIT_NOROOT_LOCKED, 0, 0, 0) < 0)
    err(1, "PR_SET_SECUREBITS");
if (setgroups(0, NULL) < 0 ||
    setresgid(gid, gid, gid) < 0 ||
    setresuid(uid, uid, uid) < 0)
    err(1, "drop uid/gid");

cap_t empty = cap_init();          /* libcap; calls capset(2) */
if (cap_set_proc(empty) < 0)
    err(1, "cap_set_proc");
cap_free(empty);
prctl(PR_CAP_AMBIENT, PR_CAP_AMBIENT_CLEAR_ALL, 0, 0, 0);

Trimmed from the full walkthrough in Linux capabilities: what the five sets actually do.

BSD equivalent

FreeBSD: no POSIX.1e-style process capability sets; Capsicum (cap_enter(2), cap_rights_limit(2)) restricts per-fd rights instead. OpenBSD: none; pledge(2).