8
Configuring Entrust-Enabled SSL Authentication

This chapter describes how to configure and use Entrust-enabled Oracle Advanced Security for Secure Socket Layer (SSL) authentication. It contains the following topics:

• Overview

• System Components

• Entrust Authentication Process

• Enabling Entrust Authentication

• Issues and Restrictions

• Troubleshooting Entrust In Oracle Advanced Security

Overview

A public-key infrastructure (PKI) includes various elements, such as a public key, bound into a digital certificate, a private key, and certain other security credentials. These credentials can be used for secure authentication over a Secure Sockets Layer (SSL) connection, to establish a secure communication channel, and to generate and process digital certificates--including digital signatures. A complete PKI includes the following:

• Certificate revocation status checking

• Easy management of user keys and certificates

• Easy deployment, hiding PKI complexity from users

This section describes the PKI implementation provided by the following:

• Oracle Advanced Security

• Entrust/PKI

• Entrust-Enabled Oracle Advanced Security

Oracle Advanced Security

Oracle Advanced Security includes elements of a PKI, such as Oracle Wallet Manager, which creates and securely stores a user's public/private key pair, as well as the trust points (the list of root certificates the user trusts). The user's PKI credentials, stored in Oracle Wallet Manager, can be used to create a secure, authenticated session over SSL. However, Oracle Advanced Security does not provide certificate creation or certificate revocation status checking, which are important elements of a complete PKI.

For example, although Oracle Wallet Manager can generate a PKCS#10 certificate signing request, users must obtain certificate fulfillment from a certificate authority and load the resulting certificate into an Oracle wallet. Oracle wallets only support authentication to Oracle applications.

Entrust/PKI

Entrust/PKI is a PKI product provided by Entrust Technologies, Inc. that provides certificate generation, certificate revocation, and key and certificate management.

Entrust-Enabled Oracle Advanced Security

The integration of Oracle Advanced Security with Entrust/PKI enables users of both Entrust and Oracle to utilize the extensive PKI capabilities of Entrust to enhance the security of their Oracle environment.

Entrust-enabled Oracle Advanced Security provides:

• Enhanced X.509-Based Authentication and Single Sign-On

• Integration with Entrust/PKI Key Management

• Integration with Entrust/PKI Certificate Revocation

  Note: Oracle Advanced Security has been certified as Entrust-Ready by Entrust Technologies Inc., as at Release 8.1.7. See Also: http://www.entrust.com

Enhanced X.509-Based Authentication and Single Sign-On

Entrust-enabled Oracle Advanced Security supports the use of Entrust credentials for X.509-based authentication and single sign-on. Instead of using an Oracle wallet to hold user PKI credentials, Oracle Advanced Security can access PKI credentials created by Entrust/Authority and held in an Entrust profile (an.epf file). Users who have deployed Entrust software within their enterprise are thus able to use it for authentication and single sign-on to Oracle9i.

Integration with Entrust/PKI Key Management

Entrust-enabled Oracle Advanced Security uses the extensive key management and rollover functionality provided by Entrust/PKI, which shield users from the complexity of a PKI deployment. For example, users are automatically notified when their certificates are expiring, and certificates are reissued according to administrator-configurable preferences.

Integration with Entrust/PKI Certificate Revocation

Entrust provides a certificate authority component, which natively checks certificate revocation status and enables the revocation of certificates.

Users using Entrust credentials for authentication to Oracle are assured that the revocation status of the certificate is checked, and connections are prevented if the certificate is revoked.

System Components

This section describes the system components required for using Entrust-enabled Oracle Advanced Security:

• Entrust/PKI 5.0.2 for Oracle

• Entrust/Toolkit Server Login 5.0.2

• Entrust IPSEC Negotiator Toolkit 5.0.2

  Note: In the following sections, the term client refers to a client connecting to an Oracle database, and the term server refers to the host on which the Oracle database resides.

Entrust/PKI 5.0.2 for Oracle can be downloaded from the Entrust Web site:

http://www.entrust.com

Entrust/Toolkit Server Login and Entrust IPSEC Negotiator Toolkit can be downloaded from the Entrust Developer Network by registered members. Users can register for membership and download these products at the following Web address:

http://www.entrust.com//developer/memberships/registration.htm

Entrust/PKI 5.0.2 for Oracle

