Manage_SSL_BYO

The Manage_SSL_BYO utility enables you to copy your own signed, organization-managed, SSL/TLS certificate that supports Control-M security level 4 from a source to a target host (which contains the new installation) to replace the less secure, BMC-provided, automatically generated self-signed SSL certificate that only supports Control-M security level 2. However, this method is not secure.

BMC recommends that you instead replace your certificates with the ctmkeytool utility, as described in Zone 2 and 3 SSL Configuration.

Manage_SSL_BYO supports the following Control-M components:

Control-M/EM server
Control-M/Server
Control-M for z/OS
Control-M/Agent

Before You Begin

Verify that you have one of the following for the component where SSL configuration is deployed:
- A private key, password, and an unlocked and non-password protected certificate, trusted root CA certificate, and certificate chain—all in PEM format.
- A PKCS #12 keystore 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.. If the keystore contains multiple certificates and key pairs, then you must also have the keystore password and required pair name.
Verify that the same root CA has signed the certificates on all components.
(Control-M/EM only) The target and source component versions must match.

Begin

Log in to the source host on the required component, create a temporary directory for the copied files, and grant the directory read, write, and execute permissions.
Run the following command to see the utility usage and determine which parameters are required:

Manage_SSL_BYO

The Manage_SSL_BYO usage appears.
Run the Manage_SSL_BYO utility with the required command-line arguments and verify that the -output option argument value is the temporary directory pathname The fully specified name of a computer file, including the position of the file in the file system directory structure..

In the following command, Temp_Keystore_Directory is defined as the SSL deployment directory:

"C:\Program Files\BMC Software\Control-M EM\Default\etc\site\manageSSL\bin\Manage_SSL_BYO.bat" -input pkcs12 -component CONTROL-M_Server -output C:\Users\smartool\Documents\Temp_Keystore_Directory -output_keystores_password abcd1234 -file
Copy the entire temporary directory to the target host.
Stop the target host component.
Do one of the following:
- (Control-M/EM 9.0.21 or higher) Open the README.TXT file in the temporary directory and follow the instructions to run the setup script, which installs the generated certificates on the target host component.
- (Control-M/EM 9.0.20.200 or lower and Control-M/Server or Agent 9.0.21 or higher) Open the README.TXT file in the following directory follow the instructions to run the setup script, which installs the generated certificates on the target host component:
  - UNIX: <Control-M_Component_Home_Directory>/data/SSL/manage
  - Windows: <Control-M_Component_Home_Directory>\data\SSL\manage

Generating Self-Signed Certificates

This procedure describes how to generate self-signed certificates for Control-M/EM, Control-M/Server, and Control-M/Agent and replace the pre-installed certificates.

Self-signed SSL certificates are generated by servers, and are not validated by a recognized trusted CA. Therefore, it is not recommended.
Control-M Mobile does not work with self-signed SSL certificates.
The version of Control-M/EM listed in the CCM must be the same version of Control-M/EM that you want to generate certificates for in this procedure.
Control-M/Server and Agent can be any supported version.

Begin

In the CCM, select the required Control-M/EM component.
Select System Parameters and then select Manage SSL.
Define SSL parameters, as described in Configuring Control-M/EM System Parameters.
From the Security tab, click Manage SSL.
Do one of the following:
- If you want to use the BMC-provided demo certificate, select Use the following site certificate authority, and do the following:
  1. The parameter fields in the first screen are populated with values supplied by BMC. Click Next.
  2. Select one of the following:
    - All Control-M Components: Generates certificates for all components.
    - By Component Type, and then select the component from the drop-down list.
    You can also enter a Unique Component Instance ID (Email) for all components of this type or for each instance of this component. This option is not available for the Control-M/EM server component.
  3. Define the generated keystore password, which must be at least eight characters.
  4. Accept the default location to save the generated certificates, or type in a new path.
  5. Click Next to generate the certificates.
  6. Click Submit.
    
    The new certificate deployment directories are created in the location you requested in the CCM client machine.
- If you want to create a new and unique instance of the pre-installed site Certificate Authority, select Create new Certificate Authority for the site, and do the following:
  1. Click Yes to accept generating a new certificate.
    
    You are informed that certificates will be generated for all the Control-M components.
  1. Enter the Country Name, Common Name (fully qualified domain name—FQDN), Email Address and other optional CA parameters, and click Next.
  2. Define the generated keystore password, which must be at least eight characters.
  1. Accept the default location to save the generated certificates, or type in a new path.
  2. Click Next to generate the certificates.
  3. Click Submit.
    
    The new certificate deployment directories are created in the location you requested in the CCM client machine.
Copy the directory Certificate_for_<Component_Name> to a temporary directory on the host where the component is installed.

<tempLocation>
Stop the component.
In the temporary directory, open the README.TXT file to learn how to run the setup script, which installs the generated certificates on the component.

If your version of Control-M/EM is lower than 9.0.21 and the destination component (Control-M/Server or Agent) is version 9.0.21 or higher, ignore the README.TXT file in the package. Instead, follow the instructions in the README.TXT file in the <Component_Home_Directory>/data/SSL/manage directory.
Start the relevant component.

After you upgrade to 9.0.22 or higher, a new CA is used when you run Manage SSL. Therefore, you must generate and deploy certificates for all components.

Certificate Copies for Control-M for z/OS

For Control-M for Z/OS you need to pass the directory content to your z/OS Control-M administrator.

The following table describes the keystore files for z/OS that are generated by running Manage SSL from CCM.

Keystore File	Details
IOAGATE.p12	Export the certificate for Control-M for z/OS with the key-pair to be used by IOAGATE in PKCS #12 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. format. The password for the PKCS #12 file is displayed in the summary window that is generated when running the Generate Component Certificates wizard.
CA.pem	Export the certificate of the Site CA that signed the certificate in PEM format when CLIAUTH=YES (which uses client authentication) is defined in IOAGATE.

Keystore File

Details

IOAGATE.p12

Export the certificate for Control-M for z/OS with the key-pair to be used by IOAGATE in PKCS #12 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. format. The password for the PKCS #12 file is displayed in the summary window that is generated when running the Generate Component Certificates wizard.

CA.pem

Export the certificate of the Site CA that signed the certificate in PEM format when CLIAUTH=YES (which uses client authentication) is defined in IOAGATE.

For more information about how to use these files, see the SSL Support.

Restoring a BMC Self-Signed Certificate

This procedure describes how to restore a BMC self-signed certificate from a backup for Control-M/EM server.

The setup scripts save a backup of the certificate state prior to the deployment in a separate directory.

Begin

From the Control-M/EM home directory, run one of the following commands:
- UNIX: <Product Home Directory>/ssl_setup/ssl_certificate_backup_<timestamp>/setup.sh <clients-em|em-ctm>
- Windows: <Product Home Directory>\ssl_setup\ssl_certificate_backup_<timestamp>\setup.bat <clients-em|em-ctm>