Skip to main content
Code42 Support

Install your own SSL certificate with OpenSSL

Available in:

StandardPremiumEnterprise
Small Business
Applies to:

Overview

Every Code42 server includes a self-signed SSL certificate to support secure https connections. This approach is secure, but browsers nonetheless generate warnings and require visitors to allow exceptions. To eliminate those browser warnings, configure your Code42 server to provide an SSL certificate signed by a trusted certificate authority (CA). This article describes how to use OpenSSL on Mac or Linux to create a keystore for your Code42 server.

Two other articles describe other tools for achieving the same end:

  • The KeyStore Explorer provides a graphic interface for managing certificates and keystores.
  • Windows users typically rely on the Java keytool rather than OpenSSL.

Before you begin

Keys and certificates on the web

A Code42 server uses the same kinds of keys and certificates, in the same ways, as other web servers. This article assumes you are familiar with public-key cryptography and SSL certificates. See the Terminology section below for more concepts included in this article.

Getting a signed certificate from a CA can take as long as a week. Therefore, creating a keystore from scratch using this process will include a break while you wait to receive the signed certificate from your CA.

Keys and certificates in the Code42 environment

  • This article is for administrators running Code42 servers on Linux systems.
  • This article describes use of two command-line tools: OpenSSL and Java keytool. OpenSSL is built into most Linux distributions. Java keytool installs as part of a system's Java Runtime Engine (JRE). If either is not present, do the following:
    • Mac:
      Download and install OpenSSL from the OpenSSL web site.
      Download and install a JRE from Oracle's web site.
    • Linux: Issue these commands:
      sudo apt-get install openssl
      sudo apt-get install default-jre
  • A Code42 server requires keys and certificates wrapped in a Java keystore file.
  • Once you have a signed keystore, you 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.

CODE42 INTERNAL USE ONLY
In environments with multiple authority servers, SSL certificates must be uploaded to each authority individually. There are three options:

  1. In your certificate signature request, use a wildcard to specify a range of domain names for all your servers, for example, *.domain.com. Upload the resulting keystore to all your servers.
  2. Create a signature request with a SAN field (subject alternative name) that specifies the domain names of all your servers. Upload the resulting keystore to all your servers.
  3. Create and upload individual keystores to each authority server, then do SSL offload at the load balancer layer with the SSL certificate of the cluster address.

Keys and certificates in your organization

Consult your security or web administrators to learn about your organization's existing keys, certificates, and keystores. Determine whether you will:

  • Generate a new keystore and get a new CA-signed certificate for it
    In this case, find the address of the CA your organization uses.
  • Import existing keys, certificates, or keystore for your Code42 server's domain.
Need help?
Assistance creating a keystore or handling a certificate signing request (CSR) are beyond the scope of Customer Champions. For assistance, please contact sales about engaging our PRO Services team.

Terminology

These instructions use the following terms:

  • Key: A unique string of characters that provides essential input to a mathematical process for encrypting data.
  • Key Pair: A public encryption key and a private encryption key, in a matched set.
  • Public Key: Allows a sender (client or server) to encrypt a message for a specific recipient (server or client). When your server sends a browser its public key, the browser can encrypt messages that only your server can read, because only your server has the matching private key.
  • Self-Signed Certificate: A file that contains a public key and identifies who owns that key and its corresponding private key.
  • CA-Signed Certificate: A certificate authority (CA) electronically signs a certificate to affirm that a public key belongs to the owner named in the certificate. Someone receiving a signed certificate can verify that the signature does belong to the CA, and determine whether anyone tampered with the certificate after the CA signed it.
  • Certificate Chain: One signed certificate affirms that the attached public key belongs to its owner. A second signed certificate affirms the trustworthiness of the first signer, a third affirms the second, and so on. The top of the chain is a self-signed but widely trusted root certificate.
  • Root Certificate: A certificate trusted to end a certificate chain. Operating systems and web browsers typically have a built-in set of trusted root certificates. When your server sends a chain of certificates and one of them matches one of a browser's trusted root certificates, then the browser trusts your server. When the browser encrypts data with your public key, the browser is assured that only your server can read it.
  • Keystore: A file that holds a combination of keys and certificates.
  • Formats: These instructions read and write files in the following formats:
  • PKCS: A binary file format typically associated with Windows systems. Typical file names are *.pkcs, *.p12, *.p7b, *.pfx
  • Java Keystore: A binary file format for use by Java applications (like the Code42 server). Typical file names are .keystore and *.jks
  • PEM: An ASCII text file that holds keys, certificates, or both. PEM files are common on Linux systems and Apache. Typical file extensions are *.pem, *.key, *.csr, *.cert

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

PEM File With ASCII Text

Create a keystore

