SSL Enabling the eG Manager Using a Certificate from Windows Local Machine Certificate Store

The Windows Local Machine Certificate Store is a system-wide, secure repository for digital certificates located in the registry under HKEY_LOCAL_MACHINE. It applies to all users on the computer and is commonly used for system authentication, web server certificates, and device-level security.

You can use a certificate imported into the Windows Local Machine Certificate Store to SSL-enable the eG manager. The broad steps to be followed in order to achieve this are listed hereunder:

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 the Windows Local Machine Certificate Store
Configuring Tomcat for using the certificate

Each of these steps has been discussed in the sections that follow.

Generating the 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]: 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 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 <EG_INSTALL_DIR>\manager\tomcat\webapps directory.

Generating a Certificate Request

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

Login to the eG manager and go to the Windows command prompt.
Set the java_home path if it is not done already.
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 the 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 the 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 the 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 ).
- -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 Certificate from Windows Local Machine Certificate Store).
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

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.
The certificate will thus be generated. Download the certificate.
We recommend that you obtain the certificate in one of the following formats:
- P7B format: PKCS#7 or P7B extension means one or more Base64 ASCII certificates stored in a .p7b or .p7c file (container). The P7B file contains the certificate and its chain (intermediate certificates) but does not contain the private key.
- A chain of certificates: . 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 is governed by a certificate hierarchy. 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.
- PFX / PKCS#12 format: This is a binary format for storing a certificate (including its intermediate) with a private key. Certificates and private key are password protected in the PFX file (container).
- 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.
Make sure that you copy the downloaded certificate to the <EG_MANAGER_INSTALL_DIR>\manager\tomcat\webapps folder.

Importing the Certificate into the Windows Local Machine Certificate Store

Once the certificate is obtained in the recommended format, it needs to be imported into the Windows Local Machine Store. For this, follow the steps below:

Login to the eG manager host.
Open the command prompt and run the following command:

certlm.msc
Figure 1 will appear. Expand the Personal sub-node under the Certificates - Local Computer node in the left pane. Then, click on the Certificates node within (seeFigure 1). The right pane will change to list the existing certificates.

Figure 1 : Viewing list of Local Machine Personal Certificates
Next, proceed to import the certificate that was obtained using the procedure discussed in Obtaining the Certificate from the CA. For that, right-click on the right pane of Figure 1. From the menu that pops out, follow the menu sequence, All Tasks -> Import (see Figure 2).

Figure 2 : Selecting Import Option
The Certificate Import Wizard will then appear (see Figure 3). Set Local Machine as the Store Location and click the Next button to proceed.

Figure 3 : Setting Store Location
This will invoke Figure 4. Use the Browse button in Figure 4 to specify the location of the certificate file to be imported. Then, click the Next button to move on.

Figure 4 : Specifying the certificate file to import
Figure 5 will then appear, only if the private key is password-protected. Here, type the password that protects the private key that you generated using the procedure described in the Generating the Keystore File. Make sure that the password you provide in Figure 5 is the same as the -keypass you specified when generating the keystore.

Figure 5 : Specifying the private key password
Then, click the Next button in Figure 5.
Figure 6 will then appear. Select Personal from the Certificate Store drop-down in Figure 6, so that the certificate is imported into the Personal store. Then, click the Next button in Figure 6.

Figure 6 : Choosing to store certificate in Personal store
This will open Figure 7. Click the Finish button in Figure 7 to complete the import and exit the wizard.

Figure 7 : Clicking Finish to exit wizard
The imported certificate will then appear in the list of Personal certificates, as indicated by Figure 8.

Figure 8 : Imported certificate listed in the list of Personal certificates
Now that the certificate is imported, proceed to grant private key access to the Tomcat service account. However, before proceeding, you need to confirm the following:
- Confirm that the certificate you imported has a 'private key'.
- Confirm that the Enhanced Key Usage property of the certificate is set to Server Authentication
- Make sure that the eG manager's host name is set as the Subject Alternative Name of the certificate.
Read on to know how each of these checks can be performed.
To confirm that the certificate has a private key, first click on the certificate displayed in Figure 8. Figure 9 will appear. If the General tab page of the Certificate dialog box displays the message indicated by Figure 9, it is a clear indicator that the certificate has a private key.

Figure 9 : Confirming that certificate is secured by a private key
Next, check the value of the Enhanced Key Usage property of the certificate. For that, click on the Details tab page in the Certificate dialog box. Figure 10 will appear listing the attributes of the chosen certificate. Browse the list of properties to locate the Enhanced Key Usage property. Make sure that its value is Server Authentication, as indicated by Figure 10.

Figure 10 : Confirming that EKU is set to Server Authentication
Then, keep browsing the list of attributes in Figure 10 until you find the Subject Alternative Name of the certificate. Confirm that this is set to the host name of the eG manager, as indicated by Figure 11.

Figure 11 : Confirming that eG manager host name is set as SAN
If all these checks provide the desired results, then proceed to grant private key access to the Tomcat service account. For that, right-click on the certificate displayed in Figure 12. From the menu that pops up, follow the sequence: All Tasks -> Manage Private Keys

Figure 12 : Choosing Manage Private Keys option
This will invoke Figure 13. Click on the Add button under the Group or user names section in Figure 13. Figure 14 will then appear.

