added comments for sandbox.h

3 files changed, 92 insertions, 28 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 47b65d356..adabf6edd 100644
--- a/src/common/compat.c
+++ b/src/common/compat.c
@@ -109,6 +109,7 @@
 #include "util.h"
 #include "container.h"
 #include "address.h"
+#include "sandbox.h"
 
 /* Inline the strl functions if the platform doesn't have them. */
 #ifndef HAVE_STRLCPY
diff --git a/src/common/sandbox.c b/src/common/sandbox.c
index 6ff4296c4..f4c077979 100644
--- a/src/common/sandbox.c
+++ b/src/common/sandbox.c
@@ -9,6 +9,10 @@
  * \brief Code to enable sandboxing.
  **/
 
+/**
+ * Temporarily required for O_LARGEFILE flag. Needs to be removed
+ * with the libevent fix.
+ */
 #define _LARGEFILE64_SOURCE
 
 #include <stdio.h>
@@ -243,7 +247,6 @@ sb_mmap2(scmp_filter_ctx ctx, sandbox_cfg_t *filter)
 }
 #endif
 
-// TODO parameters
 static int
 sb_open(scmp_filter_ctx ctx, sandbox_cfg_t *filter)
 {
@@ -589,8 +592,7 @@ sandbox_intern_string(const char *param)
     return NULL;
 
   for (elem = filter_dynamic; elem != NULL; elem = elem->next) {
-    if (elem->prot  && elem->ptype == PARAM_PTR
-        && !strncmp(param, (char*)(elem->param), MAX_PARAM_LEN)) {
+    if (elem->prot && !strncmp(param, (char*)(elem->param), MAX_PARAM_LEN)) {
       return (char*)(elem->param);
     }
   }
@@ -643,7 +645,6 @@ sandbox_cfg_allow_stat64_filename(sandbox_cfg_t **cfg, char *file, char fr)
   elem = (sandbox_cfg_t*) malloc(sizeof(sandbox_cfg_t));
   elem->syscall = SCMP_SYS(stat64);
   elem->pindex = 0;
-  elem->ptype = PARAM_PTR;
   elem->param = (intptr_t) prot_strdup((char*) file);
   elem->prot = 1;
 
@@ -688,7 +689,6 @@ sandbox_cfg_allow_open_filename(sandbox_cfg_t **cfg, char *file, char fr)
   elem = (sandbox_cfg_t*) malloc(sizeof(sandbox_cfg_t));
   elem->syscall = SCMP_SYS(open);
   elem->pindex = 0;
-  elem->ptype = PARAM_PTR;
   elem->param = (intptr_t) prot_strdup((char*) file);
   elem->prot = 1;
 
@@ -732,7 +732,6 @@ sandbox_cfg_allow_openat_filename(sandbox_cfg_t **cfg, char *file, char fr)
   elem = (sandbox_cfg_t*) malloc(sizeof(sandbox_cfg_t));
   elem->syscall = SCMP_SYS(openat);
   elem->pindex = 1;
-  elem->ptype = PARAM_PTR;
   elem->param = (intptr_t) prot_strdup((char*) file);;
   elem->prot = 1;
 
@@ -776,7 +775,6 @@ sandbox_cfg_allow_execve(sandbox_cfg_t **cfg, char *com)
   elem = (sandbox_cfg_t*) malloc(sizeof(sandbox_cfg_t));
   elem->syscall = SCMP_SYS(openat);
   elem->pindex = 1;
-  elem->ptype = PARAM_PTR;
   elem->param = (intptr_t) prot_strdup((char*) com);;
   elem->prot = 1;
 
@@ -1062,7 +1060,6 @@ tor_global_sandbox(void)
 #endif
 }
 
-/** Use <b>fd</b> to log non-survivable sandbox violations. */
 void
 sandbox_set_debugging_fd(int fd)
 {
diff --git a/src/common/sandbox.h b/src/common/sandbox.h
index e92859160..ad31e5410 100644
--- a/src/common/sandbox.h
+++ b/src/common/sandbox.h
@@ -9,8 +9,6 @@
  * \brief Header file for sandbox.c.
  **/
 
-// TODO: thinking of only having allow_file for multiple syscalls
-
 #ifndef SANDBOX_H_
 #define SANDBOX_H_
 
@@ -37,40 +35,38 @@
 #include <sys/ucontext.h>
 #include <seccomp.h>
 
+/** Security measure for filter string parameter lengths*/
 #define MAX_PARAM_LEN 64
 
 #define PARAM_PTR 0
 #define PARAM_NUM 1
 
-typedef struct {
-  int syscall;
-
-  char ptype;
-  char pindex;
-  intptr_t param;
-
-  char prot;
-} sandbox_static_cfg_t;
-
+/**
+ * Structure used to manage a sandbox configuration.
+ *
+ * It is implemented as a linked list of parameters. Currently only controls
+ * parameters for open, openat, execve, stat64.
+ */
 struct pfd_elem {
-  int syscall;
+  int syscall;    // syscall associated with parameter
 
-  char ptype;
-  char pindex;
-  intptr_t param;
+  char pindex;    // parameter index
+  intptr_t param; // parameter value
 
-  char prot;
+  char prot;      // parameter flag (0 = not protected, 1 = protected)
 
   struct pfd_elem *next;
 };
+/** Typedef to structure used to manage a sandbox configuration. */
 typedef struct pfd_elem sandbox_cfg_t;
 
+/** Function pointer defining the prototype of a filter function.*/
 typedef int (*sandbox_filter_func_t)(scmp_filter_ctx ctx,
     sandbox_cfg_t *filter);
 
-
+/** Type that will be used in step 3 in order to manage multiple sandboxes.*/
 typedef struct {
-  // function pointers associated with filter
+  // function pointers associated with the filter
   sandbox_filter_func_t *filter_func;
 
   // filter function pointer parameters
@@ -95,28 +91,98 @@ typedef struct {
 
 #endif // __linux__
 
+/** Use <b>fd</b> to log non-survivable sandbox violations. */
 void sandbox_set_debugging_fd(int fd);
-int tor_global_sandbox(void);
+
+/** Returns a registered protected string used with the sandbox, given that
+ * it matches the parameter.
+ */
 const char* sandbox_intern_string(const char *param);
 
+/** Creates an empty sandbox configuration file.*/
 sandbox_cfg_t * sandbox_cfg_new();
 
+/**
+ * Function used to add a open allowed filename to a supplied configuration.
+ * The (char*) specifies the path to the allowed file, fr = 1 tells the
+ * function that the char* needs to be free-ed, 0 means the pointer does not
+ * need to be free-ed.
+ */
 int sandbox_cfg_allow_open_filename(sandbox_cfg_t **cfg, char *file,
     char fr);
+
+/** Function used to add a series of open allowed filenames to a supplied
+ * configuration.
+ *  @param cfg  sandbox configuration.
+ *  @param num  number of files.
+ *  @param ... all future parameters are specified as pairs of <(char*), 1 / 0>
+ *    the char* specifies the path to the allowed file, 1 tells the function
+ *    that the char* needs to be free-ed, 0 means the pointer does not need to
+ *    be free-ed.
+ */
 int sandbox_cfg_allow_open_filename_array(sandbox_cfg_t **cfg, int num, ...);
 
+/**
+ * Function used to add a openat allowed filename to a supplied configuration.
+ * The (char*) specifies the path to the allowed file, fr = 1 tells the
+ * function that the char* needs to be free-ed, 0 means the pointer does not
+ * need to be free-ed.
+ */
 int sandbox_cfg_allow_openat_filename(sandbox_cfg_t **cfg, char *file,
     char fr);
+
+/** Function used to add a series of openat allowed filenames to a supplied
+ * configuration.
+ *  @param cfg  sandbox configuration.
+ *  @param num  number of files.
+ *  @param ... all future parameters are specified as pairs of <(char*), 1 / 0>
+ *    the char* specifies the path to the allowed file, 1 tells the function
+ *    that the char* needs to be free-ed, 0 means the pointer does not need to
+ *    be free-ed.
+ */
 int sandbox_cfg_allow_openat_filename_array(sandbox_cfg_t **cfg, int num, ...);
 
+/**
+ * Function used to add a execve allowed filename to a supplied configuration.
+ * The (char*) specifies the path to the allowed file, fr = 1 tells the
+ * function that the char* needs to be free-ed, 0 means the pointer does not
+ * need to be free-ed.
+ */
 int sandbox_cfg_allow_execve(sandbox_cfg_t **cfg, char *com);
+
+/** Function used to add a series of execve allowed filenames to a supplied
+ * configuration.
+ *  @param cfg  sandbox configuration.
+ *  @param num  number of files.
+ *  @param ... all future parameters are specified as pairs of <(char*), 1 / 0>
+ *    the char* specifies the path to the allowed file, 1 tells the function
+ *    that the char* needs to be free-ed, 0 means the pointer does not need to
+ *    be free-ed.
+ */
 int sandbox_cfg_allow_execve_array(sandbox_cfg_t **cfg, int num, ...);
 
+/**
+ * Function used to add a stat64 allowed filename to a supplied configuration.
+ * The (char*) specifies the path to the allowed file, fr = 1 tells the
+ * function that the char* needs to be free-ed, 0 means the pointer does not
+ * need to be free-ed.
+ */
 int sandbox_cfg_allow_stat64_filename(sandbox_cfg_t **cfg, char *file,
     char fr);
+
+/** Function used to add a series of stat64 allowed filenames to a supplied
+ * configuration.
+ *  @param cfg  sandbox configuration.
+ *  @param num  number of files.
+ *  @param ... all future parameters are specified as pairs of <(char*), 1 / 0>
+ *    the char* specifies the path to the allowed file, 1 tells the function
+ *    that the char* needs to be free-ed, 0 means the pointer does not need to
+ *    be free-ed.
+ */
 int sandbox_cfg_allow_stat64_filename_array(sandbox_cfg_t **cfg,
     int num, ...);
 
+/** Function used to initialise a sandbox configuration.*/
 int sandbox_init(sandbox_cfg_t* cfg);
 
 #endif /* SANDBOX_H_ */