Repository navigation
v2.2.0 (10/08/2026)
Release 2.2.0 has been developed according to wolfSSL's development and QA
process (see link below) and successfully passed the quality criteria.
https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance
-
New Features
- Automatic client keep-alive: the core client now sends a
PINGREQfrom
MqttClient_WaitMessage/MqttClient_WaitMessage_exonce the outbound
link has been idle for about three quarters of the negotiated keep-alive
interval, so the application no longer has to schedule pings itself and
the ping reaches the broker before the deadline. Active whenever a
non-zero keep-alive is set inCONNECT, and honors a v5 CONNACK Server
Keep Alive override. In a blocking build a keep-alive ping left
unanswered surfaces fromMqttClient_WaitMessageas
MQTT_CODE_ERROR_NETWORKrather than a timeout, so a dead link is
distinguishable from an idle one; underWOLFMQTT_NONBLOCKthe
application remains responsible for its own liveness deadline. Because the
ping round-trip runs inline usingcmd_timeout_ms, a
MqttClient_WaitMessagecall that starts a keep-alive can take up to
cmd_timeout_mslonger to return, so poll with atimeout_msshorter
than the keep-alive interval. The time source is the
compile-time macroWOLFMQTT_GET_TIME_S()(defaults totime(NULL),
overridable inuser_settings.h); defineWOLFMQTT_NO_TIMEto compile
the scheduler out on clock-less targets, where the explicit
MqttClient_PingAPIs still work. An application that already sends its
ownPINGREQcan disable the core scheduler at runtime - without changing
the negotiated keep-alive - by settingMQTT_CLIENT_FLAG_NO_AUTO_KEEPALIVE
withMqttClient_Flagsbefore connecting, avoiding duplicate pings. The
mqttclientexample now relies on the automatic ping, keeping its
previous manual keep-alive loop underWOLFMQTT_NO_TIME(#501)
- Automatic client keep-alive: the core client now sends a
-
API / Behavior Changes
- The broker now treats retaining a message as best-effort. When a
RETAIN=1PUBLISH cannot be stored (retained table full, oversized
payload, or allocation failure), the message is still delivered to all
current subscribers and acknowledged with success at every QoS and
protocol level; only the retained copy is skipped, and the skip is logged.
This matches Mosquitto and replaces the previous inconsistent handling
that could drop delivery on a retained-store failure. SeeBROKER.md. - The client rejects an inbound v5 PUBLISH that carries a Topic Alias and no
longer advertises a nonzero Topic Alias Maximum inCONNECT. Inbound
alias resolution is not implemented, so the client advertises Topic Alias
Maximum 0 and a server that sends an alias anyway is treated as a protocol
error. Outbound Topic Alias (client to server) is unchanged. An
application that supplies a nonzeroMQTT_PROP_TOPIC_ALIAS_MAXnow gets
MQTT_CODE_ERROR_PROPERTYfromMqttClient_Connect. - A v5
CONNECTnow advertisesReceive Maximumset to
MQTT_MAX_RECV_QOS2(16 by default) unless the application supplied its
ownMQTT_PROP_RECEIVE_MAX. This bounds the QoS 1 and QoS 2 PUBLISH
packets a conforming server may have in flight toward the client
[MQTT-3.3.4], keeping inbound QoS 2 within the client's de-duplication
table so a retransmitted PUBLISH cannot be delivered twice
[MQTT-4.3.3-10]. OverrideMQTT_MAX_RECV_QOS2inuser_settings.hto
trade memory for a larger window, or set the property explicitly to keep
full control. - In
WOLFMQTT_MULTITHREADbuilds, a QoS 2 PUBREC rejection processed by
the reading thread now also completes the originating
MqttClient_Publish_WriteOnlypending response with
MQTT_CODE_ERROR_PUBLISH_REJECTED, so the publisher's next poll returns
that error instead of spinning onMQTT_CODE_CONTINUEuntil
cmd_timeout_ms. This is the only v5 rejection surfaced on the write-only
path; a QoS 1 PUBACK or QoS 2 PUBCOMP reason code >= 0x80 is still not
detected there. Supersedes the v2.1.0 note below. - The client now tracks the MQTT handshake separately from the transport.
MqttClient_Publish,MqttClient_Subscribe,MqttClient_Unsubscribe,
MqttClient_PingandMqttClient_Disconnectreturn
MQTT_CODE_ERROR_STATwhen called beforeMqttClient_Connecton a
Network Connection [MQTT-3.1.0-1], and a secondMqttClient_Connecton
the same connection is refused with the same code [MQTT-3.1.0-2]. An
application that reconnects must callMqttClient_NetDisconnectfirst,
as the bundled examples already do (#590, #591) - The client keeps a connection-level record of outbound Packet
Identifiers still awaiting theirPUBACK,PUBCOMP,SUBACKor
UNSUBACK, in every build rather than only under
WOLFMQTT_MULTITHREAD. A newSUBSCRIBE,UNSUBSCRIBEor QoS>0
PUBLISHreusing one is refused withMQTT_CODE_ERROR_PACKET_ID
[MQTT-2.3.1-2]. Re-sending the samePUBLISHwithduplicateset keeps
its identifier, as [MQTT-2.3.1-3] requires. The window is
MQTT_MAX_SEND_INFLIGHT(16 by default), overridable in
user_settings.h(#589, #599, #601, #605, #611, #612, #613) MqttEncode_Connectrejects a zero-byte ClientId paired with
clean_session0 for MQTT v3.1.1 [MQTT-3.1.3-7]. MQTT v5.0 drops the
coupling and still allows it (#585)MqttConnectgainspassword_len. [MQTT-3.1.3.5] defines the Password
as Binary Data, which may contain 0x00, but the encoder measured it with
XSTRLENand truncated at the first one. Setpassword_lento send
binary password bytes verbatim; leaving it 0 keeps the previous
NUL-terminated behaviour, so existing callers are unaffected.
MqttDecode_Connectreports the wire length here, so a decode/re-encode
round trip no longer falls back toXSTRLENover a pointer into a
buffer that is not NUL terminated. The field is at the end of the
struct, so the offsets of the existing members are unchanged (#588)MqttMsgStatandMqttConnectgrew.MqttMsgStatis the first member
of every packet object, sosizeofchanges for all of them and an
application must be rebuilt against this header rather than relinked
against the library.MqttClientalso grows by the
MQTT_MAX_SEND_INFLIGHTidentifier table and, unless
WOLFMQTT_NO_SESSION_REPLAYis defined, theMQTT_MAX_REPLAY_MSGS
replay pool - about 1.3 KB underWOLFMQTT_STATIC_MEMORYat the
defaults, which matters most on the targets that use it.
- The broker now treats retaining a message as best-effort. When a
-
Fixes
- The v3.1.1
CONNACKdecoder accepted a Remaining Length above 2 and
swallowed the extra bytes; it now requires exactly 2 outside v5 (#603) PUBACK,PUBREC,PUBRELandPUBCOMPcarrying Packet Identifier 0
were treated as spurious and ignored. They are now rejected with
MQTT_CODE_ERROR_PACKET_ID, which closes the connection
[MQTT-4.8.0-1] (#607)- Broker: a refused
CONNACKwhose write returnedMQTT_CODE_CONTINUE
was never resumed, so the client saw a truncated packet and never
received the return code. The connection is now held open until the
refusal is fully written and then closed (#592) - Broker: keep-alive monitoring no longer runs while an accepted
CONNACK
is still partly written, which could close the connection mid-handshake
inWOLFMQTT_NONBLOCKbuilds. The handshake stays bounded by
BROKER_CONNECT_TIMEOUT_SEC(#594) - Broker: a QoS>0
PUBLISHthat got some bytes out and then failed inside
one blocking write is now marked for retransmission, so session recovery
replays it withDUPset [MQTT-3.3.1-1] (#604) - Broker: a partly written QoS 0
PUBLISHis dropped instead of following
the session into an orphan, where it was delivered a second time after
reconnect. QoS 0 allows no sender retry (#596). A transient
MQTT_CODE_ERROR_TIMEOUTno longer counts as such a failure: the entry
stays queued so the drain resumes from its offset instead of leaving a
truncated packet on the wire, and the drop happens at the orphan
hand-off - WebSocket: both receive callbacks now close the connection on a
non-binary data frame instead of feeding its payload to the MQTT parser
[MQTT-6.0.0-1] (#610) - Broker: static-memory fan-out now tracks the outbound QoS 1/2 Packet
Identifiers each subscriber has not yet acknowledged, so a new PUBLISH
cannot reuse one still awaiting its PUBACK or PUBCOMP [MQTT-2.3.1-4].
Dynamic-memory builds already derived this from the per-subscriber
queue. A delivery is skipped rather than sent with a reused identifier
when all BROKER_MAX_INFLIGHT_PER_SUB slots are outstanding (#614). The
slot is released when a delivery ends without an acknowledgement: an
encode or write failure, or a v5 subscriber rejecting the QoS 2 delivery
at the PUBREC stage [MQTT-4.3.3] - The client now keeps unacknowledged outbound QoS > 0 messages as Session
state and re-sends them after aCleanSession=0reconnect the server
answers with Session Present = 1: a PUBLISH goes out again with its
original Packet Identifier andDUPset, and a QoS 2 exchange already
past PUBREC re-sends the PUBREL instead [MQTT-4.4.0-1],
[MQTT-3.3.1-1]. Replaying a PUBLISH needs its topic and payload after
the caller'sMqttPublishis gone, so the client copies them into a
bounded pool ofMQTT_MAX_REPLAY_MSGSentries (4 by default; under
WOLFMQTT_STATIC_MEMORYalso bounded byMQTT_MAX_REPLAY_TOPICand
MQTT_MAX_REPLAY_PAYLOAD). A message that does not fit, or one streamed
through a payload callback, is still sent but not retained. Define
WOLFMQTT_NO_SESSION_REPLAYto compile the store out (#597, #598, #602) - A v5
PUBRECwith a reason code >= 0x80 ends the QoS 2 exchange
[MQTT-4.3.3], so the client now releases the Packet Identifier there
[MQTT-2.3.1-3] and drops the message from Session state instead of
replaying a PUBLISH the server explicitly refused - The QoS acknowledgement for a received PUBLISH is now staged on the wait
object rather than in a field shared by every reader. Another thread
completing its own read could previously overwrite it between the read
lock being dropped and the send lock being taken, sending the later
Packet Identifier twice and never the earlier one [MQTT-4.6.0-2] (#608) - Session state is keyed on the ClientId itself rather than a 32-bit hash
of it. Two different ClientIds sharing a hash would have let one
identity's replay entries and QoS 2 pending ids be treated as the
other's, which matters when the ClientId derives from untrusted input.
A ClientId longer thanMQTT_MAX_SESSION_CLIENT_ID(64 by default) is
not recorded, so its Session state is dropped rather than partially
matched [MQTT-3.1.3-2] MqttClient_Disconnectno longer clears the CONNECT-sent flag. It
writes the DISCONNECT packet but does not close the transport, so
clearing that flag reopened the duplicate-CONNECT guard and allowed a
second CONNECT on the same Network Connection [MQTT-3.1.0-2]. A separate
flag now refuses further packets after DISCONNECT [MQTT-3.14.4-1]MqttClient_CancelMessagekeeps the Packet Identifier of a packet that
already reached the wire. The peer can still answer it, and that
acknowledgement would otherwise complete whatever new exchange had taken
the identifier over; [MQTT-2.3.1-3] makes it reusable only once the
acknowledgement is processed. A packet that never fully went out still
releases its identifier immediately- Retained replay copies of topics and payloads are zeroized before being
freed, so application data - which may include credentials - is not left
in reusable heap - Outbound Session state is now bound to the ClientId that created it, so
a client object reused under a new ClientId no longer replays the
previous Session's messages into the new one when the server answers
Session Present = 1 [MQTT-3.1.3-2] - A zero-byte QoS 1/2 PUBLISH is retained for replay. Section 3.3.3 allows
an empty payload and [MQTT-4.4.0-1] asks for it back like any other
unacknowledged message; it was previously treated as a payload that
could not be copied - A v5 PUBLISH carrying properties is no longer retained for replay. The
pool stores no properties, so re-sending would strip Response Topic,
Correlation Data and the rest - a different message from the one the
server is waiting on. Retaining properties for replay is not implemented - A replay entry that can never be re-sent (no retained payload) is dropped
on reconnect instead of holding its Packet Identifier for the life of the
connection, since no acknowledgement will release it [MQTT-2.3.1-3] - The Packet Identifier reservation now records the acknowledgement that
ends its exchange, so a PUBACK naming a QoS 2 identifier cannot complete
it early [MQTT-2.3.1-3]. The reservation and its replay record are
released under one lock, closing a window where a publisher could reuse
the identifier in between and have the old ack delete the new exchange's
state - The replay record is created before the PUBLISH reaches the wire. In
WOLFMQTT_MULTITHREADbuilds a reader thread could otherwise process the
acknowledgement first, leaving an already-acknowledged message retained
and replayed after the next reconnect MqttClient_Publish,MqttClient_Subscribe,MqttClient_Unsubscribe
andMqttClient_Pingare refused afterMqttClient_Disconnect
[MQTT-3.14.4-1]- The duplicate-CONNECT guard reads the handshake flag under
lockClient
rather than throughMqttClient_Flags, which reports "no flags set" when
the lock cannot be taken and would have let a second CONNECT through
[MQTT-3.1.0-2] MqttClient_Connectnow resets the CONNACK wait state on the
MqttConnectobject it was given. Reusing one across reconnects - what
the bundled examples do - leftmc_connect->ackmid-read, so the second
handshake skipped the CONNACK read and handed whatever was still in
rx_bufto the PUBLISH payload handler instead of waiting for the new
CONNACK [MQTT-3.2.0-1]- The client's inbound QoS 2 de-duplication table is now bound to the
ClientId that populated it. Reusing oneMqttClientunder a new
ClientId no longer inherits the previous Session's pending packet ids
when the server answers Session Present = 1 [MQTT-3.1.3-2] (#595) WOLFMQTT_NO_STDIObuilds failed to compile because the default
WOLFMQTT_MALLOC/WOLFMQTT_FREEexpand tomalloc()/free()but
<stdlib.h>was only included alongside<stdio.h>. The header is now
included with the allocator defaults that need it, which also fixes
WOLFMQTT_CUSTOM_PRINTFports such as MPLAB Harmony, and a port that
supplies both macros no longer pulls it in for the allocator. The
defaultXATOIneedsatoifrom the same header, so it is included
with that macro too (#619)WOLFMQTT_CUSTOM_MALLOCwithoutWOLFMQTT_MALLOCandWOLFMQTT_FREE
now fails in the header with a message naming both macros, instead of an
implicit declaration reported from insidemqtt_client.c(#619)<string.h>is no longer pulled in forWOLFMQTT_CUSTOM_STRINGports.
It was previously included alongside<stdio.h>whatever the setting, so
such a port picked up the standard string declarations by accident; it
must now supply its own string macros and any headers those need (#619)WOLFMQTT_SESSION_ID_TRACKis derived fromWOLFMQTT_MAX_QOSand
WOLFMQTT_NO_SESSION_REPLAY, so a build that also defined it on the
command line hit a macro redefinition, fatal under-Werror. Such a
define is now discarded rather than redefining the macro (#619)WOLFMQTT_NO_STDIObroker builds failed to compile because the log
calls drop their arguments oncePRINTFis a no-op, leaving the log
string sanitizer with no callers.WOLFMQTT_NO_STDIOnow implies
WOLFMQTT_BROKER_NO_LOG, except whereWOLFMQTT_CUSTOM_PRINTFsupplies
a working sink (#619)
- The v3.1.1
-
What's Changed
- Low-severity hardening, encode/decode validation, credential/payload zeroization, and SN/example fixes (#560)
- Fenrir fixes (#559)
- Fenrir fixes (#561)
- Coverity fixes (#562)
- Add auto-ping feature to client (#563)
- Coverity and fenrir fixes (#564)
- Fix fenrir issues (#565)
- Fenrir fixes (#566)
- Serialize curl getinfo under lockCURL to fix multithread stress race (#568)
- Low-severity hardening and compliance fixes (#567)
- Harden CONNECT credential handling compliance (#572)
- Preserve nonblocking enhanced authentication state (#574)
- Preserve persistent sessions on WebSocket close (#573)
- Add contribution guidance (CONTRIBUTING.md) (#569)
- Preserve the static persistent session delivery (#570)
- Propagate persistence restore failures (#571)
- Fix broker session persistence and nonblocking CONTINUE handling (#575)
- Fenrir fixes: MQTT v5 client and broker (#576)
- Harden MQTT protocol validation and lifecycle handling (#577)
- Ensure expired messages have their records removed (#578)
- Reject AUTH, server-sent DISCONNECT and payload bytes in UNSUBACK below v5. Publish Will on write failure. (#583)
- MQTT compliance fixes for CONNECT ordering, Packet Identifier tracking, CONNACK, keepalive, and QoS replay (#615)
- Harden QoS delivery, persistent sessions, reauthentication, and MQTT SN sends (#579)
- Fix MQTT 5 property validation and QoS 2 state handling in broker and client (#618)
- Reject undersized MQTT-SN Length field in SN_Packet_Read (#621)
- Broker returns v5 UNSUBACK "No subscription existed" reason code when no filter matched (#617)
- Preserve resumed MQTT sessions and verify TLS broker identity (#623)
- Fix non-TLS builds and static analysis issues (#620)
-
New Contributors
- @ageprocpp made their first contribution (#617)