WebLogic SSL

 

 

Contents

  1. Overview
  2. Private Keys, Digital Certificates and Trusted Certificate Authorities
  3. One-Way and Two-Way SSL
  4. Setup SSL
  5. Obtain Digital Certificates
  6. CertGen Utility
  7. Certificate Chains
  8. Convert a Microsoft p7b Format to PEM Format
  9. Use Your Own Certificate Authority
  10. Get a Digital Certificate for a Web Browser
  11. Store Digital Certificates
  12. Create a Keystore
  13. Common Keytool Commands
  14. How WLS Locates Trust
  15. Configure Keystores
  16. Configure SSL
  17. Configure Two-Way SSL
  18. Disable the SSL Port
  19. Host Name Verification
  20. Enable SSL Debugging
  21. SSL Session Behavior
  22. Configure SSL for the Node Manager
  23. SSL Requirements for Managed Servers
  24. SSL Requirements for the Node Manager
  25. Demo Versus Production
  26. Host Name Verification Requirements
  27. Node Manager SSL Demo Configuration
  28. Node Manager SSL Production Configuration
  29. Using Files and the WebLogic Keystore Provider
  30. Configure RMI over IIOP with SSL
  31. SSL Certificate Validation
  32. Control the Level of Certificate Validation
  33. Check Certificate Chains
  34. Troubleshoot Certificate Problems
  35. nCipher JCE Provider with WLS

 

Overview

Secure Sockets Layer (SSL) provides secure connections by allowing two apps connecting over a network connection to authenticate the other's identity and by encrypting the data exchanged between the apps.

SSL in WLS is an implementation of the SSL 3.0 and TLS 1.0 specs.

WLS supports SSL on a dedicated listen port which defaults to 7002. To establish an SSL connection, a Web browser connects to WLS by supplying the SSL listen port and the HTTPs schema in the connection URL, i.e.,

https://myserver:7002.

Using SSL is computationally intensive and adds overhead to a connection. Avoid using SSL when it is not necessary. However, always use SSL in a production environment.

 

Private Keys, Digital Certificates and Trusted Certificate Authorities

Private keys, digital certificates, and trusted certificate authorities establish and verify server identity.

SSL uses public key encryption technology for authentication. With public key encryption, a public key and a private key are generated for a server. The keys are related such that data encrypted with the public key can only be decrypted using the corresponding private key and vice versa. The private key is carefully protected so that only the owner can decrypt messages that were encrypted using the public key.

The public key is embedded into a digital certificate with additional information describing the owner of the public key, such as name, street address, and e-mail address. A private key and digital certificate provide identity for the server.

The data embedded in a digital certificate is verified by a certificate authority and digitally signed with the certificate authority's digital certificate. Well-know certificate authorities include Verisign and Entrust.net. The trusted certificate authority (CA) certificate establishes trust for a server.

An application participating in an SSL connection is authenticated when the other party evaluates and accepts their digital certificate. Web browsers, servers, and other SSL-enabled apps generally accept as genuine any digital certificate that is signed by a trusted certificate authority and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the digital certificate of the certificate authority used to sign it expired. A server certificate can be invalidated if the host name in the digital certificate of the server does not match the host name specified by the client.

 

One-Way and Two-Way SSL

SSL can be configured one-way or two-way:

one-way SSL The server is required to present a certificate to the client but the client is not required to present a certificate to the server. To successfully negotiate an SSL connection, the client must authenticate the server but the server will accept any client into the connection. One-way SSL is common on the Internet where customers want to create secure connections before they share personal data.
two-way SSL The client also presents a certificate to the server. WLS can be configured to require clients to submit valid and trusted certificates before completing the SSL connection.

 

Setup SSL

To set up SSL:

  1. Obtain a identity private key(and digital certificates) and trust (certificates for trusted certificate authorities) for WLS. Use the digital certificates, private keys, and trusted CA certificates provided by the WLS kit, the Cert Gen utility, Sun Microsystem's keytool utility, or a reputable vendor such as Entrust or Verisign to perform this step.

  2. Store the private keys, digital certificates, and trusted CA certificates. Digital certificates are always stored in file in the domain directory of WLS. Private keys and trusted CA certificates are stored in a keystore.

    WLS 8.1 supports private keys and trusted CA certificates stored in files or in the WebLogic Keystore provider for the purpose of backward compatibility only.

  3. Configure the Identity and Trust keystores for WLS in the WLS console.

  4. Set SSL attributes for the private key alias and password in the WLS console. Optionally, set attributes that require the presentation of client certificates (for two-way SSL).

 

Obtain Private Keys, Digital Certificates and Trusted Certificate Authorities

To use SSL, you need a private key, a digital certificate containing the matching public key, and a certificate for at least one trusted certificate authority that can verify the data embedded in the digital certificate containing the public key. WLS supports private keys, digital certificates, and trusted certificate authorities from the following sources:

WLS can use digital certificates in either .pem or .der format.

A .pem (privacy-enhanced mail) format file begins with this line:

----BEGIN CERTIFICATE----

and ends with this line:

----END CERTIFICATE----

A .pem format file supports multiple digital certificates (for example, a certificate chain can be included). The order is important (include the files in the order of trust). The server digital certificate should be the first digital certificate in the file. The issuer of that digital certificate should be the next file and so on until you get to the self-signed root certificate authority certificate.

A .der format file contains binary data. A .der file can be used only for a single certificate, while a .pem file can be used for multiple certificates.

Microsoft is often used as a certificate authority. Microsoft issues trusted CA certificates in p7b format. The trusted CA certificates must be converted to PEM before they can be used with WLS.

Private key files (meaning private keys not stored in a keystore) must be in PKCS#5/PKCS#8 PEM format.

 

CertGen Utility

The CertGen utility generates digital certificates and private keys that should only be used for demonstration or testing purposes and not in a production environment.

The CertGen utility creates a private key and digital certificate signed by the demonstration certificate authority (CertGenCAB). The digital certificates generate by the Cert Gen utility have the host name of the machine on which they were generated as the common name. Therefore, if you use host name verification, generate a digital certificate for every machine on which you wish to use SSL.

The CertGen utility generates two .pem files and two .der files. View the .der files in a Web browser to view the details of the generated digital certificate. Use the .pem files when you boot WLS or use the digital certificates with a client.

To generate a certificate:

  1. Copy the following files to the directory in which you run the CertGen utility:

    $WL_HOME/server/lib/CertgenCA.der The digital certificate for a certificate authority trusted by WLS.
    $WL_HOME/server/lib/CertGenCAKey.der The private key for a certificate authority trusted by WLS.

  2. Enter the following command at a command prompt:

    prompt> java utils.CertGen password certfile keyfile [export] [hostname]

    where

    password Password for the private key.
    certfile Name of the digital certificate file. The file is put in the domain directory.
    keyfile Name of the generated private key file. The file is put in the domain directory.
    top>hostname Name of the machine for which you are obtaining a digital certificate. This option allows you to use host name verification.

    By default, the CertGen tool generates domestic strength certificates. Specify the [export] option if you want the tool to generate export strength certificates. If you want to export domestic strength digital certificates that use a host name, specify [export] as " ".

    The CertGen tool uses the JDK version 1.3 InetAddress.getLocalHost().getHostname() method to get the hostname it puts in the Subject common name. The getHostName() method works differently on different platforms. It returns a fully qualified domain name (FQDN) on some platforms (for example, Solaris) and a short host name on other platforms (for example, Windows NT). If WLS is acting as a client (and by default hostname verification is enabled), you need to ensure the hostname specified in the URL matches the Subject common name in the certificate. Otherwise, your connection fails because the host names do not match.

