SSL-enabling the eG RUM Collector

To monitor the user experience with SSL-enabled web sites/web applications, you should ideally SSL-enable the eG RUM collector. This is because, the basic security framework of browsers does not permit browsers to send resources and beacons from an HTTPS web site/application to an HTTP collector.

For ease of management, you can front the HTTP collector with an SSL-enabled load balancer (eg., F5, NetScaler, etc.). This load balancer can then be configured to forward the resources and beacons it receives to the HTTP collector.

If you do not want to use a load balancer, then you will have to SSL-enable the RUM collector.

The eG RUM collector on Windows is bundled with a self-signed SSL certificate. This certificate is named eGRUM.bin and is available in the <EG_RUM_COLLECTOR_INSTALL_DIR>\tomcat\webapps folder. To SSL-enable the RUM collector on Windows using this certificate, all you need to do is click the Yes button (in Figure 8) at step 9 of the collector installation process detailed in Installing Using the eGRUM Executable . However, it is recommended that you do not use this self-signed certificate for SSL-enabling your Windows collectors.

To SSL-enable any RUM collector – be it on Windows or Unix – you are advised to pick one of the two approaches outlined below:

  • You can obtain a signed certificate from an internal certifiying authority (eg., Microsoft Active Directory Certificate Services) and use this certificate to SSL-enable the eG RUM collector, (OR)
  • You can obtain a signed certificate from a valid, external certifying authority (eg., Verisign) and use this certificate to SSL-enable the eG RUM collector

If you go with option (a), use the procedure detailed in SSL-enabling the eG RUM Collector Using a Certificate Signed by an Internal CA. If you pick option (b), use the procedure detailed in SSL-Enabling the eG RUM Collector Using a Signed Certificate Obtained from a Valid Certifying Authority .

SSL-enabling the eG RUM Collector Using a Certificate Signed by an Internal CA

The broad steps to be followed to achieve this are as follows:

  1. Generating the keystore file
  2. Generating a certificate request
  3. Submitting the certificate request to the internal Certificate Authority (CA) and obtaining a certificate
  4. Importing the certificate into a keystore
  5. Configuring Tomcat for using the keystore file

The sub-sections below elaborate on each of these steps.

The steps detailed below are common to both Windows and Unix installations of the collector.

Generating a Keystore File

The keystore file stores the details of the certificates necessary to make the protocol secure. Certificates contain the information pertaining to the source of the application data, and helps validate the source. To generate the keystore, use the keytool command. For this purpose, login to the RUM collector host and go to the command prompt. Set the Java_home path if it is not done already. Then, execute the following commands, one after another:

cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

keytool -genkey -alias egitlab1 -keyalg RSA -keypass mykey -keystore <Filename>.keystore -storepass mykey -keysize 2048 -validity 1095

The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

  • -alias : an alias name for the certificate being generated
  • -keypass : a password used to protect the key that is generated; ensure that you provide the same values for -keypass and -storepass.
  • -keyalg : specifies the algorithm that is used to generate the keys. The options are as follows:
    • dsa : Digital Signature Algorithm
    • RSA : An algorithm used for publick-key cryptography
  • -keystore :  the keytool command stores the generated key in a .keystore file; provide a name for this file as input to the -keystore command
  • -keysize : the size of the key that is generated; the default key size is 1024 bits - the key size must be in the range 512 bits - 1024 bits
  • -validity : indicates the number of days for which the key/certicate will be valid - 1095 days refer to 3 years.

The command, upon execution, will request the following inputs:

What is your first and last name?
[Unknown]: <Type the eG RUM Collector's fully qualified domain name here>
What is the name of your organizational unit?
[Unknown]: United States
What is the name of your organization?
[Unknown]: eG Innovations Inc
What is the name of your City or Locality?
[Unknown]: Bridgewater
What is the name of your State or Province?
[Unknown]: New Jersey
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=eG Innovations Inc, OU=United States, O=eG Innovations Inc, L=Bridge Water, ST=New Jersey, C=US correct?
[no]: yes

