Skip Headers

Oracle® Application Server Containers for J2EE Security Guide 10g Release 2 (10.1.2) B14013-02 |
| Library | Product | Contents | Index

Previous | Next |

# 11 Configuring OC4J and SSL

OC4J supports Secure Socket Layer (SSL) communication between Oracle HTTP Server and OC4J in an Oracle Application Server environment, using secure AJP. This is the secure version of Apache JServ Protocol, the protocol that Oracle HTTP Server uses to communicate with OC4J. Note, however, that the secure AJP protocol used between Oracle HTTP Server and OC4J is not visible to the end user.

This chapter discusses only configuring OC4J to take advantage of SSL; for full information about configuring other Oracle Application Server components, see the Oracle Application Server Administrator's Guide .

The following sections provide details:

- Overview of SSL Keys and Certificates

- Using Keys and Certificates with OC4J and Oracle HTTP Server

- Enabling SSL in OC4J

- Requesting Client Authentication

- Resolving Common SSL Problems

Note: Secure communication between a client and Oracle HTTP Server is independent of secure communication between Oracle HTTP Server and OC4J. This chapter covers only secure communication between Oracle HTTP Server and OC4J.

This chapter assumes some prior knowledge of security and SSL concepts.

See Also: For additional information about Oracle Application Server security and Oracle HTTP Server: Oracle Application Server Security Guide Oracle HTTP Server Administrator's Guide

## Overview of SSL Ke ys and Certificates

In SSL communication between two entities, such as companies or individuals, the server has a public key and an associated private key. Each key is a number, with the private key of an entity being kept secret by that entity, and the public key of an entity being publicized to any other parties with which secure communication might be necessary. The security of the data exchanged is guaranteed by keeping the private key secret, and by the complex encryption algorithm. This system is known as asymmetric encryption, because the key used to encrypt data is not the same as the key used to decrypt data.

Asymmetric encryption has a performance cost due to its complexity. A much faster system is symmetric encryption, where the same key is used to encrypt and decrypt data. But the weakness of symmetric encryption is that the same key has to be known by both parties, and if anyone intercepts the exchange of the key, then the communication becomes unsecure.

SSL uses both asymmetric and symmetric encryption to communicate. An asymmetric key (PKI public key) is used to encode a symmetric encryption key (the bulk encryption key); the bulk encryption key is then used to encrypt subsequent communication. After both sides agree on the bulk encryption key, faster communication is possible without losing security and reliability.

When an SSL session is negotiated, the following steps take place:

1. The server sends the client its public key.

2. The client creates a bulk encryption key, often a 128 bit RC4 key, using a specified encryption suite.

3. The client encrypts the bulk key with the server public key, and sends the encrypted bulk key to the server.

4. The server decrypts the bulk encryption key using the server private key.

This set of operations is called key exchange. After key exchange has taken place, the client and the server use the bulk encryption key to encrypt all exchanged data.

Note: It is possible, but rare, for the client to have its own private and public keys as well.

In SSL the public key of the server is sent to the client in a data structure known as an X.509 certificate. This certificate, created by a certificate authority (CA), contains a public key, information concerning the owner of the certificate, and optionally some digital rights of the owner. Certificates are digitally signed by the CA which created them using the digital certificate public key of that CA.

In SSL, the CA signature is checked by the receiving process to ensure that it is on the approved list of CA signatures. This check is sometimes performed by analysis of certificate chains. This occurs if the receiving process does not have the signing CA public key on the approved list. In that case the receiving process checks to see if the signer of the certificate of the CA is on the approved list or the signer of the signer, and so on. This chain of certificate, signer of certificate, signer of signer of certificate, and so on is a certificate chain. The highest certificate in the chain (the original signer) is called the root certificate of the certificate chain.

The root certificate is often on the approved list of the receiving process. Certificates in the approve list are called trust points or trusted certificates. A root certificate can be signed by a CA or can be self-signed, meaning that the digital signature that verifies the root certificate is encrypted through the private key that corresponds with the public key that the certificate contains, rather than through the private key of a higher CA. (Note that certificates of the CAs themselves are always self-signed.)

Functionally, a certificate acts as a container for public keys and associated signatures. A single certificate file can contain one or multiple chained certificates, up to an entire chain. Private keys are normally kept separately to prevent them from being inadvertently revealed, although they can be included in a separate section of the certificate file for convenient portability between applications.

A keystore is used to store certificates, including the certificates of all trusted parties, for use by a program. Through its keystore, an entity such as OC4J (for example) can authenticate other parties as well as authenticate itself to other parties. The keystore password is obfuscated. Oracle HTTP Server has what is called a wallet for the same purpose. The Sun Microsystems SSL implementation introduces the notion of a truststore, which is a keystore file that includes the trusted certificate authorities that a client will implicitly accept during an SSL handshake.

In Java, a keystore is a `java.security.KeyStore` instance that you can create and manipulate using the `keytool` utility that is provided with the Sun Microsystems JDK. The underlying physical manifestation of this object is a file.

See Also: For information about `keytool`: `http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html`

## Using Keys and Certific ates with OC4J and Oracle HTTP Server

The following steps describe using keys and certificates for SSL communication in OC4J. These are server-level steps, typically executed prior to deployment of an application that will require secure communication, perhaps when you first set up an Oracle Application Server instance.

Note that a keystore stores certificates, including the certificates of all trusted parties, for use by a program. Through its keystore, an entity such as OC4J (for example) can authenticate other parties, as well as authenticate itself to other parties. Oracle HTTP Server uses what is called a wallet for the same purpose.

In Java, a keystore is a `java.security.KeyStore` instance that you can create and manipulate using the `keytool` utility that is provided with the Sun Microsystems JDK. The underlying physical manifestation of this object is a file.

The Oracle Wallet Manager has functionality for Oracle wallets that is equivalent to the functionality of `keytool` for keystores.

See Also: Oracle Application Server Administrator's Guide for information on Oracle Wallet Manager

Here are the steps in using certificates between OC4J and Oracle HTTP Server:

1. Use `keytool` to generate a private key, public key, and unsigned certificate.You can place this information into either a new keystore or an existing keystore.

2. Obtain a signature for the certificate, using either of the following two approaches.

   Generate your own signature:

   1. Use `keytool` to "self-sign" the certificate. This is appropriate if your clients trust you as, in effect, your own certificate authority.

   Alternatively, obtain a signature from a recognized certificate authority:

   1. Using the certificate from Step 1, use `keytool` to generate a certificate request, which is a request to have the certificate signed by a certificate authority.

   2. Submit the certificate request to a certificate authority.

   3. Receive the signature from the certificate authority, and import it into the keystore, again using `keytool`. In the keystore, the signature is matched with the associated certificate.

      Note: Oracle Application Server includes Oracle Application Server Certificate Authority (OCA). OCA enables customers to create and issue certificates for themselves and their users, although these certificates would probably be unrecognized outside a customer's organization without prior arrangements.

See Also: Oracle Application Server Certificate Authority Administrator's Guide for information about OCA

The process for requesting and receiving signatures is up to the particular certificate authority you use. Because that is outside the scope and control of Oracle Application Server, the documentation does not cover it. You can go to the Web site of any certificate authority for information. (Any browser should have a list of trusted certificate authorities.) Here are the Web addresses for VeriSign, Inc. and Thawte, Inc., for example:

    http://www.verisign.com/

    http://www.thawte.com/

For SSL communication between OC4J and Oracle HTTP Server, execute the preceding steps for Oracle HTTP Server, but use a wallet and Oracle Wallet Manager instead of a keystore and the `keytool` utility.

See Also: Oracle Application Server Administrator's Guide for information about wallets and the Oracle Wallet Manager

In addition to steps 1 and 2 above, execute the following steps as necessary:

1. If the OC4J certificate is signed by an entity that Oracle HTTP Server does not yet trust, obtain the certificate of the entity and import it into Oracle HTTP Server. The specifics depend on whether the OC4J certificate in question is self-signed, as follows.

   If OC4J has a self-signed certificate (essentially, Oracle HTTP Server does not yet trust OC4J):

   1. From OC4J, use `keytool` to export the OC4J certificate. This step places the certificate into a file that is accessible to Oracle HTTP Server.

   2. From Oracle HTTP Server, use Oracle Wallet Manager to import the OC4J certificate.

   Alternatively, if OC4J has a certificate that is signed by another entity (that Oracle HTTP Server does not yet trust):

   1. Obtain the certificate of the entity in any appropriate way, such as by exporting it from the entity. The exact steps vary widely, depending on the entity.

   2. From Oracle HTTP Server, use Oracle Wallet Manager to import the certificate of the entity.

