API requester 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 with IBM z/OS Connect
- CICS, IMS or a z/OS application, and a IBM z/OS Connect server.
- The IBM z/OS Connect server and the RESTful API endpoint.
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.
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 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 IBM z/OS Connect (or other z/OS applications). Instead of implementing TLS in IBM 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 IBM 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 IBM z/OS Connect
- For CICS®:
- 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 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 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.
Securing communications to RESTful API endpoints
TLS can also be used to secure the connection between the IBM z/OS Connect server and the RESTful API endpoints. The RESTful API endpoint determines if TLS is required, and if it requires the IBM 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 IBM 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 IBM z/OS Connect resources
TLS configuration is required in the IBM z/OS Connect server when requests come in on the HTTPS port.
requireSecure attribute on the
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 specified on the
zosconnect_zosConnectManager element by specifying the
requireSecure attribute on the
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
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 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 your CICS, IMS or z/OS application, an SSL configuration is
associated with an HTTP endpoint (using the
IBM 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 IBM 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 IBM z/OS Connect server to use TLS or AT-TLS, follow the links below.