Zone 1 SSL Configuration

Zone 1 SSL configuration allows you to configure SSL between Control-M Web Server and Control-M client applications.

The following procedures describe how to configure SSL in zone 1.

• Generating a Signed Certificate

• Generating the tomcat.p12 Keystore

• Configuring SSL on Control-M Web Server

• Managing Secure Connectors

• Testing SSL on the Control-M Web Server

• Configuring Ciphers for the Control-M Web Server

• Reverting Back to an Old Connector

• Adding Root CA Certificates to the .p12 Keystore

Generating a Signed Certificate

This procedure describes how to generate a signed certificate.

Begin

1. Navigate to one of the following directories:

   • UNIX: <EM Home Directory>/data/SSL/config directory

   • Windows: <EM Home Directory>\Data\SSL\config directory

2. In the csr_params.cfg.file, in the [dn] section, change the value of the following fields to the required values:

   • C = ex

   • ST = example_state

   • L = example_locality

   • O = example_organization

   • OU = example_unit

   • CN = example.example.com (FQDN of the Control-M/EM server)
     To enable you to specify both the shortname and the FQDN of the Control-M/EM Server, this field supports the asterisk wildcard, as in CN = example*.

   • emailAddress = admin@example.com

     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. In addition, for browser compatibility, it is recommended to add the following section to the file:

     [ req_ext ]

     keyUsage = digitalSignature, keyEncipherment

     subjectAltName = DNS:<Web Server FQDN>

     And on [ req ] section, after distinguished_name = dn, add the following line:

     req_extensions = req_ext

     For more information, see https://www.openssl.org.

     If you want the certificate that is generated by the CA using the generated csr file to support several DNS names, in the subjectAltName attribute value, you can define all DNS names that must be supported, separated by commas, in the following format:

     subjectAltName = DNS:<DNS name 1>, DNS:<DNS name 2>, DNS:<DNS name 3>

3. Create the private key and certificate signing request file by running the following:

   <ctmkeytool location>/ctmkeytool -create_csr -password <private key password>

   • (UNIX only) Ensure that you run this script using the Control-M/EM shell, such as em tcsh.

   • For more information, see ctmkeytool.

4. Use the Certificate Signing Request (CSR) file to obtain the certificate file and the certificate chain file with a .pem extension, from an external recognized CA. PEM format specify that these certificates are ASCII encoded X.509 certificates.

   Common suffixes for PEM files are .pem, .crt, .cer, .or ca-bundle.

Generating the tomcat.p12 Keystore

This procedure describes how to generate the tomcat.p12 certificate keystore.

Begin

1. Back up the existing tomcat.p12 keystore file in the <EM Home Directory>/ini/ssl directory.

2. Create the tomcat.p12 keystore file by running the following command:

   openssl pkcs12 -in <certificate pem file name> -inkey <private key file name> -export -passout pass:<new tomcat.p12 keystore password> -passin pass:<private key password> -CAfile <certificate chain pem file name> -chain -out tomcat.p12 -name <keystore friendly name> -caname <ca friendly name>

3. Save the tomcat.p12 file in the <EM Home Directory>/ini/ssl directory.

4. Verify that the Web Server certificate is installed on Control-M client computers.

   If the certificate is not installed, copy the tomcat.p12 keystore file that contains the certificate to the Control-M client computer and run the certificate installation.

Updating the tomcat.p12 Password

This procedure describes how to update/change the tomcat.p12 password in the Web Server configuration. You need to perform this procedure every time you create a new tomcat.p12 keystore or change its password.

Begin

1. Update the tomcat.p12 keystore password in the <EM Home Directory>/ini/ssl/tomcat.ini file by running the following command:

   emcryptocli <new tomcat.p12 keystore password> <EM Home Directory>/ini/ssl/tomcat.ini

2. Type the following command:

   manage_webserver

3. Update the keystore password, as follows:

   1. Press 1 to display the Tomcat configuration.

   2. Press 3 to display Secure Connector Configuration.

   3. Press 3 to edit the SSL connector.

   4. Select the connector to edit.

   5. Press 9 to update the keystore password.

Configuring SSL on Control-M Web Server

This procedure describes how to configure and enable SSL between Control-M client applications and the Control-M Web Server with the tomcat.p12.keystore. This SSL configuration occurs in zone 1.

Before You Begin

• If you did not receive a private key, signed certificate, root CA certificate and chain in PEM format or the tomcat.p12 keystore from your Security Administrator, you need generate the certificate and the tomcat.p12 keystore, as described inGenerating a Signed Certificate and Generating the tomcat.p12 Keystore .

• Verify that the certificates have the required authentication level, as described in Verifying Certificates Authentication Levels in Zone 1.

Begin

1. Type the following command:

   manage_webserver

2. Turn on SSL mode, by doing the following:

   1. Press 1 to display the Tomcat configuration.

   2. Press 4 to display SSL mode.

   3. Set the current configuration for using SSL to [true].

3. Run the following command:

   stop_web_server

4. Recycle the GUI Server and the CMS.

5. Verify that the Web Server certificate is installed on the Control-M client computer.

   If the certificate is not installed, copy the p12 keystore file that contains the certificate to the Control-M client computer and run the certificate installation.

Removing the Non-secured Connectors from the Web Server

This procedure describes how to remove the non-secured port between Control-M client applications and the Control-M Web Server. BMC recommends to remove the non-secured ports.

Begin

1. Type the following command:

   manage_webserver

2. Press 1 to display the Tomcat configuration.

