Security

boneIO ESP controllers run ESPHome. The factory firmware is built from a public YAML file; you adopt that same file in ESPHome Builder and from then on compile from your own copy. A public file cannot carry passwords or keys — everybody would know them — so securing the controller is a step you take after adoption.

What stays open until you do

The boneIO ESP 24x16A factory firmware no longer accepts firmware uploads through the browser (ota: platform: web_server). Other models, and controllers adopted earlier, still do — see below.

Secure the controller after adoption

Two installs in ESPHome Builder. Keep the key and the password in secrets.yaml, different for every controller.

1. API key and page password. Change these blocks and install:

api:
  reboot_timeout: 0s
  encryption:
    key: !secret boneio_api_key # 32 bytes in base64, ESPHome Builder can generate one

web_server:
  port: 80
  local: true
  auth:
    type: digest
    username: admin
    password: !secret boneio_web_password

• api.encryption encrypts the connection to Home Assistant. After flashing, Home Assistant asks for the key in the ESPHome integration — paste the same one.
• web_server.auth protects the device page. If you do not use the page, remove the whole web_server block.

2. OTA encryption. Add encryption: and install a second time:

ota:
  - platform: esphome
    encryption:

From then on the controller accepts only firmware encrypted with its API key — nobody else can flash it, and the firmware image (which contains the key) never crosses the network in plain text. Needs ESPHome 2026.9 or newer. On older versions set password: !secret boneio_ota_password instead of encryption: — a password only checks who is uploading, it does not encrypt the image. The two cannot be combined.

Controller adopted earlier

Adoption copies the factory file as it was on the day you adopted. If your ota has a - platform: web_server line, remove it — that is firmware upload through the browser with no password. If you need browser uploads, keep it, but only together with web_server.auth as above.

Updates to ESPHome and to the boneIO packages arrive when you compile the configuration in ESPHome Builder — do it regularly.

Reporting a vulnerability

Please do not open a public issue. Email security@boneio.eu with SECURITY in the subject — we acknowledge within 5 working days. You can also report through CERT Polska. Report problems in ESPHome itself to the ESPHome project.