mqtt-v3 1 1-Os

1
MQTT Version 3.1.1
3OASIS
429
Standard
October 2014
5Specification URIs
6This version:
7
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.doc (Authoritative)
8
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html
9
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.pdf
10Previous version:
11
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/cos01/mqtt-v3.1.1-cos01.doc (Authoritative)
12
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/cos01/mqtt-v3.1.1-cos01.html
13
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/cos01/mqtt-v3.1.1-cos01.pdf
14Latest version:
15
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.doc (Authoritative)
16
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
17
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.pdf
18Technical Committee:
19
OASIS Message Queuing Telemetry Transport (MQTT) TC
20Chairs:
21
Raphael J Cohn ([email protected]), Individual
22
Richard J Coppen ([email protected]), IBM
23Editors:
24
Andrew Banks ([email protected]), IBM
25
Rahul Gupta ([email protected]), IBM
26Related work:
27
This specification is related to:
28
29
30
MQTT and the NIST Cybersecurity Framework Version 1.0. Edited by Geoff Brown and
Louis-Philippe Lamoureux. Latest version: http://docs.oasis-open.org/mqtt/mqtt-nistcybersecurity/v1.0/mqtt-nist-cybersecurity-v1.0.html.
31Abstract:
32
MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open,
33
simple, and designed so as to be easy to implement. These characteristics make it ideal for use
34
in many situations, including constrained environments such as for communication in Machine to
35
Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required
36
and/or network bandwidth is at a premium.
37
38
39
The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless, bidirectional connections. Its features include:
Use of the publish/subscribe message pattern which provides one-to-many message

distribution and decoupling of applications.
A messaging transport that is agnostic to the content of the payload.
Three qualities of service for message delivery:
40
41
42
1mqtt-v3.1.1-os
2Standards Track Work Product
Copyright OASIS Open 2014. All Rights Reserved.
29 October 2014
Page 1 of 80
43
"At most once", where messages are delivered according to the best efforts of the
operating environment. Message loss can occur. This level could be used, for
example, with ambient sensor data where it does not matter if an individual reading is
lost as the next one will be published soon after.
"At least once", where messages are assured to arrive but duplicates can occur.
"Exactly once", where message are assured to arrive exactly once. This level could
be used, for example, with billing systems where duplicate or lost messages could
lead to incorrect charges being applied.
44
45
46
47
48
49
50
51
52
A small transport overhead and protocol exchanges minimized to reduce network traffic.
A mechanism to notify interested parties when an abnormal disconnection occurs.
53Status:
54
This document was last revised or approved by the membership of OASIS on the above date.
55
The level of approval is also listed above. Check the Latest version location noted above for
56
possible later revisions of this document. Any other numbered Versions and other technical work
57
produced by the Technical Committee (TC) are listed at https://www.oasis58
open.org/committees/tc_home.php?wg_abbrev=mqtt#technical.
59
60
61
62
TC members should send comments on this specification to the TCs email list. Others should
send comments to the TCs public comment list, after subscribing to it by following the instructions
at the Send A Comment button on the TCs web page at https://www.oasisopen.org/committees/mqtt/.
63
64
65
66
For information on whether any patents have been disclosed that may be essential to
implementing this specification, and any offers of patent licensing terms, please refer to the
Intellectual Property Rights section of the Technical Committee web page (https://www.oasisopen.org/committees/mqtt/ipr.php).
67Citation format:
68
When referencing this specification the following citation format should be used:
69
[mqtt-v3.1.1]
70
71
72
MQTT Version 3.1.1. Edited by Andrew Banks and Rahul Gupta. 29 October 2014. OASIS
Standard. http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html. Latest version:
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html.
73
3mqtt-v3.1.1-os
29 October 2014
Page 2 of 80
74Notices
75Copyright OASIS Open 2014. All Rights Reserved.
76All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual
77Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
78This document and translations of it may be copied and furnished to others, and derivative works that
79comment on or otherwise explain it or assist in its implementation may be prepared, copied, published,
80and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice
81and this section are included on all such copies and derivative works. However, this document itself may
82not be modified in any way, including by removing the copyright notice or references to OASIS, except as
83needed for the purpose of developing any document or deliverable produced by an OASIS Technical
84Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be
85followed) or as required to translate it into languages other than English.
86The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors
87or assigns.
88This document and the information contained herein is provided on an "AS IS" basis and OASIS
89DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
90WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
91OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
92PARTICULAR PURPOSE.
93OASIS requests that any OASIS Party or any other party that believes it has patent claims that would
94necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard,
95to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to
96such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that
97produced this specification.
98OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of
99any patent claims that would necessarily be infringed by implementations of this specification by a patent
100holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR
101Mode of the OASIS Technical Committee that produced this specification. OASIS may include such
102claims on its website, but disclaims any obligation to do so.
103OASIS takes no position regarding the validity or scope of any intellectual property or other rights that
104might be claimed to pertain to the implementation or use of the technology described in this document or
105the extent to which any license under such rights might or might not be available; neither does it represent
106that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to
107rights in any document or deliverable produced by an OASIS Technical Committee can be found on the
108OASIS website. Copies of claims of rights made available for publication and any assurances of licenses
109to be made available, or the result of an attempt made to obtain a general license or permission for the
110use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS
111Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any
112information or list of intellectual property rights will at any time be complete, or that any claims in such list
113are, in fact, Essential Claims.
114The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be
115used only to refer to the organization and its official outputs. OASIS welcomes reference to, and
116implementation and use of, specifications, while reserving the right to enforce its marks against
117misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above
118guidance.
119
5mqtt-v3.1.1-os
29 October 2014
Page 3 of 80
120Table
1211
122
123
124
125
126
127
128
129
130
1312
132
133
134
135
136
137
138
139
1403
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
of Contents
Introduction......................................................................................................................................... 9
1.1 Organization of MQTT....................................................................................................................... 9
1.2 Terminology....................................................................................................................................... 9
1.3 Normative references...................................................................................................................... 10
1.4 Non normative references............................................................................................................... 11
1.5 Data representations....................................................................................................................... 13
1.5.1 Bits........................................................................................................................................... 13
1.5.2 Integer data values................................................................................................................... 13
1.5.3 UTF-8 encoded strings............................................................................................................. 13
1.6 Editing conventions......................................................................................................................... 15
MQTT Control Packet format............................................................................................................ 16
2.1 Structure of an MQTT Control Packet............................................................................................. 16
2.2 Fixed header................................................................................................................................... 16
2.2.1 MQTT Control Packet type....................................................................................................... 16
2.2.2 Flags........................................................................................................................................ 17
2.2.3 Remaining Length.................................................................................................................... 18
2.3 Variable header............................................................................................................................... 19
2.3.1 Packet Identifier....................................................................................................................... 20
2.4 Payload........................................................................................................................................... 21
MQTT Control Packets...................................................................................................................... 23
3.1 CONNECT Client requests a connection to a Server...................................................................23
3.1.1 Fixed header............................................................................................................................ 23
3.1.2 Variable header........................................................................................................................ 23
3.1.3 Payload.................................................................................................................................... 29
3.1.4 Response................................................................................................................................. 30
3.2 CONNACK Acknowledge connection request..............................................................................31
3.2.1 Fixed header............................................................................................................................ 31
3.2.2 Variable header........................................................................................................................ 31
3.2.3 Payload.................................................................................................................................... 33
3.3 PUBLISH Publish message.......................................................................................................... 33
3.3.1 Fixed header............................................................................................................................ 33
3.3.2 Variable header........................................................................................................................ 35
3.3.3 Payload.................................................................................................................................... 36
3.3.4 Response................................................................................................................................. 36
3.3.5 Actions..................................................................................................................................... 36
3.4 PUBACK Publish acknowledgement............................................................................................37
3.4.1 Fixed header............................................................................................................................ 37
3.4.2 Variable header........................................................................................................................ 37
3.4.3 Payload.................................................................................................................................... 37
3.4.4 Actions..................................................................................................................................... 37
3.5 PUBREC Publish received (QoS 2 publish received, part 1)........................................................37
3.5.1 Fixed header............................................................................................................................ 38
3.5.2 Variable header........................................................................................................................ 38
7mqtt-v3.1.1-os
29 October 2014
Page 4 of 80
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
2084
3.5.3 Payload.................................................................................................................................... 38
3.5.4 Actions..................................................................................................................................... 38
3.6 PUBREL Publish release (QoS 2 publish received, part 2)..........................................................38
3.6.1 Fixed header............................................................................................................................ 38
3.6.2 Variable header........................................................................................................................ 39
3.6.3 Payload.................................................................................................................................... 39
3.6.4 Actions..................................................................................................................................... 39
3.7 PUBCOMP Publish complete (QoS 2 publish received, part 3)....................................................39
3.7.1 Fixed header............................................................................................................................ 39
3.7.2 Variable header........................................................................................................................ 40
3.7.3 Payload.................................................................................................................................... 40
3.7.4 Actions..................................................................................................................................... 40
3.8 SUBSCRIBE - Subscribe to topics.................................................................................................. 40
3.8.1 Fixed header............................................................................................................................ 40
3.8.2 Variable header........................................................................................................................ 40
3.8.3 Payload.................................................................................................................................... 41
3.8.4 Response................................................................................................................................. 42
3.9 SUBACK Subscribe acknowledgement........................................................................................ 43
3.9.1 Fixed header............................................................................................................................ 44
3.9.2 Variable header........................................................................................................................ 44
3.9.3 Payload.................................................................................................................................... 44
3.10 UNSUBSCRIBE Unsubscribe from topics..................................................................................45
3.10.1 Fixed header.......................................................................................................................... 45
3.10.2 Variable header...................................................................................................................... 45
3.10.3 Payload.................................................................................................................................. 46
3.10.4 Response............................................................................................................................... 46
3.11 UNSUBACK Unsubscribe acknowledgement.............................................................................47
3.11.1 Fixed header.......................................................................................................................... 47
3.11.2 Variable header...................................................................................................................... 47
3.11.3 Payload.................................................................................................................................. 48
3.12 PINGREQ PING request............................................................................................................ 48
3.12.1 Fixed header.......................................................................................................................... 48
3.12.2 Variable header...................................................................................................................... 48
3.12.3 Payload.................................................................................................................................. 48
3.12.4 Response............................................................................................................................... 48
3.13 PINGRESP PING response........................................................................................................ 48
3.13.1 Fixed header.......................................................................................................................... 48
3.13.2 Variable header...................................................................................................................... 49
3.13.3 Payload.................................................................................................................................. 49
3.14 DISCONNECT Disconnect notification.......................................................................................49
3.14.1 Fixed header.......................................................................................................................... 49
3.14.2 Variable header...................................................................................................................... 49
3.14.3 Payload.................................................................................................................................. 49
3.14.4 Response............................................................................................................................... 49
Operational behavior......................................................................................................................... 51
9mqtt-v3.1.1-os
29 October 2014
Page 5 of 80
209 4.1 Storing state.................................................................................................................................... 51

210
4.1.1 Non normative example........................................................................................................... 51
211 4.2 Network Connections...................................................................................................................... 52
212 4.3 Quality of Service levels and protocol flows....................................................................................52
213
4.3.1 QoS 0: At most once delivery................................................................................................... 52
214
4.3.2 QoS 1: At least once delivery................................................................................................... 53
215
4.3.3 QoS 2: Exactly once delivery................................................................................................... 54
216 4.4 Message delivery retry.................................................................................................................... 55
217 4.5 Message receipt.............................................................................................................................. 56
218 4.6 Message ordering............................................................................................................................ 56
219 4.7 Topic Names and Topic Filters......................................................................................................... 57
220
4.7.1 Topic wildcards......................................................................................................................... 57
221
4.7.2 Topics beginning with $............................................................................................................ 58
222
4.7.3 Topic semantic and usage........................................................................................................ 58
223 4.8 Handling errors................................................................................................................................ 59
2245
Security............................................................................................................................................. 60
225 5.1 Introduction...................................................................................................................................... 60
226 5.2 MQTT solutions: security and certification.......................................................................................60
227 5.3 Lightweight cryptography and constrained devices.........................................................................61
228 5.4 Implementation notes...................................................................................................................... 61
229
5.4.1 Authentication of Clients by the Server....................................................................................61
230
5.4.2 Authorization of Clients by the Server......................................................................................61
231
5.4.3 Authentication of the Server by the Client................................................................................61
232
5.4.4 Integrity of Application Messages and Control Packets............................................................62
233
5.4.5 Privacy of Application Messages and Control Packets.............................................................62
234
5.4.6 Non-repudiation of message transmission...............................................................................62
235
5.4.7 Detecting compromise of Clients and Servers.........................................................................62
236
5.4.8 Detecting abnormal behaviors.................................................................................................. 63
237
5.4.9 Other security considerations................................................................................................... 63
238
5.4.10 Use of SOCKS....................................................................................................................... 64
239
5.4.11 Security profiles...................................................................................................................... 64
2406
Using WebSocket as a network transport.........................................................................................65
241 6.1 IANA Considerations....................................................................................................................... 65
2427
Conformance.................................................................................................................................... 66
243 7.1 Conformance Targets...................................................................................................................... 66
244
7.1.1 MQTT Server........................................................................................................................... 66
245
7.1.2 MQTT Client............................................................................................................................. 66
246Appendix A.
Acknowledgements (non normative)...............................................................................68
247Appendix B.
Mandatory normative statements (non normative)...........................................................70
248Appendix C.
Revision history (non normative).....................................................................................80
249
11mqtt-v3.1.1-os
29 October 2014
Page 6 of 80
250Table
of Figures and Tables
251Figure 1.1 Structure of UTF-8 encoded strings.............................................................................................................13

252Figure 1.2 UTF-8 encoded string non normative example..14
253Figure 2.1 Structure of an MQTT Control Packet.......................................................................................................16
254Figure 2.2 - Fixed header format................................................................................................................................... 16
255Table 2.1 - Control packet types.................................................................................................................................... 16
256Table 2.2 - Flag Bits....................................................................................................................................................... 17
257Table 2.4 Size of Remaining Length field......................................................................................................................18
258Figure 2.3 - Packet Identifier bytes................................................................................................................................ 20
259Table 2.5 - Control Packets that contain a Packet Identifier..........................................................................................20
260Table 2.6 - Control Packets that contain a Payload.......................................................................................................21
261Figure 3.1 CONNECT Packet fixed header................................................................................................................23
262Figure 3.2 - Protocol Name bytes.................................................................................................................................. 23
263Figure 3.3 - Protocol Level byte.................................................................................................................................... 24
264Figure 3.4 - Connect Flag bits....................................................................................................................................... 24
265Figure 3.5 Keep Alive bytes........................................................................................................................................... 27
266Figure 3.6 - Variable header non normative example...................................................................................................28
267Figure 3.7 - Password bytes.......................................................................................................................................... 30
268Figure 3.8 CONNACK Packet fixed header............................................................................................................... 31
269Figure 3.9 CONNACK Packet variable header..........................................................................................................31
270Table 3.1 Connect Return code values......................................................................................................................32
271Figure 3.10 PUBLISH Packet fixed header................................................................................................................33
272Table 3.2 - QoS definitions............................................................................................................................................ 34
273Table 3.3 - Publish Packet non normative example......................................................................................................35
274Figure 3.11 - Publish Packet variable header non normative example.........................................................................35
275Table 3.4 - Expected Publish Packet response.............................................................................................................36
276Figure 3.12 - PUBACK Packet fixed header................................................................................................................. 37
277Figure 3.13 PUBACK Packet variable header............................................................................................................37
278Figure 3.14 PUBREC Packet fixed header................................................................................................................ 38
279Figure 3.15 PUBREC Packet variable header...........................................................................................................38
280Figure 3.16 PUBREL Packet fixed header................................................................................................................. 38
281Figure 3.17 PUBREL Packet variable header............................................................................................................39
282Figure 3.18 PUBCOMP Packet fixed header.............................................................................................................39
283Figure 3.19 PUBCOMP Packet variable header........................................................................................................40
284Figure 3.20 SUBSCRIBE Packet fixed header...........................................................................................................40
285Figure 3.21 - Variable header with a Packet Identifier of 10, Non normative example..................................................41
286Figure 3.22 SUBSCRIBE Packet payload format.......................................................................................................41
287Table 3.5 - Payload non normative example................................................................................................................. 42
288Figure 3.23 - Payload byte format non normative example...........................................................................................42
289Figure 3.24 SUBACK Packet fixed header.................................................................................................................44
290Figure 3.25 SUBACK Packet variable header............................................................................................................44
291Figure 3.26 SUBACK Packet payload format.............................................................................................................44
292Table 3.6 - Payload non normative example................................................................................................................. 45
294Figure 3.28 UNSUBSCRIBE Packet Fixed header....................................................................................................45
295Figure 3.29 UNSUBSCRIBE Packet variable header................................................................................................45
296Table3.7 - Payload non normative example.................................................................................................................. 46
13mqtt-v3.1.1-os
29 October 2014
Page 7 of 80
298Figure 3.31 UNSUBACK Packet fixed header...........................................................................................................47

299Figure 3.32 UNSUBACK Packet variable header......................................................................................................47
300Figure 3.33 PINGREQ Packet fixed header...............................................................................................................48
301Figure 3.34 PINGRESP Packet fixed header.............................................................................................................48
302Figure 3.35 DISCONNECT Packet fixed header........................................................................................................49
303Figure 4.1 QoS 0 protocol flow diagram, non normative example.............................................................................52
306Figure 6.1 - IANA WebSocket Identifier.........................................................................................................................65
307
308
15mqtt-v3.1.1-os
29 October 2014
Page 8 of 80
3091
Introduction
3101.1 Organization of MQTT

311This specification is split into seven chapters:
312
Chapter 1 - Introduction
313
Chapter 2 - MQTT Control Packet format
314
Chapter 3 - MQTT Control Packets
315
Chapter 4 - Operational behavior
316
Chapter 5 - Security
317
Chapter 6 - Using WebSocket as a network transport
318
Chapter 7 - Conformance Targets
3191.2 Terminology
320The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
321NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as
322described in IETF RFC 2119 [RFC2119].
323Network Connection:
324A construct provided by the underlying transport protocol that is being used by MQTT.
325
It connects the Client to the Server.
326
It provides the means to send an ordered, lossless, stream of bytes in both directions.
327For examples see Section 4.2.
328Application Message:
329The data carried by the MQTT protocol across the network for the application. When
330Application Messages are transported by MQTT they have an associated Quality of Service
331and a Topic Name.
332Client:
333A program or device that uses MQTT. A Client always establishes the Network Connection to the Server.
334It can
335
336
Publish Application Messages that other Clients might be interested in.

Subscribe to request Application Messages that it is interested in receiving.
337
Unsubscribe to remove a request for Application Messages.
338
Disconnect from the Server.
17mqtt-v3.1.1-os
29 October 2014
Page 9 of 80
339Server:
340A program or device that acts as an intermediary between Clients which publish Application Messages
341and Clients which have made Subscriptions. A Server
342
343
Accepts Network Connections from Clients.

Accepts Application Messages published by Clients.
344
Processes Subscribe and Unsubscribe requests from Clients.
345
Forwards Application Messages that match Client Subscriptions.
346Subscription:
347A Subscription comprises a Topic Filter and a maximum QoS. A Subscription is associated with a single
348Session. A Session can contain more than one Subscription. Each Subscription within a session has a
349different Topic Filter.
350Topic Name:
351The label attached to an Application Message which is matched against the Subscriptions known to the
352Server. The Server sends a copy of the Application Message to each Client that has a matching
353Subscription.
354Topic Filter:
355An expression contained in a Subscription, to indicate an interest in one or more topics. A Topic Filter can
356include wildcard characters.
357Session:
358A stateful interaction between a Client and a Server. Some Sessions last only as long as the Network
359Connection, others can span multiple consecutive Network Connections between a Client and a Server.
360MQTT Control Packet:
361A packet of information that is sent across the Network Connection. The MQTT specification defines
362fourteen different types of Control Packet, one of which (the PUBLISH packet) is used to convey
363Application Messages.
3641.3 Normative references

365[RFC2119]
366Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March
3671997.
368http://www.ietf.org/rfc/rfc2119.txt
369
370[RFC3629]
371Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003
373
374[RFC5246]
375Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August
3762008.
378
379[RFC6455]
19mqtt-v3.1.1-os
29 October 2014
Page 10 of 80
380Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, December 2011.
382
383[Unicode]
384The Unicode Consortium. The Unicode Standard.
385http://www.unicode.org/versions/latest/
3861.4 Non normative references

387[RFC793]
388Postel, J. Transmission Control Protocol. STD 7, IETF RFC 793, September 1981.
390
391[AES]
392Advanced Encryption Standard (AES) (FIPS PUB 197).
393http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
394
395[DES]
396Data Encryption Standard (DES).
397http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf
398
399[FIPS1402]
400Security Requirements for Cryptographic Modules (FIPS PUB 140-2)
401http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf
402
403[IEEE 802.1AR]
404IEEE Standard for Local and metropolitan area networks - Secure Device Identity
405http://standards.ieee.org/findstds/standard/802.1AR-2009.html
406
407[ISO29192]
408ISO/IEC 29192-1:2012 Information technology -- Security techniques -- Lightweight cryptography -- Part
4091: General
410http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=56425
411
412[MQTT NIST]
413MQTT supplemental publication, MQTT and the NIST Framework for Improving Critical Infrastructure
414Cybersecurity
415http://docs.oasis-open.org/mqtt/mqtt-nist-cybersecurity/v1.0/mqtt-nist-cybersecurity-v1.0.html
416
417[MQTTV31]
418MQTT V3.1 Protocol Specification.
419http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html
420
421[NISTCSF]
422Improving Critical Infrastructure Cybersecurity Executive Order 13636
423http://www.nist.gov/itl/upload/preliminary-cybersecurity-framework.pdf
424
425[NIST7628]
21mqtt-v3.1.1-os
29 October 2014
Page 11 of 80
426NISTIR 7628 Guidelines for Smart Grid Cyber Security

427http://www.nist.gov/smartgrid/upload/nistir-7628_total.pdf
428
429[NSAB]
430NSA Suite B Cryptography
431http://www.nsa.gov/ia/programs/suiteb_cryptography/
432
433[PCIDSS]
434PCI-DSS Payment Card Industry Data Security Standard
435https://www.pcisecuritystandards.org/security_standards/
436
437[RFC1928]
438Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and L. Jones, "SOCKS Protocol Version 5", RFC
4391928, March 1996.
441
442[RFC4511]
443Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June
4442006.
446
447[RFC5077]
448Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, "Transport Layer Security (TLS) Session
449Resumption without Server-Side State", RFC 5077, January 2008.
451
452[RFC5280]
453Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key
454Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, May 2008.
456
457[RFC6066]
458Eastlake 3rd, D., "Transport Layer Security (TLS) Extensions: Extension Definitions", RFC 6066, January
4592011.
461
462[RFC6749]
463Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.
465
466[RFC6960]
467Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public
468Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, June 2013.
470
23mqtt-v3.1.1-os
29 October 2014
Page 12 of 80
471[SARBANES]
472Sarbanes-Oxley Act of 2002.
473http://www.gpo.gov/fdsys/pkg/PLAW-107publ204/html/PLAW-107publ204.htm
474
475[USEUSAFEHARB]
476U.S.-EU Safe Harbor
477http://export.gov/safeharbor/eu/eg_main_018365.asp
4781.5 Data representations

4791.5.1 Bits
480Bits in a byte are labeled 7 through 0. Bit number 7 is the most significant bit, the least significant bit is
481assigned bit number 0.
4821.5.2 Integer data values

483Integer data values are 16 bits in big-endian order: the high order byte precedes the lower order byte.
484This means that a 16-bit word is presented on the network as Most Significant Byte (MSB), followed by
485Least Significant Byte (LSB).
4861.5.3 UTF-8 encoded strings

487Text fields in the Control Packets described later are encoded as UTF-8 strings. UTF-8 [RFC3629] is an
488efficient encoding of Unicode [Unicode] characters that optimizes the encoding of ASCII characters in
489support of text-based communications.
490
491Each of these strings is prefixed with a two byte length field that gives the number of bytes in a UTF-8
492encoded string itself, as illustrated in Figure 1.1 Structure of UTF-8 encoded strings below. Consequently
493there is a limit on the size of a string that can be passed in one of these UTF-8 encoded string
494components; you cannot use a string that would encode to more than 65535 bytes.
495
496Unless stated otherwise all UTF-8 encoded strings can have any length in the range 0 to 65535 bytes.
497Figure 1.1 Structure of UTF-8 encoded strings
Bit
byte 1
String length MSB
byte 2
String length LSB
byte 3 .
UTF-8 Encoded Character Data, if length > 0.
498
499The character data in a UTF-8 encoded string MUST be well-formed UTF-8 as defined by the Unicode
500specification [Unicode] and restated in RFC 3629 [RFC3629]. In particular this data MUST NOT include
501encodings of code points between U+D800 and U+DFFF. If a Server or Client receives a Control Packet
502containing ill-formed UTF-8 it MUST close the Network Connection [MQTT-1.5.3-1].
503
504A UTF-8 encoded string MUST NOT include an encoding of the null character U+0000. If a receiver
505(Server or Client) receives a Control Packet containing U+0000 it MUST close the Network
506Connection [MQTT-1.5.3-2].
25mqtt-v3.1.1-os
29 October 2014
Page 13 of 80
508The data SHOULD NOT include encodings of the Unicode [Unicode] code points listed below. If a
509receiver (Server or Client) receives a Control Packet containing any of them it MAY close the Network
510Connection:
511
512U+0001..U+001F control characters
513U+007F..U+009F control characters
514Code points defined in the Unicode specification [Unicode] to be non-characters (for example
515U+0FFFF)
516
517A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always to be interpreted to mean U+FEFF ("ZERO
518WIDTH NO-BREAK SPACE") wherever it appears in a string and MUST NOT be skipped over or stripped
519off by a packet receiver [MQTT-1.5.3-3].
520
521
1.5.3.1 Non normative example
522
523
For example, the string A which is LATIN CAPITAL Letter A followed by the code point
U+2A6D4 (which represents a CJK IDEOGRAPH EXTENSION B character) is encoded as
follows:
524
525
526Figure 1.2 UTF-8 encoded string non normative example
Bit
byte 1
String Length MSB (0x00)

0
byte 2
String Length LSB (0x05)

0
byte 3
A (0x41)
0
byte 4
(0xF0)
1
byte 5
(0xAA)
1
byte 6
(0x9B)
1
byte 7
(0x94)
1
527
5281.6 Editing conventions

529Text highlighted in Yellow within this specification identifies conformance statements. Each conformance
530statement has been assigned a reference in the format [MQTT-x.x.x-y].
27mqtt-v3.1.1-os
29 October 2014
Page 14 of 80
5312
MQTT Control Packet format
5322.1 Structure of an MQTT Control Packet

533The MQTT protocol works by exchanging a series of MQTT Control Packets in a defined way. This
534section describes the format of these packets.
535An MQTT Control Packet consists of up to three parts, always in the following order as illustrated in
536Figure 2.1 - Structure of an MQTT Control Packet.
537
538Figure 2.1 Structure of an MQTT Control Packet
Fixed header, present in all MQTT Control Packets

Variable header, present in some MQTT Control Packets
Payload, present in some MQTT Control Packets
5392.2 Fixed header

540Each MQTT Control Packet contains a fixed header. Figure 2.2 - Fixed header format illustrates the fixed
541header format.
542
543Figure 2.2 - Fixed header format
Bit
byte 1
MQTT Control Packet type
byte 2
Flags specific to each MQTT Control

Packet type
Remaining Length
544
5452.2.1 MQTT Control Packet type

546Position: byte 1, bits 7-4.
547Represented as a 4-bit unsigned value, the values are listed in Table 2.1 - Control packet types.
548
549Table 2.1 - Control packet types
Name
Value
Direction of
flow
Description
Reserved
Forbidden
Reserved
CONNECT
Client to Server
Client request to connect to Server
CONNACK
Server to Client
Connect acknowledgment
PUBLISH
Client to Server
Publish message
29mqtt-v3.1.1-os
29 October 2014
Page 15 of 80
or
Server to Client
PUBACK
Client to Server
Publish acknowledgment
or
Server to Client
PUBREC
Client to Server
Publish received (assured delivery part 1)
or
Server to Client
PUBREL
Client to Server
Publish release (assured delivery part 2)
or
Server to Client
PUBCOMP
Client to Server
Publish complete (assured delivery part 3)
or
Server to Client
SUBSCRIBE
Client to Server
Client subscribe request
SUBACK
Server to Client
Subscribe acknowledgment
UNSUBSCRIBE
10
Client to Server
Unsubscribe request
UNSUBACK
11
Server to Client
Unsubscribe acknowledgment
PINGREQ
12
Client to Server
PING request
PINGRESP
13
Server to Client
PING response
DISCONNECT
14
Client to Server
Client is disconnecting
Reserved
15
Forbidden
Reserved
550
5512.2.2 Flags
552The remaining bits [3-0] of byte 1 in the fixed header contain flags specific to each MQTT Control Packet
553type as listed in the Table 2.2 - Flag Bits below. Where a flag bit is marked as Reserved in Table 2.2 554Flag Bits, it is reserved for future use and MUST be set to the value listed in that table [MQTT-2.2.2-1]. If
555invalid flags are received, the receiver MUST close the Network Connection [MQTT-2.2.2-2]. See Section
5564.8 for details about handling errors.
557
558 Table 2.2 - Flag Bits
Control Packet
Fixed header flags
Bit 3
Bit 2
Bit 1
Bit 0
CONNECT
Reserved
CONNACK
Reserved
PUBLISH
Used in MQTT 3.1.1
DUP1
QoS2
QoS2
RETAIN3
PUBACK
Reserved
31mqtt-v3.1.1-os
29 October 2014
Page 16 of 80
PUBREC
Reserved
PUBREL
Reserved
PUBCOMP
Reserved
SUBSCRIBE
Reserved
SUBACK
Reserved
UNSUBSCRIBE
Reserved
UNSUBACK
Reserved
PINGREQ
Reserved
PINGRESP
Reserved
DISCONNECT
Reserved
559
560DUP1
561QoS
= Duplicate delivery of a PUBLISH Control Packet
= PUBLISH Quality of Service

3
562RETAIN = PUBLISH Retain flag

563See Section 3.3.1 for a description of the DUP, QoS, and RETAIN flags in the PUBLISH Control Packet.
5642.2.3 Remaining Length

565Position: starts at byte 2.
566
567The Remaining Length is the number of bytes remaining within the current packet, including data in the
568variable header and the payload. The Remaining Length does not include the bytes used to encode the
569Remaining Length.
570
571The Remaining Length is encoded using a variable length encoding scheme which uses a single byte for
572values up to 127. Larger values are handled as follows. The least significant seven bits of each byte
573encode the data, and the most significant bit is used to indicate that there are following bytes in the
574representation. Thus each byte encodes 128 values and a "continuation bit". The maximum number of
575bytes in the Remaining Length field is four.
576
577
Non normative comment
578
579
580
581
For example, the number 64 decimal is encoded as a single byte, decimal value 64, hexadecimal
0x40. The number 321 decimal (= 65 + 2*128) is encoded as two bytes, least significant first. The
first byte is 65+128 = 193. Note that the top bit is set to indicate at least one following byte. The
second byte is 2.
582
583
584
585
This allows applications to send Control Packets of size up to 268,435,455 (256 MB). The
representation of this number on the wire is: 0xFF, 0xFF, 0xFF, 0x7F.
586
Table 2.4 shows the Remaining Length values represented by increasing numbers of bytes.
587
33mqtt-v3.1.1-os
29 October 2014
Page 17 of 80
588Table 2.4 Size of Remaining Length field
Digits
From
To
0 (0x00)
127 (0x7F)
128 (0x80, 0x01)
16 383 (0xFF, 0x7F)
16 384 (0x80, 0x80, 0x01)
2 097 151 (0xFF, 0xFF, 0x7F)
2 097 152 (0x80, 0x80, 0x80, 0x01)
268 435 455 (0xFF, 0xFF, 0xFF, 0x7F)
589
590
591
592
The algorithm for encoding a non negative integer (X) into the variable length encoding scheme is
as follows:
593
do
594
encodedByte = X MOD 128
595
X = X DIV 128
596
// if there are more data to encode, set the top bit of this byte
597
if ( X > 0 )
encodedByte = encodedByte OR 128
598
endif
599
'output' encodedByte
600
601
while ( X > 0 )
602
603
604
Where MOD is the modulo operator (% in C), DIV is integer division (/ in C), and OR is bit-wise
or (| in C).
605
606
607
The algorithm for decoding the Remaining Length field is as follows:
608
609
multiplier = 1
610
value = 0
611
do
612
encodedByte = 'next byte from stream'
613
value += (encodedByte AND 127) * multiplier
614
multiplier *= 128
615
if (multiplier > 128*128*128)
616
617
throw Error(Malformed Remaining Length)

while ((encodedByte AND 128) != 0)
618
619
where AND is the bit-wise and operator (& in C).
620
621
When this algorithm terminates, value contains the Remaining Length value.
35mqtt-v3.1.1-os
29 October 2014
Page 18 of 80
6222.3 Variable header

623Some types of MQTT Control Packets contain a variable header component. It resides between the fixed
624header and the payload. The content of the variable header varies depending on the Packet type. The
625Packet Identifier field of variable header is common in several packet types.
6262.3.1 Packet Identifier

627Figure 2.3 - Packet Identifier bytes
Bit
byte 1
Packet Identifier MSB
byte 2
Packet Identifier LSB
628
629The variable header component of many of the Control Packet types includes a 2 byte Packet Identifier
630field. These Control Packets are PUBLISH (where QoS > 0), PUBACK, PUBREC, PUBREL, PUBCOMP,
631SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK.
632
633SUBSCRIBE, UNSUBSCRIBE, and PUBLISH (in cases where QoS > 0) Control Packets MUST contain a
634non-zero 16-bit Packet Identifier [MQTT-2.3.1-1]. Each time a Client sends a new packet of one of these
635types it MUST assign it a currently unused Packet Identifier [MQTT-2.3.1-2]. If a Client re-sends a
636particular Control Packet, then it MUST use the same Packet Identifier in subsequent re-sends of that
637packet. The Packet Identifier becomes available for reuse after the Client has processed the
638corresponding acknowledgement packet. In the case of a QoS 1 PUBLISH this is the corresponding
639PUBACK; in the case of QoS 2 it is PUBCOMP. For SUBSCRIBE or UNSUBSCRIBE it is the
640corresponding SUBACK or UNSUBACK [MQTT-2.3.1-3]. The same conditions apply to a Server when it
641sends a PUBLISH with QoS > 0 [MQTT-2.3.1-4].
642
643A PUBLISH Packet MUST NOT contain a Packet Identifier if its QoS value is set to 0 [MQTT-2.3.1-5].
644
645A PUBACK, PUBREC or PUBREL Packet MUST contain the same Packet Identifier as the PUBLISH
646Packet that was originally sent [MQTT-2.3.1-6]. Similarly SUBACK and UNSUBACK MUST contain the
647Packet Identifier that was used in the corresponding SUBSCRIBE and UNSUBSCRIBE Packet
648respectively [MQTT-2.3.1-7].
649
650Control Packets that require a Packet Identifier are listed in Table 2.5 - Control Packets that contain a
651Packet Identifier.
652Table 2.5 - Control Packets that contain a Packet Identifier
Control Packet
Packet Identifier field
CONNECT
NO
CONNACK
NO
PUBLISH
YES (If QoS > 0)
PUBACK
YES
PUBREC
YES
PUBREL
YES
37mqtt-v3.1.1-os
29 October 2014
Page 19 of 80
PUBCOMP
YES
SUBSCRIBE
YES
SUBACK
YES
UNSUBSCRIBE
YES
UNSUBACK
YES
PINGREQ
NO
PINGRESP
NO
DISCONNECT
NO
653
654The Client and Server assign Packet Identifiers independently of each other. As a result, Client Server
655pairs can participate in concurrent message exchanges using the same Packet Identifiers.
656
657
658
659
660
It is possible for a Client to send a PUBLISH Packet with Packet Identifier 0x1234 and then
receive a different PUBLISH with Packet Identifier 0x1234 from its Server before it receives a
PUBACK for the PUBLISH that it sent.
661
662
663
664
665
666
Client
Server
PUBLISH Packet Identifier=0x1234---
--PUBLISH Packet Identifier=0x1234
PUBACK Packet Identifier=0x1234---
--PUBACK Packet Identifier=0x1234
6672.4 Payload
668Some MQTT Control Packets contain a payload as the final part of the packet, as described in Chapter 3.
669In the case of the PUBLISH packet this is the Application Message. Table 2.6 - Control Packets that
670contain a Payload lists the Control Packets that require a Payload.
671Table 2.6 - Control Packets that contain a Payload
Control Packet
Payload
CONNECT
Required
CONNACK
None
PUBLISH
Optional
PUBACK
None
PUBREC
None
PUBREL
None
PUBCOMP
None
SUBSCRIBE
Required
SUBACK
Required
39mqtt-v3.1.1-os
29 October 2014
Page 20 of 80
UNSUBSCRIBE
Required
UNSUBACK
None
PINGREQ
None
PINGRESP
None
DISCONNECT
None
672
41mqtt-v3.1.1-os
29 October 2014
Page 21 of 80
6733
MQTT Control Packets
6743.1 CONNECT Client requests a connection to a Server

675After a Network Connection is established by a Client to a Server, the first Packet sent from the Client to
676the Server MUST be a CONNECT Packet [MQTT-3.1.0-1].
677
678A Client can only send the CONNECT Packet once over a Network Connection. The Server MUST
679process a second CONNECT Packet sent from a Client as a protocol violation and disconnect the Client
680[MQTT-3.1.0-2]. See section 4.8 for information about handling errors.
681
682The payload contains one or more encoded fields. They specify a unique Client identifier for the Client, a
683Will topic, Will Message, User Name and Password. All but the Client identifier are optional and their
684presence is determined based on flags in the variable header.
6853.1.1 Fixed header

686Figure 3.1 CONNECT Packet fixed header
Bit
byte 1
MQTT Control Packet type (1)

0
byte 2
Reserved
Remaining Length
687
688Remaining Length field
689Remaining Length is the length of the variable header (10 bytes) plus the length of the Payload. It is
690encoded in the manner described in section 2.2.3.
6913.1.2 Variable header

692The variable header for the CONNECT Packet consists of four fields in the following order: Protocol
693Name, Protocol Level, Connect Flags, and Keep Alive.
694
3.1.2.1 Protocol Name
695Figure 3.2 - Protocol Name bytes
Description
Protocol Name
byte 1
Length MSB (0)
byte 2
Length LSB (4)
byte 3
byte 4
byte 5
43mqtt-v3.1.1-os
29 October 2014
Page 22 of 80
byte 6
696
697The Protocol Name is a UTF-8 encoded string that represents the protocol name MQTT, capitalized as
698shown. The string, its offset and length will not be changed by future versions of the MQTT specification.
699
700If the protocol name is incorrect the Server MAY disconnect the Client, or it MAY continue processing the
701CONNECT packet in accordance with some other specification. In the latter case, the Server MUST NOT
702continue to process the CONNECT packet in line with this specification [MQTT-3.1.2-1].
703
704
705
Packet inspectors, such as firewalls, could use the Protocol Name to identify MQTT traffic.
3.1.2.2 Protocol Level
706
707Figure 3.3 - Protocol Level byte
Description
Protocol Level
byte 7
Level(4)
708
709The 8 bit unsigned value that represents the revision level of the protocol used by the Client. The value of
710the Protocol Level field for the version 3.1.1 of the protocol is 4 (0x04). The Server MUST respond to the
711CONNECT Packet with a CONNACK return code 0x01 (unacceptable protocol level) and then disconnect
712the Client if the Protocol Level is not supported by the Server [MQTT-3.1.2-2].
3.1.2.3 Connect Flags
713
714The Connect Flags byte contains a number of parameters specifying the behavior of the MQTT
715connection. It also indicates the presence or absence of fields in the payload.
716Figure 3.4 - Connect Flag bits
Bit
byte 8
User Name
Flag
Password
Flag
Will Retain
Will QoS
X
Will Flag
Clean
Session
Reserved
717The Server MUST validate that the reserved flag in the CONNECT Control Packet is set to zero and
718disconnect the Client if it is not zero [MQTT-3.1.2-3].
719
3.1.2.4 Clean Session
720Position: bit 1 of the Connect Flags byte.

721
722This bit specifies the handling of the Session state.
723
724The Client and Server can store Session state to enable reliable messaging to continue across a
725sequence of Network Connections. This bit is used to control the lifetime of the Session state.
45mqtt-v3.1.1-os
29 October 2014
Page 23 of 80
726
727If CleanSession is set to 0, the Server MUST resume communications with the Client based on state from
728the current Session (as identified by the Client identifier). If there is no Session associated with the Client
729identifier the Server MUST create a new Session. The Client and Server MUST store the Session after
730the Client and Server are disconnected [MQTT-3.1.2-4]. After the disconnection of a Session that had
731CleanSession set to 0, the Server MUST store further QoS 1 and QoS 2 messages that match any
732subscriptions that the client had at the time of disconnection as part of the Session state [MQTT-3.1.2-5].
733It MAY also store QoS 0 messages that meet the same criteria.
734
735If CleanSession is set to 1, the Client and Server MUST discard any previous Session and start a new
736one. This Session lasts as long as the Network Connection. State data associated with this Session
737MUST NOT be reused in any subsequent Session [MQTT-3.1.2-6].
738
739The Session state in the Client consists of:
740
741
742
743
QoS 1 and QoS 2 messages which have been sent to the Server, but have not been completely
acknowledged.
QoS 2 messages which have been received from the Server, but have not been completely
acknowledged.
744
745The Session state in the Server consists of:
746
747
748
749
750
751
752
753
The existence of a Session, even if the rest of the Session state is empty.
The Clients subscriptions.
QoS 1 and QoS 2 messages which have been sent to the Client, but have not been completely
acknowledged.
QoS 1 and QoS 2 messages pending transmission to the Client.
QoS 2 messages which have been received from the Client, but have not been completely
acknowledged.
Optionally, QoS 0 messages pending transmission to the Client.
754
755Retained messages do not form part of the Session state in the Server, they MUST NOT be deleted when
756the Session ends [MQTT-3.1.2.7].
757
758See Section 4.1 for details and limitations of stored state.
759
760When CleanSession is set to 1 the Client and Server need not process the deletion of state atomically.
761
762
763
764
To ensure consistent state in the event of a failure, the Client should repeat its attempts to
connect with CleanSession set to 1, until it connects successfully.
765
766
767
768
769
770
771
Typically, a Client will always connect using CleanSession set to 0 or CleanSession set to 1 and
not swap between the two values. The choice will depend on the application. A Client using
CleanSession set to 1 will not receive old Application Messages and has to subscribe afresh to
any topics that it is interested in each time it connects. A Client using CleanSession set to 0 will
receive all QoS 1 or QoS 2 messages that were published while it was disconnected. Hence, to
47mqtt-v3.1.1-os
29 October 2014
Page 24 of 80
ensure that you do not lose messages while disconnected, use QoS 1 or QoS 2 with
CleanSession set to 0.
772
773
774
775
776
777
778
779
780
When a Client connects with CleanSession set to 0, it is requesting that the Server maintain its
MQTT session state after it disconnects. Clients should only connect with CleanSession set to 0,
if they intend to reconnect to the Server at some later point in time. When a Client has determined
that it has no further use for the session it should do a final connect with CleanSession set to 1
and then disconnect.
3.1.2.5 Will Flag
781
782Position: bit 2 of the Connect Flags.

783
784If the Will Flag is set to 1 this indicates that, if the Connect request is accepted, a Will Message MUST be
785stored on the Server and associated with the Network Connection. The Will Message MUST be published
786when the Network Connection is subsequently closed unless the Will Message has been deleted by the
787Server on receipt of a DISCONNECT Packet [MQTT-3.1.2-8].
788Situations in which the Will Message is published include, but are not limited to:
789
790
791
792
An I/O error or network failure detected by the Server.
The Client fails to communicate within the Keep Alive time.
The Client closes the Network Connection without first sending a DISCONNECT Packet.
The Server closes the Network Connection because of a protocol error.
793
794If the Will Flag is set to 1, the Will QoS and Will Retain fields in the Connect Flags will be used by the
795Server, and the Will Topic and Will Message fields MUST be present in the payload [MQTT-3.1.2-9].
796The Will Message MUST be removed from the stored Session state in the Server once it has been
797published or the Server has received a DISCONNECT packet from the Client [MQTT-3.1.2-10].
798If the Will Flag is set to 0 the Will QoS and Will Retain fields in the Connect Flags MUST be set to zero
799and the Will Topic and Will Message fields MUST NOT be present in the payload [MQTT-3.1.2-11].
800If the Will Flag is set to 0, a Will Message MUST NOT be published when this Network Connection ends
801[MQTT-3.1.2-12].
802
803The Server SHOULD publish Will Messages promptly. In the case of a Server shutdown or failure the
804server MAY defer publication of Will Messages until a subsequent restart. If this happens there might be a
805delay between the time the server experienced failure and a Will Message being published.
806
3.1.2.6 Will QoS
807Position: bits 4 and 3 of the Connect Flags.

808
809These two bits specify the QoS level to be used when publishing the Will Message.
810
811If the Will Flag is set to 0, then the Will QoS MUST be set to 0 (0x00) [MQTT-3.1.2-13].
812If the Will Flag is set to 1, the value of Will QoS can be 0 (0x00), 1 (0x01), or 2 (0x02). It MUST NOT be 3
813(0x03) [MQTT-3.1.2-14].
814
3.1.2.7 Will Retain

49mqtt-v3.1.1-os
29 October 2014
Page 25 of 80
816
817This bit specifies if the Will Message is to be Retained when it is published.
818
819If the Will Flag is set to 0, then the Will Retain Flag MUST be set to 0 [MQTT-3.1.2-15].
820If the Will Flag is set to 1:
821
If Will Retain is set to 0, the Server MUST publish the Will Message as a non-retained message
[MQTT-3.1.2-16].
If Will Retain is set to 1, the Server MUST publish the Will Message as a retained message
[MQTT-3.1.2-17].
822
823
824
3.1.2.8 User Name Flag
825

827
828If the User Name Flag is set to 0, a user name MUST NOT be present in the payload [MQTT-3.1.2-18].
829If the User Name Flag is set to 1, a user name MUST be present in the payload [MQTT-3.1.2-19].
3.1.2.9 Password Flag
830
831Position: bit 6 of the Connect Flags byte.

832
833If the Password Flag is set to 0, a password MUST NOT be present in the payload [MQTT-3.1.2-20].
834If the Password Flag is set to 1, a password MUST be present in the payload [MQTT-3.1.2-21].
835If the User Name Flag is set to 0, the Password Flag MUST be set to 0 [MQTT-3.1.2-22].
3.1.2.10 Keep Alive
836
837Figure 3.5 Keep Alive bytes
Bit
byte 9
Keep Alive MSB
byte 10
Keep Alive LSB
838
839The Keep Alive is a time interval measured in seconds. Expressed as a 16-bit word, it is the maximum
840time interval that is permitted to elapse between the point at which the Client finishes transmitting one
841Control Packet and the point it starts sending the next. It is the responsibility of the Client to ensure that
842the interval between Control Packets being sent does not exceed the Keep Alive value. In the absence of
843sending any other Control Packets, the Client MUST send a PINGREQ Packet [MQTT-3.1.2-23].
844
845The Client can send PINGREQ at any time, irrespective of the Keep Alive value, and use the PINGRESP
846to determine that the network and the Server are working.
847
848If the Keep Alive value is non-zero and the Server does not receive a Control Packet from the Client
849within one and a half times the Keep Alive time period, it MUST disconnect the Network Connection to the
850Client as if the network had failed [MQTT-3.1.2-24].
851
852If a Client does not receive a PINGRESP Packet within a reasonable amount of time after it has sent a
853PINGREQ, it SHOULD close the Network Connection to the Server.
854
51mqtt-v3.1.1-os
29 October 2014
Page 26 of 80
855A Keep Alive value of zero (0) has the effect of turning off the keep alive mechanism. This means that, in
856this case, the Server is not required to disconnect the Client on the grounds of inactivity.
857Note that a Server is permitted to disconnect a Client that it determines to be inactive or non-responsive
858at any time, regardless of the Keep Alive value provided by that Client.
859
860
861
862
The actual value of the Keep Alive is application specific; typically this is a few minutes. The
maximum value is 18 hours 12 minutes and 15 seconds.
863
3.1.2.11 Variable header non normative example
864Figure 3.6 - Variable header non normative example
Description
Protocol Name
byte 1
Length MSB (0)
byte 2
Length LSB (4)
byte 3
byte 4
byte 5
byte 6
Description
Protocol Level
byte 7
Level (4)
Connect Flags
User Name Flag (1)
Password Flag (1)
Will Retain (0)
byte 8
Will QoS (01)

Will Flag (1)
Clean Session (1)
Reserved (0)
Keep Alive
byte 9
Keep Alive MSB (0)
byte 10
Keep Alive LSB (10)
865
53mqtt-v3.1.1-os
29 October 2014
Page 27 of 80
8663.1.3 Payload
867The payload of the CONNECT Packet contains one or more length-prefixed fields, whose presence is
868determined by the flags in the variable header. These fields, if present, MUST appear in the order Client
869Identifier, Will Topic, Will Message, User Name, Password [MQTT-3.1.3-1].
870
3.1.3.1 Client Identifier
871The Client Identifier (ClientId) identifies the Client to the Server. Each Client connecting to the Server has
872a unique ClientId. The ClientId MUST be used by Clients and by Servers to identify state that they hold
873relating to this MQTT Session between the Client and the Server [MQTT-3.1.3-2].
874
875The Client Identifier (ClientId) MUST be present and MUST be the first field in the CONNECT packet
876payload [MQTT-3.1.3-3].
877
878The ClientId MUST be a UTF-8 encoded string as defined in Section 1.5.3 [MQTT-3.1.3-4].
879
880The Server MUST allow ClientIds which are between 1 and 23 UTF-8 encoded bytes in length, and that
881contain only the characters
882"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" [MQTT-3.1.3-5].
883
884The Server MAY allow ClientIds that contain more than 23 encoded bytes. The Server MAY allow
885ClientIds that contain characters not included in the list given above.
886
887A Server MAY allow a Client to supply a ClientId that has a length of zero bytes, however if it does so the
888Server MUST treat this as a special case and assign a unique ClientId to that Client. It MUST then
889process the CONNECT packet as if the Client had provided that unique ClientId [MQTT-3.1.3-6].
890
891If the Client supplies a zero-byte ClientId, the Client MUST also set CleanSession to 1 [MQTT-3.1.3-7].
892
893If the Client supplies a zero-byte ClientId with CleanSession set to 0, the Server MUST respond to the
894CONNECT Packet with a CONNACK return code 0x02 (Identifier rejected) and then close the Network
896
897If the Server rejects the ClientId it MUST respond to the CONNECT Packet with a CONNACK return code
8980x02 (Identifier rejected) and then close the Network Connection [MQTT-3.1.3-9].
899
900
901
902
A Client implementation could provide a convenience method to generate a random ClientId. Use
of such a method should be actively discouraged when the CleanSession is set to 0.
903
3.1.3.2 Will Topic
904If the Will Flag is set to 1, the Will Topic is the next field in the payload. The Will Topic MUST be a UTF-8
905encoded string as defined in Section 1.5.3 [MQTT-3.1.3-10].
906
3.1.3.3 Will Message
907If the Will Flag is set to 1 the Will Message is the next field in the payload. The Will Message defines the
908Application Message that is to be published to the Will Topic as described in Section 3.1.2.5. This field
909consists of a two byte length followed by the payload for the Will Message expressed as a sequence of
910zero or more bytes. The length gives the number of bytes in the data that follows and does not include the
9112 bytes taken up by the length itself.
912
55mqtt-v3.1.1-os
29 October 2014
Page 28 of 80
913When the Will Message is published to the Will Topic its payload consists only of the data portion of this
914field, not the first two length bytes.
3.1.3.4 User Name
915
916If the User Name Flag is set to 1, this is the next field in the payload. The User Name MUST be a UTF-8
917encoded string as defined in Section 1.5.3 [MQTT-3.1.3-11]. It can be used by the Server for
918authentication and authorization.
3.1.3.5 Password
919
920If the Password Flag is set to 1, this is the next field in the payload. The Password field contains 0 to
92165535 bytes of binary data prefixed with a two byte length field which indicates the number of bytes used
922by the binary data (it does not include the two bytes taken up by the length field itself).
923Figure 3.7 - Password bytes
Bit
byte 1
Data length MSB
byte 2
Data length LSB
byte 3 .
Data, if length > 0.
924
9253.1.4 Response
926Note that a Server MAY support multiple protocols (including earlier versions of this protocol) on the same
927TCP port or other network endpoint. If the Server determines that the protocol is MQTT 3.1.1 then it
928validates the connection attempt as follows.
929
930
931
1.
If the Server does not receive a CONNECT Packet within a reasonable amount of time
after the Network Connection is established, the Server SHOULD close the connection.
933
934
2.
The Server MUST validate that the CONNECT Packet conforms to section 3.1 and close
the Network Connection without sending a CONNACK if it does not conform [MQTT-3.1.4-1].
936
937
938
939
3. The Server MAY check that the contents of the CONNECT Packet meet any further restrictions
and MAY perform authentication and authorization checks. If any of these checks fail, it SHOULD
send an appropriate CONNACK response with a non-zero return code as described in section 3.2
and it MUST close the Network Connection.
940
941If validation is successful the Server performs the following steps.
942
943
944
1. If the ClientId represents a Client already connected to the Server then the Server MUST
disconnect the existing Client [MQTT-3.1.4-2].
945
946
947
2. The Server MUST perform the processing of CleanSession that is described in section 3.1.2.4
[MQTT-3.1.4-3].
948
949
950
3. The Server MUST acknowledge the CONNECT Packet with a CONNACK Packet containing a
zero return code [MQTT-3.1.4-4].
57mqtt-v3.1.1-os
29 October 2014
Page 29 of 80
951
952
4. Start message delivery and keep alive monitoring.
953
954Clients are allowed to send further Control Packets immediately after sending a CONNECT Packet;
955Clients need not wait for a CONNACK Packet to arrive from the Server. If the Server rejects the
956CONNECT, it MUST NOT process any data sent by the Client after the CONNECT Packet [MQTT-3.1.49575].

Clients typically wait for a CONNACK Packet, However, if the Client exploits its freedom to send
Control Packets before it receives a CONNACK, it might simplify the Client implementation as it
does not have to police the connected state. The Client accepts that any data that it sends before it
receives a CONNACK packet from the Server will not be processed if the Server rejects the
connection.
959
960
961
962
963
964
9653.2 CONNACK Acknowledge connection request

966The CONNACK Packet is the packet sent by the Server in response to a CONNECT Packet received
967from a Client. The first packet sent from the Server to the Client MUST be a CONNACK Packet [MQTT9683.2.0-1].
969
970If the Client does not receive a CONNACK Packet from the Server within a reasonable amount of time,
971the Client SHOULD close the Network Connection. A "reasonable" amount of time depends on the type of
972application and the communications infrastructure.

974The fixed header format is illustrated in Figure 3.8 CONNACK Packet fixed header.
975Figure 3.8 CONNACK Packet fixed header
Bit
byte 1
MQTT Control Packet Type (2)

0
byte 2
Reserved
0
Remaining Length (2)

0
976
978This is the length of the variable header. For the CONNACK Packet this has the value 2.

980The variable header format is illustrated in Figure 3.9 CONNACK Packet variable header.
981Figure 3.9 CONNACK Packet variable header
Description
Connect Acknowledge Flags
byte 1
59mqtt-v3.1.1-os
SP1
Reserved
0
29 October 2014
Page 30 of 80
Connect Return code

byte 2
982
3.2.2.1 Connect Acknowledge Flags
983Byte 1 is the "Connect Acknowledge Flags". Bits 7-1 are reserved and MUST be set to 0.
984
985Bit 0 (SP1) is the Session Present Flag.
986
3.2.2.2 Session Present
987Position: bit 0 of the Connect Acknowledge Flags.

988
989If the Server accepts a connection with CleanSession set to 1, the Server MUST set Session Present to 0
990in the CONNACK packet in addition to setting a zero return code in the CONNACK packet [MQTT-3.2.29911].
992
993If the Server accepts a connection with CleanSession set to 0, the value set in Session Present depends
994on whether the Server already has stored Session state for the supplied client ID. If the Server has stored
995Session state, it MUST set Session Present to 1 in the CONNACK packet [MQTT-3.2.2-2]. If the Server
996does not have stored Session state, it MUST set Session Present to 0 in the CONNACK packet. This is in
997addition to setting a zero return code in the CONNACK packet [MQTT-3.2.2-3].
998
999The Session Present flag enables a Client to establish whether the Client and Server have a consistent
1000view about whether there is already stored Session state.
1001
1002Once the initial setup of a Session is complete, a Client with stored Session state will expect the Server to
1003maintain its stored Session state. In the event that the value of Session Present received by the Client
1004from the Server is not as expected, the Client can choose whether to proceed with the Session or to
1005disconnect. The Client can discard the Session state on both Client and Server by disconnecting,
1006connecting with Clean Session set to 1 and then disconnecting again.
1007
1008If a server sends a CONNACK packet containing a non-zero return code it MUST set Session Present to
10090 [MQTT-3.2.2-4].
1010
1011
3.2.2.3 Connect Return code
1012Byte 2 in the Variable header.

1013
1014The values for the one byte unsigned Connect Return code field are listed in Table 3.1 Connect Return
1015code values. If a well formed CONNECT Packet is received by the Server, but the Server is unable to
1016process it for some reason, then the Server SHOULD attempt to send a CONNACK packet containing the
1017appropriate non-zero Connect return code from this table. If a server sends a CONNACK packet
1018containing a non-zero return code it MUST then close the Network Connection [MQTT-3.2.2-5].
1019Table 3.1 Connect Return code values
Value
Return Code Response
Description
0x00 Connection Accepted
Connection accepted
0x01 Connection Refused, unacceptable

protocol version
The Server does not support the level of the

MQTT protocol requested by the Client
0x02 Connection Refused, identifier rejected
The Client identifier is correct UTF-8 but not
61mqtt-v3.1.1-os
29 October 2014
Page 31 of 80
allowed by the Server

3
0x03 Connection Refused, Server unavailable
The Network Connection has been made but

the MQTT service is unavailable
0x04 Connection Refused, bad user name or

password
The data in the user name or password is

malformed
0x05 Connection Refused, not authorized
The Client is not authorized to connect
6-255
Reserved for future use
1020
1021If none of the return codes listed in Table 3.1 Connect Return code values are deemed applicable, then
1022the Server MUST close the Network Connection without sending a CONNACK [MQTT-3.2.2-6].
10233.2.3 Payload
1024The CONNACK Packet has no payload.
10253.3 PUBLISH Publish message

1026A PUBLISH Control Packet is sent from a Client to a Server or from Server to a Client to transport an
1027Application Message.

1029Figure 3.10 PUBLISH Packet fixed header illustrates the fixed header format:
1030Figure 3.10 PUBLISH Packet fixed header
Bit
byte 1

0
byte 2
DUP flag
X
1
QoS level
0
RETAIN
X
Remaining Length
1031
1032
3.3.1.1 DUP
1033Position: byte 1, bit 3.

1034If the DUP flag is set to 0, it indicates that this is the first occasion that the Client or Server has attempted
1035to send this MQTT PUBLISH Packet. If the DUP flag is set to 1, it indicates that this might be re-delivery
1036of an earlier attempt to send the Packet.
1037
1038The DUP flag MUST be set to 1 by the Client or Server when it attempts to re-deliver a PUBLISH Packet
1039[MQTT-3.3.1.-1]. The DUP flag MUST be set to 0 for all QoS 0 messages [MQTT-3.3.1-2].
1040
1041The value of the DUP flag from an incoming PUBLISH packet is not propagated when the PUBLISH
1042Packet is sent to subscribers by the Server. The DUP flag in the outgoing PUBLISH packet is set
1043independently to the incoming PUBLISH packet, its value MUST be determined solely by whether the
1044outgoing PUBLISH packet is a retransmission [MQTT-3.3.1-3].
1045
1046
63mqtt-v3.1.1-os
29 October 2014
Page 32 of 80
1047
1048
The recipient of a Control Packet that contains the DUP flag set to 1 cannot assume that it has
seen an earlier copy of this packet.
1049
1050
1051
1052
1053
1054
1055
It is important to note that the DUP flag refers to the Control Packet itself and not to the
Application Message that it contains. When using QoS 1, it is possible for a Client to receive a
PUBLISH Packet with DUP flag set to 0 that contains a repetition of an Application Message that
it received earlier, but with a different Packet Identifier. Section 2.3.1 provides more information
about Packet Identifiers.
1056
3.3.1.2 QoS
1057Position: byte 1, bits 2-1.

1058This field indicates the level of assurance for delivery of an Application Message. The QoS levels are
1059listed in the Table 3.2 - QoS definitions, below.
1060
1061Table 3.2 - QoS definitions
QoS value
Bit 2
bit 1
Description
At most once delivery
At least once delivery
Exactly once delivery
Reserved must not be used
1062A PUBLISH Packet MUST NOT have both QoS bits set to 1. If a Server or Client receives a PUBLISH
1063Packet which has both QoS bits set to 1 it MUST close the Network Connection [MQTT-3.3.1-4].
1064
3.3.1.3 RETAIN
1065Position: byte 1, bit 0.

1066
1067If the RETAIN flag is set to 1, in a PUBLISH Packet sent by a Client to a Server, the Server MUST store
1068the Application Message and its QoS, so that it can be delivered to future subscribers whose
1069subscriptions match its topic name [MQTT-3.3.1-5]. When a new subscription is established, the last
1070retained message, if any, on each matching topic name MUST be sent to the subscriber [MQTT-3.3.1-6].
1071If the Server receives a QoS 0 message with the RETAIN flag set to 1 it MUST discard any message
1072previously retained for that topic. It SHOULD store the new QoS 0 message as the new retained message
1073for that topic, but MAY choose to discard it at any time - if this happens there will be no retained message
1074for that topic [MQTT-3.3.1-7]. See Section 4.1 for more information on storing state.
1075
1076When sending a PUBLISH Packet to a Client the Server MUST set the RETAIN flag to 1 if a message is
1077sent as a result of a new subscription being made by a Client [MQTT-3.3.1-8]. It MUST set the RETAIN
1078flag to 0 when a PUBLISH Packet is sent to a Client because it matches an established subscription
1079regardless of how the flag was set in the message it received [MQTT-3.3.1-9].
1080
1081A PUBLISH Packet with a RETAIN flag set to 1 and a payload containing zero bytes will be processed as
1082normal by the Server and sent to Clients with a subscription matching the topic name. Additionally any
1083existing retained message with the same topic name MUST be removed and any future subscribers for
1084the topic will not receive a retained message [MQTT-3.3.1-10]. As normal means that the RETAIN flag is
65mqtt-v3.1.1-os
29 October 2014
Page 33 of 80
1085not set in the message received by existing Clients. A zero byte retained message MUST NOT be stored
1086as a retained message on the Server [MQTT-3.3.1-11].
1087
1088If the RETAIN flag is 0, in a PUBLISH Packet sent by a Client to a Server, the Server MUST NOT store
1089the message and MUST NOT remove or replace any existing retained message [MQTT-3.3.1-12].
1090
1091
1092
1093
Retained messages are useful where publishers send state messages on an irregular basis. A
new subscriber will receive the most recent state.
1094
1096
This is the length of variable header plus the length of the payload.

1098The variable header contains the following fields in the order: Topic Name, Packet Identifier.
1099
3.3.2.1 Topic Name
1100The Topic Name identifies the information channel to which payload data is published.
1101
1102The Topic Name MUST be present as the first field in the PUBLISH Packet Variable header. It MUST be a
1103UTF-8 encoded string [MQTT-3.3.2-1] as defined in section 1.5.3.
1104The Topic Name in the PUBLISH Packet MUST NOT contain wildcard characters [MQTT-3.3.2-2].
1105The Topic Name in a PUBLISH Packet sent by a Server to a subscribing Client MUST match the
1106Subscriptions Topic Filter according to the matching process defined in Section 4.7 [MQTT-3.3.2-3].
1107However, since the Server is permitted to override the Topic Name, it might not be the same as the Topic
1108Name in the original PUBLISH Packet.
1109
3.3.2.2 Packet Identifier
1110The Packet Identifier field is only present in PUBLISH Packets where the QoS level is 1 or 2. Section
11112.3.1 provides more information about Packet Identifiers.
1112
1113Figure 3.11 - Publish Packet variable header non normative example illustrates an example variable
1114header for the PUBLISH Packet briefly described in Table 3.3 - Publish Packet non normative example.
1115Table 3.3 - Publish Packet non normative example
Field
Value
Topic Name
a/b
Packet Identifier
10
1116
1117Figure 3.11 - Publish Packet variable header non normative example
Description
Topic Name
67mqtt-v3.1.1-os
29 October 2014
Page 34 of 80
byte 1
Length MSB (0)
byte 2
Length LSB (3)
byte 3
a (0x61)
byte 4
/ (0x2F)
byte 5
b (0x62)
Packet Identifier
byte 6
Packet Identifier MSB (0)
byte 7
Packet Identifier LSB (10)
1118
11193.3.3 Payload
1120The Payload contains the Application Message that is being published. The content and format of the
1121data is application specific. The length of the payload can be calculated by subtracting the length of the
1122variable header from the Remaining Length field that is in the Fixed Header. It is valid for a PUBLISH
1123Packet to contain a zero length payload.
11243.3.4 Response
1125The receiver of a PUBLISH Packet MUST respond according to Table 3.4 - Expected Publish Packet
1126response as determined by the QoS in the PUBLISH Packet [MQTT-3.3.4-1].
1127Table 3.4 - Expected Publish Packet response
QoS Level
Expected Response
QoS 0
None
QoS 1
PUBACK Packet
QoS 2
PUBREC Packet
1128
11293.3.5 Actions
1130The Client uses a PUBLISH Packet to send an Application Message to the Server, for distribution to
1131Clients with matching subscriptions.
1132
1133The Server uses a PUBLISH Packet to send an Application Message to each Client which has a matching
1134subscription.
1135
1136When Clients make subscriptions with Topic Filters that include wildcards, it is possible for a Clients
1137subscriptions to overlap so that a published message might match multiple filters. In this case the Server
1138MUST deliver the message to the Client respecting the maximum QoS of all the matching subscriptions
1139[MQTT-3.3.5-1]. In addition, the Server MAY deliver further copies of the message, one for each
1140additional matching subscription and respecting the subscriptions QoS in each case.
1141
1142The action of the recipient when it receives a PUBLISH Packet depends on the QoS level as described in
1143Section 4.3.
69mqtt-v3.1.1-os
29 October 2014
Page 35 of 80
1144
1145If a Server implementation does not authorize a PUBLISH to be performed by a Client; it has no way of
1146informing that Client. It MUST either make a positive acknowledgement, according to the normal QoS
1147rules, or close the Network Connection [MQTT-3.3.5-2].
11483.4 PUBACK Publish acknowledgement

1149A PUBACK Packet is the response to a PUBLISH Packet with QoS level 1.

1151Figure 3.12 - PUBACK Packet fixed header
Bit
byte 1

0
byte 2
Reserved
0

0
1152
1154This is the length of the variable header. For the PUBACK Packet this has the value 2.

1156This contains the Packet Identifier from the PUBLISH Packet that is being acknowledged.
1157Figure 3.13 PUBACK Packet variable header
Bit
byte 1
byte 2
1158
11593.4.3 Payload
1160The PUBACK Packet has no payload.
11613.4.4 Actions
1162This is fully described in Section 4.3.2.
11633.5 PUBREC Publish received (QoS 2 publish received, part 1)

1164A PUBREC Packet is the response to a PUBLISH Packet with QoS 2. It is the second packet of the QoS
11652 protocol exchange.
71mqtt-v3.1.1-os
29 October 2014
Page 36 of 80

1167Figure 3.14 PUBREC Packet fixed header
Bit
byte 1

0
byte 2
Reserved
1

0
1168
1170
This is the length of the variable header. For the PUBREC Packet this has the value 2.

1172The variable header contains the Packet Identifier from the PUBLISH Packet that is being acknowledged.
1173Figure 3.15 PUBREC Packet variable header
Bit
byte 1
byte 2
1174
11753.5.3 Payload
1176The PUBREC Packet has no payload.
11773.5.4 Actions
11793.6 PUBREL Publish release (QoS 2 publish received, part 2)

1180A PUBREL Packet is the response to a PUBREC Packet. It is the third packet of the QoS 2 protocol
1181exchange.

1183Figure 3.16 PUBREL Packet fixed header
Bit
byte 1

0
byte 2
Reserved
0

0
1184
73mqtt-v3.1.1-os
29 October 2014
Page 37 of 80
1185Bits 3,2,1 and 0 of the fixed header in the PUBREL Control Packet are reserved and MUST be set to
11860,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network
1188
1190This is the length of the variable header. For the PUBREL Packet this has the value 2.

1192The variable header contains the same Packet Identifier as the PUBREC Packet that is being
1193acknowledged.
1194Figure 3.17 PUBREL Packet variable header
Bit
byte 1
byte 2
1195
11963.6.3 Payload
1197The PUBREL Packet has no payload.
11983.6.4 Actions
12003.7 PUBCOMP Publish complete (QoS 2 publish received, part 3)

1201
1202The PUBCOMP Packet is the response to a PUBREL Packet. It is the fourth and final packet of the QoS 2
1203protocol exchange.

1205Figure 3.18 PUBCOMP Packet fixed header
Bit
byte 1

0
byte 2
Reserved
1

0
1206
1208This is the length of the variable header. For the PUBCOMP Packet this has the value 2.
75mqtt-v3.1.1-os
29 October 2014
Page 38 of 80

1210The variable header contains the same Packet Identifier as the PUBREL Packet that is being
1211acknowledged.
1212Figure 3.19 PUBCOMP Packet variable header
Bit
byte 1
byte 2
1213
12143.7.3 Payload
1215The PUBCOMP Packet has no payload.
12163.7.4 Actions
12183.8 SUBSCRIBE - Subscribe to topics

1219The SUBSCRIBE Packet is sent from the Client to the Server to create one or more Subscriptions. Each
1220Subscription registers a Clients interest in one or more Topics. The Server sends PUBLISH Packets to
1221the Client in order to forward Application Messages that were published to Topics that match these
1222Subscriptions. The SUBSCRIBE Packet also specifies (for each Subscription) the maximum QoS with
1223which the Server can send Application Messages to the Client.

1225Figure 3.20 SUBSCRIBE Packet fixed header
Bit
byte 1

1
byte 2
Reserved
Remaining Length
1226
1227Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and MUST be set to
12280,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network
1230
1232
This is the length of variable header (2 bytes) plus the length of the payload.

1234The variable header contains a Packet Identifier. Section 2.3.1 provides more information about Packet
1235Identifiers.
77mqtt-v3.1.1-os
29 October 2014
Page 39 of 80
1236
Figure 3.21 shows a variable header with Packet Identifier set to 10.
1237
1238Figure 3.21 - Variable header with a Packet Identifier of 10, Non normative example
Description
byte 1
Packet Identifier MSB (0)
byte 2
Packet Identifier LSB (10)
Packet Identifier
1239
12403.8.3 Payload
1241The payload of a SUBSCRIBE Packet contains a list of Topic Filters indicating the Topics to which the
1242Client wants to subscribe. The Topic Filters in a SUBSCRIBE packet payload MUST be UTF-8 encoded
1243strings as defined in Section 1.5.3 [MQTT-3.8.3-1]. A Server SHOULD support Topic filters that contain
1244the wildcard characters defined in Section 4.7.1. If it chooses not to support topic filters that contain
1245wildcard characters it MUST reject any Subscription request whose filter contains them [MQTT-3.8.3-2].
1246Each filter is followed by a byte called the Requested QoS. This gives the maximum QoS level at which
1247the Server can send Application Messages to the Client.
1248
1249The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / QoS pair. A SUBSCRIBE
1250packet with no payload is a protocol violation [MQTT-3.8.3-3]. See section 4.8 for information about
1251handling errors.
1252
1253The requested maximum QoS field is encoded in the byte following each UTF-8 encoded topic name, and
1254these Topic Filter / QoS pairs are packed contiguously.
1255
1256Figure 3.22 SUBSCRIBE Packet payload format
Description
Topic Filter
byte 1
Length MSB
byte 2
Length LSB
bytes 3..N
Topic Filter
Requested QoS
Reserved
byte N+1
QoS
0
1257
1258The upper 6 bits of the Requested QoS byte are not used in the current version of the protocol. They are
1259reserved for future use. The Server MUST treat a SUBSCRIBE packet as malformed and close the
1260Network Connection if any of Reserved bits in the payload are non-zero, or QoS is not 0,1 or 2 [MQTT-312618.3-4].
79mqtt-v3.1.1-os
29 October 2014
Page 40 of 80
1262
1263
1264
3.8.3.1 Payload non normative example

Figure 3.23 - Payload byte format non normative example shows the payload for the SUBSCRIBE
Packet briefly described in Table 3.5 - Payload non normative example.
1265
1266Table 3.5 - Payload non normative example
Topic Name
a/b
Requested QoS
0x01
Topic Name
c/d
Requested QoS
0x02
1267Figure 3.23 - Payload byte format non normative example
Description
byte 1
Length MSB (0)
byte 2
Length LSB (3)
byte 3
a (0x61)
byte 4
/ (0x2F)
byte 5
b (0x62)
Requested QoS(1)
byte 7
Length MSB (0)
byte 8
Length LSB (3)
byte 9
c (0x63)
byte 10
/ (0x2F)
byte 11
d (0x64)
Requested QoS(2)
Topic Filter
Requested QoS
byte 6
Topic Filter
Requested QoS
byte 12
1268
12693.8.4 Response
1270When the Server receives a SUBSCRIBE Packet from a Client, the Server MUST respond with a
1271SUBACK Packet [MQTT-3.8.4-1]. The SUBACK Packet MUST have the same Packet Identifier as the
1272SUBSCRIBE Packet that it is acknowledging [MQTT-3.8.4-2].
1273
81mqtt-v3.1.1-os
29 October 2014
Page 41 of 80
1274The Server is permitted to start sending PUBLISH packets matching the Subscription before the Server
1275sends the SUBACK Packet.
1276
1277If a Server receives a SUBSCRIBE Packet containing a Topic Filter that is identical to an existing
1278Subscriptions Topic Filter then it MUST completely replace that existing Subscription with a new
1279Subscription. The Topic Filter in the new Subscription will be identical to that in the previous Subscription,
1280although its maximum QoS value could be different. Any existing retained messages matching the Topic
1281Filter MUST be re-sent, but the flow of publications MUST NOT be interrupted [MQTT-3.8.4-3].
1282
1283Where the Topic Filter is not identical to any existing Subscriptions filter, a new Subscription is created
1284and all matching retained messages are sent.
1285
1286If a Server receives a SUBSCRIBE packet that contains multiple Topic Filters it MUST handle that packet
1287as if it had received a sequence of multiple SUBSCRIBE packets, except that it combines their responses
1288into a single SUBACK response [MQTT-3.8.4-4].
1289
1290The SUBACK Packet sent by the Server to the Client MUST contain a return code for each Topic
1291Filter/QoS pair. This return code MUST either show the maximum QoS that was granted for that
1292Subscription or indicate that the subscription failed [MQTT-3.8.4-5]. The Server might grant a lower
1293maximum QoS than the subscriber requested. The QoS of Payload Messages sent in response to a
1294Subscription MUST be the minimum of the QoS of the originally published message and the maximum
1295QoS granted by the Server. The server is permitted to send duplicate copies of a message to a subscriber
1296in the case where the original message was published with QoS 1 and the maximum QoS granted was
1297QoS 0 [MQTT-3.8.4-6].
1298
1299
Non normative examples
1300
1301
1302
1303
1304
1305
If a subscribing Client has been granted maximum QoS 1 for a particular Topic Filter, then a QoS
0 Application Message matching the filter is delivered to the Client at QoS 0. This means that at
most one copy of the message is received by the Client. On the other hand a QoS 2 Message
published to the same topic is downgraded by the Server to QoS 1 for delivery to the Client, so
that Client might receive duplicate copies of the Message.
1307
1308
1309
1310
If the subscribing Client has been granted maximum QoS 0, then an Application Message
originally published as QoS 2 might get lost on the hop to the Client, but the Server should never
send a duplicate of that Message. A QoS 1 Message published to the same topic might either get
lost or duplicated on its transmission to that Client.
1311
1312
1313
1314
1315
1316
Subscribing to a Topic Filter at QoS 2 is equivalent to saying "I would like to receive Messages
matching this filter at the QoS with which they were published". This means a publisher is
responsible for determining the maximum QoS a Message can be delivered at, but a subscriber is
able to require that the Server downgrades the QoS to one more suitable for its usage.
13173.9 SUBACK Subscribe acknowledgement

1318A SUBACK Packet is sent by the Server to the Client to confirm receipt and processing of a SUBSCRIBE
1319Packet.
1320
1321A SUBACK Packet contains a list of return codes, that specify the maximum QoS level that was granted
1322in each Subscription that was requested by the SUBSCRIBE.
83mqtt-v3.1.1-os
29 October 2014
Page 42 of 80

1324Figure 3.24 SUBACK Packet fixed header
Bit
byte 1

1
Reserved
1
byte 2
Remaining Length
1325
1327
This is the length of variable header (2 bytes) plus the length of the payload.

1329The variable header contains the Packet Identifier from the SUBSCRIBE Packet that is being
1330acknowledged. Figure 3.25 - variable header format below illustrates the format of the variable header.
1331Figure 3.25 SUBACK Packet variable header
Bit
byte 1
byte 2
13323.9.3 Payload
1333The payload contains a list of return codes. Each return code corresponds to a Topic Filter in the
1334SUBSCRIBE Packet being acknowledged. The order of return codes in the SUBACK Packet MUST
1335match the order of Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1].
1336
1337Figure 3.26 - Payload format below illustrates the Return Code field encoded in a byte in the Payload.
1338Figure 3.26 SUBACK Packet payload format
Bit
Return Code
byte 1
1339
1340Allowed return codes:
13410x00 - Success - Maximum QoS 0
13440x80 - Failure
1345
1346SUBACK return codes other than 0x00, 0x01, 0x02 and 0x80 are reserved and MUST NOT be
1347used [MQTT-3.9.3-2].
85mqtt-v3.1.1-os
29 October 2014
Page 43 of 80
1348
Figure 3.27 - Payload byte format non normative example shows the payload for the SUBACK
Packet briefly described in Table 3.6 - Payload non normative example.
1349
1350
1351Table 3.6 - Payload non normative example
Success - Maximum QoS 0
Failure
128
Description
byte 1
byte 2
byte 3
Failure
1353
13543.10 UNSUBSCRIBE Unsubscribe from topics

