Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 11 Aug 2018 21:02:22 +0000 (UTC)
From:      Benedict Reuschling <bcr@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r52107 - head/en_US.ISO8859-1/books/arch-handbook/mac
Message-ID:  <201808112102.w7BL2MUF064465@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: bcr
Date: Sat Aug 11 21:02:22 2018
New Revision: 52107
URL: https://svnweb.freebsd.org/changeset/doc/52107

Log:
  Massive cleanup of style errors in this file:
  - replace spaces with tabs
  - use two spaces after a sentence stop consistently
  - rewrapping and reformatting (no user visible changes)
  
  The textproc/igor output has been significantly reduced,
  only a few issues remain that I think are false positives
  from igor itself.
  
  Sponsored by:	Essen hackathon (second half of the file)

Modified:
  head/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml

Modified: head/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml	Sat Aug 11 20:13:22 2018	(r52106)
+++ head/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml	Sat Aug 11 21:02:22 2018	(r52107)
@@ -32,23 +32,41 @@
 
     $FreeBSD$
 -->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="mac">
-  <info><title>The TrustedBSD MAC Framework</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:id="mac">
+  <info>
+    <title>The TrustedBSD MAC Framework</title>
+
     <authorgroup>
-      <author><personname><firstname>Chris</firstname><surname>Costello</surname></personname><affiliation>
-          <orgname>TrustedBSD Project</orgname>
-          <address><email>chris@FreeBSD.org</email></address>
-        </affiliation></author>
+      <author>
+	<personname>
+	  <firstname>Chris</firstname>
+	  <surname>Costello</surname>
+	</personname>
+	<affiliation>
+	  <orgname>TrustedBSD Project</orgname>
+	  <address>
+	    <email>chris@FreeBSD.org</email>
+	  </address>
+	</affiliation>
+      </author>
 
-      <author><personname><firstname>Robert</firstname><surname>Watson</surname></personname><affiliation>
-          <orgname>TrustedBSD Project</orgname>
-          <address><email>rwatson@FreeBSD.org</email></address>
-        </affiliation></author>
+      <author>
+	<personname>
+	  <firstname>Robert</firstname>
+	  <surname>Watson</surname>
+	</personname>
+	<affiliation>
+	  <orgname>TrustedBSD Project</orgname>
+	  <address>
+	    <email>rwatson@FreeBSD.org</email>
+	  </address>
+	</affiliation>
+      </author>
     </authorgroup>
   </info>
 
-  
-
   <sect1 xml:id="mac-copyright">
     <title>MAC Documentation Copyright</title>
 
@@ -66,52 +84,52 @@
 
     <orderedlist>
       <listitem>
-        <para>Redistributions of source code (SGML DocBook) must
-          retain the above copyright notice, this list of conditions
-          and the following disclaimer as the first lines of this file
-          unmodified.</para>
+	<para>Redistributions of source code (SGML DocBook) must
+	  retain the above copyright notice, this list of conditions
+	  and the following disclaimer as the first lines of this file
+	  unmodified.</para>
       </listitem>
 
       <listitem>
-        <para>Redistributions in compiled form (transformed to other
-          DTDs, converted to PDF, PostScript, RTF and other formats)
-          must reproduce the above copyright notice, this list of
-          conditions and the following disclaimer in the documentation
-          and/or other materials provided with the
-          distribution.</para>
+	<para>Redistributions in compiled form (transformed to other
+	  DTDs, converted to PDF, PostScript, RTF and other formats)
+	  must reproduce the above copyright notice, this list of
+	  conditions and the following disclaimer in the documentation
+	  and/or other materials provided with the
+	  distribution.</para>
       </listitem>
     </orderedlist>
 
     <important>
       <para>THIS DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES
-        TECHNOLOGY, INC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
-        INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-        MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-        DISCLAIMED. IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY,
-        INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-        EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-        OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-        STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-        ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN
-        IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
+	TECHNOLOGY, INC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+	INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+	MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+	DISCLAIMED. IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY,
+	INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+	EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+	LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+	OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+	CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+	STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+	ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN
+	IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
     </important>
   </sect1>
 
   <sect1 xml:id="mac-synopsis">
     <title>Synopsis</title>
 
-    <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 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 security policies,
-      including the ability to easily tag security labels (such as
-      confidentiality information) onto system objects.</para>
+    <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 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 security policies, including the ability to easily
+      tag security labels (such as confidentiality information) onto
+      system objects.</para>
 
     <para>This chapter introduces the MAC policy framework and
       provides documentation for a sample MAC policy module.</para>
