By default, Sandfly generates a self-signed certificate for HTTPS web service. Optionally, during installation, you may tell the installer to generate a real trusted certificate using Let's Encrypt🡵.

However, should you need to use an SSL/TLS certificate that is trusted in your environment and Let's Encrypt is not an option (for example, if the Sandfly web server is not internet-accessible or you cannot create public DNS records to allow Let's Encrypt to issue a certificate), you also have the option to install an SSL/TLS certificate in Sandfly after the installation process has been completed or at a later time.

Required Files

Two files are needed to install a certificate:

Certificate - The cert.pem file must contain the server certificate and (if necessary) the intermediate chain certificate(s).

The server certificate must be the first certificate in the cert.pem file. Each certificate (the server certificate and the intermediate certificates) must be PEM-encoded and include the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" delimiters.

• Intermediate Certificate Chain - (Optional: if you are installing your own self-signed certificate, there is no intermediate chain.) The intermediate chain is a single file that contains one or more intermediate certificates, one after the other.
• If you have your server certificate in certificate.pem and your intermediate certificates in cachain.pem, you can create the cert.pem file by concatenating them together in the correct order:
  • cat certificate.pem cachain.pem > cert.pem
• The complete cert.pem file should look like (without leading spaces):

• -----BEGIN CERTIFICATE-----
  MII...
  -----END CERTIFICATE-----
  -----BEGIN CERTIFICATE-----
  MII...
   -----END CERTIFICATE-----
  ... (possibly more certificates)

Private key - The privatekey.pem file must be a PEM-encoded, unecrypted private key file. It should look something like (without leading spaces):

-----BEGIN RSA PRIVATE KEY-----
MII...
-----END RSA PRIVATE KEY-----

Installation

To use your own SSL/TLS certificate for the Sandfly UI and API services, place the certificate and private key files in the sandfly-setup/setup/setup_data/server_ssl_cert/ directory, ensuring that they are named cert.pem and privatekey.pem respectively.

If one or both files are present in this directory, the TLS mode settings in Sandfly will be ignored.

If the Sandfly server is currently running, gracefully stop it by running sandfly-setup/start_scripts/shutdown_sandfly.sh. Then restart the server services by running start_sandfly.sh. If using the Standard Security mode, also run start_node.sh. Finally, open the Sandfly server in your web browser to verify that the new certificate is active.

Updating

When the time comes to change the certificate, the script located at sandfly-setup/setup/setup_scripts/reload_server_https_certificate.sh will replace the HTTPS server certificate in the running "sandfly-server" container without needing to stop and start Sandfly. Replace the cert.pem and (if necessary) the privatekey.pem file and run the reload_server_https_certificate.sh script to signal the Sandfly server container to load the updated certificate.