capabilities.7: Substantially rework "Capabilities and execution of programs by root"

capabilities.7: Substantially rework "Capabilities and execution of programs by root"

Rework for improved clarity, and also to include missing details
on the case where (1) the binary that is being executed has
capabilities attached and (2) the real user ID of the process is
not 0 (root) and (3) the effective user ID of the process is 0
(root).

Kernel code analysis and some test code (GPLv3 licensed) below.

======

My analysis of security/commoncaps.c capabilities handling
(from Linux 4.20 source):

execve() eventually calls __do_execve_file():

__do_execve_file()
  |
  +-prepare_bprm_creds(&bprm)
  |  |
  |  +-prepare_exec_creds()
  |  |  |
  |  |  +-prepare_creds()
  |  |     |
  |  |     | // Returns copy of existing creds
  |  |     |
  |  |     +-security_prepare_creds()
  |  |        |
  |  |        +-cred_prepare() [via hook]
  |  |           // Seems to do nothing for commoncaps
  |  |
  |  // Returns creds provided by prepare_creds()
  |
  // Places creds returned by prepare_exec_creds() in bprm->creds
  |
  |
  +-prepare_binprm(&bprm) // bprm from prepare_bprm_creds()
     |
     +-bprm_fill_uid(&bprm)
     |
     |  // Places current credentials into bprm
     |
     |  // Performs set-UID & set-GID transitions if those file bits are set
     |
     +-security_bprm_set_creds(&bprm)
        |
        +-bprm_set_creds(&bprm) [via hook]
           |
           +-cap_bprm_set_creds(&bprm)
              |
              // effective = false
              |
              +-get_file_caps(&bprm, &effective, &has_fcap)
              |  |
              |  +-get_vfs_caps_from_disk(..., &vcaps)
              |  |
              |  |  // Fetches file capabilities from disk and places in vcaps
              |  |
              |  +-bprm_caps_from_vfs_caps(&vcaps, &bprm, &effective, &has_fcap)
              |
              |     // If file effective bit is set: effective = true
              |     //
              |     // If file has capabilities: has_fcap |= true
              |     //
              |     // Perform execve transformation:
              |     //     P'(perm) = F(inh) & P(Inh) | F(Perm) & P(bset)
              |
              +-handle_privileged_root(&bprm, has_fcap, &effective, root_uid)
              |
              |  // If has_fcap && (rUID != root && eUID == root) then
              |  //     return without doing anything
              |  //
              |  // If rUID == root || eUID == root then
              |  //    P'(perm) = P(inh) | P(bset)
              |  //
              |  // If eUID == root then
              |  //     effective = true
              |
              // Perform execve() transformation:
              //
              //     P'(Amb) = (privprog) ? 0 : P(Amb)
              //     P'(Perm) |= P'(Amb)
              //     P'(Eff) = effective ? P'(Perm) : P'(Amb)

Summary

1. Perform set-UID/set-GID transformations

2. P'(Amb) = (privprog) ? 0 : P(Amb)

3. If [process has nonzero UIDs] OR
   ([file has caps] && [rUID != root && eUID == root]), then

        P'(perm) = F(inh) & P(Inh) | F(Perm) & P(bset) | P'(Amb)

   else // ~ [process has rUID == root || eUID == root]

        P'(perm) = P(inh) | P(bset) | P'(Amb)

4. P'(Eff) = (F(eff) || eUID == root) ? P'(Perm) : P'(Amb)

======

$ cat show_creds_and_caps_long.c

int
main(int argc, char *argv[])
{
    uid_t ruid, euid, suid;
    gid_t rgid, egid, sgid;
    cap_t caps;
    char *s;

    if (getresuid(&ruid, &euid, &suid) == -1) {
        perror("getresuid");
        exit(EXIT_FAILURE);
    }

    if (getresgid(&rgid, &egid, &sgid) == -1) {
        perror("getresgid");
        exit(EXIT_FAILURE);
    }

    printf("UID: %5ld (real), %5ld (effective), %5ld (saved)\n",
            (long) ruid, (long) euid, (long) suid);
    printf("GID: %5ld (real), %5ld (effective), %5ld (saved)\n",
            (long) rgid, (long) egid, (long) sgid);

    caps = cap_get_proc();
    if (caps == NULL) {
        perror("cap_get_proc");
        exit(EXIT_FAILURE);
    }
    s = cap_to_text(caps, NULL);
    if (s == NULL) {
        perror("cap_to_text");
        exit(EXIT_FAILURE);
    }
    printf("Capabilities: %s\n", s);

    cap_free(caps);
    cap_free(s);

    exit(EXIT_SUCCESS);
}

$ cat cred_launcher.c

                        } while (0)

                        do { fprintf(stderr, "Usage: "); \
                             fprintf(stderr, msg, progName); \
                             exit(EXIT_FAILURE); } while (0)

int
main(int argc, char *argv[])
{
    uid_t r, e, s;

    if (argc != 5 || strcmp(argv[1], "--help") == 0)
        usageErr("%s rUID eUID sUID <prog>\n", argv[0]);

    r = atoi(argv[1]);
    e = atoi(argv[2]);
    s = atoi(argv[3]);

    if (setresuid(r, e, s) == -1)
        errExit("setresuid");

    if (getresuid(&r, &e, &s) == -1)
        errExit("getresuid");

    execv(argv[4], &argv[4]);
    errExit("execve");
}

$ cc -o cred_launcher cred_launcher.c
$ cc -o show_creds_and_caps_long show_creds_and_caps_long.c -lcap

$ sudo ./cred_launcher 1000 0 1000 ./show_creds_and_caps_long
UID:  1000 (real),     0 (effective),     0 (saved)
GID:     0 (real),     0 (effective),     0 (saved)
Capabilities: =ep

$ sudo setcap cap_kill=pe show_creds_and_caps_long
$ sudo ./cred_launcher 1000 0 1000 ./show_creds_and_caps_long
UID:  1000 (real),     0 (effective),     0 (saved)
GID:     0 (real),     0 (effective),     0 (saved)
Capabilities: = cap_kill+ep

The final program execution above shows the special casing
that occurs in handle_privileged_root() for the case where:

    rUID != root && eUID == root && [file has capabilities]

======

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>