2. If the Oracle HTTP Server certificate is signed by an entity that OC4J does not yet trust, and OC4J is in a mode of operation that requires client authentication (as "Requesting Client Authentication" discusses):

   1. Obtain the certificate of the entity in any appropriate way, such as by exporting it from the entity. The exact steps vary widely, depending on the entity.

   2. From OC4J, use `keytool` to import the certificate of the entity.

      Note: During communications over SSL between Oracle HTTP Server and OC4J, all data on the communications channel between the two is encrypted. The following steps are executed: The OC4J certificate chain is authenticated to Oracle HTTP Server during establishment of the encrypted channel. Optionally, if OC4J is in client-authentication mode, Oracle HTTP Server is authenticated to OC4J. This process also occurs during establishment of the encrypted channel. Any further communication after this initial exchange will be encrypted.

Example: Creating an SSL Certificate and Generating Your Own Signature This example corresponds to the step of obtaining a signature for the certificate, in the mode where you generate your own signature by using `keytool` to self-sign the certificate.

First, create a keystore with an RSA private/public keypair, using the `keytool` command. The following example (in which `%` is the system prompt) uses the RSA keypair algorithm to generate a keystore to reside in a file named `mykeystore`, which has a password of "`123456`" and is valid for 21 days:

    % keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456
              -validity 21

Note the following:

- The `keystore` option specifies the name of the file in which the keys are stored.

- The `storepass` option sets the password for protecting the keystore.

- The `validity` option sets the number of days for which the certificate is valid.

The `keytool` prompts you for more information, as follows:

    What is your first and last name?
      [Unknown]:  Test User
    What is the name of your organizational unit?
      [Unknown]:  Support
    What is the name of your organization?
      [Unknown]:  Oracle
    What is the name of your City or Locality?
      [Unknown]:  Redwood Shores
    What is the name of your State or Province?
      [Unknown]:  CA
    What is the two-letter country code for this unit?
      [Unknown]:  US
    Is <CN=Test User, OU=Support, O=Oracle, L=Reading, ST=Berkshire, C=GB> correct?
      [no]:  yes

    Enter key password for <mykey>
            (RETURN if same as keystore password):

Note: To determine your two-letter country code, use the ISO country code list at the following URL:
    http://www.bcpl.net/~j1m5path/isocodes.html

The `mykeystore` file is created in the current directory. The default alias of the key is `mykey`.

## Enabling S SL in OC4J

For secure communication between Oracle HTTP Server and OC4J, configuration steps are required at each end, as discussed in the following section.

### Configuring Oracle HTTP Server for SSL

In Oracle HTTP Server, verify proper SSL settings in the `mod_oc4j.conf` file for secure communication. SSL must be enabled, with a wallet file and password specified, as follows:

    Oc4jEnableSSL on
    Oc4jSSLWalletFile wallet_path
    Oc4jSSLWalletPassword pwd

The `wallet_path` value is a directory path to the wallet file, without a file name. (The wallet file name is already known.) The `pwd` value is the wallet password.

See Also: Oracle HTTP Server Administrator's Guide for more information about the `mod_oc4j.conf` file

Example 11-1 Creating an SSL Certificate and Configuring HTTPS

The following example uses `keytool` to create a test certificate and shows all of the XML configuration necessary for HTTPS to work. To create a valid certificate for use in production environments, see the `keytool` documentation.

1. Install the correct JDK.

   Ensure that JDK 1.3.x is installed. This is required for SSL with OC4J. Set the `JAVA_HOME` to the JDK 1.3 directory. Ensure that the JDK 1.3.x `JAVA_HOME/bin` is at the beginning of your path. This may be achieved by doing the following.

   For UNIX:

       $ PATH=/usr/opt/java130/bin:$PATH
       $ export $PATH
       $ java -version
       java version "1.3.0"

   For Windows:

       set PATH=d:\jdk131\bin;%PATH%

   Ensure that this JDK version is set as the current version in your Windows registry. In the Windows Registry Editor under `HKEY_LOCAL_MACHINE/SOFTWARE/JavaSoft/Java Development Kit`, set `CurrentVersion` to 1.3 (or later).

