1. Administering Security for Oracle WebLogic Server
  2. Configuring SSL
  3. Using the JSSE-Based SSL Implementation

37 Using the JSSE-Based SSL Implementation

Learn how to use the JSSE-based SSL implementation, understand the support cipher suites and the differences in the Certicom-based implementation of JSSE, and how to use the RSA JSSE provided with Oracle WebLogic Server.

Note:

Note the following:

  • As of WebLogic Server version 12.1.1, JSSE is the only SSL implementation that is supported. The Certicom-based SSL implementation is removed and is no longer supported in WebLogic Server.

  • SHA-2 signed certificates are supported in the JSSE SSL implementation provided in WebLogic Server.

  • Although JSSE supports Server Name Indication (SNI) in its SSL implementation, WebLogic Server does not support SNI.

This chapter includes the following sections:

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

Learn the differences in how the JSSE and Certicom SSL implementations handle the WebLogic security system properties.

Table 37-1 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.Foot 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 37-2.

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 SSL/TLS Protocol Version.

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://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug.

SSL Performance Considerations

When WebLogic Server is configured with JDK 8, the out-of-the-box SSL performance may be slower than in previous WebLogic Server releases. This performance change is due to the stronger cipher and MAC algorithm used by default when JDK 8 is used with the JSSE-based SSL provider in WebLogic Server. You can disable the stronger ciphers that are used by default for SSL connections.

Specifically, AES is used for encryption, and SHA-2 is used for hashes. (This cipher combination is typically designated as AES + SHA-2 here; that is, cipher + MAC algorithm.)

Previous versions of WebLogic Server used the RC4 and MD5 cipher combination (RC4 + MD5) for SSL connections. In terms of performance, AES + SHA-2 is slower than RC4 + MD5. Although AES + SHA-2 is recommended, you can configure WebLogic Server to restrict the stronger ciphers and cause RC4 + MD5 to be used instead for SSL. Although RC4 + MD5 is less secure than AES + SHA-2, it may be acceptable depending on the security requirements of a particular WebLogic Server environment.

Note:

Oracle strongly recommends the stronger security provided by AES + SHA-2 for SSL connections.

To configure WebLogic Server to use RC4 + MD5, add the following property to the file JAVA_HOME/jre/lib/security/java.security: 

jdk.tls.disabledAlgorithms=AES, DESede, DES, SHA1, SHA

The preceding property disables the stronger ciphers that are used by default for SSL connections and allows RC4 + MD5 to be used instead.

Cipher Suites

Learn about the cipher suites supported by WebLogic Server, using anonymous ciphers, and setting cipher suites using WLST.

This topic includes the following sections:

List of Supported Cipher Suites

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

Deprecated Cipher Suites

Per Oracle security guidelines, the TLS cipher suites that are prefixed with TLS_RSA_ or contain _CBC_ are deprecated and are disabled by default. These disabled cipher suites are weak and do not provide sufficient security for your system. However, if necessary for your environment, you can enable these TLS cipher suites using any of the following methods:

  • Set the ExcludedCiphersuites attribute on the weblogic.management.configuration.SSLMBean MBean to an array that contains just one empty string. For example new String[]{""}.

  • Set the MinimumTLSProtocolVersion attribute on the weblogic.management.configuration.SSLMBean MBean to TLSv1.1 or earlier.

  • Set the system property -Dweblogic.security.SSL.minimumProtocolVersion to TLSv1.1 or earlier in the Java command that starts WebLogic Server.

  • Set the system property -Dweblogic.security.SSL.protocolVersion in the Java command that starts WebLogic Server. See Using the weblogic.security.SSL.protocolVersion System Property.

Backward Compatibility of Supported Cipher Suites

For backward compatibility, the JSSE-based SSL implementation accepts Certicom cipher suite names for cipher suites that are compatible with SunJSSE. The Certicom cipher suite names are converted for you to SunJSSE equivalents, usually replacing the "TLS_" prefix with "SSL_", as shown in Table 37-2.

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

  • With JSSE, the cipher suites selected by default are stronger as compared to Certicom SSL and have slower performance. The security policies in your environment typically set the requirements for the cipher suites that must be used. However, for highly secure environments, using the strongest available cipher that provides acceptable performance is recommended.

  • 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 37-1, 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 37-2. (Oracle does not encourage future use of Certicom cipher suite names.)

  • 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. You must use WLST instead, as described in Setting Cipher Suites Using WLST: An Example.

  • 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://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#KRB) for more details on the Kerberos requirements.

  • The TLS DES cipher suites have been disabled at the JSSE provider level by default. See the Oracle JRE and JDK Cryptographic Roadmap at https://java.com/en/jre-jdk-cryptoroadmap.html.

Using Anonymous Ciphers

The following anonymous ciphers are not supported out-of-the-box in the JSSE-based WebLogic SSL implementation in WebLogic Server:

  • TLS_DH_anon_WITH_3DES_EDE_CBC_SHA

  • TLS_DH_anon_WITH_RC4_128_MD5

  • TLS_DH_anon_WITH_DES_CBC_SHA

  • TLS_DH_anon_EXPORT_WITH_RC4_40_MD5

  • TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA

However, if you want to enable any of the preceding anonymous ciphers, include the following argument in the Java command that starts WebLogic Server:

-Dweblogic.security.SSL.AllowAnonymousCipher=true

In most cases, enabling anonymous ciphers is required when WebLogic Server, or its deployed application, acts as a SSL client that is making an outbound connection to an SSL server (for example, an LDAP server or RDBMS system) that is configured to use anonymous ciphers only. A typical use case is connecting to an Oracle Internet Directory instance that is configured in no-auth mode.

Note:

Oracle does not recommend the use of anonymous ciphers in production environments.

Cipher Suite Name Equivalents

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 37-2 lists each cipher suite supported in the (removed) 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 37-2 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

Setting Cipher Suites Using WLST: An Example

The following example shows a WLST script that sets the cipher suites SSL_RSA_WITH_RC4_128_MD5, SSL_RSA_WITH_RC4_128_SHA, and SSL_RSA_WITH_3DES_EDE_CBC_SHA. After this script is run, the cipher suites are set in the domain configuration (that is, the config.xml file) and the SSL listeners are restarted with the new cipher suite settings.

Note:

For clarity, this WLST example script shows the username and password in clear text. However, you should avoid entering clear-text passwords in WLST commands in general, and you should especially avoid saving on disk WLST scripts that include clear-text passwords. In these instances you should use a mechanism for passing encrypted passwords instead. See Security for WLST in Understanding the WebLogic Scripting Tool. 
url="t3://localhost:7001"
adminUsername="weblogic"
adminPassword="password"
connect(adminUsername, adminPassword, url)
edit()
server=cmo.lookupServer('myserver')
cd('Servers')
cd('myserver')
startEdit()
cd('SSL')
cd('myserver')
ssl = server.getSSL()
ciphers = ['SSL_RSA_WITH_RC4_128_MD5', 'SSL_RSA_WITH_RC4_128_SHA', 'SSL_RSA_WITH_3DES_EDE_CBC_SHA']
ssl.setCiphersuites(ciphers)
save()
activate()
disconnect()
exit()

An Important Note Regarding Null Cipher Use in SSL

A cipher suite is an SSL encryption method that includes the key exchange algorithm, the symmetric encryption algorithm, and the secure hash algorithm. A cipher suite is used to protect the integrity of a communication. For example, the cipher suite called RSA_WITH_RC4_128_MD5 uses RSA for key exchange, RC4 with a 128-bit key for bulk encryption, and MD5 for message digest.

SSL clients start the SSL handshake by connecting to the server. As part of the connection, the client sends the server a list of the cipher suites it supports. The server then selects a mutually-supported cipher suite from the list supplied by the client for the client and server to use for this session.

However, an incorrectly configured client might specify a set of cipher suites that contain only null ciphers. A null cipher passes data on the wire in clear-text. (An example of a cipher suite with a null cipher is SSL_RSA_WITH_NULL_MD5.) Using a null cipher makes it possible to see the SSL messages by using a network packet sniffer. In essence, SSL is used but does not provide any security.

The server selects the null cipher only when it is the only cipher suite they have in common. If the server selects a null cipher from the client's cipher suite list, the log contains the following message: SSL has established a session that uses a Null cipher.

