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.

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. After the specified number of requests, the HTTP connection and the underlying socket are closed. If HTTPS is used, a TLS handshake occurs every time after that number of requests is reached. The default value of maxKeepAliveRequests is -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 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 IBM z/OS Connect by using mutual TLS authentication, in which the two parties authenticate each other.

Configuring TLS for IBM z/OS Connect resources

You can use TLS server authentication, or TLS client authentication in combination with the other authentication methods:

Basic authentication.
OpenID Connect with JWT authentication. This takes precedence over TLS client authentication.

For more information, see API provider authentication and identification.

Configuring IBM z/OS Connect SSL elements

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.

z/OS Connect server on
z/OS For more information, see How to configure a TLS connection with RACF key rings and How to configure a TLS connection with PKCS12 keystores.

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, 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 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.