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.Dd July 25, 2015 33.Dt MAC 3 34.Os 35.Sh NAME 36.Nm mac 37.Nd introduction to the MAC security API 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/mac.h 42.Pp 43In the kernel configuration file: 44.Cd "options MAC" 45.Sh DESCRIPTION 46Mandatory Access Control labels describe confidentiality, integrity, and 47other security attributes of operating system objects, overriding 48discretionary access control. 49Not all system objects support MAC labeling, and MAC policies must be 50explicitly enabled by the administrator. 51This API, based on POSIX.1e, includes routines to retrieve, manipulate, set, 52and convert to and from text the MAC labels on files and processes. 53.Pp 54MAC labels consist of a set of (name, value) tuples, representing security 55attributes from MAC policies. 56For example, this label contains security labels defined by two policies, 57.Xr mac_biba 4 58and 59.Xr mac_mls 4 : 60.Bd -literal -offset indent 61biba/low,mls/low 62.Ed 63.Pp 64Further syntax and semantics of MAC labels may be found in 65.Xr maclabel 7 . 66.Pp 67Applications operate on labels stored in 68.Vt mac_t , 69but can convert between this internal format and a text format for the 70purposes of presentation to uses or external storage. 71When querying a label on an object, a 72.Vt mac_t 73must first be prepared using the interfaces described in 74.Xr mac_prepare 3 , 75allowing the application to declare which policies it wishes to interrogate. 76The application writer can also rely on default label names declared in 77.Xr mac.conf 5 . 78.Pp 79When finished with a 80.Vt mac_t , 81the application must call 82.Xr mac_free 3 83to release its storage. 84.Pp 85The following functions are defined: 86.Bl -tag -width indent 87.It Fn mac_is_present 88This function, described in 89.Xr mac_is_present 3 , 90allows applications to test whether MAC is configured, as well as whether 91specific policies are configured. 92.It Fn mac_get_fd , Fn mac_get_file , Fn mac_get_link , Fn mac_get_peer 93These functions, described in 94.Xr mac_get 3 , 95retrieve the MAC labels associated with file descriptors, files, and socket 96peers. 97.It Fn mac_get_pid , Fn mac_get_proc 98These functions, described in 99.Xr mac_get 3 , 100retrieve the MAC labels associated with processes. 101.It Fn mac_set_fd , Fn mac_set_file , Fn mac_set_link 102These functions, described in 103.Xr mac_set 3 , 104set the MAC labels associated with file descriptors and files. 105.It Fn mac_set_proc 106This function, described in 107.Xr mac_set 3 , 108sets the MAC label associated with the current process. 109.It Fn mac_free 110This function, described in 111.Xr mac_free 3 , 112frees working MAC label storage. 113.It Fn mac_from_text 114This function, described in 115.Xr mac_text 3 , 116converts a text-form MAC label into working MAC label storage, 117.Vt mac_t . 118.It Fn mac_prepare , Fn mac_prepare_file_label , Fn mac_prepare_ifnet_label , Fn mac_prepare_process_label , Fn mac_prepare_type 119These functions, described in 120.Xr mac_prepare 3 , 121allocate working storage for MAC label operations. 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 133.Sh FILES 134.Bl -tag -width ".Pa /etc/mac.conf" -compact 135.It Pa /etc/mac.conf 136MAC library configuration file, documented in 137.Xr mac.conf 5 . 138Provides default behavior for applications aware of MAC labels on 139system objects, but without policy-specific knowledge. 140.El 141.Sh SEE ALSO 142.Xr mac_free 3 , 143.Xr mac_get 3 , 144.Xr mac_is_present 3 , 145.Xr mac_prepare 3 , 146.Xr mac_set 3 , 147.Xr mac_text 3 , 148.Xr posix1e 3 , 149.Xr mac 4 , 150.Xr mac.conf 5 , 151.Xr mac 9 152.Sh STANDARDS 153These APIs are loosely based on the APIs described in POSIX.1e, as described 154in IEEE POSIX.1e draft 17. 155However, the resemblance of these APIs to the POSIX APIs is loose, as the 156POSIX APIs were unable to express some notions required for flexible and 157extensible access control. 158.Sh HISTORY 159Support for Mandatory Access Control was introduced in 160.Fx 5.0 161as part of the 162.Tn TrustedBSD 163Project. 164