oasis

MQTT Version 5.0

Committee Specification Draft 01 /
Public Review Draft 01

13 July 2017

Specification URIs

This version:

http://docs.oasis-open.org/mqtt/mqtt/v5.0/csprd01/mqtt-v5.0-csprd01.docx (Authoritative)

http://docs.oasis-open.org/mqtt/mqtt/v5.0/csprd01/mqtt-v5.0-csprd01.html

http://docs.oasis-open.org/mqtt/mqtt/v5.0/csprd01/mqtt-v5.0-csprd01.pdf

Previous version:

N/A

Latest version:

http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.docx (Authoritative)

http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html

http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.pdf

Technical Committee:

OASIS Message Queuing Telemetry Transport (MQTT) TC

Chairs:

Brian Raymor (brian.raymor@microsoft.com), Microsoft

Richard Coppen (coppen@uk.ibm.com), IBM

Editors:

Andrew Banks (andrew_banks@uk.ibm.com), IBM

Ed Briggs (edbriggs@microsoft.com), Microsoft

Ken Borgendale (kwb@us.ibm.com), IBM

Rahul Gupta (rahul.gupta@us.ibm.com), IBM

Related work:

This specification replaces or supersedes:

·         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.

This specification is related to:

·         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-nist-cybersecurity/v1.0/mqtt-nist-cybersecurity-v1.0.html.

Abstract:

MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open, simple, and designed to be easy to implement. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.

The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless, bi-directional 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:

·         "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 messages 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.

·         A small transport overhead and protocol exchanges minimized to reduce network traffic.

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

Status:

This document was last revised or approved by the OASIS Message Queuing Telemetry Transport (MQTT) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=mqtt#technical.

TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/mqtt/.

