Tomcat CSR and SSL Certificate Installation and Renewal
Posted by Aly Essa, Last modified by Aly Essa on 08 July 2016 10:14 AM

Environment

FileCatalyst Workflow and Webmail all versions.

Overview

This article will give a quick walkthrough of the installation procedure or the upgrade of an SSL Certificate with the generation of a Certificate Signing Request (CSR).

For an additional fee, our FileCatalyst Support team can assist you with this process. Please contact your account representative for more details. This fee is waived if the SSL Certificate is purchased from FileCatalyst. We use Thawte as our Trusted Certificate Vendor.

These instructions assume you acquired your certificate from Thawte and that steps from another provider may differ.

Note: To renew or upgrade an existing certificate please follow the same steps as for a new certificate, however, use a different name for the keystore file, for example, -keystore .keystoreNew

 

Resolution

Note: For the purposes of this article we will reference a Windows Environment and related file paths.

  1. Install Java JDK:

    Use the following guide to Install the Java Development Kit (JDK) on your Operating System: http://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html

  2. Generating a Certificate Signing Request (CSR):
    By default Tomcat will expect password to be "changeit". If you choose a different password you will have to make an additional change in the server.xml file.
    1. Open a Command Prompt.

    2. Navigate to the bin directory located inside the JDK Install location. A sample path looks like C:\<Path to JDK installation>\bin\

    3. Create a new folder on your system to store the Tomcat SSL. We used the following command:
      mkdir C:\Tomcat-SSL\

    4. Navigate to the Tomcat-SSL directory, by using the command:
      cd C:\Tomcat-SSL\

    5. Steps to Generate a Certificate Signing Request (CSR):

        1. Use the keytool command to create the CSR. Use the following command to execute the process:

          keytool -keysize 2048 -genkey -keyalg RSA -alias tomcat -keystore .keystore

        2. The following prompts will be displayed. Fill them out with your Company’s information:

          1. Enter keystore password: changeit

          2. What is your first and last name?
            [Unknown]: Must contain fully qualified domain name e.g.: www.mydomain.com

          3. What is the name of your organizational unit?
            [Unknown]: FileCatalyst Testing (example)


          4. What is the name of your organization?
            [Unknown]: FileCatalyst (example)


          5. What is the name of your City or Locality?
            [Unknown]: Ottawa (example)


          6. What is the name of your State or Province?
            [Unknown]: Ontario (Must contain no abbreviations)


          7. What is the two-letter country code for this unit?
            [Unknown]: CA (example)


          8. Is CN= www.mydomain.com , OU= FileCatalyst testing , O= FileCatalyst , L= Ottawa, ST= Ontario , C= CA correct?
            [no]: yes


          9. Enter key password for <tomcat>
            Press Enter if same as keystore password. Please specify the same password (changeit) for the .keystore and the keyEntry. If there was an error in the process you will receive the following error message when you restart the Tomcat Engine: 

            java.security.UnrecoverableKeyException: Cannot recover key

        3. Observe that a .keystore file was created.

        4. Run the following command to make sure you can read the .keystore file: 

          keytool -list -keystore .keystore

        5. The .keystore will be stored in the  C:\<Path to JDK installation>\bin\ directory.

        6. Create a copy of the .keystore file and store it on a removable disk for safekeeping in case of a server crash.

  3. Generate a CSR off the newly created .keystore and keyEntry:
     
    1. Open the Command Prompt.

    2. Navigate to the Tomcat-SSL directory, by using the command:

       
      cd C:\Tomcat-SSL\

    3. Run the following keytool command in a Command Prompt:

      keytool -certreq -alias tomcat -keyalg RSA -file <newcertreqname>.csr -keystore .keystore

    4. You will be prompted to enter the keystore password. The following output will be observed:

      Enter keystore password: changeit

      The CSR will be saved to your C:\Tomcat-SSL\ directory


      -----BEGIN NEW CERTIFICATE REQUEST-----

      Hash Contents

      -----END NEW CERTIFICATE REQUEST-----

  4. Send the CSR file to your Certificate Authority (CA). If you want to use a self-signed SSL certificate, you can skip this step and proceed to step 7. A self-signed certificate will always display a warning to the end user that the certificate is not valid since it was not issued by a Certificate Authority. This type of SSL certificate will also affect some Java web applications including UnlimitedFTP Servlet, FileCatalyst Webmail, and FileCatalyst Workflow. 

  5. Certificate Download and Format:

    1. When you receive the certificate from the Certificate Authority, download it in PKCS#7 format.

    2. Open the signed Certificate in Notepad or a text editor.

    3. If you obtained a certificate and it was not sent to you in PKCS#7 format, you must do these additional steps:

      1. Copy and paste the signed certificate from the email into Notepad or a text editor.

      2. Save the certificate as <yourcertname>.cer file.

      3. Double-click on the <yourcertname>.cer file and click on Install Certificate.

      4. Place the Trusted Certificate in your Personal Store.

      5. For Thawte certificate, download the Primary and Secondary Intermediate CAs for SSL 123. Make sure you download them as a .cer format.

      6. Install them by repeating steps 5c-iii.

      7. Open the Run Command on your computer and type in Certmgr.msc to open the Certificate Manager.

      8. Under Certificate for Current User, select Personal and expand the Certificates Folder.

      9. You should see your certificate that you imported as well as Thawte’s Primary and Secondary Intermediate Certificates.

      10. Right-Click on your certificate. Click on All Tasks, then hit Export.

      11. Select Cryptographic Message Syntax Standard - PKCS #7 Certificate (.p7b) and make sure to check Include all certificates in the certification path if possible.

      12. Save the file as <certname>.txt, under the C:\Tomcat-SSL\folder.

  6. Import the Certificate into the .keystore:

    1. Run the following command to import the signed certificate into the .keystore:

      keytool -import -alias tomcat -trustcacerts -file <certname>.txt -keystore .keystore

  7. Deploy the Trusted Certificate and .keystore into Tomcat:

    1. Tomcat keeps its configuration information in the <PathtoTomcatHome>\conf\server.xml file, make sure that port 8443 is not already in use and that it is enabled on your firewall. Using a text editor open server.xml file and make the changes to the Connector:

      For Tomcat 7 and 8:
       
             <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"
                 maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="<Path-to-keystore>/.keystore" keystorePass="changeit"/>

      Specify the path to your keystore file in keystoreFile="c:\tomcat-ssl\.keystore". If your keystore password is not "changeit" then make the change to keystorePass="changeit" in the factory element. If a specific port does not need to be specified in the URL, such as https://mycompany.com:<port>, then port 443 should be specified in the connector. This change will provide seamless integration.

Notes: