Lokale Beveiligingsmodule voor IAMMETER Energiemeters: Gebruikershandleiding

Lokale Beveiligingsmodule: Gebruikershandleiding

De Lokale Beveiligingsmodule is beschikbaar in firmware i.91.065.3 en later.

Doel

De Lokale Beveiligingsmodule beschermt de lokale webinterface van het apparaat en gevoelige lokale API's tegen ongeautoriseerde toegang.

Nadat de functie is ingeschakeld, zijn een beheerdersgebruikersnaam en -wachtwoord vereist voor:

• alle Set-API's die beschikbaar zijn op de WEM API-testpagina;
• GET-API's die gevoelige configuratiegegevens retourneren of gevoelige bewerkingen uitvoeren;
• lokale OTA-firmware-upload en -upgradebewerkingen.

Dit omvat bewerkingen zoals het wijzigen van netwerk- of uploadinstellingen, het bijwerken van firmware, het herstarten van het apparaat, het herstellen van fabrieksinstellingen en het wijzigen van andere gevoelige configuratieparameters.

De module biedt:

• configureerbare beheerdersreferenties;
• HTTP Basic Authentication voor beveiligde lokale API's;
• wijzigingen van referenties via de webinterface of API;
• een op Ed25519-handtekening gebaseerd herstelproces als het beheerderswachtwoord is vergeten.

De functie is standaard uitgeschakeld voor compatibiliteit met oudere firmware. Deze moet worden ingeschakeld en geconfigureerd voordat beveiligde toegang van kracht wordt.

De huidige lokale webinterface gebruikt HTTP. HTTP Basic Authentication codeert referenties maar versleutelt ze niet. Gebruik deze functie op een vertrouwd lokaal netwerk, tenzij het apparaat wordt benaderd via een aanvullend veilig transportmechanisme.

Beveiliging configureren in de webinterface

1. Open het IP-adres van het apparaat in een browser.
2. Selecteer het tabblad Security.
3. Voer een beheerdersgebruikersnaam in.
4. Voer het beheerderswachtwoord in en bevestig het.
5. Selecteer Enable Admin Security.

De gebruikersnaam en het wachtwoord moeten aan de volgende regels voldoen:

• lengte: 1 tot 32 tekens;
• alleen zichtbare ASCII-tekens;
• een dubbele punt (:), aanhalingsteken (") of backslash (\) is niet toegestaan.

Nadat de beveiligingsmodule is ingeschakeld, toont de browser een authenticatievenster wanneer een beveiligde pagina of API wordt geopend. Voer de geconfigureerde beheerdersgebruikersnaam en het wachtwoord in.

Het tabblad Security kan ook worden gebruikt om:

• de beheerdersgebruikersnaam en het wachtwoord te wijzigen;
• te controleren of beheerdersauthenticatie is ingeschakeld;
• de beveiligingsmodule uit te schakelen na authenticatie met de huidige referenties.

Browsers kunnen Basic Authentication-referenties voor het apparaatadres in de cache opslaan. Na het wijzigen van het wachtwoord kan de browser eerst de oude referenties opnieuw proberen en vervolgens een nieuw authenticatievenster tonen. Het sluiten van alle browservensters of het gebruik van een privévenster kan ook een nieuwe aanmelding afdwingen.

API's die geen Basic Authentication vereisen

De volgende eindpunten blijven beschikbaar zonder een Basic Authentication-header, zodat de webinterface basisapparaatinformatie kan laden en het ondertekende herstelproces kan werken:

POST /api/admin/enable is ook aanroepbaar zonder Basic Authentication wanneer de beveiligingsmodule is uitgeschakeld, omdat dit het eindpunt is dat wordt gebruikt voor de initiële configuratie. Als de beveiligingsmodule al is ingeschakeld, zijn de huidige geldige beheerdersreferenties vereist voordat dit eindpunt de beveiligingsconfiguratie kan wijzigen of uitschakelen.

Statische webinterfacebestanden zijn geen API-eindpunten en blijven openbaar leesbaar. Alle andere lokale API-eindpunten worden behandeld als beveiligd wanneer de beveiligingsmodule is ingeschakeld, inclusief alle Set-API's, gevoelige GET-API's en OTA-firmwarebewerkingen.

API-referentie

GET /api/admin/status

Geeft de huidige status van de beveiligingsmodule terug. Authenticatie is niet vereist.

Voorbeeldantwoord:

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

Velden:

• enabled: 1 wanneer de beveiligingsmodule is ingeschakeld; anders 0.
• hasPassword: 1 wanneer beheerdersreferenties zijn geconfigureerd.
• recoverySupported: 1 wanneer ondertekend beheerdersherstel wordt ondersteund door de firmware.

POST /api/admin/enable

Schakelt de beveiligingsmodule in of uit.

Beveiligingsmodule inschakelen:

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

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

Voorbeeld met curl:

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

Beveiligingsmodule uitschakelen:

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

{
  "enable": 0
}

Als de beveiligingsmodule al is ingeschakeld, zijn de huidige geldige Basic Authentication-referenties vereist om deze API aan te roepen.

Voorbeeld:

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

POST /api/admin/password

Wijzigt de beheerdersgebruikersnaam en het wachtwoord. Deze API is beveiligd nadat de beveiligingsmodule is ingeschakeld.

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

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

Voorbeeld:

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

Nadat het verzoek is gelukt, gebruikt u de nieuwe referenties voor volgende beveiligde verzoeken.

GET /api/admin/check

Controleert of de verstrekte Basic Authentication-referenties geldig zijn.

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

Succesvol antwoord:

{
  "successful": 1
}

Ontbrekende of ongeldige referenties resulteren in HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Maakt een apparaatspecifieke, eenmalige herstellading. Authenticatie is niet vereist omdat dit eindpunt niet zelfstandig referenties reset.

Voorbeeldantwoord:

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

De geretourneerde payload moet naar IAMMETER worden gestuurd wanneer beheerdersherstel nodig is.

Het aanvragen van een nieuwe uitdaging maakt de vorige uitdaging ongeldig. Een uitdaging wordt ook ongeldig na een succesvol herstel of herstart van het apparaat.

POST /api/admin/recovery

Dient de herstellading en de door IAMMETER verstrekte Ed25519-handtekening in.

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

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

Voorbeeld:

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":"<handtekening-van-IAMMETER>"}'

Als handtekeningverificatie slaagt, wist het apparaat de lokale beheerdersreferenties en schakelt het de beveiligingsmodule uit. Vervolgens kunnen een nieuwe beheerdersgebruikersnaam en -wachtwoord worden geconfigureerd.

Als het apparaat niet voldoende vrij geheugen heeft om handtekeningverificatie uit te voeren, retourneert de API een antwoord vergelijkbaar met:

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

Verminder in dit geval het geheugengebruik en vraag een nieuwe hersteluitdaging aan voordat u het opnieuw probeert. Als het wachtwoord niet beschikbaar is en de bedrijfsmodus niet kan worden gewijzigd, herstart dan het apparaat en voer het herstel uit voordat een MQTTS- of HTTPS-verbinding extra geheugen verbruikt.

Hoe wachtwoordherstel werkt

Het ontwerp van het herstel voorkomt het toevoegen van een niet-geauthenticeerde fabrieksresetopdracht die de beveiligingsmodule zou kunnen omzeilen.

Het proces gebruikt een Ed25519-publiek/privésleutelpaar:

• de apparaatfirmware bevat alleen de IAMMETER-herstel publieke sleutel;
• de bijbehorende privésleutel wordt bewaard door IAMMETER en wordt niet op het apparaat opgeslagen;
• het apparaat maakt een lading aan die de gevraagde bewerking, apparaat-SN, apparaat-MAC en een eenmalige nonce bevat;
• IAMMETER ondertekent die exacte lading met de herstel privésleutel;
• het apparaat verifieert de handtekening met zijn ingebedde publieke sleutel;
• alleen een geldige handtekening voor het huidige apparaat en de huidige nonce kan de beheerdersconfiguratie wissen.

De nonce wordt alleen in het RAM-geheugen opgeslagen. Deze wordt ongeldig wanneer het apparaat herstart, wanneer een andere uitdaging wordt aangevraagd, of na een succesvol herstel. Daarom kunnen een oude lading en handtekening niet worden hergebruikt voor een latere herstelsessie.

Gebruiksscenario's

Scenario 1: Een beheerdersgebruikersnaam en -wachtwoord instellen

De eenvoudigste methode is de webinterface:

1. Open http://<device-ip>/.
2. Open het tabblad Security.
3. Voer de nieuwe beheerdersgebruikersnaam en het wachtwoord in.
4. Bevestig het wachtwoord.
5. Schakel de beveiligingsmodule in.

Dezelfde bewerking kan worden uitgevoerd 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"}'

Controleer het resultaat:

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

Scenario 2: Toegang tot beveiligde API's met Basic Authentication

Stuur voor elk volgend beveiligd verzoek de beheerdersgebruikersnaam en het wachtwoord in de HTTP Basic Authentication-header.

De headerwaarde wordt als volgt opgebouwd:

Authorization: Basic Base64...

Voor de referenties admin:ExamplePassword worden deze eerst gecombineerd en vervolgens Base64-gecodeerd. De meeste HTTP-clients voeren dit automatisch uit.

Met curl:

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

Met een expliciete header:

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

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

Voor een JSON POST-verzoek:

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

De browser verwerkt deze header automatisch nadat de beheerder referenties invoert in het Basic Authentication-venster.

Scenario 3: Toegang herstellen na het vergeten van het wachtwoord

Het apparaat heeft geen hardwarematige resetknop. Om te voorkomen dat er een niet-geauthenticeerde resetfunctie wordt toegevoegd die de beveiligingsmodule zou kunnen omzeilen, gebruikt het apparaat het hierboven beschreven ondertekende herstelmechanisme.

Deze procedure is alleen bedoeld voor gevallen waarin zowel de beheerdersgebruikersnaam als het wachtwoord zijn vergeten. Bewaar de geconfigureerde referenties op een veilige plaats en vertrouw niet op het herstelproces voor routinematige wijzigingen van referenties. Als de huidige referenties nog beschikbaar zijn, wijzig ze dan rechtstreeks via het tabblad Security of met POST /api/admin/password.

1. Vraag een nieuwe hersteluitdaging aan van het apparaat:

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

2. Kopieer de volledige payload-waarde uit het antwoord. Bewerk de SN, MAC, nonce, scheidingstekens of hoofdlettergebruik niet.

3. Neem contact op met IAMMETER-ondersteuning via support@devicebit.com en dien de volledige lading in.

4. Nadat eigendom of service-autorisatie is bevestigd, ondertekent IAMMETER de lading en retourneert een Ed25519-handtekening.

5. Dien de originele lading en geretourneerde handtekening in bij het apparaat:

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

6. Na een succesvol antwoord wordt de beveiligingsmodule uitgeschakeld en worden de vorige beheerdersreferenties gewist. Open het tabblad Security of roep POST /api/admin/enable aan om nieuwe referenties in te stellen.

Herstart het apparaat niet en vraag geen andere uitdaging aan terwijl u wacht op de handtekening. Beide acties maken de ingediende lading ongeldig en het herstelproces moet opnieuw worden gestart met een nieuwe uitdaging.