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+ event 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 Introduction
• 2 MQTT Control Packet format
• 3 MQTT Control Packets
• 4 Operational behavior
• 5 Security
• 6 Using WebSocket as a network transport
• 7 Conformance

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.

Unless stated otherwise all UTF-8 encoded strings can have any length in the range 0 to 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].