Figure 13 : Adding new permissions
In the Enter the object names to select text area in Figure 14, type Local Service. Then, click the Check Names button to check the authenticity of the object name that you typed. If the object name you entered is valid, then your entry will automatically switch to caps and will be underlined (as indicated by Figure 14).

Figure 14 : Entering Local Service as object name
Then, click the OK button in Figure 14. You will return to Figure 12, but this time the Group or user names list will display the Local Service object you added recently (as shown by Figure 15). Click Apply and then OK in Figure 15 to save the changes.

Figure 15 : Local service granted at least Read permissions

Configuring Tomcat for Using the Keystore File

To SSL-enable the eG manager, you need to configure the server.xml file of Tomcat with the details of the Windows Local Machine Certificate Store.

Edit the server.xml file in the <CATALINA_HOME>\conf directory.
By default, Tomcat is configured to look up the Java Keystore for certificates. However, in our case, Tomcat should access the certificate from the Windows Local Machine Certificate. To override Tomcat's default setting, you should first instruct Tomcat to ignore Java Keystore specifications, To this effect, comment the APR/OpenSSL lifecycle listener block in the server.xml file as indicated below:
Next, 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>
Now, replace the code block above with the code block below:

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

port="<eG_Manager_SSL_Port>" sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"

scheme="https" secure="true" SSLEnabled="true" enableLookups="false" acceptCount="12000"

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

maxPostSize="-1" maxKeepAliveRequests="1" maxConnections="1536" processorCache="10000"

socket.processorCache="10000" URIEncoding="UTF-8" useSendfile="false" tcpNoDelay="true" compression="force"

compressibleMimeType="font/woff,font/woff2,text/html,text/xml,text/plain,application/x-java-applet,image/svg+xml,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_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384,TLS_AES_128_CCM_8_SHA256,TLS_AES_128_CCM_SHA256"

certificateVerification="none" protocols="TLSv1.2+TLSv1.3" sslProtocol="TLS">

<Certificate certificateKeystoreType="Windows-MY-LOCALMACHINE"

certificateKeystoreFile=""

certificateKeyAlias="<Value_of_Issued_To_Column>"

certificateKeystorePassword=""/>

</SSLHostConfig>

<UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />

</Connector>
After replacing, 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_SSL_Port>" sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"

scheme="https" secure="true" SSLEnabled="true" enableLookups="false" acceptCount="12000"

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

maxPostSize="-1" maxKeepAliveRequests="1" maxConnections="1536" processorCache="10000"

socket.processorCache="10000" URIEncoding="UTF-8" useSendfile="false" tcpNoDelay="true" compression="force"

compressibleMimeType="font/woff,font/woff2,text/html,text/xml,text/plain,application/x-java-applet,image/svg+xml,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_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384,TLS_AES_128_CCM_8_SHA256,TLS_AES_128_CCM_SHA256"

certificateVerification="none" protocols="TLSv1.2+TLSv1.3" sslProtocol="TLS">

<Certificate certificateKeystoreType="Windows-MY-LOCALMACHINE"

certificateKeystoreFile=""

certificateKeyAlias="<Value_of_Issued_To_Column>"

certificateKeystorePassword=""/>

</SSLHostConfig>

<UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />

</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 the following parameters:
- certificateKeystoreType: The value of this parameter should represent the key store/certificate store in which the eG manager's SSL certificate resides. Since our certificate is stored in the Windows Local Machine Certificate Store, make sure that this parameter is set to "Windows-MY-LOCALMACHINE"as indicated in the code block above.
- certificateKeystoreFile: This parameter is not applicable if you are using a certificate from the Windows Local Machine store. So, let the value of this parameter be empty, as indicated in the code block above.
- certificateKeyAlias: To configure this parameter, do the following:
  - Go to the command prompt on the eG manager host and run the certlm.msc command.
  - Figure 1 will appear. Expand the Personal sub-node under the Certificates - Local Computer node in the left pane. Then, click on the Certificates node within (see Figure 1). The right pane will change to list the existing certificates.
  - Locate the eG manager's SSL certificate therein and click on it to open the Certificate dialog box.
    
    Figure 16 : Copying the value displayed against Issued To
  - Next, copy the value displayed against Issued To in the General tab page of the dialog box.
  - Paste that value against certificateKeyAlias in the server.xml file.
- certificateKeystorePassword: If the private key is protected using a password, then specify the password here. Make sure that this password is the same as the -keypass you specified when generating the keystore (refer Generating the Keystore File). If the private key is not password protected, then you can leave the value of this parameter blank, as indicated in the sample code block above.
With that change, the eG manager on Windows 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:
Save the file.
Then, SSL-enable the start_manager.bat script. For this, first open the start_manager.bat file residing in the <EG_INSTALL_DIR>\lib directory. Change the URL http://<eGmanagerIp>:<eGmanagerdefaultTCPPort>/final/servlet/upload present in the last line of the batch file to https://<eGmanagerIp>:<eGmanagerPort>/final/servlet/upload.

Figure 17 : SSL-enabling the start_manager script
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 <EG_INSTALL_DIR>\manager\config directory) begins with https:// instead of http://. Then, save the file.
Finally, start the eG manager.