Configure AT-TLS

Application Transparent Transport Layer Security (AT-TLS) is an encryption solution for TCP/IP applications that is transparent to the application server and client. Packet encryption and decryption occurs in the z/OS TCPIP address space at the TCP protocol level. AT‐TLS requirements for RACF authorization are stated in the IBM RACF Mainframe Requirements.

The following RACF commands list the status of the various RACF objects that you will define in the configuration process:

RLIST STARTED PAGENT.* STDATA ALL
RLIST DIGTRING *ALL
RLIST FACILITY IRR.DIGTCERT.LISTRING ALL
RLIST FACILITY IRR.DIGCERT.LST ALL
RLIST FACILITY IRR.DIGCERT.GENCERT ALL
RACDCERT ID(stcuser) LIST
RACDCERT ID(stcuser) LISTRING(keyringname)
RACDCERT CERTAUTH LIST

Specify Parameter in TCPIP Profile

Specify the following parameter in the TCPIP profile data set to activate AT‐TLS.

TCPCONFIG TTLS

This statement may be placed in the TCP OBEY file.

Configure the Policy Agent (PAGENT)

The Policy Agent address space controls which TCP/IP traffic is encrypted.

Enter the PAGENT started task JCL.

For example:

//PAGENT PROC
//*
//PAGENT EXEC PGM=PAGENT,REGION=0K,TIME=NOLIMIT,
// PARM='POSIX(ON) ALL31(ON) ENVAR("_CEE_ENVFILE=DD:STDENV")/-d1'
//*
//STDENV DD DSN=pagentdataset,DISP=SHR//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//*
//CEEDUMP DD SYSOUT=*,DCB=(RECFM=FB,LRECL=132,BLKSIZE=132)

Enter the PAGENT environment variables. The pagentdataset data set contains the PAGENT environment variables.

For example:
```
LIBPATH=/lib:/usr/lib:/usr/lpp/ldapclient/lib:.
PAGENT_CONFIG_FILE=/etc/pagent.conf
PAGENT_LOG_FILE=/tmp/pagent.log
PAGENT_LOG_FILE_CONTROL=3000,2
_BPXK_SETIBMOPT_TRANSPORT=TCPIP
TZ=MST7MDT
```
In this example, /etc/pagent.conf contains the PAGENT configuration parameters. Use your own time zone for the TZ parameter.

Configure PAGENT.

For example:

TTLSRule TBI-TO-ZOS
{
 LocalAddr localtcpipaddress
 RemoteAddr remotetcpipaddress
 LocalPortRange localportrange
 RemotePortRange remoteportrange
 Jobname HTTPserverJobname
 Direction Inbound
 Priority 255
 TTLSGroupActionRef gAct1~TBI_ICSF
 TTLSEnvironmentActionRef eAct1~TBI_ICSF
 TTLSConnectionActionRef cAct1~TBI_ICSF
}
TTLSGroupAction gAct1~TBI_ICSF
{
 TTLSEnabled On
 Trace 2
}
TTLSEnvironmentAction eAct1~TBI_ICSF
{
 HandshakeRole Server
 EnvironmentUserInstance 0
 TTLSKeyringParmsRef keyR~ZOS
}
TTLSConnectionAction cAct1~TBI_ICSF
{
 HandshakeRole ServerWithClientAuth
 TTLSCipherParmsRef cipher1~AT-TLS__Gold
 TTLSConnectionAdvancedParmsRef cAdv1~TBI_ICSF
 CtraceClearText Off
 Trace 2
}
TTLSConnectionAdvancedParms cAdv1~TBI_ICSF
{
 ApplicationControlled Off
 HandshakeTimeout 10
 ResetCipherTimer 0
 CertificateLabel certificatelabel
 SecondaryMap Off
}
TTLSKeyringParms keyR~ZOS
{
 Keyring keyringname
}
TTLSCipherParms cipher1~AT-TLS__Gold
{
 V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
 V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
}

where:

localtcpipaddress: Local TCP/IP address for the HTTP server
remotetcpipaddress: Remote TCP/IP address for the STA client. This can be ALL for all TCP/IP addresses
localportrange: Local port of HTTP server (specified in the HTTP or SMC startup)
remoteportrange: Remote port range (1024-65535 for all ephemeral ports)
HTTPserverJobname: Jobname of the HTTP Server
certificatelabel: Label from the certificate definition
keyringname: Name from the RACF keyring definition

Activate RACF Classes

Either the RACF panels or the CLI can be used.

The RACF classes include:

DIGTCERT
DIGTNMAP
DIGTRING

SERVAUTH class must be RACLISTed to prevent PORTMAP and RXSERV from abending.

SETROPTS RACLIST(SERVAUTH)
RDEFINE SERVAUTH **UACC(ALTER) OWNER (RACFADM)
RDEFINE STARTED PAGENT*.* OWNER(RACFADM) STDATA(USER(TCPIP) GROUP(STCGROUP)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE) OWNER(RACFADM)
RDEFINE FACLITY IRR.DIGTCERT.LIST UACC(NONE) OWNER(RACFADM)
RDEFINE FACILITY IRR.DIGTCERT.GENCERT UACC(NONE) OWNER (RACFADM)

Define RACF Keyrings and Certificates

Enter the following RACF commands to create Keyrings and certificates:

RACDCERT ID(stcuser) ADDRING(keyringname)

where:

stcuser: RACF user id associated with the TCPIP address space
keyringname: Name of the keyring, must match the Keyring specified in the PAGENT configuration

For the CA certificate for the STA system:

RACDCERT ID(stcuser) GENCERT CERTAUTH SUBJECTSDN(CN('serverdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('calabel') TRUST SIZE(1024) KEYUSAGE(HANDSHAKE,DATAENCRYPT,CERTSIGN)

where:

stcuser: RACF user id associated with the TCPIP address space
serverdomainname: Domain name of the z/OS server
companyname: Organization name
unitname: Organizational unit name
country: Country
calabel: Label for certificate authority (for example, CATBISERVER)

For the SERVER certificate:

RACDCERT ID(stcuser) GENCERT SUBJECTSDN(CN('serverdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('serverlabel') TRUST SIZE(1024) SIGNWITH(CERTAUTH LABEL('calabel'))

where:

stcuser: RACF user id associated with the TCPIP address space
serverdomainname: Domain name of the z/OS server
companyname: Organization name
unitname: Organizational unit name
country: Country
serverlabel: Label for the server certificate (for example, TBISERVER)
calabel: Label for certificate authority, specified in the CA certificate definition

For the CLIENT certificate:

RACDCERT ID(stcuser) GENCERT SUBJECTSDN(CN('clientdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('clientlabel') TRUST SIZE(1024) SIGNWITH(CERTAUTH LABEL('calabel'))

where:

stcuser: RACF user id associated with the TCPIP address space
clientdomainname: Domain name of the STA client
companyname: Organization name
unitname: Organizational unit name
country: Country
clientlabel: Label for the server certificate –TBICLIENT
calabel: Label for certificate authority, specified in the CA certificate definition.

Connect the CA, SERVER, and CLIENT certificates to the keyring specified in the PAGENT configuration

Connect the CA, SERVER, and CLIENT certificates to the keyring :

RACDCERT ID(stcuser) CONNECT(CERTAUTH LABEL('calabel') RING('keyringname') USAGE(CERTAUTH))

where:

stcuser: RACF user id associated with the TCPIP address space
calabel: Label for certificate authority, specified in the CA certificate definition
keyringname: Name of the keyring, must match the Keyring specified in the PAGENT configuration

RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('serverlabel') RING('keyingname') DEFAULT USEAGE(PERSONAL)

where:

stcuser: RACF user id associated with the TCPIP address space
serverlabel: Label for the server certificate
keyringname: Name of keyring, must match the Keyring specified in the PAGENT configuration

RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('clientlabel') RING('keyingname') USEAGE(PERSONAL)

where:

stcuser: RACF user id associated with the TCPIP address space
clientlabel: Label for the client certificate
keyringname: Name of keyring, must match the Keyring specified in the PAGENT configuration

Export the CA and client certificates to be transmitted to STA

RACDCERT EXPORT (LABEL('calabel')) CERTAUTH DSN('datasetname') FORMAT(CERTB64)

where:

calabel: Label for certificate authority, specified in the CA certificate definition
datasetname: Data set to receive the exported certificate

RACDCERT EXPORT (LABEL('clientlabel')) ID(stcuser) DSN('datasetname') FORMAT(PKCS12DER) PASSWORD(' password ')

where:

clientlabel: Label for the client certificate
stcuser: RACF user id associated with the TCPIP address space
datasetname: Data set to receive the exported certificate
password: Password for data encryption. Needed when the certificate is received on STA. The password must be eight characters or more.

The export data sets are now transmitted to STA, and FTP can be used. The CA certificate is transmitted with an EBCDIC to ASCII conversion. The CLIENT certificate is transmitted as a BINARY file and contains both the client certificate and its private key.