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

Part Number B25166-04
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

D PL/SQL Interfaces to Oracle Database Vault

This appendix includes the following sections:

D.1 Oracle Database Vault Run-Time PL/SQL Procedures and Functions

Oracle Database Vault provides a set of procedures and functions in the DVSYS schema to enable access control and Oracle Label Security processing in an Oracle database. There are also procedures and functions that expose the logic to validate a DDL command for realm violations and command authorizations. Additional procedures and functions are provided to set the value of a factor, for example, from a Web application, to retrieve the trust level for a session or specific factor identity, and to get the label for a factor identity. These procedures and functions are provided so that a database administrator does not grant EXECUTE privileges on all DVSYS package procedures to the general database account population. The procedures and functions expose only the minimum methods that are required. All of these functions and procedures are publicly available for applications that need them.

Table D-1 lists the procedures and functions that are used to enable Oracle Database Vault processing with the DVSYS schema.

Table D-1 DVSYS Functions

Function Parameter

SET_FACTOR Function


Sets a factor

GET_FACTOR Function


Retrieves a factor

GET_TRUST_LEVEL Function


Retrieves the trust level assigned to a factor

GET_TRUST_LEVEL_FOR_IDENTITY Function


Retrieves the trust level for a specified factor and identity

ROLE_IS_ENABLED Function


Checks whether the specified role is enabled.

GET_FACTOR_LABEL Function


Retrieves the label for the specified factor when the factor has a label assigned to it for the specified Oracle Label Security policy


D.1.1 SET_FACTOR Function

This function can be exposed to an application that requires the ability to set factor identities dynamically. It wraps the package procedure DBMS_MACSEC.SET_FACTOR. When a factor has a rule set associated with it for assignment and if the rule set returns true, then the value will be set. Normal rule set handling occurs, and the factor value (identity) validation method will be called. This procedure is available (to execute) to the general database account population.

Syntax

SET_FACTOR(
  p_factor VARCHAR2, 
  p_value VARCHAR2);

Parameters

Table D-2 SET_FACTOR Parameters

Parameter Description

p_factor

Factor name.

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

p_value

Identity value, up to 1024 characters in mixed-case.

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


D.1.2 GET_FACTOR Function

This function is exposed to the DVF schema to allow the public factor functions to resolve the identity of a factor. This enables the F$ functions in the DVF schema. This function is available (to execute) to the general database account population.

Syntax

GET_FACTOR(
  p_factor VARCHAR2);

Parameter

Table D-3 GET_FACTOR Parameter

Parameter Description

p_factor

Factor name.

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


D.1.3 GET_TRUST_LEVEL Function

This function returns the trust level of the current session identity for the factor requested. This function is available (to execute) to the general database account population.

Syntax

GET_TRUST_LEVEL(
  p_factor VARCHAR2);

Parameter

Table D-4 GET_TRUST_LEVEL Parameter

Parameter Description

p_factor

Factor name.

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


D.1.4 GET_TRUST_LEVEL_FOR_IDENTITY Function

This function returns the trust level for the factor and identity requested. This function is available (to execute) to the general database account population.

Syntax

GET_TRUST_LEVEL_FOR_IDENTITY(
  p_factor VARCHAR2, 
  p_identity VARCHAR2);

Parameters

Table D-5 GET_TRUST_LEVEL_FOR_IDENTITY Parameters

Parameter Description

p_factor

Factor name.

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

p_identity

Identity value.

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


D.1.5 ROLE_IS_ENABLED Function

This function returns an indicator that specifies whether or not a role has been enabled. This function is available (to execute) to the general database account population.

Syntax

ROLE_IS_ENABLED(
  p_role VARCHAR2);

Parameter

Table D-6 ROLE_IS_ENABLED Parameter

Parameter Description

p_role

Role name to check.

To find existing roles, use the following views:


D.1.6 GET_FACTOR_LABEL Function

This function returns the label for the specified factor when the factor has a label assigned to it for the specified Oracle Label Security policy. The function returns a label that is merged with the maximum session label for the policy if the policy is configured with Oracle Label Security. The function is available (to execute) to the general database population.

Syntax

GET_FACTOR_LABEL(
  p_factor IN VARCHAR2, 
  p_policy_name IN VARCHAR2);

Parameters

Table D-7 GET_FACTOR_LABEL Parameters

Parameter Description

p_factor

Factor name.

To find the available 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".

p_policy_name

