ESPHome-датчик с зашифрованным API

Зашифрованный API у ESPHome-датчика проектируют как защиту одного канала связи, а не как общий режим безопасности устройства. Для каждого датчика создают отдельный 32-байтный ключ в формате Base64, включают шифрование собственного API ESPHome и передают тот же предварительно согласованный ключ Noise в Home Assistant через защищённый путь хранения учётных данных. Одновременно сохраняют раздельные меры для Wi-Fi, OTA, сетевой сегментации, физического доступа и восстановления.

Рабочая последовательность начинается не с генерации ключа, а с описания конкретного низковольтного узла: точной платы, датчика, питания, выводов и интерфейса восстановления. Затем исключают ненужные службы, прошивают устройство, подтверждают его личность и ожидаемые сущности, проверяют зашифрованное соединение и отказ неподготовленному клиенту. Проект останавливают до монтажа, если не подтверждены распиновка, путь возврата через последовательный интерфейс, отдельные учётные данные или граница сетевого доступа.

Что именно защищает шифрование API

Шифрование собственного API ESPHome защищает обмен между устройством и подключёнными клиентами, когда в конфигурации задан ключ. Пока ключ не установлен, считать канал зашифрованным нельзя. На стороне Home Assistant используется совпадающий предварительно согласованный ключ Noise. Успешное подключение означает, что стороны смогли установить защищённый сеанс с общим секретом, но этот наблюдаемый признак относится только к данному каналу.

Из этого нельзя делать вывод, что зашифрован весь трафик устройства. Шифрование API не заменяет защиту подключения к Wi-Fi, правила VLAN и межсетевого экрана, проверку OTA, защиту веб-сервера, настройки MQTT, контроль журналов или физическую защиту платы. Оно также не подтверждает происхождение прошивки, точность измерений и электрическую корректность монтажа.

Критерий проекта формулируют узко: Home Assistant подключается к определённому датчику по зашифрованному API, получает только ожидаемые сущности, а неподготовленный клиент не получает управление. Всё остальное проверяется отдельными средствами.

Граница доверия до настройки

До генерации секретов определяют участников обмена. В минимальной схеме датчик передаёт состояния одному доверенному экземпляру Home Assistant, а обслуживание выполняется через заранее выбранный путь прошивки и восстановления. Любой дополнительный клиент, веб-интерфейс, брокер или компонент должен появляться в схеме только вместе с объяснением, зачем он нужен и какое новое полномочие получает.

Такое описание позволяет не смешивать доступность и доверие. Устройство может быть видно в сети, но доступ по собственному API не считают подтверждённым без совпадающего ключа. Home Assistant может установить зашифрованный сеанс, но это не означает, что датчику разрешено выполнять действия в системе. OTA может обновлять прошивку, но его отдельный пароль не заменяется ключом API. Для каждого канала записывают собственную цель, секрет и критерий отказа.

Наблюдаемое доказательство формулируют заранее. Для API это успешное подключение доверенного клиента и отказ клиента без правильного ключа. Для состава устройства — совпадение платы, датчика и сущностей с проектной карточкой. Для уменьшения поверхности — отсутствие неиспользуемых служб в итоговой конфигурации. Для восстановления — доступный последовательный интерфейс и сохранённая офлайн-копия. Если признак нельзя проверить без раскрытия секрета или расширения сети, способ проверки пересматривают.

Сначала описывают низковольтный узел

Проект ограничивают документированной низковольтной частью. В него не включают коммутацию сетевого напряжения и не переносят выводы о безопасности канала данных на электрическую безопасность. Перед установкой записывают точную модель платы, модель датчика, способ питания, назначение каждого используемого вывода, интерфейс прошивки и способ входа в режим восстановления.

Такой список нужен не для формальности. Без точного обозначения платы нельзя подтвердить выбранные выводы, а без доступного последовательного интерфейса нельзя считать путь возврата документированным. Наблюдаемый результат подготовительного этапа — существует запись, по которой другой человек может определить, что прошивать, куда подключать низковольтные линии и как восстановить устройство без доступа к домашним секретам.

Минимальная карточка устройства

• точное обозначение платы и датчика;
• источник низковольтного питания и назначение линий;
• используемые выводы без предположений по похожей плате;
• интерфейс первичной прошивки и последовательного восстановления;
• назначение устройства, его сетевой сегмент и разрешённый клиент;
• место хранения конфигурации, резервной копии и учётных данных.

