Java Key Store Configuration and SSL Support of WebLogic 11g

A Walkthrough Guide For Jar File Administration Tasks: Java Key Store creation and Jar Configuration to enable SSL functionality of WebLogic 11g.

Table of Contents

1       Introduction.

2       Step-by-Step Documentation.

2.1         Check your PATH Environment Settings.

2.2         Create Identity Keystore.

2.3         Create CSR.

2.4         Send the CSR to Your Certificate Authority.

2.5         Optional: Extract Certificates From Bundled Certificate File.

2.6         Create Full Certificate Chain.

2.7         Conditional: Create Trusted Certificate Chain.

2.8         Import Certificates into Identity Keystore.

2.9         Optional: Trust Keystore Configuration for SSL Implementation.

3       Jar Signing.

3.1         Sign your jar file(s).

3.2         Verify your signed jar files.

4       Working with Jar Files.

4.1         High level Jar Creation/Updating and Signing Processes.

4.2         Create a Jar file.

4.3         Update a Jar File.

5       How to Setup SSL on Oracle WebLogic Server 11g.

5.1         Pre-checks.

5.2         Logon to the Admin Server’s Admin Console.

5.3         Open a server’s configuration panel.

5.4         Enable the SSL Listening Port.

5.5         Install Identity and Trust Keystore(s).

5.6         Configure SSL.

5.7         Activate Changes and Reboot Server(s).

6       How to Setup SSL on Oracle HTTP Server 11g.

6.1         Pre-checks.

6.2         Convert JKS to Oracle Wallet.

6.3         Configure OHS to use new Wallet.

7       Conditional: Install Certificate Authority Certificates on Browser.

1         Introduction

The following documentation provides step-by-step instructions on how to create a Java Key store, Certificate Signing Request (CSR), Import SSL certificates into your key store, sign jar files with the respective certificates, and setup SSL on WebLogic and Oracle HTTP Server (OHS). The following steps account for PKCS#7 encoded certificates and certificates sent via text format.

Note: If your certificate authority sends you another type of certificate, such as PKCS#12 certificates, the key store configuration process will be different.

Each step will show you an example of the various commands and a detailed explanation of the required/recommended arguments for each command. The example commands listed below should not be used for your server environment(s), but used as an example and tailor the script so that it applies to your server environment.

2         Step-by-Step Documentation

2.1       Check your PATH Environment Settings

Before the JDK keystore and jar signing utilities can be used, the JDK’s bin path must be included into your PATH variable and be listed before any other JDKs. The JDK that is used to run your WebLogic servers, should be used for this process.

2.2       Create Identity Keystore

An identity keystore must be created. Please refer to the example command below along with descriptions of the respective arguments.**

Please see the following example command:

keytool -genkey -alias server -keyalg RSA -keysize 2048 -keystore example.jks -validity 1095 -dname “CN=*.example.com,OU=System Admin, O=PITSS, L=Troy, ST=Michigan, C=us”

Arguments:

·         -genkey: Required. This tells keytool to create a keystore with a private key.

·         -alias: Required. This creates a name for the identity keystore that is created within your java keystore.

·         -keysize: Optional, but recommended. This specifies the encryption key size of the encryption algorithm. Default size is 1024; it is recommended to use an algorithm of at least 2048.
Note: The encryption key size must be a multiple of 64.

·         -keyalg:  Optional, but recommended. This specifies the encryption algorithm type. The default is DSA; it is recommended to use RSA.

·         -keystore: Required. This tells keytool what filename to create the keystore under.

·         -validity: Optional, but recommended. This specifies the time length period of which the default self-signed certificate will use when your keystore is first created. Default is 90 days. It is recommended to use a validity period which reflects your trusted certificates produced by your Certificate Authority (CA).

·         –dname: Optional but recommended. This specifies what you would like for your values to be for CN (Common Name), OU (Organizational Unit), O (Organization), L (Location: City), ST (State), C (Country).

o   If the –dname argument is not provided with the values mentioned above, you will be prompted by the keytool program to enter them.

o   For CN, depending on your certificate authority and how your end-users will access your application(s), you can use one the following values listed below. Please use the option that suites to your server architecture and certificate authority.

§  Domain name without asterisk (my.example.com)

§  Domain name with an asterisk (*.example.com)

§  IP Address

After entering the command above in command line interface, you will be prompted to enter a password for your keystore, confirm the keystore password and if you want to specify a password for the alias you are creating. It’s recommended to keep the alias password and keystore password the same.

Once the keystore creation process is done successfully, the keystore file will be created with the “jks” file extension, within the current working directory of your command line interface. For instance, if you run the example command above in “/opt/oracle”, your keystore’s full file path will be “/opt/oracle/example.jks”.

** For more information on “keytool” usage please refer to Oracle’s official keytool documentation: http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/keytool.html

2.3       Create CSR

Please see the following command for creating a CSR. Refer to the argument usage below for how to tailor the command to your requirements.

Run the following command:

keytool -certreq -alias server -keystore example.jks -file example.csr

Arguments:

·         -certreq: Required. This argument tells keytool to create a CSR.

·         -alias: Required. Must be set to the alias name specified during the keystore creation step above. For the current example, this will be “server”.

·         -keystore: Required. This argument tells keytool which keystore file path to use.

·         -file: Optional but recommended. CSR will output the CSR into the specified filepath. In the example above, CSR will store the CSR into “example.csr”

2.4       Send the CSR to Your Certificate Authority

Once your CSR is generated, you must send the CSR to your Certificate Authority to generate your SSL certificate. If you do not have a Certificate Authority, or if you have any questions on Certificate Authorities, please contact PITSS.

2.5       Optional: Extract Certificates From Bundled Certificate File

Some certificate authorities may send your certificates in a bundled certificate file like PKCS#7 or your certificate authority may send you your certificates in plain text.

IMPORTANT: If you received your certificates in plain text, please skip this step. If you received your certificates in a single base encoded file, like PKCS#7 (.p7b), then this step must be followed.

·         On a Windows system, save the certificate file onto your local file system.

·         Open a Windows Explorer window; navigate to the folder containing your base encoded certificate file.

·         Open the p7b file. This will launch Windows Certificate Manager (certmgr).

·         From the Certificates Navigator on the left hand side, please navigate down into the “Certificates” folder.

·         When the “Certificates” folder is selected you should see two or three certificates listed in the Certificate viewer. Depending on your CA, you will have your public key certificate and your Root CA Certificate, and likely an Intermediate CA Certificate. Some certificate authorities will call these certificates “primary” and “secondary” certificates respectively.

·         For each certificate, right click on each certificate, then click each “export” from the “All Tasks” menu.

·         Please select the “Base-64 encoded X.509” certificate option when prompted for an export file type.

·         Specify the target file name for the certificate file. The following are example filenames for each certificate type.

o   Public key: pub_cert.cer

o   Root CA: root_cert.cer

o   Intermediate CA: inter_cert.cer

2.6       Create Full Certificate Chain

When your certificate authority sends you your certificates, the number of certificates you receive will vary depending on how your certificate authority distributes certificates. However all authorities will give you at least your SSL/X.509 certificate and a root CA certificate.

Some authorities may give you “intermediary” CA certificates, which should be included in your certificate chain. Please refer to the following list on what order certificates must be chained in. Once your chain is completed, you can import that chain into your java keystore.

1.       SSL Certificate

2.       Intermediary CA Certificate(s) (If applicable)

3.       Root CA Certificate

To create a certificate chain, simply concatenate each proper certificate in the respective order above into a blank ASCII text file.

For an example certificate chain, please see the following example. Note the examples below are not actual certificates and are meant for example purposes only.

Certificate: cert.cer

Root CA Certificate: root_ca.cer

Full Certificate Chain: chain.cer

2.7       Conditional: Create Trusted Certificate Chain

If you plan on setting up your keystore for SSL support on WebLogic and if you received multiple CA Certificates, this step must be followed. Otherwise if you only received a Root CA Certificate and your actual certificate or if you are only wish sign jar files with your keystore, this step can be skipped.

