4 Configuring Privilege and Role Authorization

Restricting System Privileges by Securing the Data Dictionary

To secure the data dictionary, set the O7_DICTIONARY_ACCESSIBILITY initialization parameter to FALSE, which is the default value. This feature is called the dictionary protection mechanism.

The O7_DICTIONARY_ACCESSIBILITY initialization parameter controls restrictions on system privileges when you upgrade from Oracle Database release 7 to Oracle8i and later releases. If the parameter is set to TRUE, then access to objects in the SYS schema is allowed (Oracle Database release 7 behavior). Because the ANY privilege applies to the data dictionary, a malicious user with ANY privilege could access or alter data dictionary tables.

To set the O7_DICTIONARY_ACCESSIBILTY initialization parameter, modify it in the initSID.ora file. Alternatively, you can log on to SQL*Plus as user SYS with the SYSDBA privilege and then enter an ALTER SYSTEM statement, assuming you have started the database using a server parameter file (SPFILE).

Example 4-1 shows how to set the O7_DICTIONARY_ACCESSIBILTY initialization parameter to FALSE by issuing an ALTER SYSTEM statement in SQL*Plus.

ALTER SYSTEM SET O7_DICTIONARY_ACCESSIBILITY=FALSE SCOPE=SPFILE;

When you set O7_DICTIONARY_ACCESSIBILITY to FALSE, system privileges that enable access to objects in any schema (for example, users who have ANY privileges, such as CREATE ANY PROCEDURE) do not allow access to objects in the SYS schema. This means that access to the objects in the SYS schema (data dictionary objects) is restricted to users who connect using the SYSDBA privilege. Remember that the SYS user must log in with either the SYSDBA or SYSOPER privilege; otherwise, an ORA-28009: connection as SYS should be as SYSDBA or SYSOPER error is raised. If you set O7_DICTIONARY_ACCESSIBILITY to TRUE, then you would be able to log in to the database as user SYS without having to specify the SYSDBA or SYSOPER privilege.

System privileges that provide access to objects in other schemas do not give other users access to objects in the SYS schema. For example, the SELECT ANY TABLE privilege allows users to access views and tables in other schemas, but does not enable them to select dictionary objects (base tables of dynamic performance views, regular views, packages, and synonyms). You can, however, grant these users explicit object privileges to access objects in the SYS schema.

See Oracle Database Reference for more information about the O7_DICTIONARY_ACCESSIBILITY initialization parameter.

Allowing Access to Objects in the SYS Schema

Users with explicit object privileges or those who connect with administrative privileges (SYSDBA) can access objects in the SYS schema.

Table 4-1 lists roles that you can grant to users who need access to objects in the SYS schema.

Additionally, you can grant the SELECT ANY DICTIONARY system privilege to users who require access to tables created in the SYS schema. This system privilege allows query access to any object in the SYS schema, including tables created in that schema. It must be granted individually to each user requiring the privilege. It is not included in GRANT ALL PRIVILEGES, but it can be granted through a role.

The Functionality of Roles

Roles are useful for quickly and easily granting permissions to users. Although you can use Oracle Database-defined roles, you have more control and continuity if you create your own roles that contain only the privileges pertaining to your requirements. Oracle may change or remove the privileges in an Oracle Database-defined role, as it has with the CONNECT role, which now has only the CREATE SESSION privilege. Formerly, this role had eight other privileges.

Roles have the following functionality:

• A role can be granted system or object privileges.

• Any role can be granted to any database user.

• Each role granted to a user is, at a given time, either enabled or disabled. A user's security domain includes the privileges of all roles currently enabled for the user and excludes the privileges of any roles currently disabled for the user. Oracle Database allows database applications and users to enable and disable roles to provide selective availability of privileges.

• A role can be granted to other roles. However, a role cannot be granted to itself and cannot be granted circularly. For example, role role1 cannot be granted to role role2 if role role2 has previously been granted to role role1.

• If a role is not password authenticated or a secure application role, then you can grant the role indirectly to the user. An indirectly granted role is a role granted to the user through another role that has already been granted to this user. For example, suppose you grant user psmith the role1 role. Then you grant the role2 and role3 roles to the role1 role. Roles role2 and role3 are now under role1. This means psmith has been indirectly granted the roles role2 and role3, in addition to the direct grant of role1. Enabling the direct role1 for psmith enables the indirect roles role2 and role3 for this user as well.

• Optionally, you can make a directly granted role a default role. You enable or disable the default role status of a directly granted role by using the DEFAULT ROLE clause of the ALTER USER statement. Ensure that the DEFAULT ROLE clause refers only to roles that have been directly granted to the user. To find the directly granted roles for a user, query the DBA_ROLE_PRIVS data dictionary view. This view does not include the user's indirectly granted roles. To find roles that are granted to other roles, query the ROLE_ROLE_PRIVS view.

• If the role is password authenticated or a secure application role, then you cannot grant it indirectly to the user, nor can you make it a default role. You only can grant this type of role directly to the user. Typically, you enable password authenticated or secure application roles by using the SET ROLE statement.

Properties of Roles and Why They Are Advantageous

Table 4-2 describes the properties of roles that enable easier privilege management within a database.

Database administrators often create roles for a database application. You should grant a secure application role all privileges necessary to run the application. You then can grant the secure application role to other roles or users. An application can have several different roles, each granted a different set of privileges that allow for more or less data access while using the application.

The DBA can create a role with a password to prevent unauthorized use of the privileges granted to the role. Typically, an application is designed so that when it starts, it enables the proper role. As a result, an application user does not need to know the password for an application role.

Common Uses of Roles

In general, you create a role to serve one of two purposes:

• To manage the privileges for a database application (see "Common Uses of Application Roles")

• To manage the privileges for a user group (see "Common Uses of User Roles")

Figure 4-1 and the sections that follow describe the two uses of roles.

Figure 4-1 Common Uses for Roles

Description of "Figure 4-1 Common Uses for Roles"

How Roles Affect the Scope of a User's Privileges

Each role and user has its own unique security domain. The security domain of a role includes the privileges granted to the role plus those privileges granted to any roles that are granted to the role.

The security domain of a user includes privileges on all schema objects in the corresponding schema, the privileges granted to the user, and the privileges of roles granted to the user that are currently enabled. (A role can be simultaneously enabled for one user and disabled for another.) This domain also includes the privileges and roles granted to the role PUBLIC. The PUBLIC role represents all users in the database.

How Roles Work in PL/SQL Blocks

The use of roles in a PL/SQL block depends on whether it is an anonymous block or a named block (stored procedure, function, or trigger), and whether it executes with definer's rights or invoker's rights.

How Roles Aid or Restrict DDL Usage

A user requires one or more privileges to successfully execute a DDL statement, depending on the statement. For example, to create a table, the user must have the CREATE TABLE or CREATE ANY TABLE system privilege. To create a view of a table that belongs to another user, the creator requires the CREATE VIEW or CREATE ANY VIEW system privilege and either the SELECT object privilege for the table or the SELECT ANY TABLE system privilege.

Oracle Database avoids the dependencies on privileges received by way of roles by restricting the use of specific privileges in certain DDL statements. The following rules describe these privilege restrictions concerning DDL statements:

• All system privileges and object privileges that permit a user to perform a DDL operation are usable when received through a role. For example:

  • System privileges: CREATE TABLE, CREATE VIEW, and CREATE PROCEDURE privileges

  • Object privileges: ALTER and INDEX privileges for a table

    You cannot use the REFERENCES object privilege for a table to define the foreign key of a table if the privilege is received through a role.

• All system privileges and object privileges that allow a user to perform a DML operation that is required to issue a DDL statement are not usable when received through a role. The security domain does not contain roles when a CREATE VIEW statement is used. For example, a user who is granted the SELECT ANY TABLE system privilege or the SELECT object privilege for a table through a role cannot use either of these privileges to create a view on a table that belongs to another user. This is because views are definer's rights objects, so when creating them you cannot use any privileges (neither system privileges or object privileges) granted to you through a role. If the privilege is granted directly to you, then you can use the privilege. However, if the privilege is revoked at a later time, then the view definition becomes invalid ("contains errors") and must recompiled before it can be used again.

The following example further clarifies the permitted and restricted uses of privileges received through roles.

Assume that a user is:

• Granted a role that has the CREATE VIEW system privilege

• Directly granted a role that has the SELECT object privilege for the employees table

• Directly granted the SELECT object privilege for the departments table

Given these directly and indirectly granted privileges:

• The user can issue SELECT statements on both the employees and departments tables.

• Although the user has both the CREATE VIEW and SELECT privilege for the employees table through a role, the user cannot create a view on the employees table, because the SELECT object privilege for the employees table was granted through a role.

• The user can create a view on the departments table, because the user has the CREATE VIEW privilege through a role and the SELECT privilege for the departments table directly.

How Operating Systems Can Aid Roles

In some environments, you can administer database security using the operating system. The operating system can be used to grant and revoke database roles and to manage their password authentication. This capability is not available on all operating systems.

How Roles Work in a Distributed Environment

When you use roles in a distributed database environment, ensure that all needed roles are set as the default roles for a distributed (remote) session. These roles cannot be enabled when the user connects to a remote database from within a local database session. For example, the user cannot execute a remote procedure that attempts to enable a role at the remote site.

Authorizing a Role by Using the Database

You can protect a role authorized by the database by assigning the role a password. If a user is granted a role protected by a password, then you can enable or disable the role by supplying the proper password for the role in the SET ROLE statement. You cannot authenticate a password-authenticated role on logon, even if you add it to the list of default roles. You must explicitly enable it with the SET ROLE statement using the required password.

Example 4-4 shows how to set a password-authenticated role by using the SET ROLE statement.

SET ROLE clerk IDENTIFIED BY password;

Example 4-2, "Creating a User Role Authorized by a Password" shows a CREATE ROLE statement that creates a role called clerk. When it is enabled, the password must be supplied.

Authorizing a Role by Using an Application

An application role (secure application role) can be enabled only by applications using an authorized PL/SQL package. Application developers do not need to secure a role by embedding passwords inside applications. Instead, they can create an application role and specify which PL/SQL package is authorized to enable the role.

To create a role enabled by an authorized PL/SQL package, use the IDENTIFIED USING package_name clause in the CREATE ROLE SQL statement.

Example 4-5 indicates that the role admin_role is an application role and the role can only be enabled by any module defined inside the PL/SQL package hr.admin.

CREATE ROLE admin_role IDENTIFIED USING hr.admin;

See the following for more information about secure application roles:

• "Securing Role Privileges by Using Secure Application Roles"

• "Creating Secure Application Roles to Control Access to Applications"

• Oracle Database 2 Day + Security Guide

Authorizing a Role by Using an External Source

You can define the external role locally in the database, but you cannot grant the external role to global users, to global roles, or to any other roles in the database. You can create roles that are authorized by the operating system or network clients.

Example 4-6 creates a role named accts_rec and requires that the user is authorized by an external source before it can be enabled:

CREATE ROLE accts_rec IDENTIFIED EXTERNALLY;

Global Role Authorization by an Enterprise Directory Service

A role can be defined as a global role, where a (global) user can only be authorized to use the role by an enterprise directory service. You define the global role locally in the database by granting privileges and roles to it, but you cannot grant the global role itself to any user or other role in the database. When a global user attempts to connect to the database, the enterprise directory is queried to obtain any global roles associated with the user.

Example 4-7 creates a global role.

CREATE ROLE supervisor IDENTIFIED GLOBALLY;

Global roles are one component of enterprise user security. A global role only applies to one database, but you can grant it to an enterprise role defined in the enterprise directory. An enterprise role is a directory structure that contains global roles on multiple databases and can be granted to enterprise users.

See "Configuring Global User Authentication and Authorization" for a general discussion of global authentication and authorization of users, and its role in enterprise user management.

Who Can Grant or Revoke Roles?

Any user with the GRANT ANY ROLE system privilege can grant or revoke any role except a global role to or from other users or roles of the database. (A global role is managed in a directory, such as Oracle Internet Directory, but its privileges are contained within a single database.) By default, the SYS or SYSTEM user has this privilege. You should grant this system privilege conservatively because it is very powerful.

Any user granted a role with the ADMIN OPTION can grant or revoke that role to or from other users or roles of the database. This option allows administrative powers for roles to be granted on a selective basis.

Potential Security Problems of Using Ad Hoc Tools

Prebuilt database applications explicitly control the potential actions of a user, including the enabling and disabling of user roles while using the application. By contrast, ad hoc query tools such as SQL*Plus, permit a user to submit any SQL statement (which may or may not succeed), including enabling and disabling a granted role.

Potentially, an application user can exercise the privileges attached to that application to issue destructive SQL statements against database tables by using an ad hoc tool.

For example, consider the following scenario:

• The Vacation application has a corresponding vacation role.

• The vacation role includes the privileges to issue SELECT, INSERT, UPDATE, and DELETE statements against the emp_tab table.

• The Vacation application controls the use of privileges obtained through the vacation role.

Now, consider a user who has been granted the vacation role. Suppose that, instead of using the Vacation application, the user executes SQL*Plus. At this point, the user is restricted only by the privileges granted to him explicitly or through roles, including the vacation role. Because SQL*Plus is an ad hoc query tool, the user is not restricted to a set of predefined actions, as with designed database applications. The user can query or modify data in the emp_tab table as he or she chooses.

Limiting Roles Through the PRODUCT_USER_PROFILE Table

You can use the PRODUCT_USER_PROFILE table, which is in the SYSTEM schema, to disable certain SQL and SQL*Plus commands in the SQL*Plus environment for each user. SQL*Plus, not the Oracle Database, enforces this security. You can even restrict access to the GRANT, REVOKE, and SET ROLE commands to control user ability to change their database privileges.

The PRODUCT_USER_PROFILE table enables you to list roles that you do not want users to activate with an application. You can also explicitly disable the use of various commands, such as SET ROLE.

For example, you could create an entry in the PRODUCT_USER_PROFILE table to:

• Disallow the use of the clerk and manager roles with SQL*Plus

• Disallow the use of SET ROLE with SQL*Plus

Suppose user Marla connects to the database using SQL*Plus. Marla has the clerk, manager, and analyst roles. As a result of the preceding entry in PRODUCT_USER_PROFILE, Marla is only able to exercise her analyst role with SQL*Plus. Also, when Ginny attempts to issue a SET ROLE statement, she is explicitly prevented from doing so because of the entry in the PRODUCT_USER_PROFILE table prohibiting use of SET ROLE.

Be aware that the PRODUCT_USER_PROFILE table does not completely guarantee security, for multiple reasons. In the preceding example, while SET ROLE is disallowed with SQL*Plus, if Marla had other privileges granted to her directly, then she could exercise these using SQL*Plus.

Using Stored Procedures to Encapsulate Business Logic

Stored procedures encapsulate the use of privileges with business logic so that privileges are only exercised in the context of a well-formed business transaction. For example, an application developer can create a procedure to update the employee name and address in the employees table, which enforces that the data can only be updated in normal business hours. Also, rather than grant a human resources clerk the UPDATE privilege on the employees table, a security administrator may grant the privilege on the procedure only. Then, the human resources clerk can exercise the privilege only in the context of the procedures, and cannot update the employees table directly.

Granting and Revoking Object Privileges

Object privileges can be granted to and revoked from users and roles. If you grant object privileges to roles, then you can make the privileges selectively available.

You can grant or revoke object privileges to or from users and roles using the following methods:

• The GRANT and REVOKE SQL statements

• Oracle Enterprise Manager Database Control

Who Can Grant Object Privileges?

A user automatically has all object privileges for schema objects contained in his or her schema. A user with the GRANT ANY OBJECT PRIVILEGE can grant any specified object privilege to another user with or without the WITH GRANT OPTION clause of the GRANT statement. A user with the GRANT ANY OBJECT PRIVILEGE can also use that privilege to revoke any object privilege that was granted either by the object owner or by some other user with the GRANT ANY OBJECT PRIVILEGE privilege. Otherwise, the grantee can use the privilege, but cannot grant it to other users.

Using Object Privileges with Synonyms

You can use the CREATE SYNONYM statement to create synonyms for tables, views, sequences, operators, procedures, stored functions, packages, materialized views, Java class schema objects, user-defined object types, or other synonyms. If you grant users the privilege to use the synonym, then the object privileges granted on the underlying objects apply whether the user references the base object by name or by using the synonym.

For example, suppose user OE creates the following synonym for the CUSTOMERS table:

CREATE SYNONYM customer_syn FOR CUSTOMERS;

Then OE grants the SELECT privilege on the customer_syn synonym to user HR.

GRANT SELECT ON customer_syn TO HR;

User HR then tries either of the following queries:

SELECT COUNT(*) FROM OE.customer_syn;

SELECT COUNT(*) FROM OE.CUSTOMERS;

Both queries will yield the same result:

COUNT(*)
----------
       319

Be aware that when you grant the synonym to another user, the grant applies to the underlying object that the synonym represents, not to the synonym itself. For example, if user HR queries the ALL_TAB_PRIVS data dictionary view for his privileges, he will learn the following:

SELECT TABLE_SCHEMA, TABLE_NAME, PRIVILEGE 
FROM ALL_TAB_PRIVS 
WHERE TABLE_SCHEMA = 'OE';

TABLE_SCHEMA  TABLE_NAME  PRIVILEGE
------------  ----------  ----------
OE            CUSTOMER    SELECT
OE            ORDERS      UPDATE

The results show that in addition to other privileges, he has the SELECT privilege for the underlying object of the customer_syn synonym, which is the OE.CUSTOMER table.

At this point, if user OE then revokes the SELECT privilege on the customer_syn synonym from HR, here are the results if HR checks his privileges again:

TABLE_SCHEMA  TABLE_NAME  PRIVILEGE
------------  ----------  ---------
OE            ORDERS      UPDATE

User HR no longer has the SELECT privilege for the OE.CUSTOMER table. If he tries to query the OE.CUSTOMERS table, then the following error appears:

SELECT COUNT(*) FROM OE.CUSTOMERS;

ERROR at line 1:
ORA-00942: table or view does not exist

How Table Privileges Affect Data Manipulation Language Operations

You can grant privileges to use the DELETE, INSERT, SELECT, and UPDATE DML operations on a table or view. Grant these privileges only to users and roles that need to query or manipulate data in a table.

You can restrict INSERT and UPDATE privileges for a table to specific columns of the table. With a selective INSERT privilege, a privileged user can insert a row with values for the selected columns. All other columns receive NULL or the default value of the column. With a selective UPDATE privilege, a user can update only specific column values of a row. You can use selective INSERT and UPDATE privileges to restrict user access to sensitive data.

For example, if you do not want data entry users to alter the salary column of the employees table, then selective INSERT or UPDATE privileges can be granted that exclude the salary column. Alternatively, a view that excludes the salary column could satisfy this need for additional security.

How Table Privileges Affect Data Definition Language Operations

The ALTER, INDEX, and REFERENCES privileges allow DDL operations to be performed on a table. Because these privileges allow other users to alter or create dependencies on a table, you should grant these privileges conservatively.

A user attempting to perform a DDL operation on a table may need additional system or object privileges. For example, to create a trigger on a table, the user requires both the ALTER TABLE object privilege for the table and the CREATE TRIGGER system privilege.

As with the INSERT and UPDATE privileges, you can grant the REFERENCES privilege on specific columns of a table. The REFERENCES privilege enables the grantee to use the table on which the grant is made as a parent key to any foreign keys that the grantee wishes to create in his or her own tables. This action is controlled with a special privilege because the presence of foreign keys restricts the data manipulation and table alterations that can be done to the parent key. A column-specific REFERENCES privilege restricts the grantee to using the named columns (which, of course, must include at least one primary or unique key of the parent table).

About View Privileges