This Committee Specification Public Review Draft is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC’s web page (https://www.oasis-open.org/committees/mqtt/ipr.php).

Note that any machine-readable content (aka Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

Citation format:

When referencing this specification the following citation format should be used:

[mqtt-v5.0]

MQTT Version 5.0. Edited by Andrew Banks, Ed Briggs, Ken Borgendale, and Rahul Gupta. 13 July 2017. OASIS Committee Specification Draft 01 / Public Review Draft 01. http://docs.oasis-open.org/mqtt/mqtt/v5.0/csprd01/mqtt-v5.0-csprd01.html. Latest version: http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html.

 

Notices

Copyright © OASIS Open 2017. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

Table of Contents

1        Introduction. 11

1.0 IPR Policy. 11

1.1 Organization of the MQTT specification. 11

1.2 Terminology. 11

1.3 Normative references. 13

1.4 Non-normative references. 13

1.5 Data representation. 16

1.5.1 Bits. 16

1.5.2 Two Byte Integer 16

1.5.3 Four Byte Integer 16

1.5.4 UTF-8 Encoded String. 16

1.5.5 Variable Byte Integer 18

1.5.6 Binary Data. 19

1.5.7 UTF-8 String Pair 19

1.6 Security. 19

1.7 Editing convention. 19

1.8 Change history. 19

1.8.1 MQTT v3.1.1. 19

1.8.2 MQTT v5.0. 20

2        MQTT Control Packet format 21

2.1 Structure of an MQTT Control Packet 21

2.1.1 Fixed Header 21

2.1.2 MQTT Control Packet type. 21

2.1.3 Flags. 22

2.1.4 Remaining Length. 23

2.2 Variable Header 23

2.2.1 Packet Identifier 23

Figure 2.3 - Packet Identifier bytes. 23

2.2.2 Properties. 25

2.2.2.1 Property Length. 25

2.2.2.2 Property. 25

2.3 Payload. 27

2.4 Reason Code. 27

3        MQTT Control Packets. 30

3.1 CONNECT – Connection Request 30

3.1.1 CONNECT Fixed Header 30

3.1.2 CONNECT Variable Header 30

3.1.2.1 Protocol Name. 30

3.1.2.2 Protocol Version. 31

3.1.2.3 Connect Flags. 31

3.1.2.4 Clean Start 32

3.1.2.5 Will Flag. 32

3.1.2.6 Will QoS.. 33

3.1.2.7 Will Retain. 33

3.1.2.8 User Name Flag. 33

3.1.2.9 Password Flag. 33

3.1.2.10 Keep Alive. 34

3.1.2.11 CONNECT Properties. 35

3.1.2.11.1 Property Length. 35

3.1.2.11.2 Session Expiry Interval 35

3.1.2.11.3 Will Delay Interval 36

3.1.2.11.4 Receive Maximum... 36

3.1.2.11.5 Maximum Packet Size. 37

3.1.2.11.6 Topic Alias Maximum... 37

3.1.2.11.7 Request Response Information. 38

3.1.2.11.8 Request Problem Information. 38

3.1.2.11.9 User Property. 38

3.1.2.11.10 Authentication Method. 39

3.1.2.11.11 Authentication Data. 39

3.1.2.12 Variable Header non-normative example. 39

3.1.3 CONNECT Payload. 40

3.1.3.1 Client Identifier (ClientID) 40

3.1.3.2 Will Topic. 41

3.1.3.3 Will Message. 41

3.1.3.4 User Name. 41

3.1.3.5 Password. 41

3.1.4 CONNECT Actions. 41

3.2 CONNACK – Connect acknowledgement 43

3.2.1 CONNACK Fixed Header 43

3.2.2 CONNACK Variable Header 43

3.2.2.1 Connect Acknowledge Flags. 43

3.2.2.1.1 Session Present 43

3.2.2.2 Connect Reason Code. 44

3.2.2.3 CONNACK Properties. 46

3.2.2.3.1 Property Length. 46

3.2.2.3.2 Receive Maximum... 46

3.2.2.3.3 Maximum QoS.. 46

3.2.2.3.4 Retain Available. 47

3.2.2.3.5 Maximum Packet Size. 47

3.2.2.3.6 Assigned Client Identifier 47

3.2.2.3.7 Topic Alias Maximum... 48

3.2.2.3.8 Reason String. 48

3.2.2.3.9 User Property. 48

3.2.2.3.10 Wildcard Subscription Available. 48

3.2.2.3.11 Subscription Identifiers Available. 49

3.2.2.3.12 Shared Subscription Available. 49

3.2.2.3.13 Server Keep Alive. 49

3.2.2.3.14 Response Information. 50

3.2.2.3.15 Server Reference. 50

3.2.2.3.16 Authentication Method. 50

3.2.2.3.17 Authentication Data. 50

3.2.3 CONNACK Payload. 51

3.3 PUBLISH – Publish message. 51

3.3.1 PUBLISH Fixed Header 51

3.3.1.1 DUP.. 51

3.3.1.2 QoS.. 52

3.3.1.3 RETAIN.. 52

3.3.1.4 Remaining Length. 53

3.3.2 PUBLISH Variable Header 53

3.3.2.1 Topic Name. 53

3.3.2.2 Packet Identifier 54

3.3.2.3 PUBLISH Properties. 54

3.3.2.3.1 Property Length. 54

3.3.2.3.2 Payload Format Indicator 54

3.3.2.3.3 Publication Expiry Interval 54

3.3.2.3.4 Topic Alias. 55

3.3.2.3.5 Response Topic. 55

3.3.2.3.6 Correlation Data. 56

3.3.2.3.7 User Property. 56

3.3.2.3.8 Subscription Identifier 57

3.3.2.3.9 Content Type. 57

3.3.3 PUBLISH Payload. 58

3.3.4 PUBLISH Actions. 58

3.4 PUBACK – Publish acknowledgement 60

3.4.1 PUBACK Fixed Header 60

3.4.2 PUBACK Variable Header 61

3.4.2.1 PUBACK Reason Code. 61

3.4.2.2 PUBACK Properties. 62

3.4.2.2.1 Property Length. 62

3.4.2.2.2 Reason String. 62

3.4.2.2.3 User Property. 62

3.4.3 PUBACK Payload. 62

3.4.4 PUBACK Actions. 63

3.5 PUBREC – Publish received (QoS 2 delivery part 1) 63

3.5.1 PUBREC Fixed Header 63

3.5.2 PUBREC Variable Header 63

3.5.2.1 PUBREC Reason Code. 63

3.5.2.2 PUBREC Properties. 64

3.5.2.2.1 Property Length. 64

3.5.2.2.2 Reason String. 64

3.5.2.2.3 User Property. 65

3.5.3 PUBREC Payload. 65

3.5.4 PUBREC Actions. 65

3.6 PUBREL – Publish release (QoS 2 delivery part 2) 65

3.6.1 PUBREL Fixed Header 65

3.6.2 PUBREL Variable Header 65

3.6.2.1 PUBREL Reason Code. 66

3.6.2.2 PUBREL Properties. 66

3.6.2.2.1 Property Length. 66

3.6.2.2.2 Reason String. 66

3.6.2.2.3 User Property. 66

3.6.3 PUBREL Payload. 67

3.6.4 PUBREL Actions. 67

3.7 PUBCOMP – Publish complete (QoS 2 delivery part 3) 67

3.7.1 PUBCOMP Fixed Header 67

3.7.2 PUBCOMP Variable Header 67

3.7.2.1 PUBCOMP Reason Code. 68

3.7.2.2 PUBCOMP Properties. 68

3.7.2.2.1 Property Length. 68

3.7.2.2.2 Reason String. 68

3.7.2.2.3 User Property. 68

3.7.3 PUBCOMP Payload. 69

3.7.4 PUBCOMP Actions. 69

3.8 SUBSCRIBE - Subscribe request 69

3.8.1 SUBSCRIBE Fixed Header 69

3.8.2 SUBSCRIBE Variable Header 69

3.8.2.1 SUBSCRIBE Properties. 70

3.8.2.1.1 Property Length. 70

3.8.2.1.2 Subscription Identifier 70

3.8.3 SUBSCRIBE Payload. 70

3.8.3.1 Subscription Options. 70

3.8.3.2 Payload non-normative example. 72

3.8.4 SUBSCRIBE Actions. 72

3.9 SUBACK – Subscribe acknowledgement 75

3.9.1 SUBACK Fixed Header 75

3.9.2 SUBACK Variable Header 75

3.9.2.1 SUBACK Properties. 75

3.9.2.1.1 Property Length. 75

3.9.2.1.2 Reason String. 75

3.9.2.1.3 User Property. 76

3.9.3 SUBACK Payload. 76

3.9.4 Payload non-normative example. 77

3.10 UNSUBSCRIBE – Unsubscribe request 77

3.10.1 UNSUBSCRIBE Fixed Header 77

3.10.2 UNSUBSCRIBE Variable Header 78

3.10.3 UNSUBSCRIBE Payload. 78

3.10.4 UNSUBSCRIBE Actions. 79

3.11 UNSUBACK – Unsubscribe acknowledgement 79

3.11.1 UNSUBACK Fixed Header 79

3.11.2 UNSUBACK Variable Header 80

3.11.2.1 UNSUBACK Properties. 80

3.11.2.1.1 Property Length. 80

3.11.2.1.2 Reason String. 80

3.11.2.1.3 User Property. 80

3.11.3 UNSUBACK Payload. 81

3.12 PINGREQ – PING request 81

3.12.1 PINGREQ Fixed Header 82

3.12.2 PINGREQ Variable Header 82

3.12.3 PINGREQ Payload. 82

3.12.4 PINGREQ Actions. 82

3.13 PINGRESP – PING response. 82

3.13.1 PINGRESP Fixed Header 82

3.13.2 PINGRESP Variable Header 82

3.13.3 PINGRESP Payload. 83

3.13.4 PINGRESP Actions. 83

3.14 DISCONNECT – Disconnect notification. 83

3.14.1 DISCONNECT Fixed Header 83

3.14.2 DISCONNECT Variable Header 83

3.14.2.1 Disconnect Reason Code. 83

3.14.2.2 DISCONNECT Properties. 86

3.14.2.2.1 Property Length. 86

3.14.2.2.2 Session Expiry Interval 86

3.14.2.2.3 Reason String. 86

3.14.2.2.4 User Property. 86

3.14.2.2.5 Server Reference. 86

3.14.3 DISCONNECT Payload. 87

3.14.4 DISCONNECT Actions. 87

3.15 AUTH – Authentication exchange. 87

3.15.1 AUTH Fixed Header 88

3.15.2 AUTH Variable Header 88

3.15.2.1 Authenticate Reason Code. 88

3.15.2.2 AUTH Properties. 88

3.15.2.2.1 Property Length. 88

3.15.2.2.2 Authentication Method. 89

3.15.2.2.3 Authentication Data. 89

3.15.2.2.4 User Property. 89

3.15.3 AUTH Payload. 89

3.15.4 AUTH Actions. 89

4        Operational behavior 90

4.1 Session State. 90

4.1.1 Storing Session State. 90

4.1.2 Session State non-normative examples. 91

4.2 Network Connections. 91

4.3 Quality of Service levels and protocol flows. 91

4.3.1 QoS 0: At most once delivery. 91

4.3.2 QoS 1: At least once delivery. 92

4.3.3 QoS 2: Exactly once delivery. 93

4.4 Message delivery retry. 94

4.5 Message receipt 95

4.6 Message ordering. 95

4.7 Topic Names and Topic Filters. 96

4.7.1 Topic wildcards. 96

4.7.1.1 Topic level separator 96

4.7.1.2 Multi-level wildcard. 96

4.7.1.3 Single-level wildcard. 97

4.7.2 Topics beginning with $. 97

4.7.3 Topic semantic and usage. 98

4.8 Subscriptions. 98

4.8.1 Non-Shared Subscriptions. 99

4.8.2 Shared Subscriptions. 99

4.9 Flow Control 101

4.10 Request / Response. 102

4.10.1 Basic Request Response (non-normative) 102

4.10.2 Determining a Response Topic value (non-normative) 103

4.11 Server redirection. 103

4.12 Enhanced authentication. 104

4.12.1 Re-authentication. 106

4.13 Handling errors. 107

4.13.1 Malformed Packet and Protocol Errors. 107

4.13.2 Other errors. 108

5        Security. 109

5.1 Introduction. 109

5.2 MQTT solutions: security and certification. 109

5.3 Lightweight cryptography and constrained devices. 110

5.4 Implementation notes. 110

5.4.1 Authentication of Clients by the Server 110

5.4.2 Authorization of Clients by the Server 110

5.4.3 Authentication of the Server by the Client 111

5.4.4 Integrity of Application Messages and MQTT Control Packets. 111

5.4.5 Privacy of Application Messages and MQTT Control Packets. 111

5.4.6 Non-repudiation of message transmission. 112

5.4.7 Detecting compromise of Clients and Servers. 112

5.4.8 Detecting abnormal behaviors. 112

5.4.9 Other security considerations. 113

5.4.10 Use of SOCKS. 113

5.4.11 Security profiles. 113

5.4.11.1 Clear communication profile. 113

5.4.11.2 Secured network communication profile. 113

5.4.11.3 Secured transport profile. 114

5.4.11.4 Industry specific security profiles. 114

6        Using WebSocket as a network transport 115

6.1 IANA considerations. 115

7        Conformance. 116

7.1 Conformance targets. 116

7.1.1 MQTT Server 116

7.1.2 MQTT Client 116

Appendix A. Acknowledgments. 118

Appendix B. Mandatory normative statement (non-normative) 119

Appendix C. Summary of new features in MQTT v5.0 (non-normative) 134

1.1 Oasis MQTT Technical Committee issues. 136

Appendix D. Revision history. 137

 


1      Introduction

1.0 IPR Policy

This Committee Specification Public Review Draft is being developed under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established.

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 TC’s web page (https://www.oasis-open.org/committees/mqtt/ipr.php).

1.1 Organization of the MQTT specification

The specification is split into seven chapters:

·         Chapter 1 - Introduction

·         Chapter 2 - MQTT Control Packet format

·         Chapter 3 - MQTT Control Packets

·         Chapter 4 - Operational behavior

·         Chapter 5 - Security

·         Chapter 6 - Using WebSocket as a network transport

·         Chapter 7 - Conformance Targets

 

1.2 Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in IETF RFC 2119 [RFC2119], except where they appear in text that is marked as non-normative.

 

Network Connection:

A construct provided by the underlying transport protocol that is being used by MQTT.

·         It connects the Client to the Server.

·         It provides the means to send an ordered, lossless, stream of bytes in both directions.

Refer to section 4.2 Network Connection for non-normative examples.

 

Application Message:

The data carried by the MQTT protocol across the network for the application. When an Application Message is transported by MQTT it is associated with a Quality of Service (QoS), a collection of Properties, and a Topic Name.

 

Client:

A program or device that uses MQTT. A Client:

·         opens the Network Connection to the Server

·         publishes Application Messages that other Clients might be interested in.

·         subscribes to request Application Messages that it is interested in receiving.

·         unsubscribes to remove a request for Application Messages.

·         closes the Network Connection to the Server.

 

Server:

A program or device that acts as an intermediary between Clients which publish Application Messages and Clients which have made Subscriptions. A Server:

·         accepts Network Connections from Clients.

·         accepts Application Messages published by Clients.

·         processes Subscribe and Unsubscribe requests from Clients.

·         forwards Application Messages that match Client Subscriptions.

·         closes the Network Connection from the Client.

 

Session:

A stateful interaction between a Client and a Server. Some Sessions last only as long as the Network Connection, others can span multiple consecutive Network Connections between a Client and a Server.

 

Subscription:

A Subscription comprises a Topic Filter and a maximum QoS. A Subscription is associated with a single Session. A Session can contain more than one Subscription. Each Subscription within a Session has a different Topic Filter.

 

Shared Subscription:

A Shared Subscription comprises a Topic Filter and a maximum QoS. A Shared Subscription can be associated with more than one Session to allow a wider range of message exchange patterns. An Application Message that matches a Shared Subscription is only sent to the Client associated with one of these Sessions. A Session can subscribe to more than one Shared Subscription and can contain both Shared Subscriptions and Subscriptions which are not shared.

 

Wildcard Subscription:

A Wildcard Subscription is a Subscription with a Topic Filter containing one or more wildcard characters. This allows the subscription to match more than one Topic Name. Refer to section 4.7 for a description of wildcard characters in a Topic Filter.

 

Topic Name:

The label attached to an Application Message which is matched against the Subscriptions known to the Server.

 

Topic Filter:

An expression contained in a Subscription to indicate an interest in one or more topics. A Topic Filter can include wildcard characters.

 

MQTT Control Packet:

A packet of information that is sent across the Network Connection. The MQTT specification defines fifteen different types of MQTT Control Packet, for example the PUBLISH packet is used to convey Application Messages.

 

Malformed Packet:

A control packet that cannot be parsed according to this specification. Refer to section 4.13 for information about error handling. 

Protocol Error:

An error that is detected after the packet has been parsed and found to contain data that is not allowed by the protocol or is inconsistent with the state of the Client or Server. Refer to section 4.13 for information about error handling.

 

1.3 Normative references

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,

http://www.rfc-editor.org/info/rfc2119

 

[RFC3629]

Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003,

http://www.rfc-editor.org/info/rfc3629

 

[RFC6455]

Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, DOI 10.17487/RFC6455, December 2011,

http://www.rfc-editor.org/info/rfc6455

 

[Unicode]

The Unicode Consortium. The Unicode Standard,

http://www.unicode.org/versions/latest/

 

1.4 Non-normative references

[RFC0793]

Postel, J., "Transmission Control Protocol", STD 7, RFC 793, DOI 10.17487/RFC0793, September 1981, http://www.rfc-editor.org/info/rfc793

 

[RFC5246]

Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008,

http://www.rfc-editor.org/info/rfc5246

 

[AES]

Advanced Encryption Standard (AES) (FIPS PUB 197).

http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

 

[CHACHA20]

ChaCha20 and Poly1305 for IETF Protocols

https://tools.ietf.org/html/rfc7539

 

[FIPS1402]

Security Requirements for Cryptographic Modules (FIPS PUB 140-2)

http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf

 

[IEEE 802.1AR]

IEEE Standard for Local and metropolitan area networks - Secure Device Identity

http://standards.ieee.org/findstds/standard/802.1AR-2009.html

 

[ISO29192]

ISO/IEC 29192-1:2012 Information technology -- Security techniques -- Lightweight cryptography -- Part 1: General

http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=56425

 

[MQTT NIST]

MQTT supplemental publication, MQTT and the NIST Framework for Improving Critical Infrastructure Cybersecurity

http://docs.oasis-open.org/mqtt/mqtt-nist-cybersecurity/v1.0/mqtt-nist-cybersecurity-v1.0.html

 

[MQTTV311]      

MQTT V3.1.1 Protocol Specification

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html

 

[NISTCSF]

Improving Critical Infrastructure Cybersecurity Executive Order 13636 http://www.nist.gov/itl/upload/preliminary-cybersecurity-framework.pdf

 

[NIST7628]

NISTIR 7628 Guidelines for Smart Grid Cyber Security

http://www.nist.gov/smartgrid/upload/nistir-7628_total.pdf

 

[NSAB]

NSA Suite B Cryptography

http://www.nsa.gov/ia/programs/suiteb_cryptography/

 

[PCIDSS]

PCI-DSS Payment Card Industry Data Security Standard

https://www.pcisecuritystandards.org/security_standards/

 

[RFC1928]

Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and L. Jones, "SOCKS Protocol Version 5", RFC 1928, DOI 10.17487/RFC1928, March 1996,

http://www.rfc-editor.org/info/rfc1928

 

[RFC4511]

Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, DOI 10.17487/RFC4511, June 2006,

http://www.rfc-editor.org/info/rfc4511

 

[RFC5280]

Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,

http://www.rfc-editor.org/info/rfc5280

 

[RFC6066]

Eastlake 3rd, D., "Transport Layer Security (TLS) Extensions: Extension Definitions", RFC 6066, DOI 10.17487/RFC6066, January 2011,

http://www.rfc-editor.org/info/rfc6066

 

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012,

http://www.rfc-editor.org/info/rfc6749

 

[RFC6960]

Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, DOI 10.17487/RFC6960, June 2013,

http://www.rfc-editor.org/info/rfc6960

 

[SARBANES]

Sarbanes-Oxley Act of 2002.

http://www.gpo.gov/fdsys/pkg/PLAW-107publ204/html/PLAW-107publ204.htm

 

[USEUPRIVSH]

U.S.-EU Privacy Shield Framework

https://www.privacyshield.gov

 

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,

http://www.rfc-editor.org/info/rfc3986

 

[RFC1035]

Mockapetris, P., "Domain names - implementation and specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, November 1987,

http://www.rfc-editor.org/info/rfc1035

 

[RFC2782]

Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, DOI 10.17487/RFC2782, February 2000,

http://www.rfc-editor.org/info/rfc2782

 

1.5 Data representation

1.5.1 Bits

Bits in a byte are labelled 7 to 0. Bit number 7 is the most significant bit, the least significant bit is assigned bit number 0.

 

1.5.2 Two Byte Integer

Two Byte Integer data values are 16-bit unsigned integers in big-endian order: the high order byte precedes the lower order byte. This means that a 16-bit word is presented on the network as Most Significant Byte (MSB), followed by Least Significant Byte (LSB).

 

1.5.3 Four Byte Integer

Four Byte Integer data values are 32-bit unsigned integers in big-endian order: the high order byte precedes the successively lower order bytes. This means that a 32-bit word is presented on the network as Most Significant Byte (MSB), followed by the next most Significant Byte (MSB), followed by the next most Significant Byte (MSB), followed by Least Significant Byte (LSB).

 

1.5.4 UTF-8 Encoded String

Text fields within the MQTT Control Packets described later are encoded as UTF-8 strings. UTF-8 [RFC3629] is an efficient encoding of Unicode [Unicode] characters that optimizes the encoding of ASCII characters in support of text-based communications.

 

Each of these strings is prefixed with a Two Byte Integer length field that gives the number of bytes in a UTF-8 encoded string itself, as illustrated in Figure 1.1 Structure of UTF-8 Encoded Strings below. Consequently, the maximum size of a UTF-8 Encoded String is 65,535 bytes._Figure_1.1_Structure

 

Unless stated otherwise all UTF-8 encoded strings can have any length in the range 0 to 65,535 bytes.

 

Figure 1‑1 Structure of UTF-8 Encoded Strings

Bit

7

6

5

4

3

2

1

0

byte 1

String length MSB

byte 2

String length LSB

byte 3 ….

UTF-8 encoded character data, if length > 0.

 

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, the character data MUST NOT include encodings of code points between U+D800 and U+DFFF [MQTT-1.5.4-1]. If the Client or Server receives an MQTT Control Packet containing ill-formed UTF-8 it is a Malformed Packet. Refer to section 4.13 for information about handling errors.

 

A UTF-8 Encoded String MUST NOT include an encoding of the null character U+0000. [MQTT-1.5.4-2]. If a receiver (Server or Client) receives an MQTT Control Packet containing U+0000 it is a Malformed Packet. Refer to section 4.13 for information about handling errors.

 

The data SHOULD NOT include encodings of the Unicode [Unicode] code points listed below. If a receiver (Server or Client) receives an MQTT Control Packet containing any of them it MAY treat it as a Malformed Packet.

 

·         U+0001..U+001F control characters

·         U+007F..U+009F control characters

·         Code points defined in the Unicode specification [Unicode] to be non-characters (for example U+0FFFF)

 

A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always interpreted as 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-1.5.4-3].

 

Non-normative example

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:

 

Figure 1‑2 UTF-8 Encoded String non-normative example

Bit

7

6

5

4

3

2

1

0

byte 1

String Length MSB (0x00)

 

0

0

0

0

0

0

0

0

byte 2

String Length LSB (0x05)

 

0

0

0

0

0

1

0

1

byte 3

‘A’ (0x41)

 

0

1

0

0

0

0

0

1

byte 4

(0xF0)

 

1

1

1

1

0

0

0

0

byte 5

(0xAA)

 

1

0

1

0

1

0

1

0

byte 6

(0x9B)

 

1

0

0

1

1

0

1

1

byte 7

(0x94)

 

1

0

0

1

0

1

0

0

 

1.5.5 Variable Byte Integer

The Variable Byte Integer is encoded using an encoding scheme which uses a single byte for values up to 127. Larger values are handled as follows. The least significant seven bits of each byte encode the data, and the most significant bit is used to indicate whether there are bytes following in the representation. Thus, each byte encodes 128 values and a "continuation bit". The maximum number of bytes in the Variable Byte Integer field is four. The encoded value MUST use the minimum number of bytes necessary to represent the value [MQTT-1.5.5-1]. This is shown in Table 1‑1 Size of Variable Byte Integer.

 

Table 1‑1 Size of Variable Byte Integer

Digits

From

To

1

0 (0x00)

127 (0x7F)

2

128 (0x80, 0x01)

16,383 (0xFF, 0x7F)

3

16,384 (0x80, 0x80, 0x01)

2,097,151 (0xFF, 0xFF, 0x7F)

4

2,097,152 (0x80, 0x80, 0x80, 0x01)

268,435,455 (0xFF, 0xFF, 0xFF, 0x7F)

 

Non-normative comment

The algorithm for encoding a non-negative integer (X) into the Variable Byte Integer encoding scheme is as follows:

 

do

   encodedByte = X MOD 128

   X = X DIV 128

   // if there are more data to encode, set the top bit of this byte

   if (X > 0)

      encodedByte = encodedByte OR 128

   endif

   'output' encodedByte

while (X > 0)

 

Where MOD is the modulo operator (% in C), DIV is integer division (/ in C), and OR is bit-wise or (| in C).

 

Non-normative comment

The algorithm for decoding a Variable Byte Integer type is as follows:

  

multiplier = 1

value = 0

do

   encodedByte = 'next byte from stream'

   value += (encodedByte AND 127) * multiplier

   if (multiplier > 128*128*128)

      throw Error(Malformed Variable Byte Integer)

   multiplier *= 128

while ((encodedByte AND 128) != 0)

 

where AND is the bit-wise and operator (& in C).

 

When this algorithm terminates, value contains the Variable Byte Integer value.

 

1.5.6 Binary Data

Binary Data is represented by a Two Byte Integer length which indicates the number of data bytes, followed by that number of bytes. Thus, the length of Binary Data is limited to the range of 0 to 65,535 Bytes.

 

1.5.7 UTF-8 String Pair

A UTF-8 String Pair consists of two UTF-8 Encoded Strings. This data type is used to hold name-value pairs. The first string serves as the name, and the second string contains the value.

 

Both strings MUST comply with the requirements for UTF-8 Encoded Strings [MQTT-1.5.7-1]. If a receiver (Client or Server) receives a string pair which does not meet these requirements it is a Malformed Packet. Refer to section 4.13 for information about handling errors.

 

1.6 Security

MQTT Client and Server implementations SHOULD offer Authentication, Authorization and secure communication options, such as those discussed in Chapter 5. Applications concerned with critical infrastructure, personally identifiable information, or other personal or sensitive information are strongly advised to use these security capabilities.

 

1.7 Editing convention

Text highlighted in Yellow within this specification identifies conformance statements. Each conformance statement has been assigned a reference in the format [MQTT-x.x.x-y] where x.x.x is the section number and y is a statement counter within the section.

 

1.8 Change history

1.8.1 MQTT v3.1.1

MQTT v3.1.1 was the first OASIS standard version of MQTT [MQTTV311].[MQTTV311.

·         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.

 

1.8.2 MQTT v5.0

MQTT v5.0 adds a significant number of new features to MQTT while keeping much of the core in place. The major functional objectives are:

·         Enhancements for scalability and large scale systems

·         Improved error reporting

·         Formalize common patterns including capability discovery and request response

·         Extensibility mechanisms including user properties

·         Performance improvements and support for small clients

 

Refer to Appendix C for a summary of changes in MQTT v5.0 and a list of major issues included in this specification.

 

2      MQTT Control Packet format

2.1 Structure of an MQTT Control Packet

The MQTT protocol operates by exchanging a series of MQTT Control Packets in a defined way. This section describes the format of these packets.

 

An MQTT Control Packet consists of up to three parts, always in the following order as illustrated in Figure 2.1 - Structure of an MQTT Control Packet._Figure_2.1_-

 

Figure 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

 

2.1.1 Fixed Header

Each MQTT Control Packet contains a Fixed Header. Figure 2‑2 Fixed Header format illustrates the Fixed Header format._Figure_2.2_-

Figure 2‑2 Fixed Header format

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type

Flags specific to each MQTT Control Packet type

byte 2…

Remaining Length

 

2.1.2 MQTT Control Packet type

Position: byte 1, bits 7-4.

Represented as a 4-bit unsigned value, the values are listed in Table 2‑1 MQTT Control Packet types.

 

Table 2‑1 MQTT Control Packet types

Name

Value

Direction of flow

Description

Reserved

0

Forbidden

Reserved

CONNECT

1

Client to Server

Connection request

CONNACK

2

Server to Client

Connect acknowledgment

PUBLISH

3

Client to Server or

Server to Client

Publish message

PUBACK

4

Client to Server or

Server to Client

Publish acknowledgment (QoS 1)

PUBREC

5

Client to Server or

Server to Client

Publish received (QoS 2 delivery part 1)

PUBREL

6

Client to Server or

Server to Client

Publish release (QoS 2 delivery part 2)

PUBCOMP

7

Client to Server or

Server to Client

Publish complete (QoS 2 delivery part 3)

SUBSCRIBE

8

Client to Server

Subscribe request

SUBACK

9

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 or

Server to Client

Disconnect notification

AUTH

15

Client to Server or Server to Client

Authentication exchange

 

2.1.3 Flags

The remaining bits [3-0] of byte 1 in the Fixed Header contain flags specific to each MQTT Control Packet type as listed in the Table 2.2 - Flag Bits. 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.1.3-1]. If invalid flags are received it is a Malformed Packet. Refer to section 4.13 for details about handling errors.

 

Table 2‑2 Flag Bits

MQTT Control Packet

Fixed Header flags

Bit 3

Bit 2

Bit 1

Bit 0

CONNECT

Reserved

0

0

0

0

CONNACK

Reserved

0

0

0

0

PUBLISH

Used in MQTT v5.0

DUP

QoS

RETAIN

PUBACK

Reserved

0

0

0

0

PUBREC

Reserved

0

0

0

0

PUBREL

Reserved

0

0

1

0

PUBCOMP

Reserved

0

0

0

0

SUBSCRIBE

Reserved

0

0

1

0

SUBACK

Reserved

0

0

0

0

UNSUBSCRIBE

Reserved

0

0

1

0

UNSUBACK

Reserved

0

0

0

0

PINGREQ

Reserved

0

0

0

0

PINGRESP

Reserved

0

0

0

0

DISCONNECT

Reserved

0

0

0

0

AUTH

Reserved

0

0

0

0

 

DUP = Duplicate delivery of a PUBLISH packet

QoS = PUBLISH Quality of Service

RETAIN = PUBLISH retained message flag

Refer to section 3.3.1 for a description of the DUP, QoS, and RETAIN flags in the PUBLISH packet.

 

2.1.4 Remaining Length

Position: starts at byte 2.

 

The Remaining Length is a Variable Byte Integer that represents the number of bytes remaining within the current Control Packet, including data in the Variable Header and the Payload. The Remaining Length does not include the bytes used to encode the Remaining Length. The packet size is the total number of bytes in an MQTT Control Packet, this is equal to the length of the Fixed Header plus the Remaining Length.

 

2.2 Variable Header

Some types of MQTT Control Packet contain a Variable Header component. It resides between the Fixed Header and the Payload. The content of the Variable Header varies depending on the packet type. The Packet Identifier field of Variable Header is common in several packet types.

 

2.2.1 Packet Identifier

Figure 2.3 - Packet Identifier bytes

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

 

The Variable Header component of many of the MQTT Control Packet types includes a Two Byte Integer Packet Identifier field. These MQTT Control Packets are PUBLISH (where QoS > 0), PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK.

 

MQTT Control Packets that require a Packet Identifier are listed in Table 2.3 – MQTT Control Packets that contain a Packet Identifier._Table_2.5_-

Table 2‑3 MQTT Control Packets that contain a Packet Identifier

MQTT Control Packet

Packet Identifier field

CONNECT

NO

CONNACK

NO

PUBLISH

YES (If QoS > 0)

PUBACK

YES

PUBREC

YES

PUBREL

YES

PUBCOMP

YES

SUBSCRIBE

YES

SUBACK

YES

UNSUBSCRIBE

YES

UNSUBACK

YES

PINGREQ

NO

PINGRESP

NO

DISCONNECT

NO

AUTH

NO

 

A PUBLISH packet MUST NOT contain a Packet Identifier if its QoS value is set to 0 [MQTT-2.2.1-2].

 

Each time a Client sends a new SUBSCRIBE, UNSUBSCRIBE,or PUBLISH (where QoS > 0) MQTT Control Packet it MUST assign it a non-zero Packet Identifier that is currently unused [MQTT-2.2.1-3].

 

Each time a Server sends a new PUBLISH (with QoS > 0) MQTT Control Packet it MUST assign it a non zero Packet Identifier that is currently unused [MQTT-2.2.1-4].

 

The Packet Identifier becomes available for reuse after the sender has processed the corresponding acknowledgement packet, defined as follows. In the case of a QoS 1 PUBLISH, this is the corresponding PUBACK; in the case of QoS 2 PUBLISH it is PUBCOMP or a PUBREC with a Reason Code of 128 or greater. For SUBSCRIBE or UNSUBSCRIBE it is the corresponding SUBACK or UNSUBACK.

 

Packet Identifiers used with PUBLISH, SUBSCRIBE and UNSUBSCRIBE packets form a single, unified set of identifiers separately for the Client and the Server in a Session. A Packet Identifier cannot be used by more than one command at any time.

 

A PUBACK, PUBREC , PUBREL, or PUBCOMP packet MUST contain the same Packet Identifier as the PUBLISH packet that was originally sent [MQTT-2.2.1-5]. A SUBACK and UNSUBACK MUST contain the Packet Identifier that was used in the corresponding SUBSCRIBE and UNSUBSCRIBE packet respectively [MQTT-2.2.1-6].

 

The Client and Server assign Packet Identifiers independently of each other. As a result, Client-Server pairs can participate in concurrent message exchanges using the same Packet Identifiers.

 

Non-normative comment

It is possible for a Client to send a PUBLISH packet with Packet Identifier 0x1234 and then receive a different PUBLISH packet with Packet Identifier 0x1234 from its Server before it receives a PUBACK for the PUBLISH packet that it sent.

 

 Client                                                   Server

 PUBLISH Packet Identifier=0x1234---à

                                                            ß--PUBLISH Packet Identifier=0x1234

 PUBACK Packet Identifier=0x1234---à

                                                            ß--PUBACK Packet Identifier=0x1234

 

 

2.2.2 Properties

The last field in the Variable Header of the CONNECT, CONNACK, PUBLISH, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBACK, DISCONNECT, and AUTH packet is a set of Properties. This is composed of a Property Length followed by the Properties.

 

2.2.2.1 Property Length

The Property Length is encoded as a Variable Byte Integer. The Property Length does not include the bytes used to encode itself, but includes the length of the Properties. If there are no properties, this MUST be indicated by including a Property Length of zero [MQTT-2.2.2-1].

 

2.2.2.2 Property

A Property consists of an Identifier which defines its usage and data type, followed by a value. The Identifier is encoded as a Variable Byte Integer. A Control Packet which contains an Identifier which is not valid for its packet type, or contains a value not of the specified data type, is a Malformed Packet. If received, use a CONNACK or DISCONNECT packet with Reason Code 0x81 (Malformed Packet) as described in section 4.13 Handling errors. There is no significance in the order of Properties with different Identifiers.

 

Table 2‑4 - Properties

Identifier

Name (usage)

Type

Packet

 

Dec

Hex

1

0x01

Payload Format Indicator

Byte

PUBLISH

2

0x02

Publication Expiry Interval

Four Byte Integer

PUBLISH

3

0x03

Content Type

UTF-8 Encoded String

PUBLISH

8

0x08

Response Topic

UTF-8 Encoded String

PUBLISH

9

0x09

Correlation Data

Binary Data

PUBLISH

11

0x0B

Subscription Identifier

Variable Byte Integer

PUBLISH, SUBSCRIBE

17

0x11

Session Expiry Interval

Four Byte Integer

CONNECT, DISCONNECT

18

0x12

Assigned Client Identifier

UTF-8 Encoded String

CONNACK

19

0x13

Server Keep Alive

Two Byte Integer

CONNACK

21

0x15

Authentication Method

UTF-8 Encoded String

CONNECT, CONNACK, AUTH

22

0x16

Authentication Data

Binary Data

CONNECT, CONNACK, AUTH

23

0x17

Request Problem Information

Byte

CONNECT

24

0x18

Will Delay Interval

Four Byte Integer

CONNECT

25

0x19

Request Response Information

Byte

CONNECT

26

0x1A

Response Information

UTF-8 Encoded String

CONNACK

28

0x1C

Server Reference

UTF-8 Encoded String

CONNACK, DISCONNECT

31

0x1F

Reason String

UTF-8 Encoded String

CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT, AUTH

33

0x21

Receive Maximum

Two Byte Integer

CONNECT, CONNACK

34

0x22

Topic Alias Maximum

Two Byte Integer

CONNECT, CONNACK

35

0x23

Topic Alias

Two Byte Integer

PUBLISH

36

0x24

Maximum QoS

Byte

CONNACK

37

0x25

Retain Available

Byte

CONNACK

38

0x26

User Property

UTF-8 String Pair

CONNECT, CONNACK, PUBLISH, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT, AUTH

39

0x27

Maximum Packet Size

Four Byte Integer

CONNECT, CONNACK

40

0x28

Wildcard Subscription Available

Byte

CONNACK

41

0x29

Subscription Identifier Available

Byte

CONNACK

42

0x2A

Shared Subscription Available

Byte

CONNACK

 

Non-normative comment 
Although the Property Identifier is defined as a Variable Byte Integer, in this version of the specification all of the Property Identifiers are one byte long.

 

2.3 Payload

Some MQTT Control Packets contain a Payload as the final part of the packet. In the PUBLISH packet this is the Application Message Table 2‑5 - MQTT Control Packets that contain a Payload

 

Table 2‑5 - MQTT Control Packets that contain a Payload

MQTT Control Packet

Payload

CONNECT

Required

CONNACK

None

PUBLISH

Optional

PUBACK

None

PUBREC

None

PUBREL

None

PUBCOMP

None

SUBSCRIBE

Required

SUBACK

Required

UNSUBSCRIBE

Required

UNSUBACK

Required

PINGREQ

None

PINGRESP

None

DISCONNECT

None

AUTH

None

 

 

2.4 Reason Code

A Reason Code is a one byte unsigned value that indicates the result of an operation. Reason Codes less than 0x80 indicate successful completion of an operation. The normal Reason Code for success is 0. Reason Code values of 0x80 or greater indicate failure.

 

The CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, DISCONNECT and AUTH Control Packets have a single Reason Code as part of the Variable Header. The SUBACK and UNSUBACK packets contain a list of one or more Reason Codes in the Payload.

 

The Reason Codes share a common set of values as shown in Table 2‑6 - Reason Codes.

 

Table 2‑6 - Reason Codes

Reason Code

Name

Packets

 

Decimal

Hex

0

0x00

Success

CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH

0

0x00

Normal disconnection

DISCONNECT

0

0x00

Granted QoS 0

SUBACK

1

0x01

Granted QoS 1

SUBACK

2

0x02

Granted QoS 2

SUBACK

4

0x04

Disconnect with Will Message

DISCONNECT

16

0x10

No matching subscribers

PUBACK, PUBREC

17

0x11

No subscription existed

UNSUBACK

24

0x18

Continue authentication

AUTH

25

0x19

Re-authenticate

AUTH

128

0x80

Unspecified error

CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

129

0x81

Malformed Packet

CONNACK, DISCONNECT

130

0x82

Protocol Error

CONNACK, DISCONNECT

131

0x83

Implementation specific error

CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

132

0x84

Unsupported Protocol Version

CONNACK

133

0x85

Client Identifier not valid

CONNACK

134

0x86

Bad User Name or Password

CONNACK

135

0x87

Not authorized

CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

136

0x88

Server unavailable

CONNACK

137

0x89

Server busy

CONNACK, DISCONNECT

138

0x8A

Banned

CONNACK

139

0x8B

Server shutting down

DISCONNECT

140

0x8C

Bad authentication method

CONNACK, DISCONNECT

141

0x8D

Keep Alive timeout

DISCONNECT

142

0x8E

Session taken over

DISCONNECT

143

0x8F

Topic Filter invalid

SUBACK, UNSUBACK, DISCONNECT

144

0x90

Topic Name invalid

CONNACK, PUBACK, PUBREC, DISCONNECT

145

0x91

Packet Identifier in use

PUBACK, PUBREC, SUBACK, UNSUBACK

146

0x92

Packet Identifier not found

PUBREL, PUBCOMP

147

0x93

Receive Maximum exceeded

DISCONNECT

148

0x94

Topic Alias invalid

DISCONNECT

149

0x95

Packet too large

CONNACK, DISCONNECT

150

0x96

Message rate too high

DISCONNECT

151

0x97

Quota exceeded

CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT

152

0x98

Administrative action

DISCONNECT

153

0x99

Payload format invalid

PUBACK, PUBREC, DISCONNECT

154

0x9A

Retain not supported

CONNACK, DISCONNECT

155

0x9B

QoS not supported

CONNACK, DISCONNECT

156

0x9C

Use another server

CONNACK, DISCONNECT

157

0x9D

Server moved

CONNACK, DISCONNECT

158

0x9E

Shared Subscription not supported

SUBACK, DISCONNECT

159

0x9F

Connection rate exceeded

CONNACK, DISCONNECT

160

0xA0

Maximum connect time

DISCONNECT

161

0xA1

Subscription Identifiers not supported

SUBACK, DISCONNECT

162

0xA2

Wildcard Subscription not supported

SUBACK, DISCONNECT

 

Non-normative comment

For Reason Code 0x91 (Packet identifier in use), the response to this is either to try to fix the state, or to reset the Session state by connecting using Clean Start set to 1, or to decide if the Client or Server implementations are defective.

 

3      MQTT Control Packets

 

3.1 CONNECT – Connection Request

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 [MQTT-3.1.0-1].

 

A Client can only send the CONNECT packet once over a Network Connection. The Server MUST process a second CONNECT packet sent from a Client as a Protocol Error and close the Network Connection [MQTT-3.1.0-2]. Refer to section 4.13 for information about handling errors.

 

The Payload contains one or more encoded fields. They specify a unique Client identifier for the Client, a Will Topic, Will Message, User Name and Password. All but the Client identifier can be omitted and their presence is determined based on flags in the Variable Header.

 

3.1.1 CONNECT Fixed Header

Figure 3‑1 - CONNECT packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (1)

Reserved

 

0

0

0

1

0

0

0

0

byte 2…

Remaining Length

 

Remaining Length field

This is the length of the Variable Header plus the length of the Payload. It is encoded as a Variable Byte Integer.

 

3.1.2 CONNECT Variable Header

The Variable Header for the CONNECT Packet contains the following fields in this order: Protocol Name, Protocol Level, Connect Flags, Keep Alive, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

3.1.2.1 Protocol Name

Figure 3‑2 - Protocol Name bytes

 

Description

7

6

5

4

3

2

1

0

Protocol Name

byte 1

Length MSB (0)

0

0

0

0

0

0

0

0

byte 2

Length LSB (4)

0

0

0

0

0

1

0

0

byte 3

‘M’

0

1

0

0

1

1

0

1

byte 4

‘Q’

0

1

0

1

0

0

0

1

byte 5

‘T’

0

1

0

1

0

1

0

0

byte 6

‘T’

0

1

0

1

0

1

0

0

 

The Protocol Name is a UTF-8 Encoded String that represents the protocol name “MQTT”, capitalized as shown. The string, its offset and length will not be changed by future versions of the MQTT specification.

 

A Server which support multiple protocols uses the Protocol Name to determine whether the data is MQTT. The protocol name MUST be the UTF-8 String "MQTT". If the Server does not want to accept the CONNECT, and wishes to reveal that it is an MQTT Server it MAY send a CONNACK packet with Reason Code of 0x84 (Unsupported Protocol Version), and then it MUST close the Network Connection [MQTT-3.1.2-1].

 

Non-normative comment

Packet inspectors, such as firewalls, could use the Protocol Name to identify MQTT traffic.

 

3.1.2.2 Protocol Version

Figure 3‑3 - Protocol Version byte

 

Description

7

6

5

4

3

2

1

0

Protocol Level

byte 7

Version(5)

0

0

0

0

0

1

0

1

 

The one byte unsigned value that represents the revision level of the protocol used by the Client. The value of the Protocol Version field for version 5.0 of the protocol is 5 (0x05).

 

A Server which supports multiple versions of the MQTT protocol uses the Protocol Version to determine which version of MQTT the Client is using. If the Protocol Version is not 5 and the Server does not want to accept the CONNECT packet, the Server MAY send a CONNACK packet with Reason Code 0x84 (Unsupported Protocol Version) and then MUST close the Network Connection [MQTT-3.1.2-2].

 

3.1.2.3 Connect Flags

The Connect Flags byte contains several parameters specifying the behavior of the MQTT connection. It also indicates the presence or absence of fields in the Payload.

Figure 3‑4 - Connect Flag bits

Bit

7

6

5

4

3

2

1

0

 

User Name Flag

Password Flag

Will Retain

Will QoS

Will Flag

Clean Start

Reserved

byte 8

X

X

X

X

X

X

X

0

The Server MUST validate that the reserved flag in the CONNECT packet is set to 0 [MQTT-3.1.2-3]. If the reserved flag is not 0 it is a Malformed Packet. Refer to section 4.13.1 for information about handling errors.

 

3.1.2.4 Clean Start

Position: bit 1 of the Connect Flags byte.


This bit specifies whether the Connection starts a new Session or is a continuation of an existing Session. Refer to section 4.1 for a definition of the Session State.

 

If a CONNECT packet is received with Clean Start is set to 1, the Client and Server MUST discard any existing Session and start a new Session [MQTT-3.1.2-4]. Consequently, the Session Present flag in CONNACK is always set to 0 if Clean Start is set to 1.

 

If a CONNECT packet is received with Clean Start set to 0 and there is a Session associated with the Client Identifier, the Server MUST resume communications with the Client based on state from the existing Session [MQTT-3.1.2-5]. If a CONNECT packet is received with Clean Start set to 0 and there is no Session associated with the Client Identifier, the Server MUST create a new Session [MQTT-3.1.2-6].

 

3.1.2.5 Will Flag

Position: bit 2 of the Connect Flags.


If the Will Flag is set to 1 this indicates that a Will Message MUST be stored on the Server and associated with the Session [MQTT-3.1.2-7]. The Will Message MUST be published after the Network Connection is subsequently closed and either the Will Delay Interval has elapsed or the Session ends, unless the Will Message has been deleted by the Server on receipt of a DISCONNECT packet with Reason Code 0x00 (Normal disconnection) or a new Network Connection for the ClientID is opened before the Will Delay Interval has elapsed [MQTT-3.1.2-8].

Situations in which the Will Message is published include, but are not limited to:

 

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-9]. 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 with a Reason Code of 0x00 (Normal disconnection) from the Client [MQTT-3.1.2-10].

 

If the Will Flag is set to 0, the Will QoS and Will Retain fields in the Connect Flags MUST be set to 0 and the Will Topic and Will Message fields MUST NOT be present in the Payload [MQTT-3.1.2-11]. If the Will Flag is set to 0, the Server MUST NOT publish a Will Message [MQTT-3.1.2-12].

 

The Server SHOULD publish Will Messages promptly after the Network Connection is closed and the Will Delay Interval has passed, or when the Session ends, whichever occurs first. In the case of a Server shutdown or failure, the Server MAY defer publication of Will Messages until a subsequent restart. If this happens, there might be a delay between the time the Server experienced failure and when the Will Message is published.

 

Refer to section 3.1.2.11.3 for information about the Will Delay Interval.

 

Non-normative comment

The Client can arrange for the Will Message to notify that Session Expiry has occurred by setting the Will Delay Interval to be longer than the Session Expiry Interval and sending DISCONNECT with Reason Code 0x04 (Disconnect with Will Message). 

 

3.1.2.6 Will QoS

Position: bits 4 and 3 of the Connect Flags.


These two bits specify the QoS level to be used when publishing the Will Message.

 

If the Will Flag is set to 0, then the Will QoS MUST be set to 0 (0x00) [MQTT-3.1.2-13].

If the Will Flag is set to 1, the value of Will QoS can be 0 (0x00), 1 (0x01), or 2 (0x02) [MQTT-3.1.2-14]. A value of 3 (0x03) is a Malformed Packet. Refer to section 4.13.1 for information about handling errors.

 

3.1.2.7 Will Retain

Position: bit 5 of the Connect Flags.


This bit specifies if the Will Message is to be retained when it is published.

 

If the Will Flag is set to 0, then Will Retain MUST be set to 0 [MQTT-3.1.2-15]. If the Will Flag is set to 1 and Will Retain is set to 0, the Server MUST publish the Will Message as a non-retained message [MQTT-3.1.2-16]. If the Will Flag is set to 1 and Will Retain is set to 1, the Server MUST publish the Will Message as a retained message [MQTT-3.1.2-17].

 

3.1.2.8 User Name Flag

Position: bit 7 of the Connect Flags.


If the User Name Flag is set to 0, a User Name MUST NOT be present in the Payload [MQTT-3.1.2-18]. If 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

Position: bit 6 of the Connect Flags.


If the Password Flag is set to 0, a Password MUST NOT be present in the Payload [MQTT-3.1.2-20]. If the Password Flag is set to 1, a Password MUST be present in the Payload [MQTT-3.1.2-21].

 

Non-normative comment

This version of the protocol allows the sending of a Password with no User Name, where MQTT v3.1.1 did not. This reflects the common use of Password for credentials other than a password.

 

3.1.2.10 Keep Alive

Figure 3‑5 - Keep Alive bytes

Bit

7

6

5

4

3

2

1

0

byte 9

Keep Alive MSB

byte 10

Keep Alive LSB

 

The Keep Alive is a Two Byte Integer which is a time interval measured in seconds. It is the maximum time interval that is permitted to elapse between the point at which the Client finishes transmitting one MQTT Control Packet and the point it starts sending the next. It is the responsibility of the Client to ensure that the interval between MQTT Control Packets being sent does not exceed the Keep Alive value. If Keep Alive is non-zero and in the absence of sending any other MQTT Control Packets, the Client MUST send a PINGREQ packet [MQTT-3.1.2-22].

 

If the Server returns a Server Keep Alive on the CONNACK packet, the Client MUST use that value instead of the value it sent as the Keep Alive [MQTT-3.1.2-23].

 

The Client can send PINGREQ at any time, irrespective of the Keep Alive value, and check for a corresponding PINGRESP to determine that the network and the Server are available.

 

If the Keep Alive value is non-zero and the Server does not receive an MQTT Control Packet from the Client within one and a half times the Keep Alive time period, it MUST close the Network Connection to the Client as if the network had failed [MQTT-3.1.2-24].

 

If a Client does not receive a PINGRESP packet within a reasonable amount of time after it has sent a PINGREQ, it SHOULD close the Network Connection to the Server.

 

A Keep Alive value of 0 has the effect of turning off the Keep Alive mechanism. If Keep Alive is 0 the Client is not obliged to send MQTT Control Packets on any particular schedule.

 

Non-normative comment
The Server may have other reasons to disconnect the Client, for instance because it is shutting down. Setting Keep Alive does not guarantee that the Client will remain connected.

 

Non-normative comment

The actual value of the Keep Alive is application specific; typically, this is a few minutes. The maximum value of 65,535 is 18 hours 12 minutes and 15 seconds.

 

3.1.2.11 CONNECT Properties

3.1.2.11.1 Property Length

The length of the Properties in the CONNECT packet Variable Header encoded as a Variable Byte Integer.

 

3.1.2.11.2 Session Expiry Interval

17 (0x11) Byte, Identifier of the Session Expiry Interval.

Followed by the Four Byte Integer representing the Session Expiry Interval in seconds. It is a Protocol Error to include the Session Expiry Interval more than once.

 

If the Session Expiry Interval is absent, the Session does not expire. If it is set to 0, the Session ends when the Network Connection is closed.

 

The Client and Server MUST store the Session State after the Network Connection is closed if the Session Expiry Interval is absent or greater than 0 [MQTT-3.1.2-25].

 

Non-normative comment

The clock in the Client or Server may not be running for part of the time interval, for instance because the Client or Server are not running. This might cause the deletion of the state to be delayed.

 

Refer to section 4.1 for more information about Sessions. Refer to section 4.1.1 for details and limitations of stored state.

 

When the Session expires the Client and Server need not process the deletion of state atomically.

 

Non-normative comment

Setting Clean Start to 1 and a Session Expiry Interval of 0, is equivalent to setting CleanSession to 1 in the MQTT Specification Version 3.1.1. Setting Clean Start to 0 and no Session Expiry Interval, is equivalent to setting CleanSession to 0 in the MQTT Specification Version 3.1.1.

 

Non-normative comment

A Client that only wants to process messages while connected will set the Clean Start to 1 and set the Session Expiry Interval to 0. It will not receive Application Messages published before it connected and has to subscribe afresh to any topics that it is interested in each time it connects.

 

Non-normative comment

A Client might be connecting to a Server using a network that provides intermittent connectivity. This Client can use a short Session Expiry Interval so that it can reconnect when the network is available again and continue reliable message delivery. If the Client does not reconnect, allowing the Session to expire, then Application Messages will be lost.

 

Non-normative comment

When a Client connects with a long Session Expiry Interval, or no Session Expiry at all, it is requesting that the Server maintain its MQTT session state after it disconnects for an extended period. Clients should only connect with a long Session Expiry Interval 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 disconnect with a Session Expiry Interval set to 0.

 

Non-normative comment

The Client should always use the Session Present flag in the CONNACK to determine whether the Server has a Session State for this Client.

 

Non-normative comment

The Client can avoid implementing its own Session expiry and instead rely on the Session Present flag returned from the Server to determine if the Session had expired. If the Client does implement its own Session expiry, it needs to store the time at which the Session State will be deleted as part of its Session State.

3.1.2.11.3 Will Delay Interval

24 (0x18) Byte, Identifier of the Will Delay Interval.

Followed by the Four Byte Integer representing the Will Delay Interval in seconds. It is a Protocol Error to include the Will Delay Interval more than once. If the Will Delay Interval is absent, the default value is 0 and there is no delay before the Will Message is published.

 

The Server delays publishing the Client’s Will Message until the Will Delay Interval has passed or the Session ends, whichever happens first. If a new Network Connection to this Session is made before the Will Delay Interval has passed, the Server MUST NOT send the Will Message [MQTT-3.1.2-26].

 

Non-normative comment

One use of this is to avoid publishing Will Messages if there is a temporary network disconnection and the Client succeeds in reconnecting and continuing its Session before the Will Message is published.

 

Non-normative comment

If a Network Connection uses a Client Identifier of an existing Network Connection to the Server, the Will Message for the exiting connection is sent unless the new connection specifies Clean Start of 0 and the Will Delay is greater than zero. If the Will Delay is 0 the Will Message is sent at the close of the existing Network Connection, and if Clean Start is 1 the Will Message is sent because the Session ends.

 

3.1.2.11.4 Receive Maximum

33 (0x21) Byte, Identifier of the Receive Maximum.

Followed by the Two Byte Integer representing the Receive Maximum value. It is a Protocol Error to include the Receive Maximum value more than once or for it to have the value 0.

 

The Client uses this value to limit the number of QoS 1 and QoS 2 publications that it is willing to process concurrently. There is no mechanism to limit the QoS 0 publications that the Server might try to send.

 

The value of Receive Maximum applies only to the current Network Connection. If the Receive Maximum value is absent then its value defaults to 65,535.

 

Refer to section 4.9 Flow Control for details of how the Receive Maximum is used.

 

3.1.2.11.5 Maximum Packet Size

39 (0x27) Byte, Identifier of the Maximum Packet Size.

Followed by a Four Byte Integer representing the Maximum Packet Size the Client is willing to accept. If the Maximum Packet Size is not present, no limit on the packet size is imposed beyond the limitations in the protocol as a result of the remaining length encoding and the protocol header sizes.

 

It is a Protocol Error to include the Maximum Packet Size more than once, or for the value to be set to zero or greater than 2,684,354,565.

 

            Non-normative comment

It is the responsibility of the application to select a suitable Maximum Packet Size value if it chooses to restrict the Maximum Packet Size.

 

The packet size is the total number of bytes in an MQTT Control Packet, as defined in section 2.1.4. The Client uses the Maximum Packet Size to inform the Server that it will not process packets exceeding this limit.

 

The Server MUST NOT send packets exceeding Maximum Packet Size to the Client [MQTT-3.1.2-27]. If a Client receives a packet whose size exceeds this limit, this is a Protocol Error, the Client uses DISCONNECT with Reason Code 0x95 (Packet too large), as described in section 4.13.

 

Where a Packet is too large to send, the Server MUST discard it without sending it and then behave as if it had completed sending that publication [MQTT-3.1.2-28].

 

In the case of a Shared Subscription where the message is too large to send to one or more of the Clients but other Clients can receive it, the Server can choose either discard the message without sending the message to any of the Clients, or to send the message to one of the Clients that can receive it.

 

Non-normative comment

Where a packet is discarded without being sent, the Server could place the discarded packet on a ‘dead letter queue’ or perform other diagnostic action. Such actions are outside the scope of this specification.

 

3.1.2.11.6 Topic Alias Maximum

34 (0x22) Byte, Identifier of the Topic Alias Maximum.

Followed by the Two Byte Integer representing the Topic Alias Maximum value. It is a Protocol Error to include the Topic Alias Maximum value more than once. If the Topic Alias Maximum property is absent, the default value is 0.

 

This value indicates the highest value that the Client will accept as a Topic Alias sent by the Server. The Client uses this value to limit the number of Topic Aliases that it is willing to hold on this Connection. The Server MUST NOT send a Topic Alias in a PUBLISH packet to the Client greater than Topic Alias Maximum [MQTT-3.1.2-29]. A value of 0 indicates that the Client does not accept any Topic Aliases on this connection. If Topic Alias Maximum is absent or zero, the Server MUST NOT send any Topic Aliases to the Client [MQTT-3.1.2-30].

 

3.1.2.11.7 Request Response Information

25 (0x19) Byte, Identifier of the Request Response Information.

Followed by a Byte with a value of either 0 or 1. It is Protocol Error to include the Request Response Information more than once, or to have a value other than 0 or 1. If the Request Response Information is absent, the value of 0 is used.

 

The Client uses this value to request the Server to return Response Information in the CONNACK. A value of 0 indicates that the Server MUST NOT return Response Information [MQTT-3.1.2-31]. If the value is 1 the Server MAY return Response Information in the CONNACK packet.

 

Non-normative comment

The Server can choose not to include Response Information in the CONNACK, even if the Client requested it.

 

Refer to section 4.10 for more information about Request / Response.

 

3.1.2.11.8 Request Problem Information

23 (0x17) Byte, Identifier of the Request Problem Information.

Followed by a Byte with a value of either 0 or 1. It is a Protocol Error to include Request Problem Information more than once, or to have a value other than 0 or 1. If the Request Problem Information is absent, the value of 1 is used.

 

The Client uses this value to indicate whether the Reason String or User Properties are sent in the case of failures.

 

If the value of Request Problem Information is 0, the Server MAY return a Reason String or User Properties on a CONNACK or DISCONNECT packet, but MUST NOT send a Reason String or User Properties on any packet other than PUBLISH, CONNACK, or DISCONNECT [MQTT-3.1.2-32]. If the value is 0 and the Client receives a Reason String or User Properties in a packet other than PUBLISH, CONNACK, or DISCONNECT, it uses a DISCONNECT packet with Reason Code 0x82 (Protocol Error) as described in section 4.13 Handling errors.

 

If this value is 1, the Server MAY return a Reason String or User Properties on any packet where it is allowed.

 

3.1.2.11.9 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by a UTF-8 String Pair.

 

The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

Non-normative comment

User Properties on the CONNECT packet can be used to send connection related properties from the Client to the Server. The meaning of these properties is not defined by this specification.

 

3.1.2.11.10 Authentication Method

21 (0x15) Byte, Identifier of the Authentication Method.

Followed by a UTF-8 Encoded String containing the name of the authentication method used for extended authentication .It is a Protocol Error to include Authentication Method more than once.

If Authentication Method is absent, extended authentication is not performed. Refer to section 4.12.

 

If a Client sets an Authentication Method in the CONNECT, the Client MUST NOT send any packets other than AUTH or DISCONNECT packets until it has received a CONNACK packet [MQTT-3.1.2-33].

 

3.1.2.11.11 Authentication Data

22 (0x16) Byte, Identifier of the Authentication Data.

Followed by Binary Data containing authentication data. It is a Protocol Error to include Authentication Data if there is no Authentication Method. It is a Protocol Error to include Authentication Data more than once.

 

The contents of this data are defined by the authentication method. Refer to section 4.12 for more information about extended authentication.

 

3.1.2.12 Variable Header non-normative example

Figure 3‑6 - Variable Header non-normative example

 

Description

7

6

5

4

3

2

1

0

Protocol Name

byte 1

Length MSB (0)

0

0

0

0

0

0

0

0

byte 2

Length LSB (4)

0

0

0

0

0

1

0

0

byte 3

‘M’

0

1

0

0

1

1

0

1

byte 4

‘Q’

0

1

0

1

0

0

0

1

byte 5

‘T’

0

1

0

1

0

1

0

0

byte 6

‘T’

0

1

0

1

0

1

0

0

Protocol Version

 

Description

7

6

5

4

3

2

1

0

byte 7

Version (5)

0

0

0

0

0

1

0

1

Connect Flags

 

 

 

 

byte 8

User Name Flag (1)

Password Flag (1)

Will Retain (0)

Will QoS (01)

Will Flag (1)

Clean Start(1)

Reserved (0)

 

 

 

 

1

 

 

 

 

1

 

 

 

 

0

 

 

 

 

0

 

 

 

 

1

 

 

 

 

1

 

 

 

 

1

 

 

 

 

0

Keep Alive

byte 9

Keep Alive MSB (0)

0

0

0

0

0

0

0

0

byte 10

Keep Alive LSB (10)

0

0

0

0

1

0

1

0

Properties

byte 11

Length (5)

0

0

0

0

0

1

0

1

byte 12

Session Expiry Interval identifier (17)

0

0

0

1

0

0

0

1

byte 13

Session Expiry Interval (10)

0

0

0

0

0

0

0

0

byte 14

0

0

0

0

0

0

0

0

byte 15

0

0

0

0

0

0

0

0

byte 16

0

0

0

0

1

0

1

0

 

3.1.3 CONNECT Payload

The Payload of the CONNECT packet contains one or more length-prefixed fields, whose presence is determined by the flags in the Variable Header. These fields, if present, MUST appear in the order Client Identifier, Will Topic, Will Message, User Name, Password [MQTT-3.1.3-1].

 

3.1.3.1 Client Identifier (ClientID)

The Client Identifier (ClientID) identifies the Client to the Server. 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-2]. Refer to section 4.1 for more information about Session State.

 

