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 OS or Home Assistant with Docker is 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 OS / Docker 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, SMTP, LDAP, etc) that you want to be trusted by Home Assistant, you can load it with Additional CA integration.

📘 Quick Setup (TL;DR)

Install HACS
Install Additional CA integration via HACS or manually without HACS, full docs here-under
Copy private CA to config folder:

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

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

Export environment variable if running Home Assistant with Docker (no need in case of Home Assistant OS):

# compose.yml
version: '3'
services:
  homeassistant:
    # ...
    environment:
      - REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Restart Home Assistant
Done!

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
mkdir -p config/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
mkdir -p config/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:

mkdir -p config/custom_components
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

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

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
│   │   └── my_folder/
│   │       └── selfcert_2.pem
│   │   └── 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                # relative path + a cert file
  again_another_super_ca: some-super-ca/ca3.crt    # relative path + a cert file
  my_self_signed_cert: selfcert.crt                # a self-signed certificate
  self_signed_crt: my_folder/selfcert_2.pem        # relative path + a self-signed certificate
# ...

Optionally, if you're running Home Assistant with Docker, set environment variable REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt:

Example with 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.

After upgrading Home Assistant to a new version, you need to reboot Home Assistant to load again your certificates.

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 ?

4.1. Docker

If you're running Home Assistant with Docker:

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

Additional CA 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.

4.2. HAOS - Home Assistant Operating System

HAOS is actually a Linux OS running a homeassistant Docker container inside.

If you're running Home Assistant from HAOS or Supervised installation, Additional CA integration works the same way as with Docker, but you can't export environment variable permanently in HAOS, so there is a workaround: Additional CA integration will also add private CA in Certifi CA bundle /usr/local/lib/python3.xx/site-packages/certifi/cacert.pem inside homeassistant container if not yet present (thanks to @nabbi for the contribution).

Thus, for HAOS, your private CA or self-signed cert will appear in container CA trust store and in Certifi CA bundle (both inside homeassistant container).

After upgrading Home Assistant to a new version, you need to reboot Home Assistant to load again your certificates.

5. SET `REQUESTS_CA_BUNDLE` ENVIRONMENT VARIABLE

Home Assistant implements an SSL context based on the environment variable REQUESTS_CA_BUNDLE.

Only for Docker installation type and Core installation type, 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.

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

📝 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. As a workaround, Additional CA integration adds your private CA into Certifi CA bundle if not yet present.

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
# ...

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

Optionally remove your private CA file from config/additional_ca/ directory.

Then, restart Home Assistant.

7. UNINSTALL

Delete Additional CA from custom components:

Uninstall from HACS, go to your Home Assistant,

-> HACS
-> Integrations
-> Additional CA
-> From the three-dots menu: click Remove

Or uninstall manually:

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

Restart Home Assistant.

If using Docker Compose, recreate container:

docker compose up -d --force-recreate

8. TROUBLESHOOTING

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

8.1. Docker

If running Home Assistant with Docker:

Either

(Preferable) Stop and remove HA container, it will remove all changes made inside container, then start again Home Assistant with Docker.

Or

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.

8.2. HAOS - Home Assistant Operating System

If running Home Assistant from HAOS or Supervised installation type, you could reset Certifi CA bundle, two ways possible:

Either

(Preferable) Stop and remove homeassistant Docker container inside HAOS and reboot HAOS. From Home Assistant SSH prompt, run:

docker stop homeassistant
docker rm homeassistant
reboot

Or

Downloading original bundle from https://raw.githubusercontent.com/certifi/python-certifi/master/certifi/cacert.pem
Replace it at Certifi bundle path (to get Certifi bundle path: from SSH prompt, run command line docker exec -ti homeassistant python -m certifi).

8.3. Tips

To enable INFO logs level, add the following to your configuration.yaml:

logger:
  default: info

To check your certificate validity, if using x509 certs, run:

openssl x509 -in config/additional_ca/my_ca.crt -text -noout

To test manually that Additional CA is working, see Manual test with HTTPS from CONTRIBUTING.md docs.

9. KNOWN ISSUES

n/a

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github		.github
.vscode		.vscode
custom_components/additional_ca		custom_components/additional_ca
img		img
scripts		scripts
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
compose.yml		compose.yml
hacs.json		hacs.json
requirements_dev.txt		requirements_dev.txt

License

Athozs/hass-additional-ca

Folders and files

Latest commit

History

Repository files navigation