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 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).

   Note on Appropriateness for Production Use
     The TrustedBSD MAC Framework included in FreeBSD 5.0 is considered experimental, and should
     not be deployed in production environments without careful consideration of the risks
     associated with the use of experimental 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
     policy modules.

   API for Consumers
     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.

   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 pointers 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 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.

   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 appropriate
     modules to take advantage of the new entry points so that they may consistently enforce
     their policies.

ENTRY POINTS

     System service and module authors should reference the FreeBSD Architecture Handbook for
     information on the MAC Framework APIs.

SEE ALSO

     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 Architecture Handbook, http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/arch-
     handbook/.

HISTORY

     The TrustedBSD MAC Framework first appeared in FreeBSD 5.0.

AUTHORS

     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.

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.