Create a keystore using one of the following options:

  • Option 1: Create a key, get a CA to sign it, then build a keystore.
  • Option 2: Recombine existing keys and certificates into a new keystore.
  • Option 3: Convert an existing PKCS12 keystore to a Java keystore.

Option 1: Create and certify a new key

Step 1: Generate a key pair and a signing request

Create a PEM format private key and a request for a CA to certify your public key.

  1. Create a configuration file openssl.cnf like the example below:
    • Or make sure your existing openssl.cnf includes the subjectAltName extension.
    • Replace <your.domain.com> with the complete domain name of your Code42 server.
[ req ]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions     = req_ext

[ req_distinguished_name ]
countryName         = Country Name (2-letter code)
stateOrProvinceName = State or Province Name (full name) 
localityName        = Locality (e.g. city name)
organizationName    = Organization (e.g. company name)
commonName          = Common Name (your.domain.com)

[ req_ext ]
subjectAltName = @alt_names
[alt_names]
DNS.1 = <your.domain.com>
  1. Issue the command below, with two substitutions:
    • <your.domain.com>: the complete domain name of your Code42 server.
    • <path>: the file path for your openssl.cnf file.
openssl req -new -keyout <your.domain.com>.key -out <your.domain.com>.csr -nodes -newkey rsa:2048 -config <path>/openssl.cnf
  1. Answer the prompts for identifying data.
    At Common 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.
Generating a 2048 bit RSA private key
............................................+++
............................................+++
writing new private key to '<your.domain.com>.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MN
Locality Name (eg, city) []:Mnpls
Organization Name (eg, company) [Default Org.]:Example
Organizational Unit Name (eg, section) []:IX
Common Name (e.g. server FQDN or YOUR name) []:<your.domain.com>
Email Address []:<cert-admin@your.domain.com>
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:<password>
An optional company name []:Example Inc.
  1. Look for two files in the current directory: <your.domain.com>.key and <your.domain.com>.csr
  2. Confirm that a cat <filename> command displays ASCII text.
    If the two files from Step 3 exist and the command displays ASCII text, the command succeeded.
cat <your.domain.com>.csr
-----BEGIN CERTIFICATE REQUEST-----
MIIDAzCCAesCAQAwgY0xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJNTjEOMAwGA1UE
BwwFTW5wbHMxDzANBgNVBAoMBkNvZGU0MjELMAkGA1UECwwCSVgxGzAZBgNVBAMM
...
EmV4YW1wbGUuZG9tYWluLmNvbTEmMCQGCSqGSIb3DQEJARYXbmFtZUBleGFtcGxl
QITwVRVRp817TQLFS9o8pdu4iUcxpsiNdn58ZeNNUJjOgmZDxtpQPiL1sv0QuxUo
YgKjmS+0yw==
-----END CERTIFICATE REQUEST-----

Step 2: Request a CA-signed certificate

  1. 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 format, the format for a Linux system, for an Apache server.
    • Ask the CA what intermediate certificates you need and where to get them. One or more intermediate certificates are often, but not always, necessary to complete the chain of trust between your CA and a root CA trusted web browsers.
  2. Wait (usually days or a week) for the CA's reply.

Step 3: Import the CA's reply

  1. When you have the CA's reply file and intermediate certificate, combine them into a single PKCS keystore.
    The reply and certificate files must be in PEM format. If you can open them with a text editor and see ASCII characters, they are PEM.
  2. Copy the files from the CA's reply to the directory of the .key and .csr files from Step 1.

  3. Run the following commands from that directory.
    If you have multiple intermediate certificates, combine them in any order.

  4. Use the following command, with these substitutions:
    <midfile.1.cert.pem> and <midfile.2.cert.pem>: the names of intermediate certificate files.
cat <midfile.1.cert.pem> <midfile.2.cert.pem> > intermediates.cert.pem
  1. Create the keystore.p12 file. Use the command below, with these substitutions:
    • <CAreply> : The name of the CA reply file.
    • <your.domain.com> : The complete domain name of your Code42 server.
    • <intermediates.cert.pem> : The file of intermediate certificates. Not all CA replies require intermediates.
    • <yourpassword> : The password that allows access to manipulate this keystore. Provide at least 6 characters.
openssl pkcs12 -export -in <CAreply> -inkey <your.domain.com>.key 
  -certfile <intermediates.cert.pem> -name "<your.domain.com>" 
  -passout pass:<yourpassword> -out <your.domain.com>.p12

 

  1. Convert your keystore.p12 to a Java keystore.jks. Use the command below, with these substitutions:
    • <your.domain.com> : The same domain name as in the command above.
    • <yourpassword> : The same password as in the command above.
    • <youruserid>: The ID of the Linux user you used to sign in.