As described in step 2.6, some certificate authorities will give you multiple CA certificates. For example, some authorities will provide an Intermediate CA Certificate with a Root CA Certificate. Thus you will need to create a trusted certificate chain for when you need to create a trust keystore by starting creating a chain in the following order:

1.       Intermediary CA Certificate

2.       Root CA Certificate

Please see the following example below to create a trusted certificate chain.

Intermediary CA Certificate: inter_ca.cer

Root CA Certificate: root_ca.cer

Trusted Certificate Chain: trust_chain.cer

2.8       Import Certificates into Identity Keystore

Once you have your certificate chain created, you can now import the full certificate chain into your identity keystore. To do this, please see the following example command to run in your command line interface.

Run the following command to configure your Identity Keystore:

keytool -import -alias server -file chain.cer -keystore example.jks

Arguments:

·         -import: Required. Tells keytool to import a certificate into the keystore

·         -alias: Required. The value must be the alias name used during the keystore and CSR creation processes.

·         -file: Required. Tells keytool which certificate file to import into the keystore. In the example above, chain.cer is created in step 2.6.

·         -keystore: Required. Tells keytool which keystore to import the certificate into.

2.9       Optional: Trust Keystore Configuration for SSL Implementation

If you need to configure your keystores to support SSL for WebLogic Servers, follow this step to configure your keystores. If you do not need to configure your keystores for SSL support , you may skip this step.

To provide full SSL support, a trust keystore must be created. You can add the trusted keystore onto your existing keystore file or create a new keystore file for your trusted keystores (Oracle Recommended Approach).

Run the following command to create and configure a new trusted keystore:

keytool -alias trust -trustcacerts -import -file root_ca.cer -keystore example_trust.jks

OR – Run the following command to add a trusted keystore into an existing keystore:

keytool -alias truststore -trustcacerts -import -file root_ca.cer -keystore example.jks

Keytool Arguments:

·         -alias: Required. Specify a new alias for your trusted keystore.

·         -trustcacerts: Required. Tells keytool to import a trusted certificate or trusted certificate chain.

·         -import: Required. Tells keytool that you are importing a trusted certificate or trusted certificate chain.

·         -file: Required. Tells keytool the filename of the trusted certificate or trusted certificate to import.

·         -keystore: Required. Specify either a new keystore filename (to separate your trusted keystore from identity keystore) or an existing keystore filename to import your trusted keystore into.

3         Jar Signing

3.1       Sign your jar file(s)

Now that your identity keystore has been created, you can sign your jar file(s) with the trusted certificates.

Common jar files to sign are jacob.jar (used by Oracle’s webutil functionality), icon jar files (used by your forms applications), and any other custom built jar files containing images or java code.

Please see the following example to sign a jar file:

jarsigner -keystore example.jks jacob.jar server

Arguments:

·         -keystore: Required. Specify the identity keystore which has your full certificate chain imported and put a space after your keystore, followed by the alias name of your identity keystore. Do not use the “-alias” argument for the alias.

Note: all jar files beginning with “frm” in the “%ORACLE_HOME%/forms/java” directory which have the same modified timestamp are jar files developed and signed by Oracle. These are critical runtime jar files that should not be modified or otherwise signed with new certificates – as Oracle will not support an Oracle Forms Installation whose jar runtime files have been modified. These jar files are set to expire 2 years after the release date of your installed Oracle Forms release. When these jar file’s certificates expire, it is recommended to patch your Forms release to the most current release.

3.2       Verify your signed jar files

After your jar files have been signed, it is recommended to verify that the jar files have been signed with the proper certificates. You can do so by referring to the examples below.

Quick Check Command:

jarsigner -verify -certs file_name.jar

The following will give you one line of output indicating if your jar has been signed or not with two possible results below. However this does not tell you if the jar is signed with expired or authorized certificates.

·         “jar verified” Jar is signed with a proper certificate

·         “jar is unsigned. (signatures missing or not parsable)” Jar is not signed with a proper certificate

Verbose Check Command:

jarsigner -verify -certs -verbose file_name.jar > results.log

