37 Specifying the SSL/TLS 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 that WebLogic Server supports the JSSE-based SSL implementation only. See Using the JSSE-Based SSL Implementation.

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

    Note:

    SSLv3 may be disabled by default in certain JDK updates by the underlying JSSE provider. If so, then enabling SSLv3 in WebLogic Server may not take effect and you will see runtime errors for SSL connections.

    Oracle strongly recommends that you do not use SSLv3. If you want to use SSLv3, then you must remove SSLv3 from the jdk.tls.disabledAlgorithms JDK setting specified in the java.security file, and then enable SSLv3 in WebLogic Server. The java.security file is located in the JDK 8 installation directory under $JAVA_HOME/jre/lib/security.

  • -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, TLS v1.2, and TLS v1.3.

    Note:

    • WebLogic Server supports TLS v1.3 only with JDK 8 Update 261 (JDK 8u261) or later. For earlier JDK versions, TLS v1.3 may not be available.

    • Support for TLS v1.0 and v1.1 is deprecated. Oracle strongly recommends that you do not use TLS v1.0 and v1.1. In addition, these versions may be disabled by default in certain JDK updates by the underlying JSSE provider.

  • -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 TLS v1 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, TLS v1.2, and TLS v1.3. However, WebLogic Server supports TLS v1.3 only with JDK 8 Update 261 (JDK 8u261) or later. For earlier JDK versions, you must use TLS v1.2.

  • TLS v1.1 is the default minimum protocol version configured in WebLogic Server. However, Oracle recommends the use of TLS v1.2 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.2, or later (if supported by the underlying JSSE provider), 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:

Table 37-1 Values of weblogic.security.SSL.minimumProtocolVersion

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 . . . then the following protocols are enabled . . .

    TLSv1

    SSLv3

    TLSv1

    TLSv1.1

    TLSv1.2

    TLSv1.3

    TLSv1

    TLSv1.1

    TLSv1.2

    TLSv1.3

  • 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 . . . then the following protocols are enabled . . .

    TLSv1

    SSLv3

    TLSv1.1

    TLSv1.2

    TLSv1.3

    SSLv3

    TLSv1.1

    TLSv1.2

    TLSv1.3

  • 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 . . . then the following protocols are enabled . . .

    SSLv3

    TLSv1

    TLSv1.1

    TLSv1.2

    TLSv1.3

    TLSv1

    TLSv1.1

    TLSv1.2

    TLSv1.3

  • 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 . . . then the following protocols are enabled . . .

    TSLv0

    SSLv3

    TLSv1

    TLSv1.1

    TLSv1.2

    TLSv1.3

    SSLv3

    TLSv1

    TLSv1.1

    TLSv1.2

    TLSv1.3

Note:

  • WebLogic Server supports TLS v1.3 with JDK 8 Update 261 (JDK 8u261) or later. For earlier JDK versions, TLS v1.3 may not be available.

  • Support for TLS v1.0 and v1.1 is deprecated. Oracle strongly recommends that you do not use TLS v1.0 and v1.1. In addition, these versions may be disabled by default in certain JDK updates by the underlying JSSE provider.

  • Due to its vulnerability to security attacks, SSLv3 may be disabled by default in certain JDK updates by the underlying JSSE provider. If so, then setting SSLv3 using the weblogic.security.SSL.minimumProtocolVersion system property may not take effect. Oracle strongly recommends that you do not use SSLv3. If you want to use SSLv3, then you must remove SSLv3 from the jdk.tls.disabledAlgorithms JDK setting specified in the java.security file, and then enable SSLv3 in WebLogic Server. The java.security file is located in the JDK 8 installation directory under $JAVA_HOME/jre/lib/security.

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, TLSv1.2, and TLSv1.3. 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.

Note:

  • WebLogic Server supports TLS v1.3 with JDK 8 Update 261 (JDK 8u261) or later. If you are running an earlier JDK version, then TLS v1.3 may not be available.

  • Support for TLS v1.0 and v1.1 is deprecated. Oracle strongly recommends that you do not use TLS v1.0 and v1.1. In addition, these versions may be disabled by default in certain JDK updates by the underlying JSSE provider.

  • SSLv3 may be disabled by default in certain JDK updates by the underlying JSSE provider. Oracle strongly recommends that you do not use SSLv3.