SSL configuration attributes
SSL configurations contain attributes that you use to control the behavior of the server SSL transport layer on Liberty.
TLS feature
To enable SSL on a server, the Transport Security feature must be included in the server.xml file:
<featureManager>
<feature>transportSecurity-1.0</feature>
</featureManager>
SSL default
You can specify multiple SSL configurations. If more than one SSL configuration exists, you must
specify the default SSL configuration in the server.xml file by using the
sslDefault
element.
<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
configuration element in the
server.xml file.
For a list of the attributes of the ssl
element, see SSL Repertoire.
- 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.
ssl
element 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" />
Hostname verification
WebSphere Liberty performs hostname verification
on SSL certificates by default. Disable hostname verification temporarily when this security check
is not a concern, such as in non-production environments. If you want to disable the hostname
verification functionality, the verifyHostname
attribute within the
ssl
tag must be initialized to false
.
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" verifyHostname="false"/>
Keystore configuration
You can specify the key store configuration on the keyStore
element in the
server.xml file.
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.
keystore
element 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" />
keystore
element 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
server.xml
file.
This example has the following SSL configurations:defaultSSLSettings
mySSLSettings
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=" />