7
Implementing Policy Options and Labeling Functions

This chapter explains how to customize the enforcement of Oracle Label Security policies, and how to implement labeling functions.

This chapter contains these sections:

Choosing Policy Options

This section introduces the policy options, and discusses their use.

Overview of Policy Enforcement Options

Of all the enforcement controls which Oracle Label Security permits, the administrator must choose those which meet the needs of the given application. These options can operate at three different levels:

Policy level
Schema level
Table level

For each policy, you can specify a set of default enforcement options that will automatically be used whenever the policy is applied to a table. Alternatively, you can explicitly specify enforcement options by schema or by table.

When you apply a policy to a schema or a table, you can customize its enforcement in accordance with your security requirements, and specify whether the label column should be displayed or hidden. You can chose to enforce some or all of the policy options for any protected table.

Optionally, you can assign each table a labeling function and/or a SQL predicate.

The Oracle Label Security policy enforcement options are as follows:

Table 7-1 Policy Enforcement Options

Option	Description
LABEL_DEFAULT	If the user does not explicitly specify a label on INSERT, the session's default row label value is used.
LABEL_UPDATE	Applies policy enforcement to UPDATE operations that set or change the value of a label attached to a row. The WRITEUP, WRITEDOWN, and WRITEACROSS privileges are only enforced if the LABEL_UPDATE option is set.
CHECK_CONTROL	Applies READ_CONTROL policy enforcement to INSERT and UPDATE statements to assure that the new row label is read-accessible.
READ_CONTROL	Applies policy enforcement to all queries; only authorized rows are accessible for SELECT, UPDATE, and DELETE operations.
WRITE_CONTROL	Determines the ability to INSERT, UPDATE, and DELETE data in a row. If this option is set, it enforces INSERT_CONTROL, UPDATE_CONTROL, and DELETE_CONTROL.
INSERT_CONTROL	Applies policy enforcement to INSERT operations, according to the algorithm for write access described in Figure 3-8.
DELETE_CONTROL	Applies policy enforcement to DELETE operations, according to the algorithm for write access described in Figure 3-8.
UPDATE_CONTROL	Applies policy enforcement to UPDATE operations on the data columns within a row, according to the algorithm for write access described in Figure 3-8.
ALL_CONTROL	Applies all enforcement options.
NO_CONTROL	Applies no enforcement options. A labeling function or a SQL predicate can nonetheless be applied.

Remember: although Oracle Label Security may be applied to a table, not all DML operations will necessarily be governed by the policy. Depending on how the administrator has set the policy enforcement options, there will be differences in SQL processing behavior (and what an authorized user can actually see in response to a query on a protected table). Except where noted, this chapter assumes that ALL_CONTROL is set. This means that all enforcement options are in effect. If a user attempts to perform an operation for which he or she is not authorized, an error message is raised and the SQL statement fails.

The HIDE Policy Column Option

HIDE is a configuration option which you can specify when initially applying an Oracle Label Security policy to a table (that is, when adding the policy column to the table). When HIDE is specified, the column which contains the policy's labels is not displayed.

Once the policy has been applied, the hidden (or not hidden) status of the column cannot be changed unless the policy is removed with the DROP_COLUMN parameter set to TRUE. Then the policy can be reapplied with a new hidden status.

For INSERT statements, the values for the hidden label columns are not required for all-column inserts. For SELECT statements, the values of hidden label columns are not automatically returned; they must be explicitly retrieved.

Furthermore, the label column may or may not be displayed when you perform a DESCRIBE on the table, depending on how the administrator has set the HIDE option. With the HIDE option off, the label column is displayed in response to a select.

The Label Management Enforcement Options

This section describes the label enforcement options.

LABEL_DEFAULT: Using the Session's Default Row Label

If set, this option specifies that the user's session default row label should be used on insert as the new row label, if the user does not explicitly specify a value. Note that if a labeling function is in force on the table, it will override the LABEL_DEFAULT option.

