lib/libc/posix1e/mac.3

   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
  45 In the kernel configuration file:
  46 .Cd "options MAC"
  47 .Sh DESCRIPTION
  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.
  55 .Pp
  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,
  59 .Xr mac_biba 4
  60 and
  61 .Xr mac_mls 4 :
  62 .Bd -literal -offset indent
  63 biba/low,mls/low
  64 .Ed
  65 .Pp
  66 Further syntax and semantics of MAC labels may be found in
  67 .Xr maclabel 7 .
  68 .Pp
  69 Applications operate on labels stored in
  70 .Vt mac_t ,
  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
  74 .Vt mac_t
  75 must first be prepared using the interfaces described in
  76 .Xr mac_prepare 3 ,
  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
  79 .Xr mac.conf 5 .
  80 .Pp
  81 When finished with a
  82 .Vt mac_t ,
  83 the application must call
  84 .Xr mac_free 3
  85 to release its storage.
  86 .Pp
  87 The following functions are defined:
  88 .Bl -tag -width indent
  89 .It Fn mac_is_present
  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
  96 .Xr mac_get 3 ,
  97 retrieve the MAC labels associated with file descriptors, files, and socket
  98 peers.
  99 .It Fn mac_get_pid , Fn mac_get_proc
 100 These functions, described in
 101 .Xr mac_get 3 ,
 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
 105 .Xr mac_set 3 ,
 106 set the MAC labels associated with file descriptors and files.
 107 .It Fn mac_set_proc
 108 This function, described in
 109 .Xr mac_set 3 ,
 110 sets the MAC label associated with the current process.
 111 .It Fn mac_free
 112 This function, described in
 113 .Xr mac_free 3 ,
 114 frees working MAC label storage.
 115 .It Fn mac_from_text
 116 This function, described in
 117 .Xr mac_text 3 ,
 118 converts 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
 121 These functions,  described in
 122 .Xr mac_prepare 3 ,
 123 allocate working storage for MAC label operations.
 124 .Xr mac_prepare 3
 125 prepares a label based on caller-specified label names; the other calls
 126 rely on the default configuration specified in
 127 .Xr mac.conf 5 .
 128 .It Fn mac_to_text
 129 This function is described in
 130 .Xr mac_text 3 ,
 131 and may be used to convert a
 132 .Vt mac_t
 133 into 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
 138 MAC library configuration file, documented in
 139 .Xr mac.conf 5 .
 140 Provides default behavior for applications aware of MAC labels on
 141 system 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
 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.
 160 .Sh HISTORY
 161 Support for Mandatory Access Control was introduced in
 162 .Fx 5.0
 163 as part of the
 164 .Tn TrustedBSD
 165 Project.
 166 .Sh BUGS
 167 The
 168 .Tn TrustedBSD
 169 MAC Framework and associated policies, interfaces, and
 170 applications are considered to be an experimental feature in
 171 .Fx .
 172 Sites considering production deployment should keep the experimental
 173 status of these services in mind during any deployment process.
 174 See also
 175 .Xr mac 9
 176 for related considerations regarding the kernel framework.