How to add an SSL Certificate

How to add an SSL Certificate

Article: 100038277
Last Published: 2020-11-20
Ratings: 4 2
Product(s): eDiscovery Platform

Description

This document explains how to add an SSL Certificate for use with the eDiscovery Platform.  Below are links to the sections of this article:

Default Certificate

The eDiscovery Platform is shipped with a default self-signed certificate that does not have a valid trust chain.  As a result, users attempting access the application interface over HTTPS will receive the following error in their web browser every time they access the login screen.

There is a problem with this website's security certificate

Users can still proceed to access the interface by clicking Continue to this website.  Going through the steps to install this certificate will not suppress the message due to the unrecognized trust chain.

Clearwell Utility-Generated Certificate

Veritas provides a feature through the appliance's Windows Desktop Clearwell Utility to generate and install a self-signed certificate with the DNS name of the appliance. Note that the certificate generated through this feature will not be known by Internet Explorer trust chains.  As a result, users will receive the messages: There is a problem with this website's security certificate and Certificate Error warnings when they access the login screen. However, unlike the default certificate, if the user installs this certificate they will no longer receive these warnings.


Generating the self-signed certificate:

  1. From the Clearwell Utility (found on the appliance's Windows Desktop), Select Option 9 to Generate self-signed certificate.
  2. When prompted, enter the exact DNS name that end-users will ultimately use to access the appliance.
  3. Once complete, restart the Clearwell services using the Clearwell Utility.

Cluster Considerations

Since the eDiscovery Platform web interface for all appliances in a cluster is exposed to end users, a certificate is needed for each appliance in the cluster.

Provider-Generated Certificate

Overview

Deployments that require stringent security and/or those that wish to avoid browser warnings should obtain and install a certificate from a provider.  For new certificates or to change certificate providers, follow the instructions below to generate a new Certificate Signing Request (CSR), then generate a new keystore containing that certificate, and direct Clearwell to leverage this certificate.  If renewing an expiring certificate from the same Certificate Authority, it is only necessary to import the renewed certificate into the existing server.keystore file, as outlined in the Installation section below.

Steps to create a new SSL-enabled Java Keystore (JKS) file and Certificate Signing Request (CSR)

This section describes the process of generating a JKS file for the eDiscovery platform.  For further details, refer to Oracle's Java security documentation: https://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html

Note: The eDiscovery Platform uses Apache Tomcat (Catalina version) as the web server engine. This is important to know, since most certificates are generated based on the type of web server being secured. If Tomcat is not an option with your provider, use Apache instead. If you generate a certificate based on a different web server type (like Microsoft IIS), the certificate will not work with the eDiscovery Platform.

A.  Generate the new Java Keystore file

  1. On the eDiscovery appliance, create a working directory to contain the new Java Keystore file, Certificate Signing Request and Certificates.
  2. Open a command prompt in the working directory created in step 1.
  3. Create a new Java keystore using the following command:
    keytool -genkeypair -alias clearwellkey -keyalg RSA -keystore new-server.keystore

Optional Values:
• E
ncryption Strength: -keysize 2048 or 4096 (1024 if omitted)
Signature Algorithm: -sigalg SHA256withRSA (SHA1 if omitted)

4.  Enter keystore password: 123456
     Re-enter keystore password: 123456

What is your first and last name?
[Unknown]: Your_Appliance_FQDN or IP
What is the name of your organizational unit?
[Unknown]: Your_OU
What is the name of your organization?
[Unknown]: Your_Organization_Name
What is the name of your City or Locality?
[Unknown]: Your_City
What is the name of your State or Province?
[Unknown]: Your_State
What is the two-letter country code for this unit?
[Unknown]: Your_Country_Code
Is CN=Your_Appliance_FQDN or IP, OU=Your_OU, O=Your_Organization_Name, L=Your_City, ST=Your_State, C=Your_Country_Code correct?
[no]: yes

Enter key password for <clearwellkey)
     (RETURN if same as keystore password:  (Hit Return)

Screen Shot:

Notes:  
• By default, the keystore password must be 123456. If a different password is required by your organization, please open a support ticket through the Veritas Support Portal and refer to this article number.
• If your organization uses a DNS CName alias for end-user access to the eDiscovery Platform, do not use that alias as Your_Appliance_Name in the first line of the keystore creation above.  Instead, see the Subject Alternative Name option under Creating a Certificate Signing Request in the next section.
• The use of the eDiscovery Appliance IP address is not recommended as potential changes in your organization's DNS structure would require that a new Java keystore be generated.

B.  Create the Certificate Signing Request (CSR)

  1. In the working directory created in step A.1. above, run the following command to generate the CSR.
    keytool -certreq -keyalg RSA -alias clearwellkey -file my.csr -keystore new-server.keystore

    Optional Values:
    • If the Encryption Strength -keysize option was used when creating the Java keystore above, it needs to be added to the above keytool command when generating the CSR.
    • If your organization uses a DNS CName alias for end-users to access the eDiscovery Platform web service, then the alias' URL needs to be included in the CSR using the Subject Alternative Name (SAN) option outlined below.
    • The name of the output, my.csr, can be changed, for example,  to reflect the name of your eDiscovery appliance.

    By DNS name:
    -ext san=dns:<dns_name1>,dns:<dns_name2>, . . . 

    By IP address:
    -ext san=IP:###.###.###.###,IP:###.###.###.### . . .

    Note: The FQDN or IP address used to create the Java keystore above must be included as one of the SAN entries as only the  URLs listed in the SAN option are used for authentication.

  2. Copy the CSR file generated in Step 1 and forward it to your Certificate Authority, internal or external.  If you copy the text generated in the CSR file, you must include everything from "-----BEGIN", and bounded at the end by a string that starts with "-----END".

  3. You must acquire or convert your certificate in a form that can be imported in to Java via keytool.exe.  Java's SSL keytool can import X.509 v1, v2, and v3 certificates, and PKCS#7 formatted certificate chains consisting of certificates of that type. The data to be imported must be provided either in binary encoding format, or in printable encoding format (also known as Base64 encoding) as defined by the Internet RFC 1421 standard.

 

Importing the Provider-Signed Certificates into the Java Keystore

After you receive the provider-signed certificate from the Certificate Authority, it must be imported into the Java Keystore file created in step A.3 from which the CSR was generated.  Your provider may return the certificate chain in separate .cer files, typically Root, one or more Intermediate and the Server certificate or in a PKCS#7 format (extension .p7b) which contains the entire chain and from which the individual .cer files can be exported.

 

These steps will depend on your certificate provider. You should receive and follow the instructions from your certificate provider for installing the certificate into Sun's Java and/or Tomcat. Examples for several certificate providers are provided below. For certificate providers not listed in this document, contact Clearwell Support for further instructions.

Note: Use caution if using copy/paste with the examples below as some PDF clients do not copy/paste the "-" character properly into a Command Prompt.

To install the certificate

Before beginning taking any of the actions below, a remote connection will need to be established, such as Remote Desktop, to the Clearwell server and not in your Internet browser.

Note: If this is a certificate renewal that has not expired, the file(s) provided by the certificate provider can be installed using steps 1, 2, and 3 except that the install can be done directly to into CW\V<version>\config\templates\tomcat\server.keystore.

  1. Open a Command Prompt either from Start > Command Prompt or Start > Run and type cmd.
  2. Create a backup copy of the previously‐used keystore
     
    1. Make a new directory to contain the keystore.

      d:
      cd CW\V<version>\config\templates\tomcat

      (Press tab until the proper CW <version>, e.g. V91, V911 and etc..., is printed.)

      mkdir oldcerts && mv server.keystore oldcerts
       
    2. Go to the jdk directory.

      e.g. cd c:\ jdk-<version>-windows-x64\bin
       
    3. Copy the certificate provider’s certificates into intermediary files. Generally, there will be at least two intermediary files generated.
       
  3. Import certificates as shown in the appropriate examples.

    Comodo Example

    The following is an example of how to import certificates from Comodo:
keytool -import -trustcacerts -alias root -file AddTrustExternalCARoot.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias INTER -file ComodoUTNServerCA.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias clearwellkey -file EssentialSSLCA.crt -keystore new-server.keystore

GoDaddy Example

The following is an example of how to import certificates from GoDaddy:
keytool -import -trustcacerts -alias root -file valicert_class2_root.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias cross -file gd_cross_intermediate.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias intermed -file gd_intermediate.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias clearwellkey -file <SSL-cert-name>.crt -keystore new-server.keystore

Note: The root certificate for GoDaddy.com is typically a separate download and can be found at https://certs.godaddy.com/anonymous/repository.seam

Instant SSL Example

The following is an example of how to import certificates from Instant SSL:

keytool -import -trustcacerts -alias root -file AddTrustExternalCARoot.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias INTER -file ComodoUTNServerCA.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias clearwellkey -file EssentialSSLCA.crt -keystore new-server.keystore

Network Solutions Example

The following is an example of how to import certificates from Network Solutions:

keytool -import -trustcacerts -alias root -file AddTrustExternalCARoot.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias INTER -file NetworkSolutions_CA.crt -keystore new-server.keystore
keytool -import -trustcacerts -alias clearwellkey -file <SSL-cert-name> -keystore new-server.keystore

Note: Refer to “SSL Consideration Details” of the System Administration Guide (link below)

Thawte Example

The following is an example of how to import certificates from Thawte:

keytool -import -trustcacerts -alias clearwellkey -file <SSL-cert-file-name> -keystore new-server.keystore

Veritas Example

The following is an example of how to import certificates from Veritas:
keytool -import -trustcacerts -alias primaryIntermediate -file primary_inter.cer -keystore new-server.keystore
keytool -import -trustcacerts -alias secondaryIntermediate -file secondary_inter.cer -keystore new-server.keystore
keytool -import -trustcacerts -alias clearwellkey -file <SSL-cert-name>.cer -keystore new-server.keystore
 
4. Verify the imported certificate information in the keystore.
Note: For further review of the certificate entries dump the output to a text file by adding > cert.txt at the end of the command.
keytool -v -list -keystore new-server.keystore

5. Create a backup copy of the newly-created keystore.
Note: See Step 2 for detailed instructions.

6. Copy the newly created keystore to the SSL cert directory.
cp new-server.keystore d:\CW\V<version>\config\templates\tomcat\server.keystore

7. From the Clearwell utility, run option 7, Build Incremental Configuration Changes, to redeploy the Clearwell application.
Note: This step must be done in order to deploy keystore. Performing this action stops Clearwell services for a short duration (5-7 minutes), thus should be done at an appropriate time (when no users are logged in and no jobs are currently running).

8. Attempt to access the newly-secured site from a client computer by browsing to the fully-qualified domain name (FQDN) of the server, as used during the generation of the certificate signing request.

9. Verify server name, expiry date, and provider information is correct.

10. To populate the Windows Trust Store and JDK cacerts files, run the Copy Tomcat action in the Clearwell Commander utility on the desktop of each appliance.


Cluster Considerations

Since the eDiscovery Platform web interface for all appliances in a cluster is exposed to end-users, a certificate is needed for each appliance in the cluster.  A single certificate can be generated if the Subject Alternative Name method outlined in step B.1 above is used and the FQDNs, CNames and/or IP addresses of each node of the cluster is listed as a separate DNS authentication URL .
 

 

Was this content helpful?