LABEL_UPDATE: Changing Data Labels

If this option is not set, any user can change a row's label, within the range of his or her authorizations. If LABEL_UPDATE is set, then the user must have the WRITEUP, WRITEDOWN, and/or WRITEACROSS privilege in order to modify a label.

The LABEL_UPDATE option uses an Oracle after-row trigger. It is only invoked on an update operation which changes the value of the policy label column. Note that any labeling function which is in force on a table will override the LABEL_UPDATE option.

CHECK_CONTROL: Checking Data Labels

After an INSERT or UPDATE, the READ_CONTROL option is enforced on the new label to assure that the user is authorized for read access. In other words, CHECK_CONTROL ensures that the user who modifies a label on a row can still access the row after the operation.

The Access Control Enforcement Options

This section describes the options related to access control:

READ_CONTROL: Reading Data

The READ_CONTROL option uses Oracle virtual private database (VPD) technology to enforce the read access mediation algorithm, as illustrated in Figure 3-7 .

READ_CONTROL determines the set of records accessible to a session for SELECT, UPDATE and DELETE operations. If READ_CONTROL is off, then all rows in the table protected by the policy are accessible to all users.

WRITE_CONTROL: Writing Data

The WRITE_CONTROL option uses Oracle after-row triggers to enforce the write access mediation algorithm, as illustrated in Figure 3-8 . When an Oracle Label Security policy is applied to a table and the WRITE_CONTROL option is selected, triggers are generated and the algorithm is enforced.

Note:

The protection implementation for WRITE_CONTROL is the same for all write operations, but you need not apply all write options across the board. You can apply WRITE_CONTROL separately in INSERT, UPDATE, and DELETE operations using the corresponding policy enforcement option (INSERT_CONTROL, UPDATE_CONTROL, and DELETE_CONTROL).

If WRITE_CONTROL is on but LABEL_UPDATE is not specified, the user can change both data and labels. If you want to control updating the row labels, use the LABEL_UPDATE option in addition to WRITE_CONTROL.

INSERT_CONTROL, UPDATE_CONTROL, and DELETE_CONTROL

These options apply policy enforcement during the corresponding operations on the data columns within a row, according to the algorithm for write access described in Figure 3-8.

The Overriding Enforcement Options

Whereas ALL_CONTROL applies all of the label management and access control enforcement options, NO_CONTROL applies none of them. Labeling functions and SQL predicates can nonetheless be applied. Note that the ALL_CONTROL option can be used on the command line only. Oracle Policy Manager does not provide this as an alternative to selecting individual options.

If you apply a policy with NO_CONTROL specified, a policy label column is added to the table, but the label values are NULL. Since no access controls are operating on the table, you can proceed to enter labels as desired. You can then set the policy enforcement options as you wish.

NO_CONTROL can be a useful option if you have a labeling function in force to label the data correctly--but want to let all users access all the data.

Guidelines for Using the Policy Enforcement Options

You can customize policy enforcement for a schema or table through the Oracle Policy Manager, or by using the SA_POLICY_ADMIN package. This section documents the supported keywords.

Note that you can specify a string of default options for the policy; these are used if no schema or table options are specified.

If a policy is applied to a table, and subsequently applied to the schema containing that table, the options on the table are not affected. The table retains its original options.

In general, administrators will use the LABEL_DEFAULT policy option. This causes the user's row label to be used to label data. Alternatively, a labeling function can be used to label the data. If neither of these two options is used, a label would have to be specified in every INSERT statement.

The following table suggests certain combinations of policy enforcement options which you may find useful when implementing your Oracle Label Security policy. As the table illustrates, you might typically enforce READ_CONTROL and WRITE_CONTROL, and take one or another approach to setting the label.

Table 7-2 Suggested Policy Enforcement Option Combinations

Options	Access Enforcement
READ_CONTROL, WRITE_CONTROL, LABEL_DEFAULT	Read and write access based on session label. Default label provided; users can insert/update both data and labels.
READ_CONTROL, WRITE_CONTROL, Labeling Function	Read and write access based on session label. Users can set/change only row data; all row labels are set explicitly by the labeling function. Add CHECK_CONTROL to restrict new labels (on insert or update) to visible range of labels.
READ_CONTROL, WRITE_CONTROL, LABEL_UPDATE	Read and write access based on session label, but users cannot change labels without privileges. Add CHECK_CONTROL to restrict new labels (on insert or update) to visible range.

Exemptions from Oracle Label Security Policy Enforcement

Oracle Label Security is not enforced during DIRECT path export.

By design, Oracle Label Security policies cannot be applied to objects in schema SYS. As a consequence, the SYS user, and users making a DBA-privileged connection to the database (such as CONNECT AS SYSDBA) do not have Oracle Label Security policies applied to their actions. DBAs need to be able to administer the database. It would make no sense, for example, to export part of a table due to an Oracle Label Security policy being applied. The database user SYS is thus always exempt from Oracle Label Security enforcement, regardless of the export mode, application or utility used to extract data from the database.

Similarly, database users granted the Oracle9i EXEMPT ACCESS POLICY privilege, either directly or through a database role, are completely exempt from Oracle Label Security enforcement--regardless of the export mode, application or utility used to extract data from the database. This is a very powerful privilege and should be carefully managed.

Note that this privilege does not affect the enforcement of standard Oracle9i object privileges such as SELECT, INSERT, UPDATE, and DELETE. These privileges are enforced even if a user has been granted the EXEMPT ACCESS POLICY privilege.

Viewing Policy Options on Tables and Schemas

You can use the following views to see the policy enforcement options which are currently applied to tables and schemas:

DBA_SA_TABLE_POLICIES
DBA_SA_SCHEMA_POLICIES

Using a Labeling Function

Application developers can create labeling functions, programs which contain procedural logic to compute and return a label. The function can use a wide array of resources to compute the label. These include context variables (such as date or username) and data values.

This section describes how to use labeling functions.

Approaches to Data Labeling

There are three ways to label data which is being inserted:

Explicitly specify a label in every INSERT into the table.
Set the LABEL_DEFAULT option, which causes the session's row label to be used if an explicit row label is not included in the INSERT statement.
Create a labeling function which will be invoked upon every INSERT statement, and which operates independently of any user's authorization.

The recommended approach is to write a labeling function to implement your rules for labeling data. If you specify a labeling function, Oracle Label Security embeds a call to that function in INSERT and UPDATE triggers to compute a label.

For example, the following labeling function uses the contents of COL1 and COL2 of the new row to compute and return the appropriate label for the row.

my_label(:new.col1,:new.col2)

If you do not specify a labeling function, then you should use the LABEL_DEFAULT option. Otherwise, you must explicitly specify a label on every INSERT statement.

How Labeling Functions Work

Labeling functions enable you to consider, in your rules for assigning labels, information drawn from the application context. For example, you can use as a labeling consideration the IP address to which the user is attached. There are many opportunities to use SYS_CONTEXT in this way.

Note:

If the SQL is invalid, an error will occur when you apply the labeling function to the table or policy. You should thoroughly test a labeling function before using it with tables.

Labeling functions override the LABEL_DEFAULT and LABEL_UPDATE options.

A labeling function is called in the context of a before-row trigger. This enables you to pass in the old and new values of the data record, as well as the old and new labels.

You can construct a labeling function to permit an explicit label to be passed in by the user.

All labeling functions must have return types of the LBACSYS.LBAC_LABEL datatype. The TO_LBAC_DATA_LABEL function can be used to convert a label in character string format to a datatype of LBACSYS.LBAC_LABEL. Note that LBACSYS must have EXECUTE privilege on your labeling function. The owner of the labeling function must have EXECUTE privilege on the TO_LBAC_DATA_LABEL function, with GRANT option.

Creating a Labeling Function

