To install a valid SSL certificate on your UpGuard Core appliance, an UpGuard Engineer requires
a certificate (
crt) and private key file (
key). This guide will walk you through the steps
to generate these files, namely:
- How to create a valid Certificate Signing Request (CSR) that contains the correct Common Name and Subject Alternate Names (SAN) to make modern browsers happy.
- How to turn the CSR into a CRT and key.
- What UpGuard Engineers do with the CRT and key files to install the certificate.
Generating a CSR
This guide assumes you have access to a Linux, OSX or Unix based machine with openssl installed. If you have other requirements, please contact your Technical Account Manager for further assistance.
In this guide, we are going to use the domain name
upguard.example.com as the domain
of your UpGuard Core appliance. We’re going to assume your company owns and manages
its root domain at
First, create a configuration file called something like
and fill out the contents to be similar to the example format below.
We are using a configuration file here rather than a single command, as we want to specify SAN values in addition to the Common Name associated with the certificate. Even though we might only have a single domain associated with the certificate, modern browsers like Chrome are beginning to phase out just a Common Name setting without an associated SAN entry.
[req] distinguished_name = req_distinguished_name req_extensions = v3_req prompt = no [req_distinguished_name] C = US ST = CA L = Mountain View O = Example Company Name OU = My Team Name CN = upguard.example.com [v3_req] keyUsage = keyEncipherment, dataEncipherment extendedKeyUsage = serverAuth subjectAltName = @alt_names [alt_names] DNS.1 = upguard.example.com
The main components you will need to set in this file are:
- C: This is the country code for your organization. For a full list of country codes use your favorite search engine to find "SSL certificate country codes".
- ST: This is the state or province for your organization.
- L: This is the city or suburb of your organization.
- O: This is the name of your organization.
- OU: This is the organizational unit or team within your company.
- CN: This is the common name or hostname associated with the certificate. This must match the hostname, for example upguard.example.com.
- DNS.1: This is where SAN domains are listed. Here, if we're only associating the one domain with this certificate we only need to set one DNS.x entry.
Save and close the file.
Run the following command to generate the CSR and key files.
openssl req -new -out upguard.csr -newkey rsa:2048 -nodes -sha256 -keyout upguard.key -config upguard.example.com.conf
Then run the following command to verify the Common Name (
CN) and SAN values are correct:
openssl req -text -noout -verify -in upguard.csr
You should now have both the
upguard.key files available.
Generating a CRT
Your company or hosting provider should provide you with a mechanism to convert a CSR and key into a valid CRT. Please ask your UpGuard Technical Account Manager for any assistance you might need in locating the correct team or tool within your organization.
The output of this tool may also give you a series of CRT files which will reference your
main domain (
upguard.example.com) up through an optional intermediate level certificate
(potentially something like
example.com) to a root level CA. You should concatenate these
crt files into a single file “local to root”. That is, if you have three crt files you
can merge them into one like this:
$ ls upguard.example.com.crt example.com.crt rootCA.crt $ cat upguard.example.com.crt example.com.crt rootCA.crt > merged.crt
Have the files
upguard.key ready for your UpGuard Technical Account Manager.
Installing the Certificate
Installation of the certificate must be completed by an UpGuard Engineer because:
- it requires direct access into the appliance, and
- we are able to follow a correct procedure of backing up any pre-existing files before applying the update and being able to roll back incase the certificate files are invalid.
key file, an UpGuard Engineer will upload the files to the appliance and
install the certificate and key. They will then monitor the update and test that the certificate
installation was completed successfully.
For other tips on keeping your UpGuard Core appliance healthy, please visit our guide on Appliance Maintenance.