<?xml version="1.0"encoding="US-ASCII"?> <!-- This template is for creating an Internet Draft using xml2rfc, which is available here: http://xml.resource.org. -->encoding="UTF-8"?> <!DOCTYPE rfcSYSTEM "rfc2629.dtd"[<!-- One method to get references from the online citation libraries. There has to be one entity for each item to be referenced. An alternate method (rfc include) is described in the references. --> <!ENTITY RFC8174 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml"> <!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"> <!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml"> <!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml"><!ENTITYRFC4949 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4949.xml">nbsp " "> <!ENTITYRFC6066 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6066.xml">zwsp "​"> <!ENTITYRFC6234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6234.xml">nbhy "‑"> <!ENTITYRFC6749 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml"> <!ENTITY RFC7800 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7800.xml"> <!ENTITY RFC8949 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8949.xml"> <!ENTITY RFC7250 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7250.xml"> <!ENTITY RFC7252 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7252.xml"> <!ENTITY RFC7301 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7301.xml"> <!ENTITY RFC7516 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7516.xml"> <!ENTITY RFC7517 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7517.xml"> <!ENTITY RFC7519 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7519.xml"> <!ENTITY RFC7525 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7525.xml"> <!ENTITY RFC7627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7627.xml"> <!ENTITY RFC8422 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8422.xml"> <!ENTITY RFC8442 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8442.xml"> <!ENTITY RFC7925 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7925.xml"> <!ENTITY RFC8446 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8446.xml"> <!ENTITY RFC5705 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5705.xml"> <!ENTITY RFC8032 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8032.xml"> <!ENTITY RFC8152 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8152.xml"> <!ENTITY RFC8392 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8392.xml"> <!ENTITY RFC8447 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8447.xml"> <!ENTITY RFC8610 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8610.xml"> <!ENTITY RFC8747 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8747.xml">wj "⁠"> ]><?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?> <!-- used by XSLT processors --> <!-- For a complete list and description of processing instructions (PIs), please see http://xml.resource.org/authoring/README.html. --> <!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use. (Here they are set differently than their defaults in xml2rfc v1.32) --> <?rfc strict="yes" ?> <!-- give errors regarding ID-nits and DTD validation --> <!-- control the table of contents (ToC) --> <?rfc toc="yes"?> <!-- generate a ToC --> <?rfc tocdepth="4"?> <!-- the number of levels of subsections in ToC. default: 3 --> <!-- control references --> <?rfc symrefs="yes"?> <!-- use symbolic references tags, i.e, [RFC2119] instead of [1] --> <?rfc sortrefs="yes" ?> <!-- sort the reference entries alphabetically --> <!-- control vertical white space (using these PIs as follows is recommended by the RFC Editor) --> <?rfc compact="yes" ?> <!-- do not start each main section on a new page --> <?rfc subcompact="no" ?> <!-- keep one blank line between list items --> <!-- end of list of popular I-D processing instructions --><rfc xmlns:xi="http://www.w3.org/2001/XInclude" submissionType="IETF" category="std" consensus="true" docName="draft-ietf-ace-mqtt-tls-profile-17"ipr="trust200902">number="9431" ipr="trust200902" obsoletes="" updates="" xml:lang="en" tocInclude="true" tocDepth="4" symRefs="true" sortRefs="true" version="3"> <!--category values: std, bcp, info, exp, and historic ipr values: trust200902, noModificationTrust200902, noDerivativesTrust200902, or pre5378Trust200902 you can add the attributes updates="NNNN" and obsoletes="NNNN" they will automatically be output with "(if approved)" --> <!-- ***** FRONT MATTER *****xml2rfc v2v3 conversion 3.12.2 --> <front><!-- The abbreviated title is used in the page header - it is only necessary if the full title is longer than 39 characters --><title abbrev="MQTT-TLSprofileProfile of ACE">Message Queuing Telemetry Transport(MQTT)-TLS profile(MQTT) and Transport Layer Security (TLS) Profile of Authentication and Authorization for Constrained Environments (ACE) Framework</title><!-- add 'role="editor"' below for the editors if appropriate --> <!-- Author 1--><seriesInfo name="RFC" value="9431"/> <author fullname="Cigdem Sengul"initials="C.S."initials="C." surname="Sengul"> <organization>Brunel University</organization> <address> <postal><!-- Reorder these if your country does things differently --><street>Dept. of Computer Science</street> <city>Uxbridge</city> <code>UB8 3PH</code><country>UK</country><country>United Kingdom</country> </postal> <email>csengul@acm.org</email><!-- uri and facsimile elements may also be added --></address> </author><!-- Author 2--><author fullname="Anthony Kirby"initials="A.K"initials="A." surname="Kirby"> <organization>Oxbotica</organization> <address> <postal><street>1a<extaddr>1a MilfordHouse, MayfieldHouse</extaddr> <street>Mayfield Road, Summertown</street><!-- Reorder these if your country does things differently --><city>Oxford</city> <code>OX2 7EL</code><country>UK</country><country>United Kingdom</country> </postal> <email>anthony@anthony.org</email> </address> </author> <dateyear="2022"/> <!-- If the month and year are both specified and are the current ones, xml2rfc will fill in the current day for you. If only the current year is specified, xml2rfc will fill in the current day and month for you. If the year is not the current one, it is necessary to specify at least a month (xml2rfc assumes day="1" if not specified for the purpose of calculating the expiry date). With drafts it is normally sufficient to specify just the year. --> <!-- Meta-data Declarations --> <area>Security</area> <workgroup>ACE Working Group</workgroup> <!-- WG name at the upperleft corner of the doc, IETF is fine for individual submissions. If this element is not present, the default is "Network Working Group", which is used by the RFC Editor as a nod to the history of the IETF. --> <keyword>Internet-Draft</keyword> <!-- Keywords will be incorporated into HTML output files in a meta tag but they have no effect on text or nroff output. If you submit your draft to the RFC Editor, the keywords will be used for the search engine. -->month="July" year="2023"/> <area>sec</area> <workgroup>ace</workgroup> <keyword>publish-subscribe</keyword> <keyword>authorization information format</keyword> <abstract> <t> This document specifies a profile for theACE (AuthenticationAuthentication and Authorization for ConstrainedEnvironments)Environments (ACE) framework to enable authorization in a publish-subscribe messaging system based on Message Queuing Telemetry Transport(MQTT)-based publish-subscribe messaging system. Proof-of-possession(MQTT). Proof-of-Possession keys, bound toOAuth2.0OAuth 2.0 access tokens, are used to authenticate and authorize MQTT Clients. The protocol relies on TLS for confidentiality and MQTT server (Broker) authentication. </t> </abstract> </front> <middle> <sectiontitle="Introduction">numbered="true" toc="default"> <name>Introduction</name> <t> This document specifies a profile for the ACE framework <xreftarget="I-D.ietf-ace-oauth-authz"></xref>.target="RFC9200" format="default"/>. In this profile, Clients and Servers (Brokers) use MQTT to exchange Application Messages. The protocol relies on TLS for communication security between entities. The MQTT protocol interactions are described based on the <xreftarget="MQTT-OASIS-Standard-v5">MQTTtarget="MQTT-OASIS-Standard-v5" format="default">MQTT v5.0- theOASIS Standard</xref>. Since it is expected that MQTT deployments will continue to support MQTT v3.1.1 Clients, this document also describes a reduced set of protocol interactions for the <xreftarget="MQTT-OASIS-Standard-v3.1.1">MQTTtarget="MQTT-OASIS-Standard-v3.1.1" format="default">MQTT v3.1.1- theOASIS Standard</xref>. However, MQTT v5.0 is theRECOMMENDED version<bcp14>RECOMMENDED</bcp14> version, as it works more naturally with ACE-style authentication and authorization. </t> <t> MQTT is a publish-subscribe protocol, and after connecting to the MQTT Server (Broker), a Client can publish and subscribe to multiple topics. The Broker, which acts as the Resource Server (RS), is responsible for distributing messages published by the publishers to their subscribers. In the rest of the document, the terms "RS", "MQTTServer"Server", and "Broker" are used interchangeably. </t> <t> Messages are published under a Topic Name, and subscribers subscribe to the Topic Names to receive the corresponding messages. The Broker uses the Topic Name in a published message to determine which subscribers to relay the messages to. In this document,topics, moretopics (more specifically, TopicNames,Names) are treated as resources. The Clients are assumed to have identified the publish/subscribe topics of interestout-of-bandout of band (topic discovery is not a feature of the MQTT protocol). A Resource Owner canpre-configurepreconfigure policies at the Authorization Server (AS) that give Clients publish or subscribe permissions to different topics. </t> <t> Clients prove their permission to publish and subscribe to topics hosted on an MQTT Broker using an accesstoken,token that is bound to aproof-of-possessionProof-of-Possession (PoP) key. This document describes how to authorize the following exchanges between the Clients and the Broker.<list style="symbols"> <t>Connection</t> <ul spacing="normal"> <li>connection requests from the Clients to theBroker</t> <t>PublishBroker</li> <li>publish requests from the Clients to the Broker and from the Broker to theClients</t> <t>SubscribeClients</li> <li>subscribe requests from the Clients to theBroker</t> </list>Broker</li> </ul> <t> Clients use the MQTT PUBLISH packet to publish to a topic. The mechanisms specified in this document do not protect thepayloadPayload of the PUBLISH packet from the Broker. Hence, thepayloadPayload is not signed or encrypted specifically for the subscribers. This functionality may be implemented using the proposal outlined in the <xreftarget="I-D.ietf-ace-pubsub-profile">ACEtarget="I-D.ietf-ace-pubsub-profile" format="default">ACE Pub-Sub Profile</xref>. </t> <t> To provide communication confidentiality and Broker authentication to the MQTT Clients, TLS is used, and TLS 1.3 <xreftarget="RFC8446"></xref>target="RFC8446" format="default"/> isRECOMMENDED.<bcp14>RECOMMENDED</bcp14>. This document makes the same assumptions asSection 4 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="4">the ACE framework</xref> regarding Client and RS registration with the ASandfor setting up the keying material. While the Client-Broker exchanges are only over MQTT, the required Client-AS and RS-AS interactions are described for HTTPS-based communication <xreftarget="I-D.ietf-httpbis-semantics"></xref>,target="RFC9110" format="default"/>, using the "application/ace+json" contenttype, andtype and, unless otherwise specified,usingJSON encoding. The tokenMAY<bcp14>MAY</bcp14> be an opaque reference to authorization information or a JSON Web Token (JWT) <xreftarget="RFC7519"></xref>.target="RFC7519" format="default"/>. For JWTs, this document follows <xreftarget="RFC7800"></xref>target="RFC7800" format="default"/> for PoP semantics for JWTs, and the mechanisms for providing and verifying PoP are detailed in <xreftarget="connect_v5"></xref>.target="connect_v5" format="default"/>. The Client-AS and RS-AS exchangesMAY<bcp14>MAY</bcp14> also use protocols other than HTTP, e.g., Constrained Application Protocol (CoAP) <xreftarget="RFC7252"></xref>target="RFC7252" format="default"/> or MQTT. It is recommended that TLS is used to secure these communication channels between Client-AS and RS-AS. To reduce the protocol memory and bandwidth requirements, implementationsMAY<bcp14>MAY</bcp14> also use the "application/ace+cbor" content type,and CBORConcise Binary Object Representation (CBOR) encoding <xreftarget="RFC8949"></xref>, andtarget="RFC8949" format="default"/>, CBOR WebToken (CWT)Tokens (CWTs) <xreftarget="RFC8392"></xref>target="RFC8392" format="default"/>, and associated PoP semantics. For more information, see <xreftarget="RFC8747">Proof-of-Possessiontarget="RFC8747" format="default">"Proof-of-Possession Key Semantics for CBOR Web Tokens(CWTs)</xref>.(CWTs)"</xref>. A JWTtokenusesJOSE,JSON Object Signing and Encryption (JOSE), while a CWTtokenusesCOSECBOR Object Signing and Encryption (COSE) <xreftarget="RFC8152"></xref>target="RFC9052" format="default"/> for security protection. </t> <sectiontitle="Requirements Language">numbered="true" toc="default"> <name>Requirements Language</name> <t> Thekeywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY",key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and"OPTIONAL""<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as described inBCP 14BCP 14 <xreftarget="RFC2119"></xref>target="RFC2119"/> <xreftarget="RFC8174"></xref>,target="RFC8174"/> when, and only when, they appear in all capitals, as shown here. </t> </section> <sectiontitle="ACE-Related Terminology">numbered="true" toc="default"> <name>ACE-Related Terminology</name> <t> Certain security-relatedtermsterms, such as "authentication", "authorization","confidentiality","data confidentiality", "(data) integrity", "message authenticationcode",code" (MAC), and"verify""verify", are taken from <xreftarget="RFC4949"></xref>.target="RFC4949" format="default"/>. </t> <t> The terminology for entities in the architecture is defined in OAuth 2.0 <xreftarget="RFC6749"></xref>target="RFC6749" format="default"/>, such as "Client" (C), "Resource Server"(RS)(RS), and "Authorization Server" (AS). </t> <t> The term "resource" is used to refer to an MQTT Topic Name, which is defined in <xreftarget="mqtt-defs"></xref>.target="mqtt-defs" format="default"/>. Hence, the "Resource Owner" is any entity that can authoritatively speak for the topic. This document also defines a Client Authorization Server for Clients that are not able to support HTTP. </t><t> <list hangIndent="8" style="hanging"> <t hangText="Client<dl newline="true" spacing="normal" indent="8"> <dt>Client Authorization Server(CAS)"> <vspace blankLines="0"/>(CAS)</dt> <dd> An entity that prepares and endorses authentication and authorization data for aClient,Client and communicates to the AS using HTTPS.</t> </list> </t></dd> </dl> </section> <sectiontitle="MQTT-Related Terminology" anchor="mqtt-defs">anchor="mqtt-defs" numbered="true" toc="default"> <name>MQTT-Related Terminology</name> <t> The document describes message exchanges as MQTT protocol interactions. The Clients are MQTT Clients, which connect to the Broker to publish and subscribe to ApplicationMessages, labelledMessages (which are labeled with theirtopics.topics). For additional information, please refer to the <xreftarget="MQTT-OASIS-Standard-v5">MQTTtarget="MQTT-OASIS-Standard-v5" format="default">MQTT v5.0- theOASISStandard</xref>Standard </xref> orthe<xreftarget="MQTT-OASIS-Standard-v3.1.1">MQTTtarget="MQTT-OASIS-Standard-v3.1.1" format="default">MQTT v3.1.1- theOASISStandard</xref>.Standard </xref>. </t><t> <list hangIndent="8" style="hanging"> <t hangText="Broker"> <vspace blankLines="0"/><dl newline="true" spacing="normal" indent="8"> <dt>Broker</dt> <dd> The Server in MQTT. It acts as an intermediary between the Clients that publish Application Messages and the Clients that made Subscriptions. The Broker acts as the Resource Server for the Clients.</t> <t hangText="Client"> <vspace blankLines="0"/></dd> <dt>Client</dt> <dd> A device or program that uses MQTT.</t> <t hangText = "Network Connection"> <vspace blankLines="0"/></dd> <dt>Network Connection</dt> <dd> 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,lossless stream of bytes in both directions. This document uses TLS astranportthe transport protocol.</t> <t hangText = "Session"> <vspace blankLines="0"/></dd> <dt>Session</dt> <dd> A stateful interaction between a Client and a Broker. Some Sessions last only as long as the Network Connection; others can span multiple Network Connections.</t> <t hangText="Application Message"> <vspace blankLines="0"/></dd> <dt>Application Message</dt> <dd> The data carried by the MQTT protocol. The data has an associated Quality-of-Service (QoS) level and Topic Name.</t> <t hangText="MQTT</dd> <dt>MQTT ControlPacket"> <vspace blankLines="0"/>Packet</dt> <dd> The MQTT protocol operates by exchanging a series of MQTT Controlpackets.Packets. Each packet is composed of a Fixed Header, a Variable Header (depending on thecontrol packetControl Packet type), and a Payload.</t> <t hangText="UTF-8 encoded string"> <vspace blankLines="0"/></dd> <dt>UTF-8-encoded string</dt> <dd> A string prefixed with atwo-byte lengthtwo-byte-length field that gives the number of bytes in aUTF-8 encodedUTF-8-encoded string itself. Unless stated otherwise, allUTF-8 encodedUTF-8-encoded strings can have any length in the range 0 to 65535 bytes.</t> <t hangText="Binary Data"> <vspace blankLines="0"/></dd> <dt>Binary Data</dt> <dd> Binary Data is represented by atwo-byte length fieldtwo-byte-length field, 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 65535Bytes. </t> <t hangText="Variablebytes. </dd> <dt>Variable ByteInteger"> <vspace blankLines="0"/>Integer</dt> <dd> A Variable Byte Integer is encoded using an encoding scheme that uses a single byte for values up to 127. For larger values, 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.</t> <t hangText="QoS level"> <vspace blankLines="0"/></dd> <dt>QoS level</dt> <dd> The level of assurance for the delivery of an Application Message. The QoS level can be 0-2, where 0 indicates "At most once delivery", 1 indicates "At least once delivery", and 2 indicates "Exactly once delivery".</t> <t hangText="Property"> <vspace blankLines="0"/></dd> <dt>Property</dt> <dd> The last field of the Variable Header is a set of properties for several MQTTcontrol packets (e.g. CONNECT,Control Packets (e.g., CONNECT and CONNACK). APropertyproperty consists of an Identifier that defines its usage and data type, followed by a value. The Identifier is encoded as a Variable Byte Integer. For example, the "Authentication Data" property uses theIdentifieridentifier 22.</t> <t hangText="Topic Name"> <vspace blankLines="0"/></dd> <dt>Topic Name</dt> <dd> The label attached to an Application Message, which is matched to a Subscription.</t> <t hangText="Subscription"> <vspace blankLines="0"/></dd> <dt>Subscription</dt> <dd> A Subscription comprises a Topic Filter and a maximum QoS. A Subscription is associated with a singlesession. </t> <t hangText="Topic Filter"> <vspace blankLines="0"/>Session. </dd> <dt>Topic Filter</dt> <dd> An expression that indicates interest in one or more Topic Names. Topic Filters may include wildcards.</t> </list> </t></dd> </dl> <t> MQTT sends variouscontrol packetsControl Packets across a Network Connection. The following is not an exhaustive list, and thecontrol packetsControl Packets that are not relevant for authorization are not explained.These include, forFor instance, these include the PUBREL and PUBCOMP packets used in the 4-step handshake required for QoS level 2.<list hangIndent="8" style="hanging"> <t hangText="CONNECT"> <vspace blankLines="0"/></t> <dl newline="true" spacing="normal" indent="8"> <dt>CONNECT</dt> <dd> The Clientrequestrequests to connect to the Broker. This is the first packet sent by a Client.</t> <t hangText="CONNACK"> <vspace blankLines="0"/></dd> <dt>CONNACK</dt> <dd> The Broker connection acknowledgment. CONNACK packets contain return codesindicatingthat indicate either a success or an error state in response to a Client's CONNECT packet.</t> <t hangText="AUTH"> <vspace blankLines="0"/> Authentication Exchange.</dd> <dt>AUTH</dt> <dd> An AUTHcontrol packetControl Packet is sent from the Client to the Broker or from the Broker to the Client as part of an extended authentication exchange. AUTHPropertiesproperties include the Authentication Method and Authentication Data. The Authentication Method is set in the CONNECT packet, and consequent AUTH packets follow the same Authentication Method. The contents of the Authentication Data are defined by the Authentication Method.</t> <t hangText="PUBLISH"> <vspace blankLines="0"/></dd> <dt>PUBLISH</dt> <dd> Publish request sent from a publishing Client to theBroker,Broker or from the Broker to a subscribing Client.</t> <t hangText="PUBACK"> <vspace blankLines="0"/></dd> <dt>PUBACK</dt> <dd> Response to a PUBLISH request with QoS level 1.APUBACK can be sent from the Broker to a Client or from a Client to the Broker.</t> <t hangText="PUBREC"> <vspace blankLines="0"/></dd> <dt>PUBREC</dt> <dd> Response to a PUBLISH request with QoS level 2. PUBREC can be sent from the Broker to a Client or from a Client to the Broker.</t> <t hangText="SUBSCRIBE"> <vspace blankLines="0"/></dd> <dt>SUBSCRIBE</dt> <dd> Subscribe request sent from a Client.</t> <t hangText="SUBACK"> <vspace blankLines="0"/></dd> <dt>SUBACK</dt> <dd> Subscribe acknowledgment from the Broker to the Client.</t> <t hangText="PINGREQ"> <vspace blankLines="0"/></dd> <dt>PINGREQ</dt> <dd> A ping request sent from a Client to the Broker. It signals to the Broker that the Client is alive and is used to confirm that the Broker is also alive. The "Keep Alive" period is set in the CONNECT packet.</t> <t hangText="PINGRESP"> <vspace blankLines="0"/></dd> <dt>PINGRESP</dt> <dd> Response sent by the Broker to the Client in response to PINGREQ. It indicates the Broker is alive.</t> <t hangText="DISCONNECT"> <vspace blankLines="0"/></dd> <dt>DISCONNECT</dt> <dd> The DISCONNECT packet is the final MQTT Control Packet sent from the Client or the Broker. It indicates the reason why the Network Connection is being closed. If the Network Connection is closed without the Client first sending a DISCONNECT packet withReason Codereason code 0x00 (Normal disconnection) and the MQTT Connection has a Will Message, the Will Message is published.</t> <t hangText="Will"> <vspace blankLines="0"/></dd> <dt>Will</dt> <dd> <t> If the Network Connection is not closed normally, the Broker sends a last WillmessageMessage for the Client if the Client provided one in its CONNECT packet. Situations in which the Will Message is published include, but are not limitedto: <list style="symbols"> <t>Anto, the following: </t> <ul spacing="normal"> <li>an I/O error or network failure detected by theBroker.</t> <t>TheBroker,</li> <li>the Client fails to communicate within the Keep Aliveperiod.</t> <t>Theperiod,</li> <li>the Client closes the Network Connection without first sending a DISCONNECT packet witha Reason Codereason code 0x00 (Normaldisconnection).</t> <t>Thedisconnection), and</li> <li>the Broker closes the Network Connection without first receiving a DISCONNECT packet witha Reason Codereason code 0x00 (Normaldisconnection).</t> </list>disconnection).</li> </ul> <t> If the Will Flag is set in the CONNECT flags, then thepayloadPayload of the CONNECT packet includes information about the Will. The information consists of the Will Properties, Will Topic, and Will Payload fields. </t></list> </t></dd> </dl> </section> </section> <sectiontitle="Authorizinganchor="token_acquisition" numbered="true" toc="default"> <name>Authorizing ConnectionRequests" anchor="token_acquisition">Requests</name> <t> This section specifies how Client connections are authorized by the AS and verified by the MQTT Broker. <xreftarget="protocol_flow"></xref>target="protocol_flow" format="default"/> shows the basic protocolflowflows during connection setup. The token request and response use the token endpoint at the AS, specified for HTTP-based interactions inSection 5.8 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="5.8">the ACE framework</xref>. Steps (D) and (E) are optional and use the introspection endpoint specified inSection 5.9 of<xref target="RFC9200" format="default" sectionFormat="of" section="5.9"> the ACEframework.framework</xref>. The discussion in this document assumes that the Client and the Broker use HTTPS to communicate with the AS via these endpoints. The Client and the Broker use MQTT to communicate between them. The C-AS and Broker-AScommunication MAYcommunications <bcp14>MAY</bcp14> be implemented using protocols other than HTTPS,e.g.e.g., CoAP or MQTT. Whatever protocol is used for the C-AS and Broker-AS communicationsMUST<bcp14>MUST</bcp14> provide mutual authentication, confidentiality protection, and integrity protection. </t> <t> If the Client isresource-constrainedresource constrained or does not support HTTPS, a separate Client Authorization Server may carry out the token request on behalf of the Client(Figure 1(<xref target="protocol_flow"/>, steps (A) and(B)), and(B)) and, later, onboard the Client with the token. The interactions between a Client and its Client Authorization Server for token onboarding and support for MQTT-based token requests at the AS are out of the scope of this document. </t> <figurealign="center" anchor="protocol_flow" title="Connection Setup">anchor="protocol_flow"> <name>Connection Setup</name> <artworkalign="left"><![CDATA[align="left" name="" type="" alt=""><![CDATA[ +---------------------+ | Client | | | +---(A) Tokenrequest--|request------| Client - | | | Authorization | | +-(B) Accesstoken->token-----> Server Interface | | | | (HTTPS) | | | |_____________________| | | | | +--v-------------+ | Pub/Sub Interface | | Authorization | | (MQTT over TLS) | | Server |+-----------^---------++----------------^----+ |________________| | | | ^(C)Connection (F)Connection(C) Connection (F) Connection | | request + response | | access token | | | | | | | +---v--------------+ | | | Broker | | | | (MQTT over TLS) | | | |__________________| |+(D)Introspection-|+(D) Introspection-----| | | request(optional) |(optional)| RS-AS interface | | | (HTTPS) |+-(E)Introspection---->|__________________|+-(E) Introspection-------->|__________________| response (optional) ]]></artwork> </figure> <sectiontitle="Clientnumbered="true" toc="default"> <name>Client Token Request to the Authorization Server(AS)">(AS)</name> <t> The first step in the protocol flow(Figure 1(<xref target="protocol_flow"/>, step (A)) is the token acquisition by the Client from the AS. The Client and the ASMUST<bcp14>MUST</bcp14> perform mutual authentication. The Client requests an access token from theASAS, as described inSection 5.8.1 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="5.8.1">the ACE framework</xref>. The document follows the procedures defined inSection 3.2.1 of the<xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default" sectionFormat="of" section="3.2.1">the DTLS profile</xref> forRPK (Raw Public Keysraw public keys (RPKs) <xreftarget="RFC7250"></xref>),target="RFC7250" format="default"/>) and inSection 3.3.1 of the same document<xref target="RFC7250" section="3.3.1" sectionFormat="of" format="default"/> forPSK (Pre-Shared Keys).pre-shared keys (PSKs). However, the content type of the request is set to "application/ace+json", and the AS uses JSON in thepayloadPayload of its responses to the Client and the RS. As explained earlier, implementationsMAY<bcp14>MAY</bcp14> also use the "application/ace+cbor" content type. </t> <t> On receipt of the token request, the AS verifies the request. If the AS successfully verifies the access token request and authorizes the Client for the indicated audience (i.e., RS) and scopes (i.e., publish/subscribe permissions overtopicstopics, as described in <xreftarget="scope"></xref>),target="scope" format="default"/>), the AS issues an access token(Figure 1(<xref target="protocol_flow"/>, step (B)). </t> <t>The response includes the parameters described inSection 5.8.2 of<xreftarget="I-D.ietf-ace-oauth-authz">thetarget="RFC9200" section="5.8.2" sectionFormat="of" format="default">the ACE framework</xref>. ForRPK,RPKs, the parameters are as described inSection 3.2.1 of the<xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" section="3.2.1" sectionFormat="of" format="default">the DTLS profile</xref>. ForPSK,PSKs, the document followsSection 3.3.1 of the<xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default" sectionFormat="of" section="3.3.1">the DTLS profile</xref>. In both cases, if the response contains an "ace_profile" parameter, this parameter is set to "mqtt_tls". The returned token is a Proof-of-Possession (PoP) token by default. </t> <t> This document follows <xreftarget="RFC7800"></xref>target="RFC7800" format="default"/> for PoP semantics for JWTs (CWTsMAY<bcp14>MAY</bcp14> also be used). The AS includes a "cnf" (confirmation) parameter in the PoPtoken,token to declare that the Client possesses a particular key and the RS can cryptographically confirm that the Client has possession of that key, as described in <xreftarget="I-D.ietf-ace-oauth-params"></xref>.target="RFC9201" format="default"/>. </t> <t> Note that the contents of the web tokens (including the "cnf" parameter) are to be consumed by the RS and not the Client (the Client obtains the key information in a different manner). The RPK case is handled as described inSection 3.2.1 of the<xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default" sectionFormat="of" section="3.2.1">the DTLS profile</xref>. For the PSK case, the referenced procedures apply, with the following exceptions to accommodate JWT and JOSE use. In this case, the AS adds a "cnf" parameter to theaccess informationAccess Information carrying <xreftarget="RFC7517">a JWK (JSONtarget="RFC7517" format="default">a JSON WebKey)</xref>Key (JWK)</xref> object that contains either the symmetric key itself or a key identifier that can be used by the RS to determine the secret key it shares with the Client. The JWT is created as explained inSection 7 of<xreftarget="RFC7519"></xref>,target="RFC7519" section="7" sectionFormat="of" format="default"/>, and the JWTMUST<bcp14>MUST</bcp14> include <xreftarget="RFC7516">JWE</xref>.target="RFC7516" format="default"> a JSON Web Encryption (JWE)</xref>. If a CWT/COSE isusedused, this informationMUST<bcp14>MUST</bcp14> be inside the "COSE_Key"object,object andMUST<bcp14>MUST</bcp14> be encrypted using a "COSE_Encrypt0" structure. </t> <t> The AS returns error responses for JSON-based interactions followingSection 5.2 of<xreftarget="RFC6749"></xref>.target="RFC6749" section="5.2" sectionFormat="of" format="default"/>. When CBOR is used, the interactionsMUST<bcp14>MUST</bcp14> implementSection 5.8.3 ofthe procedure described in <xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" section="5.8.3" sectionFormat="of">the ACE framework</xref>. </t> </section> <sectiontitle="Clientanchor="connect_v5" numbered="true" toc="default"> <name>Client Connection Request to the Broker(C)" anchor="connect_v5">(C)</name> <sectiontitle="Overviewanchor="auth_options" numbered="true" toc="default"> <name>Overview of Client-RS Authentication Methods over TLS andMQTT" anchor="auth_options">MQTT</name> <t> Unless the Client publishes and subscribes to only public topics, the Client and the BrokerMUST<bcp14>MUST</bcp14> perform mutual authentication. The ClientMUST<bcp14>MUST</bcp14> authenticate to the Broker either over MQTT or TLS before performing any other action. For MQTT, the options are "None" and "ace". For TLS, the options are "Anon" for an anonymous client, and "Known(RPK/PSK)" forRPKRPKs andPSK,PSKs, respectively. The "None" and "Anon" options do not provide client authentication but can be used either during authentication or in combination with authentication at the other layer. When the Client uses TLS:Anon,MQTT:None, the Client can only publish or subscribe to public topics. Thus, the client authentication procedures involve the following possible combinations:<list style="symbols"> <t>TLS:Anon,MQTT:None: This</t> <dl newline="true" spacing="normal" indent="8"> <dt>TLS:Anon,MQTT:None:</dt> <dd>This option is used only for the topics that do not require authorization, including the "authz-info" topic. Publishing to the "authz-info" topic is described in <xreftarget="app-authzinfo"></xref>.</t> <t>TLS:Anon,MQTT:ace: Thetarget="app-authzinfo" format="default"/>.</dd> <dt>TLS:Anon,MQTT:ace:</dt> <dd>The token is transported inside the CONNECT packet andMUST<bcp14>MUST</bcp14> be validated using one of the methods described in <xreftarget="app-authzinfo"></xref>.target="app-authzinfo" format="default"/>. This option also supports a tokenless connection request for AS discovery. As per the <xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default">ACE framework</xref>, a separate step is needed to determine whether the discovered AS URI is authorized to act as anAS.</t> <t>TLS:Known(RPK/PSK),MQTT:none: ThisAS.</dd> <dt>TLS:Known(RPK/PSK),MQTT:none:</dt> <dd>This specification supports client authentication with TLS withRPKRPKs andPSKPSKs, following the procedures described in the <xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default">DTLS profile</xref>. For the RPK, the ClientMUST<bcp14>MUST</bcp14> have published the token to the "authz-info" topic. For the PSK, the tokenMAY<bcp14>MAY</bcp14> be published to the "authz-info"topic,topic orMAY<bcp14>MAY</bcp14> be, alternatively, provided as a "PSK identity"(e.g.(e.g., an "identity" in the "identities" field in the Client's "pre_shared_key" extension in TLS 1.3).</t> <t>TLS:Known(RPK/PSK),MQTT:ace: This</dd> <dt>TLS:Known(RPK/PSK),MQTT:ace:</dt> <dd>This optionSHOULD NOT<bcp14>SHOULD NOT</bcp14> be chosen as the token transported in the CONNECT packet and overwrites any permissions passed during the TLSauthentication.</t> </list>authentication.</dd> </dl> <t> It isRECOMMENDED<bcp14>RECOMMENDED</bcp14> that the Client implements TLS:Anon,MQTT:ace as the first choice when working with protected topics. However, MQTT v3.1.1 Clients that do not prefer to overloadusernamethe User Name andpasswordPassword fields for ACE (as described in <xreftarget="MQTTv311"></xref>) MAYtarget="MQTTv311" format="default"/>) <bcp14>MAY</bcp14> implementTLS:Known(RPK/PSK),MQTT:none, and consequentlyTLS:Known(RPK/PSK),MQTT:none and, consequently, TLS:Anon,MQTT:None to submit their token to "authz-info". </t> <t> The BrokerMUST<bcp14>MUST</bcp14> support TLS:Anon,MQTT:ace. To support Clients with different capabilities, the BrokerMAY<bcp14>MAY</bcp14> provide multiple client authentication options,e.g.e.g., support TLS:Known(RPK),MQTT:none and TLS:Anon,MQTT:None, to enable RPK-based client authentication. </t> <t> The ClientMUST<bcp14>MUST</bcp14> authenticate the Broker during the TLS handshake. If the Client authentication uses TLS:Known(RPK/PSK), then the Broker is authenticated using the respective method. Otherwise, to authenticate the Broker, the ClientMUST<bcp14>MUST</bcp14> validate a public key from an X.509 certificate or an RPK from the Broker against the "rs_cnf" parameter in the token response, which contains information about the public key used by the RS to authenticate if the token type is "pop" and asymmetric keys are used as defined in <xreftarget="I-D.ietf-ace-oauth-params"></xref>.target="RFC9201" format="default"/>. The ASMAY<bcp14>MAY</bcp14> include the thumbprint of the RS's X.509 certificate in the "rs_cnf"(thumbprint(thumbprint, as defined in <xreftarget="I-D.ietf-cose-x509"></xref>).target="RFC9360" format="default"/>). In this case, the ClientMUST<bcp14>MUST</bcp14> validate the RS certificate against this thumbprint. </t> </section> <section anchor="app-authzinfo"title="authz-info:numbered="true" toc="default"> <name>authz-info: The Authorization InformationTopic">Topic</name> <t> In the cases when the Client must transport the token to the Broker first, the Client connects to the Broker to publish its token to the "authz-info" topic. The "authz-info" topicMUST<bcp14>MUST</bcp14> only bepublish-onlypublished (i.e., the Clients are not allowed to subscribe to it). "authz-info" is not protected, and hence, the Client uses the TLS:Anon,MQTT:None option over a TLS connection. After publishing the token, the Client disconnects from the Broker and is expected to reconnect using client authentication over TLS (i.e., TLS:Known(RPK/PSK),MQTT:none). </t> <t> The Broker stores and indexes all tokens received to the "authz-info" topic in its key store (similar to the <xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default">DTLS profile for ACE</xref>). This profile follows the recommendation ofSection 5.10.1 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="5.10.1">the ACE framework</xref> and expects that the Broker stores only one token per PoP key, and any other token linked to the same key overwrites an existing token. </t> <t> The BrokerMUST<bcp14>MUST</bcp14> verify the validity of the token (i.e., through local validation orintrospection,introspection if the token is areference)reference), as described in <xreftarget="token_validation"></xref>.target="token_validation" format="default"/>. If the token is not valid, the BrokerMUST<bcp14>MUST</bcp14> discard the token. </t> <t> Depending on the QoS level of the PUBLISH packet, the Broker returns the error response as a PUBACK, PUBREC, or DISCONNECT packet. If the QoS level is equal to 0, and the token is not valid, or if the claims cannot be obtained in the case of an introspected token, the BrokerMUST<bcp14>MUST</bcp14> send a DISCONNECT packet withthereason code 0x87 (Not authorized). If the PUBLISHpayloadPayload does not parse to a token, the BrokerMUST<bcp14>MUST</bcp14> send a DISCONNECT withthereason code 0x99 (Payload format invalid). </t> <t> If the QoS level of the PUBLISH packet is greater than or equal to 1, and the token is not valid, or the claims cannot be obtained in the case of an introspected token, the BrokerMUST<bcp14>MUST</bcp14> sendthereason code 0x87 (Not authorized) in the PUBACK or PUBREC. If the PUBLISHpayloadPayload does not parse to a token, the PUBACK/PUBREC reason code is 0x99 (Payload format invalid). </t> <t>It must be noted that whenWhen the Broker sends the "Not authorized" response, it must be noted that this corresponds to the token being notvalid,valid and not that the actual PUBLISH packet was not authorized. Given that the "authz-info" is a public topic, this response is not expected to cause confusion. </t> </section> <section anchor="auth-TLS"title="Clientnumbered="true" toc="default"> <name>Client Authentication overTLS">TLS</name> <t> This document supports TLS withRaw Public Keys (RPK)raw public keys (RPKs) <xreftarget="RFC7250"></xref>target="RFC7250" format="default"/> and withPre-Shared Keys (PSK).pre-shared keys (PSKs). The TLS session setup follows the <xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default">DTLS profile for ACE</xref>, as the profile applies to TLS equally well <xreftarget="I-D.ietf-ace-extend-dtls-authorize"></xref>.target="RFC9430" format="default"/>. When there are exceptions to the DTLS profile, these are explicitly stated in the document. If TLS 1.2 is used, <xreftarget="RFC7925"></xref>target="RFC7925" format="default"/> describes how TLS can be used for constrained devices, alongside recommended cipher suites. Additionally, TLS 1.2 implementationsMUST<bcp14>MUST</bcp14> use the "Extended Main Secret" extension (terminology adopted from <xreftarget="I-D.ietf-tls-rfc8446bis"></xref>)target="I-D.ietf-tls-rfc8446bis" format="default"/>) to incorporate the handshake transcript into the main secret <xreftarget="RFC7627"></xref>.target="RFC7627" format="default"/>. TLS implementationsSHOULD<bcp14>SHOULD</bcp14> use theSNI (ServerServer NameIndication)Indication (SNI) <xreftarget="RFC6066"></xref>target="RFC6066" format="default"/> andAPLN (Application-LayerApplication-Layer ProtocolNegotiation)Negotiation (ALPN) <xreftarget="RFC7301"></xref>target="RFC7301" format="default"/> extensions so the TLS handshake authenticates as much of the protocol context as possible. </t> <section anchor="TLS-RPK"title="Rawnumbered="true" toc="default"> <name>Raw Public KeyMode">Mode</name> <t> This document follows the procedures defined inSection 3.2.2 of the<xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default" sectionFormat="of" section="3.2.2">the DTLS profile for ACE</xref> with the following exceptions. The ClientMUST<bcp14>MUST</bcp14> upload the access token to the Broker using the method specified in <xreftarget="app-authzinfo"></xref>target="app-authzinfo" format="default"/> before initiating the handshake. </t> </section> <section anchor="TLS-PSK"title="Pre-Sharednumbered="true" toc="default"> <name>Pre-Shared KeyMode">Mode</name> <t> This document follows the procedures defined inSection 3.3.2 of<xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" section="3.3.2" sectionFormat="of" format="default">the DTLS profile for ACE</xref> with the following exceptions. </t> <t> To use TLS 1.3 with pre-shared keys, the Client utilizes the PSKkeyextension specified in <xreftarget="RFC8446"></xref>target="RFC8446" format="default"/> using the key conveyed in the "cnf" parameter of the AS response. The same key is bound to the access token in the "cnf" claim. The Client can upload thetokentoken, as specified in <xreftarget="app-authzinfo"></xref>target="app-authzinfo" format="default"/>, before initiating the handshake. When using a previously uploaded token, the ClientMUST<bcp14>MUST</bcp14> indicate during the handshake which previously uploaded access token it intends to use. To do so, itMUST<bcp14>MUST</bcp14> create a "COSE_Key" or "JWK" structure with the "kid" that was conveyed in the "rs_cnf" claim in the token response from the AS and the key type "symmetric". This structure is then included as the only element in the "cnf" structure and the encoded value of that "cnf" structure used as a PSK identity in TLS. As an alternative to the access token upload, the Client can provide the most recent access token, JWT or CWT, as a PSK identity. </t> <t> In contrast to the <xreftarget="I-D.ietf-ace-dtls-authorize">DTLStarget="RFC9202" format="default">DTLS profile for ACE</xref>, a ClientMAY<bcp14>MAY</bcp14> omit support for the cipher suites TLS_PSK_WITH_AES_128_CCM_8 and TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8. For TLS 1.2, however, a clientMUST<bcp14>MUST</bcp14> support TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256 forPSK (<xref target="RFC8442"></xref>)PSKs <xref target="RFC8442" format="default"/> and TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 forRPK (<xref target="RFC8422"></xref>),RPKs <xref target="RFC8422" format="default"/>, as recommended in <xreftarget="RFC7525"></xref>target="RFC9325" format="default"/> (and adjusted to be a PSK cipher suite as appropriate). </t> </section> </section> <section anchor="auth-ACE"title="Clientnumbered="true" toc="default"> <name>Client Authentication overMQTT">MQTT</name> <section anchor="token-CONNECT"title="Transportingnumbered="true" toc="default"> <name>Transporting the Access TokenInsideinside the MQTTCONNECT">CONNECT</name> <t> This section describes how the Client transports the token to the Broker inside the CONNECT packet. If this method is used, the Client TLS connection is expected to be anonymous, and the Broker is authenticated during the TLS connection setup. The approach described in this section is similar to an earlier proposal by Fremantle, et al. <xreftarget="fremantle14"></xref>.target="Fremantle14" format="default"/>. </t> <t> After sending theCONNECT,CONNECT packet, the ClientMUST<bcp14>MUST</bcp14> wait to receive the CONNACK packet from the Broker. The only packets it is allowed to send are DISCONNECT or AUTH thatisare in response to the Broker AUTH. Similarly, except for a DISCONNECT and AUTH response from the Client, the BrokerMUST NOT<bcp14>MUST NOT</bcp14> process any packets before sending aCONNACK.CONNACK packet. </t> <t> <xreftarget="mqtt5_connect_message"></xref>target="mqtt5_connect_message" format="default"/> shows the structure of the MQTT CONNECT packet used in MQTT v5.0. A CONNECT packet is composed of afixed header,Fixed Header, avariable header,Variable Header, and apayload.Payload Thefixed headerFixed Header contains the Control Packet Type (CPT), Reserved, and Remaining Length fields. 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 Variable Header contains the Protocol Name, Protocol Level, ConnectFlags,flags, Keep Alive, and Properties fields. The ConnectFlagsflags in thevariable headerVariable Header specify the properties of the MQTTsession.Session. It also indicates the presence or absence of some fields in the Payload. ThepayloadPayload contains one or more encoded fields, namely a unique Client Identifier for the Client, a Will Topic, Will Payload, User Name, and Password. All but the Client Identifier can be omitted depending on the flags in the Variable Header. The Client Identifier identifies the Client to theBroker, andBroker and, therefore, is unique for each Client. It must be noted that the Client Identifier is an unauthenticated identifier used within the MQTT protocol and so is not bound to the access token. </t> <figurealign="center" anchor="mqtt5_connect_message" title="MQTTanchor="mqtt5_connect_message"> <name>MQTT v5 CONNECT Variable Header with Authentication Method Property forACE">ACE</name> <artworkalign="left"><![CDATA[align="center" name="" type="" alt=""><![CDATA[ 0 8 16 +---------------------------+ |Protocol name length = 4 | +---------------------------+ | 'M' 'Q' | +---------------------------+ | 'T' 'T' | +---------------------------+ |Proto.level=5|Connect flags| +---------------------------+ | Keep alive | +---------------------------+ | CONNECT Properties Length | |(Upto(up to 4 bytes) | +---------------------------+ | ( ..Other properties..) | +---------------------------+ | Authentication Method | | (0x15) |Len.Len | | Len | 'a' | | 'c' | 'e' | +---------------------------+ | Authentication Data | | (0x16) | Len | | Len | token | | or token + PoP data | +---------------------------+ ]]></artwork> </figure> <t> The CONNECT flags areUsername,User Name, Password, Willretain,Retain, Will QoS, Will Flag, Clean Start, and Reserved. <xreftarget="mqttv5_connect_flags"></xref>target="mqttv5_connect_flags" format="default"/> shows how the flagsMUST<bcp14>MUST</bcp14> be set to use AUTH packets for authentication and authorization, i.e., theusernameUser Name Flag andpassword flags MUSTPassword Flag <bcp14>MUST</bcp14> be set to 0. An MQTT v5.0 BrokerMAY<bcp14>MAY</bcp14> also support token transport usingUsernamethe User Name and Password to provide a security option for MQTT v3.1.1 Clients, as described in <xreftarget="MQTTv311"></xref>.target="MQTTv311" format="default"/>. </t><figure align="center"<table anchor="mqttv5_connect_flags"title="CONNECTalign="center"> <name>CONNECT Flags forAUTH"> <artwork align="left"><![CDATA[ +-----------------------------------------------------------+ |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| | Flag |Flag | | | |Start| | +-----------------------------------------------------------+ | 0 | 0 | X | X X | X | X | 0 | +-----------------------------------------------------------+ ]]></artwork> </figure>AUTH</name> <thead> <tr> <th>User Name Flag</th> <th>Password Flag</th> <th>Will Retain</th> <th>Will QoS</th> <th>Will Flag</th> <th>Clean Start</th> <th>Reserved</th> </tr> </thead> <tbody> <tr> <td align="center">0</td> <td align="center">0</td> <td align="center">X</td> <td align="center">X X</td> <td align="center">X</td> <td align="center">X</td> <td align="center">0</td> </tr> </tbody> </table> <t> The Will Flag indicates that a WillmessageMessage needs to be sent. The ClientMAY<bcp14>MAY</bcp14> set the Will Flag as desired (marked as "X" in <xreftarget="mqttv5_connect_flags"></xref>).target="mqttv5_connect_flags" format="default"/>). If the Will Flag is set to 1, the BrokerMUST<bcp14>MUST</bcp14> check that the token allows the publication of the WillmessageMessage (i.e., the Will TopicfilterFilter is in the scope array). The check is performed against the token scope described in <xreftarget="scope"></xref>.target="scope" format="default"/>. If the Will authorization fails, the connection isrefusedrefused, as described in <xreftarget="as_discovery"></xref>.target="as_discovery" format="default"/>. If the Broker accepts the connection request, the Broker stores the WillmessageMessage and publishes it when the Network Connection is closed according to Will QoS,andWillretain parametersRetain parameters, and MQTT Will management rules. To avoid publishing the Will Messages in the case of temporary network disconnections, the Client specifies a Will Delay Interval in the Will Properties. <xreftarget="disconnections"></xref>target="disconnections" format="default"/> explains how the Broker deals with the retained messages in further detail. </t> <t> In MQTT v5.0, the Client signals aclean sessionnew Session (i.e., that thesessionSession does not continue an existingsession)Session) by setting the Clean StartFlagflag to 1 in the CONNECT packet. In this profile, the ClientSHOULD<bcp14>SHOULD</bcp14> always start with aclean session.new Session. The BrokerMAY<bcp14>MAY</bcp14> also signal that it does not supportsessionthe continuation of an existing Session by setting the Session Expiry Interval to 0 in the CONNACK. If the Broker starts aclean session,new Session, the BrokerMUST<bcp14>MUST</bcp14> set the Session Present flag to 0 in the CONNACK packet to signal this to the Client. </t> <t> The BrokerMAY<bcp14>MAY</bcp14> supportsession continuation,continuing an existing Session, e.g., if the Broker requires it for QoS reasons. In this case, if a CONNECT packet is received with Clean Start set to00, and there is a Session associated with the Client Identifier, the BrokerMUST<bcp14>MUST</bcp14> resume communications with the Client based on the state from the existing Session. In its response, the BrokerMUST<bcp14>MUST</bcp14> set the Session Present flag to 1 in the CONNACK packet to signalsessionthe continuation of an existing Session to the Client. Thesession stateSession State stored by the Client and the Broker is described in <xreftarget="disconnections"></xref>.target="disconnections" format="default"/>. </t> <t> When reconnecting to a Broker that supportssession continuation,continuing existing Sessions, the ClientMUST<bcp14>MUST</bcp14> still provide atoken,token in addition to using the same Client Identifier and setting the Clean Start to 0. The BrokerMUST<bcp14>MUST</bcp14> still perform PoP validation on the provided token. If the token matches the stored state, the BrokerMAY<bcp14>MAY</bcp14> skip introspecting a token-by-reference and use the stored introspection result. The BrokerMUST<bcp14>MUST</bcp14> also verify the Client is authorized to receive or send MQTT packets that are pending transmission. When a Client connects with a long Session Expiry Interval, the Broker may need to maintain the Client's MQTTsession stateSession State after it disconnects for an extended period. BrokersSHOULD<bcp14>SHOULD</bcp14> implement administrative policies to limit misuse. </t> <t> Note that, according to the MQTT standard, the Broker uses the Client Identifier to identify thesession state.Session State. In the case of a Client Identifier collision, a Client may take over another Client'ssession.Session. Given that the BrokerMUST<bcp14>MUST</bcp14> associate the Client with a valid token, a Client will only send or receive messages to its authorized topics. Therefore, while this issue is not expected to affect security, it may affect QoS (i.e., PUBLISH or QoS messages saved for Client A may be delivered to a Client B). In addition, if this Client Identifier represents a Client already connected to the Broker, the Broker sends a DISCONNECT packet to the existing Client withReason Code ofreason code 0x8E (Session taken over) and closes the connection to the Client. </t> </section> <section anchor="AUTH-method"title="Authenticationnumbered="true" toc="default"> <name>Authentication Using the AUTHProperty"> <t> To use AUTH,Property</name> <t><xref target="mqtt5_connect_message"/> shows the Authentication Method and Authentication Data fields when the client authenticates using the AUTH property. The ClientMUST<bcp14>MUST</bcp14> set the Authentication Method as a property of a CONNECT packet by using the property identifier 21 (0x15). This is followed by aUTF-8 Encoded StringUTF-8-encoded string containing the name of the Authentication Method, whichMUST<bcp14>MUST</bcp14> be set to "ace". If the Broker does not support this profile, it sends a CONNACK packet witha Reason Code ofreason code 0x8C (Bad authentication method). </t> <t> The Authentication Method is followed by the Authentication Data, which has a property identifier 22 (0x16) and is Binary Data. Based on the Authentication Data, the BrokerMUST<bcp14>MUST</bcp14> support both options below:<list style="symbols"> <t>Proof-of-Possession</t> <ul spacing="normal"> <li>proof of possession using a challenge from the TLSsession</t> <t>Proof-of-Possessionsession</li> <li>proof of possession via a Broker-generatedchallenge/response</t> </list> </t>challenge/response</li> </ul> <sectiontitle="Proof-of-Possessionanchor="pop_nonce" numbered="true" toc="default"> <name>Proof of Possession Using a Challenge from the TLSsession" anchor="pop_nonce">Session</name> <figurealign="center" anchor="authdata_tlsexporter" title="Authenticationanchor="authdata_tlsexporter"> <name>Authentication Data for PoP Based on TLS ExporterContent">Content</name> <artworkalign="left"><![CDATA[align="left" name="" type="" alt=""><![CDATA[ +-----------------------------------------------------------------+ |Authentication|Token Length|Token |MAC or Signature | |Data Length | | |(over TLS exporter content) | +-----------------------------------------------------------------+ ]]></artwork> </figure> <t> For this option, the Authentication Data inside the Client's CONNECTMUSTpacket <bcp14>MUST</bcp14> contain the two-byte integer token length, the token, and the keyed message digest (MAC) or the Client signature (as shown in <xreftarget="authdata_tlsexporter"></xref>).target="authdata_tlsexporter" format="default"/>). The Proof-of-Possession key in the token is used to calculate the keyed message digest (MAC) or the Client signature based on the content obtained from the TLS exporter (<xreftarget="RFC5705"></xref>target="RFC5705" format="default"/> for TLS1.2,1.2 andSection 7.5 of<xreftarget="RFC8446"></xref>)target="RFC8446" section="7.5" sectionFormat="of" format="default"/> for TLS1.3.1.3). This content is exported from the TLS session using the exporter label "EXPORTER-ACE-MQTT-Sign-Challenge", an empty context, and a length of 32 bytes. The token is alsovalidatedvalidated, as described in <xreftarget="token_validation"></xref>,target="token_validation" format="default"/>, and the Broker responds with a CONNACK packet with the appropriate response code. The Client cannot reauthenticate using this method during the same TLS session (see <xreftarget="reauthentication"></xref>).target="reauthentication" format="default"/>). </t> </section> <sectiontitle="Proof-of-Possessionanchor="pop_challenge" numbered="true" toc="default"> <name>Proof of Possession via Broker-generatedChallenge/Response" anchor="pop_challenge">Challenge/Response</name> <figurealign="center" anchor="authdata_challenge_client" title="Authenticationanchor="authdata_challenge_client"> <name>Authentication Data to Initiate PoP Based onChallenge/Response">Challenge/Response</name> <artworkalign="left"><![CDATA[align="left" name="" type="" alt=""><![CDATA[ +------------------------------------+ |Authentication|Token Length|Token | |Data Length | | | +------------------------------------+ ]]></artwork> </figure> <figurealign="center" anchor="authdata_challenge_broker_challenge" title="Authenticationanchor="authdata_challenge_broker_challenge"> <name>Authentication Data for BrokerChallenge">Challenge</name> <artworkalign="left"><![CDATA[align="left" name="" type="" alt=""><![CDATA[ +--------------------------+ |Authentication|RS Nonce | |Data Length |(8 bytes) | +--------------------------+ ]]></artwork> </figure> <t> For this option, the Broker follows a Broker-generated challenge/response protocol. If the Authentication Data inside the Client's CONNECT contains only the two-byte integer token length and the token (as shown in <xreftarget="authdata_challenge_client"></xref>),target="authdata_challenge_client" format="default"/>), the BrokerMUST<bcp14>MUST</bcp14> respond with an AUTHpacket,packet with theAuthenticate Reason Codeauthenticated reason code set to 0x18 (Continue Authentication). The Broker also uses this method if the Authentication Data does not contain a token, but the Broker has a token stored for the connecting Client. </t> <t> The Broker continues authentication using an AUTH packet that contains the Authentication Method and the Authentication Data. The Authentication MethodMUST<bcp14>MUST</bcp14> be set to "ace", and the Authentication DataMUST NOT<bcp14>MUST NOT</bcp14> be empty andMUST<bcp14>MUST</bcp14> contain an 8-byte RS nonce as a challenge for the Client (<xreftarget="authdata_challenge_broker_challenge"></xref>).target="authdata_challenge_broker_challenge" format="default"/>). </t> <figurealign="center" anchor="authdata_challenge_client_response" title="Authenticationanchor="authdata_challenge_client_response"> <name>Authentication Data for the Client ChallengeResponse">Response</name> <artworkalign="left"><![CDATA[align="left" name="" type="" alt=""><![CDATA[ +---------------------------------------------------------+ |Authentication|Client Nonce |MAC or Signature | |Data Length |(8 bytes) |(over RS nonce+Client nonce)| +---------------------------------------------------------+ ]]></artwork> </figure> <t> The Client responds to this with an AUTH packet withareason code 0x18 (Continue Authentication). Similarly, the Client packet sets the Authentication Method to "ace". The Authentication Data in the Client's response is formatted as shown in <xreftarget="authdata_challenge_client_response"></xref>target="authdata_challenge_client_response" format="default"/> and includes the 8-byte Clientnonce,nonce and the signature or MAC computed over the RS nonce concatenated with the Client nonce using PoP key in the token. </t> <t> Next, the token is validated as described in <xreftarget="token_validation"></xref>.target="token_validation" format="default"/>. The success case is illustrated in <xreftarget="pop_challenge_response"></xref>.target="pop_challenge_response" format="default"/>. The ClientMAY<bcp14>MAY</bcp14> alsore-authenticatereauthenticate using this challenge-response flow, as described in <xreftarget="reauthentication"></xref>.target="reauthentication" format="default"/>. </t> <figurealign="center" anchor="pop_challenge_response" title="PoPanchor="pop_challenge_response"> <name>PoP Challenge/Response Flow -Success">Success</name> <artworkalign="left"><![CDATA[align="center" name="" type="" alt=""><![CDATA[ Client Broker | | |<===========>| TLS connection setup | | | | +------------>| CONNECT with Authentication Data | | contains only token | | <-------------+ AUTH 0x18 (Cont. Authentication) | | 8-byte RS nonce as challenge | | |------------>| AUTH 0x18 (Cont. Authentication) | | 8-byte Client nonce + signature/MAC | | | |---+ Token validation | | | (may involve introspection) | |<--+ | | |<------------+ CONNACK 0x00 (Success) ]]></artwork> </figure> </section> </section> </section> <sectiontitle="Brokeranchor="token_validation" numbered="true" toc="default"> <name>Broker TokenValidation" anchor="token_validation">Validation</name> <t> The BrokerMUST<bcp14>MUST</bcp14> verify the validity of the token either locally (e.g., in the case of a self-contained token) orMAY<bcp14>MAY</bcp14> send a request to the introspection endpoint of the AS (as described for HTTP-based interactions inSection 5.9 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="5.9">the ACE framework</xref>). The BrokerMUST<bcp14>MUST</bcp14> verify the claims in the access token according to the rules set inSection 5.10.1.1 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="5.10.1.1">the ACE framework</xref>. </t> <t> To authenticate the Client, the Broker validates the signature or the MAC, depending on how the PoP protocol is implemented. For self-contained tokens, the BrokerMUST<bcp14>MUST</bcp14> process the security protection of the token first, as specified by the respective token format,i.e.i.e., a CWTtokenuses COSE, while a JWTtokenuses JOSE. For a token-by-reference, the Broker uses the "cnf" structure returned as a result of tokenintrospectionintrospection, as specified in <xreftarget="RFC7519"></xref>. HS256 (HMAC-SHA-256)target="RFC7519" format="default"/>. HMAC-SHA-256 (HS256) <xreftarget="RFC6234"></xref>target="RFC6234" format="default"/> and Ed25519 <xreftarget="RFC8032"></xref>target="RFC8032" format="default"/> are mandatory to implement for the Broker. The ClientMUST<bcp14>MUST</bcp14> implement at least one of them depending on the choice of symmetric or asymmetric validation. Validation of the signature or MACMUST<bcp14>MUST</bcp14> fail if the signature algorithm is set to"none","none" when the key used for the signature algorithm cannot bedetermined,determined or the computed and received signature/MAC do not match. </t> <t> The BrokerMUST<bcp14>MUST</bcp14> check if the access token is still valid, if it is the intended destination (i.e., the audience) of the token, and if the token was issued by an authorizedauthorization server.Authorization Server. If the Client is using TLS RPK mode to authenticate to the Broker, the AS constructs the access token so that the Broker can associate the access token with the Client's public key. The "cnf" claimMUST<bcp14>MUST</bcp14> contain either the Client's RPK or, if the key is already known by the Broker (e.g., from previous communication), a reference to it. </t> </section> </section> <sectiontitle="Tokenanchor="scope" numbered="true" toc="default"> <name>Token Scope andAuthorization" anchor="scope">Authorization</name> <t> The scope field contains the publish and subscribe permissions for the Client. Therefore, the token or its introspection resultMUST<bcp14>MUST</bcp14> be cached to allow a Client's future PUBLISH and SUBSCRIBE messages. During the CONNECT, if the Will Flag is set to 1, the BrokerMUST<bcp14>MUST</bcp14> also authorize the publication of the Will Topic andmessageWill Message using the token's scope field. The Broker uses the scope to match against the Topic Name in a PUBLISH packet (including Will Topic in the CONNECT) or a Topic Filter in a SUBSCRIBE packet. </t> <t> The scope in the token is a single value. For a JWT, the single scope isbase64url encodeda base64url-encoded string with any padding characters removed, which has an internal structure of a JSON array. For a CWT, this information is represented in CBOR. The internal structure follows the <xreftarget="I-D.ietf-ace-aif">Authorizationtarget="RFC9237" format="default">Authorization Information Format (AIF) for ACE</xref>. Using the Concise Data Definition Language (CDDL) <xreftarget="RFC8610"></xref>,target="RFC8610" format="default"/>, the specific data model for MQTT is: </t> <figureanchor="MQTTaif" align="left" title="AIF-MQTT data model"> <artwork type="CDDL" name="" align="left" alt=""><![CDATA[anchor="MQTTaif"> <name>AIF-MQTT Data Model</name> <sourcecode type="cddl"><![CDATA[ AIF-MQTT = AIF-Generic<mqtt-topic-filter, mqtt-permissions> AIF-Generic<Toid, Tperm> = [* [Toid, Tperm]] mqtt-topic-filter = tstr ; as per Section 4.7 of MQTT v5.0 mqtt-permissions = [+permission] permission = "pub"/"sub"]]></artwork>]]></sourcecode> </figure> <t> TopicfiltersFilters are implemented according to Section 4.7 of the <xreftarget="MQTT-OASIS-Standard-v5">MQTTtarget="MQTT-OASIS-Standard-v5" format="default">MQTT v5.0- theOASIS Standard</xref>. By default, Wildcard Subscriptions are supported, and so, thetopic filterTopic Filter may include special wildcard characters. The multi-level wildcard, "#", matches any number of levels within a topic, and the single-level wildcard, "+", matches one topic level. The BrokerMAY<bcp14>MAY</bcp14> signal in the CONNACK explicitly whetherwildcard subscriptionsWildcard Subscriptions are supported by returning a CONNACK property "Wildcard Subscription Available". A value of 0 means that Wildcard Subscriptions are not supported. A value of 1 means Wildcard Subscriptions are supported. </t> <t> Following this model, an example scope may contain: </t> <figureanchor="MQTTaifex" align="left" title="Example scope"> <artwork type="" name="" align="left" alt=""><![CDATA[anchor="MQTTaifex"> <name>Example Scope</name> <sourcecode type="json"><![CDATA[ [["topic1",["pub","sub"]],["topic2/#",["pub"]],["+/topic3",["sub"]]]]]></artwork>]]></sourcecode> </figure> <t> This access token gives publish ("pub") and subscribe ("sub") permissions to the "topic1", publish permission to all the subtopics of "topic2", and subscribe permission to all "topic3", skipping one level. </t> <t> If the scope is empty, the Broker records no permissions for the Client for any topic. In this case, the Client is not able to publish or subscribe to any protected topics. The non-empty scope is used to authorize the Will Topic, if provided, in the CONNECT packet, during connectionsetup, andsetup and, if the connection request succeeds, the Topic Names or Topic Filters requested in the future PUBLISH and SUBSCRIBE packets. For the authorization to succeed, the BrokerMUST<bcp14>MUST</bcp14> verify that thetopic nameTopic Name orfilterTopic Filter in question is either an exact match to or a subset of at least one "topic_filter" in the scope. </t> </section> <sectiontitle="Brokernumbered="true" toc="default"> <name>Broker Response to Client ConnectionRequest">Request</name> <t> Based on the validation result (obtained either via local inspection or using the introspection interface of the AS), the BrokerMUST<bcp14>MUST</bcp14> send a CONNACK packet to the Client. </t> <sectiontitle="Unauthorizedanchor="as_discovery" numbered="true" toc="default"> <name>Unauthorized Request and the Optional Authorization ServerDiscovery" anchor="as_discovery">Discovery</name> <t> Authentication can fail for the following reasons:<list style="symbols"> <t> If</t> <ul spacing="normal"> <li>if the Client does not provide a validtoken,</t> <t> thetoken,</li> <li>the Client omits the Authentication Data field and the Broker has no token stored for theClient,</t> <t> theClient,</li> <li>the token or Authentication data are malformed, or</t> <t> if</li> <li>if the WillflagFlag is set, the authorization checks for the Willtopic fails.</t> </list>Topic fails.</li> </ul> <t> The Broker responds with the CONNACK reason code 0x87 (Not Authorized) or any other applicable reason code. </t> <t> The BrokerMAY<bcp14>MAY</bcp14> also trigger AS discovery and include a User Property (identified as property type 38 (0x26)) in the CONNACK for the AS Request Creation Hints. The User Property is a UTF-8 string pair, composed of a name and a value. The name of the User PropertyMUST<bcp14>MUST</bcp14> be set to "ace_as_hint". The value of theuser propertyUser Property is aUTF-8 encodedUTF-8-encoded JSON object containing the mandatory "AS"parameter,parameter and the optional parameters "audience", "kid", "cnonce", and"scope""scope", as defined inSection 5.3 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="5.3">the ACE framework</xref>. </t> </section> <sectiontitle="Authorization Success" anchor="auth_success">anchor="auth_success" numbered="true" toc="default"> <name>Authorization Success</name> <t> On success, the reason code of the CONNACK is 0x00 (Success). If the Broker starts a newsession,Session, itMUST<bcp14>MUST</bcp14> also set Session Present to 0 in the CONNACK packet to signal aclean sessionnew Session to the Client. Otherwise, itMUST<bcp14>MUST</bcp14> set Session Present to 1. </t> <t> Having accepted the connection, the BrokerMUST<bcp14>MUST</bcp14> be prepared to store the token during the connection and after disconnection for future use. If the token is not self-contained and the Broker uses token introspection, itMAY<bcp14>MAY</bcp14> cache the validation result to authorize the subsequent PUBLISH and SUBSCRIBE packets. PUBLISH and SUBSCRIBE packets, which are sent after a connection setup, do not contain access tokens. If the introspection result is not cached, the Broker needs to introspect the saved token for each request. The BrokerSHOULD<bcp14>SHOULD</bcp14> also use a cache timeout to introspect tokens regularly. The timeout value isapplication-specificspecific to the application and should be chosen to reduce the risk of using stale introspection responses. </t> </section> </section> </section> <sectiontitle="Authorizinganchor="pubsub_authorization" numbered="true" toc="default"> <name>Authorizing PUBLISH and SUBSCRIBEPackets" anchor="pubsub_authorisation">Packets</name> <t> Using the cached token or its introspection result, the Broker uses the scope field to match against the Topic Name in a PUBLISHpacket,packet or a Topic Filter in a SUBSCRIBE packet. </t> <sectiontitle="PUBLISHanchor="publish-packets" numbered="true" toc="default"> <name>PUBLISH Packets from the Publisher Client to theBroker">Broker</name> <t> On receiving the PUBLISH packet, the BrokerMUST<bcp14>MUST</bcp14> use the type of packet (i.e., PUBLISH) and the TopicnameName in the packet header to match against the scope array items in the cached token or its introspection result. Following the example in <xreftarget="scope"></xref>,target="scope" format="default"/>, the Client sending a PUBLISH packet for "topic2/a" would be allowed, as the scope array includes the ["topic2/#",["pub"]]. </t> <t> If the Client is allowed to publish to the topic, the Broker publishes the message to all valid subscribers of the topic. In the case of an authorization failure, the BrokerMUST<bcp14>MUST</bcp14> return an error if the Client has set the QoS level of the PUBLISH packet to greater than or equal to 1. Depending on the QoS level, the Broker responds with either a PUBACK or PUBREC packet with reason code 0x87 (Not authorized). On receiving an acknowledgment with 0x87 (Not authorized), the ClientMAY<bcp14>MAY</bcp14> reauthenticate by providing a newtokentoken, as described in <xreftarget="reauthentication"></xref>.target="reauthentication" format="default"/>. </t> <t> For QoS level 0, the Broker sends a DISCONNECT packet with reason code 0x87 (Not authorized) and closes the Network Connection. Note that the server-side DISCONNECT is a new feature of MQTT v5.0 (in MQTT v3.1.1, the server needs to drop the connection). </t> <t> For all QoS levels, the BrokerMAY<bcp14>MAY</bcp14> return 0x80Unspecified error(Unspecified error) if they do not want to leak thetopic namesTopic Names to unauthorized clients. </t> </section> <sectiontitle="PUBLISHnumbered="true" toc="default"> <name>PUBLISH Packets from the Broker to the SubscriberClients">Clients</name> <t> To forward PUBLISH packets to the subscribing Clients, the Broker identifies all the subscribers that have valid matchingtopic subscriptionsTopic Subscriptions to the TopicnameName of the PUBLISH packet (i.e., the tokens are valid, and token scopes allow asubscriptionSubscription to this particular Topicname).Name). The Broker forwards the PUBLISH packet to all the valid subscribers. </t> <t> The BrokerMUST NOT<bcp14>MUST NOT</bcp14> forward messages to unauthorized subscribers. To avoid silently dropping messages, the BrokerMUST<bcp14>MUST</bcp14> close thenetwork connectionNetwork Connection andSHOULD<bcp14>SHOULD</bcp14> inform the affected subscribers.TheIn this case, the only way to inform aclient, in this case,client would be sending a DISCONNECT packet. Therefore, the BrokerSHOULD<bcp14>SHOULD</bcp14> send a DISCONNECT packet withthereason code 0x87 (Not authorized) before closing thenetwork connectionNetwork Connection to these clients. </t> </section> <sectiontitle="Authorizingnumbered="true" toc="default"> <name>Authorizing SUBSCRIBEPackets">Packets</name> <t> In MQTT, a SUBSCRIBE packet is sent from a Client to the Broker to create one or moresubscriptionsSubscriptions to one or more topics. The SUBSCRIBE packet may contain multiple Topic Filters. The Topic Filters may include wildcard characters. </t> <t> On receiving the SUBSCRIBE packet, the BrokerMUST<bcp14>MUST</bcp14> use the type of packet (i.e., SUBSCRIBE) and the Topic Filter in the packet header to match against the scope field of the stored token or introspection result. The Topic FiltersMUST<bcp14>MUST</bcp14> be an exact match to or be a subset of at least one of the "topic_filter" fields in the scope array found in the Client's token. For example, if the Client sends asubscriptionSUBSCRIBE request for topic"a/b/*","a/b/*" and has a token that permits "a/*", this is a validsubscriptionSUBSCRIBE request, as "a/b/*" is a subset of "a/*". (The process is similar to a Broker matching the Topic Name in a PUBLISH packet against the Subscriptions known to the Server.) </t> <t> As a response to the SUBSCRIBE packet, the Broker issues aSUBACK.SUBACK packet. For each Topic Filter, the SUBACK packet includes a return code matching the QoS level for the corresponding Topic Filter. In the case of failure, the return code is 0x87, indicating that the Client is not authorized. The BrokerMAY<bcp14>MAY</bcp14> return 0x80Unspecified error(Unspecified error) if they do not want to leak thetopic namesTopic Names to unauthorized clients. A reason code is returned for each Topic Filter. Therefore, the Client may receive success codes for a subset of its Topic Filters while being unauthorized for the rest. </t> </section> </section> <section anchor="reauthentication"title="Tokennumbered="true" toc="default"> <name>Token Expiration, Update, andReauthentication">Reauthentication</name> <t> The BrokerMUST<bcp14>MUST</bcp14> check for token expiration whenever a CONNECT, PUBLISH, or SUBSCRIBE packet is received or sent. The BrokerSHOULD<bcp14>SHOULD</bcp14> check for token expiration on receiving aPINGREQUEST.PINGREQ packet. The BrokerMAY<bcp14>MAY</bcp14> also check for token expiration periodically, e.g., every hour. This may allow for early detection of a token expiry. </t> <t> The token expiration is checked by checking the "exp" claim of a JWT or introspection response or via performing an introspection request with theASAS, as described inSection 5.9 of the<xreftarget="I-D.ietf-ace-oauth-authz">ACEtarget="RFC9200" format="default" sectionFormat="of" section="5.9">the ACE framework</xref>. Token expirations may trigger the Broker to send PUBACK,SUBACKSUBACK, and DISCONNECT packets with the return code set to "Not authorized". After sending aDISCONNECT,DISCONNECT packet, the Network Connection is closed, and no more messages can be sent. </t> <t> The ClientMAY<bcp14>MAY</bcp14> reauthenticateasa response tothePUBACK andSUBACK thatSUBACK, which signal loss of authorization. The ClientsMAY<bcp14>MAY</bcp14> also proactively update their tokens, i.e., before they receive a packet with a "Not authorized" return code. To start reauthentication, the ClientMUST<bcp14>MUST</bcp14> send an AUTH packet withthereason code 0x19(Re-authentication).(Reauthentication). The ClientMUST<bcp14>MUST</bcp14> set the Authentication Method as "ace" and transport the new token in the Authentication Data. Ifre-authenticatingreauthenticating during the current TLS session, the ClientMUST NOT<bcp14>MUST NOT</bcp14> use the method described in <xreftarget ="pop_nonce"></xref>, Proof-of-Possessiontarget="pop_nonce" format="default"/>, i.e., proof of possession using a challenge from the TLS session, to avoidre-usingreusing the same challenge value from the TLS-Exporter. Note that this means that servers will either need to record in the session ticket or database entry whether the TLS-Exporter-derived challenge wasused,used or always deny use of the TLS-Exporter-derived challenge for resumed sessions. In TLS 1.3, the resumed connection would have a new exporter value, but the requirement is phrased this way for simplicity. Forre-authenticationsreauthentications in the same TLS-session, the ClientMUST<bcp14>MUST</bcp14> use the challenge-responsePoPPoP, as defined in <xreftarget="pop_challenge"></xref>.target="pop_challenge" format="default"/>. The Broker accepts reauthentication requests if the Client has already submitted a token (may be expired), for which it performedproof-of-possession.proof of possession. Otherwise, the BrokerMUST<bcp14>MUST</bcp14> deny the request. If the reauthentication fails, the BrokerMUST<bcp14>MUST</bcp14> send a DISCONNECT packet withthereason code 0x87 (Not Authorized). </t> </section> <sectiontitle="Handlinganchor="disconnections" numbered="true" toc="default"> <name>Handling Disconnections and RetainedMessages" anchor="disconnections">Messages</name> <t> In the case of a Client DISCONNECT, if the Session Expiry Interval is set to 0, the Broker doesn'tmaintain session statestore the Session State butMUST<bcp14>MUST</bcp14> keep the retained messages. If the Brokermaintains session state,stores the Session State, the stateMAY<bcp14>MAY</bcp14> include the token and its introspection result (for reference tokens) in addition to the MQTTsession state.Session State. The MQTTsession stateSession State is identified by the Client Identifier and includes the following:<list style="symbols"> <t>Client subscription state,</t><t> messages<ul spacing="normal"> <li>the Client Subscriptions, </li> <li>messages with QoS levels 1 and 2,andwhich have not been completely acknowledged or are pending transmission to the Client, and</t> <t> if</li> <li>if the Session is currently not connected, the time at which the Session will end and the Session State will bediscarded.</t> </list>discarded.</li> </ul> <t> The token/introspection state is not part of the MQTTsession state,Session State, and PoP validation is required for each new connection, regardless of whether existing MQTTsession continuation is used.Sessions are continued. </t> <t> The messages to be retained are indicated to the Broker by setting a RETAIN flag in a PUBLISH packet. This way, the publisher signals to the Broker to store the most recent message for the associated topic. Hence, the new subscribers can receive the last sent message from the publisher for that particular topic without waiting for the next PUBLISH packet. The BrokerMUST<bcp14>MUST</bcp14> continue publishing the retained messages as long as the associated tokens are valid. In the MQTT standard, if QoS is 0 for the PUBLISH packet, the Broker may discard the retained message any time. ForQoS>1,QoS > 1, the message expiry interval dictates how long the retained message is kept. However, it is important that the Broker avoids sending messages indefinitely for the Clients that never update their tokens (i.e., the Client connects briefly with a valid token, sends a PUBLISH packet with the RETAIN flag set to 1 andQoS>1,QoS > 1, disconnects, and never connects again). Therefore, the BrokerMUST<bcp14>MUST</bcp14> use the minimum of the token expiry and message expiry interval to discard a retained message. </t> <t> In case of disconnections due to network errors or server disconnection due to a protocol error (which includes authorization errors), the WillmessageMessage is sent if the Client supplied a Will in the CONNECT packet. The Client's token scope arrayMUST<bcp14>MUST</bcp14> include the Will Topic. The Willmessage MUSTMessage <bcp14>MUST</bcp14> be published to the WillTopicTopic, regardless of whether the corresponding token has expired (as it has been validated and accepted during CONNECT). </t> </section> <section anchor="MQTTv311"title="Reducednumbered="true" toc="default"> <name>Reduced Protocol Interactions for MQTTv3.1.1">v3.1.1</name> <t> This section describes a reduced set of protocol interactions for the MQTT v3.1.1 Clients. An MQTT v5.0 BrokerMAY<bcp14>MAY</bcp14> implement these interactions for the MQTT v3.1.1 Clients;Thethe flows described in this section areNOT RECOMMENDED<bcp14>NOT RECOMMENDED</bcp14> for use by MQTT v5.0 Clients. Brokers that do not support MQTT v3.1.1 Clients return a CONNACK packet withReason Codereason code 0x84 (Unsupported Protocol Version) in response to the connection requests. </t> <section anchor="token_311"title="Token Transport">numbered="true" toc="default"> <name>Token Transport</name> <t> As in MQTT v5.0, the tokenMAY<bcp14>MAY</bcp14> either be transported before, by publishing to the "authz-info" topic, or inside the CONNECT packet. If the Client provided the token via the "authz-info" topic and will not update the token in the CONNECT packet, itMUST<bcp14>MUST</bcp14> authenticate over TLS. The BrokerSHOULD<bcp14>SHOULD</bcp14> still be prepared to store the Client access token for future use (regardless of the method of transport). </t> <t>In MQTT v3.1.1, after the Client has published to the "authz-info" topic, the Broker cannot communicate the result of the token validation because PUBACK reason codes or server-side DISCONNECT packets are not supported. In any case, the subsequent TLS handshake would fail without a valid token, which can prompt the Client to obtain a valid token. </t> <t> To transport the token to the Broker inside the CONNECT packet, the Client uses theusernameUser Name andpasswordPassword fields. <xreftarget="mqtt_connect_message"></xref>target="mqtt_connect_message" format="default"/> shows the structure of the MQTT CONNECT packet. </t> <figurealign="center" anchor="mqtt_connect_message" title="MQTTanchor="mqtt_connect_message"> <name>MQTT CONNECT Variable Header UsingUsernamea User Name and Password forACE">ACE</name> <artworkalign="left"><![CDATA[align="center" name="" type="" alt=""><![CDATA[ 0 8 16 +---------------------------+ |Protocol name length = 4 | +---------------------------+ | 'M' 'Q' | +---------------------------+ | 'T' 'T' | +---------------------------+ |Proto.level=5|Connect flags| +---------------------------+ | Keep alive | +---------------------------+ | Payload | | Client Identifier | |(UTF-8 encoded(UTF-8-encoded string) | |UsernameUser Name as access token | |(UTF-8 encoded(UTF-8-encoded string) | | Password for signature/MAC| | (Binary Data) | +---------------------------+ ]]></artwork> </figure> <t> <xreftarget="mqtt_connect_flags"></xref>target="mqtt_connect_flags" format="default"/> shows how the MQTT connect flagsMUST<bcp14>MUST</bcp14> be set to initiate a connection with the Broker. </t><figure align="center" anchor="mqtt_connect_flags" title="MQTT<table anchor="mqtt_connect_flags"> <name>MQTT CONNECT Flags(Rsvd=Reserved)"> <artwork align="left"><![CDATA[ +-----------------------------------------------------------+ |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| | flag |flag | | | | | | +-----------------------------------------------------------+ | 1 | 1 | X | X X | X | X | 0 | +-----------------------------------------------------------+ ]]></artwork> </figure>(Rsvd. = Reserved)</name> <thead> <tr> <th>User Name Flag</th> <th>Password Flag</th> <th>Will Retain</th> <th>Will QoS</th> <th>Will Flag</th> <th>Clean</th> <th>Rsvd.</th> </tr> </thead> <tbody> <tr> <td align="center">1</td> <td align="center">1</td> <td align="center">X</td> <td align="center">X X</td> <td align="center">X</td> <td align="center">X</td> <td align="center">0</td> </tr> </tbody> </table> <t> The ClientSHOULD<bcp14>SHOULD</bcp14> set the Clean flag to 1 to always start a newsession.Session. If the Clean flag is set to 0, the BrokerMUST<bcp14>MUST</bcp14> resume communications with the Client based on the state from the current Session (as identified by the Client Identifier). If there is no Session associated with the Client Identifier, the BrokerMUST<bcp14>MUST</bcp14> create a newsession.Session. The BrokerMUST<bcp14>MUST</bcp14> set the Session Present flag in the CONNACK packet accordingly, i.e., 0 to indicate aclean sessionnew Session to the Client and 1 to indicatesession continuation.that the existing Session is continued. The BrokerMUST<bcp14>MUST</bcp14> still perform PoP validation on the provided Client token. MQTT v3.1.1 does not use a Session Expiry Interval, and the Client expects that the Broker maintains thesession stateSession State after it disconnects. However, the stored SessionstateState can be discarded as a result of administrator action or policies(e.g.(e.g., defining an automated response based on storage capabilities), and BrokersSHOULD<bcp14>SHOULD</bcp14> implement administrative policies to limit misuse. </t> <t> The ClientMAY<bcp14>MAY</bcp14> set the Will Flag as desired (marked as "X" in <xreftarget="mqtt_connect_flags"></xref>). Usernametarget="mqtt_connect_flags" format="default"/>). User Name and Password flagsMUST<bcp14>MUST</bcp14> be set to 1 to ensure that the Payload of the CONNECT packet includes bothUsernamethe User Name and Password fields. The MQTTUsernameUser Name is aUTF-8 encodedUTF-8-encoded string, and the MQTT Password is Binary Data. </t> <t> The CONNECT in MQTT v3.1.1 does not have a field to indicate theauthentication method.Authentication Method. To signal that theUsernameUser Name field contains an ACE token, this fieldMUST<bcp14>MUST</bcp14> be prefixed with"ace" keyword,the keyword "ace", i.e., theUsernameUser Name field is a concatenation of 'a', 'c','e''e', and the access token represented as: </t> <figureanchor="v31username" align="left" title="Usernameanchor="v31username"> <name>User Name inCONNECT">CONNECT</name> <artwork type="" name=""align="left"align="center" alt=""><![CDATA[ 'U+0061'||'U+0063'||'U+0065'||UTF-8(access token) ]]></artwork> </figure> <t> To this end, the access tokenMUST<bcp14>MUST</bcp14> bebase64url encoded,encoded with base64url, omitting the'='"=" padding characters <xreftarget="RFC4648"></xref>.target="RFC4648" format="default"/>. </t> <t> ThepasswordPassword fieldMUST<bcp14>MUST</bcp14> be set to the keyed message digest (MAC) or signature associated with the access token for PoP. The ClientMUST<bcp14>MUST</bcp14> apply the PoP key on the challenge derived from the TLSsessionsession, as described in <xreftarget="pop_nonce"></xref>.target="pop_nonce" format="default"/>. </t> </section> <section anchor="errors_311"title="Handlingnumbered="true" toc="default"> <name>Handling AuthorizationErrors">Errors</name> <t> Error handling is more primitive in MQTT v3.1.1 due to not having appropriate error fields, error codes, and server-side DISCONNECTs. Therefore, the Broker will disconnect on almost any error and may not keep thesession state,Session State, necessitating that clients make a greater effort to ensure that tokens remain valid and do not attempt to publish to topics that they do not have permissions for. The following lists how the Broker responds to specific errors. </t><t> <list style="symbols"> <t><dl newline="true" spacing="normal" indent="8"> <dt> CONNECT without atoken: Thetoken:</dt> <dd>The tokenless CONNECT attemptMUST<bcp14>MUST</bcp14> fail. This is because thechallenge-response basedchallenge-response-based PoP is not possible for MQTT v3.1.1. It is also not possible to support AS discovery since a CONNACK packet in MQTT v3.1.1 does not include a means to provide additional information to the Client. Therefore, AS discovery needs to take placeout-of-band. </t> <t>out of band. </dd> <dt> Client-Broker PUBLISH authorizationfailure: Infailure:</dt> <dd>In the case of a failure, it is not possible to return an error in MQTT v3.1.1. Acknowledgment messages only indicate success. In the case of an authorization error, the BrokerMUST<bcp14>MUST</bcp14> ignore the PUBLISH packet and disconnect the Client. Also, as DISCONNECT packets are only sent from a Client to the Broker, the server disconnection needs to take place below the application layer.</t> <t></dd> <dt> SUBSCRIBE authorizationfailure: Infailure:</dt> <dd>In the SUBACK packet, the return code is0x800x80, indicating failure for the unauthorized topic(s). Note that, in both MQTT versions, a reason code is returned for each Topic Filter.</t> <t>Broker-Client</dd> <dt>Broker-Client PUBLISH authorizationfailure: Whenfailure:</dt> <dd>When the Broker is forwarding PUBLISH packets to the subscribed Clients, it may discover that some of the subscribers are no longer authorized due to expired tokens. These token expirationsMUST<bcp14>MUST</bcp14> lead to disconnecting the Client rather than silently dropping messages.</t> </list> </t></dd> </dl> </section> </section><!-- This PI places the pagebreak correctly (before the section title) in the text output. --> <!--<?rfc needLines="8" ?>--> <!-- Possibly a 'Acknowledgments'/ 'Contributors' section ... --><section anchor="IANA"title="IANA Considerations"> <t> Note to RFC Editor: Please replace all occurrences of "[this document]" with the RFC number of this specification and delete this paragraph.</t>numbered="true" toc="default"> <name>IANA Considerations</name> <sectiontitle="TLSnumbered="true" toc="default"> <name>TLS ExporterLabel Registration">Labels Registration</name> <t> This document registers "EXPORTER-ACE-MQTT-Sign-Challenge" (introduced in <xreftarget="pop_nonce"></xref>target="pop_nonce" format="default"/> in this document) in theTLS"TLS ExporterLabel RegistryLabels" registry <xreftarget="RFC8447"></xref>. <list style="symbols"> <t>Recommended: No</t> <t>DTLS-OK: No</t> <t>Reference: [This document]</t> </list>target="RFC8447" format="default"/>. </t> <dl newline="false" spacing="normal"> <dt>Recommended:</dt> <dd>N</dd> <dt>DTLS-OK:</dt> <dd>N</dd> <dt>Reference:</dt> <dd>RFC 9431</dd> </dl> </section> <sectiontitle="Medianumbered="true" toc="default"> <name>Media TypeRegistration">Registration</name> <t>This document registers the "application/ace+json" media type for messages of the protocols defined in this document carrying parameters encoded in JSON.</t><t> <list style="symbols"> <t>Type name: application </t> <t>Subtype name: ace+json </t> <t>Required parameters: N/A </t> <t>Optional parameters: N/A </t> <t>Encoding considerations: Encoding<dl newline="false" spacing="normal"> <dt>Type name:</dt> <dd>application </dd> <dt>Subtype name:</dt> <dd>ace+json </dd> <dt>Required parameters:</dt> <dd>N/A </dd> <dt>Optional parameters:</dt> <dd>N/A </dd> <dt>Encoding considerations:</dt> <dd>Encoding considerations are identical to those specified for the "application/json" mediatype.</t> <t>Security considerations: Section 8type.</dd> <dt>Security considerations:</dt> <dd><xref target="Security" format="default"/> of[this document]</t> <t>Interoperability considerations: none </t> <t>Published specification: [this document]</t> <t>ApplicationsRFC 9431</dd> <dt>Interoperability considerations:</dt> <dd>none </dd> <dt>Published specification:</dt> <dd>RFC 9431</dd> <dt>Applications that use this mediatype: Thistype:</dt> <dd>This media type is intended forauthorization server-clientAuthorization-Server-Client andauthorization server-resource serverAuthorization-Server-Resource-Server communication as part of the ACE framework using JSONencodingencoding, as specified in[this document].</t> <t>FragmentRFC 9431.</dd> <dt>Fragment identifierconsiderations: none </t> <t>Additional information: <list style="symbols"> <t>Deprecatedconsiderations:</dt> <dd>none </dd> <dt>Additional information:</dt> <dd><t><br/></t> <dl newline="false" spacing="normal"> <dt>Deprecated alias names for thistype: none</t> <t>Magic number(s): none</t> <t>File extension(s): none</t> <t>Macintoshtype:</dt> <dd>none</dd> <dt>Magic number(s):</dt> <dd>none</dd> <dt>File extension(s):</dt> <dd>none</dd> <dt>Macintosh file typecode(s): none</t> </list> </t> <t>Personcode(s):</dt> <dd>none</dd> </dl> </dd> <dt>Person & email address to contact for furtherinformation: Cigdeminformation:</dt> <dd><t><br/>Cigdem Sengul(csengul@acm.org) </t> <t>Intended usage: COMMON</t> <t>Restrictions<csengul@acm.org></t></dd> <dt>Intended usage:</dt> <dd>COMMON</dd> <dt>Restrictions onusage: none</t> <t>Author: Cigdemusage:</dt> <dd>none</dd> <dt>Author:</dt> <dd>Cigdem Sengul(csengul@acm.org)</t> <t>Change controller: IETF </t> <t>Provisional registration? (standards tree only): no </t> </list></t><csengul@acm.org></dd> <dt>Change controller:</dt> <dd>IETF </dd> </dl> </section> <sectiontitle="ACEnumbered="true" toc="default"> <name>ACE OAuth ProfileRegistration">Registration</name> <t>The following registrationsare done forhave been made in theACE OAuth Profile Registry"ACE Profiles" registry, following the procedure specified in <xreftarget="I-D.ietf-ace-oauth-authz"></xref>.target="RFC9200" format="default"/>. </t><t> <list style="symbols"> <t>Name: mqtt_tls</t> <t>Description: Profile<dl newline="false" spacing="normal"> <dt>Name:</dt> <dd>mqtt_tls</dd> <dt>Description:</dt> <dd>Profile for delegating Client authentication and authorization using MQTT for the Client and Broker (RS)interactions,interactions and HTTP for the AS interactions. TLS is used for confidentiality and integrity protection and server authentication. Client authentication can be provided either via TLS or using in-band PoP validation at the MQTT application layer.</t> <t>CBOR Value: To be assigned by IANA in the (-256, 255) range</t> <t>Reference: [this document]</t> </list> </t></dd> <dt>CBOR Value:</dt> <dd>3</dd> <dt>Reference:</dt> <dd>RFC 9431</dd> </dl> </section> <sectiontitle="AIF">numbered="true" toc="default"> <name>AIF</name> <t>For themedia-types application/aif+cbormedia types "application/aif+cbor" andapplication/aif+json"application/aif+json", defined inSection 5.1 of<xreftarget="I-D.ietf-ace-aif"></xref>,target="RFC9237" section="5.1" sectionFormat="of" format="default"/>, IANAis requested to registerhas registered the following entries for the twomedia-typemedia type parameters Toid andTperm,Tperm in the respectivesub-registrysubregistry defined inSection 5.2 of<xreftarget="I-D.ietf-ace-aif"></xref>target="RFC9237" section="5.2" sectionFormat="of" format="default"/> within the"MIME Media"Media TypeSub-Parameter" registry group.Sub-Parameter Registries". </t><t> For Toid: <list style="symbols"> <t>Name: mqtt-topic-filter</t> <t>Description/Specification: Topic Filter<dl newline="true" spacing="normal"> <dt>For Toid:</dt> <dd> <dl newline="false" spacing="normal"> <dt>Name:</dt> <dd>mqtt-topic-filter</dd> <dt>Description/Specification:</dt> <dd>Topic Filter, as defined in <xreftarget="scope"></xref>.</t> <t>Reference: [[This document]] (<xref target="scope"></xref>)</t> </list> </t> <t>target="scope" format="default"/> of RFC 9431.</dd> <dt>Reference:</dt> <dd>RFC 9431, <xref target="scope" format="default"/></dd> </dl> </dd> <dt> ForTperm: <list style="symbols"> <t>Name: mqtt-permissions</t> <t>Description/Specification: PermissionsTperm:</dt> <dd> <dl newline="false" spacing="normal"> <dt>Name:</dt> <dd>mqtt-permissions</dd> <dt>Description/Specification:</dt> <dd>Permissions for the MQTTclientClient, as defined in <xreftarget="scope"></xref>.target="scope" format="default"/> of RFC 9431. Tperm is an array of one or more text strings that each have a value of either "pub" or"sub".</t> <t>Reference: [[This document]] (<xref target="scope"></xref>)</t> </list> </t>"sub".</dd> <dt>Reference:</dt> <dd>RFC 9431, <xref target="scope" format="default"/></dd> </dl> </dd></dl> </section> </section> <section anchor="Security"title="Security Considerations">numbered="true" toc="default"> <name>Security Considerations</name> <t> This document specifies a profile for the Authentication and Authorization for Constrained Environments (ACE) framework <xreftarget="I-D.ietf-ace-oauth-authz"></xref>.target="RFC9200" format="default"/>. Therefore, the security considerations outlined in <xreftarget="I-D.ietf-ace-oauth-authz"></xref>target="RFC9200" format="default"/> apply to this work. </t> <t> In addition, the security considerations outlined in the <xreftarget="MQTT-OASIS-Standard-v5">MQTTtarget="MQTT-OASIS-Standard-v5" format="default">MQTT v5.0- theOASIS Standard</xref> and <xreftarget="MQTT-OASIS-Standard-v3.1.1">MQTTtarget="MQTT-OASIS-Standard-v3.1.1" format="default">MQTT v3.1.1- theOASIS Standard</xref> apply. Mainly, this document provides an authorization solution for MQTT, the responsibility of which is left to the specific implementation in the MQTT standards. In the following, we comment on a few relevant issues based on the current MQTT specifications. </t> <t>After the Broker validates an access token and accepts a connection from a client, it caches the token to authorize a Client's publish and subscribe requests in an ongoingsession.Session. The Broker does not cache any tokens that cannot be validated. If a Client's permissions get revoked, but the access token has not expired, the Broker may still grant publish/subscribe to revoked topics. If the Broker caches the token introspection responses, then the BrokerSHOULD<bcp14>SHOULD</bcp14> use a reasonable cache timeout to introspect tokens regularly. The timeout value isapplication-specificapplication specific and should be chosen to reduce the risk of using stale introspection responses. When permissions change dynamically, it is expected that the AS also follows a reasonable expiration strategy for the access tokens. </t> <t> The Broker may monitor Clientbehaviourbehavior to detect potential security problems, especially those affecting availability. These include repeated token transfer attempts to the public "authz-info" topic, repeated connection attempts, abnormal terminations, and Clients that connect but do not send any data. If the Broker supports the public "authz-info" topic, described in <xreftarget="app-authzinfo"></xref>,target="app-authzinfo" format="default"/>, then this may be vulnerable to a DDoS attack, where many Clients use the "authz-info" public topic to transport tokens that are not meant to beused,used andwhichthat the Broker may need to store untilthe tokensthey expire.</t> <t>For MQTT v5.0, when a Client connects with a long Session Expiry Interval, the Broker may need to maintain the Client's MQTTsession stateSession State after it disconnects for an extended period. For MQTT v3.1.1, thesession stateSession State may need to be stored indefinitely, as it does not have a Session Expiry Interval feature. The BrokerSHOULD<bcp14>SHOULD</bcp14> implement administrative policies to limit misuseof the session continuationby theClient.Client resulting from continuing existing Sessions. </t> </section> <section anchor="Privacy"title="Privacy Considerations">numbered="true" toc="default"> <name>Privacy Considerations</name> <t>The privacy considerations outlined in <xreftarget="I-D.ietf-ace-oauth-authz"></xref>target="RFC9200" format="default"/> apply to this work. </t> <t>In MQTT, the Broker is a central trusted party and may forward potentially sensitive information between Clients. The mechanisms defined in this document do not protect the contents of the PUBLISH packet from the Broker, and hence, the content of the PUBLISH packet is not signed or encrypted separately for the subscribers. This functionality may be implemented using the proposal outlined in <xreftarget="I-D.ietf-ace-pubsub-profile">target="I-D.ietf-ace-pubsub-profile" format="default"> the ACE Pub-Sub Profile</xref>. However, this solution would still not provide privacy for other fields of the packet, such as Topic Name. </t> </section> </middle><!-- *****BACK MATTER ***** --><back><!-- References split into informative and normative --> <!-- There are 2 ways to insert reference entries from the citation libraries: 1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown) 2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here (for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml") Both are cited textually in the same manner: by using xref elements. If you use the PI option, xml2rfc will, by default, try to find included files in the same directory as the including file. You can also define the XML_LIBRARY environment variable with a value containing a set of directories to search. These can be either in the local filing system or remote ones accessed by http (http://domain/dir/... ).--> <references title="Normative References"> <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?--> &RFC2119; &RFC4648; &RFC8174; &RFC7250; &RFC8422; &RFC8442; &RFC8446; &RFC5705; &RFC6234; &RFC6749; &RFC7800; &RFC8747; &RFC8610; &RFC7519; &RFC7516; &RFC7517; &RFC8152; &RFC7627; &RFC6066; &RFC7301; &RFC8032;<displayreference target="I-D.ietf-tls-rfc8446bis" to="TLS-bis"/> <displayreference target="I-D.ietf-ace-pubsub-profile" to="ACE-PUBSUB-PROFILE"/> <references> <name>References</name> <references> <name>Normative References</name> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4648.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7250.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8422.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8442.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5705.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6234.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7800.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8747.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8610.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7516.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7517.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9052.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7627.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6066.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7301.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8032.xml"/> <reference anchor="MQTT-OASIS-Standard-v3.1.1" target="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html"> <front><title> OASIS Standard MQTT<title>MQTT Version 3.1.1 Plus Errata01 </title>01</title> <author initials="A." surname="Banks" role="editor"> <organization>IBM</organization> </author> <author initials="R." surname="Gupta" role="editor"> <organization>IBM</organization> </author> <dateyear="2015"/>year="2015" month="December"/> </front> <refcontent>OASIS Standard</refcontent> </reference> <reference anchor="MQTT-OASIS-Standard-v5"target="https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html">target="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html"> <front><title> OASIS Standard MQTT<title>MQTT Version5.0 </title>5.0</title> <author initials="A." surname="Banks" role="editor"> <organization>IBM</organization> </author> <author initials="E." surname="Briggs" role="editor"> <organization>Microsoft</organization> </author> <author initials="K." surname="Borgendale" role="editor"> <organization>IBM</organization> </author> <author initials="R." surname="Gupta" role="editor"> <organization>IBM</organization> </author> <dateyear="2017"/>year="2019" month="March"/> </front> <refcontent>OASIS Standard</refcontent> </reference><?rfc include="reference.I-D.ietf-ace-oauth-authz.xml"?> <?rfc include="reference.I-D.ietf-ace-oauth-params.xml"?> <?rfc include="reference.I-D.draft-ietf-cose-x509-08.xml"?> <?rfc include="reference.I-D.ietf-ace-aif-07.xml"?> <?rfc include="reference.I-D.ietf-ace-dtls-authorize.xml"?> <?rfc include="reference.I-D.ietf-ace-extend-dtls-authorize-02.xml"?> <?rfc include="reference.I-D.ietf-httpbis-semantics-19.xml"?> </references> <references title="Informative References"> <!-- Here we use entities that we defined at<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9200.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9201.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9360.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9237.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9202.xml"/> <reference anchor="RFC9430" target="https://www.rfc-editor.org/info/rfc9430"> <front> <title> Extension of thebeginning. --> <!-- A reference written by by an organization not a person. --> &RFC4949; &RFC7252; &RFC8949; &RFC8392; &RFC8447; &RFC7925; &RFC7525;Datagram Transport Layer Security (DTLS) Profile for Authentication and Authorization for Constrained Environments (ACE) to Transport Layer Security (TLS) </title> <author initials="O." surname="Bergmann" fullname="Olaf Bergmann"> <organization>Universität Bremen TZI</organization> </author> <author initials="J." surname="Preuß Mattsson" fullname="John Preuß Mattsson"> <organization>Ericsson AB</organization> </author> <author initials="G." surname="Selander" fullname="Göran Selander"> <organization>Ericsson AB</organization> </author> <date month="July" year="2023"/> </front> <seriesInfo name="RFC" value="9430"/> <seriesInfo name="DOI" value="10.17487/RFC9430"/> </reference> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9110.xml"/> </references> <references> <name>Informative References</name> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4949.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7252.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8949.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8392.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8447.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7925.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9325.xml"/> <referenceanchor="fremantle14"anchor="Fremantle14" target="https://dx.doi.org/10.1109/SIoT.2014.8"> <front><title> Federated<title>Federated Identity and Access Management for the Internet ofThings </title>Things</title> <author initials="P."surname="Fremantle"></author>surname="Fremantle"/> <author initials="B."surname="Aziz"></author>surname="Aziz"/> <author initials="J."surname="Kopecky"></author>surname="Kopecky"/> <author initials="P."surname="Scott"></author>surname="Scott"/> <date month="September"year="2014"></date>year="2014"/> </front> <seriesInfoname="research" value="Internationalname="DOI" value="10.1109/SIoT.2014.8"/> <refcontent>International Workshop on Secure Internet ofThings"></seriesInfo>Things</refcontent> </reference><?rfc include="reference.I-D.draft-ietf-tls-rfc8446bis-04.xml"?> <?rfc include="reference.I-D.draft-ietf-ace-pubsub-profile-04.xml"?><xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-tls-rfc8446bis.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-ace-pubsub-profile.xml"/> </references> </references> <section anchor="app-profile-requirements"title="Checklistnumbered="true" toc="default"> <name>Checklist forprofile requirements">Profile Requirements</name> <t> Based on the requirements on profiles for the ACE framework <xreftarget="I-D.ietf-ace-oauth-authz"></xref>,target="RFC9200" format="default"/>, this document fulfills the following:<list style="symbols"> <t>Optional</t> <ul spacing="normal"> <li>Optional AS discovery: AS discovery is supported with the MQTT v5.0 described in <xreftarget="connect_v5"></xref>.</t> <t>Thetarget="connect_v5" format="default"/>.</li> <li>The communication protocol between the Client and Broker (RS):MQTT</t> <t>TheMQTT</li> <li>The security protocol between the Client and RS:TLS</t> <t>ClientTLS</li> <li>Client and RS mutual authentication: Several options are possible and described in <xreftarget="auth_options"></xref>. </t> <t>target="auth_options" format="default"/>. </li> <li> Proof-of-possession protocols:Specified in <xref target="AUTH-method"></xref>; bothBoth symmetric and asymmetric keyssupported. </t> <t>Content format:are supported, as specified in <xref target="AUTH-method" format="default"/>. </li> <li>Content-Format: For the HTTPS interactions with AS, "application/ace+json".</t> <t>Unique</li> <li>Unique profile identifier:mqtt_tls</t> <t>Tokenmqtt_tls</li> <li>Token introspection: The RS uses the HTTPSintrospectintrospection interface ofAS.</t> <t>Tokenthe AS.</li> <li>Token request: The Client or its Client AS uses the HTTPS token endpoint of theAS.</t> <t>authz-infoAS.</li> <li>authz-info endpoint: ItMAY<bcp14>MAY</bcp14> be supported using the method described in <xreftarget="app-authzinfo"></xref>,target="app-authzinfo" format="default"/> but is not protected other than by the TLS channel between the Client and RS.</t> <t>Token</li> <li>Token transport: Via the "authz-info" topic,orTLS withPSK, providedPSKs (provided as a PSKidentity,identity), or in the MQTT CONNECT packet for both versions of MQTT. The AUTH extensions can also be used for authentication andre-authenticationreauthentication for MQTT v5.0, as described in Sections <xreftarget="connect_v5"></xref>target="connect_v5" format="counter"/> and <xreftarget="reauthentication"></xref>.</t> </list> </t> </section> <!-- Change Log --> <section anchor="document_updates" title="Document Updates"> <t>Version 15: Addressing GENART review comments. </t> <t>Version 11 to 15: Addressing AD review comments. </t> <t> Version 10 to 11: Clarified the TLS use between RS-AS and Client-AS. </t> <t> Version 09 to 10: Fixed version issues for references. </t> <t> Version 08 to 09: Fixed spacing issues and references. </t> <t> Version 07 to 08: <list style="symbols"> <t>Fixed several nits, typos based on WG reviews.</t> <t>Added missing references.</t> <t>Added the definition for Property defined by MQTT, and Client Authorization Server.</t> <t>Added artwork to show Authorization Data format for various PoP-related message exchange.</t> <t>Removed all MQTT-related must/should/may.</t> <t>Made AS discovery optional.</t> <t>Clarified what the client and server must implement for client authentication; cleaned up TLS 1.3 related language.</t> </list> </t> <t> Version 06 to 07: <list style="symbols"> <t>Corrected the title.</t> <t>In Section 2.2.3, added the constraint on which packets the Client can send, and the server can process after CONNECT before CONNACK.</t> <t>In Section 2.2.3, clarified that session state is identified by Client Identifier, and listed its content.</t> <t>In Section 2.2.3, clarified the issue of Client Identifier collision, when the Broker supports session continuation.</t> <t>Corrected the buggy scope example in Section 3.1.</t> </list> </t> <t> Version 05 to 06: <list style="symbols"> <t>Replace the originally proposed scope format with AIF model. Defined the AIF-MQTT, gave an example with a JSON array. Added a normative reference to the AIF draft.</t> <t>Clarified client connection after submitting token via "authz-info" topic as TLS:Known(RPK/PSK),MQTT:none. </t> <t>Expanded acronyms on their first use including the ones in the title.</t> <t>Added a definition for "Session".</t> <t>Corrected "CONNACK" definition, which earlier said it's the first packet sent by the Broker.</t> <t>Added a statement that the Broker will disconnect on almost any error and may not keep session state.</t> <t>Clarified that the Broker does not cache tokens that cannot be validated.</t> </list> </t> <t> Version 04 to 05: <list style="symbols"> <t>Reorganised Section 2 such that "Unauthorized Request: Authorization Server Discovery" is presented under Section 2.</t> <t>Fixed Figure 2 to remove the "empty" word.</t> <t>Clarified that MQTT v5.0 Brokers may implement username/password option for transporting the ACE token only for MQTT v.3.1.1 clients. This option is not recommended for MQTT v.5.0 clients.</t> <t>Changed Clean Session requirement both for MQTT v.5.0 and v.3.1.1. The Broker SHOULD NOT, instead of MUST NOT, continue sessions. Clarified expected behaviour if session continuation is supported. Added to the Security Considerations the potential misuse of session continuation.</t> <t>Fixed the Authentication Data to include token length for the Challenge/Response PoP.</t> <t>Added that Authorization Server Discovery is triggered if a token is not valid and not only missing.</t> <t>Clarified that the Broker should not accept any other packets from Client after CONNECT and before sending CONNACK.</t> <t> Added that client reauthentication is accepted only for the challenge/response PoP.</t> <t> Added Ed25519 as mandatory to implement.</t> <t>Fixed typos.</t> </list> </t> <t> Version 03 to 04: <list style="symbols"> <t>Linked the terms Broker and MQTT server more at the introduction of the document.</t> <t>Clarified support for MQTTv3.1.1 and removed phrases that might be considered as MQTTv5 is backwards compatible with MQTTv3.1.1</t> <t>Corrected the Informative and Normative references.</t> <t>For AS discovery, clarified the CONNECT message omits the Authentication Data field. Specified the User Property MUST be set to "ace_as_hint" for AS Request Creation Hints.</t> <t>Added that MQTT v5 brokers MAY also implement reduced interactions described for MQTTv3.1.1.</t> <t>Added to Section 3.1, in case of an authorization failure and QoS level 0, the RS sends a DISCONNECT with reason code 0x87 (Not authorized).</t> <t>Added a pointer to section 4.7 of MQTTv5 spec for more information on topic names and filters.</t> <t>Added HS256 and RSA256 are mandatory to implement depending on the choice of symmetric or asymmetric validation.</t> <t>Added MQTT to the TLS exporter label to make it application specific: 'EXPORTER-ACE-MQTT-Sign-Challenge'.</t> <t>Added a format for Authentication Data so that length values prefix the token (or client nonce) when Authentication Data contains more than one piece of information.</t> <t> Clarified clients still connect over TLS (server-side) for the authz-info flow. </t> </list> </t> <t> Version 02 to 03: <list style="symbols"> <t>Added the option of Broker certificate thumbprint in the 'rs_cnf' sent to the Client.</t> <t>Clarified the use of a random nonce from the TLS Exporter for PoP, added to the IANA requirements that the label should be registered.</t> <t>Added a client nonce, when Challenge/Response Authentication is used between Client and Broker.</t> <t>Clarified the use of the "authz-info" topic and the error response if token validation fails.</t> <t>Added clarification on wildcard use in scopes for publish/subscribe permissions</t> <t>Reorganised sections so that token authorization for publish/subscribe messages are better placed.</t> </list> </t> <t> Version 01 to 02: <list style="symbols"> <t> Clarified protection of Application Message payload as out of scope, and cited draft-palombini-ace-coap-pubsub-profile for a potential solution </t> <t> Expanded Client connection authorization to capture different options for Client and Broker authentication over TLS and MQTT</t> <t> Removed Payload (and specifically Client Identifier) from proof-of-possession in favor of using tls-exporter for a TLS-session based challenge.</t> <t> Moved token transport via "authz-info" topic from the Appendix to the main text.</t> <t> Clarified Will scope. </t> <t> Added MQTT AUTH to terminology.</t> <t> Typo fixes, and simplification of figures.</t> </list> </t> <t> Version 00 to 01: <list style="symbols"> <t> Present the MQTTv5 as the RECOMMENDED version, and MQTT v3.1.1 for backward compatibility. </t> <t> Clarified Will message. </t> <t> Improved consistency in the use of terminology and upper/lower case. </t> <t> Defined Broker and MQTTS. </t> <t> Clarified HTTPS use for C-AS and RS-AS communication. Removed reference to actors document, and clarified the use of client authorization server.</t> <t> Clarified the Connect message payload and Client Identifier. </t> <t> Presented different methods for passing the token and PoP. </t> <t> Added new figures to explain AUTH packets exchange, updated CONNECT message figure. </t> </list> </t>target="reauthentication" format="counter"/>.</li> </ul> </section> <section anchor="Acknowledgments"title="Acknowledgments" numbered="no"numbered="false" toc="default"> <name>Acknowledgments</name> <t> The authors would like to thankLudwig Seitz<contact fullname="Ludwig Seitz"/> for his review and his input on the authorization information endpoint;Benjamin Kaduk<contact fullname="Benjamin Kaduk"/> for his review, insightful comments, and contributions to resolving issues; andCarsten Bormann<contact fullname="Carsten Bormann"/> for his review and revisions to the AIF-MQTT data model. The authors would like to thankPaul Fremantle<contact fullname="Paul Fremantle"/> for the initial discussions on MQTT v5.0 support. </t> </section> </back> </rfc>