Skip navigation.

eDocs Home > BEA WebLogic Server 8.1 Documentation > Managing WebLogic Security > Configuring SSL

Managing WebLogic Security

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Configuring SSL

This following sections describe how to configure SSL for WebLogic Server:

Note: This chapter applies to WebLogic Server deployments using the security features in this release of WebLogic Server as well as deployments using Compatibility Security.

Configuring SSL is an optional step; however, BEA recommends using SSL in a production environment.

 

SSL: An Introduction

Secure Sockets Layer (SSL) provides secure connections by allowing two applications connecting over a network connection to authenticate the other's identity and by encrypting the data exchanged between the applications. Authentication allows a server and optionally a client to verify the identity of the application on the other end of a network connection. Encryption makes data transmitted over the network intelligible only to the intended recipient.

SSL in WebLogic Server is an implementation of the SSL 3.0 and Transport Layer Security (TLS) 1.0 specifications.

WebLogic Server supports SSL on a dedicated listen port which defaults to 7002. To establish an SSL connection, a Web browser connects to WebLogic Server by supplying the SSL listen port and the HTTPs schema in the connection URL, for example, https://myserver:7002.

Using SSL is computationally intensive and adds overhead to a connection. Avoid using SSL in development environments 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 certificate.

An application participating in an SSL connection is authenticated when the other party evaluates and accepts the application's digital certificate. Web browsers, servers, and other SSL-enabled applications 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 URL specified by the client.

 

One-Way and Two-Way SSL

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

 

Setting Up SSL: Main Steps

To set up SSL:

  1. Obtain an identity (private key and digital certificates) and trust (certificates of trusted certificate authorities) for WebLogic Server. Use the digital certificates, private keys, and trusted CA certificates provided by the WebLogic Server 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. Private keys and trusted CA certificates are stored in a keystore.

    3. Note: This release of WebLogic Server 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 WebLogic Server in the WebLogic Server Administration Console.
  4. Set SSL attributes for the private key alias and password in the WebLogic Server Administration Console. Optionally, set attributes that require the presentation of client certificates (for two-way SSL).

Note: When starting a WebLogic Server instance, you can specify the command line argument -Dweblogic.security.SSL.nojce=true to use a FIPS-compliant (FIPS 140-2) crypto module in the server's SSL implementation. FIPS 140-2 is a standard that describes U.S. Federal government requirements for sensitive, but unclassified use.

For more information on these steps, see:

 

Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities

To use SSL, the server needs a private key, a digital certificate containing the matching public key, and a certificate for at least one trusted certificate authority. WebLogic Server supports private keys, digital certificates, and trusted CA certificates from the following sources:

Note: The Certificate Request Generator servlet is deprecated in this release of WebLogic Server. Use the keytool utility from Sun Microsystems in place of the Certificate Request Generator servlet. For more information, see Common Keytool Commands.

When using the deprecated file-based private keys, digital certificates, and trusted CA, WebLogic Server can use digital certificates in either privacy-enhanced mail (PEM) or distinguished encoding rules (DER) format.

A .pem 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 WebLogic Server. For more information, see Converting a Microsoft p7b Format to PEM Format.

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

You can still use private keys and digital certificates used with other versions of WebLogic Swith with this version of WebLogic Server. Convert the private key and digital certificate from privacy-enhanced mail (PEM) format to distinguished encoding rules (DER) format. For more information, see the description of the der2pem utility in Using WebLogic Server Java Utilities.

After converting the files, ensure the digital certificate file has the
-----BEGIN CERTIFICATE----- header and the -----END CERTIFICATE----- footer. Otherwise, the digital certificate will not work.

Using the Cert Gen Utility

Note: The Cert Gen 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 provides command line options to specify a CA certificate and key to be used for issuing generated certificates. It will default to using the CertGenCA.der and CertGenCAKey.der files which contain the digital certificate and private key of the demonstration CA certificate. The digital certificates generated by the CertGen utility have the host name of the machine on which they were generated as the value for its common name field (cn) by default only. Command line options let you specify values for the cn and other Subject domain name (DN) fields, such as orgunit, organization, locality, state, countrycode.

The CertGen utility generates public certificate and private key files in PEM and DER formats. On Windows, double-click.der files to view the details of the generated digital certificate. The .pem files can be used when you boot WebLogic Server or use the digital certificates with a client.

Note: By default, the CertGen utility looks for the CertGenCA.der and CertGenCAKey.der files in the current directory, or in the WL_HOME/server/lib directory, as specified in the weblogic.home system property or the CLASSPATH.

If you want to use the default settings you need not specify CA files on the command line. Alternatively, you can specify CA files on the command line, as shown in the following command syntax.

  1. To generate a certificate, enter the following command at a command prompt:
