From 340cca524f23195c00c46874b19980bbe7138ead Mon Sep 17 00:00:00 2001 From: Cristian Toader Date: Fri, 6 Sep 2013 21:41:45 +0300 Subject: added missing documentation for sandbox functions --- src/common/sandbox.c | 157 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 121 insertions(+), 36 deletions(-) diff --git a/src/common/sandbox.c b/src/common/sandbox.c index e936b6213..1fa4d613c 100644 --- a/src/common/sandbox.c +++ b/src/common/sandbox.c @@ -54,8 +54,11 @@ #include #include +/**Determines if at least one sandbox is active.*/ static int sandbox_active = 0; +/** Holds the parameter list configuration for the sandbox.*/ static sandbox_cfg_t *filter_dynamic = NULL; +/** Holds a list of pre-recorded results from getaddrinfo().*/ static sb_addr_info_t *sb_addr_info = NULL; /** Variable used for storing all syscall numbers that will be allowed with the @@ -130,6 +133,10 @@ static int filter_nopar_gen[] = { SCMP_SYS(unlink) }; +/** + * Function responsible for setting up the rt_sigaction syscall for + * the seccomp filter sandbox. + */ static int sb_rt_sigaction(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -150,6 +157,10 @@ sb_rt_sigaction(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return rc; } +/** + * Function responsible for setting up the execve syscall for + * the seccomp filter sandbox. + */ static int sb_execve(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -175,6 +186,10 @@ sb_execve(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the time syscall for + * the seccomp filter sandbox. + */ static int sb_time(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -182,6 +197,10 @@ sb_time(scmp_filter_ctx ctx, sandbox_cfg_t *filter) SCMP_CMP(0, SCMP_CMP_EQ, 0)); } +/** + * Function responsible for setting up the accept4 syscall for + * the seccomp filter sandbox. + */ static int sb_accept4(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -205,6 +224,10 @@ sb_accept4(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } #ifdef __NR_mmap2 +/** + * Function responsible for setting up the mmap2 syscall for + * the seccomp filter sandbox. + */ static int sb_mmap2(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -263,6 +286,10 @@ sb_mmap2(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } #endif +/** + * Function responsible for setting up the open syscall for + * the seccomp filter sandbox. + */ static int sb_open(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -285,7 +312,6 @@ sb_open(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } } - // problem: required by getaddrinfo rc = seccomp_rule_add(ctx, SCMP_ACT_ERRNO(-1), SCMP_SYS(open), 1, SCMP_CMP(1, SCMP_CMP_EQ, O_RDONLY|O_CLOEXEC)); if (rc != 0) { @@ -297,6 +323,10 @@ sb_open(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the openat syscall for + * the seccomp filter sandbox. + */ static int sb_openat(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -325,6 +355,10 @@ sb_openat(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the socket syscall for + * the seccomp filter sandbox. + */ static int sb_socket(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -367,6 +401,10 @@ sb_socket(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the socketpair syscall for + * the seccomp filter sandbox. + */ static int sb_socketpair(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -387,6 +425,10 @@ sb_socketpair(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the setsockopt syscall for + * the seccomp filter sandbox. + */ static int sb_setsockopt(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -407,6 +449,10 @@ sb_setsockopt(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the getsockopt syscall for + * the seccomp filter sandbox. + */ static int sb_getsockopt(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -428,6 +474,10 @@ sb_getsockopt(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } #ifdef __NR_fcntl64 +/** + * Function responsible for setting up the fcntl64 syscall for + * the seccomp filter sandbox. + */ static int sb_fcntl64(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -459,7 +509,12 @@ sb_fcntl64(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } #endif -// allows everything but will keep for now.. +/** + * Function responsible for setting up the epoll_ctl syscall for + * the seccomp filter sandbox. + * + * Note: basically allows everything but will keep for now.. + */ static int sb_epoll_ctl(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -484,8 +539,11 @@ sb_epoll_ctl(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } /** - * If multiple filters need to be added, seccomp needs to be whitelisted in - * this list. + * Function responsible for setting up the fcntl64 syscall for + * the seccomp filter sandbox. + * + * NOTE: if multiple filters need to be added, the PR_SECCOMP parameter needs + * to be whitelisted in this function. */ static int sb_prctl(scmp_filter_ctx ctx, sandbox_cfg_t *filter) @@ -501,7 +559,11 @@ sb_prctl(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } /** - * does not NEED tobe here.. only occurs before filter + * Function responsible for setting up the fcntl64 syscall for + * the seccomp filter sandbox. + * + * NOTE: does not NEED to be here.. currently only occurs before filter; will + * keep just in case for the future. */ static int sb_mprotect(scmp_filter_ctx ctx, sandbox_cfg_t *filter) @@ -526,6 +588,10 @@ sb_mprotect(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the rt_sigprocmask syscall for + * the seccomp filter sandbox. + */ static int sb_rt_sigprocmask(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -545,7 +611,10 @@ sb_rt_sigprocmask(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } /** - * does not NEED tobe here.. only occurs before filter + * Function responsible for setting up the flock syscall for + * the seccomp filter sandbox. + * + * NOTE: does not need to be here, occurs before filter is applied. */ static int sb_flock(scmp_filter_ctx ctx, sandbox_cfg_t *filter) @@ -565,6 +634,10 @@ sb_flock(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the futex syscall for + * the seccomp filter sandbox. + */ static int sb_futex(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -591,7 +664,10 @@ sb_futex(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } /** - * does not NEED tobe here.. only occurs before filter + * Function responsible for setting up the mremap syscall for + * the seccomp filter sandbox. + * + * NOTE: so far only occurs before filter is applied. */ static int sb_mremap(scmp_filter_ctx ctx, sandbox_cfg_t *filter) @@ -606,6 +682,10 @@ sb_mremap(scmp_filter_ctx ctx, sandbox_cfg_t *filter) return 0; } +/** + * Function responsible for setting up the poll syscall for + * the seccomp filter sandbox. + */ static int sb_poll(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -621,6 +701,10 @@ sb_poll(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } #ifdef __NR_stat64 +/** + * Function responsible for setting up the stat64 syscall for + * the seccomp filter sandbox. + */ static int sb_stat64(scmp_filter_ctx ctx, sandbox_cfg_t *filter) { @@ -647,6 +731,10 @@ sb_stat64(scmp_filter_ctx ctx, sandbox_cfg_t *filter) } #endif +/** + * Array of function pointers responsible for filtering different syscalls at + * a parameter level. + */ static sandbox_filter_func_t filter_func[] = { sb_rt_sigaction, sb_rt_sigprocmask, @@ -692,6 +780,12 @@ sandbox_intern_string(const char *str) return str; } +/** + * Protects all the strings in the sandbox's parameter list configuration. It + * works by calculating the total amount of memory required by the parameter + * list, allocating the memory using mmap, and protecting it from writes with + * mprotect(). + */ static int prot_strings(sandbox_cfg_t* cfg) { @@ -754,6 +848,12 @@ prot_strings(sandbox_cfg_t* cfg) return ret; } +/** + * Auxiliary function used in order to allocate a sandbox_cfg_t element and set + * it's values according the the parameter list. All elements are initialised + * with the 'prot' field set to false, as the pointer is not protected at this + * point. + */ static sandbox_cfg_t* new_element(int syscall, int index, intptr_t value) { @@ -1019,6 +1119,10 @@ sandbox_add_addrinfo(const char* name) return ret; } +/** + * Function responsible for going through the parameter syscall filters and + * call each function pointer in the list. + */ static int add_param_filter(scmp_filter_ctx ctx, sandbox_cfg_t* cfg) { @@ -1036,6 +1140,10 @@ add_param_filter(scmp_filter_ctx ctx, sandbox_cfg_t* cfg) return 0; } +/** + * Function responsible of loading the libseccomp syscall filters which do not + * have parameter filtering. + */ static int add_noparam_filter(scmp_filter_ctx ctx) { @@ -1085,7 +1193,7 @@ install_syscall_filter(sandbox_cfg_t* cfg) } // loading the seccomp2 filter - if((rc = seccomp_load(ctx))) { + if ((rc = seccomp_load(ctx))) { log_err(LD_BUG, "(Sandbox) failed to load!"); goto end; } @@ -1183,6 +1291,11 @@ install_sigsys_debugging(void) return 0; } +/** + * Function responsible of registering the sandbox_cfg_t list of parameter + * syscall filters to the existing parameter list. This is used for incipient + * multiple-sandbox support. + */ static int register_cfg(sandbox_cfg_t* cfg) { @@ -1256,34 +1369,6 @@ sandbox_init(sandbox_cfg_t* cfg) #endif } -/** - * Enables the stage 1 general sandbox. It applies a syscall filter which does - * not restrict any Tor features. The filter is representative for the whole - * application. - */ -int -tor_global_sandbox(void) -{ - -#if defined(USE_LIBSECCOMP) - return initialise_libseccomp_sandbox(NULL); - -#elif defined(_WIN32) - log_warn(LD_BUG,"Windows sandboxing is not implemented. The feature is " - "currently disabled."); - return 0; - -#elif defined(TARGET_OS_MAC) - log_warn(LD_BUG,"Mac OSX sandboxing is not implemented. The feature is " - "currently disabled"); - return 0; -#else - log_warn(LD_BUG,"Sandboxing is not implemented for your platform. The " - "feature is currently disabled"); - return 0; -#endif -} - void sandbox_set_debugging_fd(int fd) { -- cgit v1.2.3