1355An UNSUBSCRIBE Packet is sent by the Client to the Server, to unsubscribe from topics.

1357Figure 3.28 UNSUBSCRIBE Packet Fixed header
Bit
byte 1

1
byte 2
Reserved
Remaining Length
1358
1359Bits 3,2,1 and 0 of the fixed header of the UNSUBSCRIBE Control Packet are reserved and MUST be set
1360to 0,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network
1362
1364This is the length of variable header (2 bytes) plus the length of the payload.

1366The variable header contains a Packet Identifier. Section 2.3.1 provides more information about Packet
1367Identifiers.
1368Figure 3.29 UNSUBSCRIBE Packet variable header
Bit
87mqtt-v3.1.1-os
29 October 2014
Page 44 of 80
byte 1
byte 2
1369
13703.10.3 Payload
1371The payload for the UNSUBSCRIBE Packet contains the list of Topic Filters that the Client wishes to
1372unsubscribe from. The Topic Filters in an UNSUBSCRIBE packet MUST be UTF-8 encoded strings as
1373defined in Section 1.5.3, packed contiguously [MQTT-3.10.3-1].
1374The Payload of an UNSUBSCRIBE packet MUST contain at least one Topic Filter. An UNSUBSCRIBE
1375packet with no payload is a protocol violation [MQTT-3.10.3-2]. See section 4.8 for information about
1376handling errors.
1377
1378
1379
1380

