man pages section 4: File Formats

label_encodings(4)

NAME

label_encodings- Label encodings file

SYNOPSIS

/etc/security/tsol/label_encodings

DESCRIPTION

The label_encodings file is a standard encodings file of security labels that are used to control the conversion of human-readable labels into an internal format, the conversion from the internal format to a human-readable canonical form, and the construction of banner pages for printed output. In the Trusted Solaris environment, the label_encodings file is protected at the label admin_high. The file should be edited and checked in an admin_high workspace by the security administrator using the Edit Label Encodings action in the System_Admin folder in the Application Manager.

EXTENDED DESCRIPTION

In addition to the required sections of the label encodings file described in Compartmented Mode Workstation Labeling: Encodings Format, the Trusted Solaris environment accepts optional local extensions. These extensions provide various translation options and an association between character-coded color names and sensitivity labels.

The optional local extensions section starts with the LOCAL DEFINITIONS: keyword and is followed by zero or more of the following unordered statements:

ADMIN LOW NAME=name

The string name is accepted as an alternate name for the ADMIN_LOW label when translating from character-coded to binary form. The string name is the string returned when translating the ADMIN_LOW label from binary to character-coded form. If this option is not specified, ADMIN_LOW is used.

Note that use of this option could lead to interoperability problems with machines which do not have the same alternate name.

ADMIN HIGH NAME=name

The string name is accepted as an alternate name for the ADMIN_HIGH label when translating from character-coded form to binary form. The string name is the string returned when translating the ADMIN_HIGH label from binary to character-coded form. If this option is not specified, ADMIN_HIGH is used.

Note that use of this option could lead to interoperability problems with machines which do not have the same alternate name.

DEFAULT LABEL VIEW IS EXTERNAL

Unless otherwise specified, when an ADMIN_HIGH or ADMIN_LOW binary label is translated to a character-coded label, the character-coded label will be in external form. In external form ADMIN_HIGH is demoted to the maximum label and ADMIN_LOW is promoted to the minimum label. If this option is not specified, the external label view applies.

DEFAULT LABEL VIEW IS INTERNAL

Unless otherwise specified, when an ADMIN_HIGH or ADMIN_LOW binary label is translated to a character-coded label, the character-coded label will be in internal form. In internal form, ADMIN_HIGH is represented by the string ADMIN_HIGH and ADMIN_LOW is represented by the string ADMIN_LOW. If this option is not specified, the external label view applies.

DEFAULT FLAGS= value

This option represents a default GFI Flags= keyword value to be used if no flags are specified as a parameter to the translation. Caution must be taken when defining a DEFAULT FLAGS= value that the appropriate Flags= values have been provided. A non-zero value also implies that label validation during translation from binary to character-coded form is not done. If this option is not specified, the default value is 0 (zero).

FORCED FLAGS= value

This option represents a GFI Flags= keyword value to be used in all translations. Caution must be taken when defining a FORCED FLAGS= value that the appropriate Flags= values have been provided. A non-zero value also implies that label validation during translation from binary to character-coded form is not done. If this option is not specified, the default value is 0 (zero).

CLASSIFICATION NAME= name

This option specifies the string to be displayed in the Label builder GUI for the title of the Classification names section. Specifying a NULL value for name leaves the section without a title. If this option is not specified, the default value is CLASSIFICATION.

COMPARTMENTS NAME= name

This option specifies the string to be displayed in the label builder GUI for the title of the Compartments Word section. Specifying a NULL value for name leaves the section without a title. If this option is not specified, the default value is COMPARTMENTS.

DEFAULT USER SENSITIVITY LABEL= sensitivity label

This option specifies the sensitivity label to use as the user's minimum sensitivity label if none is defined for the user in the administrative databases. The default value is the MINIMUM SENSITIVITY LABEL= value from the ACCREDITATION RANGE: section of the label encodings file.

DEFAULT USER CLEARANCE= clearance

This option specifies the clearance to use as the user's clearance if none is defined for the user in the administrative databases. The default value is the MINIMUM CLEARANCE= value from the ACCREDITATION RANGE: section of the label encodings file.

The final part of the LOCAL DEFINITIONS: section defines the character-coded color names to be associated with various words, sensitivity labels, or classifications. This section supports the bltocolor(3TSOL) function. It consists of the COLOR NAMES: keyword and is followed by zero or more color-to-label assignments. Each statement has one of the following two syntaxes:

word= word value;  color= color value;

label= label value;  color= color value;

where color value is a character-coded color name to be associated with the word word value, sensitivity label label value, or classification label value.

