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 TLS 1.0 specifications.

Note: The proxy plug-ins in this release of WebLogic Server only support SSL 3.0.

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 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 visa 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 (also referred to as trusted certificate authority) and digitally signed with the certificate authority's digital certificate. Well-know certificate authorities include Verisign and Entrust.net. A trusted certificate authority 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 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 host name specified by the client.

One-Way and Two-Way SSL

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

• With 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.

• With two-way SSL, the client also presents a certificate to the server. WebLogic Server can be configured to require clients to submit valid and trusted certificates before completing the SSL connection.

Setting Up SSL: Main Steps

To set up SSL:

1. Obtain a identity (private key and digital certificates) and trust (certificates for 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, the Certificate Request Generator servlet, 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 WebLogic Server. Private keys and trusted CA certificates can either be stored in a keystore, a keystore accessed by the WebLogic Keystore provider, or in a file in the domain directory.

3. Enable the SSL port. By default, the SSL port is not enabled because of the performance impact of its use.

4. Set SSL attributes in the WebLogic Server Administration Console or in the server start script. The SSL attributes define the location of the private key, digital certificate, and trusted CA certificates. Optionally, set attributes that require the presentation of client certificates (for two-way SSL).

For more information on these steps, see:

Obtaining Private Keys, Digital Certificates and Trusted Certificate Authorities

Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities

Enabling the SSL Port

Setting Attributes for One-Way SSL

Setting Attributes for Two-Way SSL

Obtaining 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 at least one trusted certificate authority that can verify the data embedded in the digital certificate. WebLogic Server supports private keys, digital certificates, and trusted certificate authorities from the following sources:

• The demonstration digital certificates, private keys, and trusted certificate authorities in the WL_HOME\server\lib directory.

  When you create a domain through the Configuration Wizard, the demonstration certificates and private keys are copied into the domain directory. The demonstration digital certificates, private keys, and trusted certificate authorities should only be used for demonstration or testing purposes and not in a production environment

• The Cert Gen utility generates digital certificate and private keys that should only be used for demonstration or testing purposes and not in a production environment. Use the Cert Gen utility if you want to set an expiration date in the digital certificate or specify a correct host name in the digital certificate so that you can use host name verification. For more information about using the Cert Gen utility to obtain private keys and digital certificates, see Using the Cert Gen Utility.

• The Certificate Request Generator servlet generates a private key file and a Certificate Signature Request (CSR). To acquire a digital certificate from a trusted certificate authority (such as VeriSign or Entrust.net), you must submit your request in a particular format called a CSR. The digital certificate you receive from the certificate authority and the private key from the Certificate Request Generator servlet are suitable for production environments. For more information, see Using the Certificate Request Generator Servlet.

• Sun Microsystem's keytool utility can also be used to generate a private key, a self-signed digital certificate for WebLogic Server, and a CSR. Submit the CSR to a certificate authority to obtain a digital certificate for WebLogic Server. Use keytool to update the self-signed digital certificate with a new digital certificate. For more information about Sun's keytool utility, see keytool—Key and Certificate Management Tool.

WebLogic Server 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). However, the ordering of the digital certificates in the file is important. For example, cert A, cert B (must be the issuer of cert A), cert C (must be the issuer of cert B),... to the root CA.

A .der format file contains binary data. A .der file can be used only for a single certificate, however, 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.

Using the Cert Gen Utility

Note: 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 hostname of the machine on which they were generated as the common name. If you want to use host name verification, you must 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 WebLogic Server 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 WebLogic Server.

   • WL_HOME\server\lib\CertGenCAKey.der—The private key for a certificate authority trusted by WebLogic Server.

2. Enter the following command at a command prompt:

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

   where

   • password is the password for the private key.

   • certfile is the name of the digital certificate file. The file is put in the current directory.

   • keyfile is the name of the generated private key file. The file is put in the domain directory.

   • hostname is the 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 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 the Certificate Request Generator Servlet

Before using a WebLogic Server deployment in a production environment, you need to obtain a private key and certificate from a trusted certificate authority such as VeriSign or Entrust.net. To acquire a digital certificate from a certificate authority, you must submit your request in a particular format called a CSR. The Certificate Request Generator servlet collects information from you and generates a private key file and a CSR. You then submit the CSR to a certificate authority.

To generate a CSR, perform the following steps:

1. Copy the certificate.war file to the applications directory (copy the file before the server boots or while the server is running). The Configuration Wizard performs this step for you.

2. In a Web browser, enter the URL for the Certificate Request Generator servlet as follows:

   http (or https)://hostname:port/certificate/

   The components of this URL are defined as follows:

   • hostname is the DNS name of the machine running WebLogic Server.

   • port is the number of the port at which WebLogic Server listens for SSL connections. The default is 7002. 7002 is the default port on which WebLogic Server listens for SSL communications. Any port on which WebLogic Server listens for communications can be specified.

     For example, if WebLogic Server is running on a machine named ogre and it is configured to listen for SSL communications at the default port 7002 to run the Certificate Request Generator servlet, you must enter the following URL in your Web browser:

     https://ogre:7002/certificate/

