Configuring hostname validation for TLS connections to pureScale clusters

You can configure your Db2® clients to complete hostname validation during Transport Layer Security (TLS, formerly SSL) connections to Db2 pureScale® clusters.

The pureScale feature in Db2 provides continuous availability, extreme capacity, and application transparency. A typical non-HADR pureScale cluster consists of the following components:
  • Members that are responsible for processing transactions.
  • A shared disk that all members can access.
  • One or more cluster caching facilities (CFs) that coordinate data access in the cluster.
  • Cluster services that oversee heartbeat failure detection and automatic recovery.
For hostname validation to be successful, one or more certificates must be set up on each server in one of the following three ways:

Using a separate certificate per member

The first way is to have a separate certificate per member in the cluster. In this configuration, each member has its fully qualified hostname in its certificate.

For example, assume you have the following pureScale cluster with four members and two CFs.
cf1.db2.example.com - CF 1
cf2.db2.example.com - CF 2
h1.db2.example.com - Member 1
h2.db2.example.com - Member 2
h3.db2.example.com - Member 3
h4.db2.example.com - Member 4

If a client connects to h1.db2.example.com with a connection string that looks like Hostname=h1.db2.example.com;Security=SSL;SSLClientHostnameValidation=Basic;Database=…, the certificate that is returned by this host must have h1.db2.example.com in the SAN or Common Name for hostname validation to be successful.

The following example shows how the certificate appears for hostname validation to be successful. Note the hostname in the Extensions section of the returned certificate:
Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=Example Enterprise CA
Subject : CN=h1.db2.example.com
Not Before : November 26, 2020 4:44:11 PM EST

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

Extensions
    subjectAlternativeName
        dNSName: h1.db2.example.com

Signature Algorithm : SHA1WithRSASignature

In most scenarios, this certificate setup is effective. However, if a member is identified by multiple hostnames in the DNS, and the server-side /etc/nsswitch.conf file prioritizes dns over files for the hosts database, these hostnames might need to be included in the certificate for hostname validation to succeed during automatic client reroute (ACR) or workload balancing (WLB).

For example, if Member 2 can be reached using h2.db2.example.com and anothername.db2.example.com, with both hostnames resolving to the same IP address, it is possible for the latter hostname to be returned to the client as part of a server list. If that is the case, during client reroute or workload balancing, the client uses anothername.db2.example.com to complete hostname validation. If this hostname is not found in the member’s certificate, then validation fails.

The following example shows how the certificate appears for hostname validation to be successful. Note the hostnames in the Extensions section of the returned certificate:
Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=Example Enterprise CA
Subject : CN=h2.db2.example.com
Not Before : November 26, 2020 4:44:11 PM EST

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

Extensions
    subjectAlternativeName
        dNSName: h2.db2.example.com
        dNSName: anothername.db2.example.com

Signature Algorithm : SHA1WithRSASignature

Using a common certificate with multiple SANs

When using a common certificate for all hosts in the cluster, include multiple SAN entries with fully qualified hostnames for each member in the cluster. This ensures that hostname validation is successful since the returned certificate contains the member’s hostname, regardless of the member to which the client connects. In addition, if a connection is routed to another member in the cluster due to workload balancing or ACR, hostname validation is successful for the new connection, since the certificate returned by this member contains the hostname that was originally configured on the client.

The following example shows how the certificate appears for hostname validation to be successful. Note the hostnames that appear 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: h1.db2.example.com
        dNSName: h2.db2.example.com
        dNSName: h3.db2.example.com
        dNSName: h4.db2.example.com

Signature Algorithm : SHA1WithRSASignature

Using a common certificate with a wildcard hostname

When using a common certificate for all hosts in the cluster, rather than including multiple hostnames, you can have a single SAN entry with a wildcard hostname that represents all of the hosts in the cluster. When validating the hostname, the client acknowledges the wildcard hostname as representing all members in the cluster. This ensures that, regardless of the member to which the client connects, hostname validation is successful.

In addition, if a connection is routed to another member in the cluster due to workload balancing or ACR, hostname validation is successful for this new connection since the certificate returned by this member matches the hostname to which the client was originally configured.

The following example shows how the certificate appears for hostname validation to be successful. Note the single SAN entry containing the wildcard symbol 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: h*.db2.example.com

Signature Algorithm : SHA1WithRSASignature
Note: Wildcard hostnames only represent members that share the same domain name, such as 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.

Adding and removing a member from a pureScale cluster

When adding a new member to the cluster, one or more of the server certificate might have to be updated depending on how they’re set up. Please note that server certificates can be updated online: the instance doesn’t have to be brought down to make this change.

If a separate certificate is used for each member in a cluster, the new member needs to have its fully qualified hostname in its certificate. Since a separate certificate is used per member, the other members in the cluster don’t need to be updated.

If a common certificate is used for all members in a cluster, the common certificate has to be recreated to contain an additional SAN entry for this new member and all of the members in the cluster need to be updated to use this newly created certificate if they’re not using a shared keystore.

If a common certificate containing a wildcard hostname is used for all members in a cluster, no updates are needed given that the wildcard hostname in the common certificate can match the new hostname. This certificate configuration might be preferable if new members are frequently added to the cluster since it removes the need to keep creating new certificates.

When removing a member from the cluster, no changes to the certificate used by the cluster are required for hostname validation to be successful.

IP addresses used in the nicbinding.cfg file

If the nicbinding.cfg file is configured to bind each member of a cluster to the IP address of a network interface card (NIC), the server list returned to the client contains IP addresses instead of hostnames for these members. This means that during client reroute or workload balancing, the IP address of the corresponding member is what gets used for the connection and, by extension, hostname validation.

When referencing NIC addresses using the nicbinding.cfg file, use a common certificate for all members in the cluster. The client validates the hostname in the certificate against the hostname to which it was originally configured to connect, which is successful when using a common certificate.

The other option is to have a separate certificate per member, but include the member’s IP address in its certificate. This configuration should be avoided.