Cómo configurar la verificación de certificados MQTTS y HTTPS en un medidor IAMMETER

Los medidores IAMMETER con firmware i.91.065.9 o posterior pueden verificar el certificado del servidor al enviar datos por MQTTS o HTTPS. Esto añade la verificación de la cadena de certificados y del nombre de host del servidor a las conexiones salientes seguras.

Este artículo trata la configuración de confianza TLS. No configura topics MQTT, cargas útiles JSON ni el descubrimiento de Home Assistant. Para el flujo MQTT, consulta Medidor MQTT: publicar datos IAMMETER en tu broker MQTT.

En esta página

• Elegir un modo de verificación de certificados
• Requisitos y límites importantes
• Comprobar el modo TLS actual
• Seleccionar la verificación builtin
• Seleccionar none para diagnóstico temporal
• Cargar y seleccionar una CA personalizada
• Eliminar la CA personalizada
• Usar Swagger UI de IAMMETER
• Solucionar problemas de verificación de certificados

Elegir un modo de verificación de certificados

Los clientes MQTTS y HTTPS de IAMMETER admiten tres modos de verificación del certificado del servidor:

Estos ajustes se aplican cuando IAMMETER actúa como cliente TLS y envía datos a un broker MQTTS o servidor HTTPS. No activan HTTPS en el servidor Web local del dispositivo.

builtin

builtin es el modo predeterminado. Se usa cuando no se ha guardado ninguna configuración de verificación TLS y se restaura al eliminar la configuración TLS CA o restablecer los valores de fábrica.

El firmware incluye estas CA raíz:

• DigiCert Global Root G2
• ISRG Root X1

El dispositivo verifica tanto la cadena de certificados como el nombre de host del servidor. El broker MQTTS o servidor HTTPS debe presentar un certificado cuya cadena llegue a una de estas raíces, y su Subject Alternative Name (SAN) debe coincidir con la dirección del servidor configurada.

Si la dirección de envío es una IP, el SAN debe contener exactamente esa IP. Un nombre DNS no equivale a una dirección IP, aunque ambos apunten al mismo servidor.

custom

custom realiza la misma verificación de cadena y nombre de host que builtin, pero confía en el certificado CA PEM cargado por el administrador. Úsalo cuando:

• el certificado del servidor lo emita una CA privada;
• se utilice un certificado de servidor autofirmado; o
• la CA raíz pública necesaria no esté incluida en el firmware.

Para una PKI privada, carga su certificado CA raíz. El servidor TLS debe seguir enviando los certificados intermedios necesarios durante la negociación. Un certificado de servidor autofirmado puede cargarse como ancla de confianza, pero su SAN debe seguir coincidiendo con el nombre de host o IP configurados.

none

none sigue estableciendo una conexión TLS cifrada, pero no verifica la cadena de certificados ni el nombre de host. Es similar al comportamiento TLS anterior sin autenticación del servidor.

Este modo es vulnerable a ataques de intermediario (man-in-the-middle). Úsalo solo temporalmente por compatibilidad o para diagnóstico. En producción, utiliza preferentemente builtin o custom.

Requisitos y límites importantes

Las API de configuración TLS CA requieren activar Local Admin Security. Cada solicitud debe incluir el nombre de usuario y la contraseña de administrador configurados mediante HTTP Basic Authentication.

El ordenador que ejecute curl o Swagger UI debe poder acceder a la IP local del dispositivo. Los clientes MQTTS y HTTPS comparten un modo de verificación y una CA personalizada, por lo que cualquier cambio afecta al modo de envío seguro utilizado.

Reinicia el dispositivo después de modificar TLS para que el cliente saliente se vuelva a crear con los nuevos ajustes.

Los ejemplos usan estos valores de muestra:

DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"

Sustitúyelos por la dirección real del dispositivo y las credenciales de administrador.

Comprobar el modo TLS actual

API:

GET /api/tls/ca/status

Ejemplo:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/tls/ca/status"

Respuesta de ejemplo:

{
  "successful": 1,
  "mode": "builtin",
  "customCaValid": 0,
  "customCaLength": 0,
  "customCaSha256": "",
  "restartRequiredAfterChange": 1
}

La respuesta indica el modo seleccionado y, cuando existe, la longitud y el resumen SHA-256 de la CA personalizada almacenada.

Seleccionar la verificación builtin

API:

POST /api/tls/ca/select

Ejemplo:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"builtin"}'

Reinicia el dispositivo después de una respuesta satisfactoria.

Seleccionar none para diagnóstico temporal

