The kernel enforces strict rules about which capability modifications a process is allowed to make. A process cannot arbitrarily grant itself capabilities it doesn’t already have. The rules are:

A typical capability-aware program follows this workflow with libcap:

Additional useful functions:

This is the program from Listing 39-1 in the textbook — a complete, real-world capability-aware program. It demonstrates the proper pattern for capability-aware programming: start with capabilities in the permitted set (not effective), raise them only when needed, use them for the minimum necessary time, then drop all capabilities permanently.

The program authenticates a username and password against the system’s shadow password file. Reading /etc/shadow requires CAP_DAC_READ_SEARCH. Instead of running the entire program as root, we give it only that one capability in its file permitted set.

Setup (run once as root):

/*
 * check_password_caps.c  (Based on Listing 39-1 from TLPI)
 *
 * A capability-aware program that authenticates a user against
 * the shadow password database.
 *
 * Security design:
 *   - The binary has CAP_DAC_READ_SEARCH in its file PERMITTED set (not effective).
 *   - On startup, effective set is EMPTY (file effective bit is 0).
 *   - We raise CAP_DAC_READ_SEARCH to effective ONLY to read /etc/shadow.
 *   - After reading shadow file, we drop ALL capabilities permanently.
 *   - The rest of the program runs with zero capabilities.
 *
 * This is the "capability-aware program" pattern described in Section 39.3.4.
 * The file effective bit is 0 (=p means permitted only, not effective).
 *
 * Required file capability:
 *   sudo setcap "cap_dac_read_search=p" ./check_password_caps
 *
 * Compile:
 *   gcc -o check_password_caps check_password_caps.c -lcap -lcrypt
 */

#define _BSD_SOURCE   /* Get getpass() declaration from <unistd.h> */
#define _XOPEN_SOURCE /* Get crypt() declaration */

#include <sys/capability.h>
#include <unistd.h>
#include <limits.h>
#include <pwd.h>
#include <shadow.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

/*
 * modifyCap() - Internal helper: raise or drop one capability in the effective set.
 *
 * @capability: The capability to change (e.g., CAP_DAC_READ_SEARCH)
 * @setting:    CAP_SET to raise, CAP_CLEAR to drop
 *
 * Steps:
 *   1. cap_get_proc()   — get current capability sets
 *   2. cap_set_flag()   — modify the desired capability in the user-space structure
 *   3. cap_set_proc()   — push the modified structure back to the kernel
 *   4. cap_free()       — free the libcap-allocated structure
 *
 * Returns 0 on success, -1 on failure.
 */
static int modifyCap(int capability, int setting)
{
    cap_t caps;
    cap_value_t capList[1];

    /*
     * cap_get_proc() allocates a cap_t structure and fills it with
     * this process's current capability sets from the kernel.
     * MUST be freed with cap_free() when done.
     */
    caps = cap_get_proc();
    if (caps == NULL)
        return -1;

    /*
     * cap_set_flag(cap_t, cap_flag_t, int, cap_value_t[], cap_flag_value_t)
     *
     * Arguments:
     *   caps            — the capability structure to modify
     *   CAP_EFFECTIVE   — which set to modify (we only change effective here)
     *   1               — number of capabilities in capList array
     *   capList         — array of capabilities to change
     *   setting         — CAP_SET (raise) or CAP_CLEAR (drop)
     *
     * This modifies the IN-MEMORY structure only.
     * The kernel is not updated until cap_set_proc() is called.
     */
    capList[0] = capability;
    if (cap_set_flag(caps, CAP_EFFECTIVE, 1, capList, setting) == -1) {
        cap_free(caps);
        return -1;
    }

    /*
     * cap_set_proc() pushes the modified capability structure back to
     * the kernel, actually changing the process's capabilities.
     * This is the step that the kernel checks against the rules in Section 39.7.
     */
    if (cap_set_proc(caps) == -1) {
        cap_free(caps);
        return -1;
    }

    /* Always free the libcap-allocated structure */
    if (cap_free(caps) == -1)
        return -1;

    return 0;
}

/*
 * raiseCap() - Raise a single capability in the effective set.
 * After this call, the capability is ACTIVE and the kernel will allow
 * the corresponding privileged operations.
 */
static int raiseCap(int capability)
{
    return modifyCap(capability, CAP_SET);
}

