5 Working with Labeled Data

5.1.1 The Policy Label Column

Each policy that is applied to a table creates a column in the database. By default, the data type of the policy label column is NUMBER.

Each row's label for that policy is represented by a tag in that column, using the numeric equivalent of the character-string label value. The label tag is automatically generated when the label is created, unless the administrator specifies the tag manually at that time.

The automatic label generation follows the rules established by the administrator while defining the label components, as described in Chapter 2, "Understanding Data Labels and User Labels".

SQL> describe emp;
 Name                                      Null?    Type
 ----------------------------------------- -------- --------
 EMPNO                                     NOT NULL NUMBER(4)
 ENAME                                              CHAR(10)
 JOB                                                CHAR(9)
 MGR                                                NUMBER(4)
 SAL                                                NUMBER(7,2)
 DEPTNO                                    NOT NULL NUMBER(2)
 HR_LABEL                                           NUMBER(10)

SQL> describe emp;
 Name                                      Null?    Type
 ----------------------------------------- -------- --------
 EMPNO                                     NOT NULL NUMBER(4)
 ENAME                                              CHAR(10)
 JOB                                                CHAR(9)
 MGR                                                NUMBER(4)
 SAL                                                NUMBER(7,2)
 DEPTNO                                    NOT NULL NUMBER(2)

5.1.2 Label Tags

As noted in Chapter 2, "Understanding Data Labels and User Labels", the administrator first defines a set of label components to be used in a policy. When creating labels, the administrator specifies the set of valid combinations of components that can make up a label, that is, a level optionally combined with one or more groups or compartments. Each such valid label within a policy is uniquely identified by an associated numeric tag assigned by the administrator or generated automatically upon its first use. Manual definition has the advantage of allowing the administrator to control the ordering of label values when they are sorted or logically compared.

However, label tags must be unique across all policies in the database. When you use multiple policies in a database, you cannot use the same numeric label tag in different policies. Remember that each label tag uniquely identifies one label, and that numeric tag is what is stored in the data rows, not the label's character-string representation.

This section contains these topics:

• Manually Defining Label Tags to Order Labels

• Manually Defining Label Tags to Manipulate Data

• Automatically Generated Label Tags

SELECT * FROM tab1
  WHERE hr_label = 210;

5.3.1 Converting a Character String to a Label Tag, with CHAR_TO_LABEL

Use the CHAR_TO_LABEL function to convert a character string to a label tag. This function returns the label tag for the specified character string.

Syntax:

FUNCTION CHAR_TO_LABEL (
     policy_name     IN VARCHAR2,
     label_string    IN VARCHAR2)
RETURN NUMBER; 

Example:

INSERT INTO emp (empno,hr_label) 
VALUES (999, CHAR_TO_LABEL('HR','S:A,B:G5');

Here, HR is the label policy name, S is a sensitivity level, A,B compartments, and G5 a group.

5.3.2 Converting a Label Tag to a Character String, with LABEL_TO_CHAR

When you query a table or view, you automatically retrieve all of the rows in the table or view that satisfy the qualifications of the query and are dominated by your label. If the policy label column is not hidden, then the label tag value for each row is displayed. You must use the LABEL_TO_CHAR function to display the character string value of each label.

Note that all conversions must be explicit. There is no automatic casting to and from tag and character string representations.

Syntax:

FUNCTION LABEL_TO_CHAR (
     label                 IN NUMBER)
RETURN VARCHAR2; 

SELECT label_to_char (hr_label) AS label, ename FROM tab1;
  WHERE ename = 'RWRIGHT';

LABEL          ENAME
------------   ----------
S:A,B:G1       RWRIGHT

SELECT label_to_char (hr_label) AS label,ename FROM emp
  WHERE hr_label = char_to_label ('HR', 'S:A,B:G1');

LABEL           ENAME
-------------   ---------
S:A,B:G1        RWRIGHT
S:A,B:G1        ESTANTON 

SELECT label_to_char (hr_label) AS label,ename FROM emp
  WHERE label_to_char (hr_label) like '%S:A,B:G1%';

SQL> select empno, hr_label from emp
     where ename='RWRIGHT';

EMPNO      HR_LABEL
---------- ----------
7839       1000000562

SQL> column label format a10
SQL> select label_to_char (hr_label) as label, dept.*
  2  from dept;

5.4.1 Using Numeric Label Tags in WHERE Clauses

This section describes techniques of using numeric label tags in WHERE clauses of SELECT statements.

When using labels in the NUMBER format, the administrator can set up labels so that a list of their label tags distinguishes the different levels. Comparisons of these numeric label tags can be used for ORDER BY processing, and with the logical operators.

For example, if the administrator has assigned all UNCLASSIFIED labels to the 1000 range, all SENSITIVE labels to the 2000 range, and all HIGHLY_SENSITIVE labels to the 3000 range, then you can list all SENSITIVE records by entering:

SELECT * FROM emp
WHERE hr_label BETWEEN 2000 AND 2999;

To list all SENSITIVE and UNCLASSIFIED records, you can enter:

SELECT * FROM emp
WHERE hr_label <3000;

To list all HIGHLY_SENSITIVE records, you can enter:

SELECT * FROM emp
WHERE hr_label=3000;

Alternatively, you can use dominance relationships to set up an ordering strategy.

5.4.2 Ordering Labeled Data Rows

You can perform an ORDER BY referencing the policy label column to order rows by the numeric label tag value that the administrator has set. For example:

SELECT * from emp
ORDER BY hr_label;

Notice that no functions were necessary in this statement. The statement made use of label tags set up by the administrator.

5.4.3 Ordering by Character Representation of Label

Using the LABEL_TO_CHAR function, you can order data rows by the character representation of the label. For example, the following statement returns all rows sorted by the text order of the label:

SELECT * FROM emp
ORDER BY label_to_char (hr_label);

5.4.4 Determining Upper and Lower Bounds of Labels

This section describes the Oracle Label Security functions that determine the least upper bound or the greatest lower bound of two or more labels. Two single-row functions operate on each row returned by a query. They return one result for each row.

• Finding Least Upper Bound with LEAST_UBOUND

• Finding Greatest Lower Bound with GREATEST_LBOUND

  Note:

  In all functions that take multiple labels, the labels must all belong to the same policy.

FUNCTION LEAST_UBOUND (
     label1                    IN NUMBER,
     label2                    IN NUMBER) 
RETURN VARCHAR2; 

SELECT ename,dept.deptno, 
  LEAST_UBOUND(emp.hr_label,dept.hr_label) as label
  FROM emp, dept
  WHERE emp.deptno=dept.deptno;

FUNCTION GREATEST_LBOUND (
     label1                  IN NUMBER,
     label2                  IN NUMBER) 
RETURN VARCHAR2; 

5.4.5 Merging Labels with the MERGE_LABEL Function

The MERGE_LABEL function is a utility for merging two labels together. It accepts the character string form of two labels and the three-character specification of a merge format. Its syntax is as follows:

Syntax:

FUNCTION merge_label (label1 IN number,
                      label2 IN number,
                      merge_format IN VARCHAR2)
RETURN number;

The valid merge format is specified with a three-character string:

<highest level or lowest level><union or intersection of compartments><union or intersection of groups>

• The first character indicates whether to merge using the highest level or the lowest level of the two labels.

• The second character indicates whether to merge using the union or the intersection of the compartments in the two labels.

• The third character indicates whether to merge using the union or the intersection of the groups in the two labels.

The following table defines the MERGE_LABEL format constants.

For example, HUI specifies the highest level of the two labels, union of the compartments, intersection of the groups.

The MERGE_LABEL function is particularly useful to developers if the LEAST_UBOUND function does not provide the intended result. The LEAST_UBOUND function, when used with two labels containing groups, may result in a less sensitive data label than expected. The MERGE_LABEL function enables you to compute an intersection on the groups, instead of the union of groups that is provided by the LEAST_UBOUND function.

For example, if the label of one data record contains the group UNITED_STATES, and the label of another data record contains the group UNITED_KINGDOM, and the LEAST_UBOUND function is used to compute the least upper bound of these two labels, then the resulting label would be accessible to users authorized for either the UNITED_STATES or the UNITED_KINGDOM.

If, by contrast, the MERGE_LABEL function is used with a format clause of HUI, then the resulting label would contain the highest level, the union of the compartments, and no groups. This is because UNITED_STATES and UNITED_KINGDOM do not intersect.

5.5.1 Inserting Labels Using CHAR_TO_LABEL

To insert a row label, you can specify the label character string and then transform it into a label using the CHAR_TO_LABEL function. Using the definition for table emp, the following example shows how to insert data with explicit labels:

INSERT INTO emp (ename,empno,hr_label)
VALUES ('ESTANTON',10,char_to_label ('HR', 'SENSITIVE'));

5.5.2 Inserting Labels Using Numeric Label Tag Values

You can insert data using the numeric label tag value of a label, rather than using the CHAR_TO_LABEL function. For example, if the numeric label tag for SENSITIVE is 3000, it would look like this:

INSERT INTO emp (ename, empno, hr_label)
VALUES ('ESTANTON', 10, 3000);

5.5.3 Inserting Data Without Specifying a Label

If LABEL_DEFAULT is set, or if there is a labeling function applied to the table, then you do not need to specify a label in your INSERT statements. The label will be provided automatically. You can enter the following command:

INSERT INTO emp (ename, empno)
VALUES ('ESTANTON', 10);

The resulting row label is set according to the default value (or by a labeling function).

5.5.4 Inserting Data When the Policy Label Column Is Hidden

If the label column is hidden, then the existence of the column is transparent to the insertion of data. INSERT statements can be written that do not explicitly list the table columns and do not include a value for the label column. The session's row label is used to label the data, or a labeling function is used if one was specified when the policy was applied to the table or schema.

You can insert into a table without explicitly naming the columns, as long as you specify a value for each non-hidden column in the table. The following example shows how to insert a row into the table described in "Example 2: Numeric Column Data Type with Hidden Column":

INSERT INTO emp
VALUES ('196','ESTANTON',Technician,RSTOUT,50000,10);

Its label will be one of the following three possibilities:

• The label you specify

• The label established by the LABEL_DEFAULT option of the policy being applied

• The label created by a labeling function named by the policy being applied

  Note:

  If the policy label column is not hidden, then you must explicitly include a label value (possibly null, indicated by a comma) in the INSERT statement.

5.5.5 Inserting Labels Using TO_DATA_LABEL

If you are generating new labels dynamically as you insert data, then you can use the TO_DATA_LABEL function to guarantee that this produces valid data labels. To do this, you must the have EXECUTE authority on the TO_DATA_LABEL function.

Whereas the CHAR_TO_LABEL function requires that the label already be an existing data label for the transaction to succeed, the TO_DATA_LABEL does not have this requirement. It will automatically create a valid data label.

For example:

INSERT INTO emp (ename, empno, hr_label)
VALUES ('ESTANTON', 10, to_data_label ('HR', 'SENSITIVE'));

5.6.1 SA_SESSION Functions to Change Session and Row Labels

The following functions enable the user to change the session and row labels:

5.6.2 Changing the Session Label with SA_SESSION.SET_LABEL

Use the SET_LABEL procedure to set the label of the current database session.

Syntax:

PROCEDURE SET_LABEL (policy_name IN VARCHAR2,
                     label IN VARCHAR2); 

A user can set the session label to:

• Any level equal to or less than the maximum, and equal to or greater than the minimum level

• Include any compartments in the authorized compartment list

• Include any groups in the authorized group list. (Subgroups of authorized groups are implicitly included in the authorized list.)

Note that if you change the session label, this change may affect the value of the session's row label. The session's row label contains the subset of compartments and groups for which the user has write access. This may or may not be equivalent to the session label. For example, if you use the SA_SESSION.SET_LABEL command to set your current session label to C:A,B:US and you have write access only on the A compartment, then your row label would be set to C:A.

5.6.3 Changing the Row Label with SA_SESSION.SET_ROW_LABEL

Use the SET_ROW_LABEL procedure to set the default row label value for the current database session. The compartments and groups in the label must be a subset of the compartments and groups in the session label to which the user has write access. When the LABEL_DEFAULT option is set, this row label value is used on insert if the user does not explicitly specify the label.

Syntax:

PROCEDURE SET_ROW_LABEL (policy_name IN VARCHAR2,
                         row_label IN VARCHAR2); 

If the SA_SESSION.SET_ROW_LABEL procedure is not used to set the default row label value, then this value is automatically derived from the session label. It contains the level of the session label and the subset of the compartments and groups in the session label for which the user has write authorization.

The row label is automatically reset if the session label changes. For example, if you change your session level from HIGHLY_SENSITIVE to SENSITIVE, then the level component of the row label automatically changes to SENSITIVE.

The user can set the row label independently, but only to include:

• A level that is less than or equal to the level of the session label, and greater than or equal to the user's minimum level

• A subset of the compartments and groups from the session label, for which the user is authorized to have write access

If the user tries to set the row label to an invalid value, then the operation is not permitted and the row label value is unchanged.

5.6.4 Restoring Label Defaults with SA_SESSION.RESTORE_DEFAULT_LABELS

The RESTORE_DEFAULT_LABELS procedure restores the session label and row label to those stored in the data dictionary. This command is useful to reset values after a SA_SESSION.SET_LABEL command has been processed.

Syntax:

PROCEDURE RESTORE_DEFAULT_LABELS (policy_name in VARCHAR2); 

where policy_name provides the name of an existing policy.

5.6.5 Saving Label Defaults with SA_SESSION.SAVE_DEFAULT_LABELS

The SAVE_DEFAULT_LABELS procedure stores the current session label and row label as your initial session label and default row label. It permits you to change your defaults to reflect your current session label and row label. The saved labels will be used as the initial default settings for future sessions.

Syntax:

PROCEDURE SAVE_DEFAULT_LABELS (policy_name in VARCHAR2); 

where policy_name provides the name of an existing policy.

When you log in to a database, your default session label and row label are used to initialize the session label and row label. When the administrator originally authorized your Oracle Label Security labels, he or she also defined your default level, default compartments, and default groups. If you change your session label and row label, and want to save these values as the default labels, you can use the SA_SESSION.SAVE_DEFAULT_LABELS procedure.

This procedure is useful if you have multiple sessions and want to be sure that all additional sessions have the same labels. You can save the current labels as the default, and all future sessions will have these as the initial labels.

Consider a situation in which you connect to the database through Oracle Forms and want to run a report. By saving the current session labels as the default before you call Oracle Reports, you ensure that Oracle Reports will initialize at the same labels as are being used by Oracle Forms.

5.6.6 Viewing Session Attributes with SA_SESSION Functions

You can use SA_SESSION functions to view the policy attributes for a session.

• USER_SA_SESSION View to Return All Security Attributes

• Functions to Return Individual Security Attributes

SQL> select sa_session.label ('human_resources')
  2  from dual;

SA_SESSION.LABEL('HUMAN_RESOURCES')                                                                 
---------------------------------------------
L3:M,E