TLS Client Authentication with Db2 – Part 3 Setting up Db2 Clients

See also Part 1 and Part 2 of this series

In previous articles, we revisited the basic principles of TLS encryption, their relevance for Db2 administrators and, in a deeper dive, the special characteristics for client certificate authentication. When your focus is Db2 for z/OS, you should have learned which components participate in the configuration of TLS client certificate authentication on the z/OS server side.

Before we continue to the Db2 client side, we recommend that you verify the TLS configuration on the Db2 for z/OS server side. We recommend that you configure TLS server certificate authentication and client certificate authentication in parallel, even if client certificate authentication is your long-term objective.

We also anticipate that a certificate mapping definition in z/OS exists. So, the subject and/or issuer distinguished name maps a userid on z/OS.

Getting started on the Db2 client side

First, you need a Db2 Client, Runtime Client or Data Server Driver on the client side. TLS is a security related topic and – as for any security related topic – software currency is essential. We recommend using a current version of the Db2 client products. For example, for an ODBC / CLI application you need at least version 11.5.8 of the Db2 clients or drivers if you need support for TLS v1.3.

For Java, TLS support is provided by the underlying Java Runtime Environment (JRE). Java 11 and 17 support TLS v1.3 out of the box. For Java 8, you need at least build 8u261 if you are using the Oracle JDK/JRE.

Getting the client certificate

TLS client certificate authentication requires a certificate plus a private key on the client side. Every company or institution has their own procedures how client certificates are generated and signed by a Certificate Authority. When a client certificate is issued, you should have a file in PKCS#12 format (also known as pfx file or p12 file). This file contains:

• the private key for that client
• the client certificate with public key, issuer name, subject name, and other publicly available information
• the certificate chain (the chain of CA certificates which signed the client certificate)

The private key is considered as strictly confidential information, so the PKCS#12 file is protected by a password. You need that password to make the PKCS#12 file available to your Db2 client application.

There exist several tools to manage PKCS#12 files, for example to view the certificate, check its expiration date or review the subject or issuer distinguished names on the certificate.

• Java Keytool: Part of a Java Runtime Environment. Primarily intended to set up keystores and truststores for Java applications, but you can also use it to have a deeper look at the contents of a PKCS#12 file.
• IBM GSKit / gsk8capicmd utility. IBM ships this tool with several software products, for example also with Db2 LUW server. It can also be downloaded from IBM FixCentral.
• OpenSSL: probably the most popular tool to manage certificates in the Linux/Unix world.

Let us assume your security administrator generated a PKCS#12 file for your Db2 client and you want to review the contents. In case, Java keytool is installed on your workstation, navigate to the directory of your PKCS#12 file and enter the following:

keytool -list -keystore mykeydb.p12 -storepass mykeydb

Replace “mykeydb” with the password for the PKCS#12 file.

Keytool returns a list of certificates in the PKCS#12 file. This includes your own client certificate as well as the CA certificates of the signing chain.

The first certificate in that list, named “db2sslclient” in that example represents a certificate associated with a private key (“keyEntry”). The other two certificates (“idug ca cert” and “idug intermediate cert”) represent CAs which signed the client certificate (“trustedCertEntry”).

Run the following command for the details of the client certificate:

keytool -list -keystore mykeydb.p12 -storepass mykeydb -v -alias db2sslclient

This returns information about the client certificate and the certificate chain. See here an extract with the most relevant information:

The certificate has been issued to “CN=Db2SSLCLient,OU=IDUG,O=IDUG,L=Toronto,ST=ON,C=CA” (Owner) and is signed by “OU=IDUG Intermediate CA,O=IDUG,L=LUW,C=US”.

The output also contains information about two more certificates, the certificate of the intermediate CA (which signed the client certificate) and the root CA (which signed the intermediate CA’s certificate).

When you have IBM GSKit installed, equivalent commands look like this.

For the list of certificates in the PKCS#12 file:

gsk8capicmd_64 -cert -list -db "mykeydb.p12" -pw mykeydb

Returns:

For details of the client certificates:

gsk8capicmd_64 -cert -details -db "mykeydb.p12" -pw mykeydb -label “db2sslclient”

Returns:

Note that this command does not show the entire certificate chain as the equivalent keytool command does.

