Skip Headers
Oracle® Database Vault Administrator's Guide
10g Release 2 (10.2)

Part Number B25166-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

11 Using the DVSYS.DBMS_MACADM Package

In this chapter:

11.1 About the DVSYS.DBMS_MACADM Package

The procedures and functions within the DVSYS.DBMS_MACADM package allow you to write applications that configure the realms, factors, rule sets, command rules, secure application roles, and Oracle Label Security policies normally configured in Oracle Database Vault Administrator.

The DVSYS.DBMS_MACADM package is available only for users who have the DV_ADMIN or DV_OWNER role.

Many of the parameters used in the procedures and functions in the DVSYS.DBMS_MACADM package can use the constants available in the DVSYS.DBMS_MACUTL package. See "DVSYS.DBMS_MACUTL Constants" for more information.

11.2 Realm Procedures Within DVSYS.DBMS_MACADM

Table 11-1 lists procedures within the DVSYS.DBMS_MACADM package that you can use to configure realms. For constants that you can use with these procedures, see Table 13-1 for more information.

Chapter 4, "Configuring Realms" describes realms in detail. See also Chapter 13, "Using the DVSYS.DBMS_MACUTL Package" for a set of general purpose utility procedures that you can use with the realm procedures.

Table 11-1 DVSYS.DBMS_MACADM Realm Configuration Procedures

Procedure Description

ADD_AUTH_TO_REALM Procedure

Authorizes a user or role to access a realm as a participant.

ADD_AUTH_TO_REALM Procedure

Authorizes a user or role to access a realm as an owner or participant (no rule set).

ADD_AUTH_TO_REALM Procedure

Authorizes a user or role to access a realm as a participant. Optionally, you can specify a rule set for the authorization.

ADD_AUTH_TO_REALM Procedure

Authorizes a user or role to access a realm as a participant or owner. Optionally, you can specify a rule set for the authorization.

ADD_OBJECT_TO_REALM Procedure

Registers a set of objects for realm protection.

CREATE_REALM Procedure

Creates a realm.

DELETE_AUTH_FROM_REALM Procedure

Removes the authorization of a user or role to access a realm.

DELETE_OBJECT_FROM_REALM Procedure

Removes a set of objects from realm protection.

DELETE_REALM Procedure

Deletes a realm.

DELETE_REALM_CASCADE Procedure

Deletes a realm, including its related Database Vault configuration information.

RENAME_REALM Procedure

Renames a realm. The name change takes effect everywhere the realm is used.

UPDATE_REALM Procedure

Updates a realm.

UPDATE_REALM_AUTH Procedure

Updates the authorization of a user or role to access a realm.


11.2.1 ADD_AUTH_TO_REALM Procedure

This procedure authorizes a user or role to access a realm as a participant. The person running this procedure cannot add himself or herself to the realm as a realm participant.

Syntax

ADD_AUTH_TO_REALM(
  realm_name  VARCHAR2, 
  grantee     VARCHAR2); 

Parameters

Table 11-2 ADD_AUTH_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View".

grantee

User or role name to authorize as a participant.

To find the existing users and roles in the current database instance, query the DBA_USERS and DBA_ROLES views, described in Oracle Database Reference.

To find the authorization of a particular user or role, query the DVA_DV_REALM_AUTH view, described in "DBA_DV_REALM_AUTH View".

To find existing secure application roles used in privilege management, query the DVSYS.DBA_DV_ROLE view. Both are described in "Oracle Database Vault Data Dictionary Views".


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_AUTH_TO_REALM(
  realm_name  => 'Performance Statistics Realm', 
  grantee     => 'SYSADM'); 
END;

11.2.2 ADD_AUTH_TO_REALM Procedure

This procedure authorizes a user or role to access a realm as an owner or a participant. The person running this procedure cannot add himself or herself to the realm as a realm owner or participant.

Syntax

ADD_AUTH_TO_REALM(
  realm_name   VARCHAR2, 
  grantee      VARCHAR2, 
  auth_options NUMBER);

Parameters

Table 11-3 ADD_AUTH_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View".

grantee

User or role name to authorize as owner or participant.

To find the existing users and roles in the current database instance, query the DBA_USERS and DBA_ROLES views, described in Oracle Database Reference.

To find the authorization of a particular user or role, query the DVA_DV_REALM_AUTH view, described in "DBA_DV_REALM_AUTH View".

To find existing secure application roles used in privilege management, query the DVSYS.DBA_DV_ROLE view, described in "DBA_DV_ROLE View".

auth_options

Specify one of the following ways to authorize the realm:

  • 0: Participant.

  • 1: Owner

See "Defining Realm Authorization" for more information on participants and owners.


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_AUTH_TO_REALM(
  realm_name   => 'Performance Statistics Realm', 
  grantee      => 'SYSADM', 
  auth_options => 1);
END;

11.2.3 ADD_AUTH_TO_REALM Procedure

This procedure authorizes a user or role to access a realm as a participant. The person running this procedure cannot add himself or herself to the realm as a realm participant. Optionally, you can specify a rule set to check before allowing the authorization to proceed.

Syntax

ADD_AUTH_TO_REALM(
  realm_name    VARCHAR2, 
  grantee       VARCHAR2, 
  rule_set_name VARCHAR2);

Parameters

Table 11-4 ADD_AUTH_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

grantee

User or role name to authorize as participant.

To find the existing users and roles in the current database instance, query the DBA_USERS and DBA_ROLES views, described in Oracle Database Reference.

To find the authorization of a particular user or role, query the DVA_DV_REALM_AUTH view, described in "DBA_DV_REALM_AUTH View".

To find existing secure application roles used in privilege management, query the DVSYS.DBA_DV_ROLE view, described in "DBA_DV_ROLE View".

rule_set_name

Rule set to check before authorizing (optional). If the rule set evaluates to TRUE, then the authorization is allowed.

To find the available rule sets, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

To find rules that are associated with the rule sets, query the DVSYS.DBA_DV_RULE_SET_RULE view, described in "DBA_DV_RULE_SET_RULE View".


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_AUTH_TO_REALM(
  realm_name    => 'Performance Statistics Realm', 
  grantee       => 'SYSADM', 
  rule_set_name => 'Check Conf Access');
END;

11.2.4 ADD_AUTH_TO_REALM Procedure

This procedure authorizes a user or role to access a realm as a participant or owner. The person running this procedure cannot add himself or herself to the realm as a realm owner or participant. Optionally, you can specify a rule set to check before authorizing.

Syntax

ADD_AUTH_TO_REALM(
  realm_name    VARCHAR2, 
  grantee       VARCHAR2, 
  rule_set_name VARCHAR2, 
  auth_options  NUMBER); 

Parameters

Table 11-5 ADD_AUTH_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

grantee

User or role name to authorize as owner or participant.

To find the available users and roles, query the DBA_USERS and DBA_ROLES views, described in Oracle Database Reference.

To find the authorization of a particular user or role, query the DVA_DV_REALM_AUTH view, described in "DBA_DV_REALM_AUTH View".

rule_set_name

Rule set to check before authorizing (optional). If the rule set evaluates to TRUE, then the authorization is allowed.

To find the available rule sets, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

auth_options

Specify one of the following ways to authorize the realm:

  • 0: Participant

  • 1: Owner

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_REALM_AUTH_PARTICIPANT

  • G_REALM_AUTH_OWNER

See "Defining Realm Authorization" for more information on participants and owners.


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_AUTH_TO_REALM(
  realm_name    => 'Performance Statistics Realm', 
  grantee       => 'SYSADM', 
  rule_set_name => 'Check Conf Access',
  auth_options  => 1);
END;

11.2.5 ADD_OBJECT_TO_REALM Procedure

This procedure registers a set of objects for realm protection.

Syntax

ADD_OBJECT_TO_REALM(
  realm_name   VARCHAR2, 
  object_owner VARCHAR2, 
  object_name  VARCHAR2, 
  object_type  VARCHAR2); 

Parameters

Table 11-6 ADD_OBJECT_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

object_owner

Object owner to own this realm.

To find the available users, query the DBA_USERS view, described in Oracle Database Reference.

To find the authorization of a particular user or role, query the DVA_DV_REALM_AUTH view, described in "DBA_DV_REALM_AUTH View".

object_name

Object name. (The wildcard % is allowed. See "Object Name" under "Creating Realm-Secured Objects" for exceptions to the wildcard %.) You can also use the DVSYS.DBMS_MACUTL G_ALL_OBJECT constant.

To find the available objects, query the ALL_OBJECTS view, described in Oracle Database Reference.

To find objects that are secured by existing realms, query the DVSYS.DBA_DV_REALM_OBJECT view, described in "DBA_DV_REALM_OBJECT View".

object_type

Object type, such as TABLE, INDEX, or ROLE. (The wildcard % is allowed. See "Object Types" under "Creating Realm-Secured Objects" for exceptions to the wildcard %.)

You can also use the DVSYS.DBMS_MACUTL G_ALL_OBJECT constant.


Example

BEGIN
 DVSYS.DBMS_MACACDM.ADD_OBJECT_TO_REALM(
  realm_name   => 'Performance Statistics Realm', 
  object_owner => 'SYS', 
  object_name  => 'GATHER_SYSTEM_STATISTICS', 
  object_type  => 'ROLE'); 
END;

11.2.6 CREATE_REALM Procedure

This procedure creates a realm. After you create the realm, use the following procedures to complete the realm definition:

  • ADD_OBJECT_TO_REALM procedure registers one or more objects for the realm.

  • ADD_AUTH_TO_REALM procedures authorize users or roles for the realm.

Syntax

CREATE_REALM(
  realm_name    VARCHAR2, 
  description   VARCHAR2, 
  enabled       VARCHAR2, 
  audit_options NUMBER); 

Parameters

Table 11-7 CREATE_REALM Parameters

Parameter Description

realm_name

Realm name, up to 90 characters in mixed-case.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

description

Description of the purpose of the realm, up to 1024 characters in mixed-case.

enabled

Y (yes) enables realm checking; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

audit_options

