E Oracle Database Vault DVSYS.DBMS_MACADM Package

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

This section includes the following topics:

Realm Functions Within DVSYS.DBMS_MACADM
Rule Set Functions Within DVSYS.DBMS_MACADM
Command Rule Functions Within DVSYS.DBMS_MACADM
Factor Functions Within DVSYS.DBMS_MACADM
Secure Application Role Functions Within DVSYS.DBMS_MACADM
Oracle Label Security Policy Functions Within DVSYS.DBMS_MACADM

E.1 Realm Functions Within DVSYS.DBMS_MACADM

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

Chapter 4, "Configuring Realms" describes realms in detail. See also Appendix G, "Oracle Database Vault DVSYS.DBMS_MACUTL Package" for a set of general purpose utility functions that you can use with the realm functions.

Table E-1 DVSYS.DBMS_MACADM Realm Configuration Functions

Function	Description
ADD_AUTH_TO_REALM Function	Authorizes a user or role to access a realm as a participant.
ADD_AUTH_TO_REALM Function	Authorizes a user or role to access a realm as an owner or participant (no rule set).
ADD_AUTH_TO_REALM Function	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 Function	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 Function	Registers a set of objects for realm protection.
CREATE_REALM Function	Creates a realm.
DELETE_AUTH_FROM_REALM Function	Removes the authorization of a user or role to access a realm.
DELETE_OBJECT_FROM_REALM Function	Removes a set of objects from realm protection.
DELETE_REALM Function	Deletes a realm.
DELETE_REALM_CASCADE Function	Deletes a realm, including its related Database Vault configuration information.
RENAME_REALM Function	Renames a realm. The name change takes effect everywhere the realm is used.
UPDATE_REALM Function	Updates a realm.
UPDATE_REALM_AUTH Function	Updates the authorization of a user or role to access a realm.

E.1.1 ADD_AUTH_TO_REALM Function

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

Syntax

ADD_AUTH_TO_REALM(
  realm_name  VARCHAR2, 
  grantee     VARCHAR2);

Parameters

Table E-2 ADD_AUTH_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, use the DBA_DV_REALMS view, described in "Oracle Database Vault Public Views".

grantee

User or role name to authorize as a participant.

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

To find the authorization of a particular user or role, use the DVA_DV_REALM_AUTH view. To find existing secure application roles used in privilege management, use the DBA_DV_ROLE view. Both are described in "Oracle Database Vault Public Views".

E.1.2 ADD_AUTH_TO_REALM Function

This function authorizes a user or role to access a realm as an owner or a participant. The person running this function 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 E-3 ADD_AUTH_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, use the DBA_DV_REALMS view, described in "Oracle Database Vault Public Views".

grantee

User or role name to authorize as owner or participant.

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

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.

E.1.3 ADD_AUTH_TO_REALM Function

This function authorizes a user or role to access a realm as a participant. The person running this function 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 E-4 ADD_AUTH_TO_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, use the DBA_DV_REALMS view, described in "Oracle Database Vault Public Views".

grantee

User or role name to authorize as participant.

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

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, use the DBA_DV_RULE_SET view. To find rules that are associated with the rule sets, use the DBA_DB_RULE_SET_RULE view. Both are described in "Oracle Database Vault Public Views".

E.1.4 ADD_AUTH_TO_REALM Function

This function authorizes a user or role to access a realm as a participant or owner. The person running this function 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 E-5 ADD_AUTH_TO_REALM Parameters

Parameter	Description
`realm_name`	Realm name. To find the existing realms in the current database instance, use the `DBA_DV_REALMS` view, described in "Oracle Database Vault Public Views".
`grantee`	User or role name to authorize as owner or participant. To find the available users and roles, use the `DBA_USERS` and `DBA_ROLES` views, described in Oracle Database Reference. To find the authorization of a particular user or role, use the `DVA_DV_REALM_AUTH` view, described in "Oracle Database Vault Public Views".
`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, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public Views".
`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.

E.1.5 ADD_OBJECT_TO_REALM Function

This function 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 E-6 ADD_OBJECT_TO_REALM Parameters

Parameter	Description
`realm_name`	Realm name. To find the existing realms in the current database instance, use the `DBA_DV_REALMS` view, described in "Oracle Database Vault Public Views".
`object_owner`	Object owner to own this realm. To find the available users, use the `DBA_USERS` view, described in Oracle Database Reference. To find the authorization of a particular user, use the `DVA_DV_REALM_AUTH` view, described in "Oracle Database Vault Public Views".
`object_name`	Object name. (The wildcard % is allowed. See "Object Name" under "Creating Realm-Secured Objects" for exceptions to the wildcard %.) To find the available objects, use the `ALL_OBJECTS` view, described in Oracle Database Reference. To find objects that are secured by existing realms, use the `DBA_DV_REALM_OBJECT` view, described in "Oracle Database Vault Public Views".
`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 %.)

E.1.6 CREATE_REALM Function

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

ADD_OBJECT_TO_REALM function registers one or more objects for the realm.
ADD_AUTH_TO_REALM functions authorize users or roles for the realm.

Syntax

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

Parameters

Table E-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, use the `DBA_DV_REALMS` view, described in "Oracle Database Vault Public Views".
`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`.
`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.

