Skip to main content

This article applies to version 6.

Available in:

StandardPremiumEnterprise
Small Business
Code42 Support

Install a CA-signed SSL certificate with OpenSSL

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 OpenSSL 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.
  • Windows administrators typically use the Java keytool.

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

Before you begin

Keys and SSL 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 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 includes 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 neither is present, do the following:
    • Mac:
      Download and install OpenSSL.
      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
    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 administration console. You do not need any further access to the authority server's host machine.
  • 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.

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.

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.

Need help?
Assistance creating a keystore or handling a certificate signing request (CSR) are beyond the scope of Customer Champions. For further assistance:

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       = 4096
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:4096 -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 4096 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.
    • When the command prompts for the export password, provide at least 6 characters.
openssl pkcs12 -export -in <CAreply> -inkey <your.domain.com>.key 
  -certfile <intermediates.cert.pem> -name "<your.domain.com>" 
  -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.
    • <youruserid>: The ID of the Linux user you used to sign in.
    • When the command prompts for source and destination keystore passwords, provide the same password that you used for the previous command.
sudo keytool -importkeystore 
  -srckeystore <your.domain.com>.p12 -srcstoretype PKCS12 
  -destkeystore <your.domain.com>.jks
  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.
    • <youruserid>: The ID of the Linux user you used to sign in.
    • Both commands will prompt you for passwords to the source and destination keystores.
openssl pkcs12 -export -in <existing.cert.pem> -inkey <existing.key.pem>
   -certfile <intermediate.cert.pem> -name "<your.domain.com>"
   -out <your.domain.com>.p12

keytool -importkeystore 
   -srckeystore <your.domain.com>.p12 -srcstoretype PKCS12
   -destkeystore <your.domain.com>.jks
  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.
    • <your.domain.com> : The complete domain name of your Code42 server.
    • <youruserid>: The ID of the Linux user you used to sign in.
    • The command will prompt you for passwords for the source and destination keystores.
keytool -importkeystore 
   -srckeystore <your.domain.com.p12> -srcstoretype PKCS12
   -destkeystore <your.domain.com>.jks
  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

Edit hosts file

  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 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) for enterprise support at csmsupport@code42.com.

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