A view is a presentation of data selected from one or more tables, possibly including other views. A view shows the structure of the underlying tables. Its selected data can be thought of as the result of a stored query. A view contains no actual data but rather derives what it shows from the tables and views on which it is based. You can query a view, and change the data it represents. Data in a view can be updated or deleted, and new data inserted. These operations directly alter the tables on which the view is based, and are subject to the integrity constraints and triggers of the base tables.

You can apply DML object privileges to views, similar to tables. Object privileges for a view allow various DML operations, which as noted affect the base tables from which the view is derived.

Privileges Required to Create Views

To create a view, you must meet the following requirements:

• You must have been granted one of the following system privileges, either explicitly or through a role:

  • The CREATE VIEW system privilege (to create a view in your schema)

  • The CREATE ANY VIEW system privilege (to create a view in the schema of another user)

• You must have been explicitly granted one of the following privileges:

  • The SELECT, INSERT, UPDATE, or DELETE object privileges on all base objects underlying the view

  • The SELECT ANY TABLE, INSERT ANY TABLE, UPDATE ANY TABLE, or DELETE ANY TABLE system privileges

• In addition, before you can grant other users access to you view, you must have object privileges to the base objects with the GRANT OPTION clause or appropriate system privileges with the ADMIN OPTION clause. If you do not have these privileges, then you cannot to grant other users access to your view. If you try, an ORA-01720: grant option does not exist for object_name error is raised, with object_name referring to the view's underlying object for which you do not have the sufficient privilege.

  See Also:

  Oracle Database SQL Language Reference

Increasing Table Security with Views

To use a view, the user must have the appropriate privileges but only for the view itself, not its underlying objects. However, if access privileges for the underlying objects of the view are removed, then the user no longer has access. This behavior occurs because the security domain that is used when a user queries the view is that of the definer of the view. If the privileges on the underlying objects are revoked from the view's definer, then the view becomes invalid, and no one can use the view. Therefore, even if a user has been granted access to the view, the user may not be able to use the view if the definer's rights have been revoked from the view's underlying objects.

For example, suppose User A creates a view. User A has definer's rights on the underlying objects of the view. User A then grants the SELECT privilege on that view to User B so that User B can query the view. But if User A no longer has access to the underlying objects of that view, then User B no longer has access either.

Views add two more levels of security for tables, column-level security and value-based security, as follows:

• A view can provide access to selected columns of base tables. For example, you can define a view on the employees table to show only the employee_id, last_name, and manager_id columns:

  CREATE VIEW employees_manager AS 
      SELECT last_name, employee_id, manager_id FROM employees; 
  

• A view can provide value-based security for the information in a table. A WHERE clause in the definition of a view displays only selected rows of base tables. Consider the following two examples:

  CREATE VIEW lowsal AS 
      SELECT * FROM employees 
      WHERE salary < 10000; 
  

  The lowsal view allows access to all rows of the employees table that have a salary value less than 10000. Notice that all columns of the employees table are accessible in the lowsal view.

  CREATE VIEW own_salary AS 
      SELECT last_name, salary 
      FROM employees 
      WHERE last_name = USER; 
  

  In the own_salary view, only the rows with an last_name that matches the current user of the view are accessible. The own_salary view uses the user pseudo column, whose values always refer to the current user. This view combines both column-level security and value-based security.

Using the EXECUTE Privilege for Procedure Privileges

The EXECUTE privilege is the only object privilege for procedures, including standalone procedures and functions, and for those within packages. Grant this privilege only to users who need to run a procedure or to compile another procedure that calls a desired procedure.

Procedure Execution and Security Domains

A user with the EXECUTE object privilege for a specific procedure can execute the procedure or compile a program unit that references the procedure. Oracle Database performs a run-time privilege check when any PL/SQL unit is called. A user with the EXECUTE ANY PROCEDURE system privilege can execute any procedure in the database. Privileges to run procedures can be granted to a user through roles.

How Procedure Privileges Affect Definer's Rights

The owner of a procedure, called the definer, must have all the necessary object privileges for referenced objects. If the procedure owner grants to another user the right to use that procedure, then the privileges of the procedure owner (on the objects referenced by the procedure) apply to the grantee user's exercise of the procedure. The privileges of the procedure's definer must be granted directly to the user, not granted through roles. These are termed definer's rights.

The user of a procedure who is not its owner is called the invoker. Additional privileges on referenced objects are required for invoker's rights procedures, but not for definer's rights procedures.

A user of a definer's rights procedure requires only the privilege to execute the procedure and no privileges on the underlying objects that the procedure accesses. This is because a definer's rights procedure operates under the security domain of the user who owns the procedure, regardless of who is executing it. The owner of the procedure must have all the necessary object privileges for referenced objects. Fewer privileges have to be granted to users of a definer's rights procedure. This results in stronger control of database access.

You can use definer's rights procedures to control access to private database objects and add a level of database security. By writing a definer's rights procedure and granting only EXECUTE privilege to a user, the user can be forced to access the referenced objects only through the procedure.

At run time, Oracle Database checks whether the privileges of the owner of a definer's rights stored procedure allow access to that procedure's referenced objects, before the procedure is executed. If a necessary privilege on a referenced object was revoked from the owner of a definer's rights procedure, then the procedure cannot be run by the owner or any other user.

How Procedure Privileges Affect Invoker's Rights

An invoker's rights procedure executes with all of the invoker's privileges. Oracle Database enables the privileges that were granted to the invoker through any of the invoker's enabled roles to take effect, unless a definer's rights procedure calls the invoker's rights procedure directly or indirectly. A user of an invoker's rights procedure needs privileges (granted to the user either directly or through a role) on objects that the procedure accesses through external references that are resolved in the schema of the invoker.

The invoker needs privileges at run time to access program references embedded in DML statements or dynamic SQL statements, because they are effectively recompiled at run time.

For all other external references, such as direct PL/SQL function calls, Oracle Database checks the privileges of the owner at compile time, but does not perform a run-time check. Therefore, the user of an invoker's rights procedure does not need privileges on external references outside DML or dynamic SQL statements. Alternatively, the developer of an invoker's rights procedure must only grant privileges on the procedure itself, not on all objects directly referenced by the invoker's rights procedure.

You can create a software bundle that consists of multiple program units, some with definer's rights and others with invoker's rights, and restrict the program entry points (controlled step-in). A user who has the privilege to run an entry-point procedure can also execute internal program units indirectly, but cannot directly call the internal programs. For very precise control over query processing, you can create a PL/SQL package specification with explicit cursors.

System Privileges Required to Create or Replace a Procedure

To create or replace a procedure in your own schema, you must have the CREATE PROCEDURE system privilege. To create or replace a procedure in another user's schema, you must have the CREATE ANY PROCEDURE system privilege.

The user who owns the procedure also must have privileges for schema objects referenced in the procedure body. To create a procedure, you need to have been explicitly granted the necessary privileges (system or object) on all objects referenced by the procedure. You cannot obtain the required privileges through roles. This includes the EXECUTE privilege for any procedures that are called inside the procedure being created.

System Privileges Required to Compile a Procedure

To compile a standalone procedure, run the ALTER PROCEDURE statement with the COMPILE clause. To compile a procedure that is part of a package, run the ALTER PACKAGE statement.

Example 4-9 shows how to compile a standalone procedure.

ALTER PROCEDURE psmith.remove_emp COMPILE;

If the standalone or packaged procedure is in another user's schema, you must have the ALTER ANY PROCEDURE privilege to recompile it. You can recompile procedures in your own schema without any privileges.

How Procedure Privileges Affect Packages and Package Objects

A user with the EXECUTE object privilege for a package can execute any public procedure or function in the package, and can access or modify the value of any public package variable. You cannot grant specific EXECUTE privileges for individual constructs in a package. Therefore, you may find it useful to consider two alternatives for establishing security when developing procedures, functions, and packages for a database application. The following examples describe these alternatives.

Procedure Privileges and Packages and Package Objects: Example 1

Example 4-10 shows four procedures created in the bodies of two packages.

CREATE PACKAGE BODY hire_fire AS 
  PROCEDURE hire(...) IS 
    BEGIN 
      INSERT INTO employees . . . 
    END hire; 
  PROCEDURE fire(...) IS 
    BEGIN 
      DELETE FROM employees . . . 
    END fire; 
END hire_fire; 

CREATE PACKAGE BODY raise_bonus AS 
  PROCEDURE give_raise(...) IS 
    BEGIN 
      UPDATE employees SET salary = . . . 
    END give_raise; 
  PROCEDURE give_bonus(...) IS 
    BEGIN 
      UPDATE employees SET bonus = . . . 
    END give_bonus; 
END raise_bonus; 

The following GRANT EXECUTE statements enable the big_bosses and little_bosses roles to run the appropriate procedures:

GRANT EXECUTE ON hire_fire TO big_bosses; 
GRANT EXECUTE ON raise_bonus TO little_bosses; 

Procedure Privileges and Packages and Package Objects: Example 2

This example shows four procedure definitions within the body of a single package. Two additional standalone procedures and a package are created specifically to provide access to the procedures defined in the main package.

CREATE PACKAGE BODY employee_changes AS 
  PROCEDURE change_salary(...) IS BEGIN ... END; 
  PROCEDURE change_bonus(...) IS BEGIN ... END; 
  PROCEDURE insert_employee(...) IS BEGIN ... END; 
  PROCEDURE delete_employee(...) IS BEGIN ... END; 
END employee_changes; 
 
CREATE PROCEDURE hire 
  BEGIN 
    employee_changes.insert_employee(...) 
  END hire; 
 
CREATE PROCEDURE fire 
  BEGIN 
    employee_changes.delete_employee(...) 
  END fire; 
 
PACKAGE raise_bonus IS 
  PROCEDURE give_raise(...) AS 
    BEGIN 
      employee_changes.change_salary(...) 
    END give_raise; 
 
  PROCEDURE give_bonus(...) 
    BEGIN 
      employee_changes.change_bonus(...) 
    END give_bonus; 

Using this method, the procedures that actually do the work (the procedures in the employee_changes package) are defined in a single package and can share declared global variables, cursors, on so on. By declaring top-level procedures, hire and fire, and an additional package, raise_bonus, you can grant selective EXECUTE privileges on procedures in the main package:

