API provider confidentiality and integrity

Learn how to maintain the confidentiality and integrity of the data that is handled by IBM® z/OS® Connect.

Before you study this topic, you should be familiar with the information in Overview of IBM z/OS Connect security.

Confidentiality ensures that an unauthorized party cannot obtain the information in the transferred or stored data. Typically, confidentiality is achieved by encrypting the data.

Integrity ensures that transmitted or stored information is not altered in an unauthorized or accidental manner.

Securing communications to IBM z/OS Connect

You can secure communications between a REST client and a IBM z/OS Connect server by using the Transport Layer Security (TLS) protocol. TLS provides transport layer security that includes confidentiality, integrity, and authentication to secure the connection between a client and a IBM z/OS Connect server. For more information on TLS, see Transport Layer Security (TLS).

IBM z/OS Connect uses Java™ Secure Sockets Extension (JSSE) as the TLS implementation for secure connections. JSSE provides a framework and Java implementation that handles the handshake negotiation and protection capabilities that are provided by TLS. For more information, see Java Secure Sockets Extension (JSSE).

Alternatively you can use Application Transparent Transport Layer Security (AT-TLS), a capability of z/OS Communications Server, for transport layer security with IBM z/OS Connect. For more information, see Application Transparent Transport Layer Security (AT-TLS).

Figure 1 shows the TLS implementation options available for API provider.

For any REST client that supports TLS:
- The HTTPS connection is established with port 5002. The port is associated with an SSL configuration in the IBM z/OS Connect server.
- The HTTPS connection is established with port 5004. The port is protected by an AT-TLS inbound policy so the TLS connection is managed by AT-TLS. Client certificate authentication cannot be used for this connection.
For a z/OS REST client that relies on an AT-TLS outbound policy:
- Outbound connections to port 5002 are protected by the AT-TLS outbound policy. On the server, port 5002 is associated with an SSL configuration in the IBM z/OS Connect server.
- Outbound connections to port 5004 are protected by the AT-TLS outbound policy. On the server, port 5004 is protected with an AT-TLS inbound policy so the TLS connection is managed by AT-TLS. Client certificate authentication cannot be used for this connection.

TLS can be used with both HTTP and HTTPS ports — Figure 1. TLS implementation options for API provider.

In most cases, REST clients do not connect directly to a IBM z/OS Connect server, but through an intermediate server, as shown in Figure 2.

The intermediate server uses information from the keystore and truststore to verify the REST client when a connection is established. — Figure 2. Using an intermediate server for requests to a IBM z/OS Connect server.

There might be hundreds or thousands of TLS connections constantly being created and released between the various REST clients and the intermediate server. This activity focuses the CPU cost and management of the TLS certificates on the intermediate server, and allows for comparatively fewer TLS connections between the intermediate server and the IBM z/OS Connect server. These TLS connections can be long lived through using persistent connections.

Persistent connections

Persistent connections can reduce CPU usage.

When TLS is used, CPU intensive processing occurs most during the handshake phase. The simplest way to reduce this cost is to enable persistent HTTP connections because a TLS handshake occurs only during the creation of the HTTP connection. By using this mechanism, the cost of the handshake is spread over multiple requests.

You can configure IBM z/OS Connect to limit the number of persistent requests that can reuse an HTTP connection by setting the maxKeepAliveRequests attribute on an httpOptions element that is referenced from the httpEndpoint element. At IBM z/OS Connect V3.0.46.0 (Liberty 21.0.0.3) and earlier levels, the default value of maxKeepAliveRequests is 100. After 100 requests, the HTTP connection and the underlying socket are closed. If HTTPS is used, a TLS handshake occurs every 100 requests.

From IBM z/OS Connect V3.0.47.0 (Liberty 21.0.0.6), the default value of maxKeepAliveRequests can be set to -1, which means that the HTTP connection and the underlying socket are never closed. However, an idle socket is still closed after the time specified in persistTimeout. For more information, see httpEndpoint > httpOptions in the WebSphere Application Server for z/OS Liberty documentation.

You can also increase the amount of time that a connection persists when it is not being used by changing the persistTimeout attribute on the httpOptions element. The default is 30 seconds.

Even after the persistent maximum number of requests or timeout is reached, the SSL session ID can be used to avoid another costly handshake. During the handshake phase, IBM z/OS Connect and the REST client create an SSL session ID, which is used for all the persistent HTTP connections. When another handshake is needed, and the REST client calls IBM z/OS Connect with the same SSL session ID as used in the previous handshake, IBM z/OS Connect can decide to do a null handshake. The null handshake means that the connection reuses the same symmetric key as the previous session to avoid the handshake phase. The connection is a prolongation of the persistent HTTP connections. The control of the usage of the SSL session ID is done in the httpEndpoint, which points to an sslOptions element where the sslSessionTimeout attribute establishes the time the encryption symmetric key for HTTP requests is used.

Additional trust can be established between the intermediate server and the IBM z/OS Connect server by using mutual TLS authentication, in which the two parties authenticate each other.

Configuring TLS for IBM z/OS Connect resources

By default, IBM z/OS Connect requires clients to connect to the server into the HTTPS port. The requireSecure attribute on the zosconnect_zosConnectManager, zosConnectAPI, service, and zosconnect_zosConnectService elements of the server.xml configuration file, control whether a specific request must connect into the HTTPS port. The default value of the requireSecure attribute is true. You can set this value to false to remove this requirement at a specific scope or when AT-TLS inbound is used.

TLS server authentication is enabled by default, but you can also configure TLS client authentication, also called mutual TLS authentication. In this configuration, the client authenticates itself with a personal certificate. You can then choose whether to also use the client certificate to establish the authenticated identity for the request.

Alternatively, you can use TLS server authentication, or mutual TLS authentication with other authentication methods. For example,

Use basic authentication.
Use an authentication mechanism such as OpenID Connect (that uses a JWT), OAuth, or TAI. These mechanisms all take precedence over the client certificate authentication method.

For more information, see API provider authentication and identification.

Configuring IBM z/OS Connect SSL elements

If you set requireSecure attribute to true then the IBM z/OS Connect server must be configured to use TLS.

IBM z/OS Connect TLS is configured by using elements in the server.xml configuration file. To configure TLS for connections from client applications, an SSL configuration is associated with an HTTP endpoint (using the httpEndpoint element).

IBM z/OS Connect includes a default SSL configuration. This default configuration is typically customized to add your own keystores and truststores, configure whether client authentication is required or supported, or whether only server authentication is required.

For information, see How to configure TLS with RACF key rings.

In a development environment, you might choose to start testing with the default SSL configuration. You can use this default configuration to get started quickly with TLS because a keystore and certificate are automatically created for you. For production environments, use SAF to create your own key rings and certificates.

To use the default SSL configuration, add the following element to dynamically create a keystore:

<keyStore id="defaultKeyStore" password="yourpassword" />

For more information about using the default SSL configuration, see SSL defaults in Liberty in the WebSphere Application Server for z/OS Liberty documentation.

If you require different TLS implementations, such as using different certificates for different clients, you can configure extra SSL configuration elements and HTTP endpoint elements, and associate the appropriate SSL configuration to the appropriate HTTP endpoint (HTTPS) ports.

Other considerations

When you implement API provider confidentiality and integrity, you might also want to consider the following options:

Cipher suites: You can use cipher suites to control the cryptographic algorithms used on the TLS connection. For more information, see Cipher suites.
Hardware cryptography: You can use hardware cryptography with TLS connections. For more information, see Hardware cryptography.
SP800-131a: You can configure IBM z/OS Connect to meet the SP800-131a specification. For more information, see SP800-131a.