The ClientID MUST be present and is the first field in the CONNECT packet Payload [MQTT-3.1.3-3].

 

The ClientID MUST be a UTF-8 Encoded String as defined in Section 1.5.4 [MQTT-3.1.3-4]. 

The Server MUST allow ClientID’s which are between 1 and 23 UTF-8 encoded bytes in length, and that contain only the characters

"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" [MQTT-3.1.3-5].

 

The Server MAY allow ClientID’s that contain more than 23 encoded bytes. The Server MAY allow ClientID’s that contain characters not included in the list given above.

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 [MQTT-3.1.3-6]. It MUST then process the CONNECT packet as if the Client had provided that unique ClientID, and MUST return the Assigned Client Identifier in the CONNACK packet [MQTT-3.1.3-7].

If the Server rejects the ClientID it MAY respond to the CONNECT packet with a CONNACK using Reason Code 0x85 (Client Identifier not valid) as described in section 4.13 Handling errors, and then it MUST close the Network Connection [MQTT-3.1.3-8].

 

Non-normative comment

A Client implementation could provide a convenience method to generate a random ClientID. Clients using this method should take care to avoid creating long-lived orphaned Sessions.

 

3.1.3.2 Will Topic

If 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 Encoded String as defined in Section 1.5.4 [MQTT-3.1.3-9].

 

3.1.3.3 Will Message

If the Will Flag is set to 1 the Will Message is the next field in the Payload. The Will Message defines the Application Message Payload that is to be published to the Will Topic as described in Section 3.1.2.5. This field consists of Binary Data.

 

3.1.3.4 User Name

If the User Name Flag is set to 1, the User Name is the next field in the Payload. The User Name MUST be a UTF-8 Encoded String as defined in Section 1.5.4 [MQTT-3.1.3-10]. It can be used by the Server for authentication and authorization.

 

3.1.3.5 Password

If the Password Flag is set to 1, the Password is the next field in the Payload. The Password field is Binary Data. Although this field is called Password, it can be used to carry any credential information.

 

3.1.4 CONNECT Actions

Note that a Server MAY support multiple protocols (including other versions of the MQTT protocol) on the same TCP port or other network endpoint. If the Server determines that the protocol is MQTT v5.0 then it validates the connection attempt as follows.

 

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 Network Connection.

2.     The Server MUST validate that the CONNECT packet conforms to section 3.1 and close the Network Connection if it does not conform [MQTT-3.1.4-1]. The Server MAY send a CONNACK with a Reason Code of 0x80 or greater as described in section 4.13 before closing the Network Connection.

  1. The Server MAY check that the contents of the CONNECT packet meet any further restrictions and SHOULD perform authentication and authorization checks. If any of these checks fail, it MUST close the Network Connection [MQTT-3.1.4-2]. Before closing the Network Connection, it MAY send an appropriate CONNACK response with a Reason Code of 0x80 or greater as described in sections 3.2 and 4.13.

 

If validation is successful, the Server performs the following steps.

 

1.     If the ClientID represents a Client already connected to the Server, the Server sends a DISCONNECT packet to the existing Client with Reason Code of 0x8E (Session taken over) as described in section 4.13 and MUST close the Network Connection of the existing Client [MQTT-3.1.4-3]. If the existing Client has a Will Message, that Will Message is published as described in section 3.1.2.5.

 

Non-normative comment

If the Will Delay Interval of the existing Network Connection is 0 and there is a Will Message, it will be sent because the Network Connection is closed. If the Session Expiry Interval of the existing Network Connection is 0, or the new Network Connection has Clean Start set to 1 then if the existing Network Connection has a Will Message it will be sent because the original Session is ended on the takeover.

 

2.     The Server MUST perform the processing of Clean Start that is described in section 3.1.2.4 [MQTT-3.1.4-4].

 

3.     The Server MUST acknowledge the CONNECT packet with a CONNACK packet containing a 0x00 (Success) Reason Code [MQTT-3.1.4-5].

Non-normative comment 
It is recommended that authentication and authorization checks be performed if the Server is being used to process any form of business critical data. If these checks succeed, the Server responds by sending CONNACK with a 0x00 (Success) Reason Code. If they fail, it is suggested that the Server does not to send a CONNACK at all, as this could alert a potential attacker to the presence of the MQTT Server and encourage such an attacker to launch a denial of service or password-guessing attack.

 

4.     Start message delivery and Keep Alive monitoring.

 

Clients are allowed to send further MQTT Control Packets immediately after sending a CONNECT packet; Clients need not wait for a CONNACK packet to arrive from the Server. If the Server rejects the CONNECT, it MUST NOT process any data sent by the Client after the CONNECT packet except AUTH packets [MQTT-3.1.4-6].

Non-normative comment
Clients typically wait for a CONNACK packet, However, if the Client exploits its freedom to send MQTT 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.

 

Non-normative comment
Clients that send MQTT Control Packets before they receive CONNACK will be unaware of the Server constraints and whether any existing Session is being used.

 

3.2 CONNACK – Connect acknowledgement

The CONNACK packet is the packet sent by the Server in response to a CONNECT packet received from a Client. The Server MUST send a CONNACK with a 0x00 (Success) Reason Code before sending any Packet other than AUTH [MQTT-3.2.0-1]. The Server MUST NOT send more than one CONNACK in a Network Connection [MQTT-3.2.0-2].

 

If the Client does not receive a CONNACK packet from the Server within a reasonable amount of time, the Client SHOULD close the Network Connection. A "reasonable" amount of time depends on the type of application and the communications infrastructure.

 

3.2.1 CONNACK Fixed Header

The Fixed Header format is illustrated in Figure 3‑7 – CONNACK packet ._Figure_3.8_–

Figure 3‑7 – CONNACK packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet Type (2)

Reserved

 

0

0

1

0

0

0

0

0

byte 2

Remaining Length

 

Remaining Length field

This is the length of the Variable Header encoded as a Variable Byte Integer.

 

3.2.2 CONNACK Variable Header

The Variable Header of the CONNACK Packet contains the following fields in the order: Connect Acknowledge Flags, Connect Reason Code, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

3.2.2.1 Connect Acknowledge Flags

Byte 1 is the "Connect Acknowledge Flags". Bits 7-1 are reserved and MUST be set to 0 [MQTT-3.2.2-1]. 

Bit 0 is the Session Present Flag. 

 

3.2.2.1.1 Session Present 

Position: bit 0 of the Connect Acknowledge Flags. 


The Session Present flag informs the Client whether the Server is using Session State from a previous connection for this ClientID. This allows the Client and Server to have a consistent view of the Session State. 


If the Server accepts a connection with Clean Start set to 1, the Server MUST set Session Present to 0 in the CONNACK packet in addition to setting a 0x00 (Success) Reason Code in the CONNACK packet [MQTT-3.2.2-2].

If the Server accepts a connection with Clean Start set to 0 and the Server has Session State for the ClientID, it MUST set Session Present to 1 in the CONNACK packet, otherwise it MUST set Session Present to 0 in the CONNACK packet. In both cases it MUST set a 0x00 (Success) Reason Code in the CONNACK packet [MQTT-3.2.2-3].


If the value of Session Present received by the Client from the Server is not as expected, the Client proceeds as follows:

·         If the Client does not have Session State and receives Session Present set to 1 it MUST close the Network Connection [MQTT-3.2.2-4]. If it wishes to restart with a new Session the Client can reconnect using Clean Start set to 1.

·         If the Client does have Session State and receives Session Present set to 0 it MUST discard its Session State if it continues with the Network Connection [MQTT-3.2.2-5].



If a Server sends a CONNACK packet containing a non-zero Reason Code it MUST set Session Present to 0 [MQTT-3.2.2-6].

 

3.2.2.2 Connect Reason Code

Byte 2 in the Variable Header is the Connect Reason Code.

 

The values the Connect Reason Code are listed in Table 3‑1 - Connect Reason Code values. If a well formed CONNECT packet is received by the Server, but the Server is unable to complete the Connection the Server MAY send a CONNACK packet containing the appropriate Connect Reason code from this table. If a Server sends a CONNACK packet containing a Reason code of 128 or greater it MUST then close the Network Connection [MQTT-3.2.2-7].

_Table_3.1_-

Table 3‑1 - Connect Reason Code values

Value

Hex

Reason Code name

Description

0

0x00

Success

The Connection is accepted.

128

0x80

Unspecified error

The Server does not wish to reveal the reason for the failure, or none of the other Reason Codes apply.

129

0x81

Malformed Packet

Data within the CONNECT packet could not be correctly parsed.

130

0x82

Protocol Error

Data in the CONNECT packet does not conform to this specification.

131

0x83

Implementation specific error

The CONNECT is valid but is not accepted by this Server.

132

0x84

Unsupported Protocol Version

The Server does not support the version of the MQTT protocol requested by the Client.

133

0x85

Client Identifier not valid

The Client Identifier is a valid string but is not allowed by the Server.

134

0x86

Bad User Name or Password

The Server does not accept the User Name or Password specified by the Client

135

0x87

Not authorized

The Client is not authorized to connect.

136

0x88

Server unavailable

The MQTT Server is not available.

137

0x89

Server busy

The Server is busy. Try again later.

138

0x8A

Banned

This Client has been banned by administrative action. Contact the server administrator.

140

0x8C

Bad authentication method

The authentication method is not supported or does not match the authentication method currently in use.

144

0x90

Topic Name invalid

The Will Topic Name is not malformed, but is not accepted by this Server.

149

0x95

Packet too large

The CONNECT packet exceeded the maximum permissible size.

151

0x97

Quota exceeded

An implementation or administrative imposed limit has been exceeded.

154

0x9A

Retain not supported

The Server does not support retained messages, and Will Retain was set to 1.

155

0x9B

QoS not supported

The Server does not support the QoS set in Will QoS.

156

0x9C

Use another server

The Client should temporarily use another server.

157

0x9D

Server moved

The Client should permanently use another server.

159

0x9F

Connection rate exceeded

The connection rate limit has been exceeded.

 

The Server MUST use one of the Reason Code values in Table 3‑1 - Connect Reason Code values [MQTT-3.2.2-8].

 

Non-normative comment

Reason Code 0x80 (Unspecified error) may be used where the Server knows the reason for the failure but does not wish to reveal it to the Client, or when none of the other Reason Code values applies.

 

The Server may choose to close the Network Connection without sending a CONNACK to enhance security in the case where an error is found on the CONNECT. For instance, when on a public network and the connection has not been authorized it might be unwise to indicate that this is an MQTT Server.

 

3.2.2.3 CONNACK Properties

3.2.2.3.1 Property Length

This is the length of the Properties in the CONNACK packet Variable Header encoded as a Variable Byte Integer.

 

3.2.2.3.2 Receive Maximum

33 (0x21) Byte, Identifier of the Receive Maximum.

Followed by the Two Byte Integer representing the Receive Maximum value. It is a Protocol Error to include the Receive Maximum value more than once or for it to have the value 0.

 

The Server uses this value to limit the number of QoS 1 and QoS 2 publications that it is willing to process concurrently for the Client. It does not provide a mechanism to limit the QoS 0 publications that the Client might try to send.

 

If the Receive Maximum value is absent, then its value defaults to 65,535.

 

Refer to section 4.9 Flow Control for details of how the Receive Maximum is used.

 

3.2.2.3.3 Maximum QoS

36 (0x24) Byte, Identifier of the Maximum QoS.

Followed by a Byte with a value of either 0 or 1. It is a Protocol Error to include Maximum QoS more than once, or to have a value other than 0 or 1. If the Maximum QoS is absent, the Client uses a Maximum QoS of 2.

 

If a Server does not support QoS 1 or QoS 2 PUBLISH packets it MUST send a Maximum QoS in the CONNACK packet specifying the highest QoS it supports [MQTT-3.2.2-9]. A Server that does not support QoS 1 or QoS 2 PUBLISH packets MUST still accept SUBSCRIBE packets containing a Requested QoS of 0, 1 or 2 [MQTT-3.2.2-10]

If a Client receives a Maximum QoS from a Server, it MUST NOT send PUBLISH packets at a QoS level exceeding the Maximum QoS level specified [MQTT-3.2.2-11]. It is a Protocol Error if the Server receives a PUBLISH packet with a QoS greater than the Maximum QoS it specified. In this case use DISCONNECT with Reason Code 0x9B (QoS not supported) as described in section 4.13 Handling errors.

If a Server receives a CONNECT packet containing a Will QoS that exceeds its capabilities, it MUST reject the connection. It SHOULD use a CONNACK packet with Reason Code 0x9B (QoS not supported) as described in section 4.13 Handling errors, and MUST close the Network Connection [MQTT-3.2.2-12].

Non-normative comment

A Client does not need to support QoS 1 or QoS 2 PUBLISH packets. If this is the case, the Client simply restricts the maximum QoS field in any SUBSCRIBE commands it sends to a value it can support.

 

3.2.2.3.4 Retain Available

37 (0x25) Byte, Identifier of Retain Available.

Followed by a Byte field. If present, this byte declares whether the Server supports retained messages. A value of 0 means that retained messages are not supported. A value of 1 means retained messages are supported. If not present, then retained messages are supported. It is a Protocol Error to include Retain Available more than once or to use a value other than 0 or 1.

 

If a Server receives a CONNECT packet containing a Will Message with the Will Retain set to 1, and it does not support retained publications, the Server MUST reject the connection request. It SHOULD send CONNACK with Reason Code 0x9A (Retain not supported) and then it MUST close the Network Connection [MQTT-3.2.2-13].

 

A Client receiving Retain Available from the Server MUST NOT send a PUBLISH packet with the RETAIN flag set to 1 [MQTT-3.2.2-14]. If the Server receives such a packet, this is a Protocol Error. The Server SHOULD send a DISCONNECT with Reason Code of 0x9A (Retain not supported) as described in section 4.13.

 

3.2.2.3.5 Maximum Packet Size

39 (0x27) Byte, Identifier of the Maximum Packet Size.

Followed by a Four Byte Integer representing the Maximum Packet Size the Server is willing to accept. If the Maximum Packet Size is not present, there is no limit on the packet size imposed beyond the limitations in the protocol as a result of the remaining length encoding and the protocol header sizes.

 

It is a Protocol Error to include the Maximum Packet Size more than once, or for the value to be set to zero or greater than 2,684,354,565.

 

The packet size is the total number of bytes in an MQTT Control Packet, as defined in section 2.1.4. The Server uses the Maximum Packet Size to inform the Client that it will not process packets whose size exceeds this limit.

 

The Client MUST NOT send packets exceeding Maximum Packet Size to the Server [MQTT-3.2.2-15]. If a Server receives a packet whose size exceeds this limit, this is a Protocol Error, the Server uses DISCONNECT with Reason Code 0x95 (Packet too large), as described in section 4.13.

 

3.2.2.3.6 Assigned Client Identifier

18 (0x12) Byte, Identifier of the Assigned Client Identifier.

Followed by the UTF-8 string which is the Assigned Client Identifier. It is a Protocol Error to include the Assigned Client Identifier more than once.

 

The Client Identifier which was assigned by the Server because a zero length Client Identifier was found in the CONNECT packet.

 

If the Client connects using a zero length Client Identifier, the Server MUST respond with a CONNACK containing an Assigned Client Identifier. The Assigned Client Identifier MUST be a new Client Identifier not used by any other Session currently in the Server [MQTT-3.2.2-16].

 

3.2.2.3.7 Topic Alias Maximum

34 (0x22) Byte, Identifier of the Topic Alias Maximum.

Followed by the Two Byte Integer representing the Topic Alias Maximum value. It is a Protocol Error to include the Topic Alias Maximum value more than once. If the Topic Alias Maximum property is absent, the default value is 0.


This value indicates the highest value that the Server will accept as a Topic Alias sent by the Client. The Server uses this value to limit the number of Topic Aliases that it is willing to hold on this Connection. The Client MUST NOT send a Topic Alias in a PUBLISH packet to the Server greater than this value [MQTT-3.2.2-17]. A value of 0 indicates that the Server does not accept any Topic Aliases on this connection. If Topic Alias Maximum is absent or 0, the Client MUST NOT send any Topic Aliases on to the Server [MQTT-3.2.2-18].

 

3.2.2.3.8 Reason String

31 (0x1F) Byte Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason associated with this response. This Reason String is a human readable string designed for diagnostics and SHOULD NOT be parsed by the Client.

 

The Server uses this value to give additional information to the Client. The Server MUST NOT send this property if it would increase the size of the CONNACK packet beyond the Maximum Packet Size specified by the Client [MQTT-3.2.2-19]. It is a Protocol Error to include the Reason String more than once.

 

Non-normative comment

Proper uses for the reason string in the Client would include using this information in an exception thrown by the Client code, or writing this string to a log.

 

3.2.2.3.9 User Property

38 (0x26) Byte, Identifier of User Property.

Followed by a UTF-8 String Pair. This property can be used to provide additional information to the Client including diagnostic information. The Server MUST NOT send this property if it would increase the size of the CONNACK packet beyond the Maximum Packet Size specified by the Client [MQTT-3.2.2-20]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

The content and meaning of this property is not defined by this specification.  The receiver of a CONNACK containing this property MAY ignore it.

 

3.2.2.3.10 Wildcard Subscription Available

40 (0x28) Byte, Identifier of Wildcard Subscription Available.

Followed by a Byte field. If present, this byte declares whether the Server supports Wildcard Subscriptions. A value is 0 means that Wildcard Subscriptions are not supported. A value of 1 means Wildcard Subscriptions are supported. If not present, then Wildcard Subscriptions are supported. It is a Protocol Error to include the Wildcard Subscription Available more than once or to send a value other than 0 or 1.

 

If the Server receives a SUBSCRIBE packet containing a Wildcard Subscription and it does not support Wildcard Subscriptions, this is a Protocol Error. The Server uses DISCONNECT with Reason Code 0xA2 (Wildcard subscription not supported) as described in section 4.13.

 

If a Server supports Wildcard Subscriptions, it can still reject a particular subscribe request containing a Wildcard Subscription. In this case the Server MAY send a SUBACK Control Packet with a Reason Code 0xA2 (Wildcard Subscriptions not supported).

 

3.2.2.3.11 Subscription Identifiers Available

41 (0x29) Byte, Identifier of Subscription Identifier Available.

Followed by a Byte field. If present, this byte declares whether the Server supports Subscription Identifiers. A value is 0 means that Subscription Identifiers are not supported. A value of 1 means Subscription Identifiers are supported. If not present, then Subscription Identifiers are supported. It is a Protocol Error to include the Subscription Identifier Available more than once, or to send a value other than 0 or 1.

 

If the Server receives a SUBSCRIBE packet containing Subscription Identifier and it does not support Subscription Identifiers, this is a Protocol Error. The Server uses DISCONNECT with Reason Code of 0xA1 (Subscription Identifiers not supported) as described in section 4.13.

 

3.2.2.3.12 Shared Subscription Available

42 (0x2A) Byte, Identifier of Shared Subscription Available.

Followed by a Byte field. If present, this byte declares whether the Server supports Shared Subscriptions. A value is 0 means that Shared Subscriptions are not supported. A value of 1 means Shared Subscriptions are supported. If not present, then Shared Subscriptions are supported. It is a Protocol Error to include the Shared Subscription Available more than once or to send a value other than 0 or 1.

 

If the Server receives a SUBSCRIBE packet containing Shared Subscriptions and it does not support Shared Subscriptions, this is a Protocol Error. The Server uses DISCONNECT with Reason Code 0x9E (Shared Subscription not supported) as described in section 4.13.

 

3.2.2.3.13 Server Keep Alive

19 (0x13) Byte, Identifier of the Server Keep Alive.

Followed by a Two Byte Integer with the Keep Alive time assigned by the Server. If the Server sends a Server Keep Alive on the CONNACK packet, the Client MUST use this value instead of the Keep Alive value the Client sent on CONNECT [MQTT-3.2.2-21]. If the Server does not send the Server Keep Alive, the Server MUST use the Keep Alive value set by the Client on CONNECT [MQTT-3.2.2-22]. It is a Protocol Error to include the Server Keep Alive more than once.

 

Non-normative comment

The primary use of the Server Keep Alive is for the Server to inform the Client that it will disconnect the Client for inactivity sooner than the Keep Alive specified by the Client.

 

3.2.2.3.14 Response Information

26 (0x1A) Byte, Identifier of the Response Information.

Followed by a UTF-8 Encoded String which is used as the basis for creating a Response Topic. The way in which the Client creates a Response Topic from the Response Information is not defined by this specification. It is a Protocol Error to include the Response Information more than once.

 

If the Client sends a Request Response Information with a value 1, it is OPTIONAL for the Server to send the Response Information in the CONNACK.

 

Non-normative comment

A common use of this is to pass a globally unique portion of the topic tree which is reserved for this Client for at least the lifetime of its Session. This often cannot just be a random name as both the requesting Client and the responding Client need to be authorized to use it. It is normal to use this as the root of a topic tree for a particular Client. For the Server to return this information, it normally needs to be correctly configured. Using this mechanism allows this configuration to be done once in the Server rather than in each Client.

 

Refer to section 4.10 for more information about Request / Response.

 

3.2.2.3.15 Server Reference

28 (0x1C) Byte, Identifier of the Server Reference.

Followed by a UTF-8 Encoded String which can be used by the Client to identify another Server to use. It is a Protocol Error to include the Server Reference more than once.

 

The Server uses a Server Reference in either a CONNACK or DISCONNECT packet with Reason code of 0x9C (Use another server) or Reason Code 0x9D (Server moved) as described in section 4.13.

 

Refer to section 4.11 Server redirection for information about how Server Reference is used.

 

3.2.2.3.16 Authentication Method

21 (0x15) Byte, Identifier of the Authentication Method.

Followed by a UTF-8 Encoded String containing the name of the authentication method. It is a Protocol Error to include the Authentication Method more than once. Refer to section 4.12 for more information about extended authentication.

 

3.2.2.3.17 Authentication Data

22 (0x16) Byte, Identifier of the Authentication Data.

Followed by Binary Data containing authentication data. The contents of this data are defined by the authentication method and the state of already exchanged authentication data. It is a Protocol Error to include the Authentication Data more than once. Refer to section 4.12 for more information about extended authentication.

 

3.2.3 CONNACK Payload

The CONNACK packet has no Payload.

 

3.3 PUBLISH – Publish message

A PUBLISH packet is sent from a Client to a Server or from a Server to a Client to transport an Application Message.

 

3.3.1 PUBLISH Fixed Header

Figure 3‑8 – PUBLISH packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (3)

DUP flag

QoS level

RETAIN

 

0

0

1

1

X

X

X

X

byte 2…

Remaining Length

 

3.3.1.1 DUP

Position: byte 1, bit 3.

If the DUP flag is set to 0, it indicates that this is the first occasion that the Client or Server has attempted to send this PUBLISH packet. If the DUP flag is set to 1, it indicates that this might be re-delivery of an earlier attempt to send the packet.

 

The DUP flag MUST be set to 1 by the Client or Server when it attempts to re-deliver a PUBLISH packet [MQTT-3.3.1-1]. The DUP flag MUST be set to 0 for all QoS 0 messages [MQTT-3.3.1-2].

 

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-3].

 

Non-normative comment

The receiver of an MQTT Control Packet that contains the DUP flag set to 1 cannot assume that it has seen an earlier copy of this packet.

 

Non-normative comment

It is important to note that the DUP flag refers to the MQTT 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.2.1 provides more information about Packet Identifiers.

 

3.3.1.2 QoS

Position: byte 1, bits 2-1.

This field indicates the level of assurance for delivery of an Application Message. The QoS levels are listed in the Table 3.2 - QoS definitions, below._Table_3.11_-

 

Table 3‑2 - QoS definitions

QoS value

Bit 2

bit 1

Description

0

0

0

At most once delivery

1

0

1

At least once delivery

2

1

0

Exactly once delivery

-

1

1

Reserved – must not be used

 

If the Server included a Maximum QoS in its CONNACK response to a Client and it receives a PUBLISH packet with a QoS greater than this, then it uses DISCONNECT with Reason Code 0x9B (QoS not supported) as described in section 4.13 Handling errors.

 

A PUBLISH Packet MUST NOT have both QoS bits set to 1 [MQTT-3.3.1-4]. If a Server or Client receives a PUBLISH packet which has both QoS bits set to 1 it is a Malformed Packet. Use DISCONNECT with Reason Code 0x81 (Malformed Packet) as described in section 4.13.

 

3.3.1.3 RETAIN

Position: byte 1, bit 0.

 

If the RETAIN flag is set to 1 in a PUBLISH packet sent by a Client to a Server, the Server MUST replace any existing retained message for this topic and store the Application Message and its QoS [MQTT-3.3.1-5], so that it can be delivered to future subscribers whose subscriptions match its Topic Name. If the Payload contains zero bytes it is processed normally by the Server but any 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-6]. A zero length retained message MUST NOT be stored as a retained message on the Server [MQTT-3.3.1-7].

 

If the RETAIN flag is 0 in a PUBLISH packet sent by a Client to a Server, the Server MUST NOT store the message as a retained message and MUST NOT remove or replace any existing retained message [MQTT-3.3.1-8].

 

If the Server included Retain Available in its CONNACK response to a Client with its value set to 0 and it receives a PUBLISH packet with the RETAIN flag is set to 1, then it uses the DISCONNECT Reason Code of 0x9A (Retain not supported) as described in section 4.13.

 

When a new Non-Shared Subscription is established, the last retained message, if any, on each matching topic name is sent to the Client. These messages are sent with the RETAIN flag set to 1. Which retained messages are sent is controlled by the Retain Handling Subscription Option. Refer to section 3.8.3.1 for a definition of the Subscription Options.

·         If Retain Handling is set to 0 the Server MUST send all retained messages matching the Topic Filter of the subscription to the Client [MQTT-3.3.1-9].

·         If Retain Handling is set to 1 and the subscription did not already exist, the Server MUST send all retained message matching the Topic Filter of the subscription to the Client [MQTT-3.3.1-10].

·         If Retain Handling is set to 2, the Server MUST NOT send retained messages at the time of the subscribe [MQTT-3.3.1-11].

 

If the Server receives a PUBLISH packet with the RETAIN flag set to 1, and QoS 0 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.

 

If the current retained message for a Topic expires, it is discarded and there will be no retained message for that topic.

 

The setting of the RETAIN flag in an Application Message forwarded by the Server from an established connection is controlled by the Retain As Published subscription option. Refer to section 3.8.3.1 for a definition of the Subscription Options.

 

·         If the value of Retain As Published subscription option is set to 0, the Server MUST set the RETAIN flag to 0 when forwarding an Application Message regardless of how the RETAIN flag was set in the received PUBLISH packet [MQTT-3.3.1-12].

·         If the value of Retain As Published subscription option is set to 1, the Server MUST set the RETAIN flag equal to the RETAIN flag in the received PUBLISH packet [MQTT-3.3.1-13].

 

Non-normative comment

Retained messages are useful where publishers send state messages on an irregular basis. A new non-shared subscriber will receive the most recent state.

 

3.3.1.4 Remaining Length

This is the length of Variable Header plus the length of the Payload, encoded as a Variable Byte Integer.

 

3.3.2 PUBLISH Variable Header

The Variable Header of the PUBLISH Packet contains the following fields in the order: Topic Name, Packet Identifier, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

3.3.2.1 Topic Name

The Topic Name identifies the information channel to which Payload data is published.

 

The Topic Name MUST be present as the first field in the PUBLISH packet Variable Header. It MUST be a UTF-8 Encoded String as defined in section 1.5.4 [MQTT-3.3.2-1].

 

The Topic Name in the PUBLISH packet MUST NOT contain wildcard characters [MQTT-3.3.2-2].

 

The Topic Name in a PUBLISH packet sent by a Server to a subscribing Client MUST match the Subscription’s Topic Filter according to the matching process defined in Section 4.7 [MQTT-3.3.2-3]. However, as the Server is permitted to map the Topic Name to another name, it might not be the same as the Topic Name in the original PUBLISH packet.

 

To reduce the size of the PUBLISH packet the sender can use a Topic Alias. The Topic Alias is described in section 3.3.2.3.4. It is a Protocol Error if the Topic Name is zero length and there is no Topic Alias.

 

3.3.2.2 Packet Identifier

The Packet Identifier field is only present in PUBLISH packets where the QoS level is 1 or 2. Section 2.2.1 provides more information about Packet Identifiers.

 

3.3.2.3 PUBLISH Properties

3.3.2.3.1 Property Length

The length of the Properties in the PUBLISH packet Variable Header encoded as a Variable Byte Integer.

 

3.3.2.3.2 Payload Format Indicator

1 (0x01) Byte, Identifier of the Payload Format Indicator.

Followed by the value of the Payload Format Indicator, either of:

·         0 (0x00) Byte Indicates that the Payload is unspecified bytes, which is equivalent to not sending a Payload Format Indicator.

·         1 (0x01) Byte Indicates that the Payload is UTF-8 Encoded Character Data. The UTF-8 data in the Payload does not include a length prefix, nor is it subject to the restrictions described in section 1.5.4.

 

A Server MUST send the Payload Format Indicator unaltered to all subscribers receiving the publication [MQTT-3.3.2-4]. The receiver MAY validate that the Payload is of the format indicated, and if it is not send a PUBACK, PUBREC, or DISCONNECT with Reason Code of 0x99 (Payload format invalid) as described in section 4.13.

 

3.3.2.3.3 Publication Expiry Interval

2 (0x02) Byte, Identifier of the Publication Expiry Interval.

Followed by the Four Byte Integer representing the Publication Expiry Interval.

 

If present, the Four Byte value is the lifetime of the publication in seconds. If the Publication Expiry Interval has passed and the Server has not managed to start onward delivery to a matching subscriber, then it MUST delete the copy of the message for that subscriber [MQTT-3.3.2-5].

 

If absent, the publication does not expire.

 

The PUBLISH packet sent to a Client by the Server MUST contain a Publication Expiry Interval set to the received value minus the time that the publication has been waiting in the Server [MQTT-3.3.2-6]. Refer to section 4.1 for details and limitations of stored state.

 

3.3.2.3.4 Topic Alias

35 (0x23) Byte, Identifier of the Topic Alias.

Followed by the Two Byte integer representing the Topic Alias value. It is a Protocol Error to include the Topic Alias value more than once.

 

A Topic Alias is an integer value that is used to identify the Topic instead of using the Topic Name. This reduces the size of the PUBLISH packet, and is useful when the Topic Names are long and the same Topic Names are used repetitively within a Network Connection.

 

The sender decides whether to use a Topic Alias and chooses the value. It sets a Topic Alias mapping by including a non-zero length Topic Name and a Topic Alias in the PUBLISH packet. The receiver processes the PUBLISH as normal but also sets the specified Topic Alias mapping to this Topic Name.

 

If a Topic Alias mapping has been set at the receiver, a sender can send a PUBLISH packet that contains that Topic Alias and a zero length Topic Name. The receiver then treats the incoming PUBLISH as if it had contained the Topic Name of the Topic Alias. 

 

A sender can modify the Topic Alias mapping by sending another PUBLISH in the same Network Connection with the same Topic Alias value and a different non-zero length Topic Name.

 

Topic Alias mappings exist only within a Network Connection and last only for the lifetime of that Network Connection. A receiver MUST NOT carry forward any Topic Alias mappings from one Network Connection to another [MQTT-3.3.2-7].

 

A Topic Alias of 0 is not permitted. A sender MUST NOT send a PUBLISH packet containing a Topic Alias which has the value 0 [MQTT-3.3.2-8].

 

A Client MUST NOT send a PUBLISH packet with a Topic Alias greater than the Topic Alias Maximum value returned by the Server in the CONNACK packet [MQTT-3.3.2-9]. A Client MUST accept all Topic Alias values greater than 0 and less than or equal to the Topic Alias Maximum value that it sent in the CONNECT packet [MQTT-3.3.2-10].

 

A Server MUST NOT send a PUBLISH packet with a Topic Alias greater than the Topic Alias Maximum value sent by the Client in the CONNECT packet [MQTT-3.3.2-11]. A Server MUST accept all Topic Alias values greater than 0 and less than or equal to the Topic Alias Maximum value that it returned in the CONNACK packet [MQTT-3.3.2-12].

 

The Topic Alias mappings used by the Client and Server are independent from each other. Thus, when a Client sends a PUBLISH containing a Topic Alias value of 1 to a Server and the Server sends a PUBLISH with a Topic Alias value of 1 to that Client they will in general be referring to different Topics.

 

3.3.2.3.5 Response Topic

8 (0x08) Byte, Identifier of the Response Topic.

Followed by a UTF-8 Encoded String which is used as the Topic Name for a response message. The Response Topic MUST be a UTF-8 Encoded String as defined in section 1.5.4 [MQTT-3.3.2-13]. The Response Topic MUST NOT contain wildcard characters [MQTT-3.3.2-14]. It is a Protocol Error to include the Response Topic more than once. The presence of a Response Topic identifies the Message as a Request.

 

Refer to section 4.10 for more information about Request / Response.

 

The Server MUST send the Response Topic unaltered to all subscribers receiving the publication [MQTT-3.3.2-15]. 


Non-normative comment: 
The receiver of an Application Message with a Response Topic sends a response by using the Response Topic as the Topic Name of a PUBLISH. If the Request Message contains a Correlation Data, the receiver of the Request Message should also include this Correlation Data as a property in the PUBLISH packet of the Response Message. 

3.3.2.3.6 Correlation Data

9 (0x09) Byte, Identifier of the Correlation Data.

Followed by Binary Data. The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is received. It is a Protocol Error to include Correlation Data more than once. If the Correlation Data is not present, the Requester does not require any correlation data.

 

The Server MUST send the Correlation Data unaltered to all subscribers receiving the publication [MQTT-3.3.2-16]. The value of the Correlation Data only has meaning to the sender of the Request Message and receiver of the Response Message.

 

Non-normative comment:

The receiver of an Application Message which contains both a Response Topic and a Correlation Data sends a response by using the Response Topic as the Topic Name of a PUBLISH. The Client should also send the Correlation Data unaltered as part of the PUBLISH of the responses.

 

If the Correlation Data contains information which can cause application failures if modified by the Client responding to the request, it should be encrypted and/or hashed to allow any alteration to be detected.

 

Refer to section 4.10 for more information about Request / Response.



3.3.2.3.7 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by a UTF-8 String Pair. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

The Server MUST send all User Properties unaltered in a PUBLISH packet when forwarding the Application Message to a Client [MQTT-3.3.2-17]. The Server MUST maintain the order of User Properties when forwarding the Application Message [MQTT-3.3.2-18].

 

Non-normative comment

This property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them.

 

3.3.2.3.8 Subscription Identifier

11 (0x0B), Identifier of the Subscription Identifier.

Followed by a Variable Byte Integer representing the identifier of the subscription.

 

The Subscription Identifier can have the value of 1 to 268,435,455. It is a Protocol Error if the Subscription Identifier has a value of 0. Multiple Subscription Identifiers will be included if the publication is the result of a match to more than one subscription, in this case their order is not significant..

 

3.3.2.3.9 Content Type

3 (0x03) Identifier of the Content Type.