E.1.7 DELETE_AUTH_FROM_REALM Function

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

Syntax

DELETE_AUTH_FROM_REALM(
  realm_name VARCHAR2,
  grantee    VARCHAR2);

Parameters

Table E-8 DELETE_AUTH_FROM_REALM Parameters

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, use the DBA_DV_REALMS view, described in "Oracle Database Vault Public Views".

grantee

User or role name.

To find the authorization of a particular user or role, use the DVA_DV_REALM_AUTH view, described in "Oracle Database Vault Public Views".

E.1.8 DELETE_OBJECT_FROM_REALM Function

This function 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 E-9 DELETE_OBJECT_FROM_REALM Parameters

Parameter	Description
`realm_name`	Realm name. To find the existing realms in the current database instance, use the `DBA_DV_REALMS` view, described in "Oracle Database Vault Public Views".
`object_owner`	Database schema owner. To find the available users, use the `DBA_USERS` view, described in Oracle Database Reference. To find the authorization of a particular user, use the `DVA_DV_REALM_AUTH` view, described in "Oracle Database Vault Public Views".
`object_name`	Object name. (The wildcard % is allowed. See "Object Name" under "Creating Realm-Secured Objects" for exceptions to the wildcard %.) To find objects that are secured by existing realms, use the `DBA_DV_REALM_OBJECT` view, described in "Oracle Database Vault Public Views".
`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 %.)

E.1.9 DELETE_REALM Function

This function 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 DBA_DV_REALM_OBJECT view, described in"Oracle Database Vault Public Views".

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

Syntax

DELETE_REALM(
  realm_name VARCHAR2);

Parameters

Table E-10 DELETE_REALM Parameter

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, use the DBA_DV_REALMS view, described in "Oracle Database Vault Public Views".

E.1.10 DELETE_REALM_CASCADE Function

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

Syntax

DELETE_REALM_CASCADE(
  realm_name VARCHAR2);

Parameters

Table E-11 DELETE_REALM_CASCADE Parameter

Parameter Description

realm_name

Realm name.

To find the existing realms in the current database instance, use the DBA_DV_REALMS view, described in "Oracle Database Vault Public Views".

E.1.11 RENAME_REALM Function

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

Syntax

RENAME_REALM(
  realm_name VARCHAR2, 
  new_name   VARCHAR2);

Parameters

Table E-12 RENAME_REALM Parameters

Parameter Description

Parameter	Description
`realm_name`	Current realm name. To find the existing realms in the current database instance, use the `DBA_DV_REALMS` view, described in "Oracle Database Vault Public Views".
`new_name`	New realm name, up to 90 characters in mixed-case.

realm_name

Current realm name.

To find the existing realms in the current database instance, use the DBA_DV_REALMS view, described in "Oracle Database Vault Public Views".

new_name

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

E.1.12 UPDATE_REALM Function

This function updates a realm.

Syntax

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

Parameters

Table E-13 UPDATE_REALM Parameters

Parameter	Description
`realm_name`	Realm name. To find the existing realms in the current database instance, use the `DBA_DV_REALMS` view, described in "Oracle Database Vault Public Views".
`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`.
`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.

E.1.13 UPDATE_REALM_AUTH Function

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 E-14 UPDATE_REALM_AUTH Parameters

