doc: document how to use gnutls with seccomp

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index bd12d83fe3..bae2612bbc 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -30,6 +30,7 @@ and the manpages is recommended.
 * Common types::
 * Debugging and auditing::
 * Thread safety::
+* Running in a sandbox::
 * Sessions and fork::
 * Callback functions::
 @end menu
@@ -233,6 +234,44 @@ int main()
 
 @showfuncdesc{gnutls_global_set_mutex}
 
+@node Running in a sandbox
+@subsection Running in a sandbox
+@cindex seccomp
+@cindex isolated mode
+
+Given that TLS protocol handling as well as X.509 certificate
+parsing are complicated processes involving several thousands lines of code,
+it is often desirable (and recommended) to run the TLS session handling in
+a sandbox like seccomp. That has to be allowed by the overall software design,
+but if available, it adds an additional layer of protection by
+preventing parsing errors from becoming vessels for further security issues such
+as code execution.
+
+GnuTLS requires the following system calls to be available for its proper
+operation.
+
+@itemize
+@item nanosleep
+@item time
+@item gettimeofday
+@item clock_gettime
+@item getrusage
+@item send
+@item recv
+@item writev
+@item read (to read from /dev/urandom)
+@item getrandom (this is Linux-kernel specific)
+@item select
+@end itemize
+
+As well as an calls needed for memory allocation to work. Note however, that GnuTLS
+depends on libc for the system calls, and there is no guarrantee that libc will
+call the expected system call. For that it is recommended to test your
+program in all the targetted platforms when filters like seccomp are in place.
+
+An example with a seccomp filter from GnuTLS' test suite is at:
+@url{http://gitlab.com/gnutls/gnutls/blob/master/tests/seccomp.c}.
+
 @node Sessions and fork
 @subsection Sessions and fork
 @cindex fork