This message is output only when the server has selected a null cipher from the client's list.

Note:

If there is any potential whatsoever that an SSL client might use a null cipher to inappropriately connect to the server, you should check the log file for this message. It is recommended that new client configurations be given extra attention with respect to the use of a null cipher to ensure that they are properly configured.

It is unlikely that an existing client configuration would suddenly start using null ciphers if it had not been doing so previously. However, an existing client configuration that is unknowingly configured incorrectly could be using null ciphers.

Other SSL errors unrelated to null ciphers are possible as well, and each will display an appropriate error message in the log.

See Configuring SSL. For information on viewing log files, see View and configure logs in the Oracle WebLogic Server Administration Console Online Help.

WebLogic Server Control to Prevent Null Cipher Use

As of release 10g Release 3 (10.3), WebLogic Server includes a WebLogic Server Administration Console control to prevent the server from using a null cipher.

The Allow Unencrypted Null Cipher control, which is available in the WebLogic Server Administration Console by selecting Servers > ServerName > Configuration > SSL > Advanced, determines whether null ciphers are allowed. 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.

This control is also exposed as a system runtime parameter, weblogic.security.SSL.allowUnencryptedNullCipher, and as an AllowUnencryptedNullCipher attribute on the SSLMBean.

Note:

TLS anon and NULL cipher suites are disabled by default in the JDK.

Using Debugging with JSSE SSL

JSSE SSL debugging provides detailed information about the SSL events that occurred during an SSL handshake and other operations.See SSL Debugging.

If you debug SSL when the JSSE-based SSL implementation is enabled, you can use the logging properties listed and described in Table 37-1. However, 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://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug

Using the RSA JSSE Provider in WebLogic Server

RSA JSSE is a third-party JSSE provider that can be statically registered in the JVM if you wish to use it. Learn how to install and configure RSA JSSE provider in non-FIPS mode.

Note:

This section describes using the RSA JSSE provider in non-FIPS mode. You can also use the RSA JSSE provider in FIPS mode as described in Enabling FIPS Mode.

To install and configure the RSA JSSE provider, complete the following steps:

  1. Using the following URL, download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files that correspond to the version of your JDK. These Java policy JAR files affect cipher key sizes greater than 128 bits. 
    https://www.oracle.com/java/technologies/javase-jce-all-downloads.html

    Open the .ZIP distribution and update local_policy.jar and US_export_policy.jar in JAVA_HOME/jre/lib/ security. See the README.txt file in the .ZIP distribution for more information and installation instructions.

    Note: You can skip this step if you are running WebLogic Server on JDK 8u161 or later. On JDK 8u161 and later, stronger cryptographic algorithms are available by default.
  2. Using a text editor, modify the file JAVA_HOME/jre/lib/security/java.security by making the RSA JSSE provider, com.rsa.jsse.JsseProvider, as the first provider in the list.

    For example, before making this update, the list of providers might appear as follows:

    #
# List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=com.sun.security.sasl.Provider
security.provider.7=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.8=sun.security.smartcardio.SunPCSC
security.provider.9=sun.security.mscapi.SunMSCAPI

    After you add the RSA JSSE provider, the list might appear as follows:

    #
# List of providers and their preference orders (see above):
#
security.provider.1=com.rsa.jsse.JsseProvider
security.provider.2=sun.security.provider.Sun
security.provider.3=sun.security.rsa.SunRsaSign
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider
security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.9=sun.security.smartcardio.SunPCSC
security.provider.10=sun.security.mscapi.SunMSCAPI

    That is, you need to update the sequence number of each subsequent provider. For example, security.provider.1=sun.security.provider.Sun is changed to security.provider.2=sun.security.provider.Sun (change shown in bold).

  3. Add the SSL-J jar WL_HOME/server/lib/sslj.jar at the head of the classpath. You can use the PRE_CLASSPATH environment variable to do this.

    For example, you could set sslj.jar in the PRE_CLASSPATH variable before you call the server start script, typically startWebLogic.cmd/sh: 

    set PRE_CLASSPATH=%ORACLE_HOME%\wlserver\server\lib\sslj.jar
  4. Restart WebLogic Server for the change to the RSA JSEE provider to take effect.