11 Configuring OC4J and SSL

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.

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.

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.

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.

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

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.

Oc4jEnableSSL on
Oc4jSSLWalletFile wallet_path
Oc4jSSLWalletPassword pwd

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

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

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.

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

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