1 .\" Copyright (c) 2001, 2003 Networks Associates Technology, Inc.
2 .\" Copyright (c) 2009 Robert N. M. Watson
3 .\" All rights reserved.
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.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
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.
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
39 .Nd introduction to the MAC security API
45 In the kernel configuration file:
48 Mandatory Access Control labels describe confidentiality, integrity, and
49 other security attributes of operating system objects, overriding
50 discretionary access control.
51 Not all system objects support MAC labeling, and MAC policies must be
52 explicitly enabled by the administrator.
53 This API, based on POSIX.1e, includes routines to retrieve, manipulate, set,
54 and convert to and from text the MAC labels on files and processes.
56 MAC labels consist of a set of (name, value) tuples, representing security
57 attributes from MAC policies.
58 For example, this label contains security labels defined by two policies,
62 .Bd -literal -offset indent
66 Further syntax and semantics of MAC labels may be found in
69 Applications operate on labels stored in
71 but can convert between this internal format and a text format for the
72 purposes of presentation to uses or external storage.
73 When querying a label on an object, a
75 must first be prepared using the interfaces described in
77 allowing the application to declare which policies it wishes to interrogate.
78 The application writer can also rely on default label names declared in
83 the application must call
85 to release its storage.
87 The following functions are defined:
88 .Bl -tag -width indent
90 This function, described in
91 .Xr mac_is_present 3 ,
92 allows applications to test whether MAC is configured, as well as whether
93 specific policies are configured.
94 .It Fn mac_get_fd , Fn mac_get_file , Fn mac_get_link , Fn mac_get_peer
95 These functions, described in
97 retrieve the MAC labels associated with file descriptors, files, and socket
99 .It Fn mac_get_pid , Fn mac_get_proc
100 These functions, described in
102 retrieve the MAC labels associated with processes.
103 .It Fn mac_set_fd , Fn mac_set_file , Fn mac_set_link
104 These functions, described in
106 set the MAC labels associated with file descriptors and files.
108 This function, described in
110 sets the MAC label associated with the current process.
112 This function, described in
114 frees working MAC label storage.
116 This function, described in
118 converts a text-form MAC label into working MAC label storage,
120 .It Fn mac_prepare , Fn mac_prepare_file_label , Fn mac_prepare_ifnet_label , Fn mac_prepare_process_label , Fn mac_prepare_type
121 These functions, described in
123 allocate working storage for MAC label operations.
125 prepares a label based on caller-specified label names; the other calls
126 rely on the default configuration specified in
129 This function is described in
131 and may be used to convert a
133 into a text-form MAC label.
136 .Bl -tag -width ".Pa /etc/mac.conf" -compact
138 MAC library configuration file, documented in
140 Provides default behavior for applications aware of MAC labels on
141 system objects, but without policy-specific knowledge.
146 .Xr mac_is_present 3 ,
155 These APIs are loosely based on the APIs described in POSIX.1e, as described
156 in IEEE POSIX.1e draft 17.
157 However, the resemblance of these APIs to the POSIX APIs is loose, as the
158 POSIX APIs were unable to express some notions required for flexible and
159 extensible access control.
161 Support for Mandatory Access Control was introduced in
169 MAC Framework and associated policies, interfaces, and
170 applications are considered to be an experimental feature in
172 Sites considering production deployment should keep the experimental
173 status of these services in mind during any deployment process.
176 for related considerations regarding the kernel framework.