Table of Contents

1. 1. Introduction

1.1 Organization of MQTT

1.2 Terminology

1.3 Normative references

1.4 Non normative references

1.5 Data representations

1.5.1 Bits

1.5.2 Integer data values

1.5.3 UTF-8 encoded strings

1.6 Editing conventions

MQTT Control Packet format

2.1 Structure of an MQTT Control Packet

Figure 2.2 - Fixed header format

2.2.1 MQTT Control Packet type

2.2 Flags

2.2.3 Remaining Length

2.3 Variable header

2.3.1 Packet Identifier

2.4 Payload

3 MQTT Control Packets

3.1 CONNECT – Client requests a connection to a Server

3.1.1 Fixed header

3.1.2 Variable header

3.1.3 Payload

3.1.4 Response

3.2 CONNACK – Acknowledge connection request

3.2.1 Fixed header

3.2.2 Variable header

3.2.3 Payload

3.3 PUBLISH – Publish message

3.3.1 Fixed header

3.3.2 Variable header

3.3.3 Payload

3.3.4 Response

3.3.4 Response

3.4 PUBACK – Publish acknowledgement

3.4.1 Fixed header

3.4.2 Variable header

3.4.3 Payload

3.4.4 Actions

3.5 PUBREC – Publish received (QoS 2 publish received, part 1)

3.5.1 Fixed header

3.5.2 Variable header

3.5.3 Payload

3.5.4 Actions

3.6 PUBREL – Publish release (QoS 2 publish received, part 2)

3.6.1 Fixed header

3.6.2 Variable header

3.6.3 Payload

3.6.4 Actions

3.7 PUBCOMP – Publish complete (QoS 2 publish received, part 3)

3.7.1 Fixed header

3.7.2 Variable header

3.7.3 Payload

3.7.4 Actions

3.8 SUBSCRIBE - Subscribe to topics

3.8.1 Fixed header

3.82 Variable header

3.8.3 Payload

3.8.4 Response

3.9 SUBACK – Subscribe acknowledgement

3.9.1 Fixed header

3.9.2 Variable header

3.9.3 Payload

3.10 UNSUBSCRIBE – Unsubscribe from topics

3.10.1 Fixed header

3.10.2 Variable header

3.10.3 Payload

3.10.4 Response

3.11 UNSUBACK – Unsubscribe acknowledgement

3.11.1Fixed header

3.11.2 Variable header

3.11.3 Payload

3.12 PINGREQ – PING request

3.12.1 Fixed header

3.12.2 Variable header

3.12.3 Payload

3.12.4 Response

3.13 PINGRESP – PING response

3.13.1 Fixed header

3.13.2 Variable header

3.13.3 Payload

3.14 DISCONNECT – Disconnect notification

3.14.1 Fixed header

3.14.2 Variable header

3.14.3 Payload

3.14.4 Response

4 Operational behavior

4.1 Storing state

4.1.1 Non normative example

4.2 Network Connections

4.3 Quality of Service levels and protocol flows

4.3.1 QoS 0: At most once delivery

4.3.2 QoS 1: At least once delivery

4.3.3 QoS 2: Exactly once delivery

4.4 Message delivery retry

4.5 Message receipt

4.6 Message ordering

4.7 Topic Names and Topic Filters

4.7.1 Topic wildcards

4.7.2 Topics beginning with $

4.7.1.3 Single level wildcard

4.8 Handling errors

5 Security

5.1 Introduction

5.2 MQTT solutions: security and certification

5.3 Lightweight cryptography and constrained devices

5.4 Implementation notes

5.4.1 Authentication of Clients by the Server

5.4.2 Authorization of Clients by the Server

5.4.3 Authentication of the Server by the Client

5.4.4 Integrity of Application Messages and Control Packets

5.4.5 Privacy of Application Messages and Control Packets

5.4.6 Non-repudiation of message transmission

5.4.7 Detecting compromise of Clients and Servers

5.4.8 Detecting abnormal behaviors

5.4.9 Other security considerations

5.4.10 Use of SOCKS

5.4.11 Security profiles

6 Using WebSocket as a network transport

6.1 IANA Considerations

7 Conformance

7.1 Conformance Targets

7.1.1 MQTT Server

7.1.2 MQTT Client

