stobl(3TSOL) Trusted Extensions Library Functions stobl(3TSOL)NAME
stobl, stobsl, stobclear - translate character-coded labels to binary
labels
SYNOPSIS
cc [flag...] file... -ltsol [library...]
#include <tsol/label.h>
int stobsl(const char *string, m_label_t *label, const int flags,
int *error);
int stobclear(const char *string, m_label_t *clearance,
const int flags, int *error);
DESCRIPTION
The stobsl() and stobclear() functions translate character-coded labels
into binary labels. They also modify an existing binary label by incre‐
menting or decrementing it to produce a new binary label relative to
its existing value.
The calling process must have PRIV_SYS_TRANS_LABEL in its set of effec‐
tive privileges to perform label translation on character-coded labels
that dominate the process's sensitivity label.
The generic form of an input character-coded label string is:
[ + ] classification name ] [ [ + | − ] word ...
Leading and trailing white space is ignored. Fields are separated by
white space, a `/' (slash), or a `,' (comma). Case is irrelevant. If
string starts with + or −, string is interpreted a modification to an
existing label. If string starts with a classification name followed by
a + or −, the new classification is used and the rest of the old label
is retained and modified as specified by string. + modifies an existing
label by adding words. − modifies an existing label by removing words.
To the maximum extent possible, errors in string are corrected in the
resulting binary label label.
The stobsl() and stobclear() functions also translate hexadecimal label
representations into binary labels (see hextob(3TSOL)) when the string
starts with 0x and either NEW_LABEL or NO_CORRECTION is specified in
flags.
The flags argument can take the following values:
NEW_LABEL label contents is not used, is formatted as a label of
the relevant type, and is assumed to be ADMIN_LOW for
modification changes. If NEW_LABEL is not present,
label is validated as a defined label of the correct
type dominated by the process's sensitivity label.
NO_CORRECTION No corrections are made if there are errors in the
character-coded label string. string must be complete
and contain all the label components that are required
by the label_encodings file. The NO_CORRECTION flag
implies the NEW_LABEL flag.
0 (zero) The default action is taken.
The error argument is a return parameter that is set only if the func‐
tion is unsuccessful.
The stobsl() function translates the character-coded sensitivity label
string into a binary sensitivity label and places the result in the
return parameter label.
The flags argument can be either NEW_LABEL, NO_CORRECTION, or 0 (zero).
Unless NO_CORRECTION is specified, this translation forces the label to
dominate the minimum classification, and initial compartments set that
is specified in the label_encodings file and corrects the label to
include other label components required by the label_encodings file,
but not present in string.
The stobclear() function translates the character-coded clearance
string into a binary clearance and places the result in the return
parameter clearance.
The flags argument can be either NEW_LABEL, NO_CORRECTION, or 0 (zero).
Unless NO_CORRECTION is specified, this translation forces the label to
dominate the minimum classification, and initial compartments set that
is specified in the label_encodings file and corrects the label to
include other label components that are required by the label_encodings
file, but not present in string. The translation of a clearance might
not be the same as the translation of a sensitivity label. These func‐
tions use different tables of the label_encodings file that might con‐
tain different words and constraints.
RETURN VALUES
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
error argument indicates the error.
ERRORS
When these functions return zero, error contains one of the following
values:
−1 Unable to access the label_encodings file.
0 The label label is not valid for this translation and the
NEW_LABEL or NO_CORRECTION flag was not specified, or the
label label is not dominated by the process's sensitivity
label and the process does not have PRIV_SYS_TRANS_LABEL in
its set of effective privileges.
>0 The character-coded label string is in error. error is a one-
based index into string indicating where the translation error
occurred.
FILES
/etc/security/tsol/label_encodings
The label encodings file contains the classification names, words,
constraints, and values for the defined labels of this system.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Obsolete │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
The stobsl() and stobclear() functions are obsolete. Use the
str_to_label(3TSOL) function instead.
SEE ALSOblcompare(3TSOL), hextob(3TSOL), libtsol(3LIB), str_to_label(3TSOL),
attributes(5)NOTES
The functionality described on this manual page is available only if
the system is configured with Trusted Extensions.
In addition to the ADMIN_LOW name and ADMIN_HIGH name strings defined
in the label_encodings file, the strings "ADMIN_LOW" and "ADMIN_HIGH"
are always accepted as character-coded labels to be translated to the
appropriate ADMIN_LOW and ADMIN_HIGH label, respectively.
Modifying an existing ADMIN_LOW label acts as the specification of a
NEW_LABEL and forces the label to start at the minimum label that is
specified in the label_encodings file.
Modifying an existing ADMIN_HIGH 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 label_encodings
file.
The NO_CORRECTION 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.
SunOS 5.10 20 Jul 2007 stobl(3TSOL)
