Lokal administrativ sikkerhed for IAMMETER-energimålere: Brugervejledning

Lokal administrativ sikkerhed: Brugervejledning

Modulet til lokal administrativ sikkerhed er tilgængeligt i firmware i.91.065.3 og nyere.

Formål

Modulet til lokal administrativ sikkerhed beskytter enhedens lokale webgrænseflade og følsomme lokale API'er mod uautoriseret adgang.

Når funktionen er aktiveret, kræves der et administratorbrugernavn og en adgangskode til:

• alle Set API'er, der er tilgængelige på WEM API-testsiden;
• GET API'er, der returnerer følsomme konfigurationsdata eller udfører følsomme operationer;
• lokale OTA-firmwareoverførsler og -opgraderinger.

Dette omfatter operationer som at ændre netværks- eller overførselsindstillinger, opdatere firmware, genstarte enheden, gendanne fabriksindstillinger og ændre andre følsomme konfigurationsparametre.

Modulet leverer:

• konfigurerbare administratorlegitimationsoplysninger;
• HTTP Basic Authentication til beskyttede lokale API'er;
• ændring af legitimationsoplysninger via webgrænsefladen eller API'en;
• en Ed25519-signaturbaseret gendannelsesproces, hvis administratoradgangskoden glemmes.

Funktionen er som standard deaktiveret for at bevare kompatibiliteten med ældre firmware. Den skal aktiveres og konfigureres, før den beskyttede adgang træder i kraft.

Den nuværende lokale webgrænseflade bruger HTTP. HTTP Basic Authentication koder legitimationsoplysningerne, men krypterer dem ikke. Brug denne funktion på et betroet lokalt netværk, medmindre enheden tilgås via en ekstra sikker transportmekanisme.

Konfigurér administrativ sikkerhed i webgrænsefladen

1. Åbn enhedens IP-adresse i en browser.
2. Vælg fanen Security.
3. Angiv et administratorbrugernavn.
4. Angiv og bekræft administratoradgangskoden.
5. Vælg Enable Admin Security.

Brugernavnet og adgangskoden skal opfylde følgende regler:

• længde: 1 til 32 tegn;
• kun synlige ASCII-tegn;
• et kolon (:), dobbelt anførselstegn (") eller backslash (\) er ikke tilladt.

Når Admin Security er aktiveret, viser browseren en autentificeringsprompt, når en beskyttet side eller API tilgås. Angiv det konfigurerede administratorbrugernavn og -adgangskode.

Fanen Security kan også bruges til at:

• ændre administratorbrugernavnet og -adgangskoden;
• bekræfte, at administratorautentificering er aktiveret;
• aktivere eller deaktivere Modbus/TCP-tjenesten på port 502;
• aktivere eller deaktivere SSDP-discovery;
• deaktivere Admin Security efter autentificering med de aktuelle legitimationsoplysninger.

Ændringer af Modbus/TCP- eller SSDP-tjenestetilstanden kræver en genstart af enheden. Hvis disse indstillinger aldrig er blevet gemt af en tidligere firmware, er begge tjenester som standard aktiveret for bagudkompatibilitet.

Browseren kan cache Basic Authentication-legitimationsoplysninger for enhedens adresse. Når adgangskoden er ændret, prøver browseren måske først de gamle legitimationsoplysninger og viser derefter en ny autentificeringsprompt. Lukning af alle browservinduer eller brug af et privat browservindue kan også tvinge et nyt login.

API'er, der ikke kræver Basic Authentication

Følgende endepunkter forbliver tilgængelige uden en Basic Authentication-header, så webgrænsefladen kan hente grundlæggende enhedsoplysninger, og den signerede gendannelsesproces kan fungere:

POST /api/admin/enable kan også kaldes uden Basic Authentication, når Admin Security i øjeblikket er deaktiveret, fordi det er det endepunkt, der bruges til den indledende opsætning. Hvis Admin Security allerede er aktiveret, kræves de aktuelle gyldige administratorlegitimationsoplysninger, før dette endepunkt kan ændre eller deaktivere sikkerhedskonfigurationen.

Statiske webgrænsefladefiler og andre GET-ressourcer, der ikke starter med /api/, er ikke API-endepunkter og forbliver offentligt læsbare. Alle andre lokale API-endepunkter behandles som beskyttede, når Admin Security er aktiveret, herunder alle Set API'er, følsomme GET API'er og OTA-firmwareoperationer.

API-referencer

GET /api/admin/status

Returnerer den aktuelle Admin Security-status. Autentificering er ikke påkrævet.

Eksempel på svar:

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

Feltbeskrivelser:

• enabled: 1, når Admin Security er aktiveret; ellers 0.
• hasPassword: 1, når administratorlegitimationsoplysninger er konfigureret.
• recoverySupported: 1, når signeret administratorgendannelse understøttes af firmwaren.
• modbusTcpEnabled: 1, når Modbus/TCP-tjenesten på port 502 er aktiveret.
• ssdpEnabled: 1, når SSDP-discovery er aktiveret.

POST /api/admin/enable

Aktiverer eller deaktiverer Admin Security.

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

Deaktiver Admin Security:

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

{
  "enable": 0
}

Hvis Admin Security allerede er aktiveret, kræves de aktuelle gyldige Basic Authentication-legitimationsoplysninger for at kalde denne API.

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

Ændrer administratorbrugernavnet og -adgangskoden. Denne API er beskyttet, efter Admin Security er aktiveret.

POST /api/admin/password
Authorization: Basic <curre...als>
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"}'

Når anmodningen lykkes, skal du bruge de nye legitimationsoplysninger til efterfølgende beskyttede anmodninger.

GET /api/admin/check

Kontrollerer, om de angivne Basic Authentication-legitimationsoplysninger er gyldige.

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

Svar ved succes:

{
  "successful": 1
}

Manglende eller ugyldige legitimationsoplysninger resulterer i HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Opretter en enhedsspecifik engangs-gendannelsespayload. Autentificering er ikke påkrævet, fordi dette endepunkt ikke nulstiller legitimationsoplysninger af sig selv.

Eksempel på svar:

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

Den returnerede payload skal sendes til IAMMETER, når der er behov for administratorgendannelse.

Anmodning om en ny challenge gør den tidligere challenge ugyldig. En challenge bliver også ugyldig efter en vellykket gendannelse eller en genstart af enheden.

POST /api/admin/recovery

Indsender gendannelsespayloaden og den Ed25519-signatur, som IAMMETER har leveret.

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 signaturverifikationen lykkes, fjerner enheden de lokale administratorlegitimationsoplysninger og deaktiverer Admin Security. Der kan derefter konfigureres et nyt administratorbrugernavn og en ny adgangskode.

Hvis enheden ikke har nok ledig hukommelse til at udføre signaturverifikation, returnerer API'en et svar svarende til:

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

I dette tilfælde skal du reducere hukommelsesforbruget og anmode om en ny gendannelseschallenge, før du prøver igen. Hvis adgangskoden ikke er tilgængelig, og driftsmåden ikke kan ændres, skal du genstarte enheden og udføre gendannelse, før en MQTTS- eller HTTPS-forbindelse forbruger yderligere hukommelse.

Sådan fungerer adgangskodegendannelse

Gendannelsesdesignet undgår at tilføje en uautentificeret fabriksnulstillingskommando, der kunne omgå administratorbeskyttelsen.

Processen bruger et Ed25519 offentligt/privat nøglepar:

• enhedens firmware indeholder kun IAMMETER-gendannelsens offentlige nøgle;
• den tilsvarende private nøgle opbevares af IAMMETER og gemmes ikke på enheden;
• enheden opretter en payload, der indeholder den ønskede operation, enhedens SN, enhedens MAC og en engangsnonce;
• IAMMETER underskriver netop denne payload med den private gendannelsesnøgle;
• enheden bekræfter signaturen med sin indlejrede offentlige nøgle;
• kun en gyldig signatur for den aktuelle enhed og den aktuelle nonce kan fjerne administratorkonfigurationen.

Noncen gemmes kun i RAM. Den bliver ugyldig, når enheden genstarter, når der anmodes om en ny challenge, eller efter en vellykket gendannelse. Derfor kan en gammel payload og signatur ikke genbruges til en senere gendannelsessession.

Brugsscenarier

Scenarie 1: Angiv et administratorbrugernavn og en adgangskode

Den enkleste metode er webgrænsefladen:

1. Åbn http://<device-ip>/.
2. Åbn fanen Security.
3. Angiv det nye administratorbrugernavn og -adgangskode.
4. Bekræft adgangskoden.
5. Aktivér Admin Security.

Den samme handling kan udføres 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"}'

Bekræft resultatet:

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

Scenarie 2: Få adgang til beskyttede API'er med Basic Authentication

For hver efterfølgende beskyttede anmodning skal du sende administratorbrugernavnet og -adgangskoden i HTTP Basic Authentication-headeren.

Header-værdien konstrueres som følger:

Authorization: Basic Base64...ord)

