Configuring SSL for Liberty

The Liberty profile supports a flexible SSL configuration which allows for multiple SSL settings and multiple keystore definitions. While complex SSL configurations are supported, they are not necessary; Liberty provides for a very simple, easy to use SSL configuration which will help even the most novice application developer get started using HTTPS/SSL with their application.

Using the default, auto-generated certificate

The simplest SSL configuration is the default SSL configuration. The default configuration consists of specifying the SSL feature and defining the default keystore with a password:

<server>
    <featureManager>
        <feature>ssl-1.0</feature>
    </featureManager>

    <keyStore id="defaultKeyStore" password="Liberty" />
</server>

This configuration will cause the server to generate a keystore (if it does not already exist) which contains a self-signed certificate that is valid for 365 days.

Liberty does not expose any configuration to control how the default certificate gets created (to change the validity, subject DN, etc) – this is because the automatically created certificate is not intended for production use.

The default certificate is not intended for production use

The reasons the default certificate is not intended for production use are:

  1. The automatically generated certificate is self-signed. Self-signed certificates are not recommended for use in production.
  2. The duration is 1 year, which is too short for a trusted certificate.
  3. The auto-generation of the certificate is intended for developer convenience only.

Certificates used in production should be properly chained certificates issued or signed by a trusted authority, such as Verisign or Entrust. If you want to use a self-signed certificate with a longer duration, one can be created using the bin\securityUtility createSSLCertificate task.

Run wlp\bin\securityUtility help createSSLCertificate for details.

Default SSL Configurations

The SSL configuration contains attributes that are used to control the behavior of the server SSL transport layer.

The default SSL configuration settings are:

  • When using the IBM JRE the SSL_TLS protocol will used. When using the Oracle JRE is used the SSLv3 protocol is used.
  • The HIGH cipher suites will be used. They include 3DES and 128 bit and higher ciphers.
  • Client authentication is not enabled.

To customize a SSL configuration see the InfoCenter page “Enabling SSL communication for the Liberty Profile” and “Liberty Profile:SSL attributes” for more information on these attributes.

Certificate Management

There is no certificate management or certificate monitoring in the Liberty profile version 8.5.5 or earlier.

Crypto Standards

The IBM JRE is certified to comply with advanced cryptographic standards. When the Liberty profile is running under the IBM JRE it can be configured to run under one of the following security standards:

FIPS 140-2 – The Federal Information Processing Standard (FIPS) Publication 140-2, is a government security standard used to accredit cryptographic modules.

SP800-131a – A special publication put in place by the National Institute of Standards and Technology (NIST) strengthens security by defining which algorithms can be used, and specifies minimum cryptographic strengths.

Suite B – A security standard developed by the National Security Agency (NSA) that establishes a cryptographic interoperability strategy.

You can download the IBM JRE from DeveloperWorks: http://www.ibm.com/developerworks/java/jdk/

Configuring Different Crypto Standards

To configure a Liberty server to run in SP800-131a or SuiteB mode you must be running with a level of the IBM JRE that supports SuiteB. The minimal levels of the IBM JRE include Java 6 SR 10, Java 6.0.1 SR 2, or Java 7.

FIPS 140-2, Suite B and SP800-131a are all mutually exclusive configurations. While it is possible to configure Suite B and FIPS at the same time, Elliptical Curve certificates are not allowed in the FIPS 140-2 configuration and this means the JRE is not running in a FIPS 140-2 compliant configuration.

Steps to configure FIPS 140-2

  1. Make sure you are using the IBM JRE
  2. Edit your JAVA_HOME\jre\lib\security\java.security file and put the com.ibm.crypto.fips.provider.IBMJCEFIPS ahead of the IBMJCE in the provider list.
  3. Add the -Dcom.ibm.jsse2.usefipsprovider=true property to the jvm.options file. This will enable the JSSE2 provider to run in FIPS 140-2 mode.

    This property requires IBM Java SR 10 or later. For more details on enabling FIPS on earlier JVMs, see the IBM JDK InfoCenter page Running IBMJSSE2 in FIPS mode

  4. Your certificates must be at least 1024 in size and can be signed with a DSA or RSA signature algorithm. The keytool utility can be used to generate a compatible keypair:
    keytool -genkey -alias default -keyalg RSA -keysize 1024 -dname CN=example -keystore fips.jks -storepass Liberty -keypass Liberty
  5. Configure your SSL configuration to use the TLS protocol:
    <ssl id="defaultSSLConfig" sslProtocol="TLS" />
  6. There are a list of ciphers that are supported by FIPS 140-2. The default SSL configuration will automatically enable the FIPS 140-2 compliant ciphers when the JSSE is running in FIPS mode. Specific ciphers can be configured by listing them in the enabledCiphers attribute of the SSL configuration.
  7. Common problems:
    • java.lang.RuntimeException: Provider IBMJCEFIPS not found for IBMSecureRandom
      • The IBMJCEFIPS provider is not listed in JAVA_HOME\jre\lib\security\java.security

