A variety of minor wording tweaks to the MAC Framework chapter of the

architecture handbook.

Document the current set of MAC-related system calls.

Sponsored by:	SPAWAR, McAfee Research
Obtained from:	TrustedBSD Project

en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml

@@ -1,5 +1,5 @@
 <!--
-    Copyright (c) 2002-2004 Networks Associates Technology, Inc.
+    Copyright (c) 2002-2005 Networks Associates Technology, Inc.
     All rights reserved.
     
     This software was developed for the FreeBSD Project by
@@ -231,19 +231,19 @@
 	parameters, and control behavior such as enforcement of
 	protections relating to various kernel subsystems.  In addition,
 	if MAC debugging support is compiled into the kernel, several
-	counters will be maintained tracking label allocation.  In
+	counters will be maintained tracking label allocation.
-	most cases, it is advised that per-subsystem enforcement
+	It is generally advisable that per-subsystem enforcement
 	controls not be used to control policy behavior in production
 	environments, as they broadly impact the operation of all
 	active policies.  Instead, per-policy controls should be
-	preferred to provide greater granularity and provide greater
+	preferred, as they provide greater granularity and greater
 	operational consistency for policy modules.</para>
 
       <para>Loading and unloading of policy modules is performed
 	using the system module management system calls and other
-	system interfaces, including loader variables; policy modules
+	system interfaces, including boot loader variables; policy modules
 	will have the opportunity to influence load and unload
-	events.</para>
+	events, including preventing undesired unloading of the policy.</para>
     </sect2>
 
     <sect2 id="mac-framework-kernel-arch-synchronization">
@@ -253,9 +253,9 @@
 	and the invocation of entry points is non-atomic,
 	synchronization is required to prevent loading or
 	unloading of policies while an entry point invocation
-	is progress, freezing the list of policies for the
+	is in progress, freezing the set of active policies for the
 	duration.  This is accomplished by means of a framework
-	busy count.  Whenever an entry point is entered, the
+	busy count: whenever an entry point is entered, the
 	busy count is incremented; whenever it is exited, the
 	busy count is decremented.  While the busy count is
 	elevated, policy list changes are not permitted, and
@@ -275,9 +275,10 @@
 	compile-time option is also provided which prevents any
 	change in the set of loaded policies at run-time, which
 	eliminates the mutex locking costs associated with
-	supporting dynamically loaded and unloaded policies.</para>
+	supporting dynamically loaded and unloaded policies as
+	synchronization is no longer required.</para>
 
-      <para>As the MAC Framework is not permitted to block in all
+      <para>As the MAC Framework is not permitted to block in some
 	entry points, a normal sleep lock cannot be used; as a
 	result, it is possible for the load or unload attempt to
 	block for a substantial period of time waiting for the
@@ -287,8 +288,9 @@
     <sect2 id="mac-framework-kernel-arch-label-synchronization">
       <title>Label Synchronization</title>
 
-      <para>As many kernel objects of interest may be accessed from
+      <para>As kernel objects of interest may generally be accessed from
-	more than one thread at a time, and parallel entry into
+	more than one thread at a time, and simultaneous entry of more
+	than one threadinto
 	the MAC Framework is permitted, security attribute storage
 	maintained by the MAC Framework is carefully synchronized.
 	In general, existing kernel synchronization on kernel
@@ -313,7 +315,7 @@
 
       <para>Policy modules must be written to assume that many
 	kernel threads may simultaneously enter one more more
-	policy entry points due to the parallel and preemption
+	policy entry points due to the parallel and preemptive
 	nature of the FreeBSD kernel.  If the policy module makes
 	use of mutable state, this may require the use of
 	synchronization primitives within the policy to prevent
@@ -332,7 +334,7 @@
 	they will generally need to release any in-policy locks in
 	order to avoid violating the kernel lock order or risking
 	lock recursion.  This will maintain policy locks as leaf