3. The Certificate Request Generator servlet loads a form in your Web browser. Complete the form displayed in your browser, using the information in the following table:

   Table 6-1 Fields on the Certificate Request Generator Form

   Field	Description
   Country code	Two-letter ISO code for your country. The code for the United States is US.
   Organizational unit name	Name of your division, department, or other operational unit of your organization.
   Organization name	Name of your organization. The certificate authority may require any host names entered in this attribute belong to a domain registered to this organization.
   E-mail address	E-mail address of the administrator. The digital certificate is mailed to this e-mail address.
   Full host name	Fully qualified name of the WebLogic Server on which the digital certificate will be installed. This name is the one used for DNS lookups of the WebLogic Server, for example, node.com. Web browsers compare the host name in the URL to the name in the digital certificate. If you change the host name later, you must request a new digital certificate.
   Locality name (city)	Name of your city or town. If you operate with a license granted by a city, this attribute is required; you must enter the name of the city that granted your license.
   State name	Name of the state or province in which your organization operates if your organization is in the United States or Canada, respectively. Do not abbreviate.
   Private Key Password	The password used to encrypt the private key. Enter a password in this field to use a protected key with WebLogic Server. You are prompted for the password whenever the key is used. The servlet creates a PKCS-8 encrypted private key.
   Strength	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. If you have the domestic version of WebLogic Server, choose 512-, 1024-, or 2048-bit keys. The 1024-bit key is recommended.

   
    

4. Click Generate Request.

   The Certificate Request Generator servlet displays messages informing you if any required attributes are empty or if any attributes contain invalid values. Click Back in your Web browser and correct any errors.

   When all attributes have been accepted, the Certificate Request Generator servlet generates the following files in the start directory of your WebLogic Server:

   • hostname-key.der—The private key file.

   • hostname-request.dem—The certificate request file, in binary format.

   • hostname-request.pem—The CSR file that you submit to the certificate authority. It contains the same data as the .dem file but is encoded in ASCII so that it can be copied into e-mail or pasted it into a Web form.

5. Select a certificate authority and follow the instructions on that authority's Web site to purchase a digital certificate.

   • VeriSign, Inc. offers two options for WebLogic Server: Global Site Services, which features strong 128-bit encryption for domestic and export Web browsers, and Secure Site Services, which offers 128-bit encryption for domestic Web browsers and 40-bit encryption for export Web browsers.

   • Entrust.net certificates offer 128-bit encryption for domestic browser versions and 40-bit encryption for export browser versions.

Using Certificate Chains

WebLogic Server supports the use of certificate chains.

To use a 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 format. 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 this section to convert other types of digital certificates. You just need to 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 (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. 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 attribute on the SSL Attributes tab in the WebLogic Server Administration Console.

Listing 6-1 shows a sample certificate chain.

Listing 6-1 Sample File with Certificate Chain

-----BEGIN CERTIFICATE-----
MIICyzCCAjSgAwIBAgIBLDANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk
NhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA
8GA1UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cm
FpbnRzMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMloXDTA2MTA
xNTIwMDIxMlowgZ8xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4g
RnJhbmNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MRkwFwYDVQQDE
xB3ZWJsb2dpYy5iZWEuY29tMR4wHAYJKoZIhvcNAQkBFg9zdXBwb3J0QGJlYS5jb20wgZ8wDQYJKoZIhv
cNAQEBBQADgY0AMIGJAoGBAMJX8nKUgsFej8pEu/1IVcHUkwY0c2JbBzOryu3sce4QjX+rGxiCjoPm2MY
yts2BvonuJ6CztdZf8B/LBEWCz+qRrtdFn9mKSZWGvrAkmMPz2RhXEOThpoRo5kZz2FQ9XF/PxIJXTYCM
7yooRBwXoKYjquRwiZNtUiU9kYi6Z3prAgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAh2eqQGxEMUnNTwEUD
0tBq+7YuAkjecEocGXvi2G4YSoWVLgnVzJoJuds3c35KE6sxBe1luJQuQkE9SzALG/6lDIJ5ctPsHFmZz
ZxY7scLl6hWj5ON8oN2YTh5Jo/ryqjvnZvqiNIWe/gqr2GLIkajC0mz4un1LiYORPig3fBMH0=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIC+jCCAmOgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhb
Glmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1
UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnR
zMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMVoXDTA2MTAxNjIw
MDIxMVowgbYxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJhb
mNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MS8wLQYDVQQDEyZEZW
1vIENlcnRpZmljYXRlIEF1dGhvcml0eSBDb25zdHJhaW50czEfMB0GCSqGSIb3DQEJARYQc2VjdXJpdHl
AYmVhLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA3ynD8l5JfLob4g6d94dNtI0Eep6QNl9b
blmswnrjIYz1BVjjRjNVal9fRs+8jvm85kIWlerKzIMJgiNsj50WlXzNX6orszggSsW15pqV0aYE9Re9K
CNNnORlsLjmRhuVxg9rJFEtjHMjrSYr2IDFhcdwPgIt0meWEVnKNObSFYcCAwEAAaMWMBQwEgYDVR0TAQ
H/BAgwBgEB/wIBATANBgkqhkiG9w0BAQQFAAOBgQBS+0oqWxGyqbZO028zf9tQT2RKojfuwywrDoGW96U
n5IqpFnBHIu5atliJo3OUpiH18KkwLN8DVP/3t3K3O3kXdIuLbqAL0i5xyBlAhr7gE5eVhIyeMg7ETBPL
yGO2BF13Y24LlsO+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, 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.

3. Select the Certificates option.

   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.

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 certificate authorities with WebLogic Server:

1. Ensure the trusted CA certificates are in PEM format. If they are in DER format, you can convert them using the utils.der2pem format. If you are using a digital certificate issued by Microsoft, see Converting a Microsoft p7b Format to PEM Format.

2. Either store the trusted CA certificate in a file or in a JKS keystore accessed by the WebLogic Keystore provider. For more information, see Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.

3. Configure WebLogic Server to use the trusted certificate authority. For more information, see Setting Attributes for One-Way SSL.

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.

You should note that digital certificates are not universally useful for multiple browsers, or even for different versions of the same browser.

Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities

Once you have obtained private keys, digital certificates, and trusted certificate authorities, you need to store them so that WebLogic Server can use them to verify identity. Digital certificates can only be stored in a file. Private keys can either be stored in a file or in a keystore accessed via the WebLogic Keystore provider. Trusted CA certificates can be stored in a file or in a JKS keystore. The keystore can be accessed via the WebLogic Keystore provider or specified on the command-line.

• If you store the private keys, digital certificates, and trusted CA certificates in files, you need to set the SSL Server Key File Name, Server Certificate File Name, and Trusted CA File Name attributes in the WebLogic Server Administration Console. For information about setting SSL attributes, see Setting Attributes for One-Way SSL.

• If you store the private keys and trusted CA certificates in a keystore, you need to create a keystore and load the private keys and trusted CA certificates into the keystore. This release of WebLogic Server only supports JKS keystores.

  For private keys, you must configure the WebLogic Keystore provider to point to the keystore, and set the SSL Server Private Key Alias and Server Private Key Passphrase attributes in the WebLogic Server Administration Console.

  For trusted certificate authorities, you can either configure the WebLogic Keystore provider to point to the keystore, and set the Trusted CA File Name attribute in the WebLogic Server Administration Console or use the -Dweblogic.security.SSL.trustedCAkeystore command-line argument in the server start script to specify the keystore.

  For more information, see:

  • Creating a Keystore and Loading Private Keys and Trusted Certificate Authorities into the Keystore

  • Configuring the WebLogic Server Keystore Provider to Locate a Keystore

  • Setting Attributes for One-Way SSL

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 certificates, and trusted CA certificates. This release of WebLogic Server only supports JKS keystores. The WebLogic Keystore provider locates instances of keystores. Use the following utilities to create a keystore and load private keys and trusted CA certificates into the keystore:

• The WebLogic ImportPrivateKey utility. The ImportPrivateKey utility allows you to take private key files and load them into a keystore. For more information, see utils.ImportPrivateKey in the WebLogic Server Administration Guide.

• Sun Microsystem's keytool utility. Use the keytool utility to generate a private key/digital certificate pair and then import the signed private key into the keystore. For more information, see Common Keytool Commands.

Note: The keytool utility requires a digital certificate for every private key when importing a private key into the keystore. This digital certificate is not used by WebLogic Server.

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.

Either create one keystore for both private keys and trusted CA certificates or two keystores: one for private keys and one for trusted CA certificates. 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:

• The Identity keystore may be prohibited by company policy from ever being put in the network while the Trust keystore can be distributed over the network.

• The Identity keystore may be protected by the operating system for both reading and writing by non-authorized users while the Trust keystore only needs to be write protected.

• The password for the trust keystore is generally known by more people than the password for the Identity keystore.

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 likely 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 a private key keystore named wlDefaultKeyStore.jks in the domain directory. The keystore for trusted CA certificates can use either the demonstration trusted certificate authorities (WL_HOME\server\lib\cacerts) or a trusted certificate authority available from the JDK (...\jre\lib\security\cacerts).

Note: The WL_HOME\server\lib\cacerts file should be used for demonstration or testing purposes and not in a production environment. This file contains the trusted certificate authorities in \jre\lib\security\cacerts.

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.

Trusted certificate authorities are not individually identified to WebLogic Server with aliases. 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.

Aliases are case-insensitive; the aliases Hugo and hugo would refer to the same keystore entry. Aliases for private keys are specified in the Server Private Key Alias attribute when configuring SSL.

Common Keytool Commands

Table 6-2 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.

Configuring the WebLogic Server Keystore Provider to Locate a Keystore

When using the WebLogic Keystore provider, the config.xml file that contains the password for the private key is hashed. This provides an additional level of security not available when storing private keys and trusted CA certificates in files.

Configuring a WebLogic Keystore provider is an optional step. If private keys and digital certificates are stored in files, you do not need to configure the WebLogic Keystore provider. You can also use a JKS keystore without using a WebLogic Keystore provider. For more information, see Using a JKS Keystore.

To configure the WebLogic Keystore provider, you need to create a keystore and set attributes in the WebLogic Server Administration Console that point to the keystore.

Note: Weblogic Keystore providers are configured on a domain basis. However, keystores are configured on a per machine basis. If you have multiple security realms or multiple servers running on the same machine, they can all use the same keystore.

To configure the WebLogic Keystore provider:

1. Create a keystore. For more information, see Creating a Keystore and Loading Private Keys and Trusted Certificate Authorities into the Keystore.

2. In the WebLogic Server Administration Console, expand the Security-->Realms nodes.

3. Click the name of the realm you are configuring (for example, myrealm).

4. Expand the Providers node.

5. Click Key Stores.

   The Keystore tab appears. This tab displays the name keystore configured for the security realm. By default, the WebLogic Keystore provider is configured.

   Note: The WebLogic Server Administration Console refers to the WebLogic Keystore provider as the DefaultKeystore.

6. Click DefaultKeystore.

7. On the General tab, enter the directory location of the keystore in the Private Key Store Location attribute. The default is wlDefaultKeyStore.jks.

   This attribute requires both a directory and filename location that is either absolute or relative to root directory (that is, the domain directory) of the server.

Warning: On all supported operating systems, the keystore has to be located in the same place for all servers in the domain. Otherwise, WebLogic Server will not locate the keystore.

8. Enter the directory location of the keystore that contains trusted CA certificates in the Root CA Key Store Location attribute.

   This attribute requires both a directory and filename location that is either absolute or relative to root directory (that is, the domain directory) of the server. This step is not required if both private keys and trusted CA certificates are stored in the same keystore.

   Leave the Root CA Key Store Location attribute blank, if you plan to use the -Dweblogic.security.SSL.trustedCAKeyStore command line argument to specify the location of a keystore that contains certificate authorities that the server trusts.

9. Enter the password you specified when you created in the trusted CA keystore in the Private Keystore Pass Phrase attribute.

10. Click Apply to save your changes.

11. Reboot WebLogic Server.

Using a JKS Keystore

If you don't want to use the WebLogic Keystore provider to store trusted CA certificates and private keys, you have the option of specifying a JKS keystore location as a command line argument when starting WebLogic Server.

Use the -Dweblogic.security.SSL.trustedCAKeyStore command line argument to specify the location of a keystore that contains certificate authorities that the server or client trusts. The path value must be an absolute or relative path to the directory from where the server is booted.

Weblogic Server looks for trusted certificate authorities in the following sequence:

• Uses the JKS keystore specified in the -Dweblogic.security.SSL.trustedCAkeystore command-line argument.

• Uses the keystore specified in the Root CA Key Store Location attribute for the WebLogic Keystore provider.

• Uses a trusted CA certificate file from a 6.x config.xml file (if one exists in the domain directory).

• Uses WL_HOME\server\lib\cacerts.

Enabling the SSL Port

This procedure explains how to explicitly enable the use of SSL between an individual server and SSL clients. Internally, WebLogic Server uses SSL to protect communications between the Administration Server, Managed Servers, and the Node Manager, WebLogic Server and the LDAP servers used by the LDAP Authentication providers, WebLogic Server and SSL client code, and communications through the Administration Port.

To enable the SSL port, perform the following steps:

1. Expand the Server node.

2. Select the Connections-->SSL Ports tab and set the following attributes

   • The Enabled attribute enables the use of SSL.

   • The SSL Listen Port attribute is the number of the dedicated port on which WebLogic Server listens for SSL connections. The default is 7002.

3. Click Apply to save your changes.

4. Set attributes for One-way or Two-way SSL. For more information, see Setting Attributes for One-Way SSL or Setting Attributes for Two-Way SSL.

5. Reboot WebLogic Server.

Setting Attributes for One-Way SSL

To define attributes for one-way SSL:

1. Enable the SSL port. For more information, see Enabling the SSL Port.

2. Select the Connections-->SSL tab and set the attributes described in Table 6-3.

   Table 6-3 SSL Attributes

   SSL Attribute	Description
   Server Private Key Alias	The alias specified when loading the private key for WebLogic Server into the keystore. Define this attribute only if you stored the private key for WebLogic Server in a keystore.You must have the WebLogic Keystore provider configured to use this attribute. All private key keystore entries are accessed 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.
   Server Private Key Passphrase	The password specified when loading the private key for WebLogic Server into the keystore. Define this attribute only if you stored the private key for WebLogic Server in a keystore.You must have the WebLogic Keystore provider configured to use this attribute.
   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 need to include the entire chain in PEM format in the certificate file.
   Server Key File Name	The directory location of the private key for WebLogic Server. Specify this attribute only if you stored the private key for WebLogic Server in a file. If you protected the private key file with a password, specify the weblogic.management.pkpassword command-line argument when starting the server.
   Trusted CA File Name	The name of the file containing the PEM-encoded trusted certificate authorities.

   
    

3. Click Apply to save your changes.

4. Reboot WebLogic Server.

Setting Attributes for Two-Way SSL

Two-way SSL requires clients to present a digital certificate to WebLogic Server in order to establish an SSL connection. The client first authenticates the server's digital certificate and then the server authenticates the client's digital certificate.

Before using two-way SSL both the SSL client and server need identity. In addition, the client and server must trust the issuer of each other's certificate.

To define attributes for two-way SSL:

1. Enable SSL.

2. Select the Connections-->SSL tab and set attributes for one-way SSL as described in Step 3 of Setting Attributes for One-Way SSL.

3. Enable one of the following two-way SSL attributes on the SSL tab:

   • Check the Client Certificate Enforced attribute to require a client to present a certificate. If a valid and trusted certificate chain is not presented, the SSL connection is terminated.

   • Check the Client Certificate Requested But Not Enforced attribute to ask for a certificate from the client. If this option is enabled, the connection continues if the client does not present a certificate.

4. Click Apply.

5. Reboot WebLogic Server.

Command-Line Arguments for SSL

To use a private key stored in a file with WebLogic Server, use the following command-line argument:

-Dweblogic.management.pkpassword=pkpassword

where password is the password for the private key.

Note: Using this command-line argument presents a security risk as the password is in clear text.

To specify a trusted CA keystore other than the keystore specified in the Root CA Key Store Location attribute in the WebLogic Keystore provider, use the following command line argument:

-Dweblogic.security.SSL.trustedCAkeystore=path

The path value must be a relative to where the server is booted or qualified name to a JKS keystore file. This command-line argument overrides information specified in the WebLogic Server Administration Console. For information about how WebLogic Server obtains trust, see Using a JKS Keystore.

To control Basic Constraints certificate validation on WebLogic Server, use the following command-line argument:

-Dweblogic.security.SSL.enforceConstraints=option

The default is strong. For more information, see SSL Certificate Validation.

Note: The weblogic.security.SSL.sessionCache.size and weblogic.security.SSL.sessionCache.ttl command-line arguments are not supported in this release of WebLogic Server. For more information, see SSL Session Behavior.

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:

• Trusted certificate authorities

• SSL server configuration information

• Server identity (private key and digital certificate)

• The strength that is allowed by the license in use

• Enabled ciphers

• SSL records that were passed during the SSL handshake

• SSL failures detected by WebLogic Server (for example, trust and validity checks and the default host name verifier)

• 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

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 change in this release of WebLogic Server. 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 WebLogic Server 6.x, there is one SSL session 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.

Using 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, WebLogic Server, as a function of the SSL handshake, 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.

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

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

• In the WebLogic Server Administration Console, check the Hostname Verification Ignored attribute on the SSL tab on the Server node.

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

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.

To use a custom host name verifier:

1. Expand the Server node.

2. Enter the name of the Java class used to load your custom host name verifier in the Hostname Verifier attribute on the SSL tab.

3. Click Apply.

4. Reboot WebLogic Server.

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.

Configuring 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 host name verification and the Administration port must be taken into consideration. This section describes two scenarios: using the demonstration identity and trust provided by WebLogic Server and using production-quality identity and trust.

For more information, see:

SSL Requirements for Administration Servers

SSL Requirements for Managed Servers

SSL Requirements for the Node Manager

Identity and Trust: Demonstration Versus Production

Host Name Verification Requirements

Node Manager SSL Production Configuration: Main Steps

Configuring the Administration Server to Use SSL

Configuring a Managed Server to Use SSL

Configuring the Node Manager to Use SSL

Note: Although WebLogic Server offers different techniques for storing and specifying identity and trust, this section describes the recommended use case.

SSL Requirements for Administration Servers

To use SSL, Administration Servers require:

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

  The digital certificate for the Administration Server must be stored in a file. Digital certificates must also specify a host name rather than an IP address. The location of the digitial certificate is specified in the WebLogic Server Administration Console.

  By default, the demonstration digital certificate and private key available in the WLS Domain template are copied to a domain by the Configuration Wizard when the domain is created. The Administration Server uses this digital certificate and private key for identity. However, the demonstration digital certificate and private key should not be used in production.

• Trust—Administration Servers can use trusted CA certificates stored in a JKS keystore. The JKS keystore is specified by the -Dweblogic.security.SSL.trustedCAkeystore command-line argument in the start script for the Administration Server.

Note: By default, the start script for the Administration Server specifies trust through the -Dweblogic.security.SSL.trustedCAkeystore command-line argument so any trust settings specified through the WebLogic Server Administration Server are ignored.

By default, the Administration Server trusts all the certificate authorities in the cacerts files in the WL_HOME\server\lib.

In a production environment, 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).