For eksempel kombineres legitimationsoplysningerne admin:ExamplePassword først og kodes derefter i Base64. De fleste HTTP-klienter gør dette automatisk.

Ved brug af curl:

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

Ved brug af en eksplicit header:

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

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

Til en JSON POST-anmodning:

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

Browseren håndterer denne header automatisk, efter at administratoren har angivet legitimationsoplysningerne i Basic Authentication-prompten.

Den nuværende webgrænseflade overfører firmware til POST /api/ota_successful.html. Det gamle POST /ota_successful.html-endepunkt forbliver tilgængeligt for ældre webgrænsefladeversioner og eksterne værktøjer. Begge endepunkter kræver Basic Authentication, når Admin Security er aktiveret.

Webgrænsefladens faner opfører sig som følger, når autentificeringsprompten lukkes:

• Settings og Wi-Fi kan ikke indlæse deres beskyttede konfigurations-API'er og viser en besked om administratorautentificering.
• System kan stadig vise SN, MAC og firmwareversion, fordi disse værdier blev hentet fra det offentlige /api/monitor-endepunkt. OTA-overførsel forbliver beskyttet.
• Security kan stadig vise grundstatus, fordi /api/admin/status er offentligt. Ændringer af legitimationsoplysninger og tjenesteafbrydere forbliver beskyttet.

Scenarie 3: Genopret adgang, efter adgangskoden er glemt

Enheden har ingen hardware-nulstillingsknap. For at undgå at tilføje en uautentificeret nulstillingsfunktion, der kunne omgå Admin Security, bruger enheden den signerede gendannelsesmekanisme, der er beskrevet ovenfor.

Denne procedure er kun beregnet til tilfælde, hvor både administratorbrugernavnet og -adgangskoden er glemt. Opbevar de konfigurerede legitimationsoplysninger på et sikkert sted, og undgå at stole på gendannelsesprocessen til rutinemæssige ændringer af legitimationsoplysninger. Hvis de aktuelle legitimationsoplysninger stadig er tilgængelige, skal du ændre dem direkte fra fanen Security eller med POST /api/admin/password.

1. Anmod om en ny gendannelseschallenge fra enheden:

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

2. Kopiér hele payload-værdien fra svaret. Redigér ikke SN, MAC, nonce, separatorer eller store/små bogstaver.

3. Kontakt IAMMETER-support på support@devicebit.com, og indsend hele payloaden.

4. Når ejerskab eller servicegodkendelse er bekræftet, underskriver IAMMETER payloaden og returnerer en Ed25519-signatur.

5. Indsend den oprindelige payload og den returnerede signatur til enheden:

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

6. Efter et vellykket svar er Admin Security deaktiveret, og de tidligere administratorlegitimationsoplysninger fjernes. Åbn fanen Security, eller kald POST /api/admin/enable for at angive nye legitimationsoplysninger.

Genstart ikke enheden, og anmod ikke om en ny challenge, mens du venter på signaturen. Begge handlinger gør den indsendte payload ugyldig, og gendannelsesprocessen skal startes igen med en ny challenge.