This command will give you an in-depth analysis of each respective file that has been signed or unsigned and put the results into a results.log file. It will display detailed information on each certificate that is used to sign each individual file within the jar file that is being checked.

4         Working with Jar Files

In Oracle Forms, applications may use jar files containing image files for the use of the application. After these jar files are created they must be signed with a X.509 certificate before they are deployed to a testing or production server – this process is highlighted above.  This section provides a quick reference for how to work with jar files and sign them for production use.

4.1       High level Jar Creation/Updating and Signing Processes

There are common situations where you will have to create and update jar files and re-sign them respectively. This section will cover high level processes for common situations like creating a new jar file then signing the jar and updating the jar file with new images and signing the respective jar.

New Jar File and Signing the Jar File:

1.       Use the create new jar file command, inserting your required files into the jar. Please refer to step 3.2.

2.       Sign the Jar file. Refer to the jar sign command in step 2.10.

3.       Deploy the jar file to your forms environment(s)

Append new files onto an existing and signed Jar File:

1.       Use the update jar file command, inserting new required files into the jar. Please refer to step 3.3.

2.       Sign the jar file

3.       Deploy the jar file to your forms environment(s)

4.2       Create a Jar file

Refer to the example commands below:

jar cf jar_file.jar input-file(s)

For example, say you have two images (image1.jpg and image2.jpg) that need to be in a app_img.jar file. You would need to run the following command:

jar cf app_img.jar image1.jpg image2.jpg

4.3       Update a Jar File

Refer to the example commands below:

jar uf jar_file.jar input-file(s)

For example say you need add one image (image3.jpg) to an existing jar file. You would need to run the following command:

jar uf app_img.jar image3.jpg

5         How to Setup SSL on Oracle WebLogic Server 11g

The following steps will guide you through the SSL setup process on the WebLogic Servers. If your application’s point of entry is via WebLogic Servers and not the Web Tier (OHS) and your requirement is to setup SSL, this section will help you fulfill that requirement.

However if your point of entry for your applications is the Web Tier, then it is recommended to refer to Section 6.

5.1       Pre-checks

Please check that you have the following pre-requisites before proceeding

·         AdminServer is running

·         Your Identity and Trusted Keystores have been created and configured with X.509 certificates

·         Identify whether your end-user’s internet browsers will accept secure connections from your Certificate Authority. This is most common with internal certificate authorities. If you find that your browsers do not support or accept secure connections from your certificate authority, you will have to import your certificate authority’s Root and Intermediate certificate(s).

5.2       Logon to the Admin Server’s Admin Console

Logon to the Admin Console that is located on your domain’s AdminServer.

Once logged in, click on “Servers” located under the “Environment” link from the left hand navigation, as shown below.

5.3       Open a server’s configuration panel.

Open the server that you are setting up SSL on by clicking on the link with the server’s name, as shown in the example below.

5.4       Enable the SSL Listening Port

Click the “Lock & Edit” button to enable server changes

Complete the following changes listed below:

·         Optional: Clear out the “Listen Address” property. Clearing out the Listen Address property enables your server to listen on multiple destination host names instead of one.

·         Required: Enable the “SSL Listen Port Enabled” checkbox.

·         Required: Specify an SSL port for your WebLogic Server in the “SSL Listen Port” field.

After your changes are completed, click the  button.

5.5       Install Identity and Trust Keystore(s)

Click on the “Keystores” tab, located under the “Configuration” tab set.

Specify Custom Identity and Custom Trust Settings

·         Click the “Change” button in the “Keystores” field.

·         Select “Custom Identity and Custom Trust” and Save your changes.

Fill out the following Identity Keystore fields:

·         Custom Identity Keystore: Absolute file path of your identity keystore.

·         Custom Identity Keystore Type: Type of keystore. In this case: JKS.

·         Custom Identity Keystore Passphrase: Passphrase specified during the identity keystore creation process.

Fill out the following Trust Keystore fields:

·         Custom Trust Keystore: Absolute file path of your trust keystore.

·         Custom Trust Keystore Type: Type of keystore. In this case: JKS.

·         Customer Trust Keystore Passphrase: Passphrase specified during your trust keystore creation.

