idnits 2.17.00 (12 Aug 2021) /tmp/idnits37009/draft-ietf-ace-mqtt-tls-profile-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (23 March 2022) is 52 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-httpbis-semantics' -- Possible downref: Non-RFC (?) normative reference: ref. 'MQTT-OASIS-Standard-v5' ** Downref: Normative reference to an Informational RFC: RFC 6234 ** Downref: Normative reference to an Informational RFC: RFC 8032 Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group C.S. Sengul 3 Internet-Draft Brunel University 4 Intended status: Standards Track A.K. Kirby 5 Expires: 24 September 2022 Oxbotica 6 23 March 2022 8 Message Queuing Telemetry Transport (MQTT)-TLS profile of Authentication 9 and Authorization for Constrained Environments (ACE) Framework 10 draft-ietf-ace-mqtt-tls-profile-17 12 Abstract 14 This document specifies a profile for the ACE (Authentication and 15 Authorization for Constrained Environments) framework to enable 16 authorization in a Message Queuing Telemetry Transport (MQTT)-based 17 publish-subscribe messaging system. Proof-of-possession keys, bound 18 to OAuth2.0 access tokens, are used to authenticate and authorize 19 MQTT Clients. The protocol relies on TLS for confidentiality and 20 MQTT server (Broker) authentication. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on 24 September 2022. 39 Copyright Notice 41 Copyright (c) 2022 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 46 license-info) in effect on the date of publication of this document. 47 Please review these documents carefully, as they describe your rights 48 and restrictions with respect to this document. Code Components 49 extracted from this document must include Revised BSD License text as 50 described in Section 4.e of the Trust Legal Provisions and are 51 provided without warranty as described in the Revised BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 57 1.2. ACE-Related Terminology . . . . . . . . . . . . . . . . . 4 58 1.3. MQTT-Related Terminology . . . . . . . . . . . . . . . . 5 59 2. Authorizing Connection Requests . . . . . . . . . . . . . . . 9 60 2.1. Client Token Request to the Authorization Server (AS) . . 10 61 2.2. Client Connection Request to the Broker (C) . . . . . . . 11 62 2.2.1. Overview of Client-RS Authentication Methods over TLS 63 and MQTT . . . . . . . . . . . . . . . . . . . . . . 12 64 2.2.2. authz-info: The Authorization Information Topic . . . 13 65 2.2.3. Client Authentication over TLS . . . . . . . . . . . 14 66 2.2.3.1. Raw Public Key Mode . . . . . . . . . . . . . . . 14 67 2.2.3.2. Pre-Shared Key Mode . . . . . . . . . . . . . . . 15 68 2.2.4. Client Authentication over MQTT . . . . . . . . . . . 15 69 2.2.4.1. Transporting the Access Token Inside the MQTT 70 CONNECT . . . . . . . . . . . . . . . . . . . . . . 15 71 2.2.4.2. Authentication Using AUTH Property . . . . . . . 18 72 2.2.5. Broker Token Validation . . . . . . . . . . . . . . . 21 73 2.3. Token Scope and Authorization . . . . . . . . . . . . . . 22 74 2.4. Broker Response to Client Connection Request . . . . . . 23 75 2.4.1. Unauthorized Request and the Optional Authorization 76 Server Discovery . . . . . . . . . . . . . . . . . . 23 77 2.4.2. Authorization Success . . . . . . . . . . . . . . . . 24 78 3. Authorizing PUBLISH and SUBSCRIBE Packets . . . . . . . . . . 24 79 3.1. PUBLISH Packets from the Publisher Client to the 80 Broker . . . . . . . . . . . . . . . . . . . . . . . . . 24 81 3.2. PUBLISH Packets from the Broker to the Subscriber 82 Clients . . . . . . . . . . . . . . . . . . . . . . . . . 25 83 3.3. Authorizing SUBSCRIBE Packets . . . . . . . . . . . . . . 25 84 4. Token Expiration, Update, and Reauthentication . . . . . . . 26 85 5. Handling Disconnections and Retained Messages . . . . . . . . 27 86 6. Reduced Protocol Interactions for MQTT v3.1.1 . . . . . . . . 28 87 6.1. Token Transport . . . . . . . . . . . . . . . . . . . . . 28 88 6.2. Handling Authorization Errors . . . . . . . . . . . . . . 30 89 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 90 7.1. TLS Exporter Label Registration . . . . . . . . . . . . . 31 91 7.2. Media Type Registration . . . . . . . . . . . . . . . . . 31 92 7.3. ACE OAuth Profile Registration . . . . . . . . . . . . . 32 93 7.4. AIF . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 94 8. Security Considerations . . . . . . . . . . . . . . . . . . . 33 95 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 34 96 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 97 10.1. Normative References . . . . . . . . . . . . . . . . . . 35 98 10.2. Informative References . . . . . . . . . . . . . . . . . 38 99 Appendix A. Checklist for profile requirements . . . . . . . . . 40 100 Appendix B. Document Updates . . . . . . . . . . . . . . . . . . 40 101 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 45 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 104 1. Introduction 106 This document specifies a profile for the ACE framework 107 [I-D.ietf-ace-oauth-authz]. In this profile, Clients and Servers 108 (Brokers) use MQTT to exchange Application Messages. The protocol 109 relies on TLS for communication security between entities. The MQTT 110 protocol interactions are described based on the MQTT v5.0 - the 111 OASIS Standard [MQTT-OASIS-Standard-v5]. Since it is expected that 112 MQTT deployments will continue to support MQTT v3.1.1 Clients, this 113 document also describes a reduced set of protocol interactions for 114 MQTT v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard-v3.1.1]. 115 However, MQTT v5.0 is the RECOMMENDED version as it works more 116 naturally with ACE-style authentication and authorization. 118 MQTT is a publish-subscribe protocol, and after connecting to the 119 MQTT Server (Broker), a Client can publish and subscribe to multiple 120 topics. The Broker, which acts as the Resource Server (RS), is 121 responsible for distributing messages published by the publishers to 122 their subscribers. In the rest of the document, the terms "RS", 123 "MQTT Server" and "Broker" are used interchangeably. 125 Messages are published under a Topic Name, and subscribers subscribe 126 to the Topic Names to receive the corresponding messages. The Broker 127 uses the Topic Name in a published message to determine which 128 subscribers to relay the messages to. In this document, topics, more 129 specifically, Topic Names, are treated as resources. The Clients are 130 assumed to have identified the publish/subscribe topics of interest 131 out-of-band (topic discovery is not a feature of the MQTT protocol). 132 A Resource Owner can pre-configure policies at the Authorization 133 Server (AS) that give Clients publish or subscribe permissions to 134 different topics. 136 Clients prove their permission to publish and subscribe to topics 137 hosted on an MQTT Broker using an access token, bound to a proof-of- 138 possession (PoP) key. This document describes how to authorize the 139 following exchanges between the Clients and the Broker. 141 * Connection requests from the Clients to the Broker 143 * Publish requests from the Clients to the Broker and from the 144 Broker to the Clients 146 * Subscribe requests from the Clients to the Broker 148 Clients use the MQTT PUBLISH packet to publish to a topic. The 149 mechanisms specified in this document do not protect the payload of 150 the PUBLISH packet from the Broker. Hence, the payload is not signed 151 or encrypted specifically for the subscribers. This functionality 152 may be implemented using the proposal outlined in the ACE Pub-Sub 153 Profile [I-D.ietf-ace-pubsub-profile]. 155 To provide communication confidentiality and Broker authentication to 156 the MQTT Clients, TLS is used, and TLS 1.3 [RFC8446] is RECOMMENDED. 157 This document makes the same assumptions as Section 4 of the ACE 158 framework [I-D.ietf-ace-oauth-authz] regarding Client and RS 159 registration with the AS and setting up the keying material. While 160 the Client-Broker exchanges are only over MQTT, the required Client- 161 AS and RS-AS interactions are described for HTTPS-based communication 162 [I-D.ietf-httpbis-semantics], using "application/ace+json" content 163 type, and unless otherwise specified, using JSON encoding. The token 164 MAY be an opaque reference to authorization information or JSON Web 165 Token (JWT) [RFC7519]. For JWTs, this document follows [RFC7800] for 166 PoP semantics for JWTs, and the mechanisms for providing and 167 verifying PoP are detailed in Section 2.2. The Client-AS and RS-AS 168 exchanges MAY also use protocols other than HTTP, e.g., Constrained 169 Application Protocol (CoAP) [RFC7252] or MQTT. It is recommended 170 that TLS is used to secure these communication channels between 171 Client-AS and RS-AS. To reduce the protocol memory and bandwidth 172 requirements, implementations MAY also use "application/ace+cbor" 173 content type, and CBOR encoding [RFC8949], and CBOR Web Token (CWT) 174 [RFC8392] and associated PoP semantics. For more information, see 175 Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs) 176 [RFC8747]. A JWT token uses JOSE, while a CWT token uses COSE 177 [RFC8152] for security protection. 179 1.1. Requirements Language 181 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 183 "OPTIONAL" in this document are to be interpreted as described in BCP 184 14 [RFC2119] [RFC8174], when, and only when, they appear in all 185 capitals, as shown here. 187 1.2. ACE-Related Terminology 189 Certain security-related terms such as "authentication", 190 "authorization", "confidentiality", "(data) integrity", "message 191 authentication code", and "verify" are taken from [RFC4949]. 193 The terminology for entities in the architecture is defined in OAuth 194 2.0 [RFC6749] such as "Client" (C), "Resource Server" (RS) and 195 "Authorization Server" (AS). 197 The term "resource" is used to refer to an MQTT Topic Name, which is 198 defined in Section 1.3. Hence, the "Resource Owner" is any entity 199 that can authoritatively speak for the topic. This document also 200 defines a Client Authorization Server for Clients that are not able 201 to support HTTP. 203 Client Authorization Server (CAS) 204 An entity that prepares and endorses authentication and 205 authorization data for a Client, and communicates to the AS 206 using HTTPS. 208 1.3. MQTT-Related Terminology 210 The document describes message exchanges as MQTT protocol 211 interactions. The Clients are MQTT Clients, which connect to the 212 Broker to publish and subscribe to Application Messages, labelled 213 with their topics. For additional information, please refer to the 214 MQTT v5.0 - the OASIS Standard [MQTT-OASIS-Standard-v5] or the MQTT 215 v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard-v3.1.1]. 217 Broker 218 The Server in MQTT. It acts as an intermediary between the 219 Clients that publish Application Messages and the Clients 220 that made Subscriptions. The Broker acts as the Resource 221 Server for the Clients. 223 Client 224 A device or program that uses MQTT. 226 Network Connection 227 A construct provided by the underlying transport protocol 228 that is being used by MQTT. It connects the Client to the 229 Server. It provides the means to send an ordered, lossless, 230 stream of bytes in both directions. This document uses TLS 231 as tranport protocol. 233 Session 234 A stateful interaction between a Client and a Broker. Some 235 Sessions last only as long as the Network Connection; others 236 can span multiple Network Connections. 238 Application Message 239 The data carried by the MQTT protocol. The data has an 240 associated Quality-of-Service (QoS) level and Topic Name. 242 MQTT Control Packet 243 The MQTT protocol operates by exchanging a series of MQTT 244 Control packets. Each packet is composed of a Fixed Header, 245 a Variable Header (depending on the control packet type), and 246 a Payload. 248 UTF-8 encoded string 249 A string prefixed with a two-byte length field that gives the 250 number of bytes in a UTF-8 encoded string itself. Unless 251 stated otherwise, all UTF-8 encoded strings can have any 252 length in the range 0 to 65535 bytes. 254 Binary Data 255 Binary Data is represented by a two-byte length field which 256 indicates the number of data bytes, followed by that number 257 of bytes. Thus, the length of Binary Data is limited to the 258 range of 0 to 65535 Bytes. 260 Variable Byte Integer 261 Variable Byte Integer is encoded using an encoding scheme 262 that uses a single byte for values up to 127. For larger 263 values, the least significant seven bits of each byte encode 264 the data, and the most significant bit is used to indicate 265 whether there are bytes following in the representation. 266 Thus, each byte encodes 128 values and a "continuation bit". 267 The maximum number of bytes in the Variable Byte Integer 268 field is four. 270 QoS level 271 The level of assurance for the delivery of an Application 272 Message. The QoS level can be 0-2, where 0 indicates "At 273 most once delivery", 1 "At least once delivery", and 2 274 "Exactly once delivery". 276 Property 277 The last field of the Variable Header is a set of properties 278 for several MQTT control packets (e.g. CONNECT, CONNACK). A 279 Property consists of an Identifier that defines its usage and 280 data type, followed by a value. The Identifier is encoded as 281 a Variable Byte Integer. For example, the "Authentication 282 Data" property uses the Identifier 22. 284 Topic Name 285 The label attached to an Application Message, which is 286 matched to a Subscription. 288 Subscription 289 A Subscription comprises a Topic Filter and a maximum QoS. A 290 Subscription is associated with a single session. 292 Topic Filter 293 An expression that indicates interest in one or more Topic 294 Names. Topic Filters may include wildcards. 296 MQTT sends various control packets across a Network Connection. The 297 following is not an exhaustive list, and the control packets that are 298 not relevant for authorization are not explained. These include, for 299 instance, the PUBREL and PUBCOMP packets used in the 4-step handshake 300 required for QoS level 2. 302 CONNECT 303 Client request to connect to the Broker. This is the first 304 packet sent by a Client. 306 CONNACK 307 The Broker connection acknowledgment. CONNACK packets 308 contain return codes indicating either a success or an error 309 state in response to a Client's CONNECT packet. 311 AUTH 312 Authentication Exchange. An AUTH control packet is sent from 313 the Client to the Broker or from the Broker to the Client as 314 part of an extended authentication exchange. AUTH Properties 315 include Authentication Method and Authentication Data. The 316 Authentication Method is set in the CONNECT packet, and 317 consequent AUTH packets follow the same Authentication 318 Method. The contents of the Authentication Data are defined 319 by the Authentication Method. 321 PUBLISH 322 Publish request sent from a publishing Client to the Broker, 323 or from the Broker to a subscribing Client. 325 PUBACK 326 Response to a PUBLISH request with QoS level 1. A PUBACK can 327 be sent from the Broker to a Client or from a Client to the 328 Broker. 330 PUBREC 331 Response to PUBLISH request with QoS level 2. PUBREC can be 332 sent from the Broker to a Client or from a Client to the 333 Broker. 335 SUBSCRIBE 336 Subscribe request sent from a Client. 338 SUBACK 339 Subscribe acknowledgment from the Broker to the Client. 341 PINGREQ 342 A ping request sent from a Client to the Broker. It signals 343 to the Broker that the Client is alive and is used to confirm 344 that the Broker is also alive. The "Keep Alive" period is 345 set in the CONNECT packet. 347 PINGRESP 348 Response sent by the Broker to the Client in response to 349 PINGREQ. It indicates the Broker is alive. 351 DISCONNECT 352 The DISCONNECT packet is the final MQTT Control Packet sent 353 from the Client or the Broker. It indicates the reason why 354 the Network Connection is being closed. If the Network 355 Connection is closed without the Client first sending a 356 DISCONNECT packet with Reason Code 0x00 (Normal 357 disconnection) and the Connection has a Will Message, the 358 Will Message is published. 360 Will 361 If the Network Connection is not closed normally, the Broker 362 sends a last Will message for the Client if the Client 363 provided one in its CONNECT packet. Situations in which the 364 Will Message is published include, but are not limited to: 366 * An I/O error or network failure detected by the Broker. 368 * The Client fails to communicate within the Keep Alive 369 period. 371 * The Client closes the Network Connection without first 372 sending a DISCONNECT packet with a Reason Code 0x00 373 (Normal disconnection). 375 * The Broker closes the Network Connection without first 376 receiving a DISCONNECT packet with a Reason Code 0x00 377 (Normal disconnection). 379 If the Will Flag is set in the CONNECT flags, then the 380 payload of the CONNECT packet includes information about the 381 Will. The information consists of the Will Properties, Will 382 Topic, and Will Payload fields. 384 2. Authorizing Connection Requests 386 This section specifies how Client connections are authorized by the 387 AS and verified by the MQTT Broker. Figure 1 shows the basic 388 protocol flow during connection setup. The token request and 389 response use the token endpoint at the AS, specified for HTTP-based 390 interactions in Section 5.8 of the ACE framework 391 [I-D.ietf-ace-oauth-authz]. Steps (D) and (E) are optional and use 392 the introspection endpoint specified in Section 5.9 of the ACE 393 framework. The discussion in this document assumes that the Client 394 and the Broker use HTTPS to communicate with the AS via these 395 endpoints. The Client and the Broker use MQTT to communicate between 396 them. The C-AS and Broker-AS communication MAY be implemented using 397 protocols other than HTTPS, e.g. CoAP or MQTT. Whatever protocol is 398 used for C-AS and Broker-AS communications MUST provide mutual 399 authentication, confidentiality protection, and integrity protection. 401 If the Client is resource-constrained or does not support HTTPS, a 402 separate Client Authorization Server may carry out the token request 403 on behalf of the Client (Figure 1 (A) and (B)), and later, onboard 404 the Client with the token. The interactions between a Client and its 405 Client Authorization Server for token onboarding and support for 406 MQTT-based token requests at the AS are out of the scope of this 407 document. 409 +---------------------+ 410 | Client | 411 | | 412 +---(A) Token request--| Client - | 413 | | Authorization | 414 | +-(B) Access token-> Server Interface | 415 | | | (HTTPS) | 416 | | |_____________________| 417 | | | | 418 +--v-------------+ | Pub/Sub Interface | 419 | Authorization | | (MQTT over TLS) | 420 | Server | +-----------^---------+ 421 |________________| | | 422 | ^ (C)Connection (F)Connection 423 | | request + response 424 | | access token | 425 | | | | 426 | | +---v--------------+ 427 | | | Broker | 428 | | | (MQTT over TLS) | 429 | | |__________________| 430 | +(D)Introspection-| | 431 | request (optional) | RS-AS interface | 432 | | (HTTPS) | 433 +-(E)Introspection---->|__________________| 434 response (optional) 436 Figure 1: Connection Setup 438 2.1. Client Token Request to the Authorization Server (AS) 440 The first step in the protocol flow (Figure 1 (A)) is the token 441 acquisition by the Client from the AS. The Client and the AS MUST 442 perform mutual authentication. The Client requests an access token 443 from the AS as described in Section 5.8.1 of the ACE framework 444 [I-D.ietf-ace-oauth-authz]. The document follows the procedures 445 defined in Section 3.2.1 of the DTLS profile 446 [I-D.ietf-ace-dtls-authorize] for RPK (Raw Public Keys [RFC7250]), 447 and in Section 3.3.1 of the same document for PSK (Pre-Shared Keys). 448 However, the content type of the request is set to "application/ 449 ace+json", and the AS uses JSON in the payload of its responses to 450 the Client and the RS. As explained earlier, implementations MAY 451 also use "application/ace+cbor" content type. 453 On receipt of the token request, the AS verifies the request. If the 454 AS successfully verifies the access token request and authorizes the 455 Client for the indicated audience (i.e., RS) and scopes (i.e., 456 publish/subscribe permissions over topics as described in 457 Section 2.3), the AS issues an access token (Figure 1 (B)). 459 The response includes the parameters described in Section 5.8.2 of 460 the ACE framework [I-D.ietf-ace-oauth-authz]. For RPK, the 461 parameters are as described in Section 3.2.1 of the DTLS profile 462 [I-D.ietf-ace-dtls-authorize]. For PSK, the document follows 463 Section 3.3.1 of the DTLS profile [I-D.ietf-ace-dtls-authorize]. In 464 both cases, if the response contains an "ace_profile" parameter, this 465 parameter is set to "mqtt_tls". The returned token is a Proof-of- 466 Possession (PoP) token by default. 468 This document follows [RFC7800] for PoP semantics for JWTs (CWTs MAY 469 also be used). The AS includes a "cnf" (confirmation) parameter in 470 the PoP token, to declare that the Client possesses a particular key 471 and RS can cryptographically confirm that the Client has possession 472 of that key, as described in [I-D.ietf-ace-oauth-params]. 474 Note that the contents of the web tokens (including the "cnf" 475 parameter) are to be consumed by the RS and not the Client (the 476 Client obtains the key information in a different manner). The RPK 477 case is handled as described in Section 3.2.1 of the DTLS profile 478 [I-D.ietf-ace-dtls-authorize]. For the PSK case, the referenced 479 procedures apply, with the following exceptions to accommodate JWT 480 and JOSE use. In this case, the AS adds a "cnf" parameter to the 481 access information carrying a JWK (JSON Web Key) [RFC7517] object 482 that contains either the symmetric key itself or a key identifier 483 that can be used by the RS to determine the secret key it shares with 484 the Client. The JWT is created as explained in Section 7 of 485 [RFC7519], and the JWT MUST include JWE [RFC7516]. If CWT/COSE is 486 used this information MUST be inside the "COSE_Key" object, and MUST 487 be encrypted using a "COSE_Encrypt0" structure. 489 The AS returns error responses for JSON-based interactions following 490 Section 5.2 of [RFC6749]. When CBOR is used, the interactions MUST 491 implement Section 5.8.3 of the ACE framework 492 [I-D.ietf-ace-oauth-authz]. 494 2.2. Client Connection Request to the Broker (C) 495 2.2.1. Overview of Client-RS Authentication Methods over TLS and MQTT 497 Unless the Client publishes and subscribes to only public topics, the 498 Client and the Broker MUST perform mutual authentication. The Client 499 MUST authenticate to the Broker either over MQTT or TLS before 500 performing any other action. For MQTT, the options are "None" and 501 "ace". For TLS, the options are "Anon" for an anonymous client, and 502 "Known(RPK/PSK)" for RPK and PSK, respectively. The "None" and 503 "Anon" options do not provide client authentication but can be used 504 either during authentication or in combination with authentication at 505 the other layer. When the Client uses TLS:Anon,MQTT:None, the Client 506 can only publish or subscribe to public topics. Thus, the client 507 authentication procedures involve the following possible 508 combinations: 510 * TLS:Anon,MQTT:None: This option is used only for the topics that 511 do not require authorization, including the "authz-info" topic. 512 Publishing to the "authz-info" topic is described in 513 Section 2.2.2. 515 * TLS:Anon,MQTT:ace: The token is transported inside the CONNECT 516 packet and MUST be validated using one of the methods described in 517 Section 2.2.2. This option also supports a tokenless connection 518 request for AS discovery. As per the ACE framework 519 [I-D.ietf-ace-oauth-authz], a separate step is needed to determine 520 whether the discovered AS URI is authorized to act as an AS. 522 * TLS:Known(RPK/PSK),MQTT:none: This specification supports client 523 authentication with TLS with RPK and PSK following the procedures 524 described in DTLS profile [I-D.ietf-ace-dtls-authorize]. For the 525 RPK, the Client MUST have published the token to the "authz-info" 526 topic. For the PSK, the token MAY be published to the "authz- 527 info" topic, or MAY be, alternatively, provided as a "PSK 528 identity" (e.g. an "identity" in the "identities" field in the 529 Client's "pre_shared_key" extension in TLS 1.3). 531 * TLS:Known(RPK/PSK),MQTT:ace: This option SHOULD NOT be chosen as 532 the token transported in the CONNECT overwrites any permissions 533 passed during the TLS authentication. 535 It is RECOMMENDED that the Client implements TLS:Anon,MQTT:ace as the 536 first choice when working with protected topics. However, MQTT 537 v3.1.1 Clients that do not prefer to overload username and password 538 fields for ACE (as described in Section 6) MAY implement 539 TLS:Known(RPK/PSK),MQTT:none, and consequently TLS:Anon,MQTT:None to 540 submit their token to "authz-info". 542 The Broker MUST support TLS:Anon,MQTT:ace. To support Clients with 543 different capabilities, the Broker MAY provide multiple client 544 authentication options, e.g. support TLS:Known(RPK),MQTT:none and 545 TLS:Anon,MQTT:None, to enable RPK-based client authentication. 547 The Client MUST authenticate the Broker during the TLS handshake. If 548 the Client authentication uses TLS:Known(RPK/PSK), then the Broker is 549 authenticated using the respective method. Otherwise, to 550 authenticate the Broker, the Client MUST validate a public key from 551 an X.509 certificate or an RPK from the Broker against the "rs_cnf" 552 parameter in the token response, which contains information about the 553 public key used by the RS to authenticate if the token type is "pop" 554 and asymmetric keys are used as defined in 555 [I-D.ietf-ace-oauth-params]. The AS MAY include the thumbprint of 556 the RS's X.509 certificate in the "rs_cnf" (thumbprint as defined in 557 [I-D.ietf-cose-x509]). In this case, the Client MUST validate the RS 558 certificate against this thumbprint. 560 2.2.2. authz-info: The Authorization Information Topic 562 In the cases when the Client must transport the token to the Broker 563 first, the Client connects to the Broker to publish its token to the 564 "authz-info" topic. The "authz-info" topic MUST be publish-only 565 (i.e., the Clients are not allowed to subscribe to it). "authz-info" 566 is not protected, and hence, the Client uses the TLS:Anon,MQTT:None 567 option over a TLS connection. After publishing the token, the Client 568 disconnects from the Broker and is expected to reconnect using client 569 authentication over TLS (i.e., TLS:Known(RPK/PSK),MQTT:none). 571 The Broker stores and indexes all tokens received to the "authz-info" 572 topic in its key store (similar to the DTLS profile for ACE 573 [I-D.ietf-ace-dtls-authorize]). This profile follows the 574 recommendation of Section 5.10.1 of the ACE framework 575 [I-D.ietf-ace-oauth-authz] and expects that the Broker stores only 576 one token per PoP key, and any other token linked to the same key 577 overwrites an existing token. 579 The Broker MUST verify the validity of the token (i.e., through local 580 validation or introspection, if the token is a reference) as 581 described in Section 2.2.5. If the token is not valid, the Broker 582 MUST discard the token. 584 Depending on the QoS level of the PUBLISH packet, the Broker returns 585 the error response as a PUBACK, PUBREC, or DISCONNECT packet. If the 586 QoS level is equal to 0, and the token is not valid, or the claims 587 cannot be obtained in the case of an introspected token, the Broker 588 MUST send a DISCONNECT packet with the reason code 0x87 (Not 589 authorized). If the PUBLISH payload does not parse to a token, the 590 Broker MUST send a DISCONNECT with the reason code 0x99 (Payload 591 format invalid). 593 If the QoS level of the PUBLISH packet is greater than or equal to 1, 594 and the token is not valid, or the claims cannot be obtained in the 595 case of an introspected token, the Broker MUST send the reason code 596 0x87 (Not authorized) in the PUBACK or PUBREC. If the PUBLISH 597 payload does not parse to a token, the PUBACK/PUBREC reason code is 598 0x99 (Payload format invalid). 600 It must be noted that when the Broker sends the "Not authorized" 601 response, this corresponds to the token being not valid, and not that 602 the actual PUBLISH packet was not authorized. Given that the "authz- 603 info" is a public topic, this response is not expected to cause 604 confusion. 606 2.2.3. Client Authentication over TLS 608 This document supports TLS with Raw Public Keys (RPK) [RFC7250] and 609 with Pre-Shared Keys (PSK). The TLS session setup follows the DTLS 610 profile for ACE [I-D.ietf-ace-dtls-authorize], as the profile applies 611 to TLS equally well [I-D.ietf-ace-extend-dtls-authorize]. When there 612 are exceptions to the DTLS profile, these are explicitly stated in 613 the document. If TLS 1.2 is used, [RFC7925] describes how TLS can be 614 used for constrained devices, alongside recommended cipher suites. 615 Additionally, TLS 1.2 implementations MUST use the "Extended Main 616 Secret" extension (terminology adopted from 617 [I-D.ietf-tls-rfc8446bis]) to incorporate the handshake transcript 618 into the main secret [RFC7627]. TLS implementations SHOULD use the 619 SNI (Server Name Indication) [RFC6066] and APLN (Application-Layer 620 Protocol Negotiation) [RFC7301] extensions so the TLS handshake 621 authenticates as much of the protocol context as possible. 623 2.2.3.1. Raw Public Key Mode 625 This document follows the procedures defined in Section 3.2.2 of the 626 DTLS profile for ACE [I-D.ietf-ace-dtls-authorize] with the following 627 exceptions. The Client MUST upload the access token to the Broker 628 using the method specified in Section 2.2.2 before initiating the 629 handshake. 631 2.2.3.2. Pre-Shared Key Mode 633 This document follows the procedures defined in Section 3.3.2 of DTLS 634 profile for ACE [I-D.ietf-ace-dtls-authorize] with the following 635 exceptions. 637 To use TLS 1.3 with pre-shared keys, the Client utilizes the PSK key 638 extension specified in [RFC8446] using the key conveyed in the "cnf" 639 parameter of the AS response. The same key is bound to the access 640 token in the "cnf" claim. The Client can upload the token as 641 specified in Section 2.2.2 before initiating the handshake. When 642 using a previously uploaded token, the Client MUST indicate during 643 the handshake which previously uploaded access token it intends to 644 use. To do so, it MUST create a "COSE_Key" or "JWK" structure with 645 the "kid" that was conveyed in the "rs_cnf" claim in the token 646 response from the AS and the key type "symmetric". This structure is 647 then included as the only element in the "cnf" structure and the 648 encoded value of that "cnf" structure used as a PSK identity in TLS. 649 As an alternative to the access token upload, the Client can provide 650 the most recent access token, JWT or CWT, as a PSK identity. 652 In contrast to DTLS profile for ACE [I-D.ietf-ace-dtls-authorize], a 653 Client MAY omit support for the cipher suites 654 TLS_PSK_WITH_AES_128_CCM_8 and TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8. 655 For TLS 1.2, however, a client MUST support 656 TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256 for PSK ([RFC8442]) and 657 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 for RPK ([RFC8422]), as 658 recommended in [RFC7525] (and adjusted to be a PSK cipher suite as 659 appropriate). 661 2.2.4. Client Authentication over MQTT 663 2.2.4.1. Transporting the Access Token Inside the MQTT CONNECT 665 This section describes how the Client transports the token to the 666 Broker inside the CONNECT packet. If this method is used, the Client 667 TLS connection is expected to be anonymous, and the Broker is 668 authenticated during the TLS connection setup. The approach 669 described in this section is similar to an earlier proposal by 670 Fremantle, et al. [fremantle14]. 672 After sending the CONNECT, the Client MUST wait to receive the 673 CONNACK from the Broker. The only packets it is allowed to send are 674 DISCONNECT or AUTH that is in response to the Broker AUTH. 675 Similarly, except for a DISCONNECT and AUTH response from the Client, 676 the Broker MUST NOT process any packets before sending a CONNACK. 678 Figure 2 shows the structure of the MQTT CONNECT packet used in MQTT 679 v5.0. A CONNECT packet is composed of a fixed header, a variable 680 header, and a payload. The fixed header contains the Control Packet 681 Type (CPT), Reserved, and Remaining Length fields. Remaining Length 682 is a Variable Byte Integer that represents the number of bytes 683 remaining within the current Control Packet, including data in the 684 Variable Header and the Payload. The Variable Header contains the 685 Protocol Name, Protocol Level, Connect Flags, Keep Alive, and 686 Properties fields. The Connect Flags in the variable header specify 687 the properties of the MQTT session. It also indicates the presence 688 or absence of some fields in the Payload. The payload contains one 689 or more encoded fields, namely a unique Client Identifier for the 690 Client, a Will Topic, Will Payload, User Name, and Password. All but 691 the Client Identifier can be omitted depending on the flags in the 692 Variable Header. The Client Identifier identifies the Client to the 693 Broker, and therefore, is unique for each Client. It must be noted 694 that the Client Identifier is an unauthenticated identifier used 695 within the MQTT protocol and so is not bound to the access token. 697 0 8 16 698 +---------------------------+ 699 |Protocol name length = 4 | 700 +---------------------------+ 701 | 'M' 'Q' | 702 +---------------------------+ 703 | 'T' 'T' | 704 +---------------------------+ 705 |Proto.level=5|Connect flags| 706 +---------------------------+ 707 | Keep alive | 708 +---------------------------+ 709 | CONNECT Properties Length | 710 | (Upto 4 bytes) | 711 +---------------------------+ 712 | ( ..Other properties..) | 713 +---------------------------+ 714 | Authentication Method | 715 | (0x15) | Len. | 716 | Len | 'a' | 717 | 'c' | 'e' | 718 +---------------------------+ 719 | Authentication Data | 720 | (0x16) | Len | 721 | Len | token | 722 | or token + PoP data | 723 +---------------------------+ 725 Figure 2: MQTT v5 CONNECT Variable Header with Authentication 726 Method Property for ACE 728 The CONNECT flags are Username, Password, Will retain, Will QoS, Will 729 Flag, Clean Start, and Reserved. Figure 3 shows how the flags MUST 730 be set to use AUTH packets for authentication and authorization, 731 i.e., the username and password flags MUST be set to 0. An MQTT v5.0 732 Broker MAY also support token transport using Username and Password 733 to provide a security option for MQTT v3.1.1 Clients, as described in 734 Section 6. 736 +-----------------------------------------------------------+ 737 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 738 | Flag |Flag | | | |Start| | 739 +-----------------------------------------------------------+ 740 | 0 | 0 | X | X X | X | X | 0 | 741 +-----------------------------------------------------------+ 743 Figure 3: CONNECT Flags for AUTH 745 The Will Flag indicates that a Will message needs to be sent. The 746 Client MAY set the Will Flag as desired (marked as "X" in Figure 3). 747 If the Will Flag is set to 1, the Broker MUST check that the token 748 allows the publication of the Will message (i.e., the Will Topic 749 filter is in the scope array). The check is performed against the 750 token scope described in Section 2.3. If the Will authorization 751 fails, the connection is refused as described in Section 2.4.1. If 752 the Broker accepts the connection request, the Broker stores the Will 753 message and publishes it when the Network Connection is closed 754 according to Will QoS, and Will retain parameters and MQTT Will 755 management rules. To avoid publishing the Will Messages in the case 756 of temporary network disconnections, the Client specifies a Will 757 Delay Interval in the Will Properties. Section 5 explains how the 758 Broker deals with the retained messages in further detail. 760 In MQTT v5.0, the Client signals a clean session (i.e., that the 761 session does not continue an existing session) by setting the Clean 762 Start Flag to 1 in the CONNECT packet. In this profile, the Client 763 SHOULD always start with a clean session. The Broker MAY also signal 764 that it does not support session continuation by setting Session 765 Expiry Interval to 0 in the CONNACK. If the Broker starts a clean 766 session, the Broker MUST set the Session Present flag to 0 in the 767 CONNACK packet to signal this to the Client. 769 The Broker MAY support session continuation, e.g., if the Broker 770 requires it for QoS reasons. In this case, if a CONNECT packet is 771 received with Clean Start set to 0 and there is a Session associated 772 with the Client Identifier, the Broker MUST resume communications 773 with the Client based on the state from the existing Session. In its 774 response, the Broker MUST set the Session Present flag to 1 in the 775 CONNACK packet to signal session continuation to the Client. The 776 session state stored by the Client and the Broker is described in 777 Section 5. 779 When reconnecting to a Broker that supports session continuation, the 780 Client MUST still provide a token, in addition to using the same 781 Client Identifier and setting the Clean Start to 0. The Broker MUST 782 still perform PoP validation on the provided token. If the token 783 matches the stored state, the Broker MAY skip introspecting a token- 784 by-reference and use the stored introspection result. The Broker 785 MUST also verify the Client is authorized to receive or send MQTT 786 packets that are pending transmission. When a Client connects with a 787 long Session Expiry Interval, the Broker may need to maintain the 788 Client's MQTT session state after it disconnects for an extended 789 period. Brokers SHOULD implement administrative policies to limit 790 misuse. 792 Note that, according to the MQTT standard, the Broker uses the Client 793 Identifier to identify the session state. In the case of a Client 794 Identifier collision, a Client may take over another Client's 795 session. Given that the Broker MUST associate the Client with a 796 valid token, a Client will only send or receive messages to its 797 authorized topics. Therefore, while this issue is not expected to 798 affect security, it may affect QoS (i.e., PUBLISH or QoS messages 799 saved for Client A may be delivered to a Client B). In addition, if 800 this Client Identifier represents a Client already connected to the 801 Broker, the Broker sends a DISCONNECT packet to the existing Client 802 with Reason Code of 0x8E (Session taken over) and closes the 803 connection to the Client. 805 2.2.4.2. Authentication Using AUTH Property 807 To use AUTH, the Client MUST set the Authentication Method as a 808 property of a CONNECT packet by using the property identifier 21 809 (0x15). This is followed by a UTF-8 Encoded String containing the 810 name of the Authentication Method, which MUST be set to "ace". If 811 the Broker does not support this profile, it sends a CONNACK with a 812 Reason Code of 0x8C (Bad authentication method). 814 The Authentication Method is followed by the Authentication Data, 815 which has a property identifier 22 (0x16) and is Binary Data. Based 816 on the Authentication Data, the Broker MUST support both options 817 below: 819 * Proof-of-Possession using a challenge from the TLS session 820 * Proof-of-Possession via Broker-generated challenge/response 822 2.2.4.2.1. Proof-of-Possession Using a Challenge from the TLS session 824 +-----------------------------------------------------------------+ 825 |Authentication|Token Length|Token |MAC or Signature | 826 |Data Length | | |(over TLS exporter content) | 827 +-----------------------------------------------------------------+ 829 Figure 4: Authentication Data for PoP Based on TLS Exporter Content 831 For this option, the Authentication Data inside the Client's CONNECT 832 MUST contain the two-byte integer token length, the token, and the 833 keyed message digest (MAC) or the Client signature (as shown in 834 Figure 4). The Proof-of-Possession key in the token is used to 835 calculate the keyed message digest (MAC) or the Client signature 836 based on the content obtained from the TLS exporter ([RFC5705] for 837 TLS 1.2, and Section 7.5 of [RFC8446]) for TLS 1.3. This content is 838 exported from the TLS session using the exporter label "EXPORTER-ACE- 839 MQTT-Sign-Challenge", an empty context, and length of 32 bytes. The 840 token is also validated as described in Section 2.2.5, and the Broker 841 responds with a CONNACK with the appropriate response code. The 842 Client cannot reauthenticate using this method during the same TLS 843 session (see Section 4). 845 2.2.4.2.2. Proof-of-Possession via Broker-generated Challenge/Response 847 +------------------------------------+ 848 |Authentication|Token Length|Token | 849 |Data Length | | | 850 +------------------------------------+ 852 Figure 5: Authentication Data to Initiate PoP Based on Challenge/ 853 Response 855 +--------------------------+ 856 |Authentication|RS Nonce | 857 |Data Length |(8 bytes) | 858 +--------------------------+ 860 Figure 6: Authentication Data for Broker Challenge 862 For this option, the Broker follows a Broker-generated challenge/ 863 response protocol. If the Authentication Data inside the Client's 864 CONNECT contains only the two-byte integer token length and the token 865 (as shown in Figure 5), the Broker MUST respond with an AUTH packet, 866 with the Authenticate Reason Code set to 0x18 (Continue 867 Authentication). The Broker also uses this method if the 868 Authentication Data does not contain a token, but the Broker has a 869 token stored for the connecting Client. 871 The Broker continues authentication using an AUTH packet that 872 contains the Authentication Method and the Authentication Data. The 873 Authentication Method MUST be set to "ace", and the Authentication 874 Data MUST NOT be empty and MUST contain an 8-byte RS nonce as a 875 challenge for the Client (Figure 6). 877 +---------------------------------------------------------+ 878 |Authentication|Client Nonce |MAC or Signature | 879 |Data Length |(8 bytes) |(over RS nonce+Client nonce)| 880 +---------------------------------------------------------+ 882 Figure 7: Authentication Data for Client Challenge Response 884 The Client responds to this with an AUTH packet with a reason code 885 0x18 (Continue Authentication). Similarly, the Client packet sets 886 the Authentication Method to "ace". The Authentication Data in the 887 Client's response is formatted as shown in Figure 7 and includes the 888 8-byte Client nonce, and the signature or MAC computed over the RS 889 nonce concatenated with the Client nonce using PoP key in the token. 891 Next, the token is validated as described in Section 2.2.5. The 892 success case is illustrated in Figure 8. The Client MAY also re- 893 authenticate using this challenge-response flow, as described in 894 Section 4. 896 Client Broker 897 | | 898 |<===========>| TLS connection setup 899 | | 900 | | 901 +------------>| CONNECT with Authentication Data 902 | | contains only token 903 | | 904 <-------------+ AUTH 0x18 (Cont. Authentication) 905 | | 8-byte RS nonce as challenge 906 | | 907 |------------>| AUTH 0x18 (Cont. Authentication) 908 | | 8-byte Client nonce + signature/MAC 909 | | 910 | |---+ Token validation 911 | | | (may involve introspection) 912 | |<--+ 913 | | 914 |<------------+ CONNACK 0x00 (Success) 916 Figure 8: PoP Challenge/Response Flow - Success 918 2.2.5. Broker Token Validation 920 The Broker MUST verify the validity of the token either locally 921 (e.g., in the case of a self-contained token) or MAY send a request 922 to the introspection endpoint of the AS (as described for HTTP-based 923 interactions in Section 5.9 of the ACE framework 924 [I-D.ietf-ace-oauth-authz]). The Broker MUST verify the claims in 925 the access token according to the rules set in Section 5.10.1.1 of 926 the ACE framework [I-D.ietf-ace-oauth-authz]. 928 To authenticate the Client, the Broker validates the signature or the 929 MAC, depending on how the PoP protocol is implemented. For self- 930 contained tokens, the Broker MUST process the security protection of 931 the token first, as specified by the respective token format, i.e. a 932 CWT token uses COSE, while a JWT token uses JOSE. For a token-by- 933 reference, the Broker uses the "cnf" structure returned as a result 934 of token introspection as specified in [RFC7519]. HS256 (HMAC-SHA- 935 256) [RFC6234] and Ed25519 [RFC8032] are mandatory to implement for 936 the Broker. The Client MUST implement at least one of them depending 937 on the choice of symmetric or asymmetric validation. Validation of 938 the signature or MAC MUST fail if the signature algorithm is set to 939 "none", when the key used for the signature algorithm cannot be 940 determined, or the computed and received signature/MAC do not match. 942 The Broker MUST check if the access token is still valid, if it is 943 the intended destination (i.e., the audience) of the token, and if 944 the token was issued by an authorized authorization server. If the 945 Client is using TLS RPK mode to authenticate to the Broker, the AS 946 constructs the access token so that the Broker can associate the 947 access token with the Client's public key. The "cnf" claim MUST 948 contain either the Client's RPK or, if the key is already known by 949 the Broker (e.g., from previous communication), a reference to it. 951 2.3. Token Scope and Authorization 953 The scope field contains the publish and subscribe permissions for 954 the Client. Therefore, the token or its introspection result MUST be 955 cached to allow a Client's future PUBLISH and SUBSCRIBE messages. 956 During the CONNECT, if the Will Flag is set to 1, the Broker MUST 957 also authorize the publication of the Will Topic and message using 958 the token's scope field. The Broker uses the scope to match against 959 the Topic Name in a PUBLISH packet (including Will Topic in the 960 CONNECT) or a Topic Filter in a SUBSCRIBE packet. 962 The scope in the token is a single value. For a JWT, the single 963 scope is base64url encoded string with any padding characters 964 removed, which has an internal structure of a JSON array. For a CWT, 965 this information is represented in CBOR. The internal structure 966 follows the Authorization Information Format (AIF) for ACE 967 [I-D.ietf-ace-aif]. Using the Concise Data Definition Language 968 (CDDL) [RFC8610], the specific data model for MQTT is: 970 AIF-MQTT = AIF-Generic 971 AIF-Generic = [* [Toid, Tperm]] 972 mqtt-topic-filter = tstr ; as per Section 4.7 of MQTT v5.0 973 mqtt-permissions = [+permission] 974 permission = "pub"/"sub" 976 Figure 9: AIF-MQTT data model 978 Topic filters are implemented according to Section 4.7 of MQTT v5.0 - 979 the OASIS Standard [MQTT-OASIS-Standard-v5]. By default, Wildcard 980 Subscriptions are supported, and so, the topic filter may include 981 special wildcard characters. The multi-level wildcard, "#", matches 982 any number of levels within a topic, and the single-level wildcard, 983 "+", matches one topic level. The Broker MAY signal in the CONNACK 984 explicitly whether wildcard subscriptions are supported by returning 985 a CONNACK property "Wildcard Subscription Available". A value of 0 986 means that Wildcard Subscriptions are not supported. A value of 1 987 means Wildcard Subscriptions are supported. 989 Following this model, an example scope may contain: 991 [["topic1",["pub","sub"]],["topic2/#",["pub"]],["+/topic3",["sub"]]] 993 Figure 10: Example scope 995 This access token gives publish ("pub") and subscribe ("sub") 996 permissions to the "topic1", publish permission to all the subtopics 997 of "topic2", and subscribe permission to all "topic3", skipping one 998 level. 1000 If the scope is empty, the Broker records no permissions for the 1001 Client for any topic. In this case, the Client is not able to 1002 publish or subscribe to any protected topics. The non-empty scope is 1003 used to authorize the Will Topic, if provided, in the CONNECT packet, 1004 during connection setup, and if the connection request succeeds, the 1005 Topic Names or Topic Filters requested in the future PUBLISH and 1006 SUBSCRIBE packets. For the authorization to succeed, the Broker MUST 1007 verify that the topic name or filter in question is either an exact 1008 match to or a subset of at least one "topic_filter" in the scope. 1010 2.4. Broker Response to Client Connection Request 1012 Based on the validation result (obtained either via local inspection 1013 or using the introspection interface of the AS), the Broker MUST send 1014 a CONNACK packet to the Client. 1016 2.4.1. Unauthorized Request and the Optional Authorization Server 1017 Discovery 1019 Authentication can fail for the following reasons: 1021 * If the Client does not provide a valid token, 1023 * the Client omits the Authentication Data field and the Broker has 1024 no token stored for the Client, 1026 * the token or Authentication data are malformed, or 1028 * if the Will flag is set, the authorization checks for the Will 1029 topic fails. 1031 The Broker responds with the CONNACK reason code 0x87 (Not 1032 Authorized) or any other applicable reason code. 1034 The Broker MAY also trigger AS discovery and include a User Property 1035 (identified as property type 38 (0x26)) in the CONNACK for the AS 1036 Request Creation Hints. The User Property is a UTF-8 string pair, 1037 composed of a name and a value. The name of the User Property MUST 1038 be set to "ace_as_hint". The value of the user property is a UTF-8 1039 encoded JSON object containing the mandatory "AS" parameter, and the 1040 optional parameters "audience", "kid", "cnonce", and "scope" as 1041 defined in Section 5.3 of the ACE framework 1042 [I-D.ietf-ace-oauth-authz]. 1044 2.4.2. Authorization Success 1046 On success, the reason code of the CONNACK is 0x00 (Success). If the 1047 Broker starts a new session, it MUST also set Session Present to 0 in 1048 the CONNACK packet to signal a clean session to the Client. 1049 Otherwise, it MUST set Session Present to 1. 1051 Having accepted the connection, the Broker MUST be prepared to store 1052 the token during the connection and after disconnection for future 1053 use. If the token is not self-contained and the Broker uses token 1054 introspection, it MAY cache the validation result to authorize the 1055 subsequent PUBLISH and SUBSCRIBE packets. PUBLISH and SUBSCRIBE 1056 packets, which are sent after a connection setup, do not contain 1057 access tokens. If the introspection result is not cached, the Broker 1058 needs to introspect the saved token for each request. The Broker 1059 SHOULD also use a cache timeout to introspect tokens regularly. The 1060 timeout value is application-specific and should be chosen to reduce 1061 the risk of using stale introspection responses. 1063 3. Authorizing PUBLISH and SUBSCRIBE Packets 1065 Using the cached token or its introspection result, the Broker uses 1066 the scope field to match against the Topic Name in a PUBLISH packet, 1067 or a Topic Filter in a SUBSCRIBE packet. 1069 3.1. PUBLISH Packets from the Publisher Client to the Broker 1071 On receiving the PUBLISH packet, the Broker MUST use the type of 1072 packet (i.e., PUBLISH) and the Topic name in the packet header to 1073 match against the scope array items in the cached token or its 1074 introspection result. Following the example in Section 2.3, the 1075 Client sending a PUBLISH for "topic2/a" would be allowed, as the 1076 scope array includes the ["topic2/#",["pub"]]. 1078 If the Client is allowed to publish to the topic, the Broker 1079 publishes the message to all valid subscribers of the topic. In the 1080 case of an authorization failure, the Broker MUST return an error if 1081 the Client has set the QoS level of the PUBLISH packet to greater 1082 than or equal to 1. Depending on the QoS level, the Broker responds 1083 with either a PUBACK or PUBREC packet with reason code 0x87 (Not 1084 authorized). On receiving an acknowledgment with 0x87 (Not 1085 authorized), the Client MAY reauthenticate by providing a new token 1086 as described in Section 4. 1088 For QoS level 0, the Broker sends a DISCONNECT with reason code 0x87 1089 (Not authorized) and closes the Network Connection. Note that the 1090 server-side DISCONNECT is a new feature of MQTT v5.0 (in MQTT v3.1.1, 1091 the server needs to drop the connection). 1093 For all QoS levels, the Broker MAY return 0x80 Unspecified error if 1094 they do not want to leak the topic names to unauthorized clients. 1096 3.2. PUBLISH Packets from the Broker to the Subscriber Clients 1098 To forward PUBLISH packets to the subscribing Clients, the Broker 1099 identifies all the subscribers that have valid matching topic 1100 subscriptions to the Topic name of the PUBLISH packet (i.e., the 1101 tokens are valid, and token scopes allow a subscription to this 1102 particular Topic name). The Broker forwards the PUBLISH packet to 1103 all the valid subscribers. 1105 The Broker MUST NOT forward messages to unauthorized subscribers. To 1106 avoid silently dropping messages, the Broker MUST close the network 1107 connection and SHOULD inform the affected subscribers. The only way 1108 to inform a client, in this case, would be sending a DISCONNECT 1109 packet. Therefore, the Broker SHOULD send a DISCONNECT packet with 1110 the reason code 0x87 (Not authorized) before closing the network 1111 connection to these clients. 1113 3.3. Authorizing SUBSCRIBE Packets 1115 In MQTT, a SUBSCRIBE packet is sent from a Client to the Broker to 1116 create one or more subscriptions to one or more topics. The 1117 SUBSCRIBE packet may contain multiple Topic Filters. The Topic 1118 Filters may include wildcard characters. 1120 On receiving the SUBSCRIBE packet, the Broker MUST use the type of 1121 packet (i.e., SUBSCRIBE) and the Topic Filter in the packet header to 1122 match against the scope field of the stored token or introspection 1123 result. The Topic Filters MUST be an exact match to or be a subset 1124 of at least one of the "topic_filter" fields in the scope array found 1125 in the Client's token. For example, if the Client sends a 1126 subscription request for topic "a/b/*", and has a token that permits 1127 "a/*", this is a valid subscription request, as "a/b/*" is a subset 1128 of "a/*". (The process is similar to a Broker matching the Topic 1129 Name in a PUBLISH packet against the Subscriptions known to the 1130 Server.) 1132 As a response to the SUBSCRIBE packet, the Broker issues a SUBACK. 1133 For each Topic Filter, the SUBACK packet includes a return code 1134 matching the QoS level for the corresponding Topic Filter. In the 1135 case of failure, the return code is 0x87, indicating that the Client 1136 is not authorized. The Broker MAY return 0x80 Unspecified error if 1137 they do not want to leak the topic names to unauthorized clients. A 1138 reason code is returned for each Topic Filter. Therefore, the Client 1139 may receive success codes for a subset of its Topic Filters while 1140 being unauthorized for the rest. 1142 4. Token Expiration, Update, and Reauthentication 1144 The Broker MUST check for token expiration whenever a CONNECT, 1145 PUBLISH, or SUBSCRIBE is received or sent. The Broker SHOULD check 1146 for token expiration on receiving a PINGREQUEST. The Broker MAY also 1147 check for token expiration periodically, e.g., every hour. This may 1148 allow for early detection of a token expiry. 1150 The token expiration is checked by checking the "exp" claim of a JWT 1151 or introspection response or via performing an introspection request 1152 with the AS as described in Section 5.9 of the ACE framework 1153 [I-D.ietf-ace-oauth-authz]. Token expirations may trigger the Broker 1154 to send PUBACK, SUBACK and DISCONNECT packets with return code set to 1155 "Not authorized". After sending a DISCONNECT, the Network Connection 1156 is closed, and no more messages can be sent. 1158 The Client MAY reauthenticate as a response to the PUBACK and SUBACK 1159 that signal loss of authorization. The Clients MAY also proactively 1160 update their tokens, i.e., before they receive a packet with a "Not 1161 authorized" return code. To start reauthentication, the Client MUST 1162 send an AUTH packet with the reason code 0x19 (Re-authentication). 1163 The Client MUST set the Authentication Method as "ace" and transport 1164 the new token in the Authentication Data. If re-authenticating 1165 during the current TLS session, the Client MUST NOT use the method 1166 described in Section 2.2.4.2.1, Proof-of-Possession using a challenge 1167 from the TLS session, to avoid re-using the same challenge value from 1168 the TLS-Exporter. Note that this means that servers will either need 1169 to record in the session ticket or database entry whether the TLS- 1170 Exporter-derived challenge was used, or always deny use of the TLS- 1171 Exporter-derived challenge for resumed sessions. In TLS 1.3, the 1172 resumed connection would have a new exporter value, but the 1173 requirement is phrased this way for simplicity. For re- 1174 authentications in the same TLS-session, the Client MUST use the 1175 challenge-response PoP as defined in Section 2.2.4.2.2. The Broker 1176 accepts reauthentication requests if the Client has already submitted 1177 a token (may be expired), for which it performed proof-of-possession. 1178 Otherwise, the Broker MUST deny the request. If the reauthentication 1179 fails, the Broker MUST send a DISCONNECT with the reason code 0x87 1180 (Not Authorized). 1182 5. Handling Disconnections and Retained Messages 1184 In the case of a Client DISCONNECT, if the Session Expiry Interval is 1185 set to 0, the Broker doesn't maintain session state but MUST keep the 1186 retained messages. If the Broker maintains session state, the state 1187 MAY include the token and its introspection result (for reference 1188 tokens) in addition to the MQTT session state. The MQTT session 1189 state is identified by the Client Identifier and includes the 1190 following: 1192 * Client subscription state, 1194 * messages with QoS levels 1 and 2, and which have not been 1195 completely acknowledged or are pending transmission to the Client, 1196 and 1198 * if the Session is currently not connected, the time at which the 1199 Session will end and Session State will be discarded. 1201 The token/introspection state is not part of the MQTT session state, 1202 and PoP validation is required for each new connection, regardless of 1203 whether MQTT session continuation is used. 1205 The messages to be retained are indicated to the Broker by setting a 1206 RETAIN flag in a PUBLISH packet. This way, the publisher signals to 1207 the Broker to store the most recent message for the associated topic. 1208 Hence, the new subscribers can receive the last sent message from the 1209 publisher for that particular topic without waiting for the next 1210 PUBLISH packet. The Broker MUST continue publishing the retained 1211 messages as long as the associated tokens are valid. In the MQTT 1212 standard, if QoS is 0 for the PUBLISH packet, the Broker may discard 1213 the retained message any time. For QoS>1, the message expiry 1214 interval dictates how long the retained message is kept. However, it 1215 is important that the Broker avoids sending messages indefinitely for 1216 the Clients that never update their tokens (i.e., the Client connects 1217 briefly with a valid token, sends a PUBLISH packet with RETAIN flag 1218 set to 1 and QoS>1, disconnects, and never connects again). 1219 Therefore, the Broker MUST use the minimum of token expiry and 1220 message expiry interval to discard a retained message. 1222 In case of disconnections due to network errors or server 1223 disconnection due to a protocol error (which includes authorization 1224 errors), the Will message is sent if the Client supplied a Will in 1225 the CONNECT packet. The Client's token scope array MUST include the 1226 Will Topic. The Will message MUST be published to the Will Topic 1227 regardless of whether the corresponding token has expired (as it has 1228 been validated and accepted during CONNECT). 1230 6. Reduced Protocol Interactions for MQTT v3.1.1 1232 This section describes a reduced set of protocol interactions for the 1233 MQTT v3.1.1 Clients. An MQTT v5.0 Broker MAY implement these 1234 interactions for the MQTT v3.1.1 Clients; The flows described in this 1235 section are NOT RECOMMENDED for use by MQTT v5.0 Clients. Brokers 1236 that do not support MQTT v3.1.1 Clients return a CONNACK packet with 1237 Reason Code 0x84 (Unsupported Protocol Version) in response to the 1238 connection requests. 1240 6.1. Token Transport 1242 As in MQTT v5.0, the token MAY either be transported before, by 1243 publishing to the "authz-info" topic, or inside the CONNECT packet. 1244 If the Client provided the token via the "authz-info" topic and will 1245 not update the token in the CONNECT packet, it MUST authenticate over 1246 TLS. The Broker SHOULD still be prepared to store the Client access 1247 token for future use (regardless of the method of transport). 1249 In MQTT v3.1.1, after the Client has published to the "authz-info" 1250 topic, the Broker cannot communicate the result of the token 1251 validation because PUBACK reason codes or server-side DISCONNECT 1252 packets are not supported. In any case, the subsequent TLS handshake 1253 would fail without a valid token, which can prompt the Client to 1254 obtain a valid token. 1256 To transport the token to the Broker inside the CONNECT packet, the 1257 Client uses the username and password fields. Figure 11 shows the 1258 structure of the MQTT CONNECT packet. 1260 0 8 16 1261 +---------------------------+ 1262 |Protocol name length = 4 | 1263 +---------------------------+ 1264 | 'M' 'Q' | 1265 +---------------------------+ 1266 | 'T' 'T' | 1267 +---------------------------+ 1268 |Proto.level=5|Connect flags| 1269 +---------------------------+ 1270 | Keep alive | 1271 +---------------------------+ 1272 | Payload | 1273 | Client Identifier | 1274 | (UTF-8 encoded string) | 1275 | Username as access token | 1276 | (UTF-8 encoded string) | 1277 | Password for signature/MAC| 1278 | (Binary Data) | 1279 +---------------------------+ 1281 Figure 11: MQTT CONNECT Variable Header Using Username and 1282 Password for ACE 1284 Figure 12 shows how the MQTT connect flags MUST be set to initiate a 1285 connection with the Broker. 1287 +-----------------------------------------------------------+ 1288 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 1289 | flag |flag | | | | | | 1290 +-----------------------------------------------------------+ 1291 | 1 | 1 | X | X X | X | X | 0 | 1292 +-----------------------------------------------------------+ 1294 Figure 12: MQTT CONNECT Flags (Rsvd=Reserved) 1296 The Client SHOULD set the Clean flag to 1 to always start a new 1297 session. If the Clean flag is set to 0, the Broker MUST resume 1298 communications with the Client based on the state from the current 1299 Session (as identified by the Client Identifier). If there is no 1300 Session associated with the Client Identifier, the Broker MUST create 1301 a new session. The Broker MUST set the Session Present flag in the 1302 CONNACK packet accordingly, i.e., 0 to indicate a clean session to 1303 the Client and 1 to indicate session continuation. The Broker MUST 1304 still perform PoP validation on the provided Client token. MQTT 1305 v3.1.1 does not use a Session Expiry Interval, and the Client expects 1306 that the Broker maintains the session state after it disconnects. 1307 However, stored Session state can be discarded as a result of 1308 administrator action or policies (e.g. defining an automated response 1309 based on storage capabilities), and Brokers SHOULD implement 1310 administrative policies to limit misuse. 1312 The Client MAY set the Will Flag as desired (marked as "X" in 1313 Figure 12). Username and Password flags MUST be set to 1 to ensure 1314 that the Payload of the CONNECT packet includes both Username and 1315 Password fields. The MQTT Username is a UTF-8 encoded string, and 1316 the MQTT Password is Binary Data. 1318 The CONNECT in MQTT v3.1.1 does not have a field to indicate the 1319 authentication method. To signal that the Username field contains an 1320 ACE token, this field MUST be prefixed with "ace" keyword, i.e., the 1321 Username field is a concatenation of 'a', 'c', 'e' and the access 1322 token represented as: 1324 'U+0061'||'U+0063'||'U+0065'||UTF-8(access token) 1326 Figure 13: Username in CONNECT 1328 To this end, the access token MUST be base64url encoded, omitting the 1329 '=' padding characters [RFC4648]. 1331 The password field MUST be set to the keyed message digest (MAC) or 1332 signature associated with the access token for PoP. The Client MUST 1333 apply the PoP key on the challenge derived from the TLS session as 1334 described in Section 2.2.4.2.1. 1336 6.2. Handling Authorization Errors 1338 Error handling is more primitive in MQTT v3.1.1 due to not having 1339 appropriate error fields, error codes, and server-side DISCONNECTs. 1340 Therefore, the Broker will disconnect on almost any error and may not 1341 keep the session state, necessitating that clients make a greater 1342 effort to ensure that tokens remain valid and do not attempt to 1343 publish to topics that they do not have permissions for. The 1344 following lists how the Broker responds to specific errors. 1346 * CONNECT without a token: The tokenless CONNECT attempt MUST fail. 1347 This is because the challenge-response based PoP is not possible 1348 for MQTT v3.1.1. It is also not possible to support AS discovery 1349 since a CONNACK packet in MQTT v3.1.1 does not include a means to 1350 provide additional information to the Client. Therefore, AS 1351 discovery needs to take place out-of-band. 1353 * Client-Broker PUBLISH authorization failure: In the case of a 1354 failure, it is not possible to return an error in MQTT v3.1.1. 1355 Acknowledgment messages only indicate success. In the case of an 1356 authorization error, the Broker MUST ignore the PUBLISH packet and 1357 disconnect the Client. Also, as DISCONNECT packets are only sent 1358 from a Client to the Broker, the server disconnection needs to 1359 take place below the application layer. 1361 * SUBSCRIBE authorization failure: In the SUBACK packet, the return 1362 code is 0x80 indicating failure for the unauthorized topic(s). 1363 Note that, in both MQTT versions, a reason code is returned for 1364 each Topic Filter. 1366 * Broker-Client PUBLISH authorization failure: When the Broker is 1367 forwarding PUBLISH packets to the subscribed Clients, it may 1368 discover that some of the subscribers are no longer authorized due 1369 to expired tokens. These token expirations MUST lead to 1370 disconnecting the Client rather than silently dropping messages. 1372 7. IANA Considerations 1374 Note to RFC Editor: Please replace all occurrences of "[this 1375 document]" with the RFC number of this specification and delete this 1376 paragraph. 1378 7.1. TLS Exporter Label Registration 1380 This document registers "EXPORTER-ACE-MQTT-Sign-Challenge" 1381 (introduced in Section 2.2.4.2.1 in this document) in the TLS 1382 Exporter Label Registry [RFC8447]. 1384 * Recommended: No 1386 * DTLS-OK: No 1388 * Reference: [This document] 1390 7.2. Media Type Registration 1392 This document registers the "application/ace+json" media type for 1393 messages of the protocols defined in this document carrying 1394 parameters encoded in JSON. 1396 * Type name: application 1398 * Subtype name: ace+json 1400 * Required parameters: N/A 1402 * Optional parameters: N/A 1403 * Encoding considerations: Encoding considerations are identical to 1404 those specified for the "application/json" media type. 1406 * Security considerations: Section 8 of [this document] 1408 * Interoperability considerations: none 1410 * Published specification: [this document] 1412 * Applications that use this media type: This media type is intended 1413 for authorization server-client and authorization server-resource 1414 server communication as part of the ACE framework using JSON 1415 encoding as specified in [this document]. 1417 * Fragment identifier considerations: none 1419 * Additional information: 1421 - Deprecated alias names for this type: none 1423 - Magic number(s): none 1425 - File extension(s): none 1427 - Macintosh file type code(s): none 1429 * Person & email address to contact for further information: Cigdem 1430 Sengul (csengul@acm.org) 1432 * Intended usage: COMMON 1434 * Restrictions on usage: none 1436 * Author: Cigdem Sengul (csengul@acm.org) 1438 * Change controller: IETF 1440 * Provisional registration? (standards tree only): no 1442 7.3. ACE OAuth Profile Registration 1444 The following registrations are done for the ACE OAuth Profile 1445 Registry following the procedure specified in 1446 [I-D.ietf-ace-oauth-authz]. 1448 * Name: mqtt_tls 1449 * Description: Profile for delegating Client authentication and 1450 authorization using MQTT for the Client and Broker (RS) 1451 interactions, and HTTP for the AS interactions. TLS is used for 1452 confidentiality and integrity protection and server 1453 authentication. Client authentication can be provided either via 1454 TLS or using in-band PoP validation at the MQTT application layer. 1456 * CBOR Value: To be assigned by IANA in the (-256, 255) range 1458 * Reference: [this document] 1460 7.4. AIF 1462 For the media-types application/aif+cbor and application/aif+json 1463 defined in Section 5.1 of [I-D.ietf-ace-aif], IANA is requested to 1464 register the following entries for the two media-type parameters Toid 1465 and Tperm, in the respective sub-registry defined in Section 5.2 of 1466 [I-D.ietf-ace-aif] within the "MIME Media Type Sub-Parameter" 1467 registry group. 1469 For Toid: 1471 * Name: mqtt-topic-filter 1473 * Description/Specification: Topic Filter as defined in Section 2.3. 1475 * Reference: [[This document]] (Section 2.3) 1477 For Tperm: 1479 * Name: mqtt-permissions 1481 * Description/Specification: Permissions for MQTT client as defined 1482 in Section 2.3. Tperm is an array of one or more text strings 1483 that each have a value of either "pub" or "sub". 1485 * Reference: [[This document]] (Section 2.3) 1487 8. Security Considerations 1489 This document specifies a profile for the Authentication and 1490 Authorization for Constrained Environments (ACE) framework 1491 [I-D.ietf-ace-oauth-authz]. Therefore, the security considerations 1492 outlined in [I-D.ietf-ace-oauth-authz] apply to this work. 1494 In addition, the security considerations outlined in MQTT v5.0 - the 1495 OASIS Standard [MQTT-OASIS-Standard-v5] and MQTT v3.1.1 - the OASIS 1496 Standard [MQTT-OASIS-Standard-v3.1.1] apply. Mainly, this document 1497 provides an authorization solution for MQTT, the responsibility of 1498 which is left to the specific implementation in the MQTT standards. 1499 In the following, we comment on a few relevant issues based on the 1500 current MQTT specifications. 1502 After the Broker validates an access token and accepts a connection 1503 from a client, it caches the token to authorize a Client's publish 1504 and subscribe requests in an ongoing session. The Broker does not 1505 cache any tokens that cannot be validated. If a Client's permissions 1506 get revoked, but the access token has not expired, the Broker may 1507 still grant publish/subscribe to revoked topics. If the Broker 1508 caches the token introspection responses, then the Broker SHOULD use 1509 a reasonable cache timeout to introspect tokens regularly. The 1510 timeout value is application-specific and should be chosen to reduce 1511 the risk of using stale introspection responses. When permissions 1512 change dynamically, it is expected that AS also follows a reasonable 1513 expiration strategy for the access tokens. 1515 The Broker may monitor Client behaviour to detect potential security 1516 problems, especially those affecting availability. These include 1517 repeated token transfer attempts to the public "authz-info" topic, 1518 repeated connection attempts, abnormal terminations, and Clients that 1519 connect but do not send any data. If the Broker supports the public 1520 "authz-info" topic, described in Section 2.2.2, then this may be 1521 vulnerable to a DDoS attack, where many Clients use the "authz-info" 1522 public topic to transport tokens that are not meant to be used, and 1523 which the Broker may need to store until the tokens expire. 1525 For MQTT v5.0, when a Client connects with a long Session Expiry 1526 Interval, the Broker may need to maintain the Client's MQTT session 1527 state after it disconnects for an extended period. For MQTT v3.1.1, 1528 the session state may need to be stored indefinitely, as it does not 1529 have a Session Expiry Interval feature. The Broker SHOULD implement 1530 administrative policies to limit misuse of the session continuation 1531 by the Client. 1533 9. Privacy Considerations 1535 The privacy considerations outlined in [I-D.ietf-ace-oauth-authz] 1536 apply to this work. 1538 In MQTT, the Broker is a central trusted party and may forward 1539 potentially sensitive information between Clients. The mechanisms 1540 defined in this document do not protect the contents of the PUBLISH 1541 packet from the Broker, and hence, the content of the PUBLISH packet 1542 is not signed or encrypted separately for the subscribers. This 1543 functionality may be implemented using the proposal outlined in the 1544 ACE Pub-Sub Profile [I-D.ietf-ace-pubsub-profile]. However, this 1545 solution would still not provide privacy for other fields of the 1546 packet, such as Topic Name. 1548 10. References 1550 10.1. Normative References 1552 [I-D.ietf-ace-aif] 1553 Bormann, C., "An Authorization Information Format (AIF) 1554 for ACE", Work in Progress, Internet-Draft, draft-ietf- 1555 ace-aif-07, 15 March 2022, 1556 . 1559 [I-D.ietf-ace-dtls-authorize] 1560 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 1561 L. Seitz, "Datagram Transport Layer Security (DTLS) 1562 Profile for Authentication and Authorization for 1563 Constrained Environments (ACE)", Work in Progress, 1564 Internet-Draft, draft-ietf-ace-dtls-authorize-18, 4 June 1565 2021, . 1568 [I-D.ietf-ace-extend-dtls-authorize] 1569 Bergmann, O., Mattsson, J. P., and G. Selander, "Extension 1570 of the CoAP-DTLS Profile for ACE to TLS", Work in 1571 Progress, Internet-Draft, draft-ietf-ace-extend-dtls- 1572 authorize-02, 7 March 2022, 1573 . 1576 [I-D.ietf-ace-oauth-authz] 1577 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1578 H. Tschofenig, "Authentication and Authorization for 1579 Constrained Environments (ACE) using the OAuth 2.0 1580 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 1581 draft-ietf-ace-oauth-authz-46, 8 November 2021, 1582 . 1585 [I-D.ietf-ace-oauth-params] 1586 Seitz, L., "Additional OAuth Parameters for Authorization 1587 in Constrained Environments (ACE)", Work in Progress, 1588 Internet-Draft, draft-ietf-ace-oauth-params-16, 7 1589 September 2021, . 1592 [I-D.ietf-cose-x509] 1593 Schaad, J., "CBOR Object Signing and Encryption (COSE): 1594 Header parameters for carrying and referencing X.509 1595 certificates", Work in Progress, Internet-Draft, draft- 1596 ietf-cose-x509-08, 14 December 2020, 1597 . 1600 [I-D.ietf-httpbis-semantics] 1601 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1602 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1603 httpbis-semantics-19, 12 September 2021, 1604 . 1607 [MQTT-OASIS-Standard-v3.1.1] 1608 Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT 1609 Version 3.1.1 Plus Errata 01", 2015, . 1612 [MQTT-OASIS-Standard-v5] 1613 Banks, A., Ed., Briggs, E., Ed., Borgendale, K., Ed., and 1614 R. Gupta, Ed., "OASIS Standard MQTT Version 5.0", 2017, 1615 . 1618 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1619 Requirement Levels", BCP 14, RFC 2119, 1620 DOI 10.17487/RFC2119, March 1997, 1621 . 1623 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1624 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1625 . 1627 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 1628 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 1629 March 2010, . 1631 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1632 Extensions: Extension Definitions", RFC 6066, 1633 DOI 10.17487/RFC6066, January 2011, 1634 . 1636 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1637 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1638 DOI 10.17487/RFC6234, May 2011, 1639 . 1641 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1642 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1643 . 1645 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 1646 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 1647 Transport Layer Security (TLS) and Datagram Transport 1648 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 1649 June 2014, . 1651 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1652 "Transport Layer Security (TLS) Application-Layer Protocol 1653 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1654 July 2014, . 1656 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 1657 RFC 7516, DOI 10.17487/RFC7516, May 2015, 1658 . 1660 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 1661 DOI 10.17487/RFC7517, May 2015, 1662 . 1664 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1665 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1666 . 1668 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 1669 Langley, A., and M. Ray, "Transport Layer Security (TLS) 1670 Session Hash and Extended Master Secret Extension", 1671 RFC 7627, DOI 10.17487/RFC7627, September 2015, 1672 . 1674 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1675 Possession Key Semantics for JSON Web Tokens (JWTs)", 1676 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1677 . 1679 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 1680 Signature Algorithm (EdDSA)", RFC 8032, 1681 DOI 10.17487/RFC8032, January 2017, 1682 . 1684 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1685 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1686 . 1688 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1689 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1690 May 2017, . 1692 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 1693 Curve Cryptography (ECC) Cipher Suites for Transport Layer 1694 Security (TLS) Versions 1.2 and Earlier", RFC 8422, 1695 DOI 10.17487/RFC8422, August 2018, 1696 . 1698 [RFC8442] Mattsson, J. and D. Migault, "ECDHE_PSK with AES-GCM and 1699 AES-CCM Cipher Suites for TLS 1.2 and DTLS 1.2", RFC 8442, 1700 DOI 10.17487/RFC8442, September 2018, 1701 . 1703 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1704 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1705 . 1707 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1708 Definition Language (CDDL): A Notational Convention to 1709 Express Concise Binary Object Representation (CBOR) and 1710 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1711 June 2019, . 1713 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 1714 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 1715 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 1716 2020, . 1718 10.2. Informative References 1720 [fremantle14] 1721 Fremantle, P., Aziz, B., Kopecky, J., and P. Scott, 1722 "Federated Identity and Access Management for the Internet 1723 of Things", research International Workshop on Secure 1724 Internet of Things, September 2014, 1725 . 1727 [I-D.ietf-ace-pubsub-profile] 1728 Palombini, F. and C. Sengul, "Pub-Sub Profile for 1729 Authentication and Authorization for Constrained 1730 Environments (ACE)", Work in Progress, Internet-Draft, 1731 draft-ietf-ace-pubsub-profile-04, 29 December 2021, 1732 . 1735 [I-D.ietf-tls-rfc8446bis] 1736 Rescorla, E., "The Transport Layer Security (TLS) Protocol 1737 Version 1.3", Work in Progress, Internet-Draft, draft- 1738 ietf-tls-rfc8446bis-04, 7 March 2022, 1739 . 1742 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1743 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1744 . 1746 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1747 Application Protocol (CoAP)", RFC 7252, 1748 DOI 10.17487/RFC7252, June 2014, 1749 . 1751 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1752 "Recommendations for Secure Use of Transport Layer 1753 Security (TLS) and Datagram Transport Layer Security 1754 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1755 2015, . 1757 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1758 Security (TLS) / Datagram Transport Layer Security (DTLS) 1759 Profiles for the Internet of Things", RFC 7925, 1760 DOI 10.17487/RFC7925, July 2016, 1761 . 1763 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1764 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1765 May 2018, . 1767 [RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS 1768 and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018, 1769 . 1771 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1772 Representation (CBOR)", STD 94, RFC 8949, 1773 DOI 10.17487/RFC8949, December 2020, 1774 . 1776 Appendix A. Checklist for profile requirements 1778 Based on the requirements on profiles for the ACE framework 1779 [I-D.ietf-ace-oauth-authz], this document fulfills the following: 1781 * Optional AS discovery: AS discovery is supported with the MQTT 1782 v5.0 described in Section 2.2. 1784 * The communication protocol between the Client and Broker (RS): 1785 MQTT 1787 * The security protocol between the Client and RS: TLS 1789 * Client and RS mutual authentication: Several options are possible 1790 and described in Section 2.2.1. 1792 * Proof-of-possession protocols: Specified in Section 2.2.4.2; both 1793 symmetric and asymmetric keys supported. 1795 * Content format: For the HTTPS interactions with AS, "application/ 1796 ace+json". 1798 * Unique profile identifier: mqtt_tls 1800 * Token introspection: RS uses HTTPS introspect interface of AS. 1802 * Token request: Client or its Client AS uses the HTTPS token 1803 endpoint of the AS. 1805 * authz-info endpoint: It MAY be supported using the method 1806 described in Section 2.2.2, but is not protected other than by the 1807 TLS channel between Client and RS. 1809 * Token transport: Via "authz-info" topic, or TLS with PSK, provided 1810 as a PSK identity, or in MQTT CONNECT packet for both versions of 1811 MQTT. The AUTH extensions can also be used for authentication and 1812 re-authentication for MQTT v5.0, as described in Section 2.2 and 1813 Section 4. 1815 Appendix B. Document Updates 1817 Version 15: Addressing GENART review comments. 1819 Version 11 to 15: Addressing AD review comments. 1821 Version 10 to 11: Clarified the TLS use between RS-AS and Client-AS. 1823 Version 09 to 10: Fixed version issues for references. 1825 Version 08 to 09: Fixed spacing issues and references. 1827 Version 07 to 08: 1829 * Fixed several nits, typos based on WG reviews. 1831 * Added missing references. 1833 * Added the definition for Property defined by MQTT, and Client 1834 Authorization Server. 1836 * Added artwork to show Authorization Data format for various PoP- 1837 related message exchange. 1839 * Removed all MQTT-related must/should/may. 1841 * Made AS discovery optional. 1843 * Clarified what the client and server must implement for client 1844 authentication; cleaned up TLS 1.3 related language. 1846 Version 06 to 07: 1848 * Corrected the title. 1850 * In Section 2.2.3, added the constraint on which packets the Client 1851 can send, and the server can process after CONNECT before CONNACK. 1853 * In Section 2.2.3, clarified that session state is identified by 1854 Client Identifier, and listed its content. 1856 * In Section 2.2.3, clarified the issue of Client Identifier 1857 collision, when the Broker supports session continuation. 1859 * Corrected the buggy scope example in Section 3.1. 1861 Version 05 to 06: 1863 * Replace the originally proposed scope format with AIF model. 1864 Defined the AIF-MQTT, gave an example with a JSON array. Added a 1865 normative reference to the AIF draft. 1867 * Clarified client connection after submitting token via "authz- 1868 info" topic as TLS:Known(RPK/PSK),MQTT:none. 1870 * Expanded acronyms on their first use including the ones in the 1871 title. 1873 * Added a definition for "Session". 1875 * Corrected "CONNACK" definition, which earlier said it's the first 1876 packet sent by the Broker. 1878 * Added a statement that the Broker will disconnect on almost any 1879 error and may not keep session state. 1881 * Clarified that the Broker does not cache tokens that cannot be 1882 validated. 1884 Version 04 to 05: 1886 * Reorganised Section 2 such that "Unauthorized Request: 1887 Authorization Server Discovery" is presented under Section 2. 1889 * Fixed Figure 2 to remove the "empty" word. 1891 * Clarified that MQTT v5.0 Brokers may implement username/password 1892 option for transporting the ACE token only for MQTT v.3.1.1 1893 clients. This option is not recommended for MQTT v.5.0 clients. 1895 * Changed Clean Session requirement both for MQTT v.5.0 and v.3.1.1. 1896 The Broker SHOULD NOT, instead of MUST NOT, continue sessions. 1897 Clarified expected behaviour if session continuation is supported. 1898 Added to the Security Considerations the potential misuse of 1899 session continuation. 1901 * Fixed the Authentication Data to include token length for the 1902 Challenge/Response PoP. 1904 * Added that Authorization Server Discovery is triggered if a token 1905 is not valid and not only missing. 1907 * Clarified that the Broker should not accept any other packets from 1908 Client after CONNECT and before sending CONNACK. 1910 * Added that client reauthentication is accepted only for the 1911 challenge/response PoP. 1913 * Added Ed25519 as mandatory to implement. 1915 * Fixed typos. 1917 Version 03 to 04: 1919 * Linked the terms Broker and MQTT server more at the introduction 1920 of the document. 1922 * Clarified support for MQTTv3.1.1 and removed phrases that might be 1923 considered as MQTTv5 is backwards compatible with MQTTv3.1.1 1925 * Corrected the Informative and Normative references. 1927 * For AS discovery, clarified the CONNECT message omits the 1928 Authentication Data field. Specified the User Property MUST be 1929 set to "ace_as_hint" for AS Request Creation Hints. 1931 * Added that MQTT v5 brokers MAY also implement reduced interactions 1932 described for MQTTv3.1.1. 1934 * Added to Section 3.1, in case of an authorization failure and QoS 1935 level 0, the RS sends a DISCONNECT with reason code 0x87 (Not 1936 authorized). 1938 * Added a pointer to section 4.7 of MQTTv5 spec for more information 1939 on topic names and filters. 1941 * Added HS256 and RSA256 are mandatory to implement depending on the 1942 choice of symmetric or asymmetric validation. 1944 * Added MQTT to the TLS exporter label to make it application 1945 specific: 'EXPORTER-ACE-MQTT-Sign-Challenge'. 1947 * Added a format for Authentication Data so that length values 1948 prefix the token (or client nonce) when Authentication Data 1949 contains more than one piece of information. 1951 * Clarified clients still connect over TLS (server-side) for the 1952 authz-info flow. 1954 Version 02 to 03: 1956 * Added the option of Broker certificate thumbprint in the 'rs_cnf' 1957 sent to the Client. 1959 * Clarified the use of a random nonce from the TLS Exporter for PoP, 1960 added to the IANA requirements that the label should be 1961 registered. 1963 * Added a client nonce, when Challenge/Response Authentication is 1964 used between Client and Broker. 1966 * Clarified the use of the "authz-info" topic and the error response 1967 if token validation fails. 1969 * Added clarification on wildcard use in scopes for publish/ 1970 subscribe permissions 1972 * Reorganised sections so that token authorization for publish/ 1973 subscribe messages are better placed. 1975 Version 01 to 02: 1977 * Clarified protection of Application Message payload as out of 1978 scope, and cited draft-palombini-ace-coap-pubsub-profile for a 1979 potential solution 1981 * Expanded Client connection authorization to capture different 1982 options for Client and Broker authentication over TLS and MQTT 1984 * Removed Payload (and specifically Client Identifier) from proof- 1985 of-possession in favor of using tls-exporter for a TLS-session 1986 based challenge. 1988 * Moved token transport via "authz-info" topic from the Appendix to 1989 the main text. 1991 * Clarified Will scope. 1993 * Added MQTT AUTH to terminology. 1995 * Typo fixes, and simplification of figures. 1997 Version 00 to 01: 1999 * Present the MQTTv5 as the RECOMMENDED version, and MQTT v3.1.1 for 2000 backward compatibility. 2002 * Clarified Will message. 2004 * Improved consistency in the use of terminology and upper/lower 2005 case. 2007 * Defined Broker and MQTTS. 2009 * Clarified HTTPS use for C-AS and RS-AS communication. Removed 2010 reference to actors document, and clarified the use of client 2011 authorization server. 2013 * Clarified the Connect message payload and Client Identifier. 2015 * Presented different methods for passing the token and PoP. 2017 * Added new figures to explain AUTH packets exchange, updated 2018 CONNECT message figure. 2020 Acknowledgments 2022 The authors would like to thank Ludwig Seitz for his review and his 2023 input on the authorization information endpoint; Benjamin Kaduk for 2024 his review, insightful comments, and contributions to resolving 2025 issues; and Carsten Bormann for his review and revisions to the AIF- 2026 MQTT data model. The authors would like to thank Paul Fremantle for 2027 the initial discussions on MQTT v5.0 support. 2029 Authors' Addresses 2031 Cigdem Sengul 2032 Brunel University 2033 Dept. of Computer Science 2034 Uxbridge 2035 UB8 3PH 2036 United Kingdom 2037 Email: csengul@acm.org 2039 Anthony Kirby 2040 Oxbotica 2041 1a Milford House, Mayfield Road, Summertown 2042 Oxford 2043 OX2 7EL 2044 United Kingdom 2045 Email: anthony@anthony.org