Come proteggere i dispositivi ESPHome: chiavi, password e secrets.yaml

Chiavi API cifrate, secrets.yaml, OTA protetto e web server con password: come mettere in sicurezza ogni dispositivo ESPHome.

Ultimo aggiornamento: 7 novembre 2026. Versioni testate: Home Assistant Core 2026.11.0, Supervisor 2026.10.5, Operating System 18.4, Frontend 20261028.4 (su Raspberry Pi 5), ESPHome Device Builder 2026.10.2.

I dispositivi ESPHome sono piccoli computer collegati alla tua rete di casa. Se non li proteggi, chiunque sia collegato alla stessa rete (un ospite, un altro dispositivo infettato) potrebbe leggerne i dati o comandarli. Se usi relè, prese o un portone, il rischio non è teorico. La buona notizia è che bastano poche abitudini: chiave cifrata per ogni dispositivo, password messe in un file riservato e il servizio web protetto o spento.

Pagina Secrets del Device Builder di ESPHome con i valori oscurati

Cosa otterrai

  • Una configurazione ESPHome che non contiene password in chiaro.
  • Una chiave diversa per ogni dispositivo, generata correttamente.
  • Un elenco chiaro di cosa fare se una chiave è finita dove non doveva.

Le regole da ricordare

  1. Cifra sempre la comunicazione con Home Assistant (chiave API).
  2. Una chiave diversa per ogni dispositivo. Mai riutilizzare la stessa. Se una chiave condivisa viene scoperta, tutti i dispositivi che la usano sono esposti. La documentazione ufficiale lo dice chiaramente.
  3. Metti tutto ciò che è riservato in secrets.yaml e richiamalo con !secret.
  4. Proteggi gli aggiornamenti via Wi-Fi (OTA).
  5. Se usi la pagina web del dispositivo, metti nome utente e password. Se non ti serve, spegnila.
  6. Hotspot di emergenza solo con password.

Cosa serve

Alcuni link in questa pagina sono link di affiliazione: se acquisti da lì io ricevo una piccola commissione, senza alcun costo per te. Trovi i dettagli nella pagina Trasparenza e affiliazioni.

  • ESPHome Device Builder con almeno un dispositivo già creato.
  • Un gestore di password per conservare una copia dei valori importanti. Se non ne usi uno, ti consiglio di farlo.
  • Dieci minuti di tempo: modifichi un dispositivo per volta.

Passo 1: mettere le password nel file secrets.yaml

Nel Device Builder apri il menu con i tre puntini in alto a destra (Altre opzioni) e scegli Secrets: è la pagina che gestisce il file secrets.yaml, nella stessa cartella dei tuoi dispositivi. I valori sono nascosti: per leggerli premi Mostra i valori. Le voci sono raggruppate in una sezione Condiviso (per esempio i dati del Wi-Fi) e una sezione per ogni dispositivo. Ogni riga ha un nome e un valore; nel file corrispondono a una riga per ogni valore riservato:

wifi_ssid: "NomeDellaMiaRete"
wifi_password: "password-della-rete"
luce_soggiorno_api_key: "chiave-generata-per-questo-dispositivo"
luce_soggiorno_ap_password: "password-lunga-per-hotspot"

Quelli sopra sono segnaposto: scrivi i tuoi valori reali solo dentro il file secrets, mai in un articolo, in una chat o in uno screenshot. Nei file dei dispositivi richiami i valori così:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

I dati del Wi-Fi possono essere condivisi tra dispositivi, perché la rete è la stessa. Chiavi e password dei singoli dispositivi, invece, devono essere diverse.

Se condividi un file YAML per chiedere aiuto (su un forum o su GitHub), non condividere mai secrets.yaml: condividi solo il file del dispositivo, che contiene soltanto i nomi dei segreti. Se tieni le configurazioni in un archivio online, escludi il file secrets.

Passo 2: generare una chiave API cifrata

La chiave API è una stringa di 32 byte codificata in base64. Puoi generarla in due modi:

  • Dalla pagina ufficiale del componente API sul sito di ESPHome, che genera una chiave casuale direttamente nel tuo browser (con un pulsante per rigenerarla).
  • Direttamente nel Device Builder: apri il dispositivo, vai su Native API → Encryption → Encryption key (i nomi sono in inglese) e scegli dal menu a tendina il segreto del dispositivo, per esempio nome_dispositivo__api_key. Se lasci il campo vuoto, ESPHome genera una chiave e Home Assistant la legge durante l’associazione.

Copia la chiave nel file secrets con un nome unico (per esempio nome_dispositivo_api_key) e usala così:

api:
  encryption:
    key: !secret luce_soggiorno_api_key

Dopo l’installazione, Home Assistant chiederà la chiave quando aggiungi il dispositivo. Se non la inserisci, non potrà collegarsi.

Passo 3: proteggere gli aggiornamenti (OTA)

Il file compilato contiene anche i dati del tuo Wi-Fi e la chiave API. Per questo conviene proteggere anche gli aggiornamenti. Il metodo oggi consigliato è riusare la chiave dell’API:

ota:
  - platform: esphome
    encryption:

La riga encryption: vuota usa la stessa chiave del blocco api, quindi non serve una password in più. Se un dispositivo non ha il blocco api, o non puoi usare la cifratura, la documentazione ammette una password OTA unica e robusta, ma non si possono usare entrambe contemporaneamente. Per passare da una password alla cifratura su un dispositivo già installato esiste un’opzione temporanea per un solo aggiornamento.

Passo 4: pagina web del dispositivo con autenticazione

Il componente web_server mostra una pagina di controllo sul dispositivo. Se non ti serve, non inserirlo. Se lo usi, aggiungi sempre nome utente e password:

web_server:
  port: 80
  auth:
    username: !secret web_username
    password: !secret web_password

Due cose da sapere: la documentazione avverte di non esporre mai questa pagina su internet; inoltre l’autenticazione predefinita (basic) non protegge la password in transito. Esiste il tipo digest, che la documentazione raccomanda e che diventerà il valore predefinito in ESPHome 2027.1.0: puoi già indicarlo con type: digest. Tieni presente che la pagina web di un dispositivo piccolo consuma memoria, quindi evitala dove non serve.

Passo 5: hotspot di emergenza

Il blocco ap dentro wifi crea una rete di emergenza se il Wi-Fi non funziona. Se lo lasci, dagli sempre una password forte e diversa per ogni dispositivo:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "luce-soggiorno-hotspot"
    password: !secret luce_soggiorno_ap_password

Alcuni esempi in rete usano password banali come “12345678”: cambiale sempre. Se non ti serve l’hotspot, puoi toglierlo, ma tieni conto che il recupero in caso di errori diventa più difficile.

Cosa fare se una chiave è stata condivisa

Hai pubblicato per sbaglio un file con una chiave? Non fingere che non sia successo e agisci subito:

  1. Genera una nuova chiave per ogni dispositivo coinvolto.
  2. Mettila nel file secrets e installa di nuovo la configurazione. Poiché la stessa chiave protegge anche gli aggiornamenti, con la cifratura OTA attiva ruota anche quella.
  3. Cambia anche password OTA, password web e password dell’hotspot, se erano nel file pubblicato. Se erano nella stessa condivisione anche nome e password del Wi-Fi, cambiali sul router.
  4. Aggiorna la chiave in Home Assistant se non si ricollega più: rimuovi e riaggiungi il dispositivo da Impostazioni → Dispositivi e servizi → ESPHome, inserendo la nuova chiave. La documentazione ufficiale non descrive questo passaggio nel dettaglio.
  5. Se il file è finito su un archivio online, rimuovilo e considera comunque compromesso il vecchio valore: cancellare il file non basta.

Problemi comuni

  • Dopo aver cambiato la chiave, Home Assistant non vede più il dispositivo. Aggiorna la chiave in Home Assistant oppure rimuovi e riaggiungi il dispositivo.
  • Errore in compilazione che cita un segreto non definito. Il nome del segreto nel file del dispositivo non coincide con quello in secrets.yaml. Controlla maiuscole, minuscole e trattini.
  • Il caricamento Wi-Fi fallisce dopo aver attivato la cifratura OTA. Il passaggio da password a cifratura richiede l’opzione temporanea allow_plaintext_upload per un solo aggiornamento, descritta nella documentazione OTA. Se non riesci, resta l’installazione via cavo.
  • Ho perso il file secrets. Fai sempre un backup di Home Assistant e delle configurazioni ESPHome.

Riepilogo

Una chiave diversa per ogni dispositivo, tutto nel file secrets, OTA cifrato, pagina web con password (o spenta) e hotspot con password. Se una chiave esce dalla tua rete, sostituiscila subito.

Articoli correlati

Fonti

Lascia una risposta