1.\" Copyright (c) 2001, 2003 Networks Associates Technology, Inc. 2.\" Copyright (c) 2009 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" This software was developed for the FreeBSD Project by Chris 6.\" Costello at Safeport Network Services and Network Associates 7.\" Laboratories, the Security Research Division of Network Associates, 8.\" Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part 9.\" of the DARPA CHATS research program. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $FreeBSD$ 33.\" 34.Dd August 7, 2009 35.Dt MAC 3 36.Os 37.Sh NAME 38.Nm mac 39.Nd introduction to the MAC security API 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/mac.h 44.Pp 45In the kernel configuration file: 46.Cd "options MAC" 47.Sh DESCRIPTION 48Mandatory Access Control labels describe confidentiality, integrity, and 49other security attributes of operating system objects, overriding 50discretionary access control. 51Not all system objects support MAC labeling, and MAC policies must be 52explicitly enabled by the administrator. 53This API, based on POSIX.1e, includes routines to retrieve, manipulate, set, 54and convert to and from text the MAC labels on files and processes. 55.Pp 56MAC labels consist of a set of (name, value) tuples, representing security 57attributes from MAC policies. 58For example, this label contains security labels defined by two policies, 59.Xr mac_biba 4 60and 61.Xr mac_mls 4 : 62.Bd -literal -offset indent 63biba/low,mls/low 64.Ed 65.Pp 66Further syntax and semantics of MAC labels may be found in 67.Xr maclabel 7 . 68.Pp 69Applications operate on labels stored in 70.Vt mac_t , 71but can convert between this internal format and a text format for the 72purposes of presentation to uses or external storage. 73When querying a label on an object, a 74.Vt mac_t 75must first be prepared using the interfaces described in 76.Xr mac_prepare 3 , 77allowing the application to declare which policies it wishes to interogate. 78The application writer can also rely on default label names declared in 79.Xr mac.conf 5 . 80.Pp 81When finished with a 82.Vt mac_t , 83the application must call 84.Xr mac_free 3 85to release its storage. 86.Pp 87The following functions are defined: 88.Bl -tag -width indent 89.It Fn mac_is_present 90This function, described in 91.Xr mac_is_present 3 , 92allows applications to test whether MAC is configured, as well as whether 93specific policies are configured. 94.It Fn mac_get_fd , Fn mac_get_file , Fn mac_get_link , Fn mac_get_peer 95These functions, described in 96.Xr mac_get 3 , 97retrieve the MAC labels associated with file descriptors, files, and socket 98peers. 99.It Fn mac_get_pid , Fn mac_get_proc 100These functions, described in 101.Xr mac_get 3 , 102retrieve the MAC labels associated with processes. 103.It Fn mac_set_fd , Fn mac_set_file , Fn mac_set_link 104These functions, described in 105.Xr mac_set 3 , 106set the MAC labels associated with file descriptors and files. 107.It Fn mac_set_proc 108This function, described in 109.Xr mac_set 3 , 110sets the MAC label associated with the current process. 111.It Fn mac_free 112This function, desribed in 113.Xr mac_free 3 , 114frees working MAC label storage. 115.It Fn mac_from_text 116This function, described in 117.Xr mac_text 3 , 118converts a text-form MAC label into working MAC label storage, 119.Vt mac_t . 120.It Fn mac_prepare , Fn mac_prepare_file_label , Fn mac_prepare_ifnet_label , Fn mac_prepare_process_label , Fn mac_prepare_type 121These functions, described in 122.Xr mac_prepare 3 , 123allocate working storage for MAC label operations. 124.Xr mac_prepare 3 125prepares a label based on caller-specified label names; the other calls 126rely on the default configuration specified in 127.Xr mac.conf 5 . 128.It Fn mac_to_text 129This function is described in 130.Xr mac_text 3 , 131and may be used to convert a 132.Vt mac_t 133into a text-form MAC label. 134.El 135.Sh FILES 136.Bl -tag -width ".Pa /etc/mac.conf" -compact 137.It Pa /etc/mac.conf 138MAC library configuration file, documented in 139.Xr mac.conf 5 . 140Provides default behavior for applications aware of MAC labels on 141system objects, but without policy-specific knowledge. 142.El 143.Sh SEE ALSO 144.Xr mac_free 3 , 145.Xr mac_get 3 , 146.Xr mac_is_present 3 , 147.Xr mac_prepare 3 , 148.Xr mac_set 3 , 149.Xr mac_text 3 , 150.Xr posix1e 3 , 151.Xr mac 4 , 152.Xr mac.conf 5 , 153.Xr mac 9 154.Sh STANDARDS 155These APIs are loosely based on the APIs described in POSIX.1e, as described 156in IEEE POSIX.1e draft 17. 157However, the resemblence of these APIs to the POSIX APIs is loose, as the 158POSIX APIs were unable to express some notions required for flexible and 159extensible access control. 160.Sh HISTORY 161Support for Mandatory Access Control was introduced in 162.Fx 5.0 163as part of the 164.Tn TrustedBSD 165Project. 166.Sh BUGS 167The 168.Tn TrustedBSD 169MAC Framework and associated policies, interfaces, and 170applications are considered to be an experimental feature in 171.Fx . 172Sites considering production deployment should keep the experimental 173status of these services in mind during any deployment process. 174See also 175.Xr mac 9 176for related considerations regarding the kernel framework. 177