GRANT EXECUTE ON hire, fire TO big_bosses; 
GRANT EXECUTE ON raise_bonus TO little_bosses; 

System Privileges for Named Types

Table 4-4 lists system privileges for named types (object types, VARRAYs, and nested tables).

The RESOURCE role includes the CREATE TYPE system privilege. The DBA role includes all of these privileges.

Object Privileges

The only object privilege that applies to named types is EXECUTE. If the EXECUTE privilege exists on a named type, then a user can use the named type to:

• Define a table

• Define a column in a relational table

• Declare a variable or parameter of the named type

The EXECUTE privilege permits a user to invoke the methods in the type, including the type constructor. This is similar to the EXECUTE privilege on a stored PL/SQL procedure.

Method Execution Model

Method execution is the same as any other stored PL/SQL procedure.

Privileges Required to Create Types and Tables Using Types

To create a type, you must meet the following requirements:

• You must have the CREATE TYPE system privilege to create a type in your schema or the CREATE ANY TYPE system privilege to create a type in the schema of another user. These privileges can be acquired explicitly or through a role.

• The owner of the type must be explicitly granted the EXECUTE object privileges to access all other types referenced within the definition of the type, or have been granted the EXECUTE ANY TYPE system privilege. The owner cannot obtain the required privileges through roles.

• If the type owner intends to grant access to the type to other users, then the owner must receive the EXECUTE privileges to the referenced types with the GRANT OPTION or the EXECUTE ANY TYPE system privilege with the ADMIN OPTION. If not, then the type owner has insufficient privileges to grant access on the type to other users.

To create a table using types, you must meet the requirements for creating a table and the following additional requirements:

• The owner of the table must have been directly granted the EXECUTE object privilege to access all types referenced by the table, or has been granted the EXECUTE ANY TYPE system privilege. The owner cannot exercise the required privileges if these privileges were granted through roles.

• If the table owner intends to grant access to the table to other users, then the owner must have the EXECUTE privilege to the referenced types with the GRANT OPTION or the EXECUTE ANY TYPE system privilege with the ADMIN OPTION. If not, then the table owner has insufficient privileges to grant access on the table.

Example of Privileges for Creating Types and Tables Using Types

Assume that three users exist with the CONNECT and RESOURCE roles:

• user1

• user2

• user3

The following DDL is run in the schema of user1:

CREATE TYPE type1 AS OBJECT (
  attr1 NUMBER);

CREATE TYPE type2 AS OBJECT (
  attr2 NUMBER);

GRANT EXECUTE ON type1 TO user2;
GRANT EXECUTE ON type2 TO user2 WITH GRANT OPTION;

The following DDL is performed in the schema of user2:

CREATE TABLE tab1 OF user1.type1;
CREATE TYPE type3 AS OBJECT (
  attr3 user1.type2);
CREATE TABLE tab2 (
  col1 user1.type2);

The following statements succeed because user2 has EXECUTE privilege on user1.type2 with the GRANT OPTION:

GRANT EXECUTE ON type3 TO user3;
GRANT SELECT on tab2 TO user3;

However, the following grant fails because user2 does not have EXECUTE privilege on user1.type1 with the GRANT OPTION:

GRANT SELECT ON tab1 TO user3;

The following statements can be successfully run by user3:

CREATE TYPE type4 AS OBJECT (
  attr4 user2.type3);
CREATE TABLE tab3 OF type4;

Privileges on Type Access and Object Access

Existing column-level and table-level privileges for DML statements apply to both column objects and row objects.

Table 4-5 lists the privileges for object tables.

Similar table privileges and column privileges apply to column objects. Retrieving instances does not in itself reveal type information. However, clients must access named type information to interpret the type instance images. When a client requests type information, Oracle Database checks for the EXECUTE privilege on the type.

Consider the following schema:

CREATE TYPE emp_type (
    eno NUMBER, ename CHAR(31), eaddr addr_t);
CREATE TABLE emp OF emp_t;

In addition, consider the following two queries:

SELECT VALUE(emp) FROM emp;
SELECT eno, ename FROM emp;

For either query, Oracle Database checks the SELECT privilege of the user for the emp table. For the first query, the user must obtain the emp_type type information to interpret the data. When the query accesses the emp_type type, Oracle Database checks the EXECUTE privilege of the user.

The second query, however, does not involve named types, so Oracle Database does not check type privileges.

In addition, by using the schema from the previous section, user3 can perform the following queries:

SELECT tab1.col1.attr2 FROM user2.tab1 tab1;
SELECT attr4.attr3.attr2 FROM tab3;

Note that in both SELECT statements, user3 does not have explicit privileges on the underlying types, but the statement succeeds because the type and table owners have the necessary privileges with the GRANT OPTION.

Oracle Database checks privileges on the following events, and returns an error if the client does not have the privilege for the action:

• Pinning an object in the object cache using its REF value causes Oracle Database to check for the SELECT privilege on the containing object table.

• Modifying an existing object or flushing an object from the object cache causes Oracle Database to check for the UPDATE privilege on the destination object table.

• Flushing a new object causes Oracle Database to check for the INSERT privilege on the destination object table.

• Deleting an object causes Oracle Database to check for the DELETE privilege on the destination table.

• Pinning an object of a named type causes Oracle Database to check EXECUTE privilege on the object.

Modifying the attributes of an object in a client third-generation language application causes Oracle Database to update the entire object. Therefore, the user needs the UPDATE privilege on the object table. Having the UPDATE privilege on only certain columns of the object table is not sufficient, even if the application only modifies attributes corresponding to those columns. Therefore, Oracle Database does not support column-level privileges for object tables.

Type Dependencies

As with stored objects, such as procedures and tables, types being referenced by other objects are called dependencies. There are some special issues for types on which tables depend. Because a table contains data that relies on the type definition for access, any change to the type causes all stored data to become inaccessible. Changes that can cause this are when necessary privileges required to use the type are revoked, or the type or dependent types are dropped. If these actions occur, then the table becomes invalid and cannot be accessed.

A table that is invalid because of missing privileges can automatically become valid and accessible if the required privileges are granted again. A table that is invalid because a dependent type was dropped can never be accessed again, and the only permissible action is to drop the table.

Because of the severe effects that revoking a privilege on a type or dropping a type can cause, the SQL statements REVOKE and DROP TYPE, by default, implement restricted semantics. This means that if the named type in either statement has table or type dependents, then an error is received and the statement cancels. However, if the FORCE clause for either statement is used, then the statement always succeeds. If there are depended-upon tables, then they are invalidated.

Granting the ADMIN Option

If you specify the WITH ADMIN OPTION clause when you grant a privilege or role to a user or role, then the privilege grant has the following expanded capabilities:

• The grantee can grant or revoke the system privilege or role to or from any other user or role in the database. Users cannot revoke a role from themselves.

• The grantee can grant the system privilege or role with the ADMIN option.

• The grantee of a role can alter or drop the role.

Example 4-13 grants the new_dba role with the WITH ADMIN OPTION clause to user michael.

GRANT new_dba TO michael WITH ADMIN OPTION;

User michael is able to not only use all of the privileges implicit in the new_dba role, but he can also grant, revoke, and drop the new_dba role as deemed necessary. Because of these powerful capabilities, use caution when granting system privileges or roles with the ADMIN option. These privileges are usually reserved for a security administrator, and are rarely granted to other administrators or users of the system.

Creating a New User with the GRANT Statement

Oracle Database enables you to create a new user with the GRANT statement. If you specify a password using the IDENTIFIED BY clause, and the user name does not exist in the database, then a new user with that user name and password is created.

Example 4-14 creates psmith as a new user while granting psmith the CREATE SESSION system privilege.

GRANT CREATE SESSION TO psmith IDENTIFIED BY password;

Specifying the GRANT OPTION Clause

Specify the WITH GRANT OPTION clause with the GRANT statement to enable the grantee to grant the object privileges to other users. The user whose schema contains an object is automatically granted all associated object privileges with the GRANT OPTION. This special privilege allows the grantee several expanded privileges:

• The grantee can grant the object privilege to any user in the database, with or without the GRANT OPTION, and to any role in the database.

• If both of the following conditions are true, then the grantee can create views on the table, and grant the corresponding privileges on the views to any user or role in the database:

  • The grantee receives object privileges for the table with the GRANT OPTION.

  • The grantee has the CREATE VIEW or CREATE ANY VIEW system privilege.

Granting Object Privileges on Behalf of the Object Owner

The GRANT ANY OBJECT PRIVILEGE system privilege enables users to grant and revoke any object privilege on behalf of the object owner. This privilege provides a convenient means for database and application administrators to grant access to objects in any schema without requiring that they connect to the schema. Login credentials do not need to be maintained for schema owners who have this privilege, which reduces the number of connections required during configuration.

This system privilege is part of the Oracle Database supplied DBA role and is thus granted (with the ADMIN option) to any user connecting AS SYSDBA (user SYS). As with other system privileges, the GRANT ANY OBJECT PRIVILEGE system privilege can only be granted by a user who possesses the ADMIN option.

The recorded grantor of access rights to an object is either the object owner or the person exercising the GRANT ANY OBJECT PRIVILEGE system privilege. If the grantor with GRANT ANY OBJECT PRIVILEGE does not have the object privilege with the GRANT OPTION, then the object owner is shown as the grantor. Otherwise, when that grantor has the object privilege with the GRANT OPTION, then that grantor is recorded as the grantor of the grant.

For example, consider the following scenario. User adams possesses the GRANT ANY OBJECT PRIVILEGE system privilege. He does not possess any other grant privileges. He issues the following statement:

GRANT SELECT ON HR.EMPLOYEES TO blake WITH GRANT OPTION;

If you examine the DBA_TAB_PRIVS view, then you will see that hr is shown as the grantor of the privilege:

SELECT GRANTEE, GRANTOR, PRIVILEGE, GRANTABLE
  FROM DBA_TAB_PRIVS 
  WHERE TABLE_NAME = 'EMPLOYEES' and OWNER = 'HR';

