Additional CA for Home Assistant

Additional CA integration for Home Assistant loads automatically private Certificate Authority or self-signed certificate into Home Assistant in order to access 3rd-party service with TLS/SSL, even after Home Assistant Docker container is recreated/upgraded.

📘 What to understand meaning private Certificate Authority (CA) ?

In case you manage your own CA, or you trust a CA, it gives you a kind of ca.crt file (or equivalent), that could be named shortly a personal/own/private/custom CA.
In case you generate a self-signed TLS/SSL certificate, it gives you a .crt file (or equivalent), that could be an equivalent of a personal/own/private/custom trusted CA.

📒 This documentation uses 'private CA' or 'self-signed cert' alternatively for the same purpose.

📘 What are the use-cases with this integration ?

You want to import Certificate file into Home Assistant host/container trust store, in order to access 3rd-party service with TLS/SSL:

Some of your installed integrations in Home Assistant need to access devices or third-party services with TLS/SSL (HTTPS, etc), and you got a ca.crt (or equivalent) from the service provider, you can load it with Additional CA integration.
You generated a self-signed TLS/SSL certificate for your own service (personal HTTPS Web server, etc) that you want to be trusted by Home Assistant, you can load it with Additional CA integration.

Table of contents

Additional CA for Home Assistant

1. INSTALL WITH HACS

Install HACS if not already done.
Then, go to your Home Assistant,
- -> HACS
- -> Integrations
- -> Click Explore and Download Repositories
- -> Search for "Additional CA"
- -> From the Additional CA presentation page: click Download

2. INSTALL WITHOUT HACS

2.1. Docker

If you're running Home Assistant with Docker:

Download and install using git:

# move to your Home Assistant directory containing the 'config' folder
cd /path/to/home-assistant
# git clone Addition CA integration
git clone https://github.com/Athozs/hass-additional-ca.git
# copy additional_ca integration to Home Assistant custom components
cp -r hass-additional-ca/custom_components/additional_ca config/custom_components/
# Installation done, now see Configuration section (README.md)

Download and install using wget:

# move to your Home Assistant directory containing the 'config' folder
cd /path/to/home-assistant
# download Addition CA integration archive
wget https://github.com/Athozs/hass-additional-ca/releases/latest/download/additional_ca.zip
# unzip archive
unzip additional_ca.zip
# copy additional_ca integration to Home Assistant custom components
cp -r additional_ca config/custom_components/
# Installation done, now see Configuration section (README.md)

Download and install manually
- Click button to download ZIP of Additional CA
- Unzip archive
- Move folder additional_ca into config/custom_components/ directory
- Installation done, now see Configuration section (README.md)

2.2. HAOS - Home Assistant Operating System

If you're running Home Assistant from HAOS:

Go to the Add-on store
Install one of the SSH add-ons (you need to enable advanced mode in your user profile to see them)
Configure the SSH add-on you chose by following the documentation for it
Start the SSH add-on
Connect to the SSH add-on
Download the latest release of Additional CA from Github (.zip):

wget https://github.com/Athozs/hass-additional-ca/releases/latest/download/additional_ca.zip

Unzip archive:

unzip additional_ca.zip

Move or copy folder additional_ca into config/custom_components/ directory:

cp -r additional_ca config/custom_components/

2.3. Core

If you're running Home Assistant core (Python package) directly on host, you don't need Additional CA integration. You should update your CAs from your host OS.

3. CONFIGURATION

CA files must be in PEM format (often .crt or .pem extension). Check content with a text editor. Content example (following is a fake):

Create directory config/additional_ca and copy your private CAs into it:

mkdir -p config/additional_ca
cp my_ca.crt config/additional_ca/

Optionally, you could group CAs into folders.

Directories structure example:

.
├── compose.yml
├── config/
│   ├── additional_ca/
│   │   ├── my_ca.crt
│   │   ├── selfcert.crt
│   │   └── some-super-ca/
|   |       ├── ca2.pem
│   │       └── ca3.crt
│   ├── blueprints/
│   │   └── ...
│   ├── configuration.yaml
│   ├── custom_components/
│   │   └── additional_ca/
│   │       ├── __init__.py
│   │       ├── const.py
│   │       └── manifest.json
│   ├── ...
...

Enable Additional CA integration in configuration.yaml and set private CAs:

Model:

# configuration.yaml
---
default_config:
additional_ca:
  <string>: <Certificate filename or Certificate relative path as string>
  <string>: <Certificate filename or Certificate relative path as string>
  # ...: ...

Example:

# configuration.yaml
---
default_config:
additional_ca:
  my_awesome_ca: my_ca.crt                       # a cert file
  a_super_ca: some-super-ca/ca2.pem              # a folder + a cert file
  again_another_super_ca: some-super-ca/ca3.crt  # a folder + a cert file
  my_self_signed_cert: selfcert.crt              # a self-signed certificate
# ...

Optionally, set environment variable REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt:

Example using Docker Compose:

# compose.yml
version: '3'
services:
  homeassistant:
    container_name: homeassistant
    hostname: home-assistant
    image: homeassistant/home-assistant:2023.5.2
    volumes:
      - ./config:/config
    environment:
      - TZ=Europe/Paris
      - REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
    restart: unless-stopped
    network_mode: host

Restart Home Assistant.
Check the logs, look for pattern additional_ca in traces (there is not UI for Additional CA).

4. HOW DOES Additional CA WORK UNDER THE HOOD ?

When enabled, Additional CA integration looks for private Certificates Authorities files (CAs) and self-signed certs in config/additional_ca directory.

It loads private CAs and self-signed certs only at Home Assistant startup.

It copies private CAs and self-signed certs to /usr/local/share/ca-certificates/ directory inside container and uses update-ca-certificates command line to update TLS/SSL trust store.

For now, Additional CA won't be visible in Home Assistant integrations dashboard, there is not UI component for Additional CA integration. This may be possible in future release.

5. SET `REQUESTS_CA_BUNDLE` ENVIRONMENT VARIABLE

You may need to set environment variable REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

This is optional, it depends on your installed integrations.

📝 Note: At time of writing, I could not find on the internet a reliable way to set permanently an environment variable in Home Assistant OS. So I coded another integration as a hack: https://github.com/Athozs/hass-environment-variable

5.1. Integrations based on Requests

If some of your installed Home Assistant integrations are using the famous Requests Python lib under the hood, and those integrations need to access remote servers using your private CA, then you will have to set environment variable REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt, so those integrations are aware of your private CA.

If your HA integrations does not use Requests Python package, then no need to set REQUESTS_CA_BUNDLE.

How do you know if HA integrations use Requests Python package ?

Read the Python code of those integrations and seek for requests package.

Anyway, setting environment variable REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt should not break your Home Assistant server.

5.2 RESTful core integrations

Also, if you use RESTful integrations from Home Assistant (including RESTful command and others), then you need to set REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt as an environment variable. Home Assistant implements an SSL context based on the env var REQUESTS_CA_BUNDLE.

May be possible for other integrations, I did not check.

6. HOW TO REMOVE A PRIVATE CA ?

Remove or comment CA entry under additional_ca: domain key in configuration.yaml:

# configuration.yaml
---
default_config:
additional_ca:
  # my_awesome_ca: my_ca.crt
  a_super_ca: some-super-ca/ca2.pem
# ...

Note: additional_ca: domain key need to be enabled in configuration.yaml to remove CA files on next restart of Home Assistant.

Optionally remove them from config/additional_ca/ directory.

7. UNINSTALL

Delete Additional CA from custom components:

rm -r config/custom_components/additional_ca

Remove additional_ca: domain key from configuration.yaml:

# configuration.yaml
---
default_config:
# additional_ca:
#   my_awesome_ca: my_ca.crt
# ...

Optionally remove additional_ca folder containing your private CA:

rm -r config/additional_ca

Recreate container:

docker compose up -d --force-recreate

8. TROUBLESHOOTING

Some tips to clean your system CA in case of failure:

Manually remove private CA files from /usr/local/share/ca-certificates/ directory inside HA container.
Then update manually system CA running command update-ca-certificates inside HA container.

9. KNOWN ISSUES

n/a

nabbi / hass-additional-ca

Additional CA for Home Assistant

📘 What to understand meaning private Certificate Authority (CA) ?

📘 What are the use-cases with this integration ?

1. INSTALL WITH HACS

2. INSTALL WITHOUT HACS

2.1. Docker

2.2. HAOS - Home Assistant Operating System

2.3. Core

3. CONFIGURATION

4. HOW DOES Additional CA WORK UNDER THE HOOD ?

5. SET `REQUESTS_CA_BUNDLE` ENVIRONMENT VARIABLE

5.1. Integrations based on Requests

5.2 RESTful core integrations

6. HOW TO REMOVE A PRIVATE CA ?

7. UNINSTALL

8. TROUBLESHOOTING

9. KNOWN ISSUES

About

Languages

Additional CA for Home Assistant

📘 What to understand meaning private Certificate Authority (CA) ?

📘 What are the use-cases with this integration ?

1. INSTALL WITH HACS

2. INSTALL WITHOUT HACS

2.1. Docker

2.2. HAOS - Home Assistant Operating System

2.3. Core

3. CONFIGURATION

4. HOW DOES Additional CA WORK UNDER THE HOOD ?

5. SET REQUESTS_CA_BUNDLE ENVIRONMENT VARIABLE

5.1. Integrations based on Requests

5.2 RESTful core integrations

6. HOW TO REMOVE A PRIVATE CA ?

7. UNINSTALL

8. TROUBLESHOOTING

9. KNOWN ISSUES

About

Languages

5. SET `REQUESTS_CA_BUNDLE` ENVIRONMENT VARIABLE