• SSL port—By default, the SSL port is enabled on the Administration Server.

• Host name verification—By default, host name verification is not enabled on Administration Servers. Host name verification is only necessary in a production environment.

  Host name verification is specified by the -Dweblogic.security.SSL.ignoreHostnameVerification command-line argument in the start script for the Administration Server

• 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. If you use the Administration port, the Administration Server and all Managed Servers must be configured to use the Administration port. Managed Servers that are not configured to use the Administration port will be unable to connect to the Administration Server during start.

SSL Requirements for Managed Servers

To use SSL, Managed Servers require:

• Identity—Managed Servers use private keys stored in keystores accessed through the WebLogic Keystore provider.

  The digital certificate for the Administration Server must be stored in a file. Digital certificates must also specify a host name rather than an IP address. The location of the digital certificate is specified in the WebLogic Server Administration Console.

  By default, Managed Servers do not have any configured identity. The demonstration digital certificate and private key provided by the Configuration Wizard can be used for identity for Managed Servers. However, this digital certificate and private key should not be used in a production environment.

• Trust—Managed Servers use trusted CA certificates stored in a JKS keystore. The JKS keystore is specified by the weblogic.security.SSL.trustedCAkeystore command-line argument in the remote start arguments for the Managed Server.

  By default, Managed Servers trusts all the certificate authorities in the cacerts files in the WL_HOME\server\lib.

  In a production environment, 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 not enabled on Managed Servers. Host name verification is only necessary in a production environment.

  Host name verification is specified by the -Dweblogic.security.SSL.ignoreHostnameVerification command-line argument in the remote start arguments for the Managed Server