Followed by a UTF-8 Encoded String describing the content of the Application Message. The Content Type MUST be a UTF-8 Encoded String as defined in section 1.5.4 [MQTT-3.3.2-19].

It is a Protocol Error to include the Content Type more than once. The value of the Content Type is defined by the sending and receiving application.

 

A Server MUST send the Content Type unaltered to all subscribers receiving the publication [MQTT-3.3.2-20].

 

Non-normative comment

The UTF-8 Encoded String may use a MIME content type string to describe the contents of the Application message. However, since the sending and receiving applications are responsible for the definition and interpretation of the string, MQTT performs no validation of the string except to insure it is a valid UTF-8 Encoded String.

 

Table 3‑3 PUBLISH packet Variable Header non-normative example

Field

Value

Topic Name

a/b

Packet Identifier

10

Properties

None

 

Figure 3‑9 - PUBLISH packet Variable Header non-normative example

 

Description

7

6

5

4

3

2

1

0

Topic Name

byte 1

Length MSB (0)

0

0

0

0

0

0

0

0

byte 2

Length LSB (3)

0

0

0

0

0

0

1

1

byte 3

‘a’ (0x61)

0

1

1

0

0

0

0

1

byte 4

‘/’ (0x2F)

0

0

1

0

1

1

1

1

byte 5

‘b’ (0x62)

0

1

1

0

0

0

1

0

Packet Identifier

byte 6

Packet Identifier MSB (0)

0

0

0

0

0

0

0

0

byte 7

Packet Identifier LSB (10)

0

0

0

0

1

0

1

0

Property Length

byte 8

No Properties

0

0

0

0

0

0

0

0

 

3.3.3 PUBLISH Payload

The Payload contains the Application Message that is being published. The content and format of the data is application specific. The length of the Payload can be calculated by subtracting the length of the Variable Header from the Remaining Length field that is in the Fixed Header. It is valid for a PUBLISH packet to contain a zero length Payload.

 

3.3.4 PUBLISH Actions

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.4-1].

_Table_3.3_-

Table 3‑4 Expected PUBLISH packet response

QoS Level

Expected Response

QoS 0

None

QoS 1

PUBACK packet

QoS 2

PUBREC packet

 

The Client uses a PUBLISH packet to send an Application Message to the Server, for distribution to Clients with matching subscriptions.

 

The Server uses a PUBLISH packet to send an Application Message to each Client which has a matching subscription. The PUBLISH packet includes the Subscription Identifier carried in the SUBSCRIBE packet, if there was one. 

 

When Clients make subscriptions with Topic Filters that include wildcards, it is possible for a Client’s subscriptions to overlap so that a published message might match multiple filters. In this case the Server MUST deliver the message to the Client respecting the maximum QoS of all the matching subscriptions [MQTT-3.3.4-2]. In addition, the Server MAY deliver further copies of the message, one for each additional matching subscription and respecting the subscription’s QoS in each case. 

 

If a Client receives an unsolicited publication, not resulting from a subscription, which has a QoS greater than Maximum QoS, it uses a DISCONNECT packet with Reason Code 0x9B (QoS not supported ) as described in section 4.13 Handling errors.

 

If the Client specified a Subscription Identifier for any of the overlapping subscriptions the Server MUST send those Subscription Identifiers in the message which is published as the result of the subscriptions [MQTT-3.3.4-3]. If the Server sends a single copy of the message it MUST include in the PUBLISH packet the Subscription Identifiers for all matching subscriptions which have a Subscription Identifiers, their order is not significant [MQTT-3.3.4-4]. If the Server sends multiple PUBLISH packets it MUST send, in each of them, the Subscription Identifier of the matching subscription if it has a Subscription Identifier [MQTT-3.3.4-5].

 

It is possible that the Client made several subscriptions which match a publication and that it used the same identifier for more than one of them. In this case the PUBLISH packet will carry multiple identical Subscription Identifiers. 

 

It is a Protocol Error for a PUBLISH packet to contain any Subscription Identifier other than those received in SUBSCRIBE packet which caused it to flow. A PUBLISH packet sent from a Client to a Server MUST NOT contain a Subscription Identifier [MQTT-3.3.4-6]

 

If the subscription was shared, then only the Subscription Identifiers that were present in the SUBSCRIBE packet from the Client which is receiving the message are returned in the PUBLISH packet. 

 

The action of the recipient when it receives a PUBLISH packet depends on the QoS level as described in section 4.3.

 

If the PUBLISH packet contains a Topic Alias, the receiver processes it as follows:

1)     A Topic Alias value of 0 or greater than the Maximum Topic Alias is a Protocol Error, the receiver uses DISCONNECT with Reason Code of 0x94 (Topic Alias invalid) as described in section 4.13.
 

2)     If the receiver has already established a mapping for the Topic Alias, then

a)     If the packet has a zero length Topic Name, the receiver processes it using the Topic Name that corresponds to the Topic Alias

b)    If the packet contains a non-zero length Topic Name, the receiver processes the packet using that Topic Name and updates its mapping for the Topic Alias to the Topic Name from the incoming packet

3)     If the receiver does not already have a mapping for this Topic Alias

a)     If the packet has a zero length Topic Name field it is a Protocol Error and the receiver uses DISCONNECT with Reason Code of 0x82 (Protocol Error) as described in section 4.13.

b)    If the packet contains a Topic Name with a non-zero length, the receiver processes the packet using that Topic Name and sets its mappings for the Topic Alias to Topic Name from the incoming packet.

 

Non-normative Comment

If the Server distributes Application Messages to Clients at different protocol levels (such as MQTT V3.1.1) which do not support properties or other features provided by this specification, some information in the Application Message can be lost, and applications which depend on this information might not work correctly.

 

The Client MUST NOT send more than Receive Maximum QoS 1 and QoS 2 PUBLISH packets for which it has not received PUBACK, PUBCOMP, or PUBREC with a Reason Code of 128 or greater from the Server [MQTT-3.3.4-7]. If it receives more than Receive Maximum QoS 1 and QoS 2 PUBLISH packets where it has not sent a PUBACK or PUBCOMP in response, the Server uses a DISCONNECT packet with Reason Code 0x93 (Receive Maximum exceeded) as described in section 4.13 Handling errors. Refer to section 4.9 for more information about flow control.

 

The Client MUST NOT delay the sending of any packets other than PUBLISH packets due to having sent Receive Maximum PUBLISH packets without receiving acknowledgements for them [MQTT-3.3.4-8]. The value of Receive Maximum applies only to the current Network Connection.

 

Non-normative comment

The Client might choose to send fewer than Receive Maximum messages to the Server without receiving acknowledgement, even if it has more than this number of messages available to send.

 

Non-normative comment

The Client might choose to suspend the sending of QoS 0 PUBLISH packets when it suspends the sending of QoS 1 and QoS 2 PUBLISH packets.

 

Non-normative comment

If the Client sends QoS 1 or QoS 2 PUBLISH packets before it has received a CONNACK packet, it risks being disconnected because it has sent more than Receive Maximum publications.

 

The Server MUST NOT send more than Receive Maximum QoS 1 and QoS 2 PUBLISH packets for which it has not received PUBACK, PUBCOMP, or PUBREC with a Reason Code of 128 or greater from the Client [MQTT-3.3.4-9]. If it receives more than Receive Maximum QoS 1 and QoS 2 PUBLISH packets where it has not sent a PUBACK or PUBCOMP in response, the Client uses DISCONNECT with Reason Code 0x93 (Receive Maximum exceeded) as described in section 4.13 Handling errors. Refer to section 4.9 for more information about flow control.

 

The Server MUST NOT delay the sending of any packets other than PUBLISH packets due to having sent Receive Maximum PUBLISH packets without receiving acknowledgements for them [MQTT-3.3.4-10].

 

Non-normative comment

The Server might choose to send fewer than Receive Maximum messages to the Client without receiving acknowledgement, even if it has more than this number of messages available to send.

 

Non-normative comment

The Server might choose to suspend the sending of QoS 0 PUBLISH packets when it suspends the sending of QoS 1 and QoS 2 PUBLISH packets.

 

3.4 PUBACK – Publish acknowledgement

A PUBACK packet is the response to a PUBLISH packet with QoS 1.

 

3.4.1 PUBACK Fixed Header

Figure 3‑10 - PUBACK packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (4)

Reserved

 

0

1

0

0

0

0

0

0

byte 2

Remaining Length

 

Remaining Length field

This is the length of the Variable Header, encoded as a Variable Byte Integer.

 

3.4.2 PUBACK Variable Header

The Variable Header of the PUBACK Packet contains the following fields in the order: Packet Identifier from the PUBLISH packet that is being acknowledged, PUBACK Reason Code, Property Length, and the Properties. The rules for encoding Properties are described in section 2.2.2.

 

Figure 3‑11 – PUBACK packet Variable Header

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBACK Reason Code

byte 4

Property Length

 

3.4.2.1 PUBACK Reason Code

Byte 3 in the Variable Header is the PUBACK Reason Code. If the Remaining Length is 2, then there is no Reason Code and the value of 0x00 (Success) is used.

 

Table 3‑5 - PUBACK Reason Codes

Value

Hex

Reason Code name

Description

0

0x00

Success

The message is accepted. Publication of the QoS 1 message proceeds.

16

0x10

No matching subscribers.

The message is accepted but there are no subscribers. This is sent only by the Server. If the Server knows that there are no matching subscribers, it MAY use this Reason Code instead of 0x00 (Success).

128

0x80

Unspecified error

The receiver does not accept the publish but either does not want to reveal the reason, or it does not match one of the other values.

131

0x83

Implementation specific error

The PUBLISH is valid but the receiver is not willing to accept it.

135

0x87

Not authorized

The PUBLISH is not authorized.

144

0x90

Topic Name invalid

The Topic Name is not malformed, but is not accepted by this Client or Server.

145

0x91

Packet identifier in use

The Packet Identifier is already in use. This might indicate a mismatch in the Session State between the Client and Server.

151

0x97

Quota exceeded

An implementation or administrative imposed limit has been exceeded.

153

0x99

Payload format invalid

The payload format does not match the specified Payload Format Indicator.

 

The Client or Server sending the PUBACK MUST use one of the PUBACK Reason Codes shown in Table 3‑5 - PUBACK Reason Codes [MQTT-3.4.2-1]. The Reason Code and Property Length can be omitted if the Reason Code is 0x00 (Success) and there are no Properties. In this case the PUBACK has a Remaining Length of 2.

3.4.2.2 PUBACK Properties

3.4.2.2.1 Property Length

The length of the Properties in the PUBACK packet Variable Header encoded as a Variable Byte Integer. If the Remaining Length is less than 4 there is no Property Length and the value of 0 is used.

 

3.4.2.2.2 Reason String

31 (0x1F) Byte, Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason associated with this response. This Reason String is a human readable string designed for diagnostics and is not intended to be parsed by the receiver.

 

The sender uses this value to give additional information to the receiver. The sender MUST NOT send this property if it would increase the size of the PUBACK packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.4.2-2]. It is a Protocol Error to include the Reason String more than once.

 

3.4.2.2.3 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property can be used to provide additional diagnostic or other information. The sender MUST NOT send this property if it would increase the size of the PUBACK packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.4.2-3]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

3.4.3 PUBACK Payload

The PUBACK packet has no Payload.

 

3.4.4 PUBACK Actions

This is described in section 4.3.2.

 

3.5 PUBREC – Publish received (QoS 2 delivery part 1)

A PUBREC packet is the response to a PUBLISH packet with QoS 2. It is the second packet of the QoS 2 protocol exchange.

 

3.5.1 PUBREC Fixed Header

Figure 3‑12 - PUBREC packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (5)

Reserved

 

0

1

0

1

0

0

0

0

byte 2

Remaining Length

 

Remaining Length field

This is the length of the Variable Header, encoded as a Variable Byte Integer.

 

3.5.2 PUBREC Variable Header

The Variable Header of the PUBREC Packet consists of the following fields in the order: the Packet Identifier from the PUBLISH packet that is being acknowledged, PUBREC Reason Code, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

 Figure 3‑13 - PUBREC packet Variable Header

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBREC Reason Code

byte 4

Property Length

 

3.5.2.1 PUBREC Reason Code

Byte 3 in the Variable Header is the PUBREC Reason Code. If the Remaining Length is 2, then the Publish Reason Code has the value 0x00 (Success).

 

Table 3‑6 – PUBREC Reason Codes

Value

Hex

Reason Code name

Description

0

0x00

Success

The message is accepted. Publication of the QoS 2 message proceeds.

16

0x10

No matching subscribers.

The message is accepted but there are no subscribers. This is sent only by the Server. If the Server knows that there are no matching subscribers, it MAY use this Reason Code instead of 0x00 (Success).

128

0x80

Unspecified error

The receiver does not accept the publish but either does not want to reveal the reason, or it does not match one of the other values.

131

0x83

Implementation specific error

The PUBLISH is valid but the receiver is not willing to accept it.

135

0x87

Not authorized

The PUBLISH is not authorized.

144

0x90

Topic Name invalid

The Topic Name is not malformed, but is not accepted by this Client or Server.

145

0x91

Packet Identifier in use

The Packet Identifier is already in use. This might indicate a mismatch in the Session State between the Client and Server.

151

0x97

Quota exceeded

An implementation or administrative imposed limit has been exceeded.

153

0x99

Payload format invalid

The payload format does not match the one specified in the Payload Format Indicator.

 

The Client or Server sending the PUBREC MUST use one of the PUBREC Reason Codes in Table 3‑6 – PUBREC Reason Codes [MQTT-3.5.2-1]. The Reason Code and Property Length can be omitted if the Reason Code is 0x00 (Success) and there are no Properties. In this case the PUBREC has a Remaining Length of 2.

 

3.5.2.2 PUBREC Properties

3.5.2.2.1 Property Length

The length of the Properties in the PUBREC packet Variable Header encoded as a Variable Byte Integer. If the Remaining Length is less than 4 there is no Property Length and the value of 0 is used.

 

3.5.2.2.2 Reason String

31 (0x1F) Byte, Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason associated with this response. This Reason String is human readable, designed for diagnostics and SHOULD NOT be parsed by the receiver.

 

The sender uses this value to give additional information to the receiver. The sender MUST NOT send this property if it would increase the size of the PUBREC packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.5.2-2]. It is a Protocol Error to include the Reason String more than once.

 

3.5.2.2.3 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property can be used to provide additional diagnostic or other information. The sender MUST NOT send this property if it would increase the size of the PUBREC packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.5.2-3]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

3.5.3 PUBREC Payload

The PUBREC packet has no Payload.

3.5.4 PUBREC Actions

This is described in section 4.3.3.

 

3.6 PUBREL – Publish release (QoS 2 delivery part 2)

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

 

3.6.1 PUBREL Fixed Header

Figure 3‑14 – PUBREL packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (6)

Reserved

 

0

1

1

0

0

0

1

0

byte 2

Remaining Length

 

Bits 3,2,1 and 0 of the Fixed Header in the PUBREL 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.6.1-1].

 

Remaining Length field

This is the length of the Variable Header, encoded as a Variable Byte Integer.

 

3.6.2 PUBREL Variable Header

The Variable Header of the PUBREL Packet contains the following fields in the order: the Packet Identifier from the PUBREC packet that is being acknowledged, PUBREL Reason Code, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

 Figure 3‑15 – PUBREL packet Variable Header

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBREL Reason Code

byte 4

Property Length

 

3.6.2.1 PUBREL Reason Code

Byte 3 in the Variable Header is the PUBREL Reason Code. If the Remaining Length is 2, the value of 0x00 (Success) is used.

 

Table 3‑7 - PUBREL Reason Codes

Value

Hex

Reason Code name

Description

0

0x00

Success

Message released.

146

0x92

Packet Identifier not found

The Packet Identifier is not known. This is not an error during recovery, but at other times indicates a mismatch between the Session State on the Client and Server.

 

The Client or Server sending the PUBREL MUST use one of the PUBREL Reason Codes in Table 3‑7 - PUBREL Reason Codes [MQTT-3.6.2-1]. The Reason Code and Property Length can be omitted if the Reason Code is 0x00 (Success) and there are no Properties. In this case the PUBREL has a Remaining Length of 2.

 

3.6.2.2 PUBREL Properties

3.6.2.2.1 Property Length

The length of the Properties in the PUBREL packet Variable Header encoded as a Variable Byte Integer. If the Remaining Length is less than 4 there is no Property Length and the value of 0 is used.

 

3.6.2.2.2 Reason String

31 (0x1F) Byte, Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason associated with this response. This Reason String is human readable, designed for diagnostics and SHOULD NOT be parsed by the receiver.

 

The sender uses this value to give additional information to the receiver. The sender MUST NOT send this Property if it would increase the size of the PUBREL packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.6.2-2]. It is a Protocol Error to include the Reason String more than once.

 

3.6.2.2.3 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property can be used to provide additional diagnostic or other information for the PUBREL. The sender MUST NOT send this property if it would increase the size of the PUBREL packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.6.2-3]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

3.6.3 PUBREL Payload

The PUBREL packet has no Payload.

 

3.6.4 PUBREL Actions

This is described in section 4.3.3.

 

3.7 PUBCOMP – Publish complete (QoS 2 delivery part 3)

 

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

 

3.7.1 PUBCOMP Fixed Header

Figure 3‑16 – PUBCOMP packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control packet type (7)

Reserved

 

0

1

1

1

0

0

0

0

byte 2

Remaining Length

 

Remaining Length field

This is the length of the Variable Header, encoded as a Variable Byte Integer.

 

3.7.2 PUBCOMP Variable Header

The Variable Header of the PUBCOMP Packet contains the following fields in the order: Packet Identifier from the PUBREL packet that is being acknowledged, PUBCOMP Reason Code, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

Figure 3‑17 - PUBCOMP packet Variable Header

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBCOMP Reason Code

byte 4

Property Length

 

3.7.2.1 PUBCOMP Reason Code

Byte 3 in the Variable Header is the PUBCOMP Reason Code. If the Remaining Length is 2, then the value 0x00 (Success) is used.

 

Table 3‑8 – PUBCOMP Reason Codes

Value

Hex

Reason Code name

Description

0

0x00

Success

Packet Identifier released. Publication of QoS 2 message is complete.

146

0x92

Packet Identifier not found

The Packet Identifier is not known. This is not an error during recovery, but at other times indicates a mismatch between the Session State on the Client and Server.

 

The Client or Server sending the PUBCOMP MUST use one of the PUBCOMP Reason Codes in Table 3‑8 – PUBCOMP Reason Code [MQTT-3.7.2-1]. The Reason Code and Property Length can be omitted if the Reason Code is 0x00 (Success) and there are no Properties. In this case the PUBCOMP has a Remaining Length of 2.

 

3.7.2.2 PUBCOMP Properties

3.7.2.2.1 Property Length

The length of the Properties in the PUBCOMP packet Variable Header encoded as a Variable Byte Integer. If the Remaining Length is less than 4 there is no Property Length and the value of 0 is used.

 

3.7.2.2.2 Reason String

31 (0x1F) Byte, Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason associated with this response. This Reason String is a human readable string designed for diagnostics and SHOULD NOT be parsed by the receiver.

 

The sender uses this value to give additional information to the receiver. The sender MUST NOT send this Property if it would increase the size of the PUBCOMP packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.7.2-2]. It is a Protocol Error to include the Reason String more than once.

 

3.7.2.2.3 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property can be used to provide additional diagnostic or other information. The sender MUST NOT send this property if it would increase the size of the PUBCOMP packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.7.2-3]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

3.7.3 PUBCOMP Payload

The PUBCOMP packet has no Payload.

 

3.7.4 PUBCOMP Actions

This is described in section 4.3.3.

 

3.8 SUBSCRIBE - Subscribe request

The SUBSCRIBE packet is sent from the Client to the Server to create one or more Subscriptions. Each Subscription registers a Client’s interest in one or more Topics. The Server sends PUBLISH packets to the Client to forward Application Messages that were published to Topics that match these Subscriptions. The SUBSCRIBE packet also specifies (for each Subscription) the maximum QoS with which the Server can send Application Messages to the Client.

 

3.8.1 SUBSCRIBE Fixed Header

