12 Configuring SSL

Configuring SSL is an optional step; however, Oracle recommends SSL for production environments. The following sections describe how to configure SSL for WebLogic Server.

Note:

The following sections apply to WebLogic Server deployments that use the security features in this release of WebLogic Server as well as deployments that use Compatibility Security.

All machines must be kept up to date with the current set of recommended patches from the operating system vendors.

SSL: An Introduction

Secure Sockets Layer (SSL) provides secure connections by allowing two applications connecting over a network to authenticate each 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.

Note:

WebLogic Server does not support SSL 2.0.

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

Using SSL is compute 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.

One-Way and Two-Way SSL

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

  • With one-way SSL, the server must present a certificate to the client, but the client is not required to present a certificate to the server. The client must authenticate the server, but the server accepts a connection from any client. 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 in order 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.

Java Secure Socket Extension (JSSE) SSL Implementation Supported

This release of WebLogic Server augments the Certicom SSL implementation in Weblogic Server with an SSL implementation based on Java Secure Socket Extension (JSSE). JSSE is the Java standard framework for SSL and TLS and includes both blocking-IO and non-blocking-IO APIs, and a reference implementation including several commonly-trusted CAs.

The JSSE-based SSL implementation interoperates over SSL with instances of Weblogic Server version 8.1 and later using the Certicom SSL implementation. That is, when WebLogic Server with JSSE SSL is used as either an SSL client or as the SSL server, it can communicate via SSL with instances of WebLogic Server (version 8.1 and later) that use the Certicom SSL implementation.

See Using the JSSE-Based SSL Implementation, for information about using JSSE.

See the Java Secure Socket Extension (JSSE) Reference Guide (http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html) for complete information on JSSE.

Note:

Support for the Certicom SSL implementation is deprecated and will eventually be removed. For this purpose, this release of WebLogic Server continues to support the Certicom SSLPlus Java version 4.0 SSL implementation.

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 WebLogic Server, the CertGen utility, the keytool utility, or a reputable vendor such as Entrust or Verisign to perform this step.

    Note:

    If you use the CertGen utility to generate certificates, see Limitation on CertGen Usage, for information about limitations on its use. Certificates generated by CertGen are for demo purposes only and should not be used in a production environment.
  2. Store the identity and trust. Private keys and trusted CA certificates which specify identity and trust 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. See "Configure keystores" in the Oracle WebLogic Server Administration Console Help.

  4. Set SSL configuration options for the private key alias and password in the WebLogic Server Administration Console. Optionally, set configuration options that require the presentation of client certificates (for two-way SSL). See "Servers: Configuration: SSL" and "Configure two-way SSL" in the Oracle WebLogic Server Administration Console Help.

    Note:

    JSSE in FIPS mode is not supported in this release.

    To enable a WebLogic Server instance to use a FIPS-compliant (FIPS 140-2) crypto module in the server's SSL implementation, make sure that the server start script (for example, startWebLogic.cmd/sh) contains the following:

    • cryptojFIPS.jar is added to the PRE_CLASSPATH variable. Weblogic Server includes and supports RSA Crypto-J 4.1.

    • The command line argument -Dweblogic.security.SSL.nojce=true is specified.

    FIPS 140-2 is a standard that describes U.S. Federal government requirements for sensitive, but unclassified use.

For information about configuring identity and trust for WebLogic Server, see the following sections:

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 a WebLogic Server acting as an SSL 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 accept the SSL connection. If these names do not match, the SSL connection is dropped. The SSL client is the actual party that drops the SSL connection if the names do not match.

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

If you are using the default WebLogic Server host name verifier, host name verification passes if both of the following conditions exist:

  • The host name in the certificate matches the local machine's host name.

  • The URL specifies localhost, 127.0.01, or the default IP address of the local machine.

Note:

If you are using the demo identity certificates in a multi-server domain, Managed Server instances will fail to boot if they are started using the fully-qualified DNS name of the Administration Server. For information about this limitation and suggested workarounds, see Limitation on CertGen Usage.

For more information about using host name verification, see the following topics in the Oracle WebLogic Server Administration Console Help:

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 encryption strength that is allowed

  • 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

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 Transport Layer Security (TLS) specification.

The stack trace dumps information into the log file where the ALERT originated. Therefore, when tracking an SSL problem, you may 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 setting for 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.

Command-Line Properties for Enabling SSL Debugging

Use the following command-line properties to enable SSL debugging:

-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

You can include SSL debugging properties 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 page for the Managed Server.

SSL Debugging When Using JSSE

If WebLogic Server is configured to use the JSSE-based SSL implementation (see Using the JSSE-Based SSL Implementation), additional detailed debug logging may be enabled using the following command-line property:

-Djavax.net.debug=all

Note the following:

  • The -Dssl.debug=true and -Dweblogic.StdoutDebugEnabled=true command-line properties still apply for JSSE. They enable debug logging of the SSL calling code within Weblogic Server.

  • The -Djavax.net.debug=all property enables debug logging within the JSSE-based SSL implementation.

For information about using WebLogic logging properties with the JSSE SSL logging system, see Using Debugging with JSSE SSL.

For information about debugging utilities available for JSSE, see "Debugging Utilities" in the Java™ Secure Socket Extension (JSSE) Reference Guide, available at the following URL:

http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug

SSL Session Behavior

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

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 that use the same host and port share SSL sessions by default, assuming the SSL sockets are using the same underlying SSL context.

Clients that are not configured to use SSL sessions must 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 from SSL socket 1 because 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 used by a previous session can resume a previous session as long as you create the SSL socket using an SSL socket factory from the SSL context that has the SSL session in its cache.

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. You can retrieve the SSL session by 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.

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.

The following command-line arguments are ignored:

  • weblogic.security.SSL.sessionCache.size

  • weblogic.security.SSL.sessionCache.ttl

Configuring RMI over IIOP with SSL

Use SSL to protect Internet Interop-Orb-Protocol (IIOP) connections to Remote Method Invocation (RMI) remote objects. SSL secures connections through authentication and encrypts the data exchanged between objects.

To use SSL to protect RMI over IIOP connections:

  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 RMI for Oracle WebLogic Server.

SSL Certificate Validation

WebLogic Server ensures that each certificate in a certificate chain was issued by a certificate authority. All X509 V3 CA certificates used with WebLogic Server must have the Basic Constraint extension defined as CA, thus ensuring that 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.

Notes:

Note the following:
  • Weblogic Server uses RSA Cert-J 3.1 for certain certificate processing.

  • If WebLogic Server is booted with a certificate chain 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 12-1 describes the options for the command-line argument.

Table 12-1 Options for -Dweblogic.security.SSL.enforceConstraints

Option Description

strong or true

Use this option to ensure 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.

strong_nov1cas

Functions the same as the strong option, described in the preceding row, with the additional constraint that X509 version 1 CA certificates are rejected.

For example:

-Dweblogic.security.SSL.enforceConstraints=strong_nov1cas
strict

Use this option to ensure 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.

strict_nov1cas

Functions the same as the strict option, described in the preceding row, with the additional constraint that X509 version 1 CA certificates are rejected.

For example:

-Dweblogic.security.SSL.enforceConstraints=strict_nov1cas
off

Use this option to turn off checking for the Basic Constraints extension. The rest of the certificate is still validated.

For example:

-Dweblogic.security.SSL.enforceConstraints=off

Oracle does not recommend using this option in a production environment. Instead, purchase new CA certificates that comply with the IETF RFC 2459 standard. CA certificates from most commercial certificate authorities should work with the default strong option.


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

Note:

The weblogic.security.SSL.allowedcertificatepolicyids argument is currently not supported in WebLogic Server when the JSSE-based SSL implementation is enabled.

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

Use the WebLogic Server ValidateCertChain command-line utility to confirm whether an existing certificate chain will be rejected by WebLogic Server. The utility validates 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

Using Certificate Lookup and Validation Providers

