AT-TLS security updates

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 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 user ID 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 

As mentioned in AT-TLS configuration in PROFILE.TCPIP, the Policy Agent is started after TCP/IP is initialized. This means that 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(SERVAUTH)
 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

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.

#  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

As mentioned in AT-TLS policy, Debug Manager needs a certificate so that AT-TLS can set up encrypted communication on Debug Manager’s behalf. These sample commands create a new certificate that is labeled dbgmgr, which is stored in a RACF key ring named dbgmgr.racf. Both the certificate and the key ring are owned by STCDBM, the Debug Manager started task user ID.

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

#  define profiles that control certificate access 
RDEFINE RDATALIB STCDBM.DBGMGR.RACF.LST UACC(NONE)

#  permit server user ID to access key ring and related private keys
PERMIT STCDBM.DBGMGR.RACF.LST CLASS(RDATALIB) ACCESS(CONTROL) ID(stcdbm)

#  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(stcdbm)
# PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(stcdbm)
#
# #  refresh to dynamically activate the changes
# SETROPTS RACLIST(FACILITY) REFRESH

#  create self-signed certificate
 RACDCERT ID(stcdbm) GENCERT SUBJECTSDN(CN('Debug Manager') +
   OU('RTP labs') O('IBM') L('Raleigh') SP('NC') C('US')) SIZE(2048) +
   NOTAFTER(DATE(2015-12-31)) KEYUSAGE(HANDSHAKE) WITHLABEL('dbgmgr')

# create key ring
RACDCERT ID(stcdbm) ADDRING(dbgmgr.racf)

# add certificate to key ring
RACDCERT ID(stcdbm) CONNECT(LABEL('dbgmgr') RING(dbgmgr.racf) +
  DEFAULT USAGE(PERSONAL))

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

(Optional) If you sign the server certificate with a trusted certificate authority (CA), the client trusts the signed certificate directly. Use the following commands to convert your self-signed certificate to a CA-signed one. These sample commands place the signing request in sequential data set &SYSUID..EQACERT.REQ, and assume that the signed certificate is staged in sequential VB84 data set &SYSUID..EAQCERT.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(stcdbm) GENREQ (LABEL('dbgmgr')) +
  DSN(EQACERT.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(stcdbm) CONNECT(CERTAUTH LABEL('CA cert') +
  RING(dbgmgr.racf))

#  add the signed certificate to the database;
#    this will replace the self-signed one
RACDCERT ID(stcdbm) ADD(EQACERT.CER) +
  WITHLABEL('dbgmgr') TRUST

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

The result can be verified with the following list and listring options:

RACDCERT ID(stcdbm) LIST
Digital certificate information for user STCDBM:

 Label: dbgmgr
 Certificate ID: 2QjW1OXi0sXZ1aaEqZmihUBA
 Status: TRUST
 Start Date: 2007/05/24 00:00:00
 End Date:   2015/12/31 23:59:59
 Serial Number:
      >00<
 Issuer's Name:
      >CN=CA cert.OU=CA.O=IBM.L=Raleigh.SP=NC.C=US<
 Subject's Name:
      >CN=Debug Manager.OU=zexpl.O=IBM.L=Raleigh.SP=NC.C=US<
 Private Key Type: Non-ICSF
 Private Key Size: 2048
 Ring Associations:
   Ring Owner: STCDBM
   Ring:
      >dbgmgr.racf<

RACDCERT ID(stcdbm) LISTRING(dbgmgr.racf) 
Digital ring information for user STCDBM:

  Ring: 
     >dbgmgr.racf< 
  Certificate Label Name             Cert Owner     USAGE      DEFAULT
  --------------------------------   ------------   --------   -------
  dbgmgr                             ID(STCDBM)     PERSONAL     YES
  CA cert                            CERTAUTH       CERTAUTH     NO

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)