Specify one of the following ways to audit the realm:

  • 0: Disables auditing for the realm.

  • 1: Creates an audit record when a realm violation occurs, for example, when an unauthorized user tries to modify an object that is protected by the realm.

  • 2: Creates an audit record for authorized activities on objects protected by the realm.

  • 3: Creates an audit record for both authorized and unauthorized activities on objects protected by the realm.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_REALM_AUDIT_OFF

  • G_REALM_AUDIT_SUCCESS

  • G_REALM_AUDIT_FAIL


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_REALM(
  realm_name    => 'Performance Statistics Realm', 
  description   => 'Realm to measure performance', 
  enabled       => 'Y', 
  audit_options => 1);
END; 

11.2.7 DELETE_AUTH_FROM_REALM Procedure

This procedure removes the authorization of a user or role to access a realm.

Syntax

DELETE_AUTH_FROM_REALM(
  realm_name VARCHAR2,
  grantee    VARCHAR2);

Parameters

Table 11-8 DELETE_AUTH_FROM_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

grantee

User or role name.

To find the authorization of a particular user or role, query the DVA_DV_REALM_AUTH view, described in "DBA_DV_REALM_AUTH View".


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_AUTH_FROM_REALM(
  realm_name => 'Performance Statistics Realm',
  grantee    => 'SYS');
END;

11.2.8 DELETE_OBJECT_FROM_REALM Procedure

This procedure removes a set of objects from realm protection.

Syntax

DELETE_OBJECT_FROM_REALM(
  realm_name   VARCHAR2, 
  object_owner VARCHAR2, 
  object_name  VARCHAR2, 
  object_type  VARCHAR2);

Parameters

Table 11-9 DELETE_OBJECT_FROM_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

object_owner

Database schema owner.

To find the available users, query the DBA_USERS view, described in Oracle Database Reference.

To find the authorization of a particular user, query the DVA_DV_REALM_AUTH view, described in "Oracle Database Vault Data Dictionary Views".

object_name

Object name. (The wildcard % is allowed. See "Object Name" under "Creating Realm-Secured Objects" for exceptions to the wildcard %.) You can also use the DVSYS.DBMS_MACUTL G_ALL_OBJECT constant.

To find objects that are secured by existing realms, query the DVSYS.DBA_DV_REALM_OBJECT view, described in "DBA_DV_REALM_OBJECT View".

object_type

Object type, such as TABLE, INDEX, or ROLE. (The wildcard % is allowed. See "Object Types" under "Creating Realm-Secured Objects" for exceptions to the wildcard %.)

You can also use the DVSYS.DBMS_MACUTL G_ALL_OBJECT constant.


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_OBJECT_FROM_REALM(
  realm_name   => 'Performance Statistics Realm', 
  object_owner => 'SYS', 
  object_name  => 'GATHER_SYSTEM_STATISTICS', 
  object_type  => 'ROLE'); 
END;

11.2.9 DELETE_REALM Procedure

This procedure deletes a realm but does not remove its associated objects and authorizations. Before you delete a realm, you can locate its associated objects by querying the DVSYS.DBA_DV_REALM_OBJECT view, described in"Oracle Database Vault Data Dictionary Views".

If you want to remove the associated objects and authorizations as well as the realm, see "DELETE_REALM_CASCADE Procedure".

Syntax

DELETE_REALM(
  realm_name VARCHAR2); 

Parameters

Table 11-10 DELETE_REALM Parameter

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"


Example

EXEC DVSYS.DBMS_MACADM.DELETE_REALM('Performance Statistics Realm'); 

11.2.10 DELETE_REALM_CASCADE Procedure

This procedure deletes a realm, including its related Database Vault configuration information that specifies who is authorized (DVSYS.DBA_DV_REALM_AUTH view) and what objects are protected (DVSYS.DBA_DV_REALM_OBJECT view). It does not delete the actual database objects or users. To find a listing of the realm-related objects, query the DVSYS.DBA_DV_REALM view. To find its authorizations, query DVSYS.DBA_DV_REALM_AUTH. Both are described under "Oracle Database Vault Data Dictionary Views".

Syntax

DELETE_REALM_CASCADE(
  realm_name VARCHAR2); 

Parameters

Table 11-11 DELETE_REALM_CASCADE Parameter

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"


Example

EXEC DVSYS.DBMS_MACADM.DELETE_REALM_CASCADE('Performance Statistics Realm'); 

11.2.11 RENAME_REALM Procedure

This procedure renames a realm. The name change takes effect everywhere the realm is used.

Syntax

RENAME_REALM(
  realm_name VARCHAR2, 
  new_name   VARCHAR2); 

Parameters

Table 11-12 RENAME_REALM Parameters

Parameter Description

realm_name

Current realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

new_name

New realm name, up to 90 characters in mixed-case.


Example

BEGIN
 DVSYS.DBMS_MACADM.RENAME_REALM(
  realm_name => 'Performance Statistics Realm', 
  new_name   => 'Sector 2 Performance Statistics Realm');
END; 

11.2.12 UPDATE_REALM Procedure

This procedure updates a realm.

Syntax

UPDATE_REALM(
  realm_name    VARCHAR2, 
  description   VARCHAR2, 
  enabled       VARCHAR2, 
  audit_options NUMBER); 

Parameters

Table 11-13 UPDATE_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

description

Description of the purpose of the realm, up to 1024 characters in mixed-case.

enabled

Y (yes) enables realm checking; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

audit_options

Specify one of the following ways to audit the realm:

  • 0: Disables auditing for the realm.

  • 1: Creates an audit record when a realm violation occurs, for example, when an unauthorized user tries to modify an object that is protected by the realm.

  • 2: Creates an audit record for authorized activities on objects protected by the realm.

  • 3: Creates an audit record for both authorized and unauthorized activities on objects protected by the realm.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_REALM_AUDIT_OFF

  • G_REALM_AUDIT_SUCCESS

  • G_REALM_AUDIT_FAIL


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_REALM(
  realm_name    => 'Sector 2 Performance Statistics Realm', 
  description   => 'Realm to measure performance for Sector 2 applications', 
  enabled       => 'Y', 
  audit_options => 2); 
END;

11.2.13 UPDATE_REALM_AUTH Procedure

Updates the authorization of a user or role to access a realm.

Syntax

UPDATE_REALM_AUTH(
  realm_name    VARCHAR2, 
  grantee       VARCHAR2, 
  rule_set_name VARCHAR2, 
  auth_options  NUMBER); 

Parameters

Table 11-14 UPDATE_REALM_AUTH Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, query the DVSYS.DBA_DV_REALM view, described in "DBA_DV_REALM View"

grantee

User or role name.

To find the available users and roles, query the DBA_USERS and DBA_ROLES views, described in Oracle Database Reference.

To find the authorization of a particular user or role, query the DVA_DV_REALM_AUTH view, described in DBA_DV_REALM_AUTH View.

To find existing secure application roles used in privilege management, query the DVSYS.DBA_DV_ROLE view, described in "DBA_DV_ROLE View".

rule_set_name

Rule set to check before authorizing (optional). If the rule set evaluates to TRUE, then the authorization is allowed.

To find the available rule sets, query the DVSYS.DBA_DV_RULE_SET view. To find rules that are associated with the rule sets, query the DBA_DB_RULE_SET_RULE view. Both are described in "Oracle Database Vault Data Dictionary Views".

auth_options

Specify one of the following ways to authorize the realm:

  • 0: Participant. This account or role provides system or direct privileges to access, manipulate, and create objects protected by the realm, provided these rights have been granted using the standard Oracle Database privilege grant process.

  • 1: Owner. This account or role has the same privileges as the realm participant, plus the authorization to grant or revoke realm-secured database roles. A realm can have more than one owner.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_REALM_AUTH_PARTICIPANT

  • G_REALM_AUTH_OWNER


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_REALM_AUTH(
  realm_name    => 'Sector 2 Performance Statistics Realm', 
  grantee       => 'SYSADM', 
  rule_set_name => 'Check Conf Access',, 
  auth_options  => 1,);
END; 

11.3 Rule Set Procedures Within DVSYS.DBMS_MACADM

Table 11-15 lists procedures within the DVSYS.DBMS_MACADM package that you can use to configure rule sets.

Chapter 5, "Configuring Rule Sets" describes rule sets in detail. See also Chapter 13, "Using the DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility procedures that you can use with the rule set procedures.

Table 11-15 DVSYS.DBMS_MACADM Rule Set Configuration Procedures

Procedure Description

ADD_RULE_TO_RULE_SET Procedure

Adds an enabled or disabled rule to the end of a rule set.

ADD_RULE_TO_RULE_SET Procedure

Adds a rule to a rule set and lets you specify its order within the rule set.

ADD_RULE_TO_RULE_SET Procedure

Adds a rule to a rule set.

CREATE_RULE Procedure

Creates a rule.

CREATE_RULE_SET Procedure

Creates a rule set.

DELETE_RULE Procedure

Deletes a rule.

DELETE_RULE_FROM_RULE_SET Procedure

Deletes a rule from a rule set.

DELETE_RULE_SET Procedure

Deletes a rule set.

RENAME_RULE Procedure

Renames a rule. The name change takes effect everywhere the rule is used.

RENAME_RULE_SET Procedure

Renames a rule set. The name change takes effect everywhere the rule set is used.

SYNC_RULES Procedure

Synchronizes the rules in Oracle Database Vault and Advanced Queuing Rules engine. You must perform this operation immediately after a rollback of an Add, Delete, or Modify rule operation.

UPDATE_RULE Procedure

Updates a rule.

UPDATE_RULE_SET Procedure

Updates a rule set.


11.3.1 ADD_RULE_TO_RULE_SET Procedure

This procedure adds an enabled or disabled rule to a rule set, and lets you specify its order within the rule set.

Syntax

ADD_RULE_TO_RULE_SET(
  rule_set_name  VARCHAR2, 
  rule_name      VARCHAR2, 
  rule_order     NUMBER, 
  enabled        VARCHAR2);

Parameters

Table 11-16 ADD_RULE_TO_RULE_SET Parameters

Parameter Description

rule_set_name

Rule set name.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

rule_name

Rule to add to the rule set.

To find existing rules, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, use DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE View".

rule_order

Does not apply to this release.

The order in which rules appear affects performance. See "Improving Performance by Setting the Order in Which Rules Appear in a Rule Set" for more information.

