lib/libc/posix1e/mac.3

   1 .\" Copyright (c) 2001, 2003 Networks Associates Technology, Inc.
   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 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  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 .\"
  33 .Dd April 19, 2003
  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
  44 In the kernel configuration file:
  45 .Cd "options MAC"
  46 .Sh DESCRIPTION
  47 .Fx
  48 permits administrators to define Mandatory Access Control labels
  49 defining levels for the privacy and integrity of data,
  50 overriding discretionary policies
  51 for those objects.
  52 Not all objects currently provide support for MAC labels,
  53 and MAC support must be explicitly enabled by the administrator.
  54 The library calls include routines to retrieve, duplicate,
  55 and set MAC labels associated with files and processes.
  56 .Pp
  57 POSIX.1e describes a set of MAC manipulation routines
  58 to manage the contents of MAC labels,
  59 as well as their relationships with
  60 files and processes;
  61 almost all of these support routines
  62 are implemented in
  63 .Fx .
  64 .Pp
  65 Available functions, sorted by behavior, include:
  66 .Bl -tag -width indent
  67 .It Fn mac_get_fd
  68 This function is described in
  69 .Xr mac_get 3 ,
  70 and may be used to retrieve the
  71 MAC label associated with
  72 a specific file descriptor.
  73 .It Fn mac_get_file
  74 This function is described in
  75 .Xr mac_get 3 ,
  76 and may be used to retrieve the
  77 MAC label associated with
  78 a named file.
  79 .It Fn mac_get_proc
  80 This function is described in
  81 .Xr mac_get 3 ,
  82 and may be used to retrieve the
  83 MAC label associated with
  84 the calling process.
  85 .It Fn mac_set_fd
  86 This function is described in
  87 .Xr mac_set 3 ,
  88 and may be used to set the
  89 MAC label associated with
  90 a specific file descriptor.
  91 .It Fn mac_set_file
  92 This function is described in
  93 .Xr mac_set 3 ,
  94 and may be used to set the
  95 MAC label associated with
  96 a named file.
  97 .It Fn mac_set_proc
  98 This function is described in
  99 .Xr mac_set 3 ,
 100 and may be used to set the
 101 MAC label associated with
 102 the calling process.
 103 .It Fn mac_free
 104 This function is described in
 105 .Xr mac_free 3 ,
 106 and may be used to free
 107 userland working MAC label storage.
 108 .It Fn mac_from_text
 109 This function is described in
 110 .Xr mac_text 3 ,
 111 and may be used to convert
 112 a text-form MAC label
 113 into a working
 114 .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
 119 These functions are described in
 120 .Xr mac_prepare 3 ,
 121 and may be used to preallocate storage for MAC label retrieval.
 122 .Xr mac_prepare 3
 123 prepares a label based on caller-specified label names; the other calls
 124 rely on the default configuration specified in
 125 .Xr mac.conf 5 .
 126 .It Fn mac_to_text
 127 This function is described in
 128 .Xr mac_text 3 ,
 129 and may be used to convert a
 130 .Vt mac_t
 131 into a text-form MAC label.
 132 .El
 133 The behavior of some of these calls is influenced by the configuration
 134 settings found in
 135 .Xr mac.conf 5 ,
 136 the MAC library run-time configuration file.
 137 .Sh IMPLEMENTATION NOTES
 138 .Fx Ns 's
 139 support for POSIX.1e interfaces and features
 140 is
 141 .Ud .
 142 .Sh FILES
 143 .Bl -tag -width ".Pa /etc/mac.conf" -compact
 144 .It Pa /etc/mac.conf
 145 MAC library configuration file, documented in
 146 .Xr mac.conf 5 .
 147 Provides default behavior for applications aware of MAC labels on
 148 system objects, but without policy-specific knowledge.
 149 .El
 150 .Sh SEE ALSO
 151 .Xr mac_free 3 ,
 152 .Xr mac_get 3 ,
 153 .Xr mac_prepare 3 ,
 154 .Xr mac_set 3 ,
 155 .Xr mac_text 3 ,
 156 .Xr mac 4 ,
 157 .Xr mac.conf 5 ,
 158 .Xr mac 9
 159 .Sh STANDARDS
 160 These APIs are loosely based on the APIs described in POSIX.1e.
 161 POSIX.1e is described in IEEE POSIX.1e draft 17.
 162 Discussion of the draft
 163 continues on the cross-platform POSIX.1e implementation mailing list.
 164 To join this list, see the
 165 .Fx
 166 POSIX.1e implementation page
 167 for more information.
 168 However, the resemblance of these APIs to the POSIX APIs is only loose,
 169 as the POSIX APIs were unable to express many notions required for
 170 flexible and extensible access control.
 171 .Sh HISTORY
 172 Support for Mandatory Access Control was introduced in
 173 .Fx 5.0
 174 as part of the
 175 .Tn TrustedBSD
 176 Project.
 177 .Sh BUGS
 178 The
 179 .Tn TrustedBSD
 180 MAC Framework and associated policies, interfaces, and
 181 applications are considered to be an experimental feature in
 182 .Fx .
 183 Sites considering production deployment should keep the experimental
 184 status of these services in mind during any deployment process.
 185 See also
 186 .Xr mac 9
 187 for related considerations regarding the kernel framework.