Parameter	Description
`realm_name`	Realm name. To find the existing realms in the current database instance, use the `DBA_DV_REALMS` view, described in "Oracle Database Vault Public Views".
`grantee`	User or role name. To find the available users and roles, use the `DBA_USERS` and `DBA_ROLES` views, described in Oracle Database Reference. To find the authorization of a particular user or role, use the `DVA_DV_REALM_AUTH` view. To find existing secure application roles used in privilege management, use the `DBA_DV_ROLE` view. Both are described in "Oracle Database Vault Public Views".
`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, use the `DBA_DV_RULE_SET` view. To find rules that are associated with the rule sets, use the `DBA_DB_RULE_SET_RULE` view. Both are described in "Oracle Database Vault Public 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.

E.2 Rule Set Functions Within DVSYS.DBMS_MACADM

Table E-15 lists functions 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 Appendix G, "Oracle Database Vault DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility functions that you can use with the rule set functions.

Table E-15 DVSYS.DBMS_MACADM Rule Set Configuration Functions

Function	Description
ADD_RULE_TO_RULE_SET Function	Adds an enabled or disabled rule to the end of a rule set.
ADD_RULE_TO_RULE_SET Function	Adds a rule to a rule set and lets you specify its order within the rule set.
ADD_RULE_TO_RULE_SET Function	Adds a rule to a rule set.
CREATE_RULE Function	Creates a rule.
CREATE_RULE_SET Function	Creates a rule set.
DELETE_RULE Function	Deletes a rule.
DELETE_RULE_FROM_RULE_SET Function	Deletes a rule from a rule set.
DELETE_RULE_SET Function	Deletes a rule set.
RENAME_RULE Function	Renames a rule. The name change takes effect everywhere the rule is used.
RENAME_RULE_SET Function	Renames a rule set. The name change takes effect everywhere the rule set is used.
SYNC_RULES Function	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 Function	Updates a rule.
UPDATE_RULE_SET Function	Updates a rule set.

E.2.1 ADD_RULE_TO_RULE_SET Function

This function 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 E-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, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public Views".
`rule_name`	Rule to add to the rule set. To find existing rules, use the `DBA_DV_RULE` view. To find rules that have been associated with rule sets, use `DBA_DV_RULE_SET_RULE`. Both are described in "Oracle Database Vault Public Views".
`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: `DBMS_MACUTIL.G_YES` `DBMS_MACUTIL.G_NO`

E.2.2 ADD_RULE_TO_RULE_SET Function

This function 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 E-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, use the DBA_DV_RULE_SET view, described in "Oracle Database Vault Public Views".

rule_name

Rule to add to the rule set.

To find existing rules, use the DBA_DV_RULE view. To find rules that have been associated with rule sets, use DBA_DV_RULE_SET_RULE. Both are described in "Oracle Database Vault Public Views".

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.

E.2.3 ADD_RULE_TO_RULE_SET Function

This function adds a rule to a rule set.

Syntax

ADD_RULE_TO_RULE_SET(
  rule_set_name VARCHAR2, 
  rule_name     VARCHAR2);

Parameters

Table E-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, use the DBA_DV_RULE_SET view, described in "Oracle Database Vault Public Views".

rule_name

Rule to add to the rule set.

To find existing rules in the current database instance, use the DBA_DV_RULE view. To find rules that have been associated with rule sets, use DBA_DV_RULE_SET_RULE. Both are described in "Oracle Database Vault Public Views".

E.2.4 CREATE_RULE Function

This function creates a rule.

Syntax

CREATE_RULE(
  rule_name  VARCHAR2, 
  rule_expr  VARCHAR2);

Parameters

Table E-19 CREATE_RULE Parameters

Parameter Description

Parameter	Description
`rule_name`	Rule name, up to 90 characters in mixed-case. To find existing rules in the current database instance, use the `DBA_DV_RULE` view. To find rules that have been associated with rule sets, use `DBA_DV_RULE_SET_RULE`. Both are described in "Oracle Database Vault Public Views".
`rule_expr`	PL/SQL `BOOLEAN` expression. See "Creating a New Rule" for more information on rule expressions.

rule_name

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

rule_expr

PL/SQL BOOLEAN expression.

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

E.2.5 CREATE_RULE_SET Function

This function creates a rule set. After you create a rule set, you can use the CREATE_RULE and ADD_RULE_TO_RULE set functions 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 E-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, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public Views".
`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`.
`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.
`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. 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. 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. See "Error Handling Options" for more information.
`handler`	Custom event handler logic. See "Error Handling Options" for more information.

E.2.6 DELETE_RULE Function

This function deletes a rule.

Syntax

DELETE_RULE(
  rule_name VARCHAR2);

Parameter

Table E-21 DELETE_RULE Parameter

Parameter Description

Parameter	Description
`rule_name`	Rule set name. To find existing rule sets in the current database instance, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public Views".

rule_name

Rule set name.

To find existing rule sets in the current database instance, use the DBA_DV_RULE_SET view, described in "Oracle Database Vault Public Views".

E.2.7 DELETE_RULE_FROM_RULE_SET Function

This function deletes a rule from a rule set.

Syntax

DELETE_RULE_FROM_RULE_SET(
  rule_set_name VARCHAR2, 
  rule_name     VARCHAR2);

Parameters

Table E-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, use the DBA_DV_RULE_SET view, described in "Oracle Database Vault Public Views".

rule_name

Rule to remove from the rule set.

To find rules that have been associated with rule sets, use DBA_DV_RULE_SET_RULE. Both are described in "Oracle Database Vault Public Views".

E.2.8 DELETE_RULE_SET Function

This function deletes a rule set.

Syntax

DELETE_RULE_SET(
  rule_set_name VARCHAR2);

Parameters

Table E-23 DELETE_RULE_SET Parameter

Parameter Description

rule_set_name

Rule set name.

To find existing rule sets in the current database instance, use the DBA_DV_RULE_SET view, described in "Oracle Database Vault Public Views".