Save your changes once the identity and trust keystore fields are completed with the proper changes.

5.6       Configure SSL

Please select the “SSL” tab under the “Configuration” tab of the server you are configuring for SSL.

Please fill out the following fields. See below for an example. Save your changes once they are completed.

·         Private Key Alias: the alias name of your Identity Keystore.

·         Private Key Passphrase: the password of your Identity Keystore alias

5.7       Activate Changes and Reboot Server(s)

Once your changes have been completed for the SSL server setup, please “Activate” changes. Once changes are activated, please reboot the server(s) you have setup with SSL.

For a step-by-step on how to reboot WebLogic Servers, please do the following:

·         Select “Servers”, under “Environment”.

·         Select the “Control” tab in the server summary page.

·         Please click “Shutdown” and then “Force Shutdown Now”. Click the  icon, to have the server status list automatically updated. Please wait until the server shutdown process is complete.

·         Select the server(s) that have been shutdown, click “Start”. Click the  icon, to have the server status list automatically updated. Please wait until the server(s) say “RUNNING” in the “State” column.

6         How to Setup SSL on Oracle HTTP Server 11g

6.1       Pre-checks

Please check that you have the following pre-requisites before proceeding

·         AdminServer is running

·         Your Identity and Trusted Keystores have been created and configured with X.509 certificates

·         Identify whether your end-user’s internet browsers will accept secure connections from your Certificate Authority. This is most common with internal certificate authorities. If you find that your browsers do not support or accept secure connections from your certificate authority, you will have to import your certificate authority’s Root and Intermediate certificate(s).

6.2       Convert JKS to Oracle Wallet

·         Open a Command Line Interface

·         Set JAVA_HOME environment variable to your JDK’s JAVA_HOME.

For example, if your jdk is installed in “/opt/oracle/jdk1.6.0_24” or “C:\java\jdk1.6.0_24” that will be your JAVA_HOME value respectively.

To set an environment variable, please use the following examples:

Windows: set JAVA_HOME=”C:\java\jdk1.6.0_24”

UNIX: export JAVA_HOME=/opt/oracle/jdk1.6.0_24

·         Set MW_HOME environment variable to your Middleware Home

·         Set ORACLE_INSTANCE environment variable to your Oracle Instance Home

·         Create Oracle Wallet – please use the command below as an example (Lines below are to be executed as one command):

%MW_HOME%/oracle_common/bin/orapki wallet create
-wallet ORACLE_INSTANCE%/config/OHS/ohs1/keystores/%NAME_OF_WALLET%

·         Convert JKS Keystore to PKCS12 – Please use the command below as an example to convert your JKS to Oracle Wallet (Lines below are to be executed as one command):

%MW_HOME%/oracle_common/bin/orapki wallet jks_to_pkcs12
-wallet %ORACLE_INSTANCE%/config/OHS/ohs1/keystores/%NAME_OF_WALLET%
-keystore  C:pathtoid.jks

6.3       Configure OHS to use new Wallet

Now that your new Oracle Wallet has been created and configured, OHS must be configured to read from the new wallet.

·         Open %ORACLE_INSTANCE%/config/OHS/ohs1/ssl.conf

·         Locate the “SSLWallet” parameter

Change from:
${ORACLE_INSTANCE}/config/${COMPONENT_TYPE}/${COMPONENT_NAME}/keystores/default

Change to:

${ORACLE_INSTANCE}/config/${COMPONENT_TYPE}/${COMPONENT_NAME}/keystores/%wallet_name%  

·         Save ssl.conf changes

·         Reboot OHS

Navigate to “%ORACLE_INSTANCE%/bin”

Run “opmnctl restartproc process-type=OHS”

7         Conditional: Install Certificate Authority Certificates on Browser

Depending on the CA certificates sent by your CA, you may have to install them onto your browser. This may be because the Certificate Authority is not a recognized Certificate Authority by your browser or the CA Certificates sent by your CA may not be used for production/public use. To install CA Certificates into your browser, please refer to your Certificate Authority or System Administration Group for installing CA Certificates into an internet browser.