Если один из этих пунктов остаётся неизвестным, монтаж откладывают. Шифрование API не исправляет неясную распиновку и не создаёт путь восстановления после неудачной прошивки.

Раздельные секреты для одного устройства

Для каждого датчика создают собственный ключ API и отдельные учётные данные OTA. Повторное использование одного ключа на нескольких устройствах уничтожает изоляцию между ними: утечка общего секрета затрагивает весь набор, а ротация становится общей операцией. Уникальный ключ позволяет ограничить последствия одним узлом и заменить его без изменения остальных датчиков.

Ключ не помещают в публикуемую конфигурацию, снимки экрана, журнал установки или фрагмент, который предполагается отправлять для диагностики. Файл секретов уменьшает риск случайной публикации только при условии, что защищены само хранилище, резервные копии и история изменений. Если секрет когда-либо попал в общий репозиторий, архив переписки или открытый журнал, его считают раскрытым и заменяют.

Запись в журнале проекта должна подтверждать не значение ключа, а факт его отдельного создания, место ответственного хранения и дату ротации. Сам секрет в журнал не копируют. Для OTA используют другой уникальный пароль, потому что доступ к обновлению прошивки и доступ к API — разные полномочия.

Публичный шаблон и рабочая конфигурация

Удобно разделить конфигурацию на публикуемую структуру и закрытый набор значений. В общей части остаются описание платы, датчика, сущностей и включённых возможностей; ключ API, пароль OTA и данные Wi-Fi подставляются из защищённого хранилища. Это разделение снижает вероятность случайного копирования секрета, но не отменяет проверку архивов и истории изменений.

Перед отправкой конфигурации на разбор делают отдельную очищенную копию и просматривают её как самостоятельный документ. В ней не должно быть действующих ключей, паролей, сетевых имён, адресов домашней инфраструктуры и фрагментов журналов с конфиденциальными значениями. Если нельзя уверенно установить, где ещё сохранился секрет, его заменяют, а не пытаются считать прежнее значение достаточно скрытым.

Настройка ESPHome и Home Assistant

В конфигурации устройства включают собственный API ESPHome с шифрованием и подставляют секрет через механизм закрытого хранения. На стороне Home Assistant при добавлении интеграции указывают тот же 32-байтный ключ Base64. Устаревший пароль устройства не используют как замену шифрованию. Совпадение ключей должно быть результатом контролируемой передачи, а не копирования из публичного файла.

Действия Home Assistant, которые устройство может инициировать, расширяют его полномочия. Их оставляют выключенными, если датчику достаточно публиковать свои состояния. Когда такие действия действительно нужны, доверие задают явно и отдельно описывают, какие вызовы допустимы. Сам факт зашифрованного соединения не делает любой вызов безопасным и не подтверждает, что датчик должен иметь право менять состояние других систем.

После добавления интеграции проверяют не только факт успешного подключения. Сверяют имя устройства, ожидаемый набор сущностей, типы показаний и отсутствие лишних возможностей. Если Home Assistant показывает неизвестное устройство, неожиданные сущности или требует не предусмотренный секрет, работу прекращают и возвращаются к конфигурации.

Сеть остаётся отдельным уровнем защиты

ESPHome-узел размещают в доверенном сегменте, отделённом от случайных клиентов и не выставленном напрямую в интернет. Шифрование API не превращает устройство в узел, рассчитанный на враждебную сеть. Политика сегментации должна разрешать только необходимые потоки между датчиком, службой управления и инфраструктурой, которая действительно нужна для его работы.

Wi-Fi отвечает за присоединение устройства к сети и имеет собственные учётные данные. VLAN определяет логическую границу, а межсетевой экран — разрешённые направления обмена. Эти меры не следует смешивать с ключом API: успешный защищённый сеанс не доказывает правильность сетевых правил, а строгая сеть не заменяет шифрование прикладного канала.

Прямое интернет-доступное подключение исключают. Если для диагностики возникает желание временно открыть порт или перенести датчик в общий сегмент, сначала фиксируют причину и более узкий способ проверки. Критерий остановки — для работы требуется недокументированная внешняя доступность или широкое правило, назначение которого нельзя объяснить одним конкретным потоком.

Уменьшение поверхности служб

Веб-сервер, резервную точку доступа и внешние компоненты не включают без документированной необходимости. MQTT рассматривают отдельно. Ни одна из этих возможностей не получает защиту автоматически от ключа собственного API: для каждой нужны собственные основания, аутентификация, граница доступности и проверка поведения.

