https://man.liquidfiles.com
LiquidFiles Documentation

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.

This article is for traditional certificates. If you're looking to use Let's Encrypt, the free and open CA, please see this article instead.
This section covers the tasks involved with installing the certificates but offers no background information. If you want to know how it all hangs together, please see the How does Certificates work section first.

Installing a CA signed Certificate

When creating a CA-signed certificates, there are a couple of steps involved

  1. Generate the Private Key.
  2. Generate a Certificate Signing Request.
  3. 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:

If you generate a new private key, it will invalidate the existing Certificate. The Certificate is generated from a Certificate Signing Request that is generated from the private key. If the private key changes, the Certificate will no longer match the key and a new Certificate Signing Request, and a new Certificate will need to be generated from the new key.
images/system/certificates/certificate_01.png

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:

images/system/certificates/certificate_02.png

When you hit Generate CSR, you will get a paragraph like:

-----BEGIN CERTIFICATE REQUEST----- 
MIIBqzCCARQCAQAwazELMAkGA1UEBhMCU0UxEjAQBgNVBAgTCVN0b2NraG9sbTES
MBAGA1UEBxMJU3RvY2tob2xtMRowGAYDVQQKExFBbGxhcmQgQ29uc3VsdGluZzEY
MBYGA1UEAxMPdHV2b2suYWxsYXJkLm51MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCB
iQKBgQDmnjOzpz+BJPGO87yJUr8H3wU5b/mmRY4UJxgUQ7WMiRCYwag/bqxO29zR
Wb77H/SNTLCbLoXrXvz6VEgKw4U/6RlDYpK5HI3qjDoEBzlfBVtcAGgcm9R4FPhx
bXs39XhYXieMC8XDnNM+y0wnMhbzWPiFdHDKLM38013+Q6BJXQIDAQABoAAwDQYJ
KoZIhvcNAQEEBQADgYEAp5JK0xsFP/b41Pb8+Qr/9xRFXIycS2Er9vW5vnjUxaHH
Jlvuv0QZi6o3BF6N5o4rFiHrQta1gny6imu9Pv1kUC/aFq9d1AKWUc64kGDpXvJH
r/svdu2+wNGirGfGoe+j1weAdAAKIvTlMz9lpn5gpMMcPDrxXziiaZULgfFwhkk=
-----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:

-----BEGIN CERTIFICATE-----
MIICqDCCAZACCQDsX/Y+RSLBDjANBgkqhkiG9w0BAQUFADAWMRQwEgYDVQQDEwtk
b250LnVzZS5tZTAeFw0xMTEwMDEyMjQ5MzlaFw0xMTEwMDIyMjQ5MzlaMBYxFDAS
BgNVBAMTC2RvbnQudXNlLm1lMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAoeW0E0oYUup8JR7ghKi2rkiIpXyNmVPl0A00kffwyWI7YuCSzsLxBdIxZkPk
ar/XVT+GD+RJXLCrfUd9t4ZuwWph4wKJK6rulqyRBIHtkrx1XYDH3r6DXK+Ivw23
tkeZmoIo2vq6zHAWsJs5NTOeuto7Tv03nHjGfZvQXWL5hLKkiBjcfF2VNbvoI61v
jKx10vzTqW0qt6CAQe9l9eQVxfDnrl4z67mbt3Nx2KpbiruyBSbd0FxDokex5mfc
C6foVblxBtLQaUA3mFtSSflQN81UyTmZWTkNTPVgUw7CuCBajzFe3Y1wFsh+fha8
5yB7Z4MY2z29Mw/v4swLb6WOQwIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQBkAEUH
XffMxCttSDSzjC1Lnua7jXVUTWLXxxfJZQ/28QhS+n5nQZGYzyQGXEuCE7nVxEBZ
aJYlL5Yhdu+GJr36OIWFebvoZRrMOqukFpy5FfWxghjpPlAkw+M/VM54SACm9Mzk
w95OjpI/ogCWki94NQDdrKnA09tCXIdid5WzoFlrGhAgiIAyYuCUHAz5e44DCEu1
yLr5oUpsd7cdCe4U9iY5eHK7XUQPBuBQbZ/Nt580XCydpsEoleopsYPmn+WvXyOU
jT4mQP+b5hwQCtW7+KGtPbxhk0+9jOqP1gzwsAFPADO5MuBLvk5CwdNJ5awh8L/x
K4ZLP4tYYTJSL6rh
-----END CERTIFICATE-----

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:

images/system/certificates/certificate_03.png

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:

images/system/certificates/certificate_04.png

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:

images/system/certificates/certificate_05.png

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:

-----BEGIN CERTIFICATE-----
MIIEvTCCA6WgAwIBAgIDA9uKMA0GCSqGSIb3DQEBBQUAMDwxCzAJBgNVBAYTAlVT
MRcwFQYDVQQKEw5HZW9UcnVzdCwgSW5jLjEUMBIGA1UEAxMLUmFwaWRTU0wgQ0Ew
[ This is your certificate ]
JThWjh4sr9d6bbw/oYLSJRryLU8JJXxyeFYig9HVR4og+f59kZ0f2OyTvbBFFyua
6EhB7KR+EUWFNu/ATIlYius=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIID1TCCAr2gAwIBAgIDAjbRMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMRswGQYDVQQDExJHZW9UcnVzdCBHbG9i
[ This is your CA's intermediate certificate(s) ]
knYYCnwPLKbK3opie9jzzl9ovY8+wXS7FXI6FoOpC+ZNmZzYV+yoAVHHb1c0XqtK
LEL2TxyJeN4mTvVvk0wVaydWTQBUbHq3tw==
-----END CERTIFICATE-----

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.

Please note that you don't have to run these openssl commands on the LiquidFiles system. If you're more comfortable with Windows, run it on Windows. Windows binaries are available here: http://www.openssl.org/related/binaries.html.

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

Please note that you don't have to run these openssl commands on the LiquidFiles system. If you're more comfortable with Windows, run it on Windows. Windows binaries are available here: http://www.openssl.org/related/binaries.html.

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

This section covers general information on certificates. This is mainly if you want to understand the background of how it all hangs together. It is not specifically related to LiquidFiles and you don't need to read this if you only want to install a certificate and get going.

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:

KEY → CSR → Certificate

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:

images/system/certificates/certificate_06.png

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:

images/system/certificates/google_ca.png

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
CONNECTED(00000003)
depth=1 /C=ZA/O=Thawte Consulting (Pty) Ltd./CN=Thawte SGC CA
verify error:num=20:unable to get local issuer certificate
verify return:0
---
Certificate chain
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 Formats

Example Key (so that you can see the format, this is not actually useable):

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAoeW0E0oYUup8JR7ghKi2rkiIpXyNmVPl0A00kffwyWI7YuCS
zsLxBdIxZkPkar/XVT+GD+RJXLCrfUd9t4ZuwWph4wKJK6rulqyRBIHtkrx1XYDH
3r6DXK+Ivw23tkeZmoIo2vq6zHAWsJs5NTOeuto7Tv03nHjGfZvQXWL5hLKkiBjc
fF2VNbvoI61vjKx10vzTqW0qt6CAQe9l9eQVxfDnrl4z67mbt3Nx2KpbiruyBSbd
0FxDokex5mfcC6foVblxBtLQaUA3mFtSSflQN81UyTmZWTkNTPVgUw7CuCBajzFe
3Y1wFsh+fha85yB7Z4MY2z29Mw/v4swLb6WOQwIDAQABAoIBACKomCpg/GATzsvr
lkkQDTu2T3qN9YpTialGinCNUcDrBKegSA13cj26x9SKyEWKGEEpvjt8ta/gKnZB
bcpyPxes/JOqoU714uniu5Dpd8CoE8AWp7MpudmHwpCUETY2kc2f+7sVXhQSEulv
8YlQKbT6ryOz1cnrmSKezraPT7d2Z8p18ayjsrfBlC3sksULwKZWz0iDxMtTORTv
93HdJUw5AiFU/d+i+nQAQkhgRBICkl+j/q3jpVMJerDT2jVWOWgaKGULoHzAQgEs
ce4/TCos6vmKRIHAWyIcHCUPW5pd3b8JkMcAmyfywkvWNNYuei4eNJWLCjbMAg59
H2qcJDECgYEA0a5t2zD1P6UrD0uCe27gpft7H5B9eS74VGCmgcIK6rjTX4NfEQkC
fLfKkr9ru5ccUCGlBpDgecFk05KIuymXIO53wZo7rpM6CuiU7vTLktDvTDVoLAmh
gxJ2NtGsGTHZNaUVTO31kg0ILO8YZe6bRPprfWuNlLW0WXULD92efU8CgYEAxakQ
WCNGxa6Ozfp+gqp3z12hDt5PGXJSn7TjzFbMTSW+IdWxBM3ArkDS1WE8WqVekDsx
lhwURYqjVraTbC7y6fTbts9zOzp59CtChJC/7JjhOVLyaoAmEP1Pt16nJdyqxMZb
3RVWpqrxgcqv8KL+JQIM8DbysJNunxrkh2F/6s0CgYBE4XEzNUULkF2x25NUqxrf
S9qphtTBL33ichGgxLbDXs4JLWXYecY4ZEQGqx1f9YcWh8bnfkZPmQlfO17xZPtB
lTUAA4OhmLnThY4PZZlOdJZ3yX+cH9nP7gupfH11lVuOdNmnePBX9zH9WNoB+j1F
jqIrBF7xQDOrw3hL0PjUnwKBgQCNneq661NqkP158K4xmkdLCE87ouXTWoh+KpFH
tyybXZ5TCZLR2UTi1Ej6XrdqTq9o8TA+15FinckXeKo5SY37N9cvrIRn/CaiXVhE
OJ15u7MqahaLXZNoesVhoOxrASZM472vsfkqYrG0B291HqKuC0EP3p6VCpyoXBE+
Ogn3RQKBgQCAbdY6KqkQYKtL0+qBbI95Q4ZG0DE9oLwdQLEezo6ituG5v9WeAshG
y5Qv94tSZQGM59wqeIY2bHeCiYXZdtItIfbx9zM4Ka4VjIYMObK+/yxMb08pFd0/
bx28mhUd06hLNxTzOYRyJ0RFpUjSvEbBaTg6K4pIYOh84NfRNGJcvw==
-----END RSA PRIVATE KEY-----

 

Example CSR (so that you can see the format, this is not actually useable):

-----BEGIN CERTIFICATE REQUEST-----
MIICWzCCAUMCAQAwFjEUMBIGA1UEAxMLZG9udC51c2UubWUwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQCh5bQTShhS6nwlHuCEqLauSIilfI2ZU+XQDTSR
9/DJYjti4JLOwvEF0jFmQ+Rqv9dVP4YP5ElcsKt9R323hm7BamHjAokrqu6WrJEE
ge2SvHVdgMfevoNcr4i/Dbe2R5magija+rrMcBawmzk1M5662jtO/TeceMZ9m9Bd
YvmEsqSIGNx8XZU1u+gjrW+MrHXS/NOpbSq3oIBB72X15BXF8OeuXjPruZu3c3HY
qluKu7IFJt3QXEOiR7HmZ9wLp+hVuXEG0tBpQDeYW1JJ+VA3zVTJOZlZOQ1M9WBT
DsK4IFqPMV7djXAWyH5+FrznIHtngxjbPb0zD+/izAtvpY5DAgMBAAGgADANBgkq
hkiG9w0BAQUFAAOCAQEAGDJ6eniszawZXyK/e4LmBga5sF5Mtq/Zq5ProXdkakVG
XOrrGdb65xa4gq92gciPc4lmAF+5BdLO2bpuC1BmFZ/54xB60N59JnPFe5wUDRiA
QtE/G4luRAtq4aRUmwUQozAJzuPwgLUUQ5dM+wUgOlvYgGbgDvCMC/QEzGAyH1zy
Qj/ljMCXCVMLMmufTAk1Z1vktEnIG8u4Xc8KpdMw2C2SgTc3IdBmZaX8uQ/zDrPi
Pr98MrIodrE0U5NpXQS6P4NHZXDm/+WFMpvEkmzO7UCz27DX/WtFqQgvlWb9m5DU
Ihg8I9PUVw6O6Ag6h1D/lTrWMhTABfu3Ywvjocu6/Q==
-----END CERTIFICATE REQUEST-----

 

Example Certificate (so that you can see the format, this is not actually useable):

-----BEGIN CERTIFICATE-----
MIICqDCCAZACCQDsX/Y+RSLBDjANBgkqhkiG9w0BAQUFADAWMRQwEgYDVQQDEwtk
b250LnVzZS5tZTAeFw0xMTEwMDEyMjQ5MzlaFw0xMTEwMDIyMjQ5MzlaMBYxFDAS
BgNVBAMTC2RvbnQudXNlLm1lMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAoeW0E0oYUup8JR7ghKi2rkiIpXyNmVPl0A00kffwyWI7YuCSzsLxBdIxZkPk
ar/XVT+GD+RJXLCrfUd9t4ZuwWph4wKJK6rulqyRBIHtkrx1XYDH3r6DXK+Ivw23
tkeZmoIo2vq6zHAWsJs5NTOeuto7Tv03nHjGfZvQXWL5hLKkiBjcfF2VNbvoI61v
jKx10vzTqW0qt6CAQe9l9eQVxfDnrl4z67mbt3Nx2KpbiruyBSbd0FxDokex5mfc
C6foVblxBtLQaUA3mFtSSflQN81UyTmZWTkNTPVgUw7CuCBajzFe3Y1wFsh+fha8
5yB7Z4MY2z29Mw/v4swLb6WOQwIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQBkAEUH
XffMxCttSDSzjC1Lnua7jXVUTWLXxxfJZQ/28QhS+n5nQZGYzyQGXEuCE7nVxEBZ
aJYlL5Yhdu+GJr36OIWFebvoZRrMOqukFpy5FfWxghjpPlAkw+M/VM54SACm9Mzk
w95OjpI/ogCWki94NQDdrKnA09tCXIdid5WzoFlrGhAgiIAyYuCUHAz5e44DCEu1
yLr5oUpsd7cdCe4U9iY5eHK7XUQPBuBQbZ/Nt580XCydpsEoleopsYPmn+WvXyOU
jT4mQP+b5hwQCtW7+KGtPbxhk0+9jOqP1gzwsAFPADO5MuBLvk5CwdNJ5awh8L/x
K4ZLP4tYYTJSL6rh
-----END CERTIFICATE-----