The following example shows how to create a labeling function.

 SQL> CREATE OR REPLACE FUNCTION sa_demo.gen_emp_label
                (Job varchar2,
                 Deptno number,
                 Total_sal number)
   Return LBACSYS.LBAC_LABEL
     as
       i_label varchar2(80);
     Begin
       /* Determine Class Level */
       if total_sal > 2000 then
        i_label := 'L3:';
       elsif total_sal >1000 then
        i_label := 'L2:';
       else
        i_label := 'L1:';
       end if;
     
       /* Determine Compartment */
       IF Job in ('MANAGER','PRESIDENT') then
        i_label := i_label||'M:';
       else
        i_label := i_label||'E:';
       end if;
       /* Determine Groups */
       i_label := i_label||'D'||to_char(deptno);
      return TO_LBAC_DATA_LABEL('human_resources',i_label);
     End;
     /

Specifying a Labeling Function

The following example shows how to specify a labeling function.

sa_policy_admin.remove_table_policy('human_resources','sa_demo','emp');
sa_policy_admin.apply_table_policy (


POLICY_NAME => 'human_resources',
SCHEMA_NAME => 'sa_demo',
TABLE_NAME  => 'emp',
TABLE_OPTIONS => 'READ_CONTROL,WRITE_CONTROL,CHECK_CONTROL',
LABEL_FUNCTION => 'sa_demo.gen_emp_label(:new.job,:new.deptno,:new.sal)',
PREDICATE => NULL);

Policy Options and Labeling Functions: Inserting Labeled Data

This section explains how enforcement options and labeling functions affect the insertion of labeled data.

Enforcement Control Options and INSERT

When you attempt to insert or update data based on your authorizations, the outcome depends upon the way in which the policy enforcement controls are set.

If INSERT_CONTROL is set, then you can only insert rows labeled within your write authorizations. If you attempt to update data which you can read, but for which you do not have write authorization, an error is raised. For example, if you can read compartments A and B, but you can only write to compartment A, then if you attempt to insert data with compartment B, the statement will fail.
If INSERT_CONTROL is not set, you can insert with any valid label.
If the CHECK_CONTROL option is set, you can only insert rows with labels which you are authorized to read--even if the labels are generated by a labeling function.

Inserting Labels When a Labeling Function is Specified

A labeling function takes precedence over labels entered by the user. If the administrator has set up an automatic labeling function, then no label you enter will have effect (unless the label function enables your label to be considered). New row labels are always determined by the label function.

Note that the security administrator can establish a labeling function which sets the label of a row being inserted to a value outside the range which the user can see. If this is the case, the user can potentially insert a row, but not be authorized to see the row. You can prevent this situation from occurring by using the CHECK_CONTROL option. This option verifies the user's read authorization on the new label; if this option is on, she will not be able to perform such an insert.

Inserting Child Rows into Tables with Declarative Referential Integrity Enabled

Declarative referential integrity can enforce parent-child relationships between tables, if the parent is a protected table. If a child row is in a table which has a referential integrity constraint, then the parent row must be visible (the user must be able to see the parent row) for the insert to succeed. Thus, the user must have read access to the parent row.

If the parent table has READ_CONTROL on, the user's read authorization must be sufficient to authorize a SELECT on the parent row. For example, a user who cannot read department 20, cannot insert child rows for department 20. (Note that all records will be visible if the user has FULL or READ privilege.)

Policy Options and Labeling Functions: Updating Labeled Data

Update behavior in Oracle Label Security is similar to that of insert behavior. There is nothing different, as long as the user is authorized to change the rows in question. This section contains these topics:

Updating Labels Using CHAR_TO_LABEL

If you need to change a row's label from SENSITIVE to CONFIDENTIAL, you can change the label as follows:

UPDATE emp 
SET hr_label = char_to_label ('HR', 'CONFIDENTIAL')
WHERE ename = 'ESTANTON';

Enforcement Control Options and UPDATE

When you attempt to update data based on your authorizations, the outcome depends upon the way in which enforcement controls are set.

