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
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. |
- 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.
- 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 theoutboundSSLRef
attribute, on thesslDefault
element, then there is a conflict. TheoutboundSSLRef
attribute takes precedence. - 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
-
- Direct Reference
- If a feature directly requests an SSL configuration to use, then that configuration is used.
-
- 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.
- Matching an
-
- Outbound default SSL configuration
- If no outbound SSL filter matches, then the SSL configuration that is specified on the
outboundSSLRef
attribute is used.
-
- 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 thesslRef
attribute on thesslDefault
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
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 serverserver99.ibm.com
host and port 9443. All other outbound SSL connections use the default SSL configuration ofdefaultSSLConfig
. - 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 calleddefaultSSLConfig
. Outbound connections that are going to theserver99.ibm.com
host and either port 9443 or 8020 use the SSL configuration calledalternateSSLSettings
. All other outbound SSL connections use the outbound default SSL configuration that is specified by theoutboundSSLRef
attribute calledoutboundSSLSettings
. - 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 theserver99.ibm.com
host and requests a client certificate, the certificate that is calledspecial
is used. All other outbound connections that request a client certificate use the certificate that is calleddefault
.