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.

Table 1. Attribute of the sslDefault element . This table describes the attribute of the `sslDefault` element.
Attribute	Description	Default Value
sslRef	The `sslRef` attribute specifies the name of the SSL configuration to be used as the default.	The default SSL Configuration name is `defaultSSLConfig`.

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.

Table 2. Attributes of the keystore element. This table explains the attributes of the `keystore` element.
Attribute	Description	Default Value
id	The id attribute defines a unique identifier of the keystore object.	No default value, a unique name must be specified.
location	The location attribute specifies the keystore file name. The value can include the absolute path to the file. If the absolute path is not provided, then the code looks for the file in the ${server.output.dir}/resources/security directory.	In the SSL minimal configuration, the location of the file is assumed to be ${server.output.dir}/resources/security.
type	The type attribute specifies the type of the keystore. Check that the keystore type that you specify is supported by the SDK you are running on.	The default value is PKCS12. Through 19.0.0.2, the default value is jks.
password	The password attribute specifies the password that is used to load the keystore file. The password can be stored either in clear text or encoded. For information about how to encode the password, see the securityUtility encode option.	Must be provided.
provider	The provider attribute specifies the provider to be used to load the keystore. Some keystore types required a provider other than the SDK default.	By default no provider is specified.
fileBased	The fileBased attribute specifies whether the keystore is file-based.	Default value is true.
pollingRate	The rate at which the server checks for updates to a keystore file.	500ms
updateTrigger	The method that is used to trigger the server to reload a keystore file. Specify polled to enable the server for checking the keystore file for changes, mbean to enable the server to wait for an `mbean` to reload the keystore file, or disabled to disable file monitoring.	mbean

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=" />