GRANTEE  GRANTOR PRIVILEGE    GRANTABLE
-------- ------- -----------  ----------
BLAKE    HR       SELECT      YES       

Now assume that user blake also has the GRANT ANY OBJECT PRIVILEGE system. He issues the following statement:

GRANT SELECT ON HR.EMPLOYEES TO clark;

In this case, when you query the DBA_TAB_PRIVS view again, you see that blake is shown as being the grantor of the privilege:

GRANTEE  GRANTOR  PRIVILEGE  GRANTABLE
-------- -------- ---------  ----------
BLAKE    HR       SELECT     YES       
CLARK    BLAKE    SELECT     NO        

This occurs because blake already possesses the SELECT privilege on HR.EMPLOYEES with the GRANT OPTION.

Granting Privileges on Columns

You can grant INSERT, UPDATE, or REFERENCES privileges on individual columns in a table.

The following statement grants the INSERT privilege on the acct_no column of the accounts table to user psmith:

GRANT INSERT (acct_no) ON accounts TO psmith;

In the following example, object privilege for the ename and job columns of the emp table are granted to the users jfee and tsmith:

GRANT INSERT(ename, job) ON emp TO jfee, tsmith;

Row-Level Access Control

You can also provide access control at the row level, that is, within objects, using Virtual Private Database (VPD) or Oracle Label Security (OLS).

Revoking Object Privileges on Behalf of the Object Owner

The GRANT ANY OBJECT PRIVILEGE system privilege enables you to revoke any specified object privilege where the object owner is the grantor. This occurs when the object privilege is granted by the object owner, or on behalf of the owner by any user holding the GRANT ANY OBJECT PRIVILEGE system privilege.

In a situation where the object privilege was granted by both the owner of the object and the user executing the REVOKE statement (who has both the specific object privilege and the GRANT ANY OBJECT PRIVILEGE system privilege), Oracle Database only revokes the object privilege granted by the user issuing the REVOKE statement. This can be illustrated by continuing the example started in "Granting Object Privileges on Behalf of the Object Owner".

At this point, user blake granted the SELECT privilege on HR.EMPLOYEES to clark. Even though blake possesses the GRANT ANY OBJECT PRIVILEGE system privilege, he also holds the specific object privilege, thus this grant is attributed to him. Assume that user HR also grants the SELECT privilege on HR.EMPLOYEES to user clark. A query of the DBA_TAB_PRIVS view shows that the following grants are in effect for the HR.EMPLOYEES table:

GRANTEE  GRANTOR PRIVILEGE    GRANTABLE
-------- ------- -----------  ----------
BLAKE    HR       SELECT       YES       
CLARK    BLAKE    SELECT       NO        
CLARK    HR       SELECT       NO        

User blake now issues the following REVOKE statement:

REVOKE  SELECT ON HR.EMPLOYEES FROM clark;

Only the object privilege for user clark granted by user blake is removed. The grant by the object owner, HR, remains.

GRANTEE  GRANTOR PRIVILEGE    GRANTABLE
-------- ------- -----------  ----------
BLAKE    HR       SELECT      YES       
CLARK    HR       SELECT      NO        

If blake issues the REVOKE statement again, then this time the effect is to remove the object privilege granted by adams (on behalf of HR), using the GRANT ANY OBEJCT PRIVILEGE system privilege.

Revoking Column-Selective Object Privileges

Although users can grant column-specific INSERT, UPDATE, and REFERENCES privileges for tables and views, they cannot selectively revoke column-specific privileges with a similar REVOKE statement. Instead, the grantor must first revoke the object privilege for all columns of a table or view, and then selectively repeat the grant of the column-specific privileges that the grantor intends to keep in effect.

For example, assume that role human_resources was granted the UPDATE privilege on the deptno and dname columns of the table dept. To revoke the UPDATE privilege on just the deptno column, issue the following two statements:

REVOKE UPDATE ON dept FROM human_resources;
GRANT UPDATE (dname) ON dept TO human_resources;

The REVOKE statement revokes the UPDATE privilege on all columns of the dept table from the role human_resources. The GRANT statement then repeats, restores, or reissues the grant of the UPDATE privilege on the dname column to the role human_resources.

Revoking the REFERENCES Object Privilege

If the grantee of the REFERENCES object privilege has used the privilege to create a foreign key constraint (that currently exists), then the grantor can revoke the privilege only by specifying the CASCADE CONSTRAINTS option in the REVOKE statement:

REVOKE REFERENCES ON dept FROM jward CASCADE CONSTRAINTS;

Any foreign key constraints currently defined that use the revoked REFERENCES privilege are dropped when the CASCADE CONSTRAINTS clause is specified.

Cascading Effects When Revoking System Privileges

There are no cascading effects when revoking a system privilege related to DDL operations, regardless of whether the privilege was granted with or without the ADMIN option. For example, assume the following:

1. The security administrator grants the CREATE TABLE system privilege to user jfee with the ADMIN option.

2. User jfee creates a table.

3. User jfee grants the CREATE TABLE system privilege to user tsmith.

4. User tsmith creates a table.

5. The security administrator revokes the CREATE TABLE system privilege from user jfee.

6. The table created by user jfee continues to exist. User tsmith still has the table and the CREATE TABLE system privilege.

You can observe cascading effects when you revoke a system privilege related to a DML operation. If the SELECT ANY TABLE privilege is revoked from a user, then all procedures contained in the users schema relying on this privilege can longer be executed successfully until the privilege is reauthorized.

Cascading Effects When Revoking Object Privileges

Revoking an object privilege can have cascading effects. Remember the following:

• Object definitions that depend on a DML object privilege can be affected if the DML object privilege is revoked. For example, assume that the body of the test procedure includes a SQL statement that queries data from the emp table. If the SELECT privilege on the emp table is revoked from the owner of the test procedure, then the procedure can no longer be executed successfully.

• When a REFERENCES privilege for a table is revoked from a user, any foreign key integrity constraints that are defined by the user and require the dropped REFERENCES privilege are automatically dropped. For example, assume that user jward is granted the REFERENCES privilege for the deptno column of the dept table. This user now creates a foreign key on the deptno column in the emp table that references the deptno column of the dept table. If the REFERENCES privilege on the deptno column of the dept table is revoked, then the foreign key constraint on the deptno column of the emp table is dropped in the same operation.

• The object privilege grants propagated using the GRANT OPTION are revoked if the object privilege of a grantor is revoked. For example, assume that user1 is granted the SELECT object privilege with the GRANT OPTION, and grants the SELECT privilege on emp to user2. Subsequently, the SELECT privilege is revoked from user1. This REVOKE statement is also cascaded to user2. Any objects that depend on the revoked SELECT privilege of user1 and user2 can also be affected, as described earlier.

Object definitions that require the ALTER and INDEX DDL object privileges are not affected if the ALTER or INDEX object privilege is revoked. For example, if the INDEX privilege is revoked from a user that created an index on a table that belongs to another user, then the index continues to exist after the privilege is revoked.

Step 1: Create the Access Control List and Its Privilege Definitions

Use the DBMS_NETWORK_ACL_ADMIN.CREATE_ACL procedure to create the content of the access control list. It contains a name of the access control list, a brief description, and privilege settings for one user or role that you want to associate with the access control list. In an access control list, privileges for each user or role are grouped together as an access control entry (ACE). An access control list must have the privilege settings for at least one user or role.

for example:

BEGIN
 DBMS_NETWORK_ACL_ADMIN.CREATE_ACL (
  acl          => 'file_name.xml', 
  description  => 'file description',
  principal    => 'user_or_role',
  is_grant     => TRUE|FALSE, 
  privilege    => 'connect|resolve',
  start_date   => null|timestamp_with_time_zone,
  end_date     => null|timestamp_with_time_zone); 
END;

In this specification:

• acl: Enter a name for the access control list XML file. Oracle Database creates this file relative to the /sys/acls directory in the XML DB Repository in the database. Include the .xml extension. For example:

  acl => 'us-example-com-permissions.xml',
  

• description: Enter a brief description of the purpose of this file. For example:

  description => 'Network connection permission for ACCT_MGR role',
  

• principal: Enter the first user account or role being granted or denied permissions. For example:

  principal => 'ACCT_MGR',
  

  Enter the name of the user account or role in case sensitive characters. For example, if the database stores the role name ACCT_MGR in all capital letters, entering it in mixed or lower case will not work. You can find the user accounts and roles in the current database instance by querying the DBA_USERS and DBA_ROLES data dictionary views. Typically, user names and roles are stored in upper-case letters.

  If you want to enter multiple users or grant additional privileges to this user or role, use the DBMS_NETWORK_ACL.ADD_PRIVILEGE procedure (described next) after you have created this access control list XML file.

• is_grant: Enter either TRUE or FALSE, to indicate whether the privilege is to be granted or denied. For example:

  is_grant => TRUE,
  

• privilege: Enter either connect or resolve. This setting is case sensitive, so always enter it in lowercase. For example:

  privilege => 'connect',
  

  The connect privilege grants the user permission to connect to a network service at an external host. The resolve privilege grants the user permission to resolve a network host name or an IP address.

  A database user needs the connect privilege to an external network host computer if he or she is connecting using the UTL_TCP, UTL_SMTP, UTL_MAIL, UTL_HTTP, the DBMS_LDAP package, and the HttpUriType type. To resolve the host name that was given a host IP address, or the IP address that was given a host name, with the UTL_INADDR package, grant the database user the resolve privilege instead.

  You can use the data dictionary views described in "Finding Information About Access Control Lists Configured for User Access" to find more information about existing privileges and network connections.

• start_date: (Optional) Enter the start date for the access control entry (ACE), in TIMESTAMP WITH TIME ZONE format (YYYY-MM-DD HH:MI:SS.FF TZR). When specified, the access control entry will be valid only on or after the specified date. The default is null. For example, to set a start date of February 28, 2008, at 6:30 a.m. in San Francisco, California, U.S., which is in the Pacific time zone:

  start_date => '2008-02-28 06:30:00.00 US/Pacific',
  

  The NLS_TIMESTAMP_FORMAT initialization parameter sets the default timestamp format. See Oracle Database Reference for more information.

