4/25/2019 Configuring OC4J and SSL

Oracle ® Application Se rve r Containe rs for J2EE Se curity Guide

10g Re le ase 2 (10.1.2) Home Solution Area Contents Index
B14013-02

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.

Se e 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 Keys and Certificates

In SSL communication between two entities, such as companies or individuals, the server has a public k ey and an associated
private k ey. 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.
https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 1/11
4/25/2019 Configuring OC4J and SSL
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 k ey) is used to encode
a symmetric encryption key (the bulk encryption k ey); 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 k ey 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 k eystore 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.

https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 2/11
4/25/2019 Configuring OC4J and SSL
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.

Se e Also:

For information about keytool:

http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html

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 k eystore 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.

Se e 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:

a. 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:

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

b. Submit the certificate request to a certificate authority.

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

https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 3/11
4/25/2019 Configuring OC4J and SSL

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.

Se e 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.

Se e 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 ce rtificate is signe d by an e ntity that Oracle HTTP Se rve r doe s not ye t 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):

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

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

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

https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 4/11
4/25/2019 Configuring OC4J and SSL
b. From Oracle HTTP Server, use Oracle Wallet Manager to import the certificate of the entity.

2. If the Oracle HTTP Se rve r ce rtificate is signe d by an e ntity that OC4J doe s not ye t trust, and OC4J is in a
mode of ope ration that re quire s clie nt authe ntication (as "Requesting Client Authentication" discusses):

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

b. 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 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
https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 5/11
4/25/2019 Configuring OC4J and SSL

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.

Se e 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"

https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 6/11
4/25/2019 Configuring OC4J and SSL
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.

a. Change to the ORACLE_HOME/j2ee directory.

b. 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.
https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 7/11
4/25/2019 Configuring OC4J and SSL
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:

a. 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">

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

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

d. 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).

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

b. 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:

https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 8/11
4/25/2019 Configuring OC4J and SSL
<!-- 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.

https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 9/11
4/25/2019 Configuring OC4J and SSL
a. If you are running Oracle HTTP Server, then provide the certificate for the Oracle HTTP Server initiation of the
secure AJP connection.

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

Se e 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.

Common SSL Errors and Solutions

The following errors may occur when using SSL certificates:

Ke ytool Error: java.se curity.ce rt.Ce rtificate Exce ption: Unsupporte d e ncoding
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.

Ke ytool Error: Ke yPairGe ne rator 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.

Ke ytool Error: Faile d to e stablish chain from re ply

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
https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 10/11
4/25/2019 Configuring OC4J and SSL

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 ce rtificate corre sponds to the SSL ciphe r suite s that are e nable d
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.

Copyright © 2003, 2005, Oracle. All rights reserved.

Previous Next Home Solution Area Contents Index

https://docs.oracle.com/cd/B14099_19/web.1012/b14013/configssl.htm 11/11