E Oracle Label Security PL/SQL Packages

The SA_AUDIT_ADMIN.AUDIT procedure enables policy-specific auditing.

Auditing of each policy is independent of the others. The audit records capture Oracle Label Security administrative actions and the use of Oracle Label Security privileges that were used during logons, DML executions, and trusted stored procedure invocations.

Syntax

SA_AUDIT_ADMIN.AUDIT (
     policy_name     IN VARCHAR2,
     users           IN VARCHAR2 DEFAULT NULL,
     audit_option    IN VARCHAR2 DEFAULT NULL,
     audit_type      IN VARCHAR2 DEFAULT NULL,
     success         IN VARCHAR2 DEFAULT NULL);

Parameters

Examples

The following example audits any failed APPLY and REMOVE attempts by the users psmith and rlayton.

BEGIN
 SA_AUDIT_ADMIN.AUDIT(
  policy_name      => 'hr_ols_pol',
  users            => 'jjones, rlayton',
  audit_option     => 'apply, remove',
  audit_type       => 'by access',
  success          => 'not successful');
END;
/

If the you do not specify any audit options, then all options except the privilege-related ones are audited. You must specify the auditing of privileges explicitly. For example, if you enter the following statement, then the default options are set for the hr_ols_pol policy:

EXEC SA_AUDIT_ADMIN.AUDIT ('hr_ols_pol');

When you enable auditing, it will be performed on all users by session, whether their actions are successful or not.

When you set auditing parameters and options, the new values apply only to subsequent sessions, not to the current session.

Consider also a case in which one SA_AUDIT_ADMIN.AUDIT call (with no users specified) enables auditing for APPLY operations for all users, and then a second call enables auditing of REMOVE operations for a specific user. For example:

EXEC SA_AUDIT_ADMIN.AUDIT ('hr_ols_pol', null, 'apply');
EXEC SA_AUDIT_ADMIN.AUDIT ('hr_ols_pol', 'scott', 'remove');

In this case, SCOTT is audited for both APPLY and REMOVE operations.

You can use the SA_AUDIT_ADMIN.AUDIT_LABEL procedure to record policy labels during auditing. It causes the user's session label to be stored in the audit table.

Syntax

SA_AUDIT_ADMIN.AUDIT_LABEL (
     policy_name     IN VARCHAR2);

Parameter

Example

The following example writes output indicating whether the Oracle Label Security labels are being audited for the hr_ols_pol policy.

BEGIN
 SA_AUDIT_ADMIN.AUDIT_LABEL(
  policy_name      => 'hr_ols_pol');
END;
/

The SA_AUDIT_ADMIN.AUDIT_LABEL_ENABLED function shows whether labels are being recorded in audit records for the policy.

Syntax

SA_AUDIT_ADMIN.AUDIT_LABEL_ENABLED ( 
  policy_name IN VARCHAR2)
RETURN BOOLEAN;

Parameters

Example

The following example writes output indicating whether the Oracle Label Security labels are being audited for the hr_ols_pol policy.

SET SERVEROUTPUT ON
BEGIN 
 IF SA_AUDIT_ADMIN.AUDIT_LABEL_ENABLED('hr_ols_pol')  
  THEN DBMS_OUTPUT.PUT_LINE('OLS hr_ols_pol labels are being audited.');
 ELSE 
  DBMS_OUTPUT.PUT_LINE('OLS hr_ols_pol labels not being audited.'); 
 END IF; 
END;
/

Syntax

SA_AUDIT_ADMIN.CREATE_VIEW (
     policy_name     IN VARCHAR2,
     view_name       IN VARCHAR2    DEFAULT NULL);

Parameters

Examples

The following example creates a view called hr_ols_pol_view for the hr_ols_pol policy.

BEGIN
 SA_AUDIT_ADMIN.CREATE_VIEW(
  policy_name      => 'hr_ols_pol',
  view_name        => 'hr_ols_pol_view');
END;
/

The SA_AUDIT_ADMIN.DROP_VIEW procedure drops the audit trail view for the specified policy.

Syntax

SA_AUDIT_ADMIN.DROP_VIEW (
     policy_name     IN VARCHAR2,
     view_name       IN VARCHAR2    DEFAULT NULL);

Parameters

Example

The following example drops the view called hr_ols_pol_view from the hr_ols_pol policy.

BEGIN
 SA_AUDIT_ADMIN.DROP_VIEW(
  policy_name      => 'hr_ols_pol',
  view_name        => 'hr_ols_pol_view');
END;
/

The SA_AUDIT_ADMIN.NOAUDIT procedure disables Oracle Label Security policy-specific auditing.

Syntax

SA_AUDIT_ADMIN.NOAUDIT (
     policy_name     IN VARCHAR2,
     users           IN VARCHAR2 DEFAULT NULL,
     audit_option    IN VARCHAR2 DEFAULT NULL);

Parameters

Examples

The following example disables auditing for failed APPLY and REMOVE attempts by the users psmith and rlayton.

BEGIN
 SA_AUDIT_ADMIN.NOAUDIT(
  policy_name      => 'hr_ols_pol',
  users            => 'jjones',
  audit_option     => 'apply, remove');
END;
/

You can disable auditing for all enabled options, or only for a subset of enabled options. All auditing for the specified options is disabled for all specified users (or all users, if the users parameter is NULL). For example, the following statement disables auditing of the APPLY and REMOVE operations for users John, Mary, and Scott:

EXEC SA_AUDIT_ADMIN.NOAUDIT ('HR', 'JOHN, MARY, SCOTT', 'APPLY, REMOVE');

Consider also a case in which one AUDIT call enables auditing for a specific user, and a second call (with no user specified) enables auditing for all users. For example:

EXEC SA_AUDIT_ADMIN.AUDIT ('HR', 'SCOTT');
EXEC SA_AUDIT_ADMIN.AUDIT ('HR');

In this case, a subsequent call to NOAUDIT with no users specified (such as the following statement) does not reverse the auditing that was set for SCOTT explicitly in the first call. So, auditing continues to be performed on SCOTT.

EXEC SA_AUDIT_ADMIN.NOAUDIT ('HR');

In this way, even if SA_AUDIT_ADMIN.NOAUDIT is set for all users, Oracle Label Security still audits any users for whom auditing was explicitly set.

Auditing of privileged operations must be specified explicitly. If you run SA_AUDIT_ADMIN.NOAUDIT with no options, the Oracle Label Security will nonetheless continue to audit privileged operations. For example, if auditing is enabled and you enter

EXEC SA_AUDIT_ADMIN.NOAUDIT ('HR');

then auditing will continue to be performed on the privileged operations (such as WRITEDOWN).

SA_AUDIT_ADMIN.NOAUDIT parameters and options that you set apply only to subsequent sessions, not to current sessions.

If you try to enable an audit option that has already been set, or if you try to disable an audit option that has not been set, then Oracle Label Security processes the statement without indicating an error. An attempt to specify an invalid option results in an error message. You can find the status of audit options by querying the ALL_SA_AUDIT_OPTIONS data dictionary view.

The SA_AUDIT_ADMIN.NOAUDIT_LABEL procedure disables the auditing of policy labels.

Syntax

SA_AUDIT_ADMIN.NOAUDIT_LABEL (
   policy_name     IN VARCHAR2);

Parameters

Example

The following example disables auditing for the hr_ols_pol policy.

BEGIN
 SA_AUDIT_ADMIN.NOAUDIT_LABEL(
  policy_name      => 'hr_ols_pol');
END;
/

The SA_COMPONENTS.ALTER_COMPARTMENT procedure changes the short name and long name associated with a compartment.

Once set, the comp_num parameter cannot be changed. If the comp_num parameter is used in any existing label, then its short name cannot be changed but its long name can be changed.

Syntax

SA_COMPONENTS.ALTER_COMPARTMENT (
   policy_name       IN VARCHAR2,
   comp_num          IN NUMBER(38),
   new_short_name    IN VARCHAR2,
   new_long_name     IN VARCHAR2);

SA_COMPONENTS.ALTER_COMPARTMENT (
   policy_name       IN VARCHAR2,
   short_name        IN VARCHAR2 DEFAULT NULL,
   new_long_name     IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example modifies the hr_ols_pol policy.

BEGIN
  SA_COMPONENTS.ALTER_COMPARTMENT (
   policy_name         => 'hr_ols_pol',
   comp_num            => '48',
   new_short_name      => 'FIN',
   new_long_name       => 'FINANCE');
END;
/

The SA_COMPONENTS.ALTER_GROUP procedure changes the short name and long name associated with a group.

Once set, the group_num parameter cannot be changed. If the group is used in any existing label, then its short name cannot be changed, but its long name can be changed.

Syntax

SA_COMPONENTS.ALTER_GROUP (
   policy_name    IN VARCHAR2,
   group_num      IN NUMBER(38),
   new_short_name IN VARCHAR2 DEFAULT NULL,
   new_long_name  IN VARCHAR2 DEFAULT NULL);

SA_COMPONENTS.ALTER_GROUP (
   policy_name    IN VARCHAR2,
   short_name     IN VARCHAR2,
   new_long_name  IN VARCHAR2);

Parameters

Example

The following example modifies the long_name setting for the hr_ols_pol policy.

BEGIN
  SA_COMPONENTS.ALTER_GROUP (
   policy_name     => 'hr_ols_pol',
   short_name      => 'ER_FIN',
   new_long_name   => 'ER_FINANCES');
END;
/

The SA_COMPONENTS.ALTER_GROUP_PARENT procedure changes the parent group associated with a particular group.

Syntax

SA_COMPONENTS.ALTER_GROUP_PARENT (
   policy_name     IN VARCHAR2,
   group_num       IN NUMBER(38),
   new_parent_num  IN NUMBER(38));

SA_COMPONENTS.ALTER_GROUP_PARENT (
   policy_name     IN VARCHAR2,
   group_num       IN NUMBER(38),
   new_parent_name IN VARCHAR2);

SA_COMPONENTS.ALTER_GROUP_PARENT (
   policy_name     IN VARCHAR2,
   short_name      IN VARCHAR2,
   new_parent_name IN VARCHAR2);

Parameters

Example

The following example modifies the parent name for the hr_ols_pol policy.

BEGIN
  SA_COMPONENTS.ALTER_GROUP_PARENT (
   policy_name         => 'hr_ols_pol',
   group_num           => 2100,
   new_parent_name     => 'ER');
END;
/

The SA_COMPONENTS.ALTER_LEVEL procedure changes the short name and long name associated with a level.

Once they are defined, level numbers cannot be changed. If a level is used in any existing label, then its short name cannot be changed, but its long name can be changed.

Syntax

SA_COMPONENTS.ALTER_LEVEL (
   policy_name     IN VARCHAR2,
   level_num       IN NUMBER(38),
   new_short_name  IN VARCHAR2 DEFAULT NULL,
   new_long_name   IN VARCHAR2 DEFAULT NULL);

SA_COMPONENTS.ALTER_LEVEL (
   policy_name     IN VARCHAR2,
   short_name      IN VARCHAR2,
   new_long_name   IN VARCHAR2);

Parameters

Example

The following example modifies the short and long names for the hr_ols_pol policy level.

BEGIN
 SA_COMPONENTS.ALTER_LEVEL (
   policy_name     => 'hr_ols_pol',
   level_num       => 40,
   new_short_name  => 'TS',
   new_long_name   => 'TOP_SECRET');
END;
/

The SA_COMPONENTS.CREATE_COMPARTMENT procedure creates a compartment and specify its short name and long name. The comp_num parameter determines the order in which compartments are listed in the character string representation of labels.

Syntax

SA_COMPONENTS.CREATE_COMPARTMENT (
   policy_name IN VARCHAR2,
   comp_num    IN NUMBER(38),
   short_name  IN VARCHAR2,
   long_name   IN VARCHAR2);

Parameters

Example

The following example creates a compartment for the hr_ols_pol policy.

BEGIN
  SA_COMPONENTS.CREATE_COMPARTMENT (
   policy_name     => 'hr_ols_pol',
   comp_num        => '48',
   short_name      => 'FIN',
   long_name       => 'FINANCE');
END;
/

The SA_COMPONENTS.CREATE_GROUP procedure creates a group and specify its short name and long name, and optionally a parent group.

Syntax

SA_COMPONENTS.CREATE_GROUP (
   policy_name IN VARCHAR2,
   group_num   IN NUMBER(38),
   short_name  IN VARCHAR2,
   long_name   IN VARCHAR2,
   parent_name IN VARCHAR2 DEFAULT NULL);

Parameters

Note that the group number affects the order in which groups will be displayed when labels are selected.

Examples

In the following examples, the first creates a parent group, ER, and the second creates a second group that is part of the parent group.

BEGIN
  SA_COMPONENTS.CREATE_GROUP (
   policy_name     => 'hr_ols_pol',
   group_num       => 2000,
   short_name      => 'ER',
   long_name       => 'EAST_REGION');
END;
/
 
BEGIN
  SA_COMPONENTS.CREATE_GROUP (
   policy_name     => 'hr_ols_pol',
   group_num       => 2100,
   short_name      => 'ER_FIN',
   long_name       => 'ER_FINANCES',
   parent_name     => 'ER');
END;
/

The SA_COMPONENTS.CREATE_LEVEL procedure creates a level and specify its short name and long name. The numeric values assigned to the level_num parameter determine the sensitivity ranking (that is, a lower number indicates less sensitive data).

Syntax

SA_COMPONENTS.CREATE_LEVEL (
   policy_name       IN VARCHAR2,
   level_num         IN NUMBER(38),
   short_name        IN VARCHAR2,
   long_name         IN VARCHAR2);

Parameters

Example

The following example creates a level for the hr_ols_pol policy.

BEGIN
 SA_COMPONENTS.CREATE_LEVEL (
   policy_name   => 'hr_ols_pol',
   level_num     => 40,
   short_name    => 'HS',
   long_name     => 'HIGHLY_SENSITIVE');
END;
/

The SA_COMPONENTS.DROP_COMPARTMENT procedure removes a compartment. If the compartment is used in any existing label, then it cannot be dropped. You can find all existing labels by querying the LABEL column of the ALL_SA_DATA_LABELS data dictionary view.

Syntax

SA_COMPONENTS.DROP_COMPARTMENT (
   policy_name IN VARCHAR2,
   comp_num    IN INTEGER);

SA_COMPONENTS.DROP_COMPARTMENT (
   policy_name IN VARCHAR2,
   short_name  IN VARCHAR2);

Parameters

Example

The following example removes the FIN compartment from the hr_ols_pol policy.

BEGIN
  SA_COMPONENTS.DROP_COMPARTMENT (
   policy_name     => 'hr_ols_pol',
   short_name      => 'FIN');
END;
/

The SA_COMPONENTS.DROP_GROUP procedure removes a group. If the group is used in an existing label, it cannot be dropped.

Syntax

SA_COMPONENTS.DROP_GROUP (
   policy_name IN VARCHAR2,
   group_num   IN NUMBER(38));

SA_COMPONENTS.DROP_GROUP (
   policy_name IN VARCHAR2,
   short_name  IN VARCHAR2);

Parameters

Example

The following example removes a group based on the group number for the hr_ols_pol policy.

BEGIN
  SA_COMPONENTS.DROP_GROUP (
   policy_name     => 'hr_ols_pol',
   group_num       => 2000);
END;
/

The SA_COMPONENTS.DROP_LEVEL procedure removes a level. If the level is used in any existing label, then it cannot be dropped.

Syntax

SA_COMPONENTS.DROP_LEVEL (
   policy_name IN VARCHAR2,
   level_num   IN NUMBER(38));

SA_COMPONENTS.DROP_LEVEL (
   policy_name IN VARCHAR2,
   short_name  IN VARCHAR2);

Parameters

Example

The following example drops the level 40 from the hr_ols_pol policy.

BEGIN
 SA_COMPONENTS.DROP_LEVEL (
   policy_name     => 'hr_ols_pol',
   level_num       => 40);
END;
/

The SA_LABEL_ADMIN.ALTER_LABEL procedure changes the character string label definition associated with a label tag. Note that the label tag itself cannot be changed.

If you change the character string associated with a label tag, then the sensitivity of the data in the rows changes accordingly. For example, if the label character string TS:A with an associated label tag value of 4001 is changed to the label TS:B, then access to the data changes accordingly. This is true even when the label tag value (4001) has not changed. In this way, you can change the data's sensitivity without the need to update all the rows.

Ensure that when you specify a label to alter, you can refer to it either by its label tag or by its character string value.

Syntax

SA_LABEL_ADMIN.ALTER_LABEL (
   policy_name       IN VARCHAR2,
   label_tag         IN BINARY_INTEGER,
   new_label_value   IN VARCHAR2 DEFAULT NULL,
   new_data_label    IN BOOLEAN  DEFAULT NULL);

SA_LABEL_ADMIN.ALTER_LABEL (
   policy_name       IN VARCHAR2,
   label_value       IN VARCHAR2,
   new_label_value   IN VARCHAR2 DEFAULT NULL,
   new_data_label    IN BOOLEAN  DEFAULT NULL);

Parameters

Example

The following example modifies the label_tag and label_value settings of hr_ols_pol policy.

BEGIN
  SA_LABEL_ADMIN.ALTER_LABEL (
   policy_name       => 'hr_ols_pol',
   label_tag         => 1111,
   new_label_value   => 'HS',
   new_data_label    => TRUE);
END;
/

The SA_LABEL_ADMIN.CREATE_LABEL procedure creates data labels.

Syntax

SA_LABEL_ADMIN.CREATE_LABEL (
   policy_name IN VARCHAR2,
   label_tag   IN BINARY_INTEGER,
   label_value IN VARCHAR2,
   data_label  IN BOOLEAN DEFAULT TRUE);

Parameters

When you identify valid labels, you specify which of all the possible combinations of levels, compartments, and groups can potentially be used to label data in tables.

Example

The following example creates a label for the hr_ols_pol policy.

BEGIN
  SA_LABEL_ADMIN.CREATE_LABEL (
   policy_name     => 'hr_ols_pol',
   label_tag       => 1111,
   label_value     => 'HS:FIN',
   data_label      => TRUE);
END;
/

The SA_LABEL_ADMIN.DROP_LABEL procedure deletes a specified policy label. Any subsequent reference to the label (in data rows, or in user or program unit labels) will raise an invalid label error.

Use this procedure only while setting up labels, prior to data population. If you should inadvertently drop a label that is being used, you can recover it by disabling the policy, fixing the problem, and then re-enabling the policy.

Syntax

SA_LABEL_ADMIN.DROP_LABEL (
   policy_name       IN VARCHAR2,
   label_tag         IN BINARY_INTEGER);

SA_LABEL_ADMIN.DROP_LABEL (
   policy_name       IN VARCHAR2,
   label_value       IN VARCHAR2);

Parameters

Example

The following example drops the hr_ols_pol policy label based on its label_tag setting.

BEGIN
  SA_LABEL_ADMIN.DROP_LABEL (
   policy_name     => 'hr_ols_pol',
   label_tag       => 1111);
END;
/

The SA_POLICY_ADMIN.ALTER_SCHEMA_POLICY procedure changes the default enforcement options for the policy.

Any new tables created in the schema will automatically have the new enforcement options applied. The existing tables in the schema are not affected.

To change enforcement options on a table (rather than a schema), you must first drop the policy from the table, make the change, and then reapply the policy.

If you alter the enforcement options on a schema, then this will take effect the next time a table is created in the schema. As a result, different tables within a schema may have different policy enforcement options in force.

Syntax

SA_POLICY_ADMIN.ALTER_SCHEMA_POLICY (
  policy_name         IN VARCHAR2,
  schema_name         IN VARCHAR2,
  default_options     IN VARCHAR2);

Parameters

Example

The following example adds the UPDATE_CONTROL default option to the HR schema.

BEGIN 
 SA_POLICY_ADMIN.ALTER_SCHEMA_POLICY(
  policy_name      => 'hr_ols_pol',
  schema_name      => 'HR',
  default_options  => 'read_control, write_control, update_control');
END;
/

The SA_POLICY_ADMIN.APPLY_SCHEMA_POLICY procedure applies the specified policy to all of the existing tables in a schema (that is, to those which do not already have the policy applied) and enables the policy for these tables.

Then, whenever a new table is created in the schema, the policy is automatically applied to that table, using the schema's default options. No changes are made to existing tables in the schema that already have the policy applied.

Syntax

SA_POLICY_ADMIN.APPLY_SCHEMA_POLICY (
  policy_name        IN VARCHAR2,
  schema_name        IN VARCHAR2,
  default_options    IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example applies the READ_CONTROL and WRITE_CONTROL options to the HR schema.

BEGIN 
 SA_POLICY_ADMIN.APPLY_SCHEMA_POLICY(
  policy_name      => 'hr_ols_pol',
  schema_name      => 'HR',
  default_options  => 'read_control, write_control');
END;
/

The SA_POLICY_ADMIN.APPLY_TABLE_POLICY procedure adds the specified policy to a table.

A policy label column is added to the table if it does not exist, and is set to NULL. When a policy is applied, it is automatically enabled. To change the table options, labeling function, or predicate, you must first remove the policy, and then reapply it.

Syntax

SA_POLICY_ADMIN.APPLY_TABLE_POLICY (
  policy_name       IN VARCHAR2,
  schema_name       IN VARCHAR2,
  table_name        IN VARCHAR2,
  table_options     IN VARCHAR2 DEFAULT NULL,
  label_function    IN VARCHAR2 DEFAULT NULL,
  predicate         IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following statement applies the hr_ols_pol policy to the EMPLOYEES table in the HR schema.

BEGIN
 SA_POLICY_ADMIN.APPLY_TABLE_POLICY(
  policy_name    => 'hr_ols_pol',
  schema_name    => 'HR',
  table_name     => 'EMPLOYEES',
  table_options  => NULL,
  label_function => 'hs(:new.dept,:new.status)',
  predicate      => 'no_control');
END;
/

The SA_POLICY_ADMIN.DISABLE_SCHEMA_POLICY procedure disables the enforcement of the policy for all of the tables in the specified schema, without changing the enforcement options, labeling function, or predicate values.

This procedure removes the row level security predicate and DML triggers from all the tables in the schema.

Syntax

SA_POLICY_ADMIN.DISABLE_SCHEMA_POLICY (
  policy_name    IN VARCHAR2,
  schema_name    IN VARCHAR2);

Parameters

Example

The following example disables the hr_ols_pol policy for the HR schema.

BEGIN
 SA_POLICY_ADMIN.DISABLE_SCHEMA_POLICY(
  policy_name      => 'hr_ols_pol',
  schema_name      => 'HR');
END;
/

The SA_POLICY_ADMIN.DISABLE_TABLE_POLICY procedure disables the enforcement of the policy for the specified table without changing the enforcement options, labeling function, or predicate values.

This procedure removes the row level security predicate and DML triggers from the table.

Syntax

SA_POLICY_ADMIN.DISABLE_TABLE_POLICY (
  policy_name      IN VARCHAR2,
  schema_name      IN VARCHAR2,
  table_name       IN VARCHAR2);

Parameters

Example

The following statement disables the hr_ols_pos policy on the EMPLOYEES table in the HR schema:

BEGIN
 SA_POLICY_ADMIN.DISABLE_TABLE_POLICY(
  policy_name   => 'hr_ols_pol',
  schema_name   => 'HR',
  table_name    => 'EMPLOYEES');
END;
/

The SA_POLICY_ADMIN.ENABLE_SCHEMA_POLICY procedure reenables the current enforcement options, labeling function, and predicate for the tables in the specified schema by re-applying the row level security predicate and DML triggers. The result is similar to enabling a policy for a table, but it covers all the tables in the schema.

Syntax

SA_POLICY_ADMIN.ENABLE_SCHEMA_POLICY (
  policy_name    IN VARCHAR2,
  schema_name    IN VARCHAR2);

Parameters

Example

The following example enables the hr_ols_pol policy for the HR schema.

BEGIN
 SA_POLICY_ADMIN.ENABLE_SCHEMA_POLICY(
  policy_name      => 'hr_ols_pol',
  schema_name      => 'HR');
END;
/

The SA_POLICY_ADMIN.ENABLE_TABLE_POLICY procedure reenables the current enforcement options, labeling function, and predicate for the specified table by reapplying the row level security predicate and DML triggers.

Syntax

SA_POLICY_ADMIN.ENABLE_TABLE_POLICY (
  policy_name     IN VARCHAR2,
  schema_name     IN VARCHAR2,
  table_name      IN VARCHAR2);

Parameters

Example

The following statement reenables the hr_ols_pol policy on the EMPLOYEES table in the HR schema:

BEGIN 
 SA_POLICY_ADMIN.ENABLE_TABLE_POLICY(
  policy_name   => 'hr_ols_pol',
  schema_name   => 'HR',
  table_name    => 'EMPLOYEES');
END;
/

In an Oracle Internet Directory-enabled Oracle Label Security configuration, the SA_POLICY_ADMIN.POLICY_SUBSCRIBE procedure subscribes to the policy for usage in SA_POLICY_ADMIN.APPLY_TABLE_POLICY and SA_POLICY_ADMIN.APPLY_SCHEMA_POLICY.

You must call this procedure for a policy before that policy can be applied to a table or schema. Subscribing is needed only once, not for each use of the policy in a table or schema.

You cannot drop any subscribed policy unless it has been removed from any table or schema to which it was applied, and then unsubscribed.

Syntax

SA_POLICY.POLICY_SUBSCRIBE(
  policy_name     IN VARCHAR2);

Parameter

Example

The following statement subscribes the database to the hr_ols_pol policy so that it can used by applying on tables and schema.

BEGIN
 SA_POLICY_ADMIN.POLICY_SUBSCRIBE(
  policy_name   => 'hr_ols_pol');
END;
/

In an Oracle Internet Directory enabled Oracle Label Security configuration, the SA_POLICY_ADMIN.POLICY_UNSUBSCRIBE procedure unsubscribes to the policy.

You can use this procedure only if the policy is not in use; that is, it has not been applied to any table or schema. (If it has been applied to tables or schemas, then it must be removed from all of them before it can be unsubscribed.) A policy can be dropped in Oracle Internet Directory only if is not subscribed in any of the databases that have registered with that Oracle Internet Directory. (See "olsadmintool dropprofile" for more information.)

You cannot drop any subscribed policy unless it has been removed from any table or schema to which it was applied, and then unsubscribed.

Syntax

SA_POLICY_ADMIN.POLICY_UNSUBSCRIBE(
  policy_name  IN VARCHAR2);

Parameter

Example

The following statement unsubscribes the database to the hr_ols_pol policy.

BEGIN
 SA_POLICY_ADMIN.POLICY_UNSUBSCRIBE(
  policy_name   => 'hr_ols_pol');
END;
/

The SA_POLICY_ADMIN.REMOVE_SCHEMA_POLICY procedure removes the specified policy from a schema.

The policy will be removed from all the tables in the schema and, optionally, the label column for the policy will be dropped from all the tables.

Syntax

SA_POLICY_ADMIN.REMOVE_SCHEMA_POLICY (
  policy_name     IN VARCHAR2,
  schema_name     IN VARCHAR2,
  drop_column     IN BOOLEAN DEFAULT FALSE);

Parameters

Example

The following example drops the human_resource policy's column from the HR schema.

BEGIN
 SA_POLICY_ADMIN.REMOVE_SCHEMA_POLICY(
  policy_name      => 'hr_ols_pol',
  schema_name      => 'HR',
  drop_column      => TRUE);
END;
/

The SA_POLICY_ADMIN.REMOVE_TABLE_POLICY procedure removes the specified policy from a table.

The policy predicate and any DML triggers will be removed from the table, and the policy label column can optionally be dropped. Policies can be removed from tables belonging to a schema that is protected by the policy.

Syntax

SA_POLICY_ADMIN.REMOVE_TABLE_POLICY (
policy_name        IN VARCHAR2,
schema_name        IN VARCHAR2,
table_name         IN VARCHAR2,
drop_column        IN BOOLEAN DEFAULT FALSE);

Parameters

Example

The following statement removes the hr_ols_pol policy from the EMPLOYEES table in the HR schema:

BEGIN
 SA_POLICY_ADMIN.REMOVE_TABLE_POLICY(
  policy_name    => 'hr_ols_pol',
  schema_name    => 'HR',
  table_name     => 'EMPLOYEES',
  drop_column    => TRUE);
END;
/

The SA_SESSION.COMP_READ function returns a comma-delimited list of compartments that the user is authorized to read.

Syntax

SA_SESSION.COMP_READ ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the compartments that the user can read for the hr_ols_pol policy.

SELECT SA_SESSION.COMP_READ ('hr_ols_pol') FROM DUAL; 

The SA_SESSION.COMP_WRITE function returns a comma-delimited list of compartments to which the user is authorized to write. This function is a subset of SA_SESSION.COMP_READ.

Syntax

SA_SESSION.COMP_WRITE ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the compartments that the user can modify for the hr_ols_pol policy.

SELECT SA_SESSION.COMP_WRITE ('hr_ols_pol') FROM DUAL;

The SA_SESSION.GROUP_READ function returns a comma-delimited list of groups that the user is authorized to read.

Syntax

SA_SESSION.GROUP_READ ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the list of groups that a user can read for the hr_ols_pol policy.

SELECT SA_SESSION.GROUP_READ ('hr_ols_pol') FROM DUAL;

The SA_SESSION.GROUP_WRITE function returns a comma-delimited list of groups that the user is authorized to write. This function is a subset of SA_SESSION.GROUP_READ.

Syntax

SA_SESSION.GROUP_WRITE ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the groups the user is authorized to modify for the hr_ols_pol policy.

SELECT SA_SESSION.GROUP_WRITE ('hr_ols_pol') FROM DUAL;

The SA_SESSION.LABEL function returns the label that is associated with the specified policy for the current session.

Syntax

SA_SESSION.LABEL ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the label that is associated with the hr_ols_pol policy.

SELECT SA_SESSION.LABEL ('hr_ols_pol') FROM DUAL;

The SA_SESSION.MAX_LEVEL function returns the maximum Oracle Label Security level authorized for the session.

Syntax

SA_SESSION.MAX_LEVEL ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the maximum Oracle Label Security level that is authorized for the hr_ols_pol policy.

SELECT SA_SESSION.MAX_LEVEL ('hr_ols_pol') FROM DUAL;

The SA_SESSION.MAX_READ_LABEL function returns the label string that was used to initialize the user's maximum authorized read label.

The return string is composed of the user's maximum level, compartments authorized for read access, and groups authorized for read access.

Syntax

SA_SESSION.MAX_READ_LABEL ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the maximum read label privileges for the hr_ols_pol policy.

SELECT SA_SESSION.MAX_READ_LABEL ('hr_ols_pol') FROM DUAL;

The SA_SESSION.MAX_WRITE_LABEL function returns the label string that was used to initialize the user's maximum authorized write label.

This return string is composed of the user's maximum level, compartments authorized for write access, and groups authorized for write access.

Syntax

SA_SESSION.MAX_WRITE_LABEL ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the maximum write label privileges for the hr_ols_pol policy.

SELECT SA_SESSION.MAX_WRITE_LABEL ('hr_ols_pol') FROM DUAL;

The SA_SESSION.MIN_LEVEL function returns the minimum Oracle Label Security level authorized for the session.

Syntax

SA_SESSION.MIN_LEVEL ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the current minimum level for the hr_ols_pol policy.

SELECT SA_SESSION.MIN_LEVEL ('hr_ols_pol') FROM DUAL;

The SA_SESSION.MIN_WRITE_LABEL function retrieves the label string that was used to initialize the user's minimum authorized write label.

The return string contains only the level, with no compartments or groups.

Syntax

SA_SESSION.MIN_WRITE_LABEL ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the maximum write label privileges for the hr_ols_pol policy.

SELECT SA_SESSION.MIN_WRITE_LABEL ('hr_ols_pol') FROM DUAL;

The SA_SESSION.PRIVS function returns the set of current session privileges, in a comma-delimited list.

Syntax

SA_SESSION.PRIVS ( 
  policy_name IN VARCHAR2) 
RETURN VARCHAR2;

Parameter

Example

The following example returns the current session privileges for the hr_ols_pol policy.

SELECT SA_SESSION.PRIVS ('hr_ols_pol') FROM DUAL;

The SA_SESSION.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

SA_SESSION.RESTORE_DEFAULT_LABELS (
 policy_name in VARCHAR2); 

Parameter

Example

The following example restores the default labels for the hr_ols_pol policy.

BEGIN
 SA_SESSION.RESTORE_DEFAULT_LABELS (
  policy_name         => 'hr_ols_pol');
END;
/

The SA_SESSION.ROW_LABEL function returns the name of the row label that is associated with the policy for the current session.

Syntax

SA_SESSION.ROW_LABEL ( 
  policy_name IN VARCHAR2)
RETURN VARCHAR2; 

Parameter

Example

The following example returns the row label that is associated with the hr_ols_pol policy.

SELECT SA_SESSION.ROW_LABEL ('hr_ols_pol') FROM DUAL;

The SA_SESSION.SET_LABEL procedure sets the label of the current database session.

You 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 procedure 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.

Syntax

SA_SESSION.SET_LABEL (
 policy_name IN VARCHAR2,
 label       IN VARCHAR2); 

Parameters

Example

The following example sets the label for the hr_ols_pol policy.

BEGIN
 SA_SESSION.SET_LABEL (
  policy_name         => 'hr_ols_pol',
  label               => 'C:A,B:US');
END;
/

The SA_SESSION.SA_USER_NAME function returns the name of the current Oracle Label Security user, as set by the SA_SESSION.SET_ACCESS_PROFILE procedure (or as established at login).

This is how you can determine the identity of the current user in relation to Oracle Label Security, rather than in relation to your Oracle login name.

Syntax

SA_SESSION.SA_USER_NAME ( 
  policy_name IN VARCHAR2)
RETURN VARCHAR2; 

Parameter

Example

The following example finds the name of the Oracle Label Security user for the hr_ols_pol policy.

SELECT SA_SESSION.SA_USER_NAME ('hr_ols_pol') FROM DUAL;

The SA_SESSION.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.

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.

Syntax

SA_SESSION.SAVE_DEFAULT_LABELS ( 
  policy_name IN VARCHAR2); 

Parameter

Example

The following example saves the label defaults for the hr_ols_pol policy.

BEGIN
 SA_SESSION.SAVE_DEFAULT_LABELS (
  policy_name       => 'hr_ols_pol');
END;
/

The SA_SESSION.SET_ACCESS_PROFILE procedure sets the Oracle Label Security authorizations and privileges of the database session to those of the specified user. (Note that the originating user retains the PROFILE_ACCESS privilege.)

The user executing the SA_SESSION.SET_ACCESS_PROFILE procedure must have the PROFILE_ACCESS privilege. Note that the logged-in database user (the Oracle user ID) does not change. That user assumes only the authorizations and privileges of the specified user. By contrast, the Oracle Label Security user name is changed.

This administrative procedure is useful for various tasks:

• With SA_SESSION.SET_ACCESS_PROFILE, you can see the result of the authorization and privilege settings for a particular user.

• Applications need to have proxy accounts connect as (and assume the identity of) application users, for purposes of accessing labeled data. With the SA_SESSION.SET_ACCESS_PROFILE privilege, the proxy account can act on behalf of the application users.

Syntax

SA_SESSION.SET_ACCESS_PROFILE (
  policy_name IN VARCHAR2
  user_name   IN VARCHAR2); 

Parameters

Example

The following example enables user psmith to have Oracle Label Security authorizations and privileges for the database session.

BEGIN
 SA_SESSION.SET_ACCESS_PROFILE (
  policy_name       => 'hr_ols_pol',
  user_name         => 'jjones');
END;
/

The SA_SESSION.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.

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.

Syntax

SA_SESSION.SET_ROW_LABEL (
 policy_name   IN VARCHAR2,
 row_label     IN VARCHAR2); 

Parameters

Example

The following example sets the row label for the hr_ols_pol policy.

BEGIN
 SA_SESSION.SET_ROW_LABEL (
  policy_name     => 'hr_ols_pol',
  label           => 'HR');
END;
/

The SA_SYSDBA.ALTER_POLICY procedure sets and modifies column names that are associated with the policy.

SA_SYSDBA.ALTER_POLICY can only be used to change column name for policies that are not applied on any user tables or schemas. Otherwise, this error appears:

12474, 00000, "cannot change column name for a policy in use"

Syntax

SA_SYSDBA.ALTER_POLICY (
   policy_name       IN  VARCHAR2,
   default_options   IN  VARCHAR2 DEFAULT NULL,
   column_name       IN  VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example updates the hr_ols_pol policy to use a different set of default options. Because the name of the column does not need to change, the column_name parameter is omitted.

BEGIN
 SA_SYSDBA.ALTER_POLICY ( 
  policy_name      => 'hr_ols_pol',
  default_options  => 'read_control, delete_control');
END;
/

The SA_SYSDBA.CREATE_POLICY procedure creates a new Oracle Label Security policy, define a policy-specific column name, and specify a set of default policy options.

After you create the policy, a role for it is created and granted to you. The format of the role name is policy_DBA (for example, my_ols_pol_DBA).

Syntax

SA_SYSDBA.CREATE_POLICY (
   policy_name       IN VARCHAR2,
   column_name       IN VARCHAR2 DEFAULT NULL,
   default_options   IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example creates a policy container whose default options are READ_CONTROL and WRITE_CONTROL. The WRITE_CONTROL option encompasses the INSERT_CONTROL, UPDATE_CONTROL, and DELETE_CONTROL options.

BEGIN
 SA_SYSDBA.CREATE_POLICY ( 
  policy_name      => 'hr_ols_pol',
  column_name      => 'ols_col',
  default_options  => 'read_control, write_control');
END;
/

The SA_SYSDBA.DISABLE_POLICY procedure turns off enforcement of a policy, without removing it from the database.

The policy is not enforced for all subsequent access to the database.

To disable a policy means that no access control is enforced on the tables and schemas protected by the policy. The administrator can continue to perform administrative operations while the policy is disabled.

Normally, a policy should not be disabled in order to manage data. At times, however, an administrator may need to disable a policy to perform application debugging tasks. In this case, the database should be run in single-user mode. In a development environment, for example, you may need to observe data processing operations without the policy turned on. When you reenable the policy, all of the selected enforcement options become effective again.

Syntax

SA_SYSDBA.DISABLE_POLICY (
 policy_name IN VARCHAR2);

Parameters

Example

The following example disables the hr_ols_pol policy:

EXEC SA_SYSDBA.DISABLE_POLICY ('hr_ols_pol');

The SA_SYSDBA.DROP_POLICY procedure deletes the policy and all of its associated user labels and data labels from the database.

This procedure purges the policy and these associations from the system entirely. You can optionally drop the label column from all tables controlled by the policy. The policy does not need to be disabled before you drop it.

Syntax

SA_SYSDBA.DROP_POLICY ( 
   policy_name IN VARCHAR2,
   drop_column  BOOLEAN DEFAULT FALSE);

Parameters

Example

The following example deletes the hr_ols_pol policy.

EXEC SA_SYSDBA.DROP_POLICY ('hr_ols_pol');

The SA_SYSDBA.ENABLE_POLICY procedure enforces access control on the tables and schemas protected by the policy.

A policy is automatically enabled when it is created. After creation or enablement, the policy is enforced for all subsequent access to tables protected by the policy.

Syntax

SA_SYSDBA.ENABLE_POLICY (policy_name IN VARCHAR2);

Parameters

Example

The following example enables the hr_ols_pol policy.

EXEC SA_SYSDBA.ENABLE_POLICY('hr_ols_pol');

This procedure is useful if you have already used the SA_USER_ADMIN.SET_COMPARTMENTS procedure for the user but then decide that you want to grant this user authorization for additional compartments, or to update the current set of compartments. You also can use it in place of SA_USER_ADMIN.SET_COMPARTMENTS.

Syntax

SA_USER_ADMIN.ADD_COMPARTMENTS ( 
policy_name    IN VARCHAR2,
user_name      IN VARCHAR2,
comps          IN VARCHAR2,
access_mode    IN VARCHAR2 DEFAULT NULL,
in_def         IN VARCHAR2 DEFAULT NULL,
in_row         IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example adds compartments to the hr_ols_pol policy.

BEGIN 
 SA_USER_ADMIN.ADD_COMPARTMENTS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones',
  comps          => 'FIN',
  access_mode    => SA_UTL.READ_ONLY,
  in_def         => 'y',
  in_row         => 'y');
END;
/

This procedure is useful if you have already used the SA_USER_ADMIN.SET_GROUPS procedure for the user but then decide that you want to grant this user authorization for additional groups or to update the current set of groups. You also can use it in place of SA_USER_ADMIN.SET_GROUPS.

Syntax

SA_USER_ADMIN.ADD_GROUPS ( 
  policy_name       IN VARCHAR2,
  user_name         IN VARCHAR2,
  groups            IN VARCHAR2,
  access_mode       IN VARCHAR2 DEFAULT NULL,
  in_def            IN VARCHAR2 DEFAULT NULL,
  in_row            IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example adds several groups to the hr_ols_pol policy.

BEGIN 
 SA_USER_ADMIN.ADD_GROUPS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones',
  groups         => 'ER_FIN, SR_FIN, NR_FIN, WR_FIN',
  access_mode    => SA_UTL.READ_WRITE,
  in_def         => 'y',
  in_row         => 'y');
END;
/

Syntax

SA_USER_ADMIN.ALTER_COMPARTMENTS (
  policy_name  IN VARCHAR2,
  user_name    IN VARCHAR2,
  comps        IN VARCHAR2,
  access_mode  IN VARCHAR2 DEFAULT NULL,
  in_def       IN VARCHAR2 DEFAULT NULL,
  in_row       IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example modifies compartments for the hr_ols_pol policy.

BEGIN 
 SA_USER_ADMIN.ALTER_COMPARTMENTS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones',
  comps          => 'FIN',
  access_mode    => SA_UTL.READ_ONLY,
  in_def         => 'y',
  in_row         => 'y');
END;
/

Syntax

SA_USER_ADMIN.ALTER_GROUPS ( 
  policy_name      IN VARCHAR2,
  user_name        IN VARCHAR2,
  groups           IN VARCHAR2,
  access_mode      IN VARCHAR2 DEFAULT NULL,
  in_def           IN VARCHAR2 DEFAULT NULL,
  in_row           IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example sets the access mode for the existing groups to be read only.

BEGIN 
 SA_USER_ADMIN.ALTER_GROUPS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones',
  groups         => 'ER',
  access_mode    => SA_UTL.READ_ONLY);
END;
/

Syntax

SA_USER_ADMIN.DROP_ALL_COMPARTMENTS (
 policy_name  IN VARCHAR2,
 user_name    IN VARCHAR2);

Parameters

Example

The following example drops all compartments for the hr_ols_pol policy for user jjones.

BEGIN 
 SA_USER_ADMIN.DROP_ALL_COMPARTMENTS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones');
END;
/

Syntax

SA_USER_ADMIN.DROP_ALL_GROUPS (
  policy_name IN VARCHAR2,
  user_name   IN VARCHAR2);

Parameters

Example

The following example drops all groups from the hr_ols_pol policy for user jjones.

BEGIN 
 SA_USER_ADMIN.DROP_ALL_GROUPS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones');
END;
/

Syntax

SA_USER_ADMIN.DROP_COMPARTMENTS ( 
  policy_name     IN VARCHAR2,
  user_name       IN VARCHAR2,
  comps           IN VARCHAR2);

Parameters

Example

The following example drops the FINANCIAL compartment from the hr_ols_pol policy.

BEGIN 
 SA_USER_ADMIN.DROP_COMPARTMENTS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones',
  comps          => 'HR');
END;
/

Syntax

SA_USER_ADMIN.DROP_GROUPS ( 
  policy_name IN VARCHAR2,
  user_name   IN VARCHAR2,
  groups      IN VARCHAR2);

Parameters

Example

The following example drops the NR_FIN group from the hr_ols_pol policy.

BEGIN 
 SA_USER_ADMIN.DROP_GROUPS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones',
  groups         => 'ER');
END;
/

Syntax

SA_USER_ADMIN.DROP_USER_ACCESS (
  policy_name      IN VARCHAR2,
  user_name        IN VARCHAR2); 

Parameters

Examples

The following example removes user jjones's authorization for the hr_ols_pol policy.

BEGIN 
 SA_USER_ADMIN.DROP_USER_ACCESS (
  policy_name       => 'hr_ols_pol',
  user_name         => 'jjones');
END;
/

After you have set the compartment, you can configure additional compartments by using the SA_USER_ADMIN.ADD_COMPARTMENTS procedure. (See "SA_USER_ADMIN.ADD_COMPARTMENTS".)

All users must have their levels set before their authorized compartments can be established.

The write compartments, if specified, must be a subset of the read compartments. (The write compartments are those to which the user should have write access.)

Syntax

SA_USER_ADMIN.SET_COMPARTMENTS (
  policy_name   IN VARCHAR2,
  user_name     IN VARCHAR2,
  read_comps    IN VARCHAR2,
  write_comps   IN VARCHAR2 DEFAULT NULL,
  def_comps     IN VARCHAR2 DEFAULT NULL,
  row_comps     IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example sets compartments for the hr_ols_pol policy.

BEGIN
 SA_USER_ADMIN.SET_COMPARTMENTS (
  policy_name   => 'hr_ols_pol',
  user_name     => 'jjones', 
  read_comps    => 'FIN',
  write_comps   => 'FIN',
  def_comps     => 'FIN',
  row_comps     => 'FIN');
END;
/

As long as the row label will still be dominated by the new write label, you can set the session label to:

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

• 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.)

The row label must be dominated by the new write label that will result from resetting the session label. If this condition is not true, then the SET_DEFAULT_LABEL procedure will fail.

For example, suppose the current row label is S:A,B, and that you have write access to both compartments. If you attempt to set the new default label to C:A,B, then the SET_LABEL procedure will fail. This is because the new write label would be C:A,B, which does not dominate the current row label.

To successfully reset the session label in this case, you must first lower the row label to a value that will be dominated by the resulting session label.

Syntax

SA_USER_ADMIN.SET_DEFAULT_LABELS (
  policy_name  IN VARCHAR2,
  user_name    IN VARCHAR2,
  def_label    IN VARCHAR2);

Parameters

Example

The following example sets the default label for hr_ols_pol for user jjones.

BEGIN 
 SA_USER_ADMIN.SET_DEFAULT_LABEL (
  policy_name       => 'hr_ols_pol',
  user_name         => 'jjones',
  def_label         => 'HS');
END;
/

All users must have their levels set before their authorized groups can be established. You can find information about a user's level authorization by querying the DBA_SA_USER_LEVELS data dictionary view.

Syntax

SA_USER_ADMIN.SET_GROUPS (policy_name IN VARCHAR2,
  user_name        IN VARCHAR2,
  read_groups      IN VARCHAR2,
  write_groups     IN VARCHAR2 DEFAULT NULL,
  def_group        IN VARCHAR2 DEFAULT NULL,
  row_groups       IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example defines groups for the hr_ols_pol policy.

BEGIN 
 SA_USER_ADMIN.SET_GROUPS (
  policy_name    => 'hr_ols_pol',
  user_name      => 'jjones', 
  read_groups    => 'ER_FIN',
  write_groups   => 'ER_FIN',
  def_groups     => 'ER_FIN',
  row_groups     => 'ER_FIN');
END;
/

Syntax

SA_USER_ADMIN.SET_LEVELS (policy_name IN VARCHAR2,
   user_name        IN VARCHAR2,
   max_level        IN VARCHAR2,
   min_level        IN VARCHAR2 DEFAULT NULL,
   def_level        IN VARCHAR2 DEFAULT NULL,
   row_level        IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example sets levels for the hr_ols_pol policy.

BEGIN
  SA_USER_ADMIN.SET_LEVELS (
   policy_name     => 'hr_ols_pol',
   user_name       => 'jjones',
   max_level       => 'PUB',
   min_level       => 'HS');
END;
/

To grant privileges to a stored program unit, you must have the policy_DBA role, and the EXECUTE permission on the SA_USER_ADMIN.SA_USER_ADMIN package. You can use either the SA_USER_ADMIN package or Oracle Enterprise Manager to manage Oracle Label Security privileges.

Syntax

SA_USER_ADMIN.SET_PROG_PRIVS (
  policy_name           IN VARCHAR2,
  schema_name           IN VARCHAR2,
  program_unit_name     IN VARCHAR2,
  privileges            IN VARCHAR2);

Parameters

Example

The following example gives the READ privilege to the SUM_PURCHASES function (described in "Example of a Trusted Stored Program Unit"):

BEGIN
 SA_USER_ADMIN.SET_PROG_PRIVS (
  policy_name         => 'hr_ols_pol',
  schema_name         => 'HR',
  program_unit_name   => 'check_emp_hours',
  privileges          => 'READ');
END;
/

When the check_emp_hours procedure is then called, it runs with the READ privilege as well as the current user's Oracle Label Security privileges. Using this technique, the user can be allowed to find the value of the total employee hours that were logged, without learning what hours any individual employee logged.

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

• 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

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

If you try to set the row label to an invalid value, then the operation is disallowed, and the row label value is unchanged.

Syntax

SA_USER_ADMIN.SET_ROW_LABEL (
  policy_name   IN VARCHAR2,
  user_name     IN VARCHAR2,
  row_label     IN VARCHAR2);

Parameters

Example

The following example sets the row label for the hr_ols_pol policy for user jjones.

BEGIN 
 SA_USER_ADMIN.SET_ROW_LABEL (
  policy_name       => 'hr_ols_pol',
  user_name         => 'jjones',
  row_label         => 'HS');
END;
/

Syntax

SA_USER_ADMIN.SET_USER_LABELS (
  policy_name      IN VARCHAR2,
  user_name        IN VARCHAR2,
  max_read_label   IN VARCHAR2,
  max_write_label  IN VARCHAR2 DEFAULT NULL,
  min_write_label  IN VARCHAR2 DEFAULT NULL,
  def_label        IN VARCHAR2 DEFAULT NULL,
  row_label        IN VARCHAR2 DEFAULT NULL);

Parameters

Example

The following example sets user labels for the hr_ols_pol policy for user jjones.

BEGIN 
 SA_USER_ADMIN.SET_USER_LABELS (
  policy_name       => 'hr_ols_pol',
  user_name         => 'jjones',
  max_read_label    => 'HS:FIN',
  max_write_label   => 'HS',
  def_label         => 'HS',
  row_label         => 'HS');
END;
/

These privileges do not become effective until the next time the user logs into the database. The new set of privileges replaces any existing privileges. A NULL value for the privileges parameter removes the user's privileges for the policy.

To assign policy privileges to users, you must have the EXECUTE privilege for the SA_USER_ADMIN package, and must have been granted the policy_DBA role.

Syntax

SA_USER_ADMIN.SET_USER_PRIVS (
  policy_name     IN VARCHAR2,
  user_name       IN VARCHAR2,
  privileges      IN VARCHAR2);

Parameters

Example

The following example grants user jgodfrey full privileges for the hr_ols_pol policy settings.

BEGIN 
 SA_USER_ADMIN.SET_USER_PRIVS (
  policy_name       => 'hr_ols_pol',
  user_name         => 'jgodfrey',
  privileges        => 'FULL');
END;
/

The SA_UTL.CHECK_LABEL_CHANGE function checks if the user can change the data label for a policy protected table row.

This function returns 1 if the user can change the data label. It returns 0 if the user cannot change the data label. The input values are the policy name, the current data label, and the new data label.

Syntax

SA_UTL.CHECK_LABEL_CHANGE (
  policy_name     IN VARCHAR2,
  current_label   IN NUMBER,
  new_label       IN NUMBER)
RETURN NUMBER; 

Parameters

Example

The following example indicates if users can change data labels in policy-protected rows.

SET SERVEROUTPUT ON
BEGIN
  IF SA_UTL.CHECK_LABEL_CHANGE('hr_ols_pol',2000, 2200) = 1 
   THEN DBMS_OUTPUT.PUT_LINE('Users can chagne data labels in policy-protected rows.');
  ELSE
   DBMS_OUTPUT.PUT_LINE('Users cannot change data labels in policy-protected rows.');
  END IF;
END;
/

The SA_UTL.CHECK_READ function checks if a user can read a policy-protected table row.

This function returns 1 if the user can read the table row. It returns 0 if the user cannot read the table row.

Syntax

SA_UTL.CHECK_READ (
  policy_name     IN VARCHAR2,
  label           IN NUMBER) 
RETURN NUMBER; 

Parameters

Example

The following example indicates if users can read a policy-protected row.

SET SERVEROUTPUT ON
BEGIN
  IF SA_UTL.CHECK_READ('hr_ols_pol',2000) = 1 
   THEN DBMS_OUTPUT.PUT_LINE('Users can read policy-protected rows.');
  ELSE
   DBMS_OUTPUT.PUT_LINE('Users cannot read policy-protected rows.');
  END IF;
END;
/

The SA_UTL.DATA_LABEL function returns TRUE if the label is a data label.

Syntax

SA_UTL.DATA_LABEL( 
 label IN NUMBER) 
RETURN BOOLEAN;

Parameters

Example

The following example indicates if the label 2000 is a data label.

SET SERVEROUTPUT ON
BEGIN 
 IF SA_UTL.DATA_LABEL(2000)
  THEN DBMS_OUTPUT.PUT_LINE('Label 2000 is a data label.');
 ELSE 
  DBMS_OUTPUT.PUT_LINE('Label 2000 is not a data label.'); 
 END IF; 
END;
/

The SA_UTL.GREATEST_LBOUND function returns a label that is the greatest lower bound of the two label arguments.

Syntax

SA_UTL.GREATEST_LBOUND (
 label1 IN NUMBER,
 label2 IN NUMBER)
RETURN NUMBER; 

Parameters

Examples

The following example compares existing label tags 3110 and 3111.

SELECT SA_UTL.GREATEST_LBOUND(3110,3111) FROM DUAL;

SA_UTL.GREATEST_LBOUND(3110,3111)
---------------------------------
                             3111

The SA_UTL.LEAST_UBOUND function returns a label that is the least upper bound of the label arguments.

Syntax

SA_UTL.LEAST_UBOUND (
 label1 IN NUMBER,
 label2 IN NUMBER)
RETURN NUMBER; 

Parameters

Example

The following example compares existing labels 3110 and 3111.

SELECT SA_UTL.LEAST_UBOUND(3110,3111) FROM DUAL;

SA_UTL.LEAST_UOUND(3110,3111)
-----------------------------
                         3110

The SA_UTL.NUMERIC_LABEL function returns the current session label. It takes a policy name as the input parameter and returns a NUMBER value.

Syntax

SA_UTL.NUMERIC_LABEL ( 
  policy_name) 
RETURN NUMBER;

Parameters

Example

The following example returns a the session numeric label for the user who is currently connected to the database instance.

SET SERVEROUTPUT ON
DECLARE
 num_label number;
BEGIN 
 num_label := SA_UTL.NUMERIC_LABEL('hr_ols_pol'); 
 DBMS_OUTPUT.PUT_LINE('Numeric label: '||num_label);
END;
/

The SA_UTL.NUMERIC_ROW_LABEL function returns the current row label. It takes a policy name as the input parameter and returns a NUMBER value.

Syntax

SA_UTL.NUMERIC_ROW_LABEL ( 
  policy_name) 
RETURN NUMBER;

Parameters

Examples

The following example returns the session numeric row label for the user who is currently connected to the database instance.

SET SERVEROUTPUT ON
DECLARE
 num_row number;
BEGIN 
 num_row := SA_UTL.NUMERIC_ROW_LABEL('hr_ols_pol'); 
 DBMS_OUTPUT.PUT_LINE('Numeric row label: '||num_row);
END;
/

The SA_UTL.SET_LABEL procedure sets the label of the current database session.

The session's write label and row label are set to the subset of the label's compartments and groups that are authorized for write access.

Syntax

SA_UTL.SET_LABEL (
 policy_name IN VARCHAR2,
 label       IN LBAC_LABEL); 

Parameters

Example

The following example sets the label for the hr_ols_pol policy.

BEGIN
  SA_UTL.SET_LABEL (
    policy_name => 'hr_ols_pol',
    label       => to_lbac_data_label('hr_ols_pol','hs:pii'));
END;
/

The SA_UTL.SET_ROW_LABEL procedure sets the row label of the current database session.

The compartments and groups in the label must be a subset of compartments and groups in the session label that are authorized for write access.

Syntax

SA_UTL.SET_ROW_LABEL (
 policy_name IN VARCHAR2,
 label       IN BINARY_INTEGER); 

Parameters

Example

The following example sets the row label for the hr_ols_pol policy to 3000.

BEGIN
 SA_UTL.SET_ROW_LABEL (
  policy_name         => 'hr_ols_pol',
  label               => 1111);
END;
/