When requested for the first and last name, indicate the fully qualified domain name using which you will be configuring the eG RUM collector in the eG admin interface. For instance, if the eG RUM collector is to be accessed using the URL, http://egrumcollector.eginnovations.com, where egrumcollector.eginnovations.com is the fully qualified domain name of the collector, then specify here.

Once all the required inputs are provided, a .keystore file will be generated in the <JAVA_HOME_DIR>\bin directory with the <Filename> you had provided while issuing the command.

Generating a Certificate Request

Once a keystore file is generated, proceed to request for a certificate from a valid certifying authority. The procedure for this is as follows:

  1. Login to the eG RUM collector and go to its shell/command prompt.
  2. Set the java_home path if it is not done already.
  3. Execute the following commands one after another:

    cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

    keytool -certreq -alias egitlab1 -keyalg RSA -file <Name_of_the_text_file> -keypass mykey -keystore <filename>.keystore –storepass mykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide the same alias name that you provided while generating the keystore file (see section of this document).
    • -keyalg : specifies the algorithm that was used to generate the keys; this can be rsa or dsa, depending upon which algorithm was used for key generation in the procedure detailed in section.
    • -file : Provide a name for the text file to which the certificate request will be saved.
    • -keypass : the password used to protect the key that was generated; make sure that you provide the same password that you provided while generating the keystore file (see Generating a Keystore File section of this document). Also, note that -storepass and -keypass should be the same.
    • -keystore :  Provide the name of the keystore file in which the key has been stored; specify the same file name that you used to store the key (see Generating a Keystore File ).
  1. If this command executes successfully, then a certificate request will be generated and automatically stored in the text file you specified in step 2 above.

Obtaining a Certificate from the Internal CA

  1. The first step towards obtaining a certificate is to submit the certificate request to the internal CA. For this connect to the Certificate server of the internal CA and select the option to submit the certificate. For instance, if you are using Microsoft Active Directory Certificate Services to request for a self-signed certificate, then, you need to connect to http://<YourWebServerName>/certsrv, and then pick the option to submit the certificate. Figure 1 will then appear.

    Figure 1 : Requesting for a certificate

  1. Open the text file containing the certificate request (which was created using the procedure detailed in Generating a Certificate Request ), copy the contents of the file, and then paste it to the text area of the Base 64-encoded certificate request text box of Figure 1. Then, click the Submit button.
  1. The certificate will thus be generated. Download the certificate.

Figure 2 : Downloading the certificate

Importing the Certificates into the Keystore File

The downloaded certificate can be in one of the following forms:

  • Can be a single, combined certificate
  • Can be accompanied by a certificate chain
  • Can be in a PEM format

The procedure for importing certificates differs based on the format of the downloaded certificate. These procedures have been detailed in the sub-sections below.

Importing a Combined Certificate into the Keystore File

In this case, follow the steps below to import the certificate into the keystore file:

  1. Set the java_home path if it is not done already.
  1. At the command prompt, execute the following commands, one after another:

    cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

    keytool -import –trustcacerts -alias egitlab1 -file <Name_of_the_domain_certificate> -keystore <Name_of_the_keystore_file>.keystore

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide the same alias name you provided when generating the keystore (see Generating a Keystore File)
    • -file : the name of the domain certificate that you want to import
    • -keystore :  Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File above.

Importing a Signed Certificate and the Certificate Chain into the Keystore File

Digital certificates are verified using a chain of trust. The trust anchor for the digital certificate is the Root Certificate Authority (CA). The Certificate Hierarchy is a structure of certificates that allows individuals to verify the validity of a certificate's issuer. Certificates are issued and signed by certificates that reside higher in the certificate hierarchy, so the validity and trustworthiness of a given certificate is determined by the corresponding validity of the certificate that signed it.