$ java utils.CertGen
[-cacert <ca_cert_file-name>] [-cakey <ca_key_filename>]
[-cakeypass <ca_key_password>] [-selfsigned]
[-certfile <certfile>] [-keyfile <privatekeyfile>]
[-keyfilepass <keyfilepassword>] [-strength <keystrength>]
[-cn <commonname>] [-ou <orgunit>] [-o <organization>]
[-l <locality>] [-s <state>] [-c <countrycode>]
[-subjectkeyid <subjectkeyidentifier>]
[-subjectkeyidformat UTF-8|BASE64]

Argument

Definition

ca_cert_filename

The file name of the issuer's CA public certificate.

ca_key_filename

The file name of the issuer's CA private key.

ca_key_password

The password for the issuer's CA private key.

selfsigned

Generates a self-signed certificate that can be used as a trusted CA certificate.

If this argument is specified, the ca_cert_filename, ca_key_filename, and ca_key_password arguments should not be specified.

certfile

The name of the generated certificate file.

privatekeyfile

The name of the generated private key file.

keyfilepassword

The password for the private key.

keystrength

The length (in bits) of the keys to be generated. The longer the key, the more difficult it is for someone to break the encryption.

commonname

The name to be associated with the generated certificate.

orgunit

The name of the organizational unit associated with the generated certificate.

organization

The name of the organization associated with the generated certificate.

locality

The name of a city or town.

state

The name of the state or province in which the organizational unit (ou) operates if your organization is in the United States or Canada, respectively. Do not abbreviate.

countrycode

Two-letter ISO code for your country. The code for the United States is US.

subjectkeyidentifier

Generates a certificate with the Subject Key identifier extension and the ID value specified on the command line.

UTF-8|BASE64

Format of the subjectkeyid value. Allowed values are UTF-8 or BASE64, with UTF-8 assumed by default.


 
  1. Use theImportPrivateKey utility load the digital certificate and private key into a keystore. See utils.ImportPrivateKey in the WebLogic Server Command Reference.

    2. 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 [domestic].

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 WebLogic Server 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.

Using Certificate Chains (Deprecated)

Note: The use of file-based certificate chains is deprecated in this release of WebLogic Server. Now the whole certificate chain is imported into a keystore. The steps in this section are provided for the purpose of backward compatibility only.

To use certificate chains with WebLogic Server:

  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.

    3. 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 WebLogic Server Administration Console.

Listing 8-1 shows a sample certificate chain.

Listing 8-1 Sample File with Certificate Chain

-----BEGIN CERTIFICATE-----
MIICyzCCAjSgAwIBAgIBLDANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnRzMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMloXDTA2MTAxNTIwMDIxMlowgZ8xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJhbmNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MRkwFwYDVQQDExB3ZWJsb2dpYy5iZWEuY29tMR4wHAYJKoZIhvcNAQkBFg9zdXBwb3J0QGJlYS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMJX8nKUgsFej8pEu/1IVcHUkwY0c2JbBzOryu3sce4QjX+rGxiCjoPm2MY=yts2BvonuJ6CztdZf8B/LBEWCz+qRrtdFn9mKSZWGvrAkmMPz2RhXEOThpoRo5kZz2FQ9XF/PxIJXTYCM7yooRBwXoKYjquRwiZNtUiU9kYi6Z3prAgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAh2eqQGxEMUnNTwEUD
0tBq+7YuAkjecEocGXvi2G4YSoWVLgnVzJoJuds3c35KE6sxBe1luJQuQkE9SzALG/6lDIJ5ctPsHFmZzZxY7scLl6hWj5ON8oN2YTh5Jo/ryqjvnZvqiNIWe/gqr2GLIkajC0mz4un1LiYORPig3fBMH0=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIC+jCCAmOgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnRzMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMVoXDTA2MTAxNjIwMDIxMVowgbYxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJhbmNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MS8wLQYDVQQDEyZEZW1vIENlcnRpZmljYXRlIEF1dGhvcml0eSBDb25zdHJhaW50czEfMB0GCSqGSIb3DQEJARYQc2VjdXJpdHlAYmVhLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA3ynD8l5JfLob4g6d94dNtI0Eep6QNl9bblmswnrjIYz1BVjjRjNVal9fRs+8jvm85kIWlerKzIMJgiNsj50WlXzNX6orszggSsW15pqV0aYE9Re9K
CNNnORlsLjmRhuVxg9rJFEtjHMjrSYr2IDFhcdwPgIt0meWEVnKNObSFYcCAwEAAaMWMBQwEgYDVR0TAQH/BAgwBgEB/wIBATANBgkqhkiG9w0BAQQFAAOBgQBS+0oqWxGyqbZO028zf9tQT2RKojfuwywrDoGW96Un5IqpFnBHIu5atliJo3OUpiH18KkwLN8DVP/3t3K3O3kXdIuLbqAL0i5xyBlAhr7gE5eVhIyeMg7ETBPLyGO2BF13Y24LlsO+MX9jW7fxMraPN608QeJXkZw0E0cGwrw2AQ==
-----END CERTIFICATE-----

