ctmkeytool

The ctmkeytool utility enables you to perform the following functions:

Creating a Private Key and Certificate Signing Request: Generate a private key (PEM) file and certificate signing request (CSR) file.
Deploying the PKCS #12 Keystore File and Certificate: Deploy a PKCS #12 keystore file with the certificate. This deployment updates the relevant SSL configuration on the host.
Testing the Control-M/EM SSL Connection to a Specific Control-M/Server: Test the Control-M/EM connection to a specific Control-M/Server.
Uninstalling the Current SSL Certificate: Uninstall the current SSL certificate and revert to the previous SSL certificate and configuration.

You cannot run ctmkeytool on Control-M/Agent for IBM i (AS/400).
(UNIX only) On Control-M/EM, you must run ctmkeytool in the Control-M/EM shell, such as em tcsh.

ctmkeytool Directory Locations

The ctmkeytool script exists in three separate locations, according to the required Control-M component, as follows:

UNIX:
- Control-M/EM: <Control-M/EM_Home>/bin/
- Control-M/Server: <Control-M/Server_Home>/scripts/
- Control-M/Agent: <Agent_Home>/exe/
Windows:
- Control-M/EM: <Control-M/EM_Home>\bin\
- Control-M/Server: <Control-M/Server_Home>\scripts\
- Control-M/Agent: <Agent_Home>\exe\

You must run ctmkeytool with its pathname The fully specified name of a computer file, including the position of the file in the file system directory structure..

Creating a Private Key and Certificate Signing Request

This procedure describes how to create a private key file and certificate signing request (CSR) file, according to the csr_params.cfg configuration file that is located in the <Product Home Directory>/data/SSL/config directory. The csr_params.cfg file is a standard OpenSSL configuration file. If you have any requirements for the certificate you can include them in this file. For more information, see https://www.openssl.org.

Before You Begin

Verify that you have the correct permissions to create and update the required directories.
Update the csr_params.cfg configuration file in Zones 1 and 2, as described in the following procedures:
- Zone 1: Generating a Signed Certificate
- Zone 2: Generating a Signed Certificate

Begin

Do one of the following to create the private key and CSR files, according to the required filename:
- Accept Default Filenames: Run the following command:
  - UNIX: <ctmkeytool_Directory>/ctmkeytool -create_csr -password <Private_Key_Password>
  - Windows: <ctmkeytool_Directory>\ctmkeytool.bat -create_csr -password <Private_Key_Password>
  where the <ctmkeytool_Directory> defines the ctmkeytool script directory location for the relevant Control-M component, as described in ctmkeytool Directory Locations.
  
  The script creates the files with filenames that contain the CN field that is recorded in the csr_params.cfg configuration file and creation-time timestamps. They are saved in the following directories:
- Define Filenames: Run the following command to define the same filename for the private key and CSR file:
  - UNIX: <ctmkeytool_Directory>/ctmkeytool -create_csr -password <Private_Key_Password> -out <Filename>
  - Windows: <ctmkeytool_Directory>\ctmkeytool.bat -create_csr -password <Private_Key_Password> -out <Filename>
  /home/smartool/ctm_em/bin/ctmkeytool -create_csr -password ChangeThisPassword -out 2026_SSL_Key

The private key (extension .pem) and CSR (extension .csr) files are saved in the following directories:

CSR File
- UNIX: <Control-M_Component_Home>/data/SSL/certificate_requests directory
- Windows: <Control-M_Component_Home>\Data\SSL\certificate_requests directory
Private Key File
- UNIX: <Control-M_Component_Home>/data/SSL/private_keys
- Windows: <Control-M_Component_Home>\data\SSL\private_keys

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.
To reference a different csr_params.cfg configuration file, run the script with the -conf_file flag, as follows:
- UNIX: <ctmkeytool_Directory>/ctmkeytool -create_csr -password <private key password> -conf_file <Product_Home_Directory>/config_files/csr_config_file.cfg
- Windows: <ctmkeytool_Directory>\ctmkeytool.bat -create_csr -password <private key password> -conf_file <Product_Home_Directory>\config_files\csr_config_file.cfg
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 one of the following commands:
- Control-M/EM: <Control-M/EM_Home>/bin/openssl ecparam -list_curves
- Control-M/Server: <Control-M/Server_Home>/exe/openssl ecparam -list_curves
- Control-M/Agent: <Agent_Home>/exe/openssl ecparam -list_curves
The default curve is P-256.

Deploying the PKCS #12 Keystore File and Certificate

This procedure describes how to deploy a PKCS #12 keystore file with its certificate, which updates the SSL configuration on the required host.

Begin

Run one of the following commands to update the required Control-M component:
- UNIX:
  - Control-M/EM: <Control-M/EM_Home>/bin/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_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_Pathname>
  - Control-M/Server: <Control-M/Server_Home>/scripts/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_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_Pathname>
  - Control-M/Agent: <Agent_Home>/exe/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_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_Pathname>
- Windows:
  - Control-M/EM: <Control-M/EM_Home>\bin\ctmkeytool.bat -keystore <p12_Keystore_File_with_Its_Full_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_Pathname>
  - Control-M/Server: <Control-M/Server_Home>\scripts\ctmkeytool.bat -keystore <p12_Keystore_File_with_Its_Full_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_Pathname>
  - Control-M/Agent: <Agent_Home>\exe\ctmkeytool.bat -keystore <p12_Keystore_File_with_Its_Full_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_Pathname>
Recycle the relevant components, as follows:
- 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
- Agent: The Agent that you updated

Testing the Control-M/EM SSL Connection to a Specific Control-M/Server

This procedure describes how to test the Control-M/EM SSL connection to a specific Control-M/Server and get a detailed status report.

Begin

Run the following command:
- UNIX: <Control-M/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>
- Windows: <Control-M/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 output that appears includes the following details:
- SSL configuration enablement status.
- Connection status between the selected Gateway and Control-M/Server. If the connection is not OK, you are prompted for further testing.
- Control-M/Server ports that the Gateway and CMS connect to.
- Filename that holds the keystore that the Control-M/EM Gateways and CMS use.
- SSL protocols that the Control-M/EM Gateways and CMS use.
- SSL level that the Control-M/EM Gateways and CMS use.

Uninstalling the Current SSL Certificate

This procedure describes how to uninstall the current SSL certificate and revert to the previous SSL certificate and configuration that the Control-M component used before the current keystore was deployed. You can only revert to the immediately previous configuration. Older configurations cannot be retrieved.

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

Begin

Run one of following commands to update the required Control-M component:
- UNIX: <ctmkeytool_Directory>/ctmkeytool -uninstall
- Windows: <ctmkeytool_Directory>\ctmkeytool.bat -uninstall
where the <ctmkeytool_Directory> defines the ctmkeytool script directory location for the relevant Control-M component, as described in ctmkeytool Directory Locations.
Recycle the relevant components, as follows:
- 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
- Agent: The Agent that you configured