Configure TLS Between the Connector Gateway and Mainframe

To enable TLS communication between the Connector Gateway and Mainframe, the Connector Gateway must validate the CN of the subject of certificate against the value provided in the agentCertSubject parameter in the init.xml file. The agentCertSubject parameter must only be set by using the following command:

java -jar ConnectorGateway.jar -agentCertSubject <VALUE>

For example:

java -jar ConnectorGateway.jar -agentCertSubject CertSubject

By running the above command, the Connector Gateway encrypts the value and stores it in the init.xml file under the SM tag as follows:

<agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>

Note
The value of agentCertSubject parameter must not be set directly in the init.xml file, it must be set only by using the above command.

If agentCertSubject is not specified then the Connector Gateway validates the CN of the certificate subject against the FQDN of the machine hosting the Mainframe Connector.

Perform the following steps to enable TLS between the Connector Gateway and the Mainframe Connector

  1. Set up AT-TLS on the computer where the Mainframe Connector is installed. The truststore must be exported from the Mainframe Connector and imported into the Connector Gateway.

  2. Use the following command to set the enableCGtoAgentTLS parameter to true and set the truststore path:

    java -jar ConnectorGateway.jar -enableCGtoAgentTLS "true" -trustStore "truststorePath"

    where trustStore is the full path of truststore.

    Note
    All the components the Connector Gateway, CCG, and the Mainframe Connector must be restarted after modifying the configurations.

Configure Mutual TLS Authentication Between the Connector Gateway and Mainframe

After you enable and configure TLS authentication, you can configure mutual TLS authentication on the Connector Gateway and Mainframe hosts.

Mutual TLS enables the Connector Gateway to validate the authenticity of Mainframe at the same time that Mainframe validates the Connector Gateway itself.

To enable mutual TLS authentication between Mainframe and the Connector Gateway:

  1. In the init.xml file, set the enableCGTLSAuth parameter to true and provide supporting authentication credentials:

    Important
    Don't set the keyStorePassCGTLSAuth and keyPassCGTLSAuth parameter values directly in the init.xml file. They must be set only by using the method in this step.

    java -jar ConnectorGateway.jar – enableCGTLSAuth "true" - keyStoreCGTLSAuth

    "keystorePath" –keyStorePassCGTLSAuth "keystorePassword" –keyPassCGTLSAuth “keyPassword"

    Consider the following for these commands:

    Variables

    Description

    enableCGTLSAuth

    Only used if enableCGtoAgentTLS is set to true.

    When this is set to true, Mainframe validates the authenticity of the Connector Gateway. This is set to false by default.

    keyStoreCGTLSAuth

    This is a file location where a keytool utility generated keystore.jks file can be found. Typically this is in the Connector Gateway host. This keystore.jks file is used by Mainframe to authenticate the Connector Gateway.

    keyStorePassCGTLSAuth

    The keystore.jks file is protected with a keystorePassword. The password grants access to the keystore.jks file upon successful mutual TLS authentication.

    keyPassCGTLSAuth

    This private/secret keyPassword is a fallback authentication method used if the configured keystore password fails, and the keytool needs to recover the keys.

    Note
    The keystorePassword and keyPassword values are encrypted by the Connector Gateway while updating the init.xml file.

  2. Copy or transfer the certificate from the Connector Gateway host to the Mainframe dataset and add it as a trusted certificate.

  3. Set the HandshakeRole ServerWithClientAuth and ClientAuthType Required values in the Mainframe AT-TLS policy.

    For more information on these values, refer to Implementing AT-TLS Policy for Mainframe Connector Communication.