Lokal admin-sikkerhet for IAMMETER energimålere: brukerveiledning

Lokal admin-sikkerhet: brukerveiledning

Modulen Lokal admin-sikkerhet er tilgjengelig i fastvare i.91.065.3 og nyere.

Formål

Modulen Lokal admin-sikkerhet beskytter enhetens lokale Web UI og sensitive lokale API-er mot uautorisert tilgang.

Når funksjonen er aktivert, kreves administratorbrukernavn og -passord for:

• alle Set-API-er som er tilgjengelige på WEM API Test-siden;
• GET-API-er som returnerer sensitiv konfigurasjonsdata eller utfører sensitive operasjoner;
• lokal OTA-opplasting og oppgradering av fastvare.

Dette inkluderer operasjoner som å endre nettverks- eller opplastingsinnstillinger, oppdatere fastvaren, starte enheten på nytt, gjenopprette fabrikkinstillinger og endre andre sensitive konfigurasjonsparametere.

Modulen tilbyr:

• konfigurerbar administratorlegitimasjon;
• HTTP Basic-autentisering for beskyttede lokale API-er;
• endringer av legitimasjon via Web UI eller API;
• en gjenopprettingsprosess basert på Ed25519-signatur dersom administratorpassordet er glemt.

Funksjonen er deaktivert som standard for kompatibilitet med eldre fastvare. Den må aktiveres og konfigureres før beskyttet tilgang trer i kraft.

Det nåværende lokale Web UI bruker HTTP. HTTP Basic-autentisering koder legitimasjonen, men krypterer den ikke. Bruk denne funksjonen på et pålitelig lokalt nettverk med mindre enheten nås gjennom en ekstra sikker transportmekanisme.

Konfigurere admin-sikkerhet i Web UI

1. Åpne enhetens IP-adresse i en nettleser.
2. Velg Security-fanen.
3. Angi et administratorbrukernavn.
4. Angi og bekreft administratorpassordet.
5. Velg Enable Admin Security.

Brukernavnet og passordet må oppfylle følgende regler:

• lengde: 1 til 32 tegn;
• kun synlige ASCII-tegn;
• kolon (:), doble anførselstegn (") eller backslash (\) er ikke tillatt.

Når Admin Security er aktivert, viser nettleseren en autentiseringsforespørsel når en beskyttet side eller API åpnes. Angi det konfigurerte administratorbrukernavnet og -passordet.

Security-fanen kan også brukes til å:

• endre administratorbrukernavn og -passord;
• bekrefte at administratorautentisering er aktivert;
• aktivere eller deaktivere Modbus/TCP-tjenesten på port 502;
• aktivere eller deaktivere SSDP-oppdagelse;
• deaktivere Admin Security etter å ha autentisert med gjeldende legitimasjon.

Endringer av Modbus/TCP- eller SSDP-tjenestetilstanden krever omstart av enheten. Hvis disse innstillingene aldri har blitt lagret av en eldre fastvare, er begge tjenestene som standard aktivert for bakoverkompatibilitet.

Nettlesere kan bufre Basic-autentiseringslegitimasjon for enhetens adresse. Etter at passordet er endret, kan nettleseren først prøve den gamle legitimasjonen og deretter vise en ny autentiseringsforespørsel. Å lukke alle nettleservinduer eller bruke et privat nettlesingsvindu kan også tvinge frem en ny pålogging.

API-er som ikke krever Basic-autentisering

Følgende endepunkter forblir tilgjengelige uten en Basic-autentiseringsheader, slik at Web UI kan laste grunnleggende enhetsinformasjon og den signerte gjenopprettingsprosessen kan fungere:

POST /api/admin/enable kan også kalles uten Basic-autentisering når Admin Security for øyeblikket er deaktivert, fordi det er endepunktet som brukes til første oppsett. Hvis Admin Security allerede er aktivert, kreves gjeldende gyldig administratorlegitimasjon før dette endepunktet kan endre eller deaktivere sikkerhetskonfigurasjonen.

Statiske Web UI-filer og andre GET-ressurser som ikke ligger under /api/, er ikke API-endepunkter og forblir offentlig lesbare. Alle andre lokale API-endepunkter behandles som beskyttet når Admin Security er aktivert, inkludert alle Set-API-er, sensitive GET-API-er og OTA-fastvareoperasjoner.

API-referanse

GET /api/admin/status

Returnerer gjeldende Admin Security-status. Autentisering kreves ikke.

Eksempel på respons:

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

Felt:

• enabled: 1 når Admin Security er aktivert; ellers 0.
• hasPassword: 1 når administratorlegitimasjon er konfigurert.
• recoverySupported: 1 når signert administratorgjenoppretting støttes av fastvaren.
• modbusTcpEnabled: 1 når Modbus/TCP-tjenesten på port 502 er aktivert.
• ssdpEnabled: 1 når SSDP-oppdagelse er aktivert.

POST /api/admin/enable

Aktiverer eller deaktiverer Admin Security.

Aktivere Admin Security:

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

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

Eksempel med curl:

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

Deaktivere Admin Security:

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

{
  "enable": 0
}

Hvis Admin Security allerede er aktivert, kreves gjeldende gyldig Basic-autentiseringslegitimasjon for å kalle dette API-et.

Eksempel:

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

POST /api/admin/password

Endrer administratorbrukernavn og -passord. Dette API-et er beskyttet etter at Admin Security har blitt aktivert.

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

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

Eksempel:

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

Etter at forespørselen lykkes, bruk den nye legitimasjonen for påfølgende beskyttede forespørsler.

GET /api/admin/check

Sjekker om den angitte Basic-autentiseringslegitimasjonen er gyldig.

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

Vellykket respons:

{
  "successful": 1
}

Manglende eller ugyldig legitimasjon resulterer i HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Oppretter en enhetsspesifikk engangsnyttelast for gjenoppretting. Autentisering kreves ikke fordi dette endepunktet ikke tilbakestiller legitimasjon av seg selv.

Eksempel på respons:

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

Den returnerte payload må sendes til IAMMETER når administratorgjenoppretting er nødvendig.

Å be om en ny challenge ugyldiggjør den forrige challenge-en. En challenge blir også ugyldiggjort etter en vellykket gjenoppretting eller omstart av enheten.

POST /api/admin/recovery

Sender inn gjenopprettingsnyttelasten og Ed25519-signaturen levert av 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"
}

Eksempel:

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

Hvis signaturverifiseringen lykkes, sletter enheten den lokale administratorlegitimasjonen og deaktiverer Admin Security. Deretter kan et nytt administratorbrukernavn og -passord konfigureres.

Hvis enheten ikke har nok ledig minne til å kjøre signaturverifisering, returnerer API-et en respons som ligner på:

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

I dette tilfellet bør du redusere minnebruken og be om en ny gjenopprettingsutfordring før du prøver igjen. Hvis passordet ikke er tilgjengelig og driftsmodusen ikke kan endres, start enheten på nytt og utfør gjenoppretting før en MQTTS- eller HTTPS-tilkobling bruker ekstra minne.

Hvordan passordgjenoppretting fungerer

Gjenopprettingsdesignet unngår å legge til en uautentisert fabrikktilbakestillingskommando som kunne omgått administratorbeskyttelsen.

Prosessen bruker et Ed25519-nøkkelpar med en offentlig og en privat nøkkel:

• enhetens fastvare inneholder kun IAMMETERs offentlige gjenopprettingsnøkkel;
• den tilsvarende private nøkkelen beholdes av IAMMETER og lagres ikke på enheten;
• enheten oppretter en nyttelast som inneholder den forespurte operasjonen, enhetens SN, enhetens MAC og en engangs-nonce;
• IAMMETER signerer nøyaktig denne nyttelasten med den private gjenopprettingsnøkkelen;
• enheten verifiserer signaturen med sin innebygde offentlige nøkkel;
• kun en gyldig signatur for gjeldende enhet og gjeldende nonce kan slette administratorkonfigurasjonen.

Nonce-en lagres kun i RAM. Den blir ugyldig når enheten startes på nytt, når en annen challenge blir forespurt, eller etter én vellykket gjenoppretting. Derfor kan ikke en gammel nyttelast og signatur gjenbrukes for en senere gjenopprettingsøkt.

Bruksscenarier

Scenario 1: Angi et administratorbrukernavn og -passord

Den enkleste metoden er Web UI:

1. Åpne http://<device-ip>/.
2. Åpne Security-fanen.
3. Angi det nye administratorbrukernavnet og -passordet.
4. Bekreft passordet.
5. Aktiver Admin Security.

Den samme operasjonen kan utføres gjennom 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"}'

Verifiser resultatet:

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

Scenario 2: Få tilgang til beskyttede API-er med Basic-autentisering

For hver påfølgende beskyttet forespørsel sender du administratorbrukernavnet og -passordet i HTTP Basic-autentiseringsheaderen.

Header-verdien konstrueres som følger:

Authorization: Basic Base64(username:password)

For eksempel kombineres legitimasjonen admin:ExamplePassword først og kodes deretter med Base64. De fleste HTTP-klienter gjør dette automatisk.

Med curl:

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

Med en eksplisitt header:

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

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

For en JSON POST-forespørsel:

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

Nettleseren håndterer denne headeren automatisk etter at administratoren har angitt legitimasjon i Basic-autentiseringsforespørselen.

Det nåværende Web UI laster opp fastvare til POST /api/ota_successful.html. Det eldre POST /ota_successful.html-endepunktet er fortsatt tilgjengelig for eldre Web UI-versjoner og eksterne verktøy. Begge endepunktene krever Basic-autentisering når Admin Security er aktivert.

Web UI-fanene oppfører seg som følger når autentiseringsforespørselen lukkes:

• Settings og Wi-Fi kan ikke laste sine beskyttede konfigurasjons-API-er og viser en administratorautentiseringsmelding.
• System kan fortsatt vise SN, MAC og fastvareversjon fordi disse verdiene ble hentet fra det offentlige /api/monitor-endepunktet. OTA-opplasting forblir beskyttet.
• Security kan fortsatt vise grunnleggende status fordi /api/admin/status er offentlig. Endringer av legitimasjon og tjenestebrytere forblir beskyttet.

Scenario 3: Gjenopprette tilgangen etter å ha glemt passordet

Enheten har ingen fysisk tilbakestillingsknapp. For å unngå å legge til en uautentisert tilbakestillingsfunksjon som kunne omgått Admin Security, bruker enheten den signerte gjenopprettingsmekanismen beskrevet ovenfor.

Denne prosedyren er kun ment for tilfeller der både administratorbrukernavnet og -passordet er glemt. Oppbevar den konfigurerte legitimasjonen på et sikkert sted, og unngå å basere deg på gjenopprettingsprosessen for rutinemessige legitimasjonsendringer. Hvis den gjeldende legitimasjonen fortsatt er tilgjengelig, endrer du den direkte fra Security-fanen eller med POST /api/admin/password.

1. Be om en ny gjenopprettingsutfordring fra enheten:

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

2. Kopier hele payload-verdien fra responsen. Ikke rediger SN, MAC, nonce, skilletegn eller store/små bokstaver.

3. Kontakt IAMMETER-støtte på support@devicebit.com og send inn hele nyttelasten.

4. Når eierskap eller tjenesteautorisasjon er bekreftet, signerer IAMMETER nyttelasten og returnerer en Ed25519-signatur.

5. Send den opprinnelige nyttelasten og den returnerte signaturen til enheten:

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

6. Etter en vellykket respons deaktiveres Admin Security og den tidligere administratorlegitimasjonen slettes. Åpne Security-fanen eller kall POST /api/admin/enable for å angi ny legitimasjon.

Ikke start enheten på nytt eller be om en annen challenge mens du venter på signaturen. Begge handlingene ugyldiggjør den innsendte nyttelasten, og gjenopprettingsprosessen må startes på nytt med en ny challenge.