WebLogic Server SSL has built-in certificate validation. Given a set of trusted CAs, this validation:

  • Verifies that the last certificate in the chain is either a trusted CA or is issued by a trusted CA.

  • Completes the certificate chain with trusted CAs.

  • Verifies the signatures in the chain.

  • Ensures that the chain has not expired.

You can use certificate lookup and validation (CLV) providers to perform additional validation on the certificate chain. WebLogic Server includes two CLV providers:

  • WebLogic CertPath Provider—Completes certificate paths and validates certificates using the trusted CA configured for a particular server instance, providing the same functionality as the built-in SSL certificate validation. This is configured by default.

  • Certificate Registry—The system administrator makes a list of trusted CA certificates that are allowed access to the server; a certificate is valid if the end certificate is in the registry. The administrator revokes a certificate by removing it from the certificate registry, which is an inexpensive mechanism for performing revocation checking. This is not configured by default.

Alternatively, you can write a custom CertPathValidator to provide additional validation on the certificate chain. See "CertPath Providers" in Developing Security Providers for Oracle WebLogic Server.

How SSL Certificate Validation Works in WebLogic Server

Outbound SSL and two-way inbound SSL in a WebLogic Server instance receive certificate chains during the SSL handshake that must be validated. An example of two-way inbound SSL is a browser connecting to a Web application over HTTPS where the browser sends the client's certificate chain to the Web application. The inbound certificate validation setting is used for all two-way client certificate validation in the server.

Examples of WebLogic Server using outbound SSL (that is, acting as an SSL client) include:

  • Connecting to the Node Manager

  • Connecting to another WebLogic Server instance over the Administration port

  • Connecting to an external LDAP server, such as the LDAPAuthenticator

Using the Administration Console or WLST, you can independently configure inbound and outbound SSL certificate validation using these SSLMBean attributes: InboundCertificateValidation and OutboundCertificateValidation.

Legal values for both attributes are:

  • BUILTIN_SSL_VALIDATION: Use the built-in SSL certificate validation code to complete and validate the certificate chain. That is, configure SSL to work as it has in previous releases. This is the default behavior.

  • BUILTIN_SSL_VALIDATION_AND_CERT_PATH_VALIDATORS: Use the built-in trusted CA-based validation and the configured CertPathValidator providers to perform additional validation. That is, configure SSL to work as it has in previous releases and to do extra validation.

See:

  • "SSLMBean" in the Oracle WebLogic Server MBean Reference

  • "Set Up SSL" in the Oracle WebLogic Server Administration Console Help

Troubleshooting Problems with Certificate Validation

If SSL communications that worked properly in a previous release of WebLogic Server start failing unexpectedly, the likely problem is that the certificate chain 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
    

    Note:

    If WebLogic Server is configured to use the JSSE-based SSL implementation, additional detailed debug logging may be enabled using the following command-line property:

    -Djavax.net.debug=all

    For more information, see SSL Debugging When Using JSSE.

    The following message indicates the SSL failure results from 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 you use one-way SSL, look for this error in the client log. With two-way SSL, look for this error in the client and server logs.

Using the nCipher JCE Provider with WebLogic Server

Note:

Java Cryptography Extension (JCE) providers are written using the application programming interfaces (APIs) in the JCE available in JDK 6.0. 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 affect the performance of Web servers. JCE providers like nCipher that use a hardware card for encryption offload SSL processing from Web servers, which frees the servers to process more transactions. They also provide strong encryption and cryptographic processes 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 6.0. For more information about the features in SunJCE, see the Java™ Cryptography Architecture (JCA) Reference Guide at http://download.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html.

    The JCA framework includes an ability to enforce restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available to applets/applications in different jurisdiction contexts (locations). Any such restrictions are specified in "jurisdiction policy files". For more information, see the Java™ Cryptography Architecture (JCA) Reference Guide.

    WebLogic Server 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 setting will only be able to use the J2SE export strength default cryptography. On the server, WebLogic Server will enable either export or domestic strength cryptography.

  • The nCipher JCE provider. See http://www.ncipher.com.