On Solaris, when you type hostname on the command line the server looks at the /etc/hosts file and gets a short host name. When you invoke java.net.InetAddress.getHostName(), the host goes to the /etc/nsswitch.conf file and depending on how the host is configured returns a FQDN or a short host name.

If the host entry is configured as:

hosts: dns nis [NOTFOUND=return]

The host performs a name service look up first and uses the information /etc/hosts file only if DNS is not available. In this case, a FQDN is returned.

If the host entry is configured as:

hosts: files dns nis [NOTFOUND=return]

The host goes to the /etc/hosts file first and then goes to DNS. In this case, a short hostname is returned.

 

Certificate Chains

To use certificate chains with WLS:

  1. Ensure that all the digital certificates are in PEM format. If they are in DER format, you can convert them using the utils.der2pem utility. If you are using a digital certificate issued by Microsoft, see Converting a Microsoft p7b Format to PEM Format. You can use the steps in "Converting a Microsoft p7b Format to PEM Format" to convert other types of digital certificates. Save the digital certificate in Base 64 format.

  2. Open a text editor and include all the digital certificate files into a single file. The order is important. The server digital certificate should be the first digital certificate in the file. The issuer of that digital certificate should be the next file and so on until you get to the self-signed root certificate authority certificate. This digital certificate should be the last certificate in the file.

    You cannot have blank lines between digital certificates.

  3. Specify the file in the Server Certificate File Name attribute in the SSL Configuration portion of the Keystores and SSL tab in the WLS console.

Here is a sample certificate chain.

-----BEGIN CERTIFICATE----- MIICyzCCAjSgAwIBAgIBLDANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhb Glmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1 UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnR zMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMloXDTA2MTAxNTIw MDIxMlowgZ8xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJhb mNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MRkwFwYDVQQDExB3ZW Jsb2dpYy5iZWEuY29tMR4wHAYJKoZIhvcNAQkBFg9zdXBwb3J0QGJlYS5jb20wgZ8wDQYJKoZIhvcNAQE BBQADgY0AMIGJAoGBAMJX8nKUgsFej8pEu/1IVcHUkwY0c2JbBzOryu3sce4QjX+rGxiCjoPm2MY=yts2 BvonuJ6CztdZf8B/LBEWCz+qRrtdFn9mKSZWGvrAkmMPz2RhXEOThpoRo5kZz2FQ9XF/PxIJXTYCM7yoo RBwXoKYjquRwiZNtUiU9kYi6Z3prAgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAh3eqQGxEMUnNTwEUD0tBq -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIC+jCCAmOgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhb Glmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1 UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnR zMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMVoXDTA2MTAxNjIw MDIxMVowgbYxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJhb mNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MS8wLQYDVQQDEyZEZW 1vIENlcnRpZmljYXRlIEF1dGhvcml0eSBDb25zdHJhaW50czEfMB0GCSqGSIb3DQEJARYQc2VjdXJpdHl AYmVhLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA3ynD8l5JfLob4g6d94dNtI0Eep6QNl9b blmswnrjIYz1BVjjRjNVal9fRs+8jvm85kIWlerKzIMJgiNsj50WlXzNX6orszggSsW15pqV0aYE9Re9K CNNnORlsLjmRhuVxg9rJFEtjHMjrSYr2IDFhcdwPgIt0meWEVnKNObSFYcCAwEAAaMWMBQwEgYDVR0TAQ -----END CERTIFICATE-----

 

Convert a Microsoft p7b Format to PEM Format

Microsoft is often used as a certificate authority. The digital certificates issued by Microsoft are in a format (p7b) that cannot be used by WLS. To convert a digital certificate in p7b format to PEM format:

  1. In Windows Explorer on Windows 2000, click on the file (filename.p7b) you want to convert. A Certificates window appears.

  2. In the left pane of the Certificates window, expand the file you want to convert. Select the Certificates option.

  3. A list of certificates in the p7b file appear.

  4. Select the certificate to convert to PEM format. The Certificate Export wizard appears.

  5. Click Next.

  6. Select the Base64 Encoded Cert option (exports PEM formats).

  7. Click Next.

  8. Enter a name for the converted digital certificate.

  9. Click Finish.

For p7b certificate files that contain certificate chains, you need to concatenate the issuer PEM digital certificates to the certificate file. The resulting certificate file can be used by WLS.

 

Use Your Own Certificate Authority

Many companies act as their own certificate authority. To use those trusted CA certificates with WLS:

  1. Ensure the trusted CA certificates are in PEM format.
    • If the trusted CA certificate is in DER format, use the utils.der2pem utility to convert them.
    • If the trusted CA certificate was issued by Microsoft, see Converting a Microsoft p7b Format to PEM Format.
    • If the trusted CA certificate has a custom file type, use the steps in Converting a Microsoft p7b Format to PEM Format to convert the trusted CA certificate to PEM format.

  2. Create a Trust keystore.

  3. Store the trusted CA certificate in the Trust keystore.

  4. Configure WLS to use the Trust keystore.

 

Get a Digital Certificate for a Web Browser

Low-security browser certificates are easy to acquire and can be done from within the Web browser, usually by selecting the Security menu item in Options or Preferences. Go to the Personal Certificates item and ask to obtain a new digital certificate. You will be asked for some information about yourself.

The digital certificate you receive contains public information, including your name and public key, and additional information you would like authenticated by a third party, such as your email address. Later you will present the digital certificate when authentication is requested.

As part of the process of acquiring a digital certificate, the Web browser generates a public-private key pair. The private key should remain secret. It is stored on the local file system and should never leave the Web browser's machine, to ensure that the process of acquiring a digital certificate is itself safe. With some browsers, the private key can be encrypted using a password, which is not stored. When you encrypt your private key, you will be asked by the Web browser for your password at least once per session.

Digital certificates obtained from Web browsers do not work with other types of Web browsers or on different versions of the same Web browser.

 

Store Private Keys, Digital Certificates, and Trusted Certificate Authorities

Once you have obtained private keys, digital certificates, and trusted CA certificates, you need to store them so that WLS can use them to verify identity. Private keys, their associated digital certificates, and trusted CA certificates are stored in a keystore. The keystores can be configured through the WLS console or specified on the command-line. Use the Keystore Configuration section of the Keystores and SSL page of the WLS console to configure Identity and Trust keystores for WLS.

For the purpose of backward compatibility, private keys and trusted CA certificates can be stored in a file or in a JKS keystore accessed via the WebLogic Keystore provider. In addition, trusted CA certificates can be stored in a JKS keystore that can be accessed directly by WLS. Use the SSL Configuration section of the Keystores and SSL page of the WLS console to specify identity and trust attributes for the purpose of backward compatibility.

 

Create a Keystore and Loading Private Keys and Trusted Certificate Authorities into the Keystore

A keystore is a mechanism designed to create and manage private keys and trusted CA certificates. Use the following mechanims to create a keystore and load private keys and trusted CA certificates into the keystore:

ImportPrivateKey Allows you to take private key files and load them into a keystore.
keytool Use the keytool utility to generate a private key/digital certificate pair and then import the signed private key into the keystore. While you can use the keytool utility to load new private keys and trusted CA certificates into a keystore, the utility does not allow you to take an existing private key from a file and import it into the keystore. Instead, use the WebLogic ImportPrivateKey utility.

The keytool utility requires a digital certificate for every private key when importing a private key into the keystore. This digital certificate cannot be used by WLS.

Custom utilities This release of WLS can use keystores created with custom tools or utilites. How to create and use these utilities is outside the scope of this document.

Either create one keystore for both private keys and trusted CA certificates or two keystores: one for private keys (Identity) and one for trusted CA certificates (Trust). BEA recommends creating two keystores.

By default, WLS looks for an Identity keystore named DemoIdentity.jks and a Trust keystore named DemoTrust.jks in the $WL_HOME/server/lib directory. The DemoTrust.jks keystore contains the trusted certificate authorities in the JDK /jre/lib/security/cacerts file.

All private key entries in a keystore are accessed by WLS via unique aliases. You specify the alias when loading the private key into the keystore. Aliases are case-insensitive; the aliases Hugo and hugo would refer to the same keystore entry. Aliases for private keys are specified in the Private Key Alias attribute when configuring SSL.

Trusted certificate authorities are not individually identified to WLS with aliases. All certificate authorities in a keystore identified as trusted by WLS are trusted. Although WLS does not use the alias to access trusted CA certificates, the keystore does require an alias when loading a trusted CA certificate into the keystore.

 

Common Keytool Commands

  1. Create a keystore. 

    keytool -genkey \
        -keystore keystorename \
        -storepass keystorepassword

  2. Load a private key into the keystore. 

    keytool -alias aliasforprivatkey \
        -import \
        -file privatekeyfile.pem \
        -keypass privatekeypassword \
        -keystore keystorename \
        -storepass keystorepassword

  3. Load a trusted CA certificate into the keystore. 

    keytool -alias aliasfortrustedca \ 
        -trustcacerts \ 
        -import \ 
        -file trustedcafilename.pem \ 
        -keystore keystorename \ 
        -storepass keystorepassword \

  4. Display what is in the keystore 

    keytool -list -keystore keystorename

  5. Delete a private key for the specified alias from the keystore. 

    keytool -keystore keystorename 
        -storepass keystorepassword 
        -delete 
        -alias privatekeyalias

  6. Provide online help for keytool 

    keytool -help

 

How WLS Locates Trust

You can specify trust for WLS by either configuring attributes in the WLS console or using the -Dweblogic.security.SSL.trustedCAkeystore command-line argument. Because the ordering of trust is important (meaning, trusted certificate authorities must trust each other in the correct sequence), you need to understand the sequence WLS uses when looking for trusted certificate authorities. Weblogic Server:

  1. Uses the keystore specified in the -Dweblogic.security.SSL.trustedCAkeystore command-line argument.
  2. Uses the Trust keystore specified in the WLS console.
  3. Uses a trusted CA certificate file from a 6.x config.xml file (if one exists in the domain directory).
  4. Uses $WL_HOME/server/lib/cacerts.

 

Configure Keystores

By default, WLS is configured with two keystores:

DemoIdentity.jks Contains a demonstration private key for WLS. This keystore establishes an identity for WLS.
DemoTrust.jks Contains a list of certificate authorities trusted by WLS. This keystore establishes trust for WLS.

These keystores are located in the $WL_HOME/server/lib directory. For testing and development purposes, the keystore configuration is complete. However, the demonstration keystores should not be used in a production environment. All the digital certificates and trusted CA certificates in the keystores are signed by a WLS demonstration certificate authority. Therefore, all WLS installations trust each other. This will leave your SSL connections wide open to a number of security attack.

Use the steps in this section to configure Identity and Trust keystores for production use.

Before you perform the steps in this section, you need to:

  1. Obtain private keys and digital certificates from a reputable certificate authority such as Verisign, Inc. or Entrust.net.
  2. Create Identity and Trust keystores.
  3. Load the private keys and trusted CAs into the Identity and Trust keystores.

To configure Identity and Trust keystores for WLS:

  1. Expand the Servers node.

  2. Click the name of the server for which you want to configure keystores (for example, exampleserver).

  3. Click the Configuration-->Keystores and SSL tab.

  4. The information about the demonstration keystores is displayed in the Keystore Configuration.

  5. Click the Change... link in the Keystore Configuration to configure new keystores.

  6. Choose the type of keystore configuration being used. The following options are available:

    Demo Identity and Demo Trust The demonstration Identity and Trust keystores located in the $WL_HOME/server/lib directory and configured by default.
    Custom Identity and Java Standard Trust An Identity keystore you create and the trusted CAs defined in the cacerts file in the JAVA_HOME/jre/lib/security directory.
    Custom Identity and Custom Trust Identity and Trust keystores you create.
    Custom Identity and Command-Line Trust An Identity keystore you create and command-line arguments that specify the location of the Trust keystore.

  7. Click Continue.

  8. Define attributes for the Identity keystore.

    Custom Identity Keystore File Name The fully qualified path to the Identity keystore.
    Custom Identity Keystore Type The type of the keystore. Generally, this attribute is jks.
    Custom Identity Keystore PassPhrase The password defined when creating the keystore. This attribute is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WLS only reads from the keystore so whether or not you define this property depends on the requirements of the keystore. Confirm the password.

  9. Define attributes for the Trust keystore.

    If you choose Java Standard Trust, specify the password defined when creating the keystore. Confirm the password.

    If you choose Custom Trust, define the following attributes:

    Custom Trust Keystore File Name The fully qualified path to the trust keystore.
    Custom Trust Keystore Type The type of the keystore. Generally, this attribute is jks.
    Custom Trust Keystore PassPhrase The password defined when creating the keystore. This attribute is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WLS only reads from the keystore so whether or not you define this property depends on the requirements of the keystore. Confirm the password.

  10. Click Continue.

  11. Click Finish.

    Optionally, configure the SSL attributes for WLS. You do not have to perform this step if you are using keystores for the purpose of digital signing.

  12. Reboot WLS.

 

Configure SSL

By default, SSL is enabled and configured to use the demonstration Identity and Trust keystores. For testing and development purposes, the SSL configuration is complete. Use the steps in this section to configure SSL for production use.

