TLS Client Authentication with Db2 – Part 2 Setting up Db2 for z/OS servers
See also Part 1 and Part 3 of this series
In a previous blog, we discussed the basic principles of TLS encryption and their relevance for Db2 administrators, no matter whether you are part of the Db2 LUW or Db2 for z/OS ecosystem. You should have learned that a successful TLS handshake, which is initiated from the client side at the beginning of a conversation with a Db2 server, is essential for an encrypted connection.
Also, we have shown that certificates are a core component of that TLS handshake. Partners in a TLS handshake present certificates as a proof of identity to the other partner. This is necessary to establish a level of trust. We also discussed the different characteristics of TLS server certificate vs. TLS client certificate authentication.
This article describes the required steps for setting up TLS client certificate authentication for Db2 clients and Db2 for z/OS servers. As mentioned in the previous article, Db2 LUW servers do not support TLS client certificate authentication.
Setting up the Db2 for z/OS server side - Certificates
Independent of TLS server or client authentication, a Db2 for z/OS server needs a certificate which is presented to a client in the handshake process. The following examples show how such a certificate can be generated with RACF. Note: in case you have a different z/OS security manager, refer to the documentation of that product for the equivalent commands.
The Db2 certificate can be generated as site or as personal certificate. The example below is for a personal certificate. This means, the certificate is assigned to the RACF userid owning the started task for the DDF (DIST) address space of the Db2 subsystem:
RACDCERT ID(DB2USER) GENCERT -
SUBJECTSDN(CN('DB2Z.ZOS.IDUG.ORG') -
OU('IDUG') -
O('IDUG') -
L('ZOS') -
SP('IDUG') -
C('US')) -
ALTNAME(IP(10.11.222.99)) -
NOTAFTER(DATE(2025-05-31)) -
WITHLABEL('DB2ZSERVER') -
SIGNWITH(CERTAUTH LABEL('IDUG CA CERT'))
The certificate, assigned to RACF user DB2USER, is generated and signed by a Certificate Authority (CA) in the local RACF database. The CA certificate has the label ‘IDUG CA CERT’. In case your RACF is not used as a CA you need to generate a certificate request (RACDCERT CERTREQ command), send this to your CA and import the certificate back into RACF once it is signed by the CA.
This example defines a so-called subject distinguished name (SDN) to identify the owner of the certificate and an alternate name (ALTNAME). The keyword ALTNAME is optional, but it may become relevant in the Db2 context. It can contain an IP address or DNS name (host name) of the server who uses this certificate for TLS handshakes. Db2 clients can optionally check that this IP address or DNS name in the certificate matches the IP address or DNS name of the Db2 server they are connecting to.
The certificate needs to be assigned to a RACF (or equivalent product) keyring. This is the equivalent to keystores in the non-mainframe ecosystem. The keyring itself is assigned to a RACF userid (in our case the owner of the Db2 DIST address space) and needs, in addition, the CA certificate which was used for signing. See the following commands to create a keyring and assign (“connect”) certificates to it:
RACDCERT ID(DB2USER) ADDRING(DB2ZKEYRING)
RACDCERT ID(DB2USER) CONNECT(CERTAUTH LABEL('IDUG CA CERT') RING(DB2ZKEYRING))
RACDCERT ID(DB2USER) CONNECT(ID(DB2USER) LABEL('DB2ZSERVER') –
RING(DB2ZKEYRING) DEFAULT)
These examples above show a server certificate (identified by the keyword “LABEL”) which is assigned to a userid (DB2USER). As an alternative, you can use SITE certificates which can be shared by multiple users. See this example for setting up the keyring for DB2USER with a SITE certificate:
RACDCERT SITE GENCERT -
SUBJECTSDN(CN('ZOS.IDUG.ORG') -
OU('IDUG') -
O('IDUG') -
L('ZOS') -
SP('IDUG') -
C('US')) -
ALTNAME(IP(10.11.222.99)) -
NOTAFTER(DATE(2025-05-31)) -
WITHLABEL('IDUGSITE') -
SIGNWITH(CERTAUTH LABEL('IDUG CA CERT')) -
KEYUSAGE(HANDSHAKE,DATAENCRYPT)
RACDCERT ID(DB2USER) ADDRING(DB2ZKEYRING)
RACDCERT ID(DB2USER) CONNECT(CERTAUTH LABEL('IDUG CA CERT') RING(DB2ZKEYRING))
RACDCERT ID(DB2USER) CONNECT(SITE LABEL('IDUGSITE') -
RING(DB2ZKEYRING) USAGE(PERSONAL))
Setting up the server certificate and the keyring is required regardless of TLS server or client authentication is used.
Setting up the Db2 for z/OS server side – AT-TLS rules
As a separate step, configuration of the z/OS Communications Server for TLS is required. Db2 for z/OS is (almost) not aware of TLS encryption. The TLS handshake and the actual encrypted communication is handled by the z/OS TCP/IP components (TCP/IP stack and SystemSSL) and transparent for Db2 for z/OS. This is also called “Application Transparent Transport Layer Security” or “AT-TLS”.
Network administrators define so-called “AT-TLS” rules for applications which use TLS transparently. This also requires a started task named “PAGENT” (policy agent) which handles these AT-TLS rules. These rules define the characteristics of a TLS connection, for example:
- Which TCPIP ports are used for TLS?
- Which direction is used (inbound or outbound)?
- Which jobname or started task name is affected?
- Which authentication method (server or client authentication)?
- Which (RACF) keyring is used?
- Which certificate of a keyring is used?
AT-TLS rules bring all components (RACF, Db2 for z/OS, TCPIP) together in one place.
The following example shows the AT-TLS rules for a Db2 subsystem DSAC which accepts TLS handshake requests for server authentication on TCPIP port 3607 and handshake requests for client authentication on port 3617.
TTLSRule DB2SecureServer
{
LocalPortRange 3607
Direction Inbound
Priority 1000
Jobname DSACDIST
TTLSGroupActionRef DB2@SecureGrpAct
TTLSEnvironmentActionRef DB2@SecureServerEnvAct
TTLSConnectionActionRef DB2@SecureServerConAct
}
TTLSRule DB2SecureServerCA
{
LocalPortRange 3617
Direction Inbound
Priority 1000
Jobname DSACDIST
TTLSGroupActionRef DB2@SecureGrpAct
TTLSEnvironmentActionRef DB2@SecureServerEnvActCA
TTLSConnectionActionRef DB2@SecureServerConAct
}
TTLSGroupAction DB2@SecureGrpAct
{
TTLSEnabled On
FIPS140 Off
Trace 255
}
TTLSEnvironmentAction DB2@SecureServerEnvAct
{
HandShakeRole Server
TTLSKeyRingParmsRef DB2@KeyRing
TTLSEnvironmentAdvancedParmsRef DB2@SecureServer@EnvAdvParams
}
TTLSEnvironmentAction DB2@SecureServerEnvActCA
{
HandShakeRole ServerWithClientAuth
TTLSKeyRingParmsRef DB2@KeyRing
TTLSEnvironmentAdvancedParmsRef DB2@SecureServer@EnvAdvParamsCA
}
TTLSEnvironmentAdvancedParms DB2@SecureServer@EnvAdvParams
{
ClientAuthType Required
ApplicationControlled Off
SSLv2 Off
SSLv3 Off
TLSv1 Off
TLSv1.1 Off
TLSv1.2 On
TLSv1.3 Off
}
TTLSEnvironmentAdvancedParms DB2@SecureServer@EnvAdvParamsCA
{
ClientAuthType SAFCheck
ApplicationControlled Off
SSLv2 Off
SSLv3 Off
TLSv1 Off
TLSv1.1 Off
TLSv1.2 On
TLSv1.3 Off
}
TTLSConnectionAction DB2@SecureServerConAct
{
TTLSConnectionAdvancedParms
{
CertificateLabel DB2ZSERVER
}
} TTLSKeyRingParms DB2@KeyRing
{
Keyring DB2ZKEYRING
}
Running TLS server and client authentication in parallel requires two different AT-TLS rules. Rule “DB2SecureServer” handles server authentication, rule “DB2SecureServerCA” handles client authentication. Both look very similar. The main difference is the port number (3607 vs. 3617) , the TLS handshake role (“Server” vs. “ServerWithClientAuth”) and the client authentication type (“Required” vs. “SAFCheck”). Both rules point to the same RACF keyring (“DB2ZKEYRING”) as this is used by both authentication mechanisms.
When the certificate label (“DB2ZSERVER”) is omitted, AT-TLS will use the default certificate in the keyring for TLS handshakes.
Note: there may exist multiple rules in an AT-TLS policy which match for an inbound or outbound request. The “Priority” keyword as shown in the example above controls which rules have higher priority than others in such a case. A higher value for the “Priority” keyword means a higher priority and the higher priority rule will be used.
Setting up the Db2 for z/OS server side – Db2 ports
When AT-TLS receives a request for a TLS handshake, for example from a Db2 client, it tries to find a matching rule in the AT-TLS policy. One criterion for finding a matching rule is the TCPIP port number. As every AT-TLS rule has a unique TLS handshake role (“Server” or “ServerWithClientAuth”), two different secure ports are required on the Db2 side to accommodate server and client authentication in parallel.
For Db2, this means that at least one location alias needs to be defined in addition to the standard secure port, for example:
//STEP01 EXEC PGM=IKJEFT01
//STEPLIB DD DISP=SHR,DSN=DSNC10.SDSNLOAD
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSAC)
-MODIFY DDF ALIAS(DSACCA) ADD
-MODIFY DDF ALIAS(DSACCA) PORT(3615)
-MODIFY DDF ALIAS(DSACCA) SECPORT(3617)
-MODIFY DDF ALIAS(DSACCA) START
//
This is only required if you want to run TLS server and client authentication in parallel. When only one of these two methods is required, you can use the standard secure port in the DDF location records.
Setting up the Db2 for z/OS server side – Certificate Mapping
This step is specific to TLS client authentication. With TLS client authentication Db2 for z/OS does not expect a userid and password from the client side. Identification information is taken from the certificate which the client presents in the TLS handshake.
There are different alternatives to make a client identity known to a Db2 for z/OS server. One is certificate mapping. In this case, the RACF administrator defines a mapping rule based on the SDN (Subject Distinguished Name) and/or the IDN (Issuer Distinguished Name) on the client certificate:
RACDCERT MAP ID(USR01) WITHLABEL('db2sslclient') -
SDNFILTER('CN=Db2SSLCLient.OU=IDUG.O=IDUG.L=LUW.C=US')
Whenever a TLS handshake for client with this subject distinguished name ('CN=Db2SSLCLient.OU=IDUG.O=IDUG.L=LUW.C=US') on its client certificate completes successfully, RACF maps the userid USR01 to the client who initiated the connection. No further exchange of userid and password between server and client is required. Db2 for z/OS would even reject the connection if a userid and password was provided in addition to the client certificate.
The label (“db2sslclient” in this example) is required to uniquely identify the mapping rule for a specific userid in the RACF database. It is not necessary that it matches the certificate label or alias name on the client side.
You can also add the IDN (Issuer Distinguished Name) to the mapping filter to make it even more restrictive:
RACDCERT MAP ID(USR01) WITHLABEL('db2sslclient') -
SDNFILTER('CN=Db2SSLCLient.OU=IDUG.O=IDUG.L=LUW.C=US') –
IDNFILTER('OU=IDUG CA.O=IDUG.L=LUW.C=US')
In this example, only the client certificate which has a CA with the name ‘OU=IDUG CA.O=IDUG.L=LUW.C=US’ in their certificate chain is mapped to USR01.
Important:
For the RACF mapping filters, use a period (.) to separate the components (CN, OU, O, L, etc.) of the IDN or SDN. This may differ from distributed platforms where you would use a comma as separator.
Also, “State/Province” can be a part of an IDN or SDN. On distributed platforms, State/Province is usually indicated by “ST” or “S”. For the RACF mapping, always use “SP” as identifier.
Assuming your client certificate was generated with IBM GSkit like this
gsk8capicmd_64 -certreq -create -db "..." -stashed -label "db2sslclient" -dn "CN=Db2SSLCLient,OU=IDUG,O=IDUG,L=Toronto,ST=ON,C=CA" -size 2048 -target ... -sigalg SHA256_WITH_RSA
Your mapping rule in RACF would look like this:
RACDCERT MAP ID(USR01) WITHLABEL('db2sslclient') -
SDNFILTER('CN=Db2SSLCLient.OU=IDUG.O=IDUG.L=Toronto.SP=ON.C=CA') –
IDNFILTER('OU=IDUG CA.O=IDUG.L=LUW.C=US')
Certificate mapping is just one alternative to make a client’s identity known to RACF. You could also import the client certificate (the publicly available information) into RACF. In this case, the public part of the certificate needs to be copied to a sequential file in the z/OS filesystem. The RACF administrator adds that certificate to the RACF database and assigns it to an existing userid on the z/OS side. However, as certificates have an expiration date, the client certificate needs to be renewed or re-added when it is about to expire.
Putting it all together (server side)
The following picture illustrates the relevant pieces for TLS server and client authentication from the Db2 for z/OS server side.
The z/OS security manager (e.g. RACF) needs to be set up for Db2 server certificates, the relevant CA certificate and – in case of TLS client authentication – for user mapping of client userids to userids known on the server side.
On the TCPIP side, AT-TLS rules are required to initiate TLS handshakes when clients are connecting to z/OS server applications on secure (TLS) ports.
Db2 for z/OS needs to be configured for secure communications, at least with one secure port. For TLS server and client authentication in parallel, at least one additional location alias is required.
We did not discuss the Db2 client setup for TLS so far. With TLS server authentication, the client setup is relatively simple and it is primarily a question of configuring the Db2 client application that it takes TLS instead of an unencrypted connection when it connects to a Db2 server.
This setup is more complex for TLS client authentication. Now, client certificates are required for which the related private key needs to be stored securely. We will cover this in the next article of this blog series.
Read More
TLS Client Authentication with Db2 – Part 1: Introduction
TLS Client Authentication with Db2 – Part 3 Setting up Db2 Clients