usr/src/man/man3tsol/sbltos.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 SBLTOS 3TSOL "Jul 20, 2007"
   7 .SH NAME
   8 sbltos, sbsltos, sbcleartos \- translate binary labels to canonical
   9 character-coded labels
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-ltsol\fR [\fIlibrary\fR...]
  14 .fi
  15
  16 .LP
  17 .nf
  18 #include <tsol/label.h>
  19
  20 \fBchar *\fR\fBsbsltos\fR(\fBconst m_label_t *\fR\fIlabel\fR, \fBconst int\fR \fIlen\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBchar *\fR\fBsbcleartos\fR(\fBconst m_label_t *\fR\fIclearance\fR, \fBconst int\fR \fIlen\fR);
  26 .fi
  27
  28 .SH DESCRIPTION
  29 .sp
  30 .LP
  31 These functions translate binary labels into canonical strings that are clipped
  32 to the number of printable characters specified in \fIlen\fR. Clipping is
  33 required if the number of characters of the translated string is greater than
  34 \fIlen\fR. Clipping is done by truncating the label on the right to two
  35 characters less than the specified number of characters. A clipped indicator,
  36 "<\(mi", is appended to sensitivity labels and clearances. The character-coded
  37 label begins with a classification name separated with a single space character
  38 from the list of words making up the remainder of the label. The binary labels
  39 must be of the proper defined type and dominated by the process's sensitivity
  40 label. A \fIlen\fR of 0 (zero) returns the entire string with no clipping.
  41 .sp
  42 .LP
  43 The \fBsbsltos()\fR function translates a binary sensitivity label into a
  44 clipped string using the long form of the words and the short form of the
  45 classification name. If \fIlen\fR is less than the minimum number of characters
  46 (three), the translation fails.
  47 .sp
  48 .LP
  49 The \fBsbcleartos()\fR function translates a binary clearance into a clipped
  50 string using the long form of the words and the short form of the
  51 classification name. If \fIlen\fR is less than the minimum number of characters
  52 (three), the translation fails. The translation of a clearance might not be the
  53 same as the translation of a sensitivity label. These functions use different
  54 tables of the \fBlabel_encodings\fR file which might contain different words
  55 and constraints.
  56 .sp
  57 .LP
  58 The calling process must have \fBPRIV_SYS_TRANS_LABEL\fR in its set of
  59 effective privileges to perform label translation on labels that dominate the
  60 current process's sensitivity label.
  61 .SS "Process Attributes"
  62 .sp
  63 .LP
  64 If the \fBVIEW_EXTERNAL\fR or \fBVIEW_INTERNAL\fR flags are not specified,
  65 translation of \fBADMIN_LOW\fR and \fBADMIN_HIGH\fR labels is controlled by the
  66 label view process attribute flags. If no label view process attribute flags
  67 are defined, their translation is controlled by the label view configured in
  68 the \fBlabel_encodings\fR file. A value of External specifies that
  69 \fBADMIN_LOW\fR and \fBADMIN_HIGH\fR labels are mapped to the lowest and
  70 highest labels defined in the \fBlabel_encodings\fR file. A value of Internal
  71 specifies that the \fBADMIN_LOW\fR and \fBADMIN_HIGH\fR labels are translated
  72 to the \fBadmin low name\fR and \fBadmin high name\fR strings specified in the
  73 \fBlabel_encodings\fR file. If no such names are specified, the strings
  74 "\fBADMIN_LOW\fR" and "\fBADMIN_HIGH\fR" are used.
  75 .SH RETURN VALUES
  76 .sp
  77 .LP
  78 These functions return a pointer to a statically allocated string that contains
  79 the result of the translation, or \fB(char\fR \fB*)0\fR if the translation
  80 fails for any reason.
  81 .SH EXAMPLES
  82 .SS "\fBsbsltos()\fR"
  83 .sp
  84 .LP
  85 Assume that a sensitivity label is:
  86 .sp
  87 .in +2
  88 .nf
  89 UN TOP/MIDDLE/LOWER DRAWER
  90 .fi
  91 .in -2
  92 .sp
  93
  94 .sp
  95 .LP
  96 When clipped to ten characters it is:
  97 .sp
  98 .in +2
  99 .nf
 100 UN TOP/M<\(mi
 101 .fi
 102 .in -2
 103 .sp
 104
 105 .SS "\fBsbcleartos()\fR"
 106 .sp
 107 .LP
 108 Assume that a clearance is:
 109 .sp
 110 .in +2
 111 .nf
 112 UN TOP/MIDDLE/LOWER DRAWER
 113 .fi
 114 .in -2
 115 .sp
 116
 117 .sp
 118 .LP
 119 When clipped to ten characters it is:
 120 .sp
 121 .in +2
 122 .nf
 123 UN TOP/M<\(mi
 124 .fi
 125 .in -2
 126 .sp
 127
 128 .SH FILES
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fB/etc/security/tsol/label_encodings\fR\fR
 133 .ad
 134 .sp .6
 135 .RS 4n
 136 The label encodings file contains the classification names, words, constraints,
 137 and values for the defined labels of this system.
 138 .RE
 139
 140 .SH ATTRIBUTES
 141 .sp
 142 .LP
 143 See \fBattributes\fR(5) for descriptions of the following attributes:
 144 .sp
 145
 146 .sp
 147 .TS
 148 box;
 149 c | c
 150 l | l .
 151 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 152 _
 153 Interface Stability     Obsolete
 154 _
 155 MT-Level        Unsafe
 156 .TE
 157
 158 .sp
 159 .LP
 160 These functions are obsolete and retained for ease of porting. They might be
 161 removed in a future Solaris Trusted Extensions release. Use the
 162 \fBlabel_to_str\fR(3TSOL) function instead.
 163 .SH SEE ALSO
 164 .sp
 165 .LP
 166 \fBlabel_to_str\fR(3TSOL), \fBlibtsol\fR(3LIB), \fBattributes\fR(5),
 167 \fBlabels\fR(5)
 168 .SH WARNINGS
 169 .sp
 170 .LP
 171 All these functions share the same statically allocated string storage. They
 172 are not MT-Safe. Subsequent calls to any of these functions will overwrite that
 173 string with the newly translated string.
 174 .SH NOTES
 175 .sp
 176 .LP
 177 The functionality described on this manual page is available only if the system
 178 is configured with Trusted Extensions.