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 using the supported protocol TLS 1.2.

• Generating a Signed Certificate

• Generating the tomcat.p12 Keystore

• Updating the tomcat.p12 Password

• Configuring SSL on the 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 * 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) 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 a 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.

   If the CA certificate signing your web server certificate, as described in {step} does not exist in the Trusted Root Certificate Authorities, see Installing the Root CA Certificate on the Control-M Client.

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. Back up the following files:

   • <EM Home>/ctm_em/ini/ssl/tomcat.p12

   • <EM Home>/ctm_em/ini/ssl/tomcat.ini

   • One of the following:

     • UNIX: <EM Home>/ctm_em/etc/emweb/tomcat/conf/server.xml

     • Windows: <EM Home>/ctm_em/emweb/tomcat/conf/server.xml

3. Type the following command:

   manage_webserver

4. 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.

5. Restart the Web Server.

Configuring SSL on the 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. Recycle the Web Server, GUI Server, and the CMS.

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.

6. Restart the Web Server.

Configuring SSL on Control-M Web Server with the Default Certificate

This procedure describes how to configure SSL between Control-M client applications and the Control-M Web Server using a the default certificate signed by BMC. This SSL configuration occurs in Zone 1. During Control-M/EM installation a CA certificate and a self-signed certificate that is signed by this CA certificate are generated for the Control-M Web server. These certificates and the generated private key and are saved in the tomcat.p12 keystore file, located in <EM_Home_Directory>/ini/ssl.

Begin

1. Type the following command:

   manage_webserver

2. Do the following:

   1. 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].

   2. Update the keystore password, as follows:

      1. Press 3 to display Secure Connector Configuration.

      2. Press 3 to edit the SSL Connector.

      3. Select the connector to edit.

      4. Press 9 to update the keystore password.

3. Restart the Web Server by typing the following commands:

   • stop_web_server

   • start_web_server

4. Recycle the GUI Server and the CMS.

   If the CA certificate signing your web server certificate, as described in {step}does not exist in the Trusted Root Certificate Authorities, see Installing the Root CA Certificate on the Control-M Client.

Installing the Root CA Certificate on the Control-M Client

This procedure describes how to install the root CA certificate, that signed your web server certificate, on the Control-M client computer.

1. Extract the root CA certificate from your tomcat.p12 keystore on the Control-M/EM machine where your web server runs, and type the following command:

   <EM home directory>/bin/ openssl pkcs12 -in <EM home directory>/ini/ssl/tomcat.p12 -cacerts -nokeys -password <tomcat.p12 password> > cacert.crt

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

2. Copy the created cacert.crt file to the Control-M client.

3. Double click the file to install the CA certificate.

   The Crypto Shell Extensions application opens, which shows the certificate details.

   If the Crypto Shell Extensions application does not open, configure windows to open .crt files using the Crypto Shell Extensions.

4. Install the CA certificate by clicking Install Certificate and continue with the Local Machine option and then place the certificate in the Trusted Root Certificate Authorities.

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.

5. Restart the Web Server.

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.