A bunch of small wording changes, clarifications, etc, that I've had

sitting in my tree for a while.

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

@@ -1,5 +1,5 @@
 <!--
-    Copyright (c) 2002, 2003 Networks Associates Technology, Inc.
+    Copyright (c) 2002-2004 Networks Associates Technology, Inc.
     All rights reserved.
     
     This software was developed for the FreeBSD Project by
@@ -115,11 +115,11 @@
     <para>FreeBSD includes experimental support for several
       mandatory access control policies, as well as a framework
       for kernel security extensibility, the TrustedBSD MAC
-      Framework.  The MAC Framework provides a pluggable access
+      Framework.  The MAC Framework is a pluggable access
       control framework, permitting new security policies to
       be easily linked into the kernel, loaded at boot, or loaded
       dynamically at run-time.  The framework provides a variety
-      of features to make it easier to implement new policies,
+      of features to make it easier to implement new security policies,
       including the ability to easily tag security labels (such as
       confidentiality information) onto system objects.</para>
 
@@ -140,6 +140,11 @@
       services to assist policy writers, including support for
       transient and persistent policy-agnostic object security
       labels.  This support is currently considered experimental.</para>
+
+   <para>This chapter provides information appropriate for developers
+      of policy modules, as well as potential consumers of MAC-enabled
+      environments, to learn about how the MAC Framework supports
+      access control extension of the kernel.</para>
   </sect1>
 
   <sect1 id="mac-background">
@@ -156,7 +161,8 @@
       A variety of MAC policies have been formulated by operating system
       designers and security researches, including the Multi-Level
       Security (MLS) confidentiality policy, the Biba integrity policy,
-      Role-Based Access Control (RBAC), and Type Enforcement (TE).  Each
+      Role-Based Access Control (RBAC), Domain and Type Enforcement (DTE),
+      and Type Enforcement (TE).  Each
       model bases decisions on a variety of factors, including user
       identity, role, and security clearance, as well as security labels
       on objects representing concepts such as data sensitivity and
@@ -164,7 +170,10 @@
 
     <para>The TrustedBSD MAC Framework is capable of supporting policy
       modules that implement all of these policies, as well as a broad
-      class of system hardening policies.  In addition, despite the
+      class of system hardening policies, which may use existing security
+      attributes, such as user and group IDs, as well as extended
+      attributes on files, and other system properties.  In addition,
+      despite the
       name, the MAC Framework can also be used to implement purely
       discretionary policies, as policy modules are given substantial
       flexibility in how they authorize protections.</para>
@@ -212,25 +221,29 @@
     </sect2>
 
     <sect2 id="mac-framework-kernel-arch-management">
-      <title>Management Interfaces</title>
+      <title>Framework Management Interfaces</title>
 
       <para>The TrustedBSD MAC Framework may be directly managed using
 	sysctls, loader tunables, and system calls.</para>
 
-      <para>In most cases, sysctls and loader tunables modify the same
+      <para>In most cases, sysctls and loader tunables of the same name
+	modify the same
 	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, a variety
+	if MAC debugging support is compiled into the kernel, several
-	of counters will be maintained tracking label allocation.  In
+	counters will be maintained tracking label allocation.  In
 	most cases, it is advised 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 ensure proper policy operation.</para>
+	preferred to provide greater granularity and provide 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.</para>
+	system interfaces, including loader variables; policy modules
+	will have the opportunity to influence load and unload
+	events.</para>
     </sect2>
 
     <sect2 id="mac-framework-kernel-arch-synchronization">
@@ -238,10 +251,10 @@
 
       <para>As the set of active policies may change at run-time,
 	and the invocation of entry points is non-atomic,
-	synchronization is required to prevent unloading or
+	synchronization is required to prevent loading or
-	loading of new policies while an entry point invocation
+	unloading of policies while an entry point invocation
 	is progress, freezing the list of policies for the
-	duration.  This is accomplished by means of a Framework
+	duration.  This is accomplished by means of a framework
 	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
@@ -255,7 +268,17 @@
 	of the busy count, including avoiding the full cost of
 	incrementing and decrementing if the list is empty or
 	contains only static entries (policies that are loaded
-	before the system starts, and cannot be unloaded).</para>
+	before the system starts, and cannot be unloaded).  A
+	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>
+
+      <para>As the MAC Framework is not premitted to block in all
+	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
+	framework to become idle.</para>
     </sect2>
 
     <sect2 id="mac-framework-kernel-arch-registration">
@@ -286,19 +309,23 @@
 
       <para>Kernel services interact with the MAC Framework in two ways:
 	they invoke a series of APIs to notify the framework of relevant
