Lokale Beveiligingsmodule voor IAMMETER Energiemeters: Gebruikershandleiding

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

Op deze pagina

• Doel
• Beveiliging configureren in de webinterface
• API's die geen Basic Authentication vereisen
• API-referentie
• Hoe wachtwoordherstel werkt
• Gebruiksscenario's
  • Scenario 1: Een beheerdersgebruikersnaam en -wachtwoord instellen
  • Scenario 2: Toegang tot beveiligde API's met Basic Authentication
  • Scenario 3: Toegang herstellen na het vergeten van het wachtwoord

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,
  "modbusTcpEnabled": 1,
  "ssdpEnabled": 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-credentials>
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 <current-base64-credentials>
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":"<signature-from-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(username:password)

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

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 fysieke resetknop. Om geen niet-geauthenticeerde resetfunctie toe te voegen die Admin Security kan omzeilen, gebruikt het een ondertekend, apparaatspecifiek herstelmechanisme.

Gebruik deze procedure alleen wanneer u de beheerdersgegevens bent vergeten. Als u de huidige gegevens nog kent, wijzigt u ze via het tabblad Security of met POST /api/admin/password.

Volg de volledige stapsgewijze handleiding voor herstel bij een vergeten Admin Security-wachtwoord

De herstelprocedure is als volgt:

1. Genereer een eenmalige payload met GET /api/admin/recovery_challenge.
2. Meld u aan bij de toepassing Admin Recovery van het IAMMETER Contributor-systeem. De dienst controleert of uw account bevoegd is om het serienummer van het apparaat te beheren en retourneert een Ed25519-handtekening voor precies die payload.
3. Verzend de ongewijzigde payload en de handtekening naar POST /api/admin/recovery. Na succesvolle verificatie wordt Admin Security uitgeschakeld en worden de eerdere lokale beheerdersgegevens gewist.

Start het apparaat niet opnieuw op, vernieuw de challengepagina niet en vraag geen andere challenge aan voordat het herstel is voltooid. Elk van deze acties maakt de huidige nonce ongeldig, zodat u opnieuw moet beginnen met een nieuwe payload.

De afzonderlijke herstelhandleiding bevat schermafbeeldingen, volledige curl-opdrachten, probleemoplossing voor afgewezen handtekeningen en de herstelprocedure bij weinig vrij geheugen.