Zone 1 SSL Configuration

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

The following procedures describe how to configure SSL in Zone 1 with the supported TLS 1.2 protocol, and locally deploy certificates to Control-M/EM, Control-M/Servers, and Agents:

• Generating a Signed Certificate

• Generating the Secure Connector Keystore

• Updating the Secure Connector Keystore File and Password

• Configuring SSL on the Web Server

• Removing the Non-secured Connectors from the Web Server

• Configuring SSL on the Web Server with the Default Certificate

• Installing the Root CA Certificate on the Control-M Client

• Managing Secure Connectors

• Testing SSL on the Web Server

• Reverting to an Old Connector

• Adding Root CA Certificates to the .p12 Keystore

• Verifying Certificate Authentication Levels in Zone 1

• Reconfiguring Connections Between Control-M/EM Services and the Web Server

To remotely deploy certificates to Agents and automate SSL certificate updates, see Certificate Configuration.

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 (a standard openssl configuration file) in the [dn] section, do the following:

   1. Change the value of the following fields to the required values:

      • C = <Your_Country>

      • ST = <Your_State>

      • L = <Your_Locality>

      • O = <Your_Organization>

      • OU = <Your_Organizational_Unit>

      • CN = <Control-M/EM_Server_Fully_Qualified_Domain_Name_(FQDN)>

        This field supports the * wildcard, which enables you to define the Control-M/EM server short name and FQDN, such as CN = example*.

      • emailAddress = <Your_Email_Address>

      • The first time you run the ctmkeytool -create_csr script, it automatically updates the :FQDN: and :ShortHostName: placeholders in the [ alt_names] section of the csr_params.cfg file with your host FQDN and hostname, which enables the generated signed certificate to support HTTPS connections.

      • Alternatively, you can define one or more supported DNS names in the subjectAltName section of the signed certificate in one of the following ways:

        • subjectAltName = DNS:<Host_01>, DNS:<Host_02>, DNS:<Host_03>

        • subjectAltName = @alt_names

          [ alt_names ]

          DNS.1 = <Host_01>

          DNS.2 = <Host_02>

          DNS.3 = <Host_03>

   2. If you have any other certificate requirements, you can include them in this file.

3. Run the following command to create the private key and certificate signing request file:

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

   • (UNIX only) You must run this script in the Control-M/EM shell, such as em tcsh. For more information, see ctmkeytool.

   • You can generate the private key using an elliptic curve cryptography (ECC) algorithm. 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 specifies that these certificates are ASCII-encoded X.509 certificates.

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

Generating the Secure Connector Keystore

This procedure describes how to generate the secure connector An Apache Web Server secure connector is a configuration that enables encrypted and authenticated communication between the Apache HTTP Server and clients via SSL/TLS protocols. The secure connector usually uses a keystore, such as a .p12 file, that contains a private key and certificate, which enables the Web Server to establish secure HTTPS connections. keystore.

Begin

1. Back up the existing secure connector keystore file in one of the following directories:

   • UNIX: <EM Home Directory>/ini/ssl

   • Windows: <EM Home Directory>\ini\ssl

2. Create the secure connector keystore file by running the following command:

   <EM Home>/bin/openssl pkcs12 -in <Certificate_PEM_Filename> -inkey <Private_Key_Filename> -export -passout pass:<New_Secure_Connector_Keystore_Password> -passin pass:<Private_Key_Password> -CAfile <Certificate_Chain_PEM_Filename> -chain -out tomcat.p12 -name <Keystore_Friendly_Name> -caname <CA_Friendly_Name>

3. Save the secure connector keystore file in the <EM Home Directory>/ini/ssl directory.

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

   • (UNIX only) You must run this script in the Control-M/EM shell, such as em tcsh.

Updating the Secure Connector Keystore File and Password

This procedure describes how to update the secure connector keystore file (by default, tomcat.p12) and password in the Apache Tomcat Web Server configuration. You must perform this procedure every time you update the secure connector keystore file or change its password.

Begin

1. Back up the following files:

   • UNIX:

     • <EM Home>/ctm_em/ini/ssl/<Secure_Connector_Keystore_Filename_and_Extension>

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

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

   • Windows:

     • <EM Home>\ctm_em\ini\ssl\<Secure_Connector_Keystore_Filename_and_Extension>

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

     • <EM Home>\ctm_em\emweb\tomcat\conf\server.xml

2. Run the following command to configure the secure connector keystore file on the Web Server:

   manage_webserver

   The Tomcat Configuration Manager main menu appears.

