Setting up AT-TLS

The actions needed to set up Application Transparent Transport Layer Security (AT-TLS) vary depending on the exact needs and what is already available at your site. You might encounter some common problems while setting it up or during checking or modifying an existing setup.

The Transport Layer Security (TLS) protocol defined in RFC 2246 provides communications privacy over the Internet. Similar to its predecessor Secure Socket Layer (SSL), the TLS protocol enables client and server applications to communicate in a way that is designed to prevent eavesdropping, tampering, and message forgery. Application Transparent Transport Layer Security (AT-TLS) consolidates TLS implementation for z/OS-based applications in one location, so that all applications can support TLS-based encryption without knowledge of the TLS protocol.

The information in this section shows how to set up the TCP/IP Policy Agent that manages AT-TLS and define a policy for usage by the Compiled Language Interception Processor on a z/OS® 1.13 system, with support for TLS v1.2.

Throughout this section, a uniform naming convention is used:
  • HCL OneTest™ API Session Manager user ID: stcdbm
  • Policy agent user ID: pagent
  • Certificate: dbgmgr
  • Key and certificate storage: dbgmgr.racf

Some tasks described in the following sections expect you to be active in z/OS UNIX. Do this by issuing the TSO command OMVS. Use the oedit command to edit files in z/OS UNIX and the exit command to return to TSO.

Setting up syslogd

The TCP/IP documentation recommends writing Policy Agent messages to the z/OS UNIX syslog instead of using the default log file. AT-TLS will always write messages to the z/OS UNIX syslog.

In order to do so, the z/OS UNIX syslog daemon, syslogd, must be configured and active. You also need a mechanism to control the size of the log files created by syslogd.

The following sample configuration file updates can be used to configure and start syslogd, with a simple log file management mechanism (erase existing logs when z/OS UNIX starts and create new ones upon syslogd startup).

/etc/services
syslog          514/udp
/etc/syslog.conf
# /etc/syslog.conf - control output of syslogd
# 1. all files with will be printed to /tmp/syslog.auth.log
auth.*           /tmp/syslog.auth.log
# 2. all error messages printed to /tmp/syslog.error.log
*.err            /tmp/syslog.error.log
# 3. all debug and above messages printed to /tmp/syslog.debug.log
*.debug          /tmp/syslog.debug.log
# The files named must exist before the syslog daemon is started,
# unless -c startup option is used
/etc/rc
# Start the SYSLOGD daemon for logging
# (clean up old logs)
sed -n '/^#/!s/.* \(.*\)/\1/p' /etc/syslog.conf | xargs -i rm {}
# (create new logs and add userid of message sender)
_BPX_JOBNAME='SYSLOGD' /usr/sbin/syslogd -cuf /etc/syslog.conf &
sleep 5

AT-TLS configuration in PROFILE.TCPIP

AT-TLS support is activated by the TTLS parameter on the TCPCONFIG statement in the PROFILE.TCPIP data set. AT-TLS is managed by the Policy Agent, which must be active to be able to enforce the AT-TLS policy. Because the Policy Agent must wait for TCP/IP to be active, the AUTOSTART statement in PROFILE.TCPIP is a good place to trigger startup of this server.

These requirements result in following changes to PROFILE.TCPIP, often named TCPIP.TCPPARMS(TCPPROF).
TCPCONFIG TTLS         ; Required for AT-TLS
AUTOLOG
  PAGENT               ; POLICY AGENT, required for AT-TLS
ENDAUTOLOG

Policy Agent started task

AT-TLS is managed by the Policy Agent, which can be started as a started task. Use the following JCL to create SYS1.PROCLIB(PAGENT), using the default configuration file and the recommended log location (SYSLOGD). The necessary definitions in your security software are covered in AT-TLS security updates.
//PAGENT   PROC PRM='-L SYSLOGD'                     * '' or '-L SYSLOGD'
//*
//* TCP/IP POLICY AGENT
//*                                        (PARM) (envar)
//* default cfg file: /etc/pagent.conf     (-C)   (PAGENT_CONFIG_FILE)
//* default log file: /tmp/pagent.log      (-L)   (PAGENT_LOG_FILE)
//* default log size: 300,3 (3x 300KB files) (PAGENT_LOG_FILE_CONTROL)
//*
//PAGENT   EXEC PGM=PAGENT,REGION=0M,TIME=NOLIMIT,
//            PARM='ENVAR("TZ=EST5DST")/&PRM' 
//SYSPRINT DD SYSOUT=* 
//SYSOUT   DD SYSOUT=* 
//*

Policy Agent configuration

The Policy Agent enforces TCP/IP related policies created by the TCP/IP administrator. The agent manages policies for AT-TLS, called TTLS, but also for other services such as IPSec. The Policy Agent uses a configuration file to know which policies must be enforced, and where they can be found. The default configuration file is /etc/pagent.conf, but a different location can be specified in the Policy Agent started task JCL.
#
# TCP/IP Policy Agent configuration information.
#
TTLSConfig /etc/pagent.ttls.conf
# Specifies the path of a TTLS policy file holding stack specific
# statements.
#
#TcpImage TCPIP /etc/pagent.conf
# If no TcpImage statement is specified, all policies will be installed
# to the default TCP/IP stack.
#
#LogLevel 31
# The sum of the following values that represent log levels:
#  LOGL_SYSERR     1
#  LOGL_OBJERR     2
#  LOGL_PROTERR    4
#  LOGL_WARNING    8
#  LOGL_EVENT     16
#  LOGL_ACTION    32
#  LOGL_INFO      64
#  LOGL_ACNTING  128
#  LOGL_TRACE    256
# Log Level 31 is the default log loglevel.
#
#Codepage IBM-1047
# Specify the EBCDIC code page to be used for reading all configuration
# files and policy definition files. IBM-1047 is the default code page.
This sample configuration file specifies where the Policy Agent can find the TTLS policy. It uses Policy Agent default values for other statements.

AT-TLS policy

A TTLS policy describes the desired AT-TLS rules. As defined in the Policy Agent configuration file, the TTLS policy is located in /etc/pagent.ttls.conf. The necessary definitions in your security software are covered in AT-TLS security updates.

This example shows a fairly simple, two-rule policy that activates SSL v3, TLS v1, TLS v1.1 and TLS v1.2 support for the Compiled Language Interception Processor Probe-Client. As defined in the Policy Agent configuration file, the TTLS policy is located in /etc/pagent.ttls.conf.
##
## TCP/IP Policy Agent AT-TLS configuration information.
##
##-----------------------------
TTLSRule                      CLIP_Probe-Client
{
 RemotePortRange          8003
 Direction                Outbound
 TTLSGroupActionRef       grp_Production
 TTLSEnvironmentActionRef act_CLIP_Probe-Client
}
##-----------------------------
TTLSEnvironmentAction         act_CLIP_Probe-Client
{
 HandshakeRole            Client
 TTLSKeyRingParms
 {
  Keyring *AUTH*/*         # virtual key ring holding CA certificates
 }
 TTLSEnvironmentAdvancedParms
 {
## TLSV1.2 only for z/OS 2.1 and higher
# TLSV1.2 On               # SSLv3, TLSv1 & TLSv1.1 are on by default
 }
}
##-----------------------------
TTLSGroupAction               grp_Production
{
 TTLSEnabled               On
## TLSv1.2zOS1.13 only for z/OS 1.13
 TTLSGroupAdvancedParmsRef TLSv1.2zOS1.13
 Trace                     3     # Log Errors to syslogd & IP joblog
#Trace                     254   # Log everything to syslogd
}
##-----------------------------
TTLSGroupAdvancedParms        TLSv1.2zOS1.13
{
 Envfile /etc/pagent.ttls.TLS1.2zOS1.13.env
}

A TTLS policy allows for a wide range of filters to specify when a rule becomes applicable.

When the CLIP agent back-end (probe) is started with Language Environment® (LE) option TEST(,,,RIT&&ipaddress%8003:*), it is instructed to contact the CLIP agent front-end directly at port 8003. This implies, from a TCP/IP perspective, that the host-based CLIP agent back-end (probe) is a client contacting a server (the CLIP agent front-end). This information is captured in the CLIP_Probe-Client rule.

With the host being a TCP/IP client, the Policy Manager will need a way to validate the server certificate presented by the CLIP agent front-end. Instead of using a uniformly named key ring for all users, RACF’s CERTAUTH virtual key ring (*AUTH*/*) is used. This virtual key ring holds the public certificates of Certificate Authorities (CAs), and can be used if the CLIP agent front-end presents a server certificate that is signed by one of the trusted CAs.

Note that for more complex policies, you should use the IBM® Configuration Assistant for z/OS Communications Server. This is a GUI-based tool that provides a guided interface for configuring TCP/IP policy-based networking functions and is available as a task in IBM z/OS Management Facility (z/OSMF), and as a stand-alone workstation application.

TLS v1.2 considerations

TLS v1.2 support became available in z/OS 2.1, and is disabled by default. This policy shows the command (TLSV1.2 On) to explicitly enable it, but has it commented out as the target system is using z/OS 1.13.

By applying the following two APARs, TLS v1.2 support is added to z/OS 1.13:
  • System SSL APAR OA39422
  • Communications Server (AT-TLS) APAR PM62905
z/OS 1.13 System SSL, which is used by AT-TLS to implement TLS encrypted communication, requires some additional parameters for TLS v1.2 support. These are supplied through the AT-TLS policy using a file with System SSL environment variables, /etc/pagent.ttls.TLS1.2zOS1.13.env.
#
# Add TLSv1.2 support to AT-TLS
# requires z/OS 1.13 with OA39422 and PM62905
#
 GSK_RENEGOTIATION=ALL
 GSK_PROTOCOL_TLSV1_2=ON

AT-TLS security updates

Several updates are required to your security setup for AT-TLS to work properly. This section has sample RACF® commands to do the required setup.

You use a started task to run the Policy Agent. Therefore you must define a started task user ID and a profile in the STARTED class.
#  define started task user ID
#  BPX.DAEMON permit is required for non-zero UID
 ADDUSER PAGENT DFLTGRP(SYS1) OMVS(UID(0) SHARED HOME('/')) +
   NAME('TCP/IP POLICY AGENT') NOPASSWORD

#  define started task
 RDEFINE STARTED PAGENT.* STDATA(USER(PAGENT) GROUP(SYS1)) +
   DATA('TCP/IP POLICY AGENT')

#  refresh to make the changes visible
 SETROPTS RACLIST(STARTED) REFRESH
Define a profile named MVS™.SERVMGR.PAGENT in the OPERCMDS class and give the user ID named PAGENT CONTROL access to it. The profile restricts who can start the Policy Agent. If the profile is not defined, and access to it is prevented through a generic profile, PAGENT will not be able to start the Policy Agent, which will prevent TCP/IP stack initialization.
#  restrict startup of policy agent
 RDEFINE OPERCMDS MVS.SERVMGR.PAGENT UACC(NONE) +
   DATA('restrict startup of policy agent')
 PERMIT MVS.SERVMGR.PAGENT CLASS(OPERCMDS) ACCESS(CONTROL) ID(PAGENT)

#  refresh to make the changes visible 
SETROPTS RACLIST(OPERCMDS) REFRESH 
The Policy Agent is started after TCP/IP is initialized. This means there is a (small) window where applications can use the TCP/IP stack without the TTLS policy being enforced. Define the EZB.INITSTACK.** profile in the SERVAUTH class to prevent access to the stack during this time window, except for applications with READ access to the profile. You must permit a limited set of administrative applications to the profile to ensure full initialization of the stack, as documented in “TCP/IP stack initialization access control” in Communications Server IP Configuration Guide (SC31-8775).
#  block stack access between stack and AT-TLS availability
# SETROPTS GENERIC(SERVAUTH)
# SETROPTS CLASSACT(SERVAUTH) RACLIST(FACILITY)
 RDEFINE SERVAUTH EZB.INITSTACK.** UACC(NONE)
#  Policy Agent
 PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(PAGENT)
#  OMPROUTE daemon
 PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(OMPROUTE)
#  SNMP agent and subagents
 PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(OSNMPD)
 PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(IOBSNMP)
#  NAME daemon
 PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(NAMED)

#  refresh to make the changes visible
 SETROPTS RACLIST(SERVAUTH) REFRESH
(Optional) The z/OS UNIX pasearch command displays active policy definitions. Define a profile named EZB.PAGENT.** in the SERVAUTH class to restrict access to the pasearch command.
#  restrict access to pasearch command
# RDEFINE SERVAUTH EZB.PAGENT.** UACC(NONE) + 
#   DATA('restrict access to pasearch command')
# PERMIT EZB.PAGENT.** CLASS(SERVAUTH) ACCESS(READ) ID(tcpadmin)

#  refresh to make the changes visible
# SETROPTS RACLIST(SERVAUTH) REFRESH

#  refresh to make the changes visible
 SETROPTS RACLIST(DIGTCERT) REFRESH
AT-TLS policy also documents the use of the CERTAUTH virtual key ring for validation of the server certificate presented by the CLIP agent front-end in the Probe-Client scenario. This implies that the CA certificate used by the CLIP agent front-end is trusted by your z/OS host.
#  check if the CA credentials (also a certificate) are already known
 RACDCERT CERTAUTH LIST
#  mark the CA certificate as trusted
 RACDCERT CERTAUTH ALTER(LABEL('CA cert')) TRUST
#  or add the CA certificate to the database
 RACDCERT CERTAUTH ADD(dsn) WITHLABEL('CA cert') TRUST

#  refresh to make the changes visible
 SETROPTS RACLIST(DIGTCERT) REFRESH
Use the following commands to verify your setup:
#  verify started task setup
 LISTGRP SYS1 OMVS
 LISTUSER PAGENT OMVS
 RLIST STARTED PAGENT.* ALL STDATA

#  verify Policy Agent startup permission
 RLIST OPERCMDS MVS.SERVMGR.PAGENT ALL

#  verify initstack protection
 RLIST SERVAUTH EZB.INITSTACK.** ALL

#  verify pasearch protection
 RLIST SERVAUTH EZB.PAGENT.** ALL

#  verify certificate setup
 RACDCERT CERTAUTH   LIST(LABEL('CA cert'))
 RACDCERT ID(stcdbm) LIST(LABEL('dbgmgr'))
 RACDCERT ID(stcdbm) LISTRING(dbgmgr.racf)

AT-TLS policy activation

AT-TLS setup is now complete, and the policy will be activated at next IPL of the system. Follow these steps to start using the policy without an IPL:
  1. Activate AT-TLS support in the TCP/IP stack.
    Create a TCP/IP obey file, for example, TCPIP.TCPPARMS(OBEY), with the following content:
    TCPCONFIG TTLS
    Activate it with this operator command:
    V TCPIP,,OBEY,TCPIP.TCPPARMS(OBEY)
    Verify the result by checking for this console message:
    EZZ4249I stackname INSTALLED TTLS POLICY HAS NO RULES
  2. Start the Policy Agent.
    Issue operator command:
    S PAGENT
    Verify the result by checking for console message:
    EZD1586I PAGENT HAS INSTALLED ALL LOCAL POLICIES FOR stackname
  3. Restart HCL OneTest™ API Session Manager to interrupt all active, non-encrypted, sessions.
    Issue operator commands:
    P RITMGR
    S RITMGR
Feedback