summaryrefslogtreecommitdiffstats
path: root/man2/seccomp_unotify.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/seccomp_unotify.2')
-rw-r--r--man2/seccomp_unotify.22011
1 files changed, 2011 insertions, 0 deletions
diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2
new file mode 100644
index 0000000..156fbce
--- /dev/null
+++ b/man2/seccomp_unotify.2
@@ -0,0 +1,2011 @@
+.\" Copyright (C) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH seccomp_unotify 2 2023-05-03 "Linux man-pages 6.05.01"
+.SH NAME
+seccomp_unotify \- Seccomp user-space notification mechanism
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <linux/seccomp.h>
+.B #include <linux/filter.h>
+.B #include <linux/audit.h>
+.PP
+.BI "int seccomp(unsigned int " operation ", unsigned int " flags \
+", void *" args );
+.PP
+.B #include <sys/ioctl.h>
+.PP
+.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_RECV,"
+.BI " struct seccomp_notif *" req );
+.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SEND,"
+.BI " struct seccomp_notif_resp *" resp );
+.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ID_VALID, __u64 *" id );
+.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ADDFD,"
+.BI " struct seccomp_notif_addfd *" addfd );
+.fi
+.SH DESCRIPTION
+This page describes the user-space notification mechanism provided by the
+Secure Computing (seccomp) facility.
+As well as the use of the
+.B SECCOMP_FILTER_FLAG_NEW_LISTENER
+flag, the
+.B SECCOMP_RET_USER_NOTIF
+action value, and the
+.B SECCOMP_GET_NOTIF_SIZES
+operation described in
+.BR seccomp (2),
+this mechanism involves the use of a number of related
+.BR ioctl (2)
+operations (described below).
+.\"
+.SS Overview
+In conventional usage of a seccomp filter,
+the decision about how to treat a system call is made by the filter itself.
+By contrast, the user-space notification mechanism allows
+the seccomp filter to delegate
+the handling of the system call to another user-space process.
+Note that this mechanism is explicitly
+.B not
+intended as a method implementing security policy; see NOTES.
+.PP
+In the discussion that follows,
+the thread(s) on which the seccomp filter is installed is (are)
+referred to as the
+.IR target ,
+and the process that is notified by the user-space notification
+mechanism is referred to as the
+.IR supervisor .
+.PP
+A suitably privileged supervisor can use the user-space notification
+mechanism to perform actions on behalf of the target.
+The advantage of the user-space notification mechanism is that
+the supervisor will
+usually be able to retrieve information about the target and the
+performed system call that the seccomp filter itself cannot.
+(A seccomp filter is limited in the information it can obtain and
+the actions that it can perform because it
+is running on a virtual machine inside the kernel.)
+.PP
+An overview of the steps performed by the target and the supervisor
+is as follows:
+.\"-------------------------------------
+.IP (1) 5
+The target establishes a seccomp filter in the usual manner,
+but with two differences:
+.RS
+.IP \[bu] 3
+The
+.BR seccomp (2)
+.I flags
+argument includes the flag
+.BR SECCOMP_FILTER_FLAG_NEW_LISTENER .
+Consequently, the return value of the (successful)
+.BR seccomp (2)
+call is a new "listening"
+file descriptor that can be used to receive notifications.
+Only one "listening" seccomp filter can be installed for a thread.
+.\" FIXME
+.\" Is the last sentence above correct?
+.\"
+.\" Kees Cook (25 Oct 2020) notes:
+.\"
+.\" I like this limitation, but I expect that it'll need to change in the
+.\" future. Even with LSMs, we see the need for arbitrary stacking, and the
+.\" idea of there being only 1 supervisor will eventually break down. Right
+.\" now there is only 1 because only container managers are using this
+.\" feature. But if some daemon starts using it to isolate some thread,
+.\" suddenly it might break if a container manager is trying to listen to it
+.\" too, etc. I expect it won't be needed soon, but I do think it'll change.
+.\"
+.IP \[bu]
+In cases where it is appropriate, the seccomp filter returns the action value
+.BR SECCOMP_RET_USER_NOTIF .
+This return value will trigger a notification event.
+.RE
+.\"-------------------------------------
+.IP (2)
+In order that the supervisor can obtain notifications
+using the listening file descriptor,
+(a duplicate of) that file descriptor must be passed from
+the target to the supervisor.
+One way in which this could be done is by passing the file descriptor
+over a UNIX domain socket connection between the target and the supervisor
+(using the
+.B SCM_RIGHTS
+ancillary message type described in
+.BR unix (7)).
+Another way to do this is through the use of
+.BR pidfd_getfd (2).
+.\" Jann Horn:
+.\" Instead of using unix domain sockets to send the fd to the
+.\" parent, I think you could also use clone3() with
+.\" flags==CLONE_FILES|SIGCHLD, dup2() the seccomp fd to an fd
+.\" that was reserved in the parent, call unshare(CLONE_FILES)
+.\" in the child after setting up the seccomp fd, and wake
+.\" up the parent with something like pthread_cond_signal()?
+.\" I'm not sure whether that'd look better or worse in the
+.\" end though, so maybe just ignore this comment.
+.\"-------------------------------------
+.IP (3)
+The supervisor will receive notification events
+on the listening file descriptor.
+These events are returned as structures of type
+.IR seccomp_notif .
+Because this structure and its size may evolve over kernel versions,
+the supervisor must first determine the size of this structure
+using the
+.BR seccomp (2)
+.B SECCOMP_GET_NOTIF_SIZES
+operation, which returns a structure of type
+.IR seccomp_notif_sizes .
+The supervisor allocates a buffer of size
+.I seccomp_notif_sizes.seccomp_notif
+bytes to receive notification events.
+In addition,the supervisor allocates another buffer of size
+.I seccomp_notif_sizes.seccomp_notif_resp
+bytes for the response (a
+.I struct seccomp_notif_resp
+structure)
+that it will provide to the kernel (and thus the target).
+.\"-------------------------------------
+.IP (4)
+The target then performs its workload,
+which includes system calls that will be controlled by the seccomp filter.
+Whenever one of these system calls causes the filter to return the
+.B SECCOMP_RET_USER_NOTIF
+action value, the kernel does
+.I not
+(yet) execute the system call;
+instead, execution of the target is temporarily blocked inside
+the kernel (in a sleep state that is interruptible by signals)
+and a notification event is generated on the listening file descriptor.
+.\"-------------------------------------
+.IP (5)
+The supervisor can now repeatedly monitor the
+listening file descriptor for
+.BR SECCOMP_RET_USER_NOTIF -triggered
+events.
+To do this, the supervisor uses the
+.B SECCOMP_IOCTL_NOTIF_RECV
+.BR ioctl (2)
+operation to read information about a notification event;
+this operation blocks until an event is available.
+The operation returns a
+.I seccomp_notif
+structure containing information about the system call
+that is being attempted by the target.
+(As described in NOTES,
+the file descriptor can also be monitored with
+.BR select (2),
+.BR poll (2),
+or
+.BR epoll (7).)
+.\" FIXME
+.\" Christian Brauner:
+.\"
+.\" Do we support O_NONBLOCK with SECCOMP_IOCTL_NOTIF_RECV and if
+.\" not should we?
+.\"
+.\" Michael Kerrisk:
+.\"
+.\" A quick test suggests that O_NONBLOCK has no effect on the blocking
+.\" behavior of SECCOMP_IOCTL_NOTIF_RECV.
+.
+.\"-------------------------------------
+.IP (6)
+The
+.I seccomp_notif
+structure returned by the
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation includes the same information (a
+.I seccomp_data
+structure) that was passed to the seccomp filter.
+This information allows the supervisor to discover the system call number and
+the arguments for the target's system call.
+In addition, the notification event contains the ID of the thread
+that triggered the notification and a unique cookie value that
+is used in subsequent
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+and
+.B SECCOMP_IOCTL_NOTIF_SEND
+operations.
+.IP
+The information in the notification can be used to discover the
+values of pointer arguments for the target's system call.
+(This is something that can't be done from within a seccomp filter.)
+One way in which the supervisor can do this is to open the corresponding
+.IR /proc/ tid /mem
+file (see
+.BR proc (5))
+and read bytes from the location that corresponds to one of
+the pointer arguments whose value is supplied in the notification event.
+.\" Tycho Andersen mentioned that there are alternatives to /proc/PID/mem,
+.\" such as ptrace() and /proc/PID/map_files
+(The supervisor must be careful to avoid
+a race condition that can occur when doing this;
+see the description of the
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+.BR ioctl (2)
+operation below.)
+In addition,
+the supervisor can access other system information that is visible
+in user space but which is not accessible from a seccomp filter.
+.\"-------------------------------------
+.IP (7)
+Having obtained information as per the previous step,
+the supervisor may then choose to perform an action in response
+to the target's system call
+(which, as noted above, is not executed when the seccomp filter returns the
+.B SECCOMP_RET_USER_NOTIF
+action value).
+.IP
+One example use case here relates to containers.
+The target may be located inside a container where
+it does not have sufficient capabilities to mount a filesystem
+in the container's mount namespace.
+However, the supervisor may be a more privileged process that
+does have sufficient capabilities to perform the mount operation.
+.\"-------------------------------------
+.IP (8)
+The supervisor then sends a response to the notification.
+The information in this response is used by the kernel to construct
+a return value for the target's system call and provide
+a value that will be assigned to the
+.I errno
+variable of the target.
+.IP
+The response is sent using the
+.B SECCOMP_IOCTL_NOTIF_SEND
+.BR ioctl (2)
+operation, which is used to transmit a
+.I seccomp_notif_resp
+structure to the kernel.
+This structure includes a cookie value that the supervisor obtained in the
+.I seccomp_notif
+structure returned by the
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation.
+This cookie value allows the kernel to associate the response with the
+target.
+This structure must include the cookie value that the supervisor
+obtained in the
+.I seccomp_notif
+structure returned by the
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation;
+the cookie allows the kernel to associate the response with the target.
+.\"-------------------------------------
+.IP (9)
+Once the notification has been sent,
+the system call in the target thread unblocks,
+returning the information that was provided by the supervisor
+in the notification response.
+.\"-------------------------------------
+.PP
+As a variation on the last two steps,
+the supervisor can send a response that tells the kernel that it
+should execute the target thread's system call; see the discussion of
+.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE ,
+below.
+.\"
+.SH IOCTL OPERATIONS
+The following
+.BR ioctl (2)
+operations are supported by the seccomp user-space
+notification file descriptor.
+For each of these operations, the first (file descriptor) argument of
+.BR ioctl (2)
+is the listening file descriptor returned by a call to
+.BR seccomp (2)
+with the
+.B SECCOMP_FILTER_FLAG_NEW_LISTENER
+flag.
+.\"
+.SS SECCOMP_IOCTL_NOTIF_RECV
+The
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation (available since Linux 5.0) is used to obtain a user-space
+notification event.
+If no such event is currently pending,
+the operation blocks until an event occurs.
+The third
+.BR ioctl (2)
+argument is a pointer to a structure of the following form
+which contains information about the event.
+This structure must be zeroed out before the call.
+.PP
+.in +4n
+.EX
+struct seccomp_notif {
+ __u64 id; /* Cookie */
+ __u32 pid; /* TID of target thread */
+ __u32 flags; /* Currently unused (0) */
+ struct seccomp_data data; /* See seccomp(2) */
+};
+.EE
+.in
+.PP
+The fields in this structure are as follows:
+.TP
+.I id
+This is a cookie for the notification.
+Each such cookie is guaranteed to be unique for the corresponding
+seccomp filter.
+.RS
+.IP \[bu] 3
+The cookie can be used with the
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+.BR ioctl (2)
+operation described below.
+.IP \[bu]
+When returning a notification response to the kernel,
+the supervisor must include the cookie value in the
+.I seccomp_notif_resp
+structure that is specified as the argument of the
+.B SECCOMP_IOCTL_NOTIF_SEND
+operation.
+.RE
+.TP
+.I pid
+This is the thread ID of the target thread that triggered
+the notification event.
+.TP
+.I flags
+This is a bit mask of flags providing further information on the event.
+In the current implementation, this field is always zero.
+.TP
+.I data
+This is a
+.I seccomp_data
+structure containing information about the system call that
+triggered the notification.
+This is the same structure that is passed to the seccomp filter.
+See
+.BR seccomp (2)
+for details of this structure.
+.PP
+On success, this operation returns 0; on failure, \-1 is returned, and
+.I errno
+is set to indicate the cause of the error.
+This operation can fail with the following errors:
+.TP
+.BR EINVAL " (since Linux 5.5)"
+.\" commit 2882d53c9c6f3b8311d225062522f03772cf0179
+The
+.I seccomp_notif
+structure that was passed to the call contained nonzero fields.
+.TP
+.B ENOENT
+The target thread was killed by a signal as the notification information
+was being generated,
+or the target's (blocked) system call was interrupted by a signal handler.
+.\" FIXME
+.\" From my experiments,
+.\" it appears that if a SECCOMP_IOCTL_NOTIF_RECV is done after
+.\" the target thread terminates, then the ioctl() simply
+.\" blocks (rather than returning an error to indicate that the
+.\" target no longer exists).
+.\"
+.\" I found that surprising, and it required some contortions in
+.\" the example program. It was not possible to code my SIGCHLD
+.\" handler (which reaps the zombie when the worker/target
+.\" terminates) to simply set a flag checked in the main
+.\" handleNotifications() loop, since this created an
+.\" unavoidable race where the child might terminate just after
+.\" I had checked the flag, but before I blocked (forever!) in the
+.\" SECCOMP_IOCTL_NOTIF_RECV operation. Instead, I had to code
+.\" the signal handler to simply call _exit(2) in order to
+.\" terminate the parent process (the supervisor).
+.\"
+.\" Is this expected behavior? It seems to me rather
+.\" desirable that SECCOMP_IOCTL_NOTIF_RECV should give an error
+.\" if the target has terminated.
+.\"
+.\" Jann posted a patch to rectify this, but there was no response
+.\" (Lore link: https://bit.ly/3jvUBxk) to his question about fixing
+.\" this issue. (I've tried building with the patch, but encountered
+.\" an issue with the target process entering D state after a signal.)
+.\"
+.\" For now, this behavior is documented in BUGS.
+.\"
+.\" Kees Cook commented: Let's change [this] ASAP!
+.\"
+.SS SECCOMP_IOCTL_NOTIF_ID_VALID
+The
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+operation (available since Linux 5.0) is used to check that a notification ID
+returned by an earlier
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation is still valid
+(i.e., that the target still exists and its system call
+is still blocked waiting for a response).
+.PP
+The third
+.BR ioctl (2)
+argument is a pointer to the cookie
+.RI ( id )
+returned by the
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation.
+.PP
+This operation is necessary to avoid race conditions that can occur when the
+.I pid
+returned by the
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation terminates, and that process ID is reused by another process.
+An example of this kind of race is the following
+.IP (1) 5
+A notification is generated on the listening file descriptor.
+The returned
+.I seccomp_notif
+contains the TID of the target thread (in the
+.I pid
+field of the structure).
+.IP (2)
+The target terminates.
+.IP (3)
+Another thread or process is created on the system that by chance reuses the
+TID that was freed when the target terminated.
+.IP (4)
+The supervisor
+.BR open (2)s
+the
+.IR /proc/ tid /mem
+file for the TID obtained in step 1, with the intention of (say)
+inspecting the memory location(s) that containing the argument(s) of
+the system call that triggered the notification in step 1.
+.PP
+In the above scenario, the risk is that the supervisor may try
+to access the memory of a process other than the target.
+This race can be avoided by following the call to
+.BR open (2)
+with a
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+operation to verify that the process that generated the notification
+is still alive.
+(Note that if the target terminates after the latter step,
+a subsequent
+.BR read (2)
+from the file descriptor may return 0, indicating end of file.)
+.\" Jann Horn:
+.\" the PID can be reused, but the /proc/$pid directory is
+.\" internally not associated with the numeric PID, but,
+.\" conceptually speaking, with a specific incarnation of the
+.\" PID, or something like that. (Actually, it is associated
+.\" with the "struct pid", which is not reused, instead of the
+.\" numeric PID.
+.PP
+See NOTES for a discussion of other cases where
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+checks must be performed.
+.PP
+On success (i.e., the notification ID is still valid),
+this operation returns 0.
+On failure (i.e., the notification ID is no longer valid),
+\-1 is returned, and
+.I errno
+is set to
+.BR ENOENT .
+.\"
+.SS SECCOMP_IOCTL_NOTIF_SEND
+The
+.B SECCOMP_IOCTL_NOTIF_SEND
+operation (available since Linux 5.0)
+is used to send a notification response back to the kernel.
+The third
+.BR ioctl (2)
+argument of this structure is a pointer to a structure of the following form:
+.PP
+.in +4n
+.EX
+struct seccomp_notif_resp {
+ __u64 id; /* Cookie value */
+ __s64 val; /* Success return value */
+ __s32 error; /* 0 (success) or negative error number */
+ __u32 flags; /* See below */
+};
+.EE
+.in
+.PP
+The fields of this structure are as follows:
+.TP
+.I id
+This is the cookie value that was obtained using the
+.B SECCOMP_IOCTL_NOTIF_RECV
+operation.
+This cookie value allows the kernel to correctly associate this response
+with the system call that triggered the user-space notification.
+.TP
+.I val
+This is the value that will be used for a spoofed
+success return for the target's system call; see below.
+.TP
+.I error
+This is the value that will be used as the error number
+.RI ( errno )
+for a spoofed error return for the target's system call; see below.
+.TP
+.I flags
+This is a bit mask that includes zero or more of the following flags:
+.RS
+.TP
+.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE " (since Linux 5.5)"
+Tell the kernel to execute the target's system call.
+.\" commit fb3c5386b382d4097476ce9647260fc89b34afdb
+.RE
+.PP
+Two kinds of response are possible:
+.IP \[bu] 3
+A response to the kernel telling it to execute the
+target's system call.
+In this case, the
+.I flags
+field includes
+.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
+and the
+.I error
+and
+.I val
+fields must be zero.
+.IP
+This kind of response can be useful in cases where the supervisor needs
+to do deeper analysis of the target's system call than is possible
+from a seccomp filter (e.g., examining the values of pointer arguments),
+and, having decided that the system call does not require emulation
+by the supervisor, the supervisor wants the system call to
+be executed normally in the target.
+.IP
+The
+.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
+flag should be used with caution; see NOTES.
+.IP \[bu]
+A spoofed return value for the target's system call.
+In this case, the kernel does not execute the target's system call,
+instead causing the system call to return a spoofed value as specified by
+fields of the
+.I seccomp_notif_resp
+structure.
+The supervisor should set the fields of this structure as follows:
+.RS
+.IP + 3
+.I flags
+does not contain
+.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE .
+.IP +
+.I error
+is set either to 0 for a spoofed "success" return or to a negative
+error number for a spoofed "failure" return.
+In the former case, the kernel causes the target's system call
+to return the value specified in the
+.I val
+field.
+In the latter case, the kernel causes the target's system call
+to return \-1, and
+.I errno
+is assigned the negated
+.I error
+value.
+.IP +
+.I val
+is set to a value that will be used as the return value for a spoofed
+"success" return for the target's system call.
+The value in this field is ignored if the
+.I error
+field contains a nonzero value.
+.\" FIXME
+.\" Kees Cook suggested:
+.\"
+.\" Strictly speaking, this is architecture specific, but
+.\" all architectures do it this way. Should seccomp enforce
+.\" val == 0 when err != 0 ?
+.\"
+.\" Christian Brauner
+.\"
+.\" Feels like it should, at least for the SEND ioctl where we already
+.\" verify that val and err are both 0 when CONTINUE is specified (as you
+.\" pointed out correctly above).
+.RE
+.PP
+On success, this operation returns 0; on failure, \-1 is returned, and
+.I errno
+is set to indicate the cause of the error.
+This operation can fail with the following errors:
+.TP
+.B EINPROGRESS
+A response to this notification has already been sent.
+.TP
+.B EINVAL
+An invalid value was specified in the
+.I flags field.
+.TP
+.B
+.B EINVAL
+The
+.I flags
+field contained
+.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE ,
+and the
+.I error
+or
+.I val
+field was not zero.
+.TP
+.B ENOENT
+The blocked system call in the target
+has been interrupted by a signal handler
+or the target has terminated.
+.\" Jann Horn notes:
+.\" you could also get this [ENOENT] if a response has already
+.\" been sent, instead of EINPROGRESS - the only difference is
+.\" whether the target thread has picked up the response yet
+.\"
+.SS SECCOMP_IOCTL_NOTIF_ADDFD
+The
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+operation (available since Linux 5.9)
+allows the supervisor to install a file descriptor
+into the target's file descriptor table.
+Much like the use of
+.B SCM_RIGHTS
+messages described in
+.BR unix (7),
+this operation is semantically equivalent to duplicating
+a file descriptor from the supervisor's file descriptor table
+into the target's file descriptor table.
+.PP
+The
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+operation permits the supervisor to emulate a target system call (such as
+.BR socket (2)
+or
+.BR openat (2))
+that generates a file descriptor.
+The supervisor can perform the system call that generates
+the file descriptor (and associated open file description)
+and then use this operation to allocate
+a file descriptor that refers to the same open file description in the target.
+(For an explanation of open file descriptions, see
+.BR open (2).)
+.PP
+Once this operation has been performed,
+the supervisor can close its copy of the file descriptor.
+.PP
+In the target,
+the received file descriptor is subject to the same
+Linux Security Module (LSM) checks as are applied to a file descriptor
+that is received in an
+.B SCM_RIGHTS
+ancillary message.
+If the file descriptor refers to a socket,
+it inherits the cgroup version 1 network controller settings
+.RI ( classid
+and
+.IR netprioidx )
+of the target.
+.PP
+The third
+.BR ioctl (2)
+argument is a pointer to a structure of the following form:
+.PP
+.in +4n
+.EX
+struct seccomp_notif_addfd {
+ __u64 id; /* Cookie value */
+ __u32 flags; /* Flags */
+ __u32 srcfd; /* Local file descriptor number */
+ __u32 newfd; /* 0 or desired file descriptor
+ number in target */
+ __u32 newfd_flags; /* Flags to set on target file
+ descriptor */
+};
+.EE
+.in
+.PP
+The fields in this structure are as follows:
+.TP
+.I id
+This field should be set to the notification ID
+(cookie value) that was obtained via
+.BR SECCOMP_IOCTL_NOTIF_RECV .
+.TP
+.I flags
+This field is a bit mask of flags that modify the behavior of the operation.
+Currently, only one flag is supported:
+.RS
+.TP
+.B SECCOMP_ADDFD_FLAG_SETFD
+When allocating the file descriptor in the target,
+use the file descriptor number specified in the
+.I newfd
+field.
+.TP
+.BR SECCOMP_ADDFD_FLAG_SEND " (since Linux 5.14)"
+.\" commit 0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c
+Perform the equivalent of
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+plus
+.B SECCOMP_IOCTL_NOTIF_SEND
+as an atomic operation.
+On successful invocation, the target process's
+.I errno
+will be 0
+and the return value will be the file descriptor number
+that was allocated in the target.
+If allocating the file descriptor in the target fails,
+the target's system call continues to be blocked
+until a successful response is sent.
+.RE
+.TP
+.I srcfd
+This field should be set to the number of the file descriptor
+in the supervisor that is to be duplicated.
+.TP
+.I newfd
+This field determines which file descriptor number is allocated in the target.
+If the
+.B SECCOMP_ADDFD_FLAG_SETFD
+flag is set,
+then this field specifies which file descriptor number should be allocated.
+If this file descriptor number is already open in the target,
+it is atomically closed and reused.
+If the descriptor duplication fails due to an LSM check, or if
+.I srcfd
+is not a valid file descriptor,
+the file descriptor
+.I newfd
+will not be closed in the target process.
+.IP
+If the
+.B SECCOMP_ADDFD_FLAG_SETFD
+flag it not set, then this field must be 0,
+and the kernel allocates the lowest unused file descriptor number
+in the target.
+.TP
+.I newfd_flags
+This field is a bit mask specifying flags that should be set on
+the file descriptor that is received in the target process.
+Currently, only the following flag is implemented:
+.RS
+.TP
+.B O_CLOEXEC
+Set the close-on-exec flag on the received file descriptor.
+.RE
+.PP
+On success, this
+.BR ioctl (2)
+call returns the number of the file descriptor that was allocated
+in the target.
+Assuming that the emulated system call is one that returns
+a file descriptor as its function result (e.g.,
+.BR socket (2)),
+this value can be used as the return value
+.RI ( resp.val )
+that is supplied in the response that is subsequently sent with the
+.B SECCOMP_IOCTL_NOTIF_SEND
+operation.
+.PP
+On error, \-1 is returned and
+.I errno
+is set to indicate the cause of the error.
+.PP
+This operation can fail with the following errors:
+.TP
+.B EBADF
+Allocating the file descriptor in the target would cause the target's
+.B RLIMIT_NOFILE
+limit to be exceeded (see
+.BR getrlimit (2)).
+.TP
+.B EBUSY
+If the flag
+.B SECCOMP_IOCTL_NOTIF_SEND
+is used, this means the operation can't proceed until other
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+requests are processed.
+.TP
+.B EINPROGRESS
+The user-space notification specified in the
+.I id
+field exists but has not yet been fetched (by a
+.BR SECCOMP_IOCTL_NOTIF_RECV )
+or has already been responded to (by a
+.BR SECCOMP_IOCTL_NOTIF_SEND ).
+.TP
+.B EINVAL
+An invalid flag was specified in the
+.I flags
+or
+.I newfd_flags
+field, or the
+.I newfd
+field is nonzero and the
+.B SECCOMP_ADDFD_FLAG_SETFD
+flag was not specified in the
+.I flags
+field.
+.TP
+.B EMFILE
+The file descriptor number specified in
+.I newfd
+exceeds the limit specified in
+.IR /proc/sys/fs/nr_open .
+.TP
+.B ENOENT
+The blocked system call in the target
+has been interrupted by a signal handler
+or the target has terminated.
+.PP
+Here is some sample code (with error handling omitted) that uses the
+.B SECCOMP_ADDFD_FLAG_SETFD
+operation (here, to emulate a call to
+.BR openat (2)):
+.PP
+.EX
+.in +4n
+int fd, removeFd;
+\&
+fd = openat(req\->data.args[0], path, req\->data.args[2],
+ req\->data.args[3]);
+\&
+struct seccomp_notif_addfd addfd;
+addfd.id = req\->id; /* Cookie from SECCOMP_IOCTL_NOTIF_RECV */
+addfd.srcfd = fd;
+addfd.newfd = 0;
+addfd.flags = 0;
+addfd.newfd_flags = O_CLOEXEC;
+\&
+targetFd = ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_ADDFD, &addfd);
+\&
+close(fd); /* No longer needed in supervisor */
+\&
+struct seccomp_notif_resp *resp;
+ /* Code to allocate 'resp' omitted */
+resp\->id = req\->id;
+resp\->error = 0; /* "Success" */
+resp\->val = targetFd;
+resp\->flags = 0;
+ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp);
+.in
+.EE
+.SH NOTES
+One example use case for the user-space notification
+mechanism is to allow a container manager
+(a process which is typically running with more privilege than
+the processes inside the container)
+to mount block devices or create device nodes for the container.
+The mount use case provides an example of where the
+.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
+.BR ioctl (2)
+operation is useful.
+Upon receiving a notification for the
+.BR mount (2)
+system call, the container manager (the "supervisor") can distinguish
+a request to mount a block filesystem
+(which would not be possible for a "target" process inside the container)
+and mount that file system.
+If, on the other hand, the container manager detects that the operation
+could be performed by the process inside the container
+(e.g., a mount of a
+.BR tmpfs (5)
+filesystem), it can notify the kernel that the target process's
+.BR mount (2)
+system call can continue.
+.\"
+.SS select()/poll()/epoll semantics
+The file descriptor returned when
+.BR seccomp (2)
+is employed with the
+.B SECCOMP_FILTER_FLAG_NEW_LISTENER
+flag can be monitored using
+.BR poll (2),
+.BR epoll (7),
+and
+.BR select (2).
+These interfaces indicate that the file descriptor is ready as follows:
+.IP \[bu] 3
+When a notification is pending,
+these interfaces indicate that the file descriptor is readable.
+Following such an indication, a subsequent
+.B SECCOMP_IOCTL_NOTIF_RECV
+.BR ioctl (2)
+will not block, returning either information about a notification
+or else failing with the error
+.B EINTR
+if the target has been killed by a signal or its system call
+has been interrupted by a signal handler.
+.IP \[bu]
+After the notification has been received (i.e., by the
+.B SECCOMP_IOCTL_NOTIF_RECV
+.BR ioctl (2)
+operation), these interfaces indicate that the file descriptor is writable,
+meaning that a notification response can be sent using the
+.B SECCOMP_IOCTL_NOTIF_SEND
+.BR ioctl (2)
+operation.
+.IP \[bu]
+After the last thread using the filter has terminated and been reaped using
+.BR waitpid (2)
+(or similar),
+the file descriptor indicates an end-of-file condition (readable in
+.BR select (2);
+.BR POLLHUP / EPOLLHUP
+in
+.BR poll (2)/
+.BR epoll_wait (2)).
+.SS Design goals; use of SECCOMP_USER_NOTIF_FLAG_CONTINUE
+The intent of the user-space notification feature is
+to allow system calls to be performed on behalf of the target.
+The target's system call should either be handled by the supervisor or
+allowed to continue normally in the kernel (where standard security
+policies will be applied).
+.PP
+.BR "Note well" :
+this mechanism must not be used to make security policy decisions
+about the system call,
+which would be inherently race-prone for reasons described next.
+.PP
+The
+.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
+flag must be used with caution.
+If set by the supervisor, the target's system call will continue.
+However, there is a time-of-check, time-of-use race here,
+since an attacker could exploit the interval of time where the target is
+blocked waiting on the "continue" response to do things such as
+rewriting the system call arguments.
+.PP
+Note furthermore that a user-space notifier can be bypassed if
+the existing filters allow the use of
+.BR seccomp (2)
+or
+.BR prctl (2)
+to install a filter that returns an action value with a higher precedence than
+.B SECCOMP_RET_USER_NOTIF
+(see
+.BR seccomp (2)).
+.PP
+It should thus be absolutely clear that the
+seccomp user-space notification mechanism
+.B can not
+be used to implement a security policy!
+It should only ever be used in scenarios where a more privileged process
+supervises the system calls of a lesser privileged target to
+get around kernel-enforced security restrictions when
+the supervisor deems this safe.
+In other words,
+in order to continue a system call, the supervisor should be sure that
+another security mechanism or the kernel itself will sufficiently block
+the system call if its arguments are rewritten to something unsafe.
+.\"
+.SS Caveats regarding the use of \fI/proc/\fPtid\fI/mem\fP
+The discussion above noted the need to use the
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+.BR ioctl (2)
+when opening the
+.IR /proc/ tid /mem
+file of the target
+to avoid the possibility of accessing the memory of the wrong process
+in the event that the target terminates and its ID
+is recycled by another (unrelated) thread.
+However, the use of this
+.BR ioctl (2)
+operation is also necessary in other situations,
+as explained in the following paragraphs.
+.PP
+Consider the following scenario, where the supervisor
+tries to read the pathname argument of a target's blocked
+.BR mount (2)
+system call:
+.IP (1) 5
+From one of its functions
+.RI ( func() ),
+the target calls
+.BR mount (2),
+which triggers a user-space notification and causes the target to block.
+.IP (2)
+The supervisor receives the notification, opens
+.IR /proc/ tid /mem ,
+and (successfully) performs the
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+check.
+.IP (3)
+The target receives a signal, which causes the
+.BR mount (2)
+to abort.
+.IP (4)
+The signal handler executes in the target, and returns.
+.IP (5)
+Upon return from the handler, the execution of
+.I func()
+resumes, and it returns (and perhaps other functions are called,
+overwriting the memory that had been used for the stack frame of
+.IR func() ).
+.IP (6)
+Using the address provided in the notification information,
+the supervisor reads from the target's memory location that used to
+contain the pathname.
+.IP (7)
+The supervisor now calls
+.BR mount (2)
+with some arbitrary bytes obtained in the previous step.
+.PP
+The conclusion from the above scenario is this:
+since the target's blocked system call may be interrupted by a signal handler,
+the supervisor must be written to expect that the
+target may abandon its system call at
+.B any
+time;
+in such an event, any information that the supervisor obtained from
+the target's memory must be considered invalid.
+.PP
+To prevent such scenarios,
+every read from the target's memory must be separated from use of
+the bytes so obtained by a
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+check.
+In the above example, the check would be placed between the two final steps.
+An example of such a check is shown in EXAMPLES.
+.PP
+Following on from the above, it should be clear that
+a write by the supervisor into the target's memory can
+.B never
+be considered safe.
+.\"
+.SS Caveats regarding blocking system calls
+Suppose that the target performs a blocking system call (e.g.,
+.BR accept (2))
+that the supervisor should handle.
+The supervisor might then in turn execute the same blocking system call.
+.PP
+In this scenario,
+it is important to note that if the target's system call is now
+interrupted by a signal, the supervisor is
+.I not
+informed of this.
+If the supervisor does not take suitable steps to
+actively discover that the target's system call has been canceled,
+various difficulties can occur.
+Taking the example of
+.BR accept (2),
+the supervisor might remain blocked in its
+.BR accept (2)
+holding a port number that the target
+(which, after the interruption by the signal handler,
+perhaps closed its listening socket) might expect to be able to reuse in a
+.BR bind (2)
+call.
+.PP
+Therefore, when the supervisor wishes to emulate a blocking system call,
+it must do so in such a way that it gets informed if the target's
+system call is interrupted by a signal handler.
+For example, if the supervisor itself executes the same
+blocking system call, then it could employ a separate thread
+that uses the
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
+operation to check if the target is still blocked in its system call.
+Alternatively, in the
+.BR accept (2)
+example, the supervisor might use
+.BR poll (2)
+to monitor both the notification file descriptor
+(so as to discover when the target's
+.BR accept (2)
+call has been interrupted) and the listening file descriptor
+(so as to know when a connection is available).
+.PP
+If the target's system call is interrupted,
+the supervisor must take care to release resources (e.g., file descriptors)
+that it acquired on behalf of the target.
+.\"
+.SS Interaction with SA_RESTART signal handlers
+Consider the following scenario:
+.IP (1) 5
+The target process has used
+.BR sigaction (2)
+to install a signal handler with the
+.B SA_RESTART
+flag.
+.IP (2)
+The target has made a system call that triggered a seccomp
+user-space notification and the target is currently blocked
+until the supervisor sends a notification response.
+.IP (3)
+A signal is delivered to the target and the signal handler is executed.
+.IP (4)
+When (if) the supervisor attempts to send a notification response, the
+.B SECCOMP_IOCTL_NOTIF_SEND
+.BR ioctl (2))
+operation will fail with the
+.B ENOENT
+error.
+.PP
+In this scenario, the kernel will restart the target's system call.
+Consequently, the supervisor will receive another user-space notification.
+Thus, depending on how many times the blocked system call
+is interrupted by a signal handler,
+the supervisor may receive multiple notifications for
+the same instance of a system call in the target.
+.PP
+One oddity is that system call restarting as described in this scenario
+will occur even for the blocking system calls listed in
+.BR signal (7)
+that would
+.B never
+normally be restarted by the
+.B SA_RESTART
+flag.
+.\" FIXME
+.\" About the above, Kees Cook commented:
+.\"
+.\" Does this need fixing? I imagine the correct behavior for this case
+.\" would be a response to _SEND of EINPROGRESS and the target would see
+.\" EINTR normally?
+.\"
+.\" I mean, it's not like seccomp doesn't already expose weirdness with
+.\" syscall restarts. Not even arm64 compat agrees[3] with arm32 in this
+.\" regard. :(
+.
+.\" FIXME
+.\" Michael Kerrisk:
+.\" I wonder about the effect of this oddity for system calls that
+.\" are normally nonrestartable because they have timeouts. My
+.\" understanding is that the kernel doesn't restart those system
+.\" calls because it's impossible for the kernel to restart the call
+.\" with the right timeout value. I wonder what happens when those
+.\" system calls are restarted in the scenario we're discussing.)
+.PP
+Furthermore, if the supervisor response is a file descriptor
+added with
+.BR SECCOMP_IOCTL_NOTIF_ADDFD ,
+then the flag
+.B SECCOMP_ADDFD_FLAG_SEND
+can be used to atomically add the file descriptor and return that value,
+making sure no file descriptors are inadvertently leaked into the target.
+.SH BUGS
+If a
+.B SECCOMP_IOCTL_NOTIF_RECV
+.BR ioctl (2)
+operation
+.\" or a poll/epoll/select
+is performed after the target terminates, then the
+.BR ioctl (2)
+call simply blocks (rather than returning an error to indicate that the
+target no longer exists).
+.\" FIXME
+.\" Comment from Kees Cook:
+.\"
+.\" I want this fixed. It caused me no end of pain when building the
+.\" selftests, and ended up spawning my implementing a global test timeout
+.\" in kselftest. :P Before the usage counter refactor, there was no sane
+.\" way to deal with this, but now I think we're close.
+.\"
+.SH EXAMPLES
+The (somewhat contrived) program shown below demonstrates the use of
+the interfaces described in this page.
+The program creates a child process that serves as the "target" process.
+The child process installs a seccomp filter that returns the
+.B SECCOMP_RET_USER_NOTIF
+action value if a call is made to
+.BR mkdir (2).
+The child process then calls
+.BR mkdir (2)
+once for each of the supplied command-line arguments,
+and reports the result returned by the call.
+After processing all arguments, the child process terminates.
+.PP
+The parent process acts as the supervisor, listening for the notifications
+that are generated when the target process calls
+.BR mkdir (2).
+When such a notification occurs,
+the supervisor examines the memory of the target process (using
+.IR /proc/ pid /mem )
+to discover the pathname argument that was supplied to the
+.BR mkdir (2)
+call, and performs one of the following actions:
+.IP \[bu] 3
+If the pathname begins with the prefix "/tmp/",
+then the supervisor attempts to create the specified directory,
+and then spoofs a return for the target process based on the return
+value of the supervisor's
+.BR mkdir (2)
+call.
+In the event that that call succeeds,
+the spoofed success return value is the length of the pathname.
+.IP \[bu]
+If the pathname begins with "./" (i.e., it is a relative pathname),
+the supervisor sends a
+.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
+response to the kernel to say that the kernel should execute
+the target process's
+.BR mkdir (2)
+call.
+.IP \[bu]
+If the pathname begins with some other prefix,
+the supervisor spoofs an error return for the target process,
+so that the target process's
+.BR mkdir (2)
+call appears to fail with the error
+.B EOPNOTSUPP
+("Operation not supported").
+Additionally, if the specified pathname is exactly "/bye",
+then the supervisor terminates.
+.PP
+This program can be used to demonstrate various aspects of the
+behavior of the seccomp user-space notification mechanism.
+To help aid such demonstrations,
+the program logs various messages to show the operation
+of the target process (lines prefixed "T:") and the supervisor
+(indented lines prefixed "S:").
+.PP
+In the following example, the target attempts to create the directory
+.IR /tmp/x .
+Upon receiving the notification, the supervisor creates the directory on the
+target's behalf,
+and spoofs a success return to be received by the target process's
+.BR mkdir (2)
+call.
+.PP
+.in +4n
+.EX
+$ \fB./seccomp_unotify /tmp/x\fP
+T: PID = 23168
+\&
+T: about to mkdir("/tmp/x")
+ S: got notification (ID 0x17445c4a0f4e0e3c) for PID 23168
+ S: executing: mkdir("/tmp/x", 0700)
+ S: success! spoofed return = 6
+ S: sending response (flags = 0; val = 6; error = 0)
+T: SUCCESS: mkdir(2) returned 6
+\&
+T: terminating
+ S: target has terminated; bye
+.EE
+.in
+.PP
+In the above output, note that the spoofed return value seen by the target
+process is 6 (the length of the pathname
+.IR /tmp/x ),
+whereas a normal
+.BR mkdir (2)
+call returns 0 on success.
+.PP
+In the next example, the target attempts to create a directory using the
+relative pathname
+.IR ./sub .
+Since this pathname starts with "./",
+the supervisor sends a
+.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
+response to the kernel,
+and the kernel then (successfully) executes the target process's
+.BR mkdir (2)
+call.
+.PP
+.in +4n
+.EX
+$ \fB./seccomp_unotify ./sub\fP
+T: PID = 23204
+\&
+T: about to mkdir("./sub")
+ S: got notification (ID 0xddb16abe25b4c12) for PID 23204
+ S: target can execute system call
+ S: sending response (flags = 0x1; val = 0; error = 0)
+T: SUCCESS: mkdir(2) returned 0
+\&
+T: terminating
+ S: target has terminated; bye
+.EE
+.in
+.PP
+If the target process attempts to create a directory with
+a pathname that doesn't start with "." and doesn't begin with the prefix
+"/tmp/", then the supervisor spoofs an error return
+.RB ( EOPNOTSUPP ,
+"Operation not supported")
+for the target's
+.BR mkdir (2)
+call (which is not executed):
+.PP
+.in +4n
+.EX
+$ \fB./seccomp_unotify /xxx\fP
+T: PID = 23178
+\&
+T: about to mkdir("/xxx")
+ S: got notification (ID 0xe7dc095d1c524e80) for PID 23178
+ S: spoofing error response (Operation not supported)
+ S: sending response (flags = 0; val = 0; error = \-95)
+T: ERROR: mkdir(2): Operation not supported
+\&
+T: terminating
+ S: target has terminated; bye
+.EE
+.in
+.PP
+In the next example,
+the target process attempts to create a directory with the pathname
+.BR /tmp/nosuchdir/b .
+Upon receiving the notification,
+the supervisor attempts to create that directory, but the
+.BR mkdir (2)
+call fails because the directory
+.B /tmp/nosuchdir
+does not exist.
+Consequently, the supervisor spoofs an error return that passes the error
+that it received back to the target process's
+.BR mkdir (2)
+call.
+.PP
+.in +4n
+.EX
+$ \fB./seccomp_unotify /tmp/nosuchdir/b\fP
+T: PID = 23199
+\&
+T: about to mkdir("/tmp/nosuchdir/b")
+ S: got notification (ID 0x8744454293506046) for PID 23199
+ S: executing: mkdir("/tmp/nosuchdir/b", 0700)
+ S: failure! (errno = 2; No such file or directory)
+ S: sending response (flags = 0; val = 0; error = \-2)
+T: ERROR: mkdir(2): No such file or directory
+\&
+T: terminating
+ S: target has terminated; bye
+.EE
+.in
+.PP
+If the supervisor receives a notification and sees that the
+argument of the target's
+.BR mkdir (2)
+is the string "/bye", then (as well as spoofing an
+.B EOPNOTSUPP
+error), the supervisor terminates.
+If the target process subsequently executes another
+.BR mkdir (2)
+that triggers its seccomp filter to return the
+.B SECCOMP_RET_USER_NOTIF
+action value, then the kernel causes the target process's system call to
+fail with the error
+.B ENOSYS
+("Function not implemented").
+This is demonstrated by the following example:
+.PP
+.in +4n
+.EX
+$ \fB./seccomp_unotify /bye /tmp/y\fP
+T: PID = 23185
+\&
+T: about to mkdir("/bye")
+ S: got notification (ID 0xa81236b1d2f7b0f4) for PID 23185
+ S: spoofing error response (Operation not supported)
+ S: sending response (flags = 0; val = 0; error = \-95)
+ S: terminating **********
+T: ERROR: mkdir(2): Operation not supported
+\&
+T: about to mkdir("/tmp/y")
+T: ERROR: mkdir(2): Function not implemented
+\&
+T: terminating
+.EE
+.in
+.\"
+.SS Program source
+.\" SRC BEGIN (seccomp_unotify.c)
+.EX
+#define _GNU_SOURCE
+#include <err.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <limits.h>
+#include <linux/audit.h>
+#include <linux/filter.h>
+#include <linux/seccomp.h>
+#include <signal.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/prctl.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/syscall.h>
+#include <sys/types.h>
+#include <sys/un.h>
+#include <unistd.h>
+\&
+#define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0]))
+\&
+/* Send the file descriptor \[aq]fd\[aq] over the connected UNIX domain socket
+ \[aq]sockfd\[aq]. Returns 0 on success, or \-1 on error. */
+\&
+static int
+sendfd(int sockfd, int fd)
+{
+ int data;
+ struct iovec iov;
+ struct msghdr msgh;
+ struct cmsghdr *cmsgp;
+\&
+ /* Allocate a char array of suitable size to hold the ancillary data.
+ However, since this buffer is in reality a \[aq]struct cmsghdr\[aq], use a
+ union to ensure that it is suitably aligned. */
+ union {
+ char buf[CMSG_SPACE(sizeof(int))];
+ /* Space large enough to hold an \[aq]int\[aq] */
+ struct cmsghdr align;
+ } controlMsg;
+\&
+ /* The \[aq]msg_name\[aq] field can be used to specify the address of the
+ destination socket when sending a datagram. However, we do not
+ need to use this field because \[aq]sockfd\[aq] is a connected socket. */
+\&
+ msgh.msg_name = NULL;
+ msgh.msg_namelen = 0;
+\&
+ /* On Linux, we must transmit at least one byte of real data in
+ order to send ancillary data. We transmit an arbitrary integer
+ whose value is ignored by recvfd(). */
+\&
+ msgh.msg_iov = &iov;
+ msgh.msg_iovlen = 1;
+ iov.iov_base = &data;
+ iov.iov_len = sizeof(int);
+ data = 12345;
+\&
+ /* Set \[aq]msghdr\[aq] fields that describe ancillary data */
+\&
+ msgh.msg_control = controlMsg.buf;
+ msgh.msg_controllen = sizeof(controlMsg.buf);
+\&
+ /* Set up ancillary data describing file descriptor to send */
+\&
+ cmsgp = CMSG_FIRSTHDR(&msgh);
+ cmsgp\->cmsg_level = SOL_SOCKET;
+ cmsgp\->cmsg_type = SCM_RIGHTS;
+ cmsgp\->cmsg_len = CMSG_LEN(sizeof(int));
+ memcpy(CMSG_DATA(cmsgp), &fd, sizeof(int));
+\&
+ /* Send real plus ancillary data */
+\&
+ if (sendmsg(sockfd, &msgh, 0) == \-1)
+ return \-1;
+\&
+ return 0;
+}
+\&
+/* Receive a file descriptor on a connected UNIX domain socket. Returns
+ the received file descriptor on success, or \-1 on error. */
+\&
+static int
+recvfd(int sockfd)
+{
+ int data, fd;
+ ssize_t nr;
+ struct iovec iov;
+ struct msghdr msgh;
+\&
+ /* Allocate a char buffer for the ancillary data. See the comments
+ in sendfd() */
+ union {
+ char buf[CMSG_SPACE(sizeof(int))];
+ struct cmsghdr align;
+ } controlMsg;
+ struct cmsghdr *cmsgp;
+\&
+ /* The \[aq]msg_name\[aq] field can be used to obtain the address of the
+ sending socket. However, we do not need this information. */
+\&
+ msgh.msg_name = NULL;
+ msgh.msg_namelen = 0;
+\&
+ /* Specify buffer for receiving real data */
+\&
+ msgh.msg_iov = &iov;
+ msgh.msg_iovlen = 1;
+ iov.iov_base = &data; /* Real data is an \[aq]int\[aq] */
+ iov.iov_len = sizeof(int);
+\&
+ /* Set \[aq]msghdr\[aq] fields that describe ancillary data */
+\&
+ msgh.msg_control = controlMsg.buf;
+ msgh.msg_controllen = sizeof(controlMsg.buf);
+\&
+ /* Receive real plus ancillary data; real data is ignored */
+\&
+ nr = recvmsg(sockfd, &msgh, 0);
+ if (nr == \-1)
+ return \-1;
+\&
+ cmsgp = CMSG_FIRSTHDR(&msgh);
+\&
+ /* Check the validity of the \[aq]cmsghdr\[aq] */
+\&
+ if (cmsgp == NULL
+ || cmsgp\->cmsg_len != CMSG_LEN(sizeof(int))
+ || cmsgp\->cmsg_level != SOL_SOCKET
+ || cmsgp\->cmsg_type != SCM_RIGHTS)
+ {
+ errno = EINVAL;
+ return \-1;
+ }
+\&
+ /* Return the received file descriptor to our caller */
+\&
+ memcpy(&fd, CMSG_DATA(cmsgp), sizeof(int));
+ return fd;
+}
+\&
+static void
+sigchldHandler(int sig)
+{
+ char msg[] = "\etS: target has terminated; bye\en";
+\&
+ write(STDOUT_FILENO, msg, sizeof(msg) \- 1);
+ _exit(EXIT_SUCCESS);
+}
+\&
+static int
+seccomp(unsigned int operation, unsigned int flags, void *args)
+{
+ return syscall(SYS_seccomp, operation, flags, args);
+}
+\&
+/* The following is the x86\-64\-specific BPF boilerplate code for checking
+ that the BPF program is running on the right architecture + ABI. At
+ completion of these instructions, the accumulator contains the system
+ call number. */
+\&
+/* For the x32 ABI, all system call numbers have bit 30 set */
+\&
+#define X32_SYSCALL_BIT 0x40000000
+\&
+#define X86_64_CHECK_ARCH_AND_LOAD_SYSCALL_NR \e
+ BPF_STMT(BPF_LD | BPF_W | BPF_ABS, \e
+ (offsetof(struct seccomp_data, arch))), \e
+ BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, AUDIT_ARCH_X86_64, 0, 2), \e
+ BPF_STMT(BPF_LD | BPF_W | BPF_ABS, \e
+ (offsetof(struct seccomp_data, nr))), \e
+ BPF_JUMP(BPF_JMP | BPF_JGE | BPF_K, X32_SYSCALL_BIT, 0, 1), \e
+ BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS)
+\&
+/* installNotifyFilter() installs a seccomp filter that generates
+ user\-space notifications (SECCOMP_RET_USER_NOTIF) when the process
+ calls mkdir(2); the filter allows all other system calls.
+\&
+ The function return value is a file descriptor from which the
+ user\-space notifications can be fetched. */
+\&
+static int
+installNotifyFilter(void)
+{
+ int notifyFd;
+\&
+ struct sock_filter filter[] = {
+ X86_64_CHECK_ARCH_AND_LOAD_SYSCALL_NR,
+\&
+ /* mkdir() triggers notification to user\-space supervisor */
+\&
+ BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, SYS_mkdir, 0, 1),
+ BPF_STMT(BPF_RET + BPF_K, SECCOMP_RET_USER_NOTIF),
+\&
+ /* Every other system call is allowed */
+\&
+ BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW),
+ };
+\&
+ struct sock_fprog prog = {
+ .len = ARRAY_SIZE(filter),
+ .filter = filter,
+ };
+\&
+ /* Install the filter with the SECCOMP_FILTER_FLAG_NEW_LISTENER flag;
+ as a result, seccomp() returns a notification file descriptor. */
+\&
+ notifyFd = seccomp(SECCOMP_SET_MODE_FILTER,
+ SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog);
+ if (notifyFd == \-1)
+ err(EXIT_FAILURE, "seccomp\-install\-notify\-filter");
+\&
+ return notifyFd;
+}
+\&
+/* Close a pair of sockets created by socketpair() */
+\&
+static void
+closeSocketPair(int sockPair[2])
+{
+ if (close(sockPair[0]) == \-1)
+ err(EXIT_FAILURE, "closeSocketPair\-close\-0");
+ if (close(sockPair[1]) == \-1)
+ err(EXIT_FAILURE, "closeSocketPair\-close\-1");
+}
+\&
+/* Implementation of the target process; create a child process that:
+\&
+ (1) installs a seccomp filter with the
+ SECCOMP_FILTER_FLAG_NEW_LISTENER flag;
+ (2) writes the seccomp notification file descriptor returned from
+ the previous step onto the UNIX domain socket, \[aq]sockPair[0]\[aq];
+ (3) calls mkdir(2) for each element of \[aq]argv\[aq].
+\&
+ The function return value in the parent is the PID of the child
+ process; the child does not return from this function. */
+\&
+static pid_t
+targetProcess(int sockPair[2], char *argv[])
+{
+ int notifyFd, s;
+ pid_t targetPid;
+\&
+ targetPid = fork();
+\&
+ if (targetPid == \-1)
+ err(EXIT_FAILURE, "fork");
+\&
+ if (targetPid > 0) /* In parent, return PID of child */
+ return targetPid;
+\&
+ /* Child falls through to here */
+\&
+ printf("T: PID = %ld\en", (long) getpid());
+\&
+ /* Install seccomp filter(s) */
+\&
+ if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0))
+ err(EXIT_FAILURE, "prctl");
+\&
+ notifyFd = installNotifyFilter();
+\&
+ /* Pass the notification file descriptor to the tracing process over
+ a UNIX domain socket */
+\&
+ if (sendfd(sockPair[0], notifyFd) == \-1)
+ err(EXIT_FAILURE, "sendfd");
+\&
+ /* Notification and socket FDs are no longer needed in target */
+\&
+ if (close(notifyFd) == \-1)
+ err(EXIT_FAILURE, "close\-target\-notify\-fd");
+\&
+ closeSocketPair(sockPair);
+\&
+ /* Perform a mkdir() call for each of the command\-line arguments */
+\&
+ for (char **ap = argv; *ap != NULL; ap++) {
+ printf("\enT: about to mkdir(\e"%s\e")\en", *ap);
+\&
+ s = mkdir(*ap, 0700);
+ if (s == \-1)
+ perror("T: ERROR: mkdir(2)");
+ else
+ printf("T: SUCCESS: mkdir(2) returned %d\en", s);
+ }
+\&
+ printf("\enT: terminating\en");
+ exit(EXIT_SUCCESS);
+}
+\&
+/* Check that the notification ID provided by a SECCOMP_IOCTL_NOTIF_RECV
+ operation is still valid. It will no longer be valid if the target
+ process has terminated or is no longer blocked in the system call that
+ generated the notification (because it was interrupted by a signal).
+\&
+ This operation can be used when doing such things as accessing
+ /proc/PID files in the target process in order to avoid TOCTOU race
+ conditions where the PID that is returned by SECCOMP_IOCTL_NOTIF_RECV
+ terminates and is reused by another process. */
+\&
+static bool
+cookieIsValid(int notifyFd, uint64_t id)
+{
+ return ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_ID_VALID, &id) == 0;
+}
+\&
+/* Access the memory of the target process in order to fetch the
+ pathname referred to by the system call argument \[aq]argNum\[aq] in
+ \[aq]req\->data.args[]\[aq]. The pathname is returned in \[aq]path\[aq],
+ a buffer of \[aq]len\[aq] bytes allocated by the caller.
+\&
+ Returns true if the pathname is successfully fetched, and false
+ otherwise. For possible causes of failure, see the comments below. */
+\&
+static bool
+getTargetPathname(struct seccomp_notif *req, int notifyFd,
+ int argNum, char *path, size_t len)
+{
+ int procMemFd;
+ char procMemPath[PATH_MAX];
+ ssize_t nread;
+\&
+ snprintf(procMemPath, sizeof(procMemPath), "/proc/%d/mem", req\->pid);
+\&
+ procMemFd = open(procMemPath, O_RDONLY | O_CLOEXEC);
+ if (procMemFd == \-1)
+ return false;
+\&
+ /* Check that the process whose info we are accessing is still alive
+ and blocked in the system call that caused the notification.
+ If the SECCOMP_IOCTL_NOTIF_ID_VALID operation (performed in
+ cookieIsValid()) succeeded, we know that the /proc/PID/mem file
+ descriptor that we opened corresponded to the process for which we
+ received a notification. If that process subsequently terminates,
+ then read() on that file descriptor will return 0 (EOF). */
+\&
+ if (!cookieIsValid(notifyFd, req\->id)) {
+ close(procMemFd);
+ return false;
+ }
+\&
+ /* Read bytes at the location containing the pathname argument */
+\&
+ nread = pread(procMemFd, path, len, req\->data.args[argNum]);
+\&
+ close(procMemFd);
+\&
+ if (nread <= 0)
+ return false;
+\&
+ /* Once again check that the notification ID is still valid. The
+ case we are particularly concerned about here is that just
+ before we fetched the pathname, the target\[aq]s blocked system
+ call was interrupted by a signal handler, and after the handler
+ returned, the target carried on execution (past the interrupted
+ system call). In that case, we have no guarantees about what we
+ are reading, since the target\[aq]s memory may have been arbitrarily
+ changed by subsequent operations. */
+\&
+ if (!cookieIsValid(notifyFd, req\->id)) {
+ perror("\etS: notification ID check failed!!!");
+ return false;
+ }
+\&
+ /* Even if the target\[aq]s system call was not interrupted by a signal,
+ we have no guarantees about what was in the memory of the target
+ process. (The memory may have been modified by another thread, or
+ even by an external attacking process.) We therefore treat the
+ buffer returned by pread() as untrusted input. The buffer should
+ contain a terminating null byte; if not, then we will trigger an
+ error for the target process. */
+\&
+ if (strnlen(path, nread) < nread)
+ return true;
+\&
+ return false;
+}
+\&
+/* Allocate buffers for the seccomp user\-space notification request and
+ response structures. It is the caller\[aq]s responsibility to free the
+ buffers returned via \[aq]req\[aq] and \[aq]resp\[aq]. */
+\&
+static void
+allocSeccompNotifBuffers(struct seccomp_notif **req,
+ struct seccomp_notif_resp **resp,
+ struct seccomp_notif_sizes *sizes)
+{
+ size_t resp_size;
+\&
+ /* Discover the sizes of the structures that are used to receive
+ notifications and send notification responses, and allocate
+ buffers of those sizes. */
+\&
+ if (seccomp(SECCOMP_GET_NOTIF_SIZES, 0, sizes) == \-1)
+ err(EXIT_FAILURE, "seccomp\-SECCOMP_GET_NOTIF_SIZES");
+\&
+ *req = malloc(sizes\->seccomp_notif);
+ if (*req == NULL)
+ err(EXIT_FAILURE, "malloc\-seccomp_notif");
+\&
+ /* When allocating the response buffer, we must allow for the fact
+ that the user\-space binary may have been built with user\-space
+ headers where \[aq]struct seccomp_notif_resp\[aq] is bigger than the
+ response buffer expected by the (older) kernel. Therefore, we
+ allocate a buffer that is the maximum of the two sizes. This
+ ensures that if the supervisor places bytes into the response
+ structure that are past the response size that the kernel expects,
+ then the supervisor is not touching an invalid memory location. */
+\&
+ resp_size = sizes\->seccomp_notif_resp;
+ if (sizeof(struct seccomp_notif_resp) > resp_size)
+ resp_size = sizeof(struct seccomp_notif_resp);
+\&
+ *resp = malloc(resp_size);
+ if (*resp == NULL)
+ err(EXIT_FAILURE, "malloc\-seccomp_notif_resp");
+\&
+}
+\&
+/* Handle notifications that arrive via the SECCOMP_RET_USER_NOTIF file
+ descriptor, \[aq]notifyFd\[aq]. */
+\&
+static void
+handleNotifications(int notifyFd)
+{
+ bool pathOK;
+ char path[PATH_MAX];
+ struct seccomp_notif *req;
+ struct seccomp_notif_resp *resp;
+ struct seccomp_notif_sizes sizes;
+\&
+ allocSeccompNotifBuffers(&req, &resp, &sizes);
+\&
+ /* Loop handling notifications */
+\&
+ for (;;) {
+\&
+ /* Wait for next notification, returning info in \[aq]*req\[aq] */
+\&
+ memset(req, 0, sizes.seccomp_notif);
+ if (ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_RECV, req) == \-1) {
+ if (errno == EINTR)
+ continue;
+ err(EXIT_FAILURE, "\etS: ioctl\-SECCOMP_IOCTL_NOTIF_RECV");
+ }
+\&
+ printf("\etS: got notification (ID %#llx) for PID %d\en",
+ req\->id, req\->pid);
+\&
+ /* The only system call that can generate a notification event
+ is mkdir(2). Nevertheless, we check that the notified system
+ call is indeed mkdir() as kind of future\-proofing of this
+ code in case the seccomp filter is later modified to
+ generate notifications for other system calls. */
+\&
+ if (req\->data.nr != SYS_mkdir) {
+ printf("\etS: notification contained unexpected "
+ "system call number; bye!!!\en");
+ exit(EXIT_FAILURE);
+ }
+\&
+ pathOK = getTargetPathname(req, notifyFd, 0, path, sizeof(path));
+\&
+ /* Prepopulate some fields of the response */
+\&
+ resp\->id = req\->id; /* Response includes notification ID */
+ resp\->flags = 0;
+ resp\->val = 0;
+\&
+ /* If getTargetPathname() failed, trigger an EINVAL error
+ response (sending this response may yield an error if the
+ failure occurred because the notification ID was no longer
+ valid); if the directory is in /tmp, then create it on behalf
+ of the supervisor; if the pathname starts with \[aq].\[aq], tell the
+ kernel to let the target process execute the mkdir();
+ otherwise, give an error for a directory pathname in any other
+ location. */
+\&
+ if (!pathOK) {
+ resp\->error = \-EINVAL;
+ printf("\etS: spoofing error for invalid pathname (%s)\en",
+ strerror(\-resp\->error));
+ } else if (strncmp(path, "/tmp/", strlen("/tmp/")) == 0) {
+ printf("\etS: executing: mkdir(\e"%s\e", %#llo)\en",
+ path, req\->data.args[1]);
+\&
+ if (mkdir(path, req\->data.args[1]) == 0) {
+ resp\->error = 0; /* "Success" */
+ resp\->val = strlen(path); /* Used as return value of
+ mkdir() in target */
+ printf("\etS: success! spoofed return = %lld\en",
+ resp\->val);
+ } else {
+\&
+ /* If mkdir() failed in the supervisor, pass the error
+ back to the target */
+\&
+ resp\->error = \-errno;
+ printf("\etS: failure! (errno = %d; %s)\en", errno,
+ strerror(errno));
+ }
+ } else if (strncmp(path, "./", strlen("./")) == 0) {
+ resp\->error = resp\->val = 0;
+ resp\->flags = SECCOMP_USER_NOTIF_FLAG_CONTINUE;
+ printf("\etS: target can execute system call\en");
+ } else {
+ resp\->error = \-EOPNOTSUPP;
+ printf("\etS: spoofing error response (%s)\en",
+ strerror(\-resp\->error));
+ }
+\&
+ /* Send a response to the notification */
+\&
+ printf("\etS: sending response "
+ "(flags = %#x; val = %lld; error = %d)\en",
+ resp\->flags, resp\->val, resp\->error);
+\&
+ if (ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp) == \-1) {
+ if (errno == ENOENT)
+ printf("\etS: response failed with ENOENT; "
+ "perhaps target process\[aq]s syscall was "
+ "interrupted by a signal?\en");
+ else
+ perror("ioctl\-SECCOMP_IOCTL_NOTIF_SEND");
+ }
+\&
+ /* If the pathname is just "/bye", then the supervisor breaks out
+ of the loop and terminates. This allows us to see what happens
+ if the target process makes further calls to mkdir(2). */
+\&
+ if (strcmp(path, "/bye") == 0)
+ break;
+ }
+\&
+ free(req);
+ free(resp);
+ printf("\etS: terminating **********\en");
+ exit(EXIT_FAILURE);
+}
+\&
+/* Implementation of the supervisor process:
+\&
+ (1) obtains the notification file descriptor from \[aq]sockPair[1]\[aq]
+ (2) handles notifications that arrive on that file descriptor. */
+\&
+static void
+supervisor(int sockPair[2])
+{
+ int notifyFd;
+\&
+ notifyFd = recvfd(sockPair[1]);
+\&
+ if (notifyFd == \-1)
+ err(EXIT_FAILURE, "recvfd");
+\&
+ closeSocketPair(sockPair); /* We no longer need the socket pair */
+\&
+ handleNotifications(notifyFd);
+}
+\&
+int
+main(int argc, char *argv[])
+{
+ int sockPair[2];
+ struct sigaction sa;
+\&
+ setbuf(stdout, NULL);
+\&
+ if (argc < 2) {
+ fprintf(stderr, "At least one pathname argument is required\en");
+ exit(EXIT_FAILURE);
+ }
+\&
+ /* Create a UNIX domain socket that is used to pass the seccomp
+ notification file descriptor from the target process to the
+ supervisor process. */
+\&
+ if (socketpair(AF_UNIX, SOCK_STREAM, 0, sockPair) == \-1)
+ err(EXIT_FAILURE, "socketpair");
+\&
+ /* Create a child process\-\-the "target"\-\-that installs seccomp
+ filtering. The target process writes the seccomp notification
+ file descriptor onto \[aq]sockPair[0]\[aq] and then calls mkdir(2) for
+ each directory in the command\-line arguments. */
+\&
+ (void) targetProcess(sockPair, &argv[optind]);
+\&
+ /* Catch SIGCHLD when the target terminates, so that the
+ supervisor can also terminate. */
+\&
+ sa.sa_handler = sigchldHandler;
+ sa.sa_flags = 0;
+ sigemptyset(&sa.sa_mask);
+ if (sigaction(SIGCHLD, &sa, NULL) == \-1)
+ err(EXIT_FAILURE, "sigaction");
+\&
+ supervisor(sockPair);
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR ioctl (2),
+.BR pidfd_getfd (2),
+.BR pidfd_open (2),
+.BR seccomp (2)
+.PP
+A further example program can be found in the kernel source file
+.IR samples/seccomp/user-trap.c .