enabled

Y (yes) enables rule checking; N (no) disables it. The default is Y.

You can also enter the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

See Table 13-1 for more information.


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_RULE_TO_RULE_SET(
  rule_set_name => 'Limit_DBA_Access',
  rule_name     => 'Check UPDATE operations',
  enabled       => 'DBMS_MACUTL.G_YES');
END; 

11.3.2 ADD_RULE_TO_RULE_SET Procedure

This procedure adds a rule to a rule set and lets you specify its order within the rule set.

Syntax

ADD_RULE_TO_RULE_SET(
  rule_set_name  VARCHAR2, 
  rule_name      VARCHAR2, 
  rule_order     NUMBER);

Parameters

Table 11-17 ADD_RULE_TO_RULE_SET Parameters

Parameter Description

rule_set_name

Rule set name.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

rule_name

Rule to add to the rule set.

To find existing rules, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, use DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE_SET View".

rule_order

Does not apply to this release.

The order in which rules appear affects performance. See "Improving Performance by Setting the Order in Which Rules Appear in a Rule Set" for more information.


Example

BEGIN
 ADD_RULE_TO_RULE_SET(
  rule_set_name  'Limit_DBA_Access', 
  rule_name      'Restrict DROP TABLE operations');
END;

11.3.3 ADD_RULE_TO_RULE_SET Procedure

This procedure adds a rule to a rule set.

Syntax

ADD_RULE_TO_RULE_SET(
  rule_set_name VARCHAR2, 
  rule_name     VARCHAR2); 

Parameters

Table 11-18 ADD_RULE_TO_RULE_SET Parameters

Parameter Description

rule_set_name

Rule set name.

To find existing rule sets in the current database instance, query the DVSYS.DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

rule_name

Rule to add to the rule set.

To find existing rules in the current database instance, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, query DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE_SET_RULE View".


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_RULE_TO_RULE_SET(
  rule_set_name => 'Limit_DBA_Access',
  rule_name     => 'Check UPDATE operations');
END; 

11.3.4 CREATE_RULE Procedure

This procedure creates a rule.

Syntax

CREATE_RULE(
  rule_name  VARCHAR2, 
  rule_expr  VARCHAR2);

Parameters

Table 11-19 CREATE_RULE Parameters

Parameter Description

rule_name

Rule name, up to 90 characters in mixed-case. Spaces are allowed.

To find existing rules in the current database instance, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, query DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE_SET_RULE View".

rule_expr

PL/SQL BOOLEAN expression.

If the expression contains quotation marks, do not use double quotation marks. Instead, use two single quotation marks. Enclose the entire expression within single quotation marks. For example:

'TO_CHAR(SYSDATE,''HH24'') = ''12'''

See "Creating a New Rule" for more information on rule expressions.


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_RULE(
  rule_name  => 'Check UPDATE operations', 
  rule_expr  =>'SYS_CONTEXT(''USERENV'',''SESSION_USER'') = ''SYSADM''');
END;

11.3.5 CREATE_RULE_SET Procedure

This procedure creates a rule set. After you create a rule set, you can use the CREATE_RULE and ADD_RULE_TO_RULE set procedures to create and add rules to the rule set.

Syntax

CREATE_RULE_SET(
  rule_set_name    VARCHAR2, 
  description      VARCHAR2, 
  enabled          VARCHAR2, 
  eval_options     NUMBER, 
  audit_options    NUMBER, 
  fail_options     NUMBER, 
  fail_message     VARCHAR2, 
  fail_code        NUMBER, 
  handler_options  NUMBER, 
  handler          VARCHAR2);

Parameters

Table 11-20 CREATE_RULE_SET Parameters

Parameter Description

rule_set_name

Rule set name, up to 90 characters in mixed-case. Spaces are allowed.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

description

Description of the purpose of the rule set, up to 1024 characters in mixed-case.

enabled

Y (yes) enables the rule set; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

eval_options

If you plan to assign more than one rule to the rule set, enter one of the following settings:

  • 1: All rules in the rule set must evaluate to true for the rule set itself to evaluate to true.

  • 2: At least one rule in the rule set must evaluate to true for the rule set itself to evaluate to true.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_EVAL_ALL

  • G_RULESET_EVAL_ANY

audit_options

Select one of the following settings:

  • 0: Disables auditing

  • POWER(2,0): Audits if the rule set evaluates to false (fails).

  • POWER(2,1): Audits whenever the rule set is used.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_AUDIT_OFF

  • G_RULESET_AUDIT_FAIL

  • G_RULESET_AUDIT_SUCCESS

See "Audit Options" for more information.

fail_options

Options for reporting factor errors:

  • 1: Shows an error message.

  • 2: Does not show an error message.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_FAIL_SHOW

  • G_RULESET_FAIL_SILENT

See "Error Handling Options" for more information.

fail_message

Error message for failure, up to 80 characters in mixed-case, to associate with the fail code you specify for fail_code.

fail_code

Enter a negative number in the range of -20000 to -20999, to associate with the fail_message.

handler_options

Select one of the following settings:

  • 0: Disables error handling.

  • POWER(2,0): Call handler on rule set failure.

  • POWER(2,1): Call handler on rule set success.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_HANDLER_OFF

  • G_RULESET_HANDLER_FAIL

  • G_RULESET_HANDLER_SUCCESS

See "Error Handling Options" for more information.

handler

Name of the PL/SQL function or procedure that defines the custom event handler logic.

See "Error Handling Options" for more information.


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_RULE_SET(
  rule_set_name    => 'Limit_DBA_Access', 
  description      => 'DBA access through predefined processes', 
  enabled          => 'Y',
  eval_options     => 2,
  audit_options    => POWER(2,0),
  fail_options     => 2,
  fail_message     => '',
  fail_code        => NULL,
  handler_options  => POWER(2,0), 
  handler          => 'dbavowner.email_alert');
END;

11.3.6 DELETE_RULE Procedure

This procedure deletes a rule.

Syntax

DELETE_RULE(
  rule_name VARCHAR2); 

Parameter

Table 11-21 DELETE_RULE Parameter

Parameter Description

rule_name

Rule name.

To find existing rules in the current database instance, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, query DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE_SET_RULE View".


Example

EXEC DVSYS.DBMS_MACADM.DELETE_RULE('Check UPDATE operations'); 

11.3.7 DELETE_RULE_FROM_RULE_SET Procedure

This procedure deletes a rule from a rule set.

Syntax

DELETE_RULE_FROM_RULE_SET(
  rule_set_name VARCHAR2, 
  rule_name     VARCHAR2);

Parameters

Table 11-22 DELETE_RULE_FROM_RULE_SET Parameters

Parameter Description

rule_set_name

Rule set name.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

rule_name

Rule to remove from the rule set.

To find existing rules in the current database instance, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, query DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE_SET_RULE View".


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_RULE_FROM_RULE_SET(
  rule_set_name => 'Limit DBA Access', 
  rule_name     => 'Check UPDATE operations');
END;

11.3.8 DELETE_RULE_SET Procedure

This procedure deletes a rule set.

Syntax

DELETE_RULE_SET(
  rule_set_name VARCHAR2); 

Parameters

Table 11-23 DELETE_RULE_SET Parameter

Parameter Description

rule_set_name

Rule set name.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".


Example

EXEC DVSYS.DBMS_MACADM.DELETE_RULE_SET('Limit DBA Access'); 

11.3.9 RENAME_RULE Procedure

This procedure renames a rule. The name change takes effect everywhere the rule is used.

Syntax

RENAME_RULE(
  rule_name  VARCHAR2, 
  new_name   VARCHAR2); 

Parameters

Table 11-24 RENAME_RULE Parameters

Parameter Description

rule_name

Rule name.

To find existing rules in the current database instance, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, query DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE_SET_RULE View".

new_name

New rule name, up to 90 characters in mixed-case.


Example

BEGIN
 DVSYS.DBMS_MACADM.RENAME_RULE(
  rule_name  => 'Check UPDATE operations', 
  new_name   => 'Check Sector 2 Processes');
END; 

11.3.10 RENAME_RULE_SET Procedure

This procedure renames a rule set. The name change takes effect everywhere the rule set is used.

Syntax

RENAME_RULE_SET(
  rule_set_name VARCHAR2, 
  new_name      VARCHAR2); 

Parameters

Table 11-25 RENAME_RULE_SET Parameters

Parameter Description

rule_set_name

Current rule set name.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

new_name

New rule set name, up to 90 characters in mixed-case. Spaces are allowed.


Example

BEGIN
 DVSYS.DBMS_MACADM.RENAME_RULE_SET(
  rule_set_name => 'Limit DBA Access', 
  new_name      => 'Limit Sector 2 Access'); 
END;

11.3.11 SYNC_RULES Procedure

This procedure synchronizes the rules in Oracle Database Vault and Advanced Queuing Rules engine. You must perform this operation immediately after a rollback of an Add, Delete, or Modify rule operation.

Syntax

SYNC_RULES(); 

Parameters

None.

Example

EXEC DVSYS.DBMS_MACADM.SYNC_RULES(); 

11.3.12 UPDATE_RULE Procedure

This procedure updates a rule.

Syntax

UPDATE_RULE(
  rule_name  VARCHAR2, 
  rule_expr  VARCHAR2);

Parameters

Table 11-26 UPDATE_RULE Parameters

Parameter Description

rule_name

Rule name.

To find existing rules in the current database instance, query the DVSYS.DBA_DV_RULE view, described in "DBA_DV_RULE View".

To find rules that have been associated with rule sets, query DVSYS.DBA_DV_RULE_SET_RULE, described in "DBA_DV_RULE_SET_RULE View".

rule_expr

PL/SQL BOOLEAN expression.

If the expression contains quotation marks, do not use double quotation marks. Instead, use two single quotation marks. Enclose the entire expression within single quotation marks. For example:

'TO_CHAR(SYSDATE,''HH24'') = ''12'''

See "Creating a New Rule" for more information on rule expressions.

