Creating client certificates for a secured connection from Web Viewer 12.1 to DB2

Products

• Output Management Web Viewer

Issue/Introduction

Here are the instructions for creating the client certificates (keystore and truststore) for the secured connection from Web Viewer to DB2.

This requires Web Viewer LU07347 Cumulative Build 226 or higher.

Environment

Release : 12.1

Cause

Enhancement

Resolution

The need for a keystore and a truststore on the client side depends on:

• the AT-TLS policy that defines the secured Db2 server port configuration
• the Db2 server certificate and the Certificate Authorities (CA) that signed the server certificate which are stored in a server-side External Security Manager (ESM, e.g. ACF2, RACF, TSS) keyring owned by the server (Db2 STC authid).

FYI, a “keyring” is a mainframe ESM construct that can be thought of as a keystore and a truststore combined. (FYI, and similarly, it is also possible to combine a keystore/trustore into a single keystore/truststore but in reality this is not usually done on non-mainframe platforms.)

The AT-TLS policy

If not already completed, define an AT-TLS policy in order to secure the Db2 port using AT-TLS. As a start refer to: https://www.ibm.com/docs/en/zos/2.5.0?topic=zos-communications-server and https://www.redbooks.ibm.com/abstracts/redp4799.html?Open&pdfbookmark

An enabled AT-TLS policy for the Db2 server provides several attributes including the “LocalPortRange” (the port number defined in Db2 as the secured port), the “keyring” owned by the Db2 STC authid which contains the server (Db2) certificate and possibly CA signing certificates, and the “HandshakeRole”. A sample of an AT-TLS policy is shown below.

If the AT-TLS policy’s HandShakeRole is set to “ServerWithClientAuth” then when the connection handshake is performed, the server (Db2) sends its certificate (signed by some Certificate Authority) to the client for the client to verify the server cert. AND the server demands that the client send its certificate so that the server can verify the client cert. In order for the client/server to verify the received certificate they must “recognize” the cert and signers (CAs) of the received certificate. 

Using ServerWithClientAuth means that the client needs to send a client certificate, pulled from its keystore, to the server which the server will verify.

If the HandShakeRole is set to “Server” then the client does NOT need to send a certificate to the server. Effectively, this means that the client does not need a keystore because the server does not ask the client for its client certificate.

In summary: a keystore (on the client side) having a client certificate is needed if the AT-TLS policy (for Db2 port) is configured with HandShakeRole = SeverWithClientAuth. Otherwise the keystore is not needed for HandShakeRole = Server.

A client truststore (which can unspecified and defaulted to the lib/security/cacerts file from the jdk) is required because it contains the “well known” (e.g. Digicert, Verisign, GoDaddy, etc.) CA certificates which the client uses to verify the sever certificate sent by the server.

A server that requires a client certificate makes things more complex and secure. Initially, at least configure Db2 with HandShakeRole = Server. Ultimately the HandShareRole is a customer decision but the HandShakeRole = Server is acceptable in most cases since Db2 with ESM already provides their own security.

The Db2 server certificate

If the Db2 server certificate is signed by a well-known or traditional Certificate Authority(s) then the java lib/security/cacerts file will likely contain the necessary CA certs (i.e. truststore) that can be used to verify the Db2 server certificate. If desired, you can extract the relevant certs from cacerts and use the Keystore Explorer to build a truststore using those certs.

If the Db2 server certificate is self-signed:

• It needs to be exported from the ESM
• Download to the client machine
• Add to a truststore that is provided to the client so that the client can verify the Db2 server certificate.
• Use the Keystore Explorer to import the certificate
• Create a truststore (pkcs#12).

Alternatively, you can user your browser to grab the certificate by trying to connect to the Db2 port as follows:

• On Chrome, try to connect to the secured port. Be sure to include https.
• Click on the “not secure” (or lock). 
• In the popup, click to view the certificate.
• Click on the Details tab. Then click on export to export the certificate (.crt file) to a file on your machine.
  
• Use the Keystore Explorer to create a truststore (.jks file) by importing the certificate that you just exported via the browser.
• The Keystore Explorer prompts for a password to use for the truststore  that you are creating.
• Then test that the truststore works.