Installing and managing Certificates
LiquidFiles comes with an automatically generated self-signed certificate that works perfectly for testing, evaluating and possibly for limited deployments. For production systems, you’d want to generate a “proper”, CA-signed certificate for your appliance.
Installing a CA signed Certificate
When creating a CA-signed certificates, there are a couple of steps involved
- Generate the Private Key.
- Generate a Certificate Signing Request.
- Install the Certificate and possibly the Certificate Chain on the server.
Generate the Private Key
When the LiquidFiles system boots for the first time, it generates a new private key.
If this key somehow gets compromised it needs to be re-generated. If you keep the private key secret, there is no need to ever re-generate the private key.
To re-generate the private key in LiquidFiles, please go to Admin → Certificate and click on Re-Generate Self Signed Certificate:
Once you have a new key, it will automatically invalidate any existing certificate (please see the How does Certificates work for more info) and why it will automatically install itself with a self signed certificate for you to continue.
Generate a Certificate Signing Request
This is handled in LiquidFiles from Admin → Certificates → Generate CSR and where you get to fill out Country, State, City, Organisation, Organisation Unit, the Common Name is pre-filled in. From a technical point of view, the only critical value is the Common Name.
With the Common Name, you have the option of either using a "Standard Certificate" using the Fully Qualified Domain Name (FQDN), basically what all users will see in the URL field of their browser. Or using a "Wildcard Certificate" which covers a complete DNS domain.
The CSR generation window looks like this:
When you hit Generate CSR, you will get a paragraph like:
-----BEGIN CERTIFICATE REQUEST-----
-----END CERTIFICATE REQUEST-----
This is what you send to your Certificate Authority.
Often, the Certificate Authority will ask for certificate type and you can have options like Apache, Nginx, IIS, or possibly options like PEM or DER. Please select Apache, Nginx or PEM to get the correct format for LiquidFiles.
Installing the Certificate in the appliance
When you get the certificate back from the CA, it will either come as a file, like yourcertificate.crt or directly in an email or visible in the browser like:
If you get a file, please just open the file in Notepad, or any other text editor you have available so that you can copy and paste the information as above.
In LiquidFiles, please browse to Admin → Certificate → Upload, you will be presented with a window like this:
In the Certificate section, please replace the content with the Certificate you got from the Certificate Authority.
When you hit save, LiquidFiles will validate the certificate to make sure you don't install something that will render the system unusable.
For instance, you may see this:
In this case, some data from the beginning of the certificate is missing and the certificate is no longer valid.
Or you may see this:
In this case, the CSR that was used to generate the Certificate was not generated from the private key in the Private key section. Either replace the key with the key that was used to generate the CSR and the Certificate, or select another Certificate that was generate from the private key on the LiquidFiles system (please see the How does Certificates work section for more info).
Installing an Intermediate Certificate/Certificate Chain
These days, it's very common the Certificate Authorities themselves are signed by other Certificate Authorities. In order for the browser to be able to validate the certificate, you will need to add not only your own certificate but the Certificate Authorities Intermediate Certificates as well.
When you install the intermediate certificates/certificate chain you got from your CA, paste this into the Certificate Section in Admin → Certificate → Upload, after your certificate. This will look something like this:
[ This is your certificate ]
[ This is your CA's intermediate certificate(s) ]
Converting from other Certificate Formats
The LiquidFiles appliance uses PEM format for it's certificate. If your CA is asking for a server type you can specify either Nginx, Apache or PEM as the format.
If your certificate is in another format, the easiest is probably to search the web for something like: Certificate DER to PEM, and you will find several options where you can convert the certificate. The certificate is public so there's no harm doing this on public websites.
If your certificate is in PFX/PKCS12 format (that is one file that includes both the certificate and the private key), please go to Admin → Certificate, and click on "Upload PFX/pkcs12" to upload and install the certificate and key into LiquidFiles.
The rest of these examples use the OpenSSL command line program to convert certificates to PEM format.
Convert DER to PEM
openssl x509 -inform der -in certificate.cer -out certificate.pem
Convert P7B to PEM
openssl pkcs7 -print_certs -in certificate.p7b -out certificate.pem
When completed, please open the file certificate.pem in notepad or any other text editor to copy and paste into LiquidFiles.
Creating a custom Certficate Signing Request (CSR)
If you want to create a custom CSR, such as a certificate with a 4096 bit key, you can run the following command:
openssl req -out certificate.csr -new -newkey rsa:4096 -nodes -keyout certificate.key
The content of certificate.csr is what you send to your CA, and the certificate.key you hold on to and when you get the certificate back from your CA, you upload it together with the contents of certificate.key in Admin → Certificate → Upload as described in the Certificate Upload section.
How does Certificates work
With all certificates, regardless of if they are used on the LiquidFiles appliance or in any other application that uses certificates, they all work in the same way.
The first thing we have to understand is the relationship between the private key, the certificate signing request (CSR) and the Certificate. The relationship between them works like this:
We begin by generating a key. From the key we generate a CSR, and from the CSR we generate the certificate. Also, please note that the arrows are one way from the key through to the certificate. It's not possible, and the security of the entire Internet would fall to pieces if it was possible, to calculate or derive or by any means get hold of the key from the certificate. This also mean that if you loose the key, you will need to generate a new certificate. There is no way around that.
Key: The key is the first things that needs to be generated. The key is what has the key length. Often we refer to a certificate having a key length of 1024 or 2048 bits. In reality it's actually the key that has the key length. In the LiquidFiles appliance, 2048 bit keys are used as default, but you can install a key and certificate of other lengths if required.
CSR: CSR, or Certificate Signing Request, is what gets sent to the Certificate Authority (CA). We generate the CSR from the key, and we add attributes to the CSR. The most important attribute is the CN or Common Name. The CN needs to match the hostname of the appliance. If the hostname is liquidfiles.company.com, the CSR needs to have a CN=liquidfiles.company.com. It's also possible to use a wildcard certificate. A wildcard certificate will have a CN=*.company.com. The most important thing is that that the CN matches the hostname in the URL or you will get a certificate warning.
Certificate: From the CSR we generate a Certificate by signing the CSR with a private key. If we sign the CSR with it's own key, we call the Certificate a self-signed certificate. For production systems, it's recommended to send the CSR to a public CA and have them sign the CSR. Typical CA's include Verisign, Thawte, RapidSSL and GoDaddy.
Understanding the Certificate Chain / Intermediate Certificates
It's very common that CA's require intermediate certificates, sometimes also called subordinate certificates or the certificate chain. In order to validate the certificate, the browser needs to verify the server certificate by matching it's signature against one of the known public CA's that exist in your browser. For instance, in Internet Explorer, you can go to Internet Options → Content → Publishers, and you will see the list of trusted Certificates:
With intermediate certificates, what's happened is that the CA's certificate is not known and trusted, but they have in turn got their certificate signed by one of the known and trusted CA's. If we look at https://www.google.com as an example, by clicking on the security info section when browsing there, you will see something like this:
Or to get another, more detailed view, we can use OpenSSL to connect from the command line, like this:
% openssl s_client -connect www.google.com:443
depth=1 /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
verify error:num=20:unable to get local issuer certificate
0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
i:/C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
1 s:/C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
i:/C=US/O=VeriSign, Inc./OU=Class 3 Public Primary Certification Authority
In this case the certificate for www.google.com has been signed by Thawte SGC CA, which is not trusted (it is not listed in the browsers list of certificates like in the screenshot above). But the Thawte SGC CA has in turn been signed by "Class 3 Public Primary Certificate Authority" which is actually the second certificate listed in the screenshot from Internet Explorer above. And since we trust "Class 3 Public Primary Certificate Authority" we will also trust "Thawte SGC CA", and since we now trust "Thawte SGC CA" we will also trust that "www.google.com" is secured by the certificate signed by "Thawte SGC CA".
Example Key (so that you can see the format, this is not actually useable):
-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----
Example CSR (so that you can see the format, this is not actually useable):
-----BEGIN CERTIFICATE REQUEST-----
-----END CERTIFICATE REQUEST-----
Example Certificate (so that you can see the format, this is not actually useable):