E.2.9 RENAME_RULE Function

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

Syntax

RENAME_RULE(
  rule_name  VARCHAR2, 
  new_name   VARCHAR2);

Parameters

Table E-24 RENAME_RULE Parameters

Parameter Description

Parameter	Description
`rule_name`	Rule name. To find existing rules in the current database instance, use the `DBA_DV_RULE` view. To find rules that have been associated with rule sets, use `DBA_DV_RULE_SET_RULE`. Both are described in "Oracle Database Vault Public Views".
`new_name`	New rule name, up to 90 characters in mixed-case.

rule_name

Rule name.

new_name

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

E.2.10 RENAME_RULE_SET Function

This function 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 E-25 RENAME_RULE_SET Parameters

Parameter	Description
`rule_set_name`	Current rule set name.
`new_name`	New rule set name, up to 90 characters in mixed-case. Spaces are allowed.

E.2.11 SYNC_RULES Function

This function 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.

E.2.12 UPDATE_RULE Function

This function updates a rule.

Syntax

UPDATE_RULE(
  rule_name  VARCHAR2, 
  rule_expr  VARCHAR2);

Parameters

Table E-26 UPDATE_RULE Parameters

Parameter Description

Parameter	Description
`rule_name`	Rule name. To find existing rules in the current database instance, use the `DBA_DV_RULE` view. To find rules that have been associated with rule sets, use `DBA_DV_RULE_SET_RULE`. Both are described in "Oracle Database Vault Public Views".
`rule_expr`	PL/SQL `BOOLEAN` expression. See "Creating a New Rule" for more information on rule expressions.

rule_name

Rule name.

rule_expr

PL/SQL BOOLEAN expression.

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

E.2.13 UPDATE_RULE_SET Function

This function 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 E-27 UPDATE_RULE_SET Parameters

Parameter	Description
`rule_set_name`	Rule set name. To find existing rule sets in the current database instance, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public Views".
`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`.
`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.
`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. 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. 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. See "Error Handling Options" for more information.
`handler`	Custom event handler logic. See "Error Handling Options" for more information.

E.3 Command Rule Functions Within DVSYS.DBMS_MACADM

Table E-28 lists functions 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 Appendix G, "Oracle Database Vault DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility functions that you can use with the command rule functions.

Table E-28 DVSYS.DBMS_MACADM Command Rule Configuration Functions

Function	Description
CREATE_COMMAND_RULE Function	Creates a command rule and associates it with a rule set.
DELETE_COMMAND_RULE Function	Drops a command rule declaration.
UPDATE_COMMAND_RULE Function	Updates a command rule declaration.

E.3.1 CREATE_COMMAND_RULE Function

This function 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 E-29 CREATE_COMMAND_RULE Parameters

Parameter	Description
`command`	SQL statement to protect. See Oracle Database SQL Language Reference for more information of SQL statements.
`rule_set_name`	Name of rule set to associate with this command rule. To find existing rule sets in the current database instance, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public Views".
`object_owner`	Database schema owner for this command rule. To find the available users, use 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, use the `ALL_OBJECTS` view, described in Oracle Database Reference.
`enabled`	`Y` (yes) enables command rule checking; `N` (no) disables it. The default is `Y`.

E.3.2 DELETE_COMMAND_RULE Function

This function drops a command rule declaration.

Syntax

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

Parameters

Table E-30 DELETE_COMMAND_RULE Parameters

Parameter Description

Parameter	Description
`command`	SQL statement the command rule protects. See Oracle Database SQL Language Reference for more information of SQL statements.
`object_owner`	Database schema owner for this command rule. To find the available users in the current database instance, use 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, use the `ALL_OBJECTS` view, described in Oracle Database Reference.

command

SQL statement the command rule protects.

See Oracle Database SQL Language Reference for more information of SQL statements.

object_owner

Database schema owner for this command rule.

To find the available users in the current database instance, use 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, use the ALL_OBJECTS view, described in Oracle Database Reference.

E.3.3 UPDATE_COMMAND_RULE Function

This function 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 E-31 UPDATE_COMMAND_RULE Parameters

Parameter	Description
`command`	SQL statement to protect. See Oracle Database SQL Language Reference for more information of SQL statements.
`rule_set_name`	Name of rule set to associate with this command rule. To find existing rule sets in the current database instance, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public Views".
`object_owner`	Database schema owner for this command rule. To find the available users, use 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, use the `ALL_OBJECTS` view, described in Oracle Database Reference.
`enabled`	`Y` (yes) enables command rule checking; `N` (no) disables it. The default is `Y`.

E.4 Factor Functions Within DVSYS.DBMS_MACADM

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

Chapter 7, "Configuring Factors" describes factors in detail. See also Appendix G, "Oracle Database Vault DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility functions that you can use with the factor functions.

