Безопасность локального администратора для счетчиков энергии IAMMETER: руководство пользователя

Безопасность локального администратора: руководство пользователя

Модуль безопасности локального администратора доступен в прошивке i.91.065.3 и новее.

Назначение

Модуль безопасности локального администратора защищает локальный веб-интерфейс устройства и чувствительные локальные API от несанкционированного доступа.

После включения этой функции для доступа потребуются имя пользователя и пароль администратора:

все Set API, доступные на странице тестирования WEM API;
GET API, возвращающие конфиденциальные данные конфигурации или выполняющие чувствительные операции;
операции локальной загрузки и обновления прошивки OTA.

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

Модуль предоставляет:

настраиваемые учетные данные администратора;
HTTP Basic Authentication для защищенных локальных API;
изменение учетных данных через веб-интерфейс или API;
процесс восстановления на основе подписи Ed25519 на случай, если пароль администратора был забыт.

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

Текущий локальный веб-интерфейс использует HTTP. HTTP Basic Authentication кодирует учетные данные, но не шифрует их. Используйте эту функцию в доверенной локальной сети, если только устройство не доступно через дополнительный защищенный транспортный механизм.

Настройка безопасности администратора в веб-интерфейсе

Откройте IP-адрес устройства в браузере.
Выберите вкладку Security (Безопасность).
Введите имя пользователя администратора.
Введите и подтвердите пароль администратора.
Выберите Enable Admin Security (Включить безопасность администратора).

Имя пользователя и пароль должны соответствовать следующим правилам:

длина: от 1 до 32 символов;
только видимые символы ASCII;
двоеточие (:), двойная кавычка (") или обратная косая черта (\) не допускаются.

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

Вкладка Security также может использоваться для:

изменения имени пользователя и пароля администратора;
проверки того, что аутентификация администратора включена;
включения или отключения службы Modbus/TCP на порту 502;
включения или отключения обнаружения SSDP;
отключения безопасности администратора после аутентификации с текущими учетными данными.

Вкладка Security локального веб-интерфейса IAMMETER, показывающая элементы управления учетными данными администратора и переключатели служб Modbus TCP и SSDP

Изменения состояния службы Modbus/TCP или SSDP требуют перезагрузки устройства. Если эти настройки никогда не сохранялись более ранней версией прошивки, обе службы по умолчанию включены для обратной совместимости.

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

API, не требующие Basic Authentication

Следующие конечные точки остаются доступными без заголовка Basic Authentication, чтобы веб-интерфейс мог загружать основную информацию об устройстве и чтобы процесс восстановления с подписью мог работать:

Метод	Конечная точка	Назначение
GET	`/api/admin/status`	Возвращает, включена ли безопасность администратора и поддерживается ли восстановление с подписью.
GET	`/api/admin/recovery_challenge`	Генерирует одноразовую полезную нагрузку восстановления для конкретного устройства.
GET	`/api/getbrand`	Возвращает конфигурацию брендинга локального веб-интерфейса.
GET	`/api/monitor`	Возвращает текущие данные мониторинга устройства и счетчика, используемые локальным веб-интерфейсом.
GET	`/api/monitorjson`	Возвращает ответ устаревшего мониторинга через путь совместимости `/api`.
GET	`/monitorjson`	Возвращает ответ устаревшего мониторинга.
GET	`/api/sntpstatus`	Возвращает текущий статус SNTP.
GET	`/info.xml`	Возвращает информацию об устройстве в стиле UPnP.
POST	`/api/admin/recovery`	Проверяет подпись восстановления IAMMETER и очищает забытые учетные данные администратора.

POST /api/admin/enable также можно вызывать без Basic Authentication, когда безопасность администратора в данный момент отключена, так как это конечная точка, используемая для начальной настройки. Если безопасность администратора уже включена, для вызова этой конечной точки с целью изменения или отключения конфигурации безопасности требуются действующие учетные данные администратора.

Статические файлы веб-интерфейса и другие ресурсы GET, не относящиеся к /api/, не являются конечными точками API и остаются общедоступными для чтения. Все остальные локальные конечные точки API считаются защищенными, когда безопасность администратора включена, включая все Set API, чувствительные GET API и операции с прошивкой OTA.

Справочник API

GET `/api/admin/status`

Возвращает текущий статус безопасности администратора. Аутентификация не требуется.

Пример ответа:

{
  "enabled": 1,
  "hasPassword": 1,
  "recoverySupported": 1,
  "modbusTcpEnabled": 1,
  "ssdpEnabled": 1
}

Поля:

enabled: 1, когда безопасность администратора включена; иначе 0.
hasPassword: 1, когда учетные данные администратора настроены.
recoverySupported: 1, если прошивка поддерживает восстановление администратора с подписью.
modbusTcpEnabled: 1, когда служба Modbus/TCP на порту 502 включена.
ssdpEnabled: 1, когда обнаружение SSDP включено.

POST `/api/admin/enable`

Включает или отключает безопасность администратора.

Включение безопасности администратора:

POST /api/admin/enable
Content-Type: application/json

{
  "enable": 1,
  "username": "admin",
  "password": "ExamplePassword"
}

Пример с curl:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

Отключение безопасности администратора:

POST /api/admin/enable
Authorization: Basic <base64...>
Content-Type: application/json

{
  "enable": 0
}

Если безопасность администратора уже включена, для вызова этого API требуются действующие учетные данные Basic Authentication.

Пример:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"enable":0}'