Finally, the equivalent commands for OpenSSL.

For the list of certificates in the PKCS#12 file:

openssl pkcs12 -in mykeydb.p12 -passin pass:mykeydb -nokeys

For details of a specific certificates:

openssl x509 -noout -text -in mykeydb.p12 -passin pass:mykeydb

Getting the CA certificate for validation of the server certificate

As discussed in the previous articles, clients need to verify the certificate sent by the Db2 server first before sending their own certificate. This check is performed against a CA certificate which is at the top at the server’s certificate chain. Ideally, it is the same CA certificate which is also at the top of the client’s certificate chain.

There are multiple options to make a CA certificate accessible for a Db2 client application.

• Certificate file: the certificate exists in the file system as PEM or CRT file.
• Java Keystore / GSKit KeyDB: the certificate exists in a password-protected keystore or key database, e.g. in PKCS#12 or JKS format.
• Windows certificate store: on Windows systems, certificates can also be stored in the local Windows certificate store.

The Windows certificate store can also used for client certificates. See below for more information.

Configuring the Db2 Client – ODBC/CLI

You may be aware of several options how you can configure client connections on a Db2 Client, Runtime Client, or Data Server Driver. We are focusing on configuration with the db2dsdriver.cfg XML file which is the recommended option.

See here an example for a configuration where the client certificate is stored in a password-protected PKCS#12 file:

The alias name, DB2ZCLN in this example, is used as data source name by the ODBC/CLI applications. The port name (3617) is the TCPIP port of the Db2 for z/OS server which is configured as secure port AND configured for client certificate authentication in AT-TLS.

• SecurityTransportMode: is set to “SSL” regardless of server or client certificate authentication.
• SSLClientKeystoredb: the full path to the keystore which contains the client certificate and the certificate chain.
• SSLClientKeystoreDBPassword: the password for the file in clear text.
• Authentication: Must be set to “CERTIFICATE” for client certificate authentication. This prevents the ODBC/CLI from trying to initiate a userid and password-based authentication.
• SSLClientLabel: Required for client certificate authentication. Locates the client certificate in the keystore.

As you can see in this example, there is still sensitive information, the password for the keystore, in clear text format. Therefore, Db2 clients can optionally access a so-called “stash” file which contains the password for the keystore. Applications which have read access to the stash file can use it to open the keystore without need to know the actual keystore password.

Stash files can be created with IBM GSKit’s command line utility. Assume you have an existing PKCS#12 file and know it’s password, the command would look like this:

gsk8capicmd_64 -keydb -stashpw -db "mykeydb.p12" -pw mykeydb

This creates a file with the extension “.sth”, “mykeydb.sth” in this example. Once you created this file, make sure that all users who need access to the keystore with the client certificate have read permissions on the stash file.

The configuration in db2dsdriver.cfg looks different in that case:

The keyword “SSLClientKeystoreDBPassword” is replaced with “SSLClientKeystash”.

On Windows platforms, the Windows certificate store can be used to keep the CA certificate for server validation as well as the client certificate and its certificate chain.

You need to import the client certificate, its certification chain, and the private key into the Windows certificate store first. These certificates are assigned to a Windows user account – so make sure you select the correct account from which you launch the Window certificate manager (certmgr.msc).

After the import, you should see your client certificate and the CA certificates from the PKCS#12 file in the “CurrentUser\Personal\Certificates” folder of the Windows certificate store:

Now you can change the configuration in the db2dsdriver.cfg file to take the certificate from the Windows certificate store:

As you can see, no PKCS#12 file, no password, no stash file required. Once a user authenticates successfully against Windows, she or he has access to the personal certificates without an additional authentication step.

Also notice, that currently, as of V11.5.9 of the Db2 Clients / Data Server Driver products, it is required to use TLS v1.2 (TLS v1.3 is currently not supported for that mechanism).

Testing the Db2 CLI/ODBC connection

No matter which approach you choose, you can take the db2cli utility program, shipped with the Db2 Client and Data Server Driver products, to test your client certificate setup.

Open a Db2 Command Window (Db2 Client, Runtime Client) or a command window or shell for which the Db2 environment variables are set. Invoke db2cli to validate your db2dsdriver.cfg configuration file, connect to a Db2 for z/OS data source via client authentication and check the Db2 Connect license in just one command:

db2cli validate -dsn <name of your DSN from db2dsdriver.cfg>
-connect -displaylic

Unlike the “normal” invocations of db2cli for non-TLS connections or connections with TLS server certificate authentication, no userid and password is required. The command would fail in case you provided a userid and password.

For a successful connection, you would get a message similar like this:

Your output may look different, depending on the type of Db2 Connect license and the license version.

Making it available to ODBC (Windows)

An extra configuration step is required if you want this connection be available for Windows ODBC applications. Windows keeps ODBC connections in its own registry either as a system or user data source. The definition in db2dsdriver.cfg (or equivalent options, db2cli.ini or a local Db2 catalog) is not sufficient. Use db2cli to register your existing definitions in db2dsdriver.cfg in Windows ODBC:

db2cli registerdsn -add -dsn <name of your DSN from db2dsdriver.cfg>
-system (or -user)

Windows administrator permission is required to register a System DSN (option -system). You can use db2cli again to test the connection, in this case via the ODBC stack:

db2cli validate -dsn <name of your DSN from db2dsdriver.cfg>
-connect -displaylic -odbcdsn

In case of success, you can use that connection without need for userid and password in an application that connects to ODBC data sources such as Microsoft Excel.

Important: it is not mandatory that you keep your client certificate in the Windows certificate store in order to use client certificate authentication for Windows ODBC. ODBC registration is required, regardless of managing the client certificate in a keystore (e.g. PKCS#12 file), using a password or a stash file or keeping it in the Windows certificate store.

Configuring JDBC clients

Db2 JDBC applications can use the PKCS#12 file with the client certificate and its private key similar to ODBC/CLI applications. JDBC requires the specification of additional data source properties. Like for ODBC/CLI, there exist different options.

If you keep your client certificate in a PKCS#12 file, you need to specify its password as well. See here an example how the JDBC properties for a Db2 data source could look like:

Note that our PKCS#12 file is referenced twice. Java distinguishes between a “Truststore” and a “Keystore”. Java looks in a “Truststore” for CA certificates used for validation of a server certificate. A “Keystore” is used to locate client certificates when client certificate authentication is required.

The example above shows that Truststore and Keystore can be the same. Our example has a root CA certificate which signed the Db2 server certificate and the client certificate. So, it is contained in the client’s PKCS#12 file anyway.

In case that you have a separate CA certificate in a CRT or PEM file which your application uses for validation of the Db2 server certificate, you can point the JDBC application directly to that file:

This is also recommended in case of JDBC applications with TLS server certificate authentication.

You may also notice that Db2 JDBC does not require a certificate label or alias name as Db2 ODBC/CLI does. If more than one potential client certificate is found in the keystore, JDBC will try potential certificates until one of them matches.

Unlike Db2 ODBC/CLI there is no concept of a “stash” file for Java applications. It is required to specify a password for the Keystore (and Truststore).

On Windows platforms, JDBC applications can also leverage the Windows certificate store. Assuming your Db2 server’s certificate and your client certificate have the same root CA in their certificate chain, the configuration would look like this:

Truststore type “Windows-MY” tells Java to look in the “CurrentUser” section of the Windows certificate store for the CA certificate. The same applies for the client certificate as keystore type is set to “Windows-MY” as well.

In case you keep your CA certificates separately (in the “Local Computer” part of the Windows certificate store), use “Windows-ROOT” instead of “Windows-MY”.

Important: check the settings in the “java.security” file of your JRE when you want to use the Windows certificate store for server or client certificate authentication. Add the following line if not already present:

Replace <nn> with a number according to the instructions in the java.security file.

Conclusion

As you have seen, a basic understanding about certificates is helpful if you want to set up a Db2 application for client certificate authentication. Multiple options exist to make client certificates available to your Db2 client applications. The correct configuration on the Db2 server and client side can be a time-consuming process. It is highly likely that you need multiple iterations if you do this for the first time.

In the fourth and last article of this series, we will discuss frequent errors and how you can resolve them. We will also discuss how Db2 for z/OS native REST services can be setup for TLS server and client authentication.

Read More

TLS Client Authentication with Db2 – Part 1: Introduction

TLS Client Authentication with Db2 – Part 2 Setting up Db2 for z/OS servers