Additional CA for Home Assistant

Add custom CA (Certificate Authority) to Home Assistant.

Additional CA for Home Assistant

1. INSTALL WITH HACS

For now, install Additional CA by adding this Github repository to HACS custom repositories:

Install HACS if not already done.
Then, go to your Home Assistant,
- -> HACS
- -> Integrations
- -> Click the Three-dots button in top-right corner
- -> Custom repositories
- -> Fill in
  - Repository: https://github.com/Athozs/hass-additional-ca.git
  - Category: Integration
- -> Click Add

2. INSTALL WITHOUT HACS

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

⚠️ I did not test installation on 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

Create directory config/additional_ca and copy your custom CAs into it.

Optionally, you could group CAs into folders.

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

Directories structure example:

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

CA files must be in PEM format. Example (this is a fake):

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

Model:

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

Example:

# configuration.yaml
---
default_config:
additional_ca:
  my_awesome_ca: my_ca.crt  # a cert file
  another_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
# ...

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 custom Certificates Authorities files (CAs) in config/additional_ca directory.

It loads custom CAs only at Home Assistant startup.

It copies custom CAs to /usr/local/share/ca-certificates/ directory inside container and uses update-ca-certificates command line.

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. `REQUESTS_CA_BUNDLE` ENVIRONMENT VARIABLE

This is optional.

Some of Home Assistant integrations may use the famous Requests Python package.

If some of your installed Home Assistant integrations (using Requests under the hood) need to access remote servers using your custom 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 custom CA.

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

How do I 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.

6. HOW TO REMOVE CUSTOM CA ?

Remove or comment entries under additional_ca: in configuration.yaml:

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

additional_ca: 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: config tree from configuration.yaml

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

Optionally remove additional_ca folder containing your custom 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 custom 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

I experienced what could be a bug, RESTful integrations from Home Assistant could not connect to an HTTPS server on my LAN with custom private CA. This is not due to Additional CA, you can check by disabling Additional CA and update manually CA certificates with your CA inside container (if using Docker container). Home Assistant Issue open here

milizhang/hass-additional-ca