SSL Enabling the Webhooks Service Using a Signed Certificate Obtained from a Valid Certifying Authority

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 the Webhooks Service to Use SSL

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 host, where the Webhooks service is deployed, 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 certificate 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 fully qualified domain name of the Webhooks service 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 the eG agent will be accessing the Webhooks service. For instance, if the public HTTPS URL of the Webhooks service is https://webhookO365.eginnovations.com, where webhookO365.eginnovations.com is the fully qualified domain name of the service, then specify webhookO365.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 file to a different location on the same host.

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 same Windows host on which the keystore file was generated. Then, 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 Generating a Keystore File).

  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.

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.

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

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

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

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

  2. 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 above for details.

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

    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 –aliasegitlab1-deststorepassmykey -destkeypassmykey -destkeystorekeystore,jks -srckeystorekeystore.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 the Webhooks Service to Use SSL

For this, do the following:

  1. Login to the system hosting the eG remote agent.

  2. Edit the webhooks.properties file in the <EG_AGENT_INSTALL_DIR>\Webhooks\config folder on the agent host.

  3. Against the server.port parameter in the file, enter the port number at which the Webhooks service listens.

  4. Then, under the #SSL Key Info section, specify the following:

    • Set the security.require-ssl flag to true.

    • Against the server.ssl.key-store, specify the full path to the keystore file on the eG agent host.

    • Against the server.ssl.key-store-password, specify the password using which the keystore (containing the SSL certificate) is protected. It is recommended that you encrypt the password and then specify the same in the .properties file. To encrypt the password, go to the command prompt of the eG agent host, and then switch to the <EG_AGENT_INSTALL_DIR>\lib directory. From that directory, run the obs.bat command. You will now be prompted to enter the password that you wish to encrypt. Specify the password and press the Enter key on the keyboard. The password will be instantly encrypted. Copy this password and paste it against the server.ssl.key-store-password parameter in the .properties file.

    • Enter the certificate type against server.ssl.key-store-type.

  5. Next, enter the notification endpoint's public HTTPS URL against the WebhookURL parameter. Make sure that the fully qualified domain name used in this URL is the same as the fully qualified domain name used when generating the keystore file (see Generating a Keystore File).

  6. Finally, save the file. depicts a fully-configured webhooks.properties file.

    Figure 1 : A sample webhooks.properties file with all parameters fully configured