To find existing rule expressions, query the DVSYS.DBA_DV_RULE view.


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_RULE(
  rule_name  => 'Check UPDATE operations', 
  rule_expr  =>'SYS_CONTEXT(''USERENV'',''SESSION_USER'') = ''SYSADM'' AND
               (
                 UPPER(SYS_CONTEXT(''USERENV'',''MODULE'')) LIKE ''APPSRVR%'' OR
                 UPPER(SYS_CONTEXT(''USERENV'',''MODULE'')) LIKE ''DBAPP%'' )'
               );
END;

11.3.13 UPDATE_RULE_SET Procedure

This procedure updates a rule set.

Syntax

UPDATE_RULE_SET(
  rule_set_name    VARCHAR2,
  description      VARCHAR2, 
  enabled          VARCHAR2, 
  eval_options     NUMBER, 
  audit_options    NUMBER, 
  fail_options     NUMBER, 
  fail_message     VARCHAR2, 
  fail_code        NUMBER, 
  handler_options  NUMBER, 
  handler          VARCHAR2); 

Parameters

Table 11-27 UPDATE_RULE_SET Parameters

Parameter Description

rule_set_name

Rule set name.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

description

Description of the purpose of the rule set, up to 1024 characters in mixed-case.

enabled

Y (yes) enables rule set checking; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

eval_options

If you plan to assign more than one rule to the rule set, enter one of the following settings:

  • 1: All rules in the rule set must evaluate to true for the rule set itself to evaluate to true.

  • 2: At least one rule in the rule set must evaluate to true for the rule set itself to evaluate to true.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_EVAL_ALL

  • G_RULESET_EVAL_ANY

audit_options

Select one of the following settings:

  • 0: Disables auditing

  • POWER(2,0): Audits if the rule set evaluates to false (fails).

  • POWER(2,1): Audits whenever the rule set is used.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_AUDIT_OFF

  • G_RULESET_AUDIT_FAIL

  • G_RULESET_AUDIT_SUCCESS

See "Audit Options" for more information.

fail_options

Options for reporting factor errors:

  • 1: Shows an error message.

  • 2: Does not show an error message.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_FAIL_SHOW

  • G_RULESET_FAIL_SILENT

See "Error Handling Options" for more information.

fail_message

Error message for failure, up to 80 characters in mixed-case, to associate with the fail code you specify for fail_code.

fail_code

Enter a negative number in the range of -20000 to -20999, to associate with the fail_message.

handler_options

Select one of the following settings:

  • 0: Disables error handling.

  • POWER(2,0): Call handler on rule set failure.

  • POWER(2,1): Call handler on rule set success.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_RULESET_HANDLER_OFF

  • G_RULESET_HANDLER_FAIL

  • G_RULESET_HANDLER_SUCCESS

See "Error Handling Options" for more information.

handler

Name of the PL/SQL function or procedure that defines the custom event handler logic.

See "Error Handling Options" for more information.


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_RULE_SET(
  rule_set_name    => 'Limit DBA Access', 
  description      => 'DBA access through predefined processes', 
  enabled          => 'Y'
  eval_options     => 2,
  audit_options    => POWER(2,0),
  fail_options     => 1,
  fail_message     => 'Access denied!',
  fail_code        => -20900,
  handler_options  => 0, 
  handler          => '');
END;

11.4 Command Rule Procedures Within DVSYS.DBMS_MACADM

Table 11-28 lists procedures within the DVSYS.DBMS_MACADM package that you can use to configure command rules.

Chapter 6, "Configuring Command Rules" describes command rules in detail. See also Chapter 13, "Using the DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility procedures that you can use with the command rule procedures.

Table 11-28 DVSYS.DBMS_MACADM Command Rule Configuration Procedures

Procedure Description

CREATE_COMMAND_RULE Procedure

Creates a command rule and associates it with a rule set.

DELETE_COMMAND_RULE Procedure

Drops a command rule declaration.

UPDATE_COMMAND_RULE Procedure

Updates a command rule declaration.


11.4.1 CREATE_COMMAND_RULE Procedure

This procedure creates a command rule and associates it with a rule set.

Syntax

CREATE_COMMAND_RULE(
  command         VARCHAR2, 
  rule_set_name   VARCHAR2, 
  object_owner    VARCHAR2, 
  object_name     VARCHAR2, 
  enabled         VARCHAR2);

Parameters

Table 11-29 CREATE_COMMAND_RULE Parameters

Parameter Description

command

SQL statement to protect.

See the following:

rule_set_name

Name of rule set to associate with this command rule.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".

object_owner

Database schema owner for this command rule.

To find the available users, query the DBA_USERS view, described in Oracle Database Reference.

See also "Object Owner" in "Creating and Editing a Command Rule" for more information about command rule owners.

object_name

Object name. (The wildcard % is allowed. See "Object Name" in "Creating and Editing a Command Rule" for more information about objects protected by command rules.)

To find the available objects, query the ALL_OBJECTS view, described in Oracle Database Reference.

enabled

Y (yes) enables command rule checking; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_COMMAND_RULE(
  command         => 'SELECT', 
  rule_set_name   => 'Limit Sector 2 Access', 
  object_owner    => 'SYSADM', 
  object_name     => 'EMP_DATA', 
  enabled         => 'Y');
END; 

11.4.2 DELETE_COMMAND_RULE Procedure

This procedure drops a command rule declaration.

Syntax

DELETE_COMMAND_RULE(
  command      VARCHAR2, 
  object_owner VARCHAR2, 
  object_name  VARCHAR2); 

Parameters

Table 11-30 DELETE_COMMAND_RULE Parameters

Parameter Description

command

SQL statement the command rule protects.

To find available command rules, query the DVSYS.DBA_DV_COMMAND_RULE view, described in "DBA_DV_COMMAND_RULE View"

object_owner

Database schema owner for this command rule.

To find the available users in the current database instance, query the DBA_USERS view, described in Oracle Database Reference.

See also "Object Owner" in "Creating and Editing a Command Rule" for more information about command rule owners.

object_name

Object name. (The wildcard % is allowed. See "Object Name" in "Creating and Editing a Command Rule" for more information about objects protected by command rules.)

To find the available objects, query the ALL_OBJECTS view, described in Oracle Database Reference.


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_COMMAND_RULE(
  command      => 'SELECT', 
  object_owner => 'SYSADM', 
  object_name  => 'EMP_DATA'); 
END;

11.4.3 UPDATE_COMMAND_RULE Procedure

This procedure updates a command rule declaration.

Syntax

UPDATE_COMMAND_RULE(
  command        VARCHAR2, 
  rule_set_name  VARCHAR2, 
  object_owner   VARCHAR2, 
  object_name    VARCHAR2, 
  enabled        VARCHAR2); 

Parameters

Table 11-31 UPDATE_COMMAND_RULE Parameters

Parameter Description

command

SQL statement to protect.

See the following:

rule_set_name

Name of rule set to associate with this command rule.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "Oracle Database Vault Data Dictionary Views".

object_owner

Database schema owner for this command rule.

To find the available users, query the DBA_USERS view, described in Oracle Database Reference. See also "Object Owner" in "Creating and Editing a Command Rule" for more information about command rule owners.

object_name

Object name. (The wildcard % is allowed. See "Object Name" in "Creating and Editing a Command Rule" for more information about objects protected by command rules.)

To find the available objects, query the ALL_OBJECTS view, described in Oracle Database Reference.

enabled

Y (yes) enables command rule checking; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_COMMAND_RULE(
  command         => 'SELECT', 
  rule_set_name   => 'Limit Sector 2 Access', 
  object_owner    => 'SYSADM', 
  object_name     => '%', 
  enabled         => 'Y');
END;

11.5 Factor Procedures and Functions Within DVSYS.DBMS_MACADM

Table 11-32 lists procedures and functions within the DVSYS.DBMS_MACADM package that you can use to configure factors.

Chapter 7, "Configuring Factors" describes factors in detail. See also Chapter 13, "Using the DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility procedures that you can use with the factor procedures.

Table 11-32 DVSYS.DBMS_MACADM Factor Configuration Procedures

Procedure Description

ADD_FACTOR_LINK Procedure

Specifies a parent-child relationship for two factors.

ADD_POLICY_FACTOR Procedure

Specifies that the label for a factor contributes to the Oracle Label Security label for a policy.

CHANGE_IDENTITY_FACTOR Procedure

Associates an identity with a different factor.

CHANGE_IDENTITY_VALUE Procedure

Updates the value of an identity.

CREATE_DOMAIN_IDENTITY Procedure

Adds an Oracle Real Application Clusters (RAC) database node to the domain factor identities and labels it according to the Oracle Label Security policy.

CREATE_FACTOR Procedure

Creates a factor.

CREATE_FACTOR_TYPE Procedure

Creates a factor type.

CREATE_IDENTITY Procedure

Creates an identity.

CREATE_IDENTITY_MAP Procedure

Defines a set of tests that are used to derive the identity of a factor from the value of linked child factors (subfactors).

DELETE_FACTOR Procedure

Deletes a factor.

DELETE_FACTOR_LINK Procedure

Removes a parent-child relationship for two factors.

DELETE_FACTOR_TYPE Procedure

Deletes a factor type.

DELETE_IDENTITY Procedure

Removes an identity.

DELETE_IDENTITY_MAP Procedure

Removes an identity map from a factor.

DROP_DOMAIN_IDENTITY Procedure

Removes an Oracle Real Application Clusters (RAC) database node from a domain.

GET_INSTANCE_INFO Function

Returns information from the SYS.V_$INSTANCE view; returns a VARCHAR2 value.

GET_SESSION_INFO Function

Returns information from the SYS.V_$SESSION view for the current session; returns a VARCHAR2 value.

RENAME_FACTOR Procedure

Renames a factor. The name change takes effect everywhere the factor is used.

RENAME_FACTOR_TYPE Procedure

Renames a factor type. The name change takes effect everywhere the factor type is used.

UPDATE_FACTOR Procedure

Updates a factor.

UPDATE_FACTOR_TYPE Procedure

Updates the description of a factor type.

UPDATE_IDENTITY Procedure

Updates the trust_level of a factor identity.


11.5.1 ADD_FACTOR_LINK Procedure

This procedure specifies a parent-child relationship for two factors.

Syntax

ADD_FACTOR_LINK(
  parent_factor_name VARCHAR2, 
  child_factor_name  VARCHAR2, 
  label_indicator    VARCHAR2);