3. Press 1 to navigate to the Tomcat Configuration menu.

   The Tomcat Configuration Manager sub-menu appears.

4. Press 3 to navigate to the Secure Connector Configuration menu.

   The Secure Connectors Configuration menu appears.

5. Press 3 to navigate to the Edit SSL Connector menu.

   The Select Secure Connector to Edit menu appears.

6. Press the required number to edit the secure connector.

   The Edit - <Secure_Connector_URL_and_Port_Number> menu appears.

7. Do one or more of the following:

   • Update the Secure Connector Keystore File: Do the following:

     1. Press the relevant number for the required secure connector.

        The Edit - <Secure_Connector_URL_and_Port_Number> menu appears.

     2. Press 7.

        A prompt appears that requests the new secure connector keystore filename.

     3. Type the new secure connector keystore filename.

        The file is changed in Control-M/EM and the Edit - <Secure_Connector_URL_and_Port_Number> menu reappears with the new secure connector keystore filename.

     4. If a different password is used in the new secure connector keystore file, you must also change the new secure connector keystore password, as described in the Update the Secure Connector Password option below.

   • Update the Secure Connector Keystore Password: Do the following:

     1. Press 8.

        A prompt appears that requests the new secure connector keystore password.

     2. Type the new secure connector keystore password.

        The password is changed in Control-M/EM and the Edit - <Secure_Connector_URL_and_Port_Number> menu reappears with the new secure connector keystore password.

8. Type s to save the changes.

   A confirmation prompt appears.

9. Type Y to confirm that you want to save the changes.

   The password is encrypted and the changes are saved to Control-M/EM.

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

    • UNIX: emcryptocli <New_Secure_Connector_Keystore_Password> <EM_Home>/ini/ssl/tomcat.ini

      (UNIX only) You must run this script in the Control-M/EM shell, such as em tcsh.

    • Windows: emcryptocli <New_Secure_Connector_Keystore_Password> <EM_Home>\ini\ssl\tomcat.ini

11. Recycle the Web Server, as described in Recycling a Control-M/EM Component.

Configuring SSL on the Web Server

This procedure describes how to configure and enable SSL between Control-M client applications and the Web Server with the secure connector 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 secure connector keystore from your Security Administrator, you must generate the certificate and the secure connector keystore, as described in Generating a Signed Certificate and Updating the Secure Connector Keystore File and Password.

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

• To find supported ciphers for your installation, see your Java vendor documentation for your JRE installed version. You can view details of your JRE version by running the following command:

  openssl ciphers -V

  If you want to use ciphers from the output of the openssl command for Zone 1, you need to convert their names to the Java convention names. For examples of cipher names, see the existing ciphers in <EM Home Directory>/ini/ssl_tomcat_ciphers.xml.

Begin

1. Run the following command:

   manage_webserver

   The Tomcat Configuration Manager main menu appears.

2. Type the Tomcat Configuration menu item number.

   The Tomcat Configuration Manager sub-menu appears.

3. Do the following to turn on SSL mode:

   1. Type the SSL Mode menu item number.

      The current configuration appears with a prompt that asks if you want to change it.

   2. Press Y to set the current SSL configuration to true.

4. Recycle the following components, as described in Recycling a Control-M/EM Component:

   • Web Server

   • GUI Server

   • 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 Web Server. BMC recommends that you remove the non-secured ports.

Begin

1. Run the following command:

   manage_webserver

   The Tomcat Configuration Manager main menu appears.

2. Type the Tomcat Configuration menu item number.

   The Tomcat Configuration Manager sub-menu appears.

3. Type the Non Secure Connectors Configuration menu item number.

   The Non Secure Connectors Configuration menu appears.

4. Do the following to remove a non-secured connector:

   1. Type the Delete Connector menu item number.

      The Select Connector To Delete menu appears.

   2. Type the required connector menu item number.

      A confirmation prompt appears.

   3. Press Y to confirm deletion.

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

6. Recycle the Web Server, as described in Recycling a Control-M/EM Component.

Configuring SSL on the Web Server with the Default Certificate

This procedure describes how to configure SSL between Control-M client applications and the Web Server using 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 Web Server. These certificates and the generated private key are saved in the secure connector keystore file that is located in the following directory:

<EM_Home_Directory>/ini/ssl

Begin

1. Run the following command:

   manage_webserver

   The Tomcat Configuration Manager main menu appears.

2. Type the Tomcat Configuration menu item number.

   The Tomcat Configuration Manager sub-menu appears.

