By default, Sandfly generates a new certificate authority and certificate for the 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 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 may install a certificate from any Certificate Authority (CA) in Sandfly after the installation process has been completed or at a later time.


Required Files


To install a certificate, you need three files:


Private key - The private key file is the non-encrypted, PEM-encoded private key for the certificate. The contents of the private key file should look like:


-----BEGIN RSA PRIVATE KEY-----

MII...

-----END RSA PRIVATE KEY-----


Certificate - The certificate file is the PEM-encoded certificate issued by your CA. The contents of the certificate file should look like:


-----BEGIN CERTIFICATE-----

MII...

-----END CERTIFICATE-----


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. The intermediate certificate chain file should look like:


-----BEGIN CERTIFICATE-----

MII...

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

MII...

-----END CERTIFICATE-----

... (possibly more certificates)


Preparation


With the three (or two, if no intermediate chain) files available, prepare the key, certificate, and chain for Sandfly.


From the private key, create a one-line, base64-encoded version of the file:

base64 -w0 private_key.pem > private_key.sandfly.b64


Combine the certificate and intermediate chain into a single file, with the certificate as the first item in the file. Then create a one-line, base64-encoded version of that file:

cat certificate.pem intermediate_chain.pem > certificate_and_chain.sandfly
base64 -w0 certificate_and_chain.sandfly > certificate_and_chain.sandfly.b64


The two single-line (-w0 argument to base64 prevents wrapping the output, so there are no line breaks in the files) .b64 files are the base64 strings you will add to the Sandfly configuration files.


Installation


From the sandfly-setup directory, edit the file setup/setup_data/config.server.json.


Find the section in the JSON under server > ssl > server > private_key_signed, and insert the contents of the private_key.sandfly.b64 file between the double quotation marks.


Next, find the section in the JSON under server > ssl > server > cert_signed, and insert the contents of the certificate_and_chain.sandfly.b64 file between the double quotation marks.


WARNING: Do not change any other SSL-related values

Leave the existing "cacert", "cert", and "private_key" values as they were automatically generated by the install script.


Do not change any other SSL-related values--leave the existing "cacert", "cert", and "private_key" values as they were automatically generated by the install script. Your new certificate will be used for the Sandfly HTTPS server, but the auto-generated certificate values are still required for some internal communication.


If the sandfly server is already running, stop it with docker stop sandfly-server (the postgres and rabbit services do not need to be restarted for the certificate change to take effect). Start the Sandfly services with the start_sandfly.sh script, and access the Sandfly server from your web browser to confirm the new certificate is in use.



Previous
Previous Article:

Next Article:
Next