The Chain of Trust of a Certificate Chain is an ordered list of certificates, containing an end-user subscriber certificate and intermediate certificates (that represents the Intermediate CA), that enables the receiver to verify that the sender and all intermediate certificates are trustworthy.

A certificate chain will therefore consist of multiple certificates. Before importing each of these certificates, you will have to understand the hierarchy of the certificates. To know which is the root and which is the intermediate certificate, refer to the web site of the certificate authority. Then, set the java_home path if it is not done already.

Then, follow the steps below:

  1. First, import the Root certificate. For this, execute the following commands, one after another in the command prompt:

    cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

    keytool -import –trustcacerts -alias rootcert -file <Name_of_the_root_certificate> -keystore <Name_of_the_keystore_file>.keystore –keypass mykey –storepass mykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide a unique alias name for the root certificate.
    • -file: the name of the root certificate that you want to import
    • -keystore :  Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File.

    • -keypass and –storepass : Provide the same keypass and storepass that you specified when generating the keystore; refer to Generating a Keystore File section above for details.

  1. Next, import each of the intermediate certificates, one after another, using the following command:

    keytool -import –trustcacerts -alias intercert1-file <Name_of_the_intermediate_certificate>-keystore <Name_of_the_keystore_file>.keystore–keypassmykey–storepassmykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide a unique alias name for every intermediate certificate.
    • -file: the name of the intermediate certificate that you want to import
    • -keystore :  Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File section.
    • -keypass and –storepass : Provide the same keypass and storepass that you specified when generating the keystore; refer to Section Generating a Keystore File for details.
  1. Finally, import the entity/domain certificate into the keystore by issuing the following command:

    keytool -import –trustcacerts -alias egitlab1 -file <Name_of_the_domain_certificate> -keystore <Name_of_the_keystore_file>.keystore

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide the same alias name you provided when generating the keystore (see Generating a Keystore File) .
    • -file: the name of the domain certificate that you want to import
    • -keystore : Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File .

Note:

If the domain certificate import command throws an error for any reason, it could be because, all related certificates may not have been imported. Check the web site of the CA for more details.

Importing a Certificate that is in the PEM Format

PEM is a container format that may include just the public certificate (such as with Apache installs, and CA certificate files /etc/ssl/certs), or may include an entire certificate chain including public key, private key, and root certificates, or may only contain a certificate and a private key.

If the certificate you downloaded is in the PEM format and includes only a certificate file and a private key file, then follow the steps below to import that certificate into a keystore file.

  1. Run the following command from the command prompt to export the certificate and private key file into the pkcs12 format:

    openssl pkcs12 -export -in certificate.crt -inkey private.key -certfile certificate.crt -name My certificate” -out keystore.p12

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -in : the name of the certificate that is included in the PEM container

    • -inkey: the name of the private key file the PEM container consists of

    • -certfile :  the name of the certificate that is included in the PEM container

    • -name : Provide a unique name for the certificate file that is being exported.

    • -out : Specify the name of the keystore file to which the certificate and private key are to be exported. The keystore file can have any name of your choice.

  1. Next, you need to convert the keystore file, which is currently in the pkcs12 format, into the Java keystore (i.e., JKS) format. For this, issue the following command at the command prompt:

    keytool -importkeystore –alias egitlab1-deststorepass mykey -destkeypass mykey -destkeystore keystore,jks -srckeystore keystore.pk12 -srcstoretype PKCS12 -srcstorepass mykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the aliasname of the certificate being requested; make sure that you provide the same alias name that you specified in Generating a Keystore File.

    • -deststorepass : this refers to the storepass of the destination keystore file – i.e., the keystore file in the JKS format.  The storepass of the destination keystore should be the same as the storepass of the source keystore.

    • -destkeypass : this refers to the keypass of the destination keystore file - i.e., the keystore file in the JKS format. The storepass and keypass of the destination keystore file should be the same. 

    • -destkeystore: the name of the destination keystore file – i.e., the keystore file in the JKS format. 

    • -srckeystore :  the name of the destination keystore file – i.e., the keystore file in the PKCS12 format. 

    • -srcstorepass : The storepass of the source keystore file – i.e., the keystore file in the PKCS12 firmat. make sure that you provide the same storepass you specified in Generating a Keystore File

Configuring Tomcat for Using the Keystore File

The eG RUM collector is a Tomcat-based software. Therefore, to SSL-enable the eG RUM collector, you need to configure the server.xml file of Tomcat with the name and full path to the keystore file which was created earlier.

  1. Edit the server.xml file in the <CATALINA_HOME>\conf directory.

  1. In the file, search for the XML block where the SSL Coyote HTTP connector on port 8443 is defined. If this block is commented, it indicates that the eG RUM collector is not SSL-enabled and is hence listening on an HTTP port only. To SSL-enable the eG RUM collector, first uncomment this block as indicated below:

    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
        <Connector protocol="HTTP/1.1"
                   port="8443" minSpareThreads="32" maxThreads="512"
            enableLookups="false" acceptCount="10"  connectionTimeout="20000"            
            useURIValidationHack="false" URIEncoding="UTF-8" compression="on" compressionMinSize="2048" noCompressionUserAgents="gozilla, traviata" compressableMimeType="text/html,text/xml,text/plain,application/x-java-applet,application/octet-stream,application/xml,text/javascript,text/css,image/png,image/jpeg, image/gif,application/pdf,
    application/x-
    javascript,application/javascript"
            SSLEnabled="true" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS"/>

  1. Then, proceed to make the changes indicated in Bold below in the SSL XML block:

    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
        <Connector protocol="HTTP/1.1"
                   port="7077" minSpareThreads="32" maxThreads="512"
            enableLookups="false" acceptCount="10"  connectionTimeout="20000"         useURIValidationHack="false" URIEncoding="UTF-8" compression="on" compressionMinSize="2048" noCompressionUserAgents="gozilla, traviata" compressableMimeType="text/html,text/xml,text/plain,application/x-java-applet,application/octet-stream,application/xml,text/javascript,text/css,image/png,image/jpeg,

    image/gif,
    application/pdf,application/x-javascript,application/javascript"
            SSLEnabled="true" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS" keyAlias=”egitlab1” keystoreFile="<The_full_path_to_the_keystore_file>"keystorePass="mykey" />

    Set the port parameter in the XML block to reflect the SSL port number that you have configured for the eG RUM collector. Also, note that three new parameters, namely - keyAlias, keystoreFile and keystorePass - have been inserted into the SSL block. While the keystoreFile parameter has to be set to the full path to the .keystore file that you generated earlier, the keystorePass parameter should be set to the keystore password that you specified while issuing the keytool command. Likewise, the keyAlias parameter is to be set to the alias name that you provided for the certificate file, when you generated it using the procedure detailed in the Generating a Keystore File topic.

  1. With that change, the eG RUM collector has acquired the capability to listen on two ports - the SSL port and the non-SSL port. To configure the eG RUM collector to listen only on the SSL port, simply comment that section of the server.xml file where the non-SSL Coyote HTTP connector on port 8081 has been defined, as indicated below:

    <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8081 -->

        <!-- <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"

       Port7077" minSpareThreads="32" maxThreads="512"

                   enableLookups="true" redirectPort="8443"

                   acceptCount="10" debug="0" connectionTimeout="20000"

                   useURIValidationHack="false"  URIEncoding="UTF-8"/> -->

  2. Save the file.
  3. Finally, start the eG RUM collector.

SSL-Enabling the eG RUM Collector Using a Signed Certificate Obtained from a Valid Certifying Authority

In highly secure environments, especially where the eG RUM collector is to be frequently accessed via the public internet, using a certificate signed by an internal CA may not be preferred. In such a case, you can obtain a valid certificate from a certificate authority and use that certificate to SSL-enable the eG RUM collector.