-	events, and they a policy-agnostic label structure in
+	events, and they provide a policy-agnostic label structure
-	security-relevant objects.  This label structure is maintained by
+	pointer in
+	security-relevant objects.  The label pointer is maintained by
 	the MAC Framework via label management entry points, and permits
 	the Framework to offer a labeling service to policy modules
 	through relatively non-invasive changes to the kernel subsystem
-	maintaining the object.  For example, label structures have been
+	maintaining the object.  For example, label pointers have been
 	added to processes, process credentials, sockets, pipes, vnodes,
 	Mbufs, network interfaces, IP reassembly queues, and a variety
 	of other security-relevant structures.  Kernel services also
 	invoke the MAC Framework when they perform important security
 	decisions, permitting policy modules to augment those decisions
 	based on their own criteria (possibly including data stored in
-	security labels).</para>
+	security labels).  Most of these security critical decisions
+	will be explicit access control checks; however, some affect
+	more general decision functions such as packet matching for
+	sockets and label transition at program execution.</para>
     </sect2>
 
     <sect2 id="mac-framework-kernel-arch-composition">
@@ -308,13 +335,18 @@
 	at a time, the results of the policy modules will be composed
 	by the framework using a composition operator.  This operator
 	is currently hard-coded, and requires that all active policies
-	must approve a request for it to occur.  As policies may
+	must approve a request for it to return success.  As policies may
 	return a variety of error conditions (success, access denied,
 	object doesn't exist, ...), a precedence operator selects the
 	resulting error from the set of errors returned by policies.
+	In general, errors indicating that an object does not exist will
+	be preferred to errors indicating that access to an object is
+	denied.
 	While it is not guaranteed that the resulting composition will
 	be useful or secure, we've found that it is for many useful
-	selections of policies.</para>
+	selections of policies.  For example, traditional trusted systems
+	often ship with two or more policies using a similar
+	composition.</para>
     </sect2>
 
     <sect2 id="mac-framework-kernel-arch-labels">
@@ -325,12 +357,15 @@
 	of policy-agnostic label management system calls covering
 	a variety of user-exposed objects.  Common label types
 	include partition identifiers, sensitivity labels, integrity
-	labels, compartments, domains, roles, and types.  Policy
+	labels, compartments, domains, roles, and types.  By policy
+	agnostic, we mean that policy modules are able to completely
+	define the semantics of meta-data associated with an object.
+	Policy
 	modules participate in the internalization and externalization
 	of string-based labels provides by user applications, and can
 	expose multiple label elements to applications if desired.</para>
 
-      <para>In-memory labels are stored in <structname>struct
+      <para>In-memory labels are stored in slab-allocated <structname>struct
 	label</structname>, which consists of a fixed-length array
 	of unions, each holding a <literal>void *</literal> pointer
 	and a <literal>long</literal>.  Policies registering for
@@ -341,31 +376,47 @@
 	associated with the kernel object life cycle, including
 	initialization, association/creation, and destruction.  Using
 	these interfaces, it is possible to implement reference
-	counting and other storage mechanisms.  Direct access to
+	counting and other storage models.  Direct access to
-	the kernel object is generally not required by policy
+	the object structure is generally not required by policy
 	modules to retrieve a label, as the MAC Framework generally
 	passes both a pointer to the object and a direct pointer
-	to the object's label into entry points.</para>
+	to the object's label into entry points.  The primary
+	exception to this rule is the process credential, which must
+	be manually dereferenced to access the credential label.  This
+	may change in future revisions of the MAC Framework.</para>
 
       <para>Initialization entry points frequently include a blocking
 	disposition flag indicating whether or not an initialization
 	is permitted to block; if blocking is not permitted, a failure
-	may be returned to cancel allocation of the label.  This may
+	may be returned to cancel allocation of the label (and hence
+	object).  This may
 	occur, for example, in the network stack during interrupt
-	handling, where blocking is not permitted.  Due to the
+	handling, where blocking is not permitted, or while the caller
+	holds a mutex.  Due to the
 	performance cost of maintaining labels on in-flight network
 	packets (Mbufs), policies must specifically declare a
 	requirement that Mbuf labels be allocated.  Dynamically
 	loaded policies making use of labels must be able to handle
 	the case where their init function has not been called on
 	an object, as objects may already exist when the policy is
-	loaded.</para>
+	loaded.  The MAC Framework guarantees that uninitialized label
+	slots will hold a 0 or NULL value, which policies may use to
+	detect uninitialized values.  However, as allocation of Mbuf
+	labels is conditional, policies must also be able to handle a
+	NULL label pointer for Mbufs if they have been loaded
+	dynamically.</para>
 
       <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
 	are used to permit consistent compound updates of
-	security labels on vnodes.</para>
+	security labels on vnodes.  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>
 
       <note><para>Currently, if a labeled policy permits dynamic
 	unloading, its state slot cannot be reclaimed.</para></note>