Seguretat d'administració local per als comptadors d'energia IAMMETER: guia d'usuari

El mòdul de seguretat d'administració local (Local Admin Security) està disponible al firmware i.91.065.3 i versions posteriors.

En aquesta pàgina

• Finalitat
• Configurar Admin Security a la interfície web
• API que no requereixen Basic Authentication
• Referència de l'API
• Com funciona la recuperació de la contrasenya
• Escenaris d'ús
  • Definir un nom d'usuari i una contrasenya d'administrador
  • Accedir a les API protegides amb Basic Authentication
  • Recuperar l'accés després d'oblidar la contrasenya

Finalitat

El mòdul de seguretat d'administració local protegeix la interfície web local del dispositiu i les API locals sensibles contra accessos no autoritzats.

Un cop activada la funció, cal un nom d'usuari i una contrasenya d'administrador per a:

• totes les Set API disponibles a la pàgina de proves de l'API WEM;
• les API GET que retornen dades de configuració sensibles o duen a terme operacions sensibles;
• les operacions locals de càrrega i actualització de firmware OTA.

Això inclou operacions com canviar la configuració de xarxa o de càrrega de dades, actualitzar el firmware, reiniciar el dispositiu, restaurar la configuració de fàbrica i modificar altres paràmetres de configuració sensibles.

El mòdul ofereix:

• credencials d'administrador configurables;
• autenticació bàsica HTTP (Basic Authentication) per a les API locals protegides;
• canvis de credencials a través de la interfície web o de l'API;
• un procés de recuperació basat en signatures Ed25519 si s'oblida la contrasenya d'administrador.

La funció està desactivada per defecte per compatibilitat amb firmware anterior. Cal activar-la i configurar-la perquè l'accés protegit entri en vigor.

La interfície web local actual utilitza HTTP. L'autenticació bàsica HTTP codifica les credencials, però no les xifra. Utilitzeu aquesta funció en una xarxa local de confiança, tret que s'accedeixi al dispositiu a través d'un mecanisme de transport segur addicional.

Configurar Admin Security a la interfície web

1. Obriu l'adreça IP del dispositiu en un navegador.
2. Seleccioneu la pestanya Seguretat.
3. Introduïu un nom d'usuari d'administrador.
4. Introduïu i confirmeu la contrasenya d'administrador.
5. Seleccioneu Enable Admin Security.

El nom d'usuari i la contrasenya han de complir les regles següents:

• longitud: d'1 a 32 caràcters;
• només caràcters ASCII visibles;
• no es permeten els dos punts (:), les cometes dobles (") ni la barra invertida (\).

Un cop activat Admin Security, el navegador mostra una finestra d'autenticació quan s'accedeix a una pàgina o una API protegida. Introduïu el nom d'usuari i la contrasenya d'administrador que hàgiu configurat.

La pestanya Seguretat també es pot utilitzar per a:

• canviar el nom d'usuari i la contrasenya d'administrador;
• verificar que l'autenticació d'administrador està activada;
• activar o desactivar el servei Modbus/TCP al port 502;
• activar o desactivar la descoberta SSDP;
• desactivar Admin Security després d'autenticar-vos amb les credencials actuals.

Els canvis en l'estat del servei Modbus/TCP o SSDP requereixen reiniciar el dispositiu. Si un firmware anterior no ha desat mai aquesta configuració, tots dos serveis estan activats per defecte per compatibilitat enrere.

És possible que els navegadors desin a la memòria cau les credencials de Basic Authentication per a l'adreça del dispositiu. Després de canviar la contrasenya, pot ser que el navegador torni a provar primer les credencials antigues i tot seguit mostri una finestra d'autenticació nova. Tancar totes les finestres del navegador o utilitzar una finestra de navegació privada també pot forçar un inici de sessió nou.

API que no requereixen Basic Authentication

Els endpoints següents continuen disponibles sense capçalera Basic Authentication perquè la interfície web pugui carregar la informació bàsica del dispositiu i el procés de recuperació signada pugui funcionar:

També es pot cridar POST /api/admin/enable sense Basic Authentication quan Admin Security està desactivat, perquè és l'endpoint que s'utilitza per a la configuració inicial. Si Admin Security ja està activat, calen les credencials d'administrador vàlides actuals perquè aquest endpoint pugui canviar o desactivar la configuració de seguretat.

Els fitxers estàtics de la interfície web i altres recursos GET que no es troben sota /api/ no són endpoints d'API i continuen sent de lectura pública. Tots els altres endpoints d'API locals es tracten com a protegits quan Admin Security està activat, incloent-hi totes les Set API, les API GET sensibles i les operacions de firmware OTA.

Referència de l'API

GET /api/admin/status

Retorna l'estat actual d'Admin Security. No cal autenticació.

Resposta d'exemple:

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

Camps:

• enabled: 1 quan Admin Security està activat; en cas contrari, 0.
• hasPassword: 1 quan s'han configurat credencials d'administrador.
• recoverySupported: 1 quan el firmware admet la recuperació d'administrador signada.
• modbusTcpEnabled: 1 quan el servei Modbus/TCP al port 502 està activat.
• ssdpEnabled: 1 quan la descoberta SSDP està activada.

POST /api/admin/enable

Activa o desactiva Admin Security.

Activar Admin Security:

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

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

Exemple amb curl:

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

Desactivar Admin Security:

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

{
  "enable": 0
}

Si Admin Security ja està activat, calen les credencials de Basic Authentication vàlides actuals per cridar aquesta API.

Exemple:

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

POST /api/admin/password

Canvia el nom d'usuari i la contrasenya d'administrador. Aquesta API està protegida un cop activat Admin Security.

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

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

Exemple:

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

Un cop la sol·licitud s'hagi completat correctament, utilitzeu les credencials noves per a les sol·licituds protegides següents.

GET /api/admin/check

Comprova si les credencials de Basic Authentication proporcionades són vàlides.

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

Resposta correcta:

{
  "successful": 1
}

Si falten credencials o no són vàlides, es retorna HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Crea un payload de recuperació d'un sol ús específic del dispositiu. No cal autenticació perquè aquest endpoint no restableix les credencials per si sol.

Resposta d'exemple:

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

El payload retornat s'ha d'enviar a IAMMETER quan calgui la recuperació de l'administrador.

Sol·licitar un repte nou invalida el repte anterior. Un repte també queda invalidat després d'una recuperació correcta o d'un reinici del dispositiu.

POST /api/admin/recovery

Envia el payload de recuperació i la signatura Ed25519 proporcionada per 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"
}

Exemple:

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

Si la verificació de la signatura té èxit, el dispositiu esborra les credencials d'administrador locals i desactiva Admin Security. Després es pot configurar un nom d'usuari i una contrasenya d'administrador nous.

Si el dispositiu no té prou memòria lliure per executar la verificació de la signatura, l'API retorna una resposta similar a aquesta:

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

En aquest cas, reduïu l'ús de memòria i sol·liciteu un repte de recuperació nou abans de tornar-ho a provar. Si la contrasenya no està disponible i no es pot canviar el mode de funcionament, reinicieu el dispositiu i feu la recuperació abans que una connexió MQTTS o HTTPS consumeixi memòria addicional.

Com funciona la recuperació de la contrasenya

El disseny de la recuperació evita afegir una ordre de restabliment de fàbrica sense autenticació que pogués saltar-se la protecció de l'administrador.

El procés utilitza un parell de claus pública i privada Ed25519:

• el firmware del dispositiu només conté la clau pública de recuperació d'IAMMETER;
• la clau privada corresponent la conserva IAMMETER i no s'emmagatzema al dispositiu;
• el dispositiu crea un payload que conté l'operació sol·licitada, el número de sèrie (SN) del dispositiu, la MAC del dispositiu i un nonce d'un sol ús;
• IAMMETER signa exactament aquest payload amb la clau privada de recuperació;
• el dispositiu verifica la signatura amb la clau pública que porta integrada;
• només una signatura vàlida per al dispositiu actual i el nonce actual pot esborrar la configuració de l'administrador.

El nonce s'emmagatzema només a la RAM. Esdevé invàlid quan el dispositiu es reinicia, quan es sol·licita un altre repte o després d'una recuperació correcta. Per tant, un payload i una signatura antics no es poden reutilitzar en una sessió de recuperació posterior.

Escenaris d'ús

Escenari 1: definir un nom d'usuari i una contrasenya d'administrador

El mètode més senzill és la interfície web:

1. Obriu http://<device-ip>/.
2. Obriu la pestanya Seguretat.
3. Introduïu el nom d'usuari i la contrasenya d'administrador nous.
4. Confirmeu la contrasenya.
5. Activeu Admin Security.

La mateixa operació es pot dur a terme a través de 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"}'

Verifiqueu el resultat:

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

Escenari 2: accedir a les API protegides amb Basic Authentication

Per a cada sol·licitud protegida posterior, envieu el nom d'usuari i la contrasenya d'administrador a la capçalera HTTP Basic Authentication.

El valor de la capçalera es construeix de la manera següent:

Authorization: Basic Base64(username:password)

Per exemple, les credencials admin:ExamplePassword es combinen primer i després es codifiquen en Base64. La majoria de clients HTTP ho fan automàticament.

Amb curl:

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

Amb una capçalera explícita:

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

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

Per a una sol·licitud POST JSON:

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

El navegador gestiona aquesta capçalera automàticament després que l'administrador introdueixi les credencials a la finestra d'autenticació bàsica.

La interfície web actual carrega el firmware a POST /api/ota_successful.html. L'endpoint heretat POST /ota_successful.html continua disponible per a versions antigues de la interfície web i eines externes. Tots dos endpoints requereixen Basic Authentication quan Admin Security està activat.

Les pestanyes de la interfície web es comporten de la manera següent quan es tanca la finestra d'autenticació:

• Configuració i Wi-Fi no poden carregar les seves API de configuració protegides i mostren un missatge d'autenticació d'administrador.
• Sistema encara pot mostrar l'SN, la MAC i la versió del firmware perquè aquests valors s'obtenen de l'endpoint públic /api/monitor. La càrrega OTA continua protegida.
• Seguretat encara pot mostrar l'estat bàsic perquè /api/admin/status és públic. Els canvis de credencials i els canvis d'interruptors de servei continuen protegits.

Escenari 3: recuperar l'accés després d'oblidar la contrasenya

El dispositiu no té cap botó de restabliment físic. Per evitar afegir una funció de restabliment sense autenticació que pogués saltar-se Admin Security, el dispositiu utilitza un mecanisme de recuperació signat i específic del dispositiu.

Utilitzeu aquest procediment només quan hàgiu oblidat les credencials d'administrador. Si encara coneixeu les credencials actuals, canvieu-les des de la pestanya Seguretat o amb POST /api/admin/password.

Seguiu la guia completa pas a pas de recuperació de la contrasenya d'Admin Security

El flux de recuperació és:

1. Genereu un payload d'un sol ús amb GET /api/admin/recovery_challenge.
2. Inicieu sessió a l'aplicació Admin Recovery d'IAMMETER Contributor. El servei verifica que el vostre compte està autoritzat a gestionar l'SN del dispositiu i retorna una signatura Ed25519 per a aquest payload exacte.
3. Envieu el payload i la signatura sense modificar a POST /api/admin/recovery. Després d'una verificació correcta, Admin Security es desactiva i s'esborren les credencials d'administrador locals anteriors.

No reinicieu el dispositiu, no actualitzeu la pàgina del repte ni sol·liciteu un altre repte abans de completar la recuperació. Qualsevol d'aquestes accions invalida el nonce actual, de manera que haureu de tornar a començar amb un payload nou.

La guia de recuperació específica inclou captures de pantalla, ordres curl completes, la resolució de problemes de rebuig de signatures i el procediment de recuperació amb poca memòria.