• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
2  * Use of this source code is governed by a BSD-style license that can be
3  * found in the LICENSE file.
4  */
5 
6 /*
7  * The general pattern of use here:
8  * 1) Construct a minijail with minijail_new()
9  * 2) Apply the desired restrictions to it
10  * 3) Enter it, which locks the current process inside it, or:
11  * 3) Run a process inside it
12  * 4) Destroy it.
13  */
14 
15 #ifndef _LIBMINIJAIL_H_
16 #define _LIBMINIJAIL_H_
17 
18 #include <stdint.h>
19 #include <sys/resource.h>
20 #include <sys/types.h>
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26 enum {
27 	MINIJAIL_ERR_PRELOAD = 252,
28 	MINIJAIL_ERR_JAIL = 253,
29 	MINIJAIL_ERR_INIT = 254,
30 };
31 
32 struct minijail;
33 struct sock_fprog;
34 
35 /*
36  * A hook that can be used to execute code at various events during minijail
37  * setup in the forked process. These can only be used if the jailed process is
38  * not going to be invoked with LD_PRELOAD.
39  *
40  * If the return value is non-zero, it will be interpreted as -errno and the
41  * process will abort.
42  */
43 typedef int (*minijail_hook_t)(void *context);
44 
45 /*
46  * The events during minijail setup in which hooks can run. All the events are
47  * run in the new process.
48  */
49 typedef enum {
50 	/* The hook will run just before dropping capabilities. */
51 	MINIJAIL_HOOK_EVENT_PRE_DROP_CAPS,
52 
53 	/* The hook will run just before calling execve(2). */
54 	MINIJAIL_HOOK_EVENT_PRE_EXECVE,
55 
56 	/* The hook will run just before calling chroot(2) / pivot_root(2). */
57 	MINIJAIL_HOOK_EVENT_PRE_CHROOT,
58 
59 	/* Sentinel for error checking. Must be last. */
60 	MINIJAIL_HOOK_EVENT_MAX,
61 } minijail_hook_event_t;
62 
63 /* Allocates a new minijail with no restrictions. */
64 struct minijail *minijail_new(void);
65 
66 /*
67  * These functions add restrictions to the minijail. They are not applied until
68  * minijail_enter() is called. See the documentation in minijail0.1 for
69  * explanations in detail of what the restrictions do.
70  */
71 void minijail_change_uid(struct minijail *j, uid_t uid);
72 void minijail_change_gid(struct minijail *j, gid_t gid);
73 /* Copies |list|. */
74 void minijail_set_supplementary_gids(struct minijail *j, size_t size,
75 				     const gid_t *list);
76 void minijail_keep_supplementary_gids(struct minijail *j);
77 /* Stores user to change to and copies |user| for internal consistency. */
78 int minijail_change_user(struct minijail *j, const char *user);
79 /* Does not take ownership of |group|. */
80 int minijail_change_group(struct minijail *j, const char *group);
81 void minijail_use_seccomp(struct minijail *j);
82 void minijail_no_new_privs(struct minijail *j);
83 void minijail_use_seccomp_filter(struct minijail *j);
84 void minijail_set_seccomp_filter_tsync(struct minijail *j);
85 /* Does not take ownership of |filter|. */
86 void minijail_set_seccomp_filters(struct minijail *j,
87 				  const struct sock_fprog *filter);
88 void minijail_parse_seccomp_filters(struct minijail *j, const char *path);
89 void minijail_parse_seccomp_filters_from_fd(struct minijail *j, int fd);
90 void minijail_log_seccomp_filter_failures(struct minijail *j);
91 /* 'minijail_use_caps' and 'minijail_capbset_drop' are mutually exclusive. */
92 void minijail_use_caps(struct minijail *j, uint64_t capmask);
93 void minijail_capbset_drop(struct minijail *j, uint64_t capmask);
94 /* 'minijail_set_ambient_caps' requires 'minijail_use_caps'. */
95 void minijail_set_ambient_caps(struct minijail *j);
96 void minijail_reset_signal_mask(struct minijail *j);
97 void minijail_reset_signal_handlers(struct minijail *j);
98 void minijail_namespace_vfs(struct minijail *j);
99 void minijail_namespace_enter_vfs(struct minijail *j, const char *ns_path);
100 void minijail_new_session_keyring(struct minijail *j);
101 void minijail_skip_setting_securebits(struct minijail *j,
102 				      uint64_t securebits_skip_mask);
103 
104 /*
105  * This option is *dangerous* as it negates most of the functionality of
106  * minijail_namespace_vfs(). You very likely don't need this.
107  */
108 void minijail_skip_remount_private(struct minijail *j);
109 void minijail_remount_mode(struct minijail *j, unsigned long mode);
110 void minijail_namespace_ipc(struct minijail *j);
111 void minijail_namespace_uts(struct minijail *j);
112 int minijail_namespace_set_hostname(struct minijail *j, const char *name);
113 void minijail_namespace_net(struct minijail *j);
114 void minijail_namespace_enter_net(struct minijail *j, const char *ns_path);
115 void minijail_namespace_cgroups(struct minijail *j);
116 /* Closes all open file descriptors after forking. */
117 void minijail_close_open_fds(struct minijail *j);
118 /*
119  * Implies namespace_vfs and remount_proc_readonly.
120  * WARNING: this is NOT THREAD SAFE. See the block comment in </libminijail.c>.
121  */
122 void minijail_namespace_pids(struct minijail *j);
123 /*
124  * Implies namespace_vfs.
125  * WARNING: this is NOT THREAD SAFE. See the block comment in </libminijail.c>.
126  * Minijail will by default remount /proc read-only when using a PID namespace.
127  * Certain complex applications expect to be able to do their own sandboxing
128  * which might require writing to /proc, so support a weaker version of PID
129  * namespacing with a RW /proc.
130  */
131 void minijail_namespace_pids_rw_proc(struct minijail *j);
132 void minijail_namespace_user(struct minijail *j);
133 void minijail_namespace_user_disable_setgroups(struct minijail *j);
134 int minijail_uidmap(struct minijail *j, const char *uidmap);
135 int minijail_gidmap(struct minijail *j, const char *gidmap);
136 void minijail_remount_proc_readonly(struct minijail *j);
137 void minijail_run_as_init(struct minijail *j);
138 int minijail_write_pid_file(struct minijail *j, const char *path);
139 void minijail_inherit_usergroups(struct minijail *j);
140 /*
141  * Changes the jailed process's syscall table to the alt_syscall table
142  * named |table|.
143  */
144 int minijail_use_alt_syscall(struct minijail *j, const char *table);
145 
146 /* Sets the given runtime limit. See getrlimit(2). */
147 int minijail_rlimit(struct minijail *j, int type, rlim_t cur, rlim_t max);
148 
149 /*
150  * Adds the jailed process to the cgroup given by |path|.  |path| should be the
151  * full path to the cgroups "tasks" file.
152  * Example: /sys/fs/cgroup/cpu/jailed_procs/tasks adds to the "jailed_procs" cpu
153  * cgroup.
154  */
155 int minijail_add_to_cgroup(struct minijail *j, const char *path);
156 
157 /*
158  * Install signal handlers in the minijail process that forward received
159  * signals to the jailed child process.
160  */
161 int minijail_forward_signals(struct minijail *j);
162 
163 /*
164  * minijail_enter_chroot: enables chroot() restriction for @j
165  * @j   minijail to apply restriction to
166  * @dir directory to chroot() to. Owned by caller.
167  *
168  * Enters @dir, binding all bind mounts specified with minijail_bind() into
169  * place. Requires @dir to contain all necessary directories for bind mounts
170  * (i.e., if you have requested a bind mount at /etc, /etc must exist in @dir.)
171  *
172  * Returns 0 on success.
173  */
174 int minijail_enter_chroot(struct minijail *j, const char *dir);
175 int minijail_enter_pivot_root(struct minijail *j, const char *dir);
176 
177 /*
178  * minijail_get_original_path: returns the path of a given file outside of the
179  * chroot.
180  * @j           minijail to obtain the path from.
181  * @chroot_path path inside of the chroot() to.
182  *
183  * When executing a binary in a chroot or pivot_root, return path to the binary
184  * outside of the chroot.
185  *
186  * Returns a string containing the path.  This must be freed by the caller.
187  */
188 char *minijail_get_original_path(struct minijail *j, const char *chroot_path);
189 
190 /*
191  * minijail_mount_tmp: enables mounting of a 64M tmpfs filesystem on /tmp.
192  * As be rules of bind mounts, /tmp must exist in chroot.
193  */
194 void minijail_mount_tmp(struct minijail *j);
195 
196 /*
197  * minijail_mount_tmp_size: enables mounting of a tmpfs filesystem on /tmp.
198  * As be rules of bind mounts, /tmp must exist in chroot.  Size is in bytes.
199  */
200 void minijail_mount_tmp_size(struct minijail *j, size_t size);
201 
202 /*
203  * minijail_mount_dev: enables mounting of a tmpfs filesystem on /dev.
204  * It will then be seeded with a basic set of device nodes.  For the exact
205  * list, consult the minijail(0) man page.
206  */
207 void minijail_mount_dev(struct minijail *j);
208 
209 /*
210  * minijail_mount_with_data: when entering minijail @j,
211  *   mounts @src at @dst with @flags and @data.
212  * @j         minijail to bind inside
213  * @src       source to bind
214  * @dest      location to bind (inside chroot)
215  * @type      type of filesystem
216  * @flags     flags passed to mount
217  * @data      data arguments passed to mount(2), e.g. "mode=755"
218  *
219  * This may be called multiple times; all mounts will be applied in the order
220  * of minijail_mount() calls.
221  * If @flags is 0, then MS_NODEV | MS_NOEXEC | MS_NOSUID will be used instead.
222  * If @data is NULL or "", and @type is tmpfs, then "mode=0755,size=10M" will
223  * be used instead.
224  */
225 int minijail_mount_with_data(struct minijail *j, const char *src,
226 			     const char *dest, const char *type,
227 			     unsigned long flags, const char *data);
228 
229 /*
230  * minijail_mount: when entering minijail @j, mounts @src at @dst with @flags
231  * @j         minijail to bind inside
232  * @src       source to bind
233  * @dest      location to bind (inside chroot)
234  * @type      type of filesystem
235  * @flags     flags passed to mount
236  *
237  * This may be called multiple times; all mounts will be applied in the order
238  * of minijail_mount() calls.
239  */
240 int minijail_mount(struct minijail *j, const char *src, const char *dest,
241 		   const char *type, unsigned long flags);
242 
243 /*
244  * minijail_bind: bind-mounts @src into @j as @dest, optionally writeable
245  * @j         minijail to bind inside
246  * @src       source to bind
247  * @dest      location to bind (inside chroot)
248  * @writeable 1 if the bind mount should be writeable
249  *
250  * This may be called multiple times; all bindings will be applied in the order
251  * of minijail_bind() calls.
252  */
253 int minijail_bind(struct minijail *j, const char *src, const char *dest,
254 		  int writeable);
255 
256 /*
257  * minijail_add_hook: adds @hook to the list of hooks that will be
258  * invoked when @event is reached during minijail setup. The caller is
259  * responsible for the lifetime of @payload.
260  * @j         minijail to add the hook to
261  * @hook      the function that will be invoked
262  * @payload   an opaque pointer
263  * @event     the event that will trigger the hook
264  */
265 int minijail_add_hook(struct minijail *j,
266 		      minijail_hook_t hook, void *payload,
267 		      minijail_hook_event_t event);
268 
269 /*
270  * minijail_preserve_fd: preserves @parent_fd and makes it available as
271  * @child_fd in the child process. @parent_fd will be closed if no other
272  * redirect has claimed it as a @child_fd.  This works even if
273  * minijail_close_open_fds() is invoked.
274  * @j         minijail to add the fd to
275  * @parent_fd the fd in the parent process
276  * @child_fd  the fd that will be available in the child process
277  */
278 int minijail_preserve_fd(struct minijail *j, int parent_fd, int child_fd);
279 
280 /*
281  * minijail_set_preload_path: overrides the default path for
282  * libminijailpreload.so.
283  */
284 int minijail_set_preload_path(struct minijail *j, const char *preload_path);
285 
286 /*
287  * Lock this process into the given minijail. Note that this procedure cannot
288  * fail, since there is no way to undo privilege-dropping; therefore, if any
289  * part of the privilege-drop fails, minijail_enter() will abort the entire
290  * process.
291  *
292  * Some restrictions cannot be enabled this way (pid namespaces) and attempting
293  * to do so will cause an abort.
294  */
295 void minijail_enter(const struct minijail *j);
296 
297 /*
298  * Run the specified command in the given minijail, execve(2)-style.
299  * If minijail_namespace_pids() or minijail_namespace_user() are used,
300  * this or minijail_fork() is required instead of minijail_enter().
301  */
302 int minijail_run(struct minijail *j, const char *filename,
303 		 char *const argv[]);
304 
305 /*
306  * Run the specified command in the given minijail, execve(2)-style.
307  * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing
308  * static binaries, or on systems without support for LD_PRELOAD.
309  */
310 int minijail_run_no_preload(struct minijail *j, const char *filename,
311 			    char *const argv[]);
312 
313 /*
314  * Run the specified command in the given minijail, execve(2)-style.
315  * Update |*pchild_pid| with the pid of the child.
316  */
317 int minijail_run_pid(struct minijail *j, const char *filename,
318 		     char *const argv[], pid_t *pchild_pid);
319 
320 /*
321  * Run the specified command in the given minijail, execve(2)-style.
322  * Update |*pstdin_fd| with a fd that allows writing to the child's
323  * standard input.
324  */
325 int minijail_run_pipe(struct minijail *j, const char *filename,
326 		      char *const argv[], int *pstdin_fd);
327 
328 /*
329  * Run the specified command in the given minijail, execve(2)-style.
330  * Update |*pchild_pid| with the pid of the child.
331  * Update |*pstdin_fd| with a fd that allows writing to the child's
332  * standard input.
333  * Update |*pstdout_fd| with a fd that allows reading from the child's
334  * standard output.
335  * Update |*pstderr_fd| with a fd that allows reading from the child's
336  * standard error.
337  */
338 int minijail_run_pid_pipes(struct minijail *j, const char *filename,
339 			   char *const argv[], pid_t *pchild_pid,
340 			   int *pstdin_fd, int *pstdout_fd, int *pstderr_fd);
341 
342 /*
343  * Run the specified command in the given minijail, execve(2)-style.
344  * Update |*pchild_pid| with the pid of the child.
345  * Update |*pstdin_fd| with a fd that allows writing to the child's
346  * standard input.
347  * Update |*pstdout_fd| with a fd that allows reading from the child's
348  * standard output.
349  * Update |*pstderr_fd| with a fd that allows reading from the child's
350  * standard error.
351  * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing
352  * static binaries, or on systems without support for LD_PRELOAD.
353  */
354 int minijail_run_pid_pipes_no_preload(struct minijail *j, const char *filename,
355 				      char *const argv[], pid_t *pchild_pid,
356 				      int *pstdin_fd, int *pstdout_fd,
357 				      int *pstderr_fd);
358 
359 /*
360  * Run the specified command in the given minijail, execve(2)-style.
361  * Pass |envp| as the full environment for the child.
362  * Update |*pchild_pid| with the pid of the child.
363  * Update |*pstdin_fd| with a fd that allows writing to the child's
364  * standard input.
365  * Update |*pstdout_fd| with a fd that allows reading from the child's
366  * standard output.
367  * Update |*pstderr_fd| with a fd that allows reading from the child's
368  * standard error.
369  * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing
370  * static binaries, or on systems without support for LD_PRELOAD.
371  */
372 int minijail_run_env_pid_pipes_no_preload(struct minijail *j,
373 					  const char *filename,
374 					  char *const argv[],
375 					  char *const envp[], pid_t *pchild_pid,
376 					  int *pstdin_fd, int *pstdout_fd,
377 					  int *pstderr_fd);
378 
379 /*
380  * Fork, jail the child, and return. This behaves similar to fork(2), except it
381  * puts the child process in a jail before returning.
382  * `minijail_fork` returns in both the parent and the child. The pid of the
383  * child is returned to the parent. Zero is returned in the child. LD_PRELOAD
384  * is not supported.
385  * If minijail_namespace_pids() or minijail_namespace_user() are used,
386  * this or minijail_run*() is required instead of minijail_enter().
387  */
388 pid_t minijail_fork(struct minijail *j);
389 
390 /*
391  * Kill the specified minijail. The minijail must have been created with pid
392  * namespacing; if it was, all processes inside it are atomically killed.
393  */
394 int minijail_kill(struct minijail *j);
395 
396 /*
397  * Wait for all processes in the specified minijail to exit. Returns the exit
398  * status of the _first_ process spawned in the jail.
399  */
400 int minijail_wait(struct minijail *j);
401 
402 /*
403  * Frees the given minijail. It does not matter if the process is inside the
404  * minijail or not.
405  */
406 void minijail_destroy(struct minijail *j);
407 
408 /*
409  * minijail_log_to_fd: redirects the module-wide logging to an FD instead of
410  * syslog.
411  * @fd           FD to log to. Caller must ensure this is available after
412  *               jailing (e.g. with minijail_preserve_fd()).
413  * @min_priority the minimum logging priority. Same as the priority argument
414  *               to syslog(2).
415  */
416 void minijail_log_to_fd(int fd, int min_priority);
417 
418 #ifdef __cplusplus
419 }; /* extern "C" */
420 #endif
421 
422 #endif /* !_LIBMINIJAIL_H_ */
423