Chapter 3 Making a Label Encodings File (Tasks)

This chapter describes creating and modifying a label_encodings file.

• Encodings File Syntax

• Managing Label Encodings (Task Map)

Encodings File Syntax

The label_encodings file contains a VERSION specification and seven mandatory sections: CLASSIFICATIONS, INFORMATION LABELS, SENSITIVITY LABELS, CLEARANCES, CHANNELS, PRINTER BANNERS, and ACCREDITATION RANGE. The sections must appear in the order given. An optional LOCAL DEFINITIONS section can follow.

In the following table, Mandatory keyword means only that the keyword must be present. Not all keywords must have definitions. The notes for each section indicate what must be defined and what is optional.

For all the required sections, the keywords in the preceding table must be present, but not all of the sections must have definitions. For example, a label_encodings file with only CLASSIFICATIONS and ACCREDITATION RANGE definitions is valid.

Word Order Requirements

The order in which words are configured for sensitivity labels and clearances is not enforced. However, the order is important when setting up relationships between words. By convention, the WORDS in the SENSITIVITY LABELS section are arranged in increasing order of importance.

For the effect of word order, see Specifying Channels of Chapter 4, Labeling Printer Output (Tasks). Detailed information is provided in Compartmented Mode Workstation Labeling: Encodings Format.

If a compartment word is defined for one type of label (by assigning the compartment word to one or more bits) in the label_encodings file, then the same bits must be assigned to a word in the definition of the other types of labels. While all types of labels use the same classification names, the words that are used for each type of label can be different. The words can be different even when they are encoded with the same bits and literally refer to the same thing. Clearance labels can allow combinations of words that have been disallowed in the definitions for sensitivity labels words.

Classification Name Syntax

The classification is the hierarchical portion of a label. Each label has one and only one classification. A site can define up to 255 classifications. An integer value from 1 to 255 can be assigned to a classification in the label_encodings file. The value 0 is reserved for the ADMIN_LOW administrative label. The value 32,767 is reserved for the ADMIN_HIGH administrative label. For an illustration, see Figure 1–2.

Classifications are defined once for clearances and for sensitivity labels in the CLASSIFICATIONS section of the label_encodings file.

A classification with a higher value dominates a classification with a lower value. The following table shows two sets of label names that are assigned the same values in different encodings files. The left column shows sample sensitivity labels from the label_encodings.example file. The middle column shows labels from the label_encodings.gfi.multi file. A label with the Registered or Top Secret classification, with a value of 6, dominates the labels that are listed in its column.

Keywords for Classifications

The following list describes the keywords that can be defined for classifications. For examples of initial compartment definitions, see Default and Inverse Words.

name=

Cannot contain (/) or (,) or (;). All other alphanumeric characters and white space are allowed. Users can enter either the name or the sname or the aname when specifying labels.

sname=

Required in classifications only. The short name appears in sensitivity labels in brackets.

aname=

Optional. Name that can be entered by users when a classification is needed.

value=

The values that you assign should represent the actual hierarchy among the classifications. The values should leave room for later expansion. 0 is reserved for ADMIN_LOW. Values can start at 1 and go to 255.

initial compartments=

Optional. Specify bit numbers for any default compartment words. Default compartment words are words that should initially appear in any label that has the associated classification.

Advanced: Specify bit numbers for any inverse words. The minimum classification should not have initial compartments.

initial markings=

Obsolete. Do not define.

The following example shows the top of the label_encodings.multi file.

Example 3–1 Classifications With Initial Compartments in label_encodings.multi

VERSION= Trusted Solaris Multi-Label Sample Version - 5.6 05/07/27

*
*    WARNING:  If CIPSO Tag Type 1 network labels are to be used:
*
*        a) All CLASSIFICATIONS values must be less than or equal to 255.
*        b) All COMPARTMENTS bits must be less than or equal to 239.
*

CLASSIFICATIONS:

*
name= UNCLASSIFIED;  sname= U;  value= 1;
name= CONFIDENTIAL;  sname= C;  value= 4; initial compartments= 4-5 190-239;
name= SECRET;        sname= S;  value= 5; initial compartments= 4-5 190-239;
name= TOP SECRET;    sname= TS; value= 6; initial compartments= 4-5 190-239;

Each classification has the mandatory name, sname, and value fields. The CONFIDENTIAL, SECRET, and TOP SECRET classifications have initial compartments. The lowest classification, UNCLASSIFIED, has no initial compartments.

The initial compartment bit assignments of 4-5 and 190-239 signify that bits 4, 5, and 190 through 239 are turned on. These bits are set to 1 in a label with this classification.

Some of the initial compartments are later used to define default and inverse words. Some initial compartments are reserved for possible later definitions of inverse words.

The following example shows a set of classifications that have no initial compartments.

Example 3–2 Classifications With No Initial Compartments in label_encodings.example

CLASSIFICATIONS:

name= PUBLIC; sname= PUBLIC; value= 1;
name= INTERNAL_USE_ONLY; sname= INTERNAL; aname= INTERNAL; value= 4;
name= NEED_TO_KNOW; sname= NEED_TO_KNOW; aname= NEED_TO_KNOW; value= 5;
name= REGISTERED; sname= REGISTERED; aname= REGISTERED; value= 6;

Default and Inverse Words

When a bit is defined as an initial compartment, the bit is set to 1 in every label that contains the classification. Any bit that is specified for an initial compartment can be defined later in the label_encodings file as a default word or an inverse word.

• A default compartment word is a word that appears in any label that contains the classification.

• An inverse compartment word is a word that appears in a label that has the associated classification when another word that you define with the inverse compartment's bit is not present.

Example 3–3 Assigning Initial Compartments

In this example, the PUBLIC classification is assigned no initial compartments, while the WEB COMPANY classification is assigned initial compartments 4 and 5. A label that includes the PUBLIC classification has no default compartments. A label that includes the WEB COMPANY classification always has compartment bits 4 and 5 turned on.

name= PUBLIC;  sname= P;  value= 1;
name= WEB COMPANY;  sname= WEBCO;  value= 4; initial compartments= 4-5

The following section shows how these initial compartment bits can be assigned to words.

Example 3–4 Defining Default and Inverse SENSITIVITY LABELS Words

In this example, compartment bits 4 and 5 are assigned to the word DIVISION ONLY. Each compartment bit is also associated with an inverse word. WEBC AMERICA is assigned to the inverse compartment bit ~4. WEBC WORLD is assigned to the inverse compartment bit ~5. These assignments have the following results:

• A sensitivity label with the WEB COMPANY classification initially includes the word DIVISION ONLY. The label's binary representation has the compartment bits 4 and 5 turned on.

• A sensitivity label with the PUBLIC classification always has compartment bits 4 and 5 turned off. The words WEBC AMERICA and WEBC WORLD are included in the label.

  Because a minclass of IUO is specified for the inverse words, WEBC AMERICA and WEBC WORLD are not displayed in the PUBLIC sensitivity label. The presence of these two inverse words is understood.

SENSITIVITY LABELS:

WORDS:

name= DIVISION ONLY;  sname= DO;       minclass= WEB COMPANY; compartments= 4-5;
name= WEBC AMERICA;   sname= WEBCA;    minclass= WEB COMPANY; compartments= ~4;
name= WEBC WORLD;     sname= WEBCW;    minclass= WEB COMPANY; compartments= ~5;

Compartment Words

Compartments are optional words that can be defined to appear in labels. Compartments are called categories in some other trusted systems. Compartments are used to indicate the special handling procedures to be used for the information whose label contains the compartment and the general class of people who might have access to the information.

Compartment words are assigned to non-hierarchical bits. However, hierarchies can be established between compartment words. These hierarchies are based on rules for including bits from one compartment word in the bits that are defined for another compartment word.

Compartment words are optionally defined in the WORDS subsection for each label type. Each compartment word is assigned to one or more bits.

While all types of labels use the same classifications, the words that are used for each type of label can be different. The words can be different even when they are encoded with the same bits and literally refer to the same thing.

The following example shows the WEB COMPANY compartment word. The word is specified with a short name (sname) of WEBCO and compartment bits 40-50.

Example 3–5 Sample Compartment Definition for a Sensitivity Label

WORDS:

name= WEB COMPANY; sname= WEBCO; compartments= 40-50;

Along with its classification field, each label has a 256-bit compartment field, of which 239 are available for CIPSO labels. Each bit is assignable in zero or more compartment words. Each word can have one or more compartment bits assigned. Out of the 239 available bits, many compartment words can be created. For an example, see the compartments planner in Table 6–3.

The classification, compartments, and combination requirements affect the accreditation range. The ACCREDITATION RANGE for each classification setting should be one of the following strings:

• only valid compartment combinations;

• all compartment combinations valid;

• all compartment combinations valid except;

Hierarchical Compartment Words

Hierarchical compartments can be used to differentiate between documents that are available to everyone in a larger group, and documents that are available to subgroups only.

Example 3–6 Using Bit Combinations to Establish Hierarchies

By defining a word that uses one bit and a second word that uses that same bit along with a second bit, you define a hierarchical relationship between the two words. The compartment word that is more general must be defined below the word that is more specific. For example, by defining a word that uses bit number 1 and another word that uses bits number 1 and 2, you give the two words a hierarchical relationship.

In this example, a Sales compartment is defined with two subcompartments, Direct Sales, and Indirect Sales. A single classification that is named WebCo is previously defined.

name= Direct_Sales;   compartments= 1, 2
name= Indirect_Sales;   compartments= 1, 3
name= Sales;   compartments= 1

This definition allows the WebCo company to differentiate between documents that can be accessed by anyone in the entire sales force, documents that can be accessed only by members of the indirect sales force, and documents that can be accessed only by members of the direct sales force.

• The security administrator gives the WebCo Direct_Sales clearance to employees in the direct sales organization. The WebCo Indirect_Sales clearance is given to employees in the indirect sales organization.

• Documents created by anyone working at the WebCo Direct_Sales label get the same label, so the documents are only accessible to employees in the direct sales department.

• Anyone in the indirect or direct sales forces can work at the WebCo Sales label because the compartment word Sales is below both the Direct_Sales and Indirect_Sales words. Creating documents at the WebCo Sales label makes the documents available to everyone in the Sales department.

Example 3–7 Using REQUIRED COMBINATIONS to Establish Hierarchies

If two words are specified together in the REQUIRED COMBINATIONS section, the second label is added to the label whenever the first word is used.

In this example, the definition of the Direct Sales, Indirect_Sales, and Sales serves essentially the same effect as the example in Example 3–6. The difference is that the Direct_Sales word will always have the Sales word with it

name= Direct_Sales;   compartments= 2
name= Indirect_Sales;   compartments= 3
name= Sales;   compartments= 1

REQUIRED COMBINATIONS:

Direct_Sales            Sales
Indirect_Sales          Sales

Managing Label Encodings (Task Map)

The safest time to modify a label_encodings file is when the first host is installed. Proceed with caution when modifying a file that is in use. For details, see the label_encodings(4) man page.

The following task map describes the tasks for modifying and installing a label_encodings file.

How to Create a label_encodings File

For sample files, see the /etc/security/tsol directory on an installed system. The files are described in Labels Files in Solaris Trusted Extensions Packages.

Before You Begin

You can create this file before you install Trusted Extensions on your first system. On that first system, you check the file. You can also create this file on the first system that you install with Trusted Extensions. This procedure must be completed before a second computer is configured with Trusted Extensions.

On a system that is configured with Trusted Extensions, you must be in the global zone in the Security Administrator role. On other systems, you can create and edit the file in any editor.

1. Create a backup copy of the original file.

2. Open a new or existing version of the file.

   • On a system that is not configured with Trusted Extensions, use any editor to create the file.

   • On a system that is configured with Trusted Extensions, use the Edit Encodings action to create the file.

     In CDE, the Trusted_Extensions folder in the Application Manager contains two actions for the encodings file.

     Edit Encodings

     Edits and checks the syntax of the specified label_encodings file.

     Check Encodings

     Checks the syntax of a specified label_encodings file.

3. Modify the file.

   For details, see How to Plan the Encodings File.

4. Continue with How to Analyze and Verify the label_encodings File.

How to Analyze and Verify the label_encodings File

Before You Begin

You must be in the global zone in the Security Administrator role.

1. Check the syntax and relationships of the labels.

   In a terminal, use the chk_encodings -a command to analyze and report on label relationships.

   $ chk_encodings -a encodings-file

2. Verify the file.

   The Check Encodings action runs the chk_encodings command on the specified file.

   • If the file passes, install it.

     Do you want to install this label_encodings file? yes

   • If the file does not pass, see How to Debug a label_encodings File for assistance.

3. Test the encodings file.

   Where possible, test the file on a few systems before approving the file for all systems at your site.

