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.

This procedure stores the user's session label 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;
/

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;
/

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;
/

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.

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;
/

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;
/

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;
/

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;
/

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 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;
/

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 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;
/

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;
/

If the group is used in an existing label, then 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;
/

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 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;
/

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;
/

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;
/

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;
/

That is, it applies to those tables that do not already have the policy applied. 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;
/

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;
/

However, it does not change 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;
/

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;
/

It accomplishes this 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;
/

It accomplishes this 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;
/

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;
/

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. To unsubscribe a policy, use the olsadmintool dropprofile command.

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 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 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;
/

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; 

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;

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;

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;

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;

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 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;

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;

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 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;

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;

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;
/

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;

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;
/

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;

This procedure 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;
/

Note that the originating user retains the PROFILE_ACCESS privilege.

The user who executes the SA_SESSION.SET_ACCESS_PROFILE procedure must have the PROFILE_ACCESS privilege. 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 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;
/

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;
/

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 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');

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');

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;
/

If the privileges parameter is NULL, then the program unit's privileges for the policy are removed.

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: 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

Examples

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;
/

The following example sets user labels for the XSOLSPOL1 policy for the Oracle Database Real Application Security user XSUSER1. To execute the following example, you must either be an administrative user named LBACSYS, be granted the LBAC_DBA database role and granted the EXECUTE privilege, or be granted the XSOLSPOL1_DBA role and granted the EXECUTE privilege on the SA_USER_ADMIN package.

EXEC SA_USER_ADMIN.SET_USER_LABELS('XSOLSPOL1', 'XSUSER1',‘MID','MID');

In this specification:

• XSOLSPOL1 is the name of an existing OLS policy.

• XSUSER1 is the name of an existing Oracle Database Real Application Security user.

• MID is the value of the max_read_label.

• MID is the value of the max_write_label.

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

Examples

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 following example grants Oracle Database Real Application Security user XSUSER1 the READ privilege for the Oracle Label Security policy XSOLSPOL1. To execute the following example, you must either be an administrative user named LBACSYS, be granted the LBAC_DBA database role and granted the EXECUTE privilege, or be granted the XSOLSPOL1_DBA role and granted the EXECUTE privilege on the SA_USER_ADMIN package.

EXEC SA_USER_ADMIN.SET_USER_PRIVS('XSOLSPOL1', 'XSUSER1','READ');

In this specification:

• XSOLSPOL1 is the name of an existing OLS policy.

• XSUSER1 is the name of an existing Oracle Database Real Application Security user.

• READ is the privilege to be granted to XSUSER1 in OLS policy XSOLSPOL1.

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;
/

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;
/

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;
/

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

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

This function 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;
/

This function 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 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 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;
/