38 Specifying the SSL Protocol Version

Learn how to configure Oracle WebLogic Server to limit the lowest supported versions of SSL and TLS that are enabled for SSL connections.

About the SSL Version Used in the Handshake

At the start of the SSL handshake, the SSL peers determine the highest protocol version both peers support. However, you can configure Weblogic Server to limit the lowest supported versions of SSL and TLS that are enabled for SSL connections by using the command-line utility.

To specify the SSL and TLS versions enabled for the SSL handshake, you can set either of the following system properties in the command-line argument that starts WebLogic Server:

  • weblogic.security.SSL.protocolVersion

  • weblogic.security.SSL.minimumProtocolVersion

Note the following regarding SSL protocol support in WebLogic Server:

  • When the JSSE-based SSL implementation is enabled (see Using the JSSE-Based SSL Implementation), SSL protocol support is dependent on the JSSE provider that is installed.

  • When WebLogic Server is acting as an SSL server, the protocol that the client specifies as preferred in its client hello message is used, if supported.

    Note:

    In versions of WebLogic Server prior to 12.1.3, if a client sent an SSLv2Hello, WebLogic Server converted it into an SSLv3Hello. However, WebLogic Server 12.2.1.1.0 supports only JDK 8 (clients can use JDK 7 or 8) and the SSLv2Hello protocol is not supported.

    This means that a client that sends an SSLv2Hello will not be able to connect to a version 12.2.1.1.0 WebLogic Server. Clients must send SSLv3Hello.

    Set weblogic.security.SSL.protocolVersion=SSL3, to force a client to send SSLv3Hello.

  • WebLogic Server does not support SSL V2.0.

Using the weblogic.security.SSL.protocolVersion System Property

You can specify which protocol, SSL or TLS, is used when making SSL connections. Some circumstances such as compatibility, SSL performance, and security requirements make the TLS V1 the better choice.

Use the weblogic.security.SSL.protocolVersion system property as a command-line argument when starting WebLogic Server to specify which protocol is used for SSL connections. The following command-line arguments can be specified so that WebLogic Server supports only SSL V3.0 or TLS connection.

  • -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— This property value enables any protocol starting with "TLS" for messages that are sent and accepted; for example, TLS V1.0, TLS V1.1, and TLS V1.2.

  • -Dweblogic.security.SSL.protocolVersion=ALL—This is the default behavior. If ALL is selected, the default depends on the JSSE provider and JDK version. For the supported protocol version table for Sun JSSE, see http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider.

Note the following:

  • The SSL V3.0 and TLS V1 protocols can not be interchanged. Use only the TLS V1 protocol if you are certain all desired SSL clients are capable of using the protocol.

  • Not setting the weblogic.security.SSL.protocolVersion system property enables the SSLv3Hello, SSLv3, and TLSv1 protocols. In addition, for JSSE, all versions starting with "TLS" are also enabled.

  • If you set valid, supported protocols for the weblogic.security.SSL.minimumProtocolVersion system property, the protocol value you set for weblogic.security.SSL.protocolVersion is ignored.

Note:

  • If you specify the TLS1 or ALL value in this system property, all versions of TLS V1 supported by the SSL provider are enabled for use in SSL connections. The JSSE-based implementation supports TLS V1.0, TLS V1.1, and TLS V1.2.

  • TLS V1.1 is the default minimum protocol version configured in WebLogic Server. Oracle recommends the use of TLS V1.1 or later in a production environment, which is available by using the weblogic.security.SSL.minimumProtocolVersion system property. See Using the weblogic.security.SSL.minimumProtocolVersion System Property.

Using the weblogic.security.SSL.minimumProtocolVersion System Property

In a production environment, Oracle recommends TLS V1.1, or later, for sending and receiving messages in an SSL connection. To control the minimum versions of SSL V3.0 and TLS V1 that are enabled for SSL connections, set the weblogic.security.SSL.minimumProtocolVersion=protocol as a command line option when starting WebLogic Server.

This system property accepts one of the following values for protocol:

Value Description
SSLv3

Specifies SSL V3.0 as the minimum protocol version enabled in SSL connections.

TLSv1

Specifies TLS V1.0 as the minimum protocol version enabled in SSL connections.

TLSvx.y