To install the nCipher JCE provider:

  1. Install and configure the hardware for the nCipher JCE provider according to the product's documentation.

  2. Install the files for the nCipher JCE provider. The following files are required:

    • Jurisdiction policy files—The JDK installs these files by default but they are of limited export strength.

    • 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 JCE provider JAR files

    Choose an installation method for the files:

    • Install files as an extension. Copy the files to one of the following locations:

      JAVA_HOME/jre/lib/ext
      

      For example:

      MW_HOME/jdk160_14/jre/lib/ext
      
    • Install files 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:

    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 that 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=sun.security.rsa.SunRsaSign
    security.provider.3=com.ncipher.provider.km.mCipherKM
    
  4. Boot WebLogic Server.

  5. To ensure the nCipher JCE provider is working properly, enable debugging according to the nCipher product documentation.

Specifying the Version of the SSL Protocol

WebLogic Server supports both the SSL V3.0 and TLS V1.0 protocols. When WebLogic Server is acting as an SSL server, the protocol that the client specifies as preferred in its client hello message is used. Note that WebLogic Server does not support SSL V2.0. When WebLogic Server is acting as an SSL client, it specifies TLS1.0 as the preferred protocol in its SSL V2.0 client hello message, but can use SSL V3.0 as well, if that is 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 some circumstances (compatibility, SSL performance, and environments with maximum security requirements) make the TLS V1.0 protocol more desirable. The weblogic.security.SSL.protocolVersion command-line argument lets you specify which 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. Attempts by clients to establish connections with a prior SSL version will be denied by WebLogic Server, with a denial message returned to the client.

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

  • -Dweblogic.security.SSL.protocolVersion=ALL—This is the default behavior. Only SSL V3.0 and/or TLS V1.0 messages are sent and accepted.

Using the JSSE-Based SSL Implementation

Certicom is currently the default SSL implementation in Weblogic Server. However, JSSE may be enabled as an alternate SSL implementation.

Note:

The Certicom SSL implementation is currently deprecated and will be replaced by the JSSE-based implementation in a future release.

Follow the steps described in this section to use the JSSE-based SSL implementation. The section describes the following topics:

Enabling and Disabling the JSSE-Based SSL Implementation

You can enable and disable the JSSE-based SSL implementation for WebLogic Server in the following ways:

  • From the WebLogic Server Administration Console

  • From the system property

  • Programmatically

You can also enable and disable the JSSE-based SSL implementation for the standalone client from the system property.

These options are described in the sections that follow.

Enable and Disable JSSE-Based SSL for WebLogic Server from the Administration Console

You can enable the JSSE-based SSL implementation through the Administration Console, on the Environment > Servers > ServerName > Configuration > SSL > Advanced page. This affects both outbound and inbound SSL connections.

You then need to restart SSL on the Environment > Servers > ServerName > Control > Start/Stop page.

Enable or Disable the JSSE-Based SSL Implementation for WebLogic Server from the weblogic.ssl.JSSEEnabled System Property

The following server-side system property enables or disables the JSSE-based SSL implementation by initializing the SSLMBean.JSSEEnabled attribute:

-Dweblogic.ssl.JSSEEnabled=true|false

For example, -Dweblogic.ssl.JSSEEnabled=true enables the JSSE-based SSL implementation.

This property affects both outbound and inbound SSL connections.

Enable and Disable the JSSE-Based SSL Implementation for WebLogic Server Programmatically

The SSLMBean has the following pair of setter/getter methods to enable and disable the JSSE-based SSL implementation and to determine whether it is already enabled. These methods affect both outbound and inbound SSL connections.

void setJSSEEnabled(boolean enabled);

boolean isJSSEEnabled();

The change takes effect on the next server restart.

See "SSLMBean" in the Oracle WebLogic Server MBean Reference for complete information on the SSLMBean.

Enable and Disable the JSSE-Based SSL Implementation for a Standalone Client

On standalone clients, use the weblogic.security.SSL.enableJSSE=true|false system property to enable and disable the JSSE-based SSL implementation. The default is false.

