API requester confidentiality and integrity for zosConnect-2.0

zosConnect-2.0 Applies to zosConnect-2.0.

Learn how to maintain the confidentiality and integrity of the data that IBM® z/OS® Connect handles for API requesters that call OpenAPI2 APIs.

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 with z/OS Connect

You can secure communications by using the Transport Layer Security (TLS) protocol between
  • CICS, IMS or a z/OS application, and a z/OS Connect Server.
  • The z/OS Connect Server and the RESTful API endpoint.
Figure 1 shows the TLS connections that can be used in an API requester scenario. The port values in the following examples are for illustration purposes only.
Figure 1. TLS connections in an API requester scenario.
A TLS connection can be configured between the z/OS application and the API requester and also between the API requester and the RESTful API.

TLS provides transport layer security that includes confidentiality, integrity, and authentication to secure the connection between a client and an z/OS Connect Server.

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 provided by TLS. For more information on JSSE, see Java Secure Sockets Extension (JSSE).

Alternatively you can use Application Transparent Transport Layer Security (AT-TLS), a capability of z/OS Communications Server, which can create a secure session on behalf of z/OS Connect (or other z/OS applications). Instead of implementing TLS in z/OS Connect, AT-TLS provides encryption and decryption of data based on policy statements that are coded in the Policy Agent. IBM z/OS Connect sends and receives cleartext (unencrypted data) as usual while AT-TLS encrypts and decrypts data at the TCP transport layer. Note that if you configure an AT-TLS inbound policy to secure the connection into a z/OS Connect Server, then client certificate authentication cannot be used.

For more information on AT-TLS, see Application Transparent Transport Layer Security (AT-TLS).

Securing communications to z/OS Connect

Figure 2 shows the TLS implementation options available for securing communications to a z/OS Connect Server when using API requester.
  1. For CICS®:
    • The HTTPS connection is established with port 5002. The port is associated with an SSL configuration in the z/OS Connect Server.
    • The HTTPS connection is established with port 5004. The port is protected by an AT-TLS inbound policy so AT-TLS manages the TLS connection. Client certificate authentication cannot be used for this connection.
  2. For CICS, IMS or z/OS applications.
    • Outbound connections to port 5003 are protected by the AT-TLS outbound policy. On the server, port 5003 is associated with an SSL configuration in the 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 AT-TLS manages the TLS connection. Client certificate authentication cannot be used for this connection.
Figure 2. TLS implementation options available for API requester.
TLS can be used with both HTTP and HTTPS ports

Securing communications to RESTful API endpoints

TLS can also be used to secure the connection between the z/OS Connect Server and the RESTful API endpoints. The RESTful API endpoint determines whether TLS is required, and if it requires the z/OS Connect Server to authenticate itself with a personal certificate. 

AT-TLS outbound policies can be configured to secure the TLS connection from the z/OS Connect Server. If the RESTful API endpoint supports AT-TLS, then inbound policies can also be configured to secure the TLS connection into the RESTful API endpoint. 

Configuring TLS for z/OS Connect resources

TLS configuration is required in the z/OS Connect Server when requests come in on the HTTPS port.

The requireSecure attribute on the zosconnect_zosConnectManager, zosconnect_apiRequesters, and apiRequester elements of the server.xml configuration file, control whether a TLS connection is required for a specific request. The default value of the requireSecure attribute is true. You can set this value to false to remove the requirement for a TLS connection at a specific scope. When using AT-TLS inbound set the requireSecure attribute in your server.xml configuration file to false. You can override the global setting that is specified on the zosconnect_zosConnectManager element by specifying the requireSecure attribute on the zosconnect_apiRequesters element for all API requesters or on the apiRequester element for an individual API requester. The setting for an individual API requester takes precedence over the setting for all API requesters.

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 (for example, CICS) authenticates itself with a personal certificate. 

In addition to the standard TLS behavior you can choose whether to also use client certificate authentication, by using the client certificate to establish the authenticated identity for the request. Alternatively, you can use TLS server authentication or mutual TLS authentication with basic authentication. For more information, see API requester authentication and identification.

Configuring z/OS Connect SSL elements

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

zosConnect-2.0 Applies to zosConnect-2.0.

z/OS Connect TLS is configured by using elements in the server.xml configuration file.

To configure TLS for connections from your CICS, IMS or z/OS application, an SSL configuration is associated with an HTTP endpoint (using the httpEndpoint element).

z/OS Connect includes a default SSL configuration (defined by the ssl element with id value of defaultSSLConfig). 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 TLS connections from your z/OS Connect Server to the RESTful API endpoint, the default SSL configuration is used. You can override this default SSL configuration by specifying the sslCertsRef attribute on the zosconnect_endpointConnection element. For more information, see API requester TLS client authentication to a RESTful API endpoint.

Further configuration information

For more information about how to configure CICS, IMS or a z/OS application, and the z/OS Connect Server to use TLS or AT-TLS, see the following links.