Zabezpečení místní administrace elektroměrů IAMMETER: Uživatelská příručka

Zabezpečení místní administrace: Uživatelská příručka

Modul zabezpečení místní administrace je k dispozici ve firmwaru i.91.065.3 a novějším.

Účel

Modul zabezpečení místní administrace chrání místní Web UI zařízení a citlivá místní API před neoprávněným přístupem.

Po povolení této funkce je pro následující operace vyžadováno uživatelské jméno a heslo správce:

• všechna rozhraní Set API dostupná na stránce WEM API Test;
• GET API, která vracejí citlivá konfigurační data nebo provádějí citlivé operace;
• místní operace nahrávání a aktualizace firmwaru OTA.

To zahrnuje operace, jako je změna nastavení sítě nebo nastavení nahrávání, aktualizace firmwaru, restartování zařízení, obnova továrního nastavení a úprava dalších citlivých konfiguračních parametrů.

Modul poskytuje:

• konfigurovatelné přihlašovací údaje správce;
• HTTP Basic Authentication pro chráněná místní API;
• změnu přihlašovacích údajů prostřednictvím Web UI nebo API;
• proces obnovy založený na podpisu Ed25519 pro případ zapomenutí hesla správce.

Funkce je ve výchozím stavu pro kompatibilitu se starším firmwarem zakázána. Před účinností chráněného přístupu ji musíte povolit a nakonfigurovat.

Současné místní Web UI používá HTTP. HTTP Basic Authentication kóduje přihlašovací údaje, ale nešifruje je. Používejte tuto funkci v důvěryhodné místní síti, pokud k zařízení nepřistupujete prostřednictvím dalšího zabezpečeného přenosového mechanismu.

Konfigurace zabezpečení administrace ve Web UI

1. Otevřete v prohlížeči IP adresu zařízení.
2. Vyberte kartu Security.
3. Zadejte uživatelské jméno správce.
4. Zadejte a potvrďte heslo správce.
5. Vyberte Enable Admin Security.

Uživatelské jméno a heslo musí splňovat následující pravidla:

• délka: 1 až 32 znaků;
• pouze viditelné znaky ASCII;
• dvojtečka (:), uvozovka (") a zpětné lomítko (\) nejsou povoleny.

Po povolení zabezpečení administrace zobrazí prohlížeč při přístupu k chráněné stránce nebo API výzvu k ověření. Zadejte nakonfigurované uživatelské jméno a heslo správce.

Kartu Security lze také použít k:

• změně uživatelského jména a hesla správce;
• ověření, že je ověřování správce povoleno;
• povolení nebo zakázání služby Modbus/TCP na portu 502;
• povolení nebo zakázání zjišťování SSDP;
• zakázání zabezpečení administrace po ověření aktuálními přihlašovacími údaji.

Změny stavu služeb Modbus/TCP nebo SSDP vyžadují restart zařízení. Pokud tato nastavení nebyla dřívějším firmwarem nikdy uložena, jsou obě služby ve výchozím stavu pro zpětnou kompatibilitu povoleny.

Prohlížeče mohou ukládat přihlašovací údaje Basic Authentication pro adresu zařízení do mezipaměti. Po změně hesla se prohlížeč může nejprve pokusit použít staré přihlašovací údaje a poté zobrazit novou výzvu k ověření. Zavření všech oken prohlížeče nebo použití okna v anonymním režimu může rovněž vynutit nové přihlášení.

API, která nevyžadují Basic Authentication

Následující endpointy zůstávají dostupné bez hlavičky Basic Authentication, aby Web UI mohlo načíst základní informace o zařízení a mohl fungovat proces podepsané obnovy:

POST /api/admin/enable je také možné volat bez Basic Authentication, pokud je zabezpečení administrace aktuálně zakázáno, protože se jedná o endpoint používaný pro počáteční nastavení. Pokud je zabezpečení administrace již povoleno, jsou před změnou nebo zakázáním konfigurace zabezpečení prostřednictvím tohoto endpointu vyžadovány aktuální platné přihlašovací údaje správce.

Statické soubory Web UI a další GET zdroje mimo /api/ nejsou API endpointy a zůstávají veřejně čitelné. Všechny ostatní místní API endpointy jsou při povoleném zabezpečení administrace považovány za chráněné, včetně všech rozhraní Set API, citlivých GET API a operací s firmwarem OTA.

Reference API

GET /api/admin/status

Vrací aktuální stav zabezpečení administrace. Ověřování není vyžadováno.

Příklad odpovědi:

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

Pole:

• enabled: 1, pokud je zabezpečení administrace povoleno; jinak 0.
• hasPassword: 1, pokud byly nakonfigurovány přihlašovací údaje správce.
• recoverySupported: 1, pokud firmware podporuje podepsanou obnovu správce.
• modbusTcpEnabled: 1, pokud je povolena služba Modbus/TCP na portu 502.
• ssdpEnabled: 1, pokud je povoleno zjišťování SSDP.

POST /api/admin/enable

Povoluje nebo zakazuje zabezpečení administrace.

Povolení zabezpečení administrace:

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

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

Příklad s curl:

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

Zakázání zabezpečení administrace:

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

{
  "enable": 0
}

Pokud je zabezpečení administrace již povoleno, jsou pro volání tohoto API vyžadovány aktuální platné přihlašovací údaje Basic Authentication.

Příklad:

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

POST /api/admin/password

Mění uživatelské jméno a heslo správce. Toto API je po povolení zabezpečení administrace chráněno.

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

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

Příklad:

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

Po úspěšném provedení požadavku používejte pro následné chráněné požadavky nové přihlašovací údaje.

GET /api/admin/check

Ověřuje, zda jsou dodané přihlašovací údaje Basic Authentication platné.

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

Úspěšná odpověď:

{
  "successful": 1
}

Chybějící nebo neplatné přihlašovací údaje vedou k odpovědi HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Vytváří jednorázovou datovou část (payload) pro obnovu specifickou pro dané zařízení. Ověřování není vyžadováno, protože tento endpoint sám o sobě neresetuje přihlašovací údaje.

Příklad odpovědi:

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

Vrácený payload musí být zaslán společnosti IAMMETER, pokud je vyžadována obnova správce.

Vyžádání nové výzvy zneplatní předchozí výzvu. Výzva je také zneplatněna po úspěšné obnově nebo restartu zařízení.

POST /api/admin/recovery

Odesílá datovou část pro obnovu a podpis Ed25519 dodaný společností 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"
}

Příklad:

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

Pokud ověření podpisu proběhne úspěšně, zařízení vymaže místní přihlašovací údaje správce a zakáže zabezpečení administrace. Poté lze nakonfigurovat nové uživatelské jméno a heslo správce.

Pokud zařízení nemá dostatek volné paměti pro spuštění ověření podpisu, API vrátí odpověď podobnou této:

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

V takovém případě snižte využití paměti a před opakováním si vyžádejte novou výzvu k obnově. Pokud heslo není k dispozici a provozní režim nelze změnit, restartujte zařízení a proveďte obnovu dříve, než připojení MQTTS nebo HTTPS spotřebuje další paměť.

Jak funguje obnova hesla

Návrh obnovy se vyhýbá přidání příkazu pro tovární reset bez ověření, který by mohl obejít ochranu správce.

Proces používá pár veřejného a soukromého klíče Ed25519:

• firmware zařízení obsahuje pouze veřejný klíč pro obnovu IAMMETER;
• odpovídající soukromý klíč je uchováván společností IAMMETER a není uložen v zařízení;
• zařízení vytvoří datovou část obsahující požadovanou operaci, SN zařízení, MAC zařízení a jednorázový nonce;
• IAMMETER podepíše přesně tuto datovou část soukromým klíčem pro obnovu;
• zařízení ověří podpis svým vloženým veřejným klíčem;
• pouze platný podpis pro aktuální zařízení a aktuální nonce může vymazat konfiguraci správce.

