Skip to main content
Skip table of contents

Shelly TLS: Supported Certs and Config

This article explains which TLS certificates and private keys Shelly devices accept, how to prepare and upload them, and where they’re used (e.g., MQTT over TLS/mTLS and, from v1.8.0, the local Web-UI over HTTPS for Gen3 and newer). For overall security/RED context, see our companion article: What you need to know – Shelly and EU RED EN 18031-1.

TL;DR (Quick Reference)

  • File/containers: PEM ✅, DER ✅, PKCS#12/PFX ⚠️ (the device UI does not import PFX -> use PEM/DER instead.)

  • Private keys: PKCS#8 (unencrypted) ✅, PKCS#1 (unencrypted) ✅, encrypted keys ❌ (no UI password input)

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

  • Chains: Upload leaf + intermediates (concatenated). Don’t include the root. Max intermediate depth: 8.

  • Leaf Basic Constraints: Must not be a CA (CA:TRUE is rejected).

  • Verification: With Enhanced Security enabled -> SNI sent, hostname (SAN/CN) and validity time verified.

  • TLS versions: TLS 1.2 supported; TLS 1.3 not enabled.

  • Web-UI: From v1.8.0 (Gen3+), HTTPS is supported, including custom HTTPS certificates (self-signed or private PKI).

  • Operational note: Applying new TLS material may require a device reboot.

Supported vs. not supported (matrix)

Area

Supported

Not supported / Notes

Certificate containers

PEM(.pem, .crt, .cer), DER(.der)

PKCS#12/PFX uploads are not supported by the UI; export to PEM/DER first

Private keys

PKCS#8 (unencrypted), PKCS#1 (RSA, unencrypted)

Any encrypted key (no UI password)

Key algorithms

RSA-2048; ECDSA P-256, P-384, P-521

Ed25519 (EdDSA)

Chains

Leaf + intermediates in one file; omit root; up to 8 intermediates

Leaf marked CA:TRUE

TLS

TLS 1.2

TLS 1.3

Identity checks (client side)

SNI + SAN/CN + validity-time when Enhanced Security is ON

KU/EKU checks for client certs (not enforced by default)

Web-UI

HTTPS supported from v1.8.0+ (Gen3+); custom HTTPS certs (self-signed or private PKI); Clients must trust the issuing CA (install private CA or trust the device cert)

-

Supported File & Container Formats

  • PEM (.pem, .crt, .cer) - Supported and recommended.

  • DER (.der) - Supported (binary encoding of the same data).

  • PKCS#12/PFX (.p12, .pfx) - The device UI does not import PFX. Typical PFX uploads fail. Even unencrypted .p12 isn’t imported.

    Recommendation: Extract the key and certificates to unencrypted PEM and upload those.

Private Key Formats

  • PKCS#8 (unencrypted) - Supported and preferred.

  • PKCS#1 (RSA, unencrypted) - Supported.

  • Encrypted keys - Not supported (no password prompt in the UI).

Quick identifiers in PEM:

  • Unencrypted PKCS#8 -> -----BEGIN PRIVATE KEY-----

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

  • Encrypted key (not supported) -> -----BEGIN ENCRYPTED PRIVATE KEY-----

Supported Key Algorithms

  • RSA-2048 - Supported.

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

  • Ed25519 (EdDSA) - Not supported (Curve25519/X25519 may be present for ECDH, but not for signatures).

Tip: For new deployments, ECDSA P-256 offers smaller keys and faster handshakes on constrained devices.

Certificate Chains & Trust

  • Presented chain (the identity you upload to the device):

Upload one PEM file that contains the leaf certificate first, followed by any required intermediate CA certificates (concatenated PEM). Do not include the root CA.

Applies to: the client identity for mTLS (MQTT client cert) and the Web-UI HTTPS server certificate.

  • Who must trust what (trust stores)

When Shelly is a TLS client (e.g., connecting to your MQTT broker)
Upload your root CA (and any intermediates you want Shelly to trust) to Settings -> TLS Configuration -> Custom certificate authority (CA) PEM bundle. This is the device’s trust store used to verify servers. (No private keys here.)

When Shelly is a TLS server (Web-UI over HTTPS, Gen3+, v1.8.0+)
The browser/OS (the client) must trust the CA that issued the device’s Web-UI certificate.

  • Maximum chain depth: Up to 8 intermediates.

  • Basic Constraints (leaf): The leaf must not be a CA. A leaf with CA:TRUE is rejected. A leaf with CA:FALSE or without the BasicConstraints extension is accepted.

  • Custom HTTPS certificates (Web-UI, Gen3+, v1.8.0+):

You can install a custom HTTPS server certificate (self-signed or private PKI). Ensure client devices trust the issuing CA, otherwise the browser will warn. If you access by DNS name, include that FQDN in the SAN. If you access by IP, include the IP in the SAN as an IP entry.

  • Public CA: usually already trusted.

  • Private PKI: install your private root/intermediate CA only in the client(s) or application trust store that will access the Web-UI. Do not bundle the root in the device’s presented chain.

TLS Version & Verification Behavior

  • TLS versions: TLS 1.2 is supported. TLS 1.3 is not in current builds.

  • Server identity & time checks:

    • Sends SNI (Server Name Indication) for hostname-based endpoints.

    • Verifies hostname against certificate SAN/CN.

    • Verifies certificate validity period (date/time).

Where Certificates Are Used on Shelly

  • MQTT over TLS (server-auth) - Upload the CA certificate so Shelly can validate the broker certificate.

  • MQTT with client certificates (mTLS) - Additionally upload a client certificate and matching unencrypted private key; enable the client-cert option in MQTT settings.

  • Local Web-UI over HTTPS (from v1.8.0) - The device’s web interface supports HTTPS.

    • If you will access by DNS name (e.g., shelly-dev.example.lan), include that FQDN in the SAN of the Web-UI certificate you plan to trust/use.

    • If you access by IP address, the IP must be present in SAN as an IP entry (DNS names alone won’t satisfy browsers for IP access).

    • In managed environments, consider an internal CA trusted by your endpoints, or issue a cert via ACME DNS-01 for a private name.

    • Custom HTTPS certificate (self-signed or private PKI): Upload a server certificate and matching unencrypted private key for the Web-UI (labels may vary by model; see Settings -> TLS Configuration). Make sure client devices trust the issuing CA or the device cert.

Preparing Files (OpenSSL Cheatsheet)

Generate ECDSA P-256 key & CSR (recommended)

BASH 
# Private key (PKCS#8, unencrypted)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out device.key

# CSR (adjust subject)
openssl req -new -key device.key -out device.csr -subj "/CN=device.example.com"

Generate RSA-2048 key & CSR

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

Concatenate leaf + intermediates (PEM)

BASH 
# Leaf first, then intermediates; do NOT include the root
cat device.crt intermediate1.crt intermediate2.crt > device-chain.pem

Remove a passphrase (if your key is encrypted)

BASH 
# Outputs unencrypted PKCS#8
openssl pkey -in encrypted.key -out key-unencrypted.pem

Convert DER <-> PEM

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

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

Extract PEMs from PFX (avoid uploading .p12/.pfx)

BASH 
# Unencrypted private key
openssl pkcs12 -in bundle.p12 -nocerts -nodes -out key-unencrypted.pem

# Leaf + chain
openssl pkcs12 -in bundle.p12 -clcerts -nokeys -out device.crt
openssl pkcs12 -in bundle.p12 -nodes -nokeys -cacerts -out intermediates.pem

# Uploadable chain
cat device.crt intermediates.pem > device-chain.pem

Uploading Certificates (Web-UI)

  1. Open the WebUI -> Settings -> TLS Configuration.

  2. Upload the required files:

    • CA certificate (ca.crt) for server validation.

    • Client certificate (only if using mTLS).

    • Client private key (unencrypted; matches the client certificate).

    • (Gen3+, v1.8.0+) Web-UI server certificate (optional): upload the HTTPS server certificate and its matching unencrypted private key if you want a custom UI cert (self-signed or private PKI).

  3. Save each upload.

  4. Reboot when prompted, so changes take effect.

After upload, configure the specific service (e.g., Settings -> MQTT) to use TLS and, if needed, the client certificate.

Configuration Notes & Best Practices

  • SAN matters. Ensure the exact hostname or IP you connect to is present in the server certificate SAN; CN alone is not enough for modern clients.

  • Keep PEMs lean. Include only the necessary leaf + intermediates. Huge bundles can exceed embedded memory limits.

  • Avoid encrypted keys. There’s no UI path for passwords;

  • Don’t mark the leaf as CA. Reissue if BasicConstraints shows CA:TRUE.

  • SNI requires a hostname. Use a DNS name instead of a raw IP when possible for better compatibility.

Troubleshooting (Fast Fixes)

  • “Couldn’t parse key/cert.” Likely an encrypted key or PFX. Convert to unencrypted PEM and retry.

  • Hostname mismatch. Add the exact FQDN/IP you use to the certificate SAN.

  • Chain incomplete. Concatenate leaf + all intermediates in one PEM; omit the root.

  • Handshake time errors. Ensure device clock is correct (enable NTP).

  • Memory limits. If uploads fail intermittently, strip comments/extra certs and keep PEMs minimal.

Pre-Upload Checklist

  • Private key is unencrypted (PKCS#8 or PKCS#1) in PEM.

  • Certificate file contains leaf + intermediates (concatenated), no root.

  • Key type is RSA-2048 or ECDSA P-256/P-384/P-521 (not Ed25519).

  • Leaf is not a CA (CA:FALSE or no BasicConstraints).

  • SAN covers the exact FQDN/IP you’ll use.

  • Enhanced Security enabled for outbound TLS verification.

  • On v1.8.0+, plan to access the Web-UI over HTTPS.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close