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

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

Na této stránce

• Účel
• Konfigurace zabezpečení administrace ve Web UI
• API, která nevyžadují Basic Authentication
• Reference API
• Jak funguje obnova hesla
• Scénáře použití
  • Scénář 1: Nastavení uživatelského jména a hesla správce
  • Scénář 2: Přístup k chráněným API pomocí Basic Authentication
  • Scénář 3: Obnova přístupu po zapomenutí hesla

Úč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 <base64-credentials>
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 <current-base64-credentials>
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(username:password)

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 ${TOKEN}"

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 resetování. Aby nevznikla neověřená funkce resetování umožňující obejít Admin Security, používá zařízení podepsaný mechanismus obnovení vázaný na konkrétní zařízení.

Tento postup použijte pouze při zapomenutí přihlašovacích údajů správce. Pokud aktuální údaje stále znáte, změňte je na kartě Security nebo pomocí POST /api/admin/password.

Postupujte podle úplného průvodce obnovením při zapomenutí hesla Admin Security

Postup obnovení je následující:

1. Vygenerujte jednorázový payload pomocí GET /api/admin/recovery_challenge.
2. Přihlaste se do aplikace Admin Recovery v systému IAMMETER Contributor. Služba ověří, že je váš účet oprávněn spravovat sériové číslo zařízení, a vrátí podpis Ed25519 pro přesně tento payload.
3. Odešlete nezměněný payload a podpis do POST /api/admin/recovery. Po úspěšném ověření se Admin Security vypne a předchozí přihlašovací údaje místního správce se vymažou.

Před dokončením obnovení zařízení nerestartujte, neobnovujte stránku výzvy ani nežádejte o další výzvu. Každá z těchto akcí zneplatní aktuální nonce, takže je nutné začít znovu s novým payloadem.

Samostatný průvodce obnovením obsahuje snímky obrazovky, úplné příkazy curl, řešení odmítnutých podpisů a postup obnovení při nedostatku volné paměti.