SSL defaults 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.
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.
- Location: The keystore file is called key.p12 and is in the server or clients resources/security directory.
- Keystore type: The keystore type is PKCS12.
- Through 19.0.0.2: Location: The keystore file is called key.jks and is in the server or clients resources/security directory.
- Through 19.0.0.2: Keystore type: The keystore type is JKS.
- Password: Password that is provided in the configuration.
- 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.
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.Whether you use the IBM JRE or the Oracle JRE, the sslProtocol attribute includes the TLSv1, TLSv1.1 and TLSv1.2 protocols. The TLSv1.3 protocol is also included if you use IBM Semeru Runtimes for Java™ 11 or later. For more information about using OpenSSL for cryptographic acceleration with IBM Semeru Runtimes for Java™ 11, see the Semeru Runtimes security migration guide.
- 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
andclientAuthenticationSupported
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.
ssl
element in the configuration as the default SSL
configuration, users can identify that with the sslDefault
element.<sslDefault sslRef="customSSLConfiguration" />
Both (transportSecurity-1.0)
and
(ssl-1.0)
are security processing behaviors. The
transportSecurity-1.0
behavior supersedes the ssl-1.0
behavior in
fix pack 17.0.0.1 and later. Use the transportSecurity-1.0
behavior to employ SSL
options for the outbound connection. If your security configuration does not include options for the
outbound connection, you can continue to use the ssl-1.0
behavior.
- The
(transportSecurity-1.0)
behavior -
When you enable the
transportSecurity-1.0
feature, outbound SSL options become available. You can either set an outbound default with theoutboundSSLRef
attribute on thesslDefault
element or set the SSL filter on the SSL configuration to allow for dynamic outbound connections. The filter consists of either a host or host and port combinations. Based on the host and port of the outbound connection, the outbound connection can match with the SSL configuration.The SSL runtime code does not set the
SSLContext
process default when you enable thetransportSecurity-1.0
feature. The SSL runtime code sets a customSSLSocketFactory
class with thessl.SocketFactory.provider
Java™ security property. TheSSLContext
process default is the SSLContext Java Secure Socket Extension (JSSE) default that uses the cacerts file for the key and trust.The program returns the Liberty custom SSL socket factory to any code that attempts to obtain the
SSLSocketFactory
class default with thejavax.net.ssl.SSLSocketFactory.getDefault()
property. The customSSLSocketFactory
class can resolve the proper SSL configuration for the outbound connection.Features that Liberty provides use Liberty SSL configurations. However, third-party APIs that make outbound SSL calls might require configuration to use Liberty capabilities. The Liberty SSL runtime code does not set theSSLContext
process default when thetransportSecurity-1.0
feature is enabled. Third-party APIs that rely on the default SSL context do not benefit from the Liberty SSL configuration. When thetransportSecurity-1.0
feature is enabled, the Liberty SSL runtime code sets a customSSLSocketFactory
class with thessl.SocketFactory.provider
Java security property. Third-party APIs can benefit from the Liberty SSL configuration with theSocketFactory
default by calling thejavax.net.ssl.SSLSocketFactory.getDefault()
property.Note: The Liberty customSSLSocketFactory
class does not acknowledge Java system properties, such asjavax.net.ssl.keystore
. - The
(ssl-1.0)
behavior -
The attributes from the Liberty default SSL configuration are used to create an
SSLContext
. ThatSSLContext
is set on the process as the defaultSSLContext
by using the Java APISSLContext.setDefault()
. If an application calls to an API likehttpURLConnection()
with an https URL and does not provide any SSL information, then the application picks up the defaultSSLContext
of the process. In this case is theSSLContext
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.
SSL
element to be used as the
default for outbound SSL connections, you can use the outboundSSLRef
attribute on
the sslDefault
element.<feature>transportSecurity-1.0</feature>
<sslDefault sslRef="mySSLConfig" outboundSSLRef="customSSLConfiguration" />
To
specify a default outbound SSL element, the transportSecurity-1.0
feature must be
enabled. When outboundSSLRef
is specified, outbound SSL connections default to
using an SSL configuration that is specified by that attribute. If the
transportSecurity-1.0
feature is missing, then outboundSSLRef
is
ignored. If no outboundSSLRef
attribute is specified, the outbound call uses the
value that is specified by the sslRef
attribute or
defaultSSLConfig
if sslRef
does not reference an SSL
configuration.