Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
MAC(9)		       FreeBSD Kernel Developer's Manual		MAC(9)

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.

ENTRY POINTS
     System service and	module authors should reference	the FreeBSD
     Developer's 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 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 Smorgrav.

     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.

FreeBSD	9.3		       February	16, 2002		   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | ENTRY POINTS | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=mac&sektion=9&manpath=FreeBSD+6.3-RELEASE>

home | help