If UPDATE_CONTROL is set, then you can only update rows labeled within your write authorizations. If you attempt to update data which you can read, but for which you do not have write authorization, an error is raised. Assume, for example, that you can read compartments A and B, but you can only write to compartment A. In this case, if you attempt to update data with compartment B, the statement will fail.
If UPDATE_CONTROL is not set, you can update all rows to which you have read access.
If LABEL_UPDATE is set, you must have the appropriate privilege (WRITEUP, WRITEDOWN, or WRITEACROSS) in order to update a label.
If the CHECK_CONTROL option is set, you can only specify labels which you are authorized to read.
If LABEL_UPDATE is not set but UPDATE_CONTROL is set, then you can update a label to any new label value within your write authorization.

The following figure illustrates the label evaluation process for LABEL_UPDATE.

Figure 7-1 Label Evaluation Process for LABEL_UPDATE

Text description of olsag031.gif follows

Text description of the illustration olsag031.gif

Updating Labels When a Labeling Function Is Specified

A labeling function takes precedence over labels entered by the user. If the administrator has set up an automatic labeling function, then no label you enter will have effect (unless the label function permits your label to be considered). New row labels are always determined by the label function.

Note that the security administrator can establish a labeling function which sets the label of a row being updated to a value outside the range which you can see. If this is the case, you can update a row, but not be authorized to see the row. If the CHECK_CONTROL option is on, you will not be able to perform such an update. CHECK_CONTROL verifies your read authorization on the new label.

Updating Child Rows in Tables with Declarative Referential Integrity Enabled

If a child row is in a table which has a referential integrity constraint, then the parent row must be visible (the user must be able to see the parent row) for the update to succeed. If the parent table has READ_CONTROL on, the user's read authorization must be sufficient to authorize a SELECT on the parent row.

For example, a user who cannot read department 20 in a parent table, cannot update an employee's department to department 20 in a child table. (If the user has FULL or READ privilege, then all records will be visible.)

Policy Options and Labeling Functions: Deleting Labeled Data

This section covers the deletion of labeled data.

If the DELETE_CONTROL option is set, you can only delete rows within your write authorization.
If the DELETE_CONTROL is not set, then you can only delete rows which you can read.
With DELETE_CONTROL set, and declarative referential integrity defined with cascading deletes, then you must have write authorization on all the rows to be deleted, or the statement will fail.

You cannot delete a parent row if there are any child rows attached to it, regardless of your write authorization. To delete such a parent row, you must first delete each of the child rows. If DELETE_CONTROL is set on any of the child rows, then you must have write authorization to delete the child rows.

Consider, for example, a situation in which the user is UNCLASSIFIED and there are three rows as follows:

Row	Table	Sensitivity
Parent row:	DEPT	UNCLASSIFIED
Child row:	EMP	UNCLASSIFIED
Child row:	EMP	UNCLASSIFIED

In this case, the UNCLASSIFIED user cannot delete the parent row.

DELETE_CONTROL has no effect when DELETE_RESTRICT is set. DELETE_RESTRICT is always enforced. In some cases (depending on the user's authorizations and the data's labels) it may look as though a row has no child rows, when it actually does have children but the user cannot see them. Even if a user cannot see child rows, he still cannot delete the parent row.

See Also: Oracle9i Application Developer's Guide - Fundamentals:

Using a SQL Predicate with an Oracle Label Security Policy

You can use a SQL predicate to provide extensibility for selective enforcement of data access rules.

This section contains these topics:

SQL Predicates Used with an Oracle Label Security Policy

A SQL predicate is a condition, with an optional preceding AND or OR. It can be appended for READ_CONTROL access mediation. The following predicate, for example, adds an application-specific test based on COL1 to determine if the session has access to the row.

AND my_function(col1)=1

The combined result of the policy and the user-specified predicate affects the labels which a user can read. It therefore affects the labels and data which CHECK_CONTROL will permit a user to change. An OR clause, for example, increases the number of rows a user can read.