POST `/api/admin/password`

Изменяет имя пользователя и пароль администратора. Этот API защищен после включения безопасности администратора.

POST /api/admin/password
Authorization: Basic <current...>
Content-Type: application/json

{
  "username": "newadmin",
  "password": "NewExamplePassword"
}

Пример:

curl -X POST "http://<device-ip>/api/admin/password" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"username":"newadmin","password":"NewExamplePassword"}'

После успешного выполнения запроса используйте новые учетные данные для последующих защищенных запросов.

GET `/api/admin/check`

Проверяет, являются ли предоставленные учетные данные Basic Authentication действительными.

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/admin/check"

Успешный ответ:

{
  "successful": 1
}

Отсутствие или недействительность учетных данных приводит к HTTP 401 Unauthorized.

GET `/api/admin/recovery_challenge`

Создает одноразовую полезную нагрузку восстановления для конкретного устройства. Аутентификация не требуется, так как эта конечная точка сама по себе не сбрасывает учетные данные.

Пример ответа:

{
  "successful": 1,
  "alg": "ed25519",
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE"
}

Возвращенная payload должна быть отправлена в IAMMETER, когда требуется восстановление администратора.

Запрос нового вызова аннулирует предыдущий вызов. Вызов также становится недействительным после успешного восстановления или перезагрузки устройства.

POST `/api/admin/recovery`

Отправляет полезную нагрузку восстановления и подпись Ed25519, предоставленную IAMMETER.

POST /api/admin/recovery
Content-Type: application/json

{
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE",
  "signature": "128-hex-character-ed25519-signature"
}

Пример:

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE","signature":"<signature-from-IAMMETER>"}'

Если проверка подписи прошла успешно, устройство очищает локальные учетные данные администратора и отключает безопасность администратора. Затем можно настроить новое имя пользователя и пароль администратора.

Если на устройстве недостаточно свободной памяти для выполнения проверки подписи, API возвращает ответ, подобный следующему:

{
  "successful": 0,
  "message": "low memory, please change to standalone mode",
  "freeMemory": 18000,
  "minFreeRequired": 28000
}

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

Как работает восстановление пароля

Конструкция восстановления позволяет избежать добавления неаутентифицированной команды сброса к заводским настройкам, которая могла бы обойти защиту администратора.

Процесс использует пару открытого/закрытого ключей Ed25519:

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

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

Сценарии использования

Сценарий 1: Установка имени пользователя и пароля администратора

Самый простой способ — через веб-интерфейс:

Откройте http://<device-ip>/.
Откройте вкладку Security (Безопасность).
Введите новое имя пользователя и пароль администратора.
Подтвердите пароль.
Включите безопасность администратора.