4. Create a master copy.

   For copying instructions, see How to Copy Files to Portable Media in Trusted Extensions in Oracle Solaris Trusted Extensions Configuration Guide.

5. Save a labeled copy of the file in a protected location.

How to Distribute the label_encodings File

1. Create a master copy.

   For copying instructions, see How to Copy Files to Portable Media in Trusted Extensions in Oracle Solaris Trusted Extensions Configuration Guide.

2. Immediately after installing a system with Trusted Extensions, copy the master file onto the system.

   For copying instructions, see How to Copy Files From Portable Media in Trusted Extensions in Oracle Solaris Trusted Extensions Configuration Guide.

How to Add or Rename a Classification

Before You Begin

You must be in the Security Administrator role in the global zone.

1. Edit the label_encodings file.

   Use the Edit Encodings action. For details, see How to Create a label_encodings File.

2. Specify a version number.

   In the VERSION= section put your site's name, a title for the file, a version number and the date.

   VERSION= Sun Microsystems, Inc. Example Version - 5.10 04/05/28

   Trusted Extensions uses SCCS keywords for the version number and the date. For details, see the sccs(1) man page.

   VERSION= Sun Microsystems, Inc. Example Version - %I% %E%

3. Specify the classification.

   In the CLASSIFICATIONS section, supply the long name, short name, and numeric value for the new classification.

   name= NEW_CLASS; sname= N; value= 2;

4. Include the new classification in the accreditation range.

   Add the new classification to the ACCREDITATION RANGE section.

   The following example shows three new classifications added to the ACCREDITATION RANGE section. Each classification is specified with all compartment combinations valid.

   ACCREDITATION RANGE: classification= UNCLASSIFIED; all compartment combinations valid; * i is new in this file classification= INTERNAL_USE_ONLY; all compartment combinations valid; * n is new in this file classification= NEED_TO_KNOW; all compartment combinations valid; classification= CONFIDENTIAL; all compartment combinations valid except: c c a c b classification= SECRET; only valid compartment combinations: . . . * r is new in this file classification= REGISTERED; all compartment combinations valid;

5. Adjust the ACCREDITATION RANGE section if necessary.

   You might need to make the new classification a minimum classification.

   minimum clearance= u; minimum sensitivity label= u; minimum protect as classification= u;

   ---

   Note –

   Make sure that you set a minimum clearance that is dominated by all the clearances that you plan to assign to users. Similarly, make sure that the minimum sensitivity label is dominated by all the minimum labels that you plan to assign to users.

   ---

6. Save your changes.

How to Specify Default and Inverse Words

Before You Begin

You must be in the Security Administrator role in the global zone.

1. Edit the label_encodings file.

   Use the Edit Encodings action. For details, see How to Create a label_encodings File.

2. Specify initial compartments.

   In the CLASSIFICATIONS section, specify compartments as part of the classification definition.

   CLASSIFICATIONS: name= PUBLIC; sname= P; value= 1; name= WEB COMPANY; sname= WEBCO; value= 2; initial compartments= 4-5 ;

3. Specify a default word.

   Assign an initial compartment bit to the word.

   name= DIVISION ONLY; sname= DO; minclass= IUO; compartments= 4-5; name= WEBC AMERICA; sname= WEBCA; minclass= IUO; compartments= 4; name= WEBC WORLD; sname= WEBCW; minclass= IUO; compartments= 5;

4. Specify an inverse word.

   Inverse words are created by preceding an initial compartment with a tilde (~).

   name= DIVISION ONLY; sname= DO; minclass= IUO; compartments= 4-5; name= WEBC AMERICA; sname= WEBCA; minclass= IUO; compartments= ~4; name= WEBC WORLD; sname= WEBCW; minclass= IUO; compartments= ~5;

5. Save your changes.

Troubleshooting

For any compartment bits that are not reserved for later assignment, you need to assign a word to the bit in the following sections:

• SENSITIVITY LABELS: WORDS:

• INFORMATION LABELS: WORDS:

• COMPARTMENTS: WORDS:

How to Create a Single-Label Encodings File

Certain labels must always be present in a label_encodings file:

• One sensitivity label in the user accreditation range must be defined

• One clearance in the user accreditation range must be defined

• One information label in the user accreditation range must be defined

Before You Begin

You must be in the Security Administrator role in the global zone.

1. Edit an encodings file.

   Use the Edit Encodings action. For details, see How to Create a label_encodings File. Provide a name that is different from the installed label_encodings file.

2. Create an encodings file with only one classification and only the desired compartments.

   For example, you could set up an encodings file with the INTERNAL_USE_ONLY classification, and specify no words.

   VERSION= Single-Label Encodings . . . CLASSIFICATIONS: name= INTERNAL_USE_ONLY; sname= INTERNAL; value= 5; INFORMATION LABELS: WORDS: SENSITIVITY LABELS: WORDS: CLEARANCES: WORDS: CHANNELS: WORDS: PRINTER BANNERS: WORDS:

3. In the ACCREDITATION RANGE section, include only one classification and one valid compartment combination.

   The following example encodes the INTERNAL classification.

   ACCREDITATION RANGE: classification= INTERNAL; only valid compartment combinations: INTERNAL minimum clearance= INTERNAL; minimum sensitivity label= INTERNAL; minimum protect as classification= INTERNAL;

4. Encode the LOCAL DEFINITIONS section.

   For details, see Chapter 5, Customizing LOCAL DEFINITIONS.

5. Ensure that the file is syntactically correct.

   • If the file does not pass chk_encodings, see How to Debug a label_encodings File

   • Otherwise, continue with How to Analyze and Verify the label_encodings File.

Example 3–8 Defining the Accreditation Range in a Single-Label Encodings File

The following example shows the settings in the ACCREDITATION RANGE: section. A single ANY_CLASS classification is defined. Compartments words A, B, and REL CNTRY 1 are specified for all types of labels.

ACCREDITATION RANGE:

classification= ANY_CLASS;      only valid compartment combinations:

ANY_CLASS A B REL CNTRY1

minimum clearance= ANY_CLASS A B REL CNTRY1;
minimum sensitivity label= ANY_CLASS A B REL CNTRY1;
minimum protect as classification= ANY_CLASS;

Example 3–9 Changing the Single Label Name

In this example, the label_encodings.example file is changed to handle a single-label company. The name= value is changed from SECRET to INTERNAL_USE_ONLY. The sname= value is changed from s to INTERNAL. Neither the value= nor the initial compartments= definition is changed.

CLASSIFICATIONS:
name= INTERNAL_USE_ONLY;  sname= INTERNAL;  value= 5; initial compartments= 4-5
190-239;

In the ACCREDITATION RANGE section, the short name of the classification is replaced. Also, the minimums are replaced with the new sname.

ACCREDITATION RANGE:

classification= INTERNAL;      only valid compartment combinations:

INTERNAL

minimum clearance= INTERNAL;
minimum sensitivity label= INTERNAL;
minimum protect as classification= INTERNAL;

How to Add Sun Extensions to an Encodings File

Before You Begin

You must be in the Security Administrator role in the global zone. You must have an encodings file that does not have a LOCAL DEFINITIONS section.

1. Add the LOCAL DEFINITIONS section to your file.

   Append the section from a Trusted Extensions-supplied label_encodings file. Trusted Extensions-supplied files are in the /etc/security/tsol directory.

2. Customize the extensions for your site.

   For details, see Modifying Sun Extensions (Task Map).

How to Debug a label_encodings File

Before You Begin

You must be in the Security Administrator role in the global zone.

1. Edit the label_encodings file.

   Use the Edit Encodings action. For details, see How to Create a label_encodings File.

2. Check the entries in the INFORMATION LABELS: WORDS: section.

   The entries must exactly match the entries in the SENSITIVITY LABELS: WORDS: section.

   ---

   Tip –

   Encode the sensitivity label words, then copy the words to the INFORMATION LABELS section.

   ---

3. Check that no label in the user accreditation range has a value of 0 with no compartment bits.

   This step ensures that no label is indistinguishable from the label ADMIN_HIGH.

4. Check that no label in the user accreditation range has a value of 255 with all compartment bits from 0 to 239.

   This step ensures that no label is indistinguishable from the label ADMIN_HIGH.

5. Check that no compartment has a value higher than 239.

   This step ensures that all labels can be mapped to CIPSO labels.

6. For labels that cannot be resolved, do the following:

   1. Reset any objects with the new labels to a low system label, ADMIN_LOW.

   2. Restore a known, usable label_encodings file from the backup.

   3. Use the chk_encodings -a command to analyze the label problems in the faulty file.