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.
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 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 V188.8.131.52 (Liberty 184.108.40.206) 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
From IBM z/OS Connect V220.127.116.11 (Liberty 18.104.22.168),
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
persistTimeout attribute on the
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
points to an
sslOptions element where the
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_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.
- 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.
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
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.
<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.
- 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.
- You can configure IBM z/OS Connect to meet the SP800-131a specification. For more information, see SP800-131a.