I. Introduction

• TLS Record Protocol provides connection security and has two basic properties:
  • The connection is private. Secret key cryptography is used for data encryption. The keys for this secret key encryption are generated uniquely for each connection and are based on a secret negotiated by a handshake.
  • The connection is reliable. Message transport includes a message integrity check using a keyed-hash MAC (HMAC). Secure hash functions (for example, SHA-1 or MD5) are used for MAC computations.

• The TLS Handshake Protocol operates on top of the TLS Record Protocol and allows the server and client to authenticate each other and to negotiate an encryption algorithm and cryptographic keys before the application protocol (such as HTTP) transmits or receives its first byte of data. The TLS Handshake Protocol provides connection security that has three basic properties:The peer’s identity can be authenticated using public key cryptography.
  • The negotiation of a shared secret is secure: the negotiated secret is unavailable to eavesdroppers, and for any authenticated connection the secret cannot be obtained, even by an attacker who can place himself in the middle of the connection.
  • The negotiation is reliable: no attacker can modify the negotiation communication without being detected by the parties in communication.

II. TLS handshake

There are two types of TLS handshake: a one-way handshake during which only the server certificate is sent and validated; and a two-way handshake during which both the server and the client certificates are exchanged and validated.

Figure 1 shows the actions taken by the client and server during a TLS handshake with the optional client certificate exchange in red.

Firgure 1. TLS handshake

The TLS Handshake Protocol involves the following steps:

1. Exchange hello messages to agree on a cipher suite and a compression algorithm, exchange random values, and check for session resumption.
2. Exchange the necessary cryptographic parameters to allow the client and server to agree on a premaster secret.
3. Exchange certificates and cryptographic information to allow the client and server to authenticate themselves.
4. Generate a master secret from the premaster secret and exchanged random values.
5. Provide security parameters to the record layer.
6. Allow the client and server to verify that their peer has calculated the same security parameters and that the handshake occurred without tampering by an attacker.

The two-way TLS handshake offers more security but as it involves the validation of the client certificate, the handshake may take more time to complete. For instance, in our environment the overhead z Systems Integrated Information Processor (zIIP) consumption can go up to 2 ms.

The one-way TLS handshake is suitable for simple use cases but allows any client to connect to the server, un-less another method of authentication is enabled. Table 1 outlines the main differences between one-way and two-way handshakes.

The cost of handshaking can be optimized by enabling persistent TCP/IP connections (see ‘Persistent connections’). For more information related to the TLS handshake, see the TLS V1.2 specification.

II.1 Configuration

In order to configure TLS with z/OS Connect EE you must define the ssl-1.0 (or appSecurity-2.0) feature in server.xml and then use the ssl element to define the required settings. The default setting is to use a one-way TLS handshake (see Example 1).

Example 1 One-way TLS handshake

Note: Example 1 enables use of a default key store and trust store generated by Liberty. This allows TLS to be used from REST clients to z/OS Connect EE without having to create certificates. In Example 5 we will show a more realistic configuration using a SAF (System Authorization Facility) keyring.

To enable two-way TLS handshake, the clientAuthentication attribute is set to true (see Example 2).

Example 2 Two-way TLS handshake

In Example 2, when client authentication is configured, for each HTTPS connection, z/OS Connect EE asks the client to provide its certificate. z/OS Connect EE validates the chain of trust using its trust store i.e. it validates that the client certificate issuer is in the trust store.

Note: If no trustStoreRef is defined then the keyStoreRef is used instead.

To use SAF keyring, specify the keystore type JCERACFKS and the name of the keyring in the keyStore element (see Example 3).

Example 3 Configuring a SAF keyring

For more information on using SAF-based certificates refer to the Keystores and truststores.

If the client request contains a Single Sign-On (SSO) token, for example, a Lightweight Third-Party Authentication (LTPA) token or JSON Web Token (JWT), the server tries to authenticate the user using the token.

If no SSO token is provided, the server tries to associate a user ID with the client certificate. If the client certificate is stored in a SAF (e.g. RACF) then the certificate owner’s user ID is used, or if the certificate is unknown to SAF then a Certificate Name Filter can be used to map the certificate to a user ID. For more information on RACF certificate mapping see RACDCERT MAP.

If there is no SSO token provided and no match to a Certificate Name Filter, then the client is considered as unauthenticated and an HTTP response code 401 is returned, unless the allowFailOverToBasicAuth is enabled (see Example 4).

Example 4 Configuring failover to Basic Authentication in server.xml

In Example 4, the allowFailOverToBasicAuth attribute is set to true which allow the client to use Basic Authentication to authenticate after other authentication mechanisms have failed.

The allowFailOverToBasicAuth attribute can also be used with one-way TLS handshake to enable Basic Authentication as authentication mechanism over an HTTPS connection.

In cases where some clients can only perform a one-way TLS handshake, and a two-way TLS handshake is not mandatory for every HTTPS connection, then the clientAuthenticationSupported attribute can be set to true (see Example 5).

Example 5 Configuring client authentication in server.xml

With the configuration shown in Example 5, z/OS Connect EE still prompts the client for a certificate but the handshake does not fail if the client does not provide a certificate.

Note: If clientAuthentication is set to true, z/OS Connect EE ignores the setting of clientAuthenticationSupported.

III. Persistent connections

When HTTPS is used for inbound requests to z/OS Connect EE, the use of persistent connections outperform the use of non-persistent connections. When using persistent connections, the client can reuse the underlying socket connection and the TLS handshake is avoided.

Often an intermediary (‘trusted’) server receives end-user requests and authenticates users before propagating the request to z/OS Connect EE (see Figure 2).

Figure 2

In this case, the trusted server manages the establishment of the TLS sessions to the hundreds (or thousands) of end-user clients. The overhead of this processing is on the trusted server, and not the z/OS Connect EE server. The trusted server can then establish a long-lived (‘persistent’) TLS session to z/OS Connect EE, and the end-user requests are propagated across this persistent TLS session.

III.1 Configuration

Persistent sessions are configured by setting the keepAliveEnabled attribute on the httpOptions element to true (see Example 6).

Example 6 Configuring persistent connections

IV. Cipher suites

During the TLS handshake, the TLS protocol and data exchange cipher are negotiated.
First, the client sends:

• the highest version of TLS
• the list of the ciphers that it supports

Then the server chooses:

• the highest version of TLS that is commonly supported by itself and the client
• one cipher that is commonly supported by itself and the client

It is recommended to use the latest version of TLS as it generally contains fixes to previous versions and brings enhancements like support for stronger cipher suites. As for z/OS Connect EE, the latest supported version of TLS is TLS 1.2.

Example 7 shows the cipher naming convention used by z/OS Connect EE, and an example cipher.

Example 7 Ciphers

In Example 7, the cipher TLS_RSA_WITH_AES_256_CBC_SHA256 defines the:

• TLS protocol
• RSA key exchange algorithm
• AES_CBC encryption algorithm with a 256-bit key
• SHA hash algorithm with a 256-bit key (from the SHA-2 family)

Note: The choice of the cipher and key length has an impact on performance: some algorithms are more CPU-intensive than others

IV.1 Configuration

The protocol is configured using the sslProtocol attribute of the ssl element, and the supported ciphers are configured using the enabledCiphers attribute (see Example 8).

Example 8 Configuring TLS protocol and supported ciphers in server.xml

Example 8 configures the use of TLS 1.2 and of two specific ciphers

Note: It is recommended to control what ciphers can be used in the server rather than in the client.

To enable the use of longer key sizes, the java unrestricted SDK JCE Policy files need to be used. These files can usually be found in the Java SDK for z/OS at $JAVA_HOME/demo/jce/policy-files/unrestricted/. Example 9 shows how the unrestricted policy files can be set as a JVM option in the server.env configuration file of the z/OS Connect EE server.

Example 9 Configuration the use of unrestricted policy files in server.env

Note: server.env is used as DD statement for z/OS Connect EE’s STDENV.The JVM options must be defined on a single line in server.env.

V. Java version and Java Security providers

The Java version and choice of Java security provider will have an impact on the performance of using TLS with z/OS Connect EE. For example, running z/OS Connect EE with IBM Java 8 on an IBM z13 machine provides significantly improved performance.

Java makes a variety of security providers available through the Java Cryptography Architecture (JCA). The IBM JVM default provider is IBMJCE. With IBM Java 8, the IBMJCE provider now automatically detects and exploits the Central Processor Assist for Cryptographic Functions (CPACF) of the z core in the IBM z13 to provide better performance of symmetric key algorithms (e.g. AES and 3DES) and hashing algorithms (e.g. SHA1 and SHA2) used in the TLS Record Protocol. More information on cryptography performance with Java 8 on z13 can be found in the IBM z Systems Development Blog.

The IBM JVM on z Systems provides an additional security provider called IBMJCECCA which leverages the I/O-attached cryptographic accelerator technology (the IBM Crypto Express card). When a Crypto Express card is used in accelerator mode it can significantly reduce the processing time of the TLS handshake. In order to benefit from the Crypto Express card, the IBMJCECCA provider needs to be added to the Java Cryptography Extension (JCE) providers list. Alternatively, you can specify the IBM JCE Hybrid Provider IBMJCEHYBRID, which handles failover to software cryptography in case the Crypto Express cards are unavailable.

V.1 Configuration

You can configure a list of Java security providers by modifying the default java.security file which can be found in the Java SDK for z/OS at $JAVA_HOME/lib/security/.

Example 10 Example java.security file with list of Java security providers

Example 10 shows an example list of security providers that includes IBMJCEHYBRID and IBMJCECCA.

Example 11 Configuring use of modified java.security file in server.env

Example 11 shows how the modified java.security file can be set as a JVM option using the -Djava.security.properties environment variable in the server.env configuration file of the z/OS Connect EE server. We set the location of the modified java.security file to /var/zosconnect/servers/MOPZCEP/.

To use the IBM JCE Hybrid Provider, you specify a keystore type JCEHYBRIDRACFKS in server.xml (see Example 12).

Example 12 Configuring IBM JCE Hybrid Provider keystore type in server.xml

For more information on using the IBM JCE Hybrid Provider see Instructions on how to set Liberty JVM to use IBMJCEHYBRID.

VI. Conclusion

After reading this article, you should have a better understanding of the different TLS configurations available with z/OS Connect EE, and some of the performance considerations like persistent connections, cipher suites, Java version and Java security provider.