Resort and organize some sections:
- 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
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
en_US.ISO8859-1/books
|
|
@ -268,88 +268,6 @@
|
|||
</sect2>
|
||||
</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">
|
||||
<title>MAC Policy Architecture</title>
|
||||
|
||||
|
|
@ -376,18 +294,17 @@
|
|||
entry points that are of interest to the policy.</para></listitem>
|
||||
<listitem><para>Declaration of poicy identity, module entry
|
||||
points, and policy properties.</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
</itemizedlist>
|
||||
|
||||
<sect1 id="mac-policy-declaration">
|
||||
<title>MAC Policy Declaration</title>
|
||||
<sect2 id="mac-policy-declaration">
|
||||
<title>Policy Declaration</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>
|
||||
<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>
|
||||
|
||||
<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,
|
||||
};</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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
</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 capabilities at the
|
||||
time the module is loaded. Currently, three 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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
</sect1>
|
||||
<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>
|
||||
|
||||
<sect1 id="mac-policy-entry-points">
|
||||
<title>MAC Policy Entry Points</title>
|
||||
<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>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 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>
|
||||
<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">
|
||||
|
|
@ -7654,6 +7576,88 @@ Label destruction o</programlisting>
|
|||
</sect2>
|
||||
</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">
|
||||
<title>Userland APIs</title>
|
||||
|
||||
|
|
|
|||
|
|
@ -268,88 +268,6 @@
|
|||
</sect2>
|
||||
</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">
|
||||
<title>MAC Policy Architecture</title>
|
||||
|
||||
|
|
@ -376,18 +294,17 @@
|
|||
entry points that are of interest to the policy.</para></listitem>
|
||||
<listitem><para>Declaration of poicy identity, module entry
|
||||
points, and policy properties.</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
</itemizedlist>
|
||||
|
||||
<sect1 id="mac-policy-declaration">
|
||||
<title>MAC Policy Declaration</title>
|
||||
<sect2 id="mac-policy-declaration">
|
||||
<title>Policy Declaration</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>
|
||||
<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>
|
||||
|
||||
<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,
|
||||
};</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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
</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 capabilities at the
|
||||
time the module is loaded. Currently, three 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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
</sect1>
|
||||
<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>
|
||||
|
||||
<sect1 id="mac-policy-entry-points">
|
||||
<title>MAC Policy Entry Points</title>
|
||||
<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>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 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>
|
||||
<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">
|
||||
|
|
@ -7654,6 +7576,88 @@ Label destruction o</programlisting>
|
|||
</sect2>
|
||||
</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">
|
||||
<title>Userland APIs</title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue