WAS v8.5 > Reference > Developer detailed usage information

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 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:

SSL Configuration

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

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 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 is false.
sslProtocol The sslProtocol attribute defines the SSL handshake protocol. The protocol can be SDK-dependent, so if you modify the protocol verify the value is supported by the SDK you are running under. Default 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 enableCiphers attribute with a specific list of ciphers, the system ignores this attribute.

Default is HIGH.
enableCiphers The enableCiphers attribute is used to specify a unique list of cipher suites. Separate each cipher suite in the list with a space. If the enableCiphers 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.

Here is an example of how the ssl element is configured in server.xml: 

<!--  Simple ssl configuration service object. This assumes there is a keystore object named --> <!--  defaultKeyStore and a truststore object named defaultTrustStore in server.xml. -->   < 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 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 the keystore type specified is supported by the SDK you are running on. Default 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 attributes 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 is true.

Here is an example of how the keystore element is configured in server.xml: 

<!-- 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 server.xml. This example has the following SSL configurations:

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 
       keyStoreRef="myKeyStore" 
       trustStoreRef="myTrustStore" 
       clientAuthentication="true" />   < keyStore 
            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: Enabling SSL communication for the Liberty profile


|