share/man/man9/mac.9

   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
  46 In the kernel configuration file:
  47 .Cd "options MAC"
  48 .Cd "options MAC_DEBUG"
  49 .Sh DESCRIPTION
  50 .Ss Introduction
  51 The
  52 .Tn TrustedBSD
  53 mandatory access control framework permits dynamically
  54 introduced system security modules to modify system security functionality.
  55 This can be used to support a variety of new security services, including
  56 traditional labeled mandatory access control models.
  57 The framework provides a series of entry points which must be called by
  58 code supporting various kernel services, especially with respects to access
  59 control points and object creation.
  60 The framework then calls out to security modules to offer them the
  61 opportunity to modify security behavior at those MAC API entry points.
  62 Both consumers of the API (normal kernel services) and security modules
  63 must be aware of the semantics of the API calls, particularly with respect
  64 to synchronization primitives (such as locking).
  65 .Ss Note on Appropriateness for Production Use
  66 The
  67 .Tn TrustedBSD
  68 MAC Framework included in
  69 .Fx 5.0
  70 is considered experimental, and should not be deployed in production
  71 environments without careful consideration of the risks associated with
  72 the use of experimental operating system features.
  73 .Ss Kernel Objects Supported by the Framework
  74 The MAC framework manages labels on a variety of types of in-kernel
  75 objects, including process credentials, vnodes, devfs_dirents, mount
  76 points, sockets, mbufs, bpf descriptors, network interfaces, IP fragment
  77 queues, and pipes.
  78 Label data on kernel objects, represented by
  79 .Vt "struct label" ,
  80 is policy-unaware, and may be used in the manner seen fit by policy modules.
  81 .Ss API for Consumers
  82 The MAC API provides a large set of entry points, too broad to specifically
  83 document here.
  84 In general, these entry points represent an access control check or other
  85 MAC-relevant operations, accept one or more subjects (credentials)
  86 authorizing the activity, a set of objects on which the operation
  87 is to be performed, and a set of operation arguments providing information
  88 about the type of operation being requested.
  89 .Ss Locking for Consumers
  90 Consumers of the MAC API must be aware of the locking requirements for
  91 each API entry point: generally, appropriate locks must be held over each
  92 subject or object being passed into the call, so that MAC modules may
  93 make use of various aspects of the object for access control purposes.
  94 For example, vnode locks are frequently required in order that the MAC
  95 framework and modules may retrieve security labels and attributes from the
  96 vnodes for the purposes of access control.
  97 Similarly, the caller must be aware of the reference counting semantics
  98 of any subject or object passed into the MAC API: all calls require that
  99 a valid reference to the object be held for the duration of the
 100 (potentially lengthy) MAC API call.
 101 Under some circumstances, objects must be held in either a shared or
 102 exclusive manner.
 103 .Ss API for Module Writers
 104 Each module exports a structure describing the MAC API operations that
 105 the module chooses to implement, including initialization and destruction
 106 API entry points, a variety of object creation and destruction calls,
 107 and a large set of access control check points.
 108 In the future, additional audit entry points will also be present.
 109 Module authors may choose to only implement a subset of the entry points,
 110 setting API function pointers in the description structure to
 111 .Dv NULL ,
 112 permitting the framework to avoid calling into the module.
 113 .Ss Locking for Module Writers
 114 Module writers must be aware of the locking semantics of entry points
 115 that they implement: MAC API entry points will have specific locking
 116 or reference counting semantics for each argument, and modules must follow
 117 the locking and reference counting protocol or risk a variety of failure
 118 modes (including race conditions, inappropriate pointer dereferences,
 119 etc).
 120 .Pp
 121 MAC module writers must also be aware that MAC API entry points will
 122 frequently be invoked from deep in a kernel stack, and as such must be
 123 careful to avoid violating more global locking requirements, such as
 124 global lock order requirements.
 125 For example, it may be inappropriate to lock additional objects not
 126 specifically maintained and ordered by the policy module, or the
 127 policy module might violate a global ordering requirement relating
 128 to those additional objects.
 129 .Pp
 130 Finally, MAC API module implementors must be careful to avoid
 131 inappropriately calling back into the MAC framework: the framework
 132 makes use of locking to prevent inconsistencies during policy module
 133 attachment and detachment.
 134 MAC API modules should avoid producing scenarios in which deadlocks
 135 or inconsistencies might occur.
 136 .Ss Adding New MAC Entry Points
 137 The MAC API is intended to be easily expandable as new services are
 138 added to the kernel.
 139 In order that policies may be guaranteed the opportunity to ubiquitously
 140 protect system subjects and objects, it is important that kernel
 141 developers maintain awareness of when security checks or relevant
 142 subject or object operations occur in newly written or modified kernel
 143 code.
 144 New entry points must be carefully documented so as to prevent any
 145 confusion regarding lock orders and semantics.
 146 Introducing new entry points requires four distinct pieces of work:
 147 introducing new MAC API entries reflecting the operation arguments,
 148 scattering these MAC API entry points throughout the new or modified
 149 kernel service, extending the front-end implementation of the MAC API
 150 framework, and modifying appropriate modules to take advantage of
 151 the new entry points so that they may consistently enforce their
 152 policies.
 153 .Sh ENTRY POINTS
 154 System service and module authors should reference the
 155 .%T "FreeBSD Architecture Handbook"
 156 for 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 .%U "http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/arch-handbook/"
 177 .Re
 178 .Sh HISTORY
 179 The
 180 .Tn TrustedBSD
 181 MAC Framework first appeared in
 182 .Fx 5.0 .
 183 .Sh AUTHORS
 184 This manual page was written by
 185 .An Robert Watson .
 186 This software was contributed to the
 187 .Fx
 188 Project by Network Associates Laboratories, the Security Research
 189 Division of Network Associates Inc.\& under DARPA/SPAWAR contract
 190 N66001-01-C-8035
 191 .Pq Dq CBOSS ,
 192 as part of the DARPA CHATS research program.
 193 .Pp
 194 .An -nosplit
 195 The
 196 .Tn TrustedBSD
 197 MAC Framework was designed by
 198 .An Robert Watson ,
 199 and implemented by the Network Associates Laboratories Network Security
 200 (NETSEC), Secure Execution Environment (SEE), and Adaptive
 201 Network Defense research groups.
 202 Network Associates Laboratory staff contributing to the CBOSS Project
 203 include (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 ,
 214 and
 215 .An Robert Watson .
 216 .Pp
 217 Sub-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
 224 Additional 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 ,
 232 and
 233 .An Tim Robbins .
 234 .Sh BUGS
 235 See the earlier section in this document concerning appropriateness
 236 for production use.
 237 The
 238 .Tn TrustedBSD
 239 MAC Framework is considered experimental in
 240 .Fx .
 241 .Pp
 242 While the MAC Framework design is intended to support the containment of
 243 the root user, not all attack channels are currently protected by entry
 244 point checks.
 245 As such, MAC Framework policies should not be relied on, in isolation,
 246 to protect against a malicious privileged user.