Implementing WebLogic SSL Keys and Certificates

This section provides an overview of Secure Sockets Layer (SSL) encryption with WebLogic.

To use SSL encryption with WebLogic and the current PeopleTools release, the WebLogic keystore must contain the following appropriately configured encryption keys:

  • The web server's private key.

  • The web server's public key, digitally signed by a trusted certificate authority (CA).

  • The digitally signed public key of the same CA that signed the web server's key.

A public key is transferred and stored as a data element in a digital certificate or a certificate signing request (CSR). You can obtain public keys from a variety of sources in several different formats.

When setting up SSL, you need to:

  • ensure that the encryption keys are correctly formatted.

  • install them in the keystore.

  • configure them using the Administration Console.

Note: If you've already installed and configured a set of encryption keys for use with WebLogic in a previous PeopleTools release, you must migrate them as external files to the keystore within the current WebLogic version.

If you already have a set of existing encryption keys configured as external files, you don't need to obtain new ones. To find the existing keys, refer to the documentation for the PeopleTools and WebLogic releases for which those keys were installed.

The following procedure describes how to obtain new encryption keys, using as an example the trial certificate available from Verisign.

To obtain new encryption keys:

  1. At a command prompt, change to the following directory:

    PIA_HOME\webserv\domain_name\piabin

    Where domain_name is the name of the installed PeopleSoft Pure Internet Architecture domain for which you want to obtain encryption keys.

  2. Enter the following command:

    pskeymanager -create

    Note: Pskeymanager is a script wrapper to Java's keytool, provided by PeopleSoft to manage the WebLogic keystore. For usage information, enter pskeymanager -help.

  3. Follow the prompts and enter the requested information to create a new private key and a CSR for your web server.

    • Pskeymanager uses the keystore in PIA_HOME\webserv\domain_name\piaconfig\keystore\pskey.

    • Pskeymanager prompts you for an alias for the new keys, for example, ServerABC. This is the name you'll use to refer to the keys in the future.

    • Pskeymanager prompts you for distinguished name fields. Enter the appropriate values for your organization.

    • Pskeymanager prompts you for information about the CSR expiration date, key size, key algorithms, and the private key password. All of these fields have default values.

    Pskeymanager creates the private key inside the keystore, and creates the CSR as a file called ServerABC_certreq.txt in the current directory. You use the CSR to obtain your signed public key certificate and a root certificate from a CA.

  4. Decide which trusted CA you want to sign your web server's public key.

    You can use any CA that's compatible with Sun's Java JKS standard, such as Verisign.

  5. Open your CSR file in a text editor and copy its entire contents, including the first and last lines:

    -----BEGIN NEW CERTIFICATE REQUEST-----
...
...
-----END NEW CERTIFICATE REQUEST-----

  6. Access Verisign's test certificate enrollment site at https://www.verisign.com/ssl/buy-ssl-certificates/free-ssl-certificate-trial/index.html.

    Verisign guides you through the CSR submission process, including:

    • Accepting the Verisign license agreement.

    • Entering your technical contact information, which includes the email address where Verisign can send your signed public key.

    • Pasting your CSR contents in the provided text field.

    • Verifying your CSR.

    • Confirming and submitting your order.

    Verisign also provides its own digitally signed public key in a certificate, which is known as a trusted CA certificate, a root certificate, or a chain certificate.

  7. Download the VeriSign test CA root certificate from http://digitalid.verisign.com/cgi-bin/getcacert.

    When prompted, save getcacert.cer to PIA_HOME\webserv\domain_name.

    Note: If you need to FTP your certificate to UNIX, you must FTP it in ASCII mode to PS_HOME/webserv/domain_name.

  8. Check your email.

    Verisign digitally signs your web server's public key, then returns it to you in a certificate, called the server certificate.

  9. Copy the entire certificate contents, and save it as a text file called ServerABC-cert.pem in PIA_HOME\webserv\domain_name.

    Be sure to include the first and last lines.

    Note: If you need to FTP your certificate to UNIX, you must FTP it in ASCII mode.

Note: Make backup copies of the server certificate and the root certificate before proceeding.

Your encryption keys must be in privacy enhanced mail (PEM) format, which is Base64-encoded data. Base64 encoding uses only ASCII characters. A PEM-formatted key or certificate file has an extension of either .pem or .cer. If the file is in the binary distinguished encoding rules (DER) format, it has a .der extension. Use the der2pem Java utility to convert DER-formatted keys and certificates to PEM format.

For SSL to work, your WebLogic server must present its own public key to each client browser, along with the self-signed public key of a root CA that's also in the browser's keystore, as well as any keys necessary to establish a chain of trust between the two. All of these keys must be part of the same certificate file before you can import them into the WebLogic keystore.

If you generated the private key using pskeymanager on a WebLogic platform, it's automatically correctly formatted, password protected, and installed in the keystore with no additional steps required. However, if the private key was configured as an external file on an earlier WebLogic platform/version, you must properly format it and incorporate a password, before importing it into the current WebLogic keystore along with the public key certificates.

Converting DER Files to PEM Format

It's important to convert all DER-formatted key and certificate files to PEM format before you work with them further.

To convert DER-formatted key and certificate files to PEM format:

  1. At a command prompt, change to the following directory:

    PIA_HOME\webserv\domain_name

    Where domain_name is the name of an installed PeopleSoft Pure Internet Architecture domain.

  2. Enter the following command: 

    setenv.cmd

    This sets the appropriate environment for Java commands.

  3. For each DER-formatted key or certificate file, enter the following command:

    java utils.der2pem filename.der

    Make sure that you include the DER file's directory path. A new PEM file by the same name is created in the same location.

If you converted a private key file to PEM format, you must modify the header and footer to be compatible with WebLogic.

To modify the private key file header and footer:

  1. Open the PEM-formatted private key file in a text editor.

  2. Change the following line:

    -----BEGIN CERTIFICATE-----

    To this:

    -----BEGIN RSA PRIVATE KEY-----

  3. Change the following line:

    -----END CERTIFICATE-----

    To this:

     -----END RSA PRIVATE KEY-----

  4. Save and close the private key file.

Establishing the Server Certificate Chain of Trust

Your server certificate must contain, in addition to the web server's public key, any keys necessary to establish a chain of trust that culminates in the self-signed root certificate of a trusted root CA. That CA's root certificate must be in the keystore of any browser that's used to access your web server. Most browsers have an extensive set of trusted root certificates in their keystores.

First append the root certificate of the CA who issued your server certificate to the server certificate file. If you determine that the root certificate is not likely to be in your users' browsers, you must also append to the certificate file a chain certificate that was issued to your CA by another CA, then a chain certificate issued to that CA, and so on, until you append a root certificate that was issued by a trusted CA to itself.

For example, if your server certificate file is demo_cert.pem and the CA's root certificate is ca_cert.pem, you can open demo_cert.pem in a text editor, then insert the contents of ca_cert.pem after adding a new line at the end of the file. Make sure that each certificate follows the previous one on the next line, as follows:

...
...
Dosdxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
DMICxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
...
...

The result is that demo_cert.pem, for example, now contains the data from both certificates.

Note: You can also use the type command in Windows or thecat command in UNIX to combine the certificate files.

Password Protecting the Private Key

Private keys inside the WebLogic keystore are password protected. You can't import an external private key file into the keystore without a password. If it isn't currently password protected, use the WebLogic wlkeytool utility to incorporate a password into the private key file.

To password-protect an external PEM-formatted private key file:

  1. At a command prompt, change to the following directory:

    WL_HOME\server\native\win\32

    Where WL_HOME is the root directory where you installed WebLogic.

  2. Enter the following command:

    wlkeytool insecure_privatekey.pem secure_privatekey.pem

    Where insecure_privatekey.pem is the name of the original private key file, and secure_privatekey.pem is the name of the resulting password-protected private key file.

    Note: Make sure that you include directory paths for the private key files.

    The following message appears:

    Enter password to unprotect private key:

  3. Press Enter.

    The following message appears:

    Private key not PKCS8 encoded, trying RSA key
Private key file opened successfully
Enter password to protect private key :

  4. Enter the password that you want to use for this key.

    The following message appears:

    Verify password to protect private key :

  5. Enter the password again to confirm it.

    The utility creates the password protected private key file that you specified. You import this key into the WebLogic keystore.

Each WebLogic domain maintains its own keystore in PIA_HOME\webserv\domain_name\keystore\pskey, and all servers within a domain can share the same keystore.

These utilities are available for importing keys and certificates into the keystore:

Utility

When to Use

pskeymanager

If you created the private key using the pskeymanager utility on a WebLogic platform, it's already installed in the keystore. You need only use pskeymanager to import your server certificate, which should contain your web server's signed public key, your trusted CA's root certificate, and any public keys necessary to establish a chain of trust between them.