Converting 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 WebLogic Server. To convert a digital certificate in p7b format to PEM format:

  1. In Windows Explorer on Windows 2000, select the file (filename.p7b) you want to convert.

    2. A Certificates window appears.

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

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

  4. Select the certificate to convert to PEM format.

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

Note: 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 WebLogic Server.

Using Your Own Certificate Authority

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

  1. Ensure the trusted CA certificates are in PEM format.
  2. Create a Trust keystore. For more information, see Common Keytool Commands.
  3. Store the trusted CA certificate in the Trust keystore. For more information, see Common Keytool Commands.
  4. Configure WebLogic Server to use the Trust keystore. For more information, see Configuring Keystores.

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

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

 

Storing 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 WebLogic Server can use them to find and verify identity. Private keys, their associated digital certificates, and trusted CA certificates are stored in keystores. The keystores can be configured through the WebLogic Server Administration Console or specified on the command-line. Use the Keystore Configuration section of the Keystores and SSL page of the WebLogic Server Administration Console to configure Identity and Trust keystores for WebLogic Server.

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. Use the SSL Configuration section of the Keystores and SSL page of the WebLogic Server Administration Console to specify identity and trust attributes when using a file or a JKS keystore accessed via the WebLogic Keystore provider.

For more information, see:

Creating 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/digital certificate pairs and trusted CA certificates. Use the following mechanisms to create a keystore and load private keys and trusted CA certificates into the keystore:

When configuring SSL you have to decide how identity and trust will be stored. Although one keystore can be used for both identity and trust, for the following reasons, BEA recommends using separate keystores for both identity and trust:

The Identity keystore (private key/digital certificate pairs) and the Trust keystore (trusted CA certificates) may have different security requirements. For example:

For identity, you only have to put the certificates (non-sensitive data ) in the keystore while for trust, you have to put the certificate and private key (sensitive data) in the keystore.

Machines tend to have the same trust rules across an entire domain (meaning, they use the same set of trusted CAs), while they tend to have per server identity. Identity requires a private key and private keys should not be copied from one machine to another. Therefore, separate keystores per machine are created each containing only the server identity needed for that machine. However, trust keystores can be copied from machine to machine thus making it easier to standardizes trust rules.

Identity is more likey to be store in hardware keystores such as nCipher. Trust can be stored in a file-based JDK keystore without having security issues since trust only has certificates not private keys.

By default, WebLogic Server looks for an Identity keystore named DemoIdentity.jks in the WL_HOME\server\lib directory and Trust keystores named DemoTrust.jks in the WL_HOME\server\lib directory and cacerts in the JAVA_HOME\jre\lib\security directory.

All private key entries in a keystore are accessed by WebLogic Server 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.

All certificate authorities in a keystore identified as trusted by WebLogic Server are trusted. Although WebLogic Server 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

Table 8-1 the keytool commands when creating and using JKS keystores with WebLogic Server.

Note: The keytool utility is a product of Sun Microsytems. Therefore, BEA Systems does not provide complete documentation on the utility. For more information, see keytool-Key and Certificate Management Tool.

Table 8-1 Commonly Used keytool Commands

Command

Description

keytool -genkey -keystore keystorename -storepass keystorepassword

Generates a new private key entry and self-signed digital certificate in a keystore. If the keystore does not exist, it is created.

keytool -import -alias aliasforprivatekey
-file privatekeyfilename.pem
-keypass privatekeypassword
-keystore keystorename -storepass keystorepassword

Updates the self-signed digital certificate with one signed by a trusted CA.

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

Loads a trusted CA certificate into a keystore. If the keystore does not exist, it is created.

-certreq -alias alias
-sigalg sigalg
-file certreq_file
-keypass privatekeypassword
-storetype keystoretype
-keystore keystorename
-storepass keystorepassword

Generates a CSR, using the PKCS#10 format.

Sent the CSR to be sent to a trusted CA. The trusted CA authenticates the certificate requestor and returns a digital certificate to replace the existing self-signed digital certificate in the keystore.

keytool -list -keystore keystorename

Displays what is in the keystore.

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

Delete a private key/digital certifcate pair for the specified alias from the keystore.

keytool -help

Provides online help for keytool.


 

 

How WebLogic Server Locates Trust