The broad steps to be followed to achieve this are as follows:

  1. Generating the keystore file

  2. Generating a certificate request

  3. Submitting the certificate request to the Certificate Authority (CA) and obtaining a certificate

  4. Importing the certificate into a keystore

  5. Configuring Tomcat for using the keystore file

The sub-sections below elaborate on each of these steps.

The steps detailed below are common to both Windows and Unix installations of the collector.

Generating a Keystore File

The keystore file stores the details of the certificates necessary to make the protocol secure. Certificates contain the information pertaining to the source of the application data, and helps validate the source. To generate the keystore, use the keytool command. For this purpose, login to the RUM collector and go to the Unix shell/Windows command prompt (as the case may be). Set the JAVA_HOME path if it is not done already. Then, execute the following commands, one after another:

cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

keytool -genkey -alias egitlab1 -keyalg RSA -keypass mykey -keystore <Filename>.keystore -storepass mykey -keysize 2048 -validity 1095

The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

  • -alias : an alias name for the certificate being generated
  • -keypass : a password used to protect the key that is generated; ensure that you provide the same values for -keypass and -storepass.
  • -keyalg : specifies the algorithm that is used to generate the keys. The options are as follows:

    • dsa: Digital Signature Algorithm

    • RSA : An algorithm used for publick-key cryptography

  • -keystore :  the keytool command stores the generated key in a .keystore file; provide a name for this file as input to the -keystore command

  • -keysize : the size of the key that is generated; the default key size is 1024 bits - the key size must be in the range 512 bits - 1024 bits

  • -validity : indicates the number of days for which the key/certicate will be valid - 1095 days refer to 3 years.

The command, upon execution, will request the following inputs:

What is your first and last name?
[Unknown]: <Type the eG manager's fully qualified domain name here>
What is the name of your organizational unit?
[Unknown]: United States
What is the name of your organization?
[Unknown]: eG Innovations Inc
What is the name of your City or Locality?
[Unknown]: Bridgewater
What is the name of your State or Province?
[Unknown]: New Jersey
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=eG Innovations Inc, OU=United States, O=eG Innovations Inc, L=Bridge Water, ST=New Jersey, C=US correct?
[no]: yes

When requested for the first and last name, indicate the fully qualified domain name using which you will be accessing the eG RUM collector. For instance, if the collector is to be accessed as http://egrumcollector.eginnovations.com, where egrumcollector.eginnovations.com is the fully qualified domain name of the RUM collector, then specify egrumcollector.eginnovations.com here.

Once all the required inputs are provided, a .keystore file will be generated in the <JAVA_HOME_DIR>\bin directory with the <Filename> you had provided while issuing the command.

Generating a Certificate Request

