Outbound filters for SSL configurations

You can configure Liberty so that multiple SSL configurations can be used for outbound connections to a host or host and ports by using outbound SSL filters.

By default, Liberty uses the default SSL configuration for both inbound and outbound SSL connections. Users can also configure Liberty to have a global outbound default that allows you to configure one SSL configuration for the outbound default. For more information how to configure SSL settings for outbound communications, see Configuring SSL Settings for outbound communications.

Outbound SSL filters are configured on the outboundConnection element that is nested in the ssl element. You can specify either a host or a host and port that indicates where the outbound SSL connection is going by using the outboundConnection element.

OutboundConnection element attributes

Table 1. Attributes, descriptions, and default values
Attribute Description Default value
host The host where the outbound connection is going. No default value, but the user is required to provide a host name.
port The port where the outbound connection is going. No default value. If the port attribute is not configured, then the filter matches the host name that goes to any port on the destination server.
clientCertificate The outbound SSL connection uses this certificate alias if the connection is going to a server that supports or requires client certificate authentication. No default value. If the attribute is missing and the connection requires client certificate authentication, then the Java Secure Socket Extension (JSSE) picks the certificate that is sent to the server.
Define the host attribute in one of the following ways:
  1. A host name, short name, or a fully qualified host name. Whichever is used must be an exact match to what is used for the outbound connection. If the outbound connection is using the host short name, then the filter matches only on the short name.
  2. An * (asterisk) can be used for the host attribute. If the * (asterisk) value is used and no port is specified, then it means all outbound connections. If the global outbound default is specified with the outboundSSLRef attribute, on the sslDefault element, then there is a conflict. The outboundSSLRef attribute takes precedence.
  3. The host string must start with *. to match a domain name. If the * value is specified at any other location in the string, then it is treated as a literal *. The outbound connection must be made with a fully qualified host name for the domain to match.

The port must be an exact match to the port that is used for the outbound connection. If no port is specified, then any port on the specified host matches the filter.

The clientCertificate attribute is optional. It is used if the server that the outbound SSL connection goes to requests a client certificate. If the server does not request a certificate, then it is not used. If the server requests a certificate and no certificate is specified, then the connection looks to the clientKeyAlias attribute that is specified on the parent ssl element. If neither of the attributes are configured, then the JSSE chooses the certificate to use for the connection.

Outbound SSL precedence

The outbound SSL configuration matching precedence is as follows:
  1. Direct Reference
    If a feature directly requests an SSL configuration to use, then that configuration is used.
  2. Matching an outboundConnection filter
    If no direct reference is requested, then there is an attempt to match the outbound call to the outboundConnection element filter.
  3. Outbound default SSL configuration
    If no outbound SSL filter matches, then the SSL configuration that is specified on the outboundSSLRef attribute is used.
  4. Default SSL configuration
    If no configured outbound default exists, then the default SSL configuration is used. The default SSL configuration is either the defaultSSLConfig configuration or what is specified on the sslRef attribute on the sslDefault element.

Conflicts in the outbound filters

If conflicts exist between the filters, then a message is written to the logs that indicates which SSL configuration is used. This situation can happen, for example, if more than one outboundConnection element uses the same host and port.

If the outboundSSLRef attribute is specified and a filter exists that uses the host value of * with no port specified, then the configuration that is specified by outboundSSLRef attribute is used.

Configuration examples

To use the outboundConnection element, you must specify the transportSecurity-1.0 feature in the configuration. If you do not specify the transportSecurity-1.0 feature, the outboundConnection is ignored.

<featureManager>
    <feature>transportSecurity-1.0</feature>
</featureManager>
Example 1.
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" />
<keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="yourpassword" />
<keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="yourpassword" />

<ssl id="alternateSSLSettings" keyStoreRef="alternateKeyStore" trustStoreRef="alternateTrustStore" >
	<outboundConnection host="server99.ibm.com" port="9443" />
</ssl>
	<keyStore id="alternateKeyStore" location="${server.config.dir}/alternateServerKeyFile.jks" type="JKS" password="yourpassword" />
	<keyStore id="alternateTrustStore" location="${server.config.dir}/alternateServerTrustFile.jks" type="JKS" password="yourpassword" />

In this configuration, the SSL configuration that is called alternateSSLSettings is used when outbound SSL connections go to the server server99.ibm.com host and port 9443. All other outbound SSL connections use the default SSL configuration of defaultSSLConfig.

Example 2.
<sslDefault outboundSSLRef="outboundSSLSettings" />
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" >
	<outboundConnection host="otherhost"  />
</ssl>
<keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="yourpassword" />
<keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="yourpassword" />

<ssl id="alternateSSLSettings" keyStoreRef="alternateKeyStore" trustStoreRef="alternateTrustStore" >
	<outboundConnection host="server99.ibm.com" port="8020" />
	<outboundConnection host="server99.ibm.com" port="9443" />
</ssl>

	<keyStore id="alternateKeyStore" location="${server.config.dir}/alternateServerKeyFile.jks" type="JKS" password="yourpassword" />
	<keyStore id="alternateTrustStore" location="${server.config.dir}/alternateServerTrustFile.jks" type="JKS" password="yourpassword" />

<ssl id="outboundSSLSettings" keyStoreRef="outboundKeyStore" trustStoreRef="outboundTrustStore" >
</ssl>
	<keyStore id="outboundKeyStore" location="${server.config.dir}/outboundKeyFile.jks" password="yourpassword" />
	<keyStore id="outboundTrustStore" location="${server.config.dir}/outboundTrustFile.jks" password="yourpassword" />

In this configuration, outbound SSL connections that go to any port on the otherhost host use the SSL configuration that is called defaultSSLConfig. Outbound connections that are going to the server99.ibm.com host and either port 9443 or 8020 use the SSL configuration called alternateSSLSettings. All other outbound SSL connections use the outbound default SSL configuration that is specified by the outboundSSLRef attribute called outboundSSLSettings.

Example 3.
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" clientKeyAlias="default" >
	<outboundConnection host="server99.ibm.com" port="9443" clientCertificate="special" />
</ssl>

<keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="yourpassword" />
<keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="yourpassword" />

In this configuration, outbound SSL connections use the default SSL configuration that is called defaultSSLConfig. If the outbound SSL connection is going to the server99.ibm.com host and requests a client certificate, the certificate that is called special is used. All other outbound connections that request a client certificate use the certificate that is called default.