Security Best Practices - ESPHome - Smart Home Made Simple mentions in multiple places that the API encryption keys should not be shared between devices. However, at the same time it seems unconcerned with multiple devices sharing the same WiFi network credentials. For example:
Important: Even when using secrets.yaml, each device must have unique API encryption keys (which also secure OTA), OTA passwords where still used, and web server credentials. Never reuse these across devices. Only WiFi credentials can be shared.
I’m trying to understand why this is expressed so strongly (“each device must have unique […] keys”). My understanding is that per-device unique keys could only provide incremental benefit if you assume the attacker is already present on the same network as multiple ESPHome devices, right? But do per-device keys really provide benefit in that scenario? Is the encryption that ESPHome uses more vulnerable to deriving the encryption key if an attacker can observe API traffic from multiple devices sharing the same key?
Absent that or another risk that I’m not imagining, then it seems like per-device unique keys can only help if you also assume that the attacker gains physical access to one of your ESPHome devices and dumps the firmware, which contains the key in plaintext. Is mitigating physical access risk then the goal of the per-device key recommendation? If so then I understand why a recommendation of “use per-device keys to limit compromise to only the device that the attacker gained physical access to” makes sense. But am I missing something else?
In a physical access scenario, I’d personally rate the attacker gaining your WiFi credentials a much worse impact than gaining an encryption key shared between multiple ESPHome devices on that same network. The Best Practices don’t really offer any suggestions for protecting against that, but short of flash encryption-at-rest or per-device WiFi credentials (outside ESPHome’s scope) I’m not sure how it could, so I don’t really expect them to.
If managing per-device API encryption keys were trivial or automatically performed by the ESPHome Device Builder today, I wouldn’t even be asking this…but unfortunately following this Best Practice today requires the user to manually generate and manage keys between their secrets.yaml and all device configs. Understanding the reasoning will help me decide if doing this is really worth the benefit, and where. I might for example decide to share a key between devices that are hardwired physically into my home and use per-device keys for mobile devices that could easily go missing.
@bdraco you seem to be the author of this document so I suspect you might be the best person to answer this…would you mind answering any of my questions about this? (I’m certainly happy to hear input from others too.) It would be much appreciated; thanks!
Certainly, I understand that it’s a general best practice. That’s why I mention that if there was no manual management cost to using per-device keys, there would be no reason to do anything but that. These questions are me attempting to make that decision for myself. I’m trying to gauge whether there is anything specific and perhaps non-obvious about ESPHome that should affect my decision.
The incongruity between the Security Best Practices seeming to recommend it so strongly and unequivocally, but then the Device Builder not actually implementing any easy way to do this and so leaving it completely up to the user, struck me as odd.
The ease of using per-device keys/passwords even significantly regressed this month in 2026.9.0 with the introduction of encrypted OTA updates before any method for OTA key rotation exists. The old method of rotating an OTA password may have been a quirky workaround, but it at least existed. There’s no way at all to switch from a shared API encryption key to a unique key over OTA. This will vary for everyone, but in my case 11 out of 13 of my ESPHome devices would be pretty painful to physically uninstall and serial flash.
Yes I’d agree that it seems unlikely that many people actually use unique keys given these details. And I’m not complaining; I get that these are non-trivial features to introduce and take time, and appreciate all the work that goes into making ESPHome the fantastic project that it is. I still wanted to ask the question in case I got a “no you really should do this because […]” answer back.
I think a lot of HA stuff goes FAR overboard in this area.
Some gets forced on them (e.g. what can be done on a browser connection without https), but a lot is just silly, and I think API connections is one of them.
I don’t encrypt ANY of my API connections.
If an ESP device ends up with malware on it, it seems far more likely to attack my HA server or other servers on the network (and for HA it has the key), than it is for it to go after a different esp device. And to get malware on an esp device that I compile means someone already hijacked the supply chain that gets me the compilers and include files – so it’s likely that ALL my esp’s are also compromised.
Since esp communication is unicast, a foreign device on my LAN can’t “see” those connections anyway, the L2 switching structure prevents it. To get around that they have to already have hijacked my switch.
Now if talking OTA passwords that’s slightly different, but still presumes someone/thing is on my HA subnet trying to jump in the middle and upload an OTA file. And I suspect many people with those per-device passwords for API and OTA have a web browser running on the ESP without a password.
I think a huge amount of this comes from people who just feel a need to check a box… is everything encrypted – check. Long complex passwords you’ll write down and stick on your monitor – check. User has no idea how all this stuff really works but ChatGPT helped them general keys and lock it down – check.
Maybe it’s unfair to say “just check a box”, but I still feel it’s CYA stuff – no one will be faulted if there’s a breach for going overboard on security. Even if that overboard distracted for what really is important.