To configure SSL:

  1. Expand the Servers node.

  2. Click the name of the server for which you want to configure keystores (for example, exampleserver).

  3. Click the Configuration-->Keystores and SSL tab.

    Information about the demonstration Identity and Trust keystores is displayed in the Keystore Configuration.

  4. Configure new Identity and Trust keystores for WLS.

    For the purpose of backward compatibility, private keys and trusted CA certificates can be stored in a file or in a JKS keystore accessed via the WebLogic Keystore provider. If you use one of these mechanisms to store private keys and trusted CA certificates, skip this step.

  5. Click the Change... link in the SSL Configuration to configure attributes for SSL. The Configure SSL page appears.

  6. Specify how the identity and trust for WLS is stored. The following options are available:

    Key Stores Use this option if you created Identity and Trust keystores for WLS. If you choose this option, go to step 8.
    Files or Key Store Providers Use this option if you stored private keys and trusted CA certificates in a file or in a JKS keystore accessed via the WebLogic Keystore provider. If you choose this option, go to step 9. This option is available for the purpose of backward compatibility only.

  7. Click Continue.

  8. Specify the alias used to load the private key into the keystore in the Private Key Alias and the password used to retrieve the private key from the keystore in the Passphrase attibute. You may have specified this information when creating the Identity keystore, however, for the purpose of SSL configuration specify the information again.

    You do not have to specify this information for the Trust keystore because trusted CA certificates are not individually identified to WLS with aliases. All trusted CA certificates in a keystore identified as trusted by WLS are trusted. Therefore, WLS does not require an alias when retrieving a trusted CA certificate from the keystore.

  9. Specify information about the location of identity and trust for WLS.

    Private Key File Name The directory location of the private key for WLS. Specify a value for this attribute only if you stored the private key for WLS in a file.
    Private Key Alias The alias specified when loading the private key for WLS into the keystore. Specify a value for this field only if you stored the private key for WLS in a keystore accessed by the WebLogic Keystore provider.
    Passphrase The password specified when loading the private key for WLS into the keystore. Specify a value for this field only if you stored the private key for WLS in a keystore accesssed by the WebLogic Keystore provider. Confirm the password.
    Server Certificate File Name The directory location of the digital certificate for WLS. If you are using a certificate chain that is deeper than two certificates, you to need to include the entire chain in PEM format in the certificate file.
    Trusted CA File Name The name of the file containing the PEM-encoded trusted certificate authorities.

  10. Click Continue.

  11. Click Finish.

  12. Reboot WLS.

 

Configure Two-Way SSL

By default, WLS is configured to use one-way SSL (the server passes its identity to the client). For a more secure SSL connection, use two-way SSL. In a two-way SSL connection, the client verifies the identity and trust of the server and then passes its identity and trust to the server. The server then validates the identity and trust of the client before completing the SSL connection. The server determines whether or not two-way SSL is used.

To enable two-way SSL:

  1. Configure one-way SSL as described in Configuring SSL.

  2. Expand the Servers node.

  3. Click the name of the server for which you want to configure keystores (for example, exampleserver).

  4. Click the Configuration-->Keystores and SSL tab.

  5. Click the Show link under Advanced Options.

  6. Go to the Server attributes section of the window.

  7. Set the Two Way Client Cert Behavior attribute. The following options are available:

    Client Certs Not Requested The default (meaning one-way SSL).
    Client Certs Requested But Not Enforced Requires a client to present a certificate. If a certificate is not presented, the SSL connection continues.
    Client Certs Requested And Enforced Requires a client to present a certificate. If a certificate is not presented, the SSL connection is terminated.

  8. Click Apply.

  9. Reboot WLS.

 

Disable the SSL Port

Unlike previous releases of WLS where you had to explicitly enable the use of SSL between an individual server and SSL clients, this release of WLS has the SSL port enabled by default. However, you may encounter a circumstance where you need to disable the SSL port. For example, the Administration Port uses SSL internally to protect communications between the Administration Server, Managed Servers, and the Node Manager. When using the Administration Port, you might want to disable the SSL port.

To disable the SSL port, perform the following steps:

  1. Expand the Server node.
  2. Select the General tab.
  3. Uncheck the SSL Port Enabled option.
  4. Click Apply to save your changes.
  5. Reboot WLS.

 

Host Name Verification

A host name verifier ensures the host name URL to which the client connects matches the host name in the digital certificate that the server sends back as part of the SSL connection. A host name verifier is useful when an SSL client, or a SSL server acting as a client, connects to an application server on a remote host. It helps to prevent man-in-the-middle attacks.

By default, WLS has host name verification enabled. As a function of the SSL handshake, WLS compares the common name in the SubjectDN in the SSL server's digital certificate with the host name of the SSL server used to initiate the SSL connection. If these names do not match, the SSL connection is dropped. The SSL client is the actual party that drops the SSL connection if the names do not match.

To verify that host name verification is enabled for your WLS deployment, perform the following steps for each server in your domain:

  1. Expand the Servers node.

  2. Click the name of the server (for example, exampleserver).

  3. Click the Configuration-->Keystores and SSL tab.

  4. Click the Show link under Advanced Options.

  5. Go to the Client attributes section of the window.

  6. Verify that the the Hostname Verification field is set to BEA Hostname Verifier.

If anything other than the default behavior is desired, either turn off host name verification or configure a custom host name verifier. Turning off host name verification leaves WLS vulnerable to man-in-the-middle attacks. BEA recommends leaving host name verification on in production environments.

Turn off host name verification in one of the following ways:

On the command line of the SSL client, enter the following argument:

-Dweblogic.security.SSL.ignoreHostnameVerification=true

When using Java clients, host name verification must be set on the command-line.

In the WLS console:

  • Expand the Servers node.
  • Click the name of the server (for example, exampleserver).
  • Click the Configuration-->Keystores and SSL tab.
  • Click the Show link under Advanced Options.
  • Go to the Client attributes section of the window.
  • Set the Hostname Verification field to None.
  • Reboot WLS.

You can also write a custom host name verifier. If you write a custom host name verifier, the name of the class that implements the host name verifier must be specified in the CLASSPATH of WLS.

To configure a custom host name verifier:

  1. Expand the Servers node.

  2. Click the name of the server (for example, exampleserver).

  3. Click the Configuration-->Keystores and SSL tab.

  4. Click the Show link under Advanced Options.

  5. Go to the Client attributes section of the window.

  6. Set the Hostname Verification field to Custom Hostname Verifier.

  7. Enter the name of the implementation of the weblogic.security.SSL.HostnameVerifier interface in the Custom Hostname Verifier field.

  8. Reboot WLS.

When using Java clients, a custom host name verifier must be specified on the command-line using the following argument:

-D weblogic.security.SSL.hostnameVerifier=classname

where classname specifies the implementation of the weblogic.security.SSL.HostnameVerifier interface.

 

Enable SSL Debugging

SSL debugging provides more detailed information about the SSL events that occurred during an SSL handshake. The SSL debug trace displays information about:

  1. Trusted certificate authorities
  2. SSL server configuration information
  3. Server identity private key(and digital certificate)
  4. The strength that is allowed by the license in use
  5. Enabled ciphers
  6. SSL records that were passed during the SSL handshake
  7. SSL failures detected by WLS (for example, trust and validity checks and the default host name verifier)
  8. I/O related information