• 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. If you use the Administration port, the Administration Server and all Managed Servers must be configured to use the Administration port. Managed Servers that are not configured to use the Administration port will be unable to connect to the Administration Server during start.

SSL Requirements for the Node Manager

Note: BEA recommends not running the Node Manager as a NT service when using SSL.

To use SSL, the Node Manager requires:

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

  weblogic.nodemanager.keyFile=filename

  weblogic.nodemanager.keyPassword=password_for_the_private_key

  weblogic.nodemanager.certificateFile=filename

  By default, the WebLogic Server installer copies a demonstration digital certificate and private key to the WL_HOME\common\nodemanager\config directory. However, this digital certificate and private key should not be used in a production environment.

• Trust—The Node Manager uses trusted CA certificates stored in a JKS keystore for trust. The trust keystore is specified in the start script for the Node Manager by the following command-line argument:

  weblogic.security.SSL.trustedCAkeystore=keystorename

  Because 2-way SSL is used, 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).

  By default, the Node Manager trusts all the certificate authorities in the cacerts files in the WL_HOME\server\lib.

• Host name verification—By default, host name verification is not enabled on the Node Manager. Host name verification is only necessary in a production environment. Host name verification is enabled in the start script for the Node Manager by the following command-line argument:

  weblogic.security.SSL.ignoreHostnameVerification=false

• 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 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, enable Reverse DNS on the Node Manager.

Warning: Using host names may make the WebLogic Server deployment vulnerable to man-in-the-middle attacks.

For more information, see Set Up the Node Manager Hosts File.

Identity and Trust: Demonstration Versus Production

WebLogic Server provides demonstration identity (private keys and digital certificates) and trust (trusted certificate authorities) that can be used by Administration and Managed Servers and the Node Manager

• When the Configuration Wizard creates a domain, the wizard copies the demonstration trust and identity in the WLS Domain template into the domain for use by the Administration Server. These demonstration private keys and digital certificates are suitable for testing or demonstration purposes, however, they should not be used in a production environment.

• Managed servers do not have identity and trust configured by default. However, they can also use the identity and trust provided by the Configuration wizard.

• The installer provides demonstration private keys and digital certificates for the Node Manager. These demonstration private keys and digital certificates are suitable for testing or demonstration purposes, however, they should not be used in a production environment.

In a production environment, 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. For more information, see Obtaining Private Keys, Digital Certificates and Trusted Certificate Authorities.

Host Name Verification Requirements

Running with host name verification disabled is fine in a demonstration environment. However, when moving to a production environment, BEA recommends using host name verification to ensure the host you are connecting to is the intended host. To use 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.

• Host name verification is enabled on the Node Manager, the Administration Server, and any Managed Servers.

Node Manager SSL Demonstration Configuration: Main Steps

Using the demonstration identity and trust provided by WebLogic Server to configure SSL for the Node Manager involves verifying the default settings for the SSL attributes and ensuring that the Administration Server and any Managed Servers are listening for SSL communications on different ports. Because the default settings are used with demonstration identity and trust, detailed configuration instructions are not included.

Figure 6-1 illustrates the SSL demonstration configuration.

Figure 6-1 SSL Demonstration Configuration for the Node Manager

To configure the Node Manager to use SSL and the demonstration identity and trust:

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

   1. Select the Admin Server with Managed Server(s) option.

   2. Add new Managed Server(s) to the domain. Specify a Listen port for the Managed Server that is different than the listen port of the Administration Server. Set the Listen Address of the Managed Server to localhost.

   For more information, see Creating and Configuring WebLogic Server Domains.

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

3. Create a machine for the Managed Server. Set the Listen Address to localhost. Add the Managed Server to the machine. For more information, see Configuring a Machine.

4. Verify that SSL is enabled for the Administration Server. Because the Administration port is not enabled, SSL must be enabled. Otherwise, the Administration Server will not be able to communicate with the Node Manager.

   On the Connections-->SSL Ports tab, verify the Enabled attribute is checked. For more information, see Enabling the SSL Port.

5. On the Connections-->SSL tab, verify the settings of the following SSL attributes for the Administration Server:

   • Server Key File Name—demokey.pem

   • Server Certificate File Name—democert.pem

   • Host Name Verification—off

   For more information, see Setting Attributes for One-Way SSL.

6. In the start script for the Administration Server, verify that trust is set as WL_HOME\server\lib\cacerts.

7. Verify SSL is enabled for the Managed Server. Ensure the SSL port specified is different than the SSL port used by the Administration Server.

   On the Connections-->SSL Ports tab, verify the Enabled attribute is checked. For more information, see Enabling the SSL Port.

8. On the Connections-->SSL tab, set the SSL attributes for the Managed Server as follows:

   • Server Key File Name—full path name to the demonstration private key (.../demokey.pem) for the domain in which the Managed Server runs.

   • Server Certificate File Name—full path name to the demonstration digital certificate (.../democert.pem) for the domain in which the Managed Server runs.

   • Host Name Verification—off

   For more information, see Setting Attributes for One-Way SSL.

9. Configure start command-line arguments for the Managed Server on the Servers-->Configuration-->Remote Start tab:

   • Username (Required)—Enter the name of a user with privileges to start this Managed Server (for example, weblogic).

   • Password (Required)—Click change... to change the password used to start the server (for example, weblogic). Type the new password in the New Password and Retype to confirm text boxes, then click Apply to apply the change.

10. Stop the Administration Server.

11. Start the Administration Server.

Node Manager SSL Production Configuration: Main Steps

Figure 6-2 illustrates the SSL production configuration.

Figure 6-2 SSL Production Configuration for the Node Manager

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 digital certificate matches the URL).

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

3. Start the Administration Server.

4. Configure an Administration port for the WebLogic domain.

5. Create a machine for any Managed Servers. Set the Listen Address to the host name of the machine on which the Managed Server runs. Add the Managed Server to the machine. For more information, see Configuring a Machine.

6. Turn off SSL for the Administration Server. Because the Administration port is enabled, the Node Manager uses this port for all Administration traffic. The Administration port uses SSL to protect all communications therefore you do not need to have an SSL port enabled. Only leave the SSL port enabled if you want to run application traffic over the SSL port.

7. Configure identity for the Administration Server.

8. Turn on host name verification for the Administration Server.

9. Specify the trusted certificate authority for the Administration Server.

10. Enable the Administration port for any Managed Servers.

11. Turn off SSL for the Managed Server.

12. Use remote start arguments to configure identity, trust, and enable host name verification for any Managed Servers.

13. Edit the nodemanager.hosts file for the Node Manager. Enter the names of the machines on which the Administration Servers that will be communicating with the Node Manager run. If you want to specify machines by host name rather than by IP address, enable Reverse DNS.