The character-coded color name color value for a label is determined by the order of entries in the COLOR NAMES: section that make up the label. If a label contains a word word value that is specified in this section, the color value of the label is the one associated with the first word value specified. If no specified word word value is contained in the label, the color value is the one associated with an exact match of a label value. If there is no exact match, the color value is the one associated with the first specified label value whose classification matches the classification of the label.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsr

EXAMPLES

Example 1 A sample `LOCAL DEFINITIONS:` section

LOCAL DEFINITIONS:
ADMIN LOW NAME= LoLo;   * It is strongly advised not to use this option
ADMIN HIGH NAME= HiHi;  * It is strongly advised not to use this option

DEFAULT LABEL VIEW IS INTERNAL;

DEFAULT FLAGS= 0x4;
FORCED FLAGS= 0;

CLASSIFICATION NAME=;  * No Classification name title
COMPARTMENTS NAME=;    * No Compartments word title

DEFAULT USER SENSITIVITY LABEL= C A;
DEFAULT USER CLEARANCE LABEL= S ABLE;


COLOR NAMES:

label= Admin_Low;    color= Pale Blue;
label= unclassified; color= light grey;
word= Project A;     color= bright blue;
label= c;            color= sea foam green;
label= secret;       color= #ff0000;       * Hexadecimal RGB value
word= Hotel;         color= Lavender;
word= KeLO;          color= red;
label= TS;           color= khaki;
label= TS Elephant;  color= yellow;
label= Admin_High;   color= shocking pink;

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. It is protected at the label admin_high.

DIAGNOSTICS

The following diagnostics are in addition to those found in Appendix A of Compartmented Mode Workstation Labeling: Encodings Format:

Admin_High color already assigned as XXX.: A color has already been defined for the ADMIN_HIGH label. Another cannot be defined.
Admin_Low color already assigned as XXX.: A color has already been defined for the ADMIN_LOW label. Another cannot be defined.
BOUND TRANSLATION BY CLEARANCE obsolete, Bound is always a Sensitivity Label.: This option is obsolete and ignored. All label translations are bound by the calling process' sensitivity label.
BOUND TRANSLATION BY SENSITIVITY LABEL obsolete, Bound is always a Sensitivity Label.: This option is obsolete and ignored. All label translations are bound by the calling process' sensitivity label.
Can't allocate NNN bytes for ADMIN HIGH NAME=: The system cannot dynamically allocate the memory it needs to process the ADMIN_HIGH NAME= option.
Can't allocate NNN bytes for ADMIN LOW NAME=: The system cannot dynamically allocate the memory it needs to process the ADMIN_LOW NAME= option.
Can't allocate NNN bytes for CLASSIFICATION NAME=: The system cannot dynamically allocate the memory it needs to process the CLASSIFICATION NAME= option.
Can't allocate NNN bytes for COMPARTMENTS NAME=: The system cannot dynamically allocate the memory it needs to process the COMPARTMENTS NAME= option.
Can't allocate NNN bytes for color name XXX.: The system cannot dynamically allocate the memory it needs to store color name XXX.
Can't allocate NNN bytes for color names table.: The system cannot dynamically allocate the memory it needs to process the COLOR NAMES: section.
Can't allocate NNN bytes for color table entry.: The system cannot dynamically allocate the memory it needs to process a Color Table entry.
Can't allocate NNN bytes for color word entry.: The system cannot dynamically allocate the memory it needs to process a Color Word entry.
Can't allocate NNN bytes for DEFAULT USER.: The system cannot dynamically allocate the memory it needs to process the DEFAULT USER.
DEFAULT USER CLEARANCE= XXX is not in canonical form. Is YYY what is intended?: This error occurs if the clearance specified, while understood, is not in canonical form. This additional canonicalization check ensures that no errors are made in specifying the clearance.
DEFAULT USER SENSITIVITY LABEL= XXX is not in canonical form. Is YYY what is intended?: This error occurs if a sensitivity label specified, while understood, is not in canonical form. This additional canonicalization check ensures that no errors are made in specifying the sensitivity label.
DO NOT FLOAT PROCESS INFORMATION LABEL: This option is obsolete and ignored.
Duplicate ADMIN HIGH NAME= ignored.: More than one ADMIN HIGH NAME= option was encountered. All but the first are ignored.
Duplicate ADMIN LOW NAME= ignored.: More than one ADMIN LOW NAME= option was encountered. All but the first are ignored.
Duplicate CLASSIFICATION NAME= ignored.: More than one CLASSIFICATION NAME= option was encountered. All but the first are ignored.
Duplicate COMPARTMENTS NAME= ignored.: More than one COMPARTMENTS NAME= option was encountered. All but the first are ignored.
Duplicate DEFAULT USER CLEARANCE= ignored.: More than one DEFAULT USER CLEARANCE= option was encountered. All but the first are ignored.
Duplicate DEFAULT USER SENSITIVITY LABEL= ignored.: More than one DEFAULT USER SENSITIVITY LABEL= option was encountered. All but the first are ignored.
End of File not found where expected. Found instead: XXX.: The noted extraneous text was found when the end of label encodings file was expected.
End of File or LOCAL DEFINITIONS: not found. Found instead: XXX.: The noted extraneous text was found when the LOCAL DEFINITIONS: section or end of label encodings file was expected.
FLOAT PROCESS INFORMATION LABEL: This option is obsolete and ignored.
Found color XXX without associated label.: The color XXX was found, however it had no label or word associated with it.
Invalid color label XXX.: The label XXX cannot be parsed.
Invalid DEFAULT USER CLEARANCE XXX.: The DEFAULT USER CLEARANCE XXX cannot be parsed.
Invalid DEFAULT USER SENSITIVITY LABEL XXX.: The DEFAULT USER SENSITIVITY LABEL XXX cannot be parsed.
Label preceding XXX did not have a color specification.: A label or word was found without a matching color name.
MARKINGS NAME= ignored.: This option is obsolete and ignored.
Word XXX not found as a valid Sensitivity Label word.: The word XXX was not found as a valid word for a sensitivity label.