/*
 * dropAllCaps() - Drop ALL capabilities from ALL three sets.
 *
 * Creates an empty cap_t structure (cap_init() returns a cap_t with
 * all capabilities cleared in all sets), then applies it to the process.
 *
 * After this call, the process has NO capabilities in any set.
 * This is the "nuclear option" for dropping privileges — used when
 * the program no longer needs ANY capabilities for the rest of its life.
 */
static int dropAllCaps(void)
{
    cap_t empty;
    int s;

    /*
     * cap_init() allocates a new cap_t with all capabilities cleared
     * in permitted, effective, and inheritable sets.
     */
    empty = cap_init();
    if (empty == NULL)
        return -1;

    /*
     * cap_set_proc() with an all-zeros structure permanently drops
     * all capabilities. The process now has no capabilities whatsoever.
     */
    s = cap_set_proc(empty);

    cap_free(empty);
    return s;
}

int main(int argc, char *argv[])
{
    char *username, *password, *encrypted, *p;
    struct passwd *pwd;
    struct spwd *spwd;
    int authOk;
    size_t len;
    long lnmax;

    /* ============================================================
     * At program start, effective caps are EMPTY (file effective bit = 0).
     * CAP_DAC_READ_SEARCH is in permitted set (from file permitted set).
     * We have NOT yet raised it to effective — we don't need it yet.
     * ============================================================ */

    lnmax = sysconf(_SC_LOGIN_NAME_MAX);
    if (lnmax == -1)
        lnmax = 256;

    username = malloc(lnmax);
    if (username == NULL) { perror("malloc"); exit(EXIT_FAILURE); }

    printf("Username: ");
    fflush(stdout);

    if (fgets(username, lnmax, stdin) == NULL)
        exit(EXIT_FAILURE);

    len = strlen(username);
    if (username[len - 1] == '\n')
        username[len - 1] = '\0';

    /* Get the public password record (world-readable) — no privilege needed */
    pwd = getpwnam(username);
    if (pwd == NULL) {
        fprintf(stderr, "No such user: %s\n", username);
        exit(EXIT_FAILURE);
    }

    /* ============================================================
     * RAISE CAP_DAC_READ_SEARCH in the effective set.
     *
     * We raise the capability ONLY for the brief window where we
     * need to read /etc/shadow (which is protected: -rw-r----- root shadow).
     *
     * This is the MINIMUM PRIVILEGE principle: hold elevated capabilities
     * for the shortest possible time.
     * ============================================================ */
    if (raiseCap(CAP_DAC_READ_SEARCH) == -1) {
        fprintf(stderr, "raiseCap() failed\n");
        exit(EXIT_FAILURE);
    }

    /* Read the shadow password record — requires CAP_DAC_READ_SEARCH */
    spwd = getspnam(username);
    if (spwd == NULL && errno == EACCES) {
        fprintf(stderr, "No permission to read shadow password file\n");
        exit(EXIT_FAILURE);
    }

    /* ============================================================
     * DROP ALL CAPABILITIES immediately after reading shadow file.
     *
     * We are done with all privileged operations. Drop everything
     * permanently. For the rest of this program, we run with no
     * capabilities at all — just like a normal unprivileged process.
     * ============================================================ */
    if (dropAllCaps() == -1) {
        fprintf(stderr, "dropAllCaps() failed\n");
        exit(EXIT_FAILURE);
    }

    /* Use shadow password if available */
    if (spwd != NULL)
        pwd->pw_passwd = spwd->sp_pwdp;

    /* Get the password (echoing disabled) */
    password = getpass("Password: ");

    /*
     * crypt() hashes the plaintext password using the algorithm and salt
     * stored in the shadow record. We compare the result to the stored hash.
     */
    encrypted = crypt(password, pwd->pw_passwd);

    /* Erase the cleartext password from memory immediately */
    for (p = password; *p != '\0'; )
        *p++ = '\0';

    if (encrypted == NULL) { perror("crypt"); exit(EXIT_FAILURE); }

    authOk = (strcmp(encrypted, pwd->pw_passwd) == 0);

    if (!authOk) {
        printf("Incorrect password\n");
        exit(EXIT_FAILURE);
    }

    printf("Successfully authenticated: UID=%ld\n", (long)pwd->pw_uid);

    /* At this point we run fully authenticated work with zero capabilities */
    exit(EXIT_SUCCESS);
}