CSE Roadmap

Core tier · about 3 hours · 6 parts

Part 4 of 6 · 4 min read

One capability

Think of a hotel guest who has a card that opens one door, the gym. The card does nothing at the pool or at other rooms. The analogy stops in one place: a hotel card is made by the hotel, and a process keeps its capability only because code in the process asked the kernel to keep it.

In plain words: A server usually starts as root, binds its port, and then drops to a normal user. A change of user normally clears the capabilities, so a program that wants to keep one must ask the kernel to keep its permitted set across the change (prctl with PR_SET_KEEPCAPS), switch user, and then set its capability sets with capset (a system call) to exactly the ones it needs. The program below does the three states in turn and tries two acts each time: bind port 80, and open /etc/shadow. It needs root to run, so the test used the machine's root account.

A worked example.

#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <grp.h>
#include <linux/capability.h>
#include <netinet/in.h>
#include <stdio.h>
#include <string.h>
#include <sys/prctl.h>
#include <sys/socket.h>
#include <sys/syscall.h>
#include <sys/wait.h>
#include <unistd.h>

static void report(const char *who) {
    char line[128], eff[32] = "?";
    FILE *f = fopen("/proc/self/status", "r");
    while (f && fgets(line, sizeof line, f))
        if (!strncmp(line, "CapEff:", 7)) sscanf(line + 7, "%31s", eff);
    if (f) fclose(f);
    int s = socket(AF_INET, SOCK_STREAM, 0);
    struct sockaddr_in a = { .sin_family = AF_INET, .sin_port = htons(80) };
    int b = bind(s, (struct sockaddr *)&a, sizeof a);
    int e = errno;
    close(s);
    int r = open("/etc/shadow", O_RDONLY);
    int e2 = errno;
    printf("%-22s uid=%-5d CapEff=%s bind(80): %s, open(/etc/shadow): %s\n", who,
           (int)geteuid(), eff, b == 0 ? "ok" : strerror(e),
           r >= 0 ? "ok" : strerror(e2));
    fflush(stdout);
}

static void drop_ids(void) {
    setgroups(0, NULL);
    setgid(65534);
    setuid(65534);
}

int main(void) {
    report("root, all capabilities");
    if (fork() == 0) { drop_ids(); report("nobody, no capability"); _exit(0); }
    wait(NULL);
    if (fork() == 0) {
        prctl(PR_SET_KEEPCAPS, 1);   /* keep permitted set across setuid */
        drop_ids();
        struct __user_cap_header_struct h = { _LINUX_CAPABILITY_VERSION_3, 0 };
        struct __user_cap_data_struct d[2] = {{0}};
        d[0].permitted = d[0].effective = 1u << CAP_NET_BIND_SERVICE;
        syscall(SYS_capset, &h, d);
        report("nobody + NET_BIND");
        _exit(0);
    }
    wait(NULL);
    return 0;
}

Output on the test machine:

root, all capabilities uid=0     CapEff=000001fffeffffff bind(80): ok, open(/etc/shadow): ok
nobody, no capability  uid=65534 CapEff=0000000000000000 bind(80): Permission denied, open(/etc/shadow): Permission denied
nobody + NET_BIND      uid=65534 CapEff=0000000000000400 bind(80): ok, open(/etc/shadow): Permission denied

Root passes both acts. The plain user nobody fails both, and its effective set is empty (all zeros). The third process is also nobody, but with the bind bit set (0x400): bind works, and /etc/shadow is still refused, because opening a file needs the file permission of page 2 or CAP_DAC_OVERRIDE, and the process has neither. Both failures show the same error text, Permission denied (the code EACCES), for different reasons: the first has no capability, and the second lacks the capability that the second act needs.

The key lines. The first port that needs no privilege is read from /proc/sys/net/ipv4/ip_unprivileged_port_start, which was 1024 on the test machine. On a newer system an administrator can lower it, which removes the need for the capability for those ports.

File capability

A file capability is a capability set stored on an executable file (with setcap), which a process receives when it runs that file. It gives a program one capability without making it setuid root. (The ambient set, mentioned above, does a similar job for programs that carry no file capabilities.)

Example: setcap cap_net_bind_service=ep /usr/local/bin/server lets any user run the server with that one capability.

Check yourself: 1. Why does the second process fail both acts? 2. Which bit differs between the second and third process? 3. Why is a file capability safer than setuid root?