Zone 2 and 3 SSL Configuration

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

After you configure SSL on Control-M/Server, you must configure SSL on Control-M/EM and all of the Agents that are connected to this Control-M/Server. Control-M/EM, Control-M/Server, and all Agents must use certificates that are signed by the same root Certificate Authority (CA).

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 PCKS #12 Keystore

• Configuring SSL in Zone 2 and 3

• Enabling SSL in Zone 2 and 3

• Enabling SSL on Specific 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 Agents

• Modifying SSL Configuration between an Agent and Agentless Hosts

• Verifying Certificates Authentication Levels in Zone 2 and 3

• Changing Keystore Passwords

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 (a standard openssl configuration file) in the [dn] section, do the following:

   1. Change the value of the following fields to the required values:

      • C = <Your_Country>

      • ST = <Your_State>

      • L = <Your_Locality>

      • O = <Your_Organization>

      • OU = <Your_Organizational_Unit>

      • CN = <Control-M_Component_Fully_Qualified_Domain_Name_(FQDN)>

      • emailAddress = <Your_Email_Address>

      The first time you run the ctmkeytool -create_csr script, it automatically updates the :FQDN: and :ShortHostName: placeholders with your host FQDN and hostname in your csr_params.cfg file, which enables the generated signed certificate to support HTTPS connections.

   2. If you have any other requirements from the certificate, you can include them in this file.

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

   • Control-M/EM: <EM Home>/bin/ctmkeytool -create_csr -password <Private_Key_Password>

   • Control-M/Server: <Server Home>/scripts/ctmkeytool -create_csr -password <Private_Key_Password>

   • Control-M/Agent: <Agent Home>/exe/ctmkeytool -create_csr -password <Private_Key_Password>

   • (UNIX only) In Control-M/EM, you must run this script in the Control-M/EM shell, such as em tcsh. For more information, see ctmkeytool.

   • You can generate the private key using an elliptic curve algorithm. The provider_options attribute in the component security policy must be updated to include only ciphers that use an elliptic curve algorithm for server certificate authentication. For more information, see Create CSR Option.

   • The CSR is generated at one of the following locations:

     • UNIX: $HOME/ctm_server/data/SSL/certificate_requests/<hostname>_YYYYMMDD_HHMMSS.csr

     • Windows: <Control-M/Server Install Path>\data\SSL\certificate_requests\<hostname>_YYYYMMDD_HHMMSS.csr

   • The private key, which is used to create a PCKS #12 keystore, is generated at one of the following location:

     • UNIX: $HOME/ctm_server/data/SSL/private_keys/<hostname>_YYYYMMDD_HHMMSS.pem

     • Windows: <Control-M/Server Install Path>\data\SSL\private_keys\<hostname>_YYYYMMDD_HHMMSS.pem

4. 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 specifies that these certificates are ASCII encoded X.509 certificates.

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

Generating the PCKS #12 Keystore

This procedure describes how to generate the PCKS #12 certificate keystore.

Begin

• Run the following command to create the PCKS #12 keystore file:

  <Control-M_Component_OpenSSL_Directory> pkcs12 -in <certificate pem filename> -inkey <private key filename> -export -passout pass:<new keystore password> -passin pass:<private key password> -CAfile <certificate chain pem file name|certificate authority pem filename> [-chain] -out <PCKS #12_Keystore_Filename>

  where the Control-M_Component_OpenSSL_Directory is as follows:

  • UNIX:

    • Control-M/EM: <Control-M_EM_Home>/bin/openssl

    • Control-M/Server: <Control-M/Server_Home>/exe_Linux-x86_64/openssl

    • Agent: <Agent_Home>/exe/openssl

  • Windows: 

    • Control-M/EM: <Control-M_EM_Home>\bin\openssl

    • Control-M/Server: <Control-M/Server_Home>\exe\openssl

    • Agent: <Agent_Home>\exe\openssl

  • 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 filename.

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

    • (UNIX only) You must run this script in 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 your z/OS operating system is lower than version 3.1 and PTF for IBM APAR OA65002 is installed, RACF does not support encryption algorithms AES-256 or above and you must append the following string to the PCKS #12 keystore creation 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 Agents.

Before You Begin

• If you did not receive a private key, signed certificate, root CA certificate, and chain in PEM format or the PCKS #12 keystore from your Security Administrator, you must generate it, as described in Generating the PCKS #12 Keystore.

• 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:

   • Control-M/EM: <EM Home>/bin/ctmkeytool -keystore <PCKS #12_Keystore_File_Pathname The fully specified name of a computer file, including the position of the file in the file system directory structure.> -password <Keystore_Password> -passwkey <Password_Encryption_Key_File_Pathname>

   • Control-M/Server: <Server Home>/scripts/ctmkeytool -keystore <PCKS #12_Keystore_File_Pathname> -password <Keystore_Password> -passwkey <Password_Encryption_Key_File_Pathname>

   • Control-M/Agent: <Agent Home>/exe/ctmkeytool -keystore <PCKS #12_Keystore_File_Pathname> -password <Keystore_Password> -passwkey <Password_Encryption_Key_File_Pathname>

   • (UNIX only) In Control-M/EM, you must run this script in 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 SSL configuration in the environment. The encryption key file must be a 32-byte-or-larger binary A compiled program file that enables Control-M or other software to run, such as an executable file, shared library, and Control-M-supplied utility that is located in the Control-M installation directories. or a 32-character-or-more text file. Control-M/Agent does not parse the -passwkey parameter. The Agent use its own Local.key. To change it, use the ctmagcpk utility.

   You can 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

   The Control-M/EM and Control-M/Server installations create unique, randomly-generated ess_key.txt key files.

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

3. Do one of the following:

   • To load the keystore and enable SSL, see Enabling SSL in Zone 2 and 3.

   • To only load the keystore, restart the following:

     • CMS

     • All Gateways connected to the Control-M/Servers configured with SSL.

     • EM-CTM Request service.

     • EM-MFT Updates service.

     • Control-M/Server

     • Control-M/Server Configuration Agent.

     • Control-M/Agent

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 Agents are now configured with SSL.

      If you want to enable SSL in a Control-M Unified View environment, run the following command:

      ctm_unified_view_update -sync_ssl

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

2. Enable SSL on each Agent by doing the following:

   1. Restart the Agent if you deployed a new certificate.

   2. From the CCM, right-click the required 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 on the primary Control-M/EM.

   3. On the primary Control-M/EM server and the distributed Control-M/EM servers, recycle the following:

      • Gateways that are connected to the Control-M/Servers where SSL is configured

      • EM-CTM Request Service and EM-MFT Updates Service components

Enabling SSL on Specific Agents

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

Begin

1. From the CCM, right-click the required 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 hosts:

   <EM Home>/bin/openssl ciphers -V TLSv1.2

   The ciphers that appear on both hosts 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 the Agent that the opensslciphers2java.txt file includes the cipher name with the mapping of openssl to java ciphers names by running the following command:

   • Control-M/Server: <Server Home>/exe/openssl ciphers -stdname | grep <cipher name>

   • Control-M/Agent: <Agent Home>/exe/openssl

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) You must run this script in 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 Agents are up.

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

5. Run the following commands to test the connection between Control-M/Server and the Agent:

   • 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 CMS on the primary Control-M/EM.

3. Recycle all Gateways on all Control-M/EM servers in the environment.

Disabling SSL on Control-M/Server

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

Begin

1. From the Control-M/Server host, 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 Agents that were configured with SSL, if the Secure Sockets Layer field was set to Default for the Agent in the CCM.

   If you want to disable SSL in a Control-M Unified View environment, run the following command:

   ctm_unified_view_update -sync_ssl

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

Disabling SSL on Agents

This procedure describes how to disable SSL on 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 Agent.

Modifying SSL Configuration between an Agent and Agentless Hosts

This procedure describes how to modify the SSL configuration between an Agent and its associated 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 with the openssl utility:

   • serverAuth

   • clientAuth

   • SSL Client

   • SSL Server

   • TLS Web Server Authentication

   • TLS Web Client Authentication

Changing Keystore Passwords

This procedure describes how to change the keystore passwords for Agents that utilize the PKCS #12 keystore.

Begin

1. Run the following command:

   <AG_JAVA_HOME>/bin/keytool -storepasswd -keystore "<keystore file name>" -storepass <password> -new <new password>

2. Run the following command to encode the <new password> into the local Agent password repository:

   ctmpwd -ACTION UPDATE -USER "*SSL_KEYSTORE" -PASSWORD "<new password>" -VERIFY N