Improving XCOM Data Transport transfers with TLSv1.3

You can use a network service proxy to incorporate improved TLS features into your XCOM Data Transport transfers.  This blog will show an example of using XCOM Data Transport between z/OS and Linux (RHEL 8.6) to create transfers that are secured between the systems using TLSv1.3.  While the example focuses on Linux transfers, the same concepts may be applied to other environments (e.g. Windows) where you have a TLSv1.3 capable network service proxy.

Sending data to z/OS

Your XCOM Data Transport z/OS started task will be the server in this first scenario, listening for suitable remote connections.  Using XCOM Data Transport z/OS configuration parameters:

• AT-TLS=ALLOW
• AT-TLS_PORTS=12346

you configure your XCOM Data Transport z/OS server to listen for AT-TLS secure connections on port 12346.  You can select the port of your choice, but this example will use port 12346.  AT-TLS will allow successful connections that meet the policy definitions to reach your XCOM Data Transport z/OS started task.  The following are example AT-TLS policy definitions.  You can review these example policies as a guide, but you should work with your site AT-TLS experts to get the appropriate TLSv1.3 rules in place for your environment.  The example policies are simplified definitions that use a key database file and you should consider implementing yours with a SAF key ring outside of proof-of-concept, or demo environments.  Also, the list of ciphers is incomplete (you will notice a ... break in the list) for brevity of the blog.

The policy statements are not explained in this blog, but you can find documentation for these statements here:  AT-TLS policy statements and, again, you should work with your site experts to properly implement your policies.

XCOM Data Transport Linux r12.0 currently (January 2023) supports secure transfer protocol levels up to TLSv1.2.  There is discussion to enhance XCOM Data Transport Linux r12.0 to support TLSv1.3 directly; however, you can leverage external TLS proxy software to implement TLSv1.3 transfers with XCOM Data Transport z/OS for your site today.  You might also be able to extend TLSv1.3 secured transfers to additional XCOM Data Transport partners when those partners either support TLSv1.3 or also employ an external TLS proxy supporting TLSv1.3.

On the Linux side, you will install and configure a TLS proxy that supports TLSv1.3; this blog uses stunnel as an example, but you can use a different TLS proxy program.  Configure stunnel to accept your local, unencrypted XCOM transfer network traffic on a specific local port and send that data as TLSv1.3 encrypted data to your XCOM Data Transport z/OS AT-TLS protected port.  By defining a service in the stunnel configuration you employ stunnel to supply the TLSv1.3 handshake and implement the protocol to send encrypted data over your network connection to z/OS.  stunnel becomes a middle-man in your transfer, ensuring your transfer data is encrypted in the network using the TLSv1.3 protocol.

Here is an example of the stunnel service definition used for sending data to z/OS for this blog.

/etc/stunnel/stunnel.conf

The blog example uses 12347 as the local Linux port your Linux initiated transfer communicates with directly.  Your transfer flows through stunnel on the same physical machine and gets forwarded by stunnel outbound from your Linux system to the final z/OS destination.  The outbound traffic from stunnel to z/OS's AT-TLS is TLSv1.3 protected.

Stunnel process flow sending data to z/OS

The diagram below shows the complete flow using stunnel and AT-TLS for TLSv1.3 transfers.  On Linux (RHEL on the right), xcomtcp initiates the transfer to local port 12347, where it is forwarded by stunnel using TLSv1.3 to the z/OS port 12346 as encrypted traffic (depicted by the padlock of unrecognizable bits).  The z/OS AT-TLS connection is allowed since it meets the policy and the data is presented to XCOM Data Transport z/OS to complete the transfer.

How do you know your Linux -> z/OS transfer was really secured with TLSv1.3?

You know your transfer was TLSv1.3 secure because XCOM Data Transport z/OS is AT-TLS aware and queries the connection to issue message XCOMM1504I showing the TLS version and cipher used.  For example:

TLSv1.3 capable certificates

The certificates you use for TLSv1.3 transfers must meet the TLSv1.3 requirements.  You can find many resources explaining the TLSv1.3 requirements and this blog only mentions some basic requirements based on changes from previous XCOM sample certificates that might be required for TLSv1.3.

You can create certificates using gskkyman (Certificate/Key management) on z/OS but you should work with your site certificate experts to ensure you have certificates that are properly signed by a certificate authority to meet your site requirements.  For this example, gskkyman was used to do the following from z/OS OMVS:

• Create self-signed certificates that meet the minimum TLSv1.3 certificate requirements including:
• 2048 key lengths
• supported message digest algorithms
• supported ciphers
• Create a new kdb (option 1b)
• Open the new kdb
• Create a self-signed CA certificate for cassl
• Create two user or server certificates with labels servercert and clientcert

All certificates were created with RSA 2048-bit keys and a SHA-256 message digest and defaults or names taken from the prior XCOM certificate samples.

Troubleshooting certificates that do not support TLSv1.3

Using older certificates that are insufficient for TLSv1.3 will lead to errors that might include the following:

1. XCOM Data Transport z/OS will issue TXPI errors when AT-TLS ends the connection for policy problems.  From XCOM Data Transport z/OS this will look like a broken connection (EPIPE socket value 140) since the connection is ended by z/OS Communication Server.
   In the z/OS Communications Server address space log or z/OS system log you might find some related messages (e.g. EZD1287I) with codes that help explain the problem.  For example, code 528 means the key length is too small for TLSv1.3.
2. Once you have the key size right you might encounter other problems, for example, handshake problems from a remote sender with the same EZD1287I but now with error code 414, which means the message digest signature algorithm isn't supported.
3. You can also receive code 402 with a TLSv1.3 client trying to send to a server supporting only TLSv1.2.

Certificate files for stunnel

To create your Linux certificate file used by stunnel, export the clientcert certificate and key to a file with gskkyman, in binary, version 3, with strong encryption.  Transfer the client cert and key files to Linux in binary and then you can use the following Linux openssl commands to create your pem file for stunnel.

openssl pkcs12 -in clientcert.p12 -out clientcert.crt.pem -clcerts -nokeys

openssl pkcs12 -in clientcert.p12 -out clientcert.key.pem -nocerts -nodes

Once you've extracted the certificate and key in pem format you should concatenate these into a pem file for stunnel using the following command:

cat clientcert.crt.pem clientcert.key.pem > xcom120.pem

Again, you should involve your site’s certificate experts to ensure your certificates meet site requirements.  Involving your site experts early will generally save you time in the long run.

Sending data to Linux

This second scenario is similar to the first scenario (Sending data to z/OS), although now the Linux system is the server listening for connections.  In this example, the transfer is initiated from z/OS via JCL by scheduling a transfer to occur in the XCOM Data Transfer z/OS started task.  The transfer is AT-TLS TLSv1.3 protected because it meets client rules defined in the AT-TLS policy.  The JCL used to schedule a z/OS transfer and the AT-TLS client rules used for the blog example are shown below.

On the Linux side, you configure a TLS proxy service for inbound data that supports TLSv1.3 and forwards to your local XCOM Data Transport Linux server’s port.  This blog uses stunnel as an example proxy and “txpi” as the example service name to receive inbound, TLSv1.3 encrypted data on port 12346.  The stunnel “txpi service” definition then causes stunnel to forward unencrypted transfer data to your local XCOM Data Transport Linux instance on port 8044 to complete the transfer.

Here is an example of the stunnel service definitions used for sending data from z/OS for this blog.

/etc/stunnel/stunnel.conf

Stunnel process flow sending data to Linux

The diagram below shows the flow using AT-TLS and stunnel to enable TLSv1.3 transfers from z/OS to Linux.  On z/OS the schedule JCL starts a transfer to Linux port 12346.  AT-TLS allows the connection because it meets the policy statements and sends encrypted data to Linux where stunnel receives the encrypted data on port 12346 and forwards to XCOM Data Transport Linux port 8044 as unencrypted traffic.

How do you know your z/OS -> Linux transfer was really secured with TLSv1.3?

You know your transfer was TLSv1.3 secure because XCOM Data Transport z/OS is AT-TLS aware and queries the connection to issue message XCOMM1504I showing the TLS version and cipher used.  For example:

Summary

Using a TLS network service proxy you can achieve TLSv1.3 support for your XCOM Data Transport transfers in your network between systems.