Securing 3270 Sessions with AT-TLS

In the announcement for z/OS 2.4 in July 2019, IBM made it clear that native support for secure (SSL/TLS) sessions was going to be removed from the TN3270 server, FTP server and DCAS, in favour of AT-TLS.

So, if you haven't embraced AT-TLS and the "Policy Agent" (PAGENT) in z/OS TCP/IP, now is the time! PAGENT has traditionally been regarded as somewhat complex and scary. But while you can certainly get carried away and create sophisticated policy constructs to control all aspects of IP communication with the mainframe platform, this article presents the "bare bones" approach that will get you started with PAGENT, sufficient to secure 3270 terminal emulator communications using AT-TLS.

PAGENT Configuration

If you already have PAGENT operational, skip to the TTLS policy below, otherwise create a "root" configuration file, /etc/pagent.conf:

LogLevel 255
TcpImage TCPIP /etc/pagent.TCPIP.conf FLUSH PURGE 600?        

If you have multiple TCPIP "stacks" or address spaces, you will need a "TcpImage" statement for each one (I won't deal with that case here).

Create a configuration file for your TCP/IP stack, /etc/pagent.TCPIP.conf:

TTLSConfig /etc/pagent.TTLS.policy        

Create a TN3270 policy in a TTLS policy file, /etc/pagent.TTLS.policy:

TTLSRule TN3270
{
? LocalPortRange????????????????? 992
? Direction?????????????????????? Inbound
? TTLSGroupActionRef????????????? TN3270_GA
? TTLSEnvironmentActionRef??????? TN3270_EA
}
TTLSGroupAction?????????????????? TN3270_GA
{
? TTLSEnabled???????????????????? On
# Trace?????????????????????????? 255
}
TTLSEnvironmentAction???????????? TN3270_EA
{
? HandshakeRole?????????????????? Server
? TTLSKeyringParms
? {
??? Keyring?????????????????????? TN3270/TN3270Ring
? }
? TTLSEnvironmentAdvancedParms
? {
??? TLSv1.2?????????????????????? On
??? ApplicationControlled???????? On
? }
}        

PAGENT Started Task

If you don't have a PAGENT started task defined, create a user ID to associate with the PAGENT started task. This user should have the following attributes:

1. No password or passphrase
2. PROTECTED
3. An OMVS segment with unique UID

Associate the PAGENT started task with this user. From TSO:

RDEFINE STARTED PAGENT.* STDATA(USER(PAGENT) TRUSTED)        

Define the PAGENT PROC in a system PROCLIB:

//PAGENT?? PROC??????????????????????????????????? 
//PAGENT?? EXEC PGM=PAGENT,REGION=0M,TIME=NOLIMIT, ?
//???????? PARM='ENVAR("_CEE_ENVFILE_S=DD:STDENV")/'
//SYSPRINT DD?? SYSOUT=*?????????????????????????? ?
//STDENV?? DD?? *????????????????????????????????? ?
? PAGENT_CONFIG_FILE=/etc/pagent.conf????????????? ?
? PAGENT_LOG_FILE=/tmp/pagent.log????????????????? ?
? LIBPATH=/usr/lib???????????????????????????????? ?
? TZ=AEST-10AEDT?????????????????????????????????? ?
/*??????????????????????????????????????????????????        

Issue a MVS operator command to start the PAGENT started task (and add it to your z/OS IPL automation):

S PAGENT        

Server Certificates

Generate a self-signed Certificate Authority (CA) certificate, which will be used to sign the TN3270 server's certificate. From TSO:

RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('TN3270 CA') O('MyCo') C('AU')) SIZE(2048) WITHLABEL('TN3270CA') NOTAFTER(DATE(2030-12-31))        

Generate a server certificate, owned by the user associated with for your TN3270 started task:

RACDCERT ID(TN3270) GENCERT SUBJECTSDN(CN('TN3270 Server') O('MyCo') C('AU')) SIZE(2048) WITHLABEL('TN3270Server') SIGNWITH(CERTAUTH LABEL('TN3270CA')) NOTAFTER(DATE(2030-12-31))        

Add a keyring, owned by the user associated with your TN3270 started task:

RACDCERT ID(TN3270) ADDRING(TN3270Ring)        

Connect the TN3270 CA certificate to the ring:

RACDCERT ID(TN3270) CONNECT(CERTAUTH LABEL('TN3270CA') RING(TN3270Ring) USAGE(CERTAUTH))        

Connect the TN3270 Server certificate to the ring as the DEFAULT certificate:

RACDCERT ID(TN3270) CONNECT(ID(TN3270) LABEL('TN3270Server') RING(TN3270Ring) USAGE(PERSONAL) DEFAULT)        

If RACLISTed, refresh the DIGTRING and DIGTCERT classes:

SETROPTS RACLIST(DIGTCERT) REFRESH
SETROPTS RACLIST(DIGTRING) REFRESH        

Export the TN3270 CA certificate to a data set, because the "client" terminal emulator will need this certificate in order to validate the TN3270 Server's certificate during SSL handshake processing:

RACDCERT CERTAUTH EXPORT(LABEL('TN3270CA')) DSN('TN3270CA.CERT')        

Transfer this data set, converting from EBCDIC to ASCII to your workstation(s) where you run your terminal emulator.

TN3270 Profile

You can locate your TN3270 profile data set by searching for message EZZ6044I in the MVS console log, for example:

EZZ6001I TN3270 SERVER STARTED
EZZ6044I TN3270 PROFILE PROCESSING BEGINNING FOR FILE
??????????? ADCD.Z24B.TCPPARMS(TN3270)??????????????????        

Edit your TN3270 profile to add a definition for the TLS port (we chose port 992 in the AT-TLS profile, so use the same port number here):

TelnetParms??????????? ; Standard SSL/TLS TELNET port????????????????? 
? TTLSPort 992???????????????????????????????????????????????????????? ?
? ConnType Secure????? ; Must be secure connection???????????????????? ?
EndTelnetParms???????????????????????????????????????????????????????? ?
BeginVTAM????????????? ; Mapping for TTLS port.??????????????????????? ?
? Port 992???????????? ;?????????????????????????????????????????????? ?
? DEFAULTLUS?????????? ; Define LUs to be used for general users.????? ?
??? TCP00001..TCP00030???????????????????????????????????????????????? ?
? ENDDEFAULTLUS??????????????????????????????????????????????????????? ?
? LINEMODEAPPL TSO???? ; Send all line-mode terminals directly to TSO. ?
? ALLOWAPPL TSO* DISCONNECTABLE??????????????????????????????????????? ?
?????????????????????? ; If a TSO session is closed, disconnect the user
?????????????????????? ; rather than log off the user.???????????????? ?
? ALLOWAPPL *????????? ; Allow access to all applications.???????????? ?
? USSTCP USSN????????? ; Send out the default TN USS table???????????? ?
EndVTAM?????????????????????????????????????????????????????????????????        

Activate the new TN3270 profile by issuing a MVS operator command, for example:

VARY TCPIP,TN3270,OBEY,DSN=ADCD.Z24B.TCPPARMS(TN3270)        

Emulator Configuration

Configuration of the terminal emulator on your workstation will vary depending on your workstation platform and emulator software. What follows is the procedure for IBM Personal Communications (PCOMM) 14.0 on Windows 10.

From the Windows "Settings" app, search for "certificate" and select the "Manage computer certificates" applet:

Right-click on "Trusted Root Certification Authorities" and select All Tasks->Import... :

Click "Next" on the first panel of the "Certificate Import Wizard"

Enter the name of the file containing the TN3270 CA certificate that you downloaded from z/OS, then click "Next":

Click "Next" to import the certificate as a trusted root CA certificate:

Click "Finish" to complete the importing of the certificate:

Now invoke your PCOMM emulator to establish a session with z/OS. From the menu, select Communication->Configure...->Link Parameters.

On the "Host Definition" panel, change the port number to reflect the SSL/TLS port configured on z/OS:

On the "Security Setup" panel, check the "Enable Security" checkbox, then press "OK".

Now press "OK" to dismiss the "Link Parameters" dialog.

Press "OK" again to accept the warning that your communication will be terminated.

If all is well, PCOMM will connect to z/OS using a secure TLS session. To confirm this from the PCOMM menu, select Communication->Security Information... If you can select this menu option, you have a secure connection and the "Security Protocol", "Security Encryption Level" (i.e. chosen ciphersuite) and "Server Certificate Information" will be displayed:

That's all you need to know - go for it!