@@ -123,15 +141,15 @@
 
     <para>The TrustedBSD MAC framework provides a mechanism to allow
       the compile-time or run-time extension of the kernel access
-      control model.  New system policies may be implemented as
-      kernel modules and linked to the kernel; if multiple policy
-      modules are present, their results will be composed.  The
-      MAC Framework provides a variety of access control infrastructure
-      services to assist policy writers, including support for
-      transient and persistent policy-agnostic object security
-      labels.  This support is currently considered experimental.</para>
+      control model.  New system policies may be implemented as kernel
+      modules and linked to the kernel; if multiple policy modules are
+      present, their results will be composed.  The MAC Framework
+      provides a variety of access control infrastructure 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
+    <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>
@@ -140,33 +158,33 @@
   <sect1 xml:id="mac-background">
     <title>Policy Background</title>
 
-    <para>Mandatory Access Control (MAC), refers to a set of
-      access control policies that are mandatorily enforced on
-      users by the operating system.  MAC policies may be contrasted
-      with Discretionary Access Control (DAC) protections, by which
+    <para>Mandatory Access Control (MAC), refers to a set of access
+      control policies that are mandatorily enforced on users by the
+      operating system.  MAC policies may be contrasted with
+      Discretionary Access Control (DAC) protections, by which
       non-administrative users may (at their discretion) protect
       objects.  In traditional UNIX systems, DAC protections include
-      file permissions and access control lists; MAC protections include
-      process controls preventing inter-user debugging and firewalls.
-      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), 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
-      integrity.</para>
+      file permissions and access control lists; MAC protections
+      include process controls preventing inter-user debugging and
+      firewalls.  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), 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 integrity.</para>
 
     <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, 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>
+      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>
   </sect1>
 
   <sect1 xml:id="mac-framework-kernel-arch">
@@ -174,39 +192,58 @@
 
     <para>The TrustedBSD MAC Framework permits kernel modules to
       extend the operating system security policy, as well as
-      providing infrastructure functionality required by many
-      access control modules.  If multiple policies are
-      simultaneously loaded, the MAC Framework will usefully (for
-      some definition of useful) compose the results of the
-      policies.</para>
+      providing infrastructure functionality required by many access
+      control modules.  If multiple policies are simultaneously
+      loaded, the MAC Framework will usefully (for some definition of
+      useful) compose the results of the policies.</para>
 
     <sect2 xml:id="mac-framework-kernel-arch-elements">
       <title>Kernel Elements</title>
 
-      <para>The MAC Framework contains a number of kernel elements:</para>
+      <para>The MAC Framework contains a number of kernel
+	elements:</para>
 
       <itemizedlist>
-	<listitem><para>Framework management interfaces</para></listitem>
-	<listitem><para>Concurrency and synchronization
-	  primitives.</para></listitem>
-	<listitem><para>Policy registration</para></listitem>
-	<listitem><para>Extensible security label for kernel
-	  objects</para></listitem>
-	<listitem><para>Policy entry point composition
-	  operators</para></listitem>
-	<listitem><para>Label management primitives</para></listitem>
-	<listitem><para>Entry point API invoked by kernel
-	  services</para></listitem>
-	<listitem><para>Entry point API to policy modules</para></listitem>
-	<listitem><para>Entry points implementations (policy life cycle,
-	  object life cycle/label management, access control
-	  checks).</para></listitem>
-	<listitem><para>Policy-agnostic label-management system
-	  calls</para></listitem>
-	<listitem><para><function>mac_syscall()</function> multiplex
-	  system call</para></listitem>
-	<listitem><para>Various security policies implemented as MAC
-	  policy modules</para></listitem>
+	<listitem>
+	  <para>Framework management interfaces</para>
+	</listitem>
+	<listitem>
+	  <para>Concurrency and synchronization primitives.</para>
+	</listitem>
+	<listitem>
+	  <para>Policy registration</para>
+	</listitem>
+	<listitem>
+	  <para>Extensible security label for kernel objects</para>
+	</listitem>
+	<listitem>
+	  <para>Policy entry point composition operators</para>
+	</listitem>
+	<listitem>
+	  <para>Label management primitives</para>
+	</listitem>
+	<listitem>
+	  <para>Entry point API invoked by kernel services</para>
+	</listitem>
+	<listitem>
+	  <para>Entry point API to policy modules</para>
+	</listitem>
+	<listitem>
+	  <para>Entry points implementations (policy life cycle,
+	    object life cycle/label management, access control
+	    checks).</para>
+	</listitem>
+	<listitem>
+	  <para>Policy-agnostic label-management system calls</para>
+	</listitem>
+	<listitem>
+	  <para><function>mac_syscall()</function> multiplex system
+	    call</para>
+	</listitem>
+	<listitem>
+	  <para>Various security policies implemented as MAC policy
+	    modules</para>
+	</listitem>
       </itemizedlist>
     </sect2>
 
