'\" 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 "20 Jul 2007" "SunOS 5.11" "Trusted Extensions Library Functions" .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 \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 .mk .na \fB\fBNEW_LABEL\fR\fR .ad .RS 17n .rt \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 .mk .na \fB\fBNO_CORRECTION\fR\fR .ad .RS 17n .rt 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 .mk .na \fB\fB0 (zero)\fR\fR .ad .RS 17n .rt 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 .mk .na \fB\fB\(mi1\fR\fR .ad .RS 9n .rt Unable to access the \fBlabel_encodings\fR file. .RE .sp .ne 2 .mk .na \fB\fB0\fR\fR .ad .RS 9n .rt 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 .mk .na \fB\fB>0\fR\fR .ad .RS 9n .rt 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 .mk .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 tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityObsolete _ MT-LevelMT-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.