1CAP_GET_PROC(3) Linux Programmer's Manual CAP_GET_PROC(3)
2
6 cap_get_proc, cap_set_proc, capgetp, cap_get_bound, cap_drop_bound,
7 cap_get_ambient, cap_set_ambient, cap_reset_ambient, cap_get_secbits,
8 cap_set_secbits, cap_get_mode, cap_set_mode, cap_mode_name,
9 cap_get_pid, cap_setuid, cap_setgroups - capability manipulation on
10 processes
11
13 #include <sys/capability.h>
14 cap_t cap_get_proc(void);
16 int cap_set_proc(cap_t cap_p);
18 int cap_get_bound(cap_value_t cap);
20 CAP_IS_SUPPORTED(cap_value_t cap);
22 int cap_drop_bound(cap_value_t cap);
24 int cap_get_ambient(cap_value_t cap);
26 int cap_set_ambient(cap_value_t cap, cap_flag_value_t value);
28 int cap_reset_ambient(void);
30 CAP_AMBIENT_SUPPORTED();
32 unsigned cap_get_secbits(void);
34 int cap_set_secbits(unsigned bits);
36 cap_mode_t cap_get_mode(void);
38 const char *cap_mode_name(cap_mode_t mode);
40 int cap_set_mode(cap_mode_t mode);
42 #include <sys/types.h>
44 cap_t cap_get_pid(pid_t pid);
46 int cap_setuid(uid_t uid);
48 int cap_setgroups(gid_t gid, size_t ngroups, const gid_t groups);
50 Link with -lcap.
52
54 cap_get_proc() allocates a capability state in working storage, sets
55 its state to that of the calling process, and returns a pointer to this
56 newly created capability state. The caller should free any releasable
57 memory, when the capability state in working storage is no longer
58 required, by calling cap_free() with the cap_t as an argument.
59 cap_set_proc() sets the values for all capability flags for all capa‐
61 bilities to the capability state identified by cap_p. The new capabil‐
62 ity state of the process will be completely determined by the contents
63 of cap_p upon successful return from this function. If any flag in
64 cap_p is set for any capability not currently permitted for the calling
65 process, the function will fail, and the capability state of the
66 process will remain unchanged.
67 cap_get_pid() returns cap_t, see cap_init(3), with the process capabil‐
69 ities of the process indicated by pid. (If pid is 0, then the calling
70 process's capabilities are returned.) This information can also be
71 obtained from the /proc/<pid>/status file.
72 cap_get_bound() with a cap as an argument returns the current value of
74 this bounding set capability flag in effect for the calling process.
75 This operation is unprivileged. Note, a macro function CAP_IS_SUP‐
76 PORTED(cap_value_t cap) is provided that evaluates to true (1) if the
77 system supports the specified capability, cap. If the system does not
78 support the capability, this function returns 0. This macro works by
79 testing for an error condition with cap_get_bound().
80 cap_drop_bound() can be used to lower the specified bounding set capa‐
82 bility, cap. To complete successfully, the prevailing effective capa‐
83 bility set must have a raised CAP_SETPCAP.
84 cap_get_ambient() returns the prevailing value of the specified ambient
86 capability, or -1 if the capability is not supported by the running
87 kernel. A macro CAP_AMBIENT_SUPPORTED() uses this function to deter‐
88 mine if ambient capabilities are supported by the kernel.
89 cap_set_ambient() sets the specified ambient capability to a specific
91 value. To complete successfully, the prevailing effective capability
92 set must have a raised CAP_SETPCAP. Further, to raise a specific ambi‐
93 ent capability the inheritable and permitted sets of the calling
94 process must contain the specified capability, and raised ambient bits
95 will only be retained as long as this remains true.
96 cap_reset_ambient() resets all of the ambient capabilities for the
98 calling process to their lowered value. To complete successfully, the
99 prevailing effective capability set must have a raised CAP_SETPCAP.
100 Note, the ambient set is intended to operate in a legacy environment
101 where the application has limited awareness of capabilities in general.
102 Executing a file with associated filesystem capabilities, the kernel
103 will implicitly reset the ambient set of the process. Also, changes to
104 the inheritable set by the program code without explicitly fixing up
105 the ambient set can also drop ambient bits.
106 cap_get_secbits() returns the securebits of the calling process. These
108 bits affect the way in which the calling process implements things like
109 setuid-root fixup and ambient capabilities.
110 cap_set_secbits() attempts to modify the securebits of the calling
112 process. Note CAP_SETPCAP must be in the effective capability set for
113 this to be effective. Some settings lock the sub-states of the
114 securebits, so attempts to set values may be denied by the kernel even
115 when the CAP_SETPCAP capability is raised.
116 To help manage the complexity of the securebits, libcap provides a com‐
118 bined securebit and capability set concept called a libcap mode.
119 cap_get_mode() attempts to summarize the prevailing security environ‐
120 ment in the form of a numerical cap_mode_t value. A text representation
121 of the mode can be obtained via the cap_mode_name() function. The vast
122 majority of combinations of these values are not well defined in terms
123 of a libcap mode, and for these states cap_get_mode() returns
124 (cap_mode_t)0 which cap_get_name() identifies as ``UNCERTAIN''. Sup‐
125 ported modes are: CAP_MODE_NOPRIV, CAP_MODE_PURE1E_INIT and
126 CAP_MODE_PURE1E.
127 cap_set_mode() can be used to set the desired mode. The permitted capa‐
129 bility CAP_SETPCAP is required for this function to succeed.
130 cap_setuid() is a convenience function for the setuid(2) system call.
132 Where cap_setuid() arranges for the right effective capability to be
133 raised in order to perform the system call, and also arranges to pre‐
134 serve the availability of permitted capabilities after the uid has
135 changed. Following this call all effective capabilities are lowered.
136 cap_setgroups() is a convenience function for performing both setgid(2)
138 and setgroups(2) calls in one call. The cap_setgroups() call raises the
139 right effective capability for the duration of the call, and empties
140 the effective capability set before returning.
141
143 The functions cap_get_proc() and cap_get_pid() return a non-NULL value
144 on success, and NULL on failure.
145 The function cap_get_bound() returns -1 if the requested capability is
147 unknown, otherwise the return value reflects the current state of that
148 capability in the prevailing bounding set. Note, a macro function,
149 The all of the setting functions such as cap_set_proc() and
151 cap_drop_bound() return zero for success, and -1 on failure.
152 On failure, errno is set to EINVAL, EPERM, or ENOMEM.
154
156 cap_set_proc() and cap_get_proc() are specified in the withdrawn
157 POSIX.1e draft specification. cap_get_pid() is a Linux extension.
158
160 Neither glibc, nor the Linux kernel honors POSIX semantics for setting
161 capabilities and securebits in the presence of pthreads. That is,
162 changing capability sets, by default, only affect the running thread.
163 To be meaningfully secure, however, the capability sets should be mir‐
164 rored by all threads within a common program because threads are not
165 memory isolated. As a workaround for this, libcap is packaged with a
166 separate POSIX semantics system call library: libpsx. If your program
167 uses POSIX threads, to achieve meaningful POSIX semantics capability
168 manipulation, you should link your program with:
169 ld ... -lcap -lpsx -lpthread --wrap=pthread_create
171 or,
173 gcc ... -lcap -lpsx -lpthread -Wl,-wrap,pthread_create
175 When linked this way, due to linker magic, libcap uses psx_syscall(3)
177 and psx_syscall6(3) to perform state setting system calls.
178 capgetp() and capsetp()
180 The library also supports the deprecated functions:
181 int capgetp(pid_t pid, cap_t cap_d);
183 int capsetp(pid_t pid, cap_t cap_d);
185 capgetp() attempts to obtain the capabilities of some other process;
187 storing the capabilities in a pre-allocated cap_d. See cap_init() for
188 information on allocating an empty capability set. This function is
189 deprecated; you should use cap_get_pid().
190 capsetp() attempts to set the capabilities of the calling porcess or of
192 some other process(es), pid. Note that setting capabilities of another
193 process is only possible on older kernels that do not provide VFS sup‐
194 port for setting file capabilities. See capset(2) for information on
195 which kernels provide such support.
196 If pid is positive it refers to a specific process; if it is zero, it
198 refers to the calling process; -1 refers to all processes other than
199 the calling process and process '1' (typically init(8)); other negative
200 values refer to the -pid process group.
201 In order to use this function, the kernel must support it and the call‐
203 ing process must have CAP_SETPCAP raised in its Effective capability
204 set. The capabilities set in the target process(es) are those contained
205 in cap_d.
206 Kernels that support filesystem capabilities redefine the semantics of
208 CAP_SETPCAP and on such systems, capsetp() will always fail for any
209 target not equal to the calling process. capsetp() returns zero for
210 success, and -1 on failure.
211 On kernels where it is (was) supported, capsetp() should be used with
213 care. It existed, primarily, to overcome an early lack of support for
214 capabilities in the filesystems supported by Linux. Note that on older
215 kernels where capsetp() could be used to set the capabilities of
216 another process, the only processes that had CAP_SETPCAP available to
217 them by default were processes started as kernel threads. (Typically
218 this includes init(8), kflushd and kswapd.) A kernel recompilation was
219 needed to modify this default.
220
222 The code segment below raises the CAP_FOWNER and CAP_SETFCAP effective
223 capabilities for the caller:
224 ...
226 cap_t caps;
227 const cap_value_t cap_list[2] = {CAP_FOWNER, CAP_SETFCAP};
228 if (!CAP_IS_SUPPORTED(CAP_SETFCAP))
230 /* handle error */
231 caps = cap_get_proc();
233 if (caps == NULL)
234 /* handle error */;
235 if (cap_set_flag(caps, CAP_EFFECTIVE, 2, cap_list, CAP_SET) == -1)
237 /* handle error */;
238 if (cap_set_proc(caps) == -1)
240 /* handle error */;
241 if (cap_free(caps) == -1)
243 /* handle error */;
244 ...
245 Alternatively, to completely drop privilege in a program launched
247 setuid-root but wanting to run as a specific user ID etc. in such a way
248 that neither it, nor any of its children can acquire privilege again:
249 ...
251 uid_t nobody = 65534;
252 const gid_t groups[] = {65534};
253 if (cap_setgroups(groups[0], 1, groups) != 0)
255 /* handle error */;
256 if (cap_setuid(nobody) != 0)
257 /* handle error */;
258 /*
260 * privilege is still available here
261 */
262 if (cap_set_mode(CAP_MODE_NOPRIV) != 0)
264 /* handle error */
265 ...
266 Note, the above sequence can be performed by the capsh tool as follows:
268 sudo /sbin/capsh --user=nobody --mode=NOPRIV --print
270 where --print displays the resulting privilege state.
272
274 libcap(3), libpsx(3), capsh(1), cap_clear(3), cap_copy_ext(3),
275 cap_from_text(3), cap_get_file(3), cap_init(3), psx_syscall(3), capa‐
276 bilities(7).
277 2019-12-21 CAP_GET_PROC(3)