fanotify_mark.2, fanotify.7: Document FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM

New event masks have been added to the fanotify API. Documentation to
support the use and behaviour of these new masks has been added
accordingly.

Signed-off-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>
Reviewed-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index a9a482fe7092b132db67461555f7bd73566f6c83..613c86cc49de253758043cf1f7e081f4826d3d8a 100644 (file)
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -149,6 +149,12 @@ Create an event when a read-only file or directory is closed.
 .B FAN_OPEN
 Create an event when a file or directory is opened.
 .TP
+.B FAN_OPEN_EXEC
+Create an event when a file is opened with the intent to be executed.
+See
+.B NOTES
+for additional details.
+.TP
 .B FAN_Q_OVERFLOW
 Create an event when an overflow of the event queue occurs.
 The size of the event queue is limited to 16384 entries if
@@ -164,6 +170,18 @@ or
 .B FAN_CLASS_CONTENT
 is required.
 .TP
+.B FAN_OPEN_EXEC_PERM
+Create an event when a permission to open a file for execution is
+requested.
+An fanotify file descriptor created with
+.B FAN_CLASS_PRE_CONTENT
+or
+.B FAN_CLASS_CONTENT
+is required.
+See
+.B NOTES
+for additional details.
+.TP
 .B FAN_ACCESS_PERM
 Create an event when a permission to read a file or directory is requested.
 An fanotify file descriptor created with
@@ -309,6 +327,48 @@ was introduced in version 2.6.36 of the Linux kernel and enabled in version
 2.6.37.
 .SH CONFORMING TO
 This system call is Linux-specific.
+.SH NOTES
+When using either
+.B FAN_OPEN_EXEC
+or
+.B FAN_OPEN_EXEC_PERM
+within the
+.IR mask ,
+events of these types will only be returned when the direct execution of a
+program occurs.
+More specifically, this means that events of these types shall be generated
+for files that are opened using system calls
+.BR execve(2) ,
+.BR execveat(2) ,
+or
+.BR uselib(2) .
+Events of these types will not be raised in the situation where an
+interpreter reads data as input and subsequently results in arbitrary
+computation.
+.PP
+Additionally, if a mark has also been placed on the Linux dynamic
+linker/loader, a user should also expect to receive an event for it when
+an ELF object has been successfully opened using system calls
+.BR execve(2)
+or
+.BR execveat(2) .
+.PP
+For example, if the following ELF binary were to be invoked and a
+.BR FAN_OPEN_EXEC
+mark has been placed on /:
+.PP
+.EX
+       ~> /bin/echo foo
+.EE
+.PP
+The listening application in this case will receive events
+.BR FAN_OPEN_EXEC
+for both the ELF binary and interpreter, respectively:
+.PP
+.EX
+       /bin/echo
+       /lib64/ld-linux-x86-64.so.2
+.EE
 .SH BUGS
 The following bugs were present in Linux kernels before version 3.16:
 .IP * 3

diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 00e080522a142e2257f6884caa3bca9d4a63bfa6..cc24577356982f4bb9c538efd6d133fffe083730 100644 (file)
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -250,6 +250,14 @@ A file or a directory (but see BUGS) was accessed (read).
 .B FAN_OPEN
 A file or a directory was opened.
 .TP
+.B FAN_OPEN_EXEC
+A file was opened with the intent to be executed.
+See
+.B NOTES
+in
+.BR fanotify_mark (2)
+for additional details.
+.TP
 .B FAN_MODIFY
 A file was modified.
 .TP
@@ -285,6 +293,16 @@ access the filesystem object shall be granted.
 An application wants to open a file or directory.
 The reader must write a response that determines whether the permission to
 open the filesystem object shall be granted.
+.TP
+.B FAN_OPEN_EXEC_PERM
+An application wants to open a file for execution.
+The reader must write a response that determines whether the permission to
+open the filesystem object for execution shall be granted.
+See
+.B NOTES
+in
+.BR fanotify_mark (2)
+for additional details.
 .PP
 To check for any close event, the following bit mask may be used:
 .TP