3. Do the following to turn on SSL mode:

   1. Type the SSL Mode menu item number.

      The current configuration appears with a prompt that asks if you want to change it.

   2. Press Y to set the current SSL configuration to true.

      The Tomcat Configuration Manager sub-menu reappears.

4. Update the keystore password, as described in .

   1. Type the Secure Connector Configuration menu item number.

      The Secure Connectors Configuration menu appears.

   2. Type the Edit SSL Connector menu item number.

      The Select Secure Connector to Edit menu appears.

   3. Press the required number to edit the secure connector.

      The Edit - <Secure_Connector_URL_and_Port_Number> menu appears.

   4. Type the Set Keystore Password menu item number.

      A prompt appears that requests the new secure connector keystore password.

      1. Type the new secure connector keystore password.

         The password is changed in Control-M/EM and the Edit - <Secure_Connector_URL_and_Port_Number> menu reappears.

   5. Type s to save the changes.

      A confirmation prompt appears.

   6. Type Y to confirm that you want to save the changes.

      The password is encrypted and the changes are saved to Control-M/EM.

If the CA certificate that signs your Web Server certificate does not exist in the Trusted Root Certificate Authorities, see Installing the Root CA Certificate on the Control-M Client.

5. Recycle the following components, as described in Recycling a Control-M/EM Component:

   • Web Server

   • GUI Server

   • CMS

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

1. Extract the root CA certificate from your secure connector keystore on the Control-M/EM machine where your Web Server runs, and run the following command:

   <Control-M/EM_Home>/bin/openssl pkcs12 -in <EM_Home_Directory>/ini/ssl/<Secure_Connector_Keystore_Filename_and_Extension> -cacerts -nokeys -password pass:<Secure_Connector_Keystore_Password> > cacert.crt

   (UNIX only) You must run this script in 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. Click Install Certificate, 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.

Begin

1. Run the following command:

   manage_webserver

   The Tomcat Configuration Manager main menu appears.

2. Type the Tomcat Configuration menu item number.

   The Tomcat Configuration Manager sub-menu appears.

3. Type the Secure Connectors Configuration menu item number.

   The Secure Connectors Configuration menu appears.

4. Do one of the following:

   • Add: To add a new connector, do the following:

     1. Type the Add New SSL Connector menu item number.

     2. At the prompt, type the filename for the new keystore that is located in the following directory:

        • UNIX: <Control-M/EM_Home>/ini/ssl

        • Windows: <Control-M/EM_Home>\ini\ssl

     3. At the prompt, type the keystore file password.

        The new connector now uses the keystore file that you defined.

   • Update: To update a connector, do the following:

     1. Type the Edit SSL Connector menu item number.

        The Select Secure Connector to Edit menu appears.

     2. Type the required secure connector menu item number.

        The Edit - <Secure_Connector_URL_and_Port_Number> menu appears.

     3. Type the required parameter menu item number and follow the prompts to update its value.

   • Delete: To delete a connector, do the following:

     1. Type the Delete SSL Connector menu item number.

        The Delete SSL Connector menu appears.

     2. Type the required secure connector menu item number.

        The Edit - <Secure_Connector_URL_and_Port_Number> menu appears.

     3. Type the menu item number of the secure connector that you want to delete.

        A confirmation prompt appears.

     4. Type Y to confirm deletion.

5. Recycle the Web Server, as described in Recycling a Control-M/EM Component.

Testing SSL on the Web Server

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

Begin

1. Do the following to verify that the hostname and port are used by the relevant connector:

   1. Run the following command:

      manage_webserver

      The Tomcat Configuration Manager main menu appears.

   2. Type the Tomcat Configuration menu item number.

      The Tomcat Configuration Manager sub-menu appears.

   3. Type the Secure Connectors Configuration menu item number.

      The Secure Connectors Configuration menu appears.

   4. Type the Edit SSL Connector menu item number.

      The Select Secure Connector to Edit menu appears and lists all the 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 host, type the URL as follows:

   https://<Web_Server_FQDN>:<Web_Server_Port_Number>

   The Control-M welcome page appears.

Reverting to an Old Connector

This procedure describes how to revert 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, as follows:

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

     connectionTimeout="20000"

     redirectPort="8443" />

2. Recycle the Web Server, as described in Recycling a Control-M/EM Component.

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 the command line, run the following command:

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

3. Run the following command to verify that the new CA certificate was added to your truststore:

   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. Run the following command to remove the old root CA or intermediate chain certificate from all updated keystores:

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

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

