Configuring the SSL Protocol

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

• SSL Protocol: Introduction
• Private Keys, Digital Certificates and Trusted Certificate Authorities
• One-Way and Two-Way SSL
• Setting Up the SSL Protocol: Main Steps
• Obtaining Private Keys, Digital Certificates and Trusted CAs
• Storing Private Keys, Digital Certificates, and Trusted CAs
• Enabling the SSL Protocol
• Setting Attributes for One-Way SSL
• Setting Attributes for Two-Way SSL
• Command-Line Arguments for the SSL Protocol
• SSL Session Behavior
• Using the SSL Protocol in a Cluster
• Using a Hostname Verifier
• Configuring RMI over IIOP with SSL

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

Configuring the SSL protocol is an optional step, however, BEA recommends using the SSL protocol in production.

 

---

SSL Protocol: Introduction

The Secure Sockets Layer (SSL) protocol 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.

The SSL protocol in WebLogic Server 7.0 implements the SSL 3.0 and TLS 1.0 specifications.

Note: The proxy plug-ins in WebLogic Server 7.0 only support SSL 3.0.

WebLogic Server supports the SSL protocol 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 the SSL protocol is computationally intensive and adds overhead to a connection. You should avoid using the SSL protocol when it is not necessary. However, you should always use the SSL protocol in a production environment.

 

---

Private Keys, Digital Certificates and Trusted Certificate Authorities

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

The SSL protocol 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. The private key is carefully protected so that only the owner can decrypt messages.

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.

The data embedded in a digital certificate is verified by a certificate authority (also referred to as trusted CA) and digitally signed with the certificate authority's digital certificate. Well-know certificate authorities include Verisign and Entrust.net.

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 CA and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the digital certificate of the CA used to sign it expired. A server certificate can be invalidated in the URL of the server that presented the certificate does not match the URL embedded in the certificate.

 

---

One-Way and Two-Way SSL

The SSL protocol 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 certificates issued by any of up to four trusted certificate authorities before completing the SSL connection.

 

---

Setting Up the SSL Protocol: Main Steps

To set up the SSL protocol:

1. Obtain a private key, digital certificate, and trusted CA for WebLogic Server. Use the demonstration digital certificates, private keys, and trusted CAs provided in the WebLogic Server kit, the Cert Gen utility, the Certificate Request Generator servlet, or Sun Microsystem's keytool utility to perform this step.
2. Store the private keys, digital certificates, and trusted CAs. Digital certificates are always stored in file in the domain directory of WebLogic Server. Private keys and trusted CAs can either be stored in the WebLogic Keystore provider or in a file in the domain directory.
3. Enable the SSL protocol. By default, the SSL protocol is not enabled because of the performance impact of its use.
4. Set SSL attributes in the Administration Console. The SSL attributes define the location of the private key, digital certificate, and trusted CAs. 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 CAs

Storing Private Keys, Digital Certificates, and Trusted CAs

Enabling the SSL Protocol

Setting Attributes for One-Way SSL

Setting Attributes for Two-Way SSL

 

---

Obtaining Private Keys, Digital Certificates and Trusted CAs

To use the SSL protocol, you need a private key, a digital certificate containing the matching public key, and at least one trusted CA that can verify the data embedded in the digital certificate. WebLogic Server supports private keys, digital certificates, and trusted CAs from the following sources:

• The demonstration digital certificates, private keys, and trusted CAs in the \weblogic700\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 digital certificate file contains the name of the local host and the private key file is time-stamped by the build. The demonstration digital certificates, private keys, and trusted CAs 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. 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 CA (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. The file extension determines the format of the digital certificate file.

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

----BEGIN CERTIFICATE----

and ends with this line:

----END CERTIFICATE----

A .der format file contains binary data. WebLogic Server requires that the file extension match the contents of the digital certificate, so be sure to save the file you receive from the trusted CA with the correct file extension.

Private keys 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 (CertGenCA). The digital certificates generate by the Cert Gen utility have the hostname of the machine on which they were generated as the common name, so you must generate a digital certificate for every machine on which you wish to use the SSL protocol.

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]

   where

   • password is the password for the private key.
   • certfile is the name of the digital certificate file. The file is put in the domain directory.
   • keyfile is the name of the generated private key file. The file is put in the domain directory.

   By default, the CertGen tool generates domestic strength certificates. Specify the [export] option if you want the tool to generate export strength certificates.