Parameters

Table 11-33 ADD_FACTOR_LINK Parameters

Parameter Description

parent_factor_name

Parent factor name.

To find existing parent and child factors in the current database instance, query the DVSYS.DBA_DV_FACTOR_LINK view, described in "DBA_DV_FACTOR_LINK View".

child_factor_name

Child factor name.

label_indicator

Indicates that the child factor being linked to the parent factor contributes to the label of the parent factor in an Oracle Label Security integration. Specify either Y (for Yes) or N (for No).

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

To find the Oracle Label Security policies and labels associated with factors, query the following views, described in "Oracle Database Vault Data Dictionary Views":

  • DVSYS.DBA_DV_MAC_POLICY: Lists Oracle Label Security policies defined in the current database instance.

  • DVSYS.DBA_DV_MAC_POLICY_FACTOR: Lists the factors that are associated with Oracle Label Security policies for the current database instance.

  • DVSYS.DBA_DV_POLICY_LABEL: Lists the Oracle Label Security label for each factor identifier in the DVSYS.DBA_DV_IDENTITY view for each policy.


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_FACTOR_LINK(
  parent_factor_name => 'HQ_ClientID', 
  child_factor_name  => 'Div1_ClientID', 
  label_indicator    => 'Y');
END;

11.5.2 ADD_POLICY_FACTOR Procedure

This procedure specifies that the label for a factor contributes to the Oracle Label Security label for a policy.

Syntax

ADD_POLICY_FACTOR(
  policy_name  VARCHAR2, 
  factor_name  VARCHAR2); 

Parameters

Table 11-34 ADD_POLICY_FACTOR Parameters

Parameter Description

policy_name

Oracle Label Security policy name.

To find the policies defined in the current database instance, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".

To find factors that are associated with Oracle Label Security policies, query DVSYS.DBA_DV_MAC_POLICY_FACTOR, described in "DBA_DV_MAC_POLICY_FACTOR View".

factor_name

Factor name.

To find existing factors, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".


Example

BEGIN
 DVSYS.DBMS_MACADM.ADD_POLICY_FACTOR(
  policy_name  => 'AccessData', 
  factor_name  => 'Sector2_ClientID'); 
END;

11.5.3 CHANGE_IDENTITY_FACTOR Procedure

This procedure associates an identity with a different factor.

Syntax

CHANGE_IDENTITY_FACTOR(
  factor_name     VARCHAR2, 
  value           VARCHAR2, 
  new_factor_name VARCHAR2); 

Parameters

Table 11-35 CHANGE_IDENTITY_FACTOR Parameters

Parameter Description

factor_name

Current factor name.

To find existing factors, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View"

value

Value of the identity to update.

To find existing identities for each factor in the current database instance, query the DVSYS.DBA_DV_IDENTITY view, described in "DBA_DV_IDENTITY View".

To find current identity mappings, query the DVSYS.DBA_DV_IDENTITY_MAP view, described in "DBA_DV_IDENTITY_MAP View".

new_factor_name

Name of the factor to associate with the identity.


Example

BEGIN
 DVSYS.DBMS_MACADM.CHANGE_IDENTITY_FACTOR(
  factor_name     => 'Sector2_ClientID', 
  value           => 'intranet', 
  new_factor_name => 'Sector4_ClientID'); 
END;

11.5.4 CHANGE_IDENTITY_VALUE Procedure

This procedure updates the value of an identity.

Syntax

CHANGE_IDENTITY_VALUE(
  factor_name  VARCHAR2, 
  value        VARCHAR2, 
  new_value    VARCHAR2); 

Parameters

Table 11-36 CHANGE_IDENTITY_VALUE Parameters

Parameter Description

factor_name

Factor name.

To find existing factors, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View"

value

Current value associated with the identity.

To find existing identities for each factor in the current database instance, query the DVSYS.DBA_DV_IDENTITY view, described in "DBA_DV_IDENTITY View".

To find current identity mappings, query the DVSYS.DBA_DV_IDENTITY_MAP view, described in "DBA_DV_IDENTITY_MAP View".

new_value

New identity value, up to 1024 characters in mixed-case.


Example

BEGIN
 DVSYS.DBMS_MACADM.CHANGE_IDENTITY_VALUE(
  factor_name  => 'Sector2_ClientID', 
  value        => 'remote', 
  new_value    => 'intranet, ');
END; 

11.5.5 CREATE_DOMAIN_IDENTITY Procedure

This procedure adds an Oracle Real Application Clusters (RAC) database node to the domain factor identities and labels it according to the Oracle Label Security policy.

Syntax

CREATE_DOMAIN_IDENTITY(
  domain_name  VARCHAR2, 
  domain_host  VARCHAR2, 
  policy_name  VARCHAR2 DEFAULT NULL, 
  domain_label VARCHAR2 DEFAULT NULL); 

Parameters

Table 11-37 CREATE_DOMAIN_IDENTITY Parameters

Parameter Description

domain_name

Name of the domain to which to add the host.

To find the logical location of the database within the network structure within a distributed database system, run the DVF.F$DATABASE_DOMAIN function, described in "Oracle Database Vault PL/SQL Factor Functions".

domain_host

Oracle Real Application Clusters host name being added to the domain.

To find host name of a database, query the DVF.F$DATABASE_HOSTNAME procedure, described in "Oracle Database Vault PL/SQL Factor Functions".

policy_name

Oracle Label Security policy name.

To find the available policies, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".

domain_label

Name of the domain to which to add the Oracle Label Security policy.


Examples

BEGIN
 DVSYS.DBMS_MACADM.CREATE_DOMAIN_IDENTITY(
  domain_name  => 'mycompany', 
  domain_host  => 'mydom_host', 
  policy_name  => 'AccessData', 
  domain_label => 'sensitive'); 
END;

11.5.6 CREATE_FACTOR Procedure

This procedure creates a factor. After you create a factor, you can give it an identity by using the CREATE_IDENTITY procedure, described in "CREATE_IDENTITY Procedure".

Syntax

CREATE_FACTOR(
  factor_name       VARCHAR2, 
  factor_type_name  VARCHAR2, 
  description       VARCHAR2, 
  rule_set_name     VARCHAR2, 
  get_expr          VARCHAR2, 
  validate_expr     VARCHAR2, 
  identify_by       NUMBER, 
  labeled_by        NUMBER, 
  eval_options      NUMBER, 
  audit_options     NUMBER, 
  fail_options      NUMBER); 

Parameters

Table 11-38 CREATE_FACTOR Parameters

Parameter Description

factor_name

Factor name, up to 30 characters in mixed-case, without spaces.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

factor_type_name

Category of the factor, up to 30 characters in mixed-case, without spaces.

description

Description of the purpose of the factor, up to 1024 characters in mixed-case.

rule_set_name

Rule set name if you want to use a rule set to control when and how a factor identity is set.

To find existing rule sets, query the DVSYS.DBA_DV_RULE_SET view, described in "Oracle Database Vault Data Dictionary Views". See also "Assignment Rule Set" for more information about assigning rule sets to factors.

get_expr

Valid PL/SQL expression that retrieves the identity of a factor. It can use up to 255 characters in mixed-case. See "Retrieval Method" for more information. See also the audit_options parameter.

validate_expr

Name of the procedure to validate the factor. This is a valid PL/SQL expression that returns a Boolean value (TRUE or FALSE) to validate the identity of the factor. See "Validation Method" for more information.

identify_by

Options for determining the identity of a factor, based on the expression set for the get_expr parameter:

  • 0: By constant

  • 1: By method

  • 2: By factor

  • 3: By context

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_IDENTIFY_BY_CONSTANT

  • G_IDENTIFY_BY_METHOD

  • G_IDENTIFY_BY_FACTOR

  • G_IDENTIFY_BY_CONTEXT

  • G_IDENTIFY_BY_RULESET

See "Factor Identification" for more information.

labeled_by

Options for labeling the factor:

  • 0: Labels the identities for the factor directly from the labels associated with an Oracle Label Security policy

  • 1: Derives the factor identity label from the labels of its child factor identities.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_LABELED_BY_SELF

  • G_LABELED_BY_FACTORS

See "Factor Labeling" for more information.

eval_options

Options for evaluating the factor when the user logs on:

  • 0: When the database session is created

  • 1: Each time the factor is accessed

  • 2: On start-up

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_EVAL_ON_SESSION

  • G_EVAL_ON_ACCESS

See "Evaluation" for more information.

audit_options

Options for auditing the factor if you want to generate a custom Oracle Database Vault audit record.

  • 0: Disables auditing.

  • POWER(2,0): Always audits.

  • POWER(2,1): Audits if get_expr returns an error.

  • POWER(2,2): Audits if get_expr is null.

  • POWER(2,3): Audits if the validation procedure returns an error.

  • POWER(2,4): Audits if the validation procedure is false.

  • POWER(2,5): Audits if there is no trust level set.

  • POWER(2,6): Audits if the trust level is negative.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_AUDIT_OFF

  • G_AUDIT_ALWAYS

  • G_AUDIT_ON_GET_ERROR

  • G_AUDIT_ON_GET_NULL

  • G_AUDIT_ON_VALIDATE_ERROR

  • G_AUDIT_ON_VALIDATE_FALSE

  • G_AUDIT_ON_TRUST_LEVEL_NULL

  • G_AUDIT_ON_TRUST_LEVEL_NEG

See "Audit Options" for more information.

fail_options

Options for reporting factor errors:

  • POWER(2,0): Shows an error message.

  • POWER(2,1): Does not show an error message.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_FAIL_WITH_MESSAGE

  • G_FAIL_SILENTLY

See "Error Options" for more information.


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_FACTOR(
  factor_name       => 'Sector2_DB', 
  factor_type_name  => 'Instance', 
  description       => ' ', 
  rule_set_name     => 'DB_access', 
  get_expr          => 'UPPER(SYS_CONTEXT('USERENV','DB_NAME'))', 
  validate_expr     => 'dbavowner.check_db_access', 
  identify_by       => 2, 
  labeled_by        => 0, 
  eval_options      => 0, 
  audit_options     => 0, 
  fail_options      => POWER(2,1)); 
END;

11.5.7 CREATE_FACTOR_TYPE Procedure