• end_date: (Optional) Enter the end date for the access control entry (ACE), in TIMESTAMP WITH TIME ZONE format (YYYY-MM-DD HH:MI:SS.FF TZR). When specified, the access control entry expires after the specified date. The end_date setting must be greater than or equal to the start_date setting. The default is null.

  For example, to set an end date of December 10, 2008, at 11:59 p.m. in San Francisco, California, U.S., which is in the Pacific time zone:

  end_date => '2008-12-10 23:59:00.00 US/Pacific');
  

To add more users or roles to the access control list, or grant additional privileges to one user or role, use the DBMS_NETWORK_ACL.ADD_PRIVILEGE procedure. The syntax is as follows:

BEGIN
 DBMS_NETWORK_ACL_ADMIN.ADD_PRIVILEGE ( 
  acl         => 'file_name.xml', 
  principal   => 'user_or_role',
  is_grant    => TRUE|FALSE, 
  privilege   => 'connect|resolve', 
  position    => null|value, 
  start_date  => null|timestamp_with_time_zone,
  end_date    => null|timestamp_with_time_zone);
END;

As you can see, the parameters to add the privilege are the similar to those in the CREATE_ACL procedure, except that description is not included and the position parameter, which sets the order of precedence for multiple users or roles, was added. Because you now are adding more than one user or role, you may want to consider setting their precedence. "Setting the Precedence of Multiple Users and Roles in One Access Control List" provides more information.

Other DBMS_NETWORK_ACL_ADMIN procedures that are available for this step are DELETE_PRIVILEGE and DROP_ACL.

At this stage, you have created an access control list that defines the privileges needed to connect to a network host. However, the access control list has no effect until you complete Step 2: Assign the Access Control List to One or More Network Hosts.

Step 2: Assign the Access Control List to One or More Network Hosts

After you create the access control list, then you are ready to assign it to one or more network host computers. You can use the DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL procedure to do so.

For example:

BEGIN
 DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL (
  acl         => 'file_name.xml',
  host        => 'network_host', 
  lower_port  => null|port_number,
  upper_port  => null|port_number); 
END;

In this specification:

• acl: Enter the name of the access control list XML file (from Step 1: Create the Access Control List and Its Privilege Definitions) to assign to the network host. Oracle Database creates this file relative to the /sys/acls directory in the XML DB Repository in the database. Include the .xml extension. For example:

  acl => 'us-example-com-permissions.xml',
  

• host: Enter the network host to which this access control list will be assigned. This setting can be a name or IP address of the network host. Host names are case insensitive. For example:

  host => 'us.example.com',
  

  If you specify localhost, and if the host name has not been specified with the UTL_INADDR and UTL_HTTP PL/SQL packages in situations in which the local host is assumed, then these packages will search for and use the ACL that has been assigned localhost for the host setting.

  See the following sections for more information about how network host computers in access control list assignments work:

  • "Specifying a Group of Network Host Computers"

  • "Checking Privilege Assignments That Affect User Access to a Network Host"

  • "Precedence Order for a Host Computer in Multiple Access Control List Assignments"

  • "Precedence Order for a Host in Access Control List Assignments with Port Ranges"

• lower_port: (Optional) For TCP connections, enter the lower boundary of the port range. Use this setting for the connect privilege only; omit it for the resolve privilege. The default is null, which means that there is no port restriction (that is, the ACL applies to all ports). The range of port numbers is between 1 and 65535.

  For example:

  lower_port => 80,
  

• upper_port: (Optional) For TCP connections, enter the upper boundary of the port range. Use this setting for connect privileges only; omit it for resolve privileges. The default is null, which means that there is no port restriction (that is, the ACL applies to all ports). The range of port numbers is between 1 and 65535

  For example:

  upper_port => 3999);
  

  If you enter a value for the lower_port and leave the upper_port at null (or just omit it), Oracle Database assumes the upper_port setting is the same as the lower_port. For example, if you set lower_port to 80 and omit upper_port, the upper_port setting is assumed to be 80.

  The resolve privilege in the access control list takes no effect when a port range is specified in the access control list assignment.

Only one access control list can be assigned to any host computer, domain, or IP subnet, and if specified, the TCP port range. When you assign a new access control list to a network target, Oracle Database unassigns the previous access control list that was assigned to the same target. However, Oracle Database does not drop the access control list. You can drop the access control list by using the DROP_ACL procedure. To remove an access control list assignment, use the UNASSIGN_ACL procedure.

Depending on how you create and maintain the access control list, the two steps may overlap. For example, you can create an access control list that has privileges for five users in it, and then apply it to two host computers. Later on, you can modify this access control list to have different or additional users and privileges, and assign it to different or additional host computers.

All access control list changes, including the assignment to network hosts, are transactional. They do not take effect until the transaction is committed.

You can find information about existing privileges and network connections by using the data dictionary views described in Table 4-6, "Data Dictionary Views That Display Information about Access Control Lists".

For information about using the DBMS_NETWORK_ACL_ADMIN package, see Oracle Database PL/SQL Packages and Types Reference.

Step 1: Create an Oracle Wallet

To create the wallet, you can use either the mkstore command-line utility or the Oracle Wallet Manager user interface. To store passwords in the wallet, you must use mkstore. You can use both standard and PKCS11 wallet types, and the wallet can be an auto-login wallet if you want. For detailed information about creating wallets, see Oracle Database Advanced Security Administrator's Guide.

When you create the wallet, do the following:

• Ensure that you have exported the wallet to a file.

• Make a note of the directory in which you created the wallet. You will need this directory path when you complete the procedures in this section.

Step 2: Create an Access Control List that Grants the Wallet Privileges

After you have created the wallet, you are ready to create the access control list that will assign the password or client certificate privilege the user needs to use password credentials in the wallet for HTTP authentication.

For example:

BEGIN
 DBMS_NETWORK_ACL_ADMIN.CREATE_ACL (
  acl         => 'file_name.xml',
  description => 'description',
  principal   => 'user_or_role',
  is_grant    => TRUE|FALSE,
  privilege   => 'privilege';
...
END;

In this specification:

• acl: Enter a name for the ACL, and make a note of this name. You will need this name in Step 3: Assign the Access Control List to the Wallet, next. Oracle Database creates this file relative to the /sys/acls directory in the XML DB Repository in the database. Include the .xml extension. For example:

  acl         => 'hr_access_wallet_acl.xml',
  

• description: Enter a brief description of the purpose of this file. For example:

  description => 'Wallet ACL for the hr_access application',
  

• principal: Enter the user account or role being granted or denied privileges. For example:

  principal   => 'HR_CLERK',
  

  Enter this name using case sensitive characters. For example, if the database stores the role name HR_CLERK in all capital letters, entering it in mixed or lower-case letters will not work. You can find the user accounts and roles in the current database instance by querying the DBA_USERS and DBA_ROLES data dictionary views. Typically, user names and roles are stored in upper-case letters.

  If you want to add multiple users, or if you want to grant this user an additional privilege, you can use the DBMS_NETWORK_ACL.ADD_PRIVILEGE procedure after you have created this access control list XML file.

• is_grant: Enter either TRUE or FALSE, to indicate whether the privilege is to be granted or denied. For example:

  is_grant    => TRUE,
  

• privilege: Enter one of the following settings using lowercase letters and hyphens. Remember that the privilege name is case-sensitive.

  • use-passwords to give the user permission to use passwords in the wallet

  • use-client-certificates to authenticate the user with a client certificate in the wallet

  For example:

  privilege    => 'use-client-certificates');
  

Step 3: Assign the Access Control List to the Wallet

In this step, you assign this access control list to the wallet you created earlier. Afterward, you can check your settings by querying the DBA_WALLET_ACLS data dictionary view.

For example:

BEGIN
...
 DBMS_NETWORK_ACL_ADMIN.ASSIGN_WALLET_ACL (
  acl         => 'file_name.xml',
  wallet_path => 'file:path_to_directory_containing_wallet');
END;

In this specification:

• acl: Enter the name that you created for this wallet in Step 2: Create an Access Control List that Grants the Wallet Privileges, in the previous section. For example:

  acl         => 'hr_access_wallet_acl.xml',
  

• wallet_path: Enter the path to the directory that contains the wallet. When you specify the wallet path, you must use an absolute path and include file: before this directory path. Do not use environment variables, such as $ORACLE_HOME, nor insert a space after file: and before the path name. For example:

  wallet_path => 'file:/oracle/wallets/hr_access_access'
  

Step 4: Make the HTTP Request with the Passwords and Client Certificates

In this step, you use the UTL_HTTP PL/SQL package to create a request context object that is used privately with the HTTP request and its response. For detailed information about the UTL_HTTP package, see Oracle Database PL/SQL Packages and Types Reference.

For example:

DECLARE
 req_context UTL_HTTP.REQUEST_CONTEXT_KEY;
 req         UTL_HTTP.REQ;
BEGIN
 req_context := UTL_HTTP.CREATE_REQUEST_CONTEXT (
              wallet_path          => 'file:path_to_directory_containing_wallet',
              wallet_password      => 'wallet_password'|NULL);
 req := UTL_HTTP.BEGIN_REQUEST( 
              url                  => 'URL_to_application',
              request_context      => 'request_context'|NULL);
 ...
END;

In this specification:

• req_context: Use the UTL_HTTP.CREATE_REQUEST_CONTEXT_KEY datatype to create the request context object. This object stores a randomly-generated numeric key that Oracle Database uses to identify the request context. The UTL_HTTP.CREATE_REQUEST_CONTEXT function creates the request context itself.

• req: Use the UTL_HTTP.REQ datatype to create the object that will be used to begin the HTTP request. You will refer to this object later on, when you set the user name and password from the wallet to access a password-protected Web page.

• wallet_path: Enter the path to the directory that contains the wallet. Ensure that this path is the same path you specified when you created access control list in Step 3: Assign the Access Control List to the Wallet in the previous section.You must include file: before the directory path. Do not use environment variables, such as $ORACLE_HOME.

  For example:

  wallet_path     => 'file:/oracle/wallets/hr_access_access',
  

