MAC(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 MAC(9) — the mac manual, section 9, Kernel Developer's Manual 🧚

okay bestie, welcome to the mac page — that's the TrustedBSD Mandatory Access Control framework, section 9 (kernel developer territory, so put your big-girl hat on) 💖

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <sys/mac.h>

and in the kernel configuration file:

options MAC
options MAC_DEBUG

like, that's it, that's the whole vibe check to get in 🎀

🌸 DESCRIPTION 🌸

🦋 Introduction

okay so. the TrustedBSD mandatory access control framework is literally the thing that lets security modules get introduced dynamically and then go modify how system security works 😭 it's giving "we can hot-swap the security vibes". and it's not just for one thing — it can support a whole variety of new security services, including traditional labeled mandatory access control models 💅

the framework hands you a whole series of entry points that code supporting various kernel services must call — especially anything to do with access control points and object creation. and then the framework calls out to the security modules to give them the chance to modify security behavior at those MAC API entry points 👑

but bestie, listen: both the consumers of the API (that's normal kernel services) and the security modules have to be aware of the semantics of the API calls — especially when it comes to synchronization primitives, like locking. no skipping that part fr fr 🔥

🌈 Kernel Objects Supported by the Framework

the MAC framework manages labels on a lot of different types of in-kernel objects, and the list is iconic:

  • process credentials
  • vnodes
  • devfs_dirents
  • mount points
  • sockets
  • mbufs
  • bpf descriptors
  • network interfaces
  • IP fragment queues
  • pipes

label data on kernel objects is represented by struct label, and it's policy-unaware — meaning a policy module can use it in whatever manner it sees fit 🫶

⭐ API for Consumers

the MAC API provides a large set of entry points — genuinely too broad to specifically document here, so don't come for me 🙈

but generally? these entry points represent an access control check or other MAC-relevant operations, and they accept:

  • one or more subjects (credentials) authorizing the activity
  • a set of objects on which the operation is to be performed
  • a set of operation arguments providing info about the type of operation being requested

see, structured. we love a structured API 😌

💜 Locking for Consumers

consumers of the MAC API must be aware of the locking requirements for each API entry point, okay? generally, appropriate locks must be held over each subject or object being passed into the call — that way MAC modules can actually make use of various aspects of the object for access control purposes ✨

for example: vnode locks are frequently required so that the MAC framework and modules can 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 😭 and under some circumstances, objects must be held in either a shared or exclusive manner. both. your fave has range 💅

🎀 API for Module Writers

each module exports a structure describing the MAC API operations that the module chooses to implement, and it includes:

  • initialization and destruction API entry points
  • a variety of object creation and destruction calls
  • a large set of access control check points

and in the future, additional audit entry points will also be present 👀

module authors may choose to only implement a subset of the entry points — just set API function pointers in the description structure to NULL, which lets the framework avoid calling into the module. lowkey efficient, highkey slay 💖

🧚 Locking for Module Writers

module writers must be aware of the locking semantics of the entry points 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. 💀 yeah. not cute. do the protocol.

MAC module writers must also be aware that MAC API entry points will frequently be invoked from deep in a kernel stack — so be careful to avoid violating more global locking requirements, like 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. like, stay in your lane, respectfully 🫶

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 🔥 no deadlocks in this house.

👑 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's 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. and introducing new entry points requires four distinct pieces of work:

  1. introducing new MAC API entries reflecting the operation arguments
  2. scattering these MAC API entry points throughout the new or modified kernel service
  3. extending the front-end implementation of the MAC API framework
  4. modifying appropriate modules to take advantage of the new entry points so that they may consistently enforce their policies

four steps, no shortcuts, periodt ✨

🌟 ENTRY POINTS 🌟

system service and module authors should reference the FreeBSD Architecture Handbook for information on the MAC Framework APIs 📖 (iykyk)

💖 SEE ALSO 💖

and the FreeBSD Architecture Handbook, at https://docs.freebsd.org/en/books/arch-handbook/ 🦋

🕰️ HISTORY 🕰️

the TrustedBSD MAC Framework first appeared in FreeBSD 5.0 🎉 a real one.

🌸 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 💀

okay so, 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.

bestie. read that again. in isolation = not enough on its own. don't @ me, @ the manpage 🫶

and that's the whole page, you ate that 💅✨ this one's from the Debian build, dated May 20, 2021 — mwah, go forth and label responsibly 🎀🦋

📦 where this page comes from