For ten years, wolfMQTT operated purely as a client library. With v2.0.0, we introduced its counterpart: a lightweight MQTT broker built on the same codebase, maintaining our strict footprint requirements and TLS stack. Over the last two releases, we’ve added core features needed to survive process restarts, along with fixes for edge cases that surface under heavy network load.
Persistence That Survives a Restart
With v2.1.0, we introduced pluggable persistence hooks via MqttBroker_SetPersistHooks, including an out-of-the-box POSIX backend (MqttBrokerNet_PersistPosix_Init and MqttBrokerNet_PersistPosix_Free). You can point these hooks at whatever storage your target provides (such as internal flash or an external key-value store) allowing sessions, retained messages, and queued deliveries to persist across restarts.
We also added message ordering guarantees and an offline message queue. When a subscriber reconnects with CleanSession=0, it seamlessly catches up on missed messages without dropping data.
AES-GCM Encryption at Rest
Because persisted broker state includes retained payloads, queued messages, and session metadata, sensitive application data ends up stored locally. To protect this data, especially on edge devices and gateways in physically exposed locations, the broker encrypts state at rest using AES-GCM powered by wolfCrypt.
Authentication That Fails Closed
We recently resolved an important authentication edge case. Previously, setting only one credential (such as passing the -u CLI flag without -P) silently enabled single-factor authentication. Because the missing field wasn’t validated, any password was accepted for a valid username, or any username for a valid password.
MqttBroker_Start now rejects incomplete credential setups with MQTT_CODE_ERROR_BAD_ARG, and the connection handler fails closed as a safeguard. Leaving both credentials set to NULL still disables authentication, keeping unauthenticated operation an explicit, intentional choice.
Reliability Work on Master
Recent updates on master address handling partial writes; specifically scenarios where the broker sends a partial packet before the socket blocks or fails:
- Refused CONNACK packets that returned MQTT_CODE_CONTINUE were previously dropped mid-write, leaving clients with truncated packets. The connection now remains open until the response is fully written before closing.
- Keep-alive timers now pause while sending an accepted CONNACK to prevent prematurely closing connections mid-handshake in WOLFMQTT_NONBLOCK builds. Handshake duration remains properly bounded by BROKER_CONNECT_TIMEOUT_SEC.
- If a QoS > 0 PUBLISH write fails mid-transmission, it is flagged for retransmission so session recovery re-sends it with the DUP flag set [MQTT-3.3.1-1].
- Partially written QoS 0 PUBLISH messages are now discarded rather than re-queued on reconnection, complying with the MQTT rule against QoS 0 retries. Transient timeouts (MQTT_CODE_ERROR_TIMEOUT) no longer trigger an unexpected drop.
- Static-memory builds now track unacknowledged QoS 1/2 Packet Identifiers per subscriber, preventing new PUBLISH messages from reusing in-flight identifiers [MQTT-2.3.1-4]. If all BROKER_MAX_INFLIGHT_PER_SUB slots are active, further delivery is paused rather than reusing an active identifier.
Also Worth Knowing
The broker supports concurrent secure and plain-text connections, MQTT over WebSockets, retained messages, and graceful disconnects. For embedded targets lacking a standard TCP/IP stack, it runs directly on wolfIP. Continuous integration testing includes libFuzzer-based fuzzing, AddressSanitizer, and builds across multiple compiler toolchains.
Get It
Check out the project on GitHub or download the latest release from the download page. You can find the broker source code in src/mqtt_broker.c and usage examples in the examples/ directory.
If you have questions about deploying wolfMQTT on your platform, reach out to us at facts@wolfssl.com or call +1 425 245 8247.
Download wolfSSL Now