Table E-32 DVSYS.DBMS_MACADM Factor Configuration Functions

Function	Description
ADD_FACTOR_LINK Function	Specifies a parent-child relationship for two factors.
ADD_POLICY_FACTOR Function	Specifies that the label for a factor contributes to the Oracle Label Security label for a policy.
CHANGE_IDENTITY_FACTOR Function	Associates an identity with a different factor.
CHANGE_IDENTITY_VALUE Function	Updates the value of an identity.
CREATE_DOMAIN_IDENTITY Function	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 Function	Creates a factor.
CREATE_FACTOR_TYPE Function	Creates a factor type.
CREATE_IDENTITY Function	Creates an identity.
CREATE_IDENTITY_MAP Function	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 Function	Deletes a factor.
DELETE_FACTOR_LINK Function	Removes a parent-child relationship for two factors.
DELETE_FACTOR_TYPE Function	Deletes a factor type.
DELETE_IDENTITY Function	Removes an identity.
DELETE_IDENTITY_MAP Function	Removes an identity map from a factor.
DROP_DOMAIN_IDENTITY Function	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 Function	Renames a factor. The name change takes effect everywhere the factor is used.
RENAME_FACTOR_TYPE Function	Renames a factor type. The name change takes effect everywhere the factor type is used.
UPDATE_FACTOR Function	Updates a factor.
UPDATE_FACTOR_TYPE Function	Updates the description of a factor type.
UPDATE_IDENTITY Function	Updates the trust_level of a factor identity.

E.4.1 ADD_FACTOR_LINK Function

This function 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 E-33 ADD_FACTOR_LINK Parameters

Parameter Description

Parameter	Description
`parent_factor_name`	Parent factor name. To find existing factors in the current database instance, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".
`child_factor_name`	Child factor name. To find the relationships of existing factors whose identities are determined by the association of child factors, use the `DBA_DV_FACTOR_LINK` view, described in "Oracle Database Vault Public Views".
`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 constants: `DBMS_MACUTIL.G_YES` `DBMS_MACUTIL.G_NO` To find the Oracle Label Security policies and labels associated with factors, use the following views, described in "Oracle Database Vault Public Views": `DBA_DV_MAC_POLICY`: Lists Oracle Label Security policies defined in the current database instance. `DBA_DV_MAC_POLICY_FACTOR`: Lists the factors that are associated with Oracle Label Security policies for the current database instance. `DBA_DV_POLICY_LABEL`: Lists the Oracle Label Security label for each factor identifier in the `DBA_DV_IDENTITY` view for each policy.

parent_factor_name

Parent factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

child_factor_name

Child factor name.

To find the relationships of existing factors whose identities are determined by the association of child factors, use the DBA_DV_FACTOR_LINK view, described in "Oracle Database Vault Public Views".

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

DBMS_MACUTIL.G_YES
DBMS_MACUTIL.G_NO

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

DBA_DV_MAC_POLICY: Lists Oracle Label Security policies defined in the current database instance.
DBA_DV_MAC_POLICY_FACTOR: Lists the factors that are associated with Oracle Label Security policies for the current database instance.
DBA_DV_POLICY_LABEL: Lists the Oracle Label Security label for each factor identifier in the DBA_DV_IDENTITY view for each policy.

E.4.2 ADD_POLICY_FACTOR Function

This function 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 E-34 ADD_POLICY_FACTOR Parameters

Parameter Description

Parameter	Description
`policy_name`	Oracle Label Security policy name. To find the policies defined in the current database instance, use the `DBA_DV_MAC_POLICY` view. To find factors that are associated with Oracle Label Security policies, use `DBA_DV_MAC_POLICY_FACTOR`. Both are described in "Oracle Database Vault Public Views".
`factor_name`	Factor name. To find existing factors, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".

policy_name

Oracle Label Security policy name.

To find the policies defined in the current database instance, use the DBA_DV_MAC_POLICY view. To find factors that are associated with Oracle Label Security policies, use DBA_DV_MAC_POLICY_FACTOR. Both are described in "Oracle Database Vault Public Views".

factor_name

Factor name.

To find existing factors, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

E.4.3 CHANGE_IDENTITY_FACTOR Function

This function associates an identity with a different factor.

Syntax

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

Parameters

Table E-35 CHANGE_IDENTITY_FACTOR Parameters

Parameter Description

Parameter	Description
`factor_name`	Current factor name. To find existing factors in the current database instance, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".
`value`	Value of the identity to update. To find existing identities for each factor in the current database instance, use the `DBA_DV_IDENTITY` view. To find current identity mappings, use the `DBA_DV_IDENTITY_MAP` view. Both are described in "Oracle Database Vault Public Views".
`new_factor_name`	Name of the factor to associate with the identity.

factor_name

Current factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

value

Value of the identity to update.

To find existing identities for each factor in the current database instance, use the DBA_DV_IDENTITY view. To find current identity mappings, use the DBA_DV_IDENTITY_MAP view. Both are described in "Oracle Database Vault Public Views".

new_factor_name

Name of the factor to associate with the identity.

E.4.4 CHANGE_IDENTITY_VALUE Function

This function updates the value of an identity.

Syntax

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

Parameters

Table E-36 CHANGE_IDENTITY_VALUE Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

value

Current value associated with the identity.

new_value

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

E.4.5 CREATE_DOMAIN_IDENTITY Function

This function 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 E-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, use the `DVF.F$DATABASE_DOMAIN` view, 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, use the `DVF.F$DATABASE_HOSTNAME` function, described in "Oracle Database Vault PL/SQL Factor Functions".
`policy_name`	Oracle Label Security policy name. To find the available policies, use the `DBA_DV_MAC_POLICY` view, described in "Oracle Database Vault Public Views".
`domain_label`	Name of the domain to which to add the Oracle Label Security policy.

E.4.6 CREATE_FACTOR Function

This function creates a factor. After you create a factor, you need to give it an identity by using the CREATE_IDENTITY function, described in "CREATE_IDENTITY Function".

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 E-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, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".
`factor_type_name`	Factor type name, 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, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public 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 function 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 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. 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 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 function returns an error. `POWER(2,4)`: Audits if the validation function is false. `POWER(2,5)`: Audits if there is no trust level set. `POWER(2,6)`: Audits if the trust level is negative. 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. See "Error Options" for more information.

E.4.7 CREATE_FACTOR_TYPE Function

This function creates a user-defined factor type.

Syntax

CREATE_FACTOR_TYPE(
  name        VARCHAR2, 
  description VARCHAR2);

Parameters

Table E-39 CREATE_FACTOR_TYPE Parameters

Parameter Description

Parameter	Description
`name`	Factor type name, up to 30 characters in mixed-case, without spaces. To find existing factor types, use the `DBA_DV_FACTOR_TYPE` view, described in "Oracle Database Vault Public Views".
`description`	Description of the purpose of the factor type, up to 1024 characters in mixed-case.

name

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

To find existing factor types, use the DBA_DV_FACTOR_TYPE view, described in "Oracle Database Vault Public Views".

description

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

E.4.8 CREATE_IDENTITY Function

This function 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 E-40 CREATE_IDENTITY Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

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 an Identity" for more information about trust levels and label security.

E.4.9 CREATE_IDENTITY_MAP Function

This function 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 E-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, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".
`identity_factor_value`	Value the factor will assume if the identity map evaluates to TRUE. To find existing factor identities, use the `DBA_DV_IDENTITY` view. To find current factor identity mappings, use `DBA_DV_IDENTITY_MAP`. Both are described in "Oracle Database Vault Public Views".
`parent_factor_name`	The parent factor link to which the map is related. To find existing parent-child factor mappings, use the `DBA_DV_IDENTITY_MAP` view, described in "Oracle Database Vault Public Views".
`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.

