Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

Redpaper

Front cover

IBM DB2 for z/OS: Configuring

TLS/SSL for Secure

Client/Server Communications

Chris Meyer

Derek Tempongko

IBM Db2 for z/OS: Configuring TLS/SSL

for Secure Client/Server Communications

This IBM® Redpaper publication provides information about how to set up and configure IBM

Db2® for z/OS® with Transport Layer Security (TLS), which is the modern version of Secure

Sockets Layer (SSL). This configuration is accomplished by using the IBM z/OS

Communications Server Application Transparent Transport Layer Security (AT-TLS) services.

This paper also describes the steps for configuring TLS/SSL support for the IBM Data Server

Driver Package (DS Driver) for IBM Data Server Provider for .NET, Open Database

Connectivity (ODBC), and Call Level Interface clients to access a Db2 for z/OS server. In

addition, this paper provides information about configuring that same support for the Java

Database Connectivity (JDBC) and Structured Query Language for Java (SQLJ for Type 4

connectivity) clients.

The information that is provided is applicable to Db2 12 for z/OS and Db2 11 for z/OS.

Although we use z/OS V2R4 as the referenced release in this paper, the instructions, except

for a TLSv1.3 configuration, are valid for releases as early as z/OS V2R1.

Throughout the paper, we reference z/OS Security Server or IBM Resource Access Control

Facility (IBM RACF®) in various contexts. It should be understood that anywhere we mention

RACF, it implies any System Authorization Facility (SAF)-compliant external security

manager.

The intended audience for this paper includes network administrators, security

administrators, and database administrators who want to set up and configure TLS/SSL

support for Db2 for z/OS.

This paper provides information about the following topics:

򐂰 Overview of AT-TLS

򐂰 Configuring Db2 for z/OS as a server with TLS/SSL support

򐂰 Configuring Db2 for z/OS as a requester with TLS/SSL support

򐂰 Configuring Java applications by using IBM DS Driver for JDBC and SQLJ to use TLS/SSL

򐂰 Configuring the IBM DS Driver non-Java interfaces: Command-line interface, ODBC, and

.NET

2 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

򐂰 Configuring remote client applications to use TLS/SSL through a Db2 Connect server for

Linux, UNIX, and Windows

򐂰 Client access to Db2 by using TLS/SSL client authentication

򐂰 Using Windows truststore and Windows keystore

This paper presents more information about the more general contents of Security Functions

of IBM DB2 10 for z/OS, SG24-7959.

Overview of AT-TLS

TLS is a client/server cryptographic protocol that is based on the SSL specifications that were

developed by Netscape Corporation in the 1990s for securing communications that use

Transmission Control Protocol/Internet Protocol (TCP/IP) sockets. Unless stated otherwise,

the terms TLS and SSL are used interchangeably in this document.

It is important to understand the basics of the TLS handshake and how digital certificates are

used in TLS/SSL before reading the rest of this paper. If you are not familiar with these topics,

see one of the many TLS/SSL primers that are available on the internet.

The TLS protocol runs at the application level (like its predecessor SSL). Therefore, an

application typically must be designed and coded to use TLS/SSL protection. On z/OS, the

System SSL component of the Cryptographic Services element implements the full suite of

TLS/SSL protocols (up to and including TLSv1.3 and TLSv1.2 at of the time of writing)

through a robust set of application programming interfaces (APIs) for z/OS C and C++

applications.

To make TLS/SSL more accessible to z/OS applications regardless of their source

programming language, z/OS Communications Server provides Application Transparent TLS

(AT-TLS). AT-TLS invokes TLS/SSL primitives in the TCP layer of the TCP/IP stack on behalf

of application programs based on policy rules that describe the application traffic and how to

protect it. With AT-TLS, applications that are written in almost any language that is supported

on z/OS can enjoy full TLS/SSL protection without requiring source code changes.

Db2 relies on AT-TLS to secure its TCP connections from and to remote systems.

AT-TLS policy is read, parsed, and installed into the TCP/IP stack by the z/OS

Communications Server Policy Agent (PAGENT), which implements policy-based networking

for the z/OS environment. For more information about policy-based networking, see z/OS

V2R4 Communications Server: IP Configuration Guide, SC27-3650.

Although this paper describes AT-TLS policies by using the underlying PAGENT syntax, the

preferred method for creating and maintaining AT-TLS policies is through the z/OSMF -based

IBM Network Configuration Assistant (NCA) web UI. For more information about the NCA,

see the IBM Network Configuration Assistant for z/OS Communications Server AT-TLS

tutorial, found at:

https://www.ibm.com/docs/en/zos/2.4.0?topic=folder-getting-started-tutorial-tls

Because AT-TLS is largely transparent to Db2, Db2 continues to send and receive clear text

data over its sockets while an active AT-TLS policy directs TCP/IP to invoke the required

System SSL services to protect the data that is being transmitted over the network.

Figure 1 shows the flow of Db2 for z/OS acting as a server by using AT-TLS to protect the

data exchanges over the network with a remote client system that also supports TLS.

Figure 1 Flow of Db2 for z/OS as a server by using AT-TLS

The diagram in Figure 1 illustrates the following flow:

1. After the PAGENT successfully reads the AT-TLS policy and installs it into the TCP/IP

stack, the client’s TCP connection to the Db2 server is established by using a standard

TCP 3-way handshake.

2. After accepting the new connection, Db2 issues a read request on the socket. The TCP

layer checks the AT-TLS policy and sees that AT-TLS protection is configured for this

connection. Therefore, TCP prepares for the client-initiated TLS handshake.

3. The client initiates the TLS handshake, and the TCP layer invokes System SSL to perform

its portion of the TLS handshake under the identity of the Db2 server. System SSL and the

TLS software at the client exchange handshake messages according to the relevant

Requests for Comments (RFCs) to complete the TLS session.

4. The Db2 client sends data to the Db2 server under protection of the new TLS session.

5. The TCP layer receives the inbound data, where AT-TLS invokes System SSL to decrypt

the data, and then it delivers the clear text inbound data to the Db2 server.

Likewise, when the Db2 server sends data to the Db2 client, AT-TLS takes the clear text

outbound data, calls System SSL to encrypt it, and then the encrypted data is sent to the

client.

4 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

Configuring Db2 for z/OS as a server with TLS/SSL support

There are two approaches to configuring AT-TLS and PAGENT on z/OS:

򐂰 The preferred approach is to use the z/OS Management Facility (z/OSMF) NCA for z/OS

Communications Server. The NCA is a GUI-based tool that greatly simplifies the setup,

configuration, and deployment of z/OS Communications Server policy-based

technologies, including AT-TLS.

For more information, see the tutorial and help windows in the Configuration Assistant

tool. For a complete example of configuring AT-TLS by using the Configuration Assistant,

see Chapter 12, “Application Transparent Transport Layer Security” in IBM z/OS V2R2

Communications Server TCP/IP Implementation: Volume 4 Security and Policy-Based

Networking, SG24-8363.

򐂰 The alternative approach is to hand-code all of the necessary job control language (JCL),

RACF directives, configuration files, and policy files. To provide you with greater insight

into the PAGENT and AT-TLS configuration, this approach is the one that we describe in

detail for the remainder of this document.

Security of REST service connections

Db2 supports HTTPS service requests by configuring Db2 for z/OS as a server with TLS/SSL

support. To accomplish this task, complete the following steps:

1. Configuring the PAGENT as a started task in z/OS.

2. Defining security authorizations for the PAGENT.

3. Defining the PAGENT configuration files.

4. Configuring AT-TLS.

5. Defining the AT-TLS policy rules.

6. Creating and configuring digital certificates.

7. Configuring a secure port for the Db2 for z/OS server.

We describe these steps in the following sections.

Configuring the PAGENT as a started task in z/OS

The PAGENT runs as a UNIX process, so it can be started either from the UNIX System

Services shell or as a z/OS started task. In our example, we use the z/OS started task

procedure to start the PAGENT.

To start the PAGENT as a z/OS started task, you can use the JCL procedure that is shown in

Example 1.

Example 1 PAGENT JCL procedure

//PAGENT PROC

//PAGENT EXEC PGM=PAGENT,REGION=0K,TIME=NOLIMIT,

// PARM='POSIX(ON) ALL31(ON) ENVAR("_CEE_ENVFILE=DD:STDENV")/'

//*

//* For information on the above environment variables, refer to the

//* IP CONFIGURATION GUIDE. Other environment variables can also be

//* specified through STDENV.

//*

//STDENV DD DSN=SYS1.TCPPARMS(PAENV),DISP=SHR

//*

//* Output that is written to stdout and stderr goes to the data set or

//* file specified with SYSPRINT or SYSOUT, respectively. But

//* normally, PAGENT doesn't write output to stdout or stderr.

//* Instead, output is written to the log file, which is specified

//* by the PAGENT_LOG_FILE environment variable, and defaults to

//* /tmp/pagent.log. However, when the -d parameter is specified

//* output is also written to stdout.

//*

//SYSPRINT DD SYSOUT=*

//SYSOUT DD SYSOUT=*

//CEEDUMP DD SYSOUT=*,DCB=(RECFM=FB,LRECL=132,BLKSIZE=132)

You can also find a sample started task procedure for PAGENT in

TCPIP.SEZAINST(EZAPAGSP).

You can use environment variables that are either configured in an IBM Multiple Virtual

Storage (IBM MVS) sequential or partitioned data set, or a z/OS UNIX file that is specified by

the STDENV data definition (DD) to run with the required configuration. In our example, we

configured the environment variables for PAGENT in partitioned data set SYS1.TCPPARMS,

member PAENV, as shown in Example 2.

Example 2 SYS1.TCPPARMS(PAENV) data set containing PAGENT environment variables

TZ=PST8PDT7

PAGENT_CONFIG_FILE=//'SYS1.TCPPARMS(PAGENT)'

PAGENT_LOG_FILE=SYSLOGD

The following environment variables are used in Example 2:

TZ Specifies the local time zone for the PAGENT process. Here, it

is set to PST8 (Pacific Standard Time GMT-08:00) and PDT7

(Pacific Daylight Saving Time GMT-07:00).