Verifying Certificate 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. Run the following command:

      manage_webserver

      The Tomcat Configuration Manager main menu appears.

   2. Type the Tomcat Configuration menu item number.

      The Tomcat Configuration Manager sub-menu appears.

   3. Type the Secure Connectors Configuration menu item number.

      The Secure Connectors Configuration menu appears.

   4. Type the Edit SSL Connector menu item number.

      The Select Secure Connector to Edit menu appears.

   5. Type the required secure connector menu item number.

      The Edit - <Secure_Connector_URL_and_Port_Number> menu appears.

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

      The default certificateVerification property value is none.

2. Do the following:

   1. Run the following command to view the Web Server certificate attributes:

      openssl x509 -in <Web_Server_Certificate_Path> -text -noout

      The Web Server certificate attributes appear.

   2. In the Web Server certificate attributes, search for X509v3 Extended Key Usage, as follows:

      • If X509v3 Extended Key Usage does not appear or if it appears as follows, then the Web Server certificate supports TLS Web Server and TLS web client authentication:

        X509v3 Extended Key Usage:

        TLS Web Server Authentication, TLS Web Client Authentication

      • If the following appears, then the Web Server certificate only supports TLS Web Server authentication:

        X509v3 Extended Key Usage:

        TLS Web Server Authentication

3. Do the following:

   1. Run the following command to view the root CA certificate attributes:

      openssl x509 -in <Root_CA_Certificate_Path> -text -noout

      The root CA certificate attributes appear.

   2. In the root CA certificate attributes, search for X509v3 Extended Key Usage, as follows:

      • If X509v3 Extended Key Usage does not appear or if it appears as follows, then the root CA certificate supports TLS Web Server and TLS web client authentication:

        X509v3 Extended Key Usage:

        TLS Web Server Authentication, TLS Web Client Authentication

      • If the following appears, then the root CA certificate only supports TLS Web Server authentication:

        X509v3 Extended Key Usage:

        TLS Web Server Authentication

Reconfiguring Connections Between Control-M/EM Services and the Web Server

This procedure describes how to reconfigure the HTTP/HTTPS connection attributes that enable Control-M/EM Services and the Web Server to communicate. These attributes are configured by default, as described in Default HTTP/HTTPS Connection Attributes.

Begin

1. Log in to the Control-M/EM host.

2. Open the following file in a text editor:

   • UNIX: <Control-M/EM_Home>/etc/services/config/custom/services-common-application-custom.yml

   • Windows: <Control-M/EM_Home>\Default\services\config\custom\services-common-application-custom.yml

   The HTTP/HTTPS connection attribute values that are defined in the services-common-application-custom.yml file override the values that are defined in the services-common-application.yml file.

3. In the services-common-application-custom.yml file, do the following: 

   1. Ensure that the following code snippet is at the top of the file:

      Copy

      com:
        bmc:
          services:
            ## Jetty setting
            server:

   2. On a new line under the server parameter, for each HTTPS connection attribute that you need to change, type the attribute name and its new value, as described in Default HTTP/HTTPS Connection Attributes.

      The following code snippet in the services-common-application-custom.yml file changes the default schema attribute from https to http:

      

   3. Save and close the file.

4. If you have updated the keystore or keystorepass attributes, run the following command to encrypt the password in the keystore password file:

   emcryptocli <New_Keystore_Password> <Full_Keystore_Password_Pathname>

   (UNIX only) You must run this script in the Control-M/EM shell, such as em tcsh.

   • UNIX: em emcryptocli 73YlIjW_1u%a /home/dbauser/ctm_em/ini/ssl/myTomcat_Password.ini

   • Windows: %EM_HOME%\bin\emcryptocli 73YlIjW_1u%a %EM_HOME%\ini\ssl\myTomcat_Password.ini

5. Recycle all Control-M/EM services, as described in Recycling a Control-M/EM Component.

Default HTTP/HTTPS Connection Attributes

The following code snippet describes the default HTTP/HTTPS connection attributes that enable Control-M/EM Services and the Web Server to communicate. These attributes are defined in the services-common-application.yml configuration file after the server parameter, as follows:

com:
  bmc:
    services:
      ## Jetty setting
      server:
        schema: https
        keystore: ini/ssl/tomcat.p12
        keystoreType: PKCS12
        keystorepass: ini/ssl/tomcat.ini
        rest:
          portspan: 0
          hostname: "*"

This services-common-application.yml file is located in the following directory:

• UNIX: <EM_Home>/etc/services/config/

• Windows: EM_Home>\Default\services\config\