E.4.10 DELETE_FACTOR Function

This function deletes a factor.

Syntax

DELETE_FACTOR(
factor_name VARCHAR2);

Parameters

Table E-42 DELETE_FACTOR Parameter

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

E.4.11 DELETE_FACTOR_LINK Function

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

Syntax

DELETE_FACTOR_LINK(
  parent_factor_name VARCHAR2, 
  child_factor_name  VARCHAR2);

Parameters

Table E-43 DELETE_FACTOR_LINK Parameters

Parameter Description

Parameter	Description
`parent_factor_name`	Factor name. To find factors that are used in parent-child mappings in the current database instance, use the `DBA_DV_FACTOR_LINK` view, described in "Oracle Database Vault Public Views".
`child_factor_name`	Factor name.

parent_factor_name

Factor name.

To find factors that are used in parent-child mappings in the current database instance, use the DBA_DV_FACTOR_LINK view, described in "Oracle Database Vault Public Views".

child_factor_name

Factor name.

E.4.12 DELETE_FACTOR_TYPE Function

This function deletes a factor type.

Syntax

DELETE_FACTOR_TYPE(
  name VARCHAR2);

Parameters

Table E-44 DELETE_FACTOR_TYPE Parameters

Parameter Description

Parameter	Description
`name`	Factor type name. To find existing factor types in the current database instance, use the `DBA_DV_FACTOR_TYPE` view, described in "Oracle Database Vault Public Views".

name

Factor type name.

To find existing factor types in the current database instance, use the DBA_DV_FACTOR_TYPE view, described in "Oracle Database Vault Public Views".

E.4.13 DELETE_IDENTITY Function

This function removes an identity from an existing factor.

Syntax

DELETE_IDENTITY(
  factor_name VARCHAR2, 
  value       VARCHAR2);

Parameters

Table E-45 DELETE_IDENTITY Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

value

