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 /* 23 * Rust's bindgen needs the actual definition of sock_fprog in order to 24 * generate usable bindings. 25 */ 26 #ifdef USE_BINDGEN 27 #include <linux/filter.h> 28 #endif 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /* Possible exit status codes returned by minijail_wait(). */ 35 enum { 36 /* Command can be found but cannot be run */ 37 MINIJAIL_ERR_NO_ACCESS = 126, 38 39 /* Command cannot be found */ 40 MINIJAIL_ERR_NO_COMMAND = 127, 41 42 /* (MINIJAIL_ERR_SIG_BASE + n) if process killed by signal n != SIGSYS */ 43 MINIJAIL_ERR_SIG_BASE = 128, 44 45 /* Cannot mount a file or folder in mount namespace */ 46 MINIJAIL_ERR_MOUNT = 251, 47 48 MINIJAIL_ERR_PRELOAD = 252, 49 50 /* Process killed by SIGSYS */ 51 MINIJAIL_ERR_JAIL = 253, 52 53 MINIJAIL_ERR_INIT = 254, 54 }; 55 56 struct minijail; 57 struct sock_fprog; 58 59 /* 60 * A hook that can be used to execute code at various events during minijail 61 * setup in the forked process. These can only be used if the jailed process is 62 * not going to be invoked with LD_PRELOAD. 63 * 64 * If the return value is non-zero, it will be interpreted as -errno and the 65 * process will abort. 66 */ 67 typedef int (*minijail_hook_t)(void *context); 68 69 /* 70 * The events during minijail setup in which hooks can run. All the events are 71 * run in the new process. 72 */ 73 typedef enum { 74 /* The hook will run just before dropping capabilities. */ 75 MINIJAIL_HOOK_EVENT_PRE_DROP_CAPS, 76 77 /* The hook will run just before calling execve(2). */ 78 MINIJAIL_HOOK_EVENT_PRE_EXECVE, 79 80 /* The hook will run just before calling chroot(2) / pivot_root(2). */ 81 MINIJAIL_HOOK_EVENT_PRE_CHROOT, 82 83 /* Sentinel for error checking. Must be last. */ 84 MINIJAIL_HOOK_EVENT_MAX, 85 } minijail_hook_event_t; 86 87 /* Allocates a new minijail with no restrictions. */ 88 struct minijail *minijail_new(void); 89 90 /* 91 * These functions add restrictions to the minijail. They are not applied until 92 * minijail_enter() is called. See the documentation in minijail0.1 for 93 * explanations in detail of what the restrictions do. 94 */ 95 void minijail_change_uid(struct minijail *j, uid_t uid); 96 void minijail_change_gid(struct minijail *j, gid_t gid); 97 /* Copies |list|. */ 98 void minijail_set_supplementary_gids(struct minijail *j, size_t size, 99 const gid_t *list); 100 void minijail_keep_supplementary_gids(struct minijail *j); 101 /* Stores user to change to and copies |user| for internal consistency. */ 102 int minijail_change_user(struct minijail *j, const char *user); 103 /* Does not take ownership of |group|. */ 104 int minijail_change_group(struct minijail *j, const char *group); 105 void minijail_use_seccomp(struct minijail *j); 106 void minijail_no_new_privs(struct minijail *j); 107 void minijail_use_seccomp_filter(struct minijail *j); 108 void minijail_set_seccomp_filter_tsync(struct minijail *j); 109 /* 110 * Allow speculative execution features that may cause data leaks across 111 * processes, by setting the SECCOMP_FILTER_FLAG_SPEC_ALLOW seccomp flag. 112 * 113 * WARNING: Enabling this may make the process vulnerable to speculative 114 * execution attacks (Branch Target Injection, and Speculative Store Bypass). 115 * This is only safe to use for processes that do not execute untrusted code. 116 */ 117 void minijail_set_seccomp_filter_allow_speculation(struct minijail *j); 118 /* Does not take ownership of |filter|. */ 119 void minijail_set_seccomp_filters(struct minijail *j, 120 const struct sock_fprog *filter); 121 void minijail_parse_seccomp_filters(struct minijail *j, const char *path); 122 void minijail_parse_seccomp_filters_from_fd(struct minijail *j, int fd); 123 void minijail_log_seccomp_filter_failures(struct minijail *j); 124 /* 'minijail_use_caps' and 'minijail_capbset_drop' are mutually exclusive. */ 125 void minijail_use_caps(struct minijail *j, uint64_t capmask); 126 void minijail_capbset_drop(struct minijail *j, uint64_t capmask); 127 /* 'minijail_set_ambient_caps' requires 'minijail_use_caps'. */ 128 void minijail_set_ambient_caps(struct minijail *j); 129 void minijail_reset_signal_mask(struct minijail *j); 130 void minijail_reset_signal_handlers(struct minijail *j); 131 void minijail_namespace_vfs(struct minijail *j); 132 void minijail_namespace_enter_vfs(struct minijail *j, const char *ns_path); 133 void minijail_new_session_keyring(struct minijail *j); 134 void minijail_skip_setting_securebits(struct minijail *j, 135 uint64_t securebits_skip_mask); 136 137 /* 138 * This option is *dangerous* as it negates most of the functionality of 139 * minijail_namespace_vfs(). You very likely don't need this. 140 */ 141 void minijail_skip_remount_private(struct minijail *j); 142 void minijail_remount_mode(struct minijail *j, unsigned long mode); 143 void minijail_namespace_ipc(struct minijail *j); 144 void minijail_namespace_uts(struct minijail *j); 145 int minijail_namespace_set_hostname(struct minijail *j, const char *name); 146 void minijail_namespace_net(struct minijail *j); 147 void minijail_namespace_enter_net(struct minijail *j, const char *ns_path); 148 void minijail_namespace_cgroups(struct minijail *j); 149 /* Closes all open file descriptors after forking. */ 150 void minijail_close_open_fds(struct minijail *j); 151 /* 152 * Implies namespace_vfs and remount_proc_readonly. 153 * WARNING: this is NOT THREAD SAFE. See the block comment in </libminijail.c>. 154 */ 155 void minijail_namespace_pids(struct minijail *j); 156 /* 157 * Implies namespace_vfs. 158 * WARNING: this is NOT THREAD SAFE. See the block comment in </libminijail.c>. 159 * Minijail will by default remount /proc read-only when using a PID namespace. 160 * Certain complex applications expect to be able to do their own sandboxing 161 * which might require writing to /proc, so support a weaker version of PID 162 * namespacing with a RW /proc. 163 */ 164 void minijail_namespace_pids_rw_proc(struct minijail *j); 165 void minijail_namespace_user(struct minijail *j); 166 void minijail_namespace_user_disable_setgroups(struct minijail *j); 167 int minijail_uidmap(struct minijail *j, const char *uidmap); 168 int minijail_gidmap(struct minijail *j, const char *gidmap); 169 void minijail_remount_proc_readonly(struct minijail *j); 170 void minijail_run_as_init(struct minijail *j); 171 int minijail_write_pid_file(struct minijail *j, const char *path); 172 void minijail_inherit_usergroups(struct minijail *j); 173 /* 174 * Changes the jailed process's syscall table to the alt_syscall table 175 * named |table|. 176 */ 177 int minijail_use_alt_syscall(struct minijail *j, const char *table); 178 179 /* Sets the given runtime limit. See getrlimit(2). */ 180 int minijail_rlimit(struct minijail *j, int type, rlim_t cur, rlim_t max); 181 182 /* 183 * Adds the jailed process to the cgroup given by |path|. |path| should be the 184 * full path to the cgroups "tasks" file. 185 * Example: /sys/fs/cgroup/cpu/jailed_procs/tasks adds to the "jailed_procs" cpu 186 * cgroup. 187 */ 188 int minijail_add_to_cgroup(struct minijail *j, const char *path); 189 190 /* 191 * Install signal handlers in the minijail process that forward received 192 * signals to the jailed child process. 193 */ 194 int minijail_forward_signals(struct minijail *j); 195 196 /* The jailed child process should call setsid() to create a new session. */ 197 int minijail_create_session(struct minijail *j); 198 199 /* 200 * minijail_enter_chroot: enables chroot() restriction for @j 201 * @j minijail to apply restriction to 202 * @dir directory to chroot() to. Owned by caller. 203 * 204 * Enters @dir, binding all bind mounts specified with minijail_bind() into 205 * place. Requires @dir to contain all necessary directories for bind mounts 206 * (i.e., if you have requested a bind mount at /etc, /etc must exist in @dir.) 207 * 208 * Returns 0 on success. 209 */ 210 int minijail_enter_chroot(struct minijail *j, const char *dir); 211 int minijail_enter_pivot_root(struct minijail *j, const char *dir); 212 213 /* 214 * minijail_get_original_path: returns the path of a given file outside of the 215 * chroot. 216 * @j minijail to obtain the path from. 217 * @chroot_path path inside of the chroot() to. 218 * 219 * When executing a binary in a chroot or pivot_root, return path to the binary 220 * outside of the chroot. 221 * 222 * Returns a string containing the path. This must be freed by the caller. 223 */ 224 char *minijail_get_original_path(struct minijail *j, const char *chroot_path); 225 226 /* 227 * minijail_mount_tmp: enables mounting of a 64M tmpfs filesystem on /tmp. 228 * As be rules of bind mounts, /tmp must exist in chroot. 229 */ 230 void minijail_mount_tmp(struct minijail *j); 231 232 /* 233 * minijail_mount_tmp_size: enables mounting of a tmpfs filesystem on /tmp. 234 * As be rules of bind mounts, /tmp must exist in chroot. Size is in bytes. 235 */ 236 void minijail_mount_tmp_size(struct minijail *j, size_t size); 237 238 /* 239 * minijail_mount_dev: enables mounting of a tmpfs filesystem on /dev. 240 * It will then be seeded with a basic set of device nodes. For the exact 241 * list, consult the minijail(0) man page. 242 */ 243 void minijail_mount_dev(struct minijail *j); 244 245 /* 246 * minijail_mount_with_data: when entering minijail @j, 247 * mounts @src at @dst with @flags and @data. 248 * @j minijail to bind inside 249 * @src source to bind 250 * @dest location to bind (inside chroot) 251 * @type type of filesystem 252 * @flags flags passed to mount 253 * @data data arguments passed to mount(2), e.g. "mode=755" 254 * 255 * This may be called multiple times; all mounts will be applied in the order 256 * of minijail_mount() calls. 257 * If @flags is 0, then MS_NODEV | MS_NOEXEC | MS_NOSUID will be used instead. 258 * If @data is NULL or "", and @type is tmpfs, then "mode=0755,size=10M" will 259 * be used instead. 260 */ 261 int minijail_mount_with_data(struct minijail *j, const char *src, 262 const char *dest, const char *type, 263 unsigned long flags, const char *data); 264 265 /* 266 * minijail_mount: when entering minijail @j, mounts @src at @dst with @flags 267 * @j minijail to bind inside 268 * @src source to bind 269 * @dest location to bind (inside chroot) 270 * @type type of filesystem 271 * @flags flags passed to mount 272 * 273 * This may be called multiple times; all mounts will be applied in the order 274 * of minijail_mount() calls. 275 */ 276 int minijail_mount(struct minijail *j, const char *src, const char *dest, 277 const char *type, unsigned long flags); 278 279 /* 280 * minijail_bind: bind-mounts @src into @j as @dest, optionally writeable 281 * @j minijail to bind inside 282 * @src source to bind 283 * @dest location to bind (inside chroot) 284 * @writeable 1 if the bind mount should be writeable 285 * 286 * This may be called multiple times; all bindings will be applied in the order 287 * of minijail_bind() calls. 288 */ 289 int minijail_bind(struct minijail *j, const char *src, const char *dest, 290 int writeable); 291 292 /* 293 * minijail_add_remount: when entering minijail @j, remounts @mount_name and all 294 * subdirectories as @remount_mode rather than the default MS_PRIVATE 295 * @j minijail to bind inside 296 * @mount_name mount to remount 297 * @remount_mode remount mode to use 298 * 299 * This may be called multiple times; this overrides |j->remount_mode| for the 300 * given mount. 301 */ 302 int minijail_add_remount(struct minijail *j, const char *mount_name, 303 unsigned long remount_mode); 304 /* 305 * minijail_add_hook: adds @hook to the list of hooks that will be 306 * invoked when @event is reached during minijail setup. The caller is 307 * responsible for the lifetime of @payload. 308 * @j minijail to add the hook to 309 * @hook the function that will be invoked 310 * @payload an opaque pointer 311 * @event the event that will trigger the hook 312 */ 313 int minijail_add_hook(struct minijail *j, 314 minijail_hook_t hook, void *payload, 315 minijail_hook_event_t event); 316 317 /* 318 * minijail_preserve_fd: preserves @parent_fd and makes it available as 319 * @child_fd in the child process. @parent_fd will be closed if no other 320 * redirect has claimed it as a @child_fd. This works even if 321 * minijail_close_open_fds() is invoked. 322 * @j minijail to add the fd to 323 * @parent_fd the fd in the parent process 324 * @child_fd the fd that will be available in the child process 325 */ 326 int minijail_preserve_fd(struct minijail *j, int parent_fd, int child_fd); 327 328 /* 329 * minijail_set_preload_path: overrides the default path for 330 * libminijailpreload.so. 331 */ 332 int minijail_set_preload_path(struct minijail *j, const char *preload_path); 333 334 /* 335 * Lock this process into the given minijail. Note that this procedure cannot 336 * fail, since there is no way to undo privilege-dropping; therefore, if any 337 * part of the privilege-drop fails, minijail_enter() will abort the entire 338 * process. 339 * 340 * Some restrictions cannot be enabled this way (pid namespaces) and attempting 341 * to do so will cause an abort. 342 */ 343 void minijail_enter(const struct minijail *j); 344 345 /* 346 * Run the specified command in the given minijail, execve(2)-style. 347 * If minijail_namespace_pids() or minijail_namespace_user() are used, 348 * this or minijail_fork() is required instead of minijail_enter(). 349 */ 350 int minijail_run(struct minijail *j, const char *filename, 351 char *const argv[]); 352 353 /* 354 * Run the specified command in the given minijail, execve(2)-style. 355 * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing 356 * static binaries, or on systems without support for LD_PRELOAD. 357 */ 358 int minijail_run_no_preload(struct minijail *j, const char *filename, 359 char *const argv[]); 360 361 /* 362 * Run the specified command in the given minijail, execve(2)-style. 363 * Update |*pchild_pid| with the pid of the child. 364 */ 365 int minijail_run_pid(struct minijail *j, const char *filename, 366 char *const argv[], pid_t *pchild_pid); 367 368 /* 369 * Run the specified command in the given minijail, execve(2)-style. 370 * Update |*pstdin_fd| with a fd that allows writing to the child's 371 * standard input. 372 */ 373 int minijail_run_pipe(struct minijail *j, const char *filename, 374 char *const argv[], int *pstdin_fd); 375 376 /* 377 * Run the specified command in the given minijail, execve(2)-style. 378 * Update |*pchild_pid| with the pid of the child. 379 * Update |*pstdin_fd| with a fd that allows writing to the child's 380 * standard input. 381 * Update |*pstdout_fd| with a fd that allows reading from the child's 382 * standard output. 383 * Update |*pstderr_fd| with a fd that allows reading from the child's 384 * standard error. 385 */ 386 int minijail_run_pid_pipes(struct minijail *j, const char *filename, 387 char *const argv[], pid_t *pchild_pid, 388 int *pstdin_fd, int *pstdout_fd, int *pstderr_fd); 389 390 /* 391 * Run the specified command in the given minijail, execve(2)-style. 392 * Pass |envp| as the full environment for the child. 393 * Update |*pchild_pid| with the pid of the child. 394 * Update |*pstdin_fd| with a fd that allows writing to the child's 395 * standard input. 396 * Update |*pstdout_fd| with a fd that allows reading from the child's 397 * standard output. 398 * Update |*pstderr_fd| with a fd that allows reading from the child's 399 * standard error. 400 */ 401 int minijail_run_env_pid_pipes(struct minijail *j, const char *filename, 402 char *const argv[], char *const envp[], 403 pid_t *pchild_pid, int *pstdin_fd, 404 int *pstdout_fd, int *pstderr_fd); 405 406 /* 407 * Run the specified command in the given minijail, execve(2)-style. 408 * Update |*pchild_pid| with the pid of the child. 409 * Update |*pstdin_fd| with a fd that allows writing to the child's 410 * standard input. 411 * Update |*pstdout_fd| with a fd that allows reading from the child's 412 * standard output. 413 * Update |*pstderr_fd| with a fd that allows reading from the child's 414 * standard error. 415 * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing 416 * static binaries, or on systems without support for LD_PRELOAD. 417 */ 418 int minijail_run_pid_pipes_no_preload(struct minijail *j, const char *filename, 419 char *const argv[], pid_t *pchild_pid, 420 int *pstdin_fd, int *pstdout_fd, 421 int *pstderr_fd); 422 423 /* 424 * Run the specified command in the given minijail, execve(2)-style. 425 * Pass |envp| as the full environment for the child. 426 * Update |*pchild_pid| with the pid of the child. 427 * Update |*pstdin_fd| with a fd that allows writing to the child's 428 * standard input. 429 * Update |*pstdout_fd| with a fd that allows reading from the child's 430 * standard output. 431 * Update |*pstderr_fd| with a fd that allows reading from the child's 432 * standard error. 433 * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing 434 * static binaries, or on systems without support for LD_PRELOAD. 435 */ 436 int minijail_run_env_pid_pipes_no_preload(struct minijail *j, 437 const char *filename, 438 char *const argv[], 439 char *const envp[], pid_t *pchild_pid, 440 int *pstdin_fd, int *pstdout_fd, 441 int *pstderr_fd); 442 443 /* 444 * Fork, jail the child, and return. This behaves similar to fork(2), except it 445 * puts the child process in a jail before returning. 446 * `minijail_fork` returns in both the parent and the child. The pid of the 447 * child is returned to the parent. Zero is returned in the child. LD_PRELOAD 448 * is not supported. 449 * If minijail_namespace_pids() or minijail_namespace_user() are used, 450 * this or minijail_run*() is required instead of minijail_enter(). 451 */ 452 pid_t minijail_fork(struct minijail *j); 453 454 /* 455 * Send SIGTERM to the process in the minijail and wait for it to terminate. 456 * 457 * Return the same nonnegative exit status as minijail_wait(), or a negative 458 * error code (eg -ESRCH if the process has already been waited for). 459 * 460 * This is most useful if the minijail has been created with PID namespacing 461 * since, in this case, all processes inside it are atomically killed. 462 */ 463 int minijail_kill(struct minijail *j); 464 465 /* 466 * Wait for the first process spawned in the specified minijail to exit, and 467 * return its exit status. A process can only be waited once. 468 * 469 * Return: 470 * A negative error code if the process cannot be waited for (eg -ECHILD if no 471 * process has been started or if the process has already been waited for). 472 * MINIJAIL_ERR_NO_COMMAND if command cannot be found. 473 * MINIJAIL_ERR_NO_ACCESS if command cannot be run. 474 * MINIJAIL_ERR_JAIL if process was killed by SIGSYS. 475 * (MINIJAIL_ERR_SIG_BASE + n) if process was killed by signal n != SIGSYS. 476 * (n & 0xFF) if process finished by returning code n. 477 */ 478 int minijail_wait(struct minijail *j); 479 480 /* 481 * Frees the given minijail. It does not matter if the process is inside the 482 * minijail or not. 483 */ 484 void minijail_destroy(struct minijail *j); 485 486 /* 487 * Deep copies the minijail in |from| to |out| providing two identical jails 488 * that can be used to contain separate children created with minijail_fork(). 489 * 490 * Duplicating a jail is invalid after a jail has been passed to 491 * minijail_fork(). Many minijail_*() calls will yield undefined 492 * results when called on a jail duplicated post-fork. 493 */ 494 int minijail_copy_jail(const struct minijail *from, struct minijail *out); 495 496 /* 497 * minijail_log_to_fd: redirects the module-wide logging to an FD instead of 498 * syslog. 499 * @fd FD to log to. Caller must ensure this is available after 500 * jailing (e.g. with minijail_preserve_fd()). 501 * @min_priority the minimum logging priority. Same as the priority argument 502 * to syslog(2). 503 */ 504 void minijail_log_to_fd(int fd, int min_priority); 505 506 #ifdef __cplusplus 507 } /* extern "C" */ 508 #endif 509 510 #endif /* !_LIBMINIJAIL_H_ */ 511