WebLogic Server uses the following algorithm when it loads its trusted CA certificates:

  1. If the keystore is specified by the -Dweblogic.security.SSL.trustedCAKeyStore command-line argument, load the trusted CA certificates from that keystore.
  2. Else if the keystore is specified in the configuration file (config.xml), load trusted CA certificates from the specified keystore. If the server is configured with DemoTrust, trusted CA certificates will be loaded from the WL_HOME\server\lib\DemoTrust.jks and the JDK cacerts keystores.
  3. Else if the trusted CA file is specified in the configuration file (config.xml), load trusted CA certificates from that file (this is only for compatibility with 6.x SSL configurations).
  4. Else load trusted CA certificates from WL_HOME\server\lib\cacerts keystore.

 

Configuring Keystores

By default, WebLogic Server is configured with two keystores:

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 WebLogic Server demonstration certificate authority. Therefore, all WebLogic Server 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. For more information, see Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities.
  2. Create Identity and Trust keystores. For more information, see Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
  3. Load the private keys and trusted CAs into the Identity and Trust keystores. For more information, see Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.

To configure Identity and Trust keystores for WebLogic Server:

  1. Expand the Servers node.
  2. Select the name of the server for which you want to configure keystores (for example, exampleserver).
  3. Select the Configuration-->Keystores and SSL tab.

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

  4. Click the Change... link in the Keystore Configuration to configure new keystores.
  5. 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 and the cacerts file in the JAVA_HOME\jre\lib\security directory.
    • 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. Use this option in a production environment when the Administration port is enabled and Managed servers are started on the command-line instread of by the Node Manager.
  6. Click Continue.
  7. 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. If this attribute is not specified, the default keystore type defined in the security policy file for the JDK is used.
    • 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. Some keystores do not require the passphrase to read from the keystore. Whether or not you define this property depends on the requirements of the keystore. For example, WebLogic Server only reads from the keystore so a passphrase is not required, however, WebLogic Integration writes to keystores and therefore requires a passphrase. Confirm the password.

      • Note: The passphrase for the Demo Identity keystore is DemoIdentityKeyStorePassPhrase.

  8. Define attributes for the Trust keystore.

    9. 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. If this attribute is not specified, the default keystore type defined in the security policy file for the JDK is used.
    • 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. Some keystores do not require the passphrase to read from the keystore. Whether or not you define this property depends on the requirements of the keystore. For example, WebLogic Server only reads from the keystore so a passphrase is not required, however, WebLogic Integration writes to keystores and therefore requires a passphrase. Confirm the password.
  9. Click Continue.
  10. Click Finish.
  11. Optionally, configure the SSL attributes for WebLogic Server. You do not have to perform this step if you are using keystores for the purpose of digital signing.
  12. Reboot WebLogic Server.

 

Configuring 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. Select the name of the server for which you want to configure keystores (for example, exampleserver).
  3. Select the Configuration-->Keystores and SSL tab.

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

  4. Configure new Identity and Trust keystores for WebLogic Server. For more information, see Configuring Keystores.

Note: 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 migrated from a previous version of WebLogic Server, WebLogic Server uses the existing security configuration and sets the Files or Key Store Providers option. In this circumstance, step 4 can be skipped.

  1. Click the Change... link in the SSL Configuration to configure attributes for SSL.

    2. The Configure SSL page appears.

  2. Specify how the identity and trust for WebLogic Server is stored. The following options are available:
    • Key Stores—Use this option if you created Identity and Trust keystores for WebLogic Server. 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 (as supported in previous releases of WebLogic Server). If you choose this option, go to step 9. This option is available for the purpose of backward compatibility only and it automatcally set with security information from a previous release of WebLogic Server.
  3. Click Continue.
  4. 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. Skip to step 10.

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

  1. Specify information about the location of identity and trust for WebLogic Server.

    2. Note: This step only applies if the Files or Key Store Providers option is specified.

    • Private Key File Name—The directory location of the private key for WebLogic Server. Specify a value for this attribute only if you stored the private key for WebLogic Server in a file (versus a WebLogic Keystore provider).
    • Private Key Alias—The alias specified when loading the private key for WebLogic Server from the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accessed by the WebLogic Keystore provider.
    • Passphrase—The password specified when loading the private key for WebLogic Server into the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accesssed by the WebLogic Keystore provider. Confirm the password. If you protected the private key file with a password, specify the weblogic.management.pkpassword command-line argument when starting the server.
    • Server Certificate File Name— The directory location of the digital certificate for WebLogic Server. 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.
  2. Click Continue.
  3. Click Finish.
  4. Reboot WebLogic Server.

 

Configuring Two-Way SSL

By default, WebLogic Server 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 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.

Before configuring two-way SSL, ensure the Trust key store for the server includes the certificate for the trusted certificate authority that signed the certificate for the client.

To enable two-way SSL:

  1. Configure one-way SSL as described in Configuring SSL.
  2. Expand the Servers node.
  3. Select the name of the server for which you want to configure two-way SSL (for example, exampleserver).
  4. Select 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 or if the certificate is not trusted, the SSL connection is terminated.
  8. Click Apply.
  9. Reboot WebLogic Server.

 

