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

Lokal administrationssäkerhet: användarhandbok

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

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 resetknapp i hårdvara. För att undvika en oautentiserad återställningsfunktion som skulle kunna kringgå Admin Security använder enheten den signerade återställningsmekanism som beskrivs ovan.

Den här proceduren är endast avsedd för fall där både användarnamnet och lösenordet för administratören har glömts bort. Förvara de konfigurerade uppgifterna på en säker plats och undvik att förlita dig på återställningsprocessen för rutinmässiga uppgiftsändringar. Om de aktuella uppgifterna fortfarande finns tillgängliga ändrar du dem direkt från fliken Security eller med POST /api/admin/password.

1. Begär en ny recovery challenge från enheten:

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

2. Kopiera hela payload-värdet från svaret. Ändra inte SN, MAC, nonce, avgränsare eller versaler/gemener.

3. Kontakta IAMMETER:s support på support@devicebit.com och skicka in hela nyttolasten.

4. När ägarskap eller tjänsteauktorisering har bekräftats signerar IAMMETER nyttolasten och returnerar en Ed25519-signatur.

5. Skicka den ursprungliga nyttolasten och den returnerade signaturen till enheten:

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

6. Efter ett lyckat svar inaktiveras Admin Security och de tidigare administratörsuppgifterna rensas. Öppna fliken Security eller anropa POST /api/admin/enable för att ange nya uppgifter.

Starta inte om enheten och begär inte en annan challenge medan du väntar på signaturen. Båda åtgärderna ogiltigförklarar den inlämnade nyttolasten, och återställningsprocessen måste startas om med en ny challenge.