• wallet_password: Enter the password used to open the wallet. The default is NULL, which is used for auto-login wallets. For example:

  wallet_password      => NULL);
  

• url: Enter the URL to the application that uses the wallet.

  For example:

  url                  => 'www.hr_access.example.com',
  

• request_context: Enter the name of the request context object that you created earlier in this section. This object prevents the wallet from being shared with other applications in the same database session.

  For example:

  request_context      => req_context);
  

Using a Request Context to Hold the Wallet When Sharing the Session with Other Applications

You should use a request context to hold the wallet when the database session is shared with other applications. If your application has exclusive use of the database session, you can hold the wallet in the database session by using the SET_WALLET procedure instead.

For example:

DECLARE
 req         UTL_HTTP.REQ;
BEGIN
 UTL_HTTP.SET_WALLET(
              path          => 'file:path_to_directory_containing_wallet',
              password      => 'wallet_password'|NULL);
 req := UTL_HTTP.BEGIN_REQUEST( 
              url           => 'URL_to_application');
 ...
END;

If the protected URL being requested requires the user name and password to authenticate, then use the SET_AUTHENTICATION_FROM_WALLET procedure to set the user name and password from the wallet to authenticate.

Using Only a Client Certificate to Authenticate

If the protected URL being requested requires only the client certificate to authenticate, the BEGIN_REQUEST function sends the necessary client certificate from the wallet. assuming the user has been granted the use-client-certificates privilege in the ACL assigned to the wallet. The authentication should succeed at the remote Web server and the user can proceed to retrieve the HTTP response by using the GET_RESPONSE function.

Using the Password to Authenticate

If the protected URL being requested requires the username and password to authenticate, you should use the SET_AUTHENTICATION_FROM_WALLET procedure to set the username and password from the wallet to authenticate.

For example:

DECLARE
 req_context UTL_HTTP.REQUEST_CONTEXT_KEY;
 req         UTL_HTTP.REQ;
BEGIN
...
 UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET(
  r               => HTTP_REQUEST,
  alias           => 'alias_to_retrieve_credentials_stored_in_wallet',
  scheme          => 'AWS|Basic', 
  for_proxy       => TRUE|FALSE);
END;

In this specification:

• r: Enter the HTTP request defined in the UTL_HTTP.BEGIN_REQUEST procedure that you created above, in the previous section. For example:

  r               => req,
  

• alias: Enter the alias used to identify and retrieve the user name and password credential stored in the Oracle wallet. For example, assuming the alias used to identify this user name and password credential is hr_access.

  alias           => 'hr_access',
  

• scheme: Enter one of the following:

  • AWS: Specifies the Amazon Simple Storage Service (S3) scheme. Use this scheme only if you are configuring access to the Amazon.com Web site. (Contact Amazon for more information about this setting.)

  • Basic: Specifies HTTP basic authentication. The default is Basic.

  For example:

  scheme          => 'Basic',
  

• for_proxy: Specify whether the HTTP authentication information is for access to the HTTP proxy server instead of the Web server. The default is FALSE.

  For example:

  for_proxy       => TRUE);
  

The use of the user name and password in the wallet requires the use-passwords privilege to be granted to the user in the ACL assigned to the wallet.

Example of an Access Control List for a Single Role and Network Connection

Example 4-19 shows how you would create an access control list called us-example-com-permissions.xml to grant users who have the ACCT_MGR role access to network services that run on the host us.example.com.

-- 1. Create the access control list, which includes one role:
BEGIN
 DBMS_NETWORK_ACL_ADMIN.CREATE_ACL (
  acl          => 'us-example-com-permissions.xml', 
  description  => 'Network connection permission for ACCT_MGR', 
  principal    => 'ACCT_MGR', -- Must be in upper case
  is_grant     => TRUE, 
  privilege    => 'connect'); 
END;
/

-- 2. Assign the access control list a network host:
BEGIN
 DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL (
  acl         => 'us-example-com-permissions.xml',
  host        => 'www.us.example.com', 
  lower_port  => 80,
  upper_port  => 80); 
END;
/

This example creates the us-example-com-permissions.xml file in the /sys/acls directory, which is the default location. The XML file appears as follows:

<acl description="Network connection permission for ACCT_MGR" 
  xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
  xmlns:plsql="http://xmlns.oracle.com/plsql" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
  xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd    http://xmlns.oracle.com/xdb/acl.xsd">
  <security-class>plsql:network</security-class>
  <ace>
    <grant>true</grant>
    <principal>ACCT_MGR</principal>
    <privilege><plsql:connect/></privilege>
 </ace>
</acl>

The xmlns and xsi elements are fixed and should not be modified, for example, in a text editor.

You can check the contents of the access control list in SQL*Plus. See Oracle XML DB Developer's Guide for examples.

Example of an Access Control List with Multiple Roles Assigned to Multiple Hosts

Example 4-20 shows how to create a slightly more complex version of the us-example-com-permissions.xml access control list. In this example, you specify multiple role privileges and their precedence position, and assigned to multiple host computers.

See"Specifying a Group of Network Host Computers" and "Precedence Order for a Host Computer in Multiple Access Control List Assignments" for more information about host names. See also "Setting the Precedence of Multiple Users and Roles in One Access Control List" to determine the order of multiple ACE elements in the access control list XML file.

-- 1. Create the access control list:
BEGIN
 DBMS_NETWORK_ACL_ADMIN.CREATE_ACL (
  acl          => 'us-example-com-permissions.xml', 
  description  => 'Network connection permission for ACCT_MGR and ACCT_CLERK', 
  principal    => 'ACCT_MGR', -- Must be in upper case
  is_grant     => TRUE,
  privilege    => 'resolve');
 DBMS_NETWORK_ACL_ADMIN.ADD_PRIVILEGE ( -- Creates the second role privilege
  acl          => 'us-example-com-permissions.xml',
  principal    => 'ACCT_CLERK', 
  is_grant     => TRUE, 
  privilege    => 'connect',
  position     => null);
END;
/

-- 2. Assign the access control list to hosts:
BEGIN
 DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL ( -- Creates the first target host
  acl          => 'us-example-com-permissions.xml',
  host         => '*.us.example.com'); 
 DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL ( -- Creates the second target host 
  acl          => 'us-example-com-permissions.xml',
  host         => '*.uk.example.com',
  lower_port   => 80,
  upper_port   => 99); 
END;
/

The us-example-com-permissions.xml appears as follows:

<acl description="Network connection permission for ACCT_MGR and ACCT_CLERK" 
  xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
  xmlns:plsql="http://xmlns.oracle.com/plsql" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
  xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd    http://xmlns.oracle.com/xdb/acl.xsd">
  <security-class>plsql:network</security-class>
  <ace>
    <grant>true</grant>
    <principal>ACCT_MGR</principal>
    <privilege><plsql:resolve/></privilege>
  </ace>
  <ace>
    <grant>true</grant>
    <principal>ACCT_CLERK</principal>
    <privilege><plsql:connect/></privilege>
  </ace>
</acl>

Example 4-21 shows how the DBA_NETWORK_ACL_PRIVILEGES data dictionary view displays the privilege granted in the previous access control list.

ACL  
ACLID                                  PRINCIPAL  PRIVILEGE IS_GRANT INVERT
START_DATE END_DATE
------------------------------------------
-------------------------------- ---------- -------   -------- -------
---------- ----------
/sys/acls/us-example-com-permissions.xml 2EF86135D0E29B2AE040578CE4043250 ACCT_
MGR   resolve   true       false
/sys/acls/us-example-com-permissions.xml 2EF86135D0E29B2AE040578CE4043250 ACCT_
CLERK connect   true       false

Example 4-22 shows how the DBA_NETWORK_ACLS data dictionary view displays the host assignment of the access control list.

HOST                       LOWER_PORT UPPER_PORT
ACL
ACLID
-------------------- ---------- ----------
------------------------------------------
--------------------------------
*.us.example.com                   
/sys/acls/us-example-com-permissions.xml 2EF86135D0E29B2AE040578CE4043250
*.uk.example.com      80             99
/sys/acls/us-example-com-permissions.xml 2EF86135D0E29B2AE040578CE4043250

In these examples, the ACCT_MGR role has the resolve privilege to the first host, and the ACCT_CLERK role has the connect privilege to the first and second target hosts. The ACCT_MGR role does not have the resolve privilege to the second host because a port range is specified in the assignment to the second host.

To check the contents of the access control list in SQL*Plus, see Oracle XML DB Developer's Guide for examples.

Example of an Access Control List for Using Passwords in a Non-Shared Wallet

Example 4-23 configures wallet access for two Human Resources department roles, hr_clerk and hr_manager. These roles use the use-passwords privilege to access passwords stored in the wallet. In this example, the wallet will not be shared with other applications within the same database session.

/* 1. At a command prompt, create the wallet. The following example uses the 
      user name hr_access as the alias to identify the user name and password 
      stored in the wallet. You must use this alias name when you call the
      SET_AUTHENTICATION_FROM_WALLET procedure later on. */ 
$ mkstore -wrl $ORACLE_HOME/wallets/hr_access_access -create
Enter password: password
Enter password again: password
$ mkstore -wrl $ORACLE_HOME/wallets/hr_access_access -createCredential hr_access hr_usr 
Your secret/Password is missing in the command line
Enter your secret/Password: password
Re-enter your secret/Password: password
Enter wallet password: password

/* 2. In SQL*Plus, create an access control list to grant privileges for the 
      wallet. The following example grants the use-passwords privilege to the
      hr_clerk and hr_manager roles, and then it assigns this ACL to the wallet.*/ 
