Debian Codegraph @

doc/cap_launch.3

raw
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).