Administration Application Guide
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:
The following topics provide some basic information about SSL and the WebLogic Enterprise Security Administration Application.
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.
You can configure SSL to use either one-way or two-way authentication:
WebLogic Enterprise Security uses the following algorithm when it loads its trusted CA certificates:
-Dweblogic.security.SSL.trustedCAkeystore
command-line argument, load the trusted CA certificates from that keystore.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.
To configure SSL in the WebLogic Enterprise Security Administration Server for a production environment, perform the following tasks:
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 keytoo
l 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.
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:
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.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.
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.
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:
To configure Identity and Trust keystores for WebLogic Enterprise Security:
https://
hostname
:port
/console
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
asiAdminServer
).WL_HOME
\server\lib
directory and configured by default and the cacerts
file in the JAVA_HOME\jre\lib\security
directory.JAVA_HOME\jre\lib\security
directory.jks
. If this attribute is not specified, the default keystore type defined in the security policy file for the JDK is used.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:
jks
. If this attribute is not specified, the default keystore type defined in the security policy file for the JDK is used.Use the steps in this section to configure SSL for a production environment.
https://
hostname
:port
/console
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
asiAdminServer
).Information about the demonstration Identity and Trust keystores is displayed in the Keystore Configuration.
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.
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.
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:
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.
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 -pempemcertificatefilename
java utils.ValidateCertChain -pkcs12storepkcs12storefilename
java utils.ValidateCertChain -pkcs12filepkcs12filename
password
java utils.ValidateCertChain -jksalias
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
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:
ValidateCertChain
command-line utility (see Checking Certificate Chains) to check whether the certificate chains will be accepted.-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.
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: