38 Specifying the SSL Protocol Version

This chapter explains how to configure WebLogic Server 12.1.3 to limit the lowest supported versions of SSL and TLS that are enabled for SSL connections.

This chapter includes the following topics:

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.

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 Chapter 39, "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.1.3 supports only JDK 7 (clients can use JDK 6 or 7) 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.1.3 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

While in most cases the most recent version of the SSL or TLS protocol is desirable, peers may not support it. You may want to specify the enabled SSL or TLS protocol based on circumstances (compatibility, SSL performance, and environments with maximum security requirements) that make the TLS V1 protocol more desirable for enabling acceptable SSL and TLS protocols. Specifying the weblogic.security.SSL.protocolVersion system property in a command-line argument that starts WebLogic Server lets you specify the protocol that 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/7/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.

Caution:

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. 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. For more information, 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 system property as an option in the command line that starts 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. The next section identifies these protocols for the JSSE-based SSL implementation available in WebLogic Server

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