Lokal administrationssäkerhet för IAMMETER-energimätare: användarhandbok

Modulen för lokal administrationssäkerhet finns i firmware i.91.065.3 och senare.

På den här sidan

• Syfte
• Konfigurera administratörssäkerhet i webbgränssnittet
• API:er som inte kräver Basic Authentication
• API-referens
• Så fungerar lösenordsåterställning
• Användningsscenarier
  • Scenario 1: Ange användarnamn och lösenord för administratören
  • Scenario 2: Komma åt skyddade API:er med Basic Authentication
  • Scenario 3: Återfå åtkomsten när du har glömt lösenordet

Syfte

Modulen för lokal administrationssäkerhet skyddar enhetens lokala webbgränssnitt och känsliga lokala API:er från obehörig åtkomst.

När funktionen är aktiverad krävs ett användarnamn och lösenord för administratören:

• för alla Set-API:er på WEM API Test-sidan;
• för GET-API:er som returnerar känslig konfigurationsdata eller utför känsliga åtgärder;
• för lokal firmware-uppladdning och uppgradering via OTA.

Det omfattar åtgärder som att ändra nätverks- eller uppladdningsinställningar, uppdatera firmware, starta om enheten, återställa fabriksinställningar och ändra andra känsliga konfigurationsparametrar.

Modulen erbjuder:

• konfigurerbara administratörsuppgifter;
• HTTP Basic Authentication för skyddade lokala API:er;
• ändring av administratörsuppgifterna via webbgränssnittet eller API:t;
• en återställningsprocess baserad på Ed25519-signatur om administratörslösenordet glöms bort.

Funktionen är inaktiverad som standard för kompatibilitet med äldre firmware. Den måste aktiveras och konfigureras innan skyddad åtkomst börjar gälla.

Det aktuella lokala webbgränssnittet använder HTTP. HTTP Basic Authentication kodar uppgifterna men krypterar dem inte. Använd funktionen i ett betrott lokalt nätverk, om inte enheten nås via en ytterligare säker transportmekanism.

Konfigurera administratörssäkerhet i webbgränssnittet

1. Öppna enhetens IP-adress i en webbläsare.
2. Välj fliken Security.
3. Ange ett användarnamn för administratören.
4. Ange och bekräfta administratörslösenordet.
5. Välj Enable Admin Security.

Användarnamnet och lösenordet måste uppfylla följande regler:

• längd: 1 till 32 tecken;
• endast synliga ASCII-tecken;
• kolon (:), dubbelcitationstecken (") eller omvänt snedstreck (\) är inte tillåtet.

När Admin Security är aktiverat visar webbläsaren en autentiseringsruta när en skyddad sida eller ett API används. Ange det konfigurerade användarnamnet och lösenordet.

Fliken Security kan också användas för att:

• ändra administratörens användarnamn och lösenord;
• verifiera att administratörsautentiseringen är aktiverad;
• aktivera eller inaktivera Modbus/TCP-tjänsten på port 502;
• aktivera eller inaktivera SSDP-sökning;
• inaktivera Admin Security efter autentisering med de aktuella uppgifterna.

Ändringar av Modbus/TCP- eller SSDP-tjänstens status kräver en omstart av enheten. Om dessa inställningar aldrig har sparats av tidigare firmware är båda tjänsterna aktiverade som standard för bakåtkompatibilitet.

Webbläsare kan cacha Basic Authentication-uppgifterna för enhetens adress. Efter ett lösenordsbyte kan webbläsaren först försöka med de gamla uppgifterna och sedan visa en ny autentiseringsruta. Att stänga alla webbläsarfönster eller använda ett privat fönster kan också tvinga fram en ny inloggning.

API:er som inte kräver Basic Authentication

Följande endpoints är fortfarande tillgängliga utan Basic Authentication-header så att webbgränssnittet kan hämta grundläggande enhetsinformation och den signerade återställningsprocessen kan fungera:

POST /api/admin/enable kan också anropas utan Basic Authentication när Admin Security för närvarande är inaktiverat, eftersom det är endpointen för den första installationen. Om Admin Security redan är aktiverat krävs aktuella giltiga administratörsuppgifter innan endpointen kan ändra eller inaktivera säkerhetskonfigurationen.

Statiska webbgränssnittsfiler och andra GET-resurser utanför /api/ är inte API-endpoints och förblir allmänt läsbara. Alla andra lokala API-endpoints behandlas som skyddade när Admin Security är aktiverat, inklusive alla Set-API:er, känsliga GET-API:er och OTA-åtgärder för firmware.

API-referens

GET /api/admin/status

Returnerar aktuell status för Admin Security. Autentisering krävs inte.

Exempel på svar:

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

Fält:

• enabled: 1 när Admin Security är aktiverat, annars 0.
• hasPassword: 1 när administratörsuppgifter har konfigurerats.
• recoverySupported: 1 när signerad återställning av administratören stöds av firmware.
• modbusTcpEnabled: 1 när Modbus/TCP-tjänsten på port 502 är aktiverad.
• ssdpEnabled: 1 när SSDP-sökning är aktiverad.

POST /api/admin/enable

Aktiverar eller inaktiverar Admin Security.

Aktivera Admin Security:

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

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

Exempel med curl:

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

Inaktivera Admin Security:

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

{
  "enable": 0
}

Om Admin Security redan är aktiverat krävs aktuella giltiga Basic Authentication-uppgifter för att anropa detta API.

Exempel:

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

POST /api/admin/password

Ändrar administratörens användarnamn och lösenord. Detta API är skyddat när Admin Security har aktiverats.

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

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

Exempel:

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

Efter att begäran har lyckats kan du använda de nya uppgifterna för efterföljande skyddade förfrågningar.

GET /api/admin/check

Kontrollerar om de angivna Basic Authentication-uppgifterna är giltiga.

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

Framgångsrikt svar:

{
  "successful": 1
}

Saknade eller ogiltiga uppgifter ger HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Skapar en enhetsspecifik engångsnyttolast för återställning. Autentisering krävs inte eftersom endpointen inte återställer uppgifterna på egen hand.

Exempel på svar:

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

Den returnerade payload-strängen måste skickas till IAMMETER när administratörsåterställning behövs.

När en ny challenge begärs ogiltigförklaras den föregående. En challenge ogiltigförklaras också efter en lyckad återställning eller en omstart av enheten.

POST /api/admin/recovery

Skickar in återställningsnyttolasten tillsammans med den Ed25519-signatur som IAMMETER har returnerat.

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

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

Exempel:

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

Om signaturverifieringen lyckas rensar enheten de lokala administratörsuppgifterna och inaktiverar Admin Security. Ett nytt användarnamn och lösenord för administratören kan sedan konfigureras.

Om enheten inte har tillräckligt med ledigt minne för signaturverifieringen returnerar API:et ett svar i stil med:

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

I så fall minskar du minnesanvändningen och begär en ny recovery challenge innan du försöker igen. Om lösenordet inte är tillgängligt och driftläget inte kan ändras startar du om enheten och utför återställningen innan en MQTTS- eller HTTPS-anslutning förbrukar ytterligare minne.

Så fungerar lösenordsåterställning

Återställningsdesignen undviker ett oautentiserat fabriksåterställningskommando som skulle kunna kringgå administratörsskyddet.

Processen använder ett Ed25519-nyckelpar med publik och privat nyckel:

• enhetens firmware innehåller bara IAMMETER:s publika återställningsnyckel;
• motsvarande privata nyckel förvaras hos IAMMETER och lagras inte på enheten;
• enheten skapar en nyttolast med den begärda åtgärden, enhetens SN, enhetens MAC och en engångsnonce;
• IAMMETER signerar exakt den nyttolasten med den privata återställningsnyckeln;
• enheten verifierar signaturen med sin inbyggda publika nyckel;
• endast en giltig signatur för den aktuella enheten och den aktuella noncen kan rensa administratörskonfigurationen.

Noncen lagras bara i RAM. Den blir ogiltig när enheten startas om, när en annan challenge begärs eller efter en lyckad återställning. Därför kan en gammal nyttolast och signatur inte återanvändas i en senare återställningssession.

Användningsscenarier

Scenario 1: Ange användarnamn och lösenord för administratören

Det enklaste sättet är webbgränssnittet:

1. Öppna http://<device-ip>/.
2. Öppna fliken Security.
3. Ange det nya användarnamnet och lösenordet för administratören.
4. Bekräfta lösenordet.
5. Aktivera Admin Security.

Samma åtgärd kan utföras via 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"}'

Verifiera resultatet:

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

Scenario 2: Komma åt skyddade API:er med Basic Authentication

Skicka administratörens användarnamn och lösenord i HTTP Basic Authentication-headern för varje efterföljande skyddad förfrågan.

Header-värdet konstrueras så här:

Authorization: Basic Base64(username:password)

Exempelvis kombineras uppgifterna admin:ExamplePassword först och kodas sedan med Base64. De flesta HTTP-klienter gör detta automatiskt.

Med curl:

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

Med en explicit header:

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

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

För en JSON POST-förfrågan:

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

Webbläsaren hanterar den här headern automatiskt när administratören har angett uppgifterna i Basic Authentication-rutan.

Det aktuella webbgränssnittet laddar upp firmware till POST /api/ota_successful.html. Den äldre POST /ota_successful.html-endpointen finns kvar för äldre webbgränssnitt och externa verktyg. Båda endpoints kräver Basic Authentication när Admin Security är aktiverat.

Webbgränssnittets flikar beter sig på följande sätt när autentiseringsrutan stängs:

• Settings och Wi-Fi kan inte ladda sina skyddade konfigurations-API:er och visar ett meddelande om administratörsautentisering.
• System kan fortfarande visa SN, MAC och firmwareversion eftersom dessa värden hämtades från den publika /api/monitor-endpointen. OTA-uppladdning förblir skyddad.
• Security kan fortfarande visa grundläggande status eftersom /api/admin/status är publik. Ändringar av uppgifter och tjänsteomkopplare förblir skyddade.

Scenario 3: Återfå åtkomsten när du har glömt lösenordet

Enheten har ingen fysisk återställningsknapp. För att inte lägga till en återställningsfunktion utan autentisering som kan kringgå Admin Security använder den en signerad, enhetsspecifik återställningsmekanism.

Använd endast den här proceduren om administratörsuppgifterna har glömts. Om du fortfarande känner till de aktuella uppgifterna ändrar du dem på fliken Security eller med POST /api/admin/password.

Följ den fullständiga steg-för-steg-guiden för återställning vid glömt Admin Security-lösenord

Återställningen går till så här:

1. Generera en engångsnyttolast via GET /api/admin/recovery_challenge.
2. Logga in i programmet Admin Recovery i IAMMETER Contributor-systemet. Tjänsten verifierar att ditt konto har behörighet att hantera enhetens serienummer och returnerar en Ed25519-signatur för exakt den nyttolasten.
3. Skicka den oförändrade nyttolasten och signaturen till POST /api/admin/recovery. Efter godkänd verifiering inaktiveras Admin Security och de tidigare lokala administratörsuppgifterna raderas.

Starta inte om enheten, uppdatera inte challenge-sidan och begär inte en annan challenge innan återställningen är klar. Alla dessa åtgärder gör aktuell nonce ogiltig, så du måste börja om med en ny nyttolast.

Den särskilda återställningsguiden innehåller skärmbilder, fullständiga curl-kommandon, felsökning av avvisade signaturer och återställningsproceduren vid lite ledigt minne.