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 * Pass |envp| as the full environment for the child. 348 */ 349 int minijail_run_env(struct minijail *j, const char *filename, 350 char *const argv[], char *const envp[]); 351 352 /* 353 * Run the specified command in the given minijail, execve(2)-style. 354 * If minijail_namespace_pids() or minijail_namespace_user() are used, 355 * this or minijail_fork() is required instead of minijail_enter(). 356 */ 357 int minijail_run(struct minijail *j, const char *filename, 358 char *const argv[]); 359 360 /* 361 * Run the specified command in the given minijail, execve(2)-style. 362 * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing 363 * static binaries, or on systems without support for LD_PRELOAD. 364 */ 365 int minijail_run_no_preload(struct minijail *j, const char *filename, 366 char *const argv[]); 367 368 /* 369 * Run the specified command in the given minijail, execve(2)-style. 370 * Update |*pchild_pid| with the pid of the child. 371 */ 372 int minijail_run_pid(struct minijail *j, const char *filename, 373 char *const argv[], pid_t *pchild_pid); 374 375 /* 376 * Run the specified command in the given minijail, execve(2)-style. 377 * Update |*pstdin_fd| with a fd that allows writing to the child's 378 * standard input. 379 */ 380 int minijail_run_pipe(struct minijail *j, const char *filename, 381 char *const argv[], int *pstdin_fd); 382 383 /* 384 * Run the specified command in the given minijail, execve(2)-style. 385 * Update |*pchild_pid| with the pid of the child. 386 * Update |*pstdin_fd| with a fd that allows writing to the child's 387 * standard input. 388 * Update |*pstdout_fd| with a fd that allows reading from the child's 389 * standard output. 390 * Update |*pstderr_fd| with a fd that allows reading from the child's 391 * standard error. 392 */ 393 int minijail_run_pid_pipes(struct minijail *j, const char *filename, 394 char *const argv[], pid_t *pchild_pid, 395 int *pstdin_fd, int *pstdout_fd, int *pstderr_fd); 396 397 /* 398 * Run the specified command in the given minijail, execve(2)-style. 399 * Pass |envp| as the full environment for the child. 400 * Update |*pchild_pid| with the pid of the child. 401 * Update |*pstdin_fd| with a fd that allows writing to the child's 402 * standard input. 403 * Update |*pstdout_fd| with a fd that allows reading from the child's 404 * standard output. 405 * Update |*pstderr_fd| with a fd that allows reading from the child's 406 * standard error. 407 */ 408 int minijail_run_env_pid_pipes(struct minijail *j, const char *filename, 409 char *const argv[], char *const envp[], 410 pid_t *pchild_pid, int *pstdin_fd, 411 int *pstdout_fd, int *pstderr_fd); 412 413 /* 414 * Execute the specified file descriptor in the given minijail, 415 * fexecve(3)-style. 416 * Pass |envp| as the full environment for the child or NULL to inherit. 417 * Update |*pchild_pid| with the pid of the child. 418 * Update |*pstdin_fd| with a fd that allows writing to the child's 419 * standard input. 420 * Update |*pstdout_fd| with a fd that allows reading from the child's 421 * standard output. 422 * Update |*pstderr_fd| with a fd that allows reading from the child's 423 * standard error. 424 */ 425 int minijail_run_fd_env_pid_pipes(struct minijail *j, int elf_fd, 426 char *const argv[], char *const envp[], 427 pid_t *pchild_pid, int *pstdin_fd, 428 int *pstdout_fd, int *pstderr_fd); 429 430 /* 431 * Run the specified command in the given minijail, execve(2)-style. 432 * Update |*pchild_pid| with the pid of the child. 433 * Update |*pstdin_fd| with a fd that allows writing to the child's 434 * standard input. 435 * Update |*pstdout_fd| with a fd that allows reading from the child's 436 * standard output. 437 * Update |*pstderr_fd| with a fd that allows reading from the child's 438 * standard error. 439 * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing 440 * static binaries, or on systems without support for LD_PRELOAD. 441 */ 442 int minijail_run_pid_pipes_no_preload(struct minijail *j, const char *filename, 443 char *const argv[], pid_t *pchild_pid, 444 int *pstdin_fd, int *pstdout_fd, 445 int *pstderr_fd); 446 447 /* 448 * Run the specified command in the given minijail, execve(2)-style. 449 * Pass |envp| as the full environment for the child. 450 * Update |*pchild_pid| with the pid of the child. 451 * Update |*pstdin_fd| with a fd that allows writing to the child's 452 * standard input. 453 * Update |*pstdout_fd| with a fd that allows reading from the child's 454 * standard output. 455 * Update |*pstderr_fd| with a fd that allows reading from the child's 456 * standard error. 457 * Don't use LD_PRELOAD to do privilege dropping. This is useful when sandboxing 458 * static binaries, or on systems without support for LD_PRELOAD. 459 */ 460 int minijail_run_env_pid_pipes_no_preload(struct minijail *j, 461 const char *filename, 462 char *const argv[], 463 char *const envp[], pid_t *pchild_pid, 464 int *pstdin_fd, int *pstdout_fd, 465 int *pstderr_fd); 466 467 /* 468 * Fork, jail the child, and return. This behaves similar to fork(2), except it 469 * puts the child process in a jail before returning. 470 * `minijail_fork` returns in both the parent and the child. The pid of the 471 * child is returned to the parent. Zero is returned in the child. LD_PRELOAD 472 * is not supported. 473 * If minijail_namespace_pids() or minijail_namespace_user() are used, 474 * this or minijail_run*() is required instead of minijail_enter(). 475 */ 476 pid_t minijail_fork(struct minijail *j); 477 478 /* 479 * Send SIGTERM to the process in the minijail and wait for it to terminate. 480 * 481 * Return the same nonnegative exit status as minijail_wait(), or a negative 482 * error code (eg -ESRCH if the process has already been waited for). 483 * 484 * This is most useful if the minijail has been created with PID namespacing 485 * since, in this case, all processes inside it are atomically killed. 486 */ 487 int minijail_kill(struct minijail *j); 488 489 /* 490 * Wait for the first process spawned in the specified minijail to exit, and 491 * return its exit status. A process can only be waited once. 492 * 493 * Return: 494 * A negative error code if the process cannot be waited for (eg -ECHILD if no 495 * process has been started or if the process has already been waited for). 496 * MINIJAIL_ERR_NO_COMMAND if command cannot be found. 497 * MINIJAIL_ERR_NO_ACCESS if command cannot be run. 498 * MINIJAIL_ERR_JAIL if process was killed by SIGSYS. 499 * (MINIJAIL_ERR_SIG_BASE + n) if process was killed by signal n != SIGSYS. 500 * (n & 0xFF) if process finished by returning code n. 501 */ 502 int minijail_wait(struct minijail *j); 503 504 /* 505 * Frees the given minijail. It does not matter if the process is inside the 506 * minijail or not. 507 */ 508 void minijail_destroy(struct minijail *j); 509 510 /* 511 * Deep copies the minijail in |from| to |out| providing two identical jails 512 * that can be used to contain separate children created with minijail_fork(). 513 * 514 * Duplicating a jail is invalid after a jail has been passed to 515 * minijail_fork(). Many minijail_*() calls will yield undefined 516 * results when called on a jail duplicated post-fork. 517 */ 518 int minijail_copy_jail(const struct minijail *from, struct minijail *out); 519 520 /* 521 * minijail_log_to_fd: redirects the module-wide logging to an FD instead of 522 * syslog. 523 * @fd FD to log to. Caller must ensure this is available after 524 * jailing (e.g. with minijail_preserve_fd()). 525 * @min_priority the minimum logging priority. Same as the priority argument 526 * to syslog(2). 527 */ 528 void minijail_log_to_fd(int fd, int min_priority); 529 530 #ifdef __cplusplus 531 } /* extern "C" */ 532 #endif 533 534 #endif /* !_LIBMINIJAIL_H_ */ 535