-	locks in the global lock order.</para>
+	locks in the global lock order, helping to avoid deadlock.</para>
 
     <sect2 id="mac-framework-kernel-arch-registration">
       <title>Policy Registration</title>
@@ -353,8 +355,8 @@
 	insufficient labeling state might be available), or
 	other policy prerequisites might not be met (some
 	policies may only be loaded prior to boot).  Likewise,
-	de-registration may fail if a policy refuses an
+	de-registration may fail if a policy is flagged as
-	unload.</para>
+	not unloadable.</para>
     </sect2>
 
     <sect2 id="mac-framework-kernel-arch-entrypoints">
@@ -461,15 +463,17 @@
 
       <para>In the case of file system labels, special support is
 	provided for the persistent storage of security labels in
-	extended attributes.  Where available, EA transactions
+	extended attributes.  Where available, extended attribute transactions
 	are used to permit consistent compound updates of
-	security labels on vnodes.  Policy authors may choose to
+	security labels on vnodes--currently this support is present only
+	in the UFS2 file system.  Policy authors may choose to
 	implement multilabel file system object labels using one
 	(or more) extended attributes.  For effiency reasons, the
 	vnode label (<literal>v_label</literal>) is a cache of any
 	on-disk label; policies are able to load values into the
 	cache when the vnode is instantiated, and update the cache
-	as needed.</para>
+	as needed.  As a result, the extended attribute need not be directly
+	accessed with every access control check.</para>
 
       <note><para>Currently, if a labeled policy permits dynamic
 	unloading, its state slot cannot be reclaimed, which places
@@ -496,13 +500,80 @@
 	kernel labels and user-provided labels via entry points,
 	permitting a variety of semantics.  Label management system
 	calls are generally wrapped by user library functions to
-	perform memory allocation and error handling.</para>
+	perform memory allocation and error handling, simplifying
+	user applications that must manage labels.</para>
 
-      <para>In addition, <function>mac_syscall()</function>
+      <para>The following MAC-related system calls are present in the
-	permits policy modules to create new system calls without
+	FreeBSD kernel:</para>
-	allocating system calls.  <function>mac_execve()</function>
+
-	permits an atomic process credential label change when
+      <orderedlist>
-	executing a new image.</para>
+	<listitem>
+	  <para><function>mac_get_proc()</function> may be used to
+	    retrieve the label of the current process.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_set_proc()</function> may be used to request
+	    a change in the label of the current process.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_get_fd()</function> may be used to retrieve
+	    the label of an object (file, socket, pipe, ...) referenced by a
+	    file descriptor.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_get_file()</function> may be used to retrieve
+	    the label of an object referenced by a file system path.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_set_fd()</function> may be used to request a
+	     a change in the label of an object (file, socket, pipe, ...)
+	     referenced by a file descriptor.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_set_file()</function> may be used to request
+	    a change in the label of an object referenced by a file system
+	    path.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_syscall()</function> permits policy modules to
+	    create new system calls without modifying the system call table;
+	    it accepts a target policy name, operation number, and opaque
+	    argument for use by the policy.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_get_pid()</function> may be used to request
+	    the label of another process by process id.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_get_link()</function> is identical to
+	    <function>mac_get_file()</function>, only it will not follow
+	    a symbolic link if it is the final entry in the path, so may be
+	    used to retrieve the label on a symlink.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_set_link()</function> is identical to
+	    <function>mac_set_file()</function>, only it will not follow a
+	    symbolic link if it is the final entry in a path, so may be used
+	    to manipulate the label on a symlink.</para>
+	</listitem>
+
+	<listitem>
+	  <para><function>mac_execve()</function> is identical to the
+	    <function>execve()</function> system call, only it also accepts
+	    a requested label to set the process label to when beginning
+	    execution of a new program.  This change in label on execution
+	    is referred to as a "transition".</para>
+	</listitem>
+      </orderedlist>
     </sect2>
   </sect1>