Skip to main content

This article applies to version 6.

Available in:

StandardPremiumEnterprise
Small Business
Code42 Support

Install a CA-signed SSL certificate with the Java keytool

Overview

Every Code42 server includes a self-signed certificate to support secure HTTPS connections. That certificate enables encryption of client-server communications, but it cannot adequately identify your server and protect your clients from counterfeiters. This article describes how to configure a more secure option: using the Java keytool to create an SSL/TLS certificate signed by a trusted certificate authority (CA). 

Other articles describe other tools for creating a CA-signed certificate:

  • The KeyStore Explorer provides a graphical user interface for managing certificates and keystores.
  • Linux administrators typically use OpenSSL.

Server security requires a CA-signed certificate and the TLS protocol
Reliable security of any production web server requires an SSL certificate signed by a trusted certificate authority (CA) and enforced use of the TLS protocol (i.e. HTTPS, not HTTP).

Your on-premises Code42 authority server is no exception. A Code42 server that is configured to use a signed certificate, strict TLS validation, and strict security headers protects server communications with browsers, your Code42 apps, and other servers.

  • By default, your authority server uses a self-signed certificate and TLS. That provides for encrypting client-server traffic.
  • Adding a CA-signed certificate provides further security by confirming your server's identity to clients. It prevents attackers from acquiring client data through counterfeit servers and encryption keys.
  • Never reconfigure a production server to use HTTP, rather than TLS and HTTPS.
  • Configuring Code42 servers and apps to use strict TLS validation further ensures the security of client-server connections.
  • Configuring Code42 servers to use an HTTPS Strict Transport Security (HSTS) response header further prevents unencrypted browser access to administration consoles.

Before you begin

  • Consult your security or web administrators to learn about your organization's existing keys, certificates, and keystores. Determine whether you will:
    • Generate a new key and get a new CA-signed certificate for it.
      In this case, find the address of the CA your organization uses. Once you request a signed certificate from a CA, the CA's reply my take as long as a week.
    • Import existing keys and certificates, or an existing keystore, that will work in your Code42 server's domain.
      Signed certificates secure specific domain names or ranges of subdomains. Your organization may have certificates for *.example.com. A wildcard certificate works for multiple subdomains, including authority-server.example.com.
  • Once you have a Java keystore for your Code42 server's domain, sign in to your administration console, and import the keystore for your Code42 server's use. Importing requires the Administrator or SYSADMIN role.
  • Importing a keystore requires briefly stopping and restarting your Code42 server. Consider stopping and restarting your Code42 server during low-traffic hours.
  • If you import a certificate and key with exceptionally strong encryption, first configure your Code42 server to accept longer keys.
Need help?
Assistance creating a keystore or handling a certificate signing request (CSR) are beyond the scope of Customer Champions. For assistance, please contact your Customer Success Manager (CSM) for enterprise support at csmsupport@code42.com.

Terminology

These instructions use the following terms:

  • Key: A unique string of characters that seeds a mathematical algorithm for encryption and decryption. Keys come in pairs. A public key encrypts data to be decrypted with the corresponding private key.
  • Certificate: A file that contains a public key and identifies who owns that key and its corresponding private key. In a signed certificate, a trusted certificate authority (CA) affirms that a public key does indeed belong to the owner named in the certificate. A certificate chain links a public key to a widely trusted root certificate.
  • Keystore: A file that holds a combination of keys and certificates.
  • PKCS, PFX: A binary format for key, certificate, and keystore files. Typical file names are *.pkcs, *.p12, *.p7b, *.pfx
  • Java keystore: The binary format for keystores used by Code42 servers. Typical file names are .keystore and *.jks
  • PEM: An ASCII text format for keys and certificates. Typical file extensions are *.pem, *.key, *.csr, *.cert. The binary counterpart is DER-format file. An X.509 certificate may or may not be in PEM format.

To identify a PEM file, read it with a console or text editor. If you see ASCII text, it's a PEM file.

PEM file example

Configure the keytool command

The Java keytool installs as part of a system's Java runtime engine (JRE) and runs at the Windows or Linux command line. To use keytool, install it on your system and configure its use as described below.

