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 of 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 that are created by Entrust/Authority and held in an Entrust profile (a .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 shields 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 preferences that administrators can configure.

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 6.0 for Oracle
• Entrust/Toolkit Server Login 6.0
• Entrust IPSEC Negotiator Toolkit 6.0

  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 6.0 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

Note: Oracle Advanced Security supports Entrust/PKI versions 5.0.2, 5.1, and 6.0.

Entrust/PKI 6.0 for Oracle

Entrust/PKI 6.0 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 6.0 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.

Note: Do not install Entrust/Entelligence on the server computer if it is running on a Windows platform.

Entrust/Toolkit Server Login 6.0

Entrust/Toolkit Server Login Toolkit Release 6.0 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 6.0

The Entrust IPSEC Negotiator Toolkit Release 6.0 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 asoag025.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 platforms, users can be permitted to create their own 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 2 (9.2), Entrust support installs in Typical mode. A single Oracle installation supports the use of both Oracle Wallets and Entrust Profiles.

See Also: Oracle9i operating system-specific installation documentation

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 Client

Configuring Entrust on a UNIX Client

If the client resides on a non-Windows 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 Client

If the client resides on a Windows 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 the WALLET_LOCATION parameter in the sqlnet.ora file.

   For example:

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

where initialization_file_location is the path to the .ini file.

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 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. Set the CLASSPATH environment variable to include the following paths:

   $ORACLE_HOME/JRE/lib/rt.jar
   $ORACLE_HOME/JRE/lib/i18n.jar
   $ORACLE_HOME/jlib/ewt*.jar
   $ORACLE_HOME/jlib/help*.jar
   $ORACLE_HOME/jlib/share*.jar
   $ORACLE_HOME/jlib/swingall*.jar
   $ORACLE_HOME/network/jlib/netentrust.jar
   
   

4. Enter the etbinder command to create unattended login credentials, or.ual files by using the following steps:
   1. Set the PATH environment variable to include the path to the etbinder command, which is located in the /bin directory where the Server Login Toolkit is installed.
   2. Set the LD_LIBRARY_PATH to include the path to the Entrust libraries.
   3. Set the SSL_ENTRUST_INI environment variable to include the full path to the Entrust initialization file.
   4. Enter the command as follows:

      etbinder
      
      

   5. When prompted to enter the location of the profile file, enter the full path name, including the name of the file. Then, when prompted, type in the password.

      A message displays indicating that the credentials file (filename.ual) has been created.

      Note: Ensure that the listener has a TCPS listening endpoint, then start the listener.

5. Start the Oracle database instance.

Configuring Entrust on a Windows Server

If the server is on a Windows platform, 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, which are files with a.ual extension. Ensure that the owner of the .ual file is the same as the owner of the Oracle service.

   To run the binder command choose

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

   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.

4. Start the Oracle database instance.

   Note: For all Windows environments, Oracle Corporation recommends the following: Do not install Entrust/Entelligence on the server computer. Use the Server Login Toolkit to generate the unattended login credentials (the .ual file) and access the database from a Windows client where Entrust/Entelligence is installed.

Creating Database Users

Create global users 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

An application must be specifically modified to work with Entrust. If a product is designated as Entrust-ready, then it has been integrated with Entrust by using an Entrust toolkit.

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, 5.1, and 6.0 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 releases.

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.

Error Messages Returned When Running Entrust on Any Platform

You may encounter the following error messages regardless of what platform you are running Entrust on.

ORA-28890 Entrust Login Failed

Cause: SQL*Plus login on an Entrust-enabled Oracle client errors out with this generic error message. This error can be caused by a number of problems, including the following causes:

• Entrust /Authority is not online
• Invalid Entrust profile password specified
• Invalid path to the Entrust profile specified
• Invalid Entrust initialization file specified
• Entrust Server Login program has not executed on the server

Action: To get more detail on the Entrust error, turn on tracing for SQL*Plus and the trace output should indicate the Entrust failure code. Enable tracing by specifying the following parameters in the sqlnet.ora file:

On the client:

• TRACE_LEVEL_CLIENT=16
• TRACE_DIRECTORY_CLIENT=<valid_client_directory_name>
• TRACE_FILE_CLIENT=client
• TRACE_UNIQUE_CLIENT=ON

On the server:

• TRACE_LEVEL_SERVER=16
• TRACE_DIRECTORY_SERVER=<valid_server_directory name>
• TRACE_FILE_SERVER=server
• TRACE_UNIQUE_SERVER=ON

Search for and locate the string IKMP in the generated trace file. Adjacent to this string, error messages are listed that provide details about the problem you are encountering. This detailed error code information is returned by the Entrust API.

Note: The following are examples of valid client directory names for setting the TRACE_DIRECTORY_CLIENT or TRACE_DIRECTORY_SERVER parameters in the sqlnet.ora file: (UNIX) /tmp (Windows) C:\TEMP

ORA-28890 Entrust Login Failed

(GUI does not display on the client)

Cause: The WALLET_LOCATION parameter does not specify the Entrust initialization file location in the client side slqnet.ora file.

Action: Ensure that the location of the Entrust initialization file is specified in the WALLET_LOCATION parameter in the sqlnet.ora file on the client.

See Also: "Configuring Entrust on a UNIX Client" "Configuring Entrust on a Windows Client"

Error Messages Returned When Running Entrust on Windows Platforms

You may encounter the following error messages if you are running Entrust on a Windows platform.

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

Cause: Due to a known FIPS mode incompatibility, Entrust logins may fail and return this error message.

Action: Contact Entrust support to resolve this issue.

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

Cause: Due to a known symbol conflict between Entrust and Oracle libraries, Entrust login may fail and return this error message.

Action: Contact Entrust support to resolve this issue.

TNS-12560: TNS protocol adapter error

TNS-00558> Entrust Login Failed

ORACLE SERVER (host_name)

This error may occur in the listener.log file on the server when you attempt to log in to Entrust.

Cause: If you configure the client by making the following recommended changes:

• Remove the .ual file
• De-install the Server Login
• Specify the Entrust initialization file location in the SSL_ENTRUST_INI_FILE parameter in the client sqlnet.ora file

then the server may not be able to authenticate the client when you enter the following command:

sqlplus/@tns_service_name

Action: Perform the following tasks to enable tracing on the server:

1. Choose Control Panel > Services.
2. In the Services dialog box, double click OracleTNSListener and change the Log On As from the System Account to the account that is currently logged in. This enables the server process to read the .ual file. Click OK to make the change and you are returned to the Services dialog box.

   In the Services dialog box, make the same changes for OracleService.

3. Make the following changes to the listener.ora file:
   • Specify only TCPS as the PROTOCOL in the listener ADDRESS. For example, change all of the PROTOCOL definitions to TCPS as follows:

     listener_name=
        (DESCRIPTION=
           (ADDRESS=(PROTOCOL=TCPS) (KEY=extproc0))
           (ADDRESS=(PROTOCOL=TCPS) (HOST=sales-pc) (PORT=1521)))
     
     

     Bringing up the listener only using TCPS will show whether there is a problem accessing the Entrust profile when you turn on tracing.

   • Set the SSL_CLIENT_AUTHENTICATION parameter to FALSE as follows:

     SSL_CLIENT_AUTHENTICATION=FALSE
     
     

   • Turn on tracing by setting the following parameters:

     TRACE_LEVEL_LISTENER=16
     TRACE_DIRECTORY_LISTENER=C:\temp
     
     

     The trace file is created in the C:\temp directory.

4. Make the following changes to the sqlnet.ora file to turn on tracing:

   TRACE_LEVEL_SERVER=16
   TRACE_DIRECTORY_SERVER=C:\temp
   
   

   The trace file is created in the C:\temp directory.

5. Ensure that Entrust/Entelligence is not installed on the server.

Search for and locate the string "fail" or "ntz*" function calls. Adjacent to these, error messages are listed that provide details about the problem you are encountering.

General Checklist for Running Entrust on Any Platform

The following items apply to all platforms:

1. Confirm that the Entrust/Authority is online.
2. Confirm that the .ual file is generated. These files are created for unattended login credentials.

   Note: Oracle Corporation recommends that you generate an unattended login credential file (.ual file) for the server only. If you generate a .ual file for the server only, then when users attempt to log in, they are presented a GUI that prompts them for their password and their Entrust profile name. After users supply this information, the connection request is forwarded to the Entrust server, which looks up the revocation file and the .ual file to determine the permissions for granting the request.

3. Confirm that the Entrust initialization file contains the following entry in the first section that specifies the Entrust Settings:

   IdentityLibrary=location
   
   

   The full path to the location of the libidapi.so file should be specified in the IdentityLibrary parameter. This parameter setting enables generating a .ual file on the server.

4. Ensure that all Entrust toolkits, including the Entrust IPSEC Negotiator Toolkit and the Server Login Toolkit, are the same version so they are compatible.
5. Ensure that you have specified TCP/IP with SSL in the SQLNET.AUTHENTICATION_SERVICES parameter in the sqlnet.ora file as shown in the following example:

   SQLNET.AUTHENTICATION_SERVICES=(tcps, authentication_type1, authentication_
      type2)
   

Checklist for Windows NT Installations

The following checklist items apply only to Entrust installations on the Windows NT platform.

1. Ensure that you are logged into Entrust/Entelligence and retry.
2. Choose Windows > Control Panel > Services to confirm that the Entrust Login Interface service has started and is running.
3. Confirm that the Entrust initialization file location is specified in the SSL_ENTRUST_INI_FILE parameter of the sqlnet.ora file. However, if you choose not to specify the location there, then the Entrust initialization file must reside in c:\WINNT.
4. Ensure that you are not running Entrust/Entelligence if your database is running on a Microsoft platform. If this is the case, then only the .ual file, which enables unattended login, is required.

   See Also: Step 4 of "Configuring Entrust on a Windows Server" for information about creating a .ual file with the Entrust binder command.

5. Confirm that Entrust/Authority, as specified in the Entrust Initialization file, is accessible and running.
6. Confirm that the profile password is correctly entered.
7. If an Oracle database server fails to log in to Entrust, confirm that the unattended login credential file (.ual) is generated using a valid password. Also, confirm that the versions for Entrust ServerLoginToolkit and Entrust IPSEC Negotiator Toolkit match (that is, that the IPSEC Toolkit 6.0 works with ServerLoginToolkit 6.0).
8. 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.