1.\"- 2.\" Copyright (c) 1999-2002 Robert N. M. Watson 3.\" Copyright (c) 2002-2004 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.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" $FreeBSD$ 35.\" 36.Dd July 10, 2006 37.Dt MAC 9 38.Os 39.Sh NAME 40.Nm mac 41.Nd TrustedBSD Mandatory Access Control framework 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/mac.h 45.Pp 46In the kernel configuration file: 47.Cd "options MAC" 48.Cd "options MAC_DEBUG" 49.Sh DESCRIPTION 50.Ss Introduction 51The 52.Tn TrustedBSD 53mandatory access control framework permits dynamically 54introduced system security modules to modify system security functionality. 55This can be used to support a variety of new security services, including 56traditional labeled mandatory access control models. 57The framework provides a series of entry points which must be called by 58code supporting various kernel services, especially with respects to access 59control points and object creation. 60The framework then calls out to security modules to offer them the 61opportunity to modify security behavior at those MAC API entry points. 62Both consumers of the API (normal kernel services) and security modules 63must be aware of the semantics of the API calls, particularly with respect 64to synchronization primitives (such as locking). 65.Ss Note on Appropriateness for Production Use 66The 67.Tn TrustedBSD 68MAC Framework included in 69.Fx 5.0 70is considered experimental, and should not be deployed in production 71environments without careful consideration of the risks associated with 72the use of experimental operating system features. 73.Ss Kernel Objects Supported by the Framework 74The MAC framework manages labels on a variety of types of in-kernel 75objects, including process credentials, vnodes, devfs_dirents, mount 76points, sockets, mbufs, bpf descriptors, network interfaces, IP fragment 77queues, and pipes. 78Label data on kernel objects, represented by 79.Vt "struct label" , 80is policy-unaware, and may be used in the manner seen fit by policy modules. 81.Ss API for Consumers 82The MAC API provides a large set of entry points, too broad to specifically 83document here. 84In general, these entry points represent an access control check or other 85MAC-relevant operations, accept one or more subjects (credentials) 86authorizing the activity, a set of objects on which the operation 87is to be performed, and a set of operation arguments providing information 88about the type of operation being requested. 89.Ss Locking for Consumers 90Consumers of the MAC API must be aware of the locking requirements for 91each API entry point: generally, appropriate locks must be held over each 92subject or object being passed into the call, so that MAC modules may 93make use of various aspects of the object for access control purposes. 94For example, vnode locks are frequently required in order that the MAC 95framework and modules may retrieve security labels and attributes from the 96vnodes for the purposes of access control. 97Similarly, the caller must be aware of the reference counting semantics 98of any subject or object passed into the MAC API: all calls require that 99a valid reference to the object be held for the duration of the 100(potentially lengthy) MAC API call. 101Under some circumstances, objects must be held in either a shared or 102exclusive manner. 103.Ss API for Module Writers 104Each module exports a structure describing the MAC API operations that 105the module chooses to implement, including initialization and destruction 106API entry points, a variety of object creation and destruction calls, 107and a large set of access control check points. 108In the future, additional audit entry points will also be present. 109Module authors may choose to only implement a subset of the entry points, 110setting API function pointers in the description structure to 111.Dv NULL , 112permitting the framework to avoid calling into the module. 113.Ss Locking for Module Writers 114Module writers must be aware of the locking semantics of entry points 115that they implement: MAC API entry points will have specific locking 116or reference counting semantics for each argument, and modules must follow 117the locking and reference counting protocol or risk a variety of failure 118modes (including race conditions, inappropriate pointer dereferences, 119etc). 120.Pp 121MAC module writers must also be aware that MAC API entry points will 122frequently be invoked from deep in a kernel stack, and as such must be 123careful to avoid violating more global locking requirements, such as 124global lock order requirements. 125For example, it may be inappropriate to lock additional objects not 126specifically maintained and ordered by the policy module, or the 127policy module might violate a global ordering requirement relating 128to those additional objects. 129.Pp 130Finally, MAC API module implementors must be careful to avoid 131inappropriately calling back into the MAC framework: the framework 132makes use of locking to prevent inconsistencies during policy module 133attachment and detachment. 134MAC API modules should avoid producing scenarios in which deadlocks 135or inconsistencies might occur. 136.Ss Adding New MAC Entry Points 137The MAC API is intended to be easily expandable as new services are 138added to the kernel. 139In order that policies may be guaranteed the opportunity to ubiquitously 140protect system subjects and objects, it is important that kernel 141developers maintain awareness of when security checks or relevant 142subject or object operations occur in newly written or modified kernel 143code. 144New entry points must be carefully documented so as to prevent any 145confusion regarding lock orders and semantics. 146Introducing new entry points requires four distinct pieces of work: 147introducing new MAC API entries reflecting the operation arguments, 148scattering these MAC API entry points throughout the new or modified 149kernel service, extending the front-end implementation of the MAC API 150framework, and modifying appropriate modules to take advantage of 151the new entry points so that they may consistently enforce their 152policies. 153.Sh ENTRY POINTS 154System service and module authors should reference the 155.%T "FreeBSD Architecture Handbook" 156for information on the MAC Framework APIs. 157.Sh SEE ALSO 158.Xr acl 3 , 159.Xr mac 3 , 160.Xr posix1e 3 , 161.Xr mac_biba 4 , 162.Xr mac_bsdextended 4 , 163.Xr mac_ifoff 4 , 164.Xr mac_lomac 4 , 165.Xr mac_mls 4 , 166.Xr mac_none 4 , 167.Xr mac_partition 4 , 168.Xr mac_seeotheruids 4 , 169.Xr mac_test 4 , 170.Xr ucred 9 , 171.Xr vaccess 9 , 172.Xr vaccess_acl_posix1e 9 , 173.Xr VFS 9 174.Rs 175.%T "The FreeBSD Architecture Handbook" 176.%O "http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/arch-handbook/" 177.Re 178.Sh HISTORY 179The 180.Tn TrustedBSD 181MAC Framework first appeared in 182.Fx 5.0 . 183.Sh AUTHORS 184This manual page was written by 185.An Robert Watson . 186This software was contributed to the 187.Fx 188Project by Network Associates Laboratories, the Security Research 189Division of Network Associates Inc.\& under DARPA/SPAWAR contract 190N66001-01-C-8035 191.Pq Dq CBOSS , 192as part of the DARPA CHATS research program. 193.Pp 194.An -nosplit 195The 196.Tn TrustedBSD 197MAC Framework was designed by 198.An Robert Watson , 199and implemented by the Network Associates Laboratories Network Security 200(NETSEC), Secure Execution Environment (SEE), and Adaptive 201Network Defense research groups. 202Network Associates Laboratory staff contributing to the CBOSS Project 203include (in alphabetical order): 204.An Lee Badger , 205.An Brian Feldman , 206.An Hrishikesh Dandekar , 207.An Tim Fraser , 208.An Doug Kilpatrick , 209.An Suresh Krishnaswamy , 210.An Adam Migus , 211.An Wayne Morrison , 212.An Andrew Reisse , 213.An Chris Vance , 214and 215.An Robert Watson . 216.Pp 217Sub-contracted staff include: 218.An Chris Costello , 219.An Poul-Henning Kamp , 220.An Jonathan Lemon , 221.An Kirk McKusick , 222.An Dag-Erling Sm\(/orgrav . 223.Pp 224Additional contributors include: 225.An Pawel Dawidek , 226.An Chris Faulhaber , 227.An Ilmar Habibulin , 228.An Mike Halderman , 229.An Bosko Milekic , 230.An Thomas Moestl , 231.An Andrew Reiter , 232and 233.An Tim Robbins . 234.Sh BUGS 235See the earlier section in this document concerning appropriateness 236for production use. 237The 238.Tn TrustedBSD 239MAC Framework is considered experimental in 240.Fx . 241.Pp 242While the MAC Framework design is intended to support the containment of 243the root user, not all attack channels are currently protected by entry 244point checks. 245As such, MAC Framework policies should not be relied on, in isolation, 246to protect against a malicious privileged user. 247