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

functionality. This can be used to support a variety of new security

services,
including traditional labeled mandatory access control mod

els. 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 se

curity 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 con

sidered experimental, and should not be deployed in production environ

ments 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_di

rents, mount
points, sockets, mbufs, bpf descriptors, network interfaces,

IP fragment
queues, and pipes. Label data on kernel objects, represent

ed 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 repre

sent an access
control check or other MAC-relevant operations, accept one

or more subjects (credentials) authorizing the activity, a set of ob

jects on which
the operation is to be performed, and a set of operation ar

guments providing information about the type of operation being re

quested.

Locking for Consumers

Consumers of the MAC API must be aware of the locking re

quirements 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 at

tributes 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 oper

ations that
the module chooses to implement, including initialization

and destruction
API entry points, a variety of object creation and destruc

tion 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 en

try 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 vari

ety 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 inappropri

ate 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 at

tachment and
detachment. MAC API modules should avoid producing scenar

ios in which
deadlocks or inconsistencies might occur.

Adding New MAC Entry Points

The MAC API is intended to be easily expandable as new ser

vices 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 modi

fied 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 modi

fying 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
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 soft

ware was contributed to the FreeBSD Project by Network Associates Labo

ratories, 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 Secu

rity (NETSEC),
Secure Execution Environment (SEE), and Adaptive Network De

fense 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 Kr

ishnaswamy,
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 Faul

haber, Ilmar
Habibulin, Mike Halderman, Bosko Milekic, Thomas Moestl, An

drew Reiter,
and Tim Robbins.

BUGS

See the earlier section in this document concerning appro

priateness 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 pro

tected by entry
point checks. As such, MAC Framework policies should not be

relied on,
in isolation, to protect against a malicious privileged us

er.

BSD February 16, 2002

BSD