From 7cf2858e4a096e09c43c0666923b9f9ce04a0909 Mon Sep 17 00:00:00 2001
From: Chris PeBenito <cpebenito@tresys.com>
Date: Mon, 1 Mar 2010 10:53:50 -0500
Subject: [PATCH] Improve the documentation of files interfaces:
 files_pid_file() files_config_file() files_tmp_file()
 files_read_etc_runtime_files() files_read_usr_files() files_search_var_lib()
 files_pid_filetrans()

---
 policy/modules/kernel/files.if | 165 ++++++++++++++++++++++++++++++++-
 1 file changed, 162 insertions(+), 3 deletions(-)

diff --git a/policy/modules/kernel/files.if b/policy/modules/kernel/files.if
index 7fa830931..cf82911a9 100644
--- a/policy/modules/kernel/files.if
+++ b/policy/modules/kernel/files.if
@@ -58,6 +58,14 @@
 ##		<li>logging_log_file()</li>
 ##		<li>userdom_user_home_content()</li>
 ##	</ul>
+##	<p>
+##	Example:
+##	</p>
+##	<p>
+##	type myfile_t;
+##	files_type(myfile_t)
+##	allow mydomain_t myfile_t:file read_file_perms;
+##	</p>
 ## </desc>
 ## <param name="type">
 ##	<summary>
