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
