CAP_GET_FILE(3)

💖 CAP_GET_FILE — capability manipulation on files 💖

okay bestie, sit down, hydrate, and let me tell you about the libcap file-capability girlies. this is CAP_GET_FILE(3) from the Linux Programmer's Manual and it's literally the whole "get/set capabilities on a file" friend group. no cap. 🎀

✨ NAME ✨

cap_get_file, cap_set_file, cap_get_fd, cap_set_fd, cap_get_nsowner, cap_set_nsowner — capability manipulation on files 🦋

🌸 SYNOPSIS 🌸

#include <sys/capability.h>

cap_t cap_get_file(const char *path_p);
int cap_set_file(const char *path_p, cap_t cap_p);
cap_t cap_get_fd(int fd);
int cap_set_fd(int fd, cap_t caps);
uid_t cap_get_nsowner(cap_t caps);
int cap_set_nsowner(cap_t caps, uid_t rootuid);

Link with -lcap. (yes, you have to actually link it, it's not gonna manifest itself, bestie 💅)

🫶 DESCRIPTION 🫶

So cap_get_file() and cap_get_fd() allocate a capability state in working storage and set it to represent the capability state of the pathname pointed to by path_p, or the file open on descriptor fd. They hand you back a pointer to that freshly created capability state. ✨

heads up: reading the capability state from any file that is not a regular file? the effects are undefined. so don't. 🙈

And when you're done with that capability state in working storage, you should free any releasable memory by calling cap_free() with the used cap_t as an argument. clean up after yourself, queen. 🧚

Now, cap_set_file() and cap_set_fd() — they set the values for all capability flags for all capabilities, either for the pathname pointed to by path_p or the file open on descriptor fd, using the capability state identified by cap_p. the new capability state of the file is completely determined by the contents of cap_p. iconic. 👑

A NULL value for cap_p means "hey, delete the capabilities for this file." and for these functions to succeed, the calling process needs the CAP_SETFCAP capability in its effective set, and either the effective user ID of the process must match the file owner, or the calling process must have the CAP_FOWNER capability in its effective capability set. no shortcuts, bestie. 🔥

same warning, different function: writing the capability state to any file type other than a regular file is undefined. don't test fate. 💀

A capability set held in memory can be associated with the root user ID in use in a specific user namespace. you can get and set this value (in the memory copy) with cap_get_nsowner() and cap_set_nsowner() respectively. 💜

The root user ID is ignored by the libcap library in all cases other than when the capability is written to a file. Only if the value is non-zero will the library attempt to include it in the written file capability set. that's the one and only moment it matters. periodt. 💅

⭐ RETURN VALUE ⭐

• cap_get_file() and cap_get_fd() return a non-NULL value on success, and NULL on failure. 😭
• cap_set_file() and cap_set_fd() return zero on success, and -1 on failure. 🫠

On failure, errno is set to one of: EACCES, EBADFD, ENAMETOOLONG, ENOENT, ENOMEM, ENOTDIR, EPERM, or EROFS. 🌈

🎀 CONFORMING TO 🎀

These functions are specified by the withdrawn POSIX.1e draft specification. (withdrawn, bestie — it's giving vintage, it's giving archive-core 🕰️)

👑 NOTES 👑

Support for file capabilities is provided on Linux since version 2.6.24. 🐧

On Linux, the file Effective set is a single bit. let that sink in. If it is enabled, then all Permitted capabilities are enabled in the Effective set of the calling process when the file is executed; otherwise, no capabilities are enabled in the process's Effective set following an execve(2). 🤯

Because the file Effective set is a single bit, if any capability is enabled in the Effective set of the cap_t given to cap_set_file() or cap_set_fd(), then all capabilities whose Permitted or Inheritable flag is enabled must also have the Effective flag enabled. conversely, if the Effective bit is enabled on a file, then the cap_t returned by cap_get_file() and cap_get_fd() will have the Effective flag enabled for each capability that has the Permitted or Inheritable flag enabled. it's all or nothing, main character energy only. ✨

🔥 SEE ALSO 🔥

• libcap(3)
• cap_clear(3)
• cap_copy_ext(3)
• cap_from_text(3)
• cap_get_proc(3)
• cap_init(3)
• capabilities(7)
• user_namespaces(7)

and that's the whole page, bestie — written up on 2022-10-16, straight from the Linux Programmer's Manual, CAP_GET_FILE(3), and yes you read all of it, I'm so proud, slay 💖✨🎀