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

About this task

For IBM ADDI V5.1.0.7 and earlier versions, the communication between IBM® ADDI Validation Server and IBM ADDI 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 ADDI 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 ADDI Validation Server, set the Common Name field equal to the numeric IP address of the Windows machine where the IBM ADDI 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 ADDI 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 ADDI Connect for Mainframe to authenticate the personal certificate that is presented on behalf of IBM ADDI Validation Server.
Copy [ConnectionName].ini from <IBM AD Build Client installation folder>\Bin\Release\Samples\AdConnectEncryptConnection\ in the <IBM AD Build Client installation folder>\Bin\Release\IBMApplicationDiscoveryValidationServer folder. Then, rename [ConnectionName].ini to EZLCONN1.ini file.
This EZLCONN1.ini file follows the common INI file syntax. To enable TLS connection between IBM ADDI Validation Server and IBM ADDI 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 ADDI Validation Server to connect with IBM ADDI 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 ADDI Validation Server and IBM ADDI Connect for Mainframe after you complete the setup for IBM ADDI Validation Server, the configurations for IBM ADDI Connect for Mainframe must also be completed. For instructions, see Enabling TLS Connection to IBM ADDI Validation Service.