Figure 3‑18 SUBSCRIBE packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (8)

Reserved

 

1

0

0

0

0

0

1

0

byte 2

Remaining Length

 

Bits 3,2,1 and 0 of the Fixed Header of the SUBSCRIBE 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].

 

Remaining Length field

This is the length of Variable Header plus the length of the Payload, encoded as a Variable Byte Integer.

 

3.8.2 SUBSCRIBE Variable Header

The Variable Header of the SUBSCRIBE Packet contains the following fields in the order: Packet Identifier, and Properties. Section 2.2.1 provides more information about Packet Identifiers. The rules for encoding Properties are described in section 2.2.2.

 

Variable Header non-normative example

Figure 3‑19- Variable Header with a Packet Identifier of 10, non-normative example

 

Description

7

6

5

4

3

2

1

0

Packet Identifier

byte 1

Packet Identifier MSB (0)

0

0

0

0

0

0

0

0

byte 2

Packet Identifier LSB (10)

0

0

0

0

1

0

1

0

byte 3

Property Length (0)

0

0

0

0

0

0

0

0

 

3.8.2.1 SUBSCRIBE Properties

3.8.2.1.1 Property Length

The length of Properties in the SUBSCRIBE packet Variable Header encoded as a Variable Byte Integer.

 

3.8.2.1.2 Subscription Identifier

11 (0x0B) Byte, Identifier of the Subscription Identifier.

Followed by a Variable Byte Integer representing the identifier of the subscription. The Subscription Identifier can have the value of 1 to 268,435,455. It is a Protocol Error if the Subscription Identifier has a value of 0. It is a Protocol Error to include the Subscription Identifier more than once.

 

The Subscription Identifier is associated with any subscription created or modified as the result of this SUBSCRIBE packet. If there is a Subscription Identifier, it is stored with the subscription. If this property is not specified, then the absence of a Subscription Identifier is stored with the subscription.

 

Refer to section 3.8.4 for more information about the handling of Subscription Identifiers.

 

3.8.3 SUBSCRIBE Payload

The Payload of a SUBSCRIBE packet contains a list of Topic Filters indicating the Topics to which the Client wants to subscribe. The Topic Filters MUST be a UTF-8 Encoded String [MQTT-3.8.3-1]. Each Topic Filter is followed by a Subscription Options byte.

 

The Payload MUST contain at least one Topic Filter and Subscription Options pair [MQTT-3.8.3-2]. A SUBSCRIBE packet with no Payload is a Protocol Error. Refer to section 4.13 for information about handling errors.

 

3.8.3.1 Subscription Options

Bits 0 and 1 of the Subscription Options represent Maximum QoS field. This gives the maximum QoS level at which the Server can send Application Messages to the Client. It is a Protocol Error if the Maximum QoS field has the value 3.

 

Bit 2 of the Subscription Options represents the No Local option. If the value is 1, Application Messages MUST NOT be forwarded to a connection with a ClientID equal to the ClientID of the publishing connection [MQTT-3.8.3-3]. It is a Protocol Error to set the No Local bit to 1 on a Shared Subscription [MQTT-3.8.3-4].

 

Bit 3 of the Subscription Options represents the Retain As Published option. If 1, Application Messages forwarded using this subscription keep the RETAIN flag they were published with. If 0, Application Messages forwarded using this subscription have the RETAIN flag set to 0. Retained messages sent when the subscription is established have the RETAIN flag set to 1.

 

Bits 4 and 5 of the Subscription Options represent the Retain Handling option. This option specifies whether retained messages are sent when the subscription is established. This does not affect the sending of retained messages at any point after the subscribe. If there are no retained messages matching the Topic Filter, all of these values act the same. The values are:

0 = Send retained messages at the time of the subscribe

1 = Send retained messages at subscribe only if the subscription does not currently exist

2 = Do not send retained messages at the time of the subscribe

It is a Protocol Error to send a Retain Handling value of 3.

 

Bits 6 and 7 of the Subscription Options byte are reserved for future use. The Server MUST treat a SUBSCRIBE packet as malformed if any of Reserved bits in the Payload are non-zero [MQTT-3.8.3-5].

 

Non-normative comment

The No Local and Retain As Published subscription options can be used to implement bridging where the Client is sending the message on to another Server.

 

Not sending retained messages for an existing subscription is useful when a reconnect is done and the Client is not certain whether the subscriptions were completed in the previous connection to the Session.

 

Not sending stored retained messages because of a new subscription is useful where a Client wishes to receive change notifications and does not need to know the initial state.

 

For a Server that indicates it does not support retained messages, all valid values of Retain As Published and Retain Handling give the same result which is to not send any retained messages at subscribe and to set the RETAIN flag to 0 for all messages.

 

Figure 3‑20– SUBSCRIBE packet Payload format

Description

7

6

5

4

3

2

1

0

Topic Filter

byte 1

Length MSB

byte 2

Length LSB

bytes 3..N

Topic Filter

Subscription Options

 

Reserved

Retain Handling

RAP

NL

QoS

byte N+1

0

0

X

X

X

X

X

X

RAP means Retain as Published.

NL means No Local.

 

3.8.3.2 Payload non-normative example

Figure 3.21 - Payload byte format non-normative example shows the Payload for the SUBSCRIBE Packet

_Table_3.4_-

Table 3‑9 - Payload non-normative example

Topic Name

“a/b”

Subscription Options

0x01

Topic Name

“c/d”

Subscription Options

0x02

Figure 3‑21 - Payload byte format non-normative example

 

Description

7

6

5

4

3

2

1

0

Topic Filter

byte 1

Length MSB (0)

0

0

0

0

0

0

0

0

byte 2

Length LSB (3)

0

0

0

0

0

0

1

1

byte 3

‘a’ (0x61)

0

1

1

0

0

0

0

1

byte 4

‘/’ (0x2F)

0

0

1

0

1

1

1

1

byte 5

‘b’ (0x62)

0

1

1

0

0

0

1

0

Subscription Options

byte 6

Subscription Options (1)

0

0

0

0

0

0

0

1

Topic Filter

byte 7

Length MSB (0)

0

0

0

0

0

0

0

0

byte 8

Length LSB (3)

0

0

0

0

0

0

1

1

byte 9

‘c’ (0x63)

0

1

1

0

0

0

1

1

byte 10

‘/’ (0x2F)

0

0

1

0

1

1

1

1

byte 11

‘d’ (0x64)

0

1

1

0

0

1

0

0

Subscription Options

byte 12

Subscription Options (2)

0

0

0

0

0

0

1

0

 

3.8.4 SUBSCRIBE Actions

When the Server receives a SUBSCRIBE packet from a Client, the Server MUST respond with a SUBACK packet [MQTT-3.8.4-1]. The SUBACK packet MUST have the same Packet Identifier as the SUBSCRIBE packet that it is acknowledging [MQTT-3.8.4-2].

 

The Server is permitted to start sending PUBLISH packets matching the Subscription before the Server sends the SUBACK packet.

 

If a Server receives a SUBSCRIBE packet containing a Topic Filter that is identical to a Non-Shared Subscription’s Topic Filter for the current Session, then it MUST completely replace that existing Subscription with a new Subscription [MQTT-3.8.4-3]. The Topic Filter in the new Subscription will be identical to that in the previous Subscription, although its Subscription Options could be different. If the Retain Handling option is 0, any existing retained messages matching the Topic Filter MUST be re-sent, but publications MUST NOT be lost due to replacing the Subscription [MQTT-3.8.4-4].

 

If a Server receives a Non-Shared Topic Filter that is not identical to any Topic Filter for the current Session, a new Non-Shared Subscription is created. If the Retain Handling option is not 2, all matching retained messages are sent to the Client.

 

If a Server receives a Topic Filter that is identical to the Topic Filter for a Shared Subscription that already exists on the Server, the Session is added as a subscriber to that Shared Subscription. No retained messages are sent.

 

If a Server receives a Shared Subscription Topic Filter that is not identical to any existing Shared Subscription’s Topic Filter, a new Shared Subscription is created. The Session is added as a subscriber to that Shared Subscription. No retained messages are sent.

 

Refer to section 4.8 for more details on Shared Subscriptions.

 

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 Reason Code for each Topic Filter/Subscription Option pair [MQTT-3.8.4-6]. This Reason Code MUST either show the maximum QoS that was granted for that Subscription or indicate that the subscription failed [MQTT-3.8.4-7]. The Server might grant a lower Maximum QoS than the subscriber requested. The QoS of Application 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 [MQTT-3.8.4-8]. 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.

 

Non-normative comment
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. 

Non-normative comment

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.

 

Non-normative comment

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.

 

The Subscription Identifiers are part of the Session State in the Server and are returned to the Client receiving a matching PUBLISH packet. They are removed from the Server’s Session State when the Server receives an UNSUBSCRIBE packet, when the Server receives a SUBSCRIBE packet from the Client for the same Topic Filter but with a different Subscription Identifier or with no Subscription Identifier, or when the Server sends Session Present 0 in a CONNACK packet. 

The Subscription Identifiers do not form part of the Client’s Session State in the Client. In a useful implementation, a Client will associate the Subscription Identifiers with other Client side state, this state is typically removed when the Client unsubscribes, when the Client subscribes for the same Topic Filter with a different identifier or no identifier, or when the Client receives Session Present 0 in a CONNACK packet. 

The Server need not use the same set of Subscription Identifiers in the retransmitted PUBLISH packet. The Client can remake a Subscription by sending a SUBSCRIBE packet containing a Topic Filter that is identical to the Topic Filter of an existing Subscription in the current Session. If the Client remade a subscription after the initial transmission of a PUBLISH packet and used a different Subscription Identifier, then the Server is allowed to use the identifiers from the first transmission in any retransmission. Alternatively, the Server is allowed to use the new identifiers during a retransmission. The Server is not allowed to revert to the old identifier after it has sent a PUBLISH packet containing the new one. 

 

Non-normative comment

Usage scenarios, for illustration of Subscription Identifiers. 

·         The Client implementation indicates via its programming interface that a publication matched more than one subscription. The Client implementation generates a new identifier each time a subscription is made. If the returned publication carries more than one Subscription Identifier, then the publication matched more than one subscription.

·         The Client implementation allows the subscriber to direct messages to a callback associated with the subscription. The Client implementation generates an identifier which uniquely maps the identifier to the callback. When a publication is received it uses the Subscription Identifier to determine which callback is driven.

·         The Client implementation returns the topic string used to make the subscription to the application when it delivers the published message. To achieve this the Client generates an identifier which uniquely identifies the Topic Filter. When a publication is received the Client implementation uses the identifiers to look up the original Topic Filters and return them to the Client application. 

·         A gateway forwards publications received from a Server to Clients that have made subscriptions to the gateway. The gateway implementation maintains a map of each unique Topic Filter it receives to the set of ClientID, Subscription Identifier pairs that it also received. It generates a unique identifier for each Topic Filter that it forwards to the Server. When a publication is received, the gateway uses the Subscription Identifiers it received from the Server to look up the Client Identifier, Subscription Identifier pairs associated with them. It adds these to the PUBLISH packets it sends to the Clients. If the upstream Server sent multiple PUBLISH packets because the message matched multiple subscriptions, then this behavior is mirrored to the Clients.

 

3.9 SUBACK – Subscribe acknowledgement

A SUBACK packet is sent by the Server to the Client to confirm receipt and processing of a SUBSCRIBE packet.

 

A SUBACK packet contains a list of Reason Codes, that specify the maximum QoS level that was granted or the error which was found for each Subscription that was requested by the SUBSCRIBE.

 

3.9.1 SUBACK Fixed Header

Figure 3‑22 - SUBACK Packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (9)

Reserved

 

1

0

0

1

0

0

0

0

byte 2

Remaining Length

 

 

Remaining Length field

This is the length of Variable Header plus the length of the Payload, encoded as a Variable Byte Integer.

 

3.9.2 SUBACK Variable Header

The Variable Header of the SUBACK Packet contains the following fields in the order: the Packet Identifier from the SUBSCRIBE Packet that is being acknowledged, and Properties.

 

3.9.2.1 SUBACK Properties

3.9.2.1.1 Property Length

The length of Properties in the SUBACK packet Variable Header encoded as a Variable Byte Integer. If the Remaining Length is less than 3, there is no Properties.

 

3.9.2.1.2 Reason String

31 (0x1F) Byte, Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason associated with this response. This Reason String is a human readable string designed for diagnostics and SHOULD NOT be parsed by the Client.

 

The Server uses this value to give additional information to the Client. The Server MUST NOT send this Property if it would increase the size of the SUBACK packet beyond the Maximum Packet Size specified by the Client [MQTT-3.9.2-1]. It is a Protocol Error to include the Reason String more than once.

 

3.9.2.1.3 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property can be used to provide additional diagnostic or other information. The Server MUST NOT send this property if it would increase the size of the SUBACK packet beyond the Maximum Packet Size specified by Client [MQTT-3.9.2-2]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

_Figure_3.25_-

Figure 3‑23 SUBACK packet Variable Header

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

 

3.9.3 SUBACK Payload

The Payload contains a list of Reason Codes. Each Reason Code corresponds to a Topic Filter in the SUBSCRIBE packet being acknowledged. The order of Reason Codes in the SUBACK packet MUST match the order of Topic Filters in the SUBSCRIBE packet [MQTT-3.9.3-1].

 

Table 3‑10 - Subscribe Reason Codes

Value

Hex

Reason Code name

Description

0

0x00

Granted QoS 0

The subscription is accepted and the maximum QoS sent will be QoS 0. This might be a lower QoS than was requested.

1

0x01

Granted QoS 1

The subscription is accepted and the maximum QoS sent will be QoS 1. This might be a lower QoS than was requested.

2

0x02

Granted QoS 2

The subscription is accepted and any received QoS will be sent to this subscription.

128

0x80

Unspecified error

The subscription is not accepted and the Server either does not wish to reveal the reason or none of the other Reason Codes apply.

131

0x83

Implementation specific error

The SUBSCRIBE is valid but the Server does not accept it.

135

0x87

Not authorized

The Client is not authorized to make this subscription.

143

0x8F

Topic Filter invalid

The Topic Filter is correctly formed but is not allowed for this Client.

145

0x91

Packet Identifier in use

The specified Packet Identifier is already in use.

151

0x97

Quota exceeded

An implementation or administrative imposed limit has been exceeded.

158

0x9E

Shared Subscription not supported

The Server does not support Shared Subscriptions for this Client.

161

0xA1

Subscription Identifiers not supported

The Server does not support Subscription Identifiers; the subscription is not accepted.

162

0xA2

Wildcard subscriptions not supported

The Server does not support Wildcard subscription; the subscription is not accepted.

                                                                                                            

The Server MUST send one of the Reason Codes listed in Table 3‑10 - Subscribe Reason Codes for each subscription received [MQTT-3.9.3-2].

 

Non-normative comment

There is always one Reason Code for each Topic Filter in the corresponding SUBSCRIBE packet. If the Reason Code is not specific to a Topic Filters (such as 0x91 (Packet Identifier in use)) it is set for each Topic Filter.

 

3.9.4 Payload non-normative example

Figure 3.27 - Payload byte format non-normative example shows the Payload for the SUBACK packet._Table_3.5_-

 

Table 3‑11 Payload non-normative example

Success - Maximum QoS 0 

0

Success - Maximum QoS 2

2

Failure 

128

Figure 3.27 - Payload byte format non-normative example

 

Description

7

6

5

4

3

2

1

0

byte 1

Success - Maximum QoS 0 

0

0

0

0

0

0

0

0

byte 2

Success - Maximum QoS 2 

0

0

0

0

0

0

1

0

byte 3

Failure

1

0

0

0

0

0

0

0

 

3.10 UNSUBSCRIBE – Unsubscribe request

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

 

3.10.1 UNSUBSCRIBE Fixed Header

Figure 3.28 – UNSUBSCRIBE packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (10)

Reserved

 

1

0

1

0

0

0

1

0

byte 2

Remaining Length

 

Bits 3,2,1 and 0 of the Fixed Header of the UNSUBSCRIBE 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.1-1].

 

Remaining Length field

This is the length of Variable Header (2 bytes) plus the length of the Payload, encoded as a Variable Byte Integer.

 

3.10.2 UNSUBSCRIBE Variable Header

The Variable Header of the UNSUBSCRIBE Packet contains the Packet Identifier. Section 2.2.1 provides more information about Packet Identifiers.

 

Figure 3.29 – UNSUBSCRIBE packet Variable Header

Bit

7

6

5

4

 

3

2

1

0

byte 1

 

Packet Identifier MSB

byte 2

 

Packet Identifier LSB

 

3.10.3 UNSUBSCRIBE Payload

The Payload for the UNSUBSCRIBE packet contains the list of Topic Filters that the Client wishes to unsubscribe from. The Topic Filters in an UNSUBSCRIBE packet MUST be UTF-8 Encoded Strings [MQTT-3.10.3-1] as defined in section 1.5.4, packed contiguously.

 

The Payload of an UNSUBSCRIBE packet MUST contain at least one Topic Filter [MQTT-3.10.3-2]. An UNSUBSCRIBE packet with no Payload is a Protocol Error. Refer to section 4.13 for information about handling errors.

 

Non-normative example

Figure 3.30 - Payload byte format non-normative example shows the Payload for the UNSUBSCRIBE packet briefly described in Table 3.7 - Payload non-normative example.

_Table3.6_-_Payload

Table 3.7 - Payload non-normative example

Topic Filter

“a/b”

Topic Filter

“c/d”

 

Figure 3.30 - Payload byte format non-normative example

 

Description

7

6

5

4

3

2

1

0

Topic Filter

byte 1

Length MSB (0)

0

0

0

0

0

0

0

0

byte 2

Length LSB (3)

0

0

0

0

0

0

1

1

byte 3

‘a’ (0x61)

0

1

1

0

0

0

0

1

byte 4

‘/’ (0x2F)

0

0

1

0

1

1

1

1

byte 5

‘b’ (0x62)

0

1

1

0

0

0

1

0

Topic Filter

byte 6

Length MSB (0)

0

0

0

0

0

0

0

0

byte 7

Length LSB (3)

0

0

0

0

0

0

1

1

byte 8

‘c’ (0x63)

0

1

1

0

0

0

1

1

byte 9

‘/’ (0x2F)

0

0

1

0

1

1

1

1

byte 10

‘d’ (0x64)

0

1

1

0

0

1

0

0

 

3.10.4 UNSUBSCRIBE Actions

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 MUST be deleted [MQTT-3.10.4-1], otherwise no additional processing occurs. 

When a Server receives UNSUBSCRIBE :


The Server MUST respond to an UNSUBSCRIBE request by sending an UNSUBACK packet [MQTT-3.10.4-4]. The UNSUBACK packet MUST have the same Packet Identifier as the UNSUBSCRIBE packet. Even where no Topic Subscriptions are deleted, the Server MUST respond with an UNSUBACK [MQTT-3.10.4-5].

 

If a Server receives an UNSUBSCRIBE packet that contains multiple Topic Filters, it MUST process that packet as if it had received a sequence of multiple UNSUBSCRIBE packets, except that it sends just one UNSUBACK response [MQTT-3.10.4-6]

 

3.11 UNSUBACK – Unsubscribe acknowledgement

The UNSUBACK packet is sent by the Server to the Client to confirm receipt of an UNSUBSCRIBE packet.

 

3.11.1 UNSUBACK Fixed Header

Figure 3.31 – UNSUBACK packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (11)

Reserved

 

1

0

1

1

0

0

0

0

byte 2

Remaining Length

 

Remaining Length field

This is the length of the Variable Header plus the length of the Payload, encoded as a Variable Byte Integer.

 

3.11.2 UNSUBACK Variable Header

The Variable Header of the UNSUBACK Packet the following fields in the order: the Packet Identifier from the UNSUBSCRIBE Packet that is being acknowledged, and Properties. The rules for encoding Properties are described in section 2.2.2.

 _Figure_3.32_–

Figure 3.32 – UNSUBACK packet Variable Header

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

 

3.11.2.1 UNSUBACK Properties

3.11.2.1.1 Property Length

The length of the Properties in the UNSUBACK packet Variable Header encoded as a Variable Byte Integer. If the Remaining Length is less than 3 there is no Properties.

 

