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
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 leysize >= 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.
- If the parameter is specified in the TTLSConnectionAction statement that is the value used.
- If the parameter is specified in the TTLSEnvironmentAction statement that is the value used.
- If the parameter is specified in the TTLSGroupAction statement that is the value used.
- If a default value is defined, that is the value used.
- 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.
ColinPaice 
One thought on “Using AT-TLS and PAGENT on z/OS (with ADCD)”