Identity value associated with the factor.

To find the identities for each factor in the current database instance, use the DBA_DV_IDENTITY view, described in "Oracle Database Vault Public Views".

E.4.14 DELETE_IDENTITY_MAP Function

This function 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 E-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, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".
`identity_factor_value`	Value the factor will assume if the identity map evaluates to TRUE. To find existing factor identities, use the `DBA_DV_IDENTITY` view. To find current factor identity mappings, use `DBA_DV_IDENTITY_MAP`. Both are described in "Oracle Database Vault Public Views".
`parent_factor_name`	The parent factor link to which the map is related. To find existing factors, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".
`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.
`operand2`	Right operand for the relational operator.

E.4.15 DROP_DOMAIN_IDENTITY Function

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

Syntax

DROP_DOMAIN_IDENTITY(
  domain_name  VARCHAR2, 
  domain_host  VARCHAR2);

Parameters

Table E-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, use 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, use the DVF.F$DATABASE_HOSTNAME function, described in "Oracle Database Vault PL/SQL Factor Functions".

E.4.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);

Parameters

Table E-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.

E.4.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);

Parameters

Table E-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.

E.4.18 RENAME_FACTOR Function

This function 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 E-50 RENAME_FACTOR Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

new_factor_name

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

E.4.19 RENAME_FACTOR_TYPE Function

This function 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 E-51 RENAME_FACTOR_TYPE Parameters

Parameter Description

old_name

Current factor type name.

To find existing factor types in the current database instance, use the DBA_DV_FACTOR_TYPE view, described in "Oracle Database Vault Public Views".

new_name

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

E.4.20 UPDATE_FACTOR Function

This function 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 E-52 UPDATE_FACTOR

Parameter	Description
`factor_name`	Factor name. To find existing factors in the current database instance, use the `DBA_DV_FACTOR` view, described in "Oracle Database Vault Public Views".
`factor_type_name`	Factor type name. To find existing factor types, use the `DBA_DV_FACTOR_TYPE` view, described in "Oracle Database Vault Public Views".
`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, use the `DBA_DV_RULE_SET` view, described in "Oracle Database Vault Public 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 function 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 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. 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 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 function returns an error. `POWER(2,4)`: Audits if the validation function is false. `POWER(2,5)`: Audits if there is no trust level set. `POWER(2,6)`: Audits if the trust level is negative. 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. See "Error Options" for more information.

E.4.21 UPDATE_FACTOR_TYPE Function

This function updates a factor type.

Syntax

UPDATE_FACTOR_TYPE(
  name         VARCHAR2, 
  description  VARCHAR2);

Parameters

Table E-53 UPDATE_FACTOR_TYPE Parameters

Parameter Description

name

Factor type name.

To find existing factor types in the current database instance, use the DBA_DV_FACTOR_TYPE view, described in "Oracle Database Vault Public Views".

description

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

E.4.22 UPDATE_IDENTITY Function

This function updates the trust level of a factor identity.

Syntax

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

Parameters

Table E-54 UPDATE_IDENTITY Parameters

Parameter Description

factor_name

Factor name.

To find existing factors in the current database instance, use the DBA_DV_FACTOR view, described in "Oracle Database Vault Public Views".

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

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

E.5 Secure Application Role Functions Within DVSYS.DBMS_MACADM

Table E-55 lists functions 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 Appendix G, "Oracle Database Vault DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility functions that you can use with the secure application role functions.

Table E-55 DVSYS.DBMS_MACADM Secure Application Role Configuration Functions

Function	Description
CREATE_ROLE Function	Creates an Oracle Database Vault secure application role.
DELETE_ROLE Function	Deletes an Oracle Database Vault secure application role.
RENAME_ROLE Function	Renames an Oracle Database Vault secure application role. The name change takes effect everywhere the role is used.
UPDATE_ROLE Function	Updates a Oracle Database Vault secure application role.

E.5.1 CREATE_ROLE Function

This function creates an Oracle Database Vault secure application role.

Syntax

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

Parameters

Table E-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 Language Reference.

To find existing secure application roles in the current database instance, use the DBA_DV_ROLE view, described in "Oracle Database Vault Public Views".

enabled

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

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, use the DBA_DV_RULE_SET view, described in "Oracle Database Vault Public Views".

E.5.2 DELETE_ROLE Function

This function deletes an Oracle Database Vault secure application role.

Syntax

DELETE_ROLE(
  role_name VARCHAR2);

Parameters

Table E-57 DELETE_ROLE Parameter

Parameter Description

role_name

Role name.

To find existing secure application roles in the current database instance, use the DBA_DV_ROLE view, described in "Oracle Database Vault Public Views".

E.5.3 RENAME_ROLE Function

This function 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 E-58 RENAME_ROLE Parameters

Parameter Description

role_name

Role name.

