Configure AT-TLS
Configure AT-TLS so the port number defined to the SMC HTTP Server and WebLogic is encrypted to the STA server.
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. Thepagentdataset
data set contains thePAGENT
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 thePAGENT
configuration parameters. Use your own time zone for theTZ
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 serverremotetcpipaddress
: Remote TCP/IP address for the STA client. This can be ALL for all TCP/IP addresseslocalportrange
: 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 Servercertificatelabel
: Label from the certificate definitionkeyringname
: 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 preventPORTMAP
andRXSERV
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 spacekeyringname
: 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 spaceserverdomainname
: Domain name of the z/OS servercompanyname
: Organization nameunitname
: Organizational unit namecountry
: Countrycalabel
: 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 spaceserverdomainname:
Domain name of the z/OS servercompanyname:
Organization nameunitname:
Organizational unit namecountry
: Countryserverlabel
: 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 spaceclientdomainname
: Domain name of the STA clientcompanyname
: Organization nameunitname
: Organizational unit namecountry
: Countryclientlabel
: Label for the server certificate –TBICLIENTcalabel
: 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 spacecalabel:
Label for certificate authority, specified in the CA certificate definitionkeyringname:
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 spaceserverlabel
: Label for the server certificatekeyringname
: 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 spaceclientlabel
: Label for the client certificatekeyringname
: 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 definitiondatasetname:
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 certificatestcuser
: RACF user id associated with the TCPIP address spacedatasetname
: Data set to receive the exported certificatepassword
: 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.