Configuring hostname validation for TLS connections to Db2 servers in HADR environments

You can configure your Db2 clients to use hostname validation when attempting TLS connections to servers in an HADR environment.

Connections to servers in HADR clusters not using a VIP

For hostname validation to be successful when attempting a TLS handshake with servers in an HADR environment, the certificate returned by each host in the cluster must represent its fully qualified hostname. This applies when the HADR cluster is not using a virtual IP address (VIP). To accomplish this, you need to configure the server certificate using one of the following methods:

Using a separate certificate per host

When using a separate certificate for each host in the cluster, the certificate returned for each host must contain its fully qualified hostname.

For example, let us say that we have the following HADR cluster with a primary and two standby hosts:
  • primary.db2.example.com - Primary
  • standby1.db2.example.com - Standby 1
  • standby2.db2.example.com - Standby 2
If the client connects to the primary host with a connection string similar to the following, 
Hostname=primary.db2.example.com;Security=SSL;SSLClientHostnameValidation=Basic;Database=…
then the certificate returned by this host must have primary.db2.example.com in the SAN or Common Name.

Similarly, if the client connects to standby1.db2.example.com because it assumed the role of the primary, or if reads on standby is enabled, then the certificate returned by this host must have standby1.db2.example.com in the SAN or Common Name.


Using a common certificate containing multiple SANs

When creating a common certificate for all hosts in an HADR cluster, include multiple SAN entries with fully qualified hostnames of each host in the cluster. This ensures that, whether the client connects to the primary host or one of the standby hosts, hostname validation is successful.

Note the entries that appear in the Extensions section of the 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: primary.db2.example.com
        dNSName: standby1.db2.example.com
        dNSName: standby2.db2.example.com

Signature Algorithm : SHA1WithRSASignature

Using a common certificate containing a wildcard hostname

When creating a common certificate for all hosts in an HADR cluster, rather than including multiple hostnames, use a single SAN entry with a wildcard hostname that represents all of the hosts in the cluster. This ensures that, whether the client connects to the primary host or one of the standby hosts, hostname validation is successful.

Note the single SAN entry containing the wildcard symbol in the Extensions section:
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: *.db2.example.com

Signature Algorithm : SHA1WithRSASignature
Note: Wildcard hostnames only represent members that share the same domain name, such as db2.example.com. For more information about the rules around use of wildcards, see Using wildcards in hostnames.

It is possible to include both wildcard and non-wildcard hostnames in the SANs of a certificate.

Connections to servers in HADR clusters that use a VIP

In this configuration of HADR, there is a single virtual IP address. A cluster manager, such as TSA or Pacemaker, specifies which machine in the cluster that the VIP points to at any given moment. If there is a power outage and the primary host goes down, the cluster manager initiates a failover to the standby host to which the VIP now points.

From a Db2 client’s point of view, there is no change since it still uses the hostname associated with the VIP to connect to the database. For hostname validation to be successful in this scenario, all of the hosts in the cluster need to use a common certificate that represents this hostname.

For example, let us say we have the following HADR cluster, with v1.db2.example.com as the hostname of the virtual IP address that points to one of the hosts at any given moment.
primary.db2.example.com - Primary
standby1.db2.example.com - Standby
When the client connects to v1.db2.example.com with a connection string similar to the following, 
Hostname=v1.db2.example.com;Security=SSL;SSLClientHostnameValidation=Basic;Database=…
the certificate returned by all of the above hosts must contain v1.db2.example.com for hostname validation to be successful.
Note the entry in the Extensions section in the following example 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: v1.db2.example.com

Signature Algorithm : SHA1WithRSASignature

Connections to servers in HADR clusters using ACR

When creating certificates for an HADR cluster that is not using a VIP, the instructions listed in the HADR with no VIP section is sufficient, if the UPDATE ALTERNATE SERVER command that is run on the primary host uses the fully qualified hostname of the alternate server.
UPDATE ALTERNATE SERVER FOR DATABASE <DATABASE
          ALIAS> USING HOST <HOSTNAME> PORT <PORT NUMBER>
This hostname gets returned to the client as part of the server list. When the client connects to this standby host during ACR, it uses this hostname to check against the server certificate.

You should avoid using a short hostname or an IP address when configuring this alternate server. For more information, see Using IP addresses as SAN values and Using short hostnames. If your business requires you to use a short hostname or an IP address when configuring the alternate server, this value must be present in the certificate setup on the standby host that is acting as the alternate server.

The opposite applies if the primary host is acting as the alternate server for any of the standby hosts.

Similarly, with an HADR cluster that is using a VIP, following the recommendations listed in the HADR with VIP section is sufficient.

Adding or removing a host from an HADR cluster

When adding a new host to an HADR cluster, each server certificate might have to be updated, depending on how the certificates were configured.

If a separate certificate is used for each host, the new host needs to have its fully qualified hostname in its certificate. Since a separate certificate is used per host, the other hosts in the cluster do not need to be updated.

If a common certificate containing multiple SANs is used for all hosts in a cluster, the common certificate has to be recreated to contain an additional SAN for this new host.

If a common certificate containing a wildcard hostname is used for all hosts in a cluster, no updates are needed, so long as the wildcard hostname in the common certificate matches the new hostname.

If you are removing a host from an HADR cluster, no changes to the certificate used by the cluster are required for hostname validation to be successful.