Disabling the SSL Port

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:

  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 WebLogic Server.

 

Using Host Name Verification

A host name verifier ensures the host name in the 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 an 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, WebLogic Server has host name verification enabled. As a function of the SSL handshake, WebLogic Server 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.

In this release of WebLogic Server, the host name verification feature is updated so that if the host name in the certificate matches the local machine's host name, host name verification passes if the URL specifies localhost, 127.0.01 or the default IP address of the local machine.

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

Note: The following steps only apply when a WebLogic Server instance is acting as an SSL client. Java clients acting as SSL clients specifiy the use of host name verification via command-line arguments.

  1. Expand the Servers node.
  2. Select the name of the server (for example, exampleserver).
  3. Select 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 WebLogic Server 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:

  1. Expand the Servers node.
  2. Select the name of the server (for example, exampleserver).
  3. Select 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 None.
  7. Reboot WebLogic Server.

You can also write a custom host name verifier. For more information, see Programming WebLogic Security. 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 WebLogic Server (when acting as an SSL client) or a Java client acting as an SSL client.

To configure a custom host name verifier:

  1. Expand the Servers node.
  2. Select the name of the server (for example, exampleserver).
  3. Select 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 WebLogic Server.

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

-Dweblogic.security.SSL.HostnameVerifier=classname

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

 

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

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 a 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 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, confirm whether 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:

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

 

SSL Session Behavior

WebLogic Server allows SSL sessions to be cached. Those sessions live for the life of the server. This behavior changed in this release of WebLogic Server. The weblogic.security.SSL.sessionCache.size command-line argument is 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 WebLogic Server 6.x, one SSL session is cached in the thread of execution. In this release of WebLogic Server, 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.

 

Configuring SSL for the Node Manager

The Node Manager uses two-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. The following sections describe SSL requirements for the Node Manager and describes two scenarios: using the demonstration identity and trust provided by WebLogic Server and using production-quality identity and trust.

SSL Requirements for Administration Servers

To use SSL, Administration Servers require:

SSL Requirements for Managed Servers

To use SSL, Managed Servers require:

If the Administration port is enabled, a Managed Server needs to use the SSL protocol to contact the Administration Server to download its configuration information as defined in the config.xml file. However, the config.xml file contains SSL configuration for the Managed Server. Therefore, the Managed Server needs uses the SSL protocol to obtain its SSL configuration information as defined in the config.xml file. To break the deadlock, the Managed Server defaults to demonstration trust until it has contacted the Administration Server and downloaded its configuration information. The Managed Server can also use command-line switches which explicitly set trust. Use these switches in a production environment.

SSL Requirements for the Node Manager

To use SSL, the Node Manager requires:

Host Name Verification Requirements

In previous releases of WebLogic Server, you had to enable host name verification. In this release of WebLogic Server, 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:

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 WebLogic Server demonstration certificate authority. Therefore, all WebLogic Server 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.

:Perform the following steps to configure identity and trust for a production environment:

  1. Obtain private keys and digital certificates for the Node Manager, Administration Servers, and Managed Servers from a reputable certificate authority. For more information, see Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities.
  2. Ensure Identity and Trust keystores for the Node Manager, Administration Server, and any Managed Servers exist. In previous releases, WebLogic Server only supported JKS keystores. In this release, WebLogic Server can access private keys and trusted CA certificates from any type of keystore. When you configure the keystore in the WebLogic Server Administration Console, you optionally specify its type.

    3. In a production environment, you can also 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 certificates into the Identity keystore and trusted CA certificates into the Trust keystore.
  4. Configure the keystore location and passwords for the Administration Server and Managed Server in the WebLogic Server Administration Console.
  5. Edit the nodemanager.properties file to specify the keystore location and passwords for the Node Manager.

Node Manager SSL Demonstration Configuration: Main Steps

Using the demonstration Identity and Trust keystores provided by WebLogic Server 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.

Figure 8-1 illustrates the SSL demonstation configuration for the Node Manager.

Figure 8-1 SSL Demonstration Configuration for the Node Manager


 

SSL Demonstration Configuration for the Node Manager


 


 

Note: 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. See Example: Creating a Domain with Administration Server and Clustered Managed Servers.

  2. Start the Administration Server. Do not enable the Administration port.
  3. 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
  4. 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
  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

      • Note: 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: Main Steps

Figure 8-2 illustrates the SSL production configuration for the Node Manager.

Figure 8-2 SSL Production Configuration for the Node Manager

SSL Production Configuration for the Node Manager


 

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

