ESP32 MQTT TLS: Production Setup Checklist

ESP32 MQTT TLS is the combination of MQTT's publish and subscribe workflow with a verified, encrypted connection from the device to a broker. ESP-IDF's MQTT documentation shows TLS examples using mqtts and the certificate bundle, while ESP-TLS handles certificate validation, SNI and related connection options. Starting with a working example is useful, but production needs explicit evidence for each trust and recovery decision. Source Source

This checklist is for product teams moving from a demo broker to devices that must keep state and credentials safe after deployment. It is our synthesis of Espressif, MQTT and AWS documentation, not a claim that Codesprint has operated a particular device fleet.

Verify the broker, not only the port

An mqtts:// URI and port 8883 do not prove that the device is talking to the intended broker. ESP-TLS supports server verification through a CA certificate buffer, a global CA store, a certificate bundle or pre-shared keys. Its current documentation says that if no verification option is selected, the client returns a fatal error during setup. Treat a successful connection as evidence only after checking which verification path was actually configured. Source

ESP-TLS also documents an insecure test path that skips server verification. It warns that this can connect to a server with a fake identity unless the certificate is supplied through another mechanism. Our release rule is simple: never leave skip-verification enabled to preserve a deadline, and check both firmware configuration and any build-time overrides before shipping. Source

For cloud brokers, confirm endpoint-specific rules rather than assuming every TLS endpoint behaves the same way. AWS IoT Core lists MQTT with X.509 client-certificate authentication on port 8883, and port 443 only with the required ALPN protocol name. AWS also requires SNI for clients that do not use its SDKs. Another broker may use different rules, so record the tested endpoint, port, SNI and ALPN behavior together. Source Source

Choose the right root certificate strategy

The ESP x509 Certificate Bundle embeds root certificates for server verification. ESP-IDF can include the full Mozilla-derived list or a smaller filtered set, and custom certificates can be added. The certificate bundle is embedded in the application, so ESP-IDF says it is updated with an application OTA update. That makes certificate maintenance part of the firmware lifecycle, not a one-time build decision. Source

For a private broker or enterprise CA, our recommendation is usually to trust the narrow CA chain needed by that service rather than a broad public bundle. Keep the certificate source, expiry, owner and replacement procedure with the product's security records. Test normal expiry and an emergency CA replacement before devices are distributed.

For a public cloud endpoint, document why the selected bundle entry is sufficient. Our checklist includes a test that fails when the broker presents an unrelated valid certificate and another test after rotating the endpoint's certificate chain. A connection that succeeds with any public certificate may be encrypted, but it is not providing the broker identity assurance the product intended.

Keep hostname checking and SNI intact

TLS hostname validation and SNI are easy to weaken accidentally while debugging. ESP-TLS says skip_common_name disables both hostname matching against the certificate and SNI, and it must be false for SNI to work correctly. It also documents common_name behavior: a supplied name must match the certificate, while a null value causes the certificate to be checked against the hostname. Source

Our recommendation is to test the configured DNS name, certificate SAN or CN and SNI as one unit. Do not compensate for a DNS or certificate mismatch by disabling hostname checking. If a manufacturing test server uses a different name, give it a correctly issued test certificate instead of teaching production firmware to ignore identity.

SNI can also be a broker feature, not just a certificate detail. AWS notes that SNI is needed for capabilities such as multi-account registration, custom domains, VPC endpoints and configured TLS policies. It says connections without SNI can be refused when clients do not use the AWS SDK. Verify this with the real endpoint family you deploy. AWS IoT transport security Source

Decide how the device itself authenticates

Server verification tells the device which broker it reached. Mutual TLS adds client credentials so the broker can identify the device. AWS IoT Core, for example, uses X.509 client certificates to authenticate devices over secure MQTT. ESP-TLS configuration supports client certificates and private keys, including a unified client_key path that can reference a PSA key. AWS IoT transport security Source

Our manufacturing checklist ties each client credential to a device identity and an owner. Generate or inject keys through a controlled process, record which certificate belongs to each unit and test revocation of one device without affecting the fleet. Do not reuse one private key across products because it makes initial provisioning simpler.

Where hardware support is available, evaluate protected key storage. ESP-TLS documents ATECC608A support through a PSA opaque driver with MbedTLS. If private keys remain in firmware or storage, review that protection separately from transport encryption. Our ESP32 flash encryption and secure boot guide covers that foundation, and ESP32 secure provisioning covers the setup flow. Source

Separate TLS, MQTT and application authorization

TLS protects the connection, while MQTT still needs topic and message rules. The MQTT specification says implementations should offer authentication, authorization and secure communication options, and it particularly advises those capabilities for sensitive applications. Do not let "the connection is encrypted" stand in for deciding which device can publish telemetry, receive commands or subscribe to another tenant's topic. Source

Our authorization review names each topic family, the device roles allowed to publish or subscribe and the backend service that consumes the data. Keep command topics separate from telemetry and status topics. Test a valid device certificate against a forbidden topic; TLS success should not turn into application access by accident.

Also decide what payload validation happens after the broker. A device can be authenticated and still send malformed data because of a firmware bug. Our recommendation is to validate schema, units, ranges and sequence information before a message triggers an irreversible action. This is application design, not something MQTT TLS proves on its own.

Design the offline state before testing reconnects

A successful first connection says little about intermittent power or radio coverage. AWS describes persistent sessions that restore subscriptions and stored QoS 1 messages when the same client reconnects. In MQTT 3, this is controlled with cleanSession; in MQTT 5, Clean Start and Session Expiry Interval control the behavior. AWS also documents that persistent sessions expire and that stored messages are discarded after expiration. Source

Our device-state checklist records what must survive a reboot: subscriptions, unsent measurements, command acknowledgements and the last reported state. Decide whether the broker session, local storage or an application-level retry owns each item. A persistent session can help delivery, but it does not automatically make a device command safe to repeat.

Test expired sessions as well as short disconnects. Our recommendation is to reconnect after the session lifetime has passed and confirm the device resubscribes and recovers state correctly. Avoid treating "connected" as proof that the current subscriptions and queued messages match the intended state.

Make Last Will useful but not authoritative

MQTT Last Will lets a client register a message that the broker publishes after an uninitiated disconnection. AWS notes that a client-initiated DISCONNECT does not publish the stored LWT, and that asynchronous disconnect processing means LWT messages are not guaranteed to arrive in order during reconnection. AWS recommends lifecycle events with timestamps and version numbers for more accurate connectivity state. Source

Our recommendation is to treat LWT as a signal, not as the only record of device health. Include a device identity and a monotonically increasing sequence or timestamp where the broker and policy allow it. Decide how long a missed update means degraded state, and make the dashboard distinguish a clean shutdown from a lost network path.

Avoid putting secrets, precise user activity or unrecoverable commands in a Will Message. It is a publication to subscribers, not a private alert channel. Test clean disconnect, power loss, broker restart and a rapid reconnect before relying on the resulting status.

Plan certificate and firmware updates together

Because the ESP certificate bundle is embedded and updated through OTA, a certificate migration can become a fleet availability issue. ESP-IDF's certificate-bundle documentation says a newer bundle can be included when the application is updated. Our release plan should stage broker and firmware changes so devices always have a trusted chain during the transition. Source

Our recommendation is to run old and new chains in a test environment, then migrate a small device group before broad rollout. Keep rollback and recovery images available. For that side of the lifecycle, use our ESP32 OTA rollback guide.

Test TLS 1.2 and TLS 1.3 only against the stack and broker you actually deploy. ESP-TLS can select a protocol version, while AWS IoT Core supports TLS 1.2 and TLS 1.3 through predefined security policies rather than custom policies. A cipher or session-resumption example from another stack is not evidence for your firmware. ESP-TLS documentation AWS IoT transport security

Run a failure matrix before release

Our minimum production matrix includes an expired broker certificate, a wrong hostname, a revoked client certificate, a blocked port, an empty certificate bundle, power loss during handshake and repeated reconnects on weak radio. Confirm that each failure closes the connection and leaves useful diagnostics without logging private keys or certificate-bearing payloads.

Then test application behavior after the failure. Telemetry should not be acknowledged before the intended delivery rule is met, commands should not execute twice, and stale retained messages should not override newer local state. Record firmware, ESP-IDF, MQTT component, broker and certificate-chain versions with the results.

If you are connecting an ESP32 product to a cloud backend, Codesprint can help review the firmware, broker rules and recovery plan together. Contact us when you need that review before devices leave the lab.