Configuring hostname validation for TLS connections to alternate servers, federated servers, and other topologies

You can configure the Db2® 11.5.6 client to validate hostnames of servers listed in returned certificates when negotiating TLS connections to various Db2 instances. This topic discussed configuring hostname validation for connections to alternate Db2 servers, federated data sources and other network topologies.

Connections to alternate servers

An alternate server is a Db2 server to which a Db2 client is rerouted during ACR, if the original connection to the database is lost. For hostname validation to succeed for this rerouted connection, the hostname in the certificate returned by the alternate server must match the hostname specified in the UPDATE ALTERNATE SERVER command run on the original server:

UPDATE ALTERNATE SERVER FOR DATABASE USING <HOSTNAME> PORT <PORT NUMBER>

Use a fully qualified hostname when running this command.

Connections to z/OS servers

In a sysplex environment, a Db2 client must connect to the Db2 for z/OS server using the hostname that maps to the distributor’s IP address. When setting up certificates on the server, use a common certificate across all the members containing this hostname.

For example, if a Db2 client attempts to connect to xyz.db2.example.com with a connection string that includes the hostname, the returned certificate must include xyz.db2.example.com in the SAN or the Common Name for hostname validation to be successful. This is regardless of where the connections gets routed to by the distributor.

Example connection string:

 Hostname=xyz.db2.example.com;Security=SSL;SSLClientHostnameValidation=Basic;Database=…

The following example shows how the certificate should appear for hostname validation to be successful.

Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=Example Enterprise CA
Subject : CN=none
Not Before : November 26, 2020 4:44:11 PM EST

Not After : November 27, 2021 4:44:11 PM EST

Extensions
    subjectAlternativeName
        dNSName: xyz.db2.example.com

Signature Algorithm : SHA1WithRSASignature

If a Db2 client is connecting to one of the sysplex members directly instead of going through the distributor, the certificate returned by the target member must include the hostname of the member to which the client is configured to connect.

Note: If an IP address is used instead of a hostname to connect to a Db2 for z/OS server, the certificate returned by the server should contain this IP address for hostname validation to be successful.

Connections to federated data sources

When a federated data source is configured on a Db2 server, the server is acting as an application requestor when communicating with this data source. TLS is supported for these outbound connections and the following federated DRDA wrapper server option controls the hostname validation behavior.

Server option syntax:

SSL_HOSTNAMEVALIDATION = 'Basic' | 'OFF'

where

Basic = Hostname validation is enabled
OFF = Hostname validation is disabled. This is the default value.
Note: TLS needs to be enabled when setting SSL_HOSTNAMEVALIDATION to OFF.
This server option is restricted currently to the DRDA wrapper, and it can only be set when TLS is enabled. When TLS is not enabled, setting SSL_HOSTNAMEVALIDATION to 'Basic' or 'OFF' for the federation server generates the SQL1881N error. Use the following server options to enable TLS:
- SSL_KEYSTORE
- SSL_KEYSTASH
- SSL_SERVERCERTIFICATE
For more information, see Hostname validation for Db2 clients.

Connections to Db2 Connect gateways

When Db2 is acting as a gateway server, as is the case for a Db2 Connect server, hostname validation can be enabled for inbound TLS connections.

You enable hostname validation for inbound connections by setting the SSLHostnameValidation DS Driver parameter to Basic on the client. Hostname validation is not available for outbound TLS connections from the Gateway server.

Connection to KMIP servers

If you set the SSL_KMIP_CLIENT_HOSTNAME_VALIDATION keyword in your keystore configuration file to BASIC, Db2 validates that the hostname of the KMIP server is contained within the certificate used by the KMIP server when establishing the TLS connection. For more information, see Creating a KMIP keystore configuration file

Connections to multi-homed servers

A multi-homed server can be known by more than one hostname. This means that a Db2 client can connect to the same database server using multiple hostnames. The server’s certificate must contain all of the hostnames that the clients use to connect to the database.

For example, if a Db2 server is known by the hostnames xyz.db2.example1.com, abc.db2.example2.com, and pqr.db2.example3.com, you must include these hostnames, separated by commas, in the SAN statement of the IBM Global Security Kit (GSKit) command:

The following example shows how the certificate should appear for hostname validation to be successful. Note the hostnames listed in the Extensions section of the returned certificate:

Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=ExampleCA
Subject : CN=none
Not Before : November 26, 2020 4:44:11 PM EST

Not After : November 27, 2021 4:44:11 PM EST

Extensions
    subjectAlternativeName
        dNSName: xyz.db2.example1.com
        dNSName: abc.db2.example2.com
        dNSName: pqr.db2.example3.com

Signature Algorithm : SHA1WithRSASignature

Note: Wild card hostnames can also be used if these hostnames are part of the same domain.

Connections using CNAME and DNAME DNS record names

In a DNS server, CNAME and DNAME records can be used to create aliases to a Db2 server’s hostname. If a client connects to the database using an alias hostname, the server certificate must contain this alias in the SAN statement or common name statement for hostname validation to be successful.

For example, if a client connects to xyz.db2.example.com, whose CNAME record in the DNS server points to abc.db2.example.com, the server’s certificate needs to contain the alias in the SAN for hostname validation to be successful.

Note the value in the Extensions section of the returned certificate:

Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=Example Enterprise CA
Subject : CN=none
Not Before : November 26, 2020 4:44:11 PM EST

Not After : November 27, 2021 4:44:11 PM EST

Extensions
    subjectAlternativeName
        dNSName: xyz.db2.example.com

Signature Algorithm : SHA1WithRSASignature

Connections to multiple A records for IP addresses

Recommendations from the multi-homed servers section apply here as well. In short, if there are multiple A records in the DNS for a given Db2 server, the certificate setup on the server should contain all of the hostnames that the clients use to connect to the server.

Connections to distributors or load balancers

When a Db2 client connects to a distributor or a load balancer, the network traffic from the client is redirected to an actual database server. The certificate returned by the target database server must contain the hostname of the distributor or the load balancer in the SAN or Common Name for hostname validation to be successful.

For example, if the client connects to xyz.balancer.com which is the hostname of a load balancer that forwards traffic to the real target server, abc.db2.example.com, then the certificate returned by the server must contain xyz.balancer.com as its SAN value.

Note the value in the Extensions section of the returned certificate:

Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=ExampleCA
Subject : CN=none
Not Before : November 26, 2020 4:44:11 PM EST

Not After : November 27, 2021 4:44:11 PM EST

Extensions
    subjectAlternativeName
        dNSName: xyz.balancer.com

Signature Algorithm : SHA1WithRSASignature