Enabling TLS Connection between IBM AD Build Client and IBM AD Connect for Mainframe

About this task

For IBM® AD V5.1.0.4 and earlier versions, the communication between IBM AD Build and IBM AD Connect for Mainframe is unencrypted socket session. Beginning with version 5.1.0.5, 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.

The TLS protocol is a client or server cryptographic protocol. It is based on the earlier Secure Sockets Layer (SSL) specifications that are developed by Netscape Corporation for securing communications that use Transmission Control Protocol/Internet Protocol (TCP/IP) sockets. The TLS and SSL protocols are designed to run at the application level. Therefore, typically, an application must be designed and coded to use TLS/SSL protection. OpenSSL is an open source implementation of the SSL and TLS protocols. It is widely used on most Unix-like platforms and Microsoft Windows systems. OpenSSL supports the full suite of SSL and TLS protocols (SSL V2, SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2 as of this writing), including a robust set of application programming interfaces (APIs) and a wide range of cryptographic primitives.

IBM AD Build can establish a secure communication with the mainframe host by using the OpenSSL toolkit. OpenSSL provides a wide range of configuration settings to customize the connection. IBM AD Build Client supports some of these settings. You can specify the values in a .ini file that is located in the IBM AD Build Client installation folder.

On the host side, the communication is handled by using IBM AT-TLS services. Before you configure IBM AD Build to enable TLS connection, make sure to complete the AT-TLS setup for IBM AD Connect for Mainframe. For instructions, see Enabling TLS Connection to IBM AD Build.

Procedure

  1. Go to the zOS tab in IBM AD Build Configuration, and then create a z/OS connection with the Enable AT-TLS checkbox selected, or edit an existing connection to select this checkbox.
    This image shows the zOS Connection Setup dialog in IBM Application Discovery Build Configuration.
    For V5.1.0.6 and earlier versions, find the TLS file in the IBM AD Build Client bin\release folder, and then set the flag value to Y in the file. The full path is similar to C:\Program Files\IBM Application Discovery and Delivery Intelligence\IBM Application Discovery Build Client\Bin\release.
    The TLS file contains a single flag byte. The flag can take the value Y or N. It is not case-sensitive. Y indicates that TLS is enabled, while N indicates that TLS is not enabled. If this file is not present as a sample file, it can be created from the command line with command echo Y > TLS or echo N > TLS. There is no file extension on the TLS file name. The file must be saved in the IBM AD Build Client bin\release folder.
  2. As part of the AT-TLS configuration process on the mainframe, a personal certificate that represents the IBM AD Connect for Mainframe server is created. This personal certificate must be signed with a certification authority (CA) certificate or a self-signed certificate. Save a copy of this CA certificate or self-signed certificate in the IBM AD Build Client bin\release folder. The full path is similar to C:\Program Files\IBM Application Discovery and Delivery Intelligence\IBM Application Discovery Build Client\Bin\release.

    The file that contains this certificate can have any name, but it must be in the Privacy-Enhanced Mail (PEM) format. If IBM AD Build Client must connect with multiple servers that use different CA certificates or self-signed certificates, this file can optionally contain multiple PEM format certificates. Standard practice is to place only trusted CA certificates or self-signed certificates in this file, but not the personal certificate that represents the server. For more information about the PEM format, go to https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail.

    Ensure that the certificate file is downloaded from the mainframe in the correct format. The example in the IBM AD Connect for Mainframe Configuration Guide creates a DER encoded X.509 certificate that is in the Base64 format, so download this certificate in the ASCII mode if using FTP. An alternative to FTP is to cut and paste the certificate contents from the mainframe editor screen (ISPF) to a PC-based text editor, and then save the resulting file.

    Important: The personal certificate that is presented to IBM AD Build on behalf of the IBM AD Connect for Mainframe started task must have the Subject Name CN field equal to the numeric IP address of the z/OS mainframe instance where the task is running, for example, >CN=9.30.123.456.OU=IBM CA.C=US< instead of >CN=zos.server.name.com.OU=IBM CA.C=US<. Confirm this with the person who performs AT-TLS configurations on z/OS.
  3. Create a ConnectionName.ini file, where ConnectionName is the name of the z/OS connection that is defined in the zOS Connection Setup dialog in IBM AD Build Configuration.

    Save the file in the IBM AD Build Client bin\release folder. The full path is similar to <IBM AD Build Client installation folder>\Bin\Release. You can find a sample ConnectionName.ini file in the <IBM AD Build Client installation folder>\Bin\Release\Samples\AdConnectEncryptConnection\ folder.

    This .ini file follows the common INI file syntax. To enable TLS connection between IBM AD Build and IBM AD Connect for Mainframe, the CAfile parameter must be specified in the .ini file.
    CAfile=CA_CERT.pem
    Specifies the list of trusted certificates. CA_CERT.pem is the file name of the CA certificate or the self-signed certificate that is obtained in the previous step.
    An SSL or TLS connection uses certificates to verify the identity of the peer. During the SSL handshake, the server presents its personal certificate to the client. This certificate can be either self-signed or signed by a trusted third party such as a CA. For the SSL or TLS authentication to succeed, either the personal certificate or the CA signer certificate must be present on the trusted certificates list on the client side.

    Example

    This image shows an example of the INI file.
    After setting the value of the CAfile parameter, the .ini file contains enough information to allow IBM AD Build Client to connect with IBM AD Connect for Mainframe by using the TLS protocol. The following list shows optional TLS-specific parameters that can be defined in the INI file. All the following parameters and the CAfile parameter must go under the OpenSSL section. The parameter syntax, wording, and default values closely match those for the s_client OpenSSL tool.
    CAPath=C:\certs
    Specifies a directory that contains multiple certificates in the hash format. More complex certificate chains can be defined in this directory.
    verify=depth
    Specifies the maximum length of a server certification chain.
    cert=client_cert.pem
    Specifies the certificate that is sent from the client to the server. Some configurations might require a client to send its certificate to the server.
    certform=pem|der
    Specifies the format of the certificate that is sent from the client to the server. The format can be either base64-encoded PEM or binary DER.
    cert_chain=filename
    Specifies a file that contains a set of trusted certificates for building a certificate chain. The certificate chain must start with the certificate that is specified by the cert parameter. A client can provide not only a single certificate but a certificate chain.
    key=private_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.
    pass=pass:password|file:password.txt
    Specifies the password to use the private key. Private keys are usually password-protected. For an application to use the private key, you must provide a password. The password can be provided either in plain text or in a separate file. Either this INI file or the separate file must be protected by OS permissions to prevent unauthorized access.
    servername=example.com
    Specifies the expected server name. If the server is using the TLS SNI extension, the client can send the expected server name to the server. For more information about the TLS SNI extension, go to https://en.wikipedia.org/wiki/Server_Name_Indication.
    tls13=true
    tls12=true
    tls11=true
    tls1=true
    Specify the maximum level of the SSL or TLS protocol that the client is willing to use. The final decision on the protocol level will be determined by the server.
    bugs=true
    Enables several bug workarounds for some known bugs in SSL or TLS implementations.
    cipher=TLS_AES_256_GCM_SHA384
    ciphersuites=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
    Specify ciphers and cipher suites to be used during communication. Custom ciphers must be supported by both the client and the server. For more information about the options and ciphers list syntax, go to https://www.openssl.org/docs/man1.1.1/man1/ciphers.html.
    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.
  4. Restart both IBM AD Build Client and IBM AD Build Configuration. Both applications will pick up the connection configuration changes.
  5. Test the connection by clicking the Test Connection button in the zOS Connection Setup dialog in IBM AD Build Configuration.