ctmkeytool

The ctmkeytool utility enables you to perform the following functions:

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

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, Password, and Password Encryption Key

This procedure describes how to deploy a PKCS #12 keystoreClosed A Public-Key Cryptography Standards (PKCS) #12 keystore is a password-protected, encrypted file that contains a private key, its matching SSL/TLS certificate, and optionally a certificate chain of intermediate and root Certificate Authority (CA) certificates. Control-M components use this keystore to authenticate each other and encrypt the data that they exchange over SSL/TLS, which protects workload data in transit and makes sure that each component connects only to trusted components. file with a certificate, password, and password encryption key that the relevant Zone 2 or Zone 3 component uses in its security policy. You can encrypt the password on the required Control-M component as follows:

  • Control-M/EM and Control-M/Server: Via the -passwkey argument and password encryption key file that you determine.

  • Control-M/Agent: Via the ctmpwd utility, which employs the local.key file in the <Agent_Home>/data/keys directory.

Begin

  1. Run one of the following commands to update the required Control-M component:

  2. Recycle the relevant components, as follows:

    • Control-M/EM: CMS, the relevant Gateways, the EM-CTM Request Service, and the EM-MFT Updates service

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

    • Agent: The Agent that you updated

Viewing the Security Level

This procedure describes how to view the SSL security level of a Control-M component. Security levels control the degree of authentication that is required for TLS connections between Control-M components, as described in Security Levels.

Begin

  • View the Security Level: Run the following command:

    • UNIX: <ctmkeytool_Directory>/ctmkeytool -sec_level -display -all | -policy services | -policy <Policy_Name> -role <all|client|server>

    • Windows: <ctmkeytool_Directory>\ctmkeytool.bat -sec_level -display -all | -policy services | -policy <Policy_Name> -role <all|client|server>

    where the <ctmkeytool_Directory> defines the ctmkeytool script directory location for the relevant Control-M component, as described in ctmkeytool Directory Locations. For more information, see Security Level Parameters.

    The security levels for the defined security policies on the relevant Control-M component appear.

Configuring the Security Level

This procedure describes how to configure the SSL security level of a Control-M component. Security levels control the degree of authentication that is required for TLS connections between Control-M components, as described in Security Levels.

Begin

  1. Run the following command:

    • UNIX: <ctmkeytool_Directory>/ctmkeytool -sec_level -set <1|2|3|4> -all | -policy services | -policy <Policy Name> -role <all|client|server> [-ks_pass <Keystore_Password>]

    • Windows: <ctmkeytool_Directory>\ctmkeytool.bat -sec_level -set <1|2|3|4> -all | -policy services | -policy <Policy Name> -role <all|client|server> [-ks_pass <Keystore_Password>]

    where the <ctmkeytool_Directory> defines the ctmkeytool script directory location for the relevant Control-M component, as described in ctmkeytool Directory Locations. For more information, see Security Level Parameters.

  2. Recycle the relevant components, as follows:

    • Control-M/EM: CMS, the relevant Gateways, the EM-CTM Request Service, and the EM-MFT Updates service

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

    • Agent: The Agent that you configured

Security Level Parameters

The following table describes the security level parameters for the ctmkeytool script.

Parameter

Description

-set

Configures the security level, as follows:

  • 1: Encryption only

  • 2: Encryption and presence of valid certificate on the server (with no server authentication)

  • 3: Server authentication

  • 4: Client and server authentication

For more information, see Security Levels.

-all

Applies the user-defined security level to all Control-M component policies.

-policy services

(Control-M/EM and Control-M/Server only) Applies the user-defined security level only to the HTTPS traffic between Control-M/EM services and the API Gateway on Control-M/Server.

The ignoreCertificateTrustVerify in the <Control-M_Component_Home>/services/config/https_client_server.properties file is set to true or false, according to the security level that you define, as follows:

  • true: Level 1 or 2

  • false: Level 3 or 4

-policy

Applies the user-defined security level to one of the following security policies, according to the component:

  • Control-M/EM:

    • cmsg: Control-M/EM CMS Gateway

    • gtw: Control-M/EM Gateway

    • site: Applies the security policies that are defined in the site.plc file (UNIX) or the site section in the Windows registry.

  • Control-M/Server:

    • ca

    • co

    • ns

    • site: Applies the security policies that are defined in the site.plc file (UNIX) or the site section in the Windows registry.

  • Agent:

    • ag

    • ru

    • ruj

    • site: Applies the security policies that are defined in the site.plc file (UNIX) or the site section in the Windows registry.

For more information, see the policy type descriptions that are relevant to your component host operating system, as follows:

-role

Applies the user-defined security level and security policy that is defined with the -policy flag to one of the following roles:

  • all

  • client

  • server

-ks_pass

Verifies that the certificate in the deployed keystore includes the SSL client attribute that is required for mutual (client and server) authentication.

You must include this argument when you configure the security level to 4 with the -set parameter.

-display

Shows the security level for the matching policies.

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.

Deploying a New Self-Signed Certificate

This procedure describes how to deploy a new self-signed certificate.

  • BMC recommends you bring your own certificate, except for proof of concept or demonstration purposes, as described in Bringing Your Own Certificate.

  • If a keystore file was not defined in the Control-M component installation wizard, a self-signed certificate is automatically deployed.

Begin

  1. (Optional) Do the following to define the self-signed certificate attributes.

    1. Navigate to the following directory:

      • UNIX: <Control-M_Component_Home>/data/SSL/config/self_signed.cfg

      • Windows: <Control-M_Component_Home>\data/SSL\config\self_signed.cfg

    2. Open the self_signed.cfg file in a text editor and define one or more self-signed attributes, as described in Self-Signed Certificate File Attributes.

      The self_signed.cfg file that comes installed with Control-M usually only includes the keyalg, keysize, sigalg, and validity attributes. The remaining attributes use the default values described in Self-Signed Certificate File Attributes.

      Copy 
      keyalg=RSA
      keysize=3072
      sigalg=SHA256withRSA
      validity=7300
      ca_alias=rootca
      cert_alias=mycert
      key_protection=PBEWithHmacSHA256AndAES_256
      cert_protection=PBEWithHmacSHA256AndAES_256
      password=ChangeMe1

  2. Run the following command:

    • UNIX: <ctmkeytool_Directory>/ctmkeytool -deploy_self_signed [-password <Password>]

    • Windows: <ctmkeytool_Directory>\ctmkeytool.bat -deploy_self_signed [-password <Password>]

    Where:

    • <ctmkeytool_Directory>: Defines the ctmkeytool script directory location for the relevant Control-M component, as described in ctmkeytool Directory Locations.

    • (Optional) -password <Password>: Defines the self-signed certificate password.

Self-Signed Certificate File Attributes

The following table describes the attributes that you can define in the self_signed.cfg file when you deploy a new self-signed certificate, as described in Deploying a New Self-Signed Certificate.

Attribute

Description

keyalg

Determines one of the following key algorithms that ctmkeytool uses to generate the root CA and component public/private key pairs:

  • RSA

  • EC

Default: RSA

keyalg=RSA

keysize

Defines the size (in bits) of the generated public/private key pair, according to the defined key algorithm in the keyalg attribute, as follows:

  • RSA:

    • 3072

    • 4096

  • EC:

    • 256

    • 384

    • 521

Default: 3072

keysize=3072

sigalg

Determines the signature algorithm that ctmkeytool uses to sign the certificate and generate the key pairs, according to the defined key algorithm in the keyalg attribute.

  • RSA:

    • sigalg=SHA256withRSA

    • sigalg=SHA384withRSA

    • sigalg=SHA512withRSA

  • EC:

    • sigalg=SHA256withECDSA

    • sigalg=SHA384withECDSA

    • sigalg=SHA512withECDSA

validity

Determines the number of days that the self-signed certificate is valid.

Default: 7300

validity=7300

ca_alias

Defines the alias that is used to identify the root CA certificate entry.

Default: rootca

ca_alias=rootca

cert_alias

Defines the alias that is used to identify the component public-private key pair that is created in the keystore.

cert_alias=mycert

key_protection

Defines the PKCS #12 private-key protection algorithm that is used to convert the keystore to a PKCS #12 file.

Default: PBEWithHmacSHA256AndAES_256

key_protection=PBEWithHmacSHA256AndAES_256

cert_protection

Defines the PKCS #12 certificate protection algorithm that is used to convert the keystore to a PKCS #12 file.

Default: PBEWithHmacSHA256AndAES_256

cert_protection=PBEWithHmacSHA256AndAES_256

password

Defines the keystore password that is used when the -password option is not defined in the command line command.

password=ChangeMe1

You can also define the password from the command line.

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

  1. Run one of the 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.

  2. Recycle the relevant components, as follows:

    • Control-M/EM: CMS, the relevant Gateways, the EM-CTM Request Service, and the EM-MFT Updates service

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

    • Agent: The Agent that you configured