Administration Application Guide

Configuring Secure Sockets Layer for a Production Environment

BEA WebLogic Enterprise Security uses an implementation of the Transport Layer Security (TLS) 1.0 specification. The server (WebLogic Server 8.1) hosting the WebLogic Enterprise Security Administration Application supports TLS on a dedicated listen port which defaults to 7010. To establish a secure connection, a Web browser connects to the Administration Server by supplying the listen port and the secure address (HTTPS) in the connection URL, for example, https://myserver:7010. The Administration Server returns a certificate to identify itself to the client.

When you install the BEA WebLogic Administration Application, demo certificates are provided for working in a development environment. However, it is very important that these certificates not be used in a production environment.

The following sections describe how to configure Secure Sockets Layer (SSL) for a production environment:

Some SSL Basics

The following topics provide some basic information about SSL and the WebLogic Enterprise Security Administration Application.

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 so 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 is digitally signed with the digital certificate of the certificate authority. Well-known certificate authorities include Verisign and Entrust. The trusted certificate authority (CA) certificate establishes trust for a 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 invalid because it has expired, or the digital certificate of the certificate authority used to sign it expired, or because the host name in the digital certificate of the server does not match the URL specified by the client.

One-Way SSL Versus Two-Way SSL

You can configure SSL to use either one-way or two-way authentication:

With one-way SSL, to establish an SSL connection, 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 accepts any client into the connection. One-way SSL is common on the Internet where customers want to create secure connections before sharing personal data. Often, clients use SSL to log on so that the server can authenticate them. The Administration Application is configured to use one-way SSL by default.
With two-way SSL, to establish the SSL connection, the server is required to present a certificate to the client and the client is required to present a certificate to the server. WebLogic Enterprise Security can be configured to require clients to submit valid and trusted certificates before completing the SSL connection.

How WebLogic Enterprise Security Locates Trust

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

If the keystore is specified by the -Dweblogic.security.SSL.trustedCAkeystore command-line argument, load the trusted CA certificates from that keystore.

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, where WL_HOME is BEA_HOME\weblogic81 by default.

Else load trusted CA certificates from WL_HOME\server\lib\cacerts keystore.

Configuring SSL

To configure SSL in the WebLogic Enterprise Security Administration Server for a production environment, perform the following tasks:

Obtain an identity (private key and digital certificates) and certificate from a trusted certificate authority, which signed the certificate. Use a reputable vendor such as Entrust or Verisign as the certificate authority. For instructions on how to perform this task, see Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities for details on performing this task.

Store private keys, digital certificates, and trusted CA certificates in keystores. For instruction on how to perform this task, see Creating a Keystore and Loading Private Keys and Trusted Certificate Authorities.

Configure the WebLogic Enterprise Security hosting the Administration Application to use these new identity and trust keystores. For instructions for performing these tasks, see the following topics:

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 the certificate for the certificate authority that signs the certificate. In one-way SSL, the client needs to trust the certificate authority; the server does not.

WebLogic Enterprise Security loads private keys, digital certificates, and trusted CA certificates from keystores.You can use the Sun Microsystems keytool utility to create the keystores.

This utility allows you to generate a private key, a self-signed digital certificate, and a Certificate Signing Request (CSR). Submit the CSR to a certificate authority to obtain a digital certificate. Use keytool to update the self-signed digital certificate with a new digital certificate signed by the certificate authority. For more information about the Sun Microsystems keytool utility, see keytool—Key and Certificate Management Tool.

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

Creating a Keystore and Loading Private Keys and Trusted Certificate Authorities

After you obtain private keys, digital certificates, and trusted CA certificates, you need to store them so that the Administration Server can use them to find and verify identity. Private keys, their associated digital certificates, and trusted CA certificates are stored in keystores. A keystore is a mechanism designed to create and manage private key/digital certificate pairs and trusted CA certificates.

BEA recommends creating one keystore for identity (private key/digital certificate pairs) and another keystore for trust relationships (trusted CA certificates). However, one keystore can be used for both identity and trust.

By default, WebLogic Enterprise Security looks for an Identity keystore named DemoIdentity.jks in the WL_HOME\server\lib directory and a Trust keystore named DemoTrust.jks in the WL_HOME\server\lib directory (where WL_HOME is BEA_HOME\weblogic81 by default) and cacerts in the JAVA_HOME\jre\lib\security directory (where JAVA_HOME is BEA_HOME\jdk142_04 or BEA_HOME\jdk142_05 by default).