14. Edit the start script for the Node Manager. Specify the location of identity and trust for the Node Manager and enable host name verification.

15. Start the Node Manager.

16. Stop the Administration Server.

17. Start the Administration Server.

Configuring the Administration Server to Use SSL

By default, identity and trust for the Administration Server are configured using demonstration digital certificates and private keys provided by the Configuration Wizard. In addition, SSL is configured by default. For more information, see Node Manager SSL Demonstration Configuration: Main Steps. This section describes using the Administration port and production quality identity and trust to configure an Administration Server to use SSL.

To configure the Administration Server to use SSL:

1. Obtain identity and trust for the Administration Server. Ensure the digital certificate for the Administration Server includes a host name.

   For more information, see Obtaining Private Keys, Digital Certificates and Trusted Certificate Authorities.

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

   1. Select the Admin Server with Managed Server(s) option.

   2. Add Managed Server(s) to the domain. Specify a Listen port for the Managed Server that is different than the listen port of the Administration Server. Set the Listen Address of the Managed Server to the hostname of the machine on which the Managed Server runs.

   For more information, see Creating and Configuring WebLogic Server Domains.

3. Start the Administration Server.

4. Enable the Administration port for the WebLogic Server domain. For more information, see Configuring a Domain-Wide Administration Port.

5. Turn off SSL by unchecking the Enabled attribute on the Connections-->SSL Ports tab in the WebLogic Server Administration Console.

6. Specify the location of the digital certificate in the Server Certificate File Name attribute on the SSL attributes on the Connections-->SSL tab in the WebLogic Server Administration Console.

7. Create a JKS keystore and store the private key for the Administration Server in the keystore For more information, see Common Keytool Commands.

8. Configure the WebLogic Keystore provider to access the JKS keystore. For more information, see Configuring the WebLogic Server Keystore Provider to Locate a Keystore.

9. Create a JKS keystore for the certificate authorities trusted by the Administration Server. Load the trusted CA certificates in the JKS keystore. For more information, see Common Keytool Commands.

10. Edit the start script for the Administration Server:

    • Use the -Dweblogic.security.SSL.trustedCAkeystore=path_to_keystore command-line argument to specify the location of the JKS keystore that contains the trusted certificate authorities for the Administration Server.

    • Use the -weblogic.security.SSL.ignoreHostnameVerification=false command-line argument to enable host name verification

11. Configure any Managed Servers. See Configuring a Managed Server to Use SSL.

12. Configure the Node Manager. See Configuring the Node Manager to Use SSL.

13. Start the Node Manager.

14. Stop the Administration Server.

15. Start the Administration Server.

Configuring a Managed Server to Use SSL

By default, no identity is configured for a Managed Server. The demonstration private key and digital certificate provided by the Configuration Wizard can be used to establish identity for a Managed Server, however, this private key and digital certificate should not be used in a production environment. In addition, a Managed Server trusts all the certificate authorities in the cacerts files in the WL_HOME\server\lib directory by default. For more information, see Node Manager SSL Demonstration Configuration: Main Steps.

This section describes using the Administration port and production quality identity and trust to configure a Managed Server to use SSL.

To configure a Managed Server to use SSL:

1. Obtain identity and trust for the Managed Server. Ensure the digital certificate for the Managed Server includes a host name.

2. Configure the Administration Server in the domain to use SSL. For more information, see Configuring the Administration Server to Use SSL.

3. Configure the Administration port on the Managed Server. Specify an Administration port other than the Administration port used by the Administration Server. If the Administration Server runs on the same machine as the Managed Server, set the Local Port Override attribute on the SSL tab to override the Administration Port number.

   Since you enabled the Administration port, you must specify trust and host name verification through command-line arguments on the Remote Start tab for the Managed Server.

4. Specify the location of the digital certificate in the Server Certificate File Name attribute on the SSL attributes on the Connections-->SSL tab in the WebLogic Server Administration Console.

5. Create a JKS keystore and store the private key for the Managed Server in the keystore For more information, see Common Keytool Commands.

6. Configure the WebLogic Keystore provider to access the JKS keystore. For more information, see Configuring the WebLogic Server Keystore Provider to Locate a Keystore.

7. Create a JKS keystore for the certificate authorities trusted by the Managed Server. Load the trusted CA certificates in the JKS keystore. For more information, see Common Keytool Commands.

8. Configure start command-line arguments for Managed Servers on the Servers-->Configuration-->Remote Start tab:

   • Username (Required)—Enter the name of a user with privileges to start this Managed Server (for example, weblogic).

   • Password (Required)—Click change... to change the password used to start the server (for example, weblogic). Type the new password in the New Password and Retype to confirm text boxes, then click Apply to apply the change.

   • Trust—Use the weblogic.security.SSL.trustedCAKeyStore command-line argument to specify the keystore that contains the certificate authorities trusted by the Managed Server. Use the full path name to the keystore.

   • Host Name Verification—Specify the -Dweblogic.security.SSL.ignoreHostnameVerification=false command-line argument to enable host name verification.

9. Configure the Node Manager. See Configuring the Node Manager to Use SSL.

10. Start the Node Manager.

11. Stop the Administration Server.

12. Start the Administration Server.

Configuring the Node Manager to Use SSL

To configure the Node Manager to use SSL:

1. Configure the Administration Server in the domain to use SSL. For more information, see Configuring the Administration Server to Use SSL.

2. Configure any Managed Servers in the domain to use SSL. For more information, see Configuring a Managed Server to Use SSL.

