Trusted Solaris Developer's Guide

Translating Labels

All labels can be represented in binary, text, or hexadecimal. Within the kernel all labels are stored in binary form, and binary is the form used for labels passed to and received from programming interfaces.

Binary Labels - Classifications are stored as an integer and compartments are stored as bit vectors using 0's and 1's.
Character-Coded Labels - Human-readable labels that display classifications, and compartments using the names defined in the label_encodings(4) file.
Hexadecimal Labels - The character-coded representation of the hexadecimal number that represents the same bit pattern as the corresponding binary label. The label has plain text characters but does not reveal the classification or compartment names. A process can store a label in plain text form when it will be read by processes at arbitrary labels.

Note -

If label names are stored in files at a sensitivity label lower than the sensitivity level of the label names, or in files where users without the proper permissions or authorization could access them, store the label names in either binary or hexadecimal format to make them unreadable.

Binary and Text Label Translation

Labels can be translated from binary to text and back again. The calling process needs the sys_trans_label privilege in its effective set to translate any label not dominated by the process's sensitivity label.

Text characters can be input in any combination of upper and lowercase letters, but they are always output all uppercase.
Text label input and output formats consist of classifications and words defined in the label_encodings file. Classification names and words may contain embedded blanks or punctuation if they are defined that way in the label_encodings file.

Binary to Text Label Translation Routines

These examples translate binary labels to text. The translation uses the keyword settings in label_encodings(4) and the flag parameter value. Not all flag values make sense for every label, although nothing stops you from using any flag with any type of label. The descriptions state the label type a flag is to be used with. Settings that apply to sensitivity labels also apply to CMW labels.

LONG_WORDS--Translate a binary label using the long names for words.
SHORT_WORDS--Translate a binary label using the short names for words.
LONG_CLASSIFICATION--Translate a binary label using long names for the classification.
SHORT_CLASSIFICATION--Translate a binary label using short names for the classification.
NO_CLASSIFICATION--Do not include the classification in the translation of a binary sensitivity label label
VIEW_INTERNAL--Use internal names for the highest and lowest sensitivity labels in the system: ADMIN_HIGH and ADMIN_LOW.
VIEW_EXTERNAL--Demote an ADMIN_HIGH sensitivity label to the next highest label, and promote an ADMIN_LOW label to the lowest label defined in label_encodings(4).

Note -

The label view process attribute described in "Get and Set Process Security Attribute Flags" contains the status of the label view.

CMW Labels

The text output form for CMW labels is as follows:

[SENSITIVITY LABEL]

This example initializes a CMW label to ADMIN_LOW [ADMIN_HIGH] and prints out the internal and external views. The process runs at ADMIN_HIGH and does not need privileges to translate the ADMIN_LOW [ADMIN_HIGH] label.

#include <tsol/label.h>

main()
{
	int retval, length = 0;
	char *string1 = (char *)0, *string2 = (char *)0;
	bclabel_t cmwlabel;

	bclhigh(&cmwlabel);
	retval = bcltos(&cmwlabel, &string1, length, VIEW_INTERNAL);
	printf("View Internal = %s\n", string1);

	retval = bcltos(&cmwlabel, &string2, length, VIEW_EXTERNAL);
	printf("View External = %s\n", string2);
}

The printf statements print the following:

View Internal = ADMIN_LOW [ADMIN_HIGH]
View External = UNCLASSIFIED [TS A B SA SB CC]

Note -

Although bclhigh() and the other functions in the bclmanifest() family allow you to manipulate to manipulate the value of the information label of the CMW label, you cannot set this value on an object. The information label for all objects is ADMIN_LOW by default.

Sensitivity and Information Labels

The text forms of sensitivity labels and information labels output by interfaces are separated by spaces and formatted as follows where the curly brackets indicate optional items and the ellipses indicate repeated words. In a sensitivity label, words represent compartments, and in an information label words represent compartments and markings.

CLASSIFICATION {WORD}...

The following code example translates a binary sensitivity label to text using different flags. The process runs at TS A B and needs the sys_trans_label privilege for the translation after the call to bslhigh(3TSOL). The code comments indicate where privilege bracketing as described in Chapter 3, Privileges should take place.

#include <tsol/label.h>
main()
{
	int retval, length = 0;
	char *string1 = (char *)0, *string2 = (char *)0,
		*string3 = (char *)0, *string4 = (char *)0,
		*string5 = (char *)0, *string6 = (char *)0,
		*string7 = (char *)0;
	bclabel_t cmwlabel;
	bslabel_t senslabel;

	retval = getcmwplabel(&cmwlabel);
	getcsl(&senslabel, &cmwlabel);

	retval = bsltos(&senslabel, &string1, length, LONG_WORDS);
	printf("Retval1 = %d Long Words = %s\n", retval, string1);

	retval = bsltos(&senslabel, &string2, length, SHORT_WORDS);
	printf("Retval2 = %d Short Words = %s\n", retval, string2);

	retval = bsltos(&senslabel, &string3, length, LONG_CLASSIFICATION);
	printf("Retval3 = %d Long Classifications = %s\n", retval, string3);

	retval = bsltos(&senslabel, &string4, length, SHORT_CLASSIFICATION);
	printf("Retval4 = %d Short Classifications = %s\n", retval, string4);

	retval = bsltos(&senslabel, &string5, length, NO_CLASSIFICATION);
	printf("Retval5 = %d No Classification = %s\n", retval, string5);

	bslhigh(&senslabel);
/* Turn sys_trans_label on in the effective set */
	retval = bsltos(&senslabel, &string6, length, VIEW_INTERNAL);
/* sys_trans_label off. */
	printf("Retval6 = %d View Internal = %s\n", retval, string6);

	retval = bsltos(&senslabel, &string7, length, VIEW_EXTERNAL);
	printf("Retval7 = %d View External = %s\n", retval, string7);
}

