api: implement user notification in libseccomp

This patch is heavily based on an earlier patchset by Tycho
Andersen.  I took Tycho's patch and incorporated the requested changes
from the review, fixed some corner case bugs, and simplified the API
a bit.

Kernel 5.0 includes the new user notification return code. Here's all the
infrastructure to handle that.

The idea behind the user notification return code is that the filter stops
the syscall, and forwards it to a "listener fd" that is created when
installing a filter. Then then some userspace task can listen and process
events accordingly by taking some (or no) action in userspace, and then
returning a value from the command.

Signed-off-by: Tycho Andersen <tycho@tycho.ws>
Signed-off-by: Paul Moore <paul@paul-moore.com>

7 files changed, 108 insertions, 0 deletions

diff --git a/doc/man/man3/seccomp_api_get.3 b/doc/man/man3/seccomp_api_get.3
index d358c6d..6fa83a8 100644
--- a/doc/man/man3/seccomp_api_get.3
+++ b/doc/man/man3/seccomp_api_get.3
@@ -53,6 +53,9 @@ The SCMP_FLTATR_CTL_LOG filter attribute and the SCMP_ACT_LOG action are support
 .TP
 .B 4
 The SCMP_FLTATR_CTL_SSB filter attribute is supported.
+.TP
+.B 5
+The SCMP_ACT_NOTIFY action is supported.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_notify_alloc.3 b/doc/man/man3/seccomp_notify_alloc.3
new file mode 100644
index 0000000..c265ba2
--- /dev/null
+++ b/doc/man/man3/seccomp_notify_alloc.3
@@ -0,0 +1,100 @@
+.TH "seccomp_notify_alloc" 3 "24 April 2019" "tycho@tycho.ws" "libseccomp Documentation"
+.\" //////////////////////////////////////////////////////////////////////////
+.SH NAME
+.\" //////////////////////////////////////////////////////////////////////////
+seccomp_notify_alloc, seccomp_notify_free, seccomp_notify_receive,
+seccomp_notify_respond, seccomp_notify_id_valid, seccomp_notify_fd \- Manage seccomp notifications
+.\" //////////////////////////////////////////////////////////////////////////
+.SH SYNOPSIS
+.\" //////////////////////////////////////////////////////////////////////////
+.nf
+.B #include <seccomp.h>
+.sp
+.BI "int seccomp_notify_alloc(struct seccomp_notif **" req ", struct seccomp_notif_resp **" resp ")"
+.BI "void seccomp_notify_free(struct seccomp_notif *" req ", struct seccomp_notif_resp *" resp ")"
+.BI "int seccomp_notify_receive(int " fd ", struct seccomp_notif *" req ")"
+.BI "int seccomp_notify_respond(int " fd ", struct seccomp_notif_resp *" resp ")"
+.BI "int seccomp_notify_id_valid(int " fd ", uint64_t " id ")"
+.BI "int seccomp_notify_fd(const scmp_filter_ctx " ctx ")"
+.sp
+Link with \fI\-lseccomp\fP.
+.fi
+.\" //////////////////////////////////////////////////////////////////////////
+.SH DESCRIPTION
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+The
+.BR seccomp_notify_alloc ()
+function dynamically allocates enough memory for a seccomp notification and
+response. Note that one should always use these functions and not depend on the
+structure sizes in headers, since the size can vary depending on the kernel
+version. This function takes care to ask the kernel how big each structure
+should be, and allocates the right amount of memory. The
+.BR seccomp_notify_free ()
+function frees memory allocated by
+.BR seccomp_notify_alloc ().
+.P
+The
+.BR seccomp_notify_receive ()
+function receives a notification from a seccomp notify fd (obtained from
+.BR seccomp_notify_fd ()).
+.P
+The
+.BR seccomp_notify_respond ()
+function sends a response to a particular notification. The id field should be
+the same as the id from the request, so that the kernel knows which request
+this response corresponds to.
+.P
+The
+.BR seccomp_notify_id_valid ()
+function checks to see if the syscall from a particualr notification request is
+still valid, i.e. if the task is still alive. See NOTES below for details on
+race conditions.
+.P
+The
+.BR seccomp_notify_fd ()
+returns the notification fd of a filter after it has been loaded.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH RETURN VALUE
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+The
+.BR seccomp_notify_alloc (),
+.BR seccomp_notify_receive (),
+and
+.BR seccomp_notify_respond ()
+functions all return 0 on success, -1 on failure.
+.P
+The
+.BR seccomp_notify_id_valid ()
+returns 0 if the id is valid, and -ENOENT if it is not.
+.P
+The
+.BR seccomp_notify_fd ()
+returns the notification fd of the loaded filter.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH NOTES
+.\" //////////////////////////////////////////////////////////////////////////
+.P
+Care should be taken to avoid two different time of check/time of use errors.
+First, after opening any resources relevant to the pid for a notification (e.g.
+/proc/pid/mem for reading tracee memory to make policy decisions), applications
+should call
+.BR seccomp_notify_id_valid ()
+to make sure that the resources the application has opened correspond to the
+right pid, i.e. that the pid didn't die and a different task take its place.
+.P
+Second, the classic time of check/time of use issue with seccomp memory should
+also be avoided: applications should copy any memory they wish to use to make
+decisions from the tracee into its own address space before applying any policy
+decisions, since a multi-threaded tracee may edit the memory at any time,
+including after it's used to make a policy decision.
+.P
+A complete example of how to avoid these two races is available in the Linux
+Kernel source tree at
+.BR /samples/seccomp/user-trap.c.
+.\" //////////////////////////////////////////////////////////////////////////
+.SH AUTHOR
+.\" //////////////////////////////////////////////////////////////////////////
+Tycho Andersen <tycho@tycho.ws>
+.\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_notify_fd.3 b/doc/man/man3/seccomp_notify_fd.3
new file mode 100644
index 0000000..0c168c8
--- /dev/null
+++ b/doc/man/man3/seccomp_notify_fd.3
@@ -0,0 +1 @@
+.so man3/seccomp_notify_alloc.3
diff --git a/doc/man/man3/seccomp_notify_free.3 b/doc/man/man3/seccomp_notify_free.3
new file mode 100644
index 0000000..0c168c8
--- /dev/null
+++ b/doc/man/man3/seccomp_notify_free.3
@@ -0,0 +1 @@
+.so man3/seccomp_notify_alloc.3
diff --git a/doc/man/man3/seccomp_notify_id_valid.3 b/doc/man/man3/seccomp_notify_id_valid.3
new file mode 100644
index 0000000..0c168c8
--- /dev/null
+++ b/doc/man/man3/seccomp_notify_id_valid.3
@@ -0,0 +1 @@
+.so man3/seccomp_notify_alloc.3
diff --git a/doc/man/man3/seccomp_notify_receive.3 b/doc/man/man3/seccomp_notify_receive.3
new file mode 100644
index 0000000..0c168c8
--- /dev/null
+++ b/doc/man/man3/seccomp_notify_receive.3
@@ -0,0 +1 @@
+.so man3/seccomp_notify_alloc.3
diff --git a/doc/man/man3/seccomp_notify_respond.3 b/doc/man/man3/seccomp_notify_respond.3
new file mode 100644
index 0000000..0c168c8
--- /dev/null
+++ b/doc/man/man3/seccomp_notify_respond.3
@@ -0,0 +1 @@
+.so man3/seccomp_notify_alloc.3