Warning: When you configure keystores through the WebLogic Administration Servers, passwords are available in clear text during the configuration process. The passwords will be encrypted automatically when the configuration is complete and the Node Manager is started. 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.

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

  1. 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. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
  2. Load the private keys into the Identity keystores. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
  3. 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. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
  4. Load the trusted CA certificates into the Trust keystore. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
  5. Run the Configuration Wizard and create a new WebLogic domain.
  6. Start the Administration Server.
  7. Enable the Administration port for the WebLogic domain. See Enabling the Domain-Wide Administration Port.
  8. 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.

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

    keytool -list -v -keystore fulldirectorypathtokeystore\keystorename

  9. Configure the Identity keystore for the Administration Server. See Configuring Keystores.
  10. Configure the Trust keystore for the Administration Server. See Configuring Keystores.
  11. If you have multiple servers running on the same machine, ensure the Administration Port for each server is unique. Use 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.
  12. 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.
  13. Configure the Identity keystore for the Managed Server. See Configuring Keystores.
  14. Configure the Trust keystore for the Managed Server. See Configuring Keystores.
  15. Create a machine for the Node Manager.
    1. 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.
    2. Set the Listen Port for the Node Manager. Ensure that this port number is different from the Listen port number, the SSL port number, and the Administration port number of all the servers that run on this machine.
    3. Add any Managed Servers to the machine.

      4. For more information, see Configuring, Starting,and Stopping the Node Manager in Configuring and Managing WebLogic Server.

  16. Edit the nodemanager.properties file for the Node Manager. Edit the nodemanager.properties file.
    1. Specify the keystore configuration to be used:

      2. Keystores=CustomIdentityandCustomTrust

      Keystores=CustomIdentityandJavaStandardTrust

    2. Specify information about the Identity keystore:

      3. CustomIdentityKeystoreType

      CustomIdentityAlias

      CustomIdentityKeystoreFileName

      CustomIdentityKeyStorePassPhrase

      The CustomIdentityKeystoreType attribute is optional and defaults to the keystore type defined in the security policy file for the JDK.

      The CustomIdentityKeyStorePassPhrase attribute is optional depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. Some keystores do not require the passphrase to read from the keystore. Whether or not you define this property depends on the requirements of the keystore. For example, WebLogic Server only reads from the keystore so a passphrase is not required, however, WebLogic Integration writes to keystores and therefore requires a passphrase.

      CustomIdentityPrivateKeyPassPhrase

    3. Specify information about the Trust keystore.

      4. If you use a custom Trust keystore, specify:

      CustomTrustKeystoreType

      CustomTrustKeystoreFileName

      CustomTrustKeyStorePassPhrase

      The CustomTrustKeystoreType attribute is optional and defaults to the keystore type defined in the security policy file for the JDK.

      The CustomTrustKeyStorePassPhrase attribute is optional depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. Some keystores do not require the passphrase to read from the keystore. Whether or not you define this property depends on the requirements of the keystore. For example, WebLogic Server only reads from the keystore so a passphrase is not required, however, WebLogic Integration writes to keystores and therefore requires a passphrase.

      If you use the Java Standard Trust keystore, specify:

      Keystores=CustomIdentityandJavaStandardTrust

      JavaStandardTrustKeyStorePassPhrase

      The JavaStandardTrustKeyStorePassPhrase attribute is optional depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. Some keystores do not require the passphrase to read from the keystore. Whether or not you define this property depends on the requirements of the keystore. For example, WebLogic Server only reads from the keystore so a passphrase is not required; however, WebLogic Integration writes to keystores and therefore requires a passphrase.

    4. Specify a Listen Address and Listen Port for the Node Manager:

      5. ListenAddress
      ListenPort

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

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

      6. ReverseDnsEnabled

    See Node Manager Properties in Configuring and Managing WebLogic Server.

    Note: When adding properties to the nodemanager.properties file, use forward slashes or double backslashes in file and directory names.

  17. Edit the nodemanager.hosts file located in WL_HOME\common\nodemanager\config to list 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.

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

    See Set Up the Node Manager Hosts File in Configuring and Managing WebLogic Server.

  18. Start the Node Manager.
  19. Stop the Administration Server.
  20. Start the Administration Server.

Using Files and the WebLogic Keystore Provider

For backward compatibility, WebLogic Server 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 may or may not be password protected. Private keys that are not password protected can be 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:

Note: Perform the following steps on the Administration Server and each Managed Server you plan to use.

