PERFORCE change 34990 for review
Robert Watson
rwatson at FreeBSD.org
Fri Jul 25 09:20:14 PDT 2003
http://perforce.freebsd.org/chv.cgi?CH=34990
Change 34990 by rwatson at rwatson_tislabs on 2003/07/25 09:19:45
Integrate the three remaining (conflicting) files in the
trustedbsd_doc branch. It looks like all the changes left in
these files were whitespace, or were integrated into the
FreeBSD.org version in similar but not identical ways.
Affected files ...
.. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac.ent#5 integrate
.. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#31 integrate
.. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/handbook/security/chapter.sgml#15 integrate
Differences ...
==== //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac.ent#5 (text+ko) ====
@@ -1,3 +1,5 @@
+<!-- $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/mac.ent,v 1.3 2003/06/23 02:04:49 rwatson Exp $ -->
+
<!ENTITY mac.mpo "mpo">
<!ENTITY mac.thead '
<colspec colname="first" colwidth="0">
@@ -16,9 +18,7 @@
<!ENTITY mac.externalize.paramdefs '
<paramdef>struct label *<parameter>label</parameter></paramdef>
<paramdef>char *<parameter>element_name</parameter></paramdef>
- <paramdef>char *<parameter>element_data</parameter></paramdef>
- <paramdef>size_t <parameter>size</parameter></paramdef>
- <paramdef>size_t <parameter>*len</parameter></paramdef>
+ <paramdef>struct sbuf *<parameter>sb</parameter></paramdef>
<paramdef>int <parameter>*claimed</parameter></paramdef>
'>
@@ -35,19 +35,9 @@
</row>
<row>
- <entry><parameter>element_data</parameter>
- <entry>Buffer; to be filled in with text representation of label</entry>
- </row>
-
- <row>
- <entry><parameter>size</parameter></entry>
- <entry>Size of <parameter>element_data</parameter></entry>
- </row>
-
- <row>
- <entry><parameter>len</parameter></entry>
- <entry>To be filled in with the length of the string representing the
- label data.</entry>
+ <entry><parameter>sb</parameter>
+ <entry>String buffer to be filled with a text representation of
+ label</entry>
</row>
<row>
@@ -65,7 +55,7 @@
user. Currently, all policies' <function>externalize</function> entry
points will be called, so the implementation should check the contents
of <parameter>element_name</parameter> before attempting to fill in
- <parameter>element_data</parameter>. If
+ <parameter>sb</parameter>. If
<parameter>element_name</parameter> does not match the name of your
policy, simply return <returnvalue>0</returnvalue>. Only return nonzero
if an error occurs while externalizing the label data. Once the policy
==== //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#31 (text+ko) ====
@@ -29,7 +29,7 @@
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
- $FreeBSD$
+ $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml,v 1.27 2003/04/20 23:10:35 rwatson Exp $
-->
<chapter id="mac">
@@ -112,10 +112,17 @@
<sect1 id="mac-synopsis">
<title>Synopsis</title>
- <para>MAC, or Mandatory Access Control, is a feature introduced by
- the TrustedBSD Project to supplement the existing standard DAC
- (Discretionary Access Control) policies of BSD Unix systems.</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 provides 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,
+ 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>
</sect1>
@@ -128,94 +135,310 @@
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. While the
- framework is intended to support a variety of access control
- models, its design was derived from the requirements of a set
- of specific access control models required for the TrustedBSD
- and CBOSS Projects. This includes support for fixed and
- floating label Biba integrity policies, the MLS
- confidentiality policy, the Type Enforcement rule-based access
- control policy, and the ability to support layering of the NSA
- FLASK framework above the TrustedBSD MAC framework. This
- document describes the rough architecture of the framework,
- with the understanding that this is a work-in-progress and may
- change subtantially as requirements evolve.</para>
+ 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>
</sect1>
-
- <sect1 id="mac-kernel-arch">
- <title>Kernel Architecture</title>
-
- <para>The TrustedBSD MAC framework provides the opportunity for
- policy modules to be augment system access control decisions.
- Policies are permitted the opportunity to restrict the set of
- rights available for processes at a variety of relevant points
- in the kernel. In addition, they are provided the opportunity
- to tag processes and various kernel objects with labels storing
- access control information. Policy modules may register
- interest in a subset of the total available events or objects,
- and are not required to implement events or objects that are not
- relevant to the policy. Multiple modules may be loaded at once,
- and the results of the modules are composed as necessary to
- build an over-all system policy. Policy modules may be
- implemented such that they can be loaded on-demand at run-time,
- or such that they may only be loaded early in the boot process.
- This permits policies requiring pervasive labeling of all
- objects to prevent improper use.</para>
+
+ <sect1>
+ <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
+ 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), 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. 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 id="mac-userland-arch">
- <title>Userland Architecture</title>
+ <sect1 id="mac-framework-kernel-arch">
+ <title>MAC Framework Kernel Architecture</title>
- <para>...</para>
+ <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>
+
+ <sect2 id="mac-framework-kernel-arch-elements">
+ <title>Kernel Elements</title>
+
+ <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>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="mac-framework-kernel-arch-management">
+ <title>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
+ 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
+ of 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>
+
+ <para>Loading and unloading of policy modules is performed
+ using the system module management system calls and other
+ system interfaces, including loader variables.</para>
+ </sect2>
+
+ <sect2 id="mac-framework-kernel-arch-synchronization">
+ <title>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 unloading or
+ loading of new policies while an entry point invocation
+ is progress, freezing the list of 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.</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).</para>
+ </sect2>
+
+ <sect2 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 refuses an
+ unload.</para>
+ </sect2>
+
+ <sect2 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 a policy-agnostic label structure in
+ security-relevant objects. This label structure 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
+ 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>
+ </sect2>
+
+ <sect2 id="mac-framework-kernel-arch-composition">
+ <title>Policy Composition</title>
+
+ <para>When more than one policy module is loaded into the kernel
+ 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
+ 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.
+ 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>
+ </sect2>
+
+ <sect2 id="mac-framework-kernel-arch-labels">
+ <title>Labeling Support</title>
+
+ <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. 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
+ 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
+ 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 mechanisms. Direct access to
+ the kernel object 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>
+
+ <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
+ occur, for example, in the network stack during interrupt
+ handling, where blocking is not permitted. 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>
+
+ <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>
+
+ <note><para>Currently, if a labeled policy permits dynamic
+ unloading, its state slot cannot be reclaimed.</para></note>
+ </sect2>
+
+ <sect2 id="mac-framework-kernel-arch-syscalls">
+ <title>System Calls</title>
+
+ <para>The MAC Framework implements a number of system calls:
+ most of these calls support the policy-agnostic label
+ retrieval and manipulation APIs exposed to user
+ applications.</para>
+
+ <para>The label management calls accept a label description
+ structure, <structname>struct mac</structname>, 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.</para>
+
+ <para>In addition, <function>mac_syscall()</function>
+ permits policy modules to create new system calls without
+ allocating system calls. <function>mac_execve()</function>
+ permits an atomic process credential label change when
+ executing a new image.</para>
+ </sect2>
</sect1>
-
- <sect1 id="mac-entry-point">
- <title>Entry Point Framework</title>
-
- <para>Four classes of entry points are offered to policies
- registered with the framework: entry points associated with
- the registration and management of policies, entry points
- denoting initialization, creation, destruction, and other life
- cycle events for kernel objects, events assocated with access
- control decisions that the policy module may influence, and
- calls associated with the management of labels on objects. In
- addition, a <function>mac_syscall()</function> entry point is
- provided so that policies may extend the kernel interface
- without registering new system calls.</para>
-
- <para>Policy module writers should be aware of the kernel
- locking strategy, as well as what object locks are available
- during which entry points. Writers should attempt to avoid
- deadlock scenarios by avoiding grabbing non-leaf locks inside
- of entry points, and also follow the locking protocol for
- object access and modification. In particular, writers should
- be aware that while necessary locks to access objects and
- their labels are generally held, sufficient locks to modify an
- object or its label may not be present for all entry points.
- Locking information for arguments is documented in the MAC
- framework entry point document.</para>
-
- <para>Policy entry points will pass a reference to the object
- label along with the object itself. This permits labeled
- policies to be unaware of the internals of the object yet
- still make decisions based on the label. The exception to this
- is the process credential, which is assumed to be understood
- by policies as a first class security object in the kernel.
- Policies that do not implement labels on kernel objects will
- be passed NULL pointers for label arguments to entry
- points.</para>
+
+ <sect1 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>
+
+ <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>
+ </itemizedlist>
+
+ <sect2 id="mac-policy-declaration">
+ <title>Policy Declaration</title>
- <sect2 id="mac-mpo-general">
- <title>General-Purpose Module Entry Points</title>
-
<para>Modules may be declared using the
- <function>MAC_POLICY_SET()</function> macro, which names the
- policy, provides a reference to the MAC entry point vector,
- provides load-time flags determining how the policy framework
- should handle the policy, and optionally requests the
- allocation of label state by the framework.</para>
+ <function>MAC_POLICY_SET()</function> macro, which names the
+ policy, provides a reference to the MAC entry point vector,
+ provides load-time flags determining how the policy framework
+ 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,
@@ -228,66 +451,146 @@
};</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
- about what kernel primitives they invoke so as to avoid lock
- ordering or sleeping problems.</para>
+ <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
+ about what kernel primitives they invoke so as to avoid lock
+ ordering or sleeping problems.</para>
<para>The policy declaration's module name field exists so that
- the module may be uniquely identified for the purposes of
- module dependencies. An appropriate string should be selected.
- The full string name of the policy is displayed to the user
- via the kernel log during load and unload events, and also
- exported when providing status information to userland
- processes.</para>
+ the module may be uniquely identified for the purposes of
+ module dependencies. An appropriate string should be selected.
+ The full string name of the policy is displayed to the user
+ via the kernel log during load and unload events, and also
+ exported when providing status information to userland
+ processes.</para>
+ </sect2>
+
+ <sect2 id="mac-policy-flags">
+ <title>Policy Flags</title>
- <para>The policy flags field permits the module to provide the
- framework with information about its loader-related
- capabilities. Currently, two flags are defined:</para>
+ <para>The policy declaration flags field permits the module to
+ provide the framework with information about its capabilities at
+ the time the module is loaded. Currently, three flags are
+ defined:</para>
<variablelist>
- <varlistentry>
- <term>MPC_LOADTIME_FLAG_UNLOADOK</term>
-
- <listitem>
- <para>This flag indicates that the policy module may be
- unloaded. If this flag is not provided, then the policy
- framework will reject requests to unload the module.
- This flag might be used by modules that allocate label
- state and are unable to free that state at
- runtime.</para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>MPC_LOADTIME_FLAG_UNLOADOK</term>
+
+ <listitem>
+ <para>This flag indicates that the policy module may be
+ unloaded. If this flag is not provided, then the policy
+ framework will reject requests to unload the module.
+ This flag might be used by modules that allocate label
+ state and are unable to free that state at
+ runtime.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>MPC_LOADTIME_FLAG_NOTLATE</term>
- <varlistentry>
- <term>MPC_LOADTIME_FLAG_NOTLATE</term>
-
- <listitem><para>This flag indicates that the policy module
- must be loaded and initialized early in the boot
- process. If the flag is specified, attempts to register
- the module following boot will be rejected. The flag
- may be used by policies that require pervasive labeling
- of all system objects, and cannot handle objects that
- have not been properly initialized by the policy.</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>This flag indicates that the policy module
+ must be loaded and initialized early in the boot
+ process. If the flag is specified, attempts to register
+ the module following boot will be rejected. The flag
+ may be used by policies that require pervasive labeling
+ of all system objects, and cannot handle objects that
+ have not been properly initialized by the policy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>MPC_LOADTIME_FLAG_LABELMBUFS</term>
+
+ <listitem>
+ <para>This flag indicates that the policy module requires
+ labeling of Mbufs, and that memory should always be
+ allocated for the storage of Mbuf labels. By default,
+ the MAC Framework will not allocate label storage for
+ Mbufs unless at least one loaded policy has this flag
+ set. This measurably improves network performance when
+ policies do not require Mbuf labeling. A kernel option,
+ <literal>MAC_ALWAYS_LABEL_MBUF</literal>, exists to
+ force the MAC Framework to allocate Mbuf label storage
+ regardless of the setting of this flag, and may be
+ useful in some environments.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
+ <note><para>Policies using the
+ <literal>MPC_LOADTIME_FLAG_LABELMBUFS</literal> without the
+ <literal>MPC_LOADTIME_FLAG_NOTLATE</literal> flag set
+ must be able to correctly handle <literal>NULL</literal>
+ Mbuf label pointers passed into entry points. This is necessary
+ as in-flight Mbufs without label storage may persist after a
+ policy enabling Mbuf labeling has been loaded. If a policy
+ is loaded before the network subsystem is active (i.e., the
+ policy is not being loaded late), then all Mbufs are guaranteed
+ to have label storage.</para></note>
+ </sect2>
+
+ <sect2 id="mac-policy-entry-points">
+ <title>Policy Entry Points</title>
+
+ <para>Four classes of entry points are offered to policies
+ registered with the framework: entry points associated with
+ the registration and management of policies, entry points
+ denoting initialization, creation, destruction, and other life
+ cycle events for kernel objects, events associated with access
+ control decisions that the policy module may influence, and
+ calls associated with the management of labels on objects. In
+ addition, a <function>mac_syscall()</function> entry point is
+ provided so that policies may extend the kernel interface
+ without registering new system calls.</para>
+
+ <para>Policy module writers should be aware of the kernel
+ locking strategy, as well as what object locks are available
+ during which entry points. Writers should attempt to avoid
+ deadlock scenarios by avoiding grabbing non-leaf locks inside
+ of entry points, and also follow the locking protocol for
+ object access and modification. In particular, writers should
+ be aware that while necessary locks to access objects and
+ their labels are generally held, sufficient locks to modify an
+ object or its label may not be present for all entry points.
+ Locking information for arguments is documented in the MAC
+ framework entry point document.</para>
+
+ <para>Policy entry points will pass a reference to the object
+ label along with the object itself. This permits labeled
+ policies to be unaware of the internals of the object yet
+ still make decisions based on the label. The exception to this
+ is the process credential, which is assumed to be understood
+ by policies as a first class security object in the kernel.
+ Policies that do not implement labels on kernel objects will
+ be passed NULL pointers for label arguments to entry
+ points.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="mac-entry-point-reference">
+ <title>MAC Policy Entry Point Reference</title>
+
+ <sect2 id="mac-mpo-general">
+ <title>General-Purpose Module Entry Points</title>
+
<sect3 id="mac-mpo-init">
<title><function>&mac.mpo;_init</function</title>
@@ -453,8 +756,6 @@
<funcdef>void
<function>&mac.mpo;_init_bpfdesc_label</function></funcdef>
- <paramdef>struct bpf_d
- *<parameter>bpf_d</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
</funcprototype>
@@ -466,11 +767,6 @@
<tbody>
<row>
- <entry><parameter>bpf_d</parameter></entry>
- <entry>Object; bpf descriptor</entry>
- </row>
-
- <row>
<entry><parameter>label</parameter></entry>
<entry>New label to apply</entry>
</row>
@@ -520,8 +816,6 @@
<funcdef>void
<function>&mac.mpo;_init_devfsdirent_label</function></funcdef>
- <paramdef>struct devfs_dirent
- *<parameter>devfs_dirent</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
</funcprototype>
@@ -533,11 +827,6 @@
<tbody>
<row>
- <entry><parameter>devfs_dirent</parameter></entry>
- <entry>Object; devfs directory entry</entry>
- </row>
-
- <row>
<entry><parameter>label</parameter></entry>
<entry>New label to apply</entry>
</row>
@@ -557,8 +846,6 @@
<funcdef>void
<function>&mac.mpo;_init_ifnet_label</function></funcdef>
- <paramdef>struct ifnet
- *<parameter>ifnet</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
</funcprototype>
@@ -570,11 +857,6 @@
<tbody>
<row>
- <entry><parameter>ifnet</parameter></entry>
- <entry>Object; network interface</entry>
- </row>
-
- <row>
<entry><parameter>label</parameter></entry>
<entry>New label to apply</entry>
</row>
@@ -594,10 +876,9 @@
<funcdef>void
<function>&mac.mpo;_init_ipq_label</function></funcdef>
- <paramdef>struct ipq
- *<parameter>ipq</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
+ <paramdef>int <parameter>flag</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -607,20 +888,29 @@
<tbody>
<row>
- <entry><parameter>ipq</parameter></entry>
- <entry>Object; IP reassembly queue</entry>
+ <entry><parameter>label</parameter></entry>
+ <entry>New label to apply</entry>
</row>
-
+
<row>
- <entry><parameter>label</parameter></entry>
- <entry>New label to apply</entry>
+ <entry><parameter>flag</parameter></entry>
+ <entry>Blocking/non-blocking &man.malloc.9;; see
+ below</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Initialize the label on a newly instantiated IP fragment
- reassembly queue.</para>
+ reassembly queue. The <parameter>flag</parameter> field may
+ be one of <symbol>M_WAITOK</symbol> and <symbol>M_NOWAIT</symbol>,
+ and should be employed to avoid performing a blocking
+ &man.malloc.9; during this initialization call. IP fragment
+ reassembly queue allocation frequently occurs in performance
+ sensitive environments, and the implementation should be careful
+ to avoid blocking or long-lived operations. This entry point
+ is permitted to fail resulting in the failure to allocate
+ the IP fragment reassembly queue.</para>
</sect3>
<sect3 id="mac-mpo-init-mbuf">
@@ -631,9 +921,7 @@
<funcdef>void
<function>&mac.mpo;_init_mbuf_label</function></funcdef>
- <paramdef>struct mbuf
- *<parameter>mbuf</parameter></paramdef>
- <paramdef>int <parameter>how</parameter></paramdef>
+ <paramdef>int <parameter>flag</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
</funcprototype>
@@ -645,12 +933,7 @@
<tbody>
<row>
- <entry><parameter>mbuf</parameter></entry>
- <entry>Object; mbuf</entry>
- </row>
-
- <row>
- <entry><parameter>how</parameter></entry>
+ <entry><parameter>flag</parameter></entry>
<entry>Blocking/non-blocking &man.malloc.9;; see
below</entry>
</row>
@@ -664,10 +947,10 @@
<para>Initialize the label on a newly instantiated mbuf packet
header (<parameter>mbuf</parameter>). The
- <parameter>how</parameter> field may be one of
+ <parameter>flag</parameter> field may be one of
<symbol>M_WAITOK</symbol> and <symbol>M_NOWAIT</symbol>, and
should be employed to avoid performing a blocking
- &man.malloc.9; during this initialization call. Mbuf
+ &man.malloc.9; during this initialization call. Mbuf
allocation frequently occurs in performance sensitive
environments, and the implementation should be careful to
avoid blocking or long-lived operations. This entry point
@@ -683,8 +966,6 @@
<funcdef>void
<function>&mac.mpo;_init_mount_label</function></funcdef>
- <paramdef>struct mount
- *<parameter>mount</parameter></paramdef>
<paramdef>struct label
*<parameter>mntlabel</parameter></paramdef>
<paramdef>struct label
@@ -699,11 +980,6 @@
<tbody>
<row>
- <entry><parameter>mount</parameter></entry>
- <entry>Object; file system mount point</entry>
- </row>
-
- <row>
<entry><parameter>mntlabel</parameter></entry>
<entry>Policy label to be initialized for the mount
itself</entry>
@@ -891,8 +1167,6 @@
<funcdef>void
<function>&mac.mpo;_init_vnode_label</function></funcdef>
- <paramdef>struct vnode
- *<parameter>vp</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
</funcprototype>
@@ -904,11 +1178,6 @@
<tbody>
<row>
- <entry><parameter>vp</parameter></entry>
- <entry>Object; file system object</entry>
- </row>
-
- <row>
<entry><parameter>label</parameter></entry>
<entry>New label to initialize</entry>
</row>
@@ -944,7 +1213,7 @@
</tgroup>
</informaltable>
- <para>Destroy the label on a bpf descriptor. In this entry
+ <para>Destroy the label on a BPF descriptor. In this entry
point a policy should free any internal storage associated
with <parameter>label</parameter> so that it may be
destroyed.</para>
@@ -958,8 +1227,6 @@
<funcdef>void
<function>&mac.mpo;_destroy_cred_label</function></funcdef>
- <paramdef>struct ucred
- *<parameter>cred</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
</funcprototype>
@@ -971,11 +1238,6 @@
<tbody>
<row>
- <entry><parameter>cred</parameter></entry>
- <entry>Subject; user credential</entry>
- </row>
-
- <row>
<entry><parameter>label</parameter></entry>
<entry>Label being destroyed</entry>
</row>
@@ -998,8 +1260,6 @@
<funcdef>void
<function>&mac.mpo;_destroy_devfsdirent_label</function></funcdef>
- <paramdef>struct devfs_dirent
- *<parameter>devfs_dirent</parameter></paramdef>
<paramdef>struct label
*<parameter>label</parameter></paramdef>
</funcprototype>
@@ -1011,11 +1271,6 @@
<tbody>
<row>
- <entry><parameter>devfs_dirent</parameter></entry>
- <entry>Object; devfs directory entry</entry>
- </row>
-
- <row>
<entry><parameter>label</parameter></entry>
<entry>Label being destroyed</entry>
</row>
@@ -1025,7 +1280,7 @@
<para>Destroy the label on a devfs entry. In this entry
point, a policy module should free any internal storage
- asociated with <parameter>label</parameter> so that it may
+ associated with <parameter>label</parameter> so that it may
be destroyed.</para>
</sect3>
@@ -1165,8 +1420,6 @@
<funcdef>void
<function>&mac.mpo;_destroy_mount_label</function></funcdef>
- <paramdef>struct mount
- *<parameter>mp</parameter></paramdef>
<paramdef>struct label
*<parameter>mntlabel</parameter></paramdef>
<paramdef>struct label
@@ -1180,11 +1433,6 @@
<tbody>
<row>
- <entry><parameter>mp</parameter></entry>
- <entry>Object; file system mount point</entry>
- </row>
-
- <row>
<entry><parameter>mntlabel</parameter></entry>
<entry>Mount point label being destroyed</entry>
</row>
@@ -1333,6 +1581,75 @@
destroyed.</para>
</sect3>
+ <sect3 id="mac-mpo-destroy-vnode-label">
+ <title><function>&mac.mpo;_destroy_vnode_label</function></title>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void
+ <function>&mac.mpo;_destroy_vnode_label</function></funcdef>
+ <paramdef>struct label
+ *<parameter>label</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <informaltable>
+ <tgroup cols="3">
+ &mac.thead;
+
+ <tbody>
+ <row>
+ <entry><parameter>label</parameter></entry>
+ <entry>Process label</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>Destroy the label on a vnode. In this entry point, a
+ policy module should free any internal storage associated
+ with <parameter>label</parameter> so that it may be
+ destroyed.</para>
+ </sect3>
+
+ <sect3 id="mac-mpo-copy-mbuf-label">
+ <title><function>&mac.mpo;_copy_mbuf_label</function></title>
+
>>> TRUNCATED FOR MAIL (1000 lines) <<<
More information about the p4-projects
mailing list