libselinux: add selinux_status_* interfaces for /selinux/status

The attached patch adds several interfaces to reference /selinux/status
according to sequential-lock logic.

selinux_status_open() open the kernel status page and mmap it with
read-only mode, or open netlink socket as a fallback in older kernels.

Then, we can obtain status information from the mmap'ed page using
selinux_status_updated(), selinux_status_getenfoce(),
selinux_status_policyload() or selinux_status_deny_unknown().

It enables to help to implement userspace avc with heavy access control
decision; that we cannot ignore the cost to communicate with kernel for
validation of userspace caches.

Signed-off-by: Steve Lawrence <slawrence@tresys.com>

6 files changed, 101 insertions, 0 deletions

diff --git a/libselinux/man/man3/selinux_status_close.3 b/libselinux/man/man3/selinux_status_close.3
new file mode 100644
index 00000000..52a41690
--- /dev/null
+++ b/libselinux/man/man3/selinux_status_close.3
@@ -0,0 +1 @@
+.so man3/selinux_status_open.3
diff --git a/libselinux/man/man3/selinux_status_deny_unknown.3 b/libselinux/man/man3/selinux_status_deny_unknown.3
new file mode 100644
index 00000000..52a41690
--- /dev/null
+++ b/libselinux/man/man3/selinux_status_deny_unknown.3
@@ -0,0 +1 @@
+.so man3/selinux_status_open.3
diff --git a/libselinux/man/man3/selinux_status_getenforce.3 b/libselinux/man/man3/selinux_status_getenforce.3
new file mode 100644
index 00000000..52a41690
--- /dev/null
+++ b/libselinux/man/man3/selinux_status_getenforce.3
@@ -0,0 +1 @@
+.so man3/selinux_status_open.3
diff --git a/libselinux/man/man3/selinux_status_open.3 b/libselinux/man/man3/selinux_status_open.3
new file mode 100644
index 00000000..e897939e
--- /dev/null
+++ b/libselinux/man/man3/selinux_status_open.3
@@ -0,0 +1,96 @@
+.TH "selinux_status_open" "3" "22 January 2011" "kaigai@ak.jp.nec.com" "SELinux API documentation"
+.SH "NAME"
+selinux_status_open, selinux_status_close, selinux_status_updated,
+selinux_status_getenforce, selinux_status_policyload and
+selinux_status_deny_unknown \- reference the SELinux kernel status
+without invocation of system calls.
+.SH "SYNOPSIS"
+.B #include <selinux/avc.h>
+.sp
+.BI "int selinux_status_open(int " fallback, ");"
+.sp
+.BI "void selinux_status_close(void);"
+.sp
+.BI "int selinux_status_updated(void);"
+.sp
+.BI "int selinux_status_getenforce(void);"
+.sp
+.BI "int selinux_status_policyload(void);"
+.sp
+.BI "int selinux_status_deny_unknown(void);"
+.sp
+.SH "DESCRIPTION"
+Linux 2.6.37 or later provides a SELinux kernel status page; being mostly
+placed on
+.I /selinux/status
+entry. It enables userspace applications to mmap this page with read-only
+mode, then it informs some status without system call invocations.
+.sp
+In some cases that a userspace application tries to apply heavy frequest
+access control; such as row\-level security in databases, it will face
+unignorable cost to communicate with kernel space to check invalidation
+of userspace avc.
+.sp
+These functions provides applications a way to know some kernel events
+without system\-call invocation or worker thread for monitoring.
+.sp
+.BR selinux_status_open
+tries to
+.BR open (2)
+.I /selinux/status
+and
+.BR mmap (2)
+it in read-only mode. The file-descriptor and pointer to the page shall
+be stored internally; Don't touch them directly.
+Set 1 on the
+.I fallback
+argument to handle a case of older kernels without kernel status page support.
+In this case, this function tries to open a netlink socket using
+.BR avc_netlink_open (3)
+and overwrite corresponding callbacks ( setenforce and policyload).
+Thus, we need to pay attention to the interaction with these interfaces,
+when fallback mode is enabled.
+.sp
+.BR selinux_status_close
+unmap the kernel status page and close its file descriptor, or close the
+netlink socket if fallbacked.
+.sp
+.BR selinux_status_updated
+informs us whether something has been updated since the last call.
+It returns 0 if nothing was happened, however, 1 if something has been
+updated in this duration, or -1 on error.
+.sp
+.BR selinux_status_getenforce
+returns 0 if SELinux is running in permissive mode, 1 if enforcing mode,
+or -1 on error.
+Same as
+.BR security_getenforce (3)
+except with or without system call invocation.
+.sp
+.BR selinux_status_policyload
+returns times of policy reloaded on the running system, or -1 on error.
+Note that it is not a reliable value on fallback-mode until it receive
+the first event message via netlink socket.
+Thus, don't use this value to know actual times of policy reloaded.
+.sp
+.BR selinux_status_deny_unknown
+returns 0 if SELinux treats policy queries on undefined object classes or
+permissions as being allowed, 1 if such queries are denied, or -1 on error.
+.sp
+Also note that these interfaces are not thread-safe, so you have to protect
+them from concurrent calls using exclusive locks when multiple threads are
+performing.
+.SH "RETURN VALUE"
+.BR selinux_status_open
+returns 0 or 1 on success. 1 means we are ready to use these interfaces,
+but netlink socket was opened as fallback instead of the kernel status page.
+On error, -1 shall be returned.
+.sp
+Any other functions with a return value shall return its characteristic
+value as described above, or -1 on errors.
+.sp
+.SH "SEE ALSO"
+.BR mmap (2)
+.BR avc_netlink_open (3)
+.BR security_getenforce (3)
+.BR security_deny_unknown (3)
diff --git a/libselinux/man/man3/selinux_status_policyload.3 b/libselinux/man/man3/selinux_status_policyload.3
new file mode 100644
index 00000000..52a41690
--- /dev/null
+++ b/libselinux/man/man3/selinux_status_policyload.3
@@ -0,0 +1 @@
+.so man3/selinux_status_open.3
diff --git a/libselinux/man/man3/selinux_status_updated.3 b/libselinux/man/man3/selinux_status_updated.3
new file mode 100644
index 00000000..52a41690
--- /dev/null
+++ b/libselinux/man/man3/selinux_status_updated.3
@@ -0,0 +1 @@
+.so man3/selinux_status_open.3