Chapter 4. Configuring HTTPS Cipher Suites

Abstract

This chapter explains how to specify the list of cipher suites that are made available to clients and servers for the purpose of establishing HTTPS connections. During a security handshake, the client chooses a cipher suite that matches one of the cipher suites available to the server.

4.1. Supported Cipher Suites

Overview

A cipher suite is a collection of security algorithms that determine precisely how an SSL/TLS connection is implemented.

For example, the SSL/TLS protocol mandates that messages be signed using a message digest algorithm. The choice of digest algorithm, however, is determined by the particular cipher suite being used for the connection. Typically, an application can choose either the MD5 or the SHA digest algorithm.

The cipher suites available for SSL/TLS security in Apache CXF depend on the particular JSSE provider that is specified on the endpoint.

JCE/JSSE and security providers

The Java Cryptography Extension (JCE) and the Java Secure Socket Extension (JSSE) constitute a pluggable framework that allows you to replace the Java security implementation with arbitrary third-party toolkits, known as security providers.

SunJSSE provider

In practice, the security features of Apache CXF have been tested only with SUN’s JSSE provider, which is named SunJSSE.

Hence, the SSL/TLS implementation and the list of available cipher suites in Apache CXF are effectively determined by what is available from SUN’s JSSE provider.

Cipher suites supported by SunJSSE

The following cipher suites are supported by SUN’s JSSE provider in the J2SE 1.5.0 Java development kit (see also Appendix A of SUN’s JSSE Reference Guide):

  • Standard ciphers:

    SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
    SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
    SSL_DHE_DSS_WITH_DES_CBC_SHA
    SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
    SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
    SSL_DHE_RSA_WITH_DES_CBC_SHA
    SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
    SSL_RSA_EXPORT_WITH_RC4_40_MD5
    SSL_RSA_WITH_3DES_EDE_CBC_SHA
    SSL_RSA_WITH_DES_CBC_SHA
    SSL_RSA_WITH_RC4_128_MD5
    SSL_RSA_WITH_RC4_128_SHA
    TLS_DHE_DSS_WITH_AES_128_CBC_SHA
    TLS_DHE_DSS_WITH_AES_256_CBC_SHA
    TLS_DHE_RSA_WITH_AES_128_CBC_SHA
    TLS_DHE_RSA_WITH_AES_256_CBC_SHA
    TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
    TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
    TLS_KRB5_EXPORT_WITH_RC4_40_MD5
    TLS_KRB5_EXPORT_WITH_RC4_40_SHA
    TLS_KRB5_WITH_3DES_EDE_CBC_MD5
    TLS_KRB5_WITH_3DES_EDE_CBC_SHA
    TLS_KRB5_WITH_DES_CBC_MD5
    TLS_KRB5_WITH_DES_CBC_SHA
    TLS_KRB5_WITH_RC4_128_MD5
    TLS_KRB5_WITH_RC4_128_SHA
    TLS_RSA_WITH_AES_128_CBC_SHA
    TLS_RSA_WITH_AES_256_CBC_SHA
  • Null encryption, integrity-only ciphers:

    SSL_RSA_WITH_NULL_MD5
    SSL_RSA_WITH_NULL_SHA
  • Anonymous Diffie-Hellman ciphers (no authentication):

    SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
    SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
    SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
    SSL_DH_anon_WITH_DES_CBC_SHA
    SSL_DH_anon_WITH_RC4_128_MD5
    TLS_DH_anon_WITH_AES_128_CBC_SHA
    TLS_DH_anon_WITH_AES_256_CBC_SHA

JSSE reference guide

For more information about SUN’s JSSE framework, please consult the JSSE Reference Guide at the following location:

http://download.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html

4.2. Cipher Suite Filters

Overview

In a typical application, you usually want to restrict the list of available cipher suites to a subset of the ciphers supported by the JSSE provider.

Generally, you should use the sec:cipherSuitesFilter element, instead of the sec:cipherSuites element to select the cipher suites you want to use.

The sec:cipherSuites element is not recommended for general use, because it has rather non-intuitive semantics: you can use it to require that the loaded security provider supports at least the listed cipher suites. But the security provider that is loaded might support many more cipher suites than the ones that are specified. Hence, when you use the sec:cipherSuites element, it is not clear exactly which cipher suites are supported at run time.

Namespaces

Table 4.1, “Namespaces Used for Configuring Cipher Suite Filters” shows the XML namespaces that are referenced in this section:

Table 4.1. Namespaces Used for Configuring Cipher Suite Filters

sec:cipherSuitesFilter element

You define a cipher suite filter using the sec:cipherSuitesFilter element, which can be a child of either a http:tlsClientParameters element or a httpj:tlsServerParameters element. A typical sec:cipherSuitesFilter element has the outline structure shown in Example 4.1, “Structure of a sec:cipherSuitesFilter Element” .

Example 4.1. Structure of a sec:cipherSuitesFilter Element

<sec:cipherSuitesFilter>
    <sec:include>RegularExpression</sec:include>
    <sec:include>RegularExpression</sec:include>
    ...
    <sec:exclude>RegularExpression</sec:exclude>
    <sec:exclude>RegularExpression</sec:exclude>
    ...
</sec:cipherSuitesFilter>