3. Obtain identity and trust for the Node Manager. For more information, see Obtaining Private Keys, Digital Certificates and Trusted Certificate Authorities.

   The Node Manager can only use private keys and digital certificates stored in files.

4. Create a JKS keystore and load the trusted certificate authorities into the keystore. For more information, see Common Keytool Commands.

   Because 2-way SSL is used, the Node Manager must also trust the certificate authorities used by the Administration Server and any Managed Servers.

5. There is one Node Manager per machine, however, domains managed by the Node Manager can have multiple machines. Steps 4 and 5 must be performed on every machine in the domain managed by the Node Manager.

6. Edit the start script of the Node Manager.

   The start script is located in the WL_HOME\server\bin directory. The standard Node Manager start script is named startNodeManager.cmd on Windows systems and startNodeManager.sh on UNIX systems.

   Use the following command-line arguments to specify identity and trust:

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

   • Use weblogic.security.SSL.ignoreHostnameVerification=false to enable the use of host name verification.

   • Use weblogic.nodemanager.trustedHosts=pathtofile to specify the nodemanager.hosts file for the Node Manager.

   • Set the ListenAddress property to the host name of the machine on which the Managed Server runs.

   • Set the ReverseDNSEnabled property to use the host name of an Administration Server rather than an IP address.

7. Edit the nodemanager.hosts file located in WL_HOME\common\nodemanager\config to include all the Administration Servers on this machine trusted by the Node Manager. The Administration Servers are specified by IP address or host name if Reverse DNS is used.

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

8. Start the Node Manager.

9. Stop the Administration Server.

10. Start the Administration Server.

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 won't 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 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 WebLogic Server:

-Dweblogic.security.SSL.enforceConstraints=option

Table 6-4 describes the options for the command-line argument.

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:

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

• Turn on SSL debug tracing on the processes using SSL communication. The syntax for SSL debug tracing is:

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

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 a download from JDK 1.3. 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. The default JCE provider (SunJCE) provider in the JDK 1.3 has not been tested with this version of WebLogic Server.

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. Hardware accelerators 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 nCipher JCE provider. For more information about the nCipher JCE provider, see http://www.ncipher.com/solutions/webservers.html.

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\lib\ext

     For example:

     WL_HOME\jdk131\jre\lib\ext

     UNIX

     JAVA_HOME/lib/ext

     For example:

     WL_HOME/jdk131/jre/libext

   • In the CLASSPATH of the server.

3. Edit the security properties file (java.security) to add the nCipher JCE provider to the list of approved JCE providers for WebLogic Server. The security properties file is located in:

   Windows NT

   JAVA_HOME\lib\security\java.security

   UNIX

   JAVA_HOME/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

   Note: The JCE providers must be specified in this order to ensure the nCipher JCE providers works properly.

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 uses the SSL V3.0 protocol. 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.

When WebLogic Server acts as a client, the SSL handshake starts with an SSL V2.0 hello from WebLogic Server. The peer must respond with an SSL V3.0 or TLS V1.0 message or the SSL connection is dropped. This behavior is the default.

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:

• -Dweblogic.security.SSL.protocolVersion=SSL3—Only SSL V3.0 messages are sent and accepted.

• -Dweblogic.security.SSL.protocolVersion=TLS1—Only TLS V1.0 messages are sent and accepted.

• -Dweblogic.security.SSL.protocolVersion=ALL—This is the default behavior.

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 will use 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 SSL 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 Server node.

2. Select the server that will be acting as the SSL server.

3. Select the Connections-->SSL tab.

4. Ensure the Check the Client Certificate Enforced attribute is unchecked.

5. Click Apply.

6. 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 digital 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. However, you have the option of specifying a different trust keystore. Use the following command-line argument to specify a trust keystore other than the JDK trust keystore:

-Dweblogic.security.SSL.trustedCAkeystore=pathtokeystore

where pathtokeystore is the keystore file that contains trusted CA certificates.

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.

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.

Using the SSL Protocol with a BEA Tuxedo Client and WebLogic Server

The SSL protocol can be used to protect communication between a BEA Tuxedo client and WebLogic Server. This section details the steps required to enable the use of the SSL protocol, using the client in the following code example:

BEA_HOME/sample/examples/iiop/ejb/stateless/tuxclient

To use the SSL protocol and one-way authentication between WebLogic Server and BEA Tuxedo clients:

1. Configure WebLogic Server to use one-way SSL. For more information, see Setting Attributes for One-Way SSL.

2. In the Server Certificate File Name attribute in the config.xml file for WebLogic Server, specify the name of the file that contains the certificates for WebLogic Server. The order of the certificates in this file is important: the digital certificate for the server must be specified first, followed by the certificate of the certificate authority that issued WebLogic Server's certificate, followed by the issuer of the certificate authority's certificate.

3. Reboot WebLogic Server.

4. Obtain an SSL license for the BEA Tuxedo client.

5. Load the certificate for WebLogic Server trusted certificate authority into the BEA Tuxedo Trusted Certificate Authority file ($TUXDIR/udataobj/security/certs/trust_ca.cer).

   Note: The certificates in this file must be in PEM format.

6. Reboot WebLogic Server.

7. Start the BEA Tuxedo client specifying command-line options that:

   • Enable the use of the SSL protocol.

   • Specify the secure port on which SSL network connections will be accepted.

   • Disable peer validation, if the network address at which WebLogic Server is running is not the same as that specified by the domain name in the server's digital certificate.

   For example:

   ./Client.exe -ORBid BEA_IIOP -ORBpeerValidate warn\ -ORBInitRef NameService=corbalocs:iiop:localhost:7002
   /NameService