Configuring hostname validation for encrypted communication between primary and standby hosts in an HADR environment

Transport Layer Security can be used to encrypt communication between the primary and standby hosts in a non-pureScale environment. You enable hostname validation for this communication, using the HADR_SSL_HOST_VAL database configuration parameter.

The HADR_SSL_HOST_VAL database configuration keyword

The HADR_SSL_HOST_VAL database configuration keyword specifies whether hostname validation for Transport Layer Security (TLS, formerly SSL) connections between primary and standby hosts is enabled.

The HADR_SSL_HOST_VAL keyword is currently supported on environments that do not use IBM® Db2 pureScale®. If you upgrade from Enterprise Server Edition (ESE) to Db2 pureScale while the HADR_SSL_HOST_VAL is set, db2checkSD returns the error DBT5038N. Users should set the value to OFF before trying to upgrade to Db2 pureScale.

Changes to this parameter do not affect HADR connections that are already established. Change takes effect for new connections between primary and standby servers.

When hostname validation fails for these connections, the ADM12510E admin message with reason code 14 is logged to the db2diag.log file. Message text for this reason code is as follows:
Hostname validation is enabled for SSL communication between
the primary and standby hosts and it failed because the specified
hostname does not match any of the hostname fields in the
certificate returned by this host. Details about this certificate
have been logged to the db2diag.log file.
For hostname validation to be successful, each host must set up a certificate that includes a SAN of its fully qualified hostname. There are two ways to set up certificates in this way:
  • Using a separate certificate for the primary host and each standby host
  • Using a common certificate for all hosts
Note: The following instructions for setting up hostname validation for primary and standby TLS require that fully qualified hostnames are used when configuring the hadr_remote_host and hadr_target_list database configuration parameters.

Using a separate certificate for the primary host and each standby host

When using a separate certificate for each host in an two-site multiple standby HADR cluster, each host must include its the fully qualified hostname in the certificate it returns to its peer during the TLS handshake.

The following example shows an HADR cluster containing a primary and two standby hosts:
primary.db2.example.com - Primary
standby1.db2.example.com - Standby 1
standby2.db2.example.com - Standby 2
The following example shows how the certificate on the primary host needs to be configured for hostname validation to be successful when it communicates with the standby hosts. Note that the SAN contains the fully qualified host name of the primary server, primary.db2.example.com, in the Extensions section.
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: primary.db2.example.com

Signature Algorithm : SHA1WithRSASignature
As with the primary host, each standby host must contains its fully qualified hostname in its certificate.
The following example shows how the certificate on standby1 needs to be configured for successfully communicating with the primary host when hostname validation is enabled. Note that the SAN contains the fully qualified host name of the primary server, standby1.db2.example.com, in the Extensions section :
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: standby1.db2.example.com

Signature Algorithm : SHA1WithRSASignature

Using a common certificate for all hosts

When using a common certificate for all hosts in a two-site multiple standby HADR cluster, the certificate you create must include representations for the hostnames of each host in the SAN.

There are two ways to configure the SAN to represent the hostnames of all hosts in the HADR cluster:
  • Using multiple hostnames
  • Using a wildcard hostname

Using multiple hostnames in the SAN

When using multiple hostname entries in the SAN, use the fully qualified hostname of each host.

The following example shows how a common certificate using multiple SAN entries is configured. Note the fully qualified hostname entries for the SAN 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: primary.db2.example.com
        dNSName: standby1.db2.example.com
        dNSName: standby2.db2.example.com

Signature Algorithm : SHA1WithRSASignature

Using a wildcard hostname

One drawback of using multiple hostnames in the SAN is that every time a host is either added to, or removed from, the cluster the certificate has to be recreated. If all of the hosts in the cluster are part of the same sub-domain, a single wildcard hostname in the SAN can be used to represent all the hosts in the cluster.

The following example shows how a common certificate using a single wildcard hostname is configured. Note the single entry for the SAN in the Extensions section:
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: *.db2.example.com

Signature Algorithm : SHA1WithRSASignature
Note: You can include both fully qualified hostnames and wildcard hostnames in the SAN.

Using hostname validation between HADR hosts in a NAT environment

Network Address Translation (NAT) is designed for IP address conservation. In certain HADR configurations, the primary host is located inside a NAT environment, along with a subset of the standby hosts. The remainder of the standby hosts are located outside of the NAT environment. In this configuration, the primary host is known by different names to the different subsets of the standby hosts. For hostname validation to work in a NAT environment, the certificate for the primary host must contain the different hostnames that it is known by to the rest of the cluster. In addition, any of the standby hosts behind the NAT that could potentially take over as the primary host must also contain all the different hostnames that they could be identified as in their certificates.

The following example shows an HADR cluster, containing a primary host and two standby hosts:
nat.router.com/primary.xyz.com - Primary
standby1.xyz.com - Standby 1
standby2.abc.com - Standby 2
  • The primary host and standby 1 are inside a NAT environment.
  • standby 2 is outside of the NAT environment.
  • primary is known as nat.router.com to standby2.abc.com.
  • primary is known as primary.xyz.com to standby1.xyz.com.
  • the NAT router is exposed to the outside world as nat.router.com.
The following example shows how the certificate on primary needs to be configured, for hostname validation to be successful when the standby and primary hosts communicate using TLS. Note that both the nat.router.com and primary.xyz.com hostnames are included in the SAN:
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: nat.router.com
        dNSName: primary.xyz.com

Signature Algorithm : SHA1WithRSASignature

In addition, certificates on each of the standby hosts that are inside the NAT environment must contain the NAT router hostname in their certificates. This enables these standby hosts to take over as primary in the future, and ensures that hostname validation is successful after the transition.

The following example shows how the certificate of a standby server (standby 1), that sits inside the NAT environment, needs to be configured to ensure that hostname validation is successful. Note the entries for the SAN in the Extensions section : 
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: nat.router.com
        dNSName: standby1.xyz.com

Signature Algorithm : SHA1WithRSASignature