Use the command-line properties to enable SSL debugging:

-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

The SSL debugging properties can be included in the start script of the SSL server, the SSL client, and the Node Manager. For Managed Server started by the Node Manager, specify this command-line argument on the Remote Start tab for the Managed Server.

SSL debugging dumps a stack trace whenever an ALERT is created in the SSL process. The types and severity of the ALERTS are standard defined by the TLS specification.

The stack trace dumps information into the log file where the ALERT originated. Therefore, when tracking an SSL problem, you made need to enable debugging on both sides of the SSL connection (on both the SSL client or the SSL server). The log file contains detailed information about where the failure occurred. To determine where the ALERT occurred, check if there is a trace message after the ALERT. An ALERT received after the trace message indicates the failure occurred on the peer. To determine the problem, you need to enable SSL debugging on the peer in the SSL connection.

When tracking an SSL problem, review the information in the log file to ensure:

  • The correct config.xml file was loaded
  • The license (domestic or export) is correct
  • The trusted certificate authority was valid and correct for this server.
  • The host name check was successful
  • The certificate validation was successful

Sev 1 type 0 is a normal close ALERT, not a problem.

 

SSL Session Behavior

WLS allows SSL sessions to be cached. Those sessions live for the life of the server. This behavior change in this release of WLS. The weblogic.security.SSL.sessionCache.size and weblogic.security.SSL.sessionCache.ttl command-line arguments are ignored.

By default, clients that use HTTPS URLs get a new SSL session for each URL because each URL uses a different SSL context and therefore SSL sessions can not be shared or reused. The SSL session can be retrieved using the weblogic.net.http.HttpsClient class or the weblogic.net.http.HttpsURLConnection class. Clients can also resume URLs by sharing a SSLSocket Factory between them.

Clients that use SSL sockets directly can control the SSL session cache behavior. The SSL session cache is specific to each SSL context. All SSL sockets created by SSL socket factory instances returned by a particular SSL context can share the SSL sessions.

Clients default to resuming sessions at the same IP address and port. Multiple SSL sockets use the same host and port share SSL sessions by default assuming the SSL sockets are using the same underlying SSL context.

Clients that don't want SSL sessions to be used at all need to explicitly call setEnableSessionCreation(false) on the SSL socket to ensure that no SSL sessions are cached. This setting only controls whether an SSL session is added to the cache, it does not stop an SSL socket from finding an SSL session that was already cached (for example, SSL socket 1 caches the session, SSL socket 2 sets setEnableSessionCreation to false but it can still reuse the SSL session but can still reuse the SSL session from SSL socket 1 since that session was put in the cache.)

SSL sessions exist for the lifetime of the SSL context, they are not controlled by the lifetime of the SSL socket. Therefore, creating a new SSL socket and connecting to the same host and port can resume a previous session as long as the SSL socket is created using an SSL socket factory from the SSL context that has the SSL session in its cache.

In WLS 6.x, there is one SSL session cached in the thread of execution. In this release of WLS, session caching is maintained by the SSL context which can be shared by threads. A single thread has access to the entire session cache not just one SSL session so multiple SSL sessions can be used and shared in a single (or multiple) thread.

 

Configure SSL for the Node Manager

The Node Manager uses 2-way SSL to protect communications with Administration and Managed Servers. The configuration of SSL involves obtaining identity and trust for the Node Manager and each Administration and Managed Server with which the Node Manager will be communicating and then configuring the Node Manager, the Administration Server, and any Managed Servers with the proper identity and trust. In addition, the use of the Administration port must be taken into consideration. This section describes two scenarios: using the demonstration identity and trust provided by WLS and using production-quality identity and trust.

To use SSL, Administration Servers require:

Identity Administration Servers use private keys and digital certificates stored in keystores. The digital certificate must specify a host name rather than an IP address. The location of the Identity keystore is specified in the WLS console. By default, Administration Servers are configured to use the demonstration Identity keystore (DemoIdentity.jks). For testing and development purposes the Identity keystore configuration is complete.
Trust Administration Servers use trusted CA certificates stored in a keystore. The location of the Trust keystore is specified in the WLS console.

By default, Administration Servers are configured to use the demonstration Trust keystore (DemoTrust.jks) and the Java Standard Trust keystore (JAVA_HOME/jre/lib/security/cacerts). For testing and development purposes the Trust keystore configuration is complete.

In a production environment, a custom Trust keystore (a keystore you create) or the Java Standard Trust keystore can be used with the Administration Server. The Administration Server needs to trust the certificate authorities for both the Node Manager and any Managed Servers (meaning those trusted CA certificates must be in the Trust keystore of the Administration Server).

Host name verification By default, host name verification is enabled on Administration Servers.
Administration port The use of the Administration port is optional when configuring SSL. The Administration port uses SSL internally to protect all Administration communications. By default, there is no Administration port enabled.

BEA recommends using the Administration port in a production environment. All Administration Servers, Managed Servers, and Node Managers on the same machine must use unique numbers for the Listen port.

 

SSL Requirements for Managed Servers

To use SSL, Managed Servers require:

Identity Managed Servers use private keys and digital certificates stored in keystores. The digital certificate must specify a host name rather than an IP address. The location of the Identity keystore is specified in the WLS console.

By default, Managed Servers are configured to use the demonstration Identity keystore (DemoIdentity.jks). For testing and development purposes the Identity keystore configuration is complete. However, the demonstration keystore should not be used in a production environment.

Trust Managed Servers use trusted CA certificates stored in a keystore. The location of the Trust keystore is specified in the WLS console.

By default, Managed Servers are configured to use the demonstration Trust keystore (DemoTrust.jks) and the Java Standard Trust keystore (JAVA_HOME/jre/lib/security/cacerts). For testing and development purposes the Trust keystore configuration is complete.

In a production environment, a custom Trust keystore (a keystore you create) or the Java Standard Trust keystore can be used with a Managed Server. A Managed Server needs to trust the certificate authorities for both the Node Manager and the Administration Server (meaning those trusted CA certificates must be in the trust keystore of the Managed Server).

Host name verification By default, host name verification is enabled on Managed Servers.
Administration port The use of the Administration port is optional when configuring SSL. The Administration port uses SSL internally to protect all Administration communications. By default, there is no Administration port enabled. BEA recommends using the Administration port in a production environment. All Administration Servers, Managed Servers, and Node Managers on the same machine must use unique numbers for the Administration port.

 

SSL Requirements for the Node Manager

