ctmkeytool

The ctmkeytool script can perform the following functions:

  • Generating a private key (*.pem) file and certificate signing request (*.csr) file using the Create CSR Option.

  • Deploying a p12 keystore file including the certificate. This deployment updates the relevant SSL configuration on the computer, as described in Deployment Option.

  • On Control-M/EM, testing the connection against a specific Control-M/Server using the Status Option.

The ctmkeytool script is located in the following directories and must be used with its full path:

  • Control-M/EM: <EM Home Directory>/bin/

  • Control-M/Server: <Control-M/Server Home Directory>/scripts/

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

  • The script must executed with the full pathname.

  • The script is not available for Control-M/Agent on IBM i (AS/400).

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

Create CSR Option

The ctmkeytool script creates the private key file and the certificate signing request file, using the configuration file csr_params.cfg located in <Product Home Directory>/data/SSL/config directory. Verify that the user running the script has the correct permissions to create and update the directories.

The csr_params.cfg file is a standard openssl configuration file. If you have any requirements from the certificate, you can include them in this file. For more information, see https://www.openssl.org.

Before running the script, update the csr_params.cfg file, as described in Generating a Signed Certificate for zone 1 and Generating a Signed Certificate for zone 2.

The script usage is, as follows:

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

This command creates the private key file and the certificate signing request file:

The default name for the generated private key file consists of the CN field in the configuration file, and the timestamp of the file generation. The suffix of the private key file is .pem. The file is located in the <Product Home Directory>/data/SSL/private_keys directory.

The default name of the generated certificate signing request file consists of the CN field in the configuration file, and the timestamp of the file generation. The suffix of the certificate signing request file is .csr. The file is located in one of the following locations:

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

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

You can specify a different configuration filename with the -conf_file flag.

<ctmkeytool_Directory>/ctmkeytool -create_csr -password <private key password> -conf_file <Product_Home_Directory>/config_files/csr_config_file.cfg

To specify a different name for the created private key file and certificate signing request file, use the -out flag.

<ctmkeytool_Directory>/ctmkeytool -create_csr -password <Private_Key_Password> -out <Filename>

The provided name is used for both the *.pem file and the *.csr file.

To use a certificate authentication elliptic curve cipher, generate a private key using an elliptic curve cipher, by adding -algorithm ec. There are two valid values for the algorithm name, rsa and ec. If -algorithm is not defined, the RSA algorithm is used.

You can also define -ec_curve <curve name>. Valid values for a curve name are all NIST convention names, and the curve names appear when you run the command one or more of the following commands:

  • Control-M/EM: <EM HOME directory>/bin/openssl ecparam -list_curves

  • Control-M/Server: <Server HOME directory >/exe/openssl ecparam -list_curves

  • Control-M/Agent: <Agent HOME directory >/exe/openssl ecparam -list_curves

The default curve is P-256.

Deployment Option

The ctmkeytool script usage with the deployment option is as follows:

  • Control-M/EM: <EM Home>/bin/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_Pathname> -password <keystore_Password> -passwkey <Password Encryption_Key_Filename_and_Pathname>

  • Control-M/Server: <Server Home>/scripts/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_Pathname> -password <keystore_Password> -passwkey <Password Encryption_Key_Filename_and_Pathname>

  • Control-M/Agent: <Agent Home>/exe/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_Pathname> -password <keystore_Password> -passwkey <Password Encryption_Key_Filename_and_Pathname>

This updates the SSL configuration for the relevant Control-M component.

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

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

  • Control-M/EM: <EM Home Directory>/etc/site/resource/ssl/cert/ess_key.txt

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

After you run the script, you must restart the following relevant components:

  • Control-M/EM: Control-M/EM Configuration Agent, CMS, and the relevant Gateways.

  • Control-M/Server: Control-M/Server and the Control-M/Server Configuration Agent.

  • Control-M/Agent: Specific Agents.

Status Option

The ctmkeytool status option tests and receives details about the SSL environment on Control-M/EM and its SSL connection to a specific Control-M/Server. The script usage is as follows:

<EM_Home_Directory>/bin/ctmkeytool -status -host <Control-M/Server_Name_as_It_Appears_in_CCM> -keystore_pass <Local_keystore_Password_on_Control-M/EM> -key_pass <Private_Key_Password_in_the_keystore>

The displayed output includes the following details:

  • SSL configuration enablement status.

  • The status of the connection between the selected Gateway and Control-M/Server. If the connection is not OK, you are prompted for further testing.

  • The ports on Control-M/Server that the Gateway and CMS connects to.

  • The name of the file holding the keystore used by Control-M/EM Gateways and CMS.

  • SSL protocols used by Control-M/EM Gateways and CMS.

  • SSL level used by Control-M/EM Gateways and CMS.

Uninstall Option

The ctmkeytool -uninstall option is used to revert to the last SSL certificate and configuration used by the product before the current keystore was deployed. You can only revert to the previous configuration. Any configuration prior cannot be retrieved.

You can retrieve the previous configuration on Control-M/EM, Control-M/Server, and the Agent.

The ctmkeytool -uninstall option script usage is as follows:

<ctmkeytool directory>/ctmkeytool -uninstall

After you run the script, you must restart the following relevant components:

  • Control-M/EM: Control-M/EM Configuration Agent, CMS, and the relevant Gateways.

  • Control-M/Server: Control-M/Server and Control-M/Server Configuration Agent.

  • Control-M/Agent: Specific Agents.