PAGENT_CONFIG_FILE Specifies the PAGENT configuration file to use. The

configuration file is the PAGENT member of the SYS1.TCPPARMS

data set in this example.

PAGENT_LOG_FILE Specifies the logging destination that is used by PAGENT. It is

set to log PAGENT messages to SYSLOGD.

Before you can start PAGENT, you must define the appropriate security authorizations, as

described in the next section.

Defining security authorizations for the PAGENT

The policies that are managed by the PAGENT can affect system operation significantly, s you

must restrict the list of z/OS user IDs (UIDs) under which PAGENT is allowed to run. To do

this task, you must define certain resources and controls in the system’s security manager

product, such as RACF.

To set up the PAGENT’s security definitions in RACF, complete the following steps:

1. Defining the PAGENT started task in RACF.

2. Defining the PAGENT UID.

3. Associating the PAGENT UID with the PAGENT started task.

4. Giving authorized users access to manage the PAGENT started task.

5. Restrict access to the pasearch UNIX command.

6 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

Defining the PAGENT started task in RACF

In this example, the PAGENT runs under z/OS as a started task that is named PAGENT. To

set up the PAGENT started task to RACF, you must define a profile for it in the RACF generic

resource class that is called STARTED by using the RDEFINE command.

Example 3 shows the RACF commands that are used to set up the PAGENT started task.

Example 3 RACF commands to define the PAGENT started task in RACF

//DAEMONS EXEC PGM=IKJEFT01

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

SETROPTS CLASSACT(STARTED)

SETROPTS RACLIST(STARTED)

SETROPTS GENERIC(STARTED)

RDEFINE STARTED PAGENT.*

SETROPTS RACLIST(STARTED) REFRESH

SETROPTS GENERIC(STARTED) REFRESH

If you also want to log messages through SYSLOGD, include an RDEFINE command to define a

profile for SYSLOGD to the STARTED class, as shown in the following example:

RDEFINE STARTED SYSLOGD.*

Defining the PAGENT UID

In this example, the PAGENT runs under the z/OS UID PAGENT. PAGENT often runs under a

UID with z/OS UNIX superuser authority (the z/OS UNIX UID for this user must be set to 0),

although this authority is not required. To run under a UID that does not have superuser

authority, see “Other considerations when starting the Policy Agent” in z/OS V2R4

Communications Server: IP Configuration Guide, SC27-3650. Additionally, you must assign a

default group (DFLTGRP) for the UID.

Example 4 shows the RACF command that is used to define a UID that is called PAGENT to

a default group that is called OMVSGRP with an OMVS segment with a UNIX UID of 0.

Example 4 RACF command to define a UID for the PAGENT started task

//PAUSER EXEC PGM=IKJEFT01

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

ADDUSER PAGENT DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/'))

If your security administrator defined the SHARED.IDS profile in the UNIXPRV class, the UID

value must be unique. If you want to use a UID value that is already in use, add the SHARED

keyword to the UID parameter of the ADDUSER command to indicate that you intend to share

the UID value across z/OS UIDs.

If you are also going to log messages to SYSLOGD, define a UID with superuser authority for the

SYSLOGD started task, as shown in the following example:

ADDUSER SYSLOGD DFLTGRP(OMVSGRP) OMVS(UID(0) HOME('/'))

SETROPTS: In Example 3, we include the SETROPTS commands for completeness.

Running these commands when the STARTED class is already activated has no effect.

Associating the PAGENT UID with the PAGENT started task

Use the RACF RALTER command to associate the PAGENT UID that was created to the

PAGENT started task, as illustrated in Example 5.

Example 5 RACF command to associate the UID with the PAGENT started task

//ASCPAUSR EXEC PGM=IKJEFT01

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

RALTER STARTED PAGENT.* STDATA(USER(PAGENT))

If you are also going to log messages to SYSLOGD, you must associate the SYSLOGD UID with

the SYSLOGD started task, as shown in the following example:

RALTER STARTED PAGENT.* STDATA(USER(SYSLOGD))

Giving authorized users access to manage the PAGENT started task

To restrict management access to the PAGENT started task, you must define a profile that is

named MVS.SERVMGR.PAGENT in the RACF resource class OPERCMDS, and give only authorized

users access to this profile. Example 6 shows the RACF commands that are used to achieve

this access.

Example 6 RACF commands to give authorized users access to manage the PAGENT started task

//PERMITPA EXEC PGM=IKJEFT01

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

SETROPTS CLASSACT(OPERCMDS)

SETROPTS RACLIST (OPERCMDS)

RDEFINE OPERCMDS (MVS.SERVMGR.PAGENT) UACC(NONE)

PERMIT MVS.SERVMGR.PAGENT CLASS(OPERCMDS) ACCESS(CONTROL) -

ID(PAGENT)

SETROPTS RACLIST(OPERCMDS) REFRESH

Restricting access to the pasearch UNIX command

Use the pasearch UNIX command to display policy definitions. The output from this command

indicates whether policy rules are active, and it shows the parsed results of the policy

definition attributes.

The pasearch output can be used to verify that the policies are defined correctly. However,

only users with a specific need to know this information should be able to see the policy

definitions. To restrict access to the pasearch command, a profile is defined in the RACF

SERVAUTH resource class. This type of profile can be defined for each TCP/IP stack (TcpImage)

and policy type (ptype):

EZB.PAGENT.sysname.TcpImage.ptype

8 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

In this example, these variables have the following definitions:

sysname The z/OS system name.

TcpImage The name of the TCP/IP stack (its procedure name) to which policy

information is to be restricted.

ptype The type of policy that is being requested. The following types are

possible:

QoS Quality of service (QoS) policy

IDS Intrusion Detection Services (IDS) policy

IPsec IP packet filtering and IPsec protocol policy

TTLS AT-TLS policy

Routing Policy-Based Routing policy

CFGSERV TCP/IP profile information

Example 7 shows the RACF commands that are used to restrict access to the pasearch UNIX

command. In this example, only z/OS UIDs USRT001 and USRT002 are permitted to use

pasearch for all types of policies for the TCP/IP stack that is named TCPIP on the z/OS system

that is named UTEC224.

Example 7 RACF commands to restrict access to the pasearch UNIX command

//PAGNACC EXEC PGM=IKJEFT01

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

RDEFINE SERVAUTH EZB.PAGENT.UTEC224.TCPIP.* UACC(NONE)

PERMIT EZB.PAGENT.UTEC224.TCPIP.* CLASS(SERVAUTH) -

ID(USRT001) ACCESS(READ)

PERMIT EZB.PAGENT.UTEC224.TCPIP.* CLASS(SERVAUTH) -

ID(USRT002) ACCESS(READ)

SETROPTS GENERIC(SERVAUTH) REFRESH

SETROPTS RACLIST(SERVAUTH) REFRESH

Now that you set up all the security authorizations for the PAGENT, you must configure the

policy for AT-TLS.

Defining the PAGENT configuration files

The PAGENT is responsible for reading policies from MVS data sets or from z/OS UNIX file

system files. Before we can define the AT-TLS policies, we must configure certain operational

characteristics of the PAGENT in the main configuration file. The main configuration file can

contain the following statements:

򐂰 TcpImage statement

򐂰 LogLevel statement

The following two sections describe the configuration steps:

򐂰 Defining the TcpImage statements

򐂰 Defining the appropriate logging level

Tip: Wildcard use is supported in segments of RACF profiles. For example, the

EZB.PAGENT.UTEC224.*.* profile controls pasearch access to all policy types for all TCP/IP

stacks on the z/OS system that is named UTEC224.

Defining the TcpImage statements

The TcpImage statement specifies a TCP/IP stack and its associated stack-specific

configuration file. There can be one TcpImage statement for each TCP/IP stack on the z/OS

system. If a configuration file name is specified, it identifies the file that contains

image-specific configuration definitions for AT-TLS policies. If the file name is not specified,

the main configuration file contains the image-specific configuration for that stack.

Depending on your environment, you can define the TcpImage statement in the following

ways:

򐂰 If your environment is configured with multiple TCP/IP stacks, specify TcpImage

statements identifying an image-specific configuration file for each TCP/IP stack. Figure 2

shows this type of configuration.

Figure 2 Multiple TCP/IP stacks and multiple AT-TLS policies

򐂰 If your environment is configured with a single TCP/IP stack, only one AT-TLS policy

definition is needed. In this case, you specify the TcpImage statement for the single TCP/IP

stack, and omit the specification of the image-specific configuration file. The main

configuration file contains a TTLSConfig statement that identifies a single policy file for the

TCP/IP stack.

ure 2 Multi

le TCP/IP Stacks

multi

le AT-TLS

olicies

gp ,p

TZ=PST8PDT7

PAGENT_CONFIG_FILE=//'SYS1.TCPP

ARMS(MPACFG)'

//PAGENT PROC

//PAGENT EXEC PGM=PAGENT …

// PARM=’…/’

PAENV

TcpImage TCPIP1

//'SYS1.TCPPARMS(TCP1POL)'

FLUSH PURGE

TcpImage TCPIP12

STDENV DD

DSN=SYS1.TCPPARMS(PAENV

)

…

MPACFG

TcpImage TCPIP12

//'SYS1.TCPPARMS(TCP2POL)'

FLUSH PURGE

TcpImage TCPIP13

//'SYS1.TCPPARMS(TCP3POL)'

FLUSH PURGE

Install different policies

into each TCP/IP stack

PAGENT

TCP2POL

TCP1POL

TCPIP1 TCPIP2 TCPIP3

TTLSConfig //’SYS1.TCPPARMS(TTLS1)’

TTLSConfig //’SYS1.TCPPARMS(TTLS2)’

TCP3POL

TTLS1

-T

olicies

TTLS2

-T

olicies

TTLSConfig //’SYS1.TCPPARMS(TTLS3)’

TTLS3

-T

olicies

…

Policy configuration files

10 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

Figure 3 shows this type of configuration.

Figure 3 Single TCP/IP stack and a single AT-TLS policy

It is possible that TCP/IP stacks that are configured to the PAGENT are not started or even

defined. When this situation happens, the PAGENT logs an error when trying to connect to