A SQL predicate can be useful if you want to avoid performing label-based filtering. In certain situations, a SQL predicate can easily implement row level security on tables. Used instead of READ_CONTROL, a SQL predicate will filter the data for SELECT, UPDATE, and DELETE operations.

Similarly, in a typical, Web-enabled human resources application, a user might have to be a manager to access rows in the employee table. (That is, her user label would have to dominate the label on the employee's row). A SQL predicate like the following could be added, such that an employee could bypass label-based filtering if he wanted to view his own record in the employee table. (An "OR" is used so that either the label policy will apply, or this statement will apply.)

OR SYS_CONTEXT ('USERENV', 'SESSION_USER') = employee_name

This predicate enables you to have additional access controls so that each employee can access his or her own record.

You can use such a predicate in conjunction with READ_CONTROL, or as a standalone predicate even if READ_CONTROL is not implemented.

Note:

Verify that the predicate accomplishes your security goals before you implement it in an application.

If a syntax error occurs in a predicate under Oracle Label Security, an error will not arise when you try to apply the policy to a table. Rather, a predicate error message will arise when you first attempt to reference the table.

Effect of Multiple SQL Predicates Under Oracle Label Security

A predicate applied to a table by means of an Oracle Label Security policy is appended to any other predicates which may be applied by other Oracle Label Security policies, or by Oracle fine grain access control/VPD policies. The predicates are ANDed together.

Consider the following predicates applied to the EMP table in the SCOTT schema:

A predicate generated by an Oracle VPD policy, such as deptno=10
A label-based predicate generated by an Oracle Label Security policy, such as label=100, with a user-specified predicate such as
```
OR SYS_CONTEXT ('USERENV', 'SESSION_USER') = ename
```

Correct: These predicates would be ANDed together as follows:

WHERE deptno=10 AND (label=100 OR SYS_CONTEXT ('USERENV', 'SESSION_USER') = 
ename)

Incorrect: The predicates would not be combined in the following way:

WHERE deptno=10 AND label=100 OR SYS_CONTEXT ('USERENV', 'SESSION_USER') = ename

7 Implementing Policy Options and Labeling Functions

Choosing Policy Options

Overview of Policy Enforcement Options

Table 7-1 Policy Enforcement Options

The HIDE Policy Column Option

The Label Management Enforcement Options

LABEL_DEFAULT: Using the Session's Default Row Label

LABEL_UPDATE: Changing Data Labels

CHECK_CONTROL: Checking Data Labels

The Access Control Enforcement Options

READ_CONTROL: Reading Data

WRITE_CONTROL: Writing Data

INSERT_CONTROL, UPDATE_CONTROL, and DELETE_CONTROL

The Overriding Enforcement Options

Guidelines for Using the Policy Enforcement Options

Table 7-2 Suggested Policy Enforcement Option Combinations

Exemptions from Oracle Label Security Policy Enforcement

Viewing Policy Options on Tables and Schemas

Using a Labeling Function

Approaches to Data Labeling

How Labeling Functions Work

Creating a Labeling Function

Specifying a Labeling Function

Policy Options and Labeling Functions: Inserting Labeled Data

Enforcement Control Options and INSERT

Inserting Labels When a Labeling Function is Specified

Inserting Child Rows into Tables with Declarative Referential Integrity Enabled

Policy Options and Labeling Functions: Updating Labeled Data

Updating Labels Using CHAR_TO_LABEL

Enforcement Control Options and UPDATE

Figure 7-1 Label Evaluation Process for LABEL_UPDATE

Updating Labels When a Labeling Function Is Specified

Updating Child Rows in Tables with Declarative Referential Integrity Enabled

Policy Options and Labeling Functions: Deleting Labeled Data

Using a SQL Predicate with an Oracle Label Security Policy

SQL Predicates Used with an Oracle Label Security Policy

Effect of Multiple SQL Predicates Under Oracle Label Security

7
Implementing Policy Options and Labeling Functions