Provided by:
freebsd-manpages_6.2-1_all 
NAME
mac - TrustedBSD Mandatory Access Control framework
SYNOPSIS
#include <sys/types.h>
#include <sys/mac.h>
In the kernel configuration file:
options MAC
options MAC_DEBUG
DESCRIPTION
Introduction
The TrustedBSD mandatory access control framework permits dynamically
introduced system security modules to modify system security functional‐
ity. 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 behav‐
ior 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).
Note on Appropriateness for Production Use
The TrustedBSD MAC Framework included in FreeBSD 5.0 is considered exper‐
imental, and should not be deployed in production environments without
careful consideration of the risks associated with the use of experimen‐
tal operating system features.
Kernel Objects Supported by the Framework
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 pol‐
icy modules.
API for Consumers
The MAC API provides a large set of entry points, too broad to specifi‐
cally document here. In general, these entry points represent an access
control check or other MAC-relevant operations, accept one or more sub‐
jects (credentials) authorizing the activity, a set of objects on which
the operation is to be performed, and a set of operation arguments pro‐
viding information about the type of operation being requested.
Locking for Consumers
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.
API for Module Writers
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 point‐
ers in the description structure to NULL, permitting the framework to
avoid calling into the module.
Locking for Module Writers
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 fre‐
quently be invoked from deep in a kernel stack, and as such must be care‐
ful 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 inappropri‐
ately 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.
Adding New MAC Entry Points
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 appro‐
priate 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
Developer’s Handbook for information on the MAC Framework APIs.
acl(3), mac(3), posix1e(3), mac_biba(4), mac_bsdextended(4),
mac_ifoff(4), mac_lomac(4), mac_mls(4), mac_none(4), mac_partition(4),
mac_seeotheruids(4), mac_test(4), ucred(9), vaccess(9),
vaccess_acl_posix1e(9), VFS(9)
The FreeBSD Developers’ Handbook,
http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/.
HISTORY
The TrustedBSD MAC Framework first appeared in FreeBSD 5.0.
AUTHORS
This manual page was written by Robert Watson. This software was con‐
tributed 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 imple‐
mented 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.
BUGS
See the earlier section in this document concerning appropriateness for
production use. The TrustedBSD MAC Framework is considered experimental
in FreeBSD.
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.