@@ -160,11 +168,39 @@ interface(`files_security_mountpoint',`
 ##	Make the specified type usable for
 ##	runtime process ID files.
 ## </summary>
+## <desc>
+##	<p>
+##	Make the specified type usable for runtime process ID files,
+##	typically found in /var/run.
+##	This will also make the type usable for files, making 
+##	calls to files_type() redundant.  Failure to use this interface
+##	for a PID file type may result in problems with starting
+##	or stopping services.
+##	</p>
+##	<p>
+##	Related interfaces:
+##	</p>
+##	<ul>
+##		<li>files_pid_filetrans()</li>
+##	</ul>
+##	<p>
+##	Example usage with a domain that can create and
+##	write its PID file with a private PID file type in the
+##	/var/run directory:
+##	</p>
+##	<p>
+##	type mypidfile_t;
+##	files_pid_file(mypidfile_t)
+##	allow mydomain_t mypidfile_t:file { create_file_perms write_file_perms };
+##	files_pid_filetrans(mydomain_t, mypidfile_t, file)
+##	</p>
+## </desc>
 ## <param name="type">
 ##	<summary>
 ##	Type to be used for PID files.
 ##	</summary>
 ## </param>
+## <infoflow type="none"/>
 #
 interface(`files_pid_file',`
 	gen_require(`
@@ -180,11 +216,31 @@ interface(`files_pid_file',`
 ##	Make the specified type a
 ##	configuration file.
 ## </summary>
+## <desc>
+##	<p>
+##	Make the specified type usable for configuration files.
+##	This will also make the type usable for files, making 
+##	calls to files_type() redundant.  Failure to use this interface
+##	for a temporary file may result in problems with
+##	configuration management tools.
+##	</p>
+##	<p>
+##	Example usage with a domain that can read
+##	its configuration file /etc:
+##	</p>
+##	<p>
+##	type myconffile_t;
+##	files_config_file(myconffile_t)
+##	allow mydomain_t myconffile_t:file read_file_perms;
+##	files_search_etc(mydomain_t)
+##	</p>
+## </desc>
 ## <param name="file_type">
 ##	<summary>
 ##	Type to be used as a configuration file.
 ##	</summary>
 ## </param>
+## <infoflow type="none"/>
 #
 interface(`files_config_file',`
 	gen_require(`
@@ -288,12 +344,39 @@ interface(`files_poly_member_tmp',`
 ##	Make the specified type a file
 ##	used for temporary files.
 ## </summary>
+## <desc>
+##	<p>
+##	Make the specified type usable for temporary files.
+##	This will also make the type usable for files, making 
+##	calls to files_type() redundant.  Failure to use this interface
+##	for a temporary file may result in problems with
+##	purging temporary files.
+##	</p>
+##	<p>
+##	Related interfaces:
+##	</p>
+##	<ul>
+##		<li>files_tmp_filetrans()</li>
+##	</ul>
+##	<p>
+##	Example usage with a domain that can create and
+##	write its temporary file in the system temporary file
+##	directories (/tmp or /var/tmp):
+##	</p>
+##	<p>
+##	type mytmpfile_t;
+##	files_tmp_file(mytmpfile_t)
+##	allow mydomain_t mytmpfile_t:file { create_file_perms write_file_perms };
+##	files_tmp_filetrans(mydomain_t, mytmpfile_t, file)
+##	</p>
+## </desc>
 ## <param name="file_type">
 ##	<summary>
 ##	Type of the file to be used as a
 ##	temporary file.
 ##	</summary>
 ## </param>
+## <infoflow type="none"/>
 #
 interface(`files_tmp_file',`
 	gen_require(`
@@ -2178,7 +2261,7 @@ interface(`files_manage_etc_dirs',`
 ##		<li>auth_read_shadow()</li>
 ##		<li>files_read_etc_runtime_files()</li>
 ##		<li>seutil_read_config()</li>
-##	</ul>	
+##	</ul>
 ## </desc>
 ## <param name="domain">
 ##	<summary>
@@ -2410,11 +2493,29 @@ interface(`files_create_boot_flag',`
 ##	Read files in /etc that are dynamically
 ##	created on boot, such as mtab.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read dynamically created
+##	configuration files in /etc. These files are typically
+##	general system configuration files that do
+##	not have more specific SELinux types.  Some
+##	examples of these files are:
+##	</p>
+##	<ul>
+##		<li>/etc/motd</li>
+##		<li>/etc/mtab</li>
+##		<li>/etc/nologin</li>
+##	</ul>
+##	<p>
+##	This interface does not include access to /etc/shadow.
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10" />
 ## <rolecap/>
 #
 interface(`files_read_etc_runtime_files',`
@@ -3930,11 +4031,29 @@ interface(`files_getattr_usr_files',`
 ## <summary>
 ##	Read generic files in /usr.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to read generic
+##	files in /usr. These files are various program
+##	files that do not have more specific SELinux types.
+##	Some examples of these files are:
+##	</p>
+##	<ul>
+##		<li>/usr/include/*</li>
+##		<li>/usr/share/doc/*</li>
+##		<li>/usr/share/info/*</li>
+##	</ul>
+##	<p>
+##	Generally, it is safe for many domains to have
+##	this access.
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="10"/>
 #
 interface(`files_read_usr_files',`
 	gen_require(`
@@ -4491,11 +4610,25 @@ interface(`files_getattr_var_lib_dirs',`
 ## <summary>
 ##	Search the /var/lib directory.
 ## </summary>
+## <desc>
+##	<p>
+##	Search the /var/lib directory.  This is
+##	necessary to access files or directories under
+##	/var/lib that have a private type.  For example, a
+##	domain accessing a private library file in the
+##	/var/lib directory:
+##	</p>
+##	<p>
+##	allow mydomain_t mylibfile_t:file read_file_perms;
+##	files_search_var_lib(mydomain_t)
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
 ##	</summary>
 ## </param>
+## <infoflow type="read" weight="5"/>
 #
 interface(`files_search_var_lib',`
 	gen_require(`
@@ -4938,9 +5071,34 @@ interface(`files_read_generic_pids',`
 
 ########################################
 ## <summary>
-##	Create an object in the process ID directory, with a private
-##	type using a type transition.
+##	Create an object in the process ID directory, with a private type.
 ## </summary>
+## <desc>
+##	<p>
+##	Create an object in the process ID directory (e.g., /var/run)
+##	with a private type.  Typically this is used for creating
+##	private PID files in /var/run with the private type instead
+##	of the general PID file type. To accomplish this goal,
+##	either the program must be SELinux-aware, or use this interface.
+##	</p>
+##	<p>
+##	Related interfaces:
+##	</p>
+##	<ul>
+##		<li>files_pid_file()</li>
+##	</ul>
+##	<p>
+##	Example usage with a domain that can create and
+##	write its PID file with a private PID file type in the
+##	/var/run directory:
+##	</p>
+##	<p>
+##	type mypidfile_t;
+##	files_pid_file(mypidfile_t)
+##	allow mydomain_t mypidfile_t:file { create_file_perms write_file_perms };
+##	files_pid_filetrans(mydomain_t, mypidfile_t, file)
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
@@ -4956,6 +5114,7 @@ interface(`files_read_generic_pids',`
 ##	The object class of the object being created.
 ##	</summary>
 ## </param>
+## <infoflow type="write" weight="10"/>
 #
 interface(`files_pid_filetrans',`
 	gen_require(`