3.11.2.1.2 Reason String

31 (0x1F) Byte, Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason associated with this response. This Reason String is a human readable string designed for diagnostics and SHOULD NOT be parsed by the Client.

 

The Server uses this value to give additional information to the Client. The Server MUST NOT send this Property if it would increase the size of the UNSUBACK packet beyond the Maximum Packet Size specified by the Client [MQTT-3.11.2-1]. It is a Protocol Error to include the Reason String more than once.

 

3.11.2.1.3 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property can be used to provide additional diagnostic or other information. The Server MUST NOT send this property if it would increase the size of the UNSUBACK packet beyond the Maximum Packet Size specified by the Client [MQTT-3.11.2-2]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

3.11.3 UNSUBACK Payload

The Payload contains a list of Reason Codes. Each Reason Code corresponds to a Topic Filter in the UNSUBSCRIBE packet being acknowledged. The order of Reason Codes in the UNSUBACK packet MUST match the order of Topic Filters in the UNSUBSCRIBE packet [MQTT-3.11.3-1].

 

The values for the one byte unsigned Unsubscribe Reason Codes are listed in Table 3‑12 - Unsubscribe Reason Codes. The Server MUST use one of the UNSUBSCRIBE Reason Code values from this table [MQTT-3.11.3-2].

 

Table 3‑12 - Unsubscribe Reason Codes

Value

Hex

Reason Code name

Description

0

0x00

Success

The subscription is deleted.

17

0x11

No subscription found

No matching Topic Filter is being used by the Client.

128

0x80

Unspecified error

The unsubscribe could not be completed and the Server either does not wish to reveal the reason or none of the other Reason Codes apply.

131

0x83

Implementation specific error

The UNSUBSCRIBE is valid but the Server does not accept it.

135

0x87

Not authorized

The Client is not authorized to unsubscribe.

143

0x8F

Topic Filter invalid

The Topic Filter is correctly formed but is not allowed for this Client.

145

0x91

Packet Identifier in use

The specified Packet Identifier is already in use.

 

Non-normative comment

There is always one Reason Code for each Topic Filter in the corresponding UNSUBSCRIBE packet. If the Reason Code is not specific to a Topic Filters (such as 0x91 (Packet Identifier in use)) it is set for each Topic Filter.

 

3.12 PINGREQ – PING request

The PINGREQ packet is sent from a Client to the Server. It can be used to:

·         Indicate to the Server that the Client is alive in the absence of any other MQTT Control Packets being sent from the Client to the Server.

·         Request that the Server responds to confirm that it is alive.

·         Exercise the network to indicate that the Network Connection is active.

 

This packet is used in Keep Alive processing. Refer to section 3.1.2.10 for more details.

 

3.12.1 PINGREQ Fixed Header

Figure 3.33 – PINGREQ packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (12)

Reserved

 

1

1

0

0

0

0

0

0

byte 2

Remaining Length (0)

 

0

0

0

0

0

0

0

0

 

3.12.2 PINGREQ Variable Header

The PINGREQ packet has no Variable Header.

 

3.12.3 PINGREQ Payload

The PINGREQ packet has no Payload.

 

3.12.4 PINGREQ Actions

The Server MUST send a PINGRESP packet in response to a PINGREQ packet [MQTT-3.12.4-1].

 

3.13 PINGRESP – PING response

A PINGRESP Packet is sent by the Server to the Client in response to a PINGREQ packet. It indicates that the Server is alive.

 

This packet is used in Keep Alive processing. Refer to section 3.1.2.10 for more details.

 

3.13.1 PINGRESP Fixed Header

Figure 3.34 – PINGRESP packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (13)

Reserved

 

1

1

0

1

0

0

0

0

byte 2

Remaining Length (0)

 

0

0

0

0

0

0

0

0

 

3.13.2 PINGRESP Variable Header

The PINGRESP packet has no Variable Header.

 

3.13.3 PINGRESP Payload

The PINGRESP packet has no Payload.

 

3.13.4 PINGRESP Actions

The Client takes no action on receiving this packet

 

3.14 DISCONNECT – Disconnect notification

The DISCONNECT packet is the final MQTT Control Packet sent from the Client or the Server. It indicates the reason why the Network Connection is being closed. The Client or Server MAY send a DISCONNECT packet before closing the Network Connection. If the Network Connection is closed without the Client first sending a DISCONNECT packet with Reason Code 0x00 (Normal disconnection) and the Connection has a Will Message, the Will Message is published. See section 3.1.2.5 for further details.

 

A Server MUST NOT send a DISCONNECT until after it has sent a CONNACK with Reason Code of less than 0x80 [MQTT-3.14.0-1].

 

3.14.1 DISCONNECT Fixed Header

Figure 3.35 – DISCONNECT packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (14)

Reserved

 

1

1

1

0

0

0

0

0

byte 2

Remaining Length

The Client or Server MUST validate that reserved bits are set to 0. If they are not zero it sends a DISCONNECT packet with a Reason code of 0x81 (Malformed Packet) as described in section 4.13 [MQTT-3.14.1-1].

 

Remaining Length field

This is the length of the Variable Header encoded as a Variable Byte Integer.

 

3.14.2 DISCONNECT Variable Header

The Variable Header of the DISCONNECT Packet contains the following fields in the order: Disconnect Reason Code, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

3.14.2.1 Disconnect Reason Code

Byte 1 in the Variable Header is the Disconnect Reason Code. If the Remaining Length is less than 1 the value of 0x00 (Normal disconnection) is used.

 

The values for the one byte unsigned Disconnect Reason Code field are listed in Table 3‑13 – Disconnect Reason Code values.

 

Table 3‑13 – Disconnect Reason Code values

Value

Hex

Reason Code name

Sent by

Description

0

0x00

Normal disconnection

Client or Server

Close the connection normally. Do not send the Will Message.

4

0x04

Disconnect with Will Message

Client

The Client wishes to disconnect but requires that the Server also publishes its Will Message.

128

0x80

Unspecified error

Client or Server

The Connection is closed but the sender either does not wish to reveal the reason, or none of the other Reason Codes apply.

129

0x81

Malformed Packet

Client or Server

The received packet does not conform to this specification.

130

0x82

Protocol Error

Client or Server

An unexpected or out of order packet was received.

131

0x83

Implementation specific error

Client or Server

The packet received is valid but cannot be processed by this implementation.

135

0x87

Not authorized

Server

The request is not authorized.

137

0x89

Server busy

Server

The Server is busy and cannot continue processing requests from this Client.

139

0x8B

Server shutting down

Server

The Server is shutting down.

141

0x8D

Keep Alive timeout

Server

The Connection is closed because no packet has been received for 1.5 times the Keepalive time.

142

0x8E

Session taken over

Server

Another Connection using the same ClientID has connected causing this Connection to be closed.

143

0x8F

Topic Filter invalid

Server

The Topic Filter is correctly formed, but is not accepted by this Sever.

144

0x90

Topic Name invalid

Client or Server

The Topic Name is correctly formed, but is not accepted by this Client or Server.

147

0x93

Receive Maximum exceeded

Client or Server

The Client or Server has received more than Receive Maximum publication for which it has not sent PUBACK or PUBCOMP.

148

0x94

Topic Alias invalid

Client or Server

The Client or Server has received a PUBLISH packet containing a Topic Alias which is greater than the Maximum Topic Alias it sent in the CONNECT or CONNACK packet.

149

0x95

Packet too large

Client or Server

The packet size is greater than Maximum Packet Size for this Client or Server.

150

0x96

Message rate too high

Client or Server

The received data rate is too high.

151

0x97

Quota exceeded

Client or Server

An implementation or administrative imposed limit has been exceeded.

152

0x98

Administrative action

Client or Server

The Connection is closed due to an administrative action.

153

0x99

Payload format invalid

Client or Server

The payload format does not match the one specified by the Payload Format Indicator.

154

0x9A

Retain not supported

Server

The Server has does not support retained messages.

155

0x9B

QoS not supported

Server

The Client specified a QoS greater than the QoS specified in a Maximum QoS in the CONNACK.

156

0x9C

Use another server

Server

The Client should temporarily change its Server.

157

0x9D

Server moved

Server

The Server is moved and the Client should permanently change its server location.

158

0x9E

Shared Subscription not supported

Server

The Server does not support Shared Subscriptions.

159

0x9F

Connection rate exceeded

Server

This connection is closed because the connection rate is too high.

160

0xA0

Maximum connect time

Server

The maximum connection time authorized for this connection has been exceeded.

161

0xA1

Subscription Identifiers not supported

Server

The Server does not support Subscription Identifiers; the subscription is not accepted.

162

0xA2

Wildcard subscriptions not supported

Server

The Server does not support Wildcard subscription; the subscription is not accepted.

 

The Client or Server sending the DISCONNECT packet MUST use one of the DISCONNECT Reason Codes in Table 3‑13 – Disconnect Reason Code s [MQTT-3.14.2-1]. The Reason Code and Property Length can be omitted if the Reason Code is 0x00 (Normal disconnecton) and there are no Properties. In this case the DISCONNECT has a Remaining Length of 0.

 

Non-normative comment

The DISCONNECT packet is used to indicate the reason for a disconnect for cases where there is no acknowledge packet (such as a QoS 0 publish) or when the Client or Server is unable to continue processing the Connection.

 

The information can be used by the Client to decide whether to retry the connection, and how long it should wait before retrying the connection.

 

3.14.2.2 DISCONNECT Properties

3.14.2.2.1 Property Length

The length of Properties in the DISCONNECT packet Variable Header encoded as a Variable Byte Integer. If the Remaining Length is less than 2, a value of 0 is used.

 

3.14.2.2.2 Session Expiry Interval

17 (0x11) Byte, Identifier of the Session Expiry Interval.

Followed by the Four Byte Integer representing the Session Expiry Interval in seconds. It is a Protocol Error to include the Session Expiry Interval more than once.

 

If the Session Expiry Interval is absent, the Session Expiry Interval in the CONNECT packet is used.

 

The Session Expiry Interval MUST NOT be sent on a DISCONNECT by the Server [MQTT-3.14.2-2].

 

If the Session Expiry Interval in the CONNECT packet was zero, then it is a Protocol Error to set a non-zero Session Expiry Interval in the DISCONNECT packet sent by the Client. If such a non-zero Session Expiry Interval is received by the Server, it does not treat it as a valid DISCONNECT packet. The Server uses DISCONNECT with Reason Code 0x82 (Protocol Error) as described in section 4.13.

 

3.14.2.2.3 Reason String

31 (0x1F) Byte, Identifier of the Reason String.

Followed by the UTF-8 Encoded String representing the reason for the disconnect. This Reason String is human readable, designed for diagnostics and SHOULD NOT be parsed by the receiver.

 

The sender MUST NOT send this Property if it would increase the size of the DISCONNECT packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.14.2-3]. It is a Protocol Error to include the Reason String more than once.

 

3.14.2.2.4 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property may be used to provide additional diagnostic or other information. The sender MUST NOT send this property if it would increase the size of the DISCONNECT packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.14.2-4]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

3.14.2.2.5 Server Reference

28 (0x1C) Byte, Identifier of the Server Reference.

Followed by a UTF-8 Encoded String which can be used by the Client to identify another Server to use. It is a Protocol Error to include the Server Reference more than once.

 

The Server sends DISCONNECT including a Server Reference and Reason Code 0x9C (Use another server) or 0x9D (Server moved) as described in section 4.13.

 

Refer to section 4.11 Server Redirection for information about how Server Reference is used.

 

Figure 3‑24 DISCONNECT packet Variable Header non-normative example

 

Description

7

6

5

4

3

2

1

0

Disconnect Reason Code

byte 1

 

0

0

0

0

0

0

0

0

Properties

byte 2

Length (5)

0

0

0

0

0

1

1

1

byte 3

Session Expiry Interval identifier (17)

0

0

0

1

0

0

0

1

byte 4

Session Expiry Interval (0)

0

0

0

0

0

0

0

0

byte 5

0

0

0

0

0

0

0

0

byte 6

0

0

0

0

0

0

0

0

byte 7

0

0

0

0

0

0

0

0

 

3.14.3 DISCONNECT Payload

The DISCONNECT packet has no Payload.

 

3.14.4 DISCONNECT Actions

After sending a DISCONNECT packet the sender:

 

On receipt of DISCONNECT with a Reason Code of 0x00 (Success) the Server:

 

On receipt of DISCONNECT, the receiver:

 

3.15 AUTH – Authentication exchange

An AUTH packet is sent from Client to Server or Server to Client as part of an extended authentication exchange, such as challenge / response authentication. It is a Protocol Error for the Client or Server to send an AUTH packet if the CONNECT packet did not contain the same Authentication Method.

 

3.15.1 AUTH Fixed Header

Figure 3.35 – AUTH packet Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (15)

Reserved

 

1

1

1

1

0

0

0

0

byte 2

Remaining Length

 

Bits 3,2,1 and 0 of the Fixed Header of the AUTH packet are reserved and MUST all be set to 0. The Client or Server MUST treat any other value as malformed and close the Network Connection [MQTT-3.15.1-1].

 

Remaining Length field

This is the length of the Variable Header encoded as a Variable Byte Integer.

 

3.15.2 AUTH Variable Header

The Variable Header of the AUTH Packet contains the following fields in the order: Authenticate Reason Code, and Properties. The rules for encoding Properties are described in section 2.2.2.

 

3.15.2.1 Authenticate Reason Code

Byte 0 in the Variable Header is the Authenticate Reason Code. The values for the one byte unsigned Authenticate Reason Code field are listed in Table 3‑14 Authenticate Reason Codes. The sender of the AUTH Packet MUST use one of the Authenticate Reason Codes [MQTT-3.15.2-1].

 

Table 3‑14 Authenticate Reason Codes

Value

Hex

Reason Code name

Sent by

Description

0

0x00

Success

Server

Authentication is successful

24

0x18

Continue authentication

Client or Server

Continue the authentication with another step

25

0x19

Re-authenticate

Client

Initiate a re-authentication

The Reason Code and Property Length can be omitted if the Reason Code is 0x00 (Success) and there are no Properties. In this case the AUTH has a Remaining Length of 0.

 

3.15.2.2 AUTH Properties

3.15.2.2.1 Property Length

The length of Properties in the AUTH packet Variable Header encoded as a Variable Byte Integer.

 

3.15.2.2.2 Authentication Method

21 (0x15) Byte, Identifier of the Authentication Method.

Followed by a UTF-8 Encoded String containing the name of the authentication method. It is a Protocol Error to omit the Authentication Method or to include it more than once. Refer to section 4.12 for more information about extended authentication.

 

3.15.2.2.3 Authentication Data

22 (0x16) Byte, Identifier of the Authentication Data.

Followed by Binary Data containing authentication data. It is a Protocol Error to include Authentication Data more than once. The contents of this data are defined by the authentication method. Refer to section 4.12 for more information about extended authentication.

 

3.15.2.2.4 User Property

38 (0x26) Byte, Identifier of the User Property.

Followed by UTF-8 String Pair. This property may be used to provide additional diagnostic or other information. The sender MUST NOT send this property if it would increase the size of the AUTH packet beyond the Maximum Packet Size specified by the receiver [MQTT-3.15.2-2]. The User Property is allowed to appear multiple times to represent multiple name, value pairs. The same name is allowed to appear more than once.

 

3.15.3 AUTH Payload

The AUTH packet has no Payload.

 

3.15.4 AUTH Actions

Refer to section 4.12 for more information about extended authentication.

4      Operational behavior

4.1 Session State

In order to implement QoS 1 and QoS 2 protocol flows the Client and Server need to associate state with the Client Identifier, this is referred to as the Session State. The Server also stores the subscriptions as part of the Session State.

 

The session can continue across a sequence of Network Connections. It lasts as long as the latest Network Connection plus the Session Expiry Interval.

 

The Session State in the Client consists of:

·         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.

 

The Session State in the Server consists of:

·         The existence of a Session, even if the rest of the Session State is empty.

·         The Clients subscriptions, including any Subscription Identifiers.

·         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 and OPTIOANLLY, QoS 0 messages pending transmission to the Client.

·         QoS 2 messages which have been received from the Client, but have not been completely acknowledged.The Will Message and the Will Delay Interval

·         If the Session is currently not connected, the time at which the Session will end and Session State will be discarded.

 

Retained messages do not form part of the Session State in the Server, they are not deleted as a result of a Session ending.

 

4.1.1 Storing Session State

The Client and Server MUST NOT discard the Session State while the Network Connection is open [MQTT-4.1.0-1]. The Server MUST discard the Session State when the Network Connection is closed and the Session Expiry Interval has passed [MQTT-4.1.0-2].

 

Non-normative comment

The storage capabilities of Client and Server implementations will of course have limits in terms of capacity and may be subject to administrative policies. 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 possible that hardware or software failures may result in loss or corruption of Session State stored by the Client or Server. It is prudent to evaluate the storage capabilities of the Client and Server to ensure that they are sufficient.

 

4.1.2 Session State non-normative examples

For example, an electricity meter reading solution might use QoS 1 messages to protect the readings against loss over the network. The solution developer might have determined that the power supply is sufficiently reliable that, in this case, the data in the Client and Server can be stored in volatile memory without too much risk of its loss.

 

Conversely a parking meter payment application provider might decide that the payment messages should never be lost due to a network or Client failure. Thus, they require that all data be written to non-volatile memory before it is transmitted across the network.

 

4.2 Network Connections

The MQTT protocol requires an underlying transport that provides an ordered, lossless, stream of bytes from the Client to Server and Server to Client.

 

Non-normative comment

TCP/IP as defined in [RFC0793] can be used for MQTT v5.0. The following transport protocols are also suitable:

·         TLS [RFC5246]

·         WebSocket [RFC6455]

 

Non-normative comment

TCP ports 8883 and 1883 are registered with IANA for MQTT TLS and non-TLS communication respectively.

 

Connectionless network transports such as User Datagram Protocol (UDP) are not suitable on their own because they might lose or reorder data.

 

4.3 Quality of Service levels and protocol flows

MQTT delivers Application Messages according to the Quality of Service (QoS) levels defined in the following sections. The delivery protocol is symmetric, in the description below the Client and Server can each take the role of either sender or receiver. The delivery protocol is concerned solely with the delivery of an application message from a single sender to a single receiver. When the Server is delivering an Application Message to more than one Client, each Client is treated independently. The QoS level used to deliver an Application Message outbound to the Client could differ from that of the inbound Application Message.

 

4.3.1 QoS 0: At most once delivery

The message is delivered according to the capabilities of the underlying network. No response is sent by the receiver and no retry is performed by the sender. The message arrives at the receiver either once or not at all.

 

In the QoS 0 delivery protocol, the sender

·         MUST send a PUBLISH packet with QoS 0 and DUP flag set to 0 [MQTT-4.3.1-1].

 

In the QoS 0 delivery protocol, the receiver

·         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)

 

4.3.2 QoS 1: At least once delivery

This Quality of Service level ensures that the message arrives at the receiver at least once. A QoS 1 PUBLISH packet has a Packet Identifier in its Variable Header and is acknowledged by a PUBACK packet. Section 2.2.1 provides more information about Packet Identifiers.

 

In the QoS 1 delivery protocol, the sender

·         MUST assign an unused Packet Identifier each time it has a new Application Message to publish [MQTT-4.3.2-1].

·         MUST send a PUBLISH packet containing this Packet Identifier with QoS 1 and DUP flag set to 0 [MQTT-4.3.2-2].

·         MUST treat the PUBLISH packet as “unacknowledged” until it has received the corresponding PUBACK packet from the receiver. Refer to section 4.4 for a discussion of unacknowledged messages [MQTT-4.3.2-3].

 

The Packet Identifier becomes available for reuse once the sender has received the PUBACK packet.

 

Note that a sender is permitted to send further PUBLISH packets with different Packet Identifiers while it is waiting to receive acknowledgements.

 

In the QoS 1 delivery protocol, the receiver

 

Figure 4.2 – QoS 1 protocol flow diagram, non-normative example

Sender Action

MQTT 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

 

 

 

1 The receiver does not need 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.

 

4.3.3 QoS 2: Exactly once delivery

This is the highest Quality of Service level, for use when neither loss nor duplication of messages a