those stacks for diagnostic purposes.

TZ=PST8PDT7

PAGENT_CONFIG_FILE=//'SYS1.TCPPARMS

(SPACFG)'

//PAGENT PROC

//PAGENT EXEC PGM=PAGENT …

// PARM=’…/’

//STDENV DD

PAENV

TcpImage TCPIP1 FLUSH PURGE

SN=SYS1.TCPPARMS(PAENV)

…

TcpImage TCPIP1 FLUSH PURGE

TTLSConfig

//'SYS1.TCPPARMS(TCPPOLS)' FLUSH

PURGE

Install the one policy into the

TCP/IP stack

PAGENT

SPACFG

TCPIP1

TTLS

AT-TLS policies

…

TCPPOLS

Policy configuration file

A TcpImage statement optionally can specify the parameters FLUSH/NOFLUSH or

PURGE/NOPURGE. These optional parameters determine whether policies are deleted from the

associated TCP/IP stack under the conditions that are detailed in Table 1.

Table 1 How policy agent FLUSH and PURGE parameters are used

When any (or all) TCP/IP stacks are shut down, the PAGENT continues to run. When the

TCP/IP stacks are restarted, active policies are reinstalled automatically.

The following example defines the main configuration file that installs an AT-TLS policy file

SYS1.TCPPARMS(TTLSPOL) to the TCP/IP stack that is named TCPIP after flushing the existing

policy data when the TCP/IP stack is restarted and ensuring that the policy is deleted from the

stack when PAGENT shuts down:

TcpImage TCPIP //'SYS1.TCPPARMS(TTLSPOL)' FLUSH PURGE

Defining the appropriate logging level

Use the LogLevel statement to control the amount of information that is logged by the

PAGENT. The default is to log only event, error, console, and warning messages. This level

might be an appropriate level of information for a stable policy configuration, but more logging

might be required to understand policy processing or debug problems when first setting up

policies or when making significant changes. Specify the LogLevel statement with the

appropriate logging level in the main configuration file.

To define the appropriate logging level in the main configuration file, specify the LogLevel

statement keyword followed by an integer that represents the level of logging to be performed

by the PAGENT. The following levels are supported:

1 SYSERR: System error messages

2 OBJERR: Object error messages

4 PROTERR: Protocol error messages

8 WARNING: Warning messages

16 EVENT: Event messages

32 ACTION: Action messages

Parameter When used Results

FLUSH and NOFLUSH Used after policies are read without

errors when they are triggered by the

following events:

򐂰 PAGENT start.

򐂰 TcpImage statement added.

򐂰 MODIFY REFRESH command issued.

For FLUSH:

򐂰 All policies are deleted from

PAGENT and the TCP/IP stack

before installing new policies.

򐂰 QoS policy statistics are reset to 0.

For NOFLUSH:

򐂰 No policies are deleted from

PAGENT or the TCP/IP stack before

installing new policies.

򐂰 Policies that are removed from the

configuration file are not deleted

from the PAGENT or the TCP/IP

stack.

PURGE and NOPURGE 򐂰 PAGENT shutdown.

򐂰 TcpImage statement deleted.

For PURGE:

All policies are deleted from the PAGENT

and the TCP/IP stack.

For NOPURGE:

򐂰 All policies are deleted from

PAGENT.

򐂰 No policies are deleted from the

TCP/IP stack.

12 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

64 INFO: Informational messages

128 ACNTING: Accounting messages

256 TRACE: Trace messages

To include more than one level of logging, specify the sum of all the selected log levels in the

LogLevel statement. For example, to request SYSERR messages (level 1) and EVENT messages

(level 16), you specify LogLevel 17.

Example 8 shows the definitions of the main configuration file for a single TCP/IP stack

environment. The AT-TLS policies are defined in a separate image-specific configuration file,

TTLSPOL, for the TCP/IP stack that is named TCPIP.

Example 8 PAGENT configuration file

# LogLevel statement

# SYSERR, OBJERR, PROTERR, and WARNING messages are logged.

LogLevel 15

# TcpImage statement

# TCP/IP image: TCPIP

# Path to image-specific configuration file: SYS1.TCPPARMS(TTLSPOL)

# FLUSH parameter specified to delete existing policy data in the

# stack on PAGENT start-up or when the configuration files change.

# PURGE parameter specified to delete active policy data from the

# stack when PAGENT is shut down normally.

TcpImage TCPIP //'SYS1.TCPPARMS(TTLSPOL)' FLUSH PURGE

Next, the steps to configure AT-TLS are described.

Configuring AT-TLS

AT-TLS support is enabled by the specifying TTLS parameter on the TCPCONFIG statement in

the TCP/IP profile data set. The information that is required to negotiate secure connections

is provided to the TCP/IP stack by AT-TLS policies that are read, parsed, and installed by the

PAGENT.

When AT-TLS is enabled and a new TCP connection is established, the AT-TLS component in

the TCP layer of the stack searches for an AT-TLS rule in the policy that matches the

characteristics (local and remote IP addresses, local and remote ports, connection direction,

and so on) of the connection. If such a rule is found, TLS protection is applied to it according

to the details that are specified in the AT-TLS action that is associated with the rule. If no such

rule is found, the connection is not protected by TLS.

LogLevel: LogLevel 63 is sufficient for debugging the most common policy and certificate

errors that you might encounter during your initial AT-TLS setup. If this level is not sufficient,

we advise you to set the LogLevel to 511. However, this more detailed level of logging can

produce a significant amount of output. Consider the log size when the syslog daemon is

used as the log destination.

Setting up TTLS stack initialization access control for AT-TLS

This step is optional, but might be required depending on your local security requirements

and the services that run on your z/OS system. When AT-TLS is started during TCP/IP stack

initialization, there might be a delay between the time that the stack starts and when the

PAGENT successfully installs policy information into the stack. This situation can leave a

window of time where connections that are intended to be protected by AT-TLS can be

established without that protection.

To prevent such connections from being established while this window is open, define a

profile for the EZB.INITSTACK resource in the RACF SERVAUTH resource class. The profile

name can be defined by the TCP/IP stack (TcpImage):

EZB.INITSTACK.sysname.TcpImage

The variables have these definitions:

sysname The system name that is assigned to the z/OS system.

TcpImage The TCP/IP procedure name for the TCP/IP stack to which access is

to be controlled.

With such a profile in place, you can control which applications are allowed to establish TCP

connections before the AT-TLS policy is installed by the PAGENT. To do so, provide READ

access to the EZB.INITSTACK.sysname, which is the TcpImage profile in the SERVAUTH class for

the z/OS UIDs under which such applications run. All other applications are forced to wait

until PAGENT has initialized and its policies are installed into the stack before connections

can be established.

Example 9 shows the RACF commands that are used to enable the z/OS UIDs OMVSKERN,

PAGENT, and SYSLOGD to establish TCP/IP connections before PAGENT has loaded the AT-TLS

policy.

Example 9 RACF commands to set up TCP/IP stack initialization access control for AT-TLS

//STACKACC EXEC PGM=IKJEFT01

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

SETROPTS CLASSACT(SERVAUTH)

SETROPTS RACLIST (SERVAUTH)

SETROPTS GENERIC (SERVAUTH)

Tip: To enable TTLS without modifying PROFILE.TCPIP and without stopping and starting

the TCP/IP stack, define a separate file that contains the TCPCONFIG TTLS statement, and

issue the VARY TCPIP OBEYFILE command, as shown in this example:

1. OBEYFILE calls TTLSON in the SYS1.TCPPARMS partitioned data set:

TCPCONFIG TTLS

2. On the MVS console, issue this command:

VARY TCPIP,,O,DSN=SYS1.TCPPARMS(TTLSON)

disable TTLS, perform the following actions:

1. OBEYFILE calls TTLSOFF in the SYS1.TCPPARMS partitioned data set:

TCPCONFIG NOTTLS

2. On the MVS console, issue this command:

VARY TCPIP,,O,DSN=SYS1.TCPPARMS(TTLSOFF)

14 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

RDEFINE SERVAUTH EZB.INITSTACK.UTEC224.TCPIP UACC(NONE)

PERMIT EZB.INITSTACK.UTEC224.TCPIP CLASS(SERVAUTH) -

ID(OMVSKERN) ACCESS(READ)

PERMIT EZB.INITSTACK.UTEC224.TCPIP CLASS(SERVAUTH) -

ID(PAGENT) ACCESS(READ)

PERMIT EZB.INITSTACK.UTEC224.TCPIP CLASS(SERVAUTH) -

ID(SYSLOGD) ACCESS(READ)

SETROPTS GENERIC(SERVAUTH) REFRESH

SETROPTS RACLIST(SERVAUTH) REFRESH

This step is optional for Db2 because Db2 does not process any TCP/IP connections until the

TCP/IP stack is initialized. By then, all applicable AT-TLS policies are loaded into the TCP/IP

stack.

For more information about using EZB.INITSTACK profiles, see “TCP/IP stack initialization

access control” in the z/OS V2R4 Communications Server: IP Configuration Guide,

SC27-3650, which includes advice about the minimum set of applications that typically are

given access.

AT-TLS configuration is complete. We can now start and stop the PAGENT started task and

issue the commands to refresh policies in the PAGENT.

Starting and stopping PAGENT from the z/OS console

Use the MVS START command to start the PAGENT as a started task, for example:

S PAGENT

To shut down PAGENT (normally), use the MVS STOP command, as shown in this example:

P PAGENT

If the PURGE option is specified in the policy configuration files, PAGENT deletes all policies

from the TCP/IP stack when PAGENT shuts down.

Defining the AT-TLS policy rules

An AT-TLS policy configuration file contains AT-TLS rules that identify specific types of TCP

connections, along with the type of TLS/SSL protection to be applied to those connections. If

a matching rule is found, AT-TLS invokes System SSL to protect the connection that uses the

security attributes that are specified in the actions that are associated with the rule.

An AT-TLS policy is matched (referred to as

policy mapping) to a TCP connection the first

time one of the following socket API calls occurs in a z/OS TCP application:

򐂰 An outbound connect() for a TCP socket.

򐂰 A select() to see whether a socket is readable or writable.

򐂰 A poll() to see whether a socket is readable or writable.

򐂰 Any call that sends or receives data over a socket.

򐂰 An SIOCTTLSCTL input/output control (IOCTL) invocation in the case of AT-TLS-aware and

AT-TLS-controlling applications.

An AT-TLS rule is defined with the TTLSRule statement, which specifies a set of conditions that

are compared against the TCP connection attributes. Various attributes are considered in

TTLSRule conditions, including:

LocalAddr Local IP address or addresses.

RemoteAddr Remote IP address or addresses.

LocalPortRange Local port or ports.

RemotePortRange Remote port or ports.

Jobname Job name of the owning application or wildcard job name.

Userid UID of the owning process or wildcard UID.

Direction Inbound if applied to a passive socket (established by accept),

outbound if applied to an active socket (established by connect), or

both.

The TTLSRule statement requires, at a minimum, the Direction condition and one other

condition from the previous list. These considerations apply to rules:

򐂰 If a condition is not specified, that condition is not considered when comparing the rule

and the connection for a match.

򐂰 Multiple values can be specified for the IP address and port conditions, either directly in

the condition or as a referenced group.

򐂰 IPv6 addresses are fully supported.

When creating TTLSRules, you should avoid defining rules of the same kind that overlap.

Example 10 shows two overlapping rules.

Example 10 Example of overlapping rules

TTLSRule A TTLSRule B

{ {

LocalAddr 1.1.1.1 LocalAddr 1.1.1.1

RemoteAddr 2.2.2.2 RemoteAddr 2.2.2.2

LocalPortRange 11000 LocalPortRange 11000

RemotePortRange 15000 16000 RemotePortRange 15500 16500

... ...

} }

Although both rules are identical in terms of IP addresses and local ports, they define

different remote port ranges that overlap with each other. Avoid such overlaps unless they are

used to distinguish between policy statements for Db2 for z/OS acting as a client versus Db2

for z/OS acting as a server. When overlapping rules are necessary, you should specify a

Priority value on each of the overlapping rules to tell AT-TLS the order in which to evaluate

those rules relative to each other.

Priority values are integers 1 - 2,000,000,000, with 2,000,000,000 being the highest priority.

When assigning priorities, skip several values between rules to allow for future rule insertion

between existing rules.

Tip: If a connection can map to more than one rule, always use a priority, and leave priority

space between rules.

16 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

When a rule match is found, policy lookup stops, and the connection is assigned the actions

that are associated with the rule. A TTLSRule can reference up to three actions, where each

action represents a scope of control.

Table 2 describes these AT-TLS actions.

Table 2 AT-TLS actions

For more information about these AT-TLS actions, see z/OS V2R4 Communications Server:

IP Configuration Guide, SC27-3650.

Peer authentication models

The TLS and SSL protocols support two models of peer authentication during the handshake

phase, and AT-TLS and Db2 provide a couple of extra measures that build on one of those

models.

The most basic model is called

server authentication. In this model, The TLS/SSL server

sends its X.509 certificate to the client so that the client can verify the server’s identity. So

when Db2 for z/OS is acting as a server, it sends its certificate to the client that is attempting

to connect to Db2.

Server authentication is appropriate in situations where the client must ensure that it is

communicating with the correct server but the server is willing to serve any client. Server

authentication is configured in the AT-TLS policy by coding HandshakeRole Server in the

TTLSEnvironmentAction statement.

In cases where proof of the client’s identity is also important, TLS/SSL supports

client

authentication

(sometimes called mutual authentication), which builds on server

authentication. With client authentication, after the server proves its identity to the client, the

client responds by sending its own X.509 certificate to the server so that the server can verify

the client’s identity.

Action reference Action statement Description

TTLSGroupActionRef N/A This statement is required, and it must specify

TTLSEnabled ON or TTLSEnabled OFF.

If TTLSEnabled OFF is specified, no additional action

references and statements are required.

If TTLSEnabled ON is specified, the AT-TLS environment

action is required, and the AT-TLS connection action is

optional.

TTLSEnvironmentActionRef N/A This statement is required only if the AT-TLS group

action specifies TTLSEnabled ON. If specified, this

statement requires a key ring name (either RACF or

gskkyman format), and the HandshakeRole (either Client,

Server or ServerWithClientAuth). Optionally, the

AT-TLS connection action can be specified if a subset of

connections must have separate parameters.

TTLSConnectionActionRef TTLSConnectionAction This statement is optional. It overrides

TTLSEnvironmentAction settings for specific

connections.

Client authentication is optional, and it is appropriate in situations where the server must

ensure the identity of the clients that it serves. Client authentication is configured in the

AT-TLS policy by coding HandshakeRole ServerWithClientAuth on the

TTLSEnvironmentAction statement. When client authentication is used, AT-TLS supports

several variations regarding the actual level of client authentication through the

ClientAuthType parameter of the TTLSEnvironmentAdvancedParms policy statement.

The most commonly used ClientAuthType values are:

Required This is the default ClientAuthType value. It requires the client to supply

its digital certificate during the TLS handshake. If no client certificate is

supplied, the handshake fails. If the certificate is supplied, the

handshake succeeds if System SSL successfully authenticates the

certificate.

To successfully authenticate the client certificate, the server’s key ring

must contain a trusted signing certificate that can be used to verify the

client certificate’s authenticity. We describe different certificate

configurations in more detail later.

SAFCheck Adds z/OS -specific checking to the ClientAuthType Required

behavior. After System SSL successfully authenticates the client

certificate, AT-TLS queries RACF to ensure that the client certificate is

associated with a valid z/OS UID in RACF before allowing a secure

connection to be established.

If the certificate is associated with a z/OS UID, the connection is

enabled. If not, the connection is rejected.

When ClientAuthType SAFCheck is specified for IBM Db2 Distributed Relational Database

Architecture (IBM DRDA) connections, Db2 can add more authentication measures. After the

TLS/SSL handshake and the additional AT-TLS SAFCheck authentication succeed, a DRDA

handshake flows over the secured connection. This DRDA handshake might or might not

contain user credentials. In some cases, depending on the credentials sent (or not sent)

during the DRDA handshake, Db2 might query AT-TLS for the z/OS UID that is associated

with the client certificate.

The returned z/OS UID is checked to ensure that it has permission to access the relevant

d2sn.DIST resource in the RACF DSRN resource class (where d2sn is the Db2 subsystem

name to which the client is connecting). If the z/OS UID does not have permission to access

the resource, the DRDA connection is dropped. This Db2 feature, called

client certificate

authentication

, enables you to restrict remote client access to the Db2 subsystem based on

the client certificate mapping.

For more information about Db2 client authentication logic, see “Processing client access by

using digital certificates at a Db2 for z/OS server” on page 63.

18 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

Table 3 summarizes the Db2 client authentication options available with AT-TLS when the

policy covering the DRDA connection specifies HandshakeRole ServerWithClientAuth.

Table 3 Client authentication types for Db2 DRDA connections

Coding the AT-TLS policy rules for TLS/SSL server authentication

Because it is common for a single z/OS system to support multiple Db2 for z/OS subsystems,

we illustrate the AT-TLS configuration and associated digital certificate configuration by using

a scenario that supports two similar Db2 for z/OS subsystems: One is named DB2A, and the

other is named DB2B. The policies are built by using a method that makes it easy to add Db2

for z/OS subsystems.

Each Db2 for z/OS subsystem is assumed to run under its own dedicated z/OS UID. Your

environment might be simpler (a single Db2 subsystem) or more complex (multiple

subsystems, or scenarios where a subsystem must act as both a server and a client), but you

can use the same approach regardless of the number of Db2 for z/OS subsystems.

Example 11 shows a simple AT-TLS policy that protects connections to our DB2A and DB2B

subsystems by using TLSv1.2 and TLSv1.3, strong cipher suites, and strong signature

algorithms.

Example 11 Simple AT-TLS policy for two similar Db2 for z/OS servers to support TLS/SSL

connections

TTLSRule DB2ASecureServer

{

LocalPortRange 4801

JobName DB2ADIST

Direction Inbound

Priority 1

AT-TLS

ClientAuthType

Client

certificate

DSRN class is

active and the

Db2

subsystem’s

profile is

defined

Certificate validation Notes

Passthru Optional N/A None. Not recommended.

Full Optional N/A If a client certificate is provided, it is

validated against the server’s key

ring. If not, the connection is

enabled.

Not recommended for

Db2 DRDA

connections.

Required Required N/A The certificate is validated against

the server’s key ring.

The default, which is

advisable when extra

z/OS UID-based

access controls are

not required.

SAFCheck Required Required The certificate is validated against

the server’s key ring and must be

associated with a UID in the security

product. In addition, Db2 adds client

certificate authentication in certain

cases depending on the user

credentials that are specified in the

DRDA handshake.

This level is the

strongest level of

authentication. For

more information, see

“Processing client

access by using digital

certificates at a Db2 for

z/OS server” on

page 63.

TTLSGroupActionRef DB2@GrpAct

TTLSEnvironmentActionRef DB2@SecureServerEnvAct

}

TTLSRule DB2BSecureServer

{

LocalPortRange 4802

JobName DB2BDIST

Direction Inbound

Priority 1

TTLSGroupActionRef DB2@GrpAct

TTLSEnvironmentActionRef DB2@SecureServerEnvAct

}

TTLSGroupAction DB2@GrpAct

{

TTLSEnabled On

FIPS140 Off

Trace 15

}

TTLSEnvironmentAction DB2@SecureServerEnvAct

{

HandShakeRole Server

TTLSKeyRingParmsRef DB2@KeyRing

TTLSEnvironmentAdvancedParmsRef DB2@EnvAdvParms

TTLSCipherParmsRef DB2@CipherParms

TTLSSignatureParmsRef DB2@SigParms

}

TTLSKeyRingParms DB2@KeyRing

{

Keyring DB2@KEYRING

}

TTLSEnvironmentAdvancedParms DB2@EnvAdvParms

{

TLSv1.3 On

TLSv1.2 On

TLSv1.1 Off

TLSv1 Off

SSLv3 Off

SSLv2 Off

}

TTLSCipherParms DB2@CipherParms

{

# TLSv1.2: ECDSA or RSA peer auth with ephemeral DH, AES-GCM, and SHA-2

V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

V3CipherSuites TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

V3CipherSuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

# TLSv1.3: Ephemeral DH, AES-GCM, or ChaCha-Poly1305 and SHA-2

V3CipherSuites TLS_AES_256_GCM_SHA384

V3CipherSuites TLS_AES_128_GCM_SHA256

V3CipherSuites TLS_CHACHA20_POLY1305_SHA256

}

TTLSSignatureParms DB2@SigParms

20 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

{

# Allow digital signatures with hashes of 256 bits or more

SignaturePairs TLS_SIGALG_SHA512_WITH_RSASSA_PSS

SignaturePairs TLS_SIGALG_SHA512_WITH_ECDSA

SignaturePairs TLS_SIGALG_SHA512_WITH_RSA

SignaturePairs TLS_SIGALG_SHA384_WITH_RSASSA_PSS

SignaturePairs TLS_SIGALG_SHA384_WITH_ECDSA

SignaturePairs TLS_SIGALG_SHA384_WITH_RSA

SignaturePairs TLS_SIGALG_SHA256_WITH_RSASSA_PSS

SignaturePairs TLS_SIGALG_SHA256_WITH_ECDSA

SignaturePairs TLS_SIGALG_SHA256_WITH_RSA

}

The two TTLSRule statements define the rules that protect the Distributed Data Facility (DDF)

traffic. Each rule specifies three conditions that are matched against new TCP connections:

1. The connection is initiated by a remote peer to z/OS (it is an inbound connection).

2. The connection arrives on the respective local port (4801 and 4802).

3. The ports are owned by the Db2 DDF address spaces. DB2ADIST owns 4801 and

DB2BDIST owns 4802.

Each of these rules reference (and share) a common set of extra policy statements, which we

describe here.

The TTLSGroupActionRef parameter refers to the TTLSGroupAction statement that is named

DB2@SecureGrpAct, which is shared by both TTLSRule statements. This statement provides a

System SSL instance, enables AT-TLS protection for the specified TCP traffic, and specifies a

trace level of 15. This trace level enables the tracing of instances when a connection is

mapped to an AT-TLS rule, when a secure connection is successfully initiated, and for major

AT-TLS events.

Because TTLSEnabled ON is specified in the DB2@SecureGrpAct statement, a

TTLSEnvironmentAction statement, DB2@SecureServerEnvAct, is also required. The

environment action statement specifies HandshakeRole of Server, which implies that z/OS

acts as the server during the TLS/SSL handshake, and that the server authentication model

of peer authentication is used.

The TTLSEnvironmentAction statement also includes a reference to a TTLSKeyringParms

statement that defines a RACF key ring name, DB2@KEYRING (key ring definitions are

described in “Creating and configuring digital certificates” on page 31). Each Db2 for z/OS

DDF address space requires its own key ring, which is qualified by its UID. Because the

AT-TLS policy lists only the key ring name without a qualifying UID, it can be used by multiple

Db2 for z/OS subsystems. The only requirement is that a key ring of the same name must be

created for each Db2 for z/OS subsystem’s UID. As such, DB2A uses DB2AUSER/DB2@KEYRING

and DB2B uses DB2BUSER/DB2@KEYRING at run time.

Tip: TLSv1.3 and the RSA Signature Scheme with Appendix - Probabilistic Signature

Scheme (RSASSA-PSS) signature algorithm are supported beginning with z/OS V2R4. If

you are working with a z/OS version earlier than V2R4, you must remove the following

specifications from the example:

򐂰 The TLSv1.3 protocol specification from the TTLSEnvironmentAdvancedParms statement.

򐂰 The TLSv1.3 cipher suites from the TTLSCipherParms statement.

򐂰 All signature pairs containing the RSASSA-PSS algorithm from the

TTLSSignatureParms statement.

The TTLSEnvironmentAction also refers to the TTLSEnvironmentAdvancedParms statement that

lists which TLS protocol versions are acceptable. In this case, we allow only TLSv1.2 and

TLSv1.3 because the older protocol versions have weaknesses. At the time of writing,

TLSv1.2 and TLSv1.3 are generally accepted as providing strong TLS security, and all the

client implementations that are described in this paper support at least TLSv1.2. However, if

you are working with older Db2 client software, you might need to modify this list to match the

capabilities of your communications partners. For a TLS/SSL handshake to succeed, the

server and client must support at least one TLS protocol version in common, so you might

need to customize your server’s list of supported TLS protocols to include one that your client

supports.

TTLSEnvironmentAction also refers to the TTLSCipherParms statement that lists the cipher

suites that are allowed. In this case, we allow only cipher suites that use strong algorithms (at

the time of writing) for peer authentication, key exchange, symmetric encryption, and

message authentication. The TTLSCipherParms statement specifies the list of acceptable

TLS/SSL cipher suites in order of preference (top to bottom, most preferred to least).

If you do not specify a TTLSCipherParms statement, AT-TLS uses System SSL’s default cipher

list. In most cases (when z/OS Cryptographic Services Security Level 3 feature is installed),

that list contains the following ciphers in the order that is shown:

(35) TLS_RSA_WITH_AES_256_CBC_SHA

(38) TLS_DHE_DSS_WITH_AES_256_CBC_SHA

(39) TLS_DHE_RSA_WITH_AES_256_CBC_SHA

(2F) TLS_RSA_WITH_AES_128_CBC_SHA

(32) TLS_DHE_DSS_WITH_AES_128_CBC_SHA

(33) TLS_DHE_RSA_WITH_AES_128_CBC_SHA

There are a few important points to note here:

򐂰 This default list does not contain the strongest suites that are available (the ones that are

using ephemeral elliptic curve Diffie-Hellman, Advanced Encryption Standard

(AES)-GCM, and SHA2-based message authentication), so we advise specifying a

TTLSCipherParms statement that enforces a minimum cryptographic strength that meets

your company’s security policies.

򐂰 If you must comply with the US National Institute of Standards and Technology (NIST)

Special Publication SP800-131a, you must code a TTLSCipherParms statement that

includes only compliant cipher suites (the one that is shown in Example 11 on page 18

complies with NIST SP800-131a, with preference given to the strongest suites).

򐂰 If you must comply with NIST Special Publication SP800-52 as part of compliance with

Federal Information Processing Standards Security Requirements for Cryptographic

Modules (FIPS 140-2), you must change TTLSGroupAction from FIPS140 Off to FIPS140

On. This change ensures that Db2 for z/OS use only cipher suites that comply with

FIPS140-2 requirements.

Another reason that you might need to specify the list of cipher suites is to match the

capabilities of your communications partners. For a TLS/SSL handshake to succeed, the

server and client must support at least one cipher suite in common, so you might need to

customize your server’s cipher suite list to include a cipher that your client supports.

TTLSEnvironmentAction also refers to the TTLSSignatureParms statement that lists which

pairs of digital signature algorithms are acceptable. TLSv1.2 and TLSv1.3 both use this list to

determine whether the digital signatures that are used to sign the server, client (in the case of

client authentication), and certificate authority (CA) certificates that are used for peer

authentication are acceptable. TLSv1.3 also uses these pairs to determine how to sign some

of the TLS handshake messages.

22 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

In our case, we allow only signatures that use Elliptic Curve Digital Signature Algorithm

(ECDSA), RSASSA-PSS, and Rivest-Shamir-Adleman (RSA) signatures with at least 256-bit

hashes, which conform with generally accepted practices at the time of writing. However, if

you are working with Db2, whose digital certificates were signed with shorter hashes or the

DSA algorithm, you might need to modify this list to match the capabilities of your

communications partners.

There are a few other AT-TLS policy statements that you should be aware of that we do not

expand upon in this document:

TTLSConnectionAction

This action is optional and needed only when a subset of connections

in an AT-TLS environment requires different parameters.

TTLSConnectionAction serves the same purpose as

TTLSEnvironmentAction, but for a specific connection. When a

TTLSConnectionAction statement is associated with TTLSRule, its

settings override the setting in the TTLSEnvironmentAction statement.

TTLSConnectionAdvancedParms

This statement is also optional. TTLSConnectionAdvancedParms serves

the same purpose as the TTLSEnvironmentAdvancedParms statement,

but for a specific connection. If one of these statements is associated

with TTLSConnectionAction, its settings override the setting in the

associated TTLSEnvironmentAdvancedParms statement.

TTLSGskAdvancedParms

Specifies advanced attributes that are specific to System SSL. The

TTLSGskAdvancedParms statement can be contained in or referenced by

TTLSEnvironmentAction statements.

TTLSGskOcspParms, TTLSGskHttpCdpParms, and TTLSGskLdapParms

Specifies parameters that are related to the different certificate

revocation mechanisms that are supported by System SSL. These

statements can be contained in or referenced by

TTLSEnvironmentAction statements.

For more information about AT-TLS policy configuration, see Chapter 20, “Application

Transparent Transport Layer Security data protection”, in z/OS V2R4 Communications

Server: IP Configuration Guide, SC27-3650.

For the detailed syntax of each AT-TLS policy statement, see Chapter 16, “Policy Agent and

policy applications”, in z/OS V2R4 Communications Server: IP Configuration Reference,

SC27-3651.

Coding the AT-TLS policy rules for TLS/SSL client authentication

If you must verify the identity of each client that connects to Db2, use TLS/SSL client

authentication. To do this task, specify the HandshakeRole ServerWithClientAuth parameter

for the TTLSEnvironmentAction statement in the AT-TLS policy, as shown in Example 12.

Example 12 AT-TLS server policy for TLS/SSL client authentication

TTLSEnvironmentAction DB2@SecureServerEnvAct

{

HandShakeRole ServerWithClientAuth

TTLSKeyRingParmsRef DB2@KeyRing

TTLSEnvironmentAdvancedParms DB2@EnvAdvParms

TTLSCipherParmsRef DB2@CipherParms

TTLSSignatureParmsRef DB2@SigParms

}

