README.md

@@ -1,61 +1,63 @@
-qssb.h (quite simple sandbox)
-=============================
-qssb.h is a simple header only library that provides an interface
-to sandbox applications on Linux. Using Seccomp and Linux Namespaces for that
-purpose requires some knowledge of annoying details which this library
-aims to abstract away as much as possible.
+# qssb.h (quite simple sandbox)
+`qssb.h` is a simple header-only library that wants to provides an interface to sandbox applications on Linux. Using Seccomp and Linux Namespaces for that purpose requires some knowledge of annoying details which this library aims to abstract away as much as possible, when reasonable.
 
-Status
-======
-No release yet, API is unstable.
+Hence, the goal is to provide an easy way to processes to restrict themselves in order to mitigate the effect of exploits. Currently, it utilizes technologies like Seccomp, Namespaces and Landlock to achieve this end. 
+
+In the end, sandboxing must be considered in the software architecture, e. g. by employing the common multi-process model that offloads certain computations to individual, restricted processes. This library does not directly address those architecture related questions.  
+
+## Status
+No release yet, expiremental, API is unstable, builds will break on updates of this library. 
+
+## Documentation
+See [docs](./docs/)
+
+
+## Features
 
-Features
-========
   - Systemcall filtering
   - restricting file system access
   - dropping privileges 
   - isolating the application from the network, etc.
 
-Requirements
-============
+## Requirements
+
 Kernel >=3.17
-sys/capabilities.h header. Depending on your system, libcap
+
+``sys/capabilities.h`` header. Depending on your distribution, libcap
 might be needed for this.
 
+While mostly transparent to users of this API, kernel >= 5.13 is required to take advantage of Landlock.
 
 
-FAQ
-===
 
-Does the process need to be priviliged to utilize the library?
-----------------------------------------------------------------
-No.
+## FAQ
 
-It doesn't work on Debian!
---------------------------
-You can thank a Debian-specific patch for that. In the future,
+
+### Does the process need to be priviliged to utilize the library?
+
+No. 
+
+### It doesn't work on Debian!
+
+You can thank a Debian-specific kernel patch for that. In the future,
 the library may check against that. Execute
-echo 1 > /proc/sys/kernel/unprivileged_userns_clone to disable that
-patch for now.
+`echo 1 > /proc/sys/kernel/unprivileged_userns_clone` to disable that patch for now.
 
-Documentation
-=============
-To be written
+### Examples
 
-Examples
-========
   - qswiki: https://gitea.quitesimple.org/crtxcr/qswiki
   - cgit sandboxed: https://gitea.quitesimple.org/crtxcr/cgitsb
   - qpdfviewsb sandboxed (quick and dirty): https://gitea.quitesimple.org/crtxcr/qpdfviewsb
 
 
-Contributing
-============
+### Contributing
+
 Contributions are very welcome. Options: 
-1) Pull-Request: github.com/quitesimpleorg/qssb 
-2) Mail to qssb at quitesimple.org with instructions
-on where to pull the changes.
-3) Mailing a classic patch.
+
+1. Pull-Request on [github](https://github.com/quitesimpleorg/qssb)
+2. Mail to `qssb at quitesimple.org` with instructions on where to pull the changes from.
+3. Mailing a classic patch/diff to the same address.
+
 
 License
 =======

qssb.h

@@ -201,6 +201,13 @@ struct qssb_policy *qssb_init_policy()
 	return result;
 }
 
+/* Appends path policies to the qssb_policy object
+ * The last paramater must be NULL
+ *
+ * This function does not copy parameters. All passed paths
+ * MUST NOT be freed until qssb_enable_policy() is called!
+ *
+ * @returns: 0 on success, -1 on failure */
 int qssb_append_path_policies(struct qssb_policy *qssb_policy, unsigned int path_policy, ...)
 {
 	va_list args;
@@ -741,9 +748,15 @@ static int check_policy_sanity(struct qssb_policy *policy)
 
 /* Enables the specified qssb_policy.
  *
- * The calling process is supposed *TO BE WRITTEN* if
- * this function fails.
- * @returns: 0 on sucess, <0 on error
+ * This function is not atomic (and can't be). This means some
+ * policies can apply, while others may fail.
+ *
+ * This function returns success only if all policies applied.
+ *
+ * The state is undefined if this function fails. The process generally
+ * should exit.
+ *
+ * @returns: 0 on success (all policies applied), < 0 on error (none or some policies dit not apply)
  */
 int qssb_enable_policy(struct qssb_policy *policy)
 {