Figure 3.30 - Payload byte format non normative example show the payload for the
UNSUBSCRIBE Packet briefly described in Table3.7 - Payload non normative example.
1381Table3.7 - Payload non normative example
Topic Filter
a/b
Topic Filter
c/d
Description
byte 1
Length MSB (0)
byte 2
Length LSB (3)
byte 3
a (0x61)
byte 4
/ (0x2F)
byte 5
b (0x62)
byte 6
Length MSB (0)
byte 7
Length LSB (3)
byte 8
c (0x63)
byte 9
/ (0x2F)
byte 10
d (0x64)
Topic Filter
Topic Filter
13833.10.4 Response
1384The Topic Filters (whether they contain wildcards or not) supplied in an UNSUBSCRIBE packet MUST be
1385compared character-by-character with the current set of Topic Filters held by the Server for the Client. If
1386any filter matches exactly then its owning Subscription is deleted, otherwise no additional processing
89mqtt-v3.1.1-os
29 October 2014
Page 45 of 80
1387occurs [MQTT-3.10.4-1].
1389If a Server deletes a Subscription:
1390
1391
It MUST stop adding any new messages for delivery to the Client [MQTT-3.10.4-2].
It MUST complete the delivery of any QoS 1 or QoS 2 messages which it has started to send to
the Client [MQTT-3.10.4-3].
It MAY continue to deliver any existing messages buffered for delivery to the Client.
1392
1393
1394
1395The Server MUST respond to an UNSUBSUBCRIBE request by sending an UNSUBACK packet. The
1396UNSUBACK Packet MUST have the same Packet Identifier as the UNSUBSCRIBE Packet [MQTT13973.10.4-4]. Even where no Topic Subscriptions are deleted, the Server MUST respond with an UNSUBACK
1398[MQTT-3.10.4-5].
1399
1400If a Server receives an UNSUBSCRIBE packet that contains multiple Topic Filters it MUST handle that
1401packet as if it had received a sequence of multiple UNSUBSCRIBE packets, except that it sends just one
1402UNSUBACK response [MQTT-3.10.4-6].
14033.11 UNSUBACK Unsubscribe acknowledgement

1404
1405The UNSUBACK Packet is sent by the Server to the Client to confirm receipt of an UNSUBSCRIBE
1406Packet.

1408Figure 3.31 UNSUBACK Packet fixed header
Bit
byte 1

1
byte 2
Reserved
1

0

1410
This is the length of the variable header. For the UNSUBACK Packet this has the value 2.

1412The variable header contains the Packet Identifier of the UNSUBSCRIBE Packet that is being
1413acknowledged.
1414Figure 3.32 UNSUBACK Packet variable header
Bit
byte 1
byte 2
1415
91mqtt-v3.1.1-os
29 October 2014
Page 46 of 80
14163.11.3 Payload
1417The UNSUBACK Packet has no payload.
1418
14193.12 PINGREQ PING request

1420The PINGREQ Packet is sent from a Client to the Server. It can be used to:
1421
1422
1. Indicate to the Server that the Client is alive in the absence of any other Control Packets being
sent from the Client to the Server.
1423
2. Request that the Server responds to confirm that it is alive.
1424
3. Exercise the network to indicate that the Network Connection is active.
1425
1426This Packet is used in Keep Alive processing, see Section 3.1.2.10 for more details.

1428Figure 3.33 PINGREQ Packet fixed header
Bit
byte 1

1
byte 2
Reserved
0

0
1429

1431The PINGREQ Packet has no variable header.
14323.12.3 Payload
1433The PINGREQ Packet has no payload.
14343.12.4 Response
1435The Server MUST send a PINGRESP Packet in response to a PINGREQ Packet [MQTT-3.12.4-1].
14363.13 PINGRESP PING response

1437A PINGRESP Packet is sent by the Server to the Client in response to a PINGREQ Packet. It indicates
1438that the Server is alive.
1439
1440This Packet is used in Keep Alive processing, see Section 3.1.2.10 for more details.

1442Figure 3.34 PINGRESP Packet fixed header
Bit
93mqtt-v3.1.1-os
0
29 October 2014
Page 47 of 80
byte 1

1
byte 2
Reserved
1

0
1443

1445The PINGRESP Packet has no variable header.
14463.13.3 Payload
1447The PINGRESP Packet has no payload.
14483.14 DISCONNECT Disconnect notification

1449The DISCONNECT Packet is the final Control Packet sent from the Client to the Server. It indicates that
1450the Client is disconnecting cleanly.

1452Figure 3.35 DISCONNECT Packet fixed header
Bit
byte 1

1
byte 2
Reserved
0

0
1453The Server MUST validate that reserved bits are set to zero and disconnect the Client if they are not zero
1454[MQTT-3.14.1-1].

1456The DISCONNECT Packet has no variable header.
14573.14.3 Payload
1458The DISCONNECT Packet has no payload.
14593.14.4 Response
1460After sending a DISCONNECT Packet the Client:
1461
1462
MUST close the Network Connection [MQTT-3.14.4-1].
MUST NOT send any more Control Packets on that Network Connection [MQTT-3.14.4-2].
1463
1464On receipt of DISCONNECT the Server:
1465
1466
MUST discard any Will Message associated with the current connection without publishing it, as
described in Section 3.1.2.5 [MQTT-3.14.4-3].
95mqtt-v3.1.1-os
29 October 2014
Page 48 of 80
1467
SHOULD close the Network Connection if the Client has not already done so.
97mqtt-v3.1.1-os
29 October 2014
Page 49 of 80
14684
Operational behavior
14694.1 Storing state

1470It is necessary for the Client and Server to store Session state in order to provide Quality of Service
1471guarantees. The Client and Server MUST store Session state for the entire duration of the Session
1472[MQTT-4.1.0-1]. A Session MUST last at least as long it has an active Network Connection [MQTT-4.1.014732].
1474
1475Retained messages do not form part of the Session state in the Server. The Server SHOULD retain such
1476messages until deleted by a Client.
1477
1478
1479
1480
1481
1482
1483
1484
1485
The storage capabilities of Client and Server implementations will of course have limits in terms
of capacity and may be subject to administrative policies such as the maximum time that Session
state is stored between Network Connections. Stored Session state can be discarded as a result
of an administrator action, including an automated response to defined conditions. This has the
effect of terminating the Session. These actions might be prompted by resource constraints or for
other operational reasons. It is prudent to evaluate the storage capabilities of the Client and
Server to ensure that they are sufficient.
1486
1487
1488
1489
It is possible that hardware or software failures may result in loss or corruption of Session state
stored by the Client or Server.
1490
1491
1492
1493
1494
1495
1496
1497
Normal operation of the Client of Server could mean that stored state is lost or corrupted because
of administrator action, hardware failure or software failure. An administrator action could be an
automated response to defined conditions. These actions might be prompted by resource
constraints or for other operational reasons. For example the server might determine that based
on external knowledge, a message or messages can no longer be delivered to any current or
future client.
1498
1499
1500
1501
An MQTT user should evaluate the storage capabilities of the MQTT Client and Server
implementations to ensure that they are sufficient for their needs.
1502
15034.1.1 Non normative example

1504For example, a user wishing to gather electricity meter readings may decide that they need to use QoS 1
1505messages because they need to protect the readings against loss over the network, however they may
1506have determined that the power supply is sufficiently reliable that the data in the Client and Server can be
1507stored in volatile memory without too much risk of its loss.
1508Conversely a parking meter payment application provider might decide that there are no circumstances
1509where a payment message can be lost so they require that all data are force written to non-volatile
1510memory before it is transmitted across the network.
99mqtt-v3.1.1-os
29 October 2014
Page 50 of 80
15114.2 Network Connections

1512The MQTT protocol requires an underlying transport that provides an ordered, lossless, stream of bytes
1513from the Client to Server and Server to Client.
1514
1515
1516
1517
The transport protocol used to carry MQTT 3.1 was TCP/IP as defined in [RFC793]. TCP/IP can
be used for MQTT 3.1.1. The following are also suitable:
1518
1519
TLS [RFC5246]
WebSocket [RFC6455]
1520
1521
1522
TCP ports 8883 and 1883 are registered with IANA for MQTT TLS and non TLS communication
respectively.
1523
1524Connectionless network transports such as User Datagram Protocol (UDP) are not suitable on their own
1525because they might lose or reorder data.
15264.3 Quality of Service levels and protocol flows

1527MQTT delivers Application Messages according to the Quality of Service (QoS) levels defined here. The
1528delivery protocol is symmetric, in the description below the Client and Server can each take the role of
1529either Sender or Receiver. The delivery protocol is concerned solely with the delivery of an application
1530message from a single Sender to a single Receiver. When the Server is delivering an Application
1531Message to more than one Client, each Client is treated independently. The QoS level used to deliver an
1532Application Message outbound to the Client could differ from that of the inbound Application Message.
1533The non-normative flow diagrams in the following sections are intended to show possible implementation
1534approaches.
15354.3.1 QoS 0: At most once delivery

1536The message is delivered according to the capabilities of the underlying network. No response is sent by
1537the receiver and no retry is performed by the sender. The message arrives at the receiver either once or
1538not at all.
1539
1540In the QoS 0 delivery protocol, the Sender
1541
MUST send a PUBLISH packet with QoS=0, DUP=0 [MQTT-4.3.1-1].
1542
1543In the QoS 0 delivery protocol, the Receiver
1544
1545
Accepts ownership of the message when it receives the PUBLISH packet.

Figure 4.1 QoS 0 protocol flow diagram, non normative example
Sender Action
Control Packet
Receiver Action
PUBLISH QoS 0, DUP=0

---------->
Deliver Application Message to
appropriate onward recipient(s)
101mqtt-v3.1.1-os
29 October 2014
Page 51 of 80
15464.3.2 QoS 1: At least once delivery

1547This quality of service ensures that the message arrives at the receiver at least once. A QoS 1 PUBLISH
1548Packet has a Packet Identifier in its variable header and is acknowledged by a PUBACK Packet. Section
15492.3.1 provides more information about Packet Identifiers.
1550
1552
1553
1554
MUST assign an unused Packet Identifier each time it has a new Application Message to publish.
MUST send a PUBLISH Packet containing this Packet Identifier with QoS=1, DUP=0.
MUST treat the PUBLISH Packet as unacknowledged until it has received the corresponding
PUBACK packet from the receiver. See Section 4.4 for a discussion of unacknowledged
messages.
1555
1556
1557 [MQTT-4.3.2-1].
1558 The Packet Identifier becomes available for reuse once the Sender has received the PUBACK Packet.
1559
1560Note that a Sender is permitted to send further PUBLISH Packets with different Packet Identifiers while it
1561is waiting to receive acknowledgements.
1562
1564
MUST respond with a PUBACK Packet containing the Packet Identifier from the incoming
PUBLISH Packet, having accepted ownership of the Application Message
After it has sent a PUBACK Packet the Receiver MUST treat any incoming PUBLISH packet that
contains the same Packet Identifier as being a new publication, irrespective of the setting of its
DUP flag.
1565
1566
1567
1568
1569 [MQTT-4.3.2-2].
1570
1571

Sender Action
Control Packet
Receiver action
Store message
Send PUBLISH QoS 1, DUP 0,
<Packet Identifier>
---------->
Initiate onward delivery of the
Application Message1
<----------
Send PUBACK <Packet

Identifier>
Discard message
1572
1573
1574
1575
The receiver is not required to complete delivery of the Application Message before sending the
PUBACK. When its original sender receives the PUBACK packet, ownership of the Application
Message is transferred to the receiver.
1576
103mqtt-v3.1.1-os
29 October 2014
Page 52 of 80
15774.3.3 QoS 2: Exactly once delivery

1578This is the highest quality of service, for use when neither loss nor duplication of messages are
1579acceptable. There is an increased overhead associated with this quality of service.
1580
1581A QoS 2 message has a Packet Identifier in its variable header. Section 2.3.1 provides more information
1582about Packet Identifiers. The receiver of a QoS 2 PUBLISH Packet acknowledges receipt with a two-step
1583acknowledgement process.
1584
1586
1587
1588
MUST assign an unused Packet Identifier when it has a new Application Message to publish.
MUST send a PUBLISH packet containing this Packet Identifier with QoS=2, DUP=0.
MUST treat the PUBLISH packet as unacknowledged until it has received the corresponding
PUBREC packet from the receiver. See Section 4.4 for a discussion of unacknowledged
messages.
MUST send a PUBREL packet when it receives a PUBREC packet from the receiver. This
PUBREL packet MUST contain the same Packet Identifier as the original PUBLISH packet.
MUST treat the PUBREL packet as unacknowledged until it has received the corresponding
PUBCOMP packet from the receiver.
MUST NOT re-send the PUBLISH once it has sent the corresponding PUBREL packet.
1589
1590
1591
1592
1593
1594
1595
1596[MQTT-4.3.3-1].
1597The Packet Identifier becomes available for reuse once the Sender has received the PUBCOMP Packet.
1598
1599Note that a Sender is permitted to send further PUBLISH Packets with different Packet Identifiers while it
1600is waiting to receive acknowledgements.
1601
1603
MUST respond with a PUBREC containing the Packet Identifier from the incoming PUBLISH
Packet, having accepted ownership of the Application Message.
Until it has received the corresponding PUBREL packet, the Receiver MUST acknowledge any
subsequent PUBLISH packet with the same Packet Identifier by sending a PUBREC. It MUST
NOT cause duplicate messages to be delivered to any onward recipients in this case.
MUST respond to a PUBREL packet by sending a PUBCOMP packet containing the same Packet
Identifier as the PUBREL.
After it has sent a PUBCOMP, the receiver MUST treat any subsequent PUBLISH packet that
contains that Packet Identifier as being a new publication.
1604
1605
1606
1607
1608
1609
1610
1611
1612[MQTT-4.3.3-2].
1613
1614

Sender Action
Control Packet
Receiver Action
Store message
PUBLISH QoS 2, DUP 0
<Packet Identifier>
105mqtt-v3.1.1-os
29 October 2014
Page 53 of 80
---------->
Method A, Store message
or
Method B, Store <Packet
Identifier> then Initiate onward
delivery of the Application
Message1
PUBREC <Packet Identifier>
<---------Discard message, Store
PUBREC received <Packet
Identifier>
PUBREL <Packet Identifier>
---------->
Method A, Initiate onward
delivery of the Application
Message1 then discard
message
or
Method B, Discard <Packet
Identifier>
Send PUBCOMP <Packet
Identifier>
<---------Discard stored state
1615
1616
1617
1618
1619
1620
1621
1622
The receiver is not required to complete delivery of the Application Message before sending the
PUBREC or PUBCOMP. When its original sender receives the PUBREC packet, ownership of the
Application Message is transferred to the receiver.
Figure 4.3 shows that there are two methods by which QoS 2 can be handled by the receiver. They
differ in the point within the flow at which the message is made available for onward delivery. The
choice of Method A or Method B is implementation specific. As long as an implementation chooses
exactly one of these approaches, this does not affect the guarantees of a QoS 2 flow.
1623
16244.4 Message delivery retry

1625When a Client reconnects with CleanSession set to 0, both the Client and Server MUST re-send any
1626unacknowledged PUBLISH Packets (where QoS > 0) and PUBREL Packets using their original Packet
1627Identifiers [MQTT-4.4.0-1]. This is the only circumstance where a Client or Server is REQUIRED to
1628redeliver messages.
1629
1630
1631
1632
1633

Historically retransmission of Control Packets was required to overcome data loss on some older
TCP networks. This might remain a concern where MQTT 3.1.1 implementations are to be
deployed in such environments.
107mqtt-v3.1.1-os
29 October 2014
Page 54 of 80
16344.5 Message receipt

1635When a Server takes ownership of an incoming Application Message it MUST add it to the Session state
1636of those clients that have matching Subscriptions. Matching rules are defined in Section 4.7 [MQTT-4.5.016371].
1638Under normal circumstances Clients receive messages in response to Subscriptions they have created. A
1639Client could also receive messages that do not match any of its explicit Subscriptions. This can happen if
1640the Server automatically assigned a subscription to the Client. A Client could also receive messages while
1641an UNSUBSCRIBE operation is in progress. The Client MUST acknowledge any Publish Packet it
1642receives according to the applicable QoS rules regardless of whether it elects to process the Application
1643Message that it contains [MQTT-4.5.0-2].
16444.6 Message ordering

1645A Client MUST follow these rules when implementing the protocol flows defined elsewhere in this chapter:
1646
When it re-sends any PUBLISH packets, it MUST re-send them in the order in which the original
PUBLISH packets were sent (this applies to QoS 1 and QoS 2 messages) [MQTT-4.6.0-1]
It MUST send PUBACK packets in the order in which the corresponding PUBLISH packets were
received (QoS 1 messages) [MQTT-4.6.0-2]
It MUST send PUBREC packets in the order in which the corresponding PUBLISH packets were
It MUST send PUBREL packets in the order in which the corresponding PUBREC packets were
1647
1648
1649
1650
1651
1652
1653
1654
1655A Server MUST by default treat each Topic as an "Ordered Topic". It MAY provide an administrative or
1656other mechanism to allow one or more Topics to be treated as an "Unordered Topic" [MQTT-4.6.0-5].
1657
1658When a Server processes a message that has been published to an Ordered Topic, it MUST follow the
1659rules listed above when delivering messages to each of its subscribers. In addition it MUST send
1660PUBLISH packets to consumers (for the same Topic and QoS) in the order that they were received from
1661any given Client [MQTT-4.6.0-6].
1662
1663
1664
1665
1666
1667
1668
1669
The rules listed above ensure that when a stream of messages is published and subscribed to
with QoS 1, the final copy of each message received by the subscribers will be in the order that
they were originally published in, but the possibility of message duplication could result in a resend of an earlier message being received after one of its successor messages. For example a
publisher might send messages in the order 1,2,3,4 and the subscriber might receive them in the
order 1,2,3,2,3,4.
1670
1671
1672
1673
1674
1675
1676
If both Client and Server make sure that no more than one message is in-flight at any one time
(by not sending a message until its predecessor has been acknowledged), then no QoS 1
message will be received after any later one - for example a subscriber might receive them in the
order 1,2,3,3,4 but not 1,2,3,2,3,4. Setting an in-flight window of 1 also means that order will be
preserved even if the publisher sends a sequence of messages with different QoS levels on the
same topic.
109mqtt-v3.1.1-os
29 October 2014
Page 55 of 80
16774.7 Topic Names and Topic Filters