@@ -216,162 +253,159 @@
       <para>The TrustedBSD MAC Framework may be directly managed using
 	sysctl's, loader tunables, and system calls.</para>
 
-      <para>In most cases, sysctl's 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, several
-	counters will be maintained tracking label allocation.
-	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, as they provide greater granularity and greater
-	operational consistency for policy modules.</para>
+      <para>In most cases, sysctl's 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, several counters will be maintained tracking
+	label allocation.  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, 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 boot loader variables; policy modules
-	will have the opportunity to influence load and unload
-	events, including preventing undesired unloading of the policy.</para>
+      <para>Loading and unloading of policy modules is performed using
+	the system module management system calls and other system
+	interfaces, including boot loader variables; policy modules
+	will have the opportunity to influence load and unload events,
+	including preventing undesired unloading of the policy.</para>
     </sect2>
 
     <sect2 xml:id="mac-framework-kernel-arch-synchronization">
       <title>Policy List Concurrency and Synchronization</title>
 
-      <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 loading or
-	unloading of policies while an entry point invocation
-	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 is incremented; whenever it is exited, the
-	busy count is decremented.  While the busy count is
-	elevated, policy list changes are not permitted, and
-	threads attempting to modify the policy list will sleep
-	until the list is not busy.  The busy count is protected
-	by a mutex, and a condition variable is used to wake up
-	sleepers waiting on policy list modifications.  One
-	side effect of this synchronization model is that
-	recursion into the MAC Framework from within a policy
-	module is permitted, although not generally used.</para>
+      <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 loading or unloading of policies while
+	an entry point invocation 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 is incremented; whenever it is exited,
+	the busy count is decremented.  While the busy count is
+	elevated, policy list changes are not permitted, and threads
+	attempting to modify the policy list will sleep until the list
+	is not busy.  The busy count is protected by a mutex, and a
+	condition variable is used to wake up sleepers waiting on
+	policy list modifications.  One side effect of this
+	synchronization model is that recursion into the MAC Framework
+	from within a policy module is permitted, although not
+	generally used.</para>
 
-      <para>Various optimizations are used to reduce the overhead
-	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).  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 as
-	synchronization is no longer required.</para>
+      <para>Various optimizations are used to reduce the overhead 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).  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 as synchronization is no longer
+	required.</para>
 
       <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
-	framework to become idle.</para>
+	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 xml:id="mac-framework-kernel-arch-label-synchronization">
       <title>Label Synchronization</title>
 
-      <para>As kernel objects of interest may generally be accessed from
-	more than one thread at a time, and simultaneous entry of more
-	than one thread into
-	the MAC Framework is permitted, security attribute storage
-	maintained by the MAC Framework is carefully synchronized.
-	In general, existing kernel synchronization on kernel
-	object data is used to protect MAC Framework security labels
-	on the object: for example, MAC labels on sockets are
-	protected using the existing socket mutex.  Likewise,
-	semantics for concurrent access are generally identical to
-	those of the container objects: for credentials, copy-on-write
-	semantics are maintained for label contents as with the
-	remainder of the credential structure.  The MAC Framework
-	asserts necessary locks on objects when invoked with an
-	object reference.  Policy authors must be aware of these
-	synchronization semantics, as they will sometimes limit the
-	types of accesses permitted on labels: for example, when
-	a read-only reference to a credential is passed to a policy
-	via an entry point, only read operations are permitted on
-	the label state attached to the credential.</para>
+      <para>As kernel objects of interest may generally be accessed
+	from more than one thread at a time, and simultaneous entry of
+	more than one thread into the MAC Framework is permitted,
+	security attribute storage maintained by the MAC Framework is
+	carefully synchronized.  In general, existing kernel
+	synchronization on kernel object data is used to protect MAC
+	Framework security labels on the object: for example, MAC
+	labels on sockets are protected using the existing socket
+	mutex.  Likewise, semantics for concurrent access are
+	generally identical to those of the container objects: for
+	credentials, copy-on-write semantics are maintained for label
+	contents as with the remainder of the credential structure.
+	The MAC Framework asserts necessary locks on objects when
+	invoked with an object reference.  Policy authors must be
+	aware of these synchronization semantics, as they will
+	sometimes limit the types of accesses permitted on labels: for
+	example, when a read-only reference to a credential is passed
+	to a policy via an entry point, only read operations are
+	permitted on the label state attached to the
+	credential.</para>
     </sect2>
 
     <sect2 xml:id="mac-framework-kernel-arch-policy-synchronization">
       <title>Policy Synchronization and Concurrency</title>
 