3. Press 2 to display Connector Configuration.

4. Delete a connector, as follows:

   1. Press 4.

   2. Choose the connector you want to delete from the list.

5. Repeat the above step for all configured non-secured connectors.

Managing Secure Connectors

This procedure describes how to add, change, or delete secure connectors. By default, the installation includes a secure (HTTPS) and non-secure (HTTP) connector. If you want to add, change, or delete, use this procedure.

Begin

1. Type the following command:

   manage_webserver

2. Press 1 to display the Tomcat configuration.

3. Press 3 to display Secure Connector Configuration.

4. Do one of the following:

   • To add a new connector, do the following:

     1. Press 2.

     2. Provide the name of the keystore this connector will use.

   • To update a connector, do the following:

     1. Press 3.

     2. Choose the connector that you want to edit from the list.

     3. Choose a parameter that you want to edit and update its value.

   • To delete a connector, do the following:

     1. Press 4.

     2. Choose the connector you want to delete from the list.

Testing SSL on the Control-M Web Server

This procedure describes how to test the HTTPS connector on the Control-M Web Server.

Begin

1. Verify the hostname and port which are used by the relevant connector, by doing the following:

   1. Type the following command:

      manage_webserver

   2. Press 1 to display the Tomcat configuration.

   3. Press 3 to display the secure connector configuration.

   4. Press 1 to display the list of secure connectors.

2. Log in to the CCM, select Web server URLs and then click Web Server.

3. From the web browser on the Control-M client computer, type the URL as follows:

   https://<web server’s fqdn>:<web server’s port>

   The Control-M Welcome Page appears.

Configuring Ciphers for the Control-M Web Server

This procedure describes how to configure ciphers for the Control-M Web Server in zone 1. The Control-M Web Server supports by default the TLSv1.2 SSL protocol. Refer to the manage_webserver utility to allow lower protocol values. The available ciphers for Zone 1 are defined in <EM Home Directory>/ini/ssl_tomcat_ciphers.xml. If you want to use a cipher that is not listed in the file or limit the listed ciphers perform this procedure.

Begin

1. Add the new ciphers to the <EM Home Directory>/ini/ssl_tomcat_ciphers.xml file.

2. Add the ciphers to the relevant secured connector, as follows:

   1. Type the following command:

      manage_webserver

   2. Press 1 to display the Tomcat configuration.

   3. Press 3 to display Secure Connector Configuration.

   4. Press 3 to edit the SSL Connector.

   5. Select the connector you want to edit.

3. Copy the list of existing ciphers to an external file and add or remove ciphers as required, as they appear in the <EM Home Directory>/ini/ssl_tomcat_ciphers.xml file.

4. Select 1 and insert the new list of ciphers.

5. From the CCM, recycle the Control-M Web Server.

Reverting Back to an Old Connector

This procedure describes how to revert back to an old connector if you deleted it.

Begin

1. Do one of the following:

   • To replace the server.xml file if the delete or update action was the last action in the manage_webserver utility, do the following:

     1. Navigate to the following directory:

        UNIX: <EM_HOME>/etc/emweb/tomcat/conf/

        Windows: <EM_HOME>\emweb\tomcat\conf

     2. Delete the server.xml file.

     3. Rename the server_lastfile.xml file to server.xml in the /backup directory.

   • To edit the server.xml file add the http connector:

     <Connector port="18080" protocol="HTTP/1.1"

     connectionTimeout="20000"

     redirectPort="8443" />

2. From the CCM, recycle the Web Server.

Adding Root CA Certificates to the .p12 Keystore

This procedure describes how to add root CA certificates to the .p12 keystore with minimal downtime. You need to perform this procedure if the root CA certificate or one of the certificates in the intermediate chain is about to expire.

Begin

1. Import the new root CA certificate (or chain of intermediate certificates) into the keystore used by the component.

2. From a command line type the following:

   keytool -v -importcert -trustcacerts -alias <new unique alias> -keystore <keystore file name> -storepass <keystore password> -storetype pkcs12 -file <added certificate file>

3. Verify that the new CA certificate was added to your truststore by typing the following:

   keytool -keystore <keystore file> -list

   The added certificate appears in the list.

4. Restart all components where you updated the keystore, and verify SSL connectivity.

5. Remove the old root CA or intermediate chain certificate from all updated keystores, by running the following command:

   keytool -delete -keystore <keystore file> -alias root_to_remove

6. Restart all components where you updated the keystore, and verify SSL connectivity.

Verifying Certificates Authentication Levels in Zone 1

This procedure describes how to verify the authentication level of a certificate and compare it to the security policy in the Web Server.

Begin

1. Verify the Zone 1 authentication level configuration for a specific HTTPS connector, as follows:

   1. Type the following command:

      manage_webserver

   2. Press 1 to display the Tomcat configuration.

   3. Press 3 to display Secure Connector Configuration.

   4. Press 3 to edit the SSL Connector.

   5. Select the connector you want to edit.

   6. Change the value of the 3. clientAuth property (if required).

      The default value for clientAuth is false.

2. In the certificate attributes, such as Key Usage and Extended Key Usage, check for the following values using openssl:

   • serverAuth

   • clientAuth

   • TLS Web Server Authentication

   • TLS Web Client Authentication

     • Check a CSR: openssl req -text -noout -verify -in CSR.csr.

     • Check a certificate: openssl x509 -in certificate.pem -text -noout.

     • Check a PKCS#12 file: openssl pkcs12 -info -in keyStore.p12.