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