ctmkeytool

The ctmkeytool script performs the following functions:

Generates a private key (PEM) file and certificate signing request (CSR) file, as described in Create CSR Option.
Deploys a .p12 keystore file with the certificate. This deployment updates the relevant SSL configuration on the host, as described in Deployment Option.
(On Control-M/EM) Tests the connection against a specific Control-M/Server, as described in Status Option.

The ctmkeytool script is located in the following directories, and must be run with its pathname The fully specified name of a computer file, including the position of the file in the file system directory structure.:

Control-M/EM: /bin/
Control-M/Server: <Control-M/Server Home Directory>/scripts/
Control-M/Agent: <Agent Home Directory>/exe/

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

Create CSR Option

The ctmkeytool script creates a private key file and certificate signing request file, based on the configuration file csr_params.cfg that located in the <Product Home Directory>/data/SSL/config directory. You must verify that the user who runs this script has the correct permissions to create and update the required 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 you run the script, you must update the csr_params.cfg file in Zone 1 and 2, as described in the following procedures:

Zone 1: Generating a Signed Certificate
Zone 2: Generating a Signed Certificate

You can run the ctmkeytool -create_csr option as follows:

Control-M/EM: /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>

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.

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

Private Key File: The generated private key file default name contains the CN field from the configuration file and a timestamp that indicates when it was generated. The file extension is .pem and the file is located in the following directory:

<Product Home Directory>/data/SSL/private_keys
Certificate Signing Request File: The certificate signing request default name contains the CN field from the configuration file and a timestamp that indicates when it was generated. The file extension is .csr and the file is located in one of the following directories:
- UNIX: <Product Home Directory>/data/SSL/certificate_requests directory
- Windows: <Product Home Directory>\Data\SSL\certificate_requests directory

You can define 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 and 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: /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

You must run the ctmkeytool -keystore option with the pathname The fully specified name of a computer file, including the position of the file in the file system directory structure. to update the required Control-M component, as follows:

Control-M/EM: /bin/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_Pathname> -password <keystore_Password> -passwkey <Password Encryption_Key_Pathname>
Control-M/Server: <Server Home>/scripts/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_Pathname> -password <keystore_Password> -passwkey <Password Encryption_Key_Pathname>
Control-M/Agent: <Agent Home>/exe/ctmkeytool -keystore <p12_Keystore_File_with_Its_Full_Pathname> -password <keystore_Password> -passwkey <Password Encryption_Key_Pathname>

The file specified by the -passwkey parameter is an encryption key, which is used to encrypt the keystore password in the SSL configuration on 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. The Agent uses its own local.key. To change this key, use the ctmagcpk utility.

You can use the ess_key.txt file in the following locations:

Control-M/EM: /etc/site/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.

You can use the following key file on the Agent in the following location:

UNIX: <Agent_Home>/data/keys/local.key
Windows: <Agent_Home>\DATA\keys\local.key

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.

You can run the ctmkeytool -status option 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 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.

Uninstall Option

The ctmkeytool -uninstall option enables you to revert to the last SSL certificate and configuration that the product 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.

You can run the ctmkeytool -uninstall option 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.