The CertGen tool uses the JDK version 1.3 InetAddress.getLocalHost().getHostname() method to get the hostname it puts in the common name field of a certificate. 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 common name field in the certificate. Otherwise, your connection fails because the hostnames 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 hostname. 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 hostname.

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).
2. In a Web browser, enter the URL for the Certificate Request Generator servlet as follows:

   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.

   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 5-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 if you want to use a protected key with WebLogic Server. If you choose to use a protected key, you are prompted for the password whenever the key is used. If you specify a password, you get a PKCS-8 encrypted private key. BEA recommends using a password to protect private keys.
   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-, 768-, or 1024-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 startup directory of your WebLogic Server:

   • www__com-key.der—The private key file.
   • www__com-request.dem—The certificate request file, in binary format.
   • www__com-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.

   When you are instructed to select a server type, choose BEA WebLogic Server to ensure that you receive a digital certificate that is compatible with WebLogic Server.

Converting a Microsoft p7b Format to PEM Format

Microsoft can also be 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 tp 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.

 

---

Storing Private Keys, Digital Certificates, and Trusted CAs

Once you have obtained private keys, digital certificates, and trusted CAs, you need to store them so that WebLogic Server can use them to verify identity. Digital certificates can only be stored in a file in the domain directory. Private keys and trusted CAs can either be stored in a file in the domain directory or in a keystore.

• If you store the private keys, digital certificates, and trusted CAs in files in the domain directory, you need to set the SSL Server Key File Name, Server Certificate File Name, and Trusted CA File Name attributes in the Administration Console. For information about setting SSL attributes, see Setting Attributes for One-Way SSL.
• If you store the private keys and trusted CAs in a keystore, you need to create a keystore and load the private keys and trusted CAs into the keystore, configure the WebLogic Keystore provider to point to the keystore, and set the SSL Server Private Key Alias, Server Private Key Passphrase, Server Certificate File Name, and Trusted CA File Name in the Administration Console.

For more information, see:

• Creating a Keystore and Loading Private Keys and Trusted CAs 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 CAs into the Keystore

A keystore is a mechanism designed to create and manage files that store private keys and trusted CAs. The WebLogic Keystore provider locates instances of keystores. Use the following utilities to create a keystore and load private keys and trusted CAs into the keystore:

• The WebLogic ImportPrivateKey utility. For more information, see utils.ImportPrivateKey.
• Sun Microsystem's keytool utility. For more information, see keytool—Key and Certificate Management Tool.

Note: The keytool utility requires a digital certificate to be presented 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 CAs into a keystore, the utility does not allow you to take an existing private key from a file and import it into the keystore.

Either create one keystore for both private keys and trusted CAs or two keystores: one for private keys and one for trusted CAs. BEA recommends creating two keystores.

By default, WebLogic Server looks for a private key keystore named wlDefaultKeyStore.jks in the domain directory. The keystore for trusted CAs can use either the demonstration trusted CA (weblogic700/server/lib/cacerts) or a trusted CA available from the JDK (.../jre/lib/security/cacerts).

Note: The weblogic700/server/lib/cacerts file should be used for demonstration or testing purposes and not in a production environment.

All keystore entries (private key and trusted CAs) are accessed via unique aliases. You specify the alias when loading the private key or trusted CA 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 the SSL protocol.

Configuring the WebLogic Server Keystore Provider to Locate a Keystore

Note: The WebLogic Keystore provider is deprecated in WebLogic Server 7.0 SP01.

The WebLogic Keystore provider has been enhanced in the following ways:

• You can specify a type of keystore. In WebLogic Server 7.0, only Java 2 Enterprise Edition keystores (JKS) were supported.
• You can protect each private key with an individual password. This password provides an additional level of security not available when storing private keys and trusted CAs 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.

To configure the WebLogic Keystore provider, you need to create a keystore and set attributes in the 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 CAs into the Keystore.
2. In the 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 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 the root directory of the server.

8. Enter the password you specified when you created in the keystore in the Private Keystore Pass Phrase attribute.
9. Enter the directory location of the keystore that contains trusted CAs in the Root CA Key Store Location attribute.

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

10. Enter the password you specified when you created in the trusted CA keystore in the Private Keystore Pass Phrase attribute.
11. Enter the type of keystore you are using in the Type attribute. The valid types are defined in JavaSoft Cryptography Architecture specification. Set this attribute to null or an empty string to use the default keystoretype configured in the java.security file.
12. Click Apply to save your changes.
13. Reboot WebLogic Server.

Note: If you don't want to use the WebLogic Keystore provider to store trusted CAs, you have the option of specifying another 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 a relative or qualified name to a Sun JKS keystore file. If you do not specify this argument, WebLogic Server trusts all of CA stored in JAVA_HOME\jre\lib\security\cacerts.

For more information, see the weblogic.Admin Command-Line Reference.

Weblogic Server looks for trusted CAs 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. For more information, see Configuring a WebLogic Role Mapping Provider.
• Uses a trusted CA file from a 6.x config.xml file (if one exists in the domain directory).
• Uses WL_HOME\weblogic700\server\lib\cacerts.

 

---

Enabling the SSL Protocol

To enable the SSL protocol, perform the following steps:

1. Expand the Server node.
2. Click the Configure New Server... link.
3. Select the Connections-->SSL Ports tab and set the following attributes
   • The Enabled attribute enables the use of the SSL protocol.
   • The SSL Listen Port attribute is the number of the dedicated port on which WebLogic Server listens for SSL connections. The default is 7002.
4. Click Apply to save your changes.
5. 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.
6. Reboot WebLogic Server.

 

---

Setting Attributes for One-Way SSL

To define attributes for one-way SSL:

1. Enable the SSL protocol. For more information, see Enabling the SSL Protocol.
2. Select the Connections-->SSL tab and set the attributes described in Table 5-2.

   Table 5-2 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 keystore entries (private key and trusted CAs) are accessed via unique aliases. You specify the alias when loading the private key or trusted CA 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.
   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.
   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.

To define attributes for two-way SSL:

1. Enable the SSL protocol.
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 certificate 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 the SSL Protocol

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.

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 or qualified name to a Sun JKS keystore file. If you do not specify this argument, the server or client trusts all of the CA certificates that are in shipped in the JDK (JAVA_HOME\jre\lib\security\cacerts).

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

 

---

SSL Session Behavior

WebLogic Server allows SSL sessions to be cached. Those sessions live for the life of the server.

not change this behavior in WebLogic Server 7.0. The weblogic.security.SSL.sessionCache.size and weblogic.security.SSL.sessionCache.ttl command-line arguments are ignored.

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 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 WebLogic Server 7.0, 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 the SSL Protocol in a Cluster

When using the SSL protocol in a cluster, perform the following steps:

1. For each machine in the cluster, create a new domain using the Configuration Wizard. For more information, see Creating Domains and Servers.

   This domain must have the same name on all the machines in the cluster.

2. Obtain a private key and digital certificate for each machine in the cluster. For more information, see Obtaining Private Keys, Digital Certificates and Trusted CAs.
3. On each Managed server in the cluster, store the digital certificate for each machine in the cluster in the following locations:
   • WL_HOME/NodeManagerHome/
   • The directory specified by the -Dweblogic.RootDirectory=path command-line argument

   Note: You must use the same directory location and filenames for the digital certificate for each machine in the cluster.

4. Store the private key in a keystore that can be accessed by the WebLogic Keystore provider. For more information, see Storing Private Keys, Digital Certificates, and Trusted CAs

Note: If you choose to store the private keys in a keystore, you must use the same directory location and filenames for the keystore and the private key on each machine in the cluster.

5. On each Managed server in the cluster, you need to copy the keystore into the following locations:
   • WL_HOME/NodeManagerHome/
   • The directory specified by the -Dweblogic.RootDirectory=path command-line argument
6. Configure the WebLogic Keystore provider for the domain. For more information, see Configuring the WebLogic Server Keystore Provider to Locate a Keystore. In the Private Key Store Location attribute, specify the name and directory location of the keystore you created.
7. Enable the SSL protocol. For more information, see Enabling the SSL Protocol.
8. Set the Server Private Key Alias, Server Private Key Passphrase, and Server Certificate File Name attributes on the SSL tab. For more information, see Setting Attributes for One-Way SSL.
9. Reboot WebLogic Server.

 

---

Using a Hostname Verifier

A Hostname Verifier ensures the host to which an SSL connection is made is the intended or authorized party. A Hostname Verifier is useful when WebLogic Server or a WebLogic client is acting as an SSL client to another application server. It prevents 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 actually 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.

Turn off host name verification in the following ways:

• In the Administration Console, check the Hostname Verification Ignored attribute under the SSL tab on the Server node.
• On the command line of the SSL client, enter the following argument:

-Dweblogic.security.SSL.ignoreHostnameVerification=true

You can also write a custom Hostname Verifier. For more information, see Programming WebLogic Security. If you write a custom Hostname Verifier, the name of the class that implements the Hostname Verifier must be specified in the CLASSPATH of WebLogic Server.

To use a custom Hostname Verifier:

1. Expand the Server node.
2. Click the Configure New Server... link.
3. Click the Connections-->SSL Ports tab and ensure the SSL protocol is enabled.
4. Enter the name of the Java class used to load your custom Hostname Verifier in the Hostname Verifier attribute on the SSL tab.
5. Click Apply to save your changes.
6. Reboot WebLogic Server.

 

---

Configuring RMI over IIOP with SSL

Use the SSL protocol to protect IIOP connections to RMI remote objects. The SSL protocol secures connections through authentication and encrypts the data exchanged between objects.

To use the SSL protocol to protect RMI over IIOP connections, do the following:

1. Configure WebLogic Server to use the SSL protocol.
2. Configure the client Object Request Broker (ORB) to use the SSL protocol. Refer to the product documentation for your client ORB for information about configuring the SSL protocol.
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.