66 DBMS_FGA

Syntax

DBMS_FGA.ADD_POLICY(
   object_schema      VARCHAR2, 
   object_name        VARCHAR2, 
   policy_name        VARCHAR2, 
   audit_condition    VARCHAR2, 
   audit_column       VARCHAR2, 
   handler_schema     VARCHAR2, 
   handler_module     VARCHAR2, 
   enable             BOOLEAN, 
   statement_types    VARCHAR2,
   audit_trail        BINARY_INTEGER IN DEFAULT,
   audit_column_opts  BINARY_INTEGER IN DEFAULT);

Parameters

Usage Notes

• If object_schema is not specified, the current log-on user schema is assumed.

• An FGA policy should not be applied to out-of-line columns such as LOB columns.

• Each audit policy is applied to the query individually. However, at most one audit record may be generated for each policy, no matter how many rows being returned satisfy that policy's audit_condition. In other words, whenever any number of rows being returned satisfy an audit condition defined on the table, a single audit record will be generated for each such policy.

• If a table with an FGA policy defined on it receives a Fast Path insert or a vectored update, the hint is automatically disabled before any such operations. Disabling the hint allows auditing to occur according to the policy's terms. (One example of a Fast Path insert is the statement INSERT-WITH-APPEND-hint.)

• The audit_condition must be a boolean expression that can be evaluated using the values in the row being inserted, updated, or deleted. The expression can also use functions, such as the USER or SYS_CONTEXT functions.

  The expression must not combine conditions using operators such as AND and OR. audit_condition can be NULL (or omitted), which is interpreted as TRUE, but it cannot contain the following elements:

  • Subqueries or sequences

  • The following attributes of the USERENV namespace when accessed using the SYS_CONTEXT function:

    • CURRENT_SQL

    • CURRENT_SQL_LENGTH

    • CURRENT_BIND

  • Any use of the pseudo columns LEVEL, PRIOR, or ROWNUM.

  Specifying an audit condition of "1=1" to force auditing of all specified statements ("statement_types") affecting the specified column ("audit_column") is no longer needed to achieve this purpose. A NULL value for audit_condition causes audit to happen even if no rows are processed, so that all actions on a table with this policy are audited.

• The audit_condition is evaluated using the privileges of the user who creates the policy.

• The audit function (handler_module) is an alerting mechanism for the administrator. The required interface for such a function is as follows:

  PROCEDURE fname ( object_schema VARCHAR2, object_name VARCHAR2, policy_name VARCHAR2 )  AS ...
  

  where fname is the name of the procedure, object_schema is the name of the schema of the table audited, object_name is the name of the table to be audited, and policy_name is the name of the policy being enforced. The audit function will be executed with the function owner's privilege.

  See Also:

  "Tutorial: Adding an E-Mail Alert to a Fine-Grained Audit Policy" in Oracle Database Security Guide for an example of creating an e-mail alert handler for a fine-grained audit policy

• The audit_trail parameter specifies both where the fine-grained audit trail will be written and whether it is to include the query's SQL Text and SQL Bind variable information (typically in columns named LSQLTEXT and LSQLBIND):

  • If audit_trail includes XML, then fine-grained audit records are written to XML-format operating system files stored in the directory specified by an AUDIT_FILE_DEST statement in SQL. (The default AUDIT_FILE_DEST is $ORACLE_BASE/admin/$DB_UNIQUE_NAME/adump on Unix-based systems, and $ORACLE_BASE\admin\$DB_UNIQUE_NAME\adump on Windows systems.)

  • If audit_trail includes DB instead, then the audit records are written to the SYS.FGA_LOG$ table in the database. However, for read-only databases, Oracle Database writes the fine-grained audit records to XML files, regardless of the audit_trail settings.

  • If audit_trail includes EXTENDED, then the query's SQL Text and SQL Bind variable information are included in the audit trail.

    Note that the SQL Text information could include sensitive data, such as credit card numbers, in the audit trail. See "Auditing Sensitive Information" in Oracle Database Security Guide for ways in which you can handle this.

  • For example:

    • Setting audit_trail to DBMS_FGA.DB sends the audit trail to the SYS.FGA_LOG$ table in the database and omits SQL Text and SQL Bind.

    • Setting audit_trail to DBMS_FGA.DB + DBMS_FGA.EXTENDED sends the audit trail to the SYS.FGA_LOG$ table in the database and includes SQL Text and SQL Bind.

    • Setting audit_trail to DBMS_FGA.XML writes the audit trail in XML files sent to the operating system and omits SQL Text and SQL Bind.

    • Setting audit_trail to DBMS_FGA.XML + DBMS_FGA.EXTENDED writes the audit trail in XML files sent to the operating system and includes SQL Text and SQL Bind.

  The audit_trail parameter appears in the ALL_AUDIT_POLICIES view.

• You can change the operating system destination using the following command:

  ALTER SYSTEM SET AUDIT_FILE_DEST = '<New Directory>' DEFERRED

• On many platforms, XML audit files are named <process_name>_<processId>.xml, for example, ora_2111.xml, or s002_11.xml. On Windows, the XML audit files are named <process_name>_<ThreadId>.xml (or <process_name>_ProcessId>.xml if the process is not running as a thread).