-      <para>Policy modules must be written to assume that many
-	kernel threads may simultaneously enter one more
-	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
-	inconsistent views on that state resulting in incorrect
-	operation of the policy.  Policies will generally be
-	able to make use of existing FreeBSD synchronization
-	primitives for this purpose, including mutexes, sleep
-	locks, condition variables, and counting semaphores.
-	However, policies should be written to employ these
-	primitives carefully, respecting existing kernel lock
-	orders, and recognizing that some entry points are not
-	permitted to sleep, limiting the use of primitives in
-	those entry points to mutexes and wakeup operations.</para>
+      <para>Policy modules must be written to assume that many kernel
+	threads may simultaneously enter one more 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 inconsistent views on that state resulting
+	in incorrect operation of the policy.  Policies will generally
+	be able to make use of existing FreeBSD synchronization
+	primitives for this purpose, including mutexes, sleep locks,
+	condition variables, and counting semaphores.  However,
+	policies should be written to employ these primitives
+	carefully, respecting existing kernel lock orders, and
+	recognizing that some entry points are not permitted to sleep,
+	limiting the use of primitives in those entry points to
+	mutexes and wakeup operations.</para>
 
       <para>When policy modules call out to other kernel subsystems,
 	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, helping to avoid deadlock.</para>
+	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, helping to avoid deadlock.</para>
     </sect2>
 
     <sect2 xml:id="mac-framework-kernel-arch-registration">
       <title>Policy Registration</title>
 
