I wrote this post based on getting X3270 to work with TLS to z/OS. It covers some of the lessons I learned in doing so.

Policy Server

See Getting AT-TLS and PAGENT to work on z/OS – start here.

The Communications Server’s policy server allows you to define policies for: (the list below is mainly taken from the IBM documentation)

• QoS: The overall Quality of Service provided to applications or users, in terms of elements such as throughput and delay. It might be critical to provide Business Application traffic better service during peak hours than that of FTP or web traffic.
• IDS: Intrusion Detection Services provides the following support: scan detection and reporting, attack detection, reporting, and prevention, traffic regulation for TCP connections and UDP receive queues. You can use IDS policies to specify event conditions and the actions to take for particular events
• IPSec: IP Security policy can be used for the following protection:
  • Protect a secure host on an internal network from unwanted network traffic
  • Provide protection for traffic between partner companies over connected networks
  • Allow secure sending of data over the Internet by providing IPSec virtual private network (VPN) support
• Routing: Policy conditions consist of a variety of selection criteria that act as filters for policy-based routing (Routing) rules. Traffic can be filtered based on source addresses, destination addresses, source port range, destination port range, protocol, job name, security zone, and security label.
• AT-TLS: (Application Transparent-Transport Layer Security) Provides TLS support at the TCPIP level (below the application). Using AT-TLS means applications do not need to be changed to support TLS.

The PAGENT (Policy Agent) started task runs the policy server. It can use local configuration files, or data in LDAP.

Using AT-TLS

It was a struggle to get a secure connection using AT-TLS and x3270. Many parameters need to be correct for the TLS Handshake to work. Some combinations should work – but did not, the documentation is not 100% correct. When I knew what the correct parameters were, the configuration was pretty easy! The configuration technique looks as if it was designed for a baby system. It is not easy to follow good housekeeping, and change management practices, which made the overall experience harder than I expected.

X3270 requirements

x3270 is a 3270 emulator. It can use TLS to provide a secure connection to z/OS. Although you can specify a certificate for X3270 to use – x3270 does not used the client certificate.

At a high level, the TLS flow between x3270 and AT-TLS is:

• X3270 client sends a “client-hello” request to the server. This includes what levels of TLS are supported (TLS 1.2, TLS 1.3), and the cipher specs it supports (what encryption type,what checksum algorithm etc)
• The server (Pagent) matches the information sent in the “Client-hello” with its configuration. For example, select a certificate which matches the encryption type, and finds a common cipher spec.
• If there is an acceptable certificate, and cipher spec, the selected certificate and selected cipher spec are sent down to the client (“server hello”).
• The x3270 client checks that the certificate is acceptable – the CN in the certificate matches the address of the server. (CN(10.1.1.2) matches the IP address 10.1.1.2).
• If client authentication is requested, then the client sends its certificate to the server. This is not supported by X3270, and the server has to be configured with HandshakeRole Server.

X3270 initially sends that it can support TLS 1.2 and TLS 1.3, and a variety of cipher specs.

TN3270 requirements

Not all certificates worked. I could only get certificates to work with

• RSA key size >= 2048
• NISTECC keysize >= 521

To AT-TLS, this is just a certificate name in a keyring.

In the AT-TLS configuration

• ApplicationControlled On is required. This allows TN3270 to interact with AT-TLS, for example display the cipher spec being used.
• HandshakeRole Server is required.
• It needs a keyring, and access to the private part of the certificate. For example CONTROL access to the RACF profile userid.ring.LST int the RDATALIB class.
• Certificates
  • If you do not specify a certificate – it takes the keyring default.
  • You can specify a(one) certificatelabel.
  • You can specify multiple ServerCertificateLabel statements. With this you can support different certificate types, and support migration to newer certificates.

AT-TLS configuration – in general

The Communications Server as a group of products, do not have a consistent way of configuring the individual components. For example some use # as a comment delimiter, other products use ; . Configuring the Policy Server is not difficult – just different, and does not behave as other z/OS components do, or as I expected.

In my PAGENT JCL is

//STDENV -> USER.Z24C.TCPPARMS(PAGENTEN).

This file has

PAGENT_CONFIG_FILE=//'USER.Z24C.TCPPARMS(PAGENTCF)' 
LIBPATH=/usr/lib 

The PAGENTCF member is like

CommonTTLSConfig //'USER.Z24C.TCPPARMS(PAGENTCO)' 
tcpImage TCPIP   //'USER.Z24C.TCPPARMS(PAGENTT)' 
tcpImage TCPIP1  //'USER.Z24C.TCPPARMS(PAGENT1)' 

File USER.Z24C.TCPPARMS(PAGENTT) has the configuration for one TCPIP image.

TTLSConfig //'USER.Z24C.TCPPARMS(PAGENTTN)' FLUSH PURGE 
TTLSRULE ... #and other inline definitions 

QOSConfig  //'USER.Z24C.TCPPARMS(PAGENTQ1)' FLUSH PURGE 
policyAction  ...  # and other inline QOS definitions 

# and similarly for IDS, IPSec,Routing etc

You are allowed one TTLSConfig statement per TCPIP file. If you have multiple, only the last one will be used. You can have multiple TTLSRULE statements.

How the configuration works

Within a file, if you have a set of definitions with the same name, the last one will be used. For example

TTLSEnvironmentAction                 TNEA 
{ 
  TTLSKeyringParms 
  { 
    Keyring                   START1/TN3270 
  } 
  Trace 17
} 
TTLSEnvironmentAction                 TNEA 
{ 
  TTLSKeyringParms 
  { 
    Keyring                   START2/TN3270 
  }   
} 

The keyring will be START2/TN3270 and Trace is not specified.

If you use Unix command pasearch -t , it will show keyring:START2/TN3270 and no trace statement in that section. Definitions with the same name are replaced, not merged.

Having just one TTLSCONFIG file makes it harder to manage. I would like to be able to have a configuration file for each port, or have all of the TLSRULEs in one file, and TTLSCipherParms in another file, and so on. It would make it easier to manager, and perform change management on the files.

The configurations from tcpImage TCPIP2 and tcpImage TCPIP2 are isolated from each other. If you want to use common definitions between tcpImages, put them in CommonTTLSConfig file.

The commonTTLSConfig statements are processed before the tcpImage statements, so a definition set in the tcpImage file will take precedence over a common definition.

The commonTTLSConfig file seems to need to be self consistent. I added

TTLSEnvironmentAction                 TNEA 
{ 
  TTLSSignatureParmsRef       TNESigParms 
} 

Without the TNESigParms definition. I got strange configuration error messages until I included the TNESigParms {..} in the file.

Using smaller units.

I remember some advice I was given… try to get all of your changes visible on one screen. Use subroutines or other ways of dividing up the code.

You can have

TTLSCipherParms 
{
   TTLSCipherParms 
   { 
      V3CipherSuites      TLS_CHACHA20_POLY1305_SHA256 
   } 
}

But the list of cipher suites could be long.

You can have a …REFerence o a set of definitions.

TTLSConnectionAction   TNCA 
{ 
  TTLSCipherParmsRef   TLS13TLS12 
} 
TTLSCipherParms        TLS13TLS12 
{ 
  #TLS 1.3 
   V3CipherSuites      TLS_CHACHA20_POLY1305_SHA256 
   #V3CipherSuites      TLS_AES_256_GCM_SHA384 
   #V3CipherSuites      TLS_AES_128_GCM_SHA256 
 #TLS 1.2 
   # NSTECC 
   V3CipherSuites   TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
   #RSA 
   V3CipherSuites      TLS_RSA_WITH_AES_256_CBC_SHA256 
} 

The allows you to create a “subroutine” out of the cipherspecs. It also allows you to use the same definitions in multiple places.

Within a TCPIPIMAGE configuration

The same parameter can be specified in more than one configuration statement. The documentation says:

For parameters that can be specified in multiple action types, the value used by a connection is
determined by the following hierarchical rule set, they first found is used.

1. If the parameter is specified in the TTLSConnectionAction statement that is the value used.
2. If the parameter is specified in the TTLSEnvironmentAction statement that is the value used.
3. If the parameter is specified in the TTLSGroupAction statement that is the value used.
4. If a default value is defined, that is the value used.
5. No value is used by AT-TLS and no parameter is explicitly passed to System SSL.

So if you have

TTLSEnvironmentAction  TNEA 
{ 
  TTLSCipherParmsRef     TLS13 
} 
TTLSConnectionAction   TNCA 
{ 
  TTLSCipherParmsRef    TLS13TLS12 
} 

The the CipherParms TLS13TLS12 will be used, because Connection is used before Environment.

If you use pasearch -t … it will display the configuration with sections like

TTLS Action:                  TNGA 
    Scope:                      Group 

TTLS Action:                  TNEA 
  Scope:                      Environment 

  TTLSCipherParms: 
    v3CipherSuites: 
      1303  TLS_CHACHA20_POLY1305_SHA256 
 ... 
TTLS Action:                  TNCA 
    Scope:                      Connection 
    TTLSCipherParms: 
     v3CipherSuites: 
      1303  TLS_CHACHA20_POLY1305_SHA256 
      C02C  TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 
      003D  TLS_RSA_WITH_AES_256_CBC_SHA256 

Because of the order, Scope:Connection takes precedence over Scope:Environment, the three cipher specs will be used.

When configuring AT-TLS I found it easiest if I used the Unix commands pasearch -t -f TN 1>a; oedit a and specify the rule name I was interested in (TN), then search for the last instance of the attribute of interest

PDSE or Unix file?

If you configuration is in Unix files, then you can get AT-TLS to reread this on regular basis – typically half an hour. This is useful of you want changes to be picked up automatically, but not if you want strict change control management.

AT-TLS configuration for TN3270

Below is the AT-TLS configuration for my telnet (PAGENTTN…) configuration.

