usr/src/man/man3tsol/stobl.3tsol

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH STOBL 3TSOL "Jul 20, 2007"
   7 .SH NAME
   8 stobl, stobsl, stobclear \- translate character-coded labels to binary labels
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-ltsol\fR [\fIlibrary\fR...]
  13 .fi
  14
  15 .LP
  16 .nf
  17 #include <tsol/label.h>
  18
  19 \fBint\fR \fBstobsl\fR(\fBconst char *\fR\fIstring\fR, \fBm_label_t *\fR\fIlabel\fR, \fBconst int\fR \fIflags\fR,
  20      \fBint *\fR\fIerror\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBstobclear\fR(\fBconst char *\fR\fIstring\fR, \fBm_label_t *\fR\fIclearance\fR,
  26      \fBconst int\fR \fIflags\fR, \fBint *\fR\fIerror\fR);
  27 .fi
  28
  29 .SH DESCRIPTION
  30 .sp
  31 .LP
  32 The \fBstobsl()\fR and \fBstobclear()\fR functions translate character-coded
  33 labels into binary labels. They also modify an existing binary label by
  34 incrementing or decrementing it to produce a new binary label relative to its
  35 existing value.
  36 .sp
  37 .LP
  38 The calling process must have \fBPRIV_SYS_TRANS_LABEL\fR in its set of
  39 effective privileges to perform label translation on character-coded labels
  40 that dominate the process's sensitivity label.
  41 .sp
  42 .LP
  43 The generic form of an input character-coded label string is:
  44 .sp
  45 .in +2
  46 .nf
  47 [  +  ] \fIclassification name\fR ] [ [  + | \(mi ] \fIword\fR ...
  48 .fi
  49 .in -2
  50 .sp
  51
  52 .sp
  53 .LP
  54 Leading and trailing white space is ignored. Fields are separated by white
  55 space, a `\fB/\fR' (slash), or a `\fB,\fR' (comma). Case is irrelevant. If
  56 \fIstring\fR starts with \fB+\fR or \fB\(mi\fR, \fIstring\fR is interpreted a
  57 modification to an existing label. If \fIstring\fR starts with a classification
  58 name followed by a \fB+\fR or \fB\(mi\fR, the new classification is used and
  59 the rest of the old label is retained and modified as specified by
  60 \fIstring\fR. \fB+\fR modifies an existing label by adding words. \fB\(mi\fR
  61 modifies an existing label by removing words. To the maximum extent possible,
  62 errors in \fIstring\fR are corrected in the resulting binary label \fIlabel\fR.
  63 .sp
  64 .LP
  65 The \fBstobsl()\fR and \fBstobclear()\fR functions also translate hexadecimal
  66 label representations into binary labels (see \fBhextob\fR(3TSOL)) when the
  67 string starts with \fB0x\fR and either \fBNEW_LABEL\fR or \fBNO_CORRECTION\fR
  68 is specified in \fIflags\fR.
  69 .sp
  70 .LP
  71 The \fIflags\fR argument can take the following values:
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBNEW_LABEL\fR\fR
  76 .ad
  77 .RS 17n
  78 \fIlabel\fR contents is not used, is formatted as a label of the relevant type,
  79 and is assumed to be \fBADMIN_LOW\fR for modification changes. If
  80 \fBNEW_LABEL\fR is not present, \fIlabel\fR is validated as a defined label of
  81 the correct type dominated by the process's sensitivity label.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBNO_CORRECTION\fR\fR
  88 .ad
  89 .RS 17n
  90 No corrections are made if there are errors in the character-coded label
  91 \fIstring\fR. \fIstring\fR must be complete and contain all the label
  92 components that are required by the \fBlabel_encodings\fR file. The
  93 \fBNO_CORRECTION\fR flag implies the \fBNEW_LABEL\fR flag.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fB0 (zero)\fR\fR
 100 .ad
 101 .RS 17n
 102 The default action is taken.
 103 .RE
 104
 105 .sp
 106 .LP
 107 The \fIerror\fR argument is a return parameter that is set only if the function
 108 is unsuccessful.
 109 .sp
 110 .LP
 111 The \fBstobsl()\fR function translates the character-coded sensitivity label
 112 string into a binary sensitivity label and places the result in the return
 113 parameter \fIlabel\fR.
 114 .sp
 115 .LP
 116 The \fIflags\fR argument can be either \fBNEW_LABEL\fR, \fBNO_CORRECTION\fR, or
 117 0 (zero). Unless \fBNO_CORRECTION\fR is specified, this translation forces the
 118 label to dominate the minimum classification, and initial compartments set that
 119 is specified in the \fBlabel_encodings\fR file and corrects the label to
 120 include other label components required by the \fBlabel_encodings\fR file, but
 121 not present in \fIstring\fR.
 122 .sp
 123 .LP
 124 The \fBstobclear()\fR function translates the character-coded clearance string
 125 into a binary clearance and places the result in the return parameter
 126 \fIclearance\fR.
 127 .sp
 128 .LP
 129 The \fIflags\fR argument can be either \fBNEW_LABEL\fR, \fBNO_CORRECTION\fR, or
 130 \fB0\fR (zero). Unless \fBNO_CORRECTION\fR is specified, this translation
 131 forces the label to dominate the minimum classification, and initial
 132 compartments set that is specified in the \fBlabel_encodings\fR file and
 133 corrects the label to include other label components that are required by the
 134 \fBlabel_encodings\fR file, but not present in \fIstring\fR. The translation of
 135 a clearance might not be the same as the translation of a sensitivity label.
 136 These functions use different tables of the \fBlabel_encodings\fR file that
 137 might contain different words and constraints.
 138 .SH RETURN VALUES
 139 .sp
 140 .LP
 141 These functions return 1 if the translation was successful and a valid binary
 142 label was returned. Otherwise they return 0 and the value of the \fIerror\fR
 143 argument indicates the error.
 144 .SH ERRORS
 145 .sp
 146 .LP
 147 When these functions return zero, \fIerror\fR contains one of the following
 148 values:
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fB\(mi1\fR\fR
 153 .ad
 154 .RS 9n
 155 Unable to access the \fBlabel_encodings\fR file.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fB0\fR\fR
 162 .ad
 163 .RS 9n
 164 The label \fIlabel\fR is not valid for this translation and the \fBNEW_LABEL\fR
 165 or \fBNO_CORRECTION\fR flag was not specified, or the label \fIlabel\fR is not
 166 dominated by the process's \fIsensitivity label\fR and the process does not
 167 have \fBPRIV_SYS_TRANS_LABEL\fR in its set of effective privileges.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fB>0\fR\fR
 174 .ad
 175 .RS 9n
 176 The character-coded label \fIstring\fR is in error. \fIerror\fR is a one-based
 177 index into \fIstring\fR indicating where the translation error occurred.
 178 .RE
 179
 180 .SH FILES
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fB/etc/security/tsol/label_encodings\fR\fR
 185 .ad
 186 .sp .6
 187 .RS 4n
 188 The label encodings file contains the classification names, words, constraints,
 189 and values for the defined labels of this system.
 190 .RE
 191
 192 .SH ATTRIBUTES
 193 .sp
 194 .LP
 195 See \fBattributes\fR(5) for descriptions of the following attributes:
 196 .sp
 197
 198 .sp
 199 .TS
 200 box;
 201 c | c
 202 l | l .
 203 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 204 _
 205 Interface Stability     Obsolete
 206 _
 207 MT-Level        MT-Safe
 208 .TE
 209
 210 .sp
 211 .LP
 212 The \fBstobsl()\fR and \fBstobclear()\fR functions are obsolete. Use the
 213 \fBstr_to_label\fR(3TSOL) function instead.
 214 .SH SEE ALSO
 215 .sp
 216 .LP
 217 \fBblcompare\fR(3TSOL), \fBhextob\fR(3TSOL), \fBlibtsol\fR(3LIB),
 218 \fBstr_to_label\fR(3TSOL), \fBattributes\fR(5)
 219 .SH NOTES
 220 .sp
 221 .LP
 222 The functionality described on this manual page is available only if the system
 223 is configured with Trusted Extensions.
 224 .sp
 225 .LP
 226 In addition to the \fBADMIN_LOW\fR name and \fBADMIN_HIGH\fR name strings
 227 defined in the \fBlabel_encodings\fR file, the strings "\fBADMIN_LOW\fR" and
 228 "\fBADMIN_HIGH\fR" are always accepted as character-coded labels to be
 229 translated to the appropriate \fBADMIN_LOW\fR and \fBADMIN_HIGH\fR label,
 230 respectively.
 231 .sp
 232 .LP
 233 Modifying an existing \fBADMIN_LOW\fR label acts as the specification of a
 234 \fBNEW_LABEL\fR and forces the label to start at the minimum label that is
 235 specified in the \fBlabel_encodings\fR file.
 236 .sp
 237 .LP
 238 Modifying an existing \fBADMIN_HIGH\fR label is treated as an attempt to change
 239 a label that represents the highest defined classification and all the defined
 240 compartments that are specified in the \fBlabel_encodings\fR file.
 241 .sp
 242 .LP
 243 The \fBNO_CORRECTION\fR flag is used when the character-coded label must be
 244 complete and accurate so that translation to and from the binary form results
 245 in an equivalent character-coded label.