Enabling TLS Connection between IBM AD Validation Server and IBM AD Connect for Mainframe

About this task

For IBM® AD V5.1.0.7 and earlier versions, the communication between IBM AD Validation Server and IBM AD Connect for Mainframe is unencrypted socket session. Beginning with version 5.1.0.8, the optional secure communication, which uses the Transport Layer Security (TLS) protocol, is supported by using the Application Transparent Transport Layer Security (AT-TLS) feature of IBM z/OS® Communication Server.

Procedure

Find the TLSEncryption.text file in the <IBM AD Installation Folder>\bin\release\IBMApplicationDiscoveryValidationServer folder, and then set the flag value to Y in the file.
This configuration file contains a single flag byte. The flag can take the value Y or N. It is not case-sensitive. Y indicates that AT-TLS is enabled. If N is specified or the flag value is missing, the communication will not be encrypted. A sample file is provided in the <IBM AD Installation Folder>\bin\release\IBMApplicationDiscoveryValidationServer\SampleConf folder.
Generate a personal certificate that is signed by a certificate authority (CA) to represent IBM AD Validation Server, and the key to this certificate. After the CA certificate and key files are generated, store them in the <IBM AD Installation Folder>\bin\release\IBMApplicationDiscoveryValidationServer folder.
This certificate must be in the PEM Based 64 format and contain string —– BEGIN … on the first line. A self-signed certificate can be used, but this is not recommended for a production installation.

Important: When creating the personal certificate that will be presented to the client, which is IBM AD Connect for Mainframe in this case, on behalf of IBM AD Validation Server, set the Common Name field equal to the numeric IP address of the Windows machine where the IBM AD Validation Server is running. Do not use the host name.
You can create and manage digital certificates and their related key pairs in many ways. If you use OpenSSL, see the following command example:
```
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
```
Provide a copy of the CA certificate that is generated in the preceding step to the person who configures IBM AD Connect for Mainframe.
Ensure that you preserve the selected format when the CA certificate is generated. In the preceding example, the format is CERTB64. The CERTB64 format creates a DER encoded X.509 certificate that is in the Base64 format.
During the TLS handshake process, the copy of the CA certificate will be used by IBM AD Connect for Mainframe to authenticate the personal certificate that is presented on behalf of IBM AD Validation Server.
Configure the EZLCONN1.ini file in the <IBM AD Installation Folder>\bin\release\IBMApplicationDiscoveryValidationServer folder.
This EZLCONN1.ini file follows the common INI file syntax. To enable TLS connection between IBM AD Validation Server and IBM AD Connect for Mainframe, the cert, key, and keyform parameters must be specified in this file.

cert=cert.pem

Specifies the file name of the CA certificate or the self-signed certificate that is obtained in step 2.

key=key.pem

keyform=pem|der

Specify the private key to the client certificate and the format of the key, which can be either PEM or DER.

Example

After setting the values of the cert, key, and keyform parameters, the EZLCONN1.ini file contains enough information to allow IBM AD Validation Server to connect with IBM AD Connect for Mainframe by using the TLS protocol. All the parameters must go under the OpenSSL section. The parameter syntax, wording, and default values closely match those for the s_client OpenSSL tool. For more information about the s_client OpenSSL tool and the supported parameters, go to https://www.openssl.org/docs/man1.1.1/man1/openssl-s_client.html. For more information about INI files, go to https://en.wikipedia.org/wiki/INI_file.

What to do next

To enable TLS connection between IBM AD Validation Server and IBM AD Connection for Mainframe after you complete the setup for IBM AD Validation Server, the configurations for IBM AD Connect for Mainframe must also be completed. For instructions, see Enabling TLS Connection to IBM AD Validation Server.