AT-TLS security updates

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

For more information about RACF commands, see Security Server RACF Command Language Reference (SA22–7687).

As mentioned in Policy Agent started task, you use a started task to run the Policy Agent. This requires the definition of 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 PAGENTD DFLTGRP(SYS1) OMVS(UID(0) SHARED HOME('/')) +
  NAME('TCP/IP POLICY AGENT') NOPASSWORD

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

#  refresh to dynamically activate the changes
SETROPTS RACLIST(STARTED) REFRESH

Define a profile named MVS.SERVMGR.PAGENT in the OPERCMDS class and give user ID PAGENTD 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, PAGENTD 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(PAGENTD)

#  refresh to dynamically activate the changes 
SETROPTS RACLIST(OPERCMDS) REFRESH

As mentioned in AT-TLS configuration in PROFILE.TCPIP, 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 of Communications Server IP Configuration Guide (SC31-8775).

Note: The Policy Agent issues message EZD1586I when all policies are active.

#  activate the SERVAUTH class
SETROPTS GENERIC(SERVAUTH)
SETROPTS CLASSACT(SERVAUTH) RACLIST(SERVAUTH)

#  block stack access between startup and AT-TLS availability
RDEFINE SERVAUTH EZB.INITSTACK.** UACC(NONE)
#  Policy Agent
PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(PAGENTD)
#  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 dynamically activate the changes
SETROPTS RACLIST(SERVAUTH) REFRESH

(Optional) The z/OS® UNIX pasearch command displays active policy definitions. Define profile EZB.PAGENT.** in the SERVAUTH class to restrict access to the pasearch command. Replace the #tcpadmin placeholder with valid user IDs or RACF group names.

#  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 dynamically activate the changes
SETROPTS RACLIST(SERVAUTH) REFRESH

As mentioned in AT-TLS policy, the RSED started task needs a certificate so that it can identify itself to the other party. These sample commands create a new certificate labeled FEK.cert, which is stored in an SAF key ring named FEK.keyring. Both the certificate and the key ring are owned by STCRSE, the RSED started task user ID. Access to the key ring and certificate private key is managed through the <userid>.<ring>.LST profile in the RDATALIB class. Sample commands to use the older, more generic, IRR.DIGTCERT profiles are also included.

#  activate class holding profiles that control certificate access
SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)

#  define profiles that control certificate access 
RDEFINE RDATALIB STCRSE.FEK.KEYRING.LST UACC(NONE)

#  permit server user ID to access key ring and related private keys
PERMIT STCRSE.FEK.KEYRING.LST CLASS(RDATALIB) ACCESS(CONTROL) ID(STCRSE)

#  refresh to dynamically activate the changes
SETROPTS RACLIST(RDATALIB) REFRESH

# ALTERNATIVE to using RDATALIB profiles
# #  define profiles that control certificate access 
# RDEFINE FACILITY IRR.DIGTCERT.LIST     UACC(NONE)
# RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
#
# #  permit server user ID to access certificates
# PERMIT IRR.DIGTCERT.LIST     CLASS(FACILITY) ACCESS(READ) ID(STCRSE)
# PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(STCRSE)
#
# #  refresh to dynamically activate the changes
# SETROPTS RACLIST(FACILITY) REFRESH

#  create self-signed certificate
RACDCERT ID(STCRSE) GENCERT SUBJECTSDN(CN('m094.rtp.ibm.com') +
  OU('RTP labs') O('IBM') L('Raleigh') SP('NC') C('US')) +
  NOTAFTER(DATE(2025-12-31)) SIZE(2048) +
  KEYUSAGE(HANDSHAKE) WITHLABEL('FEK.cert')

#  create keyring
RACDCERT ID(STCRSE) ADDRING(FEK.keyring)

#  add server certificate as default to keyring
RACDCERT ID(STCRSE) CONNECT(LABEL('FEK.cert') +
  RING(FEK.keyring) DEFAULT)

#  refresh to dynamically activate the changes
SETROPTS RACLIST(DIGTCERT) REFRESH

(Optional) Having a well-known Certificate Authority (CA) sign the RSE started task certificate simplifies the client trusting the server certificates of related services, like that of the Debug Manager (part of IBM® Debug for z/OS), as all client services use the same certificate keystore as RSE client, and will trust all certificates signed by a trusted CA. The following commands convert your self-signed certificate to a signed one. These sample commands place the signing request in sequential data set &SYSUID..FEKCERT.REQ, and assume the signed certificate is staged in sequential VB84 data set &SYSUID..FEKCERT.CER. Sequential VB84 data set &SYSUID..CACERT.CER is used as input staging data set if you must add the public CA certificate that matches the private key used by the CA to sign your request.

#  create a signing request for the self-signed certificate
#    Do NOT delete the self-signed certificate before replacing it.
#    If you do, you lose the private key that goes with the 
#    certificate, which makes the certificate useless.
RACDCERT ID(STCRSE) GENREQ (LABEL('FEK.cert')) +
  DSN(FEKCERT.REQ)

#  send the signing request to your CA of choice

#  ensure the CA is known and trusted by RACF
#    list all CA certificates defined in the database
RACDCERT CERTAUTH LIST
#    mark the CA certificate used to sign your certificate as trusted
RACDCERT CERTAUTH ALTER(LABEL('CA cert')) TRUST
#    or add the CA certificate used to sign yours to the database
RACDCERT CERTAUTH ADD(CACERT.CER) WITHLABEL('CA cert') TRUST

#  add the CA certificate to the key ring
RACDCERT ID(STCRSE) CONNECT(CERTAUTH LABEL('CA cert') +
  RING(FEK.keyring))

#  add the signed certificate to the database;
#    this will replace the self-signed one
RACDCERT ID(STCRSE) ADD(FEKCERT.CER) +
  WITHLABEL('FEK.cert') TRUST

#  refresh to dynamically activate the changes
SETROPTS RACLIST(DIGTCERT) REFRESH

Use the following commands to verify your setup:

#  verify started task setup
LISTGRP SYS1 OMVS
LISTUSER PAGENTD 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(STCRSE) LISTCHAIN(LABEL('FEK.cert'))
RACDCERT ID(STCRSE) LISTRING(FEK.keyring)