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

Self-signed certificates are useful in environments where ‘security’ is not a priority. In highly secure environments, especially where the eG manager is to be frequently accessed via the public internet, using a self-signed certificate may not be preferred. In such a case, you can you can obtain a valid certificate from a certificate authority and use that certificate to SSL-enable the eG manager.

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

  • Generating the keystore file
  • Generating a certificate request
  • Submitting the certificate request to the Certificate Authority (CA) and obtaining a certificate
  • Importing the certificate into a keystore
  • Configuring Tomcat for using the keystore file

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

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 Windows manager 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

keytool -genkey -alias egitlab1 -keyalg RSA -keypass mykey -keystore <Filename>.keystore -storepass mykey -keysize 2048 -validity 1095 -ext SAN=DNS:[Details of DNS1],DNS:[Details of DNS2], IP:[Details of IP1],IP:[Details of IP2]

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 public-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 minimum key size that we recommend is 2048 bits
  • -validity : indicates the number of days for which the key/certicate will be valid - 1095 days refer to 3 years.
  • -ext SAN: The Subject Alternative Name (SAN) field lets you specify additional host names (sites, IP addresses, common names, etc.) to be protected by a single SSL Certificate. Against this parameter, specify the host names, fully qualified domain names, and/or IP addresses you want this certificate to protect. Wild card patterns can also be included in your SAN specification. A sample specification is provided below:

    -ext SAN=DNS:example.com,DNS:www.example.com,DNS:mail.example.*, IP:93.184.216.34,IP:2606:2800:220:1:248:1893:25c8:1946

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]: Bridge Water
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 manager. For instance, if the eG manager is to be accessed as http://egmanager.eginnovations.com, where egmanager.eginnovation.com is the fully qualified domain name of the eG manager, then specify egmanager.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. Copy this keystore file to the /opt/egurkha/manager/tomcat/webapps directory.

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 manager and go to the Windows 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

    keytool -certreq -alias egitlab1 -keyalg RSA -file <Name_of_the_text_file> -keypass mykey -keystore <filename>.keystore –storepass mykey -ext SAN=DNS:[Details of DNS1],DNS:[Details of DNS2], IP:[Details of IP1],IP:[Details of IP2]

    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).
    • -ext SAN: The Subject Alternative Name (SAN) field lets you specify additional host names (sites, IP addresses, common names, etc.) to be protected by a single SSL Certificate. Against this parameter, specify the host names, fully qualified domain names, and/or IP addresses you want this certificate to protect. Wild card patterns can also be included in your SAN specification. Make sure your SAN specification here is the same as the one you used when generating the key store (see SSL-Enabling the eG Manager Using a Signed Certificate Obtained from a Valid Certifying Authority).
  4. 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. Alongside, a private key file is also created, which will be used in the encryption/decryption of data sent between the eG agents and the manager. Make sure you store the private key file in a secure location on the eG manager host.

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.

Configuring Tomcat for Using the Keystore File

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

For this purpose, do the following:

  1. Stop the eG manager.
  2. Edit the server.xml file in the <CATALINA_HOME>/conf directory.
  3. 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 manager is not SSL-enabled and is hence listening on an HTTP port only. To SSL-enable the eG manager, first uncomment this block as indicated below:

    <Connector executor="tomcatThreadPool" protocol="org.apache.coyote.http11.Http11Nio2Protocol"

    port="8443"

    sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation" scheme="https" secure="true" SSLEnabled="true"

    enableLookups="false" acceptCount="100" connectionTimeout="300000" socket.rxBufSize="131072" socket.txBufSize="131072" maxHttpHeaderSize="131072" URIEncoding="UTF-8" useSendfile="false" tcpNoDelay="false" compression="force" compressibleMimeType="font/woff,font/woff2,text/html,text/xml,text/plain,application /x-java-applet,application/octet-stream,application/xml,text/javascript,text/css,image/png,image/bmp,image/jpeg,image /gif,application/pdf,application/x-javascript,application/javascript,application/json,application/x-shockwave-flash,application/xhtml+xml,application/xml+xhtml" noCompressionUserAgents="gozilla, traviata" server="eG Manager">

    <SSLHostConfig honorCipherOrder="true" ciphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA" certificateVerification="none" protocols="TLSv1.2" sslProtocol="TLS"></SSLHostConfig>

    </Connector>

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

    <Connector executor="tomcatThreadPool" protocol="org.apache.coyote.http11.Http11Nio2Protocol"

    port="<eG_Manager_Port>"

    sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation" scheme="https" secure="true" SSLEnabled="true"

    enableLookups="false" acceptCount="100" connectionTimeout="300000" socket.rxBufSize="131072" socket.txBufSize="131072" maxHttpHeaderSize="131072" URIEncoding="UTF-8" useSendfile="false" tcpNoDelay="false" compression="force" compressibleMimeType="font/woff,font/woff2,text/html,text/xml,text/plain,application /x-java-applet,application/octet-stream,application/xml,text/javascript,text/css,image/png,image/bmp,image/jpeg,image /gif,application/pdf,application/x-javascript,application/javascript,application/json,application/x-shockwave-flash,application/xhtml+xml,application/xml+xhtml" noCompressionUserAgents="gozilla, traviata" server="eG Manager">

    <SSLHostConfig honorCipherOrder="true" ciphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA" certificateVerification="none" protocols="TLSv1.2" sslProtocol="TLS"><Certificate certificateFile="<Full_path_to_certificate_file_you_downloaded>" certificateKeyFile="<Full_path_to_private_key_file>"/></SSLHostConfig>

    </Connector>

    Set the port parameter in the XML block to reflect the port number that you have configured for the eG manager. Also, note that a new <Certificate> code block is inserted into the SSL block, containing two new parameters, namely - certificateFile and certificateKeyFile . The certificateFile parameter has to be set to the full path to the certificate file that you obtained from the internal certificate authority (using the procedure detailed in Obtaining the Certificate from the CA). The certificateKeyFile parameter should be set to the name and full path to the private key file that was generated along with the certificate request (refer to Generating a Certificate Request).

  5. With that change, the eG manager on Linux has acquired the capability to listen on two ports - the SSL port and the non-SSL port. To configure the eG manager 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 executor="tomcatThreadPool" protocol="org.apache.coyote.http11.Http11Nio2Protocol"

    port="7077"

    enableLookups="false" redirectPort="8443"

    acceptCount="2000" connectionTimeout="300000" socket.rxBufSize="131072" socket.txBufSize="131072" maxHttpHeaderSize="131072"

    URIEncoding="UTF-8" useSendfile="false" tcpNoDelay="false" compression="force" noCompressionUserAgents="gozilla, traviata" compressibleMimeType="font/woff,font/woff2,text/html,text/xml,text/plain,application /x-java-applet,application/octet-stream,application/xml,text/javascript,text/css,image/png,image/bmp,image/jpeg,image /gif,application/pdf,application/x-javascript,application/javascript,application/json,application/x-shockwave-flash,application/xhtml+xml,application/xml+xhtml" server="eG Manager" />

    -->

  6. Save the file.
  7. Next, make sure that the eG manager URL configured against the MailHomeURL parameter in the [misc_args] section of the eg_services.ini file (in the /opt/egurkha/manager/config directory) begins with https:// nstead of http://. Then, save the file.
  8. Finally, start the eG manager.