Windows

  1. Download and install a recent version of the JRE from Oracle.
  2. Locate the keytool with two commands.
    The second command returns the location of keytool.exe.
    cd \
    dir /b/s keytool.exe
  3. Add the directory where keytool.exe resides to the PATH variable.
    PATH=%PATH%;<directoryWhereKeytool.exeResides>
    For example:
    PATH=%PATH%;C:\Program Files\Java\jre1.8.0_111\bin
  4. Return to a directory that belongs to your user name:
    cd \Users\<yourusername>
  5. Repeat steps 2 and 3 for any terminal window in which you want to use the keytool command.

Keytool

Linux

Install a recent version of the JRE with commands like the following:
sudo apt-get update
sudo apt-get install default-jre

Create a keystore

Create a keystore using one of the following options:

  • Option 1: Create a new key and Java keystore; import a CA's signature.
  • Option 2: Package existing PEM-format keys and certificates in a new Java keystore.
  • Option 3: Convert an existing PKCS or PFX keystore to a Java keystore.

Option 1: Create a new key and Java keystore; import a CA's signature

Step 1: Create a keystore and a signing request

Create a Java keystore and a request for a CA to sign your public key.

Help writing commands
For help writing these commands, see DigiCert's Java Keytool CSR Wizard.
  1. Create the keystore with the command below, after substituting your value for one variable:
  • <your.domain.com>: the complete domain name of your Code42 server.
Enter the same password twice
The command will prompt you for two passwords. Supply the same value for both of them:
Enter keystore password:
Enter key password:
keytool -genkeypair -alias <your.domain.com> -storetype jks -keystore <your.domain.com>.jks -validity 366 -keyalg RSA -keysize 4096
  1. The command prompts you for identifying data.
    At "What is your first and last name" you must supply the domain name of the Code42 server you want to secure.
    Most CAs require values for the other fields as well.
What is your first and last name? <your.domain.com>
What is the name of your organizational unit? yourunit
What is the name of your organization? yourorg
What is the name of your City or Locality? yourcity
What is the name of your State or Province? yourstate
What is the two-letter country code for this unit? US
  1. Create the certificate signing request (CSR) with the command below, after substituting your value for one variable:
  • <your.domain.com>: the complete domain name of your Code42 server.
keytool -certreq -alias <your.domain.com> -file <your.domain.com>.csr -keystore <your.domain.com>.jks -ext san=dns:<your.domain.com> 

Step 2: Request a CA-signed certificate

  1. In the directory where you ran Step 1 above, find the file <your.domain.com>.csr
  2. Submit the file <your.domain.com>.csr to your CA.
    • Details vary from one CA to another. Typically, you submit your request via a website, then the CA contacts you to verify your identity.
    • CAs can send signed reply files in a variety of formats, and CAs use a variety of names for those formats. You want the CA's reply in PEM or PKCS#7 format.
  3. Wait (usually days or a week) for the CA's reply.

Step 3: Import the CA's reply

The CA's reply will provide one PKCS file or multiple PEM files. Import them into your keystore as follows:

  1. Copy the CA's files into the directory where you created the keystore in Step 1 above.
  2. Windows only: Configure the Keytool Command as described above.
  3. Use keytool  to import the CA reply files to your keystore
    (The commands will prompt you for your keystore password):
  • If the CA sent a PKCS file, use the command below, after substituting your values for two variables:
    • <your.domain.com> : The complete domain name of your Code42 server.
    • <CAreply.pkcs> : The name of the PKCS file provided by the CA.
keytool -importcert -alias <your.domain.com> -file <CAreply.pkcs> -keystore <your.domain.com>.jks -trustcacerts
  • If the CA sent PEM files, there may be one file, but most often there are two or three. Import the files to your keystore with commands in the order shown below, after substituting your values for four variables:
    • <root.cert.pem> : The name of the root certificate file
    • <intermediate.cert.pem> : The name of the intermediate certificate file
      The root and intermediate files link the CA's signature to a widely trusted root certificate that is known to web browsers. Most, but not all, CA replies include roots and intermediates.
    • <your.domain.com> : The complete domain name of your Code42 server
    • <server.cert.pem> : The name of the server certificate file
      The file links your domain name with your public key and the CA's signature.
