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