Tools

Creating a new keystore to install the SSL Certificate in the Web Help Desk (WHD)

This article will provides step-by-step instructions how to create a keystore, generate a new certificate signing request (CSR), and how to install the SSL Certificate via Portecle.

First published date

7/24/2019 3:27 AM

Last published date

6/7/2023 4:48 AM

Overview

What is a Keystore?

Java Keystore is the storage facility for cryptographic keys and certificates.  A keystore is required to store and install a valid SSL Certificate for WHD (using Portecle).


What is a Certificate Signing Request (CSR)? What is the purpose of a CSR?

Certificate Signing Request (CSR) file will contain all of the necessary information (i.e. Common Name, Organization Name, City, State and Country) that the Certificate Authority (CA) will use to validate and provide a signed certificate.  

It is important to note that during the CSR creation process a corresponding private key will be created and stored in the keystore.  Once the CA has provided a signed certificate, this can only be installed to the matching private key.  If the certificate is installed to a different keystore, the installation will fail and a new keystore and CSR must be generated again.


Note: If the certificate was installed on a different server and exported with the private key in PFX format (Windows) or P12 format (Linux-based), please follow this article.  

Product section

Web Help Desk

Cause

When installing a SSL certificate, this must be installed in the Java keystore where the CSR was generated from.
  1. If a certificate was renewed by the CA without submitted a new CSR file, then installation will fail.  If this occurs, a new CSR must be created and submitted to the CA to obtain a new SSL certificate.
  2. If the keystore is missing and a new keystore was created, then the installation will fail.  A new CSR file must be submitted to the CA.

Resolution

How to create a new keystore.jks file:

Important! Back up the keystore.jks and whd.conf (located in C:\Program Files\WebHelpDesk\conf) before edit the file.
  1. Stop WHD
  2. Navigate to C:\Program Files\WebHelpDesk\conf
  3. To enable the HTTPS port, uncomment the line "HTTPS_PORT=8443" by taking off the '#' hash character. 
  4. Start WHD
  5. Open the Portecle.bat file found in the "C:\Program Files\WebHelpDesk" directory.
  6. Click File > Open Keystore File
  7. Navigate to C:\Program Files\WebHelpDesk\conf\ 
  8. Select keystore.jks
image.png
 
  1. It will ask for a password. By default, password is changeit
    • The password can be found in the whd.conf file in C:\Program Files\WebHelpDesk\conf
  2. To create/generate a new key pair. Delete the present key pair named/aliased "tomcat".
image.png
  1. Select Tools > Generate Key Pair
  2. Enter the necessary details:
    • Common Name (CN) is the fully qualified domain name for the WHD server
    • Organization Unit: Friendly name for the Org Unit
    • Organization Name: Legal Business Name
    • Locality: City Name
    • State: State Name
    • Country: Country Name
    • Email: Optional
    • Subject Alternative Name: If additional FQDN names exists for WHD
 
Machine generated alternative text: Generate Key Pair Key Algorithm: Key Size: 20481
 
image.png
 
Machine generated alternative text: Key Pair Entry Alias Enter Alias: tomcat
 
  1. Click OK
  2. It will prompt you to type a password. The password should be the same in the whd.conf file. By default, KEYSTORE_PASSWORD=changeit.
image.png
  1. Right-click on tomcat and click Generate Certification Request
image.png
 
  1. Save the file and submit the CSR file to the CA provider
  2. Click File > Save Keystore


How to import the SSL Certificate (DER or PEM format):

Note: Create a backup copy of keystore.jks before making any changes.
  1. Stop WHD
  2. Navigate to C:\Program Files\WebHelpDesk
  3. Open the Portecle.bat
  4. Click File > Open Keystore File
  5. Navigate to C:\Program Files\WebHelpDesk\conf\ 
  6. Select keystore.jks
  7. Enter the password. By default, the password is changeit
    • The password can be found in the whd.conf file in "C:\Program Files\WebHelpDesk\conf".
  8. Go back to your certificate and extract the root and intermediate files.
  1. Import the root certificate first, select Tools > Import Trusted Certificate.
 
 image.png
  1. Select the root certificate, then click OK
 
image.png
  1. When the certificate details pop up, click OK.
  2. Click Yes to accept the certificate as trusted.
 
image.png
  1. Click OK. No need to rename the alias.
 
image.png
  1. Repeat steps 10-14 to import the intermediate certificate(s)
  2. Right-click tomcat
  3. Select Import the CA reply
 
image.png
  1. Select the public key file provided by the CA.
  2. Save the keystore file.
  3. Start WHD.  


Note:

Most Certificate Authority providers will provide certificate in multiple formats:

  1. PKCS#7 format will include the CA Root and Intermediate Certificates along with the signed certificate.  Follow the steps in the article to extract the Root and intermediate certificates from the bundle.
  2. DER or PEM format will be the only signed certificate.  A separate CA bundle (intermediate and/or root certificate) should be provided and imported to the keystore.
  3. PFX or P12 format can only be generated after the SSL certificate is installed.  If the certificate was installed on a different server and exported in a PFX / P12 format, then using the following article: How to import PFX SSL certificate in Web Help Desk.