All private key entries in a keystore are accessed through 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 Enterprise Security are trusted. Although WebLogic Enterprise Security 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.

You can use the following mechanisms to create a keystore and load private keys and trusted CA certificates into the keystore:

Sun Microsystems keytool utility—You can 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.

ImportPrivateKey utility—You can use the ImportPrivateKey utility to load a private key into a private keystore file. For instructions on using the ImportPrivateKey utility, see Using the ImportPrivateKey Utility.
Custom utilities—This release of WebLogic Enterprise Security can use keystores created with custom tools or utilities. For information on how to use these utilities, see the user documentation provided with the utility.

Common Keytool Commands

Table 7-1 describes the keytool commands for creating and using JKS keystores with WebLogic Enterprise Security.

Note: The keytool utility is a product of Sun Microsystems. Therefore, BEA does not provide complete documentation on the utility. For more information, see keytool-Key and Certificate Management Tool, which is available from the Sun Microsystems web site.

Table 7-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-fileprivatekeyfilename.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 -sigalgsigalg-filecertreq_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 certificate pair for the specified alias from the keystore.
`keytool -help`	Provides online help for keytool.

Using the ImportPrivateKey Utility

You can use the ImportPrivateKey utility to load a private key into a private keystore file.

The syntax for using this utility is:

java -classpath %WL_HOME%\server\lib\weblogic.jar utils.ImportPrivateKeykeystore keystorepass alias keypass certfile keyfile

Table 7-2 describes the ImportPrivateKey utility arguments.

Table 7-2 ImportPrivateKey Utility Arguments

Argument	Definition
`keystore`	Defines the name of the keystore file. A new keystore is created if one does not exist.
`keystorepass`	Defines the password to open the keystore file.
`alias`	Defines the name that is used to look up certificates and keys in the keystore.
`keypass`	Defines the password used to unlock the private key file and to protect the private key in the keystore.
`certfile`	The name of the certificate associated with the private key.
`keyfile`	The name of the file holding the protected private key.

Configuring Keystores

By default, WebLogic Enterprise Security is configured with two keystores:

DemoIdentity.jks—Contains a demonstration private key for the Administration Server. This keystore contains the identity for WebLogic Enterprise Security.
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 Enterprise Security Administration Server.

These keystores are located in the WL_HOME\server\lib directory, where WL_HOME is BEA_HOME\weblogic81 by default.

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 an Administration Server demonstration certificate authority. Therefore, all Administration Server installations trust each other. This configuration leaves your SSL connections vulnerable to a number of security attacks.

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 perform the following tasks:

Obtain private keys and digital certificates from a reputable certificate authority such as Verisign, Inc. or Entrust. For more information, see Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities.

Create Identity and Trust keystores and load the private keys and trusted CAs into the Identity and Trust keystores.. For more information, see Creating a Keystore and Loading Private Keys and Trusted Certificate Authorities.

To configure Identity and Trust keystores for WebLogic Enterprise Security:

To start the WebLogic Server Administration Console for WebLogic Enterprise Security, open an Internet Explorer browser and enter the following URL:

https://hostname:port/console

Where:
hostname is the Domain Name Server (DNS) name or IP address of the WebLogic Enterprise Administration Server.
port is the port number through which the WebLogic Server Administration Server connects. The default port is 7010.
WebLogic Enterprise Security is configured with a default identity keystore (DemoIdentity.jks) and a default trust keystore (DemoTrust.jks). In addition, WebLogic

Open the Servers folder.

Select the name of the server for which you want to configure keystores (for example, asiAdminServer).

Select the Configuration-->Keystores and SSL tab.

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

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

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.

Click Continue.

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.

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 —This attribute is not necessary as WebLogic Server only reads from the keystore.

Click Continue.

Click Finish.

To have the changes take effect, stop and restart the WebLogic Enterprise Administration Server.

Configuring One-Way SSL

Use the steps in this section to configure SSL for a production environment.

To configure SSL:

To start the WebLogic Server Administration Console for WebLogic Enterprise Security, open an Internet Explorer browser and enter the following URL:

https://hostname:port/console

Where:
hostname is the Domain Name Server (DNS) name or IP address of the WebLogic Enterprise Administration Server.
port is the port number through which the WebLogic Server Administration Server connects. The default port is 7010.
WebLogic Enterprise Security is configured with a default identity keystore (DemoIdentity.jks) and a default trust keystore (DemoTrust.jks). In addition, WebLogic

