||FreeBSD Kernel Developer's Manual
TrustedBSD Mandatory Access Control framework
In the kernel configuration file:
The TrustedBSD mandatory access control framework permits dynamically introduced
system security modules to modify system security functionality. This can be
used to support a variety of new security services, including traditional
labeled mandatory access control models. The framework provides a series of
entry points which must be called by code supporting various kernel services,
especially with respects to access control points and object creation. The
framework then calls out to security modules to offer them the opportunity to
modify security behavior at those MAC API entry points. Both consumers of the
API (normal kernel services) and security modules must be aware of the
semantics of the API calls, particularly with respect to synchronization
primitives (such as locking).
The MAC framework manages labels on a variety of types of in-kernel objects,
including process credentials, vnodes, devfs_dirents, mount points, sockets,
mbufs, bpf descriptors, network interfaces, IP fragment queues, and pipes.
Label data on kernel objects, represented by struct
label, is policy-unaware, and may be used in the manner seen fit by
The MAC API provides a large set of entry points, too broad to specifically
document here. In general, these entry points represent an access control
check or other MAC-relevant operations, accept one or more subjects
(credentials) authorizing the activity, a set of objects on which the
operation is to be performed, and a set of operation arguments providing
information about the type of operation being requested.
Consumers of the MAC API must be aware of the locking requirements for each API
entry point: generally, appropriate locks must be held over each subject or
object being passed into the call, so that MAC modules may make use of various
aspects of the object for access control purposes. For example, vnode locks
are frequently required in order that the MAC framework and modules may
retrieve security labels and attributes from the vnodes for the purposes of
access control. Similarly, the caller must be aware of the reference counting
semantics of any subject or object passed into the MAC API: all calls require
that a valid reference to the object be held for the duration of the
(potentially lengthy) MAC API call. Under some circumstances, objects must be
held in either a shared or exclusive manner.
Each module exports a structure describing the MAC API operations that the
module chooses to implement, including initialization and destruction API
entry points, a variety of object creation and destruction calls, and a large
set of access control check points. In the future, additional audit entry
points will also be present. Module authors may choose to only implement a
subset of the entry points, setting API function pointers in the description
NULL, permitting the framework to avoid
calling into the module.
Module writers must be aware of the locking semantics of entry points that they
implement: MAC API entry points will have specific locking or reference
counting semantics for each argument, and modules must follow the locking and
reference counting protocol or risk a variety of failure modes (including race
conditions, inappropriate pointer dereferences, etc).
MAC module writers must also be aware that MAC API entry points
will frequently be invoked from deep in a kernel stack, and as such must be
careful to avoid violating more global locking requirements, such as global
lock order requirements. For example, it may be inappropriate to lock
additional objects not specifically maintained and ordered by the policy
module, or the policy module might violate a global ordering requirement
relating to those additional objects.
Finally, MAC API module implementors must be careful to avoid
inappropriately calling back into the MAC framework: the framework makes use
of locking to prevent inconsistencies during policy module attachment and
detachment. MAC API modules should avoid producing scenarios in which
deadlocks or inconsistencies might occur.
The MAC API is intended to be easily expandable as new services are added to the
kernel. In order that policies may be guaranteed the opportunity to
ubiquitously protect system subjects and objects, it is important that kernel
developers maintain awareness of when security checks or relevant subject or
object operations occur in newly written or modified kernel code. New entry
points must be carefully documented so as to prevent any confusion regarding
lock orders and semantics. Introducing new entry points requires four distinct
pieces of work: introducing new MAC API entries reflecting the operation
arguments, scattering these MAC API entry points throughout the new or
modified kernel service, extending the front-end implementation of the MAC API
framework, and modifying appropriate modules to take advantage of the new
entry points so that they may consistently enforce their policies.
System service and module authors should reference the FreeBSD
Architecture Handbook for information on the MAC Framework APIs.
The FreeBSD Architecture
The TrustedBSD MAC Framework first appeared in FreeBSD
This manual page was written by Robert Watson. This
software was contributed to the FreeBSD Project by
Network Associates Laboratories, the Security Research Division of Network
Associates Inc. under DARPA/SPAWAR contract N66001-01-C-8035
(“CBOSS”), as part of the DARPA CHATS research program.
The TrustedBSD MAC Framework was designed by
Robert Watson, and implemented by the Network
Associates Laboratories Network Security (NETSEC), Secure Execution
Environment (SEE), and Adaptive Network Defense research groups. Network
Associates Laboratory staff contributing to the CBOSS Project include (in
alphabetical order): Lee Badger,
Brian Feldman, Hrishikesh
Dandekar, Tim Fraser, Doug
Kilpatrick, Suresh Krishnaswamy,
Adam Migus, Wayne Morrison,
Andrew Reisse, Chris Vance,
and Robert Watson.
Sub-contracted staff include: Chris
Costello, Poul-Henning Kamp,
Jonathan Lemon, Kirk
McKusick, Dag-Erling Smørgrav.
Additional contributors include: Pawel
Dawidek, Chris Faulhaber,
Ilmar Habibulin, Mike
Halderman, Bosko Milekic,
Thomas Moestl, Andrew
Reiter, and Tim Robbins.
While the MAC Framework design is intended to support the containment of the
root user, not all attack channels are currently protected by entry point
checks. As such, MAC Framework policies should not be relied on, in isolation,
to protect against a malicious privileged user.
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.