BEA recommends not running the Node Manager as an operating system service when using SSL. To use SSL, the Node Manager requires:

  1. Keystores

    Specify the type of keystore configuration to be used by the Node Manager. By default, the Node Managed is configured to use DemoIdentityandDemoTrust as the keystore congfiguration. The keystore configuration is specified in the nodemanager.properties file by the following properties:

    Keystores=CustomIdentityandCustomTrust
    Keystores=CustomIdentityandJavaStandardTrust

  2. Identity

    The Node Manager uses private keys and digital certificates stored in keystores. The digital certificate must specify a host name rather than an IP address.

    By default, the Node Manager is configured to use the demonstration Identity keystore (DemoIdentity.jks). For testing and development purposes the Identity keystore configuration is complete. However, this demonstration Identity keystore should not be used in a production environment.

    The Identity keystore is specified in the nodemanager.properties file by the following properties:

    CustomIdentityKeystoreType
    CustomIdentityAlias
    CustomIdentityKeystoreFileName
    CustomIdentityKeystorePassPhrase
    CustomIdentityPrivateKeyPassPhrase

  3. Trust

    The Node Manager uses trusted CA certificates stored in a keystore. You can either use a keystore you create (custom) or the keystore in the JDK (Java Standard).

    By default, the Node Manager is configured to use the demonstration Trust keystore (DemoTrust.jks) and the Java Standard Trust keystore (JAVA_HOME/jre/lib/security/cacerts). For testing and development purposes the Trust keystore configuration is complete.

    The Trust keystore is specified in the nodemanager.properties file by the following properties:

    Custom Trust keystore:
    CustomTrustKeystoreType
    CustomTrustKeystoreFileName
    CustomTrustKeystorePassPhrase
    Java Standard Trust keystore:
    JavaStandardTrustKeystorePassphrase

    In a production environment, the Node Manager must also trust the certificate authorities used by the Administration Server and any Managed Servers (meaning those trusted CA certificates must be in the Trust keystore of the Node Manager).

  4. Trusted Hosts

    The Node Manager accepts commands only from Administration Servers that reside on a trusted hosts. The trusted hosts for a Node Manager process are identified by IP address or DNS name in a file. By default, the file is named nodemanager.hosts and installed in the WL_HOME/common/nodemanager/config directory.

    There is one Node Manager per machine, however, domains managed by the Node Manager can have multiple machines. Make sure the nodemanager.hosts file lists the machines (hosts) for the Administration Servers for any domain you want to run from this machine. By default, the nodemanger.hosts file always defaults to localhost.

    The hosts may be specified by IP address or name. If you want to use host names, specify the ReverseDNSEnabled property in the nodemanager.properties file.

 

Identity and Trust: Demonstration Versus Production

By default, the Node Manager, the Administration Server, and any Managed Servers, are configured to use the demonstration Identity keystore (DemoIdentity.jks), the demonstration Trust keystore (DemoTrust.jks), and the Java Standard Trust keystore (JAVA_HOME/jre/lib/security/cacerts). For testing and development purposes the Identity and Trust keystore configuration is complete.

However, the demonstration keystores should not be used in a production environment. All the digital certificates and trusted CA certificates in the keystores are signed by a WLS demonstration certificate authority. Therefore, all WLS installations trust each other. This will leave your SSL connections wide open to a number of security attack.

Keystores are configured on a per machine basis. You can share keystores and identity and trust for Administration Servers, Managed Servers, and Node Managers that run on the same machine.

When migrating to a production environment, you need to perform the following steps:

  1. Obtain private keys and digital certificates for the Node Manager, Administration Servers, and Managed Servers from a reputable certificate authority such as Verisign, Inc. or Entrust.net.

  2. Ensure Identity and Trust keystores for the Node Manager, Administration Server, and any Managed Servers exist. In previous releases, WLS only supported JKS keystores. In this release, WLS can access private keys and trusted CA certificates from any type of keystore. When you configure the keystore in the WLS console, you optionally specify its type.

    In a production environment, you can use the Java Standard Trust keystore (JAVA_HOME/jre/lib/security/cacerts)as the Trust keystore for the Node Manager, the Administration Server, or any Managed Servers.

  3. Load the private keys and trusted CA certificates into the keystore.

  4. Configure the keystore location and passwords for the Administration Server and Managed Server in the WLS console.

  5. Edit the nodemanager.properties file to specify the keystore location and passwords for the Node Manager.

 

Host Name Verification Requirements

In previous releases of WLS, you had to enable host name verification. In this release of WLS, host name verification is enabled by default. BEA recommends using host name verification to ensure the host you are connecting to is the intended host. To avoid errors when using host name verification, check the following:

  • All digital certificates have host names rather than IP addresses.
  • All digital certificates have the correct host name.
  • All URLs use host names rather than IP addresses.
  • The Listen Address defined for the Node Manager, Administration Server, and any Managed Servers matches the host name in the digital certificate.
  • Host name verification is enabled on the Node Manager, the Administration Server, and any Managed Servers.

 

Node Manager SSL Demonstration Configuration

Using the demonstration Identity and Trust keystores provided by WLS to configure SSL for the Node Manager involves verifying the default settings for the keystore attributes and ensuring that the Administration Server and any Managed Servers are listening for SSL communications on different ports.

The following procedure assumes the Node Manager, the Administration Server, and all Managed Servers are running on the same machine.

To configure the Node Manager to use SSL and the demonstration Identity and Trust keystores:

  1. Run the Configuration Wizard and create a new WebLogic domain.

  2. Start the Administration Server. Do not enable the Administration port.

    On the Server --> Keystores and SSL tab, verify the settings of the following Identity keystore attributes for the Administration Server:

    Demo Identity Keystore DemoIdentity.jks
    Type JKS
    Passphrase DemoIdentityKeyStorePassPhrase

  3. On the Server-->Keystores and SSL tab, verify the settings of the following Trust keystore attributes for the Administration Server:

    Demo Trust Keystore DemoTrust.jks
    Type JKS
    Passphrase DemoTrustKeyStorePassPhrase

  4. On the Server-->General tab for the Managed Server, verify the SSL Listen Port Enabled attribute is checked and the port number specified in the SSL Listen Port attribute is different than the port number specified in the SSL Listen Port attribute for the Administration Server.

  5. On the Server-->Keystores and SSL tab, verify the settings of the following Identity keystore attributes for the Managed Server:

    Demo Identity Keystore DemoIdentity.jks
    Type JKS
    Passphrase DemoIdentityKeyStorePassPhrase

  6. On the Server-->Keystores and SSL tab, verify the settings of the following Trust keystore attributes for the Managed Server:

    Demo Trust Keystore DemoTrust.jks
    Type JKS
    Passphrase DemoTrustKeyStorePassPhrase

  7. No changes to the nodemanager.properties file are required. The Node Manager will automatically default to the demonstration Identity and Trust keystores.

 

Node Manager SSL Production Configuration

The following procedure assumes the Node Manager, the Administration Server, and all Managed Servers are running on the same machine.

When configuring keystores through the WebLogic Administration Servers, passwords are available in clear text during the configuration process. For a more secure deployment, BEA recommends taking the machine on which you are configuring the Node Manager off the Internet or ensure the machine is protected behind a firewall so that passwords can not be snooped.

