Representing servers in a TLS certificate

Certificates need to be created for the Db2 servers to which your clients connect. These certificates are generated from certificate signing requests (CSRs) sent to internal or third party certificate authorities for signing, or are self-signed within your organization. Hostname validation at the Db2 client is successful if the hostname which the client has been configured to connect matches one of the hostnames present in the server certificate. There are several options for representing a Db2 instance in a certificate.

Examples included in this section apply to both and created using IBM Global Security Kit (GSKit).

Using a common name (CN) value

The Common Name field in the subject name of the certificate can be used to specify the hostname of the server. Hostname validation will be successful if the hostname that the client configured matches what is present in the Common Name of the certificate.

If a subject alternate name (SAN) entry is present in the certificate, then the common name is ignored.
Wildcard (*) hostnames in the common name field are supported when performing hostname validation.

Warning: In accordance with RFC 6125, use a Subject Alternate Name (SAN) instead of a common name to specify the server’s hostname in the certificate.

For example, to create a certificate with xyz.db2.example.com as the common name, CN=xyz.db2.example.com needs to be present as part of the -dn option in the gsk8capicmd_64 -cert -create command (for self-signed certificates) or gsk8capicmd_64 -certreq command (for CSRs).

The following example shows how the common name appears in the generated certificate:

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

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

Signature Algorithm : SHA1WithRSASignature

Using DNS Names as SAN values

One or more hostnames can be specified in the certificate using dNSName entries under the Subject Alternate Name (SAN) extension. Hostname validation is successful if the hostname to which the client is configured to connect matches at least one of the dNSName entries. These entries are also referred as DNS Name in some places.

For example, to create a certificate with xyz.db2.example.com in the SAN, you include -san_dnsname "xyz.db2.example.com" option of the IBM Global Security Kit (GSKit) command

The following example shows a certificate generated to include a single DNS name 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: xyz.db2.example.com

Signature Algorithm : SHA1WithRSASignature

To create a certificate with multiple DNS names in the SAN, simply separate them with commas (-san_dnsname "xyz.db2.example.com,abc.db2.example2.com) in the IBM Global Security Kit (GSKit) command.

The following example shows a certificate generated to include multiple DNS names 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: xyz.db2.example.com
        dNSName: abc.db2.example2.com

Signature Algorithm : SHA1WithRSASignature

You can also configure your certificate to include a common name value as well as a SAN value that is used for hostname validation.

Note: With this configuration, the common name value is ignored when doing hostname validation since a SAN is specified in the certificate.

To create a certificate with xyz.db2.example.com in the common name and abc.db2.example2.com in the SAN, include both CN=xyz.db2.example.com as part of the -dn option and "abc.db2.example2.com" as the -san_dnsname option in your IBM Global Security Kit (GSKit) command.

The following example shows a certificate generated to include both a common name value and a DNS name in the SAN:

Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=Example Enterprise CA
Subject : CN=xyz.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: abc.db2.example2.com

Signature Algorithm : SHA1WithRSASignature

Using IP addresses as SAN values

You can specify one or more IP addresses in your IBM Global Security Kit (GSKit) command using the -san_ipaddr field.

As a best practice, use hostnames instead of IP addresses in the certificate for the following reasons:

An IP address is not necessarily a reliable identifier for a server, due to private networks, NAT, etc.
According to RFC 6125, less than 1% of TLS certificates issued use them.
A certificate has to be recreated every time a server’s IP address changes.

However, if the client connects to a server using an IP address (IPV4 or IPV6), this IP address has to be present in the server’s certificate for hostname validation to be successful.

Note: When an IP address is used to connect to a server, this address is not resolved to its hostname to match against the server certificate when performing hostname validation.

To create a certificate with 127.0.0.1 in the SAN, include -san_ipaddr "127.0.0.1" in the IBM Global Security Kit (GSKit) command.

The following example shows a certificate generated to include an IP address 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
        iPAddress=127.0.0.1

Signature Algorithm : SHA1WithRSASignature

To create a certificate with multiple IP addresses in the SAN, simply separate them with commas (-san_ipaddr "127.0.0.1,127.0.0.2") in the IBM Global Security Kit (GSKit) command.

The following example shows a certificate generated to include multiple IP addresses 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
        iPAddress=127.0.0.1
        iPAddress=127.0.0.2

Signature Algorithm : SHA1WithRSASignature

To create a certificate with a common name value as well as an IP address in the SAN, simply include both of the options (-dn "CN=xyz.db2.example.com,..." -san_ipaddr "127.0.0.1") in the IBM Global Security Kit (GSKit) command.

Note: In this case, the common name value is ignored when doing hostname validation since a SAN is specified in the certificate.

The following example shows a certificate generated to include both a common name and an IP address in the SAN:

Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=Example Enterprise CA
Subject : CN=xyz.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
        iPAddress=127.0.0.1

Signature Algorithm : SHA1WithRSASignature

To create a certificate with both a DNS Name and an IP address in the SAN, simply add -san statements for both options (-san_dnsname "xyz.db2.example.com" -san_ipaddr "127.0.0.1",) in the IBM Global Security Kit (GSKit) command.

The following example shows a certificate generated to include both a DNS name and an IP address 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: xyz.db2.example.com
        iPAddress=127.0.0.1

Signature Algorithm : SHA1WithRSASignature

Using wildcards in hostnames

Certificates with wildcard character, *, as part of the hostnames are supported when performing hostname validation on the client. However as specified in RFC 6125, the client employs the following rules when comparing hostnames against wildcard certificates:

The wildcard character can only be present in the left-most label and can only be included once.
The wildcard character can only be used to match a single label.
The wildcard character doesn’t have to be the only character in the label.
The wildcard character can match zero or more characters in the label.

Note: The term label in these rules refers to domain name label. Labels are strung together separated by dots to form a fully qualified hostname. For example, xyz, db2, example, and com are the labels that constitute the fully qualified hostname, xyz.db2.example.com.

For example the following use of wildcards is permitted:

"*.db2.example.com"
"f*.db2.example.com"

However, the following examples are not permitted, as the wildcard is used in labels other than the leftmost label in the hostname:

"foo.*.db2.example.com"
"*.db2.example.*.com"

To create a certificate with *.db2.example.com as the common name, include CN=*.db2.example.com as part of the -dn field in the IBM Global Security Kit (GSKit) command

To create a certificate with *.db2.example.com in the SAN, include -san_dnsname "*.db2.example.com" in the IBM Global Security Kit (GSKit) command. This allows the SAN to represent all hostnames in the example.com domain.

The following example shows a certificate generated to include a single wildcard hostname 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: *.db2.example.com

Signature Algorithm : SHA1WithRSASignature

To create a certificate with multiple wildcard hostnames in the SAN, you need to include both hostnames, separated by a comma, within the -san_dnsname field of the IBM Global Security Kit (GSKit) command.

The following example shows a certificate generated to include multiple wildcard hostnames:

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
        dNSName: a*.db2.example2.com

Signature Algorithm : SHA1WithRSASignature

To create a certificate with a combination of hostnames and wildcard hostnames, simply include both in the -san_dnsname field of the IBM Global Security Kit (GSKit) command.

-san_dnsname "xyz.db2.example.com,*.db2.example2.com"

Using short hostnames

A short hostname is essentially the first label of your fully qualified domain name (xyz.db2.example.com). When a Db2 client is configured to connect to a server using a short hostname, this hostname is not resolved into a fully qualified domain name when hostname validation is performed. The reasoning is that figuring out which domain name to append to this short hostname depends on the contents of your /etc/resolv.conf file. The client shouldn’t necessarily place its trust in the resolv.conf file, since it is possible for this file to be modified by a remote actor through DHCP.

This is also the industry standard method of hostname validation.

Because of this, use of short hostnames is not recommend when configuring your Db2 clients for hostname validation. However, your business may require you to use a short hostname when configuring the server connection information on the client. When this is the case, the certificate returned by the server during the TLS handshake must also contain this short hostname.

For example, if the client connects using a connection string that looks like Hostname=xyz;Security=SSL;SSLClientHostnameValidation=Basic;Database=…, the certificate returned by the server should look something like the following.

Key Size : 2048
Version : X509 V3
Serial : xxx
Issuer : CN=Example Enterprise CA
Subject : CN=xyz.db2.example.com
Not Before : November 26, 20204:44:11 PM EST

Not After : November 27, 20214:44:11 PM EST

Extensions
    subjectAlternativeName
        dNSName: xyz

Signature Algorithm : SHA1WithRSASignature