Ту же операцию можно выполнить через POST /api/admin/enable:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

Проверьте результат:

curl "http://<device-ip>/api/admin/status"

Сценарий 2: Доступ к защищенным API с Basic Authentication

Для каждого последующего защищенного запроса отправляйте имя пользователя и пароль администратора в заголовке HTTP Basic Authentication.

Значение заголовка формируется следующим образом:

Authorization: Basic Base64(admin:ExamplePassword)

Например, учетные данные admin:ExamplePassword сначала объединяются, а затем кодируются в Base64. Большинство HTTP-клиентов выполняют это автоматически.

Использование curl:

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/getadv"

Использование явного заголовка:

TOKEN=$(printf '%s' 'admin:ExamplePassword' | base64)

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ${TOKEN}"

Для JSON POST запроса:

curl -X POST "http://<device-ip>/api/setadv" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '<setadv-json-body>'

Браузер обрабатывает этот заголовок автоматически после того, как администратор вводит учетные данные в запросе Basic Authentication.

Текущий веб-интерфейс загружает прошивку через POST /api/ota_successful.html. Устаревшая конечная точка POST /ota_successful.html остается доступной для старых версий веб-интерфейса и внешних инструментов. Обе конечные точки требуют Basic Authentication, когда безопасность администратора включена.

Вкладки веб-интерфейса ведут себя следующим образом при закрытии запроса аутентификации:

Settings и Wi-Fi не могут загрузить свои защищенные API конфигурации и отображают сообщение об аутентификации администратора.
System по-прежнему может показывать серийный номер, MAC-адрес и версию прошивки, так как эти значения были получены из общедоступной конечной точки /api/monitor. Загрузка OTA остается защищенной.
Security по-прежнему может показывать базовый статус, так как /api/admin/status является общедоступным. Изменение учетных данных и переключатели служб остаются защищенными.

Сценарий 3: Восстановление доступа после забытого пароля

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

Эта процедура предназначена только для случаев, когда были забыты и имя пользователя, и пароль администратора. Храните настроенные учетные данные в безопасном месте и не полагайтесь на процесс восстановления для регулярной смены учетных данных. Если текущие учетные данные все еще доступны, измените их непосредственно с вкладки Security или с помощью POST /api/admin/password.

Запросите новый вызов восстановления с устройства:
```
curl "http://<device-ip>/api/admin/recovery_challenge"
```
Скопируйте полное значение payload из ответа. Не редактируйте серийный номер, MAC-адрес, одноразовый номер, разделители или регистр букв.
Свяжитесь со службой поддержки IAMMETER по адресу support@devicebit.com и отправьте полную полезную нагрузку.
После подтверждения права собственности или авторизации службы IAMMETER подписывает полезную нагрузку и возвращает подпись Ed25519.

Отправьте исходную полезную нагрузку и возвращенную подпись на устройство:

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"<original-payload>","signature":"<signature-from-IAMMETER>"}'

После успешного ответа безопасность администратора будет отключена, а предыдущие учетные данные администратора будут очищены. Откройте вкладку Security или вызовите POST /api/admin/enable, чтобы установить новые учетные данные.

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

Безопасность локального администратора для счетчиков энергии IAMMETER: руководство пользователя

Безопасность локального администратора: руководство пользователя

Назначение

Настройка безопасности администратора в веб-интерфейсе

API, не требующие Basic Authentication

Справочник API

GET /api/admin/status

POST /api/admin/enable

POST /api/admin/password

GET /api/admin/check

GET /api/admin/recovery_challenge

POST /api/admin/recovery

Как работает восстановление пароля

Сценарии использования

Сценарий 1: Установка имени пользователя и пароля администратора

Сценарий 2: Доступ к защищенным API с Basic Authentication

Сценарий 3: Восстановление доступа после забытого пароля

Wi-Fi счетчик электроэнергии

GET `/api/admin/status`

POST `/api/admin/enable`

POST `/api/admin/password`

GET `/api/admin/check`

GET `/api/admin/recovery_challenge`

POST `/api/admin/recovery`