Install a CA-signed SSL certificate with the Java keytool

Last updated
Save as PDF

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 (that is, 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 Code42 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 may 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.
  
  Existing materials must include Subject Alternative Name (SAN)
  Certificates and keystores built to an older standard may lack the Subject Alternative Name (SAN) extension. Most browsers now distrust such certificates. If your existing certificates and keystores don't have the SAN extension, start over with a new certificate signing request.

Once you have a Java keystore for your Code42 server's domain, sign in to your Code42 console, and import the keystore for your Code42 server's use. Importing requires the Server Administrator or SYSADMIN role.

Build your keystore on any machine
You can generate keys and build keystores on any secure machine and then import the result, a *.jks file, to your authority server via the Code42 console. You do not need any further access to the authority server's host machine.
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, contact your Customer Success Manager (CSM) to engage our Professional Services team.

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

Download and install a recent version of the JRE from Oracle.
Locate the keytool with two commands.
The second command returns the location of keytool.exe.
cd \ dir /b/s keytool.exe
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
Return to a directory that belongs to your user name:
cd \Users\<yourusername>
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.

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

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

Create the certificate signing request (CSR) with the command below, after substituting your value for all four occurrences of 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

In the directory where you ran Step 1 above, find the file <your.domain.com>.csr
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.
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:

Copy the CA's files into the directory where you created the keystore in Step 1 above.
Windows only: Configure the Keytool Command as described above.
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.

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.

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
Gather your private key, server certificate, and intermediate certificate into one directory.
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

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.

Windows only: Configure the keytool command as described above.
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

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:

Open the Code42 console.
Navigate to Settings > Server.
From the action menu, select Dump Database.

Step 2: Import your keystore to your Code42 server

In the Code42 console, select Settings > Security > Keys.
At SSL, check Require SSL to access console.
Click Import Keystore.
Select your Java keytore file, <your.domain.com>.jks, and provide <yourpassword>.
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

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

Web Browser Secure Connection

Troubleshooting

If your test Code42 server fails to start after installing the new keystore, uninstall and reinstall the server.
If your production Code42 server fails to start after installing the new keystore, see Recover your Code42 server to a previous state.
Most problems with SSL certificates are related to key creation, signing, and conversion. We recommend that you:
- Carefully repeat the process described above.
- Check that your certificate and keystore files include the Subject Alternative Name (SAN) extension.
  Convert your keystore or certificate to text, as described below. Look for
  X509v3 Subject Alternative Name
- Consult with your CA to make sure you have the right intermediate certificates.
- Consult documentation for the tool you're using:
For additional help, contact your Customer Success Manager (CSM).

Automatically-generated self-signed certificates

Keys are kept in a keystore. Your authority servers or storage servers use the keys in the keystore to securely process transactions.

If a Code42 server cannot find keys, it searches for keystores with the following precedence:

The keystore in the database, uploaded in the Code42 console or by API. (To upload the keys in the Code42 console, navigate to Administration > Settings > Security > Keys.)
The keystore location on the server as configured by the c42.https.keystore.default system property. To verify the location, enter the following prop.show command in the Code42 console command-line interface (CLI): prop.show c42.https.keystore.default

If for some reason your Code42 servers cannot locate the keys in these locations, they generate a self-signed certificate to ensure uninterrupted operation of your Code42 environment. The automatically-generated self-signed certificate should only be used temporarily while you troubleshoot keystore issues. Code42 strongly recommends using a CA-signed certificate for production environments.

Convert certificates and keystores to text files

Certificate and keystore files are in binary or base64 formats. You can make them easier to read by converting files to PEM format and then converting PEM files to text, as follows:

Java keystore to PKCS

keytool -importkeystore -srckeystore <filename>.jks -destkeystore <filename>.p12 -srcstoretype jks -deststoretype pkcs12

PKCS to PEM

openssl pkcs12 -in <filename>.p12 -out <filename>.crt

PEM certificate to text

openssl x509 -text -in <filename>.crt > <filename>.crt.txt

PEM CSR to text (certificate signing request)

openssl req -text -noout -in <filename>.csr > <filename>.csr.txt

A certificate in readable text

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 4096 (0x1000)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C = US, ST = MN, O = CAsOrg, OU = CAsUnit, CN = CAsName The issuer is the CA who signed the certificate.
           Validity
            Not Before: Aug 15 13:50:25 2018 GMT
            Not After : Aug 15 13:50:25 2019 GMT This certificate's expiration date.
        Subject: C = US, ST = MN, L = YourTown, O = YourOrg, OU = YourUnit, CN = yourdomain.tld,
            emailAddress = you@yourcompany.tld Subject: You and the website this certificate validates.
        Subject Public Key Info: Your public key. Clients use it to encrypt messages.
            Public Key Algorithm: rsaEncryption 
                Public-Key: (2048 bit)
                Modulus:
                    00:aa:a4:de:e3:e3:d4:b9:f3:3d:1c:1e:b7:1b:69:
                    4f:5b:22:08:4b:75:81:54:91:8f:63:57:a8:0e:bd:
                    ...
                    ab:a3:21:3f:c4:28:1c:9a:4e:e4:f0:81:a2:ab:73:
                    b3:83
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Alternative Name: Most browsers require the SAN extension.
                DNS:yourdomain.tld
            X509v3 Basic Constraints:
                CA:FALSE
            Netscape Cert Type:
                SSL Server
            Netscape Comment:
                OpenSSL Generated Server Certificate
            X509v3 Subject Key Identifier:
                12:E8:E1:E5:65:57:BB:2A:1C:CC:E3:61:E8:5C:79:34:CF:DD:E3:B1
            X509v3 Authority Key Identifier:
                keyid:F3:16:90:68:9A:B2:85:40:A8:1D:F3:2D:78:B2:6D:4E:82:0C:B0:32
                DirName:/CN=Vera/OU=Vera/O=VeraCA/L=Roseville/ST=MN/C=US
                serial:10:00
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Server Authentication
    Signature Algorithm: sha256WithRSAEncryption
         29:52:6f:5a:de:26:44:50:ad:e3:33:7b:8d:ba:2e:b5:cb:d9:
         35:21:75:0c:6b:ea:e0:f4:d0:e3:72:8e:5d:9e:3b:02:bf:8f:
         ...
         81:45:8f:1f:71:45:13:0a:ec:f1:0c:70:30:f2:6f:73:cd:5c:
         55:41:b6:b6:0a:fc:fb:c9
-----BEGIN CERTIFICATE-----
MIIFpTCCA42gAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwWzELMAkGA1UEBhMCVVMx
CzAJBgNVBAgMAk1OMRUwEwYDVQQKDAxQaGlsTm9yY3Jvc3MxDTALBgNVBAsMBFZl
...
BeWBceJRAcqt2XtY/6HteHUxpxCbSPVcEZWw6dkrM4FFjx9xRRMK7PEMcDDyb3PN
XFVBtrYK/PvJ
-----END CERTIFICATE-----