Securitate locală pentru administrator la contoarele de energie IAMMETER: Ghid de utilizare

Securitate locală pentru administrator: Ghid de utilizare

Modulul de securitate locală pentru administrator este disponibil în firmware i.91.065.3 și versiunile ulterioare.

Scop

Modulul de securitate locală pentru administrator protejează interfața web locală a dispozitivului și API-urile locale sensibile împotriva accesului neautorizat.

După activarea funcției, un nume de utilizator și o parolă de administrator sunt necesare pentru:

• toate API-urile Set disponibile pe pagina de testare WEM API;
• API-urile GET care returnează date de configurare sensibile sau efectuează operațiuni sensibile;
• operațiunile de încărcare și actualizare a firmware-ului OTA local.

Aceasta include operațiuni precum modificarea setărilor de rețea sau de încărcare, actualizarea firmware-ului, repornirea dispozitivului, restabilirea setărilor din fabrică și modificarea altor parametri de configurare sensibili.

Modulul oferă:

• acreditări de administrator configurabile;
• autentificare de bază HTTP pentru API-urile locale protejate;
• modificarea acreditărilor prin interfața web sau API;
• un proces de recuperare bazat pe semnătura Ed25519 dacă parola de administrator este uitată.

Funcția este dezactivată implicit pentru compatibilitate cu firmware-urile anterioare. Trebuie activată și configurată înainte ca accesul protejat să intre în vigoare.

Interfața web locală actuală utilizează HTTP. Autentificarea de bază HTTP codifică acreditările, dar nu le criptează. Utilizați această funcție pe o rețea locală de încredere, cu excepția cazului în care dispozitivul este accesat printr-un mecanism suplimentar de transport securizat.

Configurarea securității pentru administrator în interfața web

1. Deschideți adresa IP a dispozitivului într-un browser.
2. Selectați fila Security.
3. Introduceți un nume de utilizator de administrator.
4. Introduceți și confirmați parola de administrator.
5. Selectați Enable Admin Security.

Numele de utilizator și parola trebuie să respecte următoarele reguli:

• lungime: de la 1 la 32 de caractere;
• numai caractere ASCII vizibile;
• nu sunt permise două puncte (:), ghilimele (") sau backslash (\).

După activarea Securității admin, browserul afișează o solicitare de autentificare atunci când este accesată o pagină sau un API protejat. Introduceți numele de utilizator și parola de administrator configurate.

Fila Security poate fi utilizată și pentru:

• modificarea numelui de utilizator și a parolei de administrator;
• verificarea faptului că autentificarea de administrator este activată;
• activarea sau dezactivarea serviciului Modbus/TCP de pe portul 502;
• activarea sau dezactivarea descoperirii SSDP;
• dezactivarea Securității admin după autentificarea cu acreditările curente.

Modificările stării serviciului Modbus/TCP sau SSDP necesită o repornire a dispozitivului. Dacă aceste setări nu au fost niciodată stocate de un firmware anterior, ambele servicii sunt activate implicit pentru compatibilitate inversă.

Browserele pot stoca în cache acreditările de autentificare de bază pentru adresa dispozitivului. După modificarea parolei, browserul poate încerca mai întâi acreditările vechi și apoi afișează o nouă solicitare de autentificare. Închiderea tuturor ferestrelor browserului sau utilizarea unei ferestre de navigare privată poate forța, de asemenea, o nouă autentificare.

API-uri care nu necesită autentificare de bază

Următoarele endpoint-uri rămân disponibile fără un header de autentificare de bază, astfel încât interfața web să poată încărca informațiile de bază despre dispozitiv, iar procesul de recuperare cu semnătură să poată funcționa:

POST /api/admin/enable poate fi apelat și fără autentificare de bază atunci când Securitatea admin este momentan dezactivată, deoarece este endpoint-ul utilizat pentru configurarea inițială. Dacă Securitatea admin este deja activată, acreditările curente valide de administrator sunt necesare înainte ca acest endpoint să poată modifica sau dezactiva configurația de securitate.

Fișierele statice ale interfeței web și alte resurse GET care nu sunt /api/ nu sunt endpoint-uri API și rămân accesibile public. Toate celelalte endpoint-uri API locale sunt tratate ca protejate atunci când Securitatea admin este activată, inclusiv toate API-urile Set, API-urile GET sensibile și operațiunile cu firmware OTA.

Referință API

GET /api/admin/status

Returnează starea curentă a Securității admin. Autentificarea nu este necesară.

Exemplu de răspuns:

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

Câmpuri:

• enabled: 1 când Securitatea admin este activată; în caz contrar 0.
• hasPassword: 1 când au fost configurate acreditările de administrator.
• recoverySupported: 1 când recuperarea cu semnătură a administratorului este suportată de firmware.
• modbusTcpEnabled: 1 când serviciul Modbus/TCP de pe portul 502 este activat.
• ssdpEnabled: 1 când descoperirea SSDP este activată.

POST /api/admin/enable

Activează sau dezactivează Securitatea admin.

Activarea Securității admin:

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

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

Exemplu cu curl:

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

Dezactivarea Securității admin:

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

{
  "enable": 0
}

Dacă Securitatea admin este deja activată, acreditările curente valide de autentificare de bază sunt necesare pentru a apela acest API.

Exemplu:

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

POST /api/admin/password

Modifică numele de utilizator și parola de administrator. Acest API este protejat după ce Securitatea admin a fost activată.

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

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

Exemplu:

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

După ce cererea are succes, utilizați noile acreditări pentru cererile protejate ulterioare.

GET /api/admin/check

Verifică dacă acreditările de autentificare de bază furnizate sunt valide.

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

Răspuns reușit:

{
  "successful": 1
}

Acreditările lipsă sau invalide duc la HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Creează un payload de recuperare specific dispozitivului, de unică folosință. Autentificarea nu este necesară, deoarece acest endpoint nu resetează acreditările de la sine.

Exemplu de răspuns:

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

payload-ul returnat trebuie trimis către IAMMETER atunci când este necesară recuperarea administratorului.

Solicitarea unui nou challenge invalidează challenge-ul anterior. Un challenge este invalidat și după o recuperare reușită sau o repornire a dispozitivului.

POST /api/admin/recovery

Trimite payload-ul de recuperare și semnătura Ed25519 furnizată de 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"
}

Exemplu:

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

Dacă verificarea semnăturii are succes, dispozitivul șterge acreditările locale de administrator și dezactivează Securitatea admin. Pot fi configurate apoi un nou nume de utilizator și o nouă parolă de administrator.

Dacă dispozitivul nu are suficientă memorie liberă pentru a efectua verificarea semnăturii, API-ul returnează un răspuns similar cu:

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

În acest caz, reduceți utilizarea memoriei și solicitați un nou challenge de recuperare înainte de a reîncerca. Dacă parola nu este disponibilă și modul de operare nu poate fi modificat, reporniți dispozitivul și efectuați recuperarea înainte ca o conexiune MQTTS sau HTTPS să consume memorie suplimentară.

Cum funcționează recuperarea parolei

Proiectarea recuperării evită adăugarea unei comenzi neautentificate de resetare din fabrică care ar putea ocoli protecția administratorului.

Procesul utilizează o pereche de chei publice/private Ed25519:

• firmware-ul dispozitivului conține doar cheia publică de recuperare IAMMETER;
• cheia privată corespunzătoare este păstrată de IAMMETER și nu este stocată pe dispozitiv;
• dispozitivul creează un payload care conține operațiunea solicitată, SN-ul dispozitivului, MAC-ul dispozitivului și un nonce de unică folosință;
• IAMMETER semnează exact acel payload cu cheia privată de recuperare;
• dispozitivul verifică semnătura cu cheia publică încorporată;
• doar o semnătură validă pentru dispozitivul curent și nonce-ul curent poate șterge configurația de administrator.

Nonce-ul este stocat doar în RAM. Devine invalid când dispozitivul repornește, când este solicitat un alt challenge sau după o recuperare reușită. Prin urmare, un payload și o semnătură vechi nu pot fi reutilizate pentru o sesiune de recuperare ulterioară.

Scenarii de utilizare

Scenariul 1: Setarea unui nume de utilizator și a unei parole de administrator

Cea mai simplă metodă este interfața web:

1. Deschideți http://<device-ip>/.
2. Deschideți fila Security.
3. Introduceți noul nume de utilizator și noua parolă de administrator.
4. Confirmați parola.
5. Activați Securitatea admin.

Aceeași operațiune poate fi efectuată prin 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"}'

Verificați rezultatul:

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

Scenariul 2: Accesarea API-urilor protejate cu autentificare de bază

Pentru fiecare cerere protejată ulterioară, trimiteți numele de utilizator și parola de administrator în header-ul de autentificare de bază HTTP.

Valoarea header-ului este construită după cum urmează:

Authorization: Basic Base64...ord)

De exemplu, acreditările admin:ExamplePassword sunt combinate mai întâi și apoi codificate Base64. Majoritatea clienților HTTP efectuează acest lucru automat.

Utilizând curl:

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

Utilizând un header explicit:

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

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

Pentru o cerere POST JSON:

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

Browserul gestionează acest header automat după ce administratorul introduce acreditările în solicitarea de autentificare de bază.

Interfața web actuală încarcă firmware-ul către POST /api/ota_successful.html. Endpoint-ul moștenit POST /ota_successful.html rămâne disponibil pentru versiunile mai vechi ale interfeței web și pentru instrumente externe. Ambele endpoint-uri necesită autentificare de bază atunci când Securitatea admin este activată.

Filele interfeței web se comportă astfel atunci când solicitarea de autentificare este închisă:

• Settings și Wi-Fi nu pot încărca API-urile lor de configurare protejate și afișează un mesaj de autentificare de administrator.
• System poate afișa în continuare SN, MAC și versiunea firmware, deoarece aceste valori au fost obținute de la endpoint-ul public /api/monitor. Încărcarea OTA rămâne protejată.
• Security poate afișa în continuare starea de bază, deoarece /api/admin/status este public. Modificările acreditărilor și modificările comutatoarelor de servicii rămân protejate.

Scenariul 3: Recuperarea accesului după uitarea parolei

Dispozitivul nu are un buton hardware de resetare. Pentru a evita adăugarea unei funcții de resetare neautentificată care ar putea ocoli Securitatea admin, dispozitivul utilizează mecanismul de recuperare cu semnătură descris mai sus.

Această procedură este destinată doar cazurilor în care atât numele de utilizator, cât și parola de administrator au fost uitate. Păstrați acreditările configurate într-un loc securizat și evitați să vă bazați pe procesul de recuperare pentru modificări de rutină ale acreditărilor. Dacă acreditările curente sunt încă disponibile, modificați-le direct din fila Security sau cu POST /api/admin/password.

1. Solicitați un nou challenge de recuperare de la dispozitiv:

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

2. Copiați valoarea completă a payload-ului din răspuns. Nu modificați SN, MAC, nonce-ul, separatoarele sau literele mari/mici.

3. Contactați asistența IAMMETER la support@devicebit.com și trimiteți payload-ul complet.

4. După confirmarea dreptului de proprietate sau a autorizării serviciului, IAMMETER semnează payload-ul și returnează o semnătură Ed25519.

5. Trimiteți payload-ul original și semnătura returnată către dispozitiv:

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

6. După un răspuns reușit, Securitatea admin este dezactivată și acreditările anterioare de administrator sunt șterse. Deschideți fila Security sau apelați POST /api/admin/enable pentru a seta noi acreditări.

Nu reporniți dispozitivul și nu solicitați un alt challenge în timp ce așteptați semnătura. Oricare dintre aceste acțiuni invalidează payload-ul trimis, iar procesul de recuperare trebuie reluat cu un nou challenge.