Liberty profile: SSL configuration attributes

SSL configurations contain attributes that you 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 the server.xml file:

<featureManager>
  <feature>ssl-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 using 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 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 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.

Table 2. Attributes of the SSL element . This table describes the attributes of the `ssl` element.
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 you modify the protocol make sure that the value is supported by the SDK you 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 you 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.

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 required to load a keystore. These attribute can be set on the keystore service configuration in the server.xml file.

Table 3. Attributes of the keystore element . This table explains the attributes of `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.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 that you specify is supported by the SDK you 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 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.config.dir}/resources/security -->
  keyStore id="defaultKeyStore"
           location="MyKeyStoreFile.jks"
           type="JKS" password="myPassword" />

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

Reference topic

Terms and conditions for information centers | Feedback

Timestamp icon

Last updated: Wednesday, 22 May 2013
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=rwlp_ssl
File name: rwlp_ssl.html