To configure SSL for the Node Manager:

  1. Obtain identity and trust for the Node Manager, the Administration Server, and any Managed Servers.

    When obtaining identity and trust for the Administration Server, any Managed Server(s), and the Node Manager, ensure the digital certificates include the machine's host name (so that the digitial certificate matches the URL).

  2. Create Identity keystores for the Node Manager, the Administration Server, and any Managed Servers. If the Node Manager, the Administration Server, and the Managed Servers run on the same machine, they can share the Identity keystore.

  3. Load the private keys into the Identity keystores.

  4. Create Trust keystores for the Node Manager, Administration Server, and any Managed Servers. If the Node Manager, the Administration Server, and the Managed Servers run on the same machine, they can share the Trust keystore.

  5. Load the trusted CA certificates into the Trust keystore.

  6. Run the Configuration Wizard and create a new WebLogic domain.

  7. Start the Administration Server.

  8. Configure an Administration port for the WebLogic domain.

  9. Set the Listen Address for the Administration Server. The Listen Address is the host name of the machine on which the Administration Server runs. This host name should match the host name in the CN field of the digital certificate for the Administration Server. If you don't set the Listen Address correctly, you may encounter host name verification errors.

  10. Use the following command to determine the host name specified in the CN field of the digital certificate:

    keytool -list -v -keystore fulldirectorypathtokeystore/keystorename

  11. Configure the Identity keystore for the Administration Server.

  12. Configure the Trust keystore for the Administration Server.

  13. Enable the Listen port for any Managed Servers. Because the Administration Server runs on the same machine as the Managed Server, set the Local Administration Port Override attribute on the Server-->General tab to override the Administration Port number. Specify a port number other than the Administration port number used by the Administration Server.

  14. Set the Listen Address for the Managed Server to the host name of the machine on which the Managed Server runs. This host name should match the host name in the digital certificate for the Managed Server.

  15. Configure the Identity keystore for the Managed Server. This step is optional if the Managed Server runs on the same machine as the Administration Server and is sharing the Identity keystore with the Administration Server.

  16. Configure the Trust keystore for the Managed Server. This step is optional if the Managed Server runs on the same machine as the Administration Server and is sharing the Trust keystore with the Administration Server.

  17. Create a machine for the Node Manager.

  18. Set the Listen Address of the Node Manager to the host name of the machine on which the Node Manager runs. This host name should match the host name in the digital certificate for the Node Manager.

  19. Set the Listen Port for the Node Manager. Because the Administration Server and the Node Manager are running on the same machine, specify a port number other than the Administration port number used by the Administration Server

  20. Add any Managed Servers to the machine.

  21. Edit the nodemanager.properties file for the Node Manager. Edit the nodemanager.properties file.

    • Specify the keystore configuration to be used:

      Keystores=CustomIdentityandCustomTrust
      Keystores=CustomIdentityandJavaStandardTrust
      Specify information about the Identity keystore:
      CustomIdentityKeystoreType
      CustomIdentityAlias
      CustomIdentityKeystoreFileName
      CustomIdentityKeystorePassPhrase
      CustomIdentityPrivateKeyPassPhrase

    • Specify information about the Trust keystore. If you use a custom Trust keystore, specify:

      CustomTrustKeystoreType
      CustomTrustKeystoreFileName
      CustomTrustKeystorePassPhrase

      If you use the Java Standard Trust keystore, specify

      Keystores=CustomIdentityandJavaStandardTrust
      JavaStandardTrustKeystorePassPhrase

    • Specify a Listen Address for the Node Manager:

      ListenAddress

      Use the same host name as specified when creating the machine in step 16.

      If you want use host names rather than IP addresses, specify:

      ReverseDnsEnabled

  22. Edit the nodemanager.hosts file located in WL_HOME/common/nodemanager/config to include the names of the machines on which the Administration servers that communicate with the Node Manager run. The Administration Servers are specified by IP address or host name if Reverse DNS is used.

  23. Ensure that each machine in a domain has an updated nodemanager.hosts file. By default, the nodemanger.hosts file defaults to localhost.

  24. Start the Node Manager.

  25. Stop the Administration Server.

  26. Start the Administration Server.

Using Files and the WebLogic Keystore Provider

For backward compatibility, WLS supports using files and the WebLogic Keystore provider as a way to store identity and trust when configuring the Node Manager to use SSL. However, both of these methods are deprecated in this release. Also, private keys stored in files are not protected in any way and are vulnerable to security attacks. BEA recommends upgrading to keystores as a way to store identity and trust for the Node Manager, the Administration Server, and any Managed Servers.

The SSL requirements for identity and trust are as follows:

  • Administration Servers and Managed Servers use private keys stored in JKS keystores accessed through the WebLogic Keystore provider.

  • The digital certificate for an Administration Server and a Managed Server must be stored in a file.

  • Administration Servers and Managed Servers use trusted CA certificates stored in a JKS keystore. The JKS keystore is specified by the command-line arguments in the start script for the Administration Server or Managed Server.

  • The Node Manager can only use digital certificates and private keys stored in files. Identity is specified by the command-line arguments for the Node Manager.

  • The Node Manager uses trusted CA certificates stored in a JKS keystore for trust. The Trust keystore is specified by the command-line arguments for the Node Manager

To use files or the WebLogic Keystore provider to store identity and trust for an Administration Server or a Managed Server, do the following on the admin server and each managed server:

  1. Expand the Servers node.

  2. Click the name of the server for which you want to configure identity and trust (for example, exampleserver).

  3. Click the Configuration-->Keystores and SSL tab. Information about the demonstration Identity and Trust keystores is displayed.

  4. Click the Change... link in the SSL Configuration portion of the tab. The Configure SSL page appears.

  5. Choose the Files or Keystore Providers option.

  6. Click Continue.

  7. Specify information about the location of identity and trust for WLS.

    Private Key Alias The alias specified when loading the private key for WLS into the keystore. Specify a value for this field only if you stored the private key for WLS in a keystore accessed by the WebLogic Keystore provider.
    Passphrase The password specified when loading the private key for WLS into the keystore. Specify a value for this field only if you stored the private key for WLS in a keystore accesssed by the WebLogic Keystore provider.
    Server Certificate File Name The directory location of the digital certificate for WLS. If you are using a certificate chain that is deeper than two certificates, you to need to include the entire chain in PEM format in the certificate file.

  8. Click Continue.

  9. Click Finish.

  10. Reboot WLS.

  11. When starting the Administration Server, use the following command-line argument to specify the location of the Trust keystore:

    -Dweblogic.security.SSL.trustedCAkeystore=path_to_keystore

  12. Specify the location of the Trust keystore for the Managed Server on the Servers-->Configuration-->Remote Start tab as follows:

    weblogic.security.SSL.trustedCAKeyStore

    To use files or a JKS keystore to store identity and trust for the Node Manager, specify the following command-line arguments when starting the Node Manager:

    • Use weblogic.nodemanager.keyFile=filename to specify the location of the private key file.

    • If you password protected the private key file, use weblogic.nodemanager.keyPassword=password to specify the password.

    • Use weblogic.nodemanager.certificateFile=filename to specify the location of the digital certificate for the Node Manager.

    • Use weblogic.security.SSL.trustedCAkeystore=keystorename to specify the location of the JKS trusted keystore.

 

Configure RMI over IIOP with SSL

