Skip navigation.
Downloads | Product Documentation | Support

Managing WebLogic Security

# Configuring SSL

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

- SSL: An Introduction
- Private Keys, Digital Certificates, and Trusted Certificate Authorities
- One-Way and Two-Way SSL
- Setting Up SSL: Main Steps
- Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities
- Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities
- How WebLogic Server Locates Trust
- Configuring Keystores
- Configuring SSL
- Configuring Two-Way SSL
- Disabling the SSL Port
- Using Host Name Verification
- Enabling SSL Debugging
- SSL Session Behavior
- Configuring RMI over IIOP with SSL
- SSL Certificate Validation
- Using the nCipher JCE Provider with WebLogic Server
- Specifying the Version of the SSL Protocol
- Using the SSL Protocol to Connect to WebLogic Server from weblogic.Admin

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

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

# SSL: An Introduction

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

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

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

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

# Private Keys, Digital Certificates, and Trusted Certificate Authorities

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

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

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

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

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

# One-Way and Two-Way SSL

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

- 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. Often, clients will also use SSL to log on so that the server can authenticate them.
- With two-way SSL (SSL with client authentication), the server presents a certificate to the client and the client 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 an identity (private key and digital certificates) and trust (certificates of trusted certificate authorities) for WebLogic Server. Use the digital certificates, private keys, and trusted CA certificates provided by the WebLogic Server kit, the Cert Gen utility, Sun Microsystem's `keytool` utility, or a reputable vendor such as Entrust or Verisign to perform this step.
2. Store the private keys, digital certificates, and trusted CA certificates. Private keys and trusted CA certificates are stored in a keystore.

Note: This release of WebLogic Server supports private keys and trusted CA certificates stored in files, or in the WebLogic Keystore provider for the purpose of backward compatibility only.

3. Configure the Identity and Trust keystores for WebLogic Server in the WebLogic Server Administration Console.
4. Set SSL attributes for the private key alias and password in the WebLogic Server Administration Console. Optionally, set attributes that require the presentation of client certificates (for two-way SSL).

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
- Configuring Keystores
- Configuring SSL
- Configuring Two-Way SSL

# Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities

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

