lib/libc/posix1e/mac_get.3

   1 .\" Copyright (c) 2001, 2004 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 NAI Labs, the Security
   6 .\" Research Division of Network Associates, Inc. under DARPA/SPAWAR
   7 .\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS
   8 .\" 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 December 21, 2001
  34 .Dt MAC_GET 3
  35 .Os
  36 .Sh NAME
  37 .Nm mac_get_file ,
  38 .Nm mac_get_link ,
  39 .Nm mac_get_fd ,
  40 .Nm mac_get_peer ,
  41 .Nm mac_get_pid ,
  42 .Nm mac_get_proc
  43 .Nd get the label of a file, socket, socket peer or process
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In sys/mac.h
  48 .Ft int
  49 .Fn mac_get_file "const char *path" "mac_t label"
  50 .Ft int
  51 .Fn mac_get_link "const char *path" "mac_t label"
  52 .Ft int
  53 .Fn mac_get_fd "int fd" "mac_t label"
  54 .Ft int
  55 .Fn mac_get_peer "int fd" "mac_t label"
  56 .Ft int
  57 .Fn mac_get_pid "pid_t pid" "mac_t label"
  58 .Ft int
  59 .Fn mac_get_proc "mac_t label"
  60 .Sh DESCRIPTION
  61 The
  62 .Fn mac_get_file
  63 system call returns the label associated with a file specified by
  64 pathname.
  65 The
  66 .Fn mac_get_link
  67 function is the same as
  68 .Fn mac_get_file ,
  69 except that it does not follow symlinks.
  70 .Pp
  71 The
  72 .Fn mac_get_fd
  73 system call returns the label associated with an object referenced by
  74 the specified file descriptor.
  75 Note that in the case of a file system socket, the label returned will
  76 be the socket label, which may be different from the label of the
  77 on-disk node acting as a rendezvous for the socket.
  78 The
  79 .Fn mac_get_peer
  80 system call returns the label associated with the remote endpoint of
  81 a socket; the exact semantics of this call will depend on the protocol
  82 domain, communications type, and endpoint; typically this label will
  83 be cached when a connection-oriented protocol instance is first set up,
  84 and is undefined for datagram protocols.
  85 .Pp
  86 The
  87 .Fn mac_get_pid
  88 and
  89 .Fn mac_get_proc
  90 system calls return the process label associated with an arbitrary
  91 process ID, or the current process.
  92 .Pp
  93 Label storage for use with these calls must first be allocated and
  94 prepared using the
  95 .Xr mac_prepare 3
  96 functions.
  97 When an application is done using a label, the memory may be returned
  98 using
  99 .Xr mac_free 3 .
 100 .Sh ERRORS
 101 .Bl -tag -width Er
 102 .It Bq Er EACCES
 103 A component of
 104 .Fa path
 105 is not searchable,
 106 or MAC read access to the file
 107 is denied.
 108 .It Bq Er EINVAL
 109 The requested label operation is not valid for the object referenced by
 110 .Fa fd .
 111 .It Bq Er ENAMETOOLONG
 112 The pathname pointed to by
 113 .Fa path
 114 exceeds
 115 .Dv PATH_MAX ,
 116 or a component of the pathname exceeds
 117 .Dv NAME_MAX .
 118 .It Bq Er ENOENT
 119 A component of
 120 .Fa path
 121 does not exist.
 122 .It Bq Er ENOMEM
 123 Insufficient memory is available
 124 to allocate a new MAC label structure.
 125 .It Bq Er ENOTDIR
 126 A component of
 127 .Fa path
 128 is not a directory.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr mac 3 ,
 132 .Xr mac_free 3 ,
 133 .Xr mac_prepare 3 ,
 134 .Xr mac_set 3 ,
 135 .Xr mac_text 3 ,
 136 .Xr posix1e 3 ,
 137 .Xr mac 4 ,
 138 .Xr mac 9
 139 .Sh STANDARDS
 140 POSIX.1e is described in IEEE POSIX.1e draft 17.
 141 Discussion of the draft
 142 continues on the cross-platform POSIX.1e implementation mailing list.
 143 To join this list, see the
 144 .Fx
 145 POSIX.1e implementation page
 146 for more information.
 147 .Sh HISTORY
 148 Support for Mandatory Access Control was introduced in
 149 .Fx 5.0
 150 as part of the
 151 .Tn TrustedBSD
 152 Project.