The printf statements print the following.

Long Words = TS A B
Short Words = TS A B
Long Classifications = TOP SECRET A B
Short Classifications = TS A B
No Classification = A B
View Internal = ADMIN_HIGH
View External = TS A B SA SB CC

Text to Binary and Hexadecimal Label Translation Routines

This example translates text strings to a binary CMW label or sensitivity label using the following flag values:

NEW_LABEL - Create a new label and correct the string as much as possible so the binary label is a complete and valid label for the system as defined in label_encodings(4). If the correction cannot be made, an error is returned. The string can be a text or hexadecimal string.
NO_CORRECTION - Create a new label, but do not correct the construction of the string. If the string is not a complete and valid label for the system, an error is returned. The string can be a text hexadecimal string.

CMW Labels

Text CMW labels are accepted in the following form: [sensitivity_label].

Sensitivity and Information Labels

Text sensitivity and information labels are accepted in the following forms. Input items can be separated by white space, commas, or slashes (/). Short and long forms of classification names and words are interchangeable.

{+} {classification} {{+|-}{word}...

The vertical bar (|) indicates a choice between two items. Leading and trailing white space is ignored.
The plus and minus signs can be used to modify an existing label to turn on or off the compartments and markings associated with the words.
Curly braces indicate optional items and ellipses indicate repeated words. In a sensitivity label, the words represent compartments.

Code Examples

This example translates text strings to a binary CMW label and sensitivity label and back again using the NEW_LABEL flag. An example of translating a sensitivity label to a specified length (clipping) is also given. If the process runs at [TS A B] or higher, the sys_trans_label privilege is not needed for the label translations.

#include <tsol/label.h>

main()
{
	int retval, error, length = 0;
	char *cmwstring ="SECRET A B [TOP SECRET A B]";
	char *sensstring = "TOP SECRET A B";
	char *string1 = (char *)0, *string2 = (char *)0,
		*string3 = (char *)0;
	bclabel_t cmwlabel;
	bslabel_t senslabel;


	retval = stobcl(cmwstring, &cmwlabel, NEW_LABEL, &error);
	retval = bcltos(&cmwlabel, &string1, length, ALL_ENTRIES);
	retval = stobsl(sensstring, &senslabel, NEW_LABEL, &error);
	retval = bsltos(&senslabel, &string2, length, ALL_ENTRIES);
	string3 = sbsltos(&senslabel, 4);

	printf("CMW label = %s\nSens label = %s\nClipped label = %s\n'',
		string1, string2, string3);
}

The printf statement prints the following. In the clipped label, the arrow <-indicates the sensitivity label name has clipped letters.

CMW label = [TS A B]
Sens label = TS A B
Clipped label = TS<-

Binary and Hexadecimal Label Translation

There are two types of binary to hexadecimal routines: regular and reentrant. Both types of routines return a pointer to a string that contains the result of the translation or NULL if the label being translated is not a binary label.

Binary labels - Classifications are stored as integer values and compartments are stored as bit vectors of 0's and 1's.
Hexadecimal labels - The text representation of the hexadecimal number that represents the same bit pattern as the corresponding binary label.

Binary and Hexadecimal Label Translation Routines

This example converts a binary CMW label to hexadecimal and back again. Converting a sensitivity label is similar.

#include <tsol/label.h>
#include <stdio.h>

main()
{
	int retval;
	bclabel_t hcmwlabel, hexcmw;
	char *string;

	getcmwplabel(&hcmwlabel);
	if((string = bcltoh(&hcmwlabel)) != NULL)
		printf("Hex string = %s\n", string);

	retval = htobcl(string, &hexcmw);
	printf("Return Value = %d\n", retval);
}

The first printf statements print the binary CMW label in the following hexadecimal format:

Hex string = ADMIN_LOW [0xsensitivity label value]

The second printf statement prints the following where non-zero indicates a successful translation:

Return Value = 1

Reentrant Binary and Hexadecimal Label Translation Routines

The reentrant (MT-SAFE) routine bcltoh_r(3TSOL) requires the allocation and freeing of memory for a variable of the specified type. This example allocates memory, translates the binary CMW label to hexadecimal, and frees the memory at the end. Converting a sensitivity label to hexadecimal and back is a similar process.

#include <tsol/label.h>
#include <stdio.h>

main()
{
	int retval;
	bclabel_t hcmwlabel, hexcmw;
	char *string, *hex;

	getcmwplabel(&hcmwlabel);
	hex = h_alloc(SUN_CMW_ID);
	if((string = bcltoh_r(&hcmwlabel, hex)) != NULL)
		printf("Hex string = %s\n", string);

	retval = htobcl(string, &hexcmw);
	printf("Return Value = %d\n", retval);
	h_free(hex);
}

The printf statement prints the binary clearance in the following hexadecimal format:

Hex string =0x00000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000[0x00040c0000000000000000000000
000000000000000000000003ffffffffffff0000]

Return Value = 1