Zone 2 and 3 SSL Configuration

Zone 2 allows you to configure SSL between Control-M/EM server and Control-M/Server. Zone 3 allows you to configure SSL between Control-M/Server and Control-M/Agent.

After SSL is configured on the Control-M/Server, Control-M/EM and all Control-M/Agents that are connected to this Control-M/Server must also be configured with SSL. Control-M/EM, Control-M/Server and all Control-M/Agents must use certificates that are signed by the same root Certificate Authority.

The following procedures describe how to configure SSL in zone 2 and 3 using the supported protocol TLS1.2:

• Generating a Signed Certificate

• Generating the .p12 Keystore

• Configuring SSL in Zone 2 and 3

• Enabling SSL in Zone 2 and 3

• Enabling SSL on Specific Control-M/Agents

• Configuring Protocols and Ciphers for Zones 2 and 3

• Testing SSL on Zones 2 and 3

• Disabling SSL on Control-M/EM

• Disabling SSL on Control-M/Server

• Disabling SSL on Control-M/Agents

• Modifying SSL Configuration between Control-M/Agent and Agentless Hosts

• Verifying Certificates Authentication Levels in Zone 2 and 3

Generating a Signed Certificate

This procedure describes how to generate the signed certificate for your Control-M component.

Begin

1. Navigate to one of the following directories:

   • UNIX: <Product Home Directory>/data/SSL/config directory

   • Windows: <Product Home Directory>\Data\SSL\config directory

2. In the csr_params.cfg file, in the [dn] section, change the value of the following fields to the required values:

   • C = example_country

   • ST = example_state

   • L = example_locality

   • O = example_organization

   • OU = example_unit

   • CN = example.example.com (the Control-M component fully qualified domain name—FQDN).

   • emailAddress = admin@example.com

   The csr_params.cfg file is a standard openssl configuration file. If you have any other requirements from the certificate, you can include them in this file.

3. Ensure that the certificate suffices, by doing the following:

   1. Add the following lines to the file:

      [ req_ext ]

      keyUsage = digitalSignature, keyEncipherment

      extendedKeyUsage = serverAuth, clientAuth

   2. In the [ req ] section, add the following line:

      req_extensions = req_ext

   For more information, see https://www.openssl.org.

4. Create the private key and certificate signing request file by running the following:

   <ctmkeytool directory>/ctmkeytool -create_csr -password <private key password>

   • (UNIX only) If you are running this script on Control-M/EM, ensure that you run this script using the Control-M/EM shell, such as em tcsh. For more information, see ctmkeytool.

5. Use the Certificate Signing Request (CSR) file to obtain the certificate file and the certificate chain file with a .pem extension, from a recognized CA. PEM format specify that these certificates are ASCII encoded X.509 certificates.

   Common suffixes for PEM files are .pem, .crt, .cer, .or ca-bundle.

Generating the .p12 Keystore

This procedure describes how to generate the .p12 certificate keystore.

Begin

• Create the .p12 keystore file by running the following command:

  openssl pkcs12 -in <certificate pem file name> -inkey <private key file name> -export -passout pass:<new keystore password> -passin pass:<private key password> -CAfile <certificate chain pem file name|certificate authority pem file name> [-chain] -out <keystore p12 name> -keypbe pbeWithSHA1And3-KeyTripleDES-CBC -certpbe pbeWithSHA1And3-KeyTripleDES-CBC

  • If the CA is trusted using a certificate chain, then the -chain flag must be specified, and the -CAfile flag must point to the certificate chain .pem file. Otherwise, the -chain flag must not be specified, and the -CAfile flag must point to the root certificate authority .pem file name.

  • If you are running this command on Control-M/EM, note the following:

    • (UNIX only) Ensure that you run this command using the Control-M/EM shell, such as em tcsh.

    • If you used 3DES algorithm for the encryption of the private key password, or SHA-1 algorithm was used as the digest algorithm for the certificate, you must add -legacy at the end of this command.

  • If you run this command on Control-M/Server or Control-M/Agent with Java 11, you must add the following at the end of the command:

    -keypbe pbeWithSHA1And3-KeyTripleDES-CBC -certpbe pbeWithSHA1And3-KeyTripleDES-CBC

Configuring SSL in Zone 2 and 3

This procedure describes how to configure SSL on Control-M/Server, Control-M/EM server, and Control-M/Agents.

Before You Begin

• If you did not receive a private key, signed certificate, root CA certificate and chain in PEM format or the .p12 keystore from your Security Administrator, you need generate it, as described in Generating a Signed Certificate .

• Verify that the certificates have the required authentication level, as described in Verifying Certificates Authentication Levels in Zone 2 and 3.

• To use your keystore for HTTPS traffic for the API-GTW, verify the following by running the ctmkeytool.

  • It contains a SubjectAlternativeName with a value that fit the hostname of the component.

  • It contains an Entry type of the trustedCertEntry type.

Begin