Appendix A. Acknowledgements (non normative)

Appendix B. Mandatory normative statements (non normative)

Appendix C. Revision history (non normative)

Table of Figures and Tables

Figure 1.1 Structure of UTF-8 encoded strings

Figure 1.2 UTF-8 encoded string non normative example

Figure 2.1 – Structure of an MQTT Control Packet

Figure 2.2 - Fixed header format

Table 2.1 - Control packet types

Table 2.2 - Flag Bits

Table 2.4 Size of Remaining Length field

Figure 2.3 - Packet Identifier bytes

Table 2.5 - Control Packets that contain a Packet Identifier

Table 2.6 - Control Packets that contain a Payload

Figure 3.1 – CONNECT Packet fixed header

Figure 3.2 - Protocol Name bytes

Figure 3.3 - Protocol Level byte

Figure 3.4 - Connect Flag bits

Figure 3.5 Keep Alive bytes

Figure 3.6 - Variable header non normative example

Figure 3.7 - Password bytes

Figure 3.8 – CONNACK Packet fixed header

Figure 3.9 – CONNACK Packet variable header

Table 3.1 – Connect Return code values

Figure 3.10 – PUBLISH Packet fixed header

Table 3.2 - QoS definitions

Table 3.3 - Publish Packet non normative example

Figure 3.11 - Publish Packet variable header non normative example

Table 3.4 - Expected Publish Packet response

Figure 3.12 - PUBACK Packet fixed header

Figure 3.13 – PUBACK Packet variable header

Figure 3.14 – PUBREC Packet fixed header

Figure 3.15 – PUBREC Packet variable header

Figure 3.16 – PUBREL Packet fixed header

Figure 3.17 – PUBREL Packet variable header

Figure 3.18 – PUBCOMP Packet fixed header

Figure 3.19 – PUBCOMP Packet variable header

Figure 3.20 – SUBSCRIBE Packet fixed header

Figure 3.21 - Variable header with a Packet Identifier of 10, Non normative example

Figure 3.22 – SUBSCRIBE Packet payload format

Table 3.5 - Payload non normative example

Figure 3.23 - Payload byte format non normative example

Figure 3.24 – SUBACK Packet fixed header

Figure 3.25 – SUBACK Packet variable header

Figure 3.26 – SUBACK Packet payload format

Table 3.6 - Payload non normative example

Figure 3.27 - Payload byte format non normative example

Figure 3.28 – UNSUBSCRIBE Packet Fixed header

Figure 3.29 – UNSUBSCRIBE Packet variable header

Table3.7 - Payload non normative example

Figure 3.30 - Payload byte format non normative example

Figure 3.31 – UNSUBACK Packet fixed header

Figure 3.32 – UNSUBACK Packet variable header

Figure 3.33 – PINGREQ Packet fixed header

Figure 3.34 – PINGRESP Packet fixed header

Figure 3.34 – PINGRESP Packet fixed header

Figure 4.1 – QoS 0 protocol flow diagram, non normative example

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

Figure 4.3 – QoS 2 protocol flow diagram, non normative example

Figure 6.1 - IANA WebSocket Identifier

    1. Introduction

    Solace Implementation Note

    This document provides an annotated version of the full text of the MQTT 3.1.1 functional specification. MQTT 3.1.1 is supported by the Solace PubSub+ message brokers running Solace PubSub+ software version 7.1.1 or greater acting in the role of an MQTT server. The text of the protocol specification is annotated with boxes like this one, which indicate any deviations, limitations, or choices made in the “SHOULD” and “MAY” clauses for the Solace implementation.

    Only exceptions to the MQTT 3.1.1 specification are highlighted – meaning that unless indicated otherwise, the Solace server conforms to each section of the specification.

    The target audience for these annotations are application developers developing MQTT clients for use with a Solace MQTT appliance as their MQTT server.

    A summary of the functionality supported by Solace is below. Solace PubSub+ software has only a few exceptions from what is required in the MQTT 3.1.1 specification.

    1. Server-side role only
    2. QoS 0 and QoS 1 messages are fully supported. QoS 2 messages from clients are accepted but are treated as QoS 1 messages. QoS 2 subscriptions from clients are accepted but are downgraded to QoS 1. Both of these behaviors are allowed by the specification.
    3. Will messages are supported with certain limitations.

