Local Admin Security за електромерите IAMMETER: ръководство за потребителя

Модулът Local Admin Security е наличен във фърмуер i.91.065.3 и по-нови версии.

На тази страница

• Предназначение
• Конфигуриране на Admin Security в уеб интерфейса
• API, които не изискват Basic Authentication
• Справочник за API
• Как работи възстановяването на паролата
• Сценарии за използване
  • Сценарий 1: Задаване на администраторско потребителско име и парола
  • Сценарий 2: Достъп до защитени API с Basic Authentication
  • Сценарий 3: Възстановяване на достъпа при забравена парола

Предназначение

Модулът Local Admin Security защитава локалния уеб интерфейс и чувствителните локални API на устройството от неоторизиран достъп.

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

• всички Set API, налични на страницата WEM API Test;
• GET API, които връщат чувствителни конфигурационни данни или изпълняват чувствителни операции;
• локално качване и обновяване на фърмуера чрез OTA.

Това включва промяна на мрежови настройки или настройки за качване, обновяване на фърмуера, рестартиране на устройството, възстановяване на фабричните настройки и промяна на други чувствителни конфигурационни параметри.

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

• конфигурируеми администраторски данни за достъп;
• HTTP Basic Authentication за защитените локални API;
• промяна на данните за достъп чрез уеб интерфейса или API;
• възстановяване чрез подпис Ed25519 при забравена администраторска парола.

Функцията е изключена по подразбиране за съвместимост с по-стария фърмуер. Тя трябва да бъде включена и конфигурирана, преди защитата на достъпа да влезе в сила.

Текущият локален уеб интерфейс използва HTTP. HTTP Basic Authentication кодира данните за достъп, но не ги шифрова. Използвайте функцията в доверена локална мрежа, освен ако достъпът до устройството не преминава през допълнителен защитен транспортен механизъм.

Конфигуриране на Admin Security в уеб интерфейса

1. Отворете IP адреса на устройството в браузър.
2. Изберете раздела Security.
3. Въведете администраторско потребителско име.
4. Въведете и потвърдете администраторската парола.
5. Изберете Enable Admin Security.

Потребителското име и паролата трябва да отговарят на следните правила:

• дължина: от 1 до 32 знака;
• само видими ASCII знаци;
• не се допускат двоеточие (:), двойна кавичка (") или обратна наклонена черта (\).

След включване на Admin Security браузърът показва подкана за удостоверяване при достъп до защитена страница или API. Въведете конфигурираните администраторско потребителско име и парола.

Разделът Security може да се използва и за:

• промяна на администраторското потребителско име и парола;
• проверка дали администраторското удостоверяване е включено;
• включване или изключване на услугата Modbus/TCP на порт 502;
• включване или изключване на откриването чрез SSDP;
• изключване на Admin Security след удостоверяване с текущите данни.

Промяната на състоянието на Modbus/TCP или SSDP изисква рестартиране на устройството. Ако тези настройки никога не са били записвани от по-стар фърмуер, двете услуги са включени по подразбиране за обратна съвместимост.

Браузърите могат да кешират данните за Basic Authentication за адреса на устройството. След промяна на паролата браузърът може първо да опита старите данни и след това да покаже нова подкана за удостоверяване. Затварянето на всички прозорци или използването на прозорец за поверително сърфиране също може да наложи ново влизане.

API, които не изискват Basic Authentication

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

POST /api/admin/enable може да се извика без Basic Authentication и когато Admin Security е изключено, защото тази крайна точка се използва за първоначална настройка. Ако Admin Security вече е включено, са необходими текущите валидни администраторски данни, преди тази крайна точка да промени или изключи защитата.

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

Справочник за API

GET /api/admin/status

Връща текущото състояние на Admin Security. Не се изисква удостоверяване.

Примерен отговор:

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

Полета:

• enabled: 1, когато Admin Security е включено; в противен случай 0.
• hasPassword: 1, когато са конфигурирани администраторски данни.
• recoverySupported: 1, когато фърмуерът поддържа администраторско възстановяване с подпис.
• modbusTcpEnabled: 1, когато услугата Modbus/TCP на порт 502 е включена.
• ssdpEnabled: 1, когато откриването чрез SSDP е включено.

POST /api/admin/enable

Включва или изключва Admin Security.

Включване на Admin Security:

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"}'

Изключване на Admin Security:

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

{
  "enable": 0
}

Ако Admin Security вече е включено, за извикване на този 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 е защитен след включване на Admin Security.

POST /api/admin/password
Authorization: Basic <current-base64-credentials>
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

Създава еднократен payload за възстановяване, специфичен за устройството. Не се изисква удостоверяване, защото тази крайна точка сама по себе си не нулира данните за достъп.

Примерен отговор:

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

Върнатият payload трябва да бъде изпратен на IAMMETER, когато е необходимо възстановяване на администраторския достъп.

Заявяването на ново предизвикателство обезсилва предишното. Предизвикателството се обезсилва и след успешно възстановяване или рестартиране на устройството.

POST /api/admin/recovery

Изпраща payload за възстановяване и подписа 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>"}'

Ако проверката на подписа е успешна, устройството изчиства локалните администраторски данни и изключва Admin Security. След това могат да се зададат ново администраторско потребителско име и парола.

Ако устройството няма достатъчно свободна памет за проверката на подписа, API връща отговор, подобен на:

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

В този случай намалете използването на памет и заявете ново предизвикателство за възстановяване, преди да опитате отново. Ако паролата не е налична и режимът на работа не може да се промени, рестартирайте устройството и извършете възстановяването, преди връзка MQTTS или HTTPS да заеме допълнителна памет.

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

Дизайнът на възстановяването избягва добавянето на команда за фабрично нулиране без удостоверяване, която би могла да заобиколи администраторската защита.

Процесът използва двойка публичен/частен ключ Ed25519:

• фърмуерът съдържа само публичния ключ за възстановяване на IAMMETER;
• съответният частен ключ се пази от IAMMETER и не се съхранява в устройството;
• устройството създава payload със заявената операция, SN на устройството, MAC адрес и еднократен nonce;
• IAMMETER подписва точно този payload с частния ключ за възстановяване;
• устройството проверява подписа с вградения си публичен ключ;
• само валиден подпис за текущото устройство и текущия nonce може да изчисти администраторската конфигурация.

Nonce се съхранява само в RAM. Той става невалиден при рестартиране, заявяване на друго предизвикателство или след едно успешно възстановяване. Затова стар payload и подпис не могат да се използват повторно в следваща сесия за възстановяване.

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

Сценарий 1: Задаване на администраторско потребителско име и парола

Най-лесният начин е чрез уеб интерфейса:

1. Отворете http://<device-ip>/.
2. Отворете раздела Security.
3. Въведете новото администраторско потребителско име и парола.
4. Потвърдете паролата.
5. Включете Admin 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(username:password)

Например данните 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, когато Admin Security е включено.

Разделите на уеб интерфейса се държат по следния начин при затваряне на подканата за удостоверяване:

• Settings и Wi-Fi не могат да заредят защитените си конфигурационни API и показват съобщение за администраторско удостоверяване.
• System може да показва SN, MAC и версията на фърмуера, защото тези стойности са получени от публичната крайна точка /api/monitor. Качването чрез OTA остава защитено.
• Security може да показва основното състояние, защото /api/admin/status е публична. Промените на данните за достъп и превключвателите на услугите остават защитени.

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

Устройството няма хардуерен бутон за нулиране. За да се избегне незащитена функция за нулиране, която може да заобиколи Admin Security, то използва подписан механизъм за възстановяване, специфичен за устройството.

Използвайте тази процедура само ако сте забравили администраторските данни. Ако още знаете текущите данни, променете ги от раздела Security или с POST /api/admin/password.

Следвайте пълното ръководство стъпка по стъпка за възстановяване при забравена парола Admin Security

Процесът за възстановяване е:

1. Генерирайте еднократен payload чрез GET /api/admin/recovery_challenge.
2. Влезте в приложението Admin Recovery на системата IAMMETER Contributor. Услугата проверява дали профилът ви има право да управлява SN на устройството и връща подпис Ed25519 за точно този payload.
3. Изпратете непроменения payload и подписа към POST /api/admin/recovery. След успешна проверка Admin Security се изключва и предишните локални администраторски данни се изчистват.

Не рестартирайте устройството, не обновявайте страницата на предизвикателството и не заявявайте друго предизвикателство, преди да завършите възстановяването. Всяко от тези действия обезсилва текущия nonce и изисква ново начало с нов payload.

Специалното ръководство за възстановяване включва снимки на екрана, пълни команди curl, отстраняване на проблеми с отхвърлени подписи и процедура при малко свободна памет.