Если резервная точка доступа действительно нужна, её записывают как отдельный путь к устройству и проверяют отдельно. Когда предусмотрено последовательное восстановление, а беспроводной резерв не требуется, его отключают. Веб-сервер также не оставляют только ради редкой проверки показаний: наличие защищённого API ничего не говорит о защите веб-интерфейса.

MQTT рассматривают как отдельную систему обмена с собственными учётными данными и правилами брокера. OTA также требует отдельного пароля и проверки границы доступности обновления. Внешние компоненты требуют особой осторожности, поскольку могут содержать код вне поддержки безопасности основного проекта ESPHome. Если без такого компонента нельзя собрать датчик, его происхождение, назначение и влияние фиксируют отдельно; шифрование API не распространяет доверие на неизвестный код.

Проверка после прошивки

Первый запуск проводят в контролируемом месте, где доступны питание и последовательный интерфейс. Устройство не монтируют окончательно до завершения проверки. Перед подключением к Home Assistant сохраняют резервную копию рабочей конфигурации без раскрытия секретов и подтверждают, что восстановительная прошивка возможна через документированный интерфейс.

1. Проверка личности. Сверяют обозначение устройства, плату, назначение и сетевой сегмент. Неизвестный адрес или имя не принимают как достаточное подтверждение.
2. Проверка зашифрованного API. Home Assistant подключается только после ввода совпадающего ключа Noise, а соединение остаётся рабочим после обычного перезапуска.
3. Проверка сущностей. В интерфейсе появляются только предусмотренные датчики и диагностические элементы. Лишние сущности требуют разбора конфигурации.
4. Отрицательная проверка. Клиент без правильного ключа не должен получать рабочее подключение или управление через этот API.
5. Проверка полномочий. Действия Home Assistant со стороны устройства выключены либо ограничены явно описанной необходимостью.
6. Проверка восстановления. Сохраняется физический доступ к последовательному интерфейсу и понятный порядок возврата после ошибки сети, ключа или прошивки.

Отрицательная проверка не должна превращаться в публикацию секрета на снимке экрана или в общем журнале. В отчёт заносят результат: подключение с доверенным ключом успешно, подключение без него отклонено, ожидаемые сущности присутствуют, лишние службы отсутствуют. Значения ключей и домашние сетевые данные в отчёт не включают.

Журнал проверки и критерии остановки

Журнал делает результат воспроизводимым без раскрытия конфиденциальных данных. В нём указывают точную плату и датчик, версию рабочей конфигурации, используемые выводы, выбранный сегмент, перечень включённых служб, факт уникальности ключей, способ резервного хранения, результаты положительной и отрицательной проверки, а также путь последовательного восстановления.

Полезно отдельно записать границы вывода. Например: подтверждено зашифрованное соединение собственного API; не проверялись стойкость Wi-Fi, защита веб-сервера, безопасность внешнего компонента, калибровка показаний и происхождение прошивки. Такая запись не ослабляет проект, а не позволяет следующему обслуживанию принять один успешный тест за полный аудит устройства.

Работу прекращают и не переносят датчик в постоянное место, если ключ повторно используется, секрет обнаружен в истории или журнале, Home Assistant показывает неожиданные полномочия, доступ требует включения ненужного сервиса, сетевой сегмент допускает прямой интернет-доступ либо последовательное восстановление больше недоступно. После устранения причины проверку повторяют с начала затронутого этапа.

Ротация и восстановление

План ротации нужен до утечки, а не после неё. Для устройства должно быть понятно, где изменить ключ API, где заменить соответствующий ключ в Home Assistant и как выполнить операцию, если текущее сетевое подключение уже не работает. Отдельно описывают смену пароля OTA, потому что эти учётные данные не являются взаимозаменяемыми.

Офлайн-копия конфигурации должна позволять восстановить структуру проекта, но не обязана храниться вместе с открытым набором секретов. Резервная копия секретов защищается как самостоятельный актив. Публикуемая копия для обсуждения очищается от ключей, паролей, имён домашней сети, адресов и журналов, по которым можно восстановить инфраструктуру.

Итоговый ESPHome-датчик считается готовым не потому, что в конфигурации появилась строка шифрования, а потому, что подтверждены четыре независимых свойства: низковольтный монтаж описан, защищённый API работает только с нужным ключом, лишние службы и полномочия отсутствуют, а устройство можно восстановить и перевыпустить с новыми учётными данными. Это сохраняет управляемость узла без обещания, что один ключ автоматически защищает всю систему.