- The demonstration digital certificates, private keys, and trusted CA certificates in the `WL_HOME\``server\lib` directory.

The demonstration digital certificates, private keys, and trusted CA certificates should be used in a development environment only.

- Sun Microsystem's `keytool` utility can also be used to generate a private key, a self-signed digital certificate for WebLogic Server, and a Certificate Signing Request (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. Use the keytool utility to obtain trust and identity when using WebLogic Server in a production environment. For more information about Sun's `keytoo`l utility, see keytool—Key and Certificate Management Tool.

Note: WebLogic Server does not support the use of the Digital Signature Algorithm (DSA). When using the keytool utility, the default key pair generation algorithm is DSA. Specify another key pair generation and signature algorithm when using WebLogic Server.

- The Cert Gen utility generates digital certificates and private keys that should be used only 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. (The demonstration digital certificate provided by WebLogic Server uses the machine's default host name as the host name.) For more information about using the Cert Gen utility to obtain private keys and digital certificates, see Using the Cert Gen Utility.

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

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

A`.pem` format file begins with this line:

`----BEGIN CERTIFICATE----`

and ends with this line:

`----END CERTIFICATE----`

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

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

Microsoft is often used as a certificate authority. Microsoft issues trusted CA certificates in p7b format. The trusted CA certificates must be converted to PEM before they can be used with WebLogic Server. For more information, see Converting a Microsoft p7b Format to PEM Format.

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

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

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

## Using the Cert Gen Utility

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

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

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

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

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

1. To generate a certificate, enter the following command at a command prompt:

>     $ java utils.CertGen

>     [-cacert <ca_cert_file-name>] [-cakey <ca_key_filename>]
>     [-cakeypass <ca_key_password>] [-selfsigned]
>     [-certfile <certfile>] [-keyfile <privatekeyfile>]
>     [-keyfilepass <keyfilepassword>] [-strength <keystrength>]
>     [-cn <commonname>] [-ou <orgunit>] [-o <organization>]
>     [-l <locality>] [-s <state>] [-c <countrycode>]
>     [-subjectkeyid <subjectkeyidentifier>]
>     [-subjectkeyidformat UTF-8|BASE64]

Argument | Definition
--- | ---
`ca_cert_filename` | The file name of the issuer's CA public certificate.
`ca_key_filename` | The file name of the issuer's CA private key.
`ca_key_password` | The password for the issuer's CA private key.
`selfsigned` | Generates a self-signed certificate that can be used as a trusted CA certificate. If this argument is specified, the `ca_cert_filename`, `ca_key_filename`, and `ca_key_password` arguments should not be specified.
`certfile` | The name of the generated certificate file.
`privatekeyfile` | The name of the generated private key file.
`keyfilepassword` | The password for the private key.
`keystrength` | The length (in bits) of the keys to be generated. The longer the key, the more difficult it is for someone to break the encryption.
`commonname` | The name to be associated with the generated certificate.
`orgunit` | The name of the organizational unit associated with the generated certificate.
`organization` | The name of the organization associated with the generated certificate.
`locality` | The name of a city or town.
`state` | The name of the state or province in which the organizational unit (ou) operates if your organization is in the United States or Canada, respectively. Do not abbreviate.
`countrycode` | Two-letter ISO code for your country. The code for the United States is US.
`subjectkeyidentifier` | Generates a certificate with the Subject Key identifier extension and the ID value specified on the command line.
`UTF-8|BASE64` | Format of the `subjectkeyid` value. Allowed values are UTF-8 or BASE64, with UTF-8 assumed by default.

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

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

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

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

If the host entry is configured as:

`hosts: dns nis [NOTFOUND=return]`

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

If the host entry is configured as:

`hosts: files dns nis [NOTFOUND=return]`

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

## Using Certificate Chains (Deprecated)

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

To use certificate chains with WebLogic Server:

1. Ensure that all the digital certificates are in PEM format. If they are in DER format, you can convert them using the utils.der2pem utility. If you are using a digital certificate issued by Microsoft, see Converting a Microsoft p7b Format to PEM Format. You can use the steps in "Converting a Microsoft p7b Format to PEM Format" to convert other types of digital certificates. Save the digital certificate in Base 64 format.
2. Open a text editor and include all the digital certificate files into a single file. The order is important. The server digital certificate should be the first digital certificate in the file. The issuer of that digital certificate should be the next file and so on until you get to the self-signed root certificate authority certificate. This digital certificate should be the last certificate in the file.

You cannot have blank lines between digital certificates.

3. Specify the file in the Server Certificate File Name attribute in the SSL Configuration portion of the Keystores and SSL tab in the WebLogic Server Administration Console.

Listing 8-1 shows a sample certificate chain.

Listing 8-1 Sample File with Certificate Chain

`-----BEGIN CERTIFICATE-----
0tBq+7YuAkjecEocGXvi2G4YSoWVLgnVzJoJuds3c35KE6sxBe1luJQuQkE9SzALG/6lDIJ5ctPsHFmZzZxY7scLl6hWj5ON8oN2YTh5Jo/ryqjvnZvqiNIWe/gqr2GLIkajC0mz4un1LiYORPig3fBMH0=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CNNnORlsLjmRhuVxg9rJFEtjHMjrSYr2IDFhcdwPgIt0meWEVnKNObSFYcCAwEAAaMWMBQwEgYDVR0TAQH/BAgwBgEB/wIBATANBgkqhkiG9w0BAQQFAAOBgQBS+0oqWxGyqbZO028zf9tQT2RKojfuwywrDoGW96Un5IqpFnBHIu5atliJo3OUpiH18KkwLN8DVP/3t3K3O3kXdIuLbqAL0i5xyBlAhr7gE5eVhIyeMg7ETBPLyGO2BF13Y24LlsO+MX9jW7fxMraPN608QeJXkZw0E0cGwrw2AQ==
-----END CERTIFICATE-----`

## Converting a Microsoft p7b Format to PEM Format

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

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

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 CA certificates with WebLogic Server:

1. Ensure the trusted CA certificates are in PEM format.

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

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

## Getting a Digital Certificate for a Web Browser

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

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

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

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

# Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities

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

For the purpose of backward compatibility, private keys and trusted CA certificates can be stored in a file or in a JKS keystore accessed via the WebLogic Keystore provider. In addition, trusted CA certificates can be stored in a JKS keystore. Use the SSL Configuration section of the Keystores and SSL page of the WebLogic Server Administration Console to specify identity and trust attributes when using a file or a JKS keystore accessed via the WebLogic Keystore provider.

For more information, see:

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

- The WebLogic `ImportPrivateKey` utility. The `ImportPrivateKey` utility allows you to take private key and digital certificate 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. While you can use the `keytool` utility to generate new private keys and digital certificates and add them to 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.

Note: The `keytool` utility does allow you to import trusted CA certificates in a file into a keystore.

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

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

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

- 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 likey to be store in hardware keystores such as nCipher. Trust can be stored in a file-based JDK keystore without having security issues since trust only has certificates not private keys.

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

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

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

## Common Keytool Commands

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

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

Table 8-1 Commonly Used keytool Commands

Command | Description
--- | ---
`keytool -genkey -keystore` `keystorename``-storepass` `keystorepassword` | Generates a new private key entry and self-signed digital certificate in a keystore. If the keystore does not exist, it is created.
`keytool -import -alias` `aliasforprivatekey``-file` `privatekeyfilename.pem` `-keypass` `privatekeypassword` `-keystore` `keystorename``-storepass` `keystorepassword` | Updates the self-signed digital certificate with one signed by a trusted CA.
`keytool -import -alias` `aliasfortrustedca``-trustcacerts -file` `trustedcafilename.pem``-keystore` `keystorename``-storepass` `keystorepassword` | Loads a trusted CA certificate into a keystore. If the keystore does not exist, it is created.
-certreq -alias alias -sigalg `sigalg` -file `certreq_file` -keypass `privatekeypassword` -storetype `keystoretype` -keystore `keystorename` -storepass `keystorepassword` | Generates a CSR, using the PKCS#10 format. Sent the CSR to be sent to a trusted CA. The trusted CA authenticates the certificate requestor and returns a digital certificate to replace the existing self-signed digital certificate in the keystore.
`keytool -list -keystore` `keystorename` | Displays what is in the keystore.
`keytool -delete -keystore` `keystorename``-storepass` `keystorepassword``-alias` `privatekeyalias` | Delete a private key/digital certifcate pair for the specified alias from the keystore.
`keytool -help` | Provides online help for keytool.

# How WebLogic Server Locates Trust

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

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

# Configuring Keystores

By default, WebLogic Server is configured with two keystores:

- `DemoIdentity.jks`—Contains a demonstration private key for WebLogic Server. This keystore contains the identity for WebLogic Server.
- `DemoTrust.jks`—Contains the trusted certificate authorities from the `WL_HOME\server\lib\DemoTrust.jks` and the JDK `cacerts` keystores. This keystore establishes trust for WebLogic Server.

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

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

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

1. Obtain private keys and digital certificates from a reputable certificate authority such as Verisign, Inc. or Entrust.net. For more information, see Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities.
2. Create Identity and Trust keystores. For more information, see Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
3. Load the private keys and trusted CAs into the Identity and Trust keystores. For more information, see Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.

To configure Identity and Trust keystores for WebLogic Server:

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

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

4. Click the Change... link in the Keystore Configuration to configure new keystores.
5. Choose the type of keystore configuration being used. The following options are available:

- Demo Identity and Demo Trust—The demonstration Identity and Trust keystores located in the `WL_HOME\server\lib` directory and configured by default and the `cacerts` file in the `JAVA_HOME\jre\lib\security` directory.
- Custom Identity and Java Standard Trust—An Identity keystore you create and the trusted CAs defined in the cacerts file in the `JAVA_HOME\jre\lib\security` directory.
- Custom Identity and Custom Trust—Identity and Trust keystores you create.
- Custom Identity and Command-Line Trust—An Identity keystore you create and command-line arguments that specify the location of the Trust keystore. Use this option in a production environment when the Administration port is enabled and Managed servers are started on the command-line instread of by the Node Manager.

6. Click Continue.
7. Define attributes for the Identity keystore.

- Custom Identity Keystore File Name—The fully qualified path to the Identity keystore.
- Custom Identity Keystore Type—The type of the keystore. Generally, this attribute is `jks`. If this attribute is not specified, the default keystore type defined in the security policy file for the JDK is used.
- Custom Identity Keystore PassPhrase—The password defined when creating the keystore. This attribute is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. Some keystores do not require the passphrase to read from the keystore. Whether or not you define this property depends on the requirements of the keystore. For example, WebLogic Server only reads from the keystore so a passphrase is not required, however, WebLogic Integration writes to keystores and therefore requires a passphrase. Confirm the password.

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

8. Define attributes for the Trust keystore.

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

If you choose Custom Trust, define the following attributes:

- Custom Trust Keystore File Name—The fully qualified path to the trust keystore.
- Custom Trust Keystore Type—The type of the keystore. Generally, this attribute is `jks`. If this attribute is not specified, the default keystore type defined in the security policy file for the JDK is used.
- Custom Trust Keystore PassPhrase—The password defined when creating the keystore. This attribute is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. Some keystores do not require the passphrase to read from the keystore. Whether or not you define this property depends on the requirements of the keystore. For example, WebLogic Server only reads from the keystore so a passphrase is not required, however, WebLogic Integration writes to keystores and therefore requires a passphrase. Confirm the password.

9. Click Continue.
10. Click Finish.
11. Optionally, configure the SSL attributes for WebLogic Server. You do not have to perform this step if you are using keystores for the purpose of digital signing.
12. Reboot WebLogic Server.

# Configuring SSL

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

To configure SSL:

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

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

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

Note: For the purpose of backward compatibility, private keys and trusted CA certificates can be stored in a file or in a JKS keystore accessed via the WebLogic Keystore provider. If you migrated from a previous version of WebLogic Server, WebLogic Server uses the existing security configuration and sets the Files or Key Store Providers option. In this circumstance, step 4 can be skipped.

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

The Configure SSL page appears.

2. Specify how the identity and trust for WebLogic Server is stored. The following options are available:

- Key Stores—Use this option if you created Identity and Trust keystores for WebLogic Server. If you choose this option, go to step 8.
- Files or Key Store Providers—Use this option if you stored private keys and trusted CA certificates in a file or in a JKS keystore accessed via the WebLogic Keystore provider (as supported in previous releases of WebLogic Server). If you choose this option, go to step 9. This option is available for the purpose of backward compatibility only and it automatcally set with security information from a previous release of WebLogic Server.

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

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

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

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

- Private Key File Name—The directory location of the private key for WebLogic Server. Specify a value for this attribute only if you stored the private key for WebLogic Server in a file (versus a WebLogic Keystore provider).
- Private Key Alias—The alias specified when loading the private key for WebLogic Server from the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accessed by the WebLogic Keystore provider.
- Passphrase—The password specified when loading the private key for WebLogic Server into the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accesssed by the WebLogic Keystore provider. Confirm the password. If you protected the private key file with a password, specify the `weblogic.management.pkpassword` command-line argument when starting the server.
- Server Certificate File Name— The directory location of the digital certificate for WebLogic Server. If you are using a certificate chain that is deeper than two certificates, you to need to include the entire chain in PEM format in the certificate file.
- Trusted CA File Name—The name of the file containing the PEM-encoded trusted certificate authorities.

2. Click Continue.
3. Click Finish.
4. Reboot WebLogic Server.

# Configuring Two-Way SSL

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

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

To enable two-way SSL:

1. Configure one-way SSL as described in Configuring SSL.
2. Expand the Servers node.
3. Select the name of the server for which you want to configure two-way SSL (for example, exampleserver).
4. Select the Configuration-->Keystores and SSL tab.
5. Click the Show link under Advanced Options.
6. Go to the Server attributes section of the window.
7. Set the Two Way Client Cert Behavior attribute. The following options are available:

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

8. Click Apply.
9. Reboot WebLogic Server.

# Disabling the SSL Port

You may encounter a circumstance where you need to disable the SSL port. For example, the Administration Port uses SSL internally to protect communications between the Administration Server, Managed Servers, and the Node Manager. When using the Administration Port, you might want to disable the SSL port.

To disable the SSL port:

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

# Using Host Name Verification

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

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

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

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

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

1. Expand the Servers node.
2. Select the name of the server (for example, exampleserver).
3. Select the Configuration-->Keystores and SSL tab.
4. Click the Show link under Advanced Options.
5. Go to the Client attributes section of the window.
6. Verify that the the Hostname Verification field is set to BEA Hostname Verifier.

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

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

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

`-Dweblogic.security.SSL.ignoreHostnameVerification=true`

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

- In the WebLogic Server Administration Console:

1. Expand the Servers node.
2. Select the name of the server (for example, exampleserver).
3. Select the Configuration-->Keystores and SSL tab.
4. Click the Show link under Advanced Options.
5. Go to the Client attributes section of the window.
6. Set the Hostname Verification field to None.
7. Reboot WebLogic Server.

You can also write a custom host name verifier. For more information, see Programming WebLogic Security. If you write a custom host name verifier, the name of the class that implements the host name verifier must be specified in the CLASSPATH of WebLogic Server (when acting as an SSL client) or a Java client acting as an SSL client.

To configure a custom host name verifier:

1. Expand the Servers node.
2. Select the name of the server (for example, exampleserver).
3. Select the Configuration-->Keystores and SSL tab.
4. Click the Show link under Advanced Options.
5. Go to the Client attributes section of the window.
6. Set the Hostname Verification field to Custom Hostname Verifier.
7. Enter the name of the implementation of the `weblogic.security.SSL.HostnameVerifier` interface in the Custom Hostname Verifier field.
8. Reboot WebLogic Server.

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

`-Dweblogic.security.SSL.HostnameVerifier=``classname`

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

# Enabling SSL Debugging

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

- 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 a Managed Server started by the Node Manager, specify this command-line argument on the Remote Start tab for the Managed Server.

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

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

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

- 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 changed in this release of WebLogic Server. The `weblogic.security.SSL.sessionCache.size` command-line argument is ignored.

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

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

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

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

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

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

# Configuring SSL for the Node Manager

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

- SSL Requirements for Administration Servers
- SSL Requirements for Managed Servers
- SSL Requirements for the Node Manager
- Host Name Verification Requirements
- Host Name Verification Requirements
- Node Manager SSL Production Configuration: Main Steps
- Node Manager SSL Production Configuration: Main Steps
- Using Files and the WebLogic Keystore Provider

## SSL Requirements for Administration Servers

To use SSL, Administration Servers require:

- Identity—Administration Servers use private keys and digital certificates stored in keystores. The digital certificate must specify a host name rather than an IP address. The location of the Identity keystore is specified in the WebLogic Server Administration Console.

By default, Administration Servers are configured to use the demonstration Identity keystore (`DemoIdentity.jks`). For testing and development purposes the Identity keystore configuration is complete.

- Trust—Administration Servers use trusted CA certificates stored in a keystore. The location of the Trust keystore is specified in the WebLogic Server Administration Console.

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

In a production environment, a custom Trust keystore (a keystore you create) or the Java Standard Trust keystore can be used with the Administration Server. The Administration Server needs to trust the certificate authorities for all Node Managers running on machines in this domain and any Managed Servers (meaning those trusted CA certificates must be in the Trust keystore of the Administration Server). This requirement applies only if the Administration port is being used.

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

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

## SSL Requirements for Managed Servers

To use SSL, Managed Servers require:

- Identity—Managed Servers use private keys and digital certificates stored in keystores. The digital certificate must specify a host name rather than an IP address. The location of the Identity keystore is specified in the WebLogic Server Administration Console.

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

- Trust—Managed Servers use trusted CA certificates stored in a keystore. The location of the Trust keystore is specified in the WebLogic Server Administration Console.

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

In a production environment, a custom Trust keystore (a keystore you create) or the Java Standard Trust keystore can be used with a Managed Server. A Managed Server needs to trust the certificate authorities for all Node Managers running on machines in this domain and the Administration Server (meaning those trusted CA certificates must be in the trust keystore of the Managed Server). This requirement applies only if the Administration port is being used.

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

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

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

## SSL Requirements for the Node Manager

To use SSL, the Node Manager requires:

- Keystores—Specify the type of keystore configuration to be used by the Node Manager. By default, the Node Manager is configured to use DemoIdentityandDemoTrust as the keystore congfiguration.

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

`Keystores=CustomIdentityandCustomTrust`

`Keystores=CustomIdentityandJavaStandardTrust`

For more information, see Node Manager Properties in Configuring and Managing WebLogic Server.

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

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

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

`CustomIdentityKeystoreType`

`CustomIdentityAlias`

CustomIdentityKeystoreFileName

CustomIdentityKeyStorePassPhrase

CustomIdentityPrivateKeyPassPhrase

For more information, see Node Manager Properties in Configuring and Managing WebLogic Server.

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

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

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

Custom Trust keystore:

CustomTrustKeystoreType

CustomTrustKeystoreFileName

CustomTrustKeyStorePassPhrase

Java Standard Trust keystore:

JavaStandardTrustKeyStorePassPhrase

For more information, see Node Manager Properties in Configuring and Managing WebLogic Server.

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

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

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

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

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

## Host Name Verification Requirements

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

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

## Identity and Trust: Demonstration Versus Production

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

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

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

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

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

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

3. Load the private keys and certificates into the Identity keystore and trusted CA certificates into the Trust keystore.
4. Configure the keystore location and passwords for the Administration Server and Managed Server in the WebLogic Server Administration Console.
5. Edit the `nodemanager.properties` file to specify the keystore location and passwords for the Node Manager.

## Node Manager SSL Demonstration Configuration: Main Steps

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

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

Figure 8-1 SSL Demonstration Configuration for the Node Manager

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

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

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

See Example: Creating a Domain with Administration Server and Clustered Managed Servers.

2. Start the Administration Server. Do not enable the Administration port.
3. On the Server-->Keystores and SSL tab, verify the settings of the following Identity keystore attributes for the Administration Server:

- Demo Identity Keystore—`DemoIdentity.jks`
- Type—`JKS`
- Passphrase—`DemoIdentityKeyStorePassPhrase`

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

- Demo Trust Keystore—`DemoTrust.jks`
- Type—`JKS`
- Passphrase—`DemoTrustKeyStorePassPhrase`

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

- Demo Identity Keystore—`DemoIdentity.jks`
- Type—`JKS`
- Passphrase—`DemoIdentityKeyStorePassPhrase`

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

- Demo Trust Keystore—`DemoTrust.jks`
- Type—`JKS`
- Passphrase—`DemoTrustKeyStorePassPhrase`

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

## Node Manager SSL Production Configuration: Main Steps

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

Figure 8-2 SSL Production Configuration for the Node Manager

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

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

To configure SSL for the Node Manager:

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

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

1. Create Identity keystores for the Node Manager, the Administration Server, and any Managed Servers. If the Node Manager, the Administration Server, and the Managed Servers run on the same machine, they can share the Identity keystore. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
2. Load the private keys into the Identity keystores. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
3. Create Trust keystores for the Node Manager, Administration Server, and any Managed Servers. If the Node Manager, the Administration Server, and the Managed Servers run on the same machine, they can share the Trust keystore. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
4. Load the trusted CA certificates into the Trust keystore. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authorities.
5. Run the Configuration Wizard and create a new WebLogic domain.
6. Start the Administration Server.
7. Enable the Administration port for the WebLogic domain. See Enabling the Domain-Wide Administration Port.
8. Set the Listen Address for the Administration Server. The Listen Address is the host name of the machine on which the Administration Server runs. This host name should match the host name in the CN field of the digital certificate for the Administration Server. If you don't set the Listen Address correctly, you may encounter host name verification errors.

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

`keytool -list -v -keystore` fulldirectorypathtokeystore`\`keystorename

9. Configure the Identity keystore for the Administration Server. See Configuring Keystores.
10. Configure the Trust keystore for the Administration Server. See Configuring Keystores.
11. If you have multiple servers running on the same machine, ensure the Administration Port for each server is unique. Use the Local Administration Port Override attribute on the Server-->General tab to override the Administration Port number. Specify a port number other than the Administration port number used by the Administration Server.
12. Set the Listen Address for the Managed Server to the host name of the machine on which the Managed Server runs. This host name should match the host name in the digital certificate for the Managed Server.
13. Configure the Identity keystore for the Managed Server. See Configuring Keystores.
14. Configure the Trust keystore for the Managed Server. See Configuring Keystores.
15. Create a machine for the Node Manager.

1. Set the Listen Address of the Node Manager to the host name of the machine on which the Node Manager runs. This host name should match the host name in the digital certificate for the Node Manager.
2. Set the Listen Port for the Node Manager. Ensure that this port number is different from the Listen port number, the SSL port number, and the Administration port number of all the servers that run on this machine.
3. Add any Managed Servers to the machine.

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

16. Edit the `nodemanager.properties` file for the Node Manager. Edit the `nodemanager.properties` file.

1. Specify the keystore configuration to be used:

`Keystores=CustomIdentityandCustomTrust`

`Keystores=CustomIdentityandJavaStandardTrust`

2. Specify information about the Identity keystore:

`CustomIdentityKeystoreType`

`CustomIdentityAlias`

`CustomIdentityKeystoreFileName`

`CustomIdentityKeyStorePassPhrase`

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

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

`CustomIdentityPrivateKeyPassPhrase`

3. Specify information about the Trust keystore.

If you use a custom Trust keystore, specify:

`CustomTrustKeystoreType`

`CustomTrustKeystoreFileName`

`CustomTrustKeyStorePassPhrase`

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

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

If you use the Java Standard Trust keystore, specify:

`Keystores=CustomIdentityandJavaStandardTrust`

`JavaStandardTrustKeyStorePassPhrase`

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

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

`ListenAddress
ListenPort`

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

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

`ReverseDnsEnabled`

See Node Manager Properties in Configuring and Managing WebLogic Server.

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

17. Edit the `nodemanager.hosts` file located in WL_HOME`\common\nodemanager\config` to list the machines on which the Administration Servers that communicate with the Node Manager run. The Administration Servers are specified by IP address or host name if Reverse DNS is used.

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

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

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

## Using Files and the WebLogic Keystore Provider

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

The SSL requirements for identity and trust are as follows:

- Administration Servers and Managed Servers use private keys stored in JKS keystores accessed through the WebLogic Keystore provider or in a file.
- The digital certificate for an Administration Server and a Managed Server must be stored in a file.
- Administration Servers and Managed Servers can use trusted CA certificates stored:

- In a JKS keystore specified by the `-Dweblogic.security.SSL.trustedCAKeyStore` command-line in the start script for the Administration Server or Managed Server.
- In a JKS keystore accessed by the WebLogic Keystore provider
- A file containing the PEM-encoded trusted certificate authorities.

If no trusted CA certificate is located in either of these storage mechanisms, WebLogic Server assumes anyAdministration Server and Managed Servers trust all the certificate authorities in the `cacerts` files in the WL_HOME`\server\lib.`

- The Node Manager can only use digital certificates and private keys stored in files. Identity is specified by the command-line arguments for the Node Manager.
- The Node Manager uses trusted CA certificates stored in a JKS keystore for trust. The Trust keystore is specified by the command-line arguments for the Node Manager

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

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

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

Information about the demonstration Identity and Trust keystores is displayed.

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

The Configure SSL page appears.

5. Choose the Files or Keystore Providers option.
6. Click Continue.
7. Specify information about the location of identity and trust for WebLogic Server.

- Private Key File Name—The directory location of the private key for WebLogic Server. Specify a value for this attribute only if you stored the private key for WebLogic Server in a file (versus a WebLogic Keystore provider).
- Private Key Alias—The alias specified when loading the private key for WebLogic Server from the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accessed by the WebLogic Keystore provider.
- Passphrase—The password specified when loading the private key for WebLogic Server into the keystore. Specify a value for this field only if you stored the private key for WebLogic Server in a keystore accesssed by the WebLogic Keystore provider. Confirm the password. If you protected the private key file with a password, specify the `weblogic.management.pkpassword` command-line argument when starting the server.
- Server Certificate File Name— The directory location of the digital certificate for WebLogic Server. If you are using a certificate chain that is deeper than two certificates, you to need to include the entire chain in PEM format in the certificate file.

8. Click Continue.
9. Click Finish.
10. Reboot WebLogic Server.
11. When starting the Administration Server, use the following command-line argument to specify the location of the Trust keystore:

`-Dweblogic.security.SSL.TrustedCAKeyStore=`path_to_keystore

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

weblogic.security.SSL.trustedCAKeyStore

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

- Use `weblogic.nodemanager.keyFile=`filename to specify the location of the private key file.
- If you password protected the private key file, use `weblogic.nodemanager.keyPassword=`password to specify the password.
- Use `weblogic.nodemanager.certificateFile=`filename to specify the location of the digital certificate for the Node Manager.
- Use `weblogic.security.SSL.trustedCAKeyStore=`keystorename to specify the location of the JKS trusted keystore.

# Configuring RMI over IIOP with SSL

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

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

1. Configure WebLogic Server to use SSL.
2. Configure the client Object Request Broker (ORB) to use SSL. Refer to the product documentation for your client ORB for information about configuring SSL.
3. Use the `host2ior` utility to print the WebLogic Server IOR to the console. The `host2ior` utility prints two versions of the interoperable object reference (IOR), one for SSL connections and one for non-SSL connections. The header of the IOR specifies whether or not the IOR can be used for SSL connections.
4. Use the SSL IOR when obtaining the initial reference to the CosNaming service that accesses the WebLogic Server JNDI tree.

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

# SSL Certificate Validation

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

If WebLogic Server is booted with a certificate chains that will not pass the certificate validation, an information message is logged noting that clients could reject it.

## Controlling the Level of Certificate Validation

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

`-Dweblogic.security.SSL.enforceConstraints=``option`

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

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

Option | Description
--- | ---
`strong` or `true` | Use this option to check that the Basic Constraints extension on the CA certificate is defined as CA. For example: `-Dweblogic.security.SSL.enforceConstraints=strong` or `-Dweblogic.security.SSL.enforceConstraints=true` By default, WebLogic Server performs this level of certificate validation.
`strict` | Use this option to check whether the Basic Constraints extension on the CA certificate is defined as CA and set to critical. This option enforces the IETF RFC 2459 standard. For example: `-Dweblogic.security.SSL.enforceConstraints=strict` This option is not the default because a number of commerically available CA certificates do not conform to the IETF RFC 2459 standard.
`off` | Use this option to turn off checking for the Basic Constraints extension. The rest of the certificate validation still happens. CA certificates from most commercial certificate authorities should work with the default `strong` option. For example: `-Dweblogic.security.SSL.enforceConstraints=off` BEA does not recommend using this option in a production environment. Instead, purchase new CA certificates that comply with the IETF RFC 2459 standard.

## Accepting Certificate Policies in Certificates

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

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

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

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

## Checking Certificate Chains

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

>     java utils.ValidateCertChain -file pemcertificatefilename
>     java utils.ValidateCertChain -pem pemcertificatefilename
>     java utils.ValidateCertChain -pkcs12store pkcs12storefilename
>     java utils.ValidateCertChain -pkcs12file pkcs12filename password
>     java utils.ValidateCertChain -jks alias storefilename [storePass]

Example of valid certificate chain:

>     java utils.ValidateCertChain -pem zippychain.pem

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

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

>     Certificate chain appears valid

Example of invalid certificate chain:

>     java utils.ValidateCertChain -jks mykey mykeystore

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

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

>     Certificate chain is invalid

## Troubleshooting Problems with Certificates

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

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

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

- 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 JDK 1.4. This type of provider is different from the providers written using the WebLogic Security Service Provider Interfaces (SSPIs). WebLogic Server does not provide a JCE provider by default.

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

WebLogic Server supports the use of the following JCE providers:

- The JDK JCE provider (`SunJCE`) in the JDK 1.4.1. For more information about the features in the JDK JCE provider, see http://java.sun.com/products/jce.

By default, the JCE provider in the JDK 1.4.1 has export strength jurisdiction policy files. After filling out the appropriate forms, the domestic strength jurisdiction policy files are downloadable from Sun Microsystem at http://java.sun.com/products/jce/index-14.html#UnlimitedDownload.

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

- The nCipher JCE provider. For more information about the nCipher JCE provider, see http://www.ncipher.com/solutions/webservers.html.

To install the nCipher JCE provider:

1. Install and configure the hardware for the nCipher JCE provider per the product's documentation.
2. Install the files for the nCipher JCE provider. The following files are required:

- JCE 1.2.1 framework JAR
- Jurisdiction policy files
- JCE provider
- Certificate that signed the JAR file

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

The files are installed in one of the following ways:

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

Windows NT

`%JAVA_HOME%\jre\lib\ext`

For example:

`%WL_HOME%\jdk141\jre\lib\ext`

UNIX

`$JAVA_HOME/jre/lib/ext`

For example:

`$WL_HOME/jdk141/jre/lib/ext`

- In the CLASSPATH of the server.

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

Windows NT

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

UNIX

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

Specify the nCipher JCE provider as:

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

where

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

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

`security.provider.1=sun.security.provider.Sun`

`security.provider.2=com.sun.rsajca.Provider`

`security.provider.3=com.ncipher.provider.km.mCipherKM`

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

# Specifying the Version of the SSL Protocol

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

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

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

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

- `-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 uses host name verification. The following sections describe these steps in detail.