keytool -importcert -alias root -file <root.cert.pem> -keystore <your.domain.com>.jks -trustcacerts
keytool -importcert -alias intermediate -file <intermediate.cert.pem> -keystore <your.domain.com>.jks -trustcacerts
keytool -importcert -alias intermediat2 -file <intermediat2.cert.pem> -keystore <your.domain.com>.jks -trustcacerts
keytool -importcert -alias <your.domain.com> -file <server.cert.pem> -keystore <your.domain.com>.jks -trustcacerts
Troubleshoot
If you import certificates in the wrong order, the above commands return an error message. To resolve the error, you can:
  • Consult your CA.
  • Re-arrange the order of certificates and try again.
  • Read each certificate with the following command:
    keytool -printcert -file <filename.cert.pem>
    In the output, note the Owner and Issuer (signer) of each certificate. Order your import commands so that the Issuer of each certificate matches the Owner in the previous command.
  1. Proceed to configuring your Code42 server below.

Option 2: Package existing PEM-format key and certificates in a new Java keystore

If you have an existing private key and certificates for your Code42 server's domain, in PEM format, importing them into a Java keystore requires the OpenSSL tool. OpenSSL can package the PEM files in a PKCS keystore. Java keytool can then convert the PKCS keystore to a Java keystore.

  1. Install OpenSSL:
    • Windows: Download and install OpenSSL.
    • Linux: Verify that OpenSSL is installed by issuing the command openssl version
      If that returns an error, install OpenSSL with a command like sudo apt-get install openssl
  2. Gather your private key, server certificate, and intermediate certificate into one directory.
  3. Package the key and certificates into a PKCS keystore with the command below, after substituting your values for four variables
    (The command will prompt you for your keystore password):
    • <server.cert.pem>: The name of the server certificate file
      The file links your domain name with your public key and CA's signature.
    • <private.key.pem>: The private counterpart to the public key in <server.cert.pem>
    • <intermediate.cert.pem>: The name of the intermediate certificate file
      The file links the CA's signature to a widely trusted root certificate that is known to web browsers.
    • <your.domain.com> : The complete domain name of your Code42 server
openssl pkcs12 -export -in <server.cert.pem> -inkey <private.key.pem> -certfile <intermediate.cert.pem> -name "<your.domain.com>" -out <your.domain.com>.p12
  1. Convert the resulting PKCS keystore file, <your.domain.com>.p12 into a Java keystore. See Option 3, below.

Option 3: Convert an existing PKCS or PFX keystore to a Java keystore

If you have an existing PKCS or PFX keystore for your Code42 server's domain, convert it to a Java keystore.

  1. Windows only: Configure the keytool command as described above.
  2. Issue the command below, after substituting your values for two variables
    (The command will prompt you for keystore passwords):
    • <your.domain.com.p12> : The existing keystore file.
    • <your.domain.com> : The complete domain name of your Code42 server
keytool -importkeystore -srckeystore <your.domain.com.p12> -srcstoretype PKCS12 -destkeystore <your.domain.com>.jks -deststoretype jks
  1. Proceed to configuring your Code42 server below.

Configure your Code42 server to use your keystore

Step 1: Back up your Code42 server's database

As a best practice, back up your Code42 server's database:

  1. Open the administration console.
  2. Navigate to Settings > Server.
  3. From the action menu, select Dump Database.

Step 2: Import your keystore to your Code42 server

  1. In the administration console, select Settings > Security > Keys.
  2. At SSL, check Require SSL to access console.
  3. Click Import Keystore.
  4. Select your Java keytore file, <your.domain.com>.jks, and provide <yourpassword>.
  5. Return to the system command line and stop and restart the Code42 server:

Windows:
net stop CrashPlanPROServer
net start CrashPlanPROServer

Linux:
sudo /opt/proserver/bin/proserver stop
sudo /opt/proserver/bin/proserver start

  1. Give the server several minutes to start up, then return the browser to the administration console sign in page:
    https://<your.domain.com>:4285
  2. If the keystore import succeeds, your browser will show a secure connection icon padlock green means secure browser connection rather than an exception warning.
    Indicators vary by browser.

Web Browser Secure Connection

Troubleshoot

  • To see the contents of your Java keystore, use this command:keytool -list -keystore <your.domain.com>.jks

  • If your Code42 server fails to start after installing the new keystore, see Recovering Your Code42 Server To A Previous State.
  • Any problems that occur are most often related to key creation, signing, and conversion. We recommend:
    • Carefully repeat the process described above.
    • Consult with your CA to make sure you have the right intermediate certificates.
  • For additional help, contact your Customer Success Manager (CSM) for enterprise support at csmsupport@code42.com.