ImportPrivateKey

If the private key was previously configured as an external file on an earlier WebLogic platform, you must import it into the WebLogic keystore along with the server certificate, using the ImportPrivateKey utility. The private key should be password-protected.

Using pskeymanager to Import the Server Certificate

To import the server certificate into the WebLogic keystore:

  1. At a command prompt, change to the following directory:

    PIA_HOME\webserv\domain_name\piabin

    Where domain_name is the name of the installed PeopleSoft Pure Internet Architecture domain.

  2. Enter the following command:

    pskeymanager -import

    Note: PeopleTools provides pskeymanager (a script wrapper to Java's keytool) to help manage the WebLogic keystore. For usage information, enter pskeymanager -help.

  3. Follow the prompts and enter the requested information to create a new private key and a CSR for your web server.

    Keep the following in mind:

    • pskeymanager uses the keystore in PIA_HOME\webserv\domain_name\piaconfig\keystore\pskey,.

    • pskeymanager prompts you for an alias for the server certificate, for example, ServerABC. This should be the same alias that you specified for the corresponding private key when you created it.

    • pskeymanager prompts you for the name of the server certificate file, for example, ServerABC-cert.pem. Include the file path if necessary.

Using ImportPrivateKey to Import an External Private Key File with the Server Certificate

To import a password-protected private key and the server certificate into the WebLogic keystore:

  1. At a command prompt, change to the following directory:

    PIA_HOME\webserv\domain_name\bin

    Where domain_name is the name of an installed PeopleSoft Pure Internet Architecture domain.

  2. Enter the following command: 

    setEnv.cmd

    This sets the appropriate environment for Java commands.

  3. Enter the following command:

    java utils.ImportPrivateKey keystore\pskey store_passprivatekey_aliasprivatekey_passservercert_fileprivatekey_file

    The parameters for this command are as follows:

    Field or Control

    Definition
    store_pass

    Specify the password for the WebLogic pskey keystore.

    privatekey_alias

    Specify an alias for the private key. This is the name by which the key will be accessible inside the keystore.
    privatekey_pass

    Specify the password for the private key.
    servercert_file

    Specify the path and name of the server certificate file that includes the issuing CA's root certificate.
    privatekey_file

    Specify the path and name of the private key file.

This section describes how to configure the SSL encryption keys that you previously imported into the WebLogic keystore in PIA_HOME\webserv\domain_name\keystore\pskey, where domain_name is the name of an installed PeopleSoft Pure Internet Architecture domain.

The following procedure applies to a single server configuration of PIA. In a production environment, you would perform these steps for managed server instances of PIA, PIA1, RPS, and so on, in a multi-server domain configuration.

To configure WebLogic SSL encryption keys for the PIA server:

  1. With the PIA server running, sign in to the Administration Console.

  2. Access the keystore configuration pages.

    1. In the Domain Structure tree, expand Environment, click Servers, and click PIA from the Servers list.

    2. Select the Keystores tab.

    3. To change the configuration section, click Lock & Edit.

    4. Select Custom Identity and Custom Trust from the Keystores list.

  3. Update the fields on the Configure Keystore Properties page as follows:

    Field

    Value

    Custom Identity Key Store File Name

    keystore/pskey

    This should be the relative path and name of the keystore into which you imported your SSL keys.

    Custom Identity Key Store Type

    JKS

    Don't change this value.

    Custom Identity Key Store Passphrase

    password

    Confirm Custom Identity Key Store Passphrase

    Same as the value of Custom Identity Key Store Pass Phrase.

    Custom Trust Key Store File Name

    keystore/pskey

    This should be the relative path and name of the keystore into which you imported your SSL keys.

    Custom Trust Key Store Type

    JKS

    Don't change this value.

    Custom Trust Key Store Passphrase

    password

    Confirm Custom Trust Key Store Passphrase

    Same as the value of Custom Trust Key Store Pass Phrase.

  4. Click Save.

  5. Access the SSL tab, and update the values on the SSL Private Key Settings as follows:

    Field

    Value

    Private Key Alias

    Specify a unique identifier, such as the web server's machine name.

    This should be the alias that you specified for this server's private key.

    Passphrase

    password

    Confirm Passphrase

    Same as the value of Passphrase.

  6. Click Save and Activate Changes.

    You must click the Activate Changes button to apply your changes. If you close your browser without clicking Activate Changes, your changes will be lost.

  7. Restart the WebLogic PIA server.