Oracle Label Security policy name.

Use the following views to find information about policies and factors in the current database instance:

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

See "Oracle Database Vault Public Views" for more information.


D.2 Oracle Database Vault PL/SQL Factor Functions

In addition to the functions and procedures made available from the DVSYS schema, the DVF schema contains a single function for each factor defined in the system. These functions are created and maintained as the Oracle Database Vault configuration API (DVSYS.DBMS_MACADM) is called for managing the various factors. The functions are then available to the general database account population through PL/SQL functions and standard SQL. This allows factors to be used in Oracle Label Security, Oracle Virtual Private Database (VPD), and so on.

For example, an account can log in to SQL*Plus and use the functions exposing the factors:

SQL> SELECT DVF.F$AUTHENTICATION_TYPE FROM dual;
F$AUTHENTICATION_TYPE
------------------------------------------------
DATABASE

The name of the factor itself is case-insensitive. For example, the following statements return the same result:

SQL> SELECT DVF.F$authentication_type FROM dual;

SQL> SELECT DVF.F$Authentication_Type FROM dual;

Table D-8 describes the functions that are created during installation based on the default factors provided by Oracle Database Vault.

Table D-8 Installed Oracle Database Vault Factor Functions

DVF Factor Function Description

DVF.F$AUTHENTICATION_METHOD

Returns the method of authentication. In the list that follows, the type of user is followed by the method returned:

  • Password-authenticated enterprise user, local database user, or SYSDBA/SYSOPER using Password File; proxy with user name using password: PASSWORD

  • Kerberos-authenticated enterprise or external user: KERBEROS

  • SSL-authenticated enterprise or external user: SSL

  • Radius-authenticated external user: RADIUS

  • Operating system-authenticated external user or SYSDBA/SYSOPER: OS

  • DCE-authenticated external user: DCE

  • Proxy with certificate, distinguished name (DN), or user name without using password: NONE

You can use IDENTIFICATION_TYPE to distinguish between external and enterprise users when the authentication method is Password, Kerberos, or SSL.

DVF.F$CLIENT_IP

Returns the IP address and retrieval method for a client to the database server.

DVF.F$DATABASE_DOMAIN

Returns the domain of the database as specified in the DB_DOMAIN initialization parameter.

DVF.F$DATABASE_HOSTNAME

Returns the host name and retrieval method for a database.

DVF.F$DATABASE_INSTANCE

Returns the instance identifier and retrieval method for a database instance.

DVF.F$DATABASE_IP

Returns the IP address and retrieval method for a database server.

DVF.F$DATABASE_NAME

Returns the name of the database as specified in the DB_NAME initialization parameter.

DVF.F$DOMAIN

Returns a named collection of physical, configuration, or implementation-specific factors in the run-time environment (for example, a networked IT environment or subset of it) that operates at a specific sensitivity level.

You can identify a domain using factors such as host name, IP address, and database instance names of the Oracle Database Vault nodes in a secure access path to the database. Each domain can be uniquely determined using a combination of the factor identifiers that identify the domain. You can use these identifying factors and possibly additional factors to define the Maximum Security Label within the domain. This restricts data access and commands, depending on the physical factors about the Oracle Database Vault session. Example domains of interest may be Corporate Sensitive, Internal Public, Partners, and Customers.

DVF.F$ENTERPRISE_IDENTITY

Returns the enterprise-wide identity for a user:

  • For enterprise users: the Oracle Internet Directory DN.

  • For external users: the external identity (Kerberos principal name, Radius and DCE schema names, operating system user name, certificate DN).

  • For local users and SYSDBA/SYSOPER logins: NULL.

The value of the attribute differs by proxy method:

  • For a proxy with DN: the Oracle Internet Directory DN of the client.

  • For a proxy with certificate: the certificate DN of the client for external users; the Oracle Internet Directory DN for global users.

  • For a proxy with user name: the Oracle Internet Directory DN if the client is an enterprise user; NULL if the client is a local database user.

DVF.F$IDENTIFICATION_TYPE

Returns the way the schema of a user was created in the database. Specifically, it reflects the IDENTIFIED clause in the CREATE/ALTER USER syntax. In the list that follows, the syntax used during schema creation is followed by the identification type returned:

  • IDENTIFIED BY password: LOCAL

  • IDENTIFIED EXTERNALLY: EXTERNAL

  • IDENTIFIED GLOBALLY: GLOBAL SHARED

  • IDENTIFIED GLOBALLY AS DN: GLOBAL PRIVATE