Semantics

The following semantic rules apply to the sec:cipherSuitesFilter element:

  1. If a sec:cipherSuitesFilter element does not appear in an endpoint’s configuration (that is, it is absent from the relevant http:conduit or httpj:engine-factory element), the following default filter is used:

    <sec:cipherSuitesFilter>
        <sec:include>.*_EXPORT_.*</sec:include>
        <sec:include>.*_EXPORT1024.*</sec:include>
        <sec:include>.*_DES_.*</sec:include>
        <sec:include>.*_WITH_NULL_.*</sec:include>
    </sec:cipherSuitesFilter>
  2. If the sec:cipherSuitesFilter element does appear in an endpoint’s configuration, all cipher suites are excluded by default.
  3. To include cipher suites, add a sec:include child element to the sec:cipherSuitesFilter element. The content of the sec:include element is a regular expression that matches one or more cipher suite names (for example, see the cipher suite names in the section called “Cipher suites supported by SunJSSE”).
  4. To refine the selected set of cipher suites further, you can add a sec:exclude element to the sec:cipherSuitesFilter element. The content of the sec:exclude element is a regular expression that matches zero or more cipher suite names from the currently included set.

    Note

    Sometimes it makes sense to explicitly exclude cipher suites that are currently not included, in order to future-proof against accidental inclusion of undesired cipher suites.

Regular expression matching

The grammar for the regular expressions that appear in the sec:include and sec:exclude elements is defined by the Java regular expression utility, java.util.regex.Pattern. For a detailed description of the grammar, please consult the Java reference guide, http://download.oracle.com/javase/1.5.0/docs/api/java/util/regex/Pattern.html.

Client conduit example

The following XML configuration shows an example of a client that applies a cipher suite filter to the remote endpoint, {WSDLPortNamespace}PortName. Whenever the client attempts to open an SSL/TLS connection to this endpoint, it restricts the available cipher suites to the set selected by the sec:cipherSuitesFilter element.

<beans ... >
  <http:conduit name="{WSDLPortNamespace}PortName.http-conduit">
    <http:tlsClientParameters>
      ...
      <sec:cipherSuitesFilter>
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
    </http:tlsClientParameters>
  </http:conduit>

  <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl"/>
</beans>

4.3. SSL/TLS Protocol Version

Overview

The versions of the SSL/TLS protocol that are supported by Apache CXF depend on the particular JSSE provider configured. By default, the JSSE provider is configured to be SUN’s JSSE provider implementation.

Warning

If you enable SSL/TLS security, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566). For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x.

SSL/TLS protocol versions supported by SunJSSE

Table 4.2, “SSL/TLS Protocols Supported by SUN’s JSSE Provider” shows the SSL/TLS protocol versions supported by SUN’s JSSE provider.

Table 4.2. SSL/TLS Protocols Supported by SUN’s JSSE Provider

ProtocolDescription

SSLv2Hello

Do not use! (POODLE security vulnerability)

SSLv3

Do not use! (POODLE security vulnerability)

TLSv1

Supports TLS version 1

TLSv1.1

Supports TLS version 1.1 (JDK 7 or later)

TLSv1.2

Supports TLS version 1.2 (JDK 7 or later)

Excluding specific SSL/TLS protocol versions

By default, all of the SSL/TLS protocols provided by the JSSE provider are available to the CXF endpoints (except for the SSLv2Hello and SSLv3 protocols, which have been specifically excluded by the CXF runtime since Fuse version 6.2.0, because of the Poodle vulnerability (CVE-2014-3566)).

To exclude specific SSL/TLS protocols, use the sec:excludeProtocols element in the endpoint configuration. You can configure the sec:excludeProtocols element as a child of the httpj:tlsServerParameters element (server side).

To exclude all protocols except for TLS version 1.2, configure the sec:excludeProtocols element as follows (assuming you are using JDK 7 or later):

<?xml version="1.0" encoding="UTF-8"?>
<beans ... >
  ...
  <httpj:engine-factory bus="cxf">
    <httpj:engine port="9001">
      ...
      <httpj:tlsServerParameters>
        ...
        <sec:excludeProtocols>
          <sec:excludeProtocol>SSLv2Hello</sec:excludeProtocol>
          <sec:excludeProtocol>SSLv3</sec:excludeProtocol>
          <sec:excludeProtocol>TLSv1</sec:excludeProtocol>
          <sec:excludeProtocol>TLSv1.1</sec:excludeProtocol>
        </sec:excludeProtocols>
      </httpj:tlsServerParameters>
    </httpj:engine>
  </httpj:engine-factory>
  ...
</beans>
Important

It is recommended that you always exclude the SSLv2Hello and SSLv3 protocols, to protect against the Poodle vulnerability (CVE-2014-3566).

secureSocketProtocol attribute

Both the http:tlsClientParameters element and the httpj:tlsServerParameters element support the secureSocketProtocol attribute, which enables you to specify a particular protocol.

The semantics of this attribute are confusing, however: this attribute forces CXF to pick an SSL provider that supports the specified protocol, but it does not restrict the provider to use only the specified protocol. Hence, the endpoint could end up using a protocol that is different from the one specified. For this reason, the recommendation is that you do not use the secureSocketProtocol attribute in your code.