From 4e12649d4ea597531a5c0538f48c05a4ea539c6f Mon Sep 17 00:00:00 2001
From: Chris PeBenito <cpebenito@tresys.com>
Date: Mar 02 2010 15:24:24 +0000
Subject: Improve the documentation of devices interfaces:

dev_node()
dev_read_rand()
dev_read_urand()
dev_read_sysfs()

---

diff --git a/policy/modules/kernel/devices.if b/policy/modules/kernel/devices.if
index fe31e1f..a3796f8 100644
--- a/policy/modules/kernel/devices.if
+++ b/policy/modules/kernel/devices.if
@@ -29,14 +29,39 @@
 
 ########################################
 ## <summary>
-##	Make the passed in type a type appropriate for
-##	use on device nodes (usually files in /dev).
+##	Make the specified type usable for device
+##	nodes in a filesystem.
 ## </summary>
-## <param name="object_type">
+## <desc>
+##	<p>
+##	Make the specified type usable for device nodes
+##	in a filesystem.  Types used for device nodes that
+##	do not use this interface, or an interface that
+##	calls this one, will have unexpected behaviors
+##	while the system is running.
+##	</p>
+##	<p>
+##	Example:
+##	</p>
+##	<p>
+##	type mydev_t;
+##	dev_node(mydev_t)
+##	allow mydomain_t mydev_t:chr_file read_chr_file_perms;
+##	</p>
+##	<p>
+##	Related interfaces:
+##	</p>
+##	<ul>
+##		<li>term_tty()</li>
+##		<li>term_pty()</li>
+##	</ul>
+## </desc>
+## <param name="type">
 ##	<summary>
-##	The object type that will be used on device nodes.
+##	Type to be used for device nodes.
 ##	</summary>
 ## </param>
+## <infoflow type="none"/>
 #
 interface(`dev_node',`
 	gen_require(`
@@ -2797,13 +2822,28 @@ interface(`dev_rw_qemu',`
 ########################################
 ## <summary>
 ##	Read from random number generator
-##	devices (e.g., /dev/random)
+##	devices (e.g., /dev/random).
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read from random number
+##	generator devices (e.g., /dev/random).  Typically this is
+##	used in situations when a cryptographically secure random
+##	number is needed.
+##	</p>
+##	<p>
+##	Related interface:
+##	</p>
+##	<ul>
+##		<li>dev_read_urand()</li>
+##	</ul>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 #
 interface(`dev_read_rand',`
 	gen_require(`
@@ -3345,13 +3385,22 @@ interface(`dev_write_sysfs_dirs',`
 
 ########################################
 ## <summary>
-##	Allow caller to read hardware state information.
+##	Read hardware state information.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read the contents of
+##	the sysfs filesystem.  This filesystem contains
+##	information, parameters, and other settings on the
+##	hardware installed on the system.
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
-##	The process type reading hardware state information.
+##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 #
 interface(`dev_read_sysfs',`
 	gen_require(`
@@ -3387,13 +3436,36 @@ interface(`dev_rw_sysfs',`
 
 ########################################
 ## <summary>
-##	Read from pseudo random devices (e.g., /dev/urandom)
+##	Read from pseudo random number generator devices (e.g., /dev/urandom).
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read from pseudo random number
+##	generator devices (e.g., /dev/urandom).  Typically this is
+##	used in situations when a cryptographically secure random
+##	number is not necessarily needed.  One example is the Stack
+##	Smashing Protector (SSP, formerly known as ProPolice) support
+##	that may be compiled into programs.
+##	</p>
+##	<p>
+##	Related interface:
+##	</p>
+##	<ul>
+##		<li>dev_read_rand()</li>
+##	</ul>
+##	<p>
+##	Related tunable:
+##	</p>
+##	<ul>
+##		<li>global_ssp</li>
+##	</ul>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 #
 interface(`dev_read_urand',`
 	gen_require(`
diff --git a/policy/modules/kernel/files.if b/policy/modules/kernel/files.if
index cf82911..83d26a5 100644
--- a/policy/modules/kernel/files.if
+++ b/policy/modules/kernel/files.if
@@ -30,7 +30,9 @@
 ##	in a filesystem.  Types used for files that
 ##	do not use this interface, or an interface that
 ##	calls this one, will have unexpected behaviors
-##	while the system is running.
+##	while the system is running. If the type is used
+##	for device nodes (character or block files), then
+##	the dev_node() interface is more appropriate.
 ##	</p>
 ##	<p>
 ##	Related interfaces: