diff --git a/doc/man/man3/seccomp_notif_alloc.3 b/doc/man/man3/seccomp_notif_alloc.3 new file mode 100644 index 00000000..806a6bcd --- /dev/null +++ b/doc/man/man3/seccomp_notif_alloc.3 @@ -0,0 +1,105 @@ +.TH "seccomp_notif_alloc" 3 "24 April 2019" "tycho@tycho.ws" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_notif_alloc, seccomp_notif_free, seccomp_notif_receive, +seccomp_notif_send_resp, seccomp_notif_id_valid, seccomp_notif_fd \- Manage seccomp notifications +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include +.sp +.BI "int seccomp_notif_alloc(struct seccomp_notif **" req ", struct seccomp_notif_resp **" resp ")" +.BI "void seccomp_notif_free(struct seccomp_notif *" req ", struct seccomp_notif_resp *" resp ")" +.BI "int seccomp_notif_receive(int " fd ", struct seccomp_notif *" req ")" +.BI "int seccomp_notif_send_resp(int " fd ", struct seccomp_notif_resp *" resp ")" +.BI "int seccomp_notif_id_valid(int " fd ", uint64_t " id ")" +.BI "int seccomp_notif_fd(const scmp_filter_ctx " ctx ")" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_notif_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 kerenl how big each structure +should be, and allocates the right amount of memory. The +.BR seccomp_notif_free () +function frees memory allocated by +.BR seccomp_notif_alloc (). +.P +The +.BR seccomp_notif_receive () +function receives a notification from a seccomp notify fd (obtained from +.BR seccomp_notif_fd ()). +.P +The +.BR seccomp_notif_send_resp () +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_notif_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_notif_fd () +returns the notification fd of a filter after it has been loaded. Note that one +must set the +.BR SCMP_FLTATR_NEW_LISTENER +attribute and have loaded the filter, or this function returns an error. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_notif_alloc (), +.BR seccomp_notif_receive (), +and +.BR seccomp_notif_send_resp () +functions all return 0 on success, -1 on failure. +.P +The +.BR seccomp_notif_id_valid () +returns 0 if the id is valid, and -ENOENT if it is not. +.P +The +.BR seccomp_notif_fd () +returns the notification fd of a filter that was loaded with the +.BR SCMP_FLTATR_NEW_LISTENER +attribute set. +.\" ////////////////////////////////////////////////////////////////////////// +.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_notif_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 a +.BR /samples/seccomp/user-trap.c. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Tycho Andersen +.\" ////////////////////////////////////////////////////////////////////////// diff --git a/doc/man/man3/seccomp_notif_fd.3 b/doc/man/man3/seccomp_notif_fd.3 new file mode 100644 index 00000000..214ce0f0 --- /dev/null +++ b/doc/man/man3/seccomp_notif_fd.3 @@ -0,0 +1 @@ +.so man3/seccomp_notif_alloc.3 diff --git a/doc/man/man3/seccomp_notif_free.3 b/doc/man/man3/seccomp_notif_free.3 new file mode 100644 index 00000000..214ce0f0 --- /dev/null +++ b/doc/man/man3/seccomp_notif_free.3 @@ -0,0 +1 @@ +.so man3/seccomp_notif_alloc.3 diff --git a/doc/man/man3/seccomp_notif_id_valid.3 b/doc/man/man3/seccomp_notif_id_valid.3 new file mode 100644 index 00000000..214ce0f0 --- /dev/null +++ b/doc/man/man3/seccomp_notif_id_valid.3 @@ -0,0 +1 @@ +.so man3/seccomp_notif_alloc.3 diff --git a/doc/man/man3/seccomp_notif_receive.3 b/doc/man/man3/seccomp_notif_receive.3 new file mode 100644 index 00000000..214ce0f0 --- /dev/null +++ b/doc/man/man3/seccomp_notif_receive.3 @@ -0,0 +1 @@ +.so man3/seccomp_notif_alloc.3 diff --git a/doc/man/man3/seccomp_notif_send_resp.3 b/doc/man/man3/seccomp_notif_send_resp.3 new file mode 100644 index 00000000..214ce0f0 --- /dev/null +++ b/doc/man/man3/seccomp_notif_send_resp.3 @@ -0,0 +1 @@ +.so man3/seccomp_notif_alloc.3