Lokalna administratorska varnost za energetske števce IAMMETER: uporabniški priročnik

Lokalna administratorska varnost: uporabniški priročnik

Modul lokalne administratorske varnosti je na voljo v vdelani programski opremi i.91.065.3 in novejših različicah.

Namen

Modul lokalne administratorske varnosti ščiti lokalni spletni vmesnik naprave in občutljive lokalne API-je pred nepooblaščenim dostopom.

Ko je funkcija omogočena, sta za naslednje operacije potrebna administratorsko uporabniško ime in geslo:

• za vse Set API-je, ki so na voljo na strani WEM API Test;
• za GET API-je, ki vračajo občutljive podatke o konfiguraciji ali izvajajo občutljive operacije;
• za lokalno nalaganje in nadgradnjo vdelane programske opreme prek OTA.

To vključuje operacije, kot so spreminjanje omrežnih nastavitev ali nastavitev za nalaganje podatkov, posodabljanje vdelane programske opreme, ponovni zagon naprave, obnova tovarniških nastavitev in spreminjanje drugih občutljivih parametrov konfiguracije.

Modul ponuja:

• nastavljive administratorske poverilnice;
• osnovno overjanje HTTP (HTTP Basic Authentication) za zaščitene lokalne API-je;
• spreminjanje poverilnic prek spletnega vmesnika ali API-ja;
• postopek obnovitve na podlagi podpisa Ed25519, če je administratorsko geslo pozabljeno.

Funkcija je privzeto onemogočena zaradi združljivosti s starejšo vdelano programsko opremo. Preden zaščiteni dostop začne veljati, jo je treba omogočiti in konfigurirati.

Trenutni lokalni spletni vmesnik uporablja HTTP. Osnovno overjanje HTTP poverilnice kodira, vendar jih ne šifrira. To funkcijo uporabljajte v zaupanja vrednem lokalnem omrežju, razen če do naprave dostopate prek dodatnega varnega prenosnega mehanizma.

Konfiguracija administratorske varnosti v spletnem vmesniku

1. V brskalniku odprite naslov IP naprave.
2. Izberite zavihek Security.
3. Vnesite administratorsko uporabniško ime.
4. Vnesite in potrdite administratorsko geslo.
5. Izberite Enable Admin Security.

Uporabniško ime in geslo morata izpolnjevati naslednja pravila:

• dolžina: od 1 do 32 znakov;
• samo vidni znaki ASCII;
• dvopičje (:), dvojni narekovaj (") ali poševnica nazaj (\) ni dovoljena.

Ko je administratorska varnost omogočena, brskalnik ob dostopu do zaščitene strani ali API-ja prikaže poziv za overjanje. Vnesite konfigurirano administratorsko uporabniško ime in geslo.

Zavihek Security lahko uporabite tudi za:

• spreminjanje administratorskega uporabniškega imena in gesla;
• preverjanje, ali je administratorsko overjanje omogočeno;
• omogočanje ali onemogočanje storitve Modbus/TCP na vratih 502;
• omogočanje ali onemogočanje odkrivanja SSDP;
• onemogočanje administratorske varnosti po overitvi s trenutnimi poverilnicami.

Spremembe stanja storitve Modbus/TCP ali SSDP zahtevajo ponovni zagon naprave. Če teh nastavitev starejša vdelana programska oprema še nikoli ni shranila, sta obe storitvi zaradi združljivosti navzgor privzeto omogočeni.

Brskalniki lahko predpomnijo poverilnice osnovnega overjanja za naslov naprave. Po spremembi gesla brskalnik morda najprej poskusi s starimi poverilnicami in nato prikaže nov poziv za overjanje. Zapiranje vseh oken brskalnika ali uporaba okna zasebnega brskanja lahko prav tako prisili novo prijavo.

API-ji, ki ne zahtevajo osnovnega overjanja

Naslednje končne točke ostanejo na voljo brez glave osnovnega overjanja, da lahko spletni vmesnik naloži osnovne podatke o napravi in da lahko deluje postopek obnovitve s podpisom:

POST /api/admin/enable je prav tako mogoče klicati brez osnovnega overjanja, ko je administratorska varnost trenutno onemogočena, saj gre za končno točko, ki se uporablja za začetno nastavitev. Če je administratorska varnost že omogočena, so pred spreminjanjem ali onemogočanjem varnostne konfiguracije prek te končne točke potrebne trenutne veljavne administratorske poverilnice.

Statične datoteke spletnega vmesnika in drugi viri GET, ki niso del /api/, niso API končne točke in ostanejo javno berljivi. Vse druge lokalne API končne točke so, ko je administratorska varnost omogočena, obravnavane kot zaščitene, vključno z vsemi Set API-ji, občutljivimi GET API-ji in operacijami z vdelano programsko opremo prek OTA.

Referenca API-ja

GET /api/admin/status

Vrne trenutno stanje administratorske varnosti. Overjanje ni potrebno.

Primer odgovora:

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

Polja:

• enabled: 1, ko je administratorska varnost omogočena; sicer 0.
• hasPassword: 1, ko so administratorske poverilnice konfigurirane.
• recoverySupported: 1, ko vdelana programska oprema podpira obnovitev administratorja s podpisom.
• modbusTcpEnabled: 1, ko je storitev Modbus/TCP na vratih 502 omogočena.
• ssdpEnabled: 1, ko je odkrivanje SSDP omogočeno.

POST /api/admin/enable

Omogoči ali onemogoči administratorsko varnost.

Omogočanje administratorske varnosti:

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

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

Primer z curl:

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

Onemogočanje administratorske varnosti:

POST /api/admin/enable
Authorization: Basic <base6...ype: application/json

{
  "enable": 0
}

Če je administratorska varnost že omogočena, so za klic tega API-ja potrebne trenutne veljavne poverilnice osnovnega overjanja.

Primer:

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

POST /api/admin/password

Spremeni administratorsko uporabniško ime in geslo. Ta API je po omogočitvi administratorske varnosti zaščiten.

POST /api/admin/password
Authorization: Basic <curre...ype: application/json

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

Primer:

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

Po uspešni zahtevi pri nadaljnjih zaščitenih zahtevah uporabite nove poverilnice.

GET /api/admin/check

Preveri, ali so posredovane poverilnice osnovnega overjanja veljavne.

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

Uspešen odgovor:

{
  "successful": 1
}

Manjkajoče ali neveljavne poverilnice povzročijo odgovor HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Ustvari enkratni tovor obnovitve, specifičen za napravo. Overjanje ni potrebno, ker ta končna točka sama po sebi ne ponastavlja poverilnic.

Primer odgovora:

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

Vrnjeni payload je treba poslati podjetju IAMMETER, ko je potrebna obnovitev administratorja.

Zahteva za nov izziv razveljavi prejšnji izziv. Izziv se razveljavi tudi po uspešni obnovitvi ali ponovnem zagonu naprave.

POST /api/admin/recovery

Pošlje tovor obnovitve in podpis Ed25519, ki ga posreduje 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"
}

Primer:

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

Če preverjanje podpisa uspe, naprava počisti lokalne administratorske poverilnice in onemogoči administratorsko varnost. Nato lahko konfigurirate novo administratorsko uporabniško ime in geslo.

Če naprava nima dovolj prostega pomnilnika za izvedbo preverjanja podpisa, API vrne odgovor, podoben temu:

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

V tem primeru zmanjšajte porabo pomnilnika in pred ponovnim poskusom zahtevajte nov izziv za obnovitev. Če geslo ni na voljo in načina delovanja ni mogoče spremeniti, znova zaženite napravo in izvedite obnovitev, preden povezava MQTTS ali HTTPS porabi dodatni pomnilnik.

Kako deluje obnovitev gesla

Zasnova obnovitve se izogiba dodajanju neoverjenega ukaza za tovarniško ponastavitev, ki bi lahko zaobšel zaščito administratorja.

Postopek uporablja par javnega in zasebnega ključa Ed25519:

• vdelana programska oprema naprave vsebuje samo javni ključ za obnovitev IAMMETER;
• ustrezni zasebni ključ hrani IAMMETER in ni shranjen na napravi;
• naprava ustvari tovor z zahtevano operacijo, serijsko številko naprave (SN), naslovom MAC naprave in enkratnim nonce-jem;
• IAMMETER podpiše natanko ta tovor z zasebnim ključem za obnovitev;
• naprava preveri podpis s svojim vgrajenim javnim ključem;
• samo veljaven podpis za trenutno napravo in trenutni nonce lahko počisti konfiguracijo administratorja.