2. Request a certificate.

   1. Change to the `ORACLE_HOME``/j2ee` directory.

   2. Create a keystore with an RSA private/public keypair using the `keytool` command. In this example, we generate a keystore to reside in a file named `mykeystore`, which has a password of "`123456`" and is valid for 21 days, using the RSA key pair generation algorithm with the following syntax:

       keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456
               -validity 21

   In this tool:

   - The `keystore` option sets the filename where the keys are stored.

   - The `storepass` option sets the password for protecting the keystore.

   - The `validity` option sets number of days the certificate is valid.

   The `keytool` prompts you for more information, as follows:

       What is your first and last name?
         [Unknown]:  Test User
       What is the name of your organizational unit?
         [Unknown]:  Support
       What is the name of your organization?
         [Unknown]:  Oracle
       What is the name of your City or Locality?
         [Unknown]:  Redwood Shores
       What is the name of your State or Province?
         [Unknown]:  CA
       What is the two-letter country code for this unit?
         [Unknown]:  US
       Is <CN=Test User, OU=Support, O=Oracle, L=Reading, ST=Berkshire, C=GB> correct?
         [no]:  yes

       Enter key password for <mykey>
               (RETURN if same as keystore password):

   Note: To determine your two-letter country code, use the ISO country code list at the following URL:
       http://www.bcpl.net/~j1m5path/isocodes.html

   The `mykeystore` file is created in the current directory. The default alias of the key is `mykey`.

3. If you do not have a `secure-web-site.xml` file, then copy the `default-web-site.xml` file to create a `ORACLE_HOME``/j2ee/home/config/secure-web-site.xml` file.

4. Edit `secure-web-site.xml` with the following elements:

   1. Add `secure="true`" to the `<web-site>` element, as follows:

          <web-site port="8888"
               display-name="Default OracleAS Containers for J2EE Web Site"
               secure="true">

   2. Add the following new line inside the `<web-site>` element to define the keystore and the password.

          <ssl-config keystore="<yourkeystore>"
                      keystore-password="<yourpassword>" />

      Where `yourkeystore` is the full path to the keystore and `yourpassword` is the keystore password. In our example, this is as follows:

          <!-- Enable SSL -->
          <ssl-config keystore="../../keystore" keystore-password="123456"/>

      Note: The keystore path is relative to where the XML file resides.

   3. Change the web-site port number, to use an available port. For example, the default for SSL ports is 443, so change the Web site port attribute to port="4443". To use the default of 443, you have to be a super user.

   4. Now save the changes to `secure-web-site.xml`.

5. Edit `server.xml` to point to the `secure-web-site.xml` file (if it does not already).

   1. Uncomment or add the following line in the file `server.xml` so that the `secure-web-site`.`xml` file is read:

          <web-site path="./secure-web-site.xml" />

      Note: Even on Windows, you use a forward slash, not a backslash, in the XML files.

   2. Save the changes to `server.xml`.

6. Stop and restart OC4J to initialize the `secure-web-site.xml` file additions. Test the SSL port by accessing the site in a browser on the SSL port. If successful, you will be asked to accept the certificate, because it is not signed by an accepted authority.

When completed, OC4J listens for SSL requests on one port and non-SSL requests on another. You can disable either SSL requests or non-SSL requests by commenting out the appropriate `*-web-site.xml` file in the `server.xml` configuration file:

    <!-- Comment out the following to remove SSL -->
    <web-site path="./secure-web-site.xml" />
    <!-- Comment out the following to remove non-SSL -->
    <default-site path="./default-web-site.xml" />

## Requ esting Client Authentication

OC4J supports a client authentication mode in which the server explicitly requests authentication from the client before the server communicates with the client. In an Oracle Application Server environment, Oracle HTTP Server acts as the client to OC4J.

For client authentication, Oracle HTTP Server must have its own certificate and must authenticate itself by sending a certificate and a certificate chain that ends with a root certificate. You can configure OC4J to accept only root certificates from a specified list in establishing a chain of trust back to a client.

A certificate that OC4J trusts is called a trust point. In the certificate chain from Oracle HTTP Server, the trust point is the first certificate OC4J encounters that matches one in its own keystore. There are three ways to establish trust:

- The client certificate is in the keystore.

- One of the intermediate CA certificates in the certificate chain from Oracle HTTP Server is in the keystore.

- The root CA certificate in the certificate chain from Oracle HTTP Server is in the keystore.

OC4J verifies that the entire certificate chain, up to and including the trust point, is valid to prevent any forged certificates.

If you request client authentication with the setting `needs-client-auth="true"` in the `<ssl-config>` element, perform the following steps:

1. Decide which of the certificates in the chain from Oracle HTTP Server is to be your trust point. Ensure that you either have control over the issuance of certificates using this trust point or that you trust the certificate authority as an issuer.

2. Import the intermediate or root certificate in the server keystore as a trust point for authentication of the client certificate.

   Note: If you do not want OC4J to accept certain trust points, make sure these trust points are not in the keystore.

3. Execute the steps to create the client certificate (as discussed in "Using Keys and Certificates with OC4J and Oracle HTTP Server"). The client certificate includes the intermediate or root certificate that is installed in the server. If you wish to trust another certificate authority, obtain a certificate from that authority.

4. Save the certificate in a file on Oracle HTTP Server.

   Note: If you are running standalone OC4J, save the certificate on the client.

5. Provide the certificate.

   1. If you are running Oracle HTTP Server, then provide the certificate for the Oracle HTTP Server initiation of the secure AJP connection.

   2. If you are running OC4J in a standalone environment:

      - If the client is a browser, set the certificate in the client browser security area.

      - If the client is a Java client, you must programmatically present the client certificate and the certificate chain when initiating the HTTPS connection.

During secure communication between the client and OC4J, the following functionality is executed:

- The link (all communications) between the two is encrypted.

- OC4J is authenticated to the client. A "secret key" is securely exchanged and used for the encryption of the link.

- Optionally, if OC4J is in client-authentication mode, the client is authenticated to OC4J.

See Also: Oracle Application Server Administrator's Guide for information about Oracle Wallet Manager, PKI, and security fundamentals Documentation for JSSE: `http://java.sun.com/products/jsse/doc/guide/API_users_guide.html` Documentation for the `java.net` package: `http://java.sun.com/j2se/1.4.2/docs/api/`

## Resolving Common SSL Problems

This section discusses some common SSL errors and their causes and remedies, followed by a brief discussion of general SSL debugging.

### Com mon SSL Errors and Solutions

The following errors may occur when using SSL certificates:

Keytool Error: java.security.cert.CertificateException: Unsupported encoding
  Cause: There is trailing white space, which the `keytool` utility does not allow.
  Action: Delete all trailing white space. If the error still occurs, add a newline in your certificate reply file.

Keytool Error: KeyPairGenerator not available
  Cause: You are probably using the `keytool` utility from an older JDK.
  Action: Use the `keytool` utility from the latest supported JDK. To ensure that you are using the latest JDK, specify the full path for this JDK.

Keytool Error: Failed to establish chain from reply
  Cause: The `keytool` utility cannot locate the root CA certificates in your keystore, and therefore cannot build the certificate chain from your server key to the trusted root certificate authority.
  Action: Execute the following command:

      keytool -keystore keystore -import -alias cacert -file cacert.cer
      (keytool -keystore keystore -import -alias intercert -file inter.cer)

  If you use an intermediate CA `keytool` utility, then execute this command:

      keystore keystore -genkey -keyalg RSA -alias serverkey
      keytool -keystore keystore -certreq -file my.host.com.csr

  Get the certificate from the Certificate Signing Request (CSR), then execute the following command:

      keytool -keystore keystore -import -file my.host.com.cer -alias serverkey

No available certificate corresponds to the SSL cipher suites that are enabled
  Cause: Something is wrong with your certificate.
  Action: Determine and rectify the problem.

### General SSL Debug ging

While you are developing in OC4J standalone, you can display verbose debug information from the Java Secure Socket Extension (JSSE) implementation. To get a list of options, start OC4J as follows (where `%` is the system prompt):

    % java -Djavax.net.debug=help -jar oc4j.jar

Start it as follows to enable full verbosity:

    % java -Djavax.net.debug=all -jar oc4j.jar

This will display the browser request header, server HTTP header, server HTTP body, content length (before and after encryption), and SSL version.