Liberty: 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>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 that uses the sslDefault service configuration.
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. |
<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.
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 that is 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 that are required for signing verification. | trustStoreRef is an optional attribute. If the reference is missing, the keystore that is 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_TLSv2 for the IBM® JRE and SSL for the Oracle JRE. |
securityLevel | The securityLevel attribute
determines the cipher suite group to be used by the SSL handshake.
The attribute has one of the following values:
|
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 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.
<!-- 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.
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 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. | disabled. |
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.
<!-- 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 -->
<!-- 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.config.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" />
Full SSL Configuration Example
- defaultSSLSettings
- mySSLSettings
<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=" />