BEGIN
  DBMS_NETWORK_ACL_ADMIN.CREATE_ACL(
    acl         => 'hr_access_wallet_acl.xml', 
    description => 'Wallet ACL for hr_access application',
    principal   => 'HR_CLERK', -- Must be in upper case
    is_grant    => TRUE,
    privilege   => 'use-passwords');
 
  DBMS_NETWORK_ACL_ADMIN.ADD_PRIVILEGE(
    acl         => 'hr_access_wallet_acl.xml', 
    principal   => 'HR_MANAGER',
    is_grant    => TRUE,
    privilege   => 'use-passwords');
 
  DBMS_NETWORK_ACL_ADMIN.ASSIGN_WALLET_ACL(
    acl         => 'hr_access_wallet_acl.xml', 
    wallet_path => 'file:/oracle/wallets/hr_access_access');
END;
/
COMMIT;

/* 3. Create a request context and request object, and then set the 
      authentication for the wallet. */
DECLARE
  req_context  UTL_HTTP.REQUEST_CONTEXT_KEY;
  req          UTL_HTTP.REQ;

BEGIN
 req_context := UTL_HTTP.CREATE_REQUEST_CONTEXT(
     wallet_path          => 'file:/oracle/wallets/hr_access_access',
     wallet_password      => NULL,
     enable_cookies       => TRUE,
     max_cookies          => 300,
     max_cookies_per_site => 20);
  req := UTL_HTTP.BEGIN_REQUEST(
     url                  => 'www.hr_access.example.com',
     request_context      => req_context);
  UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET(
     r                    => req,
     alias                => 'hr_access'),
     scheme               => 'Basic', 
     for_proxy            => FALSE);
END;
/

Example of an Access Control List for Wallets in a Shared Database Session

Example 4-24 is almost the same as Example 4-23, except that it configures the wallet to be used for a shared database session; that is, all applications within the current database session will have access to this wallet.

/* Follow these steps:
   1. Use Oracle Wallet Manager to create the wallet and add the client
      certificate. See Oracle Database Advanced Security Administrator's Guide 
      for detailed information about using Oracle Wallet Manager. 

   2. In SQL*Plus, create an access control list to grant privileges for the 
      wallet. The following example grants the use-client-certificates privilege 
      to the hr_clerk and hr_manager roles, then it assigns this ACL to the 
      wallet. */
BEGIN
  DBMS_NETWORK_ACL_ADMIN.CREATE_ACL(
    acl         => 'hr_access_wallet_acl.xml', 
    description => 'Wallet ACL for hr_access application',
    principal   => 'HR_CLERK', -- Must be in upper case
    is_grant    => TRUE,
    privilege   => 'use-client-certificates');
 
  DBMS_NETWORK_ACL_ADMIN.ADD_PRIVILEGE(
    acl         => 'hr_access_wallet_acl.xml', 
    principal   => 'HR_MANAGER',
    is_grant    => TRUE,
    privilege   => 'use-client-certificates');
 
  DBMS_NETWORK_ACL_ADMIN.ASSIGN_WALLET_ACL(
    acl         => 'hr_access_wallet_acl.xml', 
    wallet_path => 'file:/oracle/wallets/hr_access_access');
END;
/
COMMIT;

/* 3. Create a request object to handle the HTTP authentication for the wallet.*/
DECLARE
  req  UTL_HTTP.req;
BEGIN
  UTL_HTTP.SET_WALLET(
   path            => 'file: $ORACLE_HOME/wallets/hr_access_access',
   password        => NULL);
 req := UTL_HTTP.BEGIN_REQUEST(
   url             => 'www.hr_access.example.com',
   method          => 'POST',
   http_version    => NULL,
   request_context => NULL);
END;
/

How a DBA Can Check User Network Connection and Domain Privileges

A database administrator can query the DBA_NETWORK_ACLS view to determine which access control lists are present for a specified host computer. This view shows the access control lists that determine the access to the network connection or domain, and then determines if each access control list grants (GRANTED), denies (DENIED), or does not apply (NULL) to the access privilege of the user. Only the database administrator can query this view.

The following sections provide examples that demonstrate how the database administrator can check user privileges for network connections and domain name resolution.

• Database Administrator Checking User Connection Privileges

• Database Administrator Checking User Privileges for Domain Name Resolution

Database Administrator Checking User Connection Privileges

Example 4-25 shows how a database administrator can check the privileges for user preston to connect to www.us.example.com. Remember that the user name you enter for the user parameter in the CHECK_PRIVILEGE_ACLID procedure is case sensitive. In this example, entering the user name preston is correct, but entering Preston or preston is incorrect.

You can find the users in the current database instance by querying the DBA_USERS data dictionary view, for example:

SELECT USERNAME FROM DBA_USERS;

SELECT HOST, LOWER_PORT, UPPER_PORT, ACL,
       DECODE(
         DBMS_NETWORK_ACL_ADMIN.CHECK_PRIVILEGE_ACLID(ACLID, 'PRESTON',
                                                      'connect'),
         1, 'GRANTED', 0, 'DENIED', NULL) PRIVILEGE
  FROM (SELECT HOST, LOWER_PORT, UPPER_PORT, ACL, ACLID,
               DBMS_NETWORK_ACL_UTILITY.CONTAINS_HOST('www.us.example.com',
                                                      HOST) PRECEDENCE
          FROM DBA_NETWORK_ACLS)
 WHERE PRECEDENCE IS NOT NULL
 ORDER BY PRECEDENCE DESC,
          LOWER_PORT NULLS LAST,
          UPPER_PORT NULLS LAST;

 HOST                 LOWER_PORT UPPER_PORT ACL                  PRIVILEGE
 -------------------- ---------- ---------- -------------------- ---------
 www.us.example.com           80         80 /sys/acls/www.xml    GRANTED
 www.us.example.com         3000       3999 /sys/acls/www.xml    GRANTED
 www.us.example.com                         /sys/acls/www.xml    GRANTED
 *.example.com                              /sys/acls/all.xml
 *                                          /sys/acls/all.xml

In this example, user preston was granted privileges for all the network host connections found for www.us.example.com. However, suppose preston had been granted access to a host connection on port 80, but then denied access to the host connections on ports 3000–3999. In this case, you need to create one access control list for the host connection on port 80, and a separate access control list for the host connection on ports 3000–3999.

Database Administrator Checking User Privileges for Domain Name Resolution

Example 4-26 shows how a database administrator can check the privileges of user preston to perform domain name resolution for the host www.us.example.com. In this example, only the access control lists assigned to hosts without a port range because the resolve privilege has no effect to those with a port range. (Remember that the user name you enter for the user parameter in CHECK_PRIVILEGE_ACLID is case sensitive.)

SELECT HOST, ACL,
       DECODE(
         DBMS_NETWORK_ACL_ADMIN.CHECK_PRIVILEGE_ACLID(ACLID, 'PRESTON',
                                                      'resolve'),
         1, 'GRANTED', 0, 'DENIED', NULL) PRIVILEGE
  FROM (SELECT HOST, LOWER_PORT, UPPER_PORT, ACL, ACLID,
               DBMS_NETWORK_ACL_UTILITY.CONTAINS_HOST('www.us.example.com',
                                                      HOST) PRECEDENCE
         FROM DBA_NETWORK_ACLS
         WHERE LOWER_PORT IS NULL AND UPPER_PORT IS NULL)
 WHERE PRECEDENCE IS NOT NULL
 ORDER BY PRECEDENCE DESC;

 HOST                 ACL                  PRIVILEGE
 -------------------- -------------------- ---------

 www.us.example.com   /sys/acls/www.xml    GRANTED
 *.example.com        /sys/acls/all.xml
 *                    /sys/acls/all.xml

How Users Can Check Their Network Connection and Domain Privileges

Users can query the USER_NETWORK_ACL_PRIVILEGES view to check their network and domain permissions. The USER_NETWORK_ACL_PRIVILEGES view is PUBLIC, so all users can select from it.

This view hides the access control lists from the user. It evaluates the permission status for the user (GRANTED or DENIED) and filters out the NULL case because the user does not need to know when the access control lists do not apply to him or her. In other words, Oracle Database only shows the user on the network hosts that explicitly grant or deny access to him or her. Therefore, the output does not display the *.example.com and * that appear in the output from the database administrator-specific DBA_NETWORK_ACLS view.

The following sections provide examples that demonstrate how a database administrator can check user permissions for network connections and domain name resolution.

• User Checking His or Her Network Connection Privileges

• User Checking Own Privileges for Domain Name Resolution

User Checking His or Her Network Connection Privileges

Example 4-27 shows how user preston can check her privileges to connect to www.us.example.com.

SELECT HOST, LOWER_PORT, UPPER_PORT, STATUS PRIVILEGE
  FROM (SELECT HOST, LOWER_PORT, UPPER_PORT, STATUS,
               DBMS_NETWORK_ACL_UTILITY.CONTAINS_HOST('www.us.example.com',
                                                      HOST) PRECEDENCE
          FROM USER_NETWORK_ACL_PRIVILEGES
         WHERE PRIVILEGE = 'connect')
 WHERE PRECEDENCE IS NOT NULL
 ORDER BY PRECEDENCE DESC,
          LOWER_PORT NULLS LAST,
          UPPER_PORT NULLS LAST;

 HOST                 LOWER_PORT UPPER_PORT ACL                  PRIVILEGE
 -------------------- ---------- ---------- -------------------- ---------
 www.us.example.com           80         80 /sys/acls/www.xml    GRANTED
 www.us.example.com         3000       3999 /sys/acls/www.xml    GRANTED
 www.us.example.com                         /sys/acls/www.xml    GRANTED

User Checking Own Privileges for Domain Name Resolution

Example 4-26 shows how the user preston can check her privileges to perform domain name resolution for www.us.example.com:

SELECT HOST, STATUS PRIVILEGE
  from (SELECT HOST, STATUS,
               DBMS_NETWORK_ACL_UTILITY.CONTAINS_HOST('www.us.example.com',
                                                      HOST) PRECEDENCE
          FROM USER_NETWORK_ACL_PRIVILEGES
         WHERE PRIVILEGE = 'resolve' AND
               LOWER_PORT IS NULL AND UPPER_PORT IS NULL)
 WHERE PRECEDENCE IS NOT NULL
 ORDER BY PRECEDENCE DESC;

 HOST                 PRIVILEGE
 -------------------- ---------
 www.us.example.com   GRANTED