Install a CA-signed SSL/TLS certificate with KeyStore Explorer
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 KeyStore Explorer to create an SSL/TLS certificate signed by a trusted certificate authority (CA).
Other articles describe other tools for creating a CA-signed certificate:
- Linux administrators typically use OpenSSL.
- 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 Code42 consoles.
Certificates and Java keystore files
The Code42 server accepts certificates bundled together in a Java KeyStore file. The keystore contains:
- The certificate and the public and private key for the Code42 server
- A certificate from the CA who signed the Code42 server certificate
- Intermediate certificates that establish a chain of trust between the CA and the Code42 server certificate
Create the keystore using a utility such as KeyStore Explorer before applying it to the Code42 server from the Code42 console.
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.
Before you begin
- Before installing an SSL certificate, back up your Code42 server's database with a database dump so that you can recover it to a previous state if necessary. To create the dump:
- Navigate to Settings > Server.
- From the action menu, choose Dump Database.
- Obtain the address of the CA to whom you will send your request for a signed certificate that verifies the validity of your keystore.
- Install KeyStore Explorer if it is not already installed.
- If you intend to import a certificate with an encryption key that exceeds the Java import limits on cryptographic algorithms, you must first configure your enterprise server to accept longer encryption keys.
Considerations
- For multi-server Code42 environments, we recommend applying this process to all Code42 servers.
- You must have the Server Administrator or SYSADMIN role to install an SSL certificate on your Code42 server.
- This article assumes you are familiar with the following:
- The basic principles of Transport Layer Security (TLS)
- Configuring SSL certificates
-
The command-line utility OpenSSL is required if you are running Linux and want to reuse existing key materials.
Assistance with the handling of a certificate signing request (CSR) or creating your keystore is beyond the scope of Customer Champions. For assistance, please contact your Customer Success Manager (CSM) to engage the Professional Services team.
Keystore terminology
Build the keystore
Building a Java KeyStore is the first step in configuring your Code42 server to use your own CA-signed SSL certificate. If you have an existing private key and corresponding X.509 certificate (referred to collectively as key materials), you can reuse them. You can also start from scratch, creating new key materials as needed. The steps are different, depending on what existing key materials you have:
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.
Option 1: Build a keystore without existing key materials
You must use the same password for the keystore and the private key. You can use any string you want for these parameters, but they must both be set to the same value.
Follow the steps below if you have no private keys or certificates from a CA and need to create them from scratch.
Step 1: Create a keystore and key pair
- Start KeyStore Explorer.
- Choose Create a new KeyStore.
- From New KeyStore Type, choose JKS.
- Click OK.
- Generate a key pair:
- Select Tools > Generate Key Pair.
- In Generate Key Pair, choose the following algorithm selection options:
- RSA
- Key Size: 4096
- Click OK.
Generating Key Pair dialog appears, then disappears after a key is generated. - From Generate Key Pair Certificate, click the Edit name icon
.
- Complete the Name fields:
- For the Common Name (CN) use the Fully Qualified Domain Name (FQDN) of your server.
- For the Common Name (CN) use the Fully Qualified Domain Name (FQDN) of your server.
- Click OK.
- Specify the domain name of your server as an alternative name. Click Add Extensions, click the + icon, and select Subject Alternative Name.
- In the Subject Alternative Name Extension dialog, click the + icon, select DNS Name, and in General Name Value type the domain name of your server.
- Click OK until you return to the Generate Key Pair Certificate dialog.
- In Generate Key Pair Certificate, click OK.
- In New Key Pair Entry Alias, enter an alias for the key pair.
The alias is pre-set to the CN set in the Name dialog. - Click OK.
- In New Key Pair Entry Password, enter a password, and click OK.
The Generate Key Pair dialog displays "Key Pair Generation Successful".
Save this password, and use it as the password for the entire keystore in step 7 below.
- Click OK.
The new key pair is displayed in the KeyStore Explorer window.
- Save the keystore:
- From the KeyStore Explorer menu, select File > Save.
The Set KeyStore Password dialog appears. - Enter a password for the keystore. This password must be the same as the password for the key pair generated in step 5 above.
- Click OK.
The Save KeyStore As dialog appears. - Enter the name of the keystore.
This format is suggested for easy identification of your keystores: fqdn_domain_com.jks - Click Save.
Your keystore file is saved to your computer.
- From the KeyStore Explorer menu, select File > Save.
Step 2: Generate and send certificate signature request
- Right-click the key pair entry.
- Choose Generate CSR.
The Generate CSR dialog appears.
- (Optional) Enter additional values.
- Click OK.
The CSR Generation Successful dialog appears. - Click OK.
- Send the generated CSR file to your certificate authority.
Step 3: Import signed certificates to your keystore
- When the certificate authority returns your signed certificate and key, place them in a directory accessible by Keystore Explorer.
- In Keystore Explorer, right-click the same key pair entry used to generate the CSR and choose Import CA Reply > From File.
- Select the signed certificate from your certificate authority, and click Import.
The signed certificate is added to the key pair entry as the server-level certificate. - To verify the certificate chain, right-click the key pair entry, and choose View Details > Certificate Chain Details.
- If you need to import intermediate and root-level certificates, right-click the key pair entry, and choose Edit Certificate Chain > Append Certificate to append the intermediate and root-level certificates. See Append certificates to an existing keystore, below.
- From the menu bar, select File > Save to save the imported certificate to your keystore.
Your keystore file is complete and ready to be imported into your Code42 server.
Option 2: Build a keystore with existing key materials
If you want to use existing key materials to build a keystore, you can choose to:
- Append certificate to an existing keystore
- Reuse existing key materials (Linux)
- Reuse existing key materials (Windows)
Append certificates to an existing keystore
If you already have a keystore that contains certificates, you can append new certificates.
If you don't have existing key materials, you can import certificates to the keystore.
- Start KeyStore Explorer.
- Choose Open an existing KeyStore.
- Select the keystore JKS file, click Open, provide the password, and click OK.
- In the main KeyStore Explorer window, right-click the key pair entry.
- Select Edit Certificate Chain > Append Certificate.
Reuse existing key materials from another application (Linux)
Follow these steps to reuse an existing private key/certificate combination from another application if you are running on Linux. These instructions assume that both your private key and certificate are PEM-formatted.
The following steps require the use of the command-line utility OpenSSL.
- Convert the PEM-formatted private key into a PKCS8-formatted key with the following command:
openssl pkcs8 -topk8 -nocrypt -outform DER -in mykey.pem -out mykey.pkcs8
- Start the KeyStore Explorer application.
- Choose Create a new KeyStore from the quick start menu.
- From New KeyStore Type, choose JKS.
- Click OK.
- From the menu bar, select Tools > Import Key Pair.
- From Import Key Pair Type, select PKCS #8.
- From Import PKCS #8 Key Pair, import the key pair as follows:
- If the private key file is encrypted, enter the decryption password in Decryption Password.
- In PKCS #8 Private Key File, enter the path to the private key file in PKCS # 8 format, or click Browse to navigate to the file.
- In Certificate(s) File, enter the path to the X.509 certificate file in PEM or DER format, or click Browse to navigate to the file.
- Click Import.
- In New Key Pair Entry Alias, enter an alias for the key pair.
- Click OK.
- In New Key Pair Entry, enter a password for the key pair.
The Key Pair Import Successful dialog appears. - Click OK.
- Select File > Save from the menu bar.
- In Set KeyStore Password, enter a keystore password, and click OK.
- In Save KeyStore As, enter the name of your new keystore file. Give the file the .jks file extension.
- Click Save.
Your keystore file is complete and ready to be imported into your Code42 server.
Reuse existing key materials from another application (Windows)
Follow these steps to reuse an existing private key/certificate combination from another application if you are running on Windows. Key materials on Windows platforms are typically stored in a PKCS12 keystore file. The KeyStore Explorer can convert a PKCS12 keystore file to a JKS file using the steps below.
- Start the KeyStore Explorer application.
- Select File > Open from the menu bar.
- Navigate to and select the PKCS12 file that you want to convert.
- Click Open.
- In Unlock KeyStore, enter the password for the keystore file and click OK.
- Select File > Save As from the menu bar.
- Enter a name with the .jks file extension for the new keystore.
- Click Save.
- Select Tools > Change Type > JKS from the menu bar.
- From Change KeyStore Type, click OK.
The Change KeyStore Type dialog displays "Change KeyStore type Successful". - Click OK.
- Select File > Save.
The keystore file is saved in JKS format.
Your keystore file is complete and ready to be imported into your Code42 server.
Configure the Code42 server to use the keystore
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-----