TTLSEnvironmentAdvancedParms DB2@EnvAdvParms

{

ClientAuthType SAFCheck

TLSv1.3 On

TLSv1.2 On

TLSv1.1 Off

TLSv1 Off

SSLv3 Off

SSLv2 Off

}

Example 12 on page 22 specifies the HandshakeRole of ServerWithClientAuth, and adds a

parameter to the TTLSEnvironmentAdvancedParms statement to specify a client authentication

type (ClientAuthType) of SAFCheck. This level of client authentication requires the client

certificate identity to be associated with a z/OS UID in RACF (see “Registering a client

certificate with RACF (optional)” on page 40).

Additionally, depending on how your Db2 subsystem obtains the client user credentials, this

UID might also need to be given permission to access the relevant d2sn.DIST resource in

RACF, as described in “Peer authentication models” on page 16.

Refreshing policies

After you define the AT-TLS rules, if PAGENT is started, you must update or refresh the

PAGENT before the AT-TLS rules take effect. The MVS MODIFY command is used to refresh or

update the PAGENT. These commands use the following syntax:

F PAGENT,UPDATE The UPDATE command causes the PAGENT to reread and process the

policy files. With UPDATE, PAGENT installs or removes from the stack

any new, changed, or deleted policies (any unchanged policies are

unaffected). Therefore, we advise that you use this command in most

cases.

F PAGENT,REFRESH The REFRESH command causes the PAGENT to reread and process the

policy files. If the FLUSH parameter was specified on the TcpImage

configuration statement, the REFRESH command triggers FLUSH

processing.

Because FLUSH deletes and reinstalls all policies, you should use this

command only if you suspect that policies have somehow become out

of sync between the TCP/IP stack and the PAGENT. One

consequence of triggering FLUSH processing is that policy statistics

that are collected in the TCP/IP stack are reset.

24 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

Verifying policies

Use the z/OS UNIX pasearch command to query information from the PAGENT. The

command can be issued from the UNIX Systems Services shell or from the Time Sharing

Option Extensions (TSO/E) oshell command. The pasearch output in Example 13 was

produced by issuing the TSO/E oshell command to run the pasearch command specifying

the -t option to display all AT-TLS policy entries:

oshell pasearch -t

Example 13 Displaying AT-TLS policies by using the pasearch -t command

TCP/IP pasearch CS V2R4 Image Name: TCPCS

Date: 06/23/2021 Time: 13:56:36

TTLS Instance ID: 1624470892

policyRule: DB2ASecureServer

Rule Type: TTLS

Version: 3 Status: Active

Weight: 1 ForLoadDist: False

Priority: 1 Sequence Actions: Don't Care

No. Policy Action: 2

policyAction: DB2@GrpAct

ActionType: TTLS Group

Action Sequence: 0

policyAction: DB2@SecureServerEnvAct

ActionType: TTLS Environment

Action Sequence: 0

Time Periods:

Day of Month Mask:

First to Last: 1111111111111111111111111111111

Last to First: 1111111111111111111111111111111

Month of Yr Mask: 111111111111

Day of Week Mask: 1111111 (Sunday - Saturday)

Start Date Time: None

End Date Time: None

Fr TimeOfDay: 00:00 To TimeOfDay: 24:00

Fr TimeOfDay UTC: 04:00 To TimeOfDay UTC: 04:00

TimeZone: Local

TTLS Condition Summary: NegativeIndicator: Off

Local Address:

FromAddr: All

ToAddr: All

Remote Address:

FromAddr: All

ToAddr: All

LocalPortFrom: 4801 LocalPortTo: 4801

RemotePortFrom: 0 RemotePortTo: 0

JobName: DB2ADIST UserId:

ServiceDirection: Inbound

Policy created: Wed Jun 23 13:54:52 2021

Policy updated: Wed Jun 23 13:54:52 2021

TTLS Action: DB2@GrpAct

Version: 3

Status: Active

Scope: Group

TTLSEnabled: On

CtraceClearText: Off

Trace: 15

FIPS140: Off

TTLSGroupAdvancedParms:

SecondaryMap: Off

SyslogFacility: Daemon

Policy created: Wed Jun 23 13:54:52 2021

Policy updated: Wed Jun 23 13:54:52 2021

TTLS Action: DB2@SecureServerEnvAct

Version: 3

Status: Active

Scope: Environment

HandshakeRole: Server

SuiteBProfile: Off

TTLSKeyringParms:

Keyring: DB2@KEYRING

TTLSEnvironmentAdvancedParms:

SSLv2: Off

SSLv3: Off

TLSv1: Off

TLSv1.1: Off

TLSv1.2: On

TLSv1.3: On

MiddleBoxCompatMode: Off

ApplicationControlled: Off

HandshakeTimeout: 10

ClientAuthType: Required

ResetCipherTimer: 0

TruncatedHMAC: Off

CertValidationMode: Any

ServerMaxSSLFragment: Off

ClientMaxSSLFragment: Off

ServerHandshakeSNI: Off

ClientHandshakeSNI: Off

Renegotiation: Default

RenegotiationIndicator: Optional

RenegotiationCertCheck: Off

3DesKeyCheck: Off

ClientEDHGroupSize: Legacy

ServerEDHGroupSize: Legacy

PeerMinCertVersion: Any

PeerMinDHKeySize: 1024

PeerMinDsaKeySize: 1024

PeerMinECCKeySize: 192

PeerMinRsaKeySize: 1024

ServerScsv: Off

TTLSSignatureParms:

ClientECurves:

0021 secp224r1

0023 secp256r1

0024 secp384r1

0025 secp521r1

0019 secp192r1

0029 X25519

ClientKeyShareGroups:

0023 secp256r1

ServerKeyShareGroups:

0023 secp256r1

0024 secp384r1

0025 secp521r1

0029 X25519

0030 X448

26 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

SignaturePairs:

0806 TLS_SIGALG_SHA512_WITH_RSASSA_PSS

0603 TLS_SIGALG_SHA512_WITH_ECDSA

0601 TLS_SIGALG_SHA512_WITH_RSA

0805 TLS_SIGALG_SHA384_WITH_RSASSA_PSS

0503 TLS_SIGALG_SHA384_WITH_ECDSA

0501 TLS_SIGALG_SHA384_WITH_RSA

0804 TLS_SIGALG_SHA256_WITH_RSASSA_PSS

0403 TLS_SIGALG_SHA256_WITH_ECDSA

0401 TLS_SIGALG_SHA256_WITH_RSA

TTLSCipherParms:

v3CipherSuites:

C02C TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

C030 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

C02B TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

C02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

009F TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

009E TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

1302 TLS_AES_256_GCM_SHA384

1301 TLS_AES_128_GCM_SHA256

1303 TLS_CHACHA20_POLY1305_SHA256

TTLSGskAdvancedParms:

GSK_V3_SESSION_TIMEOUT: 86400

GSK_V3_SIDCACHE_SIZE: 512

GSK_SESSION_TICKET_CLIENT_ENABLE: On

GSK_SESSION_TICKET_CLIENT_MAXSIZE: 8192

GSK_SESSION_TICKET_SERVER_ENABLE: On

GSK_SESSION_TICKET_SERVER_ALGORITHM: AESCBC128

GSK_SESSION_TICKET_SERVER_COUNT: 2

GSK_SESSION_TICKET_SERVER_KEY_REFRESH: 300

GSK_SESSION_TICKET_SERVER_TIMEOUT: 300

TTLSGskHttpCdpParms:

HttpCdpEnable: Off

HttpCdpProxyServerPort: 80

HttpCdpResponseTimeout: 15

HttpCdpMaxResponseSize: 204800

HttpCdpCacheSize: 32

HttpCdpCacheEntryMaxsize: 0

TTLSGskOcspParms:

OcspAiaEnable: Off

OcspProxyServerPort: 80

OcspRetrieveViaGet: Off

OcspUrlPriority: On

OcspRequestSigalg:

0401 TLS_SIGALG_SHA256_WITH_RSA

OcspClientCacheSize: 256

OcspCliCacheEntryMaxsize: 0

OcspNonceGenEnable: Off

OcspNonceCheckEnable: Off

OcspNonceSize: 8

OcspResponseTimeout: 15

OcspMaxResponseSize: 20480

OcspServerStapling: Off

Policy created: Wed Jun 23 13:54:52 2021

Policy updated: Wed Jun 23 13:54:52 2021

policyRule: DB2BSecureServer

Rule Type: TTLS

Version: 3 Status: Active

Weight: 1 ForLoadDist: False

Priority: 1 Sequence Actions: Don't Care

No. Policy Action: 2

policyAction: DB2@GrpAct

ActionType: TTLS Group

Action Sequence: 0

policyAction: DB2@SecureServerEnvAct

ActionType: TTLS Environment

Action Sequence: 0

Time Periods:

Day of Month Mask:

First to Last: 1111111111111111111111111111111

Last to First: 1111111111111111111111111111111

Month of Yr Mask: 111111111111

Day of Week Mask: 1111111 (Sunday - Saturday)

Start Date Time: None

End Date Time: None

Fr TimeOfDay: 00:00 To TimeOfDay: 24:00

Fr TimeOfDay UTC: 04:00 To TimeOfDay UTC: 04:00

TimeZone: Local

TTLS Condition Summary: NegativeIndicator: Off

Local Address:

FromAddr: All

ToAddr: All

Remote Address:

FromAddr: All

ToAddr: All

LocalPortFrom: 4802 LocalPortTo: 4802

RemotePortFrom: 0 RemotePortTo: 0

JobName: DB2BDIST UserId:

ServiceDirection: Inbound

Policy created: Wed Jun 23 13:54:52 2021

Policy updated: Wed Jun 23 13:54:52 2021

TTLS Action: DB2@GrpAct

Version: 3

Status: Active

Scope: Group

TTLSEnabled: On

CtraceClearText: Off

Trace: 15

FIPS140: Off

TTLSGroupAdvancedParms:

SecondaryMap: Off

SyslogFacility: Daemon

Policy created: Wed Jun 23 13:54:52 2021

Policy updated: Wed Jun 23 13:54:52 2021

TTLS Action: DB2@SecureServerEnvAct