API:

POST /api/tls/ca/select

Ejemplo:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"none"}'

La respuesta advierte de que la verificación del certificado del servidor está desactivada. Reinicia tras cambiar el modo y vuelve a builtin o custom después del diagnóstico.

Cargar y seleccionar una CA personalizada

Cargar una CA y seleccionar custom son operaciones separadas. La carga no modifica automáticamente el modo activo.

Requisitos del archivo de CA personalizada

El archivo cargado debe cumplir todos estos requisitos:

• formato de certificado PEM;
• cuerpo de solicitud sin procesar, ni JSON ni multipart/form-data;
• Content-Type: application/x-pem-file;
• longitud de 1 a 3072 bytes, incluidos encabezados PEM, saltos de línea y espacios;
• contiene -----BEGIN CERTIFICATE----- y -----END CERTIFICATE-----;
• no contiene una clave privada.

El límite de 3072 bytes se aplica a todo el cuerpo de la solicitud HTTP. Se acepta un archivo PEM de 3072 bytes; se rechaza uno de 3073 bytes.

Comprueba el tamaño del archivo antes de cargarlo:

wc -c root-ca.pem

Paso 1: cargar la CA

API:

POST /api/tls/ca/upload

Ejemplo:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/upload" \
  -H "Content-Type: application/x-pem-file" \
  --data-binary @root-ca.pem

Ejemplo de respuesta satisfactoria:

{
  "successful": 1,
  "length": 1939,
  "sha256": "64-character SHA-256 digest",
  "message": "CA uploaded; select custom mode and restart"
}

El dispositivo guarda la CA en varios bloques KV y verifica la longitud y el resumen SHA-256 guardados antes de marcarla como activa. Una escritura interrumpida no sustituye la CA válida anterior.

Paso 2: seleccionar custom

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"custom"}'

El dispositivo rechaza esta solicitud si no hay una CA personalizada válida almacenada. No cambia silenciosamente a none.

Paso 3: reiniciar y verificar

Reinicia desde la interfaz Web local o utiliza la API de reinicio protegida:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/restart?reset=false"

Cuando el dispositivo vuelva a conectarse, consulta de nuevo su estado:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/tls/ca/status"

Confirma que mode sea custom, que customCaValid sea 1 y que la longitud y el resumen SHA-256 coincidan con el certificado cargado.

Eliminar la CA personalizada

API:

POST /api/tls/ca/delete

Ejemplo:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/delete"

Eliminar la CA personalizada también restablece el modo builtin. Reinicia después de eliminarla.

Usar Swagger UI de IAMMETER

Puedes probar las mismas API sin escribir manualmente comandos curl:

IAMMETER WEM API Test - TLS CA

1. Abre WEM API Test en un ordenador que pueda acceder a la IP local del dispositivo.
2. Introduce la dirección, por ejemplo 192.168.1.80, y selecciona Apply.
3. Selecciona Authorize e introduce el nombre de usuario y la contraseña de administrador.
4. Abre el grupo TLS CA - Authenticated.
5. Usa GET /api/tls/ca/status para revisar la configuración actual.
6. Utiliza la operación de carga, selección o eliminación según corresponda.
7. Reinicia el dispositivo después de cambiar el modo o certificado.

La página Swagger se ejecuta en el navegador y envía solicitudes directamente desde ese ordenador al dispositivo IAMMETER. No las transmite a través de IAMMETER Cloud, por lo que el navegador necesita conectividad directa con la IP del dispositivo.

Solucionar problemas de verificación de certificados

admin security required

Activa Local Admin Security antes de usar las API TLS CA. Estos ajustes no pueden modificarse de forma anónima.

custom CA is missing or invalid

Carga correctamente una CA PEM válida antes de seleccionar custom. Consulta /api/tls/ca/status y confirma que customCaValid sea 1.

La conexión TLS falla en builtin o custom

Comprueba todos estos puntos:

• el nombre de host o IP configurados coinciden con el SAN;
• el certificado está vigente y la hora del dispositivo es correcta;
• el servidor envía los certificados intermedios necesarios;
• la CA raíz seleccionada emitió el certificado del servidor o confía en él a través de su cadena;
• el dispositivo se reinició después del cambio TLS.

TLS funciona en none pero falla en los modos verificados

Esto suele indicar un problema de cadena de certificados, nombre de host, periodo de validez o reloj del dispositivo. Mantener none oculta el fallo de autenticación, pero no lo resuelve. Corrige el despliegue del certificado o carga la CA raíz adecuada y utiliza custom.