DVF.F$LANG

Returns the ISO abbreviation for the language name, a shorter form than the existing LANGUAGE parameter.

DVF.F$LANGUAGE

Returns the language and territory currently used by your session, along with the database character set, in the following form:

language_territory.characterset

DVF.F$MACHINE

Returns the computer (host) name for the database client that established the database session.

DVF.F$NETWORK_PROTOCOL

Returns the network protocol being used for communication, as specified in the PROTOCOL=protocol portion of the connect string.

DVF.F$PROXY_ENTERPRISE_IDENTITY

Returns the Oracle Internet Directory DN when the proxy user is an enterprise user.

DVF.F$PROXYUSER

Name of the database user who opened the current session on behalf of SESSION_USER.

DVF.F$SESSION_USER

Returns the database user name by which the current user is authenticated.

This value remains the same throughout the session.


D.3 Oracle Database Vault PL/SQL Rule Set Functions

Oracle Database Vault provides a set of functions that you can use in rule sets to inspect the SQL statement that you want the rule set to protect. For example, if a rule set protects SELECT ON HR.EMPLOYEES under a command rule, then you could use these functions to make more informed decisions in the rule expression.

Table D-9 describes the functions that are created during installation based on the default rule sets provided by Oracle Database Vault.

Table D-9 Installed Oracle Database Vault PL/SQL Rule Set Functions

Rule Set Function Description

DVSYS.DV_SYSEVENT

Returns the system event firing the rule set: The event name is the same as that in the syntax of the SQL statement, for example, INSERT, CREATE.

DVSYS.DV_LOGIN_USER

Returns the login user name.

DVSYS.DV_INSTANCE_NUM

Returns the database instance number.

DVSYS.DV_DATABASE_NAME

Returns the database name.

DVSYS.DV_DICT_OBJ_TYPE

Returns the type of the dictionary object on which the database operation occurred, for example, table, procedure, view.

DVSYS.DV_DICT_OBJ_OWNER

Returns the owner of the dictionary object on which the database operation occurred.

DVSYS.DV_DICT_OBJ_NAME

Returns the name of the dictionary object on which the database operation occurred.

DVSYS.DV_SQL_TEXT

Returns the first 4000 characters of SQL text of the database statement used in the operation.


D.4 Oracle Database Vault PL/SQL Packages

Oracle Database Vault provides a collection of PL/SQL package APIs to support the maintenance and run-time behavior of Oracle Database Vault. Table D-10 lists these packages. Appendix E, "Oracle Database Vault Packages" describes these packages in detail.

Table D-10 Oracle Database Vault Administrator and Run-Time PL/SQL Packages

Package Description

DVSYS.DBMS_MACADM

This package API provides for the administration of all aspects of the secure and access control configuration data. The realm owner of the Oracle Database Vault realm can grant the ability to run this package.

See "DVSYS.DBMS_MACADM Package" for more information.

DVSYS.DBMS_MACSEC_ROLES

This package API provides the CAN_SET_ROLE method to check whether the user invoking the method is authorized to use the specified Oracle Database Vault secure application role. The authorization is determined by checking the rule set associated with the role.

The API also provides a method to issue the SET ROLE statement for a Oracle Database Vault Secure Application Role. Before SET ROLE is issued, the CAN_SET_ROLE method is called to check the rule set associated with the role. Run-time rule set behavior such as auditing, failure processing, and event handling occur during this process. The package is available to the general database account population.

See "DVSYS.DBMS_MACSEC_ROLES Package" for more information.

DVSYS.DBMS_MACUTL

This package API defines several constants and utility methods that are commonly used by other Oracle Database Vault packages, such as code/message lookup, error handling, data conversion, and privilege checks. This package can be run by the general database account population. This allows for security developers to leverage the constants in scripted configuration files. Utility methods such as USER_HAS_ROLE can also be used in Oracle Database Vault rules.

See "DVSYS.DBMS_MACUTL Package" for more information.


Note:

There are a handful of procedures in the DVSYS.DBMS_MACADM package that are not exposed in the Oracle Database Vault Administration Web application. The procedures that are not exposed include:
  • CREATE_DOMAIN_IDENTITY

  • CREATE_FACTOR_TYPE

  • DELETE_FACTOR_TYPE

  • RENAME_FACTOR_TYPE

  • UPDATE_FACTOR_TYPE