| 1 |
.TH CAP_LAUNCH 3 "2021-08-01" "" "Linux Programmer's Manual" |
| 2 |
.SH NAME |
| 3 |
cap_new_launcher, cap_func_launcher, cap_launcher_callback, \ |
| 4 |
cap_launcher_set_mode, cap_launcher_set_iab, cap_launcher_set_chroot, \ |
| 5 |
cap_launch, cap_launcher_setuid, cap_launcher_setgroups \ |
| 6 |
\- libcap launch functionality |
| 7 |
.SH SYNOPSYS |
| 8 |
.nf |
| 9 |
#include <sys/capability.h> |
| 10 |
|
| 11 |
cap_launch_t cap_new_launcher(const char *arg0, const char *const *argv, |
| 12 |
const char *const *envp); |
| 13 |
|
| 14 |
cap_launch_t cap_func_launcher(int (callback_fn)(void *detail)); |
| 15 |
|
| 16 |
int cap_launcher_callback(cap_launch_t attr, |
| 17 |
int (callback_fn)(void *detail)); |
| 18 |
int cap_launcher_set_mode(cap_launch_t attr, cap_mode_t flavor); |
| 19 |
cap_iab_t cap_launcher_set_iab(cap_launch_t attr, cap_iab_t iab); |
| 20 |
int cap_launcher_set_chroot(cap_launch_t attr, const char *chroot); |
| 21 |
|
| 22 |
#include <sys/types.h> |
| 23 |
|
| 24 |
pid_t cap_launch(cap_launch_t attr, void *detail); |
| 25 |
int cap_launcher_setuid(cap_launch_t attr, uid_t uid); |
| 26 |
int cap_launcher_setgroups(cap_launch_t attr, gid_t gid, |
| 27 |
int ngroups, const gid_t *groups); |
| 28 |
.fi |
| 29 |
.sp |
| 30 |
Link with \fI\-lcap\fP. |
| 31 |
.SH DESCRIPTION |
| 32 |
A launcher provides a mechanism for code to execute a callback |
| 33 |
function and/or a program executable in an environment with a modified |
| 34 |
security context. Essentially it provides a mechanism for a program to |
| 35 |
.BR fork (2) |
| 36 |
a new context from that of the main program manipulate capability and other privileged state in that |
| 37 |
.BR fork (2)d |
| 38 |
process before (optionally) |
| 39 |
.BR execve (2)ing |
| 40 |
a new program. When the application links to \fI\-lpsx\fP this support |
| 41 |
is needed to robustly execute the launched code without modifying the |
| 42 |
privilge of the whole (POSIX semantics honoring) main application. |
| 43 |
.PP |
| 44 |
A launcher is defined by one of these two functions: |
| 45 |
.BR cap_new_launcher () |
| 46 |
or |
| 47 |
.BR cap_func_launcher (). |
| 48 |
The return value being of opaque type |
| 49 |
.B cap_launch_t |
| 50 |
a return value of NULL implies an error has occurred. |
| 51 |
.PP |
| 52 |
Once defined, a |
| 53 |
.B cap_launch_t |
| 54 |
value can be used with |
| 55 |
.BR cap_launch () |
| 56 |
to execute that \fIlauncher\fP. In such cases, a non-negative return |
| 57 |
value indicates success: zero meaning success without a program being |
| 58 |
invoked; non-zero being equal to the process ID |
| 59 |
.RB ( pid_t ) |
| 60 |
of the newly launched program. |
| 61 |
.PP |
| 62 |
A |
| 63 |
.B cap_launch_t |
| 64 |
occupies allocated memory and should be freed with |
| 65 |
.BR cap_free (3). |
| 66 |
Before being |
| 67 |
.BR cap_free (3)d |
| 68 |
a |
| 69 |
.B cap_value_t |
| 70 |
value may be reused for multiple independent launches. The |
| 71 |
.I detail |
| 72 |
argument to |
| 73 |
.BR cap_launch (), |
| 74 |
in conjunction with the launcher's callback function, can be used to |
| 75 |
customize the invocation of the launch. Care must be taken to leverage |
| 76 |
custom shared memory (see |
| 77 |
.BR mmap (2)) |
| 78 |
or some other IPC to return values to the main program via |
| 79 |
.I detail |
| 80 |
since the callback and any subsequent program execution will occur |
| 81 |
outside the main process of the calling application. An example of |
| 82 |
this would be to allocate detail as follows: |
| 83 |
.nf |
| 84 |
|
| 85 |
const char *args[] = { "echo", "hello", NULL }; |
| 86 |
cap_launch_t cmd = cap_new_launcher("/usr/bin/echo", args, NULL); |
| 87 |
int *detail = mmap(NULL, sizeof(int), PROT_READ | PROT_WRITE, |
| 88 |
MAP_SHARED | MAP_ANONYMOUS, -1, 0); |
| 89 |
cap_launcher_callback(cmd, &answer_detail_fn); |
| 90 |
*detail = 41; |
| 91 |
pid_t pid = cap_launch(cmd, detail); |
| 92 |
printf("launcher callback set detail to %d\\n", *detail); |
| 93 |
munmap(detail, sizeof(int)); |
| 94 |
|
| 95 |
.fi |
| 96 |
.PP |
| 97 |
Unless modified by the callback function, the launched code will |
| 98 |
execute with the capability and other security context of the |
| 99 |
application. |
| 100 |
|
| 101 |
If the callback function returns anything other than zero, a |
| 102 |
.BR cap_launch () |
| 103 |
will be aborted. If detail of the failure is important to the caller, |
| 104 |
it should be communicated via the |
| 105 |
.I detail |
| 106 |
argument. |
| 107 |
|
| 108 |
The following functions can be used to instruct the launcher to modify |
| 109 |
the security state of the invoked program without altering the state |
| 110 |
of the calling program. Such modifications must be performed prior to |
| 111 |
calling \fBcap_launch\fP() if they are to have the desired |
| 112 |
effect. Further, they are only invoked after any installed callback |
| 113 |
has completed. For example, one can drop or modify capabilities, |
| 114 |
\fIjust\fP for executing a file. |
| 115 |
.PP |
| 116 |
The following functions instruct the launcher to do some common tasks |
| 117 |
of this sort (note some require permitted capability bits to succeed): |
| 118 |
.sp |
| 119 |
.BR cap_launcher_callback () |
| 120 |
can be used to install or replace the currently installed callback |
| 121 |
function of the launcher. |
| 122 |
.sp |
| 123 |
.BR cap_launcher_set_mode () |
| 124 |
can be used to ensure that the libcap-mode of the launched program is |
| 125 |
the desired one. |
| 126 |
.sp |
| 127 |
.BR cap_launcher_set_iab () |
| 128 |
This function returns the \fBcap_iab_t\fP previously associated with |
| 129 |
the launcher. Calling this function with an IAB value of NULL will |
| 130 |
configure the launcher to not set an IAB value (the default). See |
| 131 |
\fBcap_iab\fP(3) for details on the IAB set. Note, the launcher is |
| 132 |
associated directly with the supplied \fIiab\fP value, and does not |
| 133 |
make a copy of it. This iab value is locked to the laucher and cannot |
| 134 |
be modified while associated with the launcher. Set with NULL to |
| 135 |
regain control over the memory associated with that IAB value, |
| 136 |
otherwise the IAB value will be \fBcap_free\fI()\fP'd when the |
| 137 |
launcher is. |
| 138 |
.sp |
| 139 |
.BR cap_launcher_set_chroot () |
| 140 |
This function causes the launched program executable to be invoked |
| 141 |
inside a chroot \fIroot\fP directory. |
| 142 |
.sp |
| 143 |
.BR cap_launcher_setuid () |
| 144 |
This function causes the launched program executable to be invoked |
| 145 |
with the specified user identifier (\fIuid_t\fP). |
| 146 |
.sp |
| 147 |
.BR cap_launcher_setgroups () |
| 148 |
This function causes the launched program executable to be invoked |
| 149 |
with the specified primary and supplementary group IDs. |
| 150 |
.sp |
| 151 |
.PP |
| 152 |
Note, if any of the launcher enhancements made by the above functions |
| 153 |
should fail to take effect (typically for a lack of sufficient |
| 154 |
privilege), the launch will fail and return -1. |
| 155 |
|
| 156 |
.SH "ERRORS" |
| 157 |
A return of NULL for a |
| 158 |
.B cap_launch_t |
| 159 |
should be considered an error. |
| 160 |
.PP |
| 161 |
.BR cap_launch () |
| 162 |
returns -1 in the case of an error. |
| 163 |
.PP |
| 164 |
In all such cases a return value of 0 implies success. In other cases, |
| 165 |
consult |
| 166 |
.BR errno (3) |
| 167 |
for further details. |
| 168 |
.SH "HISTORY" |
| 169 |
The \fBcap_launch\fP() family of functions were introduced in libcap |
| 170 |
2.33. It primarily addresses a complexity with \fI-lpsx\fP linked |
| 171 |
pthreads(7) applications that use capabilities but also honor POSIX |
| 172 |
semantics. |
| 173 |
|
| 174 |
Using \fI\-lcap\fP and \fI\-lpthread\fP together without the POSIX |
| 175 |
semantics support from \fI\-lpsx\fP introduces a subtle class of |
| 176 |
exposure to privilege escalation. (See |
| 177 |
https://sites.google.com/site/fullycapable/who-ordered-libpsx for an |
| 178 |
explanation.) |
| 179 |
.SH "SEE ALSO" |
| 180 |
.BR libpsx (3), |
| 181 |
.BR psx_syscall (3), |
| 182 |
.BR libcap (3), |
| 183 |
.BR cap_mode (3), |
| 184 |
.BR cap_iab (3), |
| 185 |
.BR capabilities (7), |
| 186 |
.BR errno (3), |
| 187 |
.BR fork (2), |
| 188 |
.BR mmap (2), |
| 189 |
.BR chroot (2), |
| 190 |
and |
| 191 |
.BR munmap (2). |