Enabling SSL/TLS authentication
This article explains how to enable SSL/TLS authentication on Evoko Home and strictly enforce TLS checking on Liso devices. This allows for a secure connection to Evoko Home, and allows Lisos to ensure that the Evoko Home server is valid and reduces the risk of man-in-the-middle (MITM) attacks.
Note that strict TLS checking is disabled by default. To avoid accidentally disabling all Lisos in your system, please read this article in its entirety before enabling strict TLS checking.
Updating the SSL/TLS certificate
Evoko Home generates a self-signed certificate during installation. As a result, your browser will warn that the connection to Evoko Home is not private, due to an invalid certificate authority. For better security, you can replace the self-signed certificate with your own trusted certificate, either during or after the initial configuration of Evoko Home.
To change the certificate that Evoko Home uses, replace the self-signed certificate and private key files with trusted ones. Be sure to back up the self-signed certificate and key prior to replacing them, so that you can revert to them in case of issues. Once the process is complete, you can access Evoko Home via HTTP (e.g., http://localhost:3000) and it should, if successful, redirect you to HTTPS (e.g., https://localhost:3002).
Additionally, please note that:
- The file names need to be exactly
server.crtandserver.key - The files should be in PEM format
- The private key needs to be unencrypted (i.e., not password-protected)
- In some cases (e.g., when enabling strict TLS), it may be necessary to concatenate the certificate with the intermediate and root certificates so that the full trust chain is available on the Evoko Home server
Windows
By default, these files are stored in C:\Program Files\Evoko\EvokoHome\liso_files\certificates\
After replacing the files, you can restart the Evoko Home service from a Command Prompt:
net stop evokohomeservice & net start evokohomeservice
Ubuntu
By default, these files are stored in ~/Evoko Home/liso_files/certificates/
After replacing the files, you can restart the Evoko Home service from the Terminal:
evoko_home restart
Extending the Trusted CA list for Evoko Home
When you use an internal Certificate Authority (CA) certificate, in order to add the certificate as a trusted CA, you must extend the trusted certificates list by setting the NODE_EXTRA_CA_CERTS environment variable with the location of the CA certificate.
In this document, we will use OpenSSL to convert the certificate to .pem format; this may or may not be necessary for your organization.
Complete the following steps depending on your operating system.
Windows (Command Prompt)
- Convert the CA certificate to PEM format. Replace <CertificateName> with the filename of your CA certificate.
openssl x509 -in <CertificateName>.crt -out <CertificateName>.pem -outform PEM
- Create the environment variable NODE_EXTRA_CA_CERTS. Replace <C:\Path\to\CACert.pem> with the full path to the PEM file.
setx /m NODE_EXTRA_CA_CERTS <C:\Path\to\CACert.pem>
- Restart the Evoko Home service.
net stop evokohomeservice & net start evokohomeservice
Ubuntu (Terminal)
- Convert the CA certificate to PEM format. Replace <CertificateName> with the filename of your CA certificate.
openssl x509 -in <CertificateName>.crt -out <CertificateName>.pem -outform PEM
- Create the environment variable NODE_EXTRA_CA_CERTS. Replace </path/to/CACert.pem> with the full path to the PEM file.
export NODE_EXTRA_CA_CERTS= </path/to/CACert.pem>
- Restart the Evoko Home service.
evoko_home restart
Enabling strict TLS on Liso
Enabling the strict TLS check will require Evoko Home to present a valid, trusted certificate for the Lisos to connect. If the Liso is not presented with a trusted certificate by Evoko Home, it will refuse to connect (see A word of caution).
Prior to enabling strict TLS, the following requirements must be met:
- Evoko Home software and Evoko Liso firmware are each v2.5 or later
- Lisos are connected to Evoko Home via a full server and domain name (i.e., not an IP address)
- A trusted and valid certificate for this domain name is installed in Evoko Home
If all of these requirements are met, you can enable strict TLS on Liso from the Authentication section of the Global Settings page on Evoko Home.
A word of caution
If strict TLS is enabled but no valid certificate is installed, the Lisos will refuse to connect. Disabling strict TLS will not help at this point, because the Lisos are disconnected from Evoko Home and thus will not receive the configuration change. In this scenario, there are three options:
- Insert a valid certificate and restart the Evoko Home service, then either wait for every Liso to reboot (done automatically every night) or manually reboot them by cycling PoE power or removing and reinserting the power cable from each Liso.
- Disable strict TLS checking in Evoko Home, then log onto each Liso as an Admin and reconnect it to Evoko Home. This operation cannot be performed remotely; every Liso will need to be physically visited. You will need to know an existing admin PIN to complete this process.
- Disable strict TLS checking, firmware reset each Liso and reconnect it to Evoko Home. This is a last resort if you are unable to install a valid certificate and cannot log into the Liso as an Admin.