Configuración de certificados compatibles con TLS de Kbsa Shelly

Este artículo explica qué certificados TLS y claves privadas aceptan los dispositivos Shelly, cómo prepararlos y cargarlos, y dónde se utilizan (por ejemplo, MQTT mediante TLS/mTLS y, desde v1.8.0, la interfaz web local mediante HTTPS en Gen3 y versiones posteriores). Para obtener información general sobre seguridad y RED, consulta nuestro artículo complementario: Lo que debes saber: Shelly y la norma EU RED EN 18031-1.

TL;DR (Referencia rápida)

• Archivos/contenedores: PEM ✅, DER ✅, PKCS#12/PFX ⚠️ (la interfaz del dispositivo no importa PFX -> usa PEM/DER en su lugar.)

• Claves privadas: PKCS#8 (sin cifrar) ✅, PKCS#1 (sin cifrar) ✅, claves cifradas ❌ (sin campo de contraseña en la interfaz)

• Algoritmos: RSA-2048 ✅, ECDSA P-256/P-384/P-521 ✅, Ed25519 ❌

• Cadenas: Carga la hoja + los certificados intermedios (concatenados). No incluyas la raíz. Profundidad máxima de certificados intermedios: 8.

• Restricciones básicas de la hoja: No debe ser una CA (se rechaza CA:TRUE).

• Verificación: Con Enhanced Security habilitado -> se envía SNI y se verifican el nombre de host (SAN/CN) y el tiempo de validez.

• Versiones de TLS: TLS 1.2 compatible; TLS 1.3 no está habilitado.

• Interfaz web: Desde v1.8.0 (Gen3+), se admite HTTPS, incluidos certificados HTTPS personalizados (autofirmados o de una PKI privada).

• Nota operativa: Aplicar nuevo material TLS puede requerir un reinicio del dispositivo.

Compatible frente a no compatible (matriz)

Formatos de archivo y contenedor compatibles

• PEM (.pem, .crt, .cer) - Compatible y recomendado.

• DER (.der) - Compatible (codificación binaria de los mismos datos).

• PKCS#12/PFX (.p12, .pfx) - La interfaz del dispositivo no importa PFX. Las cargas de archivos PFX habituales fallan. Ni siquiera se importan los archivos .p12 sin cifrar.

  Recomendación: Extrae la clave y los certificados como PEM sin cifrar y súbelos.

Formatos de clave privada

• PKCS#8 (sin cifrar) - Compatible y recomendado.

• PKCS#1 (RSA, sin cifrar) - Compatible.

• Claves cifradas - No compatibles (la interfaz no solicita ninguna contraseña).

Identificadores rápidos en PEM:

• PKCS#8 sin cifrar -> -----BEGIN PRIVATE KEY-----

• PKCS#1 (RSA) sin cifrar -> -----BEGIN RSA PRIVATE KEY-----

• Clave cifrada (no compatible) -> -----BEGIN ENCRYPTED PRIVATE KEY-----

Algoritmos de clave compatibles

• RSA-2048 - Compatible.

• ECDSA - secp256r1 (P-256), secp384r1 (P-384), secp521r1 (P-521) - Compatible.

• Ed25519 (EdDSA) - No compatible (Curve25519/X25519 puede estar disponible para ECDH, pero no para firmas).

Consejo: Para implementaciones new, ECDSA P-256 ofrece claves más pequeñas y negociaciones más rápidas en dispositivos con recursos limitados.

Cadenas de certificados y confianza

• Cadena presentada (la identidad que subes al dispositivo):

Sube un único archivo PEM que contenga primero el certificado hoja, seguido de cualquier certificado de CA intermedia necesario (PEM concatenado). No incluyas la CA raíz.

Se aplica a: el certificado de identidad del cliente para mTLS (certificado de cliente MQTT) y el certificado del servidor HTTPS de la interfaz web.

• Quién debe confiar en qué (almacenes de confianza)

Cuando Shelly es un cliente TLS (por ejemplo, al conectarse a tu broker MQTT)
Sube tu CA raíz (y cualquier CA intermedia en la que quieras que Shelly confíe) en Settings -> TLS Configuration -> Custom certificate authority (CA) PEM bundle. Este es el almacén de confianza del dispositivo que se utiliza para verificar servidores. (No incluyas claves privadas aquí.)

Cuando Shelly es un servidor TLS (Web-UI mediante HTTPS, Gen3+, v1.8.0+)
El navegador/SO (el cliente) debe confiar en la CA que emitió el certificado de Web-UI del dispositivo.

• Profundidad máxima de la cadena: Hasta 8 certificados intermedios.

• Restricciones básicas (hoja): La hoja no debe ser una CA. Se rechaza una hoja con CA:TRUE. Se acepta una hoja con CA:FALSE o sin la extensión BasicConstraints.

• Certificados HTTPS personalizados (Web-UI, Gen3+, v1.8.0+):

Puedes instalar un certificado de servidor HTTPS personalizado (autofirmado o de una PKI privada). Asegúrate de que los dispositivos cliente confíen en la CA emisora; de lo contrario, el navegador mostrará una advertencia. Si accedes mediante un nombre DNS, incluye ese FQDN en el SAN. Si accedes mediante una IP, incluye la IP en el SAN como una entrada de IP.

• CA pública: normalmente ya es de confianza.

• PKI privada: instala tu CA raíz/intermedia privada únicamente en los clientes o el almacén de confianza de la aplicación que accederán a la Web-UI. No incluyas la raíz en la cadena que presenta el dispositivo.

Versión de TLS y comportamiento de verificación

• Versiones de TLS: Se admite TLS 1.2. TLS 1.3 no está disponible en las compilaciones actuales.

• Comprobaciones de identidad y hora del servidor:

  • Envía SNI (indicación del nombre del servidor) para endpoints basados en el nombre de host.

  • Verifica el nombre de host con respecto al SAN/CN del certificado.

  • Verifica el periodo de validez del certificado (fecha/hora).

Dónde se usan los certificados en Shelly

• MQTT mediante TLS (autenticación del servidor) - Carga el certificado de la CA para que Shelly pueda validar el certificado del broker.

• MQTT con certificados de cliente (mTLS) - Además, carga un certificado de cliente y una clave privada sin cifrar coincidente; activa la opción de certificado de cliente en la configuración de MQTT.

• Web-UI local mediante HTTPS (desde v1.8.0) - La interfaz web del dispositivo admite HTTPS.

  • Si vas a acceder mediante un nombre DNS (p. ej., shelly-dev.example.lan), incluye ese FQDN en el SAN del certificado de Web-UI que planeas confiar/utilizar.

  • Si accedes mediante una dirección IP, la IP debe estar presente en SAN como una entrada IP (los nombres DNS por sí solos no bastarán para que los navegadores permitan el acceso mediante IP).

  • En entornos administrados, considera una CA interna en la que confíen tus endpoints, o emite un certificado mediante ACME DNS-01 para un nombre privado.

  • Certificado HTTPS personalizado (autofirmado o de una PKI privada): carga un certificado de servidor y la clave privada sin cifrar correspondiente para la Web-UI (las etiquetas pueden variar según el modelo; consulta Configuración -> Configuración de TLS). Asegúrate de que los dispositivos cliente confíen en la CA emisora o en el certificado del dispositivo.

Preparación de archivos (guía rápida de OpenSSL)

Generar una clave ECDSA P-256 y una CSR (recomendado)

# Clave privada (PKCS#8, sin cifrar) openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out device.key # CSR (ajusta el sujeto) openssl req -new -key device.key -out device.csr -subj "/CN=device.example.com" 

Generar una clave RSA-2048 y una CSR

openssl genrsa -out device.key 2048 openssl req -new -key device.key -out device.csr -subj "/CN=device.example.com" 

Concatenar la hoja y los certificados intermedios (PEM)

# Primero la hoja y luego los certificados intermedios; NO incluyas la raíz cat device.crt intermediate1.crt intermediate2.crt > device-chain.pem 

Eliminar una frase de contraseña (si la clave está cifrada)

# Genera PKCS#8 sin cifrar openssl pkey -in encrypted.key -out key-unencrypted.pem 

Convertir DER <-> PEM

# PEM -> DER openssl x509 -in device.crt -outform der -out device.der # DER -> PEM openssl x509 -in device.der -inform der -out device.crt 

Extraer archivos PEM de PFX (evita cargar .p12/.pfx)

# Clave privada sin cifrar openssl pkcs12 -in bundle.p12 -nocerts -nodes -out key-unencrypted.pem # Hoja + cadena openssl pkcs12 -in bundle.p12 -clcerts -nokeys -out device.crt openssl pkcs12 -in bundle.p12 -nodes -nokeys -cacerts -out intermediates.pem # Cadena que se puede cargar cat device.crt intermediates.pem > device-chain.pem 

Carga de certificados (Web-UI)

1. Abre la WebUI -> Configuración -> Configuración de TLS.

2. Carga los archivos necesarios:

   • Certificado de la CA (ca.crt) para validar el servidor.

   • Certificado del cliente (solo si se usa mTLS).

   • Clave privada del cliente (sin cifrar; coincide con el certificado del cliente).

   • (Gen3+, v1.8.0+) Certificate del servidor de la interfaz web (opcional): carga el certificado del servidor HTTPS y su clave privada sin cifrar correspondiente si quieres un certificado personalizado para la interfaz (autofirmado o de una PKI privada).

3. Guarda cada carga.

4. Reinicia cuando se te solicite para que los cambios surtan efecto.

Después de cargarlo, configura el servicio específico (por ejemplo, Configuración -> MQTT) para que use TLS y, si es necesario, el certificado del cliente.

Notas de configuración y prácticas recomendadas

• SAN es importante. Asegúrate de que el nombre de host o IP exacto al que te conectas esté presente en el SAN del certificado del servidor; el CN por sí solo no basta para los clientes modernos.

• Mantén los PEM concisos. Incluye únicamente el leaf + los intermediarios necesarios. Los paquetes enormes pueden superar los límites de memoria integrada.

• Evita las claves cifradas. No existe una opción en la interfaz para introducir contraseñas;

• No marques el leaf como CA. Emite uno nuevo si BasicConstraints muestra CA:TRUE.

• SNI requiere un nombre de host. Cuando sea posible, usa un nombre DNS en lugar de una IP sin procesar para lograr una mejor compatibilidad.

Solución de problemas (soluciones rápidas)

• «No se pudo analizar la clave o el certificado». Probablemente se trata de una clave cifrada o un PFX. Convierte a un PEM sin cifrar y vuelve a intentarlo.

• El nombre de host no coincide. Añade el FQDN/IP exacto que usas al SAN del certificado.

• Cadena incompleta. Concatena leaf + todos los intermediarios en un único PEM; omite la raíz.

• Errores de tiempo durante el handshake. Asegúrate de que el reloj del dispositivo sea correcto (habilita NTP).

• Límites de memoria. Si las cargas fallan intermitentemente, elimina los comentarios/certificados adicionales y mantén los archivos PEM mínimos.

Lista de comprobación previa a la carga

• La clave privada está sin cifrar (PKCS#8 o PKCS#1) en PEM.

• El archivo de Certificate contiene leaf + intermediarios (concatenados), sin la raíz.

• El tipo de clave es RSA-2048 o ECDSA P-256/P-384/P-521 (no Ed25519).

• Leaf no es una CA (CA:FALSE o sin BasicConstraints).

• SAN cubre el FQDN/IP exacto que usarás.

• Seguridad mejorada habilitada para la verificación TLS saliente.

• En v1.8.0+, planifica acceder a la interfaz web mediante HTTPS.