Skip Headers
Oracle® Application Server Containers for J2EE Security Guide
10g Release 2 (10.1.2)
B14013-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
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:


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:


Overview of SSL Keys 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:


Using Keys and Certificates 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:


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.

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:


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:
      1. The OC4J certificate chain is authenticated to Oracle HTTP Server during establishment of the encrypted channel.

      2. 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.

      3. 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 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 SSL 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:


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" />

Requesting 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:

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:


See Also:


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.

Common 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 Debugging

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.