| mac.3 (6fb9b618f59bb8cf57ee05626515d113a8be92d3) | mac.3 (3a67af38ba24cdf225a521d181e278c8b98722b9) |
|---|---|
| 1.\" Copyright (c) 2001, 2003 Networks Associates Technology, Inc. | 1.\" Copyright (c) 2001, 2003 Networks Associates Technology, Inc. |
| 2.\" Copyright (c) 2009 Robert N. M. Watson |
|
| 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.\" --- 15 unchanged lines hidden (view full) --- 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.\" | 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.\" --- 15 unchanged lines hidden (view full) --- 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.\" |
| 33.Dd April 19, 2003 | 34.Dd August 7, 2009 |
| 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 | 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 |
| 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. | 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. |
| 56.Pp | 55.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 . | 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 |
| 64.Pp | 65.Pp |
| 65Available functions, sorted by behavior, include: | 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: |
| 66.Bl -tag -width indent | 88.Bl -tag -width indent |
| 67.It Fn mac_get_fd 68This function is described in | 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 |
| 69.Xr mac_get 3 , | 96.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 | 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 |
| 75.Xr mac_get 3 , | 101.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 | 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 |
| 87.Xr mac_set 3 , | 105.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. | 106set the MAC labels associated with file descriptors and files. |
| 97.It Fn mac_set_proc | 107.It Fn mac_set_proc |
| 98This function is described in | 108This function, described in |
| 99.Xr mac_set 3 , | 109.Xr mac_set 3 , |
| 100and may be used to set the 101MAC label associated with 102the calling process. | 110sets the MAC label associated with the current process. |
| 103.It Fn mac_free | 111.It Fn mac_free |
| 104This function is described in | 112This function, desribed in |
| 105.Xr mac_free 3 , | 113.Xr mac_free 3 , |
| 106and may be used to free 107userland working MAC label storage. | 114frees working MAC label storage. |
| 108.It Fn mac_from_text | 115.It Fn mac_from_text |
| 109This function is described in | 116This function, described in |
| 110.Xr mac_text 3 , | 117.Xr mac_text 3 , |
| 111and may be used to convert 112a text-form MAC label 113into a working | 118converts a text-form MAC label into working MAC label storage, |
| 114.Vt mac_t . | 119.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.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 |
| 120.Xr mac_prepare 3 , | 122.Xr mac_prepare 3 , |
| 121and may be used to preallocate storage for MAC label retrieval. | 123allocate 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 | 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 |
| 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 , | 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 , |
|
| 153.Xr mac_prepare 3 , 154.Xr mac_set 3 , 155.Xr mac_text 3 , | 147.Xr mac_prepare 3 , 148.Xr mac_set 3 , 149.Xr mac_text 3 , |
| 150.Xr posix1e 3 , |
|
| 156.Xr mac 4 , 157.Xr mac.conf 5 , 158.Xr mac 9 159.Sh STANDARDS | 151.Xr mac 4 , 152.Xr mac.conf 5 , 153.Xr mac 9 154.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. | 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 158PSOXI APIS were unable to express some notinos required for flexible and 159extensible 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. | 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. |