Nonce je shranjen samo v pomnilniku RAM. Neveljaven postane ob ponovnem zagonu naprave, ob zahtevi za drug izziv ali po eni uspešni obnovitvi. Zato starega tovora in podpisa ni mogoče ponovno uporabiti v poznejši seji obnovitve.

Primeri uporabe

Primer 1: Nastavitev administratorskega uporabniškega imena in gesla

Najpreprostejša metoda je spletni vmesnik:

1. Odprite http://<device-ip>/.
2. Odprite zavihek Security.
3. Vnesite novo administratorsko uporabniško ime in geslo.
4. Potrdite geslo.
5. Omogočite administratorsko varnost.

Isto operacijo je mogoče izvesti prek 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"}'

Preverite rezultat:

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

Primer 2: Dostop do zaščitenih API-jev z osnovnim overjanjem

Pri vsaki nadaljnji zaščiteni zahtevi pošljite administratorsko uporabniško ime in geslo v glavi osnovnega overjanja HTTP.

Vrednost glave se oblikuje na naslednji način:

Authorization: Basic Base64...nFor example, the credentials `admin:ExamplePassword` are combined first and then Base64 encoded. Most HTTP clients perform this automatically.

Z uporabo curl:

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

Z izrecno glavo:

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

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

Za zahtevo JSON POST:

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

Brskalnik to glavo obravnava samodejno, ko administrator vnese poverilnice v poziv za osnovno overjanje.

Trenutni spletni vmesnik nalaga vdelano programsko opremo na POST /api/ota_successful.html. Starejša končna točka POST /ota_successful.html ostane na voljo za starejše različice spletnega vmesnika in zunanja orodja. Obe končni točki zahtevata osnovno overjanje, ko je administratorska varnost omogočena.

Zavihki spletnega vmesnika se ob zaprtju poziva za overjanje obnašajo takole:

• Settings (Nastavitve) in Wi-Fi ne moreta naložiti zaščitenih konfiguracijskih API-jev in prikažeta sporočilo o overjanju administratorja.
• System (Sistem) lahko še vedno prikaže SN, MAC in različico vdelane programske opreme, ker so bile te vrednosti pridobljene iz javne končne točke /api/monitor. Nalaganje prek OTA ostane zaščiteno.
• Security (Varnost) lahko še vedno prikaže osnovno stanje, ker je /api/admin/status javna. Spreminjanje poverilnic in spreminjanje stikal storitev ostaneta zaščitena.

Primer 3: Obnovitev dostopa po pozabljenem geslu

Naprava nima strojne tipke za ponastavitev. Da bi se izognili dodajanju neoverjene funkcije ponastavitve, ki bi lahko zaobšla administratorsko varnost, naprava uporablja zgoraj opisani mehanizem obnovitve s podpisom.

Ta postopek je namenjen le primerom, ko sta pozabljeni tako administratorsko uporabniško ime kot geslo. Konfigurirane poverilnice hranite na varnem mestu in se za redno spreminjanje poverilnic ne zanašajte na postopek obnovitve. Če so trenutne poverilnice še vedno na voljo, jih spremenite neposredno z zavihka Security ali z POST /api/admin/password.

1. Zahtevajte nov izziv za obnovitev od naprave:

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

2. Kopirajte celotno vrednost payload iz odgovora. Ne spreminjajte SN, MAC, nonce-ja, ločil ali velikosti črk.

3. Stopite v stik s podporo IAMMETER na naslovu support@devicebit.com in pošljite celoten tovor.

4. Ko je lastništvo ali avtorizacija storitve potrjena, IAMMETER podpiše tovor in vrne podpis Ed25519.

5. Pošljite prvotni tovor in vrnjeni podpis napravi:

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

6. Po uspešnem odgovoru je administratorska varnost onemogočena in prejšnje administratorske poverilnice so počičene. Odprite zavihek Security ali pokličite POST /api/admin/enable, da nastavite nove poverilnice.

Med čakanjem na podpis naprave ne znova zaženite in ne zahtevajte drugega izziva. Oba dejanja razveljavita posredovani tovor, postopek obnovitve pa je treba začeti znova z novim izzivom.