Use SSL to protect IIOP connections to RMI remote objects. SSL secures connections through authentication and encrypts the data exchanged between objects. To use SSL to protect RMI over IIOP connections, do the following:

  1. Configure WLS to use SSL.

  2. Configure the client Object Request Broker (ORB) to use SSL. Refer to the product documentation for your client ORB for information about configuring SSL.

  3. Use the host2ior utility to print the WLS IOR to the console. The host2ior utility prints two versions of the interoperable object reference (IOR), one for SSL connections and one for non-SSL connections. The header of the IOR specifies whether or not the IOR can be used for SSL connections.

  4. Use the SSL IOR when obtaining the initial reference to the CosNaming service that accesses the WLS JNDI tree.

 

SSL Certificate Validation

In previous releases, WLS did not ensure each certificate in a certificate chain was issued by a certificate authority. This problem meant anyone could get a personal certificate from a trusted certificate authority, use that certificate to issue other certificates and WLS would not detect the invalid certificates. Now all X509 V3 CA certificates used with WLS must have the Basic Constraint extension defined as CA thus ensuring all certificates in a certificate chain were issued by a certificate authority. By default, any certificates for certificate authorities not meeting this criteria are rejected. This section describes the command-line argument that controls the level of certificate validation.

If WLS is booted with a certificate chains that won't pass the certificate validation, an information message is logged noting that clients could reject it.

 

Control the Level of Certificate Validation

By default WLS will reject any certificates in a certificate chain that do not have the Basic Constraint extension defined as CA. However, you may be using certificates that do not meet this requirement or you may want to increase the level of security to conform to the IETF RFC 2459 standard. Use the following command-line argument to control the level of certificate validation performed by WLS:

-Dweblogic.security.SSL.enforceConstraints=option

Options for -Dweblogic.security.SSL.enforceConstraints include:

Option Description
strong or true Use this option to check that the Basic Constraints extension on the CA certificate is defined as CA. For example:

-Dweblogic.security.SSL.enforceConstraints=strong

or

-Dweblogic.security.SSL.enforceConstraints=true

This is the default level of certificate validation.

strict Use this option to check the Basic Constraints extension on the CA certificate is defined as CA and set to critical. This option enforces the IETF RFC 2459 standard. For example:

-Dweblogic.security.SSL.enforceConstraints=strict

This option is not the default because a number of commerically available CA certificates do not conform to the IETF RFC 2459 standard.

off Use this option to disable certificate validation. Use this option carefully. For example, if you purchased CA certificates from a reputable commerical certificate authority and the certificates do not pass the new validation, use this option. However, CA certificates from most commerical certificate authorities should work with the default strong option. For example:

-Dweblogic.security.SSL.enforceConstraints=off

BEA does not recommend use this option in production environment. Instead, purchase new CA certificates that comply with the IETF RFC 2459 standard.

 

Check Certificate Chains

WLS provides a ValidateCertChain command-line utility to check whether or not an existing certificate chain will be rejected by WLS. The utility uses certificate chains from PEM files, PKCS-12 files, PKCS-12 keystores, and JKS keystores. A complete certificate chain must be used with the utility. The following is the syntax for the ValidateCertChain command-line utility:

java utils.ValidateCertChain -file pemcertificatefilenamejava utils.ValidateCertChain -pem pemcertificatefilenamejava utils.ValidateCertChain -pkcs12store pkcs12storefilenamejava utils.ValidateCertChain -pkcs12file pkcs12filename passwordjava utils.ValidateCertChain -jks alias storefilename [storePass]

For example:

java utils.ValidateCertChain -pem zippychain.pemCert[0]: CN=zippy,OU=FOR TESTINGONLY,O=MyOrganization,L=MyTown,ST=MyState,C=USCert[1]: CN=CertGenCAB,OU=FOR TESTINGONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US

 

Troubleshoot Certificate Problems

If SSL communications were working properly in a previous release of WLS and start failing unexpectedly, the problem is mostly likely because the certificate chain used by WLS is failing the validation.

Determine where the certificate chain is being rejected, and decide whether to update the certificate chain with one that will be accepted or change the setting of the -Dweblogic.security.SSL.enforceConstraints command-line argument.

To troubleshoot problems with certificates, use one of the following methods:

  1. If you know where the certificate chains for the processes using SSL communication are located, use the ValidateCertChain command-line utility to check whether the certificate chains will be accepted.

  2. Turn on SSL debug tracing on the processes using SSL communication:

    -Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

    The following message indicates the SSL failure is due to problems in the certificate chain:

    <CA certificate rejected. The basic constraints for a CA certificate were not marked for being a CA, or were not marked as critical>

    When using one-way SSL, look for this error in the client log. When using two-way SSL, look for this error in the client and server logs.

 

nCipher JCE Provider with WLS

JCE providers are written using the Java Cryptography Extension API, available in JDK 1.4. This type of provider is different from the providers written using the WebLogic Security Service Provider Interfaces (SSPIs). WLS does not provide a JCE provider by default.

SSL is a key component in the protection of resources available in Web servers. However, heavy SSL traffic can cause bottlenecks that impact the performance of Web servers. JCE providers offload SSL processing from Web servers freeing the servers to process more transactions. They also provide strong encryption and cryptographic process to preserve the integrity and secrecy of keys.

WLS supports the use of the following JCE providers:

  • The JDK JCE provider (SunJCE) in the JDK 1.4.1.

    By default, the JCE provider in the JDK 1.4.1 has export strength jurisdiction policy files. After filling out the appropriate forms, the domestic strength jurisdiction policy files are downloadable from Sun Microsystem.

    The BEA license will continue to control the strength of the cryptography used by the WLS Application Programming Interfaces (APIs). Client code without the appropriate domestic strength cryptography license will only be able to use the J2SE export strengtth default cryptography. On the server, there will always be a BEA license that will enable either export or domestic strength cryptography.

  • The nCipher JCE provider.

    To install the nCipher JCE provider:

      1. Install and configure the hardware for the nCipher JCE provider per the product's documentation.

      2. Install the files for the nCipher JCE provider. The following files are required:
        • JCE 1.2.1 framework JAR
        • Jurisdiction policy files
        • JCE provider
        • Certificate that signed the JAR file

        The files are installed in one of the following ways:

        • As an installed extension. Copy the files to

          $JAVA_HOME/jre/lib/ext

        • In the CLASSPATH of the server.

      3. Edit the Java security properties file (java.security) to add the nCipher JCE provider to the list of approved JCE providers for WLS.

        $JAVA_HOME/jre/lib/security/java.security

        Specify the nCipher JCE provider as:

        security.provider.n=com.ncipher.provider.km.mCipherKM

        where n specifies the preference order which determines the order in which providers are searched for requested algorithms when no specific provider is requested. The order is 1-based; 1 is the most preferred, followed by 2, and so on.

        The nCipher JCE provider must follow the RSA JCA provider in the security properties file. For example:

        security.provider.1=sun.security.provider.Sun
        security.provider.2=com.sun.rsajca.Provider
        security.provider.3=com.ncipher.provider.km.mCipherKM

      4. Reboot WLS.

      5. To ensure the nCipher JCE provider is working properly, enable debugging per the nCipher product documentation.

        Home