• The audit_column_opts parameter establishes whether a statement is audited

  • when the query references any column specified in the audit_column parameter (audit_column_opts = DBMS_FGA.ANY_COLUMNS), or

  • only when all such columns are referenced (audit_column_opts = DBMS_FGA.ALL_COLUMNS).

  The default is DBMS_FGA.ANY_COLUMNS.

  The ALL_AUDIT_POLICIES view also shows audit_column_opts.

• When audit_column_opts is set to DBMS_FGA.ALL_COLUMNS, a SQL statement is audited only when all the columns mentioned in audit_column have been explicitly referenced in the statement. And these columns must be referenced in the same SQL-statement or in the sub-select.

  Also, all these columns must refer to a single table/view or alias.

  Thus, if a SQL statement selects the columns from different table aliases, the statement will not be audited.

V$XML_AUDIT_TRAIL View

The new values for the audit_trail parameter (XML and XML+EXTENDED) cause fine-grained auditing records to be written to operating system files in XML format.

Audit records stored in operating system files can be more secure than database-stored audit records because access can require file permissions that DBAs do not have. Operating system storage for audit records also offers higher availability, since such records remain available even if the database is temporarily inaccessible.

A new dynamic view, V$XML_AUDIT_TRAIL, makes such audit records from XML files available to DBAs through SQL query, providing enhanced usability. Querying this view causes all XML files (all files with an.xml extension) in the AUDIT_FILE_DEST directory to be parsed and presented in relational table format.

The DBA_COMMON_AUDIT_TRAIL view includes the contents of the V$XML_AUDIT_TRAIL dynamic view for standard and fine-grained audit records.

Since the audit XML files are stored in files with extension.xml on all platforms, the dynamic view presents audit information similarly on all platforms, using the following schema:

Usage Notes

• Every XML audit record contains the elements AUDIT_TYPE and EXTENDED_TIMESTAMP, with the latter printed in UTC zone (with no timezone information). Values retrieved using V$XML_AUDIT_TRAIL view are converted to session timezone and printed.

• For SQL_TEXT and SQL_BIND element values (CLOB type columns), the dynamic view shows only the first 4000 characters. The underlying XML file may have more than 4000 characters for such SQL_TEXT and SQL_BIND values.

• For large numbers of XML audit files, querying V$XML_AUDIT_TRAIL is faster when they are loaded into a database table using SQL*Loader or a similar tool. XML audit files are larger than the equivalent written to OS files when AUDIT_TRAIL=OS.

• Error handling is the same as when AUDIT_TRAIL=OS. If any error occurs in writing an audit record to disk, including the directory identified by AUDIT_FILE_DEST being full, the auditing operation fails. An alert message is logged.

• The policy event handler module will be executed with the module owner's privilege.

• Do not create recursive fine-grained audit handlers. For example, suppose you create a handler that executes an INSERT statement on the HR.EMPLOYEES table. The policy that is associated with this handler is for INSERT statements (as set by the statement_types parameter). When the policy is used, the handler executes recursively until the system has run out of memory. This can raise the error ORA-1000: maximum open cursors exceeded or ORA-00036: maximum number of recursive SQL levels (50) exceeded. See also Oracle Database Security Guide

Examples

DBMS_FGA.ADD_POLICY (
   object_schema      =>  'scott', 
   object_name        =>  'emp', 
   policy_name        =>  'mypolicy1', 
   audit_condition    =>  'sal < 100', 
   audit_column       =>  'comm,sal', 
   handler_schema     =>   NULL, 
   handler_module     =>   NULL, 
   enable             =>   TRUE, 
   statement_types    =>  'INSERT, UPDATE', 
   audit_trail        =>   DBMS_FGA.XML + DBMS_FGA.EXTENDED, 
   audit_column_opts  =>   DBMS_FGA.ANY_COLUMNS); 

Syntax

DBMS_FGA.DISABLE_POLICY(
   object_schema  VARCHAR2, 
   object_name    VARCHAR2, 
   policy_name    VARCHAR2 ); 

Parameters

The default value for object_schema is NULL. (If NULL, the current log-on user schema is assumed.)

Examples

DBMS_FGA.DISABLE_POLICY (
object_schema   =>  'scott',
object_name     =>  'emp',
policy_name     =>  'mypolicy1');

Syntax

DBMS_FGA.DROP_POLICY(
   object_schema  VARCHAR2, 
   object_name    VARCHAR2, 
   policy_name    VARCHAR2 );

Parameters

Usage Notes

The DBMS_FGA procedures cause current DML transactions, if any, to commit before the operation unless they are inside a DDL event trigger. With DDL transactions, the DBMS_FGA procedures are part of the DDL transaction. The default value for object_schema is NULL. (If NULL, the current log-on user schema is assumed.)

Examples

DBMS_FGA.DROP_POLICY (
object_schema   =>  'scott',
object_name     =>  'emp',
policy_name     =>  'mypolicy1');

Syntax

DBMS_FGA.ENABLE_POLICY(
   object_schema  VARCHAR2,
   object_name    VARCHAR2,
   policy_name    VARCHAR2,
   enable         BOOLEAN);

Parameters

Examples

DBMS_FGA.ENABLE_POLICY (
object_schema    =>  'scott',
object_name      =>  'emp',
policy_name      =>  'mypolicy1',
enable           =>   TRUE);