SSL configuration attributes

SSL configuration attributes

SSL configurations contain attributes that we use to control the behavior of the server SSL transport layer on a Liberty profile. 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 server.xml:
<featureManager> <feature>ssl-1.0</feature> </featureManager>

SSL Default

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

Attribute Description Default Value
sslRef The sslRef attribute specifies the SSL configuration to be used as the default. If this attribute is not specified, then the value used is defaultSSLSettings. The default SSL Configuration name is defaultSSLConfig.

In server.xml, the entry is as follows:
<sslDefault sslRef="mySSLSettings" />

SSL Configuration

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

of the SSL element . This table describes the attributes
Attribute Description Default Value
id The id attribute assigns a unique name to the SSL configuration object. No default value; a unique name must be specified.
keyStoreRef The keyStoreRef attribute names the keystore service object that defines the SSL configurations keystore. The keystore holds the key required to make an SSL connection. No default value; a keystore reference must be specified.
trustStoreRef The trustStoreRef attribute names the keystore service object that defines the SSL configurations truststore. The truststore holds certificates required for signing verification. trustStoreRef is an optional attribute. If the reference is missing, the keystore specified by keyStoreRef is used.
clientAuthentication The clientAuthentication attribute determines whether SSL client authentication is required. Default value is false.
clientAuthenticationSupported The clientAuthenticationSupported attribute determines whether SSL client authentication is supported. The client does not have to supply a client certificate. If the clientAuthentication attribute is set to true, the value of the clientAuthenticationSupported attribute is overwritten. Default value is false.
sslProtocol The sslProtocol attribute defines the SSL handshake protocol. The protocol can be SDK-dependent, so if we modify the protocol verify the value is supported by the SDK we are running under. Default value is SSL_TLS.
securityLevel The securityLevel attribute determines the cipher suite group to be used by the SSL handshake. The attribute has one of the following values:

HIGH (128-bit ciphers and higher)

MEDIUM (40-bit ciphers)

WEAK (for all ciphers without encryption)

CUSTOM (if the cipher suite group is customized).

When we set the enabledCiphers attribute with a specific list of ciphers, the system ignores this attribute.
Default value is HIGH.
enabledCiphers The enabledCiphers attribute is used to specify a unique list of cipher suites. Separate each cipher suite in the list with a space. If the enabledCiphers attribute is set then the securityLevel attribute is ignored. No default value.
serverKeyAlias The serverKeyAlias attribute names the key in the keystore to be used as the SSL configurations key. This attribute is only required if the keystore has more than one key entry in it. If the keystore has more than one key entry and this attribute does not specify a key, then the JSSE picks a key. No default value.
clientKeyAlias The clientKeyAlias attribute names the key in the keystore to be used as the key for SSL configuration when clientAuthentication is enabled. The attribute is only required if the keystore contains more than one key entry. No default value.

The key manager is used by the SSL handshake to determine what certificate alias to use. The key manager is not configured in server.xml, 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 server.xml, 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 server.xml:
  <ssl id="myDefaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" />   <ssl id="myDefaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" clientAuthentication="true" sslProtocol="TLS" />    <ssl id="myDefaultSSLConfig" keyStoreRef="defaultKeyStore" serverKeyAlias="default" />

Keystore Configuration

The keystore configuration consists of the attributes required to load a keystore. These attribute can be set on the keystore service configuration in server.xml.

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.config.dir}/resources/security directory. In the SSL minimal configuration, the location of the file is assumed to be ${server.config.dir}/resources/security/key.jks.
type The type attribute specifies the type of the keystore. Check that the keystore type specified is supported by the SDK we are running on. Default value is jks.
password The password attribute specifies the password 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.

Here is an example of how the keystore element is configured in server.xml:
   keyStore id="defaultKeyStore" location="MyKeyStoreFile.jks" type="JKS" password="myPassword" />

Full SSL Configuration Example

Here is an example of a full SSL configuration in server.xml. This example has the following SSL configurations:

defaultSSLSettings

mySSLSettings

By default, the SSL configuration is set to defaultSSLConfig.
<featureManager> <feature>ssl-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=" />

Parent topic: Enable SSL communication
Concepts:
The limits to protection through password encryption
Tasks:
Set up a Liberty profile to run in SP800-131a
Reference:
Keystores
Related information:

Intel Advanced Encryption Standard New Instructions

Attribute	Description	Default Value
id	The id attribute assigns a unique name to the SSL configuration object.	No default value; a unique name must be specified.
keyStoreRef	The keyStoreRef attribute names the keystore service object that defines the SSL configurations keystore. The keystore holds the key required to make an SSL connection.	No default value; a keystore reference must be specified.
trustStoreRef	The trustStoreRef attribute names the keystore service object that defines the SSL configurations truststore. The truststore holds certificates required for signing verification.	trustStoreRef is an optional attribute. If the reference is missing, the keystore specified by keyStoreRef is used.
clientAuthentication	The clientAuthentication attribute determines whether SSL client authentication is required.	Default value is false.
clientAuthenticationSupported	The clientAuthenticationSupported attribute determines whether SSL client authentication is supported. The client does not have to supply a client certificate. If the clientAuthentication attribute is set to true, the value of the clientAuthenticationSupported attribute is overwritten.	Default value is false.
sslProtocol	The sslProtocol attribute defines the SSL handshake protocol. The protocol can be SDK-dependent, so if we modify the protocol verify the value is supported by the SDK we are running under.	Default value is SSL_TLS.
securityLevel	The securityLevel attribute determines the cipher suite group to be used by the SSL handshake. The attribute has one of the following values: HIGH (128-bit ciphers and higher) MEDIUM (40-bit ciphers) WEAK (for all ciphers without encryption) CUSTOM (if the cipher suite group is customized). When we set the enabledCiphers attribute with a specific list of ciphers, the system ignores this attribute.	Default value is HIGH.
enabledCiphers	The enabledCiphers attribute is used to specify a unique list of cipher suites. Separate each cipher suite in the list with a space. If the enabledCiphers attribute is set then the securityLevel attribute is ignored.	No default value.
serverKeyAlias	The serverKeyAlias attribute names the key in the keystore to be used as the SSL configurations key. This attribute is only required if the keystore has more than one key entry in it. If the keystore has more than one key entry and this attribute does not specify a key, then the JSSE picks a key.	No default value.
clientKeyAlias	The clientKeyAlias attribute names the key in the keystore to be used as the key for SSL configuration when clientAuthentication is enabled. The attribute is only required if the keystore contains more than one key entry.	No default value.

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.config.dir}/resources/security directory.	In the SSL minimal configuration, the location of the file is assumed to be ${server.config.dir}/resources/security/key.jks.
type	The type attribute specifies the type of the keystore. Check that the keystore type specified is supported by the SDK we are running on.	Default value is jks.
password	The password attribute specifies the password 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.