sudo keytool -importkeystore 
  -srckeystore <your.domain.com>.p12 -srcstorepass <yourpassword> -srcstoretype PKCS12 
  -destkeystore <your.domain.com>.jks -deststorepass <yourpassword>
  1. If the command succeeds, it returns this message:
Import command completed: 1 entries successfully imported, 0 entries failed or cancelled
[Storing <your.domain.com>.jks]
  1. Set your ownership of the keystore file.
sudo chown <youruserid>:<youruserid> <your.domain.com>.jks
  1. Proceed to configuring your Code42 server to use the keystore.

If the commands fail, you see messages like the following, for example:

Error opening certificates from certfile <filename>: The command cannot find the file.

unable to load certificates: There is some error in a certificate file.

Option 2: Recombine existing pem keys and certificates

If you have an existing private key and certificates for your Code42 server's domain, in PEM format, combine them into a PKCS keystore, then convert the PKCS keystore into a Java keystore.

  1. Issue the two commands below, with these substitutions:
    • <existing.cert.pem>: The existing signed certificate file that matches your existing private key.
    • <existing.key.pem>: The existing private key file.
    • <intermediate.cert.pem>: The existing intermediate certificates that complete the chain from your certificate to a root CA.
    • <your.domain.com> : The complete domain name of your Code42 server.
    • <existingpassword> : The password that allows access to the existing key file.
    • <yourpassword> : The password that allows access to your new keystore. Provide at least 6 characters.
    • <youruserid>: The ID of the Linux user you used to sign in.
openssl pkcs12 -export -in <existing.cert.pem> -inkey <existing.key.pem>
   -certfile <intermediate.cert.pem> -name "<your.domain.com>"
   -passin pass:<existingpassword> -passout pass:<yourpassword>
   -out <your.domain.com>.p12

keytool -importkeystore 
   -srckeystore <your.domain.com>.p12 -srcstorepass <yourpassword> -srcstoretype PKCS12
   -destkeystore <your.domain.com>.jks -deststorepass <yourpassword>
  1. Set your ownership of the keystore file.
sudo chown <youruserid>:<youruserid> <your.domain.com>.jks

Option 3: Convert an existing pkcs12 keystore

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

  1. Use the command below, with these substitutions:
    • <your.domain.com.p12> : The existing PKCS file.
    • <yourpassword> : The password that allows access to manipulate this keystore. Provide at least 6 characters.
    • <your.domain.com> : The complete domain name of your Code42 server.
    • <youruserid>: The ID of the Linux user you used to sign in.
keytool -importkeystore 
   -srckeystore <your.domain.com.p12> -srcstorepass <yourpassword> -srcstoretype PKCS12
   -destkeystore <your.domain.com>.jks -deststorepass <yourpassword>
  1. Set your ownership of the Java keystore file.
sudo chown <youruserid>:<youruserid> <your.domain.com>.jks

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: Set up a test server

Code42 strongly recommends trying out your keystore on a test server before moving it into production, as errors in a keystore can completely lock up a server.

  1. Sign in to Linux test system or virtual machine.
  2. Edit that system's hosts file to provide the same domain name as your production Code42 server.
    1. Open /etc/hosts with a text editor:
      sudo nano /etc/hosts
    2. Insert or change a line so that it begins with the test server's IP address followed by your Code42 server's domain name.
    3. Exit and save:
      control-X y return

  1. Install a Code42 server.
  2. Sign in to the administration console at
    https://<your.domain.com>:4285
  3. At Settings > Server > General > Website protocol, host and port, provide the same address:
    https://<your.domain.com>:4285.
  4. Press Save.

Step 3: 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 keystore file, <your.domain.com.jks>, and provide <yourpassword>.
  5. Return to the Linux command line and stop and restart the Code42 server:
    sudo /opt/proserver/bin/proserver stop
    sudo /opt/proserver/bin/proserver start
  6. Give the server several minutes to start up, then return the browser to the administration console sign in page:
    https://<your.domain.com>:4285
  7. 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

  1. If the keystore import succeeds on your test server, repeat these Step 3 instructions on your production Code42 server.

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 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.
    • Check that your key and certificate files are in PEM format (are readable with a text editor).
    • Consult documentation for:
  • For additional help, contact sales to discuss consulting options.

Read certificate and keystore files

The following commands print certificate and keystore files to your terminal window:

  • Read a certificate signing request (CSR)

openssl req -text -noout -in <filename>

  • Read a CA reply certificate or intermediate certificate:

openssl x509 -text -in <filename>

  • Read a PKCS keystore:

openssl pkcs12 -info -nodes -in <filename> -passin pass:<password>

  • Read a Java keystore:

keytool -list -keystore <filename> -storepass <password> -rfc

To write to a text file, add the following to the end of any command above:
> <filename>.txt