System Property Differences Between the JSSE-Based and Certicom SSL Implementations

Table 12-2 shows the differences in how the JSSE-based SSL implementation handles the WebLogic system properties.

Table 12-2 System Properties Differences

System Property JSSE Applicability Description
weblogic.security.SSL.ignoreHostnameVerification

This property continues to work and is not affected by the JSSE integration.

Does not verify the hostname in the URL to the hostname in the certificate.

weblogic.ReverseDNSAllowed

This property continues to work and is not affected by the JSSE integration.

If set to true then use reverse DNS lookup to figure out if urlhostname is a loopback address (“localhost” or “127.0.0.1”, or the IPV6 equivalent.

weblogic.security.SSL.trustedCAKeyStore

This property continues to work and is not affected by the JSSE integration.

Loads the trusted CA certificates from that keystore.

weblogic.security.SSL.verbose

Use this property in combination with javax.net.debug=all to get verbose debug output from the SSL calling code and the JSSE-based implementation.Foot 1 

For additional SSL debugging when -Dssl.debug=true is used.

ssl.debug=true

Use this property in combination with javax.net.debug=ssl to get debug output from the SSL calling code and the JSSE-based implementation.Footref 1

Displays SSL debug information to the console or logs. This property is for the calling WebLogic code. The JSSE-based SSL implementation has its own logging system, which is activated by the javax.net.debug property.

Note: You can set JSSE logging (javax.net.debug) independently of WebLogic SSL logging (ssl.debug).

weblogic.security.SSL.disableJsseCipherSuiteAliases=true|false

The default is false.

Disables the conversion of Certicom cipher suite names to SunJSSE cipher suite names, where applicable. By default, Certicom cipher suite names are converted to JSSE cipher suite names when JSSE is used for SSL.

For a list of Certicom cipher suite names and their SunJSSE equivalents, see Table 12-3.

weblogic.security.SSL.ignoreHostnameVerify

This property continues to work and is not affected by the JSSE integration.

See weblogic.security.SSL.ignoreHostnameVerification

weblogic.security.SSL.HostnameVerifier=classname

This property continues to work and is not affected by the JSSE integration.

Specifies the class name of a custom hostname verification class.

weblogic.security.SSL.protocolVersion=protocol

This property continues to work and is not affected by the JSSE integration.

The supported protocol values are mapped to the corresponding protocols supported by JSSE.

See Specifying the Version of the SSL Protocol.

One of the following:

  • weblogic.security.SSL.allowUnencryptedNullCipher

  • SSLMBean. SetAllowUnencryptedNullCipher(boolean)

  • weblogic.security.disableNullCipher

SunJSSE supports the following two null ciphers, but they are not enabled by default:

  • SSL_RSA_WITH_NULL_MD5

  • SSL_RSA_WITH_NULL_SHA

If this setting is enabled, these two null ciphers are added to the cipher list.

By default, this control is not set and the use of a null cipher is not allowed on the server. In such a configuration, if the SSL clients want to use the null cipher suite (by indicating SSL_RSA_WITH_NULL_MD5 as the only supported cipher suite), the SSL handshake will fail.

If you set this control, the null cipher suite (for example, SSL_RSA_WITH_NULL_MD5) is added to the list of supported cipher suites by the server. The SSL connection has a chance to use the null cipher suite if the client wants to do so. If the null cipher suite is used, the message will be unencrypted.

Caution: Do not set this control in a production environment unless you are aware of the implications and consequences of doing so.

weblogic.security.SSL.enforceConstraints=option

Off is not supported, but other options are supported.

Ensures that the Basic Constraints extension on the CA certificate is defined as CA. See Controlling the Level of Certificate Validation.

weblogic.security.SSL.allowedcertificatepolicyids

Not supported.

WebLogic Server offers limited support for Certificate Policy Extensions in X.509 certificates. See Accepting Certificate Policies in Certificates.

weblogic.security.SSL.nojce

Not supported.

See Setting Up SSL: Main Steps.


Footnote 1 This WebLogic system property is applicable to both the Certicom and JSSE-based SSL implementations. However, for JSSE, this property affects only the SSL calling code, not the JSSE-based implementation. For more information about the javax.net.debug system property and debugging the JSSE-based SSL implementation, see "Debugging Utilities" in the Java Secure Socket Extension (JSSE) Reference Guide at http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug.

Supported Cipher Suites

The set of cipher suites supported by the JDK default JSSE provider, SunJSSE, is available at the following URL:

http://download.oracle.com/javase/6/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider

For backward compatibility, the JSSE-based SSL implementation accepts Certicom cipher suite names for cipher suites that are compatible with SunJSSE. (See "Cipher Suites" in Understanding Security for Oracle WebLogic Server for a list of Certicom cipher suites.) The Certicom cipher suite names are converted for you to SunJSSE equivalents, usually replacing the “TLS_” prefix with “SSL_”, as shown in Table 12-3.

Please keep the following in mind as you consider backward compatibility with Certicom cipher suites:

  • For operations where enabled or supported cipher suites are returned, both the Certicom and SunJSSE names of the cipher suites are returned. (Note that the weblogic.security.SSL.disableJsseCipherSuiteAliases=true property, described in Table 12-2, disables this behavior.)

  • For operations where you specify enabled cipher suites, you can use either the equivalent Certicom cipher suite names, or the SunJSSE names. The Certicom cipher suites, and their SunJSSE equivalents, are listed in Table 12-3.

  • The _DSS_ cipher suites requires certificates signed with DSS, the Digital Signature Standard defined by NIST FIPS Pub 186. DSA is the key generation scheme as described in FIPS 186.

  • The _anon_ cipher suites are disabled by default, and cannot be managed from the WebLogic Server Administration console. To enable one of these cipher suites, configure the <ciphersuite> element in the <ssl> element in the DOMAIN_HOME\server\config\config.xml file, as follows:

    <ssl>
    <name>examplesServer</name>
    <enabled>true</enabled>
    <listen-port>7002</listen-port>
    <ciphersuite>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</ciphersuite>
    ...
    
  • To use the Kerberos cipher suites TLS_KRB5_***, you must have KDC accounts set up. See the Java Secure Socket Extension (JSSE) Reference Guide (http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug) for more details on the Kerberos requirements.

By default, Certicom cipher suite names are converted to SunJSSE cipher suite names when WebLogic Server is configured to use the JSSE-based SSL implementation. Table 12-3 lists each cipher suite supported in the WebLogic Server Certicom SSL implementation and its SunJSSE equivalent. The TLS_ name is the Certicom cipher suite name; the SSL_ name is the equivalent SunJSSE provider cipher suite name.

Table 12-3 Cipher Suite Name Equivalence

Certicom Cipher Suite SunJSSE Equivalent Cipher Suite
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
TLS_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_DHE_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
TLS_DH_anon_WITH_DES_CBC_SHA
SSL_DH_anon_WITH_DES_CBC_SHA
TLS_DH_anon_WITH_RC4_128_MD5
SSL_DH_anon_WITH_RC4_128_MD5
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_RC4_40_MD5
TLS_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA
TLS_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_MD5
TLS_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_RC4_128_SHA

Using Debugging with JSSE SSL

As described in SSL Debugging, SSL debugging provides more detailed information about the SSL events that occurred during an SSL handshake and other operations.

If you debug SSL when the JSSE-based SSL implementation is enabled, you can use the same debug logging properties as when the Certicom SSL implementation is enabled. These logging properties are listed and described in Table 12-2. However, when the JSSE-based SSL implementation is enabled, some properties affect only the SSL calling code and not the JSSE implementation. The JSSE-based SSL implementation has its own logging system, which is activated by the javax.net.debug property. The javax.net.debug property provides multiple levels of control over the amount of output and can be used independently of WebLogic SSL logging (ssl.debug).

See the "Debugging Utilities" section of the Java Secure Socket Extension (JSSE) Reference Guide, available at the following URL, for more details about the javax.net.debug property:

http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug