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]
stobl, stobsl, stobclear - translate character-coded labels to binary labels

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);

The stobsl() and stobclear() 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.

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective 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

NO_CORRECTION 0 (zero)

The error argument is a return parameter that is set only if the function 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 functions use different tables of the label_encodings file that might contain different words and constraints.

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.

When these functions return zero, error contains one of the following values: -1

0 >0 /etc/security/tsol/label_encodings

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.

blcompare(3TSOL), hextob(3TSOL), libtsol(3LIB), str_to_label(3TSOL), attributes(5)

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.