SSL Certificates

ACUITY uses HTTPS for secure connections that require SSL certificates. Normally such certificates can be bought from some of Certificate Authorities (CAs), then they are signed by these CAs. But for testing purposes or if you plan to use ACUITY only internally, you may use a self-signed certificate. In this case, though, it's only your responsibility to keep the root certificate safe, and if it's lost or stolen, connections from the computer that trusts it are compromised, so it should immediately be removed from trusted.

Prerequisites

To follow this instruction, you need to have:

• EITHER a certificate bought from CA that signed it (then you may follow the instruction provided the CA to receive it; to use it, you need to have a certificate as pair of .key and .crt files, their names should be changed to ca in both cases)...
• OR an installed OpenSSL command line tool allowing you to generate a root certificate and sign a certificate for ACUITY by yourself (you may find if for different OSs here, but also it is preinstalled on many *nix systems installations, e.g. Ubuntu Server, so you may use a preinstalled one).
• domain name (or at least static public IP address) assigned to your ACUITY instance: your certificate will be generated for this particular domain name. Or several; if you have several domain names and/or IP addresses your ACUITY instance should be accessible by, you'll need them all.

Generation of self-signed certificate

If you decided to buy a certificate from CA, you may skip this section. Otherwise, proceed. The following way to do it is rather for orientation; feel free to modify it as you need if you're familiar with OpenSSL and know what you do.

Generation of root certificate

First of all, you need to generate a new root SSL certificate by which you will further sign your SSL certificate for ACUITY. To do it:

• prepare a text file with the following content (feel free to replace any values in the [ req_disginguished_name ] section with something more familiar for you: this change nothing in this case):

[req]
default_bits       = 2048
distinguished_name = req_distinguished_name
default_md         = sha256
prompt			   = no

[req_distinguished_name]
countryName                = RC
stateOrProvinceName        = Root State
localityName               = Root Locality
organizationName           = Root Org
organizationalUnitName     = Root Unit
commonName                 = Root Common Name
emailAddress			   = [email protected]

• save the prepared file as root.cnf
• run the following commands in the directory you placed the root.cnf file:

openssl genrsa -out root.key 2048
openssl req -x509 -new -key root.key -days 10000 -out root.crt -config root.cnf

• now you have root key file (root.key) and root certificate file (root.crt) in the same directory.

`

Generation and signing of ACUITY app certificate

Now you can create and sign a certificate for ACUITY.

• prepare another text file with the following content. Here you may also update any values in the [req_disginguished_name] section as you like, EXCEPT the commonName option: value of this one should be your application domain name (or public IP address if you plan to use it to access your ACUITY instance). Even more important, you need to set up the [alt_names] section: the same value as for commonName option should be assigned to DNS.1 (if it's a domain name) or to IP.1 (if it's an IP address) option. If you have for your alternative domain names and/or IPs that you plan to use to access to your ACUITY instance, add them as DNS.2, DNS.3 or IP.2, IP.3 and so on.

[req]
default_bits       = 2048
distinguished_name = req_distinguished_name
x509_extensions    = v3_req
default_md         = sha256
prompt			   = no

[req_distinguished_name]
countryName                 = CN
stateOrProvinceName         = Some State
localityName                = Some Locality
organizationName            = Some Organization
organizationalUnitName      = Some Unit
commonName                  = some.app.domain.name.com
emailAddress			    = [email protected]

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = some.app.domain.name.com
DNS.2 = other.app.domain.name.com
IP.1 = 0.0.0.0

• save the prepared file as ca.cnf in the same directory where you have root.crt and root.key
• run the following commands (here you generate a key file, create a Certificate Signing Request, then generate and sign the certificate by yourself using your root certificate and check the generated certificate content - there you can see subject name, alternative names and all other data you entered):

openssl genrsa -out ca.key 2048
openssl req -out ca.csr -newkey rsa:2048 -nodes -keyout ca.key -config ca.cnf -extensions v3_req
openssl x509 -req -in ca.csr -CA root.crt -CAkey root.key -CAcreateserial -out ca.crt -days 9999 -extfile ca.cnf -extensions v3_req
openssl x509 -in ca.crt -noout -text

• now you have a new certificate for your ACUITY instance, it consists of two files: ca.key and ca.crt.

Installation of certificates

When you have a certificate, you need to install them. For a new ACUITY installation, just follow the main installation instruction. If you want to add a new certificate to an existing ACUITY installation, do the following:

• on your ACUITY machine, place your certificate ca.key file to the <your-ACUITY-root-dir>/ssl-certificates/keys/ directory and your ca.crt file to the <your-ACUITY-root-dir>/ssl-certificates/certs/ directory
• restart httpd docker service to use the new certificates with one of the following commands (run it from your ACUITY root directory):

# for building mode:
docker-compose -f docker-compose_building-mode.yml restart httpd
# for regular mode:
docker-compose restart httpd

Importing self-signed certificate to trusted store

• if you use a certificate signed by external CA, that's probably all, but if your certificate is self-signed, you have also to add your root certificate as a trusted one on the client side (it should be done on each machine from which your ACUITY instance should be accessed) The way to do it depends on the browser used to access ACUITY, but in case of Google Chrome the procedure is the following (described for Chrome 90.0.4430.212):
  • open the Settings page
  • find Privacy and Security section, open Security, then find and open Manage certificates
  • in the new window open the tab Trusted Root Certificate Authorities, then press Import...; in the import wizard, choose your root.crt certificate, after that just follow the wizard instructions without changing any options. When your press Finish and then Yes, the certificate will be added.
• please KEEP SAFE the key part of your root certificate (root.key file)! If it's stolen, every computer it's added as a trusted root CA will be in danger, so in this case remove it from trusted ASAP on each of computers.