SSL defaults in Liberty

Specifies the default SSL certificate, keystore, and configuration in Liberty.

Default Certificate and keystore

As a convenience tool to help developers get up and running, users can use the createSSLCertificate parameter in the securityUtility command to create self-signed certificates. Users can either call the tool directly from the command line or allow the server to call it to create the default certificate and keystore on server startup.

The server creates the default keystore and certificate if a user has a keystore element that is called defaultKeyStore in the server.xml file. For example:
<keyStore id="defaultKeyStore" password="yourPassword" />

If a keystore configuration for the defaultKeyStore is in place and the keystore does not exist when the server starts, the server calls the createSSLCertificate parameter. This parameter creates the keystore with a password that is specified in the configuration.

Default keystore details:
  • Location: The keystore file is called key.jks and is in the server or clients resources/security directory.
  • Keystore type: The keystore type is JKS.
  • Password: Password that is provided in the configuration.
Default certificate that is created by Liberty details:
  • Type: The certificate is a self-signed certificate.
  • Size: The default certificate size is 2048.
  • Signature algorithm: The signature algorithm for the certificate is SHA256WITHRSA.
  • Validity: The certificate is valid for 365 days.
  • SubjectDN: The certificate gets created with CN=<hostname>,OU=<client or server name>,O=ibm,C=US as the SubjectDN.

The createSSLCertificate parameter can be called on the command line if users would like to customize the certificate.

Note: The self-signed certificates that are created by a stand-alone Liberty server are not intended for production use. They are created as a developer convenience. They are no less secure than certificates issued by a trusted certificate authority. However, certificates that are used in production must be properly chained certificates that are issued or signed by a trusted certificate authority. The chained certificates that are issued by the Collective Controller to members are signed certificates.

Default SSL configuration

The minimal configuration that is needed for SSL is a single keystore element called defaultKeyStore. When the defaultKeyStore exists in the configuration, the run time builds an SSL configuration that is called defaultSSLConfig around it.

defaultSSLConfig details:

  • Protocol: When the IBM® JRE is used, the protocol is set to SSL_TLSv2 by default. If the Oracle JRE is used, SSL is used as the protocol.
  • Ciphers: The cipher list is built by getting a list of supported ciphers from the underlying JRE. By default, the list is reduced to all the ciphers that are 128 bit and higher or 3DES. RC4 is removed because having them enabled is not considered to be safe.ECDHE ciphers are removed because they can cause errors if you are going to a server that does not support them. The cipher list can be customized to include them.
  • Client authentication: By default clientAuthentication and clientAuthenticationSupported are disabled.
  • Keystore: In the default configuration, the defaultKeyStore is used as both the key and truststore.

An SSL element that is called defaultSSLConfig can be entered in the server.xml file for customization of the SSL configuration properties. A customized ssl element that is called defaultSSLConfig is still treated like the default SSL configuration when a different SSL configuration is not identified as the default. For more information, see SSL configuration attributes.

To designate a different ssl element in the configuration as the default SSL configuration, users can identify that with the sslDefault element.
<sslDefault sslRef="customSSLConfiguration" />

The attributes from the Liberty default SSL configuration are used to create an SSLContext. That SSLContext is set on the process as the default SSLContext by using the Java™ API SSLContext.setDefault(). If an application calls to an API like httpURLConnection() with an https URL and does not provide any SSL information, then the application picks up the default SSLContext of the process. In this case is the SSLContext that is created with the Liberty default SSL configuration.

Liberty uses the JSSE's default SSLContext if a default SSL configuration is not set in Liberty. The JSSE's default SSLContext uses the cacerts file for the keystore and truststore. Liberty does not have a default SSL configuration if the SSL feature is not defined, or if the SSL configuration that exists is not identified as the default. The default configuration is either called defaultSSLConfig, which can be implicit if a defaultKeyStore is defined or an alternative SSL configuration can be designated by using the sslDefault element.

The javax system properties, javax.net.ssl.keystore is used to set up the keystore and truststore information for the default SSL context and must not be used. If the properties are set on the process, then the call to SSLContext.setDefault() wipes them out.


Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: Saturday, 3 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwlp_liberty_ssl_defaults
File name: rwlp_liberty_ssl_defaults.html