1. Deploy SSL configuration on each component:

   <ctmkeytool location>/ctmkeytool -keystore <p12 keystore file with its full path> -password <keystore password> -passwkey <name of file containing the password encryption key, with its full path>

   • (UNIX only) If you are running this script on Control-M/EM, ensure that you run this script using the Control-M/EM shell, such as em tcsh.

   • For more information, see ctmkeytool.

   The file that uses the -passwkey parameter is an encryption key, which is used to encrypt the keystore password in the environment’s SSL configuration. Both binary and textual files can be used for this purpose. Control-M/Agent does not parse the -passwkey parameter. Agent use its own Local.key. To change it, use the ctmagcpk utility.

   It is possible to use the ess_key.txt file in the following locations:

   Control-M/EM:

   • UNIX: /<EM_HOME>/etc/site/resource/ssl/cert/ess_key.txt

   • Windows: <EM_HOME>\etc\resource\ssl\cert\ess_key.txt

   Control-M/Server: <CTM Home Directory>/data/SSL/cert/ess_key.txt

2. Update the supported protocols and ciphers in your environment, as described in Configuring Protocols and Ciphers for Zones 2 and 3.

Enabling SSL in Zone 2 and 3

This procedure describes how to enable SSL in zone 2 and 3.

Begin

1. Enable SSL on Control-M/Server by doing the following:

   1. Run the ctmsys utility.

   2. Press 2 - System Parameters.

   3. Press n to move to the next page of parameters.

   4. Set option 9 Secure Sockets Layer to ENABLED.

      By default, all connected Control-M/Agents are now configured with SSL.

   5. Restart the Control-M/Server Configuration Agent and the Control-M/Server component.

2. Enable SSL on each Control-M/Agent by doing the following:

   1. Restart the Control-M/Agent if you deployed a new certificate.

   2. From the CCM, right-click the required Control-M/Agent and select Properties and then click the Communication.

   3. From the Secure Socket Layer drop-down list, select Default.

      This inherits the value from the Control-M/Server configuration.

   4. Click Test.

   5. After the test has validated the settings, click OK.

3. Enable SSL on the CMS and Gateway components by doing the following:

   1. From the CCM, change the value of the CmsCommMode system parameter to AUTO or to SSL, as described in SSL Communication Parameters.

   2. Recycle the CMS.

   3. Recycle the Gateway(s) that are connected to the Control-M/Servers where SSL is configured.

   4. Recycle the EM-CTM Request Service and EM-MFT Updates Service components.

Enabling SSL on Specific Control-M/Agents

This procedure describes how to enable SSL on specific Control-M/Agents when Control-M/Server is not enabled with SSL.

Begin

1. From the CCM, right-click the required Control-M/Agent and select Properties and then click the Communication.

2. From the Secure Socket Layer drop-down list, select Default.

3. Click Test.

4. After the test has validated the settings, click OK.

Configuring Protocols and Ciphers for Zones 2 and 3

This procedure describes how to configure SSL connections for zones 2 and 3 to work with the TLSv1.2 protocol and ciphers.

For each SSL connection, the same protocols and ciphers must be configured on both components that acts as the client and server for the connection.

To use more than one cipher, use a space to separate them.

Begin

1. For each connection, run the following command on both the client and server computers:

   openssl ciphers -V TLSv1.2

   The ciphers that appear on both computers can be used for the connection.

2. Do one of the following:

   • UNIX: Edit the relevant policy file, as described UNIX Environment.

   • Windows: Edit the relevant registry hive, as described in Windows Environment.

3. Edit the provider_options field, as follows:

   provider_options=SSLProtocol=TLS1_2,TLSCipherSuite= <List of ciphers>

   The names of the ciphers are exactly as they appear in the available cipher list above.

4. Verify in Control-M/Server and Control-M/Agent that the opensslciphers2java.txt file includes the cipher name with the mapping of openssl to java ciphers names by running the following command:

   openssl ciphers -stdname | grep <cipher name>

5. Restart the relevant component.

   provider_options=SSLProtocol=TLS1_2,TLSCipherSuite=DHE-RSA-AES256-SHA AES256-SHA DHE-RSA-AES128-SHA

Testing SSL on Zones 2 and 3

This procedure describes how to test SSL on zones 2 and 3.

Begin

1. Test the SSL configuration between Control-M/EM and Control-M/Server by running the following command on Control-M/EM:

   <ctmkeytool location>/ctmkeytool -status -host <Control-M/Server name as displayed in CCM> -keystore_pass <password of the local keystore on EM> -key_pass <password of the private key in the keystore>

   • (UNIX only) Ensure that you run this script using the Control-M/EM shell, such as em tcsh.

   • For more information, see ctmkeytool.

2. Verify that all operations between Control-M/EM and Control-M/Server, such as job ordering, are working.

3. From the CCM, verify that all Control-M/Servers and Control-M/Agents are Up.

4. Verify that the status of all Gateways that are configured to work with SSL appear as Connected (SSL).

5. Test the connection between Control-M/Server and Control-M/Agent by running the following commands:

   • ag_diag_comm

   • ctm_diag_comm

Disabling SSL on Control-M/EM

This procedure describes how to disable SSL on Control-M/EM in zone 2 and 3.