This procedure creates a user-defined factor type.

Syntax

CREATE_FACTOR_TYPE(
  name        VARCHAR2, 
  description VARCHAR2);

Parameters

Table 11-39 CREATE_FACTOR_TYPE Parameters

Parameter Description

name

Factor type name, up to 30 characters in mixed-case, without spaces.

To find existing factor types, query the DVSYS.DBA_DV_FACTOR_TYPE view, described in "DBA_DV_FACTOR_TYPE View".

description

Description of the purpose of the factor type, up to 1024 characters in mixed-case.


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_FACTOR_TYPE(
  name        => 'Sector2Instance', 
  description => 'Checks DB instances used in Sector 2');
END;

11.5.8 CREATE_IDENTITY Procedure

This procedure assigns an identity and an associated trust level for a given factor. After you create a factor, you must assign it an identity.

Syntax

CREATE_IDENTITY(
  factor_name  VARCHAR2, 
  value        VARCHAR2, 
  trust_level  NUMBER); 

Parameters

Table 11-40 CREATE_IDENTITY Parameters

Parameter Description

factor_name

Factor name.

To find existing factors, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

value

The actual value of the factor, up to 1024 characters in mixed-case. For example, the identity of an IP_Address factor could be the IP address of 234.43.41.99.

trust_level

Number that indicates the magnitude of trust relative to other identities for the same factor. In general, the higher the trust level number is set, the greater the trust. A trust level of 10 indicates "very trusted." Negative trust levels are not trusted.

See "Creating and Configuring a Factor Identity" for more information about trust levels and label security.


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_IDENTITY(
  factor_name  => 'Sector2_ClientID', 
  value        => 'intranet', 
  trust_level  => 5); 
END;

11.5.9 CREATE_IDENTITY_MAP Procedure

This procedure defines a set of tests that are used to derive the identity of a factor from the value of linked child factors (subfactors).

Syntax

CREATE_IDENTITY_MAP(
  identity_factor_name  VARCHAR2,
  identity_factor_value VARCHAR2, 
  parent_factor_name    VARCHAR2, 
  child_factor_name     VARCHAR2, 
  operation             VARCHAR2, 
  operand1              VARCHAR2, 
  operand2              VARCHAR2);

Parameters

Table 11-41 CREATE_IDENTITY_MAP Parameters

Parameter Description

identity_factor_name

Factor the identity map is for.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "Oracle Database Vault Data Dictionary Views".

identity_factor_value

Value the factor will assume if the identity map evaluates to TRUE.

To find existing factor identities, query the DVSYS.DBA_DV_IDENTITY view, described in "DBA_DV_IDENTITY View".

To find current factor identity mappings, use DVSYS.DBA_DV_IDENTITY_MAP, described in "DBA_DV_IDENTITY_MAP View".

parent_factor_name

The parent factor link to which the map is related.

To find existing parent-child factor mappings, query the DVSYS.DBA_DV_IDENTITY_MAP view, described in "DBA_DV_IDENTITY_MAP View".

child_factor_name

The child factor link to which the map is related.

operation

Relational operator for the identity map (for example, <, >, =, and so on).

operand1

Left operand for the relational operator; refers to the low value you enter.

operand2

Right operand for the relational operator; refers to the high value you enter.


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_IDENTITY_MAP(
  identity_factor_name  => 'Sector2_ClientID',
  identity_factor_value => 'intranet', 
  parent_factor_name    => 'HQ_ClientID', 
  child_factor_name     => 'Div1_ClientID', 
  operation             => '<', 
  operand1              => '123.45.78.890', 
  operand2              => '988.77.56.123');
END;

11.5.10 DELETE_FACTOR Procedure

This procedure deletes a factor.

Syntax

DELETE_FACTOR(
  factor_name VARCHAR2);

Parameters

Table 11-42 DELETE_FACTOR Parameter

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".


Example

EXEC DVSYS.DBMS_MACADM.DELETE_FACTOR('Sector2_ClientID');

11.5.11 DELETE_FACTOR_LINK Procedure

This procedure removes a parent-child relationship for two factors.

Syntax

DELETE_FACTOR_LINK(
  parent_factor_name VARCHAR2, 
  child_factor_name  VARCHAR2); 

Parameters

Table 11-43 DELETE_FACTOR_LINK Parameters

Parameter Description

parent_factor_name

Factor name.

To find factors that are used in parent-child mappings in the current database instance, query the DVSYS.DBA_DV_FACTOR_LINK view, described in "DBA_DV_FACTOR_LINK View".

child_factor_name

Factor name.


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_FACTOR_LINK(
  parent_factor_name => 'HQ_ClientID', 
  child_factor_name  => 'Div1_ClientID'); 
END;

11.5.12 DELETE_FACTOR_TYPE Procedure

This procedure deletes a factor type.

Syntax

DELETE_FACTOR_TYPE(
  name VARCHAR2);

Parameters

Table 11-44 DELETE_FACTOR_TYPE Parameters

Parameter Description

name

Factor type name.

To find existing factor types, query the DVSYS.DBA_DV_FACTOR_TYPE view, described in "DBA_DV_FACTOR_TYPE View".


Example

EXEC DVSYS.DBMS_MACADM.DELETE_FACTOR_TYPE('Sector2Instance');

11.5.13 DELETE_IDENTITY Procedure

This procedure removes an identity from an existing factor.

Syntax

DELETE_IDENTITY(
  factor_name VARCHAR2, 
  value       VARCHAR2); 

Parameters

Table 11-45 DELETE_IDENTITY Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

value

Identity value associated with the factor.

To find the identities for each factor in the current database instance, query the DVSYS.DBA_DV_IDENTITY view, described in "DBA_DV_IDENTITY View".


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_IDENTITY(
  factor_name => 'Sector2_ClientID', 
  value       => 'intranet, '); 
END;

11.5.14 DELETE_IDENTITY_MAP Procedure

This procedure removes an identity map for a factor.

Syntax

DELETE_IDENTITY_MAP(
  identity_factor_name  VARCHAR2, 
  identity_factor_value VARCHAR2,
  parent_factor_name    VARCHAR2, 
  child_factor_name     VARCHAR2, 
  operation             VARCHAR2, 
  operand1              VARCHAR2, 
  operand2              VARCHAR2); 

Parameters

Table 11-46 DELETE_IDENTITY_MAP Parameters

Parameter Description

identity_factor_name

Factor the identity map is for.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

identity_factor_value

Value the factor will assume if the identity map evaluates to TRUE.

To find existing factor identities, query the DVSYS.DBA_DV_IDENTITY view, described in "DBA_DV_IDENTITY View".

To find current factor identity mappings, query DVSYS.DBA_DV_IDENTITY_MAP, described in "DBA_DV_IDENTITY_MAP View".

parent_factor_name

The parent factor link to which the map is related.

To find existing parent-child factors, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR_LINK View".

child_factor_name

The child factor to which the map is related.

operation

Relational operator for the identity map (for example, <, >, =, and so on).

operand1

Left (low value) operand for the relational operator.

operand2

Right (high value) operand for the relational operator.


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_IDENTITY_MAP(
  identity_factor_name  => 'Sector2_ClientID',
  identity_factor_value => 'intranet', 
  parent_factor_name    => 'HQ_ClientID', 
  child_factor_name     => 'Div1_ClientID', 
  operation             => '<', 
  operand1              => '123.45.78.890', 
  operand2              => '988.77.56.123');
END;

11.5.15 DROP_DOMAIN_IDENTITY Procedure

This procedure removes an Oracle Real Application Clusters database node from a domain.

Syntax

DROP_DOMAIN_IDENTITY(
  domain_name  VARCHAR2, 
  domain_host  VARCHAR2); 

Parameters

Table 11-47 DROP_DOMAIN_IDENTITY Parameters

Parameter Description

domain_name

Name of the domain to which the host was added.

To find the domain of a database as specified by the DB_DOMAIN initialization parameter, run the DVF.F$DATABASE_DOMAIN function, described in "Oracle Database Vault PL/SQL Factor Functions".

domain_host

Oracle Real Application Clusters host name being that was added to the domain.

To find the host name for a specified database, run the DVF.F$DATABASE_HOSTNAME function, described in "Oracle Database Vault PL/SQL Factor Functions".


Example

BEGIN
 DVSYS.DBMS_MACADM.DROP_DOMAIN_IDENTITY(
  domain_name  => 'mycompany', 
  domain_host  => 'mydom_host'); 
END;

11.5.16 GET_INSTANCE_INFO Function

This function returns information from the SYS.V_$INSTANCE view; it returns a VARCHAR2 value. For more information about SYS.V_$INSTANCE, see Oracle Database Reference.

Syntax

GET_INSTANCE_INFO(
  p_parameter VARCHAR2)
RETURNS VARCHAR2; 

Parameters

Table 11-48 GET_INSTANCE_INFO Parameter

Parameter Description

p_parameter

Column name in the SYS.V_$INSTANCE view. See Oracle Database Reference for a listing of the SYS.V_$INSTANCE columns.


Example

DECLARE
 instance_var varchar2 := null;
BEGIN 
 instance_var = DVSYS.DBMS_MACADM.GET_INSTANCE_INFO('INSTANCE_NAME'); 
END;

11.5.17 GET_SESSION_INFO Function

This function returns information from the SYS.V_$SESSION view for the current session; it returns a VARCHAR2 value. For more information about SYS.V_$SESSION, see Oracle Database Reference.

Syntax

GET_SESSION_INFO(
  p_parameter VARCHAR2)
RETURNS VARCHAR2;

Parameters

Table 11-49 GET_SESSION_INFO Parameter

Parameter Description

p_parameter

Column name in the SYS.V_$SESSION view.See Oracle Database Reference for a listing of the SYS.V_$SESSION columns.


Example

DECLARE
 session_var varchar2 := null;
BEGIN 
 session_var = DVSYS.DBMS_MACADM.GET_SESSION_INFO('PROCESS'); 
END;

11.5.18 RENAME_FACTOR Procedure

This procedure renames a factor. The name change takes effect everywhere the factor is used.

Syntax

RENAME_FACTOR(
  factor_name     VARCHAR2, 
  new_factor_name VARCHAR2);