Trusted Solaris 8 Reference Manual

bcltobanner(3TSOL), blinset(3TSOL), bltocolor(3TSOL), bltos(3TSOL), blvalid(3TSOL), labelinfo(3TSOL), labelvers(3TSOL), stobl(3TSOL), chk_encodings(1M)

Trusted Solaris Label Administration

Defense Intelligence Agency document DDS-2600-6216-93, Compartmented Mode Workstation Labeling: Encodings Format, September 1993.

SunOS 5.8 Reference Manual

attributes(5)

WARNINGS

Creation of and modification to the label encodings file should only be undertaken with a thorough understanding not only of the concepts in Compartmented Mode Workstation Labeling: Encodings Format but also of the details of the local labeling requirements.

The following warnings are paraphrased from Compartmented Mode Workstation Labeling: Encodings Format.

Take extreme care when modifying a label encodings file that is already loaded and running in a Trusted Solaris environment. Once the system runs with the label encodings file, many objects are labeled with sensitivity labels that are well formed with respect to the loaded label encodings file. If the label encodings file is subsequently changed, it is possible that the existing labels will no longer be well-formed. Changing the bit patterns associated with words causes existing objects whose labels contain the words to have possibly invalid labels. Raising the minimum classification or lowering the maximum classification associated with words will likely cause existing objects whose labels contain the words to no longer be well-formed.

Information Labels (ILs) are now obsolete. See NOTES.

Changes to a current encodings file that has already been used should be limited only to adding new classifications or words, changing the names of existing words, or modifying the local extensions. As described in Compartmented Mode Workstation Labeling: Encodings Format, it is important to reserve extra inverse bits when the label encodings file is first created to allow for later expansion of the label encodings file to incorporate new inverse words. If an inverse word is added that does not use reserved inverse bits, all existing objects in the environment will erroneously have labels that include the new inverse word.

NOTES

Defining the label encodings file is a three-step process. First, the set of human-readable labels to be represented must be identified and understood. The definition of this set includes the list of classifications and other words used in the human-readable labels, relations between and among the words, classification restrictions associated with use of each word, and intended use of the words in mandatory access control and labeling system output. Next, this definition is associated with an internal format of integers, bit patterns, and logical relationship statements. Finally, a label encodings file is created. The Compartmented Mode Workstation Labeling: Encodings Format document describes the second and third steps, and assumes that the first has already been performed.

Information labels (ILs) are not supported in Trusted Solaris 7 and later releases. Trusted Solaris software interprets any ILs on communications and files from systems running earlier releases as ADMIN_LOW.

Objects still have CMW labels, and CMW labels still include the IL component: IL[SL]; however, the IL component is fixed at ADMIN_LOW.

As a result, Trusted Solaris 7 and later releases have the following characteristics:

ILs do not display in window labels; SLs (Sensitivity Labels) display alone within brackets.
ILs do not float.
Setting an IL on an object has no effect.
Getting an object's IL will always return ADMIN_LOW.
Although certain utilities, library functions, and system calls can manipulate IL strings, the resulting ILs are always ADMIN_LOW, and cannot be set on any objects.

Trusted Solaris 8 Last Revised 7 Sep 2000