To use files or the WebLogic Keystore provider to store identity and trust for an Administration Server or a Managed Server:

  1. Expand the Servers node.
  2. Select the name of the server for which you want to configure identity and trust (for example, exampleserver).
  3. Select the Configuration-->Keystores and SSL tab.

    4. Information about the demonstration Identity and Trust keystores is displayed.

  4. Click the Change... link in the SSL Configuration portion of the tab.

    5. 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 WebLogic Server.
    • Private Key File Name—The directory location of the private key for WebLogic Server. Specify a value for this attribute only if you stored the private key for WebLogic Server in a file (versus a WebLogic Keystore provider).
    • Private Key Alias—The alias specified when loading the private key for WebLogic Server from the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accessed by the WebLogic Keystore provider.
    • Passphrase—The password specified when loading the private key for WebLogic Server into the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accesssed by the WebLogic Keystore provider. Confirm the password. If you protected the private key file with a password, specify the weblogic.management.pkpassword command-line argument when starting the server.
    • Server Certificate File Name— The directory location of the digital certificate for WebLogic Server. 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 WebLogic Server.
  11. When starting the Administration Server, use the following command-line argument to specify the location of the Trust keystore:

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

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

 

Configuring 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 WebLogic Server 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 WebLogic Server 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 WebLogic Server JNDI tree.

For more information about using RMI over IIOP, see Programming WebLogic RMI and Programming WebLogic RMI over IIOP.

 

SSL Certificate Validation

In previous releases, WebLogic Server 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 WebLogic Server would not detect the invalid certificates. Now all X509 V3 CA certificates used with WebLogic Server 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 WebLogic Server is booted with a certificate chains that will not pass the certificate validation, an information message is logged noting that clients could reject it.

Controlling the Level of Certificate Validation

By default WebLogic Server rejects 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 WebLogic Server:

-Dweblogic.security.SSL.enforceConstraints=option

Table 8-2 describes the options for the command-line argument.

Table 8-2 Options for -Dweblogic.security.SSL.enforceConstraints

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

By default, WebLogic Server performs this level of certificate validation.

strict

Use this option to check whether 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 turn off checking for the Basic Constraints extension. The rest of the certificate validation still happens.

CA certificates from most commercial certificate authorities should work with the default strong option.

For example:

-Dweblogic.security.SSL.enforceConstraints=off

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


 

Accepting Certificate Policies in Certificates

WebLogic Server offers limited support for Certificate Policy Extensions in X.509 certificates. Use the weblogic.security.SSL.allowedcertificatepolicyids argument to provide a comma separated list of Certificate Policy IDs. When WebLogic Server receives a certificate with a critical Certificate Policies Extension, it verifies whether any Certificate Policy is on the list of allowed certificate policies and whether therea are any unsupported policy qualifiers. This release of WebLogic Server supports Certification Practice Statement (CPS) Policy qualifiers and does not support User Notice qualifiers. A certificate is also accepted if it contains a special policy anyPolicy with the ID 2.5.29.32.0, which indicates that the CA does not wish to limit the set of policies for this certificate.

To enable acceptance of Certificate Policies, start WebLogic Server with the following argument:

-Dweblogic.security.SSL.allowedcertificatepolicyids <identifier1>,<identifier2>,...

This argument should contain a comma-separated list of Certificate Policy identifiers for all the certificates with critical extensions that might be present in the certificate chain, back to the root certificate, in order for WebLogic Server to accept such a certificate chain.

Checking Certificate Chains

WebLogic Server provides a ValidateCertChain command-line utility to check whether or not an existing certificate chain will be rejected by WebLogic Server. 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 pemcertificatefilename
java utils.ValidateCertChain -pem pemcertificatefilename
java utils.ValidateCertChain -pkcs12store pkcs12storefilename
java utils.ValidateCertChain -pkcs12file pkcs12filename password
java utils.ValidateCertChain -jks alias storefilename [storePass]

Example of valid certificate chain:

java utils.ValidateCertChain -pem zippychain.pem

Cert[0]: CN=zippy,OU=FOR TESTING
ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US

Cert[1]: CN=CertGenCAB,OU=FOR TESTING
ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US
Certificate chain appears valid

Example of invalid certificate chain:

java utils.ValidateCertChain -jks mykey mykeystore

Cert[0]: CN=corba1,OU=FOR TESTING ONLY, O=MyOrganization,L=MyTown,ST=MyState,C=US
CA cert not marked with critical BasicConstraint indicating it is a CA
Cert[1]: CN=CACERT,OU=FOR TESTING ONLY, O=MyOrganization,L=MyTown,ST=MyState,C=US

Certificate chain is invalid

Troubleshooting Problems with Certificates

If SSL communications were working properly in a previous release of WebLogic Server and start failing unexpectedly, the problem is mostly likely because the certificate chain used by WebLogic Server 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:

 

Using the nCipher JCE Provider with WebLogic Server

Note: JCE providers are written using the application programming interfaces (APIs) in the Java Cryptography Extension (JCE) available in JDK 1.4. This type of provider is different from the providers written using the WebLogic Security Service Provider Interfaces (SSPIs). WebLogic Server 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.

