SSL configuration attributes

SSL configurations contain attributes that you use to control the behavior of the server SSL transport layer on Liberty. This topic iterates all the settings available for an SSL configuration.

SSL Feature

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

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

SSL Default

You can have multiple SSL configurations configured. If more than one SSL configuration is configured, then the default SSL configuration must be specified in the server.xml file that uses the sslDefault service configuration.

In the server.xml file, the entry is as follows:

<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 service 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.

Here is an example of how the ssl element is configured 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

The keystore configuration consists of the attributes that are required to load a keystore. These attributes can be set on the keystore service configuration 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 the keystore element is configured 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" />

Through 19.0.0.2, the following example shows how the keystore element is configured 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

Here is an example of 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=" />