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

• 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

• Configuring Ciphers for the Web Server

• Reverting Back to an Old Connector

• Adding Root CA Certificates to the .p12 Keystore

• Verifying Certificates 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 requirements from the certificate, 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 Create CSR Option.

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.

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 .

• Verify that the certificates have the required authentication level, as described in Verifying Certificates 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

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

Begin

1. Run 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. From the list that appears, select the required connector.

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

6. Restart the Web Server.

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 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 Web Server. These certificates and the generated private key and 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

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

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

Begin

1. Run 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 Web Server

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

Begin

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

   1. Run 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 host, type the URL as follows:

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

   The Control-M Welcome Page appears.

Configuring Ciphers for the Web Server

This procedure describes how to configure ciphers for the Web Server in Zone 1. The 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. Run 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 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. Run 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 clientAuth property (if required).

      The default value for clientAuth is false.

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. Restart all Control-M/EM services.

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\