diff options
Diffstat (limited to 'doc/libcap.3')
| -rw-r--r-- | doc/libcap.3 | 112 |
1 files changed, 102 insertions, 10 deletions
diff --git a/doc/libcap.3 b/doc/libcap.3 index b8c8520..a91cf7e 100644 --- a/doc/libcap.3 +++ b/doc/libcap.3 @@ -1,15 +1,21 @@ -.TH LIBCAP 3 "2021-03-06" "" "Linux Programmer's Manual" +.TH LIBCAP 3 "2022-10-16" "" "Linux Programmer's Manual" .SH NAME cap_clear, cap_clear_flag, cap_compare, cap_copy_ext, cap_copy_int, \ -cap_free, cap_from_name, cap_from_text, cap_get_fd, cap_get_file, \ -cap_get_flag, cap_get_pid, cap_get_proc, cap_set_fd, cap_set_file, \ -cap_set_flag, cap_set_proc, cap_size, cap_to_name, cap_to_text, \ -cap_get_pid, cap_dup \- capability data object manipulation +cap_drop_bound, cap_dup, cap_fill, cap_fill_flag, cap_free, cap_from_name, \ +cap_from_text, cap_get_ambient, cap_get_bound, cap_get_fd, \ +cap_get_file, cap_get_flag, cap_get_mode, cap_get_nsowner, cap_get_pid, \ +cap_get_pid, cap_get_proc, cap_get_secbits, cap_init, cap_max_bits, \ +cap_prctl, cap_prctlw, cap_proc_root, cap_reset_ambient, \ +cap_set_ambient, cap_set_fd, cap_set_file, cap_set_flag, cap_setgroups, \ +cap_set_mode, cap_set_nsowner, cap_set_proc, cap_set_secbits, \ +cap_setuid, cap_size, cap_to_name, cap_to_text \- capability data object manipulation .SH SYNOPSIS .nf #include <sys/capability.h> int cap_clear(cap_t cap_p); +int cap_fill(cap_t cap_p, cap_flag_t to, cap_flag_t from); +int cap_fill_flag(cap_t cap_p, cap_flag_t to, const cap_t ref, cap_flag_t from); int cap_clear_flag(cap_t cap_p, cap_flag_t flag); int cap_compare(cap_t cap_a, cap_t cap_b); ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size); @@ -21,6 +27,7 @@ cap_t cap_get_fd(int fd); cap_t cap_get_file(const char *path_p); int cap_get_flag(cap_t cap_p, cap_value_t cap , cap_flag_t flag, cap_flag_value_t *value_p); +cap_value_t cap_max_bits(); #include <sys/types.h> @@ -35,18 +42,42 @@ ssize_t cap_size(cap_t cap_p); char *cap_to_name(cap_value_t cap); char *cap_to_text(cap_t caps, ssize_t *length_p); cap_t cap_get_pid(pid_t pid); +cap_t cap_init(); cap_t cap_dup(cap_t cap_p); + +char *cap_proc_root(const char *root); +int cap_get_nsowner(cap_t cap_p); +int cap_set_nsowner(cap_t cap_p, uid_t rootuid); +int cap_get_bound(cap_value_t cap); +int cap_drop_bound(cap_value_t cap); +int cap_get_ambient(cap_value_t cap); +int cap_set_ambient(cap_value_t cap, cap_flag_value_t value); +int cap_reset_ambient(void); +int cap_set_mode(cap_mode_t flavor); +cap_mode_t cap_get_mode(void); +const char *cap_mode_name(cap_mode_t flavor); +unsigned cap_get_secbits(); +int cap_set_secbits(unsigned bits); +int cap_prctl(long int pr_cmd, long int arg1, long int arg2, long int arg3, + long int arg4, long int arg5); +int cap_prctlw(long int pr_cmd, long int arg1, long int arg2, long int arg3, + long int arg4, long int arg5); +int cap_setuid(uid_t uid); +int cap_setgroups(gid_t gid, size_t ngroups, const gid_t groups[]); .fi .sp Link with \fI\-lcap\fP. .fi .SH DESCRIPTION -These functions work on a capability state held in working storage. +These primary functions work on a capability state held in working +storage and attempt to complete the POSIX.1e (draft) user space API +for Capability based privilege. +.PP A .I cap_t holds information about the capabilities in each of the three sets, -Permitted, Inheritable, and Effective. -Each capability in a set may be clear (disabled, 0) or set (enabled, 1). +Permitted, Inheritable, and Effective. Each capability in a set may +be clear (disabled, 0) or set (enabled, 1). .PP These functions work with the following data types: .TP 18 @@ -79,10 +110,65 @@ is set appropriately. These functions are as per the withdrawn POSIX.1e draft specification. The following functions are Linux extensions: .BR cap_clear_flag (), +.BR cap_drop_bound (), +.BR cap_fill (), +.BR cap_fill_flag (), .BR cap_from_name (), -.BR cap_to_name (), +.BR cap_get_ambient (), +.BR cap_get_bound (), +.BR cap_get_mode (), +.BR cap_get_nsowner (), +.BR cap_get_secbits (), +.BR cap_mode_name (), +.BR cap_proc_root (), +.BR cap_prctl (), +.BR cap_prctlw (), +.BR cap_reset_ambient (), +.BR cap_setgroups (), +.BR cap_setuid (), +.BR cap_set_ambient (), +.BR cap_set_mode (), +.BR cap_set_nsowner (), +.BR cap_set_secbits (), +.BR cap_to_name () and .BR cap_compare (). +.PP +A Linux, \fIIAB\fP, extension of Inheritable, Bounding and Ambient +tuple capability vectors are also supported by \fBlibcap\fP. Those +functions are described in a companion man page: +.BR cap_iab (3). +Further, for managing the complexity of launching a sub-process, +\fBlibcap\fP supports the abstraction: +.BR cap_launch (3). +.PP +In addition to the \fBcap_\fP prefixed \fBlibcap\fP API, the library +also provides prototypes for the Linux system calls that provide the +native API for process capabilities. These prototypes are: +.sp +.nf +int capget(cap_user_header_t header, cap_user_data_t data); +int capset(cap_user_header_t header, const cap_user_data_t data); +.fi +.sp +Further, \fBlibcap\fP provides a set-up function, +.sp +.nf +void cap_set_syscall( + long int (*new_syscall)(long int, long int, long int, long int), + long int (*new_syscall6)(long int, + long int, long int, long int, + long int, long int, long int)); +.fi +.sp +which can be used to redirect its use of the +.BR capset () +and other system calls that write kernel managed state. This is +especially useful when supporting POSIX semantics for security +state. When a program is linked against +.BR libpsx (3) +as described in that man page, this function is used to connect +\fBlibcap\fP to POSIX semantics system calls. .SH "REPORTING BUGS" The .B libcap @@ -98,9 +184,15 @@ https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757 .BR cap_from_text (3), .BR cap_get_file (3), .BR cap_get_proc (3), +.BR cap_iab (3), .BR cap_init (3), +.BR cap_launch (3), .BR capabilities (7), .BR getpid (2), -.BR capsh (1) +.BR capsh (1), +.BR captree (8), +.BR getcap (8), +.BR getpcaps (8), +.BR setcap (8) and .BR libpsx (3). |