WebLogic Server supports the use of the following JCE providers:

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

      • Note: This step may have been performed as part of installing the hardware for nCipher JCE provider. In that case, verify that the files are correctly installed.

    The files are installed in one of the following ways:

    • As an installed extension. Copy the files to one of the following locations:

      • Windows NT

      %JAVA_HOME%\jre\lib\ext

      For example:

      %WL_HOME%\jdk141\jre\lib\ext

      UNIX

      $JAVA_HOME/jre/lib/ext

      For example:

      $WL_HOME/jdk141/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 WebLogic Server. The Java security properties file is located in:

    4. Windows NT

    %JAVA_HOME%\jre\lib\security\java.security

    UNIX

    $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. Boot WebLogic Server.
  5. To ensure the nCipher JCE provider is working properly, enable debugging per the nCipher product documentation.

 

Specifying the Version of the SSL Protocol

WebLogic Server supports both the SSL V3.0 and TLS V1.0 protocols. By default, WebLogic Server, when acting as an SSL server, will agree to either SSL 3.0 or TLS 1.0 protocol versions, and use whichever of these the client has specified as preferred in its client hello message. When WebLogic Server is acting as an SSL client, it will specify TLS1.0 as the preferred protocol in its SSL V2.0 client hello message, but will agree to SSL V3.0 as well, if that's the highest version that the SSL server on the other end supports. The peer must respond with an SSL V3.0 or TLS V1.0 message or the SSL connection is dropped.

While in most cases the SSL V3.0 protocol is acceptable there are circumstances (compatibility, SSL performance, and environments with maximum security requirements) where the TLS V1.0 protocol is desired. The weblogic.security.SSL.protocolVersion command-line argument allows you to specify what protocol is used for SSL connections.

Note: The SSL V3.0 and TLS V1.0 protocols can not be interchanged. Only use the TLS V1.0 protocol if you are certain all desired SSL clients are capable of using the protocol.

The following command-line argument can be specified so that WebLogic Server supports only SSL V3.0 or TLS V1.0 connections:

 

Using the SSL Protocol to Connect to WebLogic Server from weblogic.Admin

Using the SSL protocol to connect to WebLogic Server from weblogic.Admin requires you to disable two-way SSL on the server, use a secure server port in the URL for the client, specify trust for the client, and configure how the client uses host name verification. The following sections describe these steps in detail.

Ensure Two-Way SSL Is Disabled on the SSL Server

There is no way to specify identity when using weblogic.Admin. Identity (private key and digital certificate or certificate chain) is required when the SSL server is configured for two-way SSL. Therefore, two-way SSL cannot be enabled when using weblogic.Admin. Before establishing an SSL connection from weblogic.Admin to an SSL server, ensure that the SSL server is not configured to use two-way SSL. If two-way SSL is enabled on the SSL server, the SSL connection will fail.

To disable two-way SSL when using WebLogic Server:

  1. Expand the Servers node.
  2. Select the server that will be acting as the SSL server.
  3. Select the Configuration-->Keystores and SSL tab.
  4. Click the Show link in the Advanced Options section.
  5. Set the Two Way Client Cert Behavior attribute to Client Certs Not Requested or Client Certs Requested But Not Enforced.
  6. Click Apply.
  7. Reboot WebLogic Server.

Use a Secure Port in the URL

To use the SSL protocol to make a connection, specify a secure protocol and port in the URL for weblogic.Admin. For example:

weblogic.Admin -url t3s://localhost:9002

Specify Trust for weblogic.Admin

All SSL clients need to specify trust. Trust is a set of CA certificates that specify which trusted certificate authorities are trusted by the client. In order to establish an SSL connection the client needs to trust the certificate authorities that issued the server's digitial certificates.

When using weblogic.Admin, the trusted CA certificates must be stored in a keystore. By default, all the trusted certificate authorities available from the JDK (...\jre\lib\security\cacerts) are trusted by weblogic.Admin. Optionally, use the following command-line argument to specify a password for the JDK cacerts trust keystore:

-Dweblogic.security.JavaStandardTrustKeyStorePassPhrase=password

where password is the password for the Java Standard Trust keystore. This password is defined when the keystore is created.

You also have the option of specifying the one of the following types of trust:

Specify Host Name Verification for weblogic.Admin

By default, weblogic.Admin performs a host name verification check. It compares the CN field in the digital certificate received from the server with the server name in the URL the client used to connect to the server. The CN field and the server name must match to pass the host name verification check. This check is performed to prevent man-in-the-middle attacks. In this release of WebLogic Server, the default host name verifier handles the case where the URL contains localhost or an IP address and the CN field of the digital certificate matches the name of the local host.

It is possible to disable the check by specifying the following command-line argument:

-Dweblogic.security.SSL.ignoreHostnameVerification=true

Note: If the SSL server specified an IP address in its URL, disable the host name verification check.

Use the following command-line argument to specify a custom host name verifier:

-Dweblogic.security.SSL.hostnameVerifier=classname

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

 

Skip navigation bar  Back to Top Previous Next