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