Add SSL/TLS certificate to HomeAssistant’s web interface

Even if your home’s automation is separated from any other network and not internet accessible, it’s always a good practice to use encryption. Failing to encrypt the connection to HomeAssistant’s web interface using an SSL/TLS certificate, results in leaving your password and other data traveling the network as plaintext susceptible to eavesdropping.

The following guide was tested both on a fresh install of HomeAssistant OS 10.1 as well as an existing older installation which was manually updated to the final version.

Why to encrypt http traffic

Http is an old protocol and does not use any form of encryption for transmitting or receiving data. If an adversary capture the traffic between the device you use and the HomeAssistant’s UI during the logon, then he will be able to view your password (and not only) in plain text. The following screenshot shows a wireshark capture of the login phase. As you can see all the data of the packet, including the username and the password, are available for anyone with access to the specific network traffic.

Install Terminal & SSH Add-on

To apply our own certificate, we must first install the Terminal & SSH Add-on (version 9.7.0 as of writing) to access the terminal of the HomeAssistant OS. Terminal & SSH Add-on is only visible to "Advanced Mode" users, to enable advanced mode, go to: Profile (the username on the bottom left of the menu) -> and turn on Advanced Mode

Then navigate to Settings select Add-ons

and start typing Terminal & SSH Add-on. Click on the card with the name of the add-on which will appear under the category "Official add-ons"

Next, Click INSTALL

And when the installation complete, Click START

Wait until the red indicator on the top right becomes green and then Click OPEN WEB UI

“`

A new terminal window will appear in your browser logged in as root.

Install OpenSSL

OpenSSL is a software library for applications that provide secure communications over computer networks against eavesdropping or need to identify the party at the other end. For the specific use case we need OpenSSL to generate the required certificate which will be used for the encryption of the data. HomeAssistant OS 10.1 does not come with OpenSSL preinstalled but it can be installed using the apk package manager using the following command:

apk add openssl

To verify the installation of OpenSSL use the command:

openssl version

Generate the required certificate

In order to encrypt the connection to HomeAssistant’s web interface an SSL/TLS certificate must be generated using the command:

openssl req -new -x509 -days 3650 -nodes -keyout ssl/hass.key -out ssl/hass.crt

This command will generate a certificate with a ten year validity (3650 days) period and the required private key. While generating the certificate you will be asked to provide additional information. All the fields can be skipped using the dot (.), except the Common Name field. When asked for the Common Name you must type the Fully Qualified Domain Name (FQDN) of HomeAssistant’s device otherwise you will not be able to use the specific certificate to encrypt the traffic for HomeAssistant’s web interface. The default FQDN of HomeAssistant’s OS installation is homeassistant.local and this is the one for which we will generate the certificate for.

Backup the existing configuration

Following the certificate generation, backup the existing configuration and verify the creation of the backup file using the following commands.

cp config/configuration.yaml config/configuration.bak
ls config

Encrypt HomeAssistant’s web interface

Modify the current configuration, using the nano text editor by issuing the following command:

nano config/configuration.yaml

HomeAssistant’s configuration is stored in a .yaml file. YAML syntax is very sensitive with the whitespace (space, line ends, etc), so be careful when typing or copying the following commands at the end of your configuration file:

http:
  ssl_certificate: /ssl/hass.crt
  ssl_key: /ssl/hass.key

After appending the http configuration close the file using the key combination CTRL + X, save the changes by pressing y and verify the name by pressing the ENTER key.

Restart HomeAssistant

To apply the new configuration file, navigate to Settings -> System -> Hardware

Click the Power Button at the top right edge and from the popup window select Restart Home Assistant

Wait for the restart process to complete and then navigate to https://homeassistant.local. Your browser will show the "Your connection is not private" warning due to the use of a self signed certificate (and not a certificate from a valid third party Authority).

Click on Advanced and then on Proceed to homeassistant.local (unsafe)

Home Assistant’s web interface will load and the url will be starting wth https. You will still have the Not secure indication next to the url, but this is due to the use of a self signed certificate. The reason you see this warning is because your browser can’t verify that this webpage is indeed the one which you requested and may be a result of a Man In The Middle (MITM) Attack. To get rid of this warning you must buy a certificate from a trusted third party Certification Authority.

Results

After applying the self signed certificate, all the traffic to and from the web interface is now encrypted and nothing is transferred as plaintext. All the HTTP requests and replies have been replaced by TLSv1.2 requests and replies.