16784.7.1 Topic wildcards
1679The topic level separator is used to introduce structure into the Topic Name. If present, it divides the Topic
1680Name into multiple topic levels.
1681A subscriptions Topic Filter can contain special wildcard characters, which allow you to subscribe to
1682multiple topics at once.
1683The wildcard characters can be used in Topic Filters, but MUST NOT be used within a Topic Name
1684[MQTT-4.7.1-1].
1685
4.7.1.1 Topic level separator
1686The forward slash (/ U+002F) is used to separate each level within a topic tree and provide a hierarchical
1687structure to the Topic Names. The use of the topic level separator is significant when either of the two
1688wildcard characters is encountered in Topic Filters specified by subscribing Clients. Topic level separators
1689can appear anywhere in a Topic Filter or Topic Name. Adjacent Topic level separators indicate a zero
1690length topic level.
1691
4.7.1.2 Multi-level wildcard
1692The number sign (# U+0023) is a wildcard character that matches any number of levels within a topic.
1693The multi-level wildcard represents the parent and any number of child levels. The multi-level wildcard
1694character MUST be specified either on its own or following a topic level separator. In either case it MUST
1695be the last character specified in the Topic Filter [MQTT-4.7.1-2].
1696
1697
1698
1699
For example, if a Client subscribes to sport/tennis/player1/#, it would receive messages

published using these topic names:
1700
1701
1702
sport/tennis/player1
sport/tennis/player1/ranking
sport/tennis/player1/score/wimbledon
1703
1704
1705
1706
1707
1708
1709
1710
sport/# also matches the singular sport, since # includes the parent level.
# is valid and will receive every Application Message
sport/tennis/# is valid
sport/tennis# is not valid
sport/tennis/#/ranking is not valid
4.7.1.3 Single level wildcard
1711The plus sign (+ U+002B) is a wildcard character that matches only one topic level.
1712
1713The single-level wildcard can be used at any level in the Topic Filter, including first and last levels. Where
1714it is used it MUST occupy an entire level of the filter [MQTT-4.7.1-3]. It can be used at more than one level
1715in the Topic Filter and can be used in conjunction with the multilevel wildcard.
1716
1717
111mqtt-v3.1.1-os
29 October 2014
Page 56 of 80
1718
1719
1720
For example, sport/tennis/+ matches sport/tennis/player1 and sport/tennis/player2, but not

sport/tennis/player1/ranking. Also, because the single-level wildcard matches only a single level,
sport/+ does not match sport but it does match sport/.
1721
1722
1723
1724
1725
1726
1727
+ is valid
+/tennis/# is valid
sport+ is not valid
sport/+/player1 is valid
/finance matches +/+ and /+, but not +
17284.7.2 Topics beginning with $

1729The Server MUST NOT match Topic Filters starting with a wildcard character (# or +) with Topic Names
1730beginning with a $ character [MQTT-4.7.2-1]. The Server SHOULD prevent Clients from using such Topic
1731Names to exchange messages with other Clients. Server implementations MAY use Topic Names that
1732start with a leading $ character for other purposes.
1733
1734
1735
$SYS/ has been widely adopted as a prefix to topics that contain Server-specific
information or control APIs
Applications cannot use a topic with a leading $ character for their own purposes
1736
1737
1738
1739
1740
A subscription to # will not receive any messages published to a topic beginning with a
$
A subscription to +/monitor/Clients will not receive any messages published to

$SYS/monitor/Clients
A subscription to $SYS/# will receive messages published to topics beginning with

$SYS/
A subscription to $SYS/monitor/+ will receive messages published to

$SYS/monitor/Clients
For a Client to receive messages from topics that begin with $SYS/ and from topics that
dont begin with a $, it has to subscribe to both # and $SYS/#
1741
1742
1743
1744
1745
1746
1747
1748
1749
17504.7.3 Topic semantic and usage

1751The following rules apply to Topic Names and Topic Filters:
1752
1753
1754
1755
1756
1757
1758
All Topic Names and Topic Filters MUST be at least one character long [MQTT-4.7.3-1]
Topic Names and Topic Filters are case sensitive
Topic Names and Topic Filters can include the space character
A leading or trailing / creates a distinct Topic Name or Topic Filter
A Topic Name or Topic Filter consisting only of the / character is valid
Topic Names and Topic Filters MUST NOT include the null character (Unicode U+0000)
[Unicode] [MQTT-4.7.3-2]
113mqtt-v3.1.1-os
29 October 2014
Page 57 of 80
1759
1760
Topic Names and Topic Filters are UTF-8 encoded strings, they MUST NOT encode to more than
65535 bytes [MQTT-4.7.3-3]. See Section 1.5.3
1761There is no limit to the number of levels in a Topic Name or Topic Filter, other than that imposed by the
1762overall length of a UTF-8 encoded string.
1763When it performs subscription matching the Server MUST NOT perform any normalization of Topic
1764Names or Topic Filters, or any modification or substitution of unrecognized characters [MQTT-4.7.3-4].
1765Each non-wildcarded level in the Topic Filter has to match the corresponding level in the Topic Name
1766character for character for the match to succeed.
1767
1768
1769
1770
1771
The UTF-8 encoding rules mean that the comparison of Topic Filter and Topic Name could be
performed either by comparing the encoded UTF-8 bytes, or by comparing decoded Unicode
characters
1772
1773
1774
1775
1776
ACCOUNTS and Accounts are two different topic names
Accounts payable is a valid topic name
/finance is different from finance
1777
1778An Application Message is sent to each Client Subscription whose Topic Filter matches the Topic Name
1779attached to an Application Message. The topic resource MAY be either predefined in the Server by an
1780administrator or it MAY be dynamically created by the Server when it receives the first subscription or an
1781Application Message with that Topic Name. The Server MAY also use a security component to selectively
1782authorize actions on the topic resource for a given Client.
17834.8 Handling errors

1784
1785Unless stated otherwise, if either the Server or Client encounters a protocol violation, it MUST close the
1786Network Connection on which it received that Control Packet which caused the protocol violation [MQTT17874.8.0-1].
1788A Client or Server implementation might encounter a Transient Error (for example an internal buffer full
1789condition) that prevents successful processing of an MQTT packet.
1790If the Client or Server encounters a Transient Error while processing an inbound Control Packet it MUST
1791close the Network Connection on which it received that Control Packet [MQTT-4.8.0-2]. If a Server
1792detects a Transient Error it SHOULD NOT disconnect or have any other effect on its interactions with any
1793other Client.
115mqtt-v3.1.1-os
29 October 2014
Page 58 of 80
17945
Security
17955.1 Introduction
1796This Chapter is provided for guidance only and is Non Normative. However, it is strongly recommended
1797that Server implementations that offer TLS [RFC5246] SHOULD use TCP port 8883 (IANA service name:
1798secure-mqtt).
1799
1800There are a number of threats that solution providers should consider. For example:
1801
1802
1803
1804
1805
1806
Devices could be compromised
Data at rest in Clients and Servers might be accessible
Protocol behaviors could have side effects (e.g. timing attacks)
Denial of Service (DoS) attacks
Communications could be intercepted, altered, re-routed or disclosed
Injection of spoofed Control Packets
1807
1808MQTT solutions are often deployed in hostile communication environments. In such cases,
1809implementations will often need to provide mechanisms for:
1810
1811
1812
1813
Authentication of users and devices
Authorization of access to Server resources
Integrity of MQTT Control Packets and application data contained therein
Privacy of MQTT Control Packets and application data contained therein
1814
1815As a transport protocol, MQTT is concerned only with message transmission and it is the implementers
1816responsibility to provide appropriate security features. This is commonly achieved by using TLS
1817[RFC5246].
1818
1819In addition to technical security issues there could also be geographic (e.g. U.S.-EU SafeHarbor
1820[USEUSAFEHARB]), industry specific (e.g. PCI DSS [PCIDSS]) and regulatory considerations (e.g.
1821Sarbanes-Oxley [SARBANES]).
18225.2 MQTT solutions: security and certification

1823An implementation might want to provide conformance with specific industry security standards such as
1824NIST Cyber Security Framework [NISTCSF], PCI-DSS [PCIDSS]), FIPS-140-2 [FIPS1402] and NSA
1825Suite B [NSAB].
1826Guidance on using MQTT within the NIST Cyber Security Framework [NISTCSF] can be found in the
1827MQTT supplemental publication, MQTT and the NIST Framework for Improving Critical Infrastructure
1828Cybersecurity [MQTT NIST]. The use of industry proven, independently verified and certified
1829technologies will help meet compliance requirements.
18305.3 Lightweight cryptography and constrained devices

1831Advanced Encryption Standard [AES] and Data Encryption Standard [DES] are widely adopted.
1832
117mqtt-v3.1.1-os
29 October 2014
Page 59 of 80
1833ISO 29192 [ISO29192] makes recommendations for cryptographic primitives specifically tuned to
1834perform on constrained low end devices.
18355.4 Implementation notes

1836There are many security concerns to consider when implementing or using MQTT. The following section
1837should not be considered a check list.
1838
1839An implementation might want to achieve some, or all, of the following:
18405.4.1 Authentication of Clients by the Server

1841The CONNECT Packet contains Username and Password fields. Implementations can choose how to
1842make use of the content of these fields. They may provide their own authentication mechanism, use an
1843external authentication system such as LDAP [RFC4511] or OAuth [RFC6749] tokens, or leverage
1844operating system authentication mechanisms.
1845
1846Implementations passing authentication data in clear text, obfuscating such data elements or requiring no
1847authentication data should be aware this can give rise to Man-in-the-Middle and replay attacks. Section
18485.4.5 introduces approaches to ensure data privacy.
1849
1850A Virtual Private Network (VPN) between the Clients and Servers can provide confidence that data is only
1851being received from authorized Clients.
1852
1853Where TLS [RFC5246] is used, SSL Certificates sent from the Client can be used by the Server to
1854authenticate the Client.
1855
1856An implementation might allow for authentication where the credentials are sent in an Application
1857Message from the Client to the Server.
18585.4.2 Authorization of Clients by the Server

1859An implementation may restrict access to Server resources based on information provided by the Client
1860such as User Name, Client Identifier, the hostname/IP address of the Client, or the outcome of
1861authentication mechanisms.
18625.4.3 Authentication of the Server by the Client

1863The MQTT protocol is not trust symmetrical: it provides no mechanism for the Client to authenticate the
1864Server.
1865
1866Where TLS [RFC5246] is used, SSL Certificates sent from the Server can be used by the Client to
1867authenticate the Server. Implementations providing MQTT service for multiple hostnames from a single IP
1868address should be aware of the Server Name Indication extension to TLS defined in section 3 of RFC
18696066 [RFC6066].This allows a Client to tell the Server the hostname of the Server it is trying to connect
1870to.
1871
1872An implementation might allow for authentication where the credentials are sent in an Application
1873Message from the Server to the Client.
1874
1875A VPN between Clients and Servers can provide confidence that Clients are connecting to the intended
1876Server.
119mqtt-v3.1.1-os
29 October 2014
Page 60 of 80
18775.4.4 Integrity of Application Messages and Control Packets

1878Applications can independently include hash values in their Application Messages. This can provide
1879integrity of the contents of Publish Control Packets across the network and at rest.
1880
1881TLS [RFC5246] provides hash algorithms to verify the integrity of data sent over the network.
1882
1883The use of VPNs to connect Clients and Servers can provide integrity of data across the section of the
1884network covered by a VPN.
18855.4.5 Privacy of Application Messages and Control Packets

1886TLS [RFC5246] can provide encryption of data sent over the network. There are valid TLS cipher suites
1887that include a NULL encryption algorithm that does not encrypt data. To ensure privacy Clients and
1888Servers should avoid these cipher suites.
1889
1890An application might independently encrypt the contents of its Application Messages. This could provide
1891privacy of the Application Message both over the network and at rest. This would not provide privacy for
1892other properties of the Application Message such as Topic Name.
1893
1894Client and Server implementations can provide encrypted storage for data at rest such as Application
1895Messages stored as part of a Session.
1896
1897The use of VPNs to connect Clients and Servers can provide privacy of data across the section of the
1898network covered by a VPN.
18995.4.6 Non-repudiation of message transmission

1900Application designers might need to consider appropriate strategies to achieve end to end non1901repudiation.
19025.4.7 Detecting compromise of Clients and Servers

1903Client and Server implementations using TLS [RFC5246] should provide capabilities to ensure that any
1904SSL certificates provided when initiating a TLS [RFC5246] connection are associated with the hostname
1905of the Client connecting or Server being connected to.
1906
1907Client and Server implementations using TLS [RFC5246] can choose to provide capabilities to check
1908Certificate Revocation Lists (CRLs [RFC5280]) and Online Certificate Status Protocol (OSCP)
1909[RFC6960] to prevent revoked certificates from being used.
1910
1911Physical deployments might combine tamper-proof hardware with the transmission of specific data in
1912Application Messages. For example a meter might have an embedded GPS to ensure it is not used in an
1913unauthorized location. [IEEE 802.1AR] is a standard for implementing mechanisms to authenticate a
1914devices identity using a cryptographically bound identifier.
19155.4.8 Detecting abnormal behaviors

1916Server implementations might monitor Client behavior to detect potential security incidents. For example:
1917
1918
Repeated connection attempts
Repeated authentication attempts
121mqtt-v3.1.1-os
29 October 2014
Page 61 of 80
1919
1920
1921
1922
Abnormal termination of connections
Topic scanning (attempts to send or subscribe to many topics)
Sending undeliverable messages (no subscribers to the topics)
Clients that connect but do not send data
1923
1924Server implementations might disconnect Clients that breach its security rules.
1925
1926Server implementations detecting unwelcome behavior might implement a dynamic block list based on
1927identifiers such as IP address or Client Identifier.
1928
1929Deployments might use network level controls (where available) to implement rate limiting or blocking
1930based on IP address or other information.
19315.4.9 Other security considerations

1932If Client or Server SSL certificates are lost or it is considered that they might be compromised they should
1933be revoked (utilizing CRLs [RFC5280] and/or OSCP [RFC6960]).
1934
1935Client or Server authentication credentials, such as User Name and Password, that are lost or considered
1936compromised should be revoked and/or reissued.
1937
1938In the case of long lasting connections:
1939
Client and Server implementations using TLS [RFC5246] should allow for session renegotiation
to establish new cryptographic parameters (replace session keys, change cipher suites, change
authentication credentials).
Servers may disconnect Clients and require them to re-authenticate with new credentials.
1940
1941
1942
1943
1944Constrained devices and Clients on constrained networks can make use of TLS session resumption
1945[RFC5077], in order to reduce the costs of reconnecting TLS [RFC5246] sessions.
1946
1947Clients connected to a Server have a transitive trust relationship with other Clients connected to the same
1948Server and who have authority to publish data on the same topics.
19495.4.10 Use of SOCKS

1950Implementations of Clients should be aware that some environments will require the use of SOCKSv5
1951[RFC1928] proxies to make outbound Network Connections. Some MQTT implementations could make
1952use of alternative secured tunnels (e.g. SSH) through the use of SOCKS. Where implementations choose
1953to use SOCKS, they should support both anonymous and user-name password authenticating SOCKS
1954proxies. In the latter case, implementations should be aware that SOCKS authentication might occur in
1955plain-text and so should avoid using the same credentials for connection to a MQTT Server.
19565.4.11 Security profiles

1957Implementers and solution designers might wish to consider security as a set of profiles which can be
1958applied to the MQTT protocol. An example of a layered security hierarchy is presented below.
123mqtt-v3.1.1-os
29 October 2014
Page 62 of 80
1959
5.4.11.1 Clear communication profile
1960When using the clear communication profile, the MQTT protocol runs over an open network with no
1961additional secure communication mechanisms in place.
1962
5.4.11.2 Secured network communication profile
1963When using the secured network communication profile, the MQTT protocol runs over a physical or virtual
1964network which has security controls e.g., VPNs or physically secure network.
1965
5.4.11.3 Secured transport profile
1966When using the secured transport profile, the MQTT protocol runs over a physical or virtual network and
1967using TLS [RFC5246] which provides authentication, integrity and privacy.
1968
1969TLS [RFC5246] Client authentication can be used in addition to or in place of MQTT Client
1970authentication as provided by the Username and Password fields.
1971
5.4.11.4 Industry specific security profiles
1972It is anticipated that the MQTT protocol will be designed into industry specific application profiles, each
1973defining a threat model and the specific security mechanisms to be used to address these threats.
1974Recommendations for specific security mechanisms will often be taken from existing works including:
1975
1976[NISTCSF] NIST Cyber Security Framework
1977[NIST7628] NISTIR 7628 Guidelines for Smart Grid Cyber Security
1978[FIPS1402] Security Requirements for Cryptographic Modules (FIPS PUB 140-2)
1979[PCIDSS] PCI-DSS Payment Card Industry Data Security Standard
1980[NSAB] NSA Suite B Cryptography
125mqtt-v3.1.1-os
29 October 2014
Page 63 of 80
19816
Using WebSocket as a network transport
1982If MQTT is transported over a WebSocket [RFC6455] connection, the following conditions apply:
1983
MQTT Control Packets MUST be sent in WebSocket binary data frames. If any other type of data
frame is received the recipient MUST close the Network Connection [MQTT-6.0.0-1].
A single WebSocket data frame can contain multiple or partial MQTT Control Packets. The
receiver MUST NOT assume that MQTT Control Packets are aligned on WebSocket frame
boundaries [MQTT-6.0.0-2].
The client MUST include mqtt in the list of WebSocket Sub Protocols it offers [MQTT-6.0.0-3].
The WebSocket Sub Protocol name selected and returned by the server MUST be mqtt
[MQTT-6.0.0-4].
The WebSocket URI used to connect the client and server has no impact on the MQTT protocol.
1984
1985
1986
1987
1988
1989
1990
1991
19926.1 IANA Considerations

1993 This specification requests IANA to register the WebSocket MQTT sub-protocol under the WebSocket
1994 Subprotocol Name registry with the following data:
1995
1996Figure 6.1 - IANA WebSocket Identifier
Subprotocol Identifier
mqtt
Subprotocol Common Name
mqtt
Subprotocol Definition
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
1997
127mqtt-v3.1.1-os
29 October 2014
Page 64 of 80
19987
Conformance
1999The MQTT specification defines conformance for MQTT Client implementations and MQTT Server
2000implementations.
2001
2002An MQTT implementation MAY conform as both an MQTT Client and MQTT Server implementation. A
2003Server that both accepts inbound connections and establishes outbound connections to other Servers
2004MUST conform as both an MQTT Client and MQTT Server [MQTT-7.0.0-1].
2005
2006Conformant implementations MUST NOT require the use of any extensions defined outside of this
2007specification in order to interoperate with any other conformant implementation [MQTT-7.0.0-2].
20087.1 Conformance Targets

20097.1.1 MQTT Server
2010An MQTT Server conforms to this specification only if it satisfies all the statements below:
20111. The format of all Control Packets that the Server sends matches the format described in Chapter 2 and
2012Chapter 3.
20132. It follows the Topic matching rules described in Section 4.7.
20143. It satisfies all of the MUST level requirements in the following chapters that are identified except for
2015those that only apply to the Client:
2016
- Chapter 1 - Introduction
2017
- Chapter 2 - MQTT Control Packet format
2018
- Chapter 3 - MQTT Control Packets
2019
- Chapter 4 - Operational behavior
2020
- Chapter 6 - (if MQTT is transported over a WebSocket connection)
2021
- Chapter 7 - Conformance Targets
2022
2023A conformant Server MUST support the use of one or more underlying transport protocols that provide an
2024ordered, lossless, stream of bytes from the Client to Server and Server to Client [MQTT-7.1.1-1]. However
2025conformance does not depend on it supporting any specific transport protocols. A Server MAY support
2026any of the transport protocols listed in Section 4.2, or any other transport protocol that meets the
2027requirements of [MQTT-7.1.1-1].
20287.1.2 MQTT Client

2029An MQTT Client conforms to this specification only if it satisfies all the statements below:
20301. The format of all Control Packets that the Client sends matches the format described in Chapter 2 and
2031Chapter 3.
20322. It satisfies all of the MUST level requirements in the following chapters that are identified except for
2033those that only apply to the Server:
2034
- Chapter 1 - Introduction
2035
- Chapter 2 - MQTT Control Packet format
2036
- Chapter 3 - MQTT Control Packets
2037
- Chapter 4 - Operational behavior
129mqtt-v3.1.1-os
29 October 2014
Page 65 of 80
2038
- Chapter 6 - (if MQTT is transported over a WebSocket connection)
2039
- Chapter 7 - Conformance Targets
2040
2041A conformant Client MUST support the use of one or more underlying transport protocols that provide an
2042ordered, lossless, stream of bytes from the Client to Server and Server to Client [MQTT-7.1.2-1]. However
2043conformance does not depend on it supporting any specific transport protocols. A Client MAY support any
2044of the transport protocols listed in Section 4.2, or any other transport protocol that meets the requirements
2045of [MQTT-7.1.2-1].
131mqtt-v3.1.1-os
29 October 2014
Page 66 of 80
2046Appendix
A. Acknowledgements (non normative)
2047The TC owes special thanks to Dr Andy Stanford-Clark and Arlen Nipper as the original inventors of the
2048MQTT protocol and for their continued support with the standardization process.
2049
2050The following individuals were members of the OASIS Technical Committee during the creation of this
2051specification and their contributions are gratefully acknowledged:
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
Sanjay Aiyagari (VMware, Inc.)
Ben Bakowski (IBM)
Andrew Banks (IBM)
Arthur Barr (IBM)
William Bathurst (Machine-to-Machine Intelligence (M2MI) Corporation)
Ken Borgendale (IBM)
Geoff Brown (Machine-to-Machine Intelligence (M2MI) Corporation)
James Butler (Cimetrics Inc.)
Marco Carrer (Eurotech S.p.A.)
Raphael Cohn (Individual)
Sarah Cooper (Machine-to-Machine Intelligence (M2MI) Corporation)
Richard Coppen (IBM)
AJ Dalola (Telit Communications S.p.A.)
Mark Darbyshire (TIBCO Software Inc.)
Scott deDeugd (IBM)
Paul Duffy (Cisco Systems)
Phili DesAutels (LogMeIn Inc.)
John Fallows (Kaazing)
Pradeep Fernando (WSO2)
Paul Fremantle (WSO2)
Thomas Glover (Cognizant Technology Solutions)
Rahul Gupta (IBM)
Steve Huston (Individual)
Wes Johnson (Eurotech S.p.A.)
Christopher Kelley (Cisco Systems)
David Kemper (TIBCO Software Inc.)
James Kirkland (Red Hat)
Alex Kritikos (Software AG, Inc.)
Louis-P. Lamoureux (Machine-to-Machine Intelligence (M2MI) Corporation)
David Locke (IBM)
Shawn McAllister (Solace Systems)
133mqtt-v3.1.1-os
29 October 2014
Page 67 of 80
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
Dale Moberg (Axway Software)
Manu Namboodiri (Machine-to-Machine Intelligence (M2MI) Corporation)
Peter Niblett (IBM)
Arlen Nipper (Individual)
Julien Niset (Machine-to-Machine Intelligence (M2MI) Corporation)
Mark Nixon (Emerson Process Management)
Nicholas O'Leary (IBM)
Sandor Palfy (LogMeIn Inc.)
Dominik Obermaier (dc-square GmbH)
Pavan Reddy (Cisco Systems)
Andrew Schofield (IBM)
Wadih Shaib (BlackBerry)
Ian Skerrett (Eclipse Foundation)
Joe Speed (IBM)
Allan Stockdill-Mander (IBM)
Gary Stuebing (Cisco Systems)
Steve Upton (IBM)
James Wert jr. (Telit Communications S.p.A.)
T. Wyatt (Individual)
SHAWN XIE (Machine-to-Machine Intelligence (M2MI) Corporation)
Dominik Zajac (dc-square GmbH)
2104
2105Secretary:
2106
Geoff Brown ([email protected]), M2MI
2107
135mqtt-v3.1.1-os
29 October 2014
Page 68 of 80
2108Appendix
2109
B. Mandatory normative statements (non

normative)
2110This Appendix is non-normative and is provided as a convenient summary of the numbered conformance
2111statements found in the main body of this document. See Chapter 7 for a definitive list of conformance
2112requirements.
Normative
Statement Number
Normative Statement
[MQTT-1.5.3-1]
The character data in a UTF-8 encoded string MUST be well-formed UTF-8 as

defined by the Unicode specification [Unicode] and restated in RFC 3629
[RFC3629]. In particular this data MUST NOT include encodings of code points
between U+D800 and U+DFFF. If a Server or Client receives a Control Packet
containing ill-formed UTF-8 it MUST close the Network Connection.
[MQTT-1.5.3-2]
A UTF-8 encoded string MUST NOT include an encoding of the null character
U+0000. If a receiver (Server or Client) receives a Control Packet containing
U+0000 it MUST close the Network Connection.
[MQTT-1.5.3-3]
A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always to be interpreted to

mean U+FEFF ("ZERO WIDTH NO-BREAK SPACE") wherever it appears in a
string and MUST NOT be skipped over or stripped off by a packet receiver.
[MQTT-2.2.2-1]
Where a flag bit is marked as Reserved in Table 2.2 - Flag Bits, it is reserved
for future use and MUST be set to the value listed in that table.
[MQTT-2.2.2-2]
If invalid flags are received, the receiver MUST close the Network Connection.
[MQTT-2.3.1-1]
SUBSCRIBE, UNSUBSCRIBE, and PUBLISH (in cases where QoS > 0) Control
Packets MUST contain a non-zero 16-bit Packet Identifier.
[MQTT-2.3.1-2]
Each time a Client sends a new packet of one of these types it MUST assign it a
currently unused Packet Identifier.
[MQTT-2.3.1-3]
If a Client re-sends a particular Control Packet, then it MUST use the same
Packet Identifier in subsequent re-sends of that packet. The Packet Identifier
becomes available for reuse after the Client has processed the corresponding
acknowledgement packet. In the case of a QoS 1 PUBLISH this is the
corresponding PUBACK; in the case of QO2 it is PUBCOMP. For SUBSCRIBE or
UNSUBSCRIBE it is the corresponding SUBACK or UNSUBACK.
[MQTT-2.3.1-4]
The same conditions [MQTT-2.3.1-3] apply to a Server when it sends a PUBLISH

with QoS >0.
[MQTT-2.3.1-5]
A PUBLISH Packet MUST NOT contain a Packet Identifier if its QoS value is set
to 0.
[MQTT-2.3.1-6]
A PUBACK, PUBREC or PUBREL Packet MUST contain the same Packet

Identifier as the PUBLISH Packet that was originally sent.
[MQTT-2.3.1-7]
Similarly to [MQTT-2.3.1-6], SUBACK and UNSUBACK MUST contain the

Packet Identifier that was used in the corresponding SUBSCRIBE and
UNSUBSCRIBE Packet respectively.
[MQTT-3.1.0-1]
After a Network Connection is established by a Client to a Server, the first Packet

sent from the Client to the Server MUST be a CONNECT Packet.
137mqtt-v3.1.1-os
29 October 2014
Page 69 of 80
[MQTT-3.1.0-2]
The Server MUST process a second CONNECT Packet sent from a Client as a
protocol violation and disconnect the Client.
[MQTT-3.1.2-1]
If the protocol name is incorrect the Server MAY disconnect the Client, or it MAY
continue processing the CONNECT packet in accordance with some other
specification. In the latter case, the Server MUST NOT continue to process the
CONNECT packet in line with this specification.
[MQTT-3.1.2-2]
The Server MUST respond to the CONNECT Packet with a CONNACK return
code 0x01 (unacceptable protocol level) and then disconnect the Client if the
Protocol Level is not supported by the Server.
[MQTT-3.1.2-3]
The Server MUST validate that the reserved flag in the CONNECT Control
Packet is set to zero and disconnect the Client if it is not zero.
[MQTT-3.1.2-4]
If CleanSession is set to 0, the Server MUST resume communications with the

Client based on state from the current Session (as identified by the Client
identifier). If there is no Session associated with the Client identifier the Server
MUST create a new Session. The Client and Server MUST store the Session
after the Client and Server are disconnected.
[MQTT-3.1.2-5]
After the disconnection of a Session that had CleanSession set to 0, the Server
MUST store further QoS 1 and QoS 2 messages that match any subscriptions
that the client had at the time of disconnection as part of the Session state.
[MQTT-3.1.2-6]
If CleanSession is set to 1, the Client and Server MUST discard any previous
Session and start a new one. This Session lasts as long as the Network
Connection. State data associated with this Session MUST NOT be reused in
any subsequent Session.
[MQTT-3.1.2.7]
Retained messages do not form part of the Session state in the Server, they
MUST NOT be deleted when the Session ends.
[MQTT-3.1.2-8]
If the Will Flag is set to 1 this indicates that, if the Connect request is accepted, a
Will Message MUST be stored on the Server and associated with the Network
Connection. The Will Message MUST be published when the Network
Connection is subsequently closed unless the Will Message has been deleted by
the Server on receipt of a DISCONNECT Packet.
[MQTT-3.1.2-9]
If the Will Flag is set to 1, the Will QoS and Will Retain fields in the Connect
Flags will be used by the Server, and the Will Topic and Will Message fields
MUST be present in the payload.
[MQTT-3.1.2-10]
The Will Message MUST be removed from the stored Session state in the Server
once it has been published or the Server has received a DISCONNECT packet
from the Client.
[MQTT-3.1.2-11]
If the Will Flag is set to 0 the Will QoS and Will Retain fields in the Connect Flags
MUST be set to zero and the Will Topic and Will Message fields MUST NOT be
present in the payload.
[MQTT-3.1.2-12]
If the Will Flag is set to 0, a Will Message MUST NOT be published when this
Network Connection ends.
[MQTT-3.1.2-13]
If the Will Flag is set to 0, then the Will QoS MUST be set to 0 (0x00).
[MQTT-3.1.2-14]
If the Will Flag is set to 1, the value of Will QoS can be 0 (0x00), 1 (0x01), or 2
(0x02). It MUST NOT be 3 (0x03).
[MQTT-3.1.2-15]
If the Will Flag is set to 0, then the Will Retain Flag MUST be set to 0.
139mqtt-v3.1.1-os
29 October 2014
Page 70 of 80
[MQTT-3.1.2-16]
If the Will Flag is set to 1 and If Will Retain is set to 0, the Server MUST publish
the Will Message as a non-retained message.
[MQTT-3.1.2-17]
If the Will Flag is set to 1 and If Will Retain is set to 1, the Server MUST publish
the Will Message as a retained message.
[MQTT-3.1.2-18]
If the User Name Flag is set to 0, a user name MUST NOT be present in the
payload.
[MQTT-3.1.2-19]
If the User Name Flag is set to 1, a user name MUST be present in the payload.
[MQTT-3.1.2-20]
If the Password Flag is set to 0, a password MUST NOT be present in the

payload.
[MQTT-3.1.2-21]
If the Password Flag is set to 1, a password MUST be present in the payload.
[MQTT-3.1.2-22]
If the User Name Flag is set to 0, the Password Flag MUST be set to 0.
[MQTT-3.1.2-23]
It is the responsibility of the Client to ensure that the interval between Control
Packets being sent does not exceed the Keep Alive value. In the absence of
sending any other Control Packets, the Client MUST send a PINGREQ Packet.
[MQTT-3.1.2-24]
If the Keep Alive value is non-zero and the Server does not receive a Control
Packet from the Client within one and a half times the Keep Alive time period, it
MUST disconnect the Network Connection to the Client as if the network had
failed.
[MQTT-3.1.3-1]
These fields, if present, MUST appear in the order Client Identifier, Will Topic,
Will Message, User Name, Password.
[MQTT-3.1.3-2]
Each Client connecting to the Server has a unique ClientId. The ClientId MUST
be used by Clients and by Servers to identify state that they hold relating to this
MQTT Session between the Client and the Server.
[MQTT-3.1.3-3]
The Client Identifier (ClientId) MUST be present and MUST be the first field in the
CONNECT packet payload.
[MQTT-3.1.3-4]
The ClientId MUST be a UTF-8 encoded string as defined in Section 1.5.3.
[MQTT-3.1.3-5]
The Server MUST allow ClientIds which are between 1 and 23 UTF-8 encoded
bytes in length, and that contain only the characters
"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXY
Z".
[MQTT-3.1.3-6]
A Server MAY allow a Client to supply a ClientId that has a length of zero bytes.
However if it does so the Server MUST treat this as a special case and assign a
unique ClientId to that Client. It MUST then process the CONNECT packet as if
the Client had provided that unique ClientId.
[MQTT-3.1.3-7]
If the Client supplies a zero-byte ClientId, the Client MUST also set
CleanSession to 1.
[MQTT-3.1.3-8]
If the Client supplies a zero-byte ClientId with CleanSession set to 0, the Server
MUST respond to the CONNECT Packet with a CONNACK return code 0x02
(Identifier rejected) and then close the Network Connection.
[MQTT-3.1.3-9]
If the Server rejects the ClientId it MUST respond to the CONNECT Packet with
a CONNACK return code 0x02 (Identifier rejected) and then close the Network
Connection.
[MQTT-3.1.3-10]
The Will Topic MUST be a UTF-8 encoded string as defined in Section 1.5.3.
141mqtt-v3.1.1-os
29 October 2014
Page 71 of 80
[MQTT-3.1.3-11]
The User Name MUST be a UTF-8 encoded string as defined in Section 1.5.3.
[MQTT-3.1.4-1]
The Server MUST validate that the CONNECT Packet conforms to section 3.1
and close the Network Connection without sending a CONNACK if it does not
conform.
[MQTT-3.1.4-2]
If the ClientId represents a Client already connected to the Server then the
Server MUST disconnect the existing Client.
[MQTT-3.1.4-3]
If CONNECT validation is successful the Server MUST perform the processing of

CleanSession that is described in section 3.1.2.4.
[MQTT-3.1.4-4]
If CONNECT validation is successful the Server MUST acknowledge the

CONNECT Packet with a CONNACK Packet containing a zero return code.
[MQTT-3.1.4-5]
If the Server rejects the CONNECT, it MUST NOT process any data sent by the
Client after the CONNECT Packet.
[MQTT-3.2.0-1]
The first packet sent from the Server to the Client MUST be a CONNACK
Packet.
[MQTT-3.2.2-1]
If the Server accepts a connection with CleanSession set to 1, the Server MUST
set Session Present to 0 in the CONNACK packet in addition to setting a zero
return code in the CONNACK packet.
[MQTT-3.2.2-2]
If the Server accepts a connection with CleanSession set to 0, the value set in
Session Present depends on whether the Server already has stored Session
state for the supplied client ID. If the Server has stored Session state, it MUST
set Session Present to 1 in the CONNACK packet.
[MQTT-3.2.2-3]
If the Server does not have stored Session state, it MUST set Session Present to
0 in the CONNACK packet. This is in addition to setting a zero return code in the
CONNACK packet.
[MQTT-3.2.2-4]
If a server sends a CONNACK packet containing a non-zero return code it MUST

set Session Present to 0.
[MQTT-3.2.2-5]
If a server sends a CONNACK packet containing a non-zero return code it MUST

then close the Network Connection.
[MQTT-3.2.2-6]
If none of the return codes listed in Table 3.1 Connect Return code values are
deemed applicable, then the Server MUST close the Network Connection without
sending a CONNACK.
[MQTT-3.3.1-1]
The DUP flag MUST be set to 1 by the Client or Server when it attempts to redeliver a PUBLISH Packet.
[MQTT-3.3.1-2]
The DUP flag MUST be set to 0 for all QoS 0 messages.
[MQTT-3.3.1-3]
The value of the DUP flag from an incoming PUBLISH packet is not propagated
when the PUBLISH Packet is sent to subscribers by the Server. The DUP flag in
the outgoing PUBLISH packet is set independently to the incoming PUBLISH
packet, its value MUST be determined solely by whether the outgoing PUBLISH
packet is a retransmission.
[MQTT-3.3.1-4]
A PUBLISH Packet MUST NOT have both QoS bits set to 1. If a Server or Client
receives a PUBLISH Packet which has both QoS bits set to 1 it MUST close the
Network Connection.
[MQTT-3.3.1-5]
If the RETAIN flag is set to 1, in a PUBLISH Packet sent by a Client to a Server,

the Server MUST store the Application Message and its QoS, so that it can be
143mqtt-v3.1.1-os
29 October 2014
Page 72 of 80
delivered to future subscribers whose subscriptions match its topic name.

[MQTT-3.3.1-6]
When a new subscription is established, the last retained message, if any, on

each matching topic name MUST be sent to the subscriber.
[MQTT-3.3.1-7]
If the Server receives a QoS 0 message with the RETAIN flag set to 1 it
MUST discard any message previously retained for that topic. It
SHOULD store the new QoS 0 message as the new retained message
for that topic, but MAY choose to discard it at any time - if this happens
there will be no retained message for that topic.
[MQTT-3.3.1-8]
When sending a PUBLISH Packet to a Client the Server MUST set the RETAIN
flag to 1 if a message is sent as a result of a new subscription being made by a
Client.
[MQTT-3.3.1-9]
It MUST set the RETAIN flag to 0 when a PUBLISH Packet is sent to a Client
because it matches an established subscription regardless of how the flag was
set in the message it received.
[MQTT-3.3.1-10]
A PUBLISH Packet with a RETAIN flag set to 1 and a payload containing zero
bytes will be processed as normal by the Server and sent to Clients with a
subscription matching the topic name. Additionally any existing retained message
with the same topic name MUST be removed and any future subscribers for the
topic will not receive a retained message.
[MQTT-3.3.1-11]
A zero byte retained message MUST NOT be stored as a retained message on

the Server.
[MQTT-3.3.1-12]
If the RETAIN flag is 0, in a PUBLISH Packet sent by a Client to a Server, the

Server MUST NOT store the message and MUST NOT remove or replace any
existing retained message.
[MQTT-3.3.2-1]
The Topic Name MUST be present as the first field in the PUBLISH Packet
Variable header. It MUST be a UTF-8 encoded string.
[MQTT-3.3.2-2]
The Topic Name in the PUBLISH Packet MUST NOT contain wildcard
characters.
[MQTT-3.3.2-3]
The Topic Name in a PUBLISH Packet sent by a Server to a subscribing Client

MUST match the Subscriptions Topic Filter according to the matching process
defined in Section 4.7.
[MQTT-3.3.4-1]
The receiver of a PUBLISH Packet MUST respond according to Table 3.4 Expected Publish Packet response as determined by the QoS in the PUBLISH
Packet.
[MQTT-3.3.5-1]
The Server MUST deliver the message to the Client respecting the maximum
QoS of all the matching subscriptions.
[MQTT-3.3.5-2]
If a Server implementation does not authorize a PUBLISH to be performed by a

Client; it has no way of informing that Client. It MUST either make a positive
acknowledgement, according to the normal QoS rules, or close the Network
Connection.
[MQTT-3.6.1-1]
Bits 3,2,1 and 0 of the fixed header in the PUBREL Control Packet are reserved
and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other
value as malformed and close the Network Connection.
[MQTT-3.8.1-1]
Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are
reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat
145mqtt-v3.1.1-os
29 October 2014
Page 73 of 80
any other value as malformed and close the Network Connection.

[MQTT-3.8.3-1]
The Topic Filters in a SUBSCRIBE packet payload MUST be UTF-8 encoded

strings as defined in Section 1.5.3.
[MQTT-3.8.3-2]
If the Server chooses not to support topic filters that contain wildcard characters
it MUST reject any Subscription request whose filter contains them.
[MQTT-3.8.3-3]
The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter /
QoS pair. A SUBSCRIBE packet with no payload is a protocol violation.
[MQTT-3-8.3-4]
The Server MUST treat a SUBSCRIBE packet as malformed and close the
Network Connection if any of Reserved bits in the payload are non-zero, or QoS
is not 0,1 or 2.
[MQTT-3.8.4-1]
When the Server receives a SUBSCRIBE Packet from a Client, the Server MUST
respond with a SUBACK Packet.
[MQTT-3.8.4-2]
The SUBACK Packet MUST have the same Packet Identifier as the SUBSCRIBE
Packet that it is acknowledging.
[MQTT-3.8.4-3]
If a Server receives a SUBSCRIBE Packet containing a Topic Filter that is

identical to an existing Subscriptions Topic Filter then it MUST completely
replace that existing Subscription with a new Subscription. The Topic Filter in the
new Subscription will be identical to that in the previous Subscription, although its
maximum QoS value could be different. Any existing retained messages
matching the Topic Filter MUST be re-sent, but the flow of publications MUST
NOT be interrupted.
[MQTT-3.8.4-4]
If a Server receives a SUBSCRIBE packet that contains multiple Topic Filters it

MUST handle that packet as if it had received a sequence of multiple
SUBSCRIBE packets, except that it combines their responses into a single
SUBACK response.
[MQTT-3.8.4-5]
The SUBACK Packet sent by the Server to the Client MUST contain a return
code for each Topic Filter/QoS pair. This return code MUST either show the
maximum QoS that was granted for that Subscription or indicate that the
subscription failed.
[MQTT-3.8.4-6]
The Server might grant a lower maximum QoS than the subscriber requested.
The QoS of Payload Messages sent in response to a Subscription MUST be the
minimum of the QoS of the originally published message and the maximum QoS
granted by the Server. The server is permitted to send duplicate copies of a
message to a subscriber in the case where the original message was published
with QoS 1 and the maximum QoS granted was QoS 0.
[MQTT-3.9.3-1]
The order of return codes in the SUBACK Packet MUST match the order of Topic
Filters in the SUBSCRIBE Packet.
[MQTT-3.9.3-2]
SUBACK return codes other than 0x00, 0x01, 0x02 and 0x80 are reserved and
MUST NOT be used.
[MQTT-3.10.1-1]
Bits 3,2,1 and 0 of the fixed header of the UNSUBSCRIBE Control Packet are
reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat
any other value as malformed and close the Network Connection.
[MQTT-3.10.3-1]
The Topic Filters in an UNSUBSCRIBE packet MUST be UTF-8 encoded strings

as defined in Section 1.5.3, packed contiguously.
[MQTT-3.10.3-2]
The Payload of an UNSUBSCRIBE packet MUST contain at least one Topic
147mqtt-v3.1.1-os
29 October 2014
Page 74 of 80
Filter. An UNSUBSCRIBE packet with no payload is a protocol violation.

[MQTT-3.10.4-1]
The Topic Filters (whether they contain wildcards or not) supplied in an

UNSUBSCRIBE packet MUST be compared character-by-character with the
current set of Topic Filters held by the Server for the Client. If any filter matches
exactly then its owning Subscription is deleted, otherwise no additional
processing occurs.
[MQTT-3.10.4-2]
If a Server deletes a Subscription It MUST stop adding any new messages for
delivery to the Client.
[MQTT-3.10.4-3]
If a Server deletes a Subscription It MUST complete the delivery of any QoS 1 or

QoS 2 messages which it has started to send to the Client.
[MQTT-3.10.4-4]
The Server MUST respond to an UNSUBSUBCRIBE request by sending an

UNSUBACK packet. The UNSUBACK Packet MUST have the same Packet
Identifier as the UNSUBSCRIBE Packet.
[MQTT-3.10.4-5]
Even where no Topic Subscriptions are deleted, the Server MUST respond with
an UNSUBACK.
[MQTT-3.10.4-6]
If a Server receives an UNSUBSCRIBE packet that contains multiple Topic

Filters it MUST handle that packet as if it had received a sequence of multiple
UNSUBSCRIBE packets, except that it sends just one UNSUBACK response.
[MQTT-3.12.4-1]
The Server MUST send a PINGRESP Packet in response to a PINGREQ packet.
[MQTT-3.14.1-1]
The Server MUST validate that reserved bits are set to zero and disconnect the
Client if they are not zero.
[MQTT-3.14.4-1]
After sending a DISCONNECT Packet the Client MUST close the Network
Connection.
[MQTT-3.14.4-2]
After sending a DISCONNECT Packet the Client MUST NOT send any more
Control Packets on that Network Connection.
[MQTT-3.14.4-3]
On receipt of DISCONNECT the Server MUST discard any Will Message

associated with the current connection without publishing it, as described in
Section 3.1.2.5.
[MQTT-4.1.0-1]
The Client and Server MUST store Session state for the entire duration of the
Session.
[MQTT-4.1.0-2]
A Session MUST last at least as long it has an active Network Connection.
[MQTT-4.3.1-1]
In the QoS 0 delivery protocol, the Sender
[MQTT-4.3.2-1]
[MQTT-4.3.2-2]
MUST send a PUBLISH packet with QoS=0, DUP=0.
MUST assign an unused Packet Identifier each time it has a new

Application Message to publish.
MUST send a PUBLISH Packet containing this Packet Identifier with

QoS=1, DUP=0.
MUST treat the PUBLISH Packet as "unacknowledged" until it has

received the corresponding PUBACK packet from the receiver. See
Section 4.4 for a discussion of unacknowledged messages.
In the QoS 1 delivery protocol, the Receiver
149mqtt-v3.1.1-os
29 October 2014
Page 75 of 80
[MQTT-4.3.3-1]
[MQTT-4.3.3-2]
MUST respond with a PUBACK Packet containing the Packet Identifier

from the incoming PUBLISH Packet, having accepted ownership of the
Application Message.
After it has sent a PUBACK Packet the Receiver MUST treat any
incoming PUBLISH packet that contains the same Packet Identifier as
being a new publication, irrespective of the setting of its DUP flag.
MUST assign an unused Packet Identifier when it has a new Application

Message to publish.
MUST send a PUBLISH packet containing this Packet Identifier with

QoS=2, DUP=0.
MUST treat the PUBLISH packet as "unacknowledged" until it has

received the corresponding PUBREC packet from the receiver. See
Section 4.4 for a discussion of unacknowledged messages.
MUST send a PUBREL packet when it receives a PUBREC packet from

the receiver. This PUBREL packet MUST contain the same Packet
Identifier as the original PUBLISH packet.
MUST treat the PUBREL packet as "unacknowledged" until it has

received the corresponding PUBCOMP packet from the receiver.
MUST NOT re-send the PUBLISH once it has sent the corresponding
PUBREL packet.
In the QoS 2 delivery protocol, the Receiver
MUST respond with a PUBREC containing the Packet Identifier from the
incoming PUBLISH Packet, having accepted ownership of the
Application Message.
Until it has received the corresponding PUBREL packet, the Receiver

MUST acknowledge any subsequent PUBLISH packet with the same
Packet Identifier by sending a PUBREC. It MUST NOT cause duplicate
messages to be delivered to any onward recipients in this case.
MUST respond to a PUBREL packet by sending a PUBCOMP packet

containing the same Packet Identifier as the PUBREL.
After it has sent a PUBCOMP, the receiver MUST treat any subsequent
PUBLISH packet that contains that Packet Identifier as being a new
publication.
[MQTT-4.4.0-1]
When a Client reconnects with CleanSession set to 0, both the Client and Server
MUST re-send any unacknowledged PUBLISH Packets (where QoS > 0) and
PUBREL Packets using their original Packet Identifiers.
[MQTT-4.5.0-1]
When a Server takes ownership of an incoming Application Message it MUST

add it to the Session state of those clients that have matching Subscriptions.
Matching rules are defined in Section 4.7.
[MQTT-4.5.0-2]
The Client MUST acknowledge any Publish Packet it receives according to the
applicable QoS rules regardless of whether it elects to process the Application
Message that it contains.
[MQTT-4.6.0-1]
When it re-sends any PUBLISH packets, it MUST re-send them in the order in
which the original PUBLISH packets were sent (this applies to QoS 1 and QoS 2
messages).
151mqtt-v3.1.1-os
29 October 2014
Page 76 of 80
[MQTT-4.6.0-2]
Client MUST send PUBACK packets in the order in which the corresponding
PUBLISH packets were received (QoS 1 messages).
[MQTT-4.6.0-3]
Client MUST send PUBREC packets in the order in which the corresponding
PUBLISH packets were received (QoS 2 messages).
[MQTT-4.6.0-4]
Client MUST send PUBREL packets in the order in which the corresponding
PUBREC packets were received (QoS 2 messages).
[MQTT-4.6.0-5]
A Server MUST by default treat each Topic as an "Ordered Topic". It MAY provide
an administrative or other mechanism to allow one or more Topics to be treated
as an "Unordered Topic".
[MQTT-4.6.0-6]
When a Server processes a message that has been published to an Ordered

Topic, it MUST follow the rules listed above when delivering messages to each of
its subscribers. In addition it MUST send PUBLISH packets to consumers (for the
same Topic and QoS) in the order that they were received from any given Client.
[MQTT-4.7.1-1]
The wildcard characters can be used in Topic Filters, but MUST NOT be used
within a Topic Name.
[MQTT-4.7.1-2]
The multi-level wildcard character MUST be specified either on its own or

following a topic level separator. In either case it MUST be the last character
specified in the Topic Filter.
[MQTT-4.7.1-3]
The single-level wildcard can be used at any level in the Topic Filter, including
first and last levels. Where it is used it MUST occupy an entire level of the filter.
[MQTT-4.7.2-1]
The Server MUST NOT match Topic Filters starting with a wildcard character (#
or +) with Topic Names beginning with a $ character.
[MQTT-4.7.3-1]
All Topic Names and Topic Filters MUST be at least one character long.
[MQTT-4.7.3-2]
Topic Names and Topic Filters MUST NOT include the null character (Unicode
U+0000).
[MQTT-4.7.3-3]
Topic Names and Topic Filters are UTF-8 encoded strings, they MUST NOT
encode to more than 65535 bytes.
[MQTT-4.7.3-4]
When it performs subscription matching the Server MUST NOT perform any
normalization of Topic Names or Topic Filters, or any modification or substitution
of unrecognized characters.
[MQTT-4.8.0-1]
Unless stated otherwise, if either the Server or Client encounters a protocol

violation, it MUST close the Network Connection on which it received that Control
Packet which caused the protocol violation.
[MQTT-4.8.0-2]
If the Client or Server encounters a Transient Error while processing an inbound

Control Packet it MUST close the Network Connection on which it received that
Control Packet.
[MQTT-6.0.0-1]
MQTT Control Packets MUST be sent in WebSocket binary data frames. If any
other type of data frame is received the recipient MUST close the Network
Connection.
[MQTT-6.0.0-2]
A single WebSocket data frame can contain multiple or partial MQTT Control
Packets. The receiver MUST NOT assume that MQTT Control Packets are
aligned on WebSocket frame boundaries.
[MQTT-6.0.0-3]
The client MUST include mqtt in the list of WebSocket Sub Protocols it offers.
153mqtt-v3.1.1-os
29 October 2014
Page 77 of 80
[MQTT-6.0.0-4]
The WebSocket Sub Protocol name selected and returned by the server MUST
be mqtt.
[MQTT-7.0.0-1]
A Server that both accepts inbound connections and establishes outbound

connections to other Servers MUST conform as both an MQTT Client and MQTT
Server.
[MQTT-7.0.0-2]
Conformant implementations MUST NOT require the use of any extensions

defined outside of this specification in order to interoperate with any other
conformant implementation.
[MQTT-7.1.1-1]
A conformant Server MUST support the use of one or more underlying transport
protocols that provide an ordered, lossless, stream of bytes from the Client to
Server and Server to Client.
[MQTT-7.1.2-1]
A conformant Client MUST support the use of one or more underlying transport
protocols that provide an ordered, lossless, stream of bytes from the Client to
Server and Server to Client.
2113
155mqtt-v3.1.1-os
29 October 2014
Page 78 of 80
2114Appendix
C. Revision history (non normative)
2115
Revision
Date
Editor
Changes Made
[02]
[29 April 2013]
[A Banks]
[Tighten up language for Connect packet]
[03]
[09 May 2013]
[ A Banks]
[Tighten up language in Section 02 Command

Message Format]
[04]
[20 May 2013]
[Rahul Gupta]
Tighten up language for PUBLISH message
[05]
[5th June 2013]
[ A Banks]
[ Issues -5,9,13 ]
[Rahul Gupta]
[Formatting and language tighten up in

PUBACK, PUBREC, PUBREL, PUBCOMP
message]
[Rahul Gupta]
[Issue 17, 2, 28, 33]
[06]
[20th June 2013]
[Formatting and language tighten up in

SUBSCRIBE, SUBACK, UNSUBSCRIBE,
UNSUBACK, PINGREQ, PINGRESP,
DISCONNECT Control Packets]
Terms Command message change to Control
Packet
Term message is generically used, replaced
this word accordingly with packet, publication,
subscription.
[06]
[07]
[08]
[21 June 2013]
[03 July 2013]

[19 July 2013]
[A Banks]
Resolved Issues 12,20,15, 3, 35, 34, 23, 5,

21
[Rahul Gupta]
Resolved Issues 32,39, 41
[A Banks]
Resolved Issues 18,11,4
[Rahul Gupta]
Resolved Issues 26,31,36,37
[A Banks]
Resolved Issues 6, 29, 45
[Rahul Gupta]

Added table for fixed header and payload
[09]
[01 August 2013]
[A Banks]
Resolved Issues 49, 53, 46, 67, 29, 66, 62,

45, 69, 40, 61, 30
[10]
[10 August 2013]
[A Banks]
Resolved Issues 19, 63, 57, 65, 72
[Rahul Gupta]
Conformance section added
[A Banks]
Resolved Issues 56
[N O'Leary &
Rahul Gupta]
Updated Conformance section
[Rahul Gupta]
Resolved Issues 22, 42, 81, 84, 85, 7, 8, 14,

16, Security section is added
[A Banks]
Resolved Issue -1
[11]
[12]
[10 September 2013]
[18 September 2013]
157mqtt-v3.1.1-os
29 October 2014
Page 79 of 80
[13]
[27 September 2013]
[A Banks]
Resolved Issues 64, 68, 76, 86, 27, 60, 82,

55, 78, 51, 83, 80
[14]
[10 October 2013]
[A Banks]
Resolved Issues 58, 59, 10, 89, 90, 88, 77
[Rahul Gupta]
Resolved Issues 94, 96, 93, 92, 95, 87, 74,

71
[A Banks]
Resolved Issues 52, 97, 98, 101
[Rahul Gupta]
Resolved Issues 100
[15]
[24 October 2013]
Added normative statement numbering and

Appendix A
[16]
[21 November 2013]
[A Banks]
Resolved Issues -103, 104, 44
[17]
[05 December 2013]
[A Banks]
Resolved Issues 105, 70, 102, 106, 107, 108,

109, 110
[Rahul Gupta]
Updated normative statement numbering and

Appendix A
[CSD04]
[28 January 2014]
[Rahul Gupta]
Resolved Issues 112, 114, 115, 120, 117,

134, 132, 133, 130, 131, 129
[18]
[20 February 2014]
[A Banks]
Resolved Issues 175, 139, 176, 166, 149,

164, 140, 154, 178, 188, 181, 155, 170, 196,
173, 157, 195, 191, 150, 179, 185, 174, 163
[Rahul Gupta]
[19]
[20]
[21]
[22]
[28 February 2014]
[07 March 2014]

[17 March 2014]
[27 March 2014]
Resolved Issues 135, 136, 147, 161, 169,

180, 182, 184, 189, 187
[A Banks]
Resolved Issues 167, 192, 141, 138, 137,

198, 165
[Rahul Gupta]
Resolved Issues 199, 144, 159,
[A Banks]
[Rahul Gupta]
[A Banks]
[Rahul Gupta]
Resolved Issues 205,
[Rahul Gupta]
[A Banks]
Resolved Issues 152, 193
[23]
[28 March 2014]
[A Banks]
Resolved Issues 204, 148, 210, 208, 209,

171, 183, 117, 212
[24]
[7 April 2014]
[Rahul Gupta]
Added Table of figures
[A Banks]
Corrected Issue 209
[25]
[8 May 2014]
[Rahul Gupta]
Resolved Issues 213, 214
[25]
[3 September 2014]
[A Banks]
[26]
[17 September 2014]
[Rahul Gupta]
Resolved Issues 247
2116
159mqtt-v3.1.1-os
29 October 2014
Page 80 of 80

mqtt-v3 1 1-Os

Uploaded by

Copyright:

Available Formats

mqtt-v3 1 1-Os

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

mqtt-v3 1 1-Os

Uploaded by

Copyright:

Available Formats

1

MQTT Version 3.1.1

Use of the publish/subscribe message pattern which provides one-to-many message

A messaging transport that is agnostic to the content of the payload.

Three qualities of service for message delivery:

Copyright OASIS Open 2014. All Rights Reserved.

A mechanism to notify interested parties when an abnormal disconnection occurs.

Copyright OASIS Open 2014. All Rights Reserved.

Copyright OASIS Open 2014. All Rights Reserved.

Copyright OASIS Open 2014. All Rights Reserved.

Copyright OASIS Open 2014. All Rights Reserved.

209 4.1 Storing state.................................................................................................................................... 51

Copyright OASIS Open 2014. All Rights Reserved.

of Figures and Tables

251Figure 1.1 Structure of UTF-8 encoded strings.............................................................................................................13

Copyright OASIS Open 2014. All Rights Reserved.

298Figure 3.31 UNSUBACK Packet fixed header...........................................................................................................47

Copyright OASIS Open 2014. All Rights Reserved.

3101.1 Organization of MQTT

Chapter 2 - MQTT Control Packet format

Chapter 3 - MQTT Control Packets

Chapter 4 - Operational behavior

Chapter 6 - Using WebSocket as a network transport

Chapter 7 - Conformance Targets

It connects the Client to the Server.

327For examples see Section 4.2.

Publish Application Messages that other Clients might be interested in.

Unsubscribe to remove a request for Application Messages.

Disconnect from the Server.

Copyright OASIS Open 2014. All Rights Reserved.

Accepts Network Connections from Clients.

Processes Subscribe and Unsubscribe requests from Clients.

Forwards Application Messages that match Client Subscriptions.

3641.3 Normative references

Copyright OASIS Open 2014. All Rights Reserved.

3861.4 Non normative references

Copyright OASIS Open 2014. All Rights Reserved.

426NISTIR 7628 Guidelines for Smart Grid Cyber Security

Copyright OASIS Open 2014. All Rights Reserved.

4781.5 Data representations

4821.5.2 Integer data values

4861.5.3 UTF-8 encoded strings

String length MSB

String length LSB

UTF-8 Encoded Character Data, if length > 0.

Copyright OASIS Open 2014. All Rights Reserved.

1.5.3.1 Non normative example

526Figure 1.2 UTF-8 encoded string non normative example

String Length MSB (0x00)

String Length LSB (0x05)

5281.6 Editing conventions

Copyright OASIS Open 2014. All Rights Reserved.

MQTT Control Packet format

5322.1 Structure of an MQTT Control Packet

Fixed header, present in all MQTT Control Packets

5392.2 Fixed header

MQTT Control Packet type

Flags specific to each MQTT Control

5452.2.1 MQTT Control Packet type

if (multiplier > 128128128)