1.\"- 2.\" Copyright (c) 1999, 2000, 2001, 2002 Robert N. M. Watson 3.\" Copyright (c) 2002 Networks Associates Technology, Inc. 4.\" All rights reserved. 5.\" 6.\" This software was developed by Robert Watson for the TrustedBSD Project. 7.\" 8.\" This software was developed for the FreeBSD Project in part by Network 9.\" Associates Laboratories, the Security Research Division of Network 10.\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 11.\" ("CBOSS"), as part of the DARPA CHATS research program. 12.\" 13.\" Redistribution and use in source and binary forms, with or without 14.\" modification, are permitted provided that the following conditions 15.\" are met: 16.\" 1. Redistributions of source code must retain the above copyright 17.\" notice, this list of conditions and the following disclaimer. 18.\" 2. Redistributions in binary form must reproduce the above copyright 19.\" notice, this list of conditions and the following disclaimer in the 20.\" documentation and/or other materials provided with the distribution. 21.\" 3. The names of the authors may not be used to endorse or promote 22.\" products derived from this software without specific prior written 23.\" permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.\" $FreeBSD$ 38.\" 39.Dd February 16, 2002 40.Os 41.Dt MAC 9 42.Sh NAME 43.Nm mac 44.Nd TrustedBSD Mandatory Access Control framework 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/mac.h 48.Pp 49In the kernel configuration file: 50.Cd "options MAC" 51.Cd "options MAC_DEBUG" 52.Sh DESCRIPTION 53.Ss Introduction 54The TrustedBSD mandatory access control framework permits dynamically 55introduced system security modules to modify system security functionality. 56This can be used to support a variety of new security services, including 57traditional labeled mandatory access control models. 58The framework provides a series of entry points which must be called by 59code supporting various kernel services, especially with respects to access 60control points and object creation. 61The framework then calls out to security modules to offer them the 62opportunity to modify security behavior at those MAC API entry points. 63Both consumers of the API (normal kernel services) and security modules 64must be aware of the semantics of the API calls, particularly with respect 65to synchronization primitives (such as locking). 66.Ss Kernel objects supported by the framework 67The MAC framework manages labels on a variety of types of in-kernel 68objects, including process credentials, vnodes, devfs_dirents, mount 69points, sockets, mbufs, bpf descriptors, network interfaces, ip fragment 70queues, and pipes. 71Label data on kernel objects, represented by struct label, is 72policy-unaware, and may be used in the manner seen fit by policy modules. 73.Ss API for Consumers 74The MAC API provides a large set of entry points, too broad to specifically 75document here. 76In general, these entry points represent an access control check or other 77MAC-relevant operations, accept one or more subjects (credentials) 78authorizing the activity, a set of objects on which the operation 79is to be performed, and a set of operation arguments providing information 80about the type of operation being requested. 81.Ss Locking for Consumers 82Consumers of the MAC API must be aware of the locking requirements for 83each API entry point: generally, appropriate locks must be held over each 84subject or object being passed into the call, so that MAC modules may 85make use of various aspects of the object for access control purposes. 86For example, vnode locks are frequently required in order that the MAC 87framework and modules may retrieve security labels and attributes from the 88vnodes for the purposes of access control. 89Similarly, the caller must be aware of the reference counting semantics 90of any subject or object passed into the MAC API: all calls require that 91a valid reference to the object be held for the duration of the 92(potentially lengthy) MAC API call. 93Under some circumstances, objects must be held in either a shared or 94exclusive manner. 95.Ss API for Module Writers 96Each module exports a structure describing the MAC API operations that 97the module chooses to implement, including initialization and destruction 98API entry points, a variety of object creation and destruction calls, 99and a large set of access control check points. 100In the future, additional audit entry points will also be present. 101Module authors may choose to only implement a subset of the entry points, 102setting API function pointers in the description structure to NULL, 103permitting the framework to avoid calling into the module. 104.Ss Locking for Module Writers 105Module writers must be aware of the locking semantics of entry points 106that they implement: MAC API entry points will have specific locking 107or reference counting semantics for each argument, and modules must follow 108the locking and reference counting protocol or risk a variety of failure 109modes (including race conditions, inappropriate pointer dereferences, 110etc). 111.Pp 112MAC module writers must also be aware that MAC API entry points will 113frequently be invoked from deep in a kernel stack, and as such must be 114careful to avoid violating more global locking requirements, such as 115global lock order requirements. 116For example, it may be inappropriate to lock additional objects not 117specifically maintained and ordered by the policy module, or the 118policy module might violate a global ordering requirement relating 119to those additional objects. 120.Pp 121Finally, MAC API module implementors must be careful to avoid 122inappropriately calling back into the MAC framework: the framework 123makes use of locking to prevent inconsistencies during policy module 124attachment and detachment. 125MAC API modules should avoid producing scenarios in which deadlocks 126or inconsistencies might occur. 127.Ss Adding New MAC Entry Points 128The MAC API is intended to be easily expandable as new services are 129added to the kernel. 130In order that policies may be guaranteed the opportunity to ubiquitously 131protect system subjects and objects, it is important that kernel 132developers maintain awareness of when security checks or relevant 133subject or object operations occur in newly written or modified kernel 134code. 135New entry points must be carefully documented so as to prevent any 136confusion regarding lock orders and semantics. 137Introducing new entry points requires four distinct pieces of work: 138introducing new MAC API entries reflecting the operation arguments, 139scattering these MAC API entry points throughout the new or modified 140kernel service, extending the front-end implementation of the MAC API 141framework, and modifying appropriate modules to take advantage of 142the new entry points so that they may consistently enforce their 143policies. 144.Sh ENTRY POINTS 145System service and module authors should reference the FreeBSD 146Developer's Handbook for information on the MAC Framework APIs. 147.Pp 148.Sh SEE ALSO 149.Xr acl 3 , 150.Xr cap 3 , 151.Xr mac 3 , 152.Xr lomac 4 , 153.Xr posix1e 3 , 154.Xr ucred 9 , 155.Xr vaccess 9 , 156.Xr vaccess_acl_posix1e 9 , 157.Xr VFS 9 , 158.Sh AUTHORS 159This man page was written by 160.An Robert Watson . 161This software was contributed to the 162.Fx 163Project by Network Associates Laboratories, the Security Research 164Division of Network Associates Inc. under DARPA/SPAWAR contract 165N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS research program. 166.Pp 167.An -nosplit 168The TrustedBSD MAC Framework was designed by 169.An Robert Watson , 170and implemented by the Network Associates Laboratories Network Security 171(NETSEC), Secure Execution Environement (SEE), and Adaptive 172Network Defense research groups. 173Network Associates Laboratory staff contributing to the CBOSS Project 174include (in alphabetical order): 175.An Lee Badger , 176.An Brian Feldman , 177.An Tim Fraser , 178.An Doug Kilpatrick , 179.An Suresh Krishnaswamy , 180.An Adam Migus , 181.An Wayne Morrison , 182.An Chris Vance , 183and 184.An Robert Watson . 185.Pp 186Sub-contracted staff include: 187.An Chris Costello , 188.An Poul-Henning Kamp , 189.An Jonathan Lemon , 190.An Kirk McKusick , 191.An Dag-Erling Smorgrav . 192.Pp 193Additional contributors include: 194.An Chris Faulhaber , 195.An Ilmar Habibulin , 196.An Thomas Moestl , 197and 198.An Andrew Reiter . 199.An -split 200