Home Assistant Add-On: step-ca-client

Share your Projects!
, ,
1

Home Assistant Add-on: step-ca-client

GitHub Release Project Stage License
Supports armhf Architecture Supports armv7 Architecture Supports aarch64 Architecture Supports amd64 Architecture Supports i386 Architecture
Github Actions Project Maintenance GitHub Activity

About

This is a step-ca client add-on for Home Assistant.

It manages the automatic creation and renewal of x509 certificates from a
remote step-ca PKI server, in order to enable TLS/SSL connections in
Home Assistant and the installed addons.

Here is a quick-start guide on how to setup step-ca.

With a Yubikey you can even set up setup a hardware based, local PKI.

:books: Read the full add-on documentation

Installation

The installation of this add-on is pretty straightforward and not different
compared to installing any other Home Assistant add-on.

  1. First you will need to add the repository to your add-on store with the
    following button:

    Add the add-on repository to your Home Assistant instance.

  2. Click on add to complete adding the repository.

  3. Click the Home Assistant My button below to open the add-on on your Home
    Assistant instance.

    Open this add-on in your Home Assistant instance.

  4. Click the “Install” button to install the add-on.

  5. Configure the add-on in the configuration tab.

  6. Start the “step-ca-client” add-on.

  7. Check the logs of the “step-ca-client” add-on to see it in action.

Configuration

You will need a one-time token generated with step ca token to issue the
certificate, and to keep the addon always running so it renews the certificate
automatically (enable “Start on boot” and “Watchdog” on the
[addon configuration page][addon-config]).

Note: Certificates in step-ca have short lifetimes, usually 24 hours, if the addon
is not running and the certificate expires, you must manually generate
a new one-time token.

The certificate lifetime is dictated when creating the token. It will use the
default provisioner lifetime. You can change it with step ca provisioner update <provisioner-name> --x509-default-dur=<duration>
before generating the token, but keep in mind [the design decisions of step-ca][passive-revocation].

Example add-on configuration:

ca_url: https://tinyca.internal
root_ca_fingerprint: "d9d0978692f1c7cc791f5c343ce98771900721405e834cd27b9502cc719f5097"
token: "692f1c7cc791f5c343ce987d9d0978692f1c7cc791f5c343ce98692f1c7cc791f5c343ce987"
subjects:
  - homeassistant.local
  - mqtt.local
keyfile: privkey.pem
certfile: fullchain.pem
key_type: RSA
log_level: info
1 Like
2

This is awesome! I’ve been playing around with step ca and this worked great. Can you explain why the core needs to be restarted on every renewal?

3

Glad you found this useful!

The certificate file is loaded and cached on startup, so a restart is needed to load the new one. Reload on the fly functionality is yet to be implemented on Home Assistant core.

4

If I’m using the nginx proxy add on and defining the SSL certificate there, as long as I restart that add on after a renewal, should I be fine to not restart the core?

5

Sure, whatever does the ssl termination.

Some of the reverse proxies do natively support reloading the ssl certficate, but as far as I know the reverse proxy addons don’t expose that functionality yet.

6

what is the subject I need to use with the token command?

when I try
step ca token haos.local --ca-url https://10.x.x.x:9000
the ca server print this error in the logs:
TLS handshake error from 10.x.x.x:59016: remote error: tls: bad certificate
that local ip refers to my desktop lan ip

solved: I forgot the bootstrap passage

7

That error means that the step cli client on your machine is not recognizing your remote server step-ca web server certificate.
Did you do the initial bootstrap on the client machine before doing anything else with the step client?
That will save the server certificate as trusted on your local machine so you can make requests later and not get those errors.

8

Bootstraping implies that the step client needs to be installed on the server HA is running on. How? I am running on a RPi 3B+ with HA OS installed, and I don’t see any way to install step. Please enlighten me.

9

Did you follow the linked tutorials to setup the PKI server?
You don’t need to install step in HA OS.
You do however need a valid token from the step-ca server, for that you will need to connect to the server using other machine, and use step ca token to get it. And for that you do need to install step and bootstrap the client on that other machine. And for that you need to have a server somewhere up and running. It is all in the linked tutorials.

This addon will not work on its own, it is just another client connecting to an already running step-ca environment.