To find existing secure application roles in the current database instance, use the DBA_DV_ROLE view, described in "Oracle Database Vault Public Views".

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 Language Reference.

E.5.4 UPDATE_ROLE Function

This function updates a Oracle Database Vault secure application role.

Syntax

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

Parameters

Table E-59 UPDATE_ROLE Parameters

Parameter Description

role_name

Role name.

To find existing secure application roles in the current database instance, use the DBA_DV_ROLE view, described in "Oracle Database Vault Public Views".

enabled

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

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, use the DBA_DV_RULE_SET view, described in "Oracle Database Vault Public Views".

E.6 Oracle Label Security Policy Functions Within DVSYS.DBMS_MACADM

Table E-60 lists functions 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 Appendix G, "Oracle Database Vault DVSYS.DBMS_MACUTL Package" for a set of general-purpose utility functions that you can use with the Oracle Label Security policy functions.

Table E-60 DVSYS.DBMS_MACADM Oracle Label Security Configuration Functions

Function	Description
CREATE_MAC_POLICY Function	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 Function	Labels an identity within an Oracle Label Security policy.
DELETE_MAC_POLICY_CASCADE Function	Deletes all Oracle Database Vault objects related to an Oracle Label Security policy.
DELETE_POLICY_FACTOR Function	Removes the factor from contributing to the Oracle Label Security label.
DELETE_POLICY_LABEL Function	Removes the label from an identity within an Oracle Label Security policy.
UPDATE_MAC_POLICY Function	Specifies the algorithm that is used to merge labels when computing the label for a factor, or the Oracle Label Security Session label.

E.6.1 CREATE_MAC_POLICY Function

This function 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 E-61 CREATE_MAC_POLICY Parameters

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, use the DBA_DV_MAC_POLICY view, described in "Oracle Database Vault Public Views".

algorithm

Merge algorithm for cases when Oracle Label Security has merged two labels. Enter the code listed in Table E-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 E-62 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

E.6.2 CREATE_POLICY_LABEL Function

This function 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 E-63 CREATE_POLICY_LABEL Parameters

Parameter	Description
`identity_factor_name`	Name of factor being labeled. To find existing factors in the current database instance, use the `DBA_DV_FACTOR` view. To find factors that are associated with Oracle Label Security policies, use `DBA_DV_MAC_POLICY_FACTOR`. Both are described in "Oracle Database Vault Public Views". 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, use the `DBA_DV_IDENTITY` view, described in "Oracle Database Vault Public Views".
`policy_name`	Name of existing policy. To find existing policies in the current database instance, use the `DBA_DV_MAC_POLICY` view, described in "Oracle Database Vault Public Views".
`label`	Oracle Label Security label name. To find existing policy labels for factor identifiers, use the `DBA_DV_POLICY_LABEL` view, described in "Oracle Database Vault Public Views".

E.6.3 DELETE_MAC_POLICY_CASCADE Function

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

Syntax

DELETE_MAC_POLICY_CASCADE(
  policy_name  VARCHAR2);

Parameters

Table E-64 DELETE_MAC_POLICY_CASCADE Parameter

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, use the DBA_DV_MAC_POLICY view, described in "Oracle Database Vault Public Views".

E.6.4 DELETE_POLICY_FACTOR Function

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

Syntax

DELETE_POLICY_FACTOR(
  policy_name  VARCHAR2, 
  factor_name  VARCHAR2);

Parameters

Table E-65 DELETE_POLICY_FACTOR Parameters

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, use the DBA_DV_MAC_POLICY view, described in "Oracle Database Vault Public Views".

factor_name

Name of factor associated with the Oracle Label Security label.

To find factors that are associated with Oracle Label Security policies, use DBA_DV_MAC_POLICY_FACTOR. Both are described in "Oracle Database Vault Public Views".

E.6.5 DELETE_POLICY_LABEL Function

This function 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 E-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, use `DBA_DV_MAC_POLICY_FACTOR`. Both are described in "Oracle Database Vault Public Views". 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, use the `DBA_DV_IDENTITY` view, described in "Oracle Database Vault Public Views".
`policy_name`	Name of existing policy. To find existing policies in the current database instance, use the `DBA_DV_MAC_POLICY` view, described in "Oracle Database Vault Public Views".
`label`	Oracle Label Security label name. To find existing policy labels for factor identifiers, use the `DBA_DV_POLICY_LABEL` view, described in "Oracle Database Vault Public Views".

E.6.6 UPDATE_MAC_POLICY Function

This function 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 E-67 UPDATE_MAC_POLICY

Parameter Description

policy_name

Name of existing policy.

To find existing policies in the current database instance, use the DBA_DV_MAC_POLICY view, described in "Oracle Database Vault Public Views".

algorithm

Merge algorithm for cases when Oracle Label Security has merged two labels. For example:

"LII - Minimum Level/Intersection/Intersection"

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