-      <para>The MAC Framework maintains two lists of active
-	policies: a static list, and a dynamic list.  The lists
-	differ only with regards to their locking semantics: an
-	elevated reference count is not required to make use of
-	the static list.  When kernel modules containing MAC
-	Framework policies are loaded, the policy module will
-	use <literal>SYSINIT</literal> to invoke a registration
-	function; when a policy module is unloaded,
-	<literal>SYSINIT</literal> will likewise invoke a
-	de-registration function.  Registration may fail if a
-	policy module is loaded more than once, if insufficient
-	resources are available for the registration (for
-	example, the policy might require labeling and
-	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 is flagged as
-	not unloadable.</para>
+      <para>The MAC Framework maintains two lists of active policies:
+	a static list, and a dynamic list.  The lists differ only with
+	regards to their locking semantics: an elevated reference
+	count is not required to make use of the static list.  When
+	kernel modules containing MAC Framework policies are loaded,
+	the policy module will use <literal>SYSINIT</literal> to
+	invoke a registration function; when a policy module is
+	unloaded, <literal>SYSINIT</literal> will likewise invoke a
+	de-registration function.  Registration may fail if a policy
+	module is loaded more than once, if insufficient resources are
+	available for the registration (for example, the policy might
+	require labeling and 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 is flagged as not
+	unloadable.</para>
     </sect2>
 
     <sect2 xml:id="mac-framework-kernel-arch-entrypoints">
       <title>Entry Points</title>
 
-      <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 provide a policy-agnostic label structure
-	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 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
+      <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 provide a policy-agnostic label
+	structure 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 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).  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>
+	decisions, permitting policy modules to augment those
+	decisions based on their own criteria (possibly including data
+	stored in 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 xml:id="mac-framework-kernel-arch-composition">
@@ -381,18 +415,17 @@
 	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 return success.  As policies may
-	return a variety of error conditions (success, access denied,
-	object does not 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 have found that it is for many useful
-	selections of policies.  For example, traditional trusted systems
-	often ship with two or more policies using a similar
-	composition.</para>
+	must approve a request for it to return success.  As policies
+	may return a variety of error conditions (success, access
+	denied, object does not 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 have found
+	that it is for many useful selections of policies.  For
+	example, traditional trusted systems often ship with two or
+	more policies using a similar composition.</para>
     </sect2>
 
     <sect2 xml:id="mac-framework-kernel-arch-labels">
@@ -400,33 +433,33 @@
 
       <para>As many interesting access control extensions rely on
 	security labels on objects, the MAC Framework provides a set
-	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.  By policy
-	agnostic, we mean that policy modules are able to completely
-	define the semantics of meta-data associated with an object.
-	Policy
+	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.  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>
+	expose multiple label elements to applications if
+	desired.</para>
 
-      <para>In-memory labels are stored in slab-allocated <varname remap="structname">struct
-	label</varname>, which consists of a fixed-length array
-	of unions, each holding a <literal>void *</literal> pointer
-	and a <literal>long</literal>.  Policies registering for
-	label storage will be assigned a "slot" identifier, which
-	may be used to dereference the label storage.  The semantics
-	of the storage are left entirely up to the policy module:
-	modules are provided with a variety of entry points
-	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 models.  Direct access to
-	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.  The primary
+      <para>In-memory labels are stored in slab-allocated <varname
+	  remap="structname">struct label</varname>, which consists of
+	a fixed-length array of unions, each holding a <literal>void
+	  *</literal> pointer and a <literal>long</literal>.  Policies
+	registering for label storage will be assigned a "slot"
+	identifier, which may be used to dereference the label
+	storage.  The semantics of the storage are left entirely up to
+	the policy module: modules are provided with a variety of
+	entry points 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 models.  Direct
+	access to 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.  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>
@@ -435,41 +468,41 @@
 	disposition flag indicating whether or not an initialization
 	is permitted to sleep; if sleeping is not permitted, a failure
 	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 sleeping 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.  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>
+	object).  This may occur, for example, in the network stack
+	during interrupt handling, where sleeping 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.  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, extended attribute transactions
-	are used to permit consistent compound updates of
-	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 efficiency 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.  As a result, the extended attribute need not be directly
-	accessed with every access control check.</para>
+	extended attributes.  Where available, extended attribute
+	transactions are used to permit consistent compound updates of
+	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 efficiency 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.  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
-	a strict (and relatively low) bound on the number of
-	unload-reload operations for labeled policies.</para></note>
+      <note>
+	<para>Currently, if a labeled policy permits dynamic
+	  unloading, its state slot cannot be reclaimed, which places
+	  a strict (and relatively low) bound on the number of
+	  unload-reload operations for labeled policies.</para>
+      </note>
     </sect2>
 
     <sect2 xml:id="mac-framework-kernel-arch-syscalls">
@@ -481,18 +514,18 @@
 	applications.</para>
 
       <para>The label management calls accept a label description
-	structure, <varname remap="structname">struct mac</varname>, which
-	contains a series of MAC label elements.  Each element
-	contains a character string name, and character string
-	value.  Each policy will be given the chance to claim a
-	particular element name, permitting policies to expose
-	multiple independent elements if desired.  Policy modules
-	perform the internalization and externalization between
-	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, simplifying
-	user applications that must manage labels.</para>
+	structure, <varname remap="structname">struct mac</varname>,
+	which contains a series of MAC label elements.  Each element
+	contains a character string name, and character string value.
+	Each policy will be given the chance to claim a particular
+	element name, permitting policies to expose multiple
+	independent elements if desired.  Policy modules perform the
+	internalization and externalization between 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, simplifying user applications that must
+	manage labels.</para>
 
       <para>The following MAC-related system calls are present in the
 	FreeBSD kernel:</para>
@@ -504,107 +537,131 @@
 	</listitem>
 
 	<listitem>
-	  <para><function>mac_set_proc()</function> may be used to request
-	    a change in the label of the current process.</para>
+	  <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>
+	  <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>
+	  <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 change in the label of an object (file, socket, pipe, ...)
-	     referenced by a file descriptor.</para>
+	  <para><function>mac_set_fd()</function> may be used to
+	    request 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>
+	  <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>
+	  <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>
+	  <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>
+	    <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>
+	    <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>
+	    <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>
 
 	<listitem>
-	  <para><function>mac_get_peer()</function>, actually implemented
-	    via a socket option, retrieves the label of a remote peer on a
-	    socket, if available.</para>
+	  <para><function>mac_get_peer()</function>, actually
+	    implemented via a socket option, retrieves the label of a
+	    remote peer on a socket, if available.</para>
 	</listitem>
       </itemizedlist>
 
       <para>In addition to these system calls, the
-	<literal>SIOCSIGMAC</literal> and <literal>SIOCSIFMAC</literal>
-	network interface ioctls permit the labels on network interfaces to
-	be retrieved and set.</para>
+	<literal>SIOCSIGMAC</literal> and
+	<literal>SIOCSIFMAC</literal> network interface ioctls permit
+	the labels on network interfaces to be retrieved and
+	set.</para>
     </sect2>
   </sect1>
 
   <sect1 xml:id="mac-policy-architecture">
     <title>MAC Policy Architecture</title>
 
-    <para>Security policies are either linked directly into the kernel,
-      or compiled into loadable kernel modules that may be loaded at
-      boot, or dynamically using the module loading system calls at
-      runtime.  Policy modules interact with the system through a
-      set of declared entry points, providing access to a stream of
-      system events and permitting the policy to influence access
-      control decisions.  Each policy contains a number of elements:</para>
+    <para>Security policies are either linked directly into the
+      kernel, or compiled into loadable kernel modules that may be
+      loaded at boot, or dynamically using the module loading system
+      calls at runtime.  Policy modules interact with the system
+      through a set of declared entry points, providing access to a
+      stream of system events and permitting the policy to influence
+      access control decisions.  Each policy contains a number of
+      elements:</para>
 
     <itemizedlist>
-      <listitem><para>Optional configuration parameters for
-	policy.</para></listitem>
-      <listitem><para>Centralized implementation of the policy
-	logic and parameters.</para></listitem>
-      <listitem><para>Optional implementation of policy life cycle
-	events, such as initialization and destruction.</para></listitem>
-      <listitem><para>Optional support for initializing, maintaining, and
-	destroying labels on selected kernel objects.</para></listitem>
-      <listitem><para>Optional support for user process inspection and
-	modification of labels on selected objects.</para></listitem>
-      <listitem><para>Implementation of selected access control
-	entry points that are of interest to the policy.</para></listitem>
-      <listitem><para>Declaration of policy identity, module entry
-	points, and policy properties.</para></listitem>
+      <listitem>
+	<para>Optional configuration parameters for
+	  policy.</para>
+      </listitem>
+      <listitem>
+	<para>Centralized implementation of the policy logic and
+	  parameters.</para>
+      </listitem>
+      <listitem>
+	<para>Optional implementation of policy life cycle events,
+	  such as initialization and destruction.</para>
+      </listitem>
+      <listitem>
+	<para>Optional support for initializing, maintaining, and
+	  destroying labels on selected kernel
+	  objects.</para>
+      </listitem>
+      <listitem>
+	<para>Optional support for user process inspection and
+	  modification of labels on selected
+	  objects.</para>
+      </listitem>
+      <listitem>
+	<para>Implementation of selected access control entry points
+	  that are of interest to the policy.</para>
+      </listitem>
+      <listitem>
+	<para>Declaration of policy identity, module entry points, and
+	  policy properties.</para>
+      </listitem>
     </itemizedlist>
 
     <sect2 xml:id="mac-policy-declaration">
@@ -617,7 +674,7 @@
 	should handle the policy, and optionally requests the
 	allocation of label state by the framework.</para>
 
-    <programlisting>static struct mac_policy_ops mac_<replaceable>policy</replaceable>_ops =
+      <programlisting>static struct mac_policy_ops mac_<replaceable>policy</replaceable>_ops =
 {
         .mpo_destroy = mac_<replaceable>policy</replaceable>_destroy,
         .mpo_init = mac_<replaceable>policy</replaceable>_init,
@@ -630,32 +687,33 @@
 };</programlisting>
 
       <para>The MAC policy entry point vector,
-	<varname>mac_<replaceable>policy</replaceable>_ops</varname> in this example, associates
-	functions defined in the module with specific entry points. A
-	complete listing of available entry points and their
-	prototypes may be found in the MAC entry point reference
-	section.  Of specific interest during module registration are
-	the <symbol>.mpo_destroy</symbol> and <symbol>.mpo_init</symbol>
-	entry points. <symbol>.mpo_init</symbol> will be invoked once a
-	policy is successfully registered with the module framework
-	but prior to any other entry points becoming active. This
-	permits the policy to perform any policy-specific allocation
-	and initialization, such as initialization of any data or
-	locks.  <symbol>.mpo_destroy</symbol> will be invoked when a
-	policy module is unloaded to permit releasing of any allocated
-	memory and destruction of locks.  Currently, these two entry
-	points are invoked with the MAC policy list mutex held to
-	prevent any other entry points from being invoked: this will
-	be changed, but in the mean time, policies should be careful

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201808112102.w7BL2MUF064465>