IAMMETER-energiamittarien paikallinen järjestelmänvalvojan suojaus: käyttöopas

Paikallinen järjestelmänvalvojan suojaus: käyttöopas

Paikallinen järjestelmänvalvojan suojausmoduuli on käytettävissä laiteohjelmistossa i.91.065.3 ja sitä uudemmissa.

Tarkoitus

Paikallinen järjestelmänvalvojan suojausmoduuli suojaa laitteen paikallista Web-käyttöliittymää ja arkaluonteisia paikallisia API-rajapintoja luvattomalta käytöltä.

Kun ominaisuus on otettu käyttöön, järjestelmänvalvojan käyttäjänimi ja salasana vaaditaan seuraaviin toimiin:

• kaikki Set API -rajapinnat, jotka ovat saatavilla WEM API -testisivulla;
• GET-API:t, jotka palauttavat arkaluonteisia määritystietoja tai suorittavat arkaluonteisia toimintoja;
• paikalliset OTA-laiteohjelmiston lataus- ja päivitystoiminnot.

Tähän kuuluvat esimerkiksi verkko- tai latausasetusten muuttaminen, laiteohjelmiston päivittäminen, laitteen uudelleenkäynnistäminen, tehdasasetusten palauttaminen ja muiden arkaluonteisten määritysparametrien muokkaaminen.

Moduuli tarjoaa:

• muokattavat järjestelmänvalvojan tunnistetiedot;
• HTTP Basic Authentication -tunnistautumisen suojatuille paikallisille API-rajapinnoille;
• tunnistetietojen vaihtamisen Web-käyttöliittymän tai API:n kautta;
• Ed25519-allekirjoitukseen perustuvan palautusprosessin, jos järjestelmänvalvojan salasana unohtuu.

Ominaisuus on oletusarvoisesti pois käytöstä yhteensopivuuden varmistamiseksi vanhempien laiteohjelmistojen kanssa. Se on otettava käyttöön ja määritettävä, ennen kuin suojattu pääsy tulee voimaan.

Nykyinen paikallinen Web-käyttöliittymä käyttää HTTP:tä. HTTP Basic Authentication koodaa tunnistetiedot, mutta ei salaa niitä. Käytä tätä ominaisuutta luotetussa paikallisessa verkossa, ellei laitteeseen oteta yhteyttä lisäsuojatun siirtomekanismin kautta.

Järjestelmänvalvojan suojauksen määrittäminen Web-käyttöliittymässä

1. Avaa laitteen IP-osoite selaimessa.
2. Valitse Security-välilehti.
3. Syötä järjestelmänvalvojan käyttäjänimi.
4. Syötä ja vahvista järjestelmänvalvojan salasana.
5. Valitse Enable Admin Security.

Käyttäjänimen ja salasanan on täytettävä seuraavat säännöt:

• pituus: 1–32 merkkiä;
• vain näkyviä ASCII-merkkejä;
• kaksoispiste (:), lainausmerkki (") tai kenoviiva (\) ei ole sallittu.

Kun järjestelmänvalvojan suojaus on otettu käyttöön, selain näyttää tunnistautumiskehotteen, kun suojattua sivua tai API:a käytetään. Syötä määritetty järjestelmänvalvojan käyttäjänimi ja salasana.

Security-välilehteä voidaan käyttää myös seuraaviin:

• järjestelmänvalvojan käyttäjänimen ja salasanan vaihtamiseen;
• sen varmistamiseen, että järjestelmänvalvojan tunnistautuminen on käytössä;
• Modbus/TCP-palvelun käyttöönottoon tai poistamiseen käytöstä portissa 502;
• SSDP-hakupalvelun käyttöönottoon tai poistamiseen käytöstä;
• järjestelmänvalvojan suojauksen poistamiseen käytöstä tunnistautumisen jälkeen nykyisillä tunnistetiedoilla.

Modbus/TCP- tai SSDP-palvelun tilan muutokset edellyttävät laitteen uudelleenkäynnistystä. Jos näitä asetuksia ei ole koskaan tallennettu vanhemmalla laiteohjelmistolla, molemmat palvelut ovat oletusarvoisesti käytössä taaksepäin yhteensopivuuden varmistamiseksi.

Selaimet voivat tallentaa välimuistiin Basic Authentication -tunnistetiedot laitteen osoitteelle. Salasanan vaihtamisen jälkeen selain saattaa ensin yrittää vanhoja tunnistetietoja ja näyttää sitten uuden tunnistautumiskehotteen. Kaikkien selainikkunoiden sulkeminen tai yksityisen selausikkunan käyttäminen voi myös pakottaa uuden kirjautumisen.

API:t, jotka eivät vaadi Basic Authentication -tunnistautumista

Seuraavat päätepisteet pysyvät käytettävissä ilman Basic Authentication -otsikkoa, jotta Web-käyttöliittymä voi ladata laitteen perustiedot ja allekirjoitettu palautusprosessi voi toimia:

POST /api/admin/enable on myös kutsuttavissa ilman Basic Authentication -tunnistautumista, kun järjestelmänvalvojan suojaus on tällä hetkellä pois käytöstä, koska se on alkuasetuksiin käytettävä päätepiste. Jos järjestelmänvalvojan suojaus on jo käytössä, nykyiset voimassa olevat järjestelmänvalvojan tunnistetiedot vaaditaan, ennen kuin tämä päätepiste voi muuttaa tai poistaa käytöstä suojausmäärityksen.

Staattiset Web-käyttöliittymän tiedostot ja muut kuin /api/-alkuiset GET-resurssit eivät ole API-päätepisteitä, ja ne pysyvät julkisesti luettavina. Kaikkia muita paikallisia API-päätepisteitä käsitellään suojattuina, kun järjestelmänvalvojan suojaus on käytössä, mukaan lukien kaikki Set-API:t, arkaluonteiset GET-API:t ja OTA-laiteohjelmistotoiminnot.

API-viite

GET /api/admin/status

Palauttaa nykyisen järjestelmänvalvojan suojauksen tilan. Tunnistautumista ei vaadita.

Esimerkkivastaus:

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

Kentät:

• enabled: 1, kun järjestelmänvalvojan suojaus on käytössä; muutoin 0.
• hasPassword: 1, kun järjestelmänvalvojan tunnistetiedot on määritetty.
• recoverySupported: 1, kun laiteohjelmisto tukee allekirjoitettua järjestelmänvalvojan palautusta.
• modbusTcpEnabled: 1, kun Modbus/TCP-palvelu portissa 502 on käytössä.
• ssdpEnabled: 1, kun SSDP-hakupalvelu on käytössä.

POST /api/admin/enable

Ottaa järjestelmänvalvojan suojauksen käyttöön tai poistaa sen käytöstä.

Järjestelmänvalvojan suojauksen käyttöönotto:

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

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

Esimerkki curl-komennolla:

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

Järjestelmänvalvojan suojauksen poistaminen käytöstä:

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

{
  "enable": 0
}

Jos järjestelmänvalvojan suojaus on jo käytössä, tämän API:n kutsumiseen vaaditaan nykyiset voimassa olevat Basic Authentication -tunnistetiedot.

Esimerkki:

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

POST /api/admin/password

Vaihtaa järjestelmänvalvojan käyttäjänimen ja salasanan. Tämä API on suojattu, kun järjestelmänvalvojan suojaus on otettu käyttöön.

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

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

Esimerkki:

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

Kun pyyntö on onnistunut, käytä uusia tunnistetietoja myöhemmissä suojatuissa pyynnöissä.

GET /api/admin/check

Tarkistaa, ovatko annetut Basic Authentication -tunnistetiedot kelvollisia.

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

Onnistunut vastaus:

{
  "successful": 1
}

Puuttuvat tai virheelliset tunnistetiedot johtavat HTTP 401 Unauthorized -vastaukseen.

GET /api/admin/recovery_challenge

Luo laitekohtaisen, kertakäyttöisen palautushyötykuorman. Tunnistautumista ei vaadita, koska tämä päätepiste ei nollaa tunnistetietoja itsestään.

Esimerkkivastaus:

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

Palautettu payload on lähetettävä IAMMETERille, kun järjestelmänvalvojan palautus on tarpeen.

Uuden haasteen pyytäminen mitätöi edellisen haasteen. Haaste mitätöidään myös onnistuneen palautuksen tai laitteen uudelleenkäynnistyksen jälkeen.

POST /api/admin/recovery

Lähettää palautushyötykuorman ja IAMMETERin toimittaman Ed25519-allekirjoituksen.

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

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

Esimerkki:

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

Jos allekirjoituksen vahvistus onnistuu, laite tyhjentää paikalliset järjestelmänvalvojan tunnistetiedot ja poistaa järjestelmänvalvojan suojauksen käytöstä. Tämän jälkeen voidaan määrittää uusi järjestelmänvalvojan käyttäjänimi ja salasana.

Jos laitteessa ei ole riittävästi vapaata muistia allekirjoituksen vahvistamiseen, API palauttaa vastauksen, joka muistuttaa seuraavaa:

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

Tässä tapauksessa vähennä muistin käyttöä ja pyydä uutta palautushaastetta ennen uudelleenyritystä. Jos salasana ei ole saatavilla eikä käyttötilaa voida muuttaa, käynnistä laite uudelleen ja suorita palautus, ennen kuin MQTTS- tai HTTPS-yhteys kuluttaa lisää muistia.

Näin salasanan palautus toimii

Palautuksen suunnittelussa on vältetty tunnistautumattoman tehdasnollauskomennon lisäämistä, joka voisi ohittaa järjestelmänvalvojan suojauksen.

Prosessi käyttää Ed25519-julkisen ja yksityisen avaimen paria:

• laitteen laiteohjelmisto sisältää vain IAMMETERin palautuksen julkisen avaimen;
• vastaava yksityinen avain on IAMMETERin hallussa, eikä sitä tallenneta laitteeseen;
• laite luo hyötykuorman, joka sisältää pyydetyn toiminnon, laitteen SN-tunnuksen, MAC-osoitteen ja kertakäyttöisen nonce-arvon;
• IAMMETER allekirjoittaa kyseisen hyötykuorman palautuksen yksityisellä avaimella;
• laite vahvistaa allekirjoituksen sisäänrakennetulla julkisella avaimella;
• vain nykyiselle laitteelle ja nykyiselle nonce-arvolle kelpaava allekirjoitus voi tyhjentää järjestelmänvalvojan määrityksen.

Nonce-arvo tallennetaan vain RAM-muistiin. Se mitätöityy, kun laite käynnistetään uudelleen, kun toista haastetta pyydetään tai yhden onnistuneen palautuksen jälkeen. Siksi vanhaa hyötykuormaa ja allekirjoitusta ei voida käyttää uudelleen myöhemmässä palautusistunnossa.

Käyttöskenaariot

Skenaario 1: Järjestelmänvalvojan käyttäjänimen ja salasanan asettaminen

Yksinkertaisin tapa on Web-käyttöliittymä:

1. Avaa http://<device-ip>/.
2. Avaa Security-välilehti.
3. Syötä uusi järjestelmänvalvojan käyttäjänimi ja salasana.
4. Vahvista salasana.
5. Ota järjestelmänvalvojan suojaus käyttöön.

Sama toiminto voidaan suorittaa POST /api/admin/enable -kutsulla:

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

Vahvista tulos:

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

Skenaario 2: Suojattuihin API-rajapintoihin pääsy Basic Authentication -tunnistautumisella

Lähetä jokaisessa myöhemmässä suojatussa pyynnössä järjestelmänvalvojan käyttäjänimi ja salasana HTTP Basic Authentication -otsikossa.

Otsikon arvo muodostetaan seuraavasti:

Authorization: Basic Base64(username:password)

Esimerkiksi tunnistetiedot admin:ExamplePassword yhdistetään ensin ja koodataan sitten Base64-muotoon. Useimmat HTTP-asiakasohjelmat tekevät tämän automaattisesti.

curl-komennolla:

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

Käyttämällä nimenomaista otsikkoa:

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

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

JSON-POST-pyyntöä varten:

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

Selain käsittelee tämän otsikon automaattisesti, kun järjestelmänvalvoja on syöttänyt tunnistetiedot Basic Authentication -kehotteeseen.

Nykyinen Web-käyttöliittymä lataa laiteohjelmiston osoitteeseen POST /api/ota_successful.html. Vanha POST /ota_successful.html -päätepiste on edelleen käytettävissä vanhemmille Web-käyttöliittymille ja ulkoisille työkaluille. Molemmat päätepisteet edellyttävät Basic Authentication -tunnistautumista, kun järjestelmänvalvojan suojaus on käytössä.

Web-käyttöliittymän välilehdet toimivat seuraavasti, kun tunnistautumiskehote suljetaan:

• Settings- ja Wi-Fi-välilehdet eivät voi ladata suojattuja määritys-API-rajapintojaan, ja ne näyttävät järjestelmänvalvojan tunnistautumisviestin.
• System-välilehti voi edelleen näyttää SN-tunnuksen, MAC-osoitteen ja laiteohjelmistoversion, koska nämä arvot on haettu julkisesta /api/monitor-päätepisteestä. OTA-lataus pysyy suojattuna.
• Security-välilehti voi edelleen näyttää perustilan, koska /api/admin/status on julkinen. Tunnistetietojen muutokset ja palvelukytkimien muutokset pysyvät suojattuina.

Skenaario 3: Pääsyn palauttaminen salasanan unohtumisen jälkeen

Laitteessa ei ole laitteistopainiketta nollausta varten. Välttääkseen tunnistautumattoman nollaustoiminnon lisäämisen, joka voisi ohittaa järjestelmänvalvojan suojauksen, laite käyttää edellä kuvattua allekirjoitettua palautusmekanismia.

Tämä menettely on tarkoitettu vain tapauksiin, joissa sekä järjestelmänvalvojan käyttäjänimi että salasana on unohdettu. Säilytä määritetyt tunnistetiedot turvallisessa paikassa ja vältä luottamasta palautusprosessiin rutiininomaisissa tunnistetietojen muutoksissa. Jos nykyiset tunnistetiedot ovat edelleen saatavilla, vaihda ne suoraan Security-välilehdellä tai POST /api/admin/password -kutsulla.

1. Pyydä laitteelta uutta palautushaastetta:

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

2. Kopioi vastauksesta koko payload-arvo. Älä muokkaa SN-tunnusta, MAC-osoitetta, nonce-arvoa, erottimia tai kirjainkokoa.

3. Ota yhteyttä IAMMETERin tukeen osoitteessa support@devicebit.com ja toimita koko hyötykuorma.

4. Kun omistajuus tai palvelun valtuutus on vahvistettu, IAMMETER allekirjoittaa hyötykuorman ja palauttaa Ed25519-allekirjoituksen.

5. Toimita alkuperäinen hyötykuorma ja palautettu allekirjoitus laitteelle:

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

6. Onnistuneen vastauksen jälkeen järjestelmänvalvojan suojaus poistetaan käytöstä ja aiemmat järjestelmänvalvojan tunnistetiedot tyhjennetään. Avaa Security-välilehti tai kutsu POST /api/admin/enable -päätepistettä asettaaksesi uudet tunnistetiedot.

Älä käynnistä laitetta uudelleen äläkä pyydä toista haastetta odottaessasi allekirjoitusta. Kummatkin toimet mitätöivät toimitetun hyötykuorman, ja palautusprosessi on aloitettava uudelleen uudella haasteella.