Steps to configure SP800-131a

The steps to configure SP800-131 are similar to the steps to configure FIPS. See the InfoCenter page “Setting up a Liberty profile to run in SP800-131″ for complete details.

Steps to configure Suite B

SuiteB 128-bit mode

  1. Make sure you are running on a level of the IBM JRE that supports SuiteB
  2. Add the -Dcom.ibm.jsse2.suiteb=128 system property to the jvm.options file to enable the JSSE to run in suiteB 128 mode.
  3. Make sure your server’s certificates meet the criteria for Suite B 128-bit. The keytool utility can be used to generate a compatible keypair:
    keytool -genkey -alias default -sigalg SHA256withECDSA -keyalg EC -keysize 256 -dname CN=example -keystore suiteB128.jks -storepass Liberty -keypass Liberty
    • They have a key length of 256-bit curve.
    • They are signed with SHA256withECDSA signature algorithm.
  4. Configure your SSL configuration to use the TLSv1.2 protocol and to use the TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 cipher:
    <ssl id="defaultSSLConfig" sslProtocol="TLSv1.2" enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" />
  5. Common problems:
    • javax.net.ssl.SSLHandshakeException: Client requested protocol TLSv1 not enabled or not supported
      • The browser in use does not support TLS 1.2. The browser level may not support TLS 1.2 or have it disabled by default. TLS 1.2 support for Internet Explorer 8 and above can be enabled by selecting Tools -> Internet Options -> Advanced -> Settings -> Security -> Use TLS 1.2

SuiteB 192-bit mode

  1. Make sure you are running on a level of the IBM JRE that supports SuiteB
    • Note: to run in Suite B 192-bit mode the IBM JRE’s unrestricted policy must be in place to access the higher algorithms. Information about obtaining the unrestricted policy files can be found on the InfoCenter: IBM SDK Policy files
  2. Add the -Dcom.ibm.jsse2.suiteb=192 system property to the jvm.options file to enable the JSSE to run in suiteB 192 mode.
  3. Make sure your server’s certificates meet the criteria for Suite B 192-bit. The keytool utility can be used to generate a compatible keypair:
    keytool -genkey -alias default -sigalg SHA384withECDSA -keyalg EC -keysize 384 -dname CN=example -keystore suiteB192.jks -storepass Liberty -keypass Liberty
    • They have a key length of 384-bit curve.
    • They are signed with SHA384withECDSA signature algorithm.
  4. Configure your SSL configuration to use the TLSv1.2 protocol and to use the TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 cipher:
    <ssl id="defaultSSLConfig" sslProtocol="TLSv1.2" enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384" />
  5. Common problems:
    • javax.net.ssl.SSLHandshakeException: Client requested protocol TLSv1 not enabled or not supported
      • The browser in use does not support TLS 1.2. The browser level may not support TLS 1.2 or have it disabled by default. TLS 1.2 support for Internet Explorer 8 and above can be enabled by selecting Tools -> Internet Options -> Advanced -> Settings -> Security -> Use TLS 1.2
    • java.lang.IllegalArgumentException: Cannot support TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 with currently installed providers
      • The unrestricted policy files are not in place for the IBM JRE.

Client Authentication

Two modes are supported for client certificate authentication:

  • Supported – the client may present an SSL certificate, although it is not necessary. If the client presents a certificate which is not trusted, the client certificate will be ignored. If the certificate is trusted, it can be used for application authentication.
  • Required – the client must present an SSL certificate which must be trusted by the server. If the certificate is not sent or not trusted, the connection will be rejected.

For details on configuring client authentication, see the InfoCenter page “Configuring your web application and server for client certificate authentication”.

Would you like to know more?

Please see the InfoCenter section “Securing communications with the Liberty profile”