os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Resort and organize some sections:

Browse source 
- Move Userland Architecture down to the Userland APIs section.

- Push most of the Policy-related subsections into the MAC Policy
  Architecture section.  Tweak a little language so it makes
  sense.
This commit is contained in:
Robert Watson 2003-04-20 18:01:22 +00:00
parent a7b83db368
commit 96eb481cbd
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=16626
2 changed files with 424 additions and 416 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -268,88 +268,6 @@
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="mac-userland-arch">
<title>Userland Architecture</title>
<para>The TrustedBSD MAC Framework includes a number of
policy-agnostic elements, including MAC library interfaces
for abstractly managing labels, modifications to the system
credential management and login libraries to support the
assignment of MAC labels to users, and a set of tools to
monitor and modify labels on processes, files, and network
interfaces. More details on the user architecture will
be added to this section in the near future.</para>
<sect2 id="mac-userland-labels">
<title>APIs for Policy-Agnostic Label Management</title>
<para>The TrustedBSD MAC Framework provides a number of
library and system calls permitting applications to
manage MAC labels on objects using a poloicy-agnostic
interface. This permits applications to manipulate
labels for a variety of policies without being
written to support specific policies. These interfaces
are used by general-purpose tools such as &man.ifconfig.8;,
&man.ls.1; and &man.ps.1; to view labels on network
interfaces, files, and processes. The APIs also support
MAC management tools including &man.getfmac.8;,
&man.getpmac.8;, &man.setfmac.8;, &man.setfsmac.8;,
and &man.setpmac.8;. The MAC APIs are documented in
&man.mac.3;.</para>
<para>Applications handle MAC labels in two forms: an
internalized form used to return and set labels on
processes and objects (<literal>mac_t</literal>),
and externalized form based on C strings appropriate for
storage in configuration files, display to the user, or
input from the user. Each MAC label contains a number of
elements, each consisting of a name and value pair.
Policy modules in the kernel bind to specific names
and interpret the values in policy-specific ways. In
the externalized string form, labels are represented
by a comma-delimited list of name and value pairs separated
by the <literal>/</literal> character. Labels may be
directly converted to and from text using provided APIs;
when retrieving labels from the kernel, internalized
label storage must first be prepared for the desired
label element set. Typically, this is done in one of
two ways: using &man.mac.prepare.3; and an arbitrary
list of desired label elements, or one of the variants
of the call that loads a default element set from the
&man.mac.conf.5; configuration file. Per-object
defaults permit application writers to usefully display
labels associated with objects without being aware of
the policies present in the system.</para>
<note><para>Currently, direct manipulation of label elements
other than by conversion to a text string, string editing,
and conversion back to an internalized label is not supported
by the MAC library. Such interfaces may be added in the
future if they prove necessary for application
writers.</para></note>
</sect2>
<sect2 id="mac-userland-credentials">
<title>Binding of Labels to Users</title>
<para>The standard user context management interface,
&man.setusercontext.3;, has been modified to retrieve
MAC labels associated with a user's class from
&man.login.conf.5;. These labels are then set along
with other user context when either
<literal>LOGIN_SETALL</literal> is specified, or when
<literal>LOGIN_SETMAC</literal> is explicitly
specified.</para>
<note><para>It is expected that, in a future version of FreeBSD,
the MAC label database will be separated from the
<filename>login.conf</filename> user class abstraction,
and be maintained in a separate database. However, the
&man.setusercontext.3; API should remain the same
following such a change.</para></note>
</sect2>
</sect1>
<sect1 id="mac-policy-architecture"> <sect1 id="mac-policy-architecture">
<title>MAC Policy Architecture</title> <title>MAC Policy Architecture</title>
@ -376,18 +294,17 @@
entry points that are of interest to the policy.</para></listitem> entry points that are of interest to the policy.</para></listitem>
<listitem><para>Declaration of poicy identity, module entry <listitem><para>Declaration of poicy identity, module entry
points, and policy properties.</para></listitem> points, and policy properties.</para></listitem>
</itemizedlist> </itemizedlist>
</sect1>
<sect1 id="mac-policy-declaration"> <sect2 id="mac-policy-declaration">
<title>MAC Policy Declaration</title> <title>Policy Declaration</title>
<para>Modules may be declared using the <para>Modules may be declared using the
<function>MAC_POLICY_SET()</function> macro, which names the <function>MAC_POLICY_SET()</function> macro, which names the
policy, provides a reference to the MAC entry point vector, policy, provides a reference to the MAC entry point vector,
provides load-time flags determining how the policy framework provides load-time flags determining how the policy framework
should handle the policy, and optionally requests the should handle the policy, and optionally requests the
allocation of label state by the framework.</para> 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 =
{ {
@ -401,134 +318,139 @@
.mpo_check_vnode_write = mac_<replaceable>policy</replaceable>_check_vnode_write, .mpo_check_vnode_write = mac_<replaceable>policy</replaceable>_check_vnode_write,
};</programlisting> };</programlisting>
<para>The MAC policy entry point vector, <para>The MAC policy entry point vector,
<varname>mac_<replaceable>policy</replaceable>_ops</varname> in this example, associates <varname>mac_<replaceable>policy</replaceable>_ops</varname> in this example, associates
functions defined in the module with specific entry points. A functions defined in the module with specific entry points. A
complete listing of available entry points and their complete listing of available entry points and their
prototypes may be found in the MAC entry point reference prototypes may be found in the MAC entry point reference
section. Of specific interest during module registration are section. Of specific interest during module registration are
the <symbol>.mpo_destroy</symbol> and <symbol>.mpo_init</symbol> the <symbol>.mpo_destroy</symbol> and <symbol>.mpo_init</symbol>
entry points. <symbol>.mpo_init</symbol> will be invoked once a entry points. <symbol>.mpo_init</symbol> will be invoked once a
policy is successfully registered with the module framework policy is successfully registered with the module framework
but prior to any other entry points becoming active. This but prior to any other entry points becoming active. This
permits the policy to perform any policy-specific allocation permits the policy to perform any policy-specific allocation
and initialization, such as initialization of any data or and initialization, such as initialization of any data or
locks. <symbol>.mpo_destroy</symbol> will be invoked when a locks. <symbol>.mpo_destroy</symbol> will be invoked when a
policy module is unloaded to permit releasing of any allocated policy module is unloaded to permit releasing of any allocated
memory and destruction of locks. Currently, these two entry memory and destruction of locks. Currently, these two entry
points are invoked with the MAC policy list mutex held to points are invoked with the MAC policy list mutex held to
prevent any other entry points from being invoked: this will prevent any other entry points from being invoked: this will
be changed, but in the mean time, policies should be careful be changed, but in the mean time, policies should be careful
about what kernel primitives they invoke so as to avoid lock about what kernel primitives they invoke so as to avoid lock
ordering or sleeping problems.</para> ordering or sleeping problems.</para>
<para>The policy declaration's module name field exists so that <para>The policy declaration's module name field exists so that
the module may be uniquely identified for the purposes of the module may be uniquely identified for the purposes of
module dependencies. An appropriate string should be selected. module dependencies. An appropriate string should be selected.
The full string name of the policy is displayed to the user The full string name of the policy is displayed to the user
via the kernel log during load and unload events, and also via the kernel log during load and unload events, and also
exported when providing status information to userland exported when providing status information to userland
processes.</para> processes.</para>
</sect2>
<para>The policy flags field permits the module to provide the <sect2 id="mac-policy-flags">
framework with information about its capabilities at the <title>Policy Flags</title>
time the module is loaded. Currently, three flags are
defined:</para>
<variablelist> <para>The policy declaration flags field permits the module to
<varlistentry> provide the framework with information about its capabilities at
<term>MPC_LOADTIME_FLAG_UNLOADOK</term> the time the module is loaded. Currently, three flags are
defined:</para>
<listitem> <variablelist>
<para>This flag indicates that the policy module may be <varlistentry>
unloaded. If this flag is not provided, then the policy <term>MPC_LOADTIME_FLAG_UNLOADOK</term>
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> <listitem>
<term>MPC_LOADTIME_FLAG_NOTLATE</term> <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>
<listitem><para>This flag indicates that the policy module <varlistentry>
must be loaded and initialized early in the boot <term>MPC_LOADTIME_FLAG_NOTLATE</term>
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> <listitem>
<term>MPC_LOADTIME_FLAG_LABELMBUFS</term> <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> <varlistentry>
<para>This flag indicates that the policy module requires <term>MPC_LOADTIME_FLAG_LABELMBUFS</term>
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> <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 <note><para>Policies using the
<literal>MPC_LOADTIME_FLAG_LABELMBUFS</literal> without the <literal>MPC_LOADTIME_FLAG_LABELMBUFS</literal> without the
<literal>MPC_LOADTIME_FLAG_NOTLATE</literal> flag set <literal>MPC_LOADTIME_FLAG_NOTLATE</literal> flag set
must be able to correctly handle <literal>NULL</literal> must be able to correctly handle <literal>NULL</literal>
Mbuf label pointers passed into entry points. This is necessary Mbuf label pointers passed into entry points. This is necessary
as in-flight Mbufs without label storage may persist after a as in-flight Mbufs without label storage may persist after a
policy enabling Mbuf labeling has been loaded. If a policy policy enabling Mbuf labeling has been loaded. If a policy
is loaded before the network subsystem is active (i.e., the is loaded before the network subsystem is active (i.e., the
policy is not being loaded late), then all Mbufs are guaranteed policy is not being loaded late), then all Mbufs are guaranteed
to have label storage.</para></note> to have label storage.</para></note>
</sect1> </sect2>
<sect1 id="mac-policy-entry-points"> <sect2 id="mac-policy-entry-points">
<title>MAC Policy Entry Points</title> <title>Policy Entry Points</title>
<para>Four classes of entry points are offered to policies <para>Four classes of entry points are offered to policies
registered with the framework: entry points associated with registered with the framework: entry points associated with
the registration and management of policies, entry points the registration and management of policies, entry points
denoting initialization, creation, destruction, and other life denoting initialization, creation, destruction, and other life
cycle events for kernel objects, events associated with access cycle events for kernel objects, events associated with access
control decisions that the policy module may influence, and control decisions that the policy module may influence, and
calls associated with the management of labels on objects. In calls associated with the management of labels on objects. In
addition, a <function>mac_syscall()</function> entry point is addition, a <function>mac_syscall()</function> entry point is
provided so that policies may extend the kernel interface provided so that policies may extend the kernel interface
without registering new system calls.</para> without registering new system calls.</para>
<para>Policy module writers should be aware of the kernel <para>Policy module writers should be aware of the kernel
locking strategy, as well as what object locks are available locking strategy, as well as what object locks are available
during which entry points. Writers should attempt to avoid during which entry points. Writers should attempt to avoid
deadlock scenarios by avoiding grabbing non-leaf locks inside deadlock scenarios by avoiding grabbing non-leaf locks inside
of entry points, and also follow the locking protocol for of entry points, and also follow the locking protocol for
object access and modification. In particular, writers should object access and modification. In particular, writers should
be aware that while necessary locks to access objects and be aware that while necessary locks to access objects and
their labels are generally held, sufficient locks to modify an their labels are generally held, sufficient locks to modify an
object or its label may not be present for all entry points. object or its label may not be present for all entry points.
Locking information for arguments is documented in the MAC Locking information for arguments is documented in the MAC
framework entry point document.</para> framework entry point document.</para>
<para>Policy entry points will pass a reference to the object <para>Policy entry points will pass a reference to the object
label along with the object itself. This permits labeled label along with the object itself. This permits labeled
policies to be unaware of the internals of the object yet policies to be unaware of the internals of the object yet
still make decisions based on the label. The exception to this still make decisions based on the label. The exception to this
is the process credential, which is assumed to be understood is the process credential, which is assumed to be understood
by policies as a first class security object in the kernel. by policies as a first class security object in the kernel.
Policies that do not implement labels on kernel objects will Policies that do not implement labels on kernel objects will
be passed NULL pointers for label arguments to entry be passed NULL pointers for label arguments to entry
points.</para> points.</para>
</sect2>
</sect1> </sect1>
<sect1 id="mac-entry-point-reference"> <sect1 id="mac-entry-point-reference">
@ -7654,6 +7576,88 @@ Label destruction o</programlisting>
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="mac-userland-arch">
<title>Userland Architecture</title>
<para>The TrustedBSD MAC Framework includes a number of
policy-agnostic elements, including MAC library interfaces
for abstractly managing labels, modifications to the system
credential management and login libraries to support the
assignment of MAC labels to users, and a set of tools to
monitor and modify labels on processes, files, and network
interfaces. More details on the user architecture will
be added to this section in the near future.</para>
<sect2 id="mac-userland-labels">
<title>APIs for Policy-Agnostic Label Management</title>
<para>The TrustedBSD MAC Framework provides a number of
library and system calls permitting applications to
manage MAC labels on objects using a poloicy-agnostic
interface. This permits applications to manipulate
labels for a variety of policies without being
written to support specific policies. These interfaces
are used by general-purpose tools such as &man.ifconfig.8;,
&man.ls.1; and &man.ps.1; to view labels on network
interfaces, files, and processes. The APIs also support
MAC management tools including &man.getfmac.8;,
&man.getpmac.8;, &man.setfmac.8;, &man.setfsmac.8;,
and &man.setpmac.8;. The MAC APIs are documented in
&man.mac.3;.</para>
<para>Applications handle MAC labels in two forms: an
internalized form used to return and set labels on
processes and objects (<literal>mac_t</literal>),
and externalized form based on C strings appropriate for
storage in configuration files, display to the user, or
input from the user. Each MAC label contains a number of
elements, each consisting of a name and value pair.
Policy modules in the kernel bind to specific names
and interpret the values in policy-specific ways. In
the externalized string form, labels are represented
by a comma-delimited list of name and value pairs separated
by the <literal>/</literal> character. Labels may be
directly converted to and from text using provided APIs;
when retrieving labels from the kernel, internalized
label storage must first be prepared for the desired
label element set. Typically, this is done in one of
two ways: using &man.mac.prepare.3; and an arbitrary
list of desired label elements, or one of the variants
of the call that loads a default element set from the
&man.mac.conf.5; configuration file. Per-object
defaults permit application writers to usefully display
labels associated with objects without being aware of
the policies present in the system.</para>
<note><para>Currently, direct manipulation of label elements
other than by conversion to a text string, string editing,
and conversion back to an internalized label is not supported
by the MAC library. Such interfaces may be added in the
future if they prove necessary for application
writers.</para></note>
</sect2>
<sect2 id="mac-userland-credentials">
<title>Binding of Labels to Users</title>
<para>The standard user context management interface,
&man.setusercontext.3;, has been modified to retrieve
MAC labels associated with a user's class from
&man.login.conf.5;. These labels are then set along
with other user context when either
<literal>LOGIN_SETALL</literal> is specified, or when
<literal>LOGIN_SETMAC</literal> is explicitly
specified.</para>
<note><para>It is expected that, in a future version of FreeBSD,
the MAC label database will be separated from the
<filename>login.conf</filename> user class abstraction,
and be maintained in a separate database. However, the
&man.setusercontext.3; API should remain the same
following such a change.</para></note>
</sect2>
</sect1>
<sect1 id="mac-userland-api"> <sect1 id="mac-userland-api">
<title>Userland APIs</title> <title>Userland APIs</title>

416
en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml
View file

@ -268,88 +268,6 @@
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="mac-userland-arch">
<title>Userland Architecture</title>
<para>The TrustedBSD MAC Framework includes a number of
policy-agnostic elements, including MAC library interfaces
for abstractly managing labels, modifications to the system
credential management and login libraries to support the
assignment of MAC labels to users, and a set of tools to
monitor and modify labels on processes, files, and network
interfaces. More details on the user architecture will
be added to this section in the near future.</para>
<sect2 id="mac-userland-labels">
<title>APIs for Policy-Agnostic Label Management</title>
<para>The TrustedBSD MAC Framework provides a number of
library and system calls permitting applications to
manage MAC labels on objects using a poloicy-agnostic
interface. This permits applications to manipulate
labels for a variety of policies without being
written to support specific policies. These interfaces
are used by general-purpose tools such as &man.ifconfig.8;,
&man.ls.1; and &man.ps.1; to view labels on network
interfaces, files, and processes. The APIs also support
MAC management tools including &man.getfmac.8;,
&man.getpmac.8;, &man.setfmac.8;, &man.setfsmac.8;,
and &man.setpmac.8;. The MAC APIs are documented in
&man.mac.3;.</para>
<para>Applications handle MAC labels in two forms: an
internalized form used to return and set labels on
processes and objects (<literal>mac_t</literal>),
and externalized form based on C strings appropriate for
storage in configuration files, display to the user, or
input from the user. Each MAC label contains a number of
elements, each consisting of a name and value pair.
Policy modules in the kernel bind to specific names
and interpret the values in policy-specific ways. In
the externalized string form, labels are represented
by a comma-delimited list of name and value pairs separated
by the <literal>/</literal> character. Labels may be
directly converted to and from text using provided APIs;
when retrieving labels from the kernel, internalized
label storage must first be prepared for the desired
label element set. Typically, this is done in one of
two ways: using &man.mac.prepare.3; and an arbitrary
list of desired label elements, or one of the variants
of the call that loads a default element set from the
&man.mac.conf.5; configuration file. Per-object
defaults permit application writers to usefully display
labels associated with objects without being aware of
the policies present in the system.</para>
<note><para>Currently, direct manipulation of label elements
other than by conversion to a text string, string editing,
and conversion back to an internalized label is not supported
by the MAC library. Such interfaces may be added in the
future if they prove necessary for application
writers.</para></note>
</sect2>
<sect2 id="mac-userland-credentials">
<title>Binding of Labels to Users</title>
<para>The standard user context management interface,
&man.setusercontext.3;, has been modified to retrieve
MAC labels associated with a user's class from
&man.login.conf.5;. These labels are then set along
with other user context when either
<literal>LOGIN_SETALL</literal> is specified, or when
<literal>LOGIN_SETMAC</literal> is explicitly
specified.</para>
<note><para>It is expected that, in a future version of FreeBSD,
the MAC label database will be separated from the
<filename>login.conf</filename> user class abstraction,
and be maintained in a separate database. However, the
&man.setusercontext.3; API should remain the same
following such a change.</para></note>
</sect2>
</sect1>
<sect1 id="mac-policy-architecture"> <sect1 id="mac-policy-architecture">
<title>MAC Policy Architecture</title> <title>MAC Policy Architecture</title>
@ -376,18 +294,17 @@
entry points that are of interest to the policy.</para></listitem> entry points that are of interest to the policy.</para></listitem>
<listitem><para>Declaration of poicy identity, module entry <listitem><para>Declaration of poicy identity, module entry
points, and policy properties.</para></listitem> points, and policy properties.</para></listitem>
</itemizedlist> </itemizedlist>
</sect1>
<sect1 id="mac-policy-declaration"> <sect2 id="mac-policy-declaration">
<title>MAC Policy Declaration</title> <title>Policy Declaration</title>
<para>Modules may be declared using the <para>Modules may be declared using the
<function>MAC_POLICY_SET()</function> macro, which names the <function>MAC_POLICY_SET()</function> macro, which names the
policy, provides a reference to the MAC entry point vector, policy, provides a reference to the MAC entry point vector,
provides load-time flags determining how the policy framework provides load-time flags determining how the policy framework
should handle the policy, and optionally requests the should handle the policy, and optionally requests the
allocation of label state by the framework.</para> 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 =
{ {
@ -401,134 +318,139 @@
.mpo_check_vnode_write = mac_<replaceable>policy</replaceable>_check_vnode_write, .mpo_check_vnode_write = mac_<replaceable>policy</replaceable>_check_vnode_write,
};</programlisting> };</programlisting>
<para>The MAC policy entry point vector, <para>The MAC policy entry point vector,
<varname>mac_<replaceable>policy</replaceable>_ops</varname> in this example, associates <varname>mac_<replaceable>policy</replaceable>_ops</varname> in this example, associates
functions defined in the module with specific entry points. A functions defined in the module with specific entry points. A
complete listing of available entry points and their complete listing of available entry points and their
prototypes may be found in the MAC entry point reference prototypes may be found in the MAC entry point reference
section. Of specific interest during module registration are section. Of specific interest during module registration are
the <symbol>.mpo_destroy</symbol> and <symbol>.mpo_init</symbol> the <symbol>.mpo_destroy</symbol> and <symbol>.mpo_init</symbol>
entry points. <symbol>.mpo_init</symbol> will be invoked once a entry points. <symbol>.mpo_init</symbol> will be invoked once a
policy is successfully registered with the module framework policy is successfully registered with the module framework
but prior to any other entry points becoming active. This but prior to any other entry points becoming active. This
permits the policy to perform any policy-specific allocation permits the policy to perform any policy-specific allocation
and initialization, such as initialization of any data or and initialization, such as initialization of any data or
locks. <symbol>.mpo_destroy</symbol> will be invoked when a locks. <symbol>.mpo_destroy</symbol> will be invoked when a
policy module is unloaded to permit releasing of any allocated policy module is unloaded to permit releasing of any allocated
memory and destruction of locks. Currently, these two entry memory and destruction of locks. Currently, these two entry
points are invoked with the MAC policy list mutex held to points are invoked with the MAC policy list mutex held to
prevent any other entry points from being invoked: this will prevent any other entry points from being invoked: this will
be changed, but in the mean time, policies should be careful be changed, but in the mean time, policies should be careful
about what kernel primitives they invoke so as to avoid lock about what kernel primitives they invoke so as to avoid lock
ordering or sleeping problems.</para> ordering or sleeping problems.</para>
<para>The policy declaration's module name field exists so that <para>The policy declaration's module name field exists so that
the module may be uniquely identified for the purposes of the module may be uniquely identified for the purposes of
module dependencies. An appropriate string should be selected. module dependencies. An appropriate string should be selected.
The full string name of the policy is displayed to the user The full string name of the policy is displayed to the user
via the kernel log during load and unload events, and also via the kernel log during load and unload events, and also
exported when providing status information to userland exported when providing status information to userland
processes.</para> processes.</para>
</sect2>
<para>The policy flags field permits the module to provide the <sect2 id="mac-policy-flags">
framework with information about its capabilities at the <title>Policy Flags</title>
time the module is loaded. Currently, three flags are
defined:</para>
<variablelist> <para>The policy declaration flags field permits the module to
<varlistentry> provide the framework with information about its capabilities at
<term>MPC_LOADTIME_FLAG_UNLOADOK</term> the time the module is loaded. Currently, three flags are
defined:</para>
<listitem> <variablelist>
<para>This flag indicates that the policy module may be <varlistentry>
unloaded. If this flag is not provided, then the policy <term>MPC_LOADTIME_FLAG_UNLOADOK</term>
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> <listitem>
<term>MPC_LOADTIME_FLAG_NOTLATE</term> <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>
<listitem><para>This flag indicates that the policy module <varlistentry>
must be loaded and initialized early in the boot <term>MPC_LOADTIME_FLAG_NOTLATE</term>
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> <listitem>
<term>MPC_LOADTIME_FLAG_LABELMBUFS</term> <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> <varlistentry>
<para>This flag indicates that the policy module requires <term>MPC_LOADTIME_FLAG_LABELMBUFS</term>
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> <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 <note><para>Policies using the
<literal>MPC_LOADTIME_FLAG_LABELMBUFS</literal> without the <literal>MPC_LOADTIME_FLAG_LABELMBUFS</literal> without the
<literal>MPC_LOADTIME_FLAG_NOTLATE</literal> flag set <literal>MPC_LOADTIME_FLAG_NOTLATE</literal> flag set
must be able to correctly handle <literal>NULL</literal> must be able to correctly handle <literal>NULL</literal>
Mbuf label pointers passed into entry points. This is necessary Mbuf label pointers passed into entry points. This is necessary
as in-flight Mbufs without label storage may persist after a as in-flight Mbufs without label storage may persist after a
policy enabling Mbuf labeling has been loaded. If a policy policy enabling Mbuf labeling has been loaded. If a policy
is loaded before the network subsystem is active (i.e., the is loaded before the network subsystem is active (i.e., the
policy is not being loaded late), then all Mbufs are guaranteed policy is not being loaded late), then all Mbufs are guaranteed
to have label storage.</para></note> to have label storage.</para></note>
</sect1> </sect2>
<sect1 id="mac-policy-entry-points"> <sect2 id="mac-policy-entry-points">
<title>MAC Policy Entry Points</title> <title>Policy Entry Points</title>
<para>Four classes of entry points are offered to policies <para>Four classes of entry points are offered to policies
registered with the framework: entry points associated with registered with the framework: entry points associated with
the registration and management of policies, entry points the registration and management of policies, entry points
denoting initialization, creation, destruction, and other life denoting initialization, creation, destruction, and other life
cycle events for kernel objects, events associated with access cycle events for kernel objects, events associated with access
control decisions that the policy module may influence, and control decisions that the policy module may influence, and
calls associated with the management of labels on objects. In calls associated with the management of labels on objects. In
addition, a <function>mac_syscall()</function> entry point is addition, a <function>mac_syscall()</function> entry point is
provided so that policies may extend the kernel interface provided so that policies may extend the kernel interface
without registering new system calls.</para> without registering new system calls.</para>
<para>Policy module writers should be aware of the kernel <para>Policy module writers should be aware of the kernel
locking strategy, as well as what object locks are available locking strategy, as well as what object locks are available
during which entry points. Writers should attempt to avoid during which entry points. Writers should attempt to avoid
deadlock scenarios by avoiding grabbing non-leaf locks inside deadlock scenarios by avoiding grabbing non-leaf locks inside
of entry points, and also follow the locking protocol for of entry points, and also follow the locking protocol for
object access and modification. In particular, writers should object access and modification. In particular, writers should
be aware that while necessary locks to access objects and be aware that while necessary locks to access objects and
their labels are generally held, sufficient locks to modify an their labels are generally held, sufficient locks to modify an
object or its label may not be present for all entry points. object or its label may not be present for all entry points.
Locking information for arguments is documented in the MAC Locking information for arguments is documented in the MAC
framework entry point document.</para> framework entry point document.</para>
<para>Policy entry points will pass a reference to the object <para>Policy entry points will pass a reference to the object
label along with the object itself. This permits labeled label along with the object itself. This permits labeled
policies to be unaware of the internals of the object yet policies to be unaware of the internals of the object yet
still make decisions based on the label. The exception to this still make decisions based on the label. The exception to this
is the process credential, which is assumed to be understood is the process credential, which is assumed to be understood
by policies as a first class security object in the kernel. by policies as a first class security object in the kernel.
Policies that do not implement labels on kernel objects will Policies that do not implement labels on kernel objects will
be passed NULL pointers for label arguments to entry be passed NULL pointers for label arguments to entry
points.</para> points.</para>
</sect2>
</sect1> </sect1>
<sect1 id="mac-entry-point-reference"> <sect1 id="mac-entry-point-reference">
@ -7654,6 +7576,88 @@ Label destruction o</programlisting>
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="mac-userland-arch">
<title>Userland Architecture</title>
<para>The TrustedBSD MAC Framework includes a number of
policy-agnostic elements, including MAC library interfaces
for abstractly managing labels, modifications to the system
credential management and login libraries to support the
assignment of MAC labels to users, and a set of tools to
monitor and modify labels on processes, files, and network
interfaces. More details on the user architecture will
be added to this section in the near future.</para>
<sect2 id="mac-userland-labels">
<title>APIs for Policy-Agnostic Label Management</title>
<para>The TrustedBSD MAC Framework provides a number of
library and system calls permitting applications to
manage MAC labels on objects using a poloicy-agnostic
interface. This permits applications to manipulate
labels for a variety of policies without being
written to support specific policies. These interfaces
are used by general-purpose tools such as &man.ifconfig.8;,
&man.ls.1; and &man.ps.1; to view labels on network
interfaces, files, and processes. The APIs also support
MAC management tools including &man.getfmac.8;,
&man.getpmac.8;, &man.setfmac.8;, &man.setfsmac.8;,
and &man.setpmac.8;. The MAC APIs are documented in
&man.mac.3;.</para>
<para>Applications handle MAC labels in two forms: an
internalized form used to return and set labels on
processes and objects (<literal>mac_t</literal>),
and externalized form based on C strings appropriate for
storage in configuration files, display to the user, or
input from the user. Each MAC label contains a number of
elements, each consisting of a name and value pair.
Policy modules in the kernel bind to specific names
and interpret the values in policy-specific ways. In
the externalized string form, labels are represented
by a comma-delimited list of name and value pairs separated
by the <literal>/</literal> character. Labels may be
directly converted to and from text using provided APIs;
when retrieving labels from the kernel, internalized
label storage must first be prepared for the desired
label element set. Typically, this is done in one of
two ways: using &man.mac.prepare.3; and an arbitrary
list of desired label elements, or one of the variants
of the call that loads a default element set from the
&man.mac.conf.5; configuration file. Per-object
defaults permit application writers to usefully display
labels associated with objects without being aware of
the policies present in the system.</para>
<note><para>Currently, direct manipulation of label elements
other than by conversion to a text string, string editing,
and conversion back to an internalized label is not supported
by the MAC library. Such interfaces may be added in the
future if they prove necessary for application
writers.</para></note>
</sect2>
<sect2 id="mac-userland-credentials">
<title>Binding of Labels to Users</title>
<para>The standard user context management interface,
&man.setusercontext.3;, has been modified to retrieve
MAC labels associated with a user's class from
&man.login.conf.5;. These labels are then set along
with other user context when either
<literal>LOGIN_SETALL</literal> is specified, or when
<literal>LOGIN_SETMAC</literal> is explicitly
specified.</para>
<note><para>It is expected that, in a future version of FreeBSD,
the MAC label database will be separated from the
<filename>login.conf</filename> user class abstraction,
and be maintained in a separate database. However, the
&man.setusercontext.3; API should remain the same
following such a change.</para></note>
</sect2>
</sect1>
<sect1 id="mac-userland-api"> <sect1 id="mac-userland-api">
<title>Userland APIs</title> <title>Userland APIs</title>