Begin

1. From the CCM, change the value of the CmsCommMode system parameter to TCP.

2. Restart the Control-M/EM Configuration Agent, and CMS.

3. Recycle all Gateways.

Disabling SSL on Control-M/Server

This procedure describes how to disable SSL on the Control-M/Server and the connected Control-M/Agents, using the Control-M/Server ctmsys utility.

Begin

1. From the Control-M/Server computer, run ctmsys.

2. Select option 2 System Parameters.

3. Press n to move to the next page of parameters.

4. Set option 9 Secure Sockets Layer to DISABLE.

   This also turns off SSL on all connected Control-M/Agents that were configured with SSL, if the Secure Sockets Layer field was set to Default for the Control-M/Agent in the CCM.

5. Restart the Control-M/Server Configuration Agent and the Control-M/Server component.

Disabling SSL on Control-M/Agents

This procedure describes how to disable SSL on Control-M/Agents that are not connected to a Control-M/Server.

Begin

1. Edit the CONFIG.dat file that is located under <Agent home directory>/ctm/data.

2. Change the value of COMMOPT to SSL=N.

3. Save the file and restart the Control-M/Agent.

Modifying SSL Configuration between Control-M/Agent and Agentless Hosts

This procedure describes how to modify the SSL configuration between Control-M/Agent and Agentless Hosts to enable utilities to run on Agentless hosts.

The following message is an example that appears in the job output on failure:

Begin

1. Do one of the following:

   • Windows: Navigate to the following path in the Registry Editor:

     HKEY_LOCAL_MACHINE\SOFTWARE\BMC Software\Control-M/Agent <instance>\SecurityPolicy\RU\server

   • UNIX: Navigate to the following file:

     <Control-M/Agent Home Directory>/ctm/data/SSL/cert/ru.plc

2. In the [server] section, edit the provider_options parameter with SSL protocols and ciphers, if needed.

   SSLProtocol=TLS1_2,TLSCipherSuite=DHE-RSA-AES256-SHA AES256-SHA DES-CBC3-SHA DHE-RSA-AES128-SHA AES128-SHA EDH-RSA-DES-CBC-SHA DHE-RSA-AES256-SHA AES256-SHA

3. From the RU key, create or edit the client key.

4. Add or edit the following parameters in the client key:

   • ssl_protocol: (TLSv1.2)

   • cipher_suite: You can use the following ciphers:

     TLS_RSA_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_DHE_RSA_WITH_DES_CBC_SHA SSL_DHE_RSA_WITH_AES_256_CBC_SHA SSL_RSA_WITH_AES_256_CBC_SHA SSL_DHE_RSA_WITH_AES_128_CBC_SHA SSL_RSA_WITH_AES_128_CBC_SHA TLS_EMPTY_RENEGOTIATION_INFO_SCSV

   [server]

   identity=AGDN

   logfile=rusrv.log

   security_level=3

   provider_options=SSLProtocol=TLS1_2CipherSuite=DHE-RSA-AES256-SHA AES256-SHA DES-CBC3-SHA DHE-RSA-AES128-SHA AES128-SHA EDH-RSA-DES-CBC-SHA DHE-RSA-AES256-SHA AES256-SHA

   [client]

   ssl_protocol=TLSv1.2

   cipher_suite=TLS_RSA_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_DHE_RSA_WITH_DES_CBC_SHA SSL_DHE_RSA_WITH_AES_256_CBC_SHA SSL_RSA_WITH_AES_256_CBC_SHA SSL_DHE_RSA_WITH_AES_128_CBC_SHA SSL_RSA_WITH_AES_128_CBC_SHA TLS_EMPTY_RENEGOTIATION_INFO_SCSV

Verifying Certificates Authentication Levels in Zone 2 and 3

This procedure describes how to verify the authentication level of a certificate and compare it to the security policy in the specific Control-M component in zone 2 and 3.

Begin

1. Verify the Zone 2 and 3 authentication level configuration by verifying the security_level property in the security policy as described in Security Policies:

2. In the certificate attributes, such as Key Usage and Extended Key Usage, check for the following values using openssl:

   • serverAuth

   • clientAuth

   • SSL Client

   • SSL Server

   • TLS Web Server Authentication

   • TLS Web Client Authentication

     • Check a CSR: openssl req -text -noout -verify -in CSR.csr.

     • Check a certificate: openssl x509 -in certificate.pem -text -noout -purpose.

     • Check a PKCS#12 file: openssl pkcs12 -info -in keyStore.p12.

   • • If you are running this command on Control-M/EM, note the following:

       • (UNIX only) Ensure that you run this command using the Control-M/EM shell, such as em tcsh.

       • If you used 3DES algorithm for the encryption of the private key password, or SHA-1 algorithm was used as the digest algorithm for the certificate, you must add -legacy at the end of this command.

     • If you run this command on Control-M/Server or Agent with Java 11, you must add the following at the end of the command:

       -keypbe pbeWithSHA1And3-KeyTripleDES-CBC -certpbe pbeWithSHA1And3-KeyTripleDES-CBC