In the Open the Servers folder.

Select the name of the server for which you want to configure keystores (for example, asiAdminServer).

Select the Configuration-->Keystores and SSL tab.

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

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

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

The Configure SSL page appears.

Use the Key Stores option to specify how the identity and trust for WebLogic Enterprise Security is stored.

Click Continue.

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 attribute. 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 Enterprise Security Administration Server with aliases. All trusted CA certificates in a keystore identified as trusted by WebLogic Enterprise Security are trusted. Therefore, WebLogic Enterprise Security does not require an alias when retrieving a trusted CA certificate from the keystore.

Click Continue.

Click Finish.

To have the changes take effect, stop and restart the WebLogic Enterprise Administration Server.

Configuring Two-Way SSL

By default, WebLogic Enterprise Security Administration 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 keystore for the server includes the certificate for the trusted certificate authority to be used to sign the certificates for the clients.

To enable two-way SSL:

Configure one-way SSL as described in Configuring One-Way SSL.

Open the Servers folder.

Select the name of the server for which you want to configure two-way SSL (for example, asiAdminServer).

Select the Configuration-->Keystores and SSL tab.

Click the Show link under Advanced Options.

Go to the Server attributes section of the window.

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.

Click Apply.

Log out and restart the Administration Console.

SSL Certificate Validation

WebLogic Enterprise Security must verify all SSL certificates chains. Each CA certificate in a certificate chain must have a Basic Constraint extension defined, that designates it as a Certificate Authority. Any certificate authorities not meeting this criteria are rejected. This section describes the command-line argument that controls the level of certificate validation.

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

To assist you in managing SSL certificate validation, WebLogic Enterprise Security provides mechanisms for setting the level of the SSL certificate validation and for checking whether or not existing certificate chains will be rejected. For more information, see the following topics:

Setting the Level of Certificate Validation

By default, WebLogic Enterprise Security 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:

-Dweblogic.security.SSL.enforceConstraints=option

Table 7-3 describes the options for the command-line argument.

Table 7-3 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. This option does not enforce the IETF RFC 2459 standard. For example: `-Dweblogic.security.SSL.enforceConstraints=strong` or `-Dweblogic.security.SSL.enforceConstraints=true` By default, WebLogic Enterprise Security performs this level of certificate validation.
`strict`	Use this option to check the Basic Constraints extension on the CA certificate is defined as CA and set to critical. This option enforces the IETF RFC 2459 standard. For example: `-Dweblogic.security.SSL.enforceConstraints=strict` This option is not the default because a number of commercially available CA certificates do not conform to the IETF RFC 2459 standard.
`off`	Use this option to disable certificate validation. Use this option carefully. For example, if you purchased CA certificates from a reputable commercial certificate authority and the certificates do not pass the new validation, use this option. However, 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 use of this option in production environment. Instead, purchase new CA certificates that comply with the IETF RFC 2459 standard.

Option

Description

strong or true

Use this option to check that the Basic Constraints extension on the CA certificate is defined as CA. This option does not enforce the IETF RFC 2459 standard.

For example:

-Dweblogic.security.SSL.enforceConstraints=strong

-Dweblogic.security.SSL.enforceConstraints=true

By default, WebLogic Enterprise Security performs this level of certificate validation.

strict

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

For example:

-Dweblogic.security.SSL.enforceConstraints=strict

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

off

Use this option to disable certificate validation. Use this option carefully. For example, if you purchased CA certificates from a reputable commercial certificate authority and the certificates do not pass the new validation, use this option. However, 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 use of this option in production environment. Instead, purchase new CA certificates that comply with the IETF RFC 2459 standard.

Checking Certificate Chains

WebLogic Enterprise Security provides a ValidateCertChain command-line utility to check whether or not an existing certificate chain will be rejected. This 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 and start failing unexpectedly, the problem is mostly likely because the certificate chain used by the Administration 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 (see Checking Certificate Chains) 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.

Specifying the Version of the SSL Protocol

WebLogic Enterprise Security supports both the SSL V3.0 and TLS V1.0 protocols. By default, the WebLogic Enterprise Security uses the SSL V3.0 protocol. While in most cases the SSL V3.0 protocol is acceptable, there are circumstances (such as 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 lets you specify what protocol to use for SSL connections.

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

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 connections can be made using that protocol.

To specify which type of encrypted connection the the Administration Server supports, use the following command-line arguments:

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