How to install or renew an SSL Certificate in the 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
• Clearwell Utility-Generated Certificate
• Provider-Generated Certificate
• Importing the Provider-Signed Certificates into the Java Keystore

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:
• Encryption 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.
Note:  CName aliases are usually only available from internal Certificate Authorities as they are typically unroutable.
• 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. As browser vendors continue to tighten the security of their product, one recent change has been to implement the recommendation in RFC-2818.  In 2012, this RFC recommended using subjectAltName for certificate validation over the subject common name, i.e., the FQDN in first line when creating the server keystore in step A.4 above. It is recommended to use the Subject Alternative Name (SAN) option when creating new server keystores for the eDiscovery platform going forward.  This will prevent receiving errors such as "Not Secure" or "SSL_ERROR_BAD_CERT_DOMAIN".
    
2. 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 -ext san=dns:<dns_name1>,dns:<dns_name2>
   
   • Replace the <dns_name#> with the FQDN of the server(s) this certificate will secure.
   • You may add as many dns_name options as required separated by a comma, including a CName alias if the certificate will be generated by an internal Certificate Authority. 
   
   Notes: 
   • The FQDN used to create the Java keystore above must be included as only the names listed in the SAN option are used for certificate authentication.
   • Use the SAN option even if the only entry is for the FQDN of the subject server.
   
   Subject Alternative Name By IP address:
   -ext san=IP:###.###.###.###,IP:###.###.###.###
   
   Note: The IP address option is not recommended as IP address are more frequently subject to change.
   
   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.
   • The name of the output, my.csr, can be changed to reflect the name of your eDiscovery appliance.

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

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

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:

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 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:

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.  The exception is in the case where a remote, shared MySQL database server is used. A remote, shared data MySQL database server does not employ Java and is only accessed by the eDiscovery nodes on port 3306 using encrypted credentials.

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 .