Nonce je uložen pouze v paměti RAM. Zneplatní se při restartu zařízení, při vyžádání další výzvy nebo po jedné úspěšné obnově. Starou datovou část a podpis proto nelze znovu použít pro pozdější relaci obnovy.

Scénáře použití

Scénář 1: Nastavení uživatelského jména a hesla správce

Nejjednodušší metodou je Web UI:

1. Otevřete http://<device-ip>/.
2. Otevřete kartu Security.
3. Zadejte nové uživatelské jméno a heslo správce.
4. Potvrďte heslo.
5. Povolte zabezpečení administrace.

Stejnou operaci lze provést prostřednictvím 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"}'

Ověřte výsledek:

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

Scénář 2: Přístup k chráněným API pomocí Basic Authentication

Pro každý následující chráněný požadavek odešlete uživatelské jméno a heslo správce v hlavičce HTTP Basic Authentication.

Hodnota hlavičky se sestaví následovně:

Authorization: Basic Base64...ord)

Například přihlašovací údaje admin:ExamplePassword se nejprve zkombinují a poté zakódují do Base64. Většina HTTP klientů to provede automaticky.

Pomocí curl:

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

Pomocí explicitní hlavičky:

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

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ***"

Pro požadavek JSON POST:

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

Prohlížeč tuto hlavičku zpracuje automaticky poté, co správce zadá přihlašovací údaje do výzvy Basic Authentication.

Současné Web UI nahrává firmware na POST /api/ota_successful.html. Starší endpoint POST /ota_successful.html zůstává k dispozici pro starší verze Web UI a externí nástroje. Oba endpointy vyžadují Basic Authentication, pokud je povoleno zabezpečení administrace.

Karty Web UI se po zavření výzvy k ověření chovají následovně:

• Settings a Wi-Fi nemohou načíst své chráněné konfigurační API a zobrazí zprávu o ověření správce.
• System může stále zobrazovat SN, MAC a verzi firmwaru, protože tyto hodnoty byly získány z veřejného endpointu /api/monitor. Nahrávání OTA zůstává chráněno.
• Security může stále zobrazovat základní stav, protože /api/admin/status je veřejný. Změny přihlašovacích údajů a změny přepínačů služeb zůstávají chráněné.

Scénář 3: Obnova přístupu po zapomenutí hesla

Zařízení nemá hardwarové tlačítko reset. Aby se předešlo přidání funkce resetu bez ověření, která by mohla obejít zabezpečení administrace, používá zařízení výše popsaný mechanismus podepsané obnovy.

Tento postup je určen pouze pro případy, kdy bylo zapomenuto uživatelské jméno i heslo správce. Uchovávejte nakonfigurované přihlašovací údaje na bezpečném místě a nespoléhejte se při běžných změnách přihlašovacích údajů na proces obnovy. Pokud jsou aktuální přihlašovací údaje stále k dispozici, změňte je přímo na kartě Security nebo pomocí POST /api/admin/password.

1. Vyžádejte si od zařízení novou výzvu k obnově:

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

2. Zkopírujte z odpovědi celou hodnotu payload. Neupravujte SN, MAC, nonce, oddělovače ani velikost písmen.

3. Kontaktujte podporu IAMMETER na adrese support@devicebit.com a odešlete kompletní datovou část.

4. Po potvrzení vlastnictví nebo autorizace služby IAMMETER datovou část podepíše a vrátí podpis Ed25519.

5. Odešlete zařízení původní datovou část a vrácený podpis:

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

6. Po úspěšné odpovědi je zabezpečení administrace zakázáno a předchozí přihlašovací údaje správce jsou vymazány. Otevřete kartu Security nebo zavolejte POST /api/admin/enable a nastavte nové přihlašovací údaje.

Během čekání na podpis zařízení nerestartujte ani nevyžadujte další výzvu. Oba tyto úkony zneplatní odeslanou datovou část a proces obnovy bude nutné zahájit znovu s novou výzvou.