From 7a0c0b40889175cfc1896aad4202589c38ac9c32 Mon Sep 17 00:00:00 2001
From: Chris PeBenito <cpebenito@tresys.com>
Date: Feb 25 2010 17:59:11 +0000
Subject: Improve documentation on kernel_read_system_state(), kernel_read_network_state(), and kernel_read_proc_symlinks().


---

diff --git a/policy/modules/kernel/kernel.if b/policy/modules/kernel/kernel.if
index 8a970d5..f1fae05 100644
--- a/policy/modules/kernel/kernel.if
+++ b/policy/modules/kernel/kernel.if
@@ -759,13 +759,22 @@ interface(`kernel_getattr_proc_files',`
 
 ########################################
 ## <summary>
-##	Read symbolic links in /proc.
+##	Read generic symbolic links in /proc.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read (follow) generic
+##	symbolic links (symlinks) in the proc filesystem (/proc).
+##	This interface does not include access to the targets of
+##	these links.  An example symlink is /proc/self.
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 #
 interface(`kernel_read_proc_symlinks',`
 	gen_require(`
@@ -777,13 +786,33 @@ interface(`kernel_read_proc_symlinks',`
 
 ########################################
 ## <summary>
-##	Allows caller to read system state information in proc.
+##	Allows caller to read system state information in /proc.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read general system
+##	state information from the proc filesystem (/proc).
+##	</p>
+##	<p>
+##	Generally it should be safe to allow this access.  Some
+##	example files that can be read based on this interface:
+##	</p>
+##	<ul>
+##		<li>/proc/cpuinfo</li>
+##		<li>/proc/meminfo</li>
+##		<li>/proc/uptime</li>
+##	</ul>
+##	<p>
+##	This does not allow access to sysctl entries (/proc/sys/*)
+##	nor process state information (/proc/pid).
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
-##	The process type reading the system state information.
+##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 ## <rolecap/>
 #
 interface(`kernel_read_system_state',`
@@ -1082,13 +1111,24 @@ interface(`kernel_search_network_state',`
 
 ########################################
 ## <summary>
-##	Allow caller to read the network state information.
+##	Read the network state information.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read the networking
+##	state information. This includes several pieces
+##	of networking information, such as network interface
+##	names, netfilter (iptables) statistics, protocol
+##	information, routes, and remote procedure call (RPC)
+##	information.
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
-##	The process type reading the state.
+##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 ## <rolecap/>
 #
 interface(`kernel_read_network_state',`
@@ -1650,13 +1690,35 @@ interface(`kernel_read_crypto_sysctls',`
 
 ########################################
 ## <summary>
-##	Read generic kernel sysctls.
+##	Read general kernel sysctls.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read general
+##	kernel sysctl settings. These settings are typically
+##	read using the sysctl program.  The settings
+##	that are included by this interface are prefixed
+##	with "kernel.", for example, kernel.sysrq.
+##	</p>
+##	<p>
+##	This does not include access to the hotplug
+##	handler setting (kernel.hotplug)
+##	nor the module installer handler setting
+##	(kernel.modprobe).
+##	</p>
+##	<p>
+##	Related interfaces:
+##	</p>
+##	<ul>
+##		<li>kernel_rw_kernel_sysctl()</li>
+##	</ul>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 #
 interface(`kernel_read_kernel_sysctls',`
 	gen_require(`