## Ensure Two-Way SSL Is Disabled on the SSL Server

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

To disable two-way SSL when using WebLogic Server:

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

## Use a Secure Port in the URL

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

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

## Specify Trust for weblogic.Admin

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

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

`-Dweblogic.security.JavaStandardTrustKeyStorePassPhrase=``password`

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

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

- Demo Trust—The trusted CA certificates in the demonstration Trust keystore (`DemoTrust.jks`) located in the `WL_HOME\server\lib` directory. In addition, the trusted CAs in the JDK `cacerts` keystore are trusted. To use the Demo Trust, specify the following command-line argument:

`-Dweblogic.security.TrustKeyStore=DemoTrust`

Optionally, use the following command-line argument to specify a password for the JDK cacerts trust keystore:

`-Dweblogic.security.JavaStandardTrustKeyStorePassPhrase=``password`

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

- Custom Trust—A trust keystore you create. To use Custom Trust, specify the following command-line arguments:

- `weblogic.security.TrustKeyStore=CustomTrust`

This required command-line argument specifies the use of Custom Trust

- `weblogic.security.CustomTrustKeyStoreFileName=``filename`

This required command-line argument specifies the fully qualified path to the trust keystore

- `weblogic.security.TrustKeystoreType=``keystore_type`

This optional command-line argument specifies the type of the keystore. Generally, this value for type is the default value, `jks`.

- `weblogic.security.CustomTrustKeyStorePassPhrase=``password`

This optional command-line argument specifies the password defined when creating the keystore.

## Specify Host Name Verification for weblogic.Admin

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

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

`-Dweblogic.security.SSL.ignoreHostnameVerification=true`

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

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

`-Dweblogic.security.SSL.hostnameVerifier=``classname`

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