Seguridad de administración local para medidores IAMMETER: guía del usuario

Seguridad de administración local: guía del usuario

El módulo Local Admin Security está disponible a partir del firmware i.91.065.3.

Finalidad

El módulo protege la interfaz web local y las API locales sensibles del dispositivo frente a accesos no autorizados.

Después de activarlo, se requieren un nombre de usuario y una contraseña de administrador para:

• todas las Set API disponibles en la página de prueba de API de WEM;
• las API GET que devuelven datos de configuración sensibles o realizan operaciones sensibles;
• la carga y actualización local del firmware mediante OTA.

Esto incluye operaciones como cambiar la configuración de red o de carga, actualizar el firmware, reiniciar el dispositivo, restaurar los valores de fábrica y modificar otros parámetros sensibles.

El módulo ofrece:

• credenciales de administrador configurables;
• HTTP Basic Authentication para las API locales protegidas;
• cambio de credenciales mediante la interfaz web o la API;
• un proceso de recuperación basado en firma Ed25519 si se olvida la contraseña.

La función está desactivada de forma predeterminada para mantener la compatibilidad con firmware anteriores. Debe activarse y configurarse antes de que la protección entre en vigor.

La interfaz web local actual utiliza HTTP. HTTP Basic Authentication codifica las credenciales, pero no las cifra. Utiliza esta función en una red local de confianza, salvo que se acceda al dispositivo mediante un mecanismo de transporte seguro adicional.

Configurar Admin Security en la interfaz web

1. Abre la dirección IP del dispositivo en un navegador.
2. Selecciona la pestaña Security.
3. Introduce un nombre de usuario de administrador.
4. Introduce y confirma la contraseña.
5. Selecciona Enable Admin Security.

El nombre de usuario y la contraseña deben cumplir estas reglas:

• longitud de 1 a 32 caracteres;
• únicamente caracteres ASCII visibles;
• no se permiten los dos puntos (:), las comillas dobles (") ni la barra invertida (\).

Cuando Admin Security está activado, el navegador muestra una solicitud de autenticación al acceder a una página o API protegida. Introduce el nombre de usuario y la contraseña configurados.

La pestaña Security también permite:

• cambiar el nombre de usuario y la contraseña;
• comprobar que la autenticación de administrador está activada;
• activar o desactivar el servicio Modbus/TCP en el puerto 502;
• activar o desactivar el descubrimiento SSDP;
• desactivar Admin Security después de autenticarse con las credenciales actuales.

Los cambios en el estado de Modbus/TCP o SSDP requieren reiniciar el dispositivo. Si estos ajustes no fueron guardados por un firmware anterior, ambos servicios están activados de forma predeterminada para conservar la compatibilidad.

El navegador puede guardar en caché las credenciales de Basic Authentication para la dirección del dispositivo. Después de cambiar la contraseña, puede probar primero las credenciales antiguas y luego mostrar una nueva solicitud. Cerrar todas las ventanas o utilizar navegación privada también puede forzar un nuevo inicio de sesión.

API que no requieren Basic Authentication

Los siguientes endpoints continúan disponibles sin cabecera Basic Authentication para que la interfaz web pueda cargar información básica y funcione el proceso de recuperación firmado:

POST /api/admin/enable también puede llamarse sin Basic Authentication cuando Admin Security está desactivado, ya que se utiliza para la configuración inicial. Si ya está activado, se necesitan las credenciales válidas actuales para cambiar o desactivar la configuración.

Los archivos estáticos de la interfaz web y otros recursos GET que no se encuentran bajo /api/ no son endpoints API y siguen siendo legibles públicamente. Todos los demás endpoints API locales se protegen al activar Admin Security, incluidas todas las Set API, las API GET sensibles y las operaciones OTA.

Referencia de API

GET /api/admin/status

Devuelve el estado actual de Admin Security. No requiere autenticación.

Respuesta de ejemplo:

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

Campos:

• enabled: 1 cuando Admin Security está activado; en caso contrario, 0.
• hasPassword: 1 cuando se han configurado credenciales de administrador.
• recoverySupported: 1 cuando el firmware admite recuperación firmada.
• modbusTcpEnabled: 1 cuando está activado Modbus/TCP en el puerto 502.
• ssdpEnabled: 1 cuando está activado el descubrimiento SSDP.

POST /api/admin/enable

Activa o desactiva Admin Security.

Activación:

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

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

Ejemplo con curl:

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

Desactivación:

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

{
  "enable": 0
}

Si Admin Security ya está activado, se necesitan las credenciales válidas actuales de Basic Authentication para llamar a esta API.

Ejemplo:

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

POST /api/admin/password

Cambia el nombre de usuario y la contraseña. Esta API queda protegida después de activar Admin Security.

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

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

Ejemplo:

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

Después de una respuesta correcta, utiliza las nuevas credenciales en las siguientes solicitudes protegidas.

GET /api/admin/check

Comprueba si las credenciales de Basic Authentication proporcionadas son válidas.

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

Respuesta correcta:

{
  "successful": 1
}

Las credenciales ausentes o no válidas producen HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Crea un payload de recuperación de un solo uso específico del dispositivo. No requiere autenticación porque este endpoint no restablece las credenciales por sí solo.

Respuesta de ejemplo:

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

El valor payload debe enviarse a IAMMETER cuando se necesite recuperar el acceso de administrador.

Solicitar un nuevo desafío invalida el anterior. También queda invalidado después de una recuperación correcta o al reiniciar el dispositivo.

POST /api/admin/recovery

Envía el payload de recuperación y la firma Ed25519 proporcionada por 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"
}

Ejemplo:

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 firma es válida, el dispositivo borra las credenciales locales y desactiva Admin Security. A continuación se pueden configurar un nuevo nombre de usuario y contraseña.

Si el dispositivo no dispone de suficiente memoria libre para verificar la firma, la API devuelve una respuesta similar:

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

En ese caso, reduce el uso de memoria y solicita un nuevo desafío antes de volver a intentarlo. Si no tienes la contraseña y no puedes cambiar el modo de funcionamiento, reinicia el dispositivo y recupera el acceso antes de que una conexión MQTTS o HTTPS consuma memoria adicional.

Cómo funciona la recuperación de contraseña

El diseño evita añadir un comando de restauración de fábrica sin autenticación que pueda eludir la protección del administrador.

El proceso utiliza un par de claves pública/privada Ed25519:

• el firmware contiene únicamente la clave pública de recuperación de IAMMETER;
• IAMMETER conserva la clave privada correspondiente, que no se guarda en el dispositivo;
• el dispositivo crea un payload con la operación solicitada, el número de serie, la dirección MAC y un nonce de un solo uso;
• IAMMETER firma exactamente ese payload con la clave privada;
• el dispositivo verifica la firma con su clave pública integrada;
• solo una firma válida para el dispositivo y el nonce actuales puede borrar la configuración.

El nonce se guarda únicamente en la RAM. Deja de ser válido al reiniciar el dispositivo, solicitar otro desafío o completar una recuperación. Por tanto, un payload y una firma antiguos no pueden reutilizarse en otra sesión.

Escenarios de uso

Escenario 1: definir el nombre de usuario y la contraseña

El método más sencillo es la interfaz web:

1. Abre http://<device-ip>/.
2. Abre la pestaña Security.
3. Introduce el nuevo nombre de usuario y contraseña.
4. Confirma la contraseña.
5. Activa Admin Security.

La misma operación puede realizarse mediante 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"}'

Comprueba el resultado:

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

Escenario 2: acceder a API protegidas con Basic Authentication

En cada solicitud protegida posterior, envía el nombre de usuario y la contraseña en la cabecera HTTP Basic Authentication.

El valor de la cabecera se construye así:

Authorization: Basic Base64(username:password)

Por ejemplo, las credenciales admin:ExamplePassword se combinan y después se codifican en Base64. La mayoría de clientes HTTP lo hacen automáticamente.

Con curl:

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

Con una cabecera explícita:

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

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

Para una solicitud JSON POST:

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

El navegador gestiona automáticamente esta cabecera después de que el administrador introduzca sus credenciales en la solicitud de Basic Authentication.

La interfaz web actual carga el firmware en POST /api/ota_successful.html. El endpoint antiguo POST /ota_successful.html sigue disponible para versiones anteriores y herramientas externas. Ambos requieren Basic Authentication cuando Admin Security está activado.

Si se cierra la solicitud de autenticación, las pestañas se comportan así:

• Settings y Wi-Fi no pueden cargar sus API de configuración protegidas y muestran un mensaje de autenticación;
• System puede seguir mostrando SN, MAC y versión de firmware porque proceden del endpoint público /api/monitor. La carga OTA permanece protegida;
• Security puede mostrar el estado básico porque /api/admin/status es público. Los cambios de credenciales y servicios permanecen protegidos.

Escenario 3: recuperar el acceso tras olvidar la contraseña

El dispositivo no dispone de botón físico de restablecimiento. Para evitar una función sin autenticación que pudiera eludir Admin Security, utiliza el mecanismo de recuperación firmado descrito anteriormente.

Este procedimiento está pensado únicamente para los casos en que se hayan olvidado tanto el nombre de usuario como la contraseña. Guarda las credenciales en un lugar seguro y no utilices la recuperación para cambios rutinarios. Si todavía dispones de las credenciales actuales, cámbialas desde la pestaña Security o con POST /api/admin/password.

1. Solicita un nuevo desafío de recuperación:

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

2. Copia el valor completo de payload. No modifiques el SN, la MAC, el nonce, los separadores ni las mayúsculas/minúsculas.

3. Contacta con el soporte de IAMMETER en support@devicebit.com y envía el payload completo.

4. Una vez confirmada la propiedad o autorización de servicio, IAMMETER firma el payload y devuelve una firma Ed25519.

5. Envía al dispositivo el payload original y la firma recibida:

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

6. Tras una respuesta correcta, Admin Security se desactiva y se borran las credenciales anteriores. Abre la pestaña Security o llama a POST /api/admin/enable para establecer unas nuevas.

No reinicies el dispositivo ni solicites otro desafío mientras esperas la firma. Cualquiera de estas acciones invalida el payload enviado y obliga a iniciar de nuevo el proceso con otro desafío.