SSL configuration attributes

SSL configurations contain attributes that you use to control the behavior of the server SSL transport layer on Liberty.

TLS feature

To enable SSL on a server, the Transport Security feature must be included in the server.xml file:

<featureManager>
  <feature>transportSecurity-1.0</feature>
</featureManager>

SSL default

You can specify multiple SSL configurations. If more than one SSL configuration exists, you must specify the default SSL configuration in the server.xml file by using the sslDefault element.

<sslDefault sslRef="mySSLSettings" />

SSL configuration

You use the SSL configuration attributes to customize the SSL environment to suit your needs. These attributes can be set on the ssl configuration element in the server.xml file.

For a list of the attributes of the ssl element, see SSL Repertoire.

Note:

The key manager is used by the SSL handshake to determine what certificate alias to use. The key manager is not configured in the server.xml file. It is retrieved from the security property ssl.KeyManagerFactory.algorithm of the SDK.
The trust manager is used by the SSL handshake to make trust decisions. The trust manager is not configured in the server.xml file. It is retrieved from the security property ssl.TrustManagerFactory.algorithm of the SDK.

The following example shows how to configure the ssl element in the server.xml file:

<!--  Simple ssl configuration service object. This assumes there is a keystore object named -->
<!--  defaultKeyStore and a truststore object named defaultTrustStore in the server.xml file. -->
  <ssl id="myDefaultSSLConfig"
       keyStoreRef="defaultKeyStore"
       trustStoreRef="defaultTrustStore" />


<!--  A ssl configuration service object that enabled clientAuthentication -->
<!--  and specifies the TLS protocol be used. -->
  <ssl id="myDefaultSSLConfig"
       keyStoreRef="defaultKeyStore"
       trustStoreRef="defaultTrustStore"
       clientAuthentication="true"
       sslProtocol="TLS" />

<!-- An SSL configuration service object that names the serverKeyAlias -->
<!-- to be used by the handshake. This assumes there is a certificate -->
<!-- called "default" in the keystore defined by keyStoreRef. -->
  <ssl id="myDefaultSSLConfig"
       keyStoreRef="defaultKeyStore"
       serverKeyAlias="default" />

Keystore configuration

You can specify the key store configuration on the keyStore element in the server.xml file.

Keystore files can be reloaded by the server if the updateTrigger attribute is set to polled or mbean. If polled is enabled, then the server monitors the keystore file for changes based on the rate set in the pollingRate attribute. If the updateTrigger attribute is set to, mbean then the server will reload the keystore file when it receives notification from the WebSphere:service=com.ibm.ws.kernel.filemonitor.FileNotificationMBean MBean. File monitoring is disabled by default.

The following example shows how to configure the keystore element in the server.xml file:

<!-- A keystore object called defaultKeyStore provides a location, -->
<!-- type, and password. The MyKeyStoreFile.p12 file is assumed -->
<!-- to be located in ${server.output.dir}/resources/security -->
<!-- This keystore is configured to be monitored every 5 seconds -->
<!-- for updates -->
   <keyStore id="defaultKeyStore"
           location="MyKeyStoreFile.p12"
           type="PKCS12" password="myPassword"
           pollingRate="5s"
           updateTrigger="polled" />

<!-- A keystore object called defaultKeyStore provides a location, -->
<!-- type, and password. The MyKeyStoreFile.p12 file is assumed -->
<!-- to be located in ${server.output.dir}/resources/security -->
<!-- This keystore is configured to be reloaded when the server -->
<!-- recieves an mbean notification to do so -->
   <keyStore id="defaultKeyStore"
           location="MyKeyStoreFile.p12"
           type="PKCS12" password="myPassword"
           updateTrigger="mbean" />

In version 19.0.0.2 and earlier, the following example shows how to configure the keystore element in the server.xml file:

<!-- A keystore object called defaultKeyStore provides a location, -->
<!-- type, and password. The MyKeyStoreFile.jks file is assumed -->
<!-- to be located in ${server.output.dir}/resources/security -->
<!-- This keystore is configured to be monitored every 5 seconds -->
<!-- for updates -->
   <keyStore id="defaultKeyStore"
           location="MyKeyStoreFile.jks"
           type="JKS" password="myPassword"
           pollingRate="5s"
           updateTrigger="polled" />

<!-- A keystore object called defaultKeyStore provides a location, -->
<!-- type, and password. The MyKeyStoreFile.jks file is assumed -->
<!-- to be located in ${server.output.dir}/resources/security -->
<!-- This keystore is configured to be reloaded when the server -->
<!-- recieves an mbean notification to do so -->
   <keyStore id="defaultKeyStore"
           location="MyKeyStoreFile.jks"
           type="JKS" password="myPassword"
           updateTrigger="mbean" />

If you do not set the server.output.dir directory, then the server.output.dir directory is the same as the server.config.dir directory.

Full SSL configuration example

The following example shows a full SSL configuration in the server.xml file. This example has the following SSL configurations:

defaultSSLSettings
mySSLSettings

By default, the SSL configuration is set to defaultSSLConfig.

<featureManager>
  <feature>transportSecurity-1.0</feature>
</featureManager>


<!-- default SSL configuration is defaultSSLSettings ->
  <sslDefault sslRef="defaultSSLSettings" />
  <ssl id="defaultSSLSettings"
       keyStoreRef="defaultKeyStore"
       trustStoreRef="defaultTrustStore"
       clientAuthenticationSupported="true" />
  <keyStore id="defaultKeyStore"
            location="key.jks"
            type="JKS" password="defaultPWD" />
  <keyStore id="defaultTrustStore"
            location="trust.jks"
            type="JKS" password="defaultPWD" />

  <ssl id="mySSLSettings"
       keyStoreRef="myKeyStore"
       trustStoreRef="myTrustStore"
       clientAuthentication="true" />
  <keyStore id="LDAPKeyStore"
            location="${server.config.dir}/myKey.p12"
            type="PKCS12"
            password="{xor}CDo9Hgw=" />
  <keyStore id="LDAPTrustStore"
            location="${server.config.dir}/myTrust.p12"
            type="PKCS12"
            password="{xor}CDo9Hgw=" />