Parameters

Table 11-50 RENAME_FACTOR Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

new_factor_name

New factor name, up to 30 characters in mixed-case, without spaces.


Example

BEGIN
 DVSYS.DBMS_MACADM.RENAME_FACTOR(
  factor_name     => 'Sector2_ClientID', 
  new_factor_name => 'Sector2_Clients');
END;

11.5.19 RENAME_FACTOR_TYPE Procedure

This procedure renames a factor type. The name change takes effect everywhere the factor type is used.

Syntax

RENAME_FACTOR_TYPE(
  old_name  VARCHAR2, 
  new_name  VARCHAR2); 

Parameters

Table 11-51 RENAME_FACTOR_TYPE Parameters

Parameter Description

old_name

Current factor type name.

To find existing factor types in the current database instance, query the DVSYS.DBA_DV_FACTOR_TYPE view, described in "DBA_DV_FACTOR_TYPE View".

new_name

New factor type name, up to 30 characters in mixed-case, without spaces.


Example

BEGIN
 DVSYS.DBMS_MACADM.RENAME_FACTOR_TYPE(
  old_name  => 'Sector2Instance', 
  new_name  => 'Sector2DBInstance'); 
END;

11.5.20 UPDATE_FACTOR Procedure

This procedure updates the description of a factor type.

Syntax

UPDATE_FACTOR(
  factor_name       VARCHAR2, 
  factor_type_name  VARCHAR2, 
  description       VARCHAR2, 
  rule_set_name     VARCHAR2, 
  get_expr          VARCHAR2, 
  validate_expr     VARCHAR2, 
  identify_by       NUMBER, 
  labeled_by        NUMBER, 
  eval_options      NUMBER, 
  audit_options     NUMBER, 
  fail_options      NUMBER); 

Parameters

Table 11-52 UPDATE_FACTOR

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

factor_type_name

Factor type name.

To find existing factor types, query the DVSYS.DBA_DV_FACTOR_TYPE view, described in "DBA_DV_FACTOR_TYPE View".

description

Description of the purpose of the factor, up to 1024 characters in mixed-case.

rule_set_name

Name of the rule set used to control when and how a factor identity is set.

To find existing rule sets, query the DVSYS.DBA_DV_RULE_SET view, described in "Oracle Database Vault Data Dictionary Views".

See also "Assignment Rule Set" for more information about assigning rule sets to factors.

get_expr

Valid PL/SQL expression that retrieves the identity of a factor. It can use up to 255 characters in mixed-case. See "Retrieval Method" for more information. See also the audit_options parameter.

validate_expr

Name of the procedure to validate factor. This is a valid PL/SQL expression that returns a Boolean value (TRUE or FALSE) to validate the identity of the factor. See "Validation Method" for more information.

identify_by

Options for determining the identity of a factor, based on the expression set for the get_expr parameter:

  • 0: By constant

  • 1: By method

  • 2: By factor

  • 3: By context

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_IDENTIFY_BY_CONSTANT

  • G_IDENTIFY_BY_METHOD

  • G_IDENTIFY_BY_FACTOR

  • G_IDENTIFY_BY_CONTEXT

See "Factor Identification" for more information.

labeled_by

Options for labeling the factor:

  • 0: Labels the identities for the factor directly from the labels associated with an Oracle Label Security policy

  • 1: Derives the factor identity label from the labels of its child factor identities.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_LABELED_BY_SELF

  • G_LABELED_BY_FACTORS

See "Factor Labeling" for more information.

eval_options

Options for evaluating the factor when the user logs on:

  • 0: When the database session is created

  • 1: Each time the factor is accessed

  • 2: On start-up

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_EVAL_ON_SESSION

  • G_EVAL_ON_ACCESS

See "Evaluation" for more information.

audit_options

Options for auditing the factor if you want to generate a custom Oracle Database Vault audit record.

  • 0: Disables auditing.

  • POWER(2,0): Always audits.

  • POWER(2,1): Audits if get_expr returns an error.

  • POWER(2,2): Audits if get_expr is null.

  • POWER(2,3): Audits if the validation procedure returns an error.

  • POWER(2,4): Audits if the validation procedure is false.

  • POWER(2,5): Audits if there is no trust level set.

  • POWER(2,6): Audits if the trust level is negative.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_AUDIT_OFF

  • G_AUDIT_ALWAYS

  • G_AUDIT_ON_GET_ERROR

  • G_AUDIT_ON_GET_NULL

  • G_AUDIT_ON_VALIDATE_ERROR

  • G_AUDIT_ON_VALIDATE_FALSE

  • G_AUDIT_ON_TRUST_LEVEL_NULL

  • G_AUDIT_ON_TRUST_LEVEL_NEG

See "Audit Options" for more information.

fail_options

Options for reporting factor errors:

  • POWER(2,0): Shows an error message.

  • POWER(2,1): Does not show an error message.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_FAIL_WITH_MESSAGE

  • G_FAIL_SILENTLY

See "Error Options" for more information.


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_FACTOR(
  factor_name       => 'Sector2_DB', 
  factor_type_name  => 'Instance', 
  description       => ' ', 
  rule_set_name     => 'DB_access', 
  get_expr          => 'UPPER(SYS_CONTEXT('USERENV','DB_NAME'))', 
  validate_expr     => 'dbavowner.check_db_access', 
  identify_by       => 2, 
  labeled_by        => 0, 
  eval_options      => 0, 
  audit_options     => POWER(2,0), 
  fail_options      => POWER(2,0)); 
END;

11.5.21 UPDATE_FACTOR_TYPE Procedure

This procedure updates a factor type.

Syntax

UPDATE_FACTOR_TYPE(
  name         VARCHAR2, 
  description  VARCHAR2);

Parameters

Table 11-53 UPDATE_FACTOR_TYPE Parameters

Parameter Description

name

Factor type name.

To find existing factor types in the current database instance, query the DVSYS.DBA_DV_FACTOR_TYPE view, described in "DBA_DV_FACTOR_TYPE View".

description

Description of the purpose of the factor type, up to 1024 characters in mixed-case.


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_FACTOR_TYPE(
  name        => 'Sector2DBInstance', 
  description => 'Checks DB instances used in Sector 2');
END;

11.5.22 UPDATE_IDENTITY Procedure

This procedure updates the trust level of a factor identity.

Syntax

UPDATE_IDENTITY(
  factor_name  VARCHAR2, 
  value        VARCHAR2, 
  trust_level  NUMBER); 

Parameters

Table 11-54 UPDATE_IDENTITY Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, query the DBSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

To find factors that have identities, query DVSYS.DBA_DV_IDENTITY, described in "DBA_DV_IDENTITY View".

value

New factor identity, up to 1024 characters in mixed-case. For example, the identity of an IP_Address factor could be the IP address of 234.43.41.99.

trust_level

Number that indicates the magnitude of trust relative to other identities for the same factor. In general, the higher the trust level number is set, the greater the trust. A trust level of 10 indicates "very trusted." Negative trust levels are not trusted.

See "Creating and Configuring a Factor Identity" for more information about trust levels and label security.


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_IDENTITY(
  factor_name  => 'Sector2_ClientID', 
  value        => 'intranet', 
  trust_level  => 10); 
END;

11.6 Secure Application Role Procedures Within DVSYS.DBMS_MACADM

Table 11-55 lists procedures within the DVSYS.DBMS_MACADM package that you can use to configure Oracle Database Vault secure application roles.

Chapter 8, "Configuring Secure Application Roles for Oracle Database Vault" describes secure application roles in detail. See also Chapter 13, "Using the DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility procedures that you can use with the secure application role procedures.

Table 11-55 DVSYS.DBMS_MACADM Secure Application Role Configuration Procedures

Procedure Description

CREATE_ROLE Procedure

Creates an Oracle Database Vault secure application role.

DELETE_ROLE Procedure

Deletes an Oracle Database Vault secure application role.

RENAME_ROLE Procedure

Renames an Oracle Database Vault secure application role. The name change takes effect everywhere the role is used.

UPDATE_ROLE Procedure

Updates a Oracle Database Vault secure application role.


11.6.1 CREATE_ROLE Procedure

This procedure creates an Oracle Database Vault secure application role.

Syntax

CREATE_ROLE(
  role_name      VARCHAR2, 
  enabled        VARCHAR2,
  rule_set_name  VARCHAR2);

Parameters

Table 11-56 CREATE_ROLE Parameters

Parameter Description

role_name

Role name, up to 30 characters, with no spaces. Preferably, enter the role name in upper case letters, though you are not required to do so. Ensure that this name follows the standard Oracle naming conventions for role creation described in Oracle Database SQL Reference.

To find existing secure application roles in the current database instance, query the DVSYS.DBA_DV_ROLE view, described in "DBA_DV_ROLE View".

enabled

Y (yes) enables role checking; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

rule_set_name

Name of rule set to determine whether a user can set this secure application role.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_ROLE(
  role_name      => 'Sector2_APP_MGR>, 
  enabled        => 'Y',
  rule_set_name  => 'Check App2 Access');
END;

11.6.2 DELETE_ROLE Procedure

This procedure deletes an Oracle Database Vault secure application role.

Syntax

DELETE_ROLE(
  role_name VARCHAR2); 

Parameters

Table 11-57 DELETE_ROLE Parameter

Parameter Description

role_name

Role name.

To find existing secure application roles in the current database instance, query the DVSYS.DBA_DV_ROLE view, described in "DBA_DV_ROLE View".


Example

EXEC DVSYS.DBMS_MACADM.DELETE_ROLE('SECT2_APP_MGR'); 

11.6.3 RENAME_ROLE Procedure

This procedure renames an Oracle Database Vault secure application role. The name change takes effect everywhere the role is used.

Syntax

RENAME_ROLE(
  role_name      VARCHAR2, 
  new_role_name  VARCHAR2);

Parameters

Table 11-58 RENAME_ROLE Parameters

Parameter Description

role_name

Role name.

To find existing secure application roles in the current database instance, query the DVSYS.DBA_DV_ROLE view, described in "DBA_DV_ROLE View".

new_role_name

Role name, up to 30 characters, in uppercase, with no spaces. Ensure that this name follows the standard Oracle naming conventions for role creation described in Oracle Database SQL Reference.