1.1 Organization of MQTT

This specification is split into seven chapters:

1.2 Terminology

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.

For examples see Section 4.2 Network Connections.

Application Message:

The data carried by the MQTT protocol across the network for the application. When Application Messages are transported by MQTT they have an associated Quality of Service and a Topic Name.

Client:

A program or device that uses MQTT. A Client always establishes the Network Connection to the Server. It can

  • Publish Application Messages that other Clients might be interested in.
  • Subscribe to request Application Messages that it is interested in receiving.
  • Unsubscribe to remove a request for Application Messages.
  • Disconnect from 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.

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.

Topic Name:

The label attached to an Application Message which is matched against the Subscriptions known to the Server. The Server sends a copy of the Application Message to each Client that has a matching Subscription.

Topic Filter:

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

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.

MQTT Control Packet:

A packet of information that is sent across the Network Connection. The MQTT specification defines fourteen different types of Control Packet, one of which (the PUBLISH packet) is used to convey Application Messages.

1.3 Normative references

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt

 

[RFC 3629]

Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003 http://www.ietf.org/rfc/rfc3629.txt

 

[RFC 5246]

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

http://www.ietf.org/rfc/rfc5246.txt

 

[RFC 6455]

Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, December 2011.

http://www.ietf.org/rfc/rfc6455.txt

 

[Unicode]

The Unicode Consortium. The Unicode Standard.

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

1.4 Non normative references

Postel, J. Transmission Control Protocol . STD 7, IETF RFC 793, September 1981.

http://www.ietf.org/rfc/rfc793.txt

 

[AES]

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

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

 

[DES]

Data Encryption Standard (DES).

http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf

 

[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

 

[MQTTV31]

MQTT V3.1 Protocol Specification.

http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html

 

[NISTCSF]

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

 

[NIST 7628]

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, March 1996.

http://www.ietf.org/rfc/rfc1928.txt

 

[RFC4511]

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

http://www.ietf.org/rfc/rfc4511.txt

 

[RFC5077]

Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, "Transport Layer Security (TLS) Session Resumption without Server-Side State", RFC 5077, January 2008.

http://www.ietf.org/rfc/rfc5077.txt

 

[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, May 2008.

http://www.ietf.org/rfc/rfc5280.txt

 

[RFC6066]

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

http://www.ietf.org/rfc/rfc6066.txt

 

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.

http://www.ietf.org/rfc/rfc6749.txt

 

[RFC 69960]

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, June 2013.

http://www.ietf.org/rfc/rfc6960.txt

 

[SARBANES]

Sarbanes-Oxley Act of 2002.

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

 

[USEUSAFEHARB]

U.S.-EU Safe Harbor

http://export.gov/safeharbor/eu/eg_main_018365.asp

1.5 Data representations

1.5.1 Bits

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

1.5.2 Integer data values

Integer data values are 16 bits 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 UTF-8 encoded strings

Text fields in the Control Packets described later are encoded as UTF-8 strings. UTF-8 [RFC 3629]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 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 there is a limit on the size of a string that can be passed in one of these UTF-8 encoded string components; you cannot use a string that would encode to more than 65535 bytes.

Figure 1.1 Structure of UTF-8 encoded strings

The character data in a UTF-8 encoded string MUST be well-formed UTF-8 as defined by the Unicode specification [[Unicode]] and restated in RFC 3629 [RFC3629]. In particular this data MUST NOT include encodings of code points between U+D800 and U+DFFF. If a Server or Client receives a Control Packet containing ill-formed UTF-8 it MUST close the Network Connection [MQTT-1.5.3-1].

A UTF-8 encoded string MUST NOT include an encoding of the null character U+0000. If a receiver (Server or Client) receives a Control Packet containing U+0000 it MUST close the Network Connection [MQTT-1.5.3-2].

The data SHOULD NOT include encodings of the Unicode code points listed below. If a receiver (Server or Client) receives a Control Packet containing any of them it MAY close the Network Connection:

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 to be interpreted to mean U+FEFF ("ZERO WIDTH NO-BREAK SPACE") wherever it appears in a string and MUST NOT be skipped over or stripped off by a packet receiver [MQTT-1.5.3-3].

1.5.3.1 Non normative example

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.6 Editing conventions

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