| 1 |
.TH LIBCAP 3 "2022-10-16" "" "Linux Programmer's Manual" |
| 2 |
.SH NAME |
| 3 |
cap_clear, cap_clear_flag, cap_compare, cap_copy_ext, cap_copy_int, \ |
| 4 |
cap_drop_bound, cap_dup, cap_fill, cap_fill_flag, cap_free, cap_from_name, \ |
| 5 |
cap_from_text, cap_get_ambient, cap_get_bound, cap_get_fd, \ |
| 6 |
cap_get_file, cap_get_flag, cap_get_mode, cap_get_nsowner, cap_get_pid, \ |
| 7 |
cap_get_pid, cap_get_proc, cap_get_secbits, cap_init, cap_max_bits, \ |
| 8 |
cap_prctl, cap_prctlw, cap_proc_root, cap_reset_ambient, \ |
| 9 |
cap_set_ambient, cap_set_fd, cap_set_file, cap_set_flag, cap_setgroups, \ |
| 10 |
cap_set_mode, cap_set_nsowner, cap_set_proc, cap_set_secbits, \ |
| 11 |
cap_setuid, cap_size, cap_to_name, cap_to_text \- capability data object manipulation |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
#include <sys/capability.h> |
| 15 |
|
| 16 |
int cap_clear(cap_t cap_p); |
| 17 |
int cap_fill(cap_t cap_p, cap_flag_t to, cap_flag_t from); |
| 18 |
int cap_fill_flag(cap_t cap_p, cap_flag_t to, const cap_t ref, cap_flag_t from); |
| 19 |
int cap_clear_flag(cap_t cap_p, cap_flag_t flag); |
| 20 |
int cap_compare(cap_t cap_a, cap_t cap_b); |
| 21 |
ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size); |
| 22 |
cap_t cap_copy_int(const void *ext_p); |
| 23 |
int cap_free(void *obj_d); |
| 24 |
int cap_from_name(const char *name, cap_value_t *cap_p); |
| 25 |
cap_t cap_from_text(const char *buf_p); |
| 26 |
cap_t cap_get_fd(int fd); |
| 27 |
cap_t cap_get_file(const char *path_p); |
| 28 |
int cap_get_flag(cap_t cap_p, cap_value_t cap , |
| 29 |
cap_flag_t flag, cap_flag_value_t *value_p); |
| 30 |
cap_value_t cap_max_bits(); |
| 31 |
|
| 32 |
#include <sys/types.h> |
| 33 |
|
| 34 |
cap_t cap_get_pid(pid_t pid); |
| 35 |
cap_t cap_get_proc(void); |
| 36 |
int cap_set_fd(int fd, cap_t caps); |
| 37 |
int cap_set_file(const char *path_p, cap_t cap_p); |
| 38 |
int cap_set_flag(cap_t cap_p, cap_flag_t flag, int ncap , |
| 39 |
const cap_value_t *caps, cap_flag_value_t value); |
| 40 |
int cap_set_proc(cap_t cap_p); |
| 41 |
ssize_t cap_size(cap_t cap_p); |
| 42 |
char *cap_to_name(cap_value_t cap); |
| 43 |
char *cap_to_text(cap_t caps, ssize_t *length_p); |
| 44 |
cap_t cap_get_pid(pid_t pid); |
| 45 |
cap_t cap_init(); |
| 46 |
cap_t cap_dup(cap_t cap_p); |
| 47 |
|
| 48 |
char *cap_proc_root(const char *root); |
| 49 |
int cap_get_nsowner(cap_t cap_p); |
| 50 |
int cap_set_nsowner(cap_t cap_p, uid_t rootuid); |
| 51 |
int cap_get_bound(cap_value_t cap); |
| 52 |
int cap_drop_bound(cap_value_t cap); |
| 53 |
int cap_get_ambient(cap_value_t cap); |
| 54 |
int cap_set_ambient(cap_value_t cap, cap_flag_value_t value); |
| 55 |
int cap_reset_ambient(void); |
| 56 |
int cap_set_mode(cap_mode_t flavor); |
| 57 |
cap_mode_t cap_get_mode(void); |
| 58 |
const char *cap_mode_name(cap_mode_t flavor); |
| 59 |
unsigned cap_get_secbits(); |
| 60 |
int cap_set_secbits(unsigned bits); |
| 61 |
int cap_prctl(long int pr_cmd, long int arg1, long int arg2, long int arg3, |
| 62 |
long int arg4, long int arg5); |
| 63 |
int cap_prctlw(long int pr_cmd, long int arg1, long int arg2, long int arg3, |
| 64 |
long int arg4, long int arg5); |
| 65 |
int cap_setuid(uid_t uid); |
| 66 |
int cap_setgroups(gid_t gid, size_t ngroups, const gid_t groups[]); |
| 67 |
.fi |
| 68 |
.sp |
| 69 |
Link with \fI\-lcap\fP. |
| 70 |
.fi |
| 71 |
.SH DESCRIPTION |
| 72 |
These primary functions work on a capability state held in working |
| 73 |
storage and attempt to complete the POSIX.1e (draft) user space API |
| 74 |
for Capability based privilege. |
| 75 |
.PP |
| 76 |
A |
| 77 |
.I cap_t |
| 78 |
holds information about the capabilities in each of the three sets, |
| 79 |
Permitted, Inheritable, and Effective. Each capability in a set may |
| 80 |
be clear (disabled, 0) or set (enabled, 1). |
| 81 |
.PP |
| 82 |
These functions work with the following data types: |
| 83 |
.TP 18 |
| 84 |
.I cap_value_t |
| 85 |
identifies a capability, such as |
| 86 |
.BR CAP_CHOWN . |
| 87 |
.TP |
| 88 |
.I cap_flag_t |
| 89 |
identifies one of the three flags associated with a capability |
| 90 |
(i.e., it identifies one of the three capability sets). |
| 91 |
Valid values for this type are |
| 92 |
.BR CAP_EFFECTIVE , |
| 93 |
.B CAP_INHERITABLE |
| 94 |
or |
| 95 |
.BR CAP_PERMITTED . |
| 96 |
.TP |
| 97 |
.I cap_flag_value_t |
| 98 |
identifies the setting of a particular capability flag |
| 99 |
(i.e, the value of a capability in a set). |
| 100 |
Valid values for this type are |
| 101 |
.BR CAP_CLEAR (0) |
| 102 |
or |
| 103 |
.BR CAP_SET (1). |
| 104 |
.SH "RETURN VALUE" |
| 105 |
The return value is generally specific to the individual function called. |
| 106 |
On failure, |
| 107 |
.I errno |
| 108 |
is set appropriately. |
| 109 |
.SH "CONFORMING TO" |
| 110 |
These functions are as per the withdrawn POSIX.1e draft specification. |
| 111 |
The following functions are Linux extensions: |
| 112 |
.BR cap_clear_flag (), |
| 113 |
.BR cap_drop_bound (), |
| 114 |
.BR cap_fill (), |
| 115 |
.BR cap_fill_flag (), |
| 116 |
.BR cap_from_name (), |
| 117 |
.BR cap_get_ambient (), |
| 118 |
.BR cap_get_bound (), |
| 119 |
.BR cap_get_mode (), |
| 120 |
.BR cap_get_nsowner (), |
| 121 |
.BR cap_get_secbits (), |
| 122 |
.BR cap_mode_name (), |
| 123 |
.BR cap_proc_root (), |
| 124 |
.BR cap_prctl (), |
| 125 |
.BR cap_prctlw (), |
| 126 |
.BR cap_reset_ambient (), |
| 127 |
.BR cap_setgroups (), |
| 128 |
.BR cap_setuid (), |
| 129 |
.BR cap_set_ambient (), |
| 130 |
.BR cap_set_mode (), |
| 131 |
.BR cap_set_nsowner (), |
| 132 |
.BR cap_set_secbits (), |
| 133 |
.BR cap_to_name () |
| 134 |
and |
| 135 |
.BR cap_compare (). |
| 136 |
.PP |
| 137 |
A Linux, \fIIAB\fP, extension of Inheritable, Bounding and Ambient |
| 138 |
tuple capability vectors are also supported by \fBlibcap\fP. Those |
| 139 |
functions are described in a companion man page: |
| 140 |
.BR cap_iab (3). |
| 141 |
Further, for managing the complexity of launching a sub-process, |
| 142 |
\fBlibcap\fP supports the abstraction: |
| 143 |
.BR cap_launch (3). |
| 144 |
.PP |
| 145 |
In addition to the \fBcap_\fP prefixed \fBlibcap\fP API, the library |
| 146 |
also provides prototypes for the Linux system calls that provide the |
| 147 |
native API for process capabilities. These prototypes are: |
| 148 |
.sp |
| 149 |
.nf |
| 150 |
int capget(cap_user_header_t header, cap_user_data_t data); |
| 151 |
int capset(cap_user_header_t header, const cap_user_data_t data); |
| 152 |
.fi |
| 153 |
.sp |
| 154 |
Further, \fBlibcap\fP provides a set-up function, |
| 155 |
.sp |
| 156 |
.nf |
| 157 |
void cap_set_syscall( |
| 158 |
long int (*new_syscall)(long int, long int, long int, long int), |
| 159 |
long int (*new_syscall6)(long int, |
| 160 |
long int, long int, long int, |
| 161 |
long int, long int, long int)); |
| 162 |
.fi |
| 163 |
.sp |
| 164 |
which can be used to redirect its use of the |
| 165 |
.BR capset () |
| 166 |
and other system calls that write kernel managed state. This is |
| 167 |
especially useful when supporting POSIX semantics for security |
| 168 |
state. When a program is linked against |
| 169 |
.BR libpsx (3) |
| 170 |
as described in that man page, this function is used to connect |
| 171 |
\fBlibcap\fP to POSIX semantics system calls. |
| 172 |
.SH "REPORTING BUGS" |
| 173 |
The |
| 174 |
.B libcap |
| 175 |
library is distributed from |
| 176 |
https://sites.google.com/site/fullycapable/ where the release notes |
| 177 |
may already cover recent issues. Please report newly discovered bugs |
| 178 |
via: |
| 179 |
.TP |
| 180 |
https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757 |
| 181 |
.SH "SEE ALSO" |
| 182 |
.BR cap_clear (3), |
| 183 |
.BR cap_copy_ext (3), |
| 184 |
.BR cap_from_text (3), |
| 185 |
.BR cap_get_file (3), |
| 186 |
.BR cap_get_proc (3), |
| 187 |
.BR cap_iab (3), |
| 188 |
.BR cap_init (3), |
| 189 |
.BR cap_launch (3), |
| 190 |
.BR capabilities (7), |
| 191 |
.BR getpid (2), |
| 192 |
.BR capsh (1), |
| 193 |
.BR captree (8), |
| 194 |
.BR getcap (8), |
| 195 |
.BR getpcaps (8), |
| 196 |
.BR setcap (8) |
| 197 |
and |
| 198 |
.BR libpsx (3). |