TTLSRule                      TN 
{ 
  LocalPortRange              2023 
  Jobname                     TN3270 
  Direction                   INBOUND 
  TTLSConnectionActionRef     TNCA   
  TTLSGroupActionRef          TNGA 
  TTLSEnvironmentActionRef    TNEA 

} 
TTLSConnectionAction              TNCA 
{ 
  TTLSCipherParmsRef              TLS13TLS12 
  TTLSSignatureParmsRef           TNESigParms 
  TTLSConnectionAdvancedParmsRef  TNCOonAdvParms 
  CtraceClearText                 Off 
  Trace                           50 
} 
TTLSConnectionAdvancedParms       TNCOonAdvParms 
{ 
 ServerCertificateLabel  NISTECC521 
 ServerCertificateLabel  RSA2048 
#ccp this was added 
  ApplicationControlled         On 
  SSLv3          OFF 
  TLSv1          OFF 
  TLSv1.1        OFF 
  TLSv1.2        ON 
  TLSv1.3        OFF 
  SecondaryMap   OFF 
  HandshakeTimeout 3 
} 

TTLSGroupAction      TNGA 
{ 
  TTLSEnabled        ON 
  trace              50 
} 
TTLSKeyringParms    TNKEYRING 
{ 
  Keyring           START1/TN3270 
} 

TTLSEnvironmentAction      TNEA 
{ 
  HandshakeRole            Server 
  TTLSKeyringParms 
  { 
    Keyring                START1/TN3270 
  } 
  TTLSSignatureParmsRef    TNESigParms 
} 
TTLSSignatureParms         TNESigParms 
{ 
   CLientECurves Any 
} 
TTLSCipherParms             TLS13TLS12 
{ 
#TLS 1.3 
 V3CipherSuites      TLS_CHACHA20_POLY1305_SHA256 
#V3CipherSuites      TLS_AES_256_GCM_SHA384 
#V3CipherSuites      TLS_AES_128_GCM_SHA256 
#TLS 1.2 
# NSTECC 
 V3CipherSuites      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 
#RSA 
 V3CipherSuites      TLS_RSA_WITH_AES_256_CBC_SHA256 
} 

I did many system SSL traces to get it working.

Using certificates

• If you do not specify a certificate label in the configuration, AT-TLS takes the default from the keyring.
• You can specify a certificate label using CertificateLabel…
• If you want to specify more than one Certificate label – for example you are migrating from one certificate to another, or you want to support an RSA certificate and an Elliptic Curve certificate then specify one or more ServerCertificateLabel … statements.

Some lessons learned

• When configuring TN3270 use V3CipherSuites not V3CipherSuites4char. V3CipherSuites takes 2 character identifiers and long TLS_… strings. V3CipherSuites4char only take 4 character identifiers , and not TLS_… strings.
• If you change the PAGENT configuration you need F PAGNET,UPDATE to pick up the changes.
• If you make a change to the PAGENT configuration, it does not always report problems. You should use Unix command commands like pagent -t -f TN 1>a ;oedit a to display the TTLS configuration for rule TN, and edit the file to check.
• If you change a keyring, you need F CPAGENT,REFRESH to pick up the change.
• When you start PAGENT use the -l /var/log/pagent.log -d1 options. Review the /var/log/pagent.log file and check for “WARNING” and “ERR”
• The PAGENT configuration can have the same parameter specified at the environment level and at the connection level. The pasearch -t -f TN command displays both sets of data … you have to be careful you are checking the right set of data.
• PAGENT does not report if a section was skipped. I had two TTLSConfig statements in a TCPIP image file, and only the last one was used.
• You need the syslogd daemon running to capture error messages in a file.

General PAGENT commands

See here for starting PAGENT (and the trace levels you can use).

Updating PAGENT

If you change the PAGENT configuration (my job is CPAGENT) you can use

F CPAGENT,UPDATE

To refresh the configuration,

F CPAGENT,REFRESH

to refresh the configuration and restart processing. Existing sessions will continue unchanged.

When configuring TN3270 you can use the Unix command pasearch -t -f TN 1>a to display just the TLS policy you are interested in (TN) .

Displaying information

You display configuration information using the Unix command pasearch…

What does a rule configuration look like?

I frequently use

pasearch -t -f TN

This shows me the TLS configuration for rule TN

What does the high level TLS object look like?

pasearch -c -t

gave me

TTLS Policy Object:                                                     
  ConfigLocation:       Local             LDAPServer:        False      
  CommonFileName:                                                       
  ImageFileName:        //'USER.Z24C.TCPPARMS(PAGENTTN)'                
  ApplyFlush:           True              PolicyFlush:       True       
  ApplyPurge:           True              PurgePolicies:     True       
  AtomicParse:          True              DeleteOnNoflush:   False      
  DummyOnEmptyPolicy:   True              ModifyOnIDChange:  False      
  Configured:           True              UpdateInterval:    1800       
  TTLS Enabled:         True                                            
  InstanceId:           1666079380                                      
  LastPolicyChanged:    Tue Oct 18 08:49:40 2022                        

The CommonFileName: value was blank, which was a surprise as I had specified a file.

How to display a summary of a rule?

pasearch -t -n

gave

policyRule:             TN         
  TTLS Action:          TNGA       
  TTLS Action:          TNEA       
  TTLS Action:          TNCA       

How do I display which policy or rule has been used?

I could not find a way of displaying which rules were used, and which options were used.