Hostname Validation in Db2
For the past 30 years, Transport Layer Security (TLS) has been the cornerstone of securing data in transit on the web. Billions of messages are sent across the internet every year, and the vast majority of them rely on the security provided by TLS to protect their data. As the security landscape constantly changes, TLS too has evolved over the years to adapt and combat new and emerging threats. One of the oldest problems of TLS has to do with authentication: how can a TLS client tell that the server it is communicating with is the server it wants to connect to? Without a method of doing this, an attacker may be able to pretend to be the server, intercept all communication that the client thinks is heading for the server, and do whatever they want with it. The client would be completely oblivious to the fact that it is not communicating with the server it is intending to. One of the technologies developed to answer this question is hostname validation.
Hostname validation is simple: in a TLS handshake, the server sends its certificate to the client. This certificate contains information telling the client who it is talking to, namely, the server’s hostname or IP address. When the client receives the server certificate, it validates that the certificate is signed by someone the client trusts. As part of this, the client will compare the server’s hostname or IP address in the certificate with the hostname or IP address it requested to connect to. If it matches, the identity of the server is validated.
Usually, certificates are signed by trusted certificate authorities (CA), who will validate your ownership over any hostnames or IP addresses as part of obtaining the certificate. This prevents malicious actors from obtaining seemingly legitimate certificates with someone else’s address and ensures the integrity of the hostname validation mechanism.
Db2 11.5.6 launched with a new optional hostname validation client-side feature that does exactly this. It is compliant with RFC 6125 and aims to better protect your data against malicious actors. In 12.1, we further improved Db2’s security by enabling this client-side feature by default. Now all connections utilizing TLS will take advantage of this feature out of the box.
However, this means that if you don’t have your server certificates configured correctly, your connections will fail. This blog aims to provide a brief introduction to hostname validation in Db2, how to take advantage of it, and how to troubleshoot your connections if hostname validation causes them to fail.
Taking Advantage of Hostname Validation
If you are on 11.5.6 or later, you can enable hostname validation on your TLS clients by setting the DS Driver parameter SSLClientHostnameValidation parameter to Basic. On 12.1, you don’t need to do anything – this is enabled out of the box. However, your server certificate does need to adequately represent your servers in a way that suits your configuration. Some of these configurations will be detailed below.
The Server Certificate
A TLS certificate is what is used to establish the identity of the TLS peer and the parameters necessary for an encrypted session. It may look something like this:
...
Serial : 1f384365bdf43cbd
Issuer : “CN=Dept. X Db2 Server”
Subject : “CN=Dept. X Db2 Server”
Not Before : June 25, 2024 3:35:26 PM EDT
Not After : June 26, 2025 3:35:26 PM EDT
…
Extensions
subjectAlternativeName
iPAddress: 127.0.0.1
dNSName: h1.db2.example.com
…
Signature Algorithm : SHA256WithRSASignature (1.2.840.113549.1.1.11)
…
Parts of the certificate have been left out for brevity, but the important portions to pay attention to are the Subject and subjectAlternativeName (SAN) (both bolded). These are the values used for comparison against the client’s configured address in hostname validation. The rules used to validate the hostname is compliant with RFC 6125. More notably, according to this RFC, if the SAN is provided, the CN is ignored.
Representing Servers in the Certificate
How you configure the addresses in your certificate is dependent on your topology and configuration. The key point is that the address in your certificate must match the address your client is configured to connect to. To get you started, we’ll walk you through some of the most basic scenarios.
Serial Client-Server Connection
This one is relatively simple. Let’s say you have a CLI application that connects to a server at h1.db2.example.com. Your connection string may look something like this:
"database=ssldb;hostname-h1.db2.example.com;port=60006; security=SSL;sslservercertificate=server.arm;uid=netwon;pwd=password;"
The SAN in your server certificate should be h1.db2.example.com. You can create such a certificate with GSKit:
gsk8capicmd_64 -cert -create -db /my/keystore.p12 -stashed -label serverlabel -san_dnsname h1.db2.example.com -dn ‘CN=test’
and make sure our database is using the certificate serverlabel with
update dbm cfg using SSL_SVR_LABEL serverlabel
Note that this example creates a self-signed certificate for the purposes of showcasing the certificate contents. In your case, it may be more appropriate to create a certificate signing request (CSR) which will be sent to the CA to sign. The relevant portions of the certificate may look like this:
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
Signature Algorithm : SHA1WithRSASignature
Clients using this certificate will be able to connect to your server.
Serial Client-Server Connection with Alternate Server
But let’s say you wanted to configure an alternate server for your client to reroute to in the case of an outage. This alternate server may sit on a different hostname (e.g h2.db2.example.com). You may have this configured in your db2dsdriver.cfg like so:
<configuration>
<dsncollection>
<dsn alias="test" name="testdb" host="h1.db2.example.com" port="1234">
</dsn>
</dsncollection>
<databases>
<database name="testdb" host="h1.db2.example.com" port="1234">
<acr>
<parameter name="enableAcr" value="true"/>
<parameter name="maxAcrRetries" value="10"/>
<parameter name="acrRetryInterval" value="5"/>
<parameter name="enableAlternateServerListFirstConnect" value="true"/>
<alternateserverlist>
<server name="server1" hostname="h2.db2.example.com" port="1234"/>
</alternateserverlist>
</acr>
</database>
</databases>
</configuration>
Db2 makes hostname validation very easy in these scenarios. The certificate used must contain either the hostname of the primary server (h1.db2.example.com), or the hostname of the alternate server (h2.db2.example.com). Hostname validation will be successful for either of these hostnames when retrying the connection to the alternate server. For the primary hostname configured, the requirements remain the same as the Serial Client-Server Connection.
Multi-node Topologies
Db2’s hostname validation is not limited to just one address; it also supports multiple hosts. To illustrate this, we will use DPF as an example. You may also wish to set up hostname validation in a pureScale environment. You may find the relevant documentation here.
On DPF, each partition may live on a different machine with a different hostname. As before, the hostname that the client connects to must be reflected in the certificate. Let’s say we have the following cluster:
partition 0 - h1.db2.example.com (catalog partition)
partition 1 - h2.db2.example.com
partition 2 - h3.db2.example.com
partition 3 - h4.db2.example.com
If a client wants to connect to a catalog partition, then the connection string may look something like this:
Hostname=h1.db2.example.com;Security=SSL;Database=…
The SAN must include the target hostname:
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
Signature Algorithm : SHA1WithRSASignature
But what if we want to connect directly to a non-catalog partition? We have a number of options on how the certificates for this topology are set up.
- Use a separate certificate for each DPF host. If a client wishes to connect to h2.db2.example.com, then the SAN in the certificate must contain h2.db2.example.com.
- Use a common certificate with multiple SANs. In this case, you would just need one certificate shared between all hosts. The certificate would contain all the hostnames of all the partitions in the SAN. You can create a certificate like this in GSKit:
gsk8capicmd_64 -cert -create -db /your/keystore -stashed -label yourlabel -dn ‘CN=yourlabel’ -san_dnsname ‘h1.db2.example.com,h2.db2.example.com,h3.db2.example.com,h4.db2.example.com’
This would result in a certificate with the following in the SAN:
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: h1.db2.example.com
dNSName: h2.db2.example.com
dNSName: h3.db2.example.com
dNSName: h4.db2.example.com
...
3. Use a common certificate with a wildcard hostname. A wildcard hostname looks like this:
*.db2.example.com. All hostnames in the .db2.example.com domain would match against
this certificate. However, this would assume that all hosts in your cluster share the same
domain name. To create a certificate like this, you can use:
gsk8capicmd_64 -cert -create -db /your/keystore -stashed -label yourlabel -dn ‘CN=yourlabel’ -san_dnsname ‘h*.db2.example.com’
This would create a certificate like this:
Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=h1.db2.example.com
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: h*.db2.example.com
...
4. Use a combination of 2 or 3. A certificate can contain both wildcard hostnames and non-
wildcard hostnames.
An additional caveat when using hostname validation with DPF is that new hosts in the cluster must also be represented in the server certificates in one of the four ways above.
Troubleshooting Hostname Validation
When an error occurs due to hostname validation, the client will return SQL20576N, reason code 1:
SQL20576N The command or operation failed because a TLS connection
could not be established with reason "1" and additional
information "<configured hostname>".
where <configured hostname> is the hostname the client is configured to connect to. To troubleshoot this error, you will need to examine the client’s db2diag.log for the following information:
2021-04-06-16.35.00.951803-240 E9461858E1589 LEVEL: Error
PID : 2996888 TID : 140497763679360 PROC : db2bp
INSTANCE: <instance user> NODE : 000
HOSTNAME: <client hostname>
FUNCTION: DB2 UDB, common communication, sqlccHostnameValidationDumpCert, probe:500
MESSAGE : Failed to validate the hostname against the server certificate sent
by the server. Dumping the expected hostname(s), certificate CN(s), and
certificate SAN(s).
DATA #1 : String, 19 bytes
Hostname configured
DATA #2 : String
<Hostname that the client configured>
DATA #3 : String, 33 bytes
Hostname in the server list entry
DATA #4 : String
<Hostname associated with the server list entry>
DATA #5 : String, 47 bytes
Hostname of the last connected alternate server
DATA #7 : String, 29 bytes
Certificate Dump: Common Name
DATA #8 : String
<hostname in the common name of the subject>
DATA #9 : String, 52 bytes
Certificate Dump: Subject Alternative Name (DNSNAME)
DATA #10: String, 27 bytes
<Hostnames in the SAN>
DATA #11: String, 55 bytes
Certificate Dump: Subject Alternative Name (RFC822NAME)
DATA #12: String, 50 bytes
Server certificate does not have any RFC822 names.
DATA #13: String, 58 bytes
Certificate Dump: Subject Alternative Name (DIRECTORYNAME)
DATA #14: String, 53 bytes
Server certificate does not have any Directory names.
DATA #15: String, 48 bytes
Certificate Dump: Subject Alternative Name (URI)
DATA #16: String, 42 bytes
Server certificate does not have any URIs.
DATA #17: String, 54 bytes
Certificate Dump: Subject Alternative Name (IPADDRESS)
DATA #18: String, 50 bytes
Server certificate does not have any IP addresses.
This message logs the hostname the client was configured with and all the relevant fields in your certificate that are used in comparison. You can use this message to compare what hostname your client was trying to connect to with the hostnames found in your certificate. If a field does not contain any hostnames or IP addresses, it will be indicated like so:
DATA #17: String, 54 bytes
Certificate Dump: Subject Alternative Name (IPADDRESS)
DATA #18: String, 50 bytes
Server certificate does not have any IP addresses.
You can also view the contents of your certificate at the server with:
gsk8capicmd_64 -cert -details -db /your/keystore -stashed -label yourlabel
You will be able to see the SAN extension contents as well as the CN, which may also help.
If a connection fails because of hostname validation, you will need to regenerate your server’s certificate using the correct hostname information as described above. Various other configurations and topologies may be found in the Db2 Documentation.
Closing Remarks
Db2’s hostname validation feature makes it extremely simple for Db2 clients to validate the identity of the server they are communicating with. In this post, we examined how to configure your servers for hostname validation in two different topologies. We learned about TLS certificates and the SAN extensions that are used to compare against the client’s configured hostname. There are many other places where hostname validation is available. Hostname validation is also available out of the box for HADR Primary/Standby communications, communication with KMIP centralized keystores for native encryption, DRDA data sources for federation, and much more. You can be assured that Db2 has the safety of your data in mind and will continue to be a driving force for the security of your business.
About the Author
Cyrus Ng is a Software Developer on the Db2 Security team at the IBM Toronto Lab with a Bachelor's in Computing from Queen’s University. He has worked with various security features in Db2, such as TLS 1.3 support, hostname validation, and audit. Cyrus can be reached at cyrus.ng@ibm.com.
Further Reading
- https://www.ibm.com/docs/en/db2/11.5?topic=transit-hostname-validation
- https://www.ibm.com/docs/en/db2/11.5?topic=transit-digital-certificates
- https://www.ibm.com/docs/en/db2/11.5?topic=validation-configuring-db2-instances
- https://www.ibm.com/docs/en/db2/11.5?topic=validation-configuring-db2-clients
- https://www.ibm.com/docs/en/db2/11.5?topic=validation-troubleshooting-hostname
- https://www.ibm.com/docs/en/db2/11.5?topic=validation-communication-between-primary-standby-hosts-in-hadr
- https://www.ibm.com/docs/en/db2/11.5?topic=encryption-data-in-transit