Version: 3

Status: Active

Scope: Environment

HandshakeRole: Server

SuiteBProfile: Off

TTLSKeyringParms:

Keyring: DB2@KEYRING

TTLSEnvironmentAdvancedParms:

SSLv2: Off

SSLv3: Off

TLSv1: Off

TLSv1.1: Off

28 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

TLSv1.2: On

TLSv1.3: On

MiddleBoxCompatMode: Off

ApplicationControlled: Off

HandshakeTimeout: 10

ClientAuthType: Required

ResetCipherTimer: 0

TruncatedHMAC: Off

CertValidationMode: Any

ServerMaxSSLFragment: Off

ClientMaxSSLFragment: Off

ServerHandshakeSNI: Off

ClientHandshakeSNI: Off

Renegotiation: Default

RenegotiationIndicator: Optional

RenegotiationCertCheck: Off

3DesKeyCheck: Off

ClientEDHGroupSize: Legacy

ServerEDHGroupSize: Legacy

PeerMinCertVersion: Any

PeerMinDHKeySize: 1024

PeerMinDsaKeySize: 1024

PeerMinECCKeySize: 192

PeerMinRsaKeySize: 1024

ServerScsv: Off

TTLSSignatureParms:

ClientECurves:

0021 secp224r1

0023 secp256r1

0024 secp384r1

0025 secp521r1

0019 secp192r1

0029 X25519

ClientKeyShareGroups:

0023 secp256r1

ServerKeyShareGroups:

0023 secp256r1

0024 secp384r1

0025 secp521r1

0029 X25519

0030 X448

SignaturePairs:

0806 TLS_SIGALG_SHA512_WITH_RSASSA_PSS

0603 TLS_SIGALG_SHA512_WITH_ECDSA

0601 TLS_SIGALG_SHA512_WITH_RSA

0805 TLS_SIGALG_SHA384_WITH_RSASSA_PSS

0503 TLS_SIGALG_SHA384_WITH_ECDSA

0501 TLS_SIGALG_SHA384_WITH_RSA

0804 TLS_SIGALG_SHA256_WITH_RSASSA_PSS

0403 TLS_SIGALG_SHA256_WITH_ECDSA

0401 TLS_SIGALG_SHA256_WITH_RSA

TTLSCipherParms:

v3CipherSuites:

C02C TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

C030 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

C02B TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

C02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

009F TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

009E TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

1302 TLS_AES_256_GCM_SHA384

1301 TLS_AES_128_GCM_SHA256

1303 TLS_CHACHA20_POLY1305_SHA256

TTLSGskAdvancedParms:

GSK_V3_SESSION_TIMEOUT: 86400

GSK_V3_SIDCACHE_SIZE: 512

GSK_SESSION_TICKET_CLIENT_ENABLE: On

GSK_SESSION_TICKET_CLIENT_MAXSIZE: 8192

GSK_SESSION_TICKET_SERVER_ENABLE: On

GSK_SESSION_TICKET_SERVER_ALGORITHM: AESCBC128

GSK_SESSION_TICKET_SERVER_COUNT: 2

GSK_SESSION_TICKET_SERVER_KEY_REFRESH: 300

GSK_SESSION_TICKET_SERVER_TIMEOUT: 300

TTLSGskHttpCdpParms:

HttpCdpEnable: Off

HttpCdpProxyServerPort: 80

HttpCdpResponseTimeout: 15

HttpCdpMaxResponseSize: 204800

HttpCdpCacheSize: 32

HttpCdpCacheEntryMaxsize: 0

TTLSGskOcspParms:

OcspAiaEnable: Off

OcspProxyServerPort: 80

OcspRetrieveViaGet: Off

OcspUrlPriority: On

OcspRequestSigalg:

0401 TLS_SIGALG_SHA256_WITH_RSA

OcspClientCacheSize: 256

OcspCliCacheEntryMaxsize: 0

OcspNonceGenEnable: Off

OcspNonceCheckEnable: Off

OcspNonceSize: 8

OcspResponseTimeout: 15

OcspMaxResponseSize: 20480

OcspServerStapling: Off

Policy created: Wed Jun 23 13:54:52 2021

Policy updated: Wed Jun 23 13:54:52 2021

Diagnosing AT-TLS problems

There are several useful tools for diagnosing AT-TLS problems. For a description of common

AT-TLS start-up errors, debugging steps and tools, and descriptions of AT-TLS return codes,

see Chapter 27, “Diagnosing Application Transparent Transport Layer Security (AT-TLS)”, in

z/OS V2R4 Communications Server IP Diagnosis Guide, GC27-3652. That document

explains how to diagnose TCP/IP problems and determine whether a specific problem is in

the z/OS Communications Server TCP/IP component. The document also explains how to

gather information for and describe problems to the IBM Software Support Center.

For your convenience, here is a summary of the tools that you can use to diagnose AT-TLS

problems in the order that you would usually use them:

򐂰 Commands:

–The pasearch command provides details about the AT-TLS policies that are installed.

–The TSO Netstat command and its z/OS UNIX counterpart netstat provide AT-TLS

information as it relates to specific TCP connections. The COnn/-c and TTLS/-x options

are especially useful for AT-TLS diagnosis.

For a complete description of these commands and their output, see z/OS V2R4

Communications Server IP System Administrator’s Commands, SC27-3661.

30 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

򐂰 Any errors that are detected by the policy agent when parsing the AT-TLS policy

statements are written to the PAGENT log, which can be either a z/OS UNIX file or

syslogd.

The specific PAGENT log destination is controlled by the PAGENT -L startup parameter.

Either SYSLOGD or a z/OS UNIX file can be specified. If SYSLOGD is specified, syslogd takes

the messages and writes them under the facility name daemon to a destination (typically a

z/OS UNIX file) that is specified in the /etc/syslog.conf file. The environment variable

PAGENT_LOG_FILE also specifies the destination of the log file by using the same format as

this option. The -L option overrides the PAGENT_LOG_FILE environment variable.

If the PAGENT log file destination is not specified by either the -L parameter or the

PAGENT_LOG_FILE environment variable, the default location is /tmp/pagent.log. For more

information about specifying the PAGENT log file destination, see “Starting Policy Agent

from the z/OS shell” in Chapter 16, “Policy Agent and policy applications”, in z/OS V2R4

Communications Server: IP Configuration Reference, SC27-3651.

򐂰 AT-TLS messages are written to syslogd under the facility name daemon. Syslogd takes

the messages and writes them to a destination (typically a z/OS UNIX file) that is specified

in the /etc/syslog.conf file.

AT-TLS messages begin with the prefix EZD. Most are in the range EZD1281I - EZD1290I.

Descriptions of the messages and suggested actions can be found in z/OS V2R4

Communications Server: IP Messages Volume 2 (EZB, EZD), SC27-3655.

AT-TLS error messages contain detailed return codes that are useful in isolating problems.

The following convention is used for AT-TLS return code values:

– Return code values 1 - 5000 come directly from System SSL. These return codes,

including detailed descriptions and suggested actions, are described in Chapter 13,

“Messages and codes”, in z/OS V2R4 Cryptographic Services System Secure Sockets

Layer Programming, SC14-7495.

– Return code values 5001 and higher are generated by AT-TLS code in the TCP/IP

stack. These return codes, including detailed descriptions and suggested actions, are

described in Chapter 27, “Diagnosing Application Transparent Transport Layer Security

(AT-TLS)”, in z/OS V2R4 Communications Server IP Diagnosis Guide, GC27-3652.

For more information about configuring syslogd, see the "Configuring the syslog daemon"

topic in Chapter 5, “TCP/IP Customization”, in z/OS V2R4 Communications Server: IP

Configuration Guide, SC27-3650.

򐂰 AT-TLS traces can be enabled through the AT-TLS policy Trace parameter of the

TTLSEnvironmentAction or TTLS ConnectionAction statements. AT-TLS trace records are

also written to syslogd under the facility name daemon. Depending on the level of tracing

that you choose, these trace records can provide many details of the internal AT-TLS

operation that can help you isolate errors.

򐂰 System SSL traces. In some cases, you might need to examine the details of System

SSL’s operation regarding a problem. To do this task, enable System SSL tracing. For

more information about setting up and using System SSL traces, see Chapter 12,

“Obtaining diagnostic information”, in z/OS V2R4 Cryptographic Services System Secure

Sockets Layer Programming, SC14-7495. When using AT-TLS,

you must enable System

SSL trace through the z/OS component trace facility

. AT-TLS does not support enabling

System SSL trace through environment variables.

Example 14 on page 31 shows a Db2 message that is often generated in the syslog when a

DRDA connection cannot be established because of an AT-TLS configuration error. In this

case, the error causes Db2 to fail while attempting to process a TLS/SSL message.

Example 14 Network policy issue

DSNL032I -DB2R DSNLIRTR DRDA EXCEPTION CONDITION IN

REQUEST FROM REQUESTOR LOCATION=::10.0.45.11 FOR THREAD WITH

LUWID=GA002D0B.PB61.CD2843B2841D

REASON=00D3101A

ERROR ID=DSNLIRTR0003

IFCID=0192

SEE TRACE RECORD WITH IFCID SEQUENCE NUMBER=00000008

The following message is the corresponding client message that is generated in db2diaglog

on a non-Java client:

DIA3604E The SSL function "gsk_secure_soc_init" failed with the return code "410"

in "sqlccSSLSocketSetup".

For more information about the possible IBM Global Security Kit for SSL (IBM GSKit) return

codes, see the following website:

https://www.ibm.com/docs/en/txseries/8.1.0?topic=communications-gskit-return-codes

Creating and configuring digital certificates

There are numerous ways to create and manage digital certificates and their related key

pairs. On z/OS, these ways include the following options:

򐂰 z/OS Security Server RACF (and other SAF-compliant external security managers).

򐂰 The gskkyman tool that is included with System SSL.

򐂰 z/OS Cryptographic Services PKI Services.

The gskkyman tool and RACF are suited for smaller scale certificate deployments, and public

key infrastructure services (PKI Services) is a full-blown CA and management system that

can manage digital certificates on an enterprise level.

There are many facilities on other platforms from CLI tools to complete digital certificate

management systems (CMSs) that can be used too. When these tools are used, the

certificates and keys they generate must be imported onto z/OS by using either RACF or

gskkyman.

If your company has an established PKI, the keys and certificates that you use for your secure

Db2 connections most likely come from that infrastructure. However, when you are

experimenting with the TLS/SSL protection of your Db2 connections, you probably want to

experiment with more localized tools. Likewise, if you do not have an established PKI, you

might choose to use a more localized facility to create and manage your certificates and keys.

In this paper, we use RACF exclusively to generate and manage certificates and keys in SAF

key rings on z/OS. We also show examples of a few different non- z/OS utilities that are

commonly used in some of the Db2 client environments.

For more information about gskkyman, see Chapter 10, “Certificate/Key management”, in z/OS

V2R4 Cryptographic Services System Secure Sockets Layer Programming, SC14-7495. For

more information about z/OS PKI Services, see z/OS V2R4 Cryptographic Services PKI

Services Guide and Reference, SA23-2286.

32 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

You can use RACF to perform the following tasks regarding X.509 digital certificates on z/OS:

򐂰 Create, register, store, and administer digital certificates and their associated private keys.

򐂰 Build certificate requests that can be sent to a CA for signing.

򐂰 Create and manage key rings of stored digital certificates.

Digital certificates and key rings are managed in RACF primarily by using the RACDCERT

command. In this section, we describe how to use the RACDCERT command to administer

digital certificates and key rings.

For a complete description of the RACDCERT command and all the functions that it supports,

see Chapter 5, “RACF command syntax”, in z/OS V2R4 Security Server RACF Command

Language Reference, SA23-2292.

The next sections describe the following topics:

򐂰 Setting up access controls for certificates and key rings

򐂰 Creating the keys, digital certificates, and key rings by using RACDCERT

򐂰 Registering a client certificate with RACF (optional)

򐂰 Creating and activating client certificate name filters

Setting up access controls for certificates and key rings

In “Coding the AT-TLS policy rules for TLS/SSL server authentication” on page 18, where we

defined the AT-TLS rules DB2ASecureServer and DB2BSecureServer, one of the conditions

that was specified was the JobName condition. The JobNames that were specified were

DB2ADIST and DB2BDIST (the started task job names of the respective Db2 DDF address

spaces), which indicates to AT-TLS that the rules apply only if a job with the specified name

owns the local socket for the TCP connection.

Because AT-TLS invokes System SSL under the UID of the application that owns the TCP

connection, we must grant sufficient authority to the Db2 started task UIDs to access their

own RACF key rings, certificates, and private keys.

In our example, the UID that is associated with the started task DB2ADIST is DB2AUSER,

and the UID that is associated with DB2BDIST is DB2BUSER.

We also assume that a separate administrative UID is used for creating and managing

certificates and key rings in RACF, which includes the certificates and keys that are owned by

to the two Db2 started task UIDs and the certificate authority (CERTAUTH) certificates.

For illustration purposes, we call this UID CERTMGR. In practice, the UID can be whatever UID

is appropriate in your environment.

All three of these UIDs require appropriate permissions to their own RACF certificate-related

resources.

Controlling Db2 access to key rings

There are two mechanisms for controlling an application's access to key rings at run time. The

preferred approach uses the RDATALIB class and the other approach uses the FACILITY

class. The RDATALIB approach is preferred because it provides granular authorization to a

specified key ring. In contrast, the FACILITY class allows global authorization to all key rings

and certificates. For more information, see z/OS V2R4 Security Server RACF Callable

Services, SA23-2293.

򐂰 Controlling access by using the RDATALIB class (recommended):

a. If they are not already defined, create the RDATALIB definitions that are required to

control access to the RACF key rings that belong to each of our Db2 instances by

issuing the following TSO commands:

SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)

RDEFINE RDATALIB DB2AUSER.DB2@KEYRING.LST UACC(NONE)

RDEFINE RDATALIB DB2BUSER.DB2@KEYRING.LST UACC(NONE)

b. To permit the Db2 instance UIDs to access the certificates and keys that are connected

to their respective key rings, issue the following TSO commands:

PERMIT DB2AUSER.[email protected] CLASS(RDATALIB) ID(DB2AUSER) ACCESS(READ)

PERMIT DB2BUSER.[email protected] CLASS(RDATALIB) ID(DB2BUSER) ACCESS(READ)

c. Refresh the RDATALIB class:

SETROPTS RACLIST(RDATALIB) REFRESH

򐂰 Controlling access by using the FACILITY class:

a. If they are not already defined, create the definitions that are required to allow

certificates to be stored and accessed from the RACF database by issuing the

following TSO commands:

RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)

RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)

b. To permit the Db2 started task UIDs to access the required resources, issue the

following TSO commands:

PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(DB2AUSER) ACCESS(READ)

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(DB2AUSER) ACCESS(READ)

PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(DB2BUSER) ACCESS(READ)

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(DB2BUSER) ACCESS(READ)

c. Refresh the FACILITY class:

SETROPTS RACLIST(FACILITY) REFRESH

Controlling certificate administrator access to the RACDCERT command

The RACDCERT command is your primary administrative tool for managing digital certificates

and key rings in RACF. It is the command that the CERTMGR UID uses to perform its certificate

and key ring management tasks.

In our example, the authority to use the RACDCERT command is controlled through resources

that are defined in the FACILITY class. The RACDCERT command is used to manage resources

in the DIGTCERT, DIGTRING, DIGTNMAP, and USER classes.

Tip: You do not have to activate the DIGTCERT and DIGTRING classes to use the

resources in these classes. However, performance is improved when you activate and

RACLIST these classes.

34 IBM Db2 for z/OS: Configuring TLS/SSL for Secure Client/Server Communications

To control the use of the RACDCERT command, authority to the IRR.DIGTCERT.function

resource in the FACILITY class must be granted to a user unless the user has the SPECIAL

attribute. One of the following authorities must be granted to the user:

򐂰 READ access to the IRR.DIGTCERT.function to issue the RACDCERT command for

themselves

򐂰 UPDATE access to the IRR.DIGTCERT.function to issue the RACDCERT command for others

򐂰 CONTROL access to the IRR.DIGTCERT.function to issue the RACDCERT command for

SITE and CERTAUTH certificates (this authority also includes other uses)

In our scenario, the CERTMGR UID creates and manages the digital certificates, private keys,

and key rings that belong to the Db2 started task UIDs and any required CERTAUTH

certificates. CERTMGR must be authorized to use the RACDCERT command.

To define profiles and permit the CERTMGR UID to use the required RACDCERT commands,

complete the following steps:

1. If they are not already defined, define the following profiles to control access to the specific

RACDCERT commands that are needed by the CERTMGR UID by issuing the following TSO

commands:

RDEFINE FACILITY IRR.DIGTCERT.ADD UACC(NONE)

RDEFINE FACILITY IRR.DIGTCERT.ADDRING UACC(NONE)

RDEFINE FACILITY IRR.DIGTCERT.CONNECT UACC(NONE)RDEFINE FACILITY

IRR.DIGTCERT.GENCERT UACC(NONE)

2. Issue the following TSO commands to grant the required permission to the CERTMGR UID:

PERMIT IRR.DIGTCERT.ADD CLASS(FACILITY) ID(CERTMGR) ACC(CONTROL)

PERMIT IRR.DIGTCERT.ADDRING CLASS(FACILITY) ID(CERTMGR) ACC(UPDATE)

PERMIT IRR.DIGTCERT.CONNECT CLASS(FACILITY) ID(CERTMGR) ACC(CONTROL)

PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(CERTMGR) ACC(CONTROL)

PERMIT IRR.DIGTCERT.EXPORT CLASS(FACILITY) ID(CERTMGR) ACC(CONTROL)

PERMIT IRR.DIGTCERT.MAP CLASS(FACILITY) ID(CERTMGR) ACC(UPDATE)

PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(CERTMGR) ACC(CONTROL)

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(CERTMGR) ACC(UPDATE)

3. Refresh the FACILITY class:

SETROPTS RACLIST(FACILITY) REFRESH

4. If the RDATALIB class is being used to control access to the Db2 instance key rings, the

CERTMGR UID must also be permitted to access the RDATALIB profile for each of those key

rings:

PERMIT DB2AUSER.[email protected] CLASS(RDATALIB) ID(CERTMGR) ACCESS(UPDATE)

PERMIT DB2BUSER.[email protected] CLASS(RDATALIB) ID(CERTMGR) ACCESS(UPDATE)

SETROPTS CLASSACT(RDATALIB) REFRESH

Examples: Tying the certificate and key ring permissions together

Here are examples for setting up certificate and key ring permissions by using each of the

approaches that are described in “Setting up access controls for certificates and key rings” on

page 32:

򐂰 Controlling access by using the RDATALIB and FACILITY classes (recommended)

Example 16 on page 36 illustrates how to grant the appropriate authority to our three UIDs

by using the RDATALIB and FACILITY classes.

Example 15 Granting permission for RACF digital certificate resources by using the RDATALIB and

FACILITY classes

//RACDCERT EXEC PGM=IKJEFT01

//SYSTSPRT DD SYSOUT=*

//SYSUADS DD DSN=SYS1.UADS,DISP=SHR

//SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR

//SYSTSIN DD *

* Activate required SAF classes and define required resources

SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)

RDEFINE RDATALIB DB2AUSER.DB2@KEYRING.LST UACC(NONE)

RDEFINE RDATALIB DB2BUSER.DB2@KEYRING.LST UACC(NONE)

SETROPTS CLASSACT(DIGTCERT DIGTRNG)

RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)

RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)

* Give Db2 for z/OS user IDs sufficient authority so System SSL can use RACF

cert APIs

PERMIT DB2AUSER.[email protected] CLASS(RDATALIB) ID(DB2AUSER) ACCESS(READ)

PERMIT DB2BUSER.[email protected] CLASS(RDATALIB) ID(DB2BUSER) ACCESS(READ)

* Give cert management user ID sufficient access to manage certificates and key

rings

* on behalf of Db2 user IDs and for certificate authorities