Specifies TLS Vx.y as the minimum protocol version enabled in SSL connections, where:

  • x is an integer between 1 and 9, inclusive

  • y is an integer between 0 and 9, inclusive

For example, TLSv1.2.

The specific protocols that are enabled by each of the values you can specify for the weblogic.security.SSL.minimumProtocolVersion system property depend upon the SSL implementation with which WebLogic Server is configured.

Protocols Enabled with the JSSE-Based SSL Implementation identifies these protocols for the JSSE-based SSL implementation available in WebLogic Server:

Note:

The weblogic.security.SSL.minimumProtocolVersion system property cannot take effect if the jdk.tls.client.protocols JDK system property is specified.

Protocols Enabled with the JSSE-Based SSL Implementation

When WebLogic Server is configured to use the JSSE-based SSL implementation and you specify a minimum protocol version using the weblogic.security.SSL.minimumProtocolVersion system property, the specific SSL and TLS protocols that are enabled depend on the protocols that are supported in the SSL implementation, as follows:

  • If the particular minimum protocol version you specify is supported, WebLogic Server enables that protocol version and all later protocol versions that are supported.

    For example:

    If you specify . . . . . . and the JSSE-based SSL implementation supports . . . . . . the following protocols are enabled
    TLSv1
    SSLv3
    TLSv1
    TLSv1.1
    TLSv1.2
    TLSv1
    TLSv1.1
    TLSv1.2
  • If the particular minimum protocol version you specify is not supported, Weblogic Server enables the next lower protocol and all later protocols that are supported. Note that the lowest protocol will be limited to SSLv3.

    For example:

    If you specify . . . . . . and the JSSE-based SSL implementation supports . . . . . . the following protocols are enabled
    TLSv1
    SSLv3
    TLSv1.1
    TLSv1.2
    SSLv3
    TLSv1.1
    TLSv1.2
  • If the exact minimum protocol you specify is not supported, and no older (lower) protocol is supported that is SSLv3 or higher, WebLogic Server enables all newer (higher) supported versions. This case usually applies when SSLv3 is set as the minimum.

    For example:

    If you specify . . . . . . and the JSSE-based SSL implementation supports . . . . . . the following protocols are enabled
    SSLv3
    TLSv1
    TLSv1.1
    TLSv1.2
    TLSv1
    TLSv1.1
    TLSv1.2
  • If the particular minimum protocol you specify is invalid, WebLogic Server enables SSLv3 and all later protocol versions that are supported.

    For example:

    If you specify . . . . . . and the JSSE-based SSL implementation supports . . . . . . the following protocols are enabled
    TSLv0
    SSLv3
    TLSv1
    TLSv1.1
    TLSv1.2
    SSLv3
    TLSv1
    TLSv1.1
    TLSv1.2

Using the weblogic.security.ssl.sslcontext.protocol System Property

For some JSSE providers, there is a correlation between the javax.net.ssl.SSLContext algorithm and the initially enabled SSL/TLS protocols. WebLogic Server includes a weblogic.security.ssl.sslcontext.protocol system property that provides the ability to specify a custom javax.net.ssl.SSLContext algorithm for your JSSE provider.

The default protocol setting used with the Oracle JDK JSSE provider is TLS. Some vendors interpret the protocol parameter differently and you may need to change the setting. Refer to the vendor-specific documentation for the correlations between the javax.net.ssl.SSLContext setting and the enabled SSL/TLS protocols.

Note:

When using the IBM JSSE provider, WebLogic Server attempts to select a javax.net.ssl.SSLContext algorithm equivalent to the default TLS.

If a custom javax.net.ssl.SSLContext algorithm is required for use by WebLogic Server, you can set the system property at the command line as follows:

-Dweblogic.security.ssl.sslcontext.protocol=protocol

The protocol parameter is a key for selecting a specific javax.net.ssl.SSLContext algorithm. When set, it overrides the default value. Standard supported values are SSL, SSLv3, TLS, TLSv1, TLSv1.1, and TLSv1.2. See SSLContext Algorithms in Java Cryptography Architecture Standard Algorithm Name Documentation for JDK 8. WebLogic Server does not support SSLv2. Alternatively, you can set the property to a custom value supported by the underlying JSSE provider, however it may affect which SSL/TLS protocol versions are enabled in the TLS connections.