MAC(9) 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 in- troduced 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 pro- vides a series of entry points which must be called by code supporting var- ious 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). Kernel Objects Supported by the Framework The MAC framework manages labels on a variety of types of in-kernel ob- jects, 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 (cre- dentials) 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 sub- ject 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 circum- stances, 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 im- plement 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 refer- ence 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 careful to avoid violating more global locking requirements, such as global lock order requirements. For example, it may be inappropriate to lock addi- tional objects not specifically maintained and ordered by the policy mod- ule, or the policy module might violate a global ordering requirement re- lating 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 lock- ing to prevent inconsistencies during policy module attachment and detach- ment. 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 ker- nel developers maintain awareness of when security checks or relevant sub- ject or object operations occur in newly written or modified kernel code. New entry points must be carefully documented so as to prevent any confu- sion regarding lock orders and semantics. Introducing new entry points re- quires four distinct pieces of work: introducing new MAC API entries re- flecting the operation arguments, scattering these MAC API entry points throughout the new or modified kernel service, extending the front-end im- plementation of the MAC API framework, and modifying appropriate modules to take advantage of the new entry points so that they may consistently en- force 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(4), ucred(9), vaccess(9), vac- cess_acl_posix1e(9), VFS(9), VOP_SETLABEL(9) The FreeBSD Architecture Handbook, https://docs.freebsd.org/en/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 con- tributed to the FreeBSD Project by Network Associates Laboratories, the Se- curity Research Division of Network Associates Inc. under DARPA/SPAWAR con- tract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS research pro- gram. 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 in- clude (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 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 15.1 May 20, 2021 MAC(9)
NAME | SYNOPSIS | DESCRIPTION | ENTRY POINTS | SEE ALSO | HISTORY | AUTHORS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mac&sektion=9&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>