Example

BEGIN
 DVSYS.DBMS_MACADM.RENAME_ROLE(
  role_name      => 'SECT2_APP_MGR', 
  new_role_name  => 'SECT2_SYSADMIN', );
END;

11.6.4 UPDATE_ROLE Procedure

This procedure updates a Oracle Database Vault secure application role.

Syntax

UPDATE_ROLE(
  role_name      VARCHAR2, 
  enabled        VARCHAR2, 
  rule_set_name  VARCHAR2);

Parameters

Table 11-59 UPDATE_ROLE Parameters

Parameter Description

role_name

Role name.

To find existing secure application roles in the current database instance, query the DVSYS.DBA_DV_ROLE view, described in "DBA_DV_ROLE View".

enabled

Y (yes) enables the role; N (no) disables it. The default is Y.

You can also use the following DVSYS.DBMS_MACUTL constants:

  • G_YES

  • G_NO

rule_set_name

Name of rule set to determine whether a user can set this secure application role.

To find existing rule sets in the current database instance, query the DVSYS.DBA_DV_RULE_SET view, described in "DBA_DV_RULE_SET View".


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_ROLE(
  role_name      => 'SECT2_SYSADMIN', 
  enabled        => 'Y', 
  rule_set_name  => 'System Access Controls');
END;

11.7 Oracle Label Security Policy Procedures Within DVSYS.DBMS_MACADM

Table 11-60 lists procedures within the DVSYS.DBMS_MACADM package that you can use to configure Oracle Label Security policies.

Chapter 9, "Integrating Oracle Database Vault with Other Oracle Products" describes Oracle Label Security policies in detail. See also Chapter 13, "Using the DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility procedures that you can use with the Oracle Label Security policy procedures.

Table 11-60 DVSYS.DBMS_MACADM Oracle Label Security Configuration Procedures

Procedure Description

CREATE_MAC_POLICY Procedure

Specifies the algorithm that is used to merge labels when computing the label for a factor, or the Oracle Label Security Session label.

CREATE_POLICY_LABEL Procedure

Labels an identity within an Oracle Label Security policy.

DELETE_MAC_POLICY_CASCADE Procedure

Deletes all Oracle Database Vault objects related to an Oracle Label Security policy.

DELETE_POLICY_FACTOR Procedure

Removes the factor from contributing to the Oracle Label Security label.

DELETE_POLICY_LABEL Procedure

Removes the label from an identity within an Oracle Label Security policy.

UPDATE_MAC_POLICY Procedure

Specifies the algorithm that is used to merge labels when computing the label for a factor, or the Oracle Label Security Session label.


11.7.1 CREATE_MAC_POLICY Procedure

This procedure specifies the algorithm that is used to merge labels when computing the label for a factor, or the Oracle Label Security Session label.

Syntax

CREATE_MAC_POLICY(
  policy_name  VARCHAR2,
  algorithm    VARCHAR2);

Parameters

Table 11-61 CREATE_MAC_POLICY Parameters

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".

algorithm

Merge algorithm for cases when Oracle Label Security has merged two labels. Enter the code listed in Table 11-62 that corresponds to the merge algorithm you want. For example, enter HUU to if you want to select the Maximum Level/Union/Union merge algorithm.

For more information on label-merging algorithms, see Oracle Label Security Administrator's Guide.


Table 11-62 Oracle Label Security Merge Algorithm Codes

Code Value

HUU

Maximum Level/Union/Union

HIU

Maximum Level/Intersection/Union

HMU

Maximum Level/Minus/Union

HNU

Maximum Level/Null/Union

HUI

Maximum Level/Union/Intersection

HII

Maximum Level/Intersection/Intersection

HMI

Maximum Level/Minus/Intersection

HNI

Maximum Level/Null/Intersection

HUM

Maximum Level/Union/Minus

HIM

Maximum Level/Intersection/Minus

HMM

Maximum Level/Minus/Minus

HNM

Maximum Level/Null/Minus

HUN

Maximum Level/Union/Null

HIN

Maximum Level/Intersection/Null

HMN

Maximum Level/Minus/Null

HNN

Maximum Level/Null/Null

LUU

Minimum Level/Union/Union

LIU

Minimum Level/Intersection/Union

LMU

Minimum Level/Minus/Union

LNU

Minimum Level/Null/Union

LUI

Minimum Level/Union/Intersection

LII

Minimum Level/Intersection/Intersection

LMI

Minimum Level/Minus/Intersection

LNI

Minimum Level/Null/Intersection

LUM

Minimum Level/Union/Minus

LIM

Minimum Level/Intersection/Minus

LMM

Minimum Level/Minus/Minus

LNM

Minimum Level/Null/Minus

LUN

Minimum Level/Union/Null

LIN

Minimum Level/Intersection/Null

LMN

Minimum Level/Minus/Null

LNN

Minimum Level/Null/Null


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_MAC_POLICY(
  policy_name  => 'Access Locations',
  algorithm    => 'HUU');
END;

11.7.2 CREATE_POLICY_LABEL Procedure

This procedure labels an identity within an Oracle Label Security policy.

Syntax

CREATE_POLICY_LABEL(
  identity_factor_name   VARCHAR2, 
  identity_factor_value  VARCHAR2, 
  policy_name            VARCHAR2, 
  label                  VARCHAR2); 

Parameters

Table 11-63 CREATE_POLICY_LABEL Parameters

Parameter Description

identity_factor_name

Name of factor being labeled.

To find existing factors in the current database instance, query the DVSYS.DBA_DV_FACTOR view, described in "DBA_DV_FACTOR View".

To find factors that are associated with Oracle Label Security policies, use DVSYS.DBA_DV_MAC_POLICY_FACTOR, described in "DBA_DV_MAC_POLICY_FACTOR View".

See also "Label Security Policy Factors" for more information.

identity_factor_value

Value of identity for the factor being labeled.

To find the identities of existing factors in the current database instance, query the DVSYS.DBA_DV_IDENTITY view, described in "DBA_DV_IDENTITY View".

policy_name

Name of existing policy.

To find existing policies in the current database instance, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".

label

Oracle Label Security label name.

To find existing policy labels for factor identifiers, query the DVSYS.DBA_DV_POLICY_LABEL view, described in "DBA_DV_POLICY_LABEL View".


Example

BEGIN
 DVSYS.DBMS_MACADM.CREATE_POLICY_LABEL(
  identity_factor_name   => 'App_Host_Name', 
  identity_factor_value  => 'Sect2_Fin_Apps', 
  policy_name            => 'Access Locations', 
  label                  => 'Sensitive'); 
END;

11.7.3 DELETE_MAC_POLICY_CASCADE Procedure

This procedure deletes all Oracle Database Vault objects related to an Oracle Label Security policy.

Syntax

DELETE_MAC_POLICY_CASCADE(
  policy_name  VARCHAR2); 

Parameters

Table 11-64 DELETE_MAC_POLICY_CASCADE Parameter

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".


Example

EXEC DVSYS.DBMS_MACADM.DELETE_MAC_POLICY_CASCADE('Access Locations'); 

11.7.4 DELETE_POLICY_FACTOR Procedure

This procedure removes the factor from contributing to the Oracle Label Security label.

Syntax

DELETE_POLICY_FACTOR(
  policy_name  VARCHAR2, 
  factor_name  VARCHAR2); 

Parameters

Table 11-65 DELETE_POLICY_FACTOR Parameters

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".

factor_name

Name of factor associated with the Oracle Label Security label.

To find factors that are associated with Oracle Label Security policies, query DVSYS.DBA_DV_MAC_POLICY_FACTOR, described in "DBA_DV_MAC_POLICY_FACTOR View".


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_POLICY_FACTOR(
  policy_name  => 'Access Locations', 
  factor_name  => 'App_Host_Name',); 
END;

11.7.5 DELETE_POLICY_LABEL Procedure

This procedure removes the label from an identity within an Oracle Label Security policy.

Syntax

DELETE_POLICY_LABEL(
  identity_factor_name   VARCHAR2, 
  identity_factor_value  VARCHAR2, 
  policy_name            VARCHAR2, 
  label                  VARCHAR2); 

Parameters

Table 11-66 DELETE_POLICY_LABEL Parameters

Parameter Description

identity_factor_name

Name of factor that was labeled.

To find existing factors in the current database instance that are associated with Oracle Label Security policies, query DVSYS.DBA_DV_MAC_POLICY_FACTOR, described in "DBA_DV_MAC_POLICY_FACTOR View".

See also "Label Security Policy Factors" for more information.

identity_factor_value

Value of identity for the factor that was labeled.

To find the identities of existing factors in the current database instance, query the DVSYS.DBA_DV_IDENTITY view, described in "DBA_DV_IDENTITY View".

policy_name

Name of existing policy.

To find existing policies in the current database instance, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".

label

Oracle Label Security label name.

To find existing policy labels for factor identifiers, query the DVSYS.DBA_DV_POLICY_LABEL view, described in "DBA_DV_POLICY_LABEL View".


Example

BEGIN
 DVSYS.DBMS_MACADM.DELETE_POLICY_LABEL(
  identity_factor_name   => 'App_Host_Name', , 
  identity_factor_value  => 'Sect2_Fin_Apps', 
  policy_name            => 'Access Locations', 
  label                  => 'Sensitive'); 
END;

11.7.6 UPDATE_MAC_POLICY Procedure

This procedure specifies the algorithm that is used to merge labels when computing the label for a factor, or the Oracle Label Security Session label.

Syntax

UPDATE_MAC_POLICY(
  policy_name  VARCHAR2, 
  algorithm    VARCHAR2); 

Parameters

Table 11-67 UPDATE_MAC_POLICY

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, query the DVSYS.DBA_DV_MAC_POLICY view, described in "DBA_DV_MAC_POLICY View".

algorithm

Merge algorithm for cases when Oracle Label Security has merged two labels. See Table 11-62 for listing of the available algorithms.

For more information on label-merging algorithms, see Oracle Label Security Administrator's Guide.


Example

BEGIN
 DVSYS.DBMS_MACADM.UPDATE_MAC_POLICY(
  policy_name  => 'Access Locations',
  algorithm    => 'LUI');
END;