Secure Socket Layer

Secure Socket Layer

This feature enables support for SSL connections. The secure HTTPS listener is not started unless the ssl-1.0 feature is enabled. The Liberty profile provides a dummy keystore and a dummy truststore, which are the same as those provided by previous versions of WAS.

Enable this feature

To enable the Secure Socket Layer feature, add the following element declaration inside the featureManager element in the server.xml file:
<feature>ssl-1.0</feature>

Developing a feature that depends on this feature

If we are developing a feature that depends on the Secure Socket Layer feature, include the following item in the Subsystem-Content header in the feature manifest file for the new feature:
com.ibm.websphere.appserver.ssl-1.0; type="osgi.subsystem.feature"

Features that enable this feature

Web Admin Center

Application Security 2.0

LDAP User Registry

OAuth

OpenID Connect Client

JMX REST Connector

SPI packages provided by this feature

com.ibm.websphere.ssl

com.ibm.wsspi.ssl

Feature configuration elements

We can use the following elements in the server.xml file to configure the Secure Socket Layer feature:

channelfw

keyStore

ssl

sslDefault

sslOptions

tcpOptions

channelfw

Defines channel and chain management settings.

Attribute name Data type Default value Description
chainQuiesceTimeout A period of time with millisecond precision 30s Default amount of time to wait while quiescing chains. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
chainStartRetryAttempts int
Minimum: 0
60 Number of retry attempts to make per chain.
chainStartRetryInterval A period of time with millisecond precision 5s Time interval between start retries. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
warningWaitTime A period of time with millisecond precision 10s Amount of time to wait before notifying of a missing factory configuration. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

keyStore

A repository of security certificates used for SSL encryption.

Attribute name Data type Default value Description
id string A unique configuration ID.
location Path to a file ${server.output.dir}/resources/security/key.jks An absolute or relative path to the keystore file. If a relative path is provided, the server will attempt to locate the file in the ${server.config.dir}/resources/security directory. Use the keystore file for a file-based keystore, the keyring name for SAF keyrings, or the device configuration file for hardware cryptography devices. In the SSL minimal configuration, the location of the file is assumed to be ${server.config.dir}/resources/security/key.jks.
password Reversably encoded password (string) The password used to load the keystore file. Stored in clear text or encoded form. Use the securityUtility tool to encode the password.
type string jks A keystore type supported by the target SDK.

ssl

An SSL repertoire with an ID, a defined keystore, and an optional truststore.

Attribute name Data type Default value Description
id string A unique configuration ID.
keyStoreRef string A keystore containing key entries for the SSL repertoire. This attribute is required.
trustStoreRef string ${keyStoreRef} A keystore containing trusted certificate entries used by the SSL repertoire for signing verification. This attribute is optional. If unspecified, the same keystore is used for both key and trusted certificate entries.

sslDefault

The default repertoire for SSL services.

Attribute name Data type Default value Description
sslRef string defaultSSLConfig The default SSL repertoire. The default value is defaultSSLSettings.

sslOptions

The SSL protocol configuration for a transport.

Attribute name Data type Default value Description
id string A unique configuration ID.
sessionTimeout A period of time with second precision 1d Amount of time to wait for a read or write request to complete on a socket. This value is overridden by protocol-specific timeouts. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
sslRef string The default SSL configuration repertoire. The default value is defaultSSLSettings.
suppressHandshakeErrors boolean false Disable logging of SSL handshake errors. SSL handshake errors can occur during normal operation, however these messages can be useful when SSL is behaving unexpectedly.

tcpOptions

Defines TCP protocol settings.

Attribute name Data type Default value Description
id string A unique configuration ID.
inactivityTimeout A period of time with millisecond precision 60s Amount of time to wait for a read or write request to complete on a socket. This value is overridden by protocol-specific timeouts. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
soReuseAddr boolean true Enables immediate rebind to a port with no active listener.

Attribute name	Data type	Default value	Description
chainQuiesceTimeout	A period of time with millisecond precision	30s	Default amount of time to wait while quiescing chains. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
chainStartRetryAttempts	int Minimum: 0	60	Number of retry attempts to make per chain.
chainStartRetryInterval	A period of time with millisecond precision	5s	Time interval between start retries. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
warningWaitTime	A period of time with millisecond precision	10s	Amount of time to wait before notifying of a missing factory configuration. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
location	Path to a file	${server.output.dir}/resources/security/key.jks	An absolute or relative path to the keystore file. If a relative path is provided, the server will attempt to locate the file in the ${server.config.dir}/resources/security directory. Use the keystore file for a file-based keystore, the keyring name for SAF keyrings, or the device configuration file for hardware cryptography devices. In the SSL minimal configuration, the location of the file is assumed to be ${server.config.dir}/resources/security/key.jks.
password	Reversably encoded password (string)		The password used to load the keystore file. Stored in clear text or encoded form. Use the securityUtility tool to encode the password.
type	string	jks	A keystore type supported by the target SDK.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
keyStoreRef	string		A keystore containing key entries for the SSL repertoire. This attribute is required.
trustStoreRef	string	${keyStoreRef}	A keystore containing trusted certificate entries used by the SSL repertoire for signing verification. This attribute is optional. If unspecified, the same keystore is used for both key and trusted certificate entries.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
sessionTimeout	A period of time with second precision	1d	Amount of time to wait for a read or write request to complete on a socket. This value is overridden by protocol-specific timeouts. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
sslRef	string		The default SSL configuration repertoire. The default value is defaultSSLSettings.
suppressHandshakeErrors	boolean	false	Disable logging of SSL handshake errors. SSL handshake errors can occur during normal operation, however these messages can be useful when SSL is behaving unexpectedly.

Attribute name	Data type	Default value	Description
id	string		A unique configuration ID.
inactivityTimeout	A period of time with millisecond precision	60s	Amount of time to wait for a read or write request to complete on a socket. This value is overridden by protocol-specific timeouts. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.
soReuseAddr	boolean	true	Enables immediate rebind to a port with no active listener.