lib/libc/posix1e/mac_text.3

   1 .\" Copyright (c) 2001 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 .\" 3. The name of the author may not be used to endorse or promote
  19 .\"    products derived from this software without specific prior written
  20 .\"    permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\" $FreeBSD$
  35 .Dd December 21, 2001
  36 .Dt MAC_TEXT 3
  37 .Sh NAME
  38 .Nm mac_from_text ,
  39 .Nm mac_to_text
  40 .Nd convert MAC label to/from text representation
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/mac.h
  45 .Ft mac_t
  46 .Fn mac_from_text "const char *text_p"
  47 .Ft "char *"
  48 .Fn mac_to_text "mac_t label" "size_t *len_p"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn mac_from_text
  52 function converts the text representation of a label
  53 into a
  54 .Vt mac_t ,
  55 which must later be freed with
  56 .Xr mac_free .
  57 The
  58 .Fn mac_to_text
  59 function returns
  60 the text representation of
  61 .Fa label
  62 and sets
  63 .Fa *len_p
  64 to the length of the returned string.
  65 .Pp
  66 .Fx
  67 uses the following format
  68 for MAC policy text representations:
  69 .Pp
  70 .Dl Sy policy Ns No / Ns Sy qualifier
  71 .Pp
  72 Where
  73 .Sy policy
  74 can be one of
  75 .Dq biba ,
  76 .Dq mls ,
  77 or
  78 .Dq te .
  79 .Pp
  80 Valid labels can have the following arguments for
  81 .Sy qualifier ,
  82 depending on the value of
  83 .Sy policy .
  84 .Bl -tag -width "Policy" -offset indent
  85 .It Em Policy
  86 .Em Qualifier
  87 .It biba
  88 .Dq high ,
  89 .Dq low ,
  90 .Dq equal ,
  91 or a numeric grade.
  92 .It mls
  93 .Dq high ,
  94 .Dq low ,
  95 .Dq equal ,
  96 or a numeric level.
  97 .It te
  98 Types for
  99 .Dq te
 100 consist of a type name which must
 101 neither be empty nor exceed the length limit for the label.
 102 .El
 103 .Pp
 104 All policies must be present
 105 in a comma-separated list,
 106 but may be in any order
 107 (see
 108 .Sx EXAMPLES ) .
 109 .Sh RETURN VALUES
 110 The
 111 .Fn mac_from_text
 112 function returns a valid
 113 .Vt mac_t
 114 equivalent to
 115 the MAC label described in
 116 .Fa text_p
 117 upon success, and
 118 .Dv NULL
 119 upon failure, setting
 120 .Va errno
 121 to indicate the error.
 122 .Pp
 123 The
 124 .Fn mac_to_text
 125 function returns a string
 126 containing the text representation of
 127 .Fa label
 128 upon success, and
 129 .Dv NULL
 130 upon failure, setting
 131 .Va errno
 132 to indicate the error.
 133 .Sh EXAMPLES
 134 The following are valid MAC labels:
 135 .Bd -literal -offset indent
 136 biba/high,mls/low,te/none
 137 biba/low,mls/low,te/none
 138 biba/low,mls/3,te/none
 139 .Ed
 140 .Sh COMPATIBILITY
 141 POSIX.1e does not define
 142 a text format for text representations
 143 of MAC labels.
 144 .Sh ERRORS
 145 .Bl -tag -width Er
 146 .It Bq Er EINVAL
 147 An invalid policy or qualifier
 148 was specified in
 149 .Fa text_p ,
 150 or an invalid MAC label
 151 was specified in
 152 .Fa label .
 153 .It Bq Er ENOMEM
 154 Insufficient memory was available
 155 to allocate internal storage.
 156 .El
 157 .Sh SEE ALSO
 158 .Xr mac 3 ,
 159 .Xr mac_free 3 ,
 160 .Xr mac_get 3 ,
 161 .Xr mac_set 3
 162 .Sh STANDARDS
 163 POSIX.1e is described in IEEE POSIX.1e draft 17.
 164 Discussion of the draft
 165 continues on the cross-platform POSIX.1e implementation mailing list.
 166 To join this list, see the
 167 .Fx
 168 POSIX.1e implementation page
 169 for more information.