Once a keystore file is generated, proceed to request for a certificate from a valid certifying authority. The procedure for this is as follows:

  1. Login to the eG RUM collector host and go to the Unix shell/Windows command prompt (as the case may be).

  2. Set the java_home path if it is not done already.

  3. Execute the following commands one after another:

    cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

    keytool -certreq -alias egitlab1 -keyalg RSA -file <Name_of_the_text_file> -keypass mykey -keystore <filename>.keystore –storepass mykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide the same alias name that you provided while generating the keystore file (see Generating a Keystore File).

    • -keyalg : specifies the algorithm that was used to generate the keys; this can be rsa or dsa, depending upon which algorithm was used for key generation in the procedure detailed in Generating a Keystore File

    • -file : Provide a name for the text file to which the certificate request will be saved.

    • -keypass : the password used to protect the key that was generated; make sure that you provide the same password that you provided while generating the keystore file (see Generating a Keystore File). Also, note that -storepass and -keypass should be the same.

    • -keystore :  Provide the name of the keystore file in which the key has been stored; specify the same file name that you used to store the key (see Generating a Keystore File.

  1. If this command executes successfully, then a certificate request will be generated and automatically stored in the text file you specified in step 2 above.

Obtaining the Certificate from the CA

  1. The first step towards obtaining a certificate is to submit the certificate request to the CA. For this connect to the Certificate server of the CA and submit the certificate. The procedure for request submission will differ from one CA to another.

  2. The certificate will thus be generated. Download the certificate.

Importing the Certificates into the Keystore File

The downloaded certificate can be in one of the following forms:

  • Can be a single, combined certificate
  • Can be accompanied by a certificate chain
  • Can be in a PEM format

The procedure for importing certificates differs based on the format of the downloaded certificate. These procedures have been detailed in the sub-sections below.

Importing a Combined Certificate into the Keystore File

In this case, follow the steps below to import the certificate into the keystore file:

  1. Set the java_home path if it is not done already.

  1. At the command prompt, execute the following commands, one after another:

    cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

    keytool -import –trustcacerts -alias egitlab1 -file <Name_of_the_domain_certificate> -keystore <Name_of_the_keystore_file>.keystore

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide the same alias name you provided when generating the keystore (see Generating a Keystore File) .

    • -file: the name of the domain certificate that you want to import

    • -keystore :  Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File section above.

Importing a Signed Certificate and the Certificate Chain into the Keystore File

Digital certificates are verified using a chain of trust. The trust anchor for the digital certificate is the Root Certificate Authority (CA). The Certificate Hierarchy is a structure of certificates that allows individuals to verify the validity of a certificate's issuer. Certificates are issued and signed by certificates that reside higher in the certificate hierarchy, so the validity and trustworthiness of a given certificate is determined by the corresponding validity of the certificate that signed it.

The Chain of Trust of a Certificate Chain is an ordered list of certificates, containing an end-user subscriber certificate and intermediate certificates (that represents the Intermediate CA), that enables the receiver to verify that the sender and all intermediate certificates are trustworthy.

A certificate chain will therefore consist of multiple certificates. Before importing each of these certificates, you will have to understand the hierarchy of the certificates. To know which is the root and which is the intermediate certificate, refer to the web site of the certificate authority. For instance, if Comodo is the Certificate Authority that has issued the SSL certificate, then connect to the following URL, https://support.comodo.com/index.php?/Default/Knowledgebase/Article/View/620/1/, to gain clarity.

Then, follow the steps below:

  1. Set the java_home path if it is not done already.

  1. Then, import the Root certificate. For this, execute the following commands, one after another in the command prompt:

    cd %JAVA_HOME%\bin (on Windows; on Unix, this will be cd $JAVA_HOME/bin)

    keytool -import –trustcacerts -alias rootcert -file <Name_of_the_root_certificate> -keystore <Name_of_the_keystore_file>.keystore –keypass mykey –storepass mykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide a unique alias name for the root certificate.

    • -file: the name of the root certificate that you want to import

    • -keystore :  Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File.

    • -keypass and –storepass : Provide the same keypass and storepass that you specified when generating the keystore; refer to Generating a Keystore File.

  1. Next, import each of the intermediate certificates, one after another, using the following command:

    keytool -import –trustcacerts -alias intercert1-file <Name_of_the_intermediate_certificate>-keystore <Name_of_the_keystore_file>.keystore–keypassmykey–storepassmykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide a unique alias name for every intermediate certificate.

    • -file: the name of the intermediate certificate that you want to import

    • -keystore :  Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File above.

    • -keypass and –storepass : Provide the same keypass and storepass that you specified when generating the keystore; refer to Generating a Keystore File.

  1. Finally, import the entity/domain certificate into the keystore by issuing the following command:

    keytool -import –trustcacerts -alias egitlab1 -file <Name_of_the_domain_certificate> -keystore <Name_of_the_keystore_file>.keystore

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the alias name of the certificate being requested; make sure that you provide the same alias name you provided when generating the keystore (see Generating a Keystore File) .

    • -file: the name of the domain certificate that you want to import

    • -keystore :  Provide the name of the keystore file you generated when you followed the procedure detailed in Generating a Keystore File.

Note:

If the domain certificate import command throws an error for any reason, it could be because, all related certificates may not have been imported. Check the web site of the CA for more details.

Importing a Certificate that is in the PEM Format

PEM is a container format that may include just the public certificate (such as with Apache installs, and CA certificate files /etc/ssl/certs), or may include an entire certificate chain including public key, private key, and root certificates, or may only contain a certificate and a private key.

If the certificate you downloaded is in the PEM format and includes only a certificate file and a private key file, then follow the steps below to import that certificate into a keystore file.

  1. Run the following command from the command prompt to export the certificate and private key file into the pkcs12 format:

    openssl pkcs12 -export -in certificate.crt -inkey private.key -certfile certificate.crt -name “My certificate” -out keystore.p12

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -in : the name of the certificate that is included in the PEM container

    • -inkey: the name of the private key file the PEM container consists of

    • -certfile :  the name of the certificate that is included in the PEM container

    • -name : Provide a unique name for the certificate file that is being exported.

    • -out : Specify the name of the keystore file to which the certificate and private key are to be exported. The keystore file can have any name of your choice.

  2. Next, you need to convert the keystore file, which is currently in the pkcs12 format, into the Java keystore (i.e., JKS) format. For this, issue the following command at the command prompt:

    keytool -importkeystore –alias egitlab1-deststorepass mykey -destkeypass mykey -destkeystore keystore,jks -srckeystore keystore.pk12 -srcstoretype PKCS12 -srcstorepass mykey

    The text in Bold in the above command line indicates those inputs that can change according to the requirements of your environment. These inputs have been described below:

    • -alias : the aliasname of the certificate being requested; make sure that you provide the same alias name that you specified in Generating a Keystore File.

    • -deststorepass : this refers to the storepass of the destination keystore file – i.e., the keystore file in the JKS format.  The storepass of the destination keystore should be the same as the storepass of the source keystore.

    • -destkeypass : this refers to the keypass of the destination keystore file - i.e., the keystore file in the JKS format. The storepass and keypass of the destination keystore file should be the same. 

    • -destkeystore: the name of the destination keystore file – i.e., the keystore file in the JKS format. 

    • -srckeystore :  the name of the destination keystore file – i.e., the keystore file in the PKCS12 format. 

    • -srcstorepass : The storepass of the source keystore file – i.e., the keystore file in the PKCS12 format. make sure that you provide the same storepass you specified in Generating a Keystore File

Configuring Tomcat for Using the Keystore File

The eG RUM collector uses Tomcat as the web server. Therefore, to SSL-enable the collector, you need to configure the server.xml file of Tomcat with the name and full path to the keystore file which was created earlier.

  1. Edit the server.xml file in the <CATALINA_HOME>\conf directory.

  1. In the file, search for the XML block where the SSL Coyote HTTP connector on port 8443 is defined. If this block is commented, it indicates that the eG collector is not SSL-enabled and is hence listening on an HTTP port only. To SSL-enable the eG RUM collector, first uncomment this block as indicated below:

    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
        <Connector protocol="HTTP/1.1"
                   port="8443" minSpareThreads="32" maxThreads="512"
            enableLookups="false" acceptCount="10"  connectionTimeout="20000"            
            useURIValidationHack="false" URIEncoding="UTF-8" compression="on" compressionMinSize="2048" noCompressionUserAgents="gozilla, traviata" compressableMimeType="text/html,text/xml,text/plain,application/x-java-applet,application/octet-stream,application/xml,text/javascript,text/css,image/png,image/jpeg,

    image/gif,application/pdf,application/
    x-javascript,application/javascript"
            SSLEnabled="true" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS"/>

  2. Then, proceed to make the changes indicated in Bold below in the SSL XML block:

    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
        <Connector protocol="HTTP/1.1"
                   port="7080" minSpareThreads="32" maxThreads="512"
            enableLookups="false" acceptCount="10"  connectionTimeout="20000"         useURIValidationHack="false" URIEncoding="UTF-8" compression="on" compressionMinSize="2048" noCompressionUserAgents="gozilla, traviata" compressableMimeType="text/html,text/xml,text/plain,application/x-java-applet,application/octet-stream,application/xml,text/javascript,text/css,image/png,image/jpeg, image/gif,
    application/pdf,application/x-javascript,application/javascript"
            SSLEnabled="true" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS" keyAlias=”egitlab1” keystoreFile="<The_full_path_to_the_keystore_file>"keystorePass="mykey" />

    Set the port parameter in the XML block to reflect the SSL port number that you have configured for the eG RUM collector. Also, note that three new parameters, namely - keyAlias, keystoreFile and keystorePass - have been inserted into the SSL block. While the keystoreFile parameter has to be set to the full path to the .keystore file that you generated earlier, the keystorePass parameter should be set to the keystore password that you specified while issuing the keytool command. Likewise, the keyAlias parameter is to be set to the alias name that you provided for the certificate file, when you generated it in Generating a Keystore File.

  3. With that change, the eG RUM collector has acquired the capability to listen on two ports - the SSL port and the non-SSL port. To configure the collector to listen only on the SSL port, simply comment that section of the server.xml file where the non-SSL Coyote HTTP connector on port 8081 has been defined, as indicated below:

    <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8081 -->

        <!-- <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"

       Port7077" minSpareThreads="32" maxThreads="512"

                   enableLookups="true" redirectPort="8443"

                   acceptCount="10" debug="0" connectionTimeout="20000"

                   useURIValidationHack="false"  URIEncoding="UTF-8"/> -->

  4. Save the file.

Troubleshooting SSL-enabling the eG RUM Collector

Troubleshooting the “Certificate error” that occurs when accessing an eG manager that is SSL-enabled using a certificate from an internal CA

Typically, when you attempt to access an eG manager that has been SSL-enabled using the certificate obtained from an internal CA, the browser will throw the following error message:

Figure 3 : The “Certificate error” that the browser reports

To avoid this error, you will have to import the internal CA’s root certificate to the browser and store it as a ‘trusted root certificate’. For this, follow the broad steps outlined below:

  1. Copy the internal CA’s root certificate to the host from which you are accessing the eG manager (i.e., the browser host). For instance, if Microsoft Active Directory Certificate Services is your internal CA, then, you will find the root certificate of this CA on your domain server. So, in this case, you will have to copy the root certificate from the domain server to your browser host.

  1. Next, using Windows Explorer, browse for the certificate, and once found, right-click on it. From the shortcut menu that appears, select the Install Certificate option (see Figure 4) to import the certificate to the browser.

    Figure 4 : Selecting the option to install the certificate on the browser host

  2. Figure 5 will then appear. Click Next here to continue.

    Figure 5 : Welcome screen of the Certificate Import Wizard

  3. Figure 5 will then appear. Here, select the Place all certificates in the following store option, and click the Browser button to indicate where the certificate is to be stored.

    Figure 6 : Choosing to place the certificate in a specific store

  4. From Figure 7 that then appears, select the Trusted Root Certificate Authorities store and click ok.

    Figure 7 : Storing the certificate in the Trusted Root Certificate Authorities store

  5. The chosen store will then appear in the text box below Place all certificates in the following store option, as depicted by Figure 8. Click Next in Figure 8 to continue.

    Figure 8 : The chosen store displayed

  6. A quick summary of your selections will appear in Figure 9. Review your specifications and click Finish to complete the import.

    Figure 9 : Finishing the import

  7. The following warning message will appear. Click Yes in Figure 10 to proceed with the import.

    Figure 10 : A warning message that appears when importing a certificate issued by an internal CA

  8. If import is successful, the following message will appear. Click ok.

    Figure 11 : A message box informing you that the certificate has been successfully imported

You will now be able to access the eG manager without a glitch!

Figure 12 : The login screen of the eG manager, without the ‘Certificate error’