1.\" Copyright (c) 2001, 2003 Networks Associates Technology, Inc. 2.\" All rights reserved. 3.\" 4.\" This software was developed for the FreeBSD Project by Chris 5.\" Costello at Safeport Network Services and Network Associates 6.\" Laboratories, the Security Research Division of Network Associates, 7.\" Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part 8.\" of the DARPA CHATS research program. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd April 19, 2003 34.Dt MAC 3 35.Os 36.Sh NAME 37.Nm mac 38.Nd introduction to the MAC security API 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/mac.h 43.Pp 44In the kernel configuration file: 45.Cd "options MAC" 46.Sh DESCRIPTION 47.Fx 48permits administrators to define Mandatory Access Control labels 49defining levels for the privacy and integrity of data, 50overriding discretionary policies 51for those objects. 52Not all objects currently provide support for MAC labels, 53and MAC support must be explicitly enabled by the administrator. 54The library calls include routines to retrieve, duplicate, 55and set MAC labels associated with files and processes. 56.Pp 57POSIX.1e describes a set of MAC manipulation routines 58to manage the contents of MAC labels, 59as well as their relationships with 60files and processes; 61almost all of these support routines 62are implemented in 63.Fx . 64.Pp 65Available functions, sorted by behavior, include: 66.Bl -tag -width indent 67.It Fn mac_get_fd 68This function is described in 69.Xr mac_get 3 , 70and may be used to retrieve the 71MAC label associated with 72a specific file descriptor. 73.It Fn mac_get_file 74This function is described in 75.Xr mac_get 3 , 76and may be used to retrieve the 77MAC label associated with 78a named file. 79.It Fn mac_get_proc 80This function is described in 81.Xr mac_get 3 , 82and may be used to retrieve the 83MAC label associated with 84the calling process. 85.It Fn mac_set_fd 86This function is described in 87.Xr mac_set 3 , 88and may be used to set the 89MAC label associated with 90a specific file descriptor. 91.It Fn mac_set_file 92This function is described in 93.Xr mac_set 3 , 94and may be used to set the 95MAC label associated with 96a named file. 97.It Fn mac_set_proc 98This function is described in 99.Xr mac_set 3 , 100and may be used to set the 101MAC label associated with 102the calling process. 103.It Fn mac_free 104This function is described in 105.Xr mac_free 3 , 106and may be used to free 107userland working MAC label storage. 108.It Fn mac_from_text 109This function is described in 110.Xr mac_text 3 , 111and may be used to convert 112a text-form MAC label 113into a working 114.Vt mac_t . 115.It Fn mac_prepare 116.It Fn mac_prepare_file_label 117.It Fn mac_prepare_ifnet_label 118.It Fn mac_prepare_process_label 119These functions are described in 120.Xr mac_prepare 3 , 121and may be used to preallocate storage for MAC label retrieval. 122.Xr mac_prepare 3 123prepares a label based on caller-specified label names; the other calls 124rely on the default configuration specified in 125.Xr mac.conf 5 . 126.It Fn mac_to_text 127This function is described in 128.Xr mac_text 3 , 129and may be used to convert a 130.Vt mac_t 131into a text-form MAC label. 132.El 133The behavior of some of these calls is influenced by the configuration 134settings found in 135.Xr mac.conf 5 , 136the MAC library run-time configuration file. 137.Sh IMPLEMENTATION NOTES 138.Fx Ns 's 139support for POSIX.1e interfaces and features 140is 141.Ud . 142.Sh FILES 143.Bl -tag -width ".Pa /etc/mac.conf" -compact 144.It Pa /etc/mac.conf 145MAC library configuration file, documented in 146.Xr mac.conf 5 . 147Provides default behavior for applications aware of MAC labels on 148system objects, but without policy-specific knowledge. 149.El 150.Sh SEE ALSO 151.Xr mac_free 3 , 152.Xr mac_get 3 , 153.Xr mac_prepare 3 , 154.Xr mac_set 3 , 155.Xr mac_text 3 , 156.Xr mac 4 , 157.Xr mac.conf 5 , 158.Xr mac 9 159.Sh STANDARDS 160These APIs are loosely based on the APIs described in POSIX.1e. 161POSIX.1e is described in IEEE POSIX.1e draft 17. 162Discussion of the draft 163continues on the cross-platform POSIX.1e implementation mailing list. 164To join this list, see the 165.Fx 166POSIX.1e implementation page 167for more information. 168However, the resemblance of these APIs to the POSIX APIs is only loose, 169as the POSIX APIs were unable to express many notions required for 170flexible and extensible access control. 171.Sh HISTORY 172Support for Mandatory Access Control was introduced in 173.Fx 5.0 174as part of the 175.Tn TrustedBSD 176Project. 177.Sh BUGS 178The 179.Tn TrustedBSD 180MAC Framework and associated policies, interfaces, and 181applications are considered to be an experimental feature in 182.Fx . 183Sites considering production deployment should keep the experimental 184status of these services in mind during any deployment process. 185See also 186.Xr mac 9 187for related considerations regarding the kernel framework. 188