Entrust/PKI 5.0.2 for Oracle requires a database for storing information about Entrust users and the infastructure, and a Lightweight Directory Access Protocol (LDAP)-compliant directory for information such as user names, public certificates, and certificate revocation lists.

Entrust/PKI 5.0.2 for Oracle is comprised of the following software components:

• Entrust/Authority

• Entrust/RA

• Entrust/Entelligence

Entrust/Authority

Entrust/Authority is the centerpiece of Entrust/PKI. It performs core certificate authority, certificate, and user management functions, such as creating users and user profiles containing the user's credentials.

Note: Oracle Corporation only supports the use of Entrust-enabled Oracle Advanced Security with versions of Entrust/Authority that run on Oracle9i.

See Also: Chapter 7, Configuring Secure Sockets Layer Authentication, for information about certificate authorities.

Entrust/Authority supports unattended login, also called Server Login, which eliminates the need for a Database Administrator (DBA) to repeatedly enter a password for the Entrust profile on the server. With unattended login, the DBA need only enter a password once to open the Entrust profile for the server to authenticate itself to multiple incoming connections.

Entrust/RA

Entrust/RA is the administrator's secure interface to Entrust/Authority.

Entrust/Entelligence

Entrust/Entelligence provides support for user key management and single sign-on functionality on both clients and server by enabling Oracle9i server process access to incoming SSL connections.

Entrust/Toolkit Server Login 5.0.2

Entrust/Toolkit Server Login Toolkit Release 5.0.2 is required for single sign-on functionality on servers operating on UNIX platforms.

Entrust/Server Login Toolkit provides single sign-on by enabling Oracle9i server process access to incoming SSL connections. Without this capability, a database administrator or other privileged user would have to enter the password for the Entrust profile on the server for every incoming connection.

You can download Entrust/Toolkit Server Login from the Entrust Web site:

http://www.entrust.com/developer/software/files/desc_serverlogin.cfm

Entrust IPSEC Negotiator Toolkit 5.0.2

The Entrust IPSEC Negotiator Toolkit Release 5.0.2 is required on both clients and servers for integrating the Oracle Advanced Security SSL stack with Entrust/PKI, enabling SSL authentication to use Entrust profiles.

You can download the IPSEC Negotiator Toolkit from the Entrust Web site:

http://www.entrust.com/developer/software/index.htm

Entrust Authentication Process

Figure 8-1 illustrates the following Entrust authentication process:

1. The Entrust user on the Oracle client establishes a secure connection with the server using SSL and Entrust credentials.

2. The Oracle SSL adapter on the server communicates with the Entrust Authority to check the certificate revocation status of the Entrust user.

   Note: Figure 8-1 does not include client and server profiles creation, which is presumed.

   Figure 8-1 Entrust Authentication Process

   
   
   Text description of the illustration ano81025.gif

See Also: How SSL Works in an Oracle Environment: The SSL Handshake

Enabling Entrust Authentication

This section describes the following tasks that enable Entrust-enabled Oracle Advanced Security SSL authentication:

• Creating Entrust Profiles

• Installing Oracle Advanced Security and Related Products

• Configuring SSL on the Client and Server

• Configuring Entrust on the Client

• Configuring Entrust on the Server

• Creating Database Users

• Logging Into the Database

Creating Entrust Profiles

This section describes how to create Entrust profiles. Entrust profiles can be created by either administrators or users. On UNIX platforms, administrators create the Entrust profiles for all clients. On Windows NT platforms, users can be permitted to create their Entrust profiles.

Administrator-Created Entrust Profiles

Administrators create Entrust profiles as follows:

1. The Entrust administrator adds the Entrust user using the Entrust/RA tool.

   See Also: The Entrust administration documentation for information about creating Entrust Users

2. The administrator enters the user's name and password.

3. The Entrust Authority creates the profile, or.epf file.

4. The administrator securely sends all profile-related files to the user. The preset password can be changed by the user.

User-Created Entrust Profiles

Entrust users create their own Entrust profiles as follows:

1. The Entrust administrator adds the Entrust user using the Entrust/RA tool. In the New User dialog box, the Create Profile option should be deselected.

   See Also: The Entrust administration documentation for information about creating Entrust profiles

2. The user receives a secure e-mail notification from the administrator that contains a reference number, authorization code, and expiration date.

3. The user navigates to the Create Entrust Profiles screen in Entrust/Entelligence as follows:

   Start>Programs>Entrust>Entrust Profiles>Create Entrust Profiles

