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