Merge branch 'less_closed'

[unleashed.git] / usr / src / man / man3tsol / stobl.3tsol

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH STOBL 3TSOL "Jul 20, 2007"
.SH NAME
stobl, stobsl, stobclear \- translate character-coded labels to binary labels
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-ltsol\fR [\fIlibrary\fR...]
.fi

.LP
.nf
#include <tsol/label.h>

\fBint\fR \fBstobsl\fR(\fBconst char *\fR\fIstring\fR, \fBm_label_t *\fR\fIlabel\fR, \fBconst int\fR \fIflags\fR,
     \fBint *\fR\fIerror\fR);
.fi

.LP
.nf
\fBint\fR \fBstobclear\fR(\fBconst char *\fR\fIstring\fR, \fBm_label_t *\fR\fIclearance\fR,
     \fBconst int\fR \fIflags\fR, \fBint *\fR\fIerror\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBstobsl()\fR and \fBstobclear()\fR functions translate character-coded
labels into binary labels. They also modify an existing binary label by
incrementing or decrementing it to produce a new binary label relative to its
existing value.
.sp
.LP
The calling process must have \fBPRIV_SYS_TRANS_LABEL\fR in its set of
effective privileges to perform label translation on character-coded labels
that dominate the process's sensitivity label.
.sp
.LP
The generic form of an input character-coded label string is:
.sp
.in +2
.nf
[  +  ] \fIclassification name\fR ] [ [  + | \(mi ] \fIword\fR ...
.fi
.in -2
.sp

.sp
.LP
Leading and trailing white space is ignored. Fields are separated by white
space, a `\fB/\fR' (slash), or a `\fB,\fR' (comma). Case is irrelevant. If
\fIstring\fR starts with \fB+\fR or \fB\(mi\fR, \fIstring\fR is interpreted a
modification to an existing label. If \fIstring\fR starts with a classification
name followed by a \fB+\fR or \fB\(mi\fR, the new classification is used and
the rest of the old label is retained and modified as specified by
\fIstring\fR. \fB+\fR modifies an existing label by adding words. \fB\(mi\fR
modifies an existing label by removing words. To the maximum extent possible,
errors in \fIstring\fR are corrected in the resulting binary label \fIlabel\fR.
.sp
.LP
The \fBstobsl()\fR and \fBstobclear()\fR functions also translate hexadecimal
label representations into binary labels (see \fBhextob\fR(3TSOL)) when the
string starts with \fB0x\fR and either \fBNEW_LABEL\fR or \fBNO_CORRECTION\fR
is specified in \fIflags\fR.
.sp
.LP
The \fIflags\fR argument can take the following values:
.sp
.ne 2
.na
\fB\fBNEW_LABEL\fR\fR
.ad
.RS 17n
\fIlabel\fR contents is not used, is formatted as a label of the relevant type,
and is assumed to be \fBADMIN_LOW\fR for modification changes. If
\fBNEW_LABEL\fR is not present, \fIlabel\fR is validated as a defined label of
the correct type dominated by the process's sensitivity label.
.RE

.sp
.ne 2
.na
\fB\fBNO_CORRECTION\fR\fR
.ad
.RS 17n
No corrections are made if there are errors in the character-coded label
\fIstring\fR. \fIstring\fR must be complete and contain all the label
components that are required by the \fBlabel_encodings\fR file. The
\fBNO_CORRECTION\fR flag implies the \fBNEW_LABEL\fR flag.
.RE

.sp
.ne 2
.na
\fB\fB0 (zero)\fR\fR
.ad
.RS 17n
The default action is taken.
.RE

.sp
.LP
The \fIerror\fR argument is a return parameter that is set only if the function
is unsuccessful.
.sp
.LP
The \fBstobsl()\fR function translates the character-coded sensitivity label
string into a binary sensitivity label and places the result in the return
parameter \fIlabel\fR.
.sp
.LP
The \fIflags\fR argument can be either \fBNEW_LABEL\fR, \fBNO_CORRECTION\fR, or
0 (zero). Unless \fBNO_CORRECTION\fR is specified, this translation forces the
label to dominate the minimum classification, and initial compartments set that
is specified in the \fBlabel_encodings\fR file and corrects the label to
include other label components required by the \fBlabel_encodings\fR file, but
not present in \fIstring\fR.
.sp
.LP
The \fBstobclear()\fR function translates the character-coded clearance string
into a binary clearance and places the result in the return parameter
\fIclearance\fR.
.sp
.LP
The \fIflags\fR argument can be either \fBNEW_LABEL\fR, \fBNO_CORRECTION\fR, or
\fB0\fR (zero). Unless \fBNO_CORRECTION\fR is specified, this translation
forces the label to dominate the minimum classification, and initial
compartments set that is specified in the \fBlabel_encodings\fR file and
corrects the label to include other label components that are required by the
\fBlabel_encodings\fR file, but not present in \fIstring\fR. The translation of
a clearance might not be the same as the translation of a sensitivity label.
These functions use different tables of the \fBlabel_encodings\fR file that
might contain different words and constraints.
.SH RETURN VALUES
.sp
.LP
These functions return 1 if the translation was successful and a valid binary
label was returned. Otherwise they return 0 and the value of the \fIerror\fR
argument indicates the error.
.SH ERRORS
.sp
.LP
When these functions return zero, \fIerror\fR contains one of the following
values:
.sp
.ne 2
.na
\fB\fB\(mi1\fR\fR
.ad
.RS 9n
Unable to access the \fBlabel_encodings\fR file.
.RE

.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 9n
The label \fIlabel\fR is not valid for this translation and the \fBNEW_LABEL\fR
or \fBNO_CORRECTION\fR flag was not specified, or the label \fIlabel\fR is not
dominated by the process's \fIsensitivity label\fR and the process does not
have \fBPRIV_SYS_TRANS_LABEL\fR in its set of effective privileges.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 9n
The character-coded label \fIstring\fR is in error. \fIerror\fR is a one-based
index into \fIstring\fR indicating where the translation error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/security/tsol/label_encodings\fR\fR
.ad
.sp .6
.RS 4n
The label encodings file contains the classification names, words, constraints,
and values for the defined labels of this system.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     Obsolete
_
MT-Level        MT-Safe
.TE

.sp
.LP
The \fBstobsl()\fR and \fBstobclear()\fR functions are obsolete. Use the
\fBstr_to_label\fR(3TSOL) function instead.
.SH SEE ALSO
.sp
.LP
\fBblcompare\fR(3TSOL), \fBhextob\fR(3TSOL), \fBlibtsol\fR(3LIB),
\fBstr_to_label\fR(3TSOL), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
The functionality described on this manual page is available only if the system
is configured with Trusted Extensions.
.sp
.LP
In addition to the \fBADMIN_LOW\fR name and \fBADMIN_HIGH\fR name strings
defined in the \fBlabel_encodings\fR file, the strings "\fBADMIN_LOW\fR" and
"\fBADMIN_HIGH\fR" are always accepted as character-coded labels to be
translated to the appropriate \fBADMIN_LOW\fR and \fBADMIN_HIGH\fR label,
respectively.
.sp
.LP
Modifying an existing \fBADMIN_LOW\fR label acts as the specification of a
\fBNEW_LABEL\fR and forces the label to start at the minimum label that is
specified in the \fBlabel_encodings\fR file.
.sp
.LP
Modifying an existing \fBADMIN_HIGH\fR label is treated as an attempt to change
a label that represents the highest defined classification and all the defined
compartments that are specified in the \fBlabel_encodings\fR file.
.sp
.LP
The \fBNO_CORRECTION\fR flag is used when the character-coded label must be
complete and accurate so that translation to and from the binary form results
in an equivalent character-coded label.