4. The user enters the reference number, authorization code, and expiration date provided in the e-mail notification, creating a profile, or.epf file, and the Entrust initialization file.

Installing Oracle Advanced Security and Related Products

For Oracle Advanced Security Release 9.0.1, Entrust support installs in Typical mode. A single Oracle installation supports the use of both Oracle Wallets and Entrust Profiles.

See Also: The Oracle9i installation documentation for your platform.

Notes: Installing Entrust on a UNIX server uses different parameters than in prior releases See Also: Configuring Entrust on a UNIX Server

Configuring SSL on the Client and Server

Configure SSL on the client and server.

See Also: Chapter 7, Configuring Secure Sockets Layer Authentication, for information about configuring SSL on the client and server; skip the section that describes the Oracle wallet location.

Configuring Entrust on the Client

The steps for configuring Entrust on the client vary according to the type of platform:

• Configuring Entrust on a UNIX Client

• Configuring Entrust on a Windows NT Client

Configuring Entrust on a UNIX Client

If the client resides on a non-Windows NT platform, perform the following steps:

1. Set the JAVA_HOME variable to JDK or JRE location.

   For example:

   >setenv JAVA_HOME $ORACLE_HOME/JRE

2. Set WALLET_LOCATION in the sqlnet.ora file.

   For example:

   WALLET_LOCATION =
     (SOURCE =
         (METHOD = ENTR)
         (METHOD_DATA = 
             (PROFILE = profile_location)
             (INIFILE = initialization_file_location)
         )
     )
   
   

Configuring Entrust on a Windows NT Client

If the client resides on a Windows NT platform, ensure that the Entrust/Entelligence component is installed on the client and perform the following steps to set up the entrust credentials.

1. Set WALLET_LOCATION in the sqlnet.ora file.

   For example:

   WALLET_LOCATION =
     (SOURCE =
         (METHOD = ENTR)
         (METHOD_DATA = 
               (INIFILE = initialization_file_location)
         )
     )
   

where initialization_file_location is typically c:\WinNT.

2. Choose the Entrust icon on the system tray to open the Entrust_Login dialog box.

3. Log on to Entrust by entering the profile name and password.

Configuring Entrust on the Server

The steps for configuring Entrust on the server vary according to the type of platform:

• Configuring Entrust on a UNIX Server

• Configuring Entrust on a Windows NT Server

Configuring Entrust on a UNIX Server

If the server is a UNIX platform, ensure that the Entrust/Server Login Toolkit component is installed on the server and perform the following steps:

See Also: System Components for information about downloading the Entrust/Toolkit Server Login.

1. Stop the Oracle database instance.

2. Set the wallet_location parameter in the sqlnet.ora and listener.ora files to specify the paths to the server's profile and the Entrust initialization file:

   WALLET_LOCATION =
     (SOURCE =
         (METHOD = ENTR)
         (METHOD_DATA = 
             (PROFILE = profile_location)
             (INIFILE = initialization_file_location)
         )
     )
   

3. Enter the binder command to create unattended login credentials, or.ual files.

   For example:

   binder

4. Enter the path to the profile, the password, and the path to the Entrust initialization file. A message informs you that you have successfully created a credential file.

5. Start the Oracle database instance.

Configuring Entrust on a Windows NT Server

If the server is a Windows NT platform, ensure that the Entrust/Entelligence component is installed on the client and perform the following steps:

See Also: System Components for information about downloading Entrust/Entelligence.

1. Stop the Oracle database instance.

2. Set the wallet_location parameter in the sqlnet.ora and listener.ora files to specify the paths to the server's profile and the Entrust initialization file:

   WALLET_LOCATION =
     (SOURCE =
         (METHOD = ENTR)
         (METHOD_DATA = 
             (PROFILE = profile_location)
             (INIFILE = initialization_file_location)
         )
     )
   

3. Run the Entrust binder command to create unattended login credentials, or.ual files as follows:

   Start>Programs>Entrust Toolkit>Server Login>Entrust Binder

4. Enter the path to the profile, the password, and the path to the Entrust initialization file. A message informs you that you have successfully created a credential file.

5. Start the Oracle database instance.

Creating Database Users

Create global user in the database based on the distinguished name (DN) of each Entrust user.

For example:

SQL> create user jdoe identified globally as 'cn=jdoe,o=oracle,c=us';

where "cn=jdoe, o=oracle, c=us" is the Entrust distinguished name of the user.

Logging Into the Database

1. Use SQL*Plus to connect to the Oracle instance as follows:

   sqlplus /@tns_service_name

   where tns_service_name is the service name of the Oracle instance.

   The Entrust_Login dialog box appears.

2. Enter the path to the profile and the password.

3. If you did not specify a value for the WALLET_LOCATION parameter, you are prompted to enter the path to the Entrust initialization file.

   Note: Oracle Corporation recommends that the initialization file be specified in the WALLET_LOCATION parameter file.

Issues and Restrictions

The Entrust-ready designation from Entrust typically requires that a partner product integration with Entrust is done using an Entrust toolkit. This means that an application must be specifically modified to work with Entrust.

For example, Oracle has modified its SSL libraries to access an Entrust profile instead of an Oracle wallet. Accordingly, the Entrust profile is not accessible from standard SSL libraries.

In addition, the following restrictions apply:

• The use of Entrust components for digital signatures in applications based on Oracle is not supported.

• The Entrust-enabled Oracle Advanced Security integration is only supported with versions of Entrust/PKI Release 5.0.2 running on Oracle9i.

• The use of earlier releases of Entrust/Authority with Entrust-enabled Oracle Advanced Security is not supported.

• Interoperability between Entrust and non-Entrust PKIs is not supported.

• Entrust has certified Oracle Internet Directory version 2.1.1 for Release 8.1.7 (and subsequent).

Troubleshooting Entrust In Oracle Advanced Security

This section describes how to diagnose errors returned from Entrust to Oracle Advanced Security users.

Note: Entrust returns the following generic error message to Oracle Advanced Security users: ORA-28890 "Entrust Login Failed" This troubleshooting section describes how to get more details about the underlying error, and how to diagnose the problem.

ORA-28890 Entrust Login Failed

Problem

SQLPLUS login on an Entrust-enabled Oracle client errors out with the following generic error message:

ORA-28890 Entrust Login Failed

Getting Details

To get more detail on the exact Entrust error, turn on TRACING for SQLPLUS by specifying the following parameters in sqlnet.ora:

• TRACE_LEVEL_CLIENT=16

• TRACE_DIRECTORY_CLIENT=c:\temp

• TRACE_FILE_CLIENT=clitrc

Search for the word IKMP within the created TRACE file. The TRACE file contains information about the exact error code returned by Entrust API.

Checklist

1. Windows NT: Log into Entrust/Entelligence, if you have not already done so, and retry.

2. Windows NT: Confirm through the Windows/Control Panel/Services applet that the Entrust Login Interface service has started and is running.

3. Windows NT: If the parameter SSL_ENTRUST_INI_FILE is not specified in sqlnet.ora, the Entrust initialization file (entrust.ini) must reside in c:\WINNT.

4. Due to a known FIPS mode incompatibility, Entrust logins may fail with the following error message:

   The software authentication filed. (error code - 162).

   Contact Entrust support to resolve this issue.

5. Due to a known symbol conflict between Entrust and Oracle libraries, Entrust login might fail with the following error message:

   Algorithm self-test failed. (error code - 176).

   Contact Entrust support to resolve this issue.

6. Confirm that Entrust/Authority, as specified in the Entrust Initialization file, is accessible and running.

7. Confirm that the profile password is correctly entered.

8. If Oracle database server fails to log into Entrust, confirm that the unattended credential file (.ual) is generated using a valid password. Also, confirm that the versions for Entrust ServerLoginToolkit and Entrust IPSEC Negotiator Toolkit match (i.e., that the IPSEC Toolkit 5.0.2 works with ServerLoginToolkit 5.0.2).

9. Ensure that the Entrust initialization file has the following entry in the first section, Entrust Settings:

   IdentityLibrary = location
   
   

   where location is the location of libidapi.so, including the file name.

General Problems and Guidelines

1. Windows NT: Oracle Universal Installer might not list Oracle Entrust Adapter as one of the choices for the CUSTOM install option. This is because it is expecting the registry key

   \\HKEY_CURRENT_USER\Software\Entrust Technologies\Toolkits\Version\IPSec

   to be "5.0.1" (or "5.0.2").

   Contact Oracle Support to obtain an Installer patch that resolves this issue.

2. As far as possible, confirm that all of the Entrust toolkits (IPSEC and ServerLogin) are the same version.