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.
-
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.
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
- 📘 What to understand meaning private Certificate Authority (CA) ?
- 📘 What are the use-cases with this integration ?
- 1. INSTALL WITH HACS
- 2. INSTALL WITHOUT HACS
- 3. CONFIGURATION
- 4. HOW DOES Additional CA WORK UNDER THE HOOD ?
- 5. SET
REQUESTS_CA_BUNDLE
ENVIRONMENT VARIABLE - 6. HOW TO REMOVE A PRIVATE CA ?
- 7. UNINSTALL
- 8. TROUBLESHOOTING
- 9. KNOWN ISSUES
- 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
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
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
intoconfig/custom_components/
directory:
cp -r additional_ca config/custom_components/
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.
- CA files must be in PEM format (often
.crt
or.pem
extension). Check content with a text editor. Content example (following is a fake):
-----BEGIN CERTIFICATE-----
ACeuur4QnujqmguSrHU3mhf+cJodzTQNqo4tde+PD1/eFdYAELu8xF+0At7xJiPY
i5RKwilyP56v+3iY2T9lw7S8TJ041VLhaIKp14MzSUzRyeoOAsJ7QADMClHKUDlH
UU2pNuo88Y6igovT3bsnwJNiEQNqymSSYhktw0taduoqjqXn06gsVioWTVDXysd5
qEx4t6sIgIcMm26YH1vJpCQEhKpc2y07gRkklBZRtMjThv4cXyyMX7uTcdT7AJBP
ueifCoV25JxXuo8d5139gwP1BAe7IBVPx2u7KN/UyOXdZmwMf/TmFGwDdCfsyHf/
ZsB2wLHozTYoAVmQ9FoU1JLgcVivqJ+vNlBhHXhlxMdN0j80R9Nz6EIglQjeK3O8
I/cFGm/B8+42hOlCId9ZdtndJcRJVji0wD0qwevCafA9jJlHv/jsE+I9Uz6cpCyh
sw+lrFdxUgqU58axqeK89FR+No4q0IIO+Ji1rJKr9nkSB0BqXozVnE1YB/KLvdIs
uYZJuqb2pKku+zzT6gUwHUTZvBiNOtXL4Nxwc/KT7WzOSd2wP10QI8DKg4vfiNDs
HWmB1c4Kji6gOgA5uSUzaGmq/v4VncK5Ur+n9LbfnfLc28J5ft/GotinMyDk3iar
F10YlqcOmeX1uFmKbdi/XorGlkCoMF3TDx8rmp9DBiB/
-----END CERTIFICATE-----
- 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).
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.
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
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.
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.
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.
- Delete Additional CA from custom components:
rm -r config/custom_components/additional_ca
- Remove
additional_ca:
domain key fromconfiguration.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
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.
n/a