diff options
author | rwatson <rwatson@FreeBSD.org> | 2002-10-21 23:51:18 +0000 |
---|---|---|
committer | rwatson <rwatson@FreeBSD.org> | 2002-10-21 23:51:18 +0000 |
commit | c7b342f47ccfa38cb1cb558555d2e23f7f14eb30 (patch) | |
tree | 3bafc52b559414dde0e59e1ce537b2240a08ca68 /share/man/man9 | |
parent | 0a4c2cb09a1d3914f1de8580e161f0c4bf93e501 (diff) | |
download | FreeBSD-src-c7b342f47ccfa38cb1cb558555d2e23f7f14eb30.zip FreeBSD-src-c7b342f47ccfa38cb1cb558555d2e23f7f14eb30.tar.gz |
Add mac(9), a man page providing a basic introduction to the concepts
associated with the TrustedBSD MAC Framework, as well as some credits
to developers and contributors.
Obtained from: TrustedBSD Project
Sponsored by: DARPA, Network Associates Laboratories
Diffstat (limited to 'share/man/man9')
-rw-r--r-- | share/man/man9/Makefile | 2 | ||||
-rw-r--r-- | share/man/man9/mac.9 | 199 |
2 files changed, 200 insertions, 1 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 91a935b..e4900d4 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -48,7 +48,7 @@ MAN= BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \ jumbo.9 \ kernacc.9 kobj.9 kthread.9 ktr.9 \ lock.9 \ - mac_bsdextended.9 \ + mac.9 mac_bsdextended.9 \ make_dev.9 malloc.9 mbchain.9 mbuf.9 mdchain.9 \ mi_switch.9 microseq.9 microtime.9 microuptime.9 \ module.9 mtx_pool.9 mutex.9 \ diff --git a/share/man/man9/mac.9 b/share/man/man9/mac.9 new file mode 100644 index 0000000..d12a68b --- /dev/null +++ b/share/man/man9/mac.9 @@ -0,0 +1,199 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001, 2002 Robert N. M. Watson +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" This software was developed for the FreeBSD Project in part 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. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The names of the authors may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 16, 2002 +.Os +.Dt MAC 9 +.Sh NAME +.Nm mac +.Nd TrustedBSD Mandatory Access Control framework +.Sh SYNOPSIS +.In sys/types.h +.In sys/mac.h +.Pp +In the kernel configuration file: +.Cd "options MAC" +.Cd "options MAC_DEBUG" +.Sh DESCRIPTION +.Ss Introduction +The TrustedBSD mandatory access control framework permits dynamically +introduced 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 provides a series of entry points which must be called by +code supporting various 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). +.Ss Kernel objects supported by the framework +The MAC framework manages labels on a variety of types of in-kernel +objects, 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. +.Ss 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 (credentials) +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. +.Ss 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 +subject 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 circumstances, objects must be held in either a shared or +exclusive manner. +.Ss 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 implement 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. +.Ss 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 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). +.Pp +MAC module writers must also be aware that MAC API entry points will +frequently 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 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. +.Pp +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. +.Ss 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 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. +Introducing new entry points requires four distinct pieces of work: +introducing new MAC API entries reflecting the operation arguments, +scattering these MAC API entry points throughout the new or modified +kernel service, extending the front-end implementation of the MAC API +framework, and modifying appropriate modules to take advantage of +the new entry points so that they may consistently enforce their +policies. +.Sh ENTRY POINTS +System service and module authors should reference the FreeBSD +Developer's Handbook for information on the MAC Framework APIs. +.Pp +.Sh SEE ALSO +.Xr acl 3 , +.Xr cap 3 , +.Xr mac 3 , +.Xr lomac 4 , +.Xr posix1e 3 , +.Xr ucred 9 , +.Xr vaccess 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr VFS 9 , +.Sh AUTHORS +This man page was written by +.An Robert Watson . +This software was contributed to the +.Fx +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. +.Pp +.An -nosplit +The TrustedBSD MAC Framework was designed by +.An Robert Watson , +and implemented by the Network Associates Laboratories Network Security +(NETSEC), Secure Execution Environement (SEE), and Adaptive +Network Defense research groups. +Network Associates Laboratory staff contributing to the CBOSS Project +include (in alphabetical order): +.An Lee Badger , +.An Brian Feldman , +.An Tim Fraser , +.An Doug Kilpatrick , +.An Suresh Krishnaswamy , +.An Adam Migus , +.An Wayne Morrison , +.An Chris Vance , +and +.An Robert Watson . +.Pp +Sub-contracted staff include: +.An Chris Costello , +.An Poul-Henning Kamp , +.An Jonathan Lemon , +.An Kirk McKusick , +.An Dag-Erling Smorgrav . +.Pp +Additional contributors include: +.An Chris Faulhaber , +.An Ilmar Habibulin , +.An Thomas Moestl , +and +.An Andrew Reiter . +.An -split |