idnits 2.17.1 draft-ietf-ace-mqtt-tls-profile-10.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 copyright year in the IETF Trust and authors Copyright Line does not match the current year == 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 (December 18, 2020) is 1196 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC-XXXX' is mentioned on line 1095, but not defined == Outdated reference: A later version (-07) exists of draft-ietf-ace-aif-00 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-36 == Outdated reference: A later version (-16) exists of draft-ietf-ace-oauth-params-13 == Outdated reference: A later version (-09) exists of draft-ietf-cose-x509-08 -- Possible downref: Non-RFC (?) normative reference: ref. 'MQTT-OASIS-Standard' -- Possible downref: Non-RFC (?) normative reference: ref. 'MQTT-OASIS-Standard-v5' ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) == Outdated reference: A later version (-18) exists of draft-ietf-ace-dtls-authorize-14 == Outdated reference: A later version (-09) exists of draft-ietf-ace-pubsub-profile-01 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group C. Sengul 3 Internet-Draft Brunel University 4 Intended status: Standards Track A. Kirby 5 Expires: June 21, 2021 Oxbotica 6 December 18, 2020 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-10 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 June 21, 2021. 39 Copyright Notice 41 Copyright (c) 2020 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 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 58 1.2. ACE-Related Terminology . . . . . . . . . . . . . . . . . 4 59 1.3. MQTT-Related Terminology . . . . . . . . . . . . . . . . 5 60 2. Authorizing Connection Requests . . . . . . . . . . . . . . . 7 61 2.1. Client Token Request to the Authorization Server (AS) . . 8 62 2.2. Client Connection Request to the Broker (C) . . . . . . . 9 63 2.2.1. Client-Server Authentication over TLS and MQTT . . . 9 64 2.2.2. authz-info: The Authorization Information Topic . . . 10 65 2.2.3. Transporting Access Token Inside the MQTT CONNECT . . 11 66 2.2.4. Authentication Using AUTH Property . . . . . . . . . 14 67 2.2.4.1. Proof-of-Possession Using a Challenge from the 68 TLS session . . . . . . . . . . . . . . . . . . . 14 69 2.2.4.2. Proof-of-Possession via Broker-generated 70 Challenge/Response . . . . . . . . . . . . . . . 15 71 2.2.5. Token Validation . . . . . . . . . . . . . . . . . . 16 72 2.2.6. The Broker's Response to Client Connection Request . 16 73 2.2.6.1. Unauthorised Request and the Optional 74 Authorisation Server Discovery . . . . . . . . . 17 75 2.2.6.2. Authorisation Success . . . . . . . . . . . . . . 17 76 3. Authorizing PUBLISH and SUBSCRIBE Messages . . . . . . . . . 17 77 3.1. PUBLISH Messages from the Publisher Client to the Broker 18 78 3.2. PUBLISH Messages from the Broker to the Subscriber 79 Clients . . . . . . . . . . . . . . . . . . . . . . . . . 19 80 3.3. Authorizing SUBSCRIBE Messages . . . . . . . . . . . . . 19 81 4. Token Expiration, Update and Reauthentication . . . . . . . . 20 82 5. Handling Disconnections and Retained Messages . . . . . . . . 20 83 6. Reduced Protocol Interactions for MQTT v3.1.1 . . . . . . . . 21 84 6.1. Token Transport . . . . . . . . . . . . . . . . . . . . . 21 85 6.2. Handling Authorization Errors . . . . . . . . . . . . . . 22 86 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 87 8. Security Considerations . . . . . . . . . . . . . . . . . . . 24 88 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 25 89 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 90 10.1. Normative References . . . . . . . . . . . . . . . . . . 25 91 10.2. Informative References . . . . . . . . . . . . . . . . . 27 92 Appendix A. Checklist for profile requirements . . . . . . . . . 28 93 Appendix B. Document Updates . . . . . . . . . . . . . . . . . . 29 94 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 97 1. Introduction 99 This document specifies a profile for the ACE framework 100 [I-D.ietf-ace-oauth-authz]. In this profile, Clients and Servers 101 (Brokers) use MQTT to exchange Application Messages. The protocol 102 relies on TLS for communication security between entities. The MQTT 103 protocol interactions are described based on the MQTT v5.0 - the 104 OASIS Standard [MQTT-OASIS-Standard-v5]. Since it is expected that 105 MQTT deployments will continue to support MQTT v3.1.1 clients, this 106 document also describes a reduced set of protocol interactions for 107 MQTT v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard]. However, 108 MQTT v5.0 is the RECOMMENDED version as it works more naturally with 109 ACE-style authentication and authorization. 111 MQTT is a publish-subscribe protocol and after connecting to the MQTT 112 Server (Broker), a Client can publish and subscribe to multiple 113 topics. The Broker, which acts as the Resource Server (RS), is 114 responsible for distributing messages published by the publishers to 115 their subscribers. In the rest of the document the terms "RS", "MQTT 116 Server" and "Broker" are used interchangeably. 118 Messages are published under a Topic Name, and subscribers subscribe 119 to the Topic Names to receive the corresponding messages. The Broker 120 uses the Topic Name in a published message to determine which 121 subscribers to relay the messages. In this document, topics, more 122 specifically, Topic Names, are treated as resources. The Clients are 123 assumed to have identified the publish/subscribe topics of interest 124 out-of-band (topic discovery is not a feature of the MQTT protocol). 125 A Resource Owner can pre-configure policies at the Authorisation 126 Server (AS) that give Clients publish or subscribe permissions to 127 different topics. 129 Clients prove their permission to publish and subscribe to topics 130 hosted on an MQTT broker using an access token, bound to a proof-of- 131 possession (PoP) key. This document describes how to authorize the 132 following exchanges between the Clients and the Broker. 134 o Connection requests from the Clients to the Broker 136 o Publish requests from the Clients to the Broker, and from the 137 Broker to the Clients 139 o Subscribe requests from Clients to the Broker 141 Clients use MQTT PUBLISH message to publish to a topic. This 142 document does not protect the payload of the PUBLISH message from the 143 Broker. Hence, the payload is not signed or encrypted specifically 144 for the subscribers. This functionality MAY be implemented using the 145 proposal outlined in the ACE Pub-Sub Profile 146 [I-D.ietf-ace-pubsub-profile]. 148 To provide communication confidentiality and RS authentication, TLS 149 is used, and TLS 1.3 [RFC8446] is RECOMMENDED. This document makes 150 the same assumptions as Section 4 of the ACE framework 151 [I-D.ietf-ace-oauth-authz] regarding Client and RS registration with 152 the AS and setting up keying material. While the Client-Broker 153 exchanges are only over MQTT, the required Client-AS and RS-AS 154 interactions are described for HTTPS-based communication [RFC7230], 155 using 'application/ace+json' content type, and unless otherwise 156 specified, using JSON encoding. The token MAY be a reference or JSON 157 Web Token (JWT) [RFC7519]. For JWTs, this document follows [RFC7800] 158 for PoP semantics for JWTs. The Client-AS and RS-AS MAY also use 159 protocols other than HTTP, e.g. Constrained Application Protocol 160 (CoAP) [RFC7252] or MQTT. Implementations MAY also use "application/ 161 ace+cbor" content type, and CBOR encoding [RFC8949], and CBOR Web 162 Token (CWT) [RFC8392] and associated PoP semantics to reduce the 163 protocol memory and bandwidth requirements. For more information, 164 see Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs) 165 [RFC8747]. 167 1.1. Requirements Language 169 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 171 "OPTIONAL" in this document are to be interpreted as described in BCP 172 14 [RFC2119] [RFC8174], when, and only when, they appear in all 173 capitals, as shown here. 175 1.2. ACE-Related Terminology 177 Certain security-related terms such as "authentication", 178 "authorization", "confidentiality", "(data) integrity", "message 179 authentication code", and "verify" are taken from [RFC4949]. 181 The terminology for entities in the architecture is defined in OAuth 182 2.0 [RFC6749] such as "Client" (C), "Resource Server" (RS) and 183 "Authorization Server" (AS). 185 The term "resource" is used to refer to an MQTT Topic Name, which is 186 defined in Section 1.3. Hence, the "Resource Owner" is any entity 187 that can authoritatively speak for the topic. This document also 188 defines a Client Authorisation Server, for Clients that are not able 189 to support HTTP. 191 Client Authorization Server (CAS) 192 An entity that prepares and endorses authentication and 193 authorization data for a Client, and communicates using HTTPS 194 to the AS. 196 1.3. MQTT-Related Terminology 198 The document describes message exchanges as MQTT protocol 199 interactions. The Clients are MQTT Clients, which connect to the 200 Broker to publish and subscribe to Application Messages, labelled 201 with their topics. For additional information, please refer to the 202 MQTT v5.0 - the OASIS Standard [MQTT-OASIS-Standard-v5] or the MQTT 203 v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard]. 205 MQTTS 206 Secured transport profile of MQTT. MQTTS runs over TLS. 208 Broker 209 The Server in MQTT. It acts as an intermediary between the 210 Clients that publish Application Messages, and the Clients 211 that made Subscriptions. The Broker acts as the Resource 212 Server for the Clients. 214 Client 215 A device or program that uses MQTT. 217 Session 218 A stateful interaction between a Client and a Broker. Some 219 Sessions last only as long as the network connection, others 220 can span multiple network connections. 222 Application Message 223 The data carried by the MQTT protocol. The data has an 224 associated Quality-of-Service (QoS) level and a Topic Name. 226 QoS level 227 The level of assurance for the delivery of an Application 228 Message. The QoS level can be 0-2, where "0" indicates "At 229 most once delivery", "1" "At least once delivery", and "2" 230 "Exactly once delivery". 232 Property 233 The last field of the Variable Header is a set of properties 234 for several MQTT control messages (e.g. CONNECT, CONNACK) . 235 A Property consists of an Identifier which defines its usage 236 and data type, followed by a value. The Identifier is 237 encoded as a Variable Byte Integer. For example, 238 "Authentication Data" property with an Identifier 22. 240 Topic Name 241 The label attached to an Application Message, which is 242 matched to a Subscription. 244 Subscription 245 A Subscription comprises a Topic Filter and a maximum QoS. A 246 Subscription is associated with a single session. 248 Topic Filter 249 An expression that indicates interest in one or more Topic 250 Names. Topic Filters may include wildcards. 252 MQTT sends various control messages across a network connection. The 253 following is not an exhaustive list and the control packets that are 254 not relevant for authorization are not explained. These include, for 255 instance, the PUBREL and PUBCOMP packets used in the 4-step handshake 256 required for QoS level 2. 258 CONNECT 259 Client request to connect to the Broker. This is the first 260 packet sent by a Client. 262 CONNACK 263 The Broker connection acknowledgment. CONNACK packets 264 contain return codes indicating either a success or an error 265 state in response to a Client's CONNECT packet. 267 AUTH 268 Authentication Exchange. An AUTH control packet is sent from 269 the Client to the Broker or from the Broker to the Client as 270 part of an extended authentication exchange. AUTH Properties 271 include Authentication Method and Authentication Data. The 272 Authentication Method is set in the CONNECT packet, and 273 consequent AUTH packets follow the same Authentication 274 Method. The contents of the Authentication Data are defined 275 by the Authentication Method. 277 PUBLISH 278 Publish request sent from a publishing Client to the Broker, 279 or from the Broker to a subscribing Client. 281 PUBACK 282 Response to a PUBLISH request with QoS level 1. A PUBACK can 283 be sent from the Broker to a Client or from a Client to the 284 Broker. 286 PUBREC 287 Response to PUBLISH request with QoS level 2. PUBREC can be 288 sent from the Broker to a Client or from a Client to the 289 Broker. 291 SUBSCRIBE 292 Subscribe request sent from a Client. 294 SUBACK 295 Subscribe acknowledgment. 297 PINGREQ 298 A ping request sent from a Client to the Broker. It signals 299 to the Broker that the Client is alive, and is used to 300 confirm that the Broker is also alive. The "Keep Alive" 301 period is set in the CONNECT message. 303 PINGRESP 304 Response sent by the Broker to the Client in response to 305 PINGREQ. It indicates the Broker is alive. 307 Will 308 If the network connection is not closed normally, the Broker 309 sends a last Will message for the Client, if the Client 310 provided one in its CONNECT message. If the Will Flag is set 311 in the CONNECT flags, then the payload of the CONNECT message 312 includes information about the Will. The information 313 consists of the Will Properties, Will Topic, and Will Payload 314 fields. 316 2. Authorizing Connection Requests 318 This section specifies how Client connections are authorized by the 319 MQTT Broker. Figure 1 shows the basic protocol flow during 320 connection set-up. The token request and response use the token 321 endpoint at the AS, specified in Section 5.6 of the ACE framework 322 [I-D.ietf-ace-oauth-authz]. Steps (D) and (E) are optional and use 323 the introspection endpoint, specified in Section 5.7 of the ACE 324 framework. The Client and the Broker use HTTPS to communicate to AS 325 via these endpoints. The Client and the Broker use MQTT to 326 communicate between them. The C-AS and Broker-AS communication MAY 327 be implemented using protocols other than HTTPS, e.g. CoAP or MQTT. 329 If the Client is resource-constrained or does not support HTTPS, a 330 separate Client Authorisation Server may carry out the token request 331 on behalf of the Client, and later, onboard the Client with the 332 token. The interactions between a Client and its Client 333 Authorization Server for token onboarding, and support for MQTTS- 334 based token requests at the AS are out of scope of this document. 336 +---------------------+ 337 | Client | 338 | | 339 +---(A) Token request--| Client - | 340 | | Authorization | 341 | +-(B) Access token-> Server Interface | 342 | | | (HTTPS) | 343 | | |_____________________| 344 | | | | 345 +--v-------------+ | Pub/Sub Interface | 346 | Authorization | | (MQTTS) | 347 | Server | +-----------^---------+ 348 |________________| | | 349 | ^ (C)Connection (F)Connection 350 | | request + response 351 | | access token | 352 | | | | 353 | | +---v--------------+ 354 | | | Broker (MQTTS) | 355 | | |__________________| 356 | +(D)Introspection-| | 357 | request (optional) | RS-AS interface | 358 | | (HTTPS) | 359 +-(E)Introspection---->|__________________| 360 response (optional) 362 Figure 1: Connection set-up 364 2.1. Client Token Request to the Authorization Server (AS) 366 The first step in the protocol flow (Figure 1 (A)) is the token 367 acquisition by the Client from the AS. The Client and the AS MUST 368 perform mutual authentication. The Client requests an access token 369 from the AS as described in Section 5.6.1 of the ACE framework 370 [I-D.ietf-ace-oauth-authz]. The media format is 'application/ 371 ace+json'. The AS uses JSON in the payload of its responses to the 372 Client and the RS. 374 If the AS successfully verifies the access token request and 375 authorizes the Client for the indicated audience (i.e. RS) and 376 scopes (i.e. publish/subscribe permissions over topics as described 377 in Section 3), the AS issues an access token (Figure 1 (B)). The 378 response includes the parameters described in Section 5.6.2 of the 379 ACE framework [I-D.ietf-ace-oauth-authz], and specifically, the 380 "ace_profile" parameter is set to "mqtt_tls". The returned token is 381 a Proof-of-Possession (PoP) token by default. This document follows 382 [RFC7800] for PoP semantics for JWTs. The PoP token includes a 'cnf' 383 parameter with a symmetric or asymmetric PoP key. Note that the 384 'cnf' parameter in the web tokens are to be consumed by the RS and 385 not the Client. For the asymmetric case, the PoP token may include 386 the 'rs_cnf' parameter containing the information about the public 387 key to be used by the RS to authenticate as described in 388 [I-D.ietf-ace-oauth-params]. 390 The AS returns error responses for JSON-based interactions following 391 Section 5.2 of [RFC6749]. When CBOR is used, the interactions MUST 392 implement Section 5.6.3 of the ACE framework 393 [I-D.ietf-ace-oauth-authz]. 395 2.2. Client Connection Request to the Broker (C) 397 2.2.1. Client-Server Authentication over TLS and MQTT 399 The Client and the Broker MUST perform mutual authentication. The 400 Client MUST authenticate to the Broker either over MQTT or TLS. For 401 MQTT, the options are "None" and "ace". For TLS, the options are 402 "Anon" for an anonymous client, and "Known(RPK/PSK)" for Raw Public 403 Keys (RPK) [RFC7250] and Pre-Shared Keys (PSK), respectively. 404 Combined, client authentication has the following options: 406 o "TLS:Anon-MQTT:None": This option is used only for the topics that 407 do not require authorization, including the "authz-info" topic. 408 Publishing to the "authz-info" topic is described in 409 Section 2.2.2. 411 o "TLS:Anon-MQTT:ace": The token is transported inside the CONNECT 412 message, and MUST be validated using one of the methods described 413 in Section 2.2.2. This option also supports a tokenless 414 connection request for AS discovery. 416 o "TLS:Known(RPK/PSK)-MQTT:none": For the RPK, the token MUST have 417 been published to the "authz-info" topic. For the PSK, the token 418 MAY be, alternatively, provided as an "identity" in the 419 "identities" field in the client's "pre_shared_key" extension in 420 TLS 1.3. The TLS session set-up is as described in DTLS profile 421 for ACE [I-D.ietf-ace-dtls-authorize]. 423 o "TLS:Known(RPK/PSK)-MQTT:ace": This option SHOULD NOT be chosen as 424 the token transported in the CONNECT overwrites any permissions 425 passed during the TLS authentication. 427 It is RECOMMENDED that the Client implements "TLS:Anon-MQTT:ace" as a 428 first choice when working with protected topics. However, depending 429 on the Client capability, Client MAY implement "TLS:Known(RPK/PSK)- 430 MQTT:none", and consequently "TLS:Anon-MQTT:None" to submit its token 431 to "authz-info". 433 The Broker MUST support "TLS:Anon-MQTT:ace". To support Clients with 434 different capabilities, the Broker MAY provide multiple client 435 authentication options, e.g. support "TLS:Known(RPK)-MQTT:none" and 436 "TLS:Anon-MQTT:None", to enable RPK-based client authentication, but 437 fall back to "TLS:Anon-MQTT:ace" if the Client does not send a client 438 certificate (i.e. it sends an empty Certificate message) during the 439 TLS handshake. 441 The Broker MUST be authenticated during the TLS handshake. If the 442 Client authentication uses TLS:Known(RPK/PSK), then the Broker is 443 authenticated using the respective method. Otherwise, to 444 authenticate the Broker, the client MUST validate a public key from a 445 X.509 certificate or an RPK from the Broker against the 'rs_cnf' 446 parameter in the token response. The AS MAY include the thumbprint 447 of the RS's X.509 certificate in the 'rs_cnf' (thumbprint as defined 448 in [I-D.ietf-cose-x509]). In this case, the client MUST validate the 449 RS certificate against this thumbprint. 451 2.2.2. authz-info: The Authorization Information Topic 453 In the cases when the Client MUST transport the token to the Broker 454 first, the Client connects to the Broker to publish its token to the 455 "authz-info" topic. The "authz-info" topic MUST be publish-only 456 (i.e. the Clients are not allowed to subscribe to it). "authz-info" 457 is not protected, and hence, the Client uses the "TLS:Anon-MQTT:None" 458 option over a TLS connection. After publishing the token, the Client 459 disconnects from the Broker and is expected to reconnect using client 460 authentication over TLS (i.e. TLS:Known(RPK/PSK)-MQTT:none). 462 The Broker stores and indexes all tokens received to the "authz-info" 463 topic in its key store (similar to DTLS profile for ACE 464 [I-D.ietf-ace-dtls-authorize]). This profile follows the 465 recommendation of Section 5.8.1 of the ACE framework 466 [I-D.ietf-ace-oauth-authz], and expects that the Broker stores only 467 one token per proof-of-possession key, and any other token linked to 468 the same key overwrites an existing token. 470 The Broker MUST verify the validity of the token (i.e. through local 471 validation or introspection, if the token is a reference) as 472 described in Section 2.2.5. If the token is not valid, the Broker 473 MUST discard the token. Depending on the QoS level of the PUBLISH 474 message, the Broker returns the error response as a PUBACK or a 475 DISCONNECT message as explained below. 477 If the QoS level is equal to 0, and the token is invalid or the 478 claims cannot be obtained in the case of an introspected token, the 479 Broker MUST send a DISCONNECT message with the reason code '0x87 (Not 480 authorized)'. If the PUBLISH payload does not parse to a token, the 481 RS MUST send a DISCONNECT with the reason code '0x99 (Payload format 482 invalid)'. 484 If the QoS level of the PUBLISH message is greater than or equal to 485 1, the Broker MUST return 'Not authorized' in PUBACK. If the PUBLISH 486 payload does not parse to a token, the PUBACK reason code is '0x99 487 (Payload format invalid)'. 489 It must be noted that when the RS sends the 'Not authorized' 490 response, this corresponds to the token being invalid, and not that 491 the actual PUBLISH message was not authorized. Given that the 492 "authz-info" is a public topic, this response is not expected to 493 cause confusion. 495 2.2.3. Transporting Access Token Inside the MQTT CONNECT 497 This section describes how the Client transports the token to the 498 Broker (RS) inside the CONNECT message. If this method is used, the 499 Client TLS connection is expected to be anonymous, and the Broker is 500 authenticated during the TLS connection set-up. The approach 501 described in this section is similar to an earlier proposal by 502 Fremantle et al [fremantle14]. 504 After sending the CONNECT, the client MUST wait to receive the 505 CONNACK from the Broker. The only messages it is allowed to send are 506 DISCONNECT or AUTH that is in response to the Broker AUTH. 507 Similarly, the Broker MUST NOT process any packets before it has sent 508 a CONNACK. The only exceptions are DISCONNECT or an AUTH response 509 from the Client. 511 Figure 2 shows the structure of the MQTT CONNECT message used in MQTT 512 v5.0. A CONNECT message is composed of a fixed header, a variable 513 header and a payload. The fixed header contains the Control Packet 514 Type (CPT), Reserved, and Remaining Length fields. The Variable 515 Header contains the Protocol Name, Protocol Level, Connect Flags, 516 Keep Alive, and Properties fields. The Connect Flags in the variable 517 header specify the properties of the MQTT session. It also indicates 518 the presence or absence of some fields in the Payload. The payload 519 contains one or more encoded fields, namely a unique Client 520 identifier for the Client, a Will Topic, Will Payload, User Name and 521 Password. All but the Client identifier can be omitted depending on 522 the flags in the Variable Header. 524 0 8 16 24 32 525 +------------------------------------------------------+ 526 |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | 527 +------------------------------------------------------+ 528 | 'M' 'Q' 'T' 'T' | 529 +------------------------------------------------------+ 530 | Proto.level=5|Connect flags| Keep alive | 531 +------------------------------------------------------+ 532 | Property length | 533 | Auth. Method (0x15) | 'ace' | 534 | Auth. Data (0x16) | token or | 535 | token + PoP data | 536 +------------------------------------------------------+ 537 | Payload | 538 +------------------------------------------------------+ 540 Figure 2: MQTT v5 CONNECT control message with ACE authentication. 541 (CPT=Control Packet Type) 543 The CONNECT message flags are Username, Password, Will retain, Will 544 QoS, Will Flag, Clean Start, and Reserved. Figure 3 shows how the 545 flags MUST be set to use AUTH packets for authentication and 546 authorisation, i.e. the username and password flags MUST be set to 0. 547 An MQTT v5.0 RS MAY also support token transport using Username and 548 Password to provide a security option for MQTT v3.1.1 clients, as 549 described in Section 6. 551 +-----------------------------------------------------------+ 552 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 553 | Flag |Flag | | | |Start| | 554 +-----------------------------------------------------------+ 555 | 0 | 0 | X | X X | X | X | 0 | 556 +-----------------------------------------------------------+ 558 Figure 3: CONNECT flags for AUTH 560 The Will Flag indicates that a Will message needs to be sent if the 561 network connection is not closed normally. The situations in which 562 the Will message is published include disconnections due to I/O or 563 network failures, and the server closing the network connection due 564 to a protocol error. The Client MAY set the Will Flag as desired 565 (marked as 'X' in Figure 3). If the Will Flag is set to 1 and the 566 Broker accepts the connection request, the Broker stores the Will 567 message and publish it when the network connection is closed 568 according to Will QoS and Will retain parameters and MQTT Will 569 management rules. To avoid publishing Will Messages in the case of 570 temporary network disconnections, the Client specifies a Will Delay 571 Interval in the Will Properties. Section 5 explains how the Broker 572 deals with the retained messages in further detail. 574 In MQTT v5.0, the Client signals a clean session (i.e. the session 575 does not continue an existing session), by setting the Clean Start 576 Flag to 1 and, the Session Expiry Interval to 0 in the CONNECT 577 message. In this profile, the Broker SHOULD always start with a 578 clean session regardless of how these parameters are set. Starting a 579 clean session helps the Broker avoid keeping unnecessary session 580 state for unauthorised clients. If the Broker starts a clean 581 session, the Broker MUST set the Session Present flag to 0 in the 582 CONNACK packet to signal this to the Client. 584 The Broker MAY support session continuation e.g., if the Broker 585 requires it for QoS reasons. With session continuation, the Broker 586 maintains and uses client state from the existing session. The 587 session state kept at the server MAY include token and its 588 introspection result (for reference tokens) in addition to the MQTT 589 session state. The MQTT session state is identified by the Client 590 identifier and includes state on client subscriptions; messages with 591 QoS levels 1 and 2, and which have not been completely acknowledged 592 or pending transmission to the Client; and if the Session is 593 currently not connected, the time at which the Session will end and 594 Session State will be discarded. 596 When reconnecting to a Broker that supports session continuation, the 597 Client MUST still provide a token, in addition to using the same 598 Client identifier, setting the Clean Start to 0 and supplying a 599 Session Expiry interval in the CONNECT message. The Broker MUST 600 perform proof-of-possession validation on the provided token. If the 601 token matches the stored state, the Broker MAY skip introspecting a 602 token by reference, and use the stored introspection result. The 603 Broker MUST also verify the Client is authorized to receive or send 604 packets that are pending transmission. When a Client connects with a 605 long Session Expiry Interval, the Broker may need to maintain 606 Client's MQTT session state after it disconnects for an extended 607 period. Brokers SHOULD implement administrative policies to limit 608 misuse. 610 Note that, according to the MQTT standard, the Broker uses the Client 611 identifier to identify the session state. In the case of a Client 612 identifier collision, a client may take over another client's 613 session. Given that clients provide a token at each connection, 614 clients will only send or receive messages to their authorized 615 topics. Therefore, while this issue is not expected to affect 616 security, it may affect QoS (i.e. PUBLISH or QoS messages saved for 617 Client A may be delivered to a Client B). In addition, if this 618 Client identifier represents a Client already connected to the 619 Broker, the Broker sends a DISCONNECT packet to the existing Client 620 with Reason Code of '0x8E (Session taken over)', and closes the 621 connection to the client. 623 2.2.4. Authentication Using AUTH Property 625 To use AUTH, the Client MUST set the Authentication Method as a 626 property of a CONNECT packet by using the property identifier 21 627 (0x15). This is followed by a UTF-8 Encoded String containing the 628 name of the Authentication Method, which MUST be set to 'ace'. If 629 the RS does not support this profile, it sends a CONNACK with a 630 Reason Code of '0x8C (Bad authentication method)'. 632 The Authentication Method is followed by the Authentication Data, 633 which has a property identifier 22 (0x16) and is binary data. The 634 binary data in MQTT is represented by a two-byte integer length, 635 which indicates the number of data bytes, followed by that number of 636 bytes. Based on the Authentication Data, RS MUST support both 637 options below: 639 o Proof-of-Possession using a challenge from the TLS session 641 o Proof-of-Possession via Broker generated challenge/response 643 2.2.4.1. Proof-of-Possession Using a Challenge from the TLS session 645 +-----------------------------------------------------------------+ 646 |Authentication|Token Length|Token |MAC or Signature | 647 |Data Length | | |(over TLS exporter content) | 648 +-----------------------------------------------------------------+ 650 Figure 4: Authentication Data for PoP based on TLS exporter content 652 For this option, the Authentication Data MUST contain the two-byte 653 integer token length, the token, and the keyed message digest (MAC) 654 or the Client signature (as shown in Figure 4). The Proof-of- 655 Possession key in the token is used to calculate the keyed message 656 digest (MAC) or the Client signature based on the content obtained 657 from the TLS exporter ([RFC5705] for TLS 1.2 and for TLS 1.3, 658 Section 7.5 of [RFC8446]). This content is exported from the TLS 659 session using the exporter label 'EXPORTER-ACE-MQTT-Sign-Challenge', 660 an empty context, and length of 32 bytes. The token is also 661 validated as described in Section 2.2.5 and the server responds with 662 a CONNACK with the appropriate response code. The client cannot 663 reauthenticate using this method during the same session ( see 664 Section 4). 666 2.2.4.2. Proof-of-Possession via Broker-generated Challenge/Response 668 +------------------------------------+ 669 |Authentication|Token Length|Token | 670 |Data Length | | | 671 +------------------------------------+ 673 Figure 5: Authentication Data to Initiate PoP based on Challenge/ 674 Response 676 +------------------------------+ 677 |Authentication|Nonce (8 bytes)| 678 |Data Length | | 679 +------------------------------+ 681 Figure 6: Authentication Data for Broker Challenge 683 For this option, the RS follows a Broker-generated challenge/response 684 protocol. If the Authentication Data contains only the two-byte 685 integer token length and the token (as shown in Figure 5), the RS 686 MUST respond with an AUTH packet, with the Authenticate Reason Code 687 set to "0x18 (Continue Authentication)". This packet includes the 688 Authentication Method, which MUST be set to "ace" and Authentication 689 Data. The Authentication Data MUST NOT be empty and contains an 690 8-byte nonce as a challenge for the Client (Figure 6). 692 +------------------------------------------------------------------+ 693 |Authentication|Client Nonce |Client|MAC or Signature | 694 |Data Length |Length |nonce |(over RS nonce+Client nonce)| 695 +------------------------------------------------------------------+ 697 Figure 7: Authentication Data for Client Challenge Response 699 The Client responds to this with an AUTH packet with a reason code 700 "0x18 (Continue Authentication)". Similarly, the Client packet sets 701 the Authentication Method to "ace". The Authentication Data in the 702 Client's response is formatted as shown in Figure 7 and includes the 703 client nonce length, the client nonce, and the signature or MAC 704 computed over the RS nonce concatenated with the client nonce using 705 PoP key in the token. 707 Next, the token is validated as described in Section 2.2.5. The 708 success case is illustrated in Figure 8. The client MAY also re- 709 authenticate using this challenge-response flow, as described in 710 Section 4. 712 Resource 713 Client Server 714 | | 715 |<===========>| TLS connection set-up 716 | | 717 | | 718 +------------>| CONNECT with Authentication Data 719 | | contains only token 720 | | 721 <-------------+ AUTH '0x18 (Cont. Authentication)' 722 | | 8-byte nonce as RS challenge 723 | | 724 |------------>| AUTH '0x18 (Cont. Authentication)' 725 | | 8-byte client nonce + signature/MAC 726 | | 727 | |---+ Token validation 728 | | | (may involve introspection) 729 | |<--+ 730 | | 731 |<------------+ CONNACK '0x00 (Success)' 733 Figure 8: PoP Challenge/Response Flow - Success 735 2.2.5. Token Validation 737 The RS MUST verify the validity of the token either locally (e.g. in 738 the case of a self-contained token) or the RS MAY send an 739 introspection request to the AS. The RS MUST verify the claims 740 according to the rules set in the Section 5.8.1.1 of the ACE 741 framework [I-D.ietf-ace-oauth-authz]. 743 To authenticate the Client, the RS validates the signature or the 744 MAC, depending on how the PoP protocol is implemented. HS256 (HMAC- 745 SHA-256) [RFC6234] and Ed25519 [RFC8032] are mandatory to implement 746 depending on the choice of symmetric or asymmetric validation. 747 Validation of the signature or MAC MUST fail if the signature 748 algorithm is set to "none", when the key used for the signature 749 algorithm cannot be determined, or the computed and received 750 signature/MAC do not match. 752 2.2.6. The Broker's Response to Client Connection Request 754 Based on the validation result (obtained either via local inspection 755 or using the /introspection interface of the AS), the Broker MUST 756 send a CONNACK message to the Client. 758 2.2.6.1. Unauthorised Request and the Optional Authorisation Server 759 Discovery 761 If the Client does not provide a valid token or omits the 762 Authentication Data field, or the token or Authentication data are 763 malformed, authentication fails. The Broker responds with the 764 CONNACK reason code "0x87 (Not Authorized)" 766 The Broker MAY also trigger AS discovery, and include a User Property 767 (identified by 38 (0x26)) in the CONNACK for the AS Request Creation 768 Hints. The User Property is a UTF-8 string pair, composed of a name 769 and a value. The name of the User Property MUST be set to 770 "ace_as_hint". The value of the user property is a UTF-8 encoded 771 JSON string containing the mandatory "AS" parameter, and the optional 772 parameters "audience", "kid", "cnonce", and "scope" as defined in 773 Section 5.1.2 of the ACE framework [I-D.ietf-ace-oauth-authz]. 775 2.2.6.2. Authorisation Success 777 On success, the reason code of the CONNACK is "0x00 (Success)". The 778 AS informs the client that selected profile is "mqtt_tls" using the 779 "ace_profile" parameter in the token response. If the Broker starts 780 a new session, it MUST also set Session Present to 0 in the CONNACK 781 packet to signal a clean session to the Client. Otherwise, it MUST 782 set Session Present to 1. 784 If the Broker accepts the connection, it MUST store the token until 785 the end of the connection. On Client or Broker disconnection, the 786 Client is expected to transport a token again on the next connection 787 attempt. 789 If the token is not self-contained and the Broker uses token 790 introspection, it MAY cache the validation result to authorize the 791 subsequent PUBLISH and SUBSCRIBE messages. PUBLISH and SUBSCRIBE 792 messages, which are sent after a connection set-up, do not contain 793 access tokens. If the introspection result is not cached, then the 794 RS needs to introspect the saved token for each request. The Broker 795 SHOULD also use a cache time out to introspect tokens regularly. 797 3. Authorizing PUBLISH and SUBSCRIBE Messages 799 To authorize a Client's PUBLISH and SUBSCRIBE messages, the Broker 800 uses the scope field in the token (or in the introspection result). 801 The scope field contains the publish and subscribe permissions for 802 the Client. The scope is a JSON array, each item following the 803 Authorization Information Format (AIF) for ACE [I-D.ietf-ace-aif]. 804 Using the Concise Data Definition Language (CDDL) [RFC8610], the 805 specific data model for MQTT is: 807 AIF-MQTT = AIF-Generic 808 AIF-Generic = [*[topic_filter, permissions]] 809 topic_filter = tstr 810 permissions = [+permission] 811 permission = "pub"/"sub" 813 Figure 9: AIF-MQTT data model 815 Topic filters are implemented according to Section 4.7 of MQTT v5.0 - 816 the OASIS Standard [MQTT-OASIS-Standard-v5] and includes special 817 wildcard characters. The multi-level wildcard, '#', matches any 818 number of levels within a topic, and the single-level wildcard, '+', 819 matches one topic level. 821 If the scope is empty i.e., the JSON array is empty, the RS records 822 no permissions for the client for any topic. In this case, the 823 client is not able to publish or subscribe to any protected topics. 825 An example scope may contain: 827 [["topic1", ["pub","sub"]], ["topic2/#",["pub"]], ["+/topic3",["sub"]]] 829 Figure 10: Example scope 831 This access token gives publish ("pub") and subscribe ("sub") 832 permissions to the "topic1", publish permission to all the subtopics 833 of "topic2", and subscribe permission to all "topic3", skipping one 834 level. 836 If the Will Flag is set, then the Broker MUST check that the token 837 allows the publication of the Will message (i.e. the Will Topic 838 filter is in the scope array). 840 3.1. PUBLISH Messages from the Publisher Client to the Broker 842 On receiving the PUBLISH message, the Broker MUST use the type of 843 message (i.e. PUBLISH) and the Topic name in the message header to 844 match against the scope array items in the cached token or its 845 introspection result. Following the example in the previous section, 846 a client sending a PUBLISH message to 'topic2/a' would be allowed, as 847 the scope array includes the '["topic2/#",["pub"]]'. 849 If the Client is allowed to publish to the topic, the Broker 850 publishes the message to all valid subscribers of the topic. In the 851 case of an authorization failure, the Broker MUST return an error, if 852 the Client has set the QoS level of the PUBLISH message to greater 853 than or equal to 1. Depending on the QoS level, the Broker responds 854 with either a PUBACK or PUBREC packet with reason code '0x87 (Not 855 authorized)'. On receiving an acknowledgement with '0x87 (Not 856 authorized)', the Client MAY reauthenticate by providing a new token 857 as described in Section 4. 859 For QoS level 0, the Broker sends a DISCONNECT with reason code "0x87 860 (Not authorized)" and closes the network connection. Note that the 861 server-side DISCONNECT is a new feature of MQTT v5.0 (in MQTT v3.1.1, 862 the server needs to drop the connection). 864 3.2. PUBLISH Messages from the Broker to the Subscriber Clients 866 To forward PUBLISH messages to the subscribing Clients, the Broker 867 identifies all the subscribers that have valid matching topic 868 subscriptions (i.e. the tokens are valid, and token scopes allow a 869 subscription to the particular topic). The Broker sends a PUBLISH 870 message with the Topic name to all the valid subscribers. 872 The Broker MUST NOT forward messages to the unauthorized subscribers. 873 There is no way to inform the Clients with invalid tokens that an 874 authorization error has occurred other than sending a DISCONNECT 875 message. The Broker SHOULD send a DISCONNECT message with the reason 876 code '0x87 (Not authorized)'. 878 3.3. Authorizing SUBSCRIBE Messages 880 In MQTT, a SUBSCRIBE message is sent from a Client to the Broker to 881 create one or more subscriptions to one or more topics. The 882 SUBSCRIBE message may contain multiple Topic Filters. The Topic 883 Filters may include wildcard characters. 885 On receiving the SUBSCRIBE message, the Broker MUST use the type of 886 message (i.e. SUBSCRIBE) and the Topic Filter in the message header 887 to match against the scope field of the stored token or introspection 888 result. The Topic Filters MUST be equal or a subset of at least one 889 of the 'topic_filter' fields in the scope array found in the Client's 890 token. 892 As a response to the SUBSCRIBE message, the Broker issues a SUBACK 893 message. For each Topic Filter, the SUBACK packet includes a return 894 code matching the QoS level for the corresponding Topic Filter. In 895 the case of failure, the return code is 0x87, indicating that the 896 Client is 'Not authorized'. A reason code is returned for each Topic 897 Filter. Therefore, the Client may receive success codes for a subset 898 of its Topic Filters while being unauthorized for the rest. 900 4. Token Expiration, Update and Reauthentication 902 The Broker MUST check for token expiration whenever a CONNECT, 903 PUBLISH or SUBSCRIBE message is received or sent. The Broker SHOULD 904 check for token expiration on receiving a PINGREQUEST message. The 905 Broker MAY also check for token expiration periodically, e.g. every 906 hour. This may allow for early detection of a token expiry. 908 The token expiration is checked by checking the 'exp' claim of a JWT 909 or introspection response, or via performing an introspection request 910 with the AS as described in Section 5.7 of the ACE framework 911 [I-D.ietf-ace-oauth-authz]. Token expirations may trigger the RS to 912 send PUBACK, SUBACK and DISCONNECT messages with return code set to 913 "Not authorized". After sending a DISCONNECT message, the network 914 connection is closed, and no more messages can be sent. 916 If the Client used the challenge-respose PoP as defined in 917 Section 2.2.4.2, the Client MAY reauthenticate as a response to the 918 PUBACK and SUBACK that signal loss of authorization. The Clients MAY 919 also proactively update their tokens, i.e. before they receive a 920 message with a "Not authorized" return code. To start 921 reauthentication, the Client MUST send an AUTH packet with the reason 922 code "0x19 (Re-authentication)". The Client MUST set the 923 Authentication Method as "ace" and transport the new token in the 924 Authentication Data. The Broker accepts reauthentication requests if 925 the Client has already submitted a token (may be expired) and 926 validated via the challenge-response PoP. Otherwise, the Broker MUST 927 deny the request. If the reauthentication fails, the Broker MUST 928 send a DISCONNECT with the reason code "0x87 (Not Authorized)". 930 5. Handling Disconnections and Retained Messages 932 In the case of a Client DISCONNECT, the Broker deletes all the 933 session state but MUST keep the retained messages. By setting a 934 RETAIN flag in a PUBLISH message, the publisher indicates to the 935 Broker to store the most recent message for the associated topic. 936 Hence, the new subscribers can receive the last sent message from the 937 publisher for that particular topic without waiting for the next 938 PUBLISH message. The Broker MUST continue publishing the retained 939 messages as long as the associated tokens are valid. 941 In case of disconnections due to network errors or server 942 disconnection due to a protocol error (which includes authorization 943 errors), the Will message is sent if the Client supplied a Will in 944 the CONNECT message. The Client's token scope array MUST include the 945 Will Topic. The Will message MUST be published to the Will Topic 946 regardless of whether the corresponding token has expired. In the 947 case of a server-side DISCONNECT, the server returns the '0x87 Not 948 Authorized' return code to the Client. 950 6. Reduced Protocol Interactions for MQTT v3.1.1 952 This section describes a reduced set of protocol interactions for the 953 MQTT v3.1.1 Clients. An MQTT v5.0 Broker MAY implement these 954 interactions for the MQTT v3.1.1 clients; MQTT v5.0 clients are NOT 955 RECOMMENDED to use the flows described in this section. Brokers that 956 do not support MQTT v3.1.1 clients return a CONNACK packet with 957 Reason Code '0x84 (Unsupported Protocol Version)' in response to the 958 connection requests. 960 6.1. Token Transport 962 As in MQTT v5.0, the token MAY either be transported before by 963 publishing to the "authz-info" topic, or inside the CONNECT message. 965 In MQTT v3.1.1, after the Client published to the "authz-info" topic, 966 the Broker cannot communicate the result of the token validation as 967 PUBACK reason codes or server-side DISCONNECT messages are not 968 supported. In any case, an invalid token would fail the subsequent 969 TLS handshake, which can prompt the Client to obtain a valid token. 971 To transport the token to the Broker inside the CONNECT message, the 972 Client uses the username and password fields. Figure 11 shows the 973 structure of the MQTT CONNECT message. 975 0 8 16 24 32 976 +------------------------------------------------------+ 977 |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | 978 +------------------------------------------------------+ 979 | 'M' 'Q' 'T' 'T' | 980 +------------------------------------------------------+ 981 | Proto.level=4|Connect flags| Keep alive | 982 +------------------------------------------------------+ 983 | Payload | 984 | Client Identifier | 985 | Username as access token (UTF-8) | 986 | Password length (2 Bytes) | 987 | Password data as signature/MAC (binary) | 988 +------------------------------------------------------+ 990 Figure 11: MQTT CONNECT control message. (CPT=Control Packet Type, 991 Rsvd=Reserved, len.=length, Proto.=Protocol) 993 Figure 12 shows how the MQTT connect flags MUST be set to initiate a 994 connection with the Broker. 996 +-----------------------------------------------------------+ 997 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 998 | flag |flag | | | | | | 999 +-----------------------------------------------------------+ 1000 | 1 | 1 | X | X X | X | X | 0 | 1001 +-----------------------------------------------------------+ 1003 Figure 12: MQTT CONNECT flags. (Rsvd=Reserved) 1005 The Broker SHOULD NOT accept session continuation. To this end, the 1006 Broker ignores how the Clean Session Flag is set, and on connection 1007 success, the Broker MUST set the Session Present flag to 0 in the 1008 CONNACK packet to indicate a clean session to the Client. If the 1009 Broker wishes to support session continuation, it MUST still perform 1010 proof-of-possession validation on the provided Client token. MQTT 1011 v3.1.1 does not use a Session Expiry Interval, and the Client expects 1012 that the Broker maintains the session state after it disconnects. 1013 However, stored Session state can be discarded as a result of 1014 administrator policies, and Brokers SHOULD implement the necessary 1015 policies to limit misuse. 1017 The Client MAY set the Will Flag as desired (marked as 'X' in 1018 Figure 12). Username and Password flags MUST be set to 1 to ensure 1019 that the Payload of the CONNECT message includes both Username and 1020 Password fields. 1022 The CONNECT in MQTT v3.1.1 does not have a field to indicate the 1023 authentication method. To signal that the Username field contains an 1024 ACE token, this field MUST be prefixed with 'ace' keyword, which is 1025 followed by the access token. The Password field MUST be set to the 1026 keyed message digest (MAC) or signature associated with the access 1027 token for proof-of-possession. The Client MUST apply the PoP key on 1028 the challenge derived from the TLS session as described in 1029 Section 2.2.4.1. 1031 In MQTT v3.1.1, the MQTT Username is a UTF-8 encoded string (i.e. is 1032 prefixed by a 2-byte length field followed by UTF-8 encoded character 1033 data) and may be up to 65535 bytes. Therefore, an access token that 1034 is not a valid UTF-8 MUST be Base64 [RFC4648] encoded. (The MQTT 1035 Password allows binary data up to 65535 bytes.) 1037 6.2. Handling Authorization Errors 1039 Handling errors are more primitive in MQTT v3.1.1 due to not having 1040 appropriate error fields, error codes, and server-side DISCONNECTs. 1041 Therefore, the broker will disconnect on almost any error and may not 1042 keep session state, necessitating clients to make a greater effort to 1043 ensure that tokens remain valid and not attempt to publish to topics 1044 that they do not have permissions for. The following lists how the 1045 broker responds to specific errors. 1047 o CONNECT without a token: It is not possible to support AS 1048 discovery via sending a tokenless CONNECT message to the Broker. 1049 This is because a CONNACK packet in MQTT v3.1.1 does not include a 1050 means to provide additional information to the Client. Therefore, 1051 AS discovery needs to take place out-of-band. The tokenless 1052 CONNECT attempt MUST fail. 1054 o Client-RS PUBLISH authorization failure: In the case of a failure, 1055 it is not possible to return an error in MQTT v3.1.1. 1056 Acknowledgement messages only indicate success. In the case of an 1057 authorization error, the Broker SHOULD disconnect the Client. 1058 Otherwise, it MUST ignore the PUBLISH message. Also, as 1059 DISCONNECT messages are only sent from a Client to the Broker, the 1060 server disconnection needs to take place below the application 1061 layer. 1063 o SUBSCRIBE authorization failure: In the SUBACK packet, the return 1064 code is 0x80 indicating 'Failure' for the unauthorized topic(s). 1065 Note that, in both MQTT versions, a reason code is returned for 1066 each Topic Filter. 1068 o RS-Client PUBLISH authorization failure: When RS is forwarding 1069 PUBLISH messages to the subscribed Clients, it may discover that 1070 some of the subscribers are no more authorized due to expired 1071 tokens. These token expirations SHOULD lead to disconnecting the 1072 Client rather than silently dropping messages. 1074 7. IANA Considerations 1076 This document registers 'EXPORTER-ACE-MQTT-Sign-Challenge' 1077 (introduced in Section 2.2.4.1 in this document) in the TLS Exporter 1078 Label Registry [RFC8447]. 1080 In addition, the following registrations are done for the ACE OAuth 1081 Profile Registry following the procedure specified in 1082 [I-D.ietf-ace-oauth-authz]. 1084 Note to the RFC editor: Please replace all occurrences of "[RFC- 1085 XXXX]" with the RFC number of this specification and delete this 1086 paragraph. 1088 Name: mqtt_tls 1089 Description: Profile for delegating Client authentication and 1090 authorization using MQTT as the application protocol and TLS For 1091 transport layer security. 1093 CBOR Value: 1095 Reference: [RFC-XXXX] 1097 8. Security Considerations 1099 This document specifies a profile for the Authentication and 1100 Authorization for Constrained Environments (ACE) framework 1101 [I-D.ietf-ace-oauth-authz]. Therefore, the security considerations 1102 outlined in [I-D.ietf-ace-oauth-authz] apply to this work. 1104 In addition, the security considerations outlined in MQTT v5.0 - the 1105 OASIS Standard [MQTT-OASIS-Standard-v5] and MQTT v3.1.1 - the OASIS 1106 Standard [MQTT-OASIS-Standard] apply. Mainly, this document provides 1107 an authorization solution for MQTT, the responsibility of which is 1108 left to the specific implementation in the MQTT standards. In the 1109 following, we comment on a few relevant issues based on the current 1110 MQTT specifications. 1112 After the RS validates an access token and accepts a connection from 1113 a client, it caches the token to authorize a Client's publish and 1114 subscribe requests in an ongoing session. RS does not cache any 1115 invalid tokens. If a client's permissions get revoked but the access 1116 token has not expired, the RS may still grant publish/subscribe to 1117 revoked topics. If the RS caches the token introspection responses, 1118 then the RS SHOULD use a reasonable cache timeout to introspect 1119 tokens regularly. When permissions change dynamically, it is 1120 expected that AS also follows a reasonable expiration strategy for 1121 the access tokens. 1123 The RS may monitor Client behaviour to detect potential security 1124 problems, especially those affecting availability. These include 1125 repeated token transfer attempts to the public "authz-info" topic, 1126 repeated connection attempts, abnormal terminations, and Clients that 1127 connect but do not send any data. If the RS supports the public 1128 "authz-info" topic, described in Section 2.2.2, then this may be 1129 vulnerable to a DDoS attack, where many Clients use the "authz-info" 1130 public topic to transport fictitious tokens, which RS may need to 1131 store indefinitely. 1133 For MQTT v5.0, when a Client connects with a long Session Expiry 1134 Interval, the RS may need to maintain Client's MQTT session state 1135 after it disconnects for an extended period. For MQTT v3.1.1, the 1136 session state may need to be stored indefinitely, as it does not have 1137 a Session Expiry Interval feature. The RS SHOULD implement 1138 administrative policies to limit misuse of the session continuation 1139 by the Client. 1141 9. Privacy Considerations 1143 The privacy considerations outlined in [I-D.ietf-ace-oauth-authz] 1144 apply to this work. 1146 In MQTT, the RS is a central trusted party and may forward 1147 potentially sensitive information between Clients. This document 1148 does not protect the contents of the PUBLISH message from the Broker, 1149 and hence, the content of the PUBLISH message is not signed or 1150 encrypted separately for the subscribers. This functionality may be 1151 implemented using the proposal outlined in the ACE Pub-Sub Profile 1152 [I-D.ietf-ace-pubsub-profile]. However, this solution would still 1153 not provide privacy for other properties of the message such as Topic 1154 Name. 1156 10. References 1158 10.1. Normative References 1160 [I-D.ietf-ace-aif] 1161 Bormann, C., "An Authorization Information Format (AIF) 1162 for ACE", draft-ietf-ace-aif-00 (work in progress), July 1163 2020. 1165 [I-D.ietf-ace-oauth-authz] 1166 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1167 H. Tschofenig, "Authentication and Authorization for 1168 Constrained Environments (ACE) using the OAuth 2.0 1169 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-36 1170 (work in progress), November 2020. 1172 [I-D.ietf-ace-oauth-params] 1173 Seitz, L., "Additional OAuth Parameters for Authorization 1174 in Constrained Environments (ACE)", draft-ietf-ace-oauth- 1175 params-13 (work in progress), April 2020. 1177 [I-D.ietf-cose-x509] 1178 Schaad, J., "CBOR Object Signing and Encryption (COSE): 1179 Header parameters for carrying and referencing X.509 1180 certificates", draft-ietf-cose-x509-08 (work in progress), 1181 December 2020. 1183 [MQTT-OASIS-Standard] 1184 Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT 1185 Version 3.1.1 Plus Errata 01", 2015, . 1188 [MQTT-OASIS-Standard-v5] 1189 Banks, A., Ed., Briggs, E., Ed., Borgendale, K., Ed., and 1190 R. Gupta, Ed., "OASIS Standard MQTT Version 5.0", 2017, 1191 . 1194 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1195 Requirement Levels", BCP 14, RFC 2119, 1196 DOI 10.17487/RFC2119, March 1997, 1197 . 1199 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1200 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1201 . 1203 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 1204 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 1205 March 2010, . 1207 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1208 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1209 . 1211 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1212 Protocol (HTTP/1.1): Message Syntax and Routing", 1213 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1214 . 1216 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 1217 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 1218 Transport Layer Security (TLS) and Datagram Transport 1219 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 1220 June 2014, . 1222 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1223 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1224 . 1226 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1227 Possession Key Semantics for JSON Web Tokens (JWTs)", 1228 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1229 . 1231 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1232 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1233 May 2017, . 1235 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1236 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1237 . 1239 [RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS 1240 and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018, 1241 . 1243 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1244 Definition Language (CDDL): A Notational Convention to 1245 Express Concise Binary Object Representation (CBOR) and 1246 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1247 June 2019, . 1249 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 1250 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 1251 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 1252 2020, . 1254 10.2. Informative References 1256 [fremantle14] 1257 Fremantle, P., Aziz, B., Kopecky, J., and P. Scott, 1258 "Federated Identity and Access Management for the Internet 1259 of Things", research International Workshop on Secure 1260 Internet of Things, September 2014, 1261 . 1263 [I-D.ietf-ace-dtls-authorize] 1264 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 1265 L. Seitz, "Datagram Transport Layer Security (DTLS) 1266 Profile for Authentication and Authorization for 1267 Constrained Environments (ACE)", draft-ietf-ace-dtls- 1268 authorize-14 (work in progress), October 2020. 1270 [I-D.ietf-ace-pubsub-profile] 1271 Palombini, F., "Pub-Sub Profile for Authentication and 1272 Authorization for Constrained Environments (ACE)", draft- 1273 ietf-ace-pubsub-profile-01 (work in progress), July 2020. 1275 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1276 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1277 . 1279 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1280 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1281 DOI 10.17487/RFC6234, May 2011, 1282 . 1284 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1285 Application Protocol (CoAP)", RFC 7252, 1286 DOI 10.17487/RFC7252, June 2014, 1287 . 1289 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 1290 Signature Algorithm (EdDSA)", RFC 8032, 1291 DOI 10.17487/RFC8032, January 2017, 1292 . 1294 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1295 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1296 May 2018, . 1298 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1299 Representation (CBOR)", STD 94, RFC 8949, 1300 DOI 10.17487/RFC8949, December 2020, 1301 . 1303 Appendix A. Checklist for profile requirements 1305 o AS discovery: AS discovery is possible with the MQTT v5.0 1306 described in Section 2.2. 1308 o The communication protocol between the Client and RS: MQTT 1310 o The security protocol between the Client and RS: TLS 1312 o Client and RS mutual authentication: Several options are possible 1313 and described in Section 2.2.1. 1315 o Content format: For the HTTPS interactions with AS, "application/ 1316 ace+json". 1318 o PoP protocols: Either symmetric or asymmetric keys can be 1319 supported. 1321 o Unique profile identifier: mqtt_tls 1323 o Token introspection: RS uses HTTPS /introspect interface of AS. 1325 o Token request: Client or its Client AS uses HTTPS /token interface 1326 of AS. 1328 o /authz-info endpoint: It MAY be supported using the method 1329 described in Section 2.2.2, but is not protected. 1331 o Token transport: Via "authz-info" topic, or in MQTT CONNECT 1332 message for both versions of MQTT. AUTH extensions also used for 1333 authentication and re-authentication for MQTT v5.0 as described in 1334 Section 2.2 and in Section 4. 1336 Appendix B. Document Updates 1338 Version 07 to 08: 1340 o Fixed several nits, typos based on WG reviews. 1342 o Added missing references. 1344 o Added the definition for Property defined by MQTT, and Client 1345 Authorisation Server. 1347 o Added artwork to show Authorisation Data format for various PoP- 1348 related message exchange. 1350 o Removed all MQTT-related must/should/may. 1352 o Made AS discovery optional. 1354 o Clarified what the client and server must implement for client 1355 authentication; cleaned up TLS 1.3 related language. 1357 Version 06 to 07: 1359 o Corrected the title. 1361 o In Section 2.2.3, added the constraint on which packets the Client 1362 can send, and the server can process after CONNECT before CONNACK. 1364 o In Section 2.2.3, clarified that session state is identified by 1365 Client Identifier, and listed its content. 1367 o In Section 2.2.3, clarified the issue of Client Identifier 1368 collision, when the broker supports session continuation. 1370 o Corrected the buggy scope example in Section 3.1. 1372 Version 05 to 06: 1374 o Replace the originally proposed scope format with AIF model. 1375 Defined the AIF-MQTT, gave an example with a JSON array. Added a 1376 normative reference to the AIF draft. 1378 o Clarified client connection after submitting token via "authz- 1379 info" topic as TLS:Known(RPK/PSK)-MQTT:none. 1381 o Expanded acronyms on their first use including the ones in the 1382 title. 1384 o Added a definition for "Session". 1386 o Corrected "CONNACK" definition, which earlier said it's the first 1387 packet sent by the broker. 1389 o Added a statement that the the broker will disconnect on almost 1390 any error and may not keep session state. 1392 o Clarified that the broker does not cache invalid tokens. 1394 Version 04 to 05: 1396 o Reorganised Section 2 such that "Unauthorised Request: 1397 Authorisation Server Discovery" is presented under Section 2. 1399 o Fixed Figure 2 to remove the "empty" word. 1401 o Clarified that MQTT v5.0 Brokers may implement username/password 1402 option for transporting the ACE token only for MQTT v.3.1.1 1403 clients. This option is not recommended for MQTT v.5.0 clients. 1405 o Changed Clean Session requirement both for MQTT v.5.0 and v.3.1.1. 1406 The Broker SHOULD NOT, instead of MUST NOT, continue sessions. 1407 Clarified expected behaviour if session continuation is supported. 1408 Added to the Security Considerations the potential misuse of 1409 session continuation. 1411 o Fixed the Authentication Data to include token length for the 1412 Challenge/Response PoP. 1414 o Added that Authorisation Server Discovery is triggered if a token 1415 is invalid and not only missing. 1417 o Clarified that the Broker should not accept any other packets from 1418 Client after CONNECT and before sending CONNACK. 1420 o Added that client reauthentication is accepted only for the 1421 challenge/response PoP. 1423 o Added Ed25519 as mandatory to implement. 1425 o Fixed typos. 1427 Version 03 to 04: 1429 o Linked the terms Broker and MQTT server more at the introduction 1430 of the document. 1432 o Clarified support for MQTTv3.1.1 and removed phrases that might be 1433 considered as MQTTv5 is backwards compatible with MQTTv3.1.1 1435 o Corrected the Informative and Normative references. 1437 o For AS discovery, clarified the CONNECT message omits the 1438 Authentication Data field. Specified the User Property MUST be 1439 set to "ace_as_hint" for AS Request Creation Hints. 1441 o Added that MQTT v5 brokers MAY also implement reduced interactions 1442 described for MQTTv3.1.1. 1444 o Added to Section 3.1, in case of an authorisation failure and QoS 1445 level 0, the RS sends a DISCONNECT with reason code '0x87 (Not 1446 authorized)'. 1448 o Added a pointer to section 4.7 of MQTTv5 spec for more information 1449 on topic names and filters. 1451 o Added HS256 and RSA256 are mandatory to implement depending on the 1452 choice of symmetric or asymmetric validation. 1454 o Added MQTT to the TLS exporter label to make it application 1455 specific: 'EXPORTER-ACE-MQTT-Sign-Challenge'. 1457 o Added a format for Authentication Data so that length values 1458 prefix the token (or client nonce) when Authentication Data 1459 contains more than one piece of information. 1461 o Clarified clients still connect over TLS (server-side) for the 1462 authz-info flow. 1464 Version 02 to 03: 1466 o Added the option of Broker certificate thumbprint in the 'rs_cnf' 1467 sent to the Client. 1469 o Clarified the use of a random nonce from the TLS Exporter for PoP, 1470 added to the IANA requirements that the label should be 1471 registered. 1473 o Added a client nonce, when Challenge/Response Authentication is 1474 used between Client and Broker. 1476 o Clarified the use of the "authz-info" topic and the error response 1477 if token validation fails. 1479 o Added clarification on wildcard use in scopes for publish/ 1480 subscribe permissions 1482 o Reorganised sections so that token authorisation for publish/ 1483 subscribe messages are better placed. 1485 Version 01 to 02: 1487 o Clarified protection of Application Message payload as out of 1488 scope, and cited draft-palombini-ace-coap-pubsub-profile for a 1489 potential solution 1491 o Expanded Client connection authorization to capture different 1492 options for Client and Broker authentication over TLS and MQTT 1494 o Removed Payload (and specifically Client Identifier) from proof- 1495 of-possession in favor of using tls-exporter for a TLS-session 1496 based challenge. 1498 o Moved token transport via "authz-info" topic from the Appendix to 1499 the main text. 1501 o Clarified Will scope. 1503 o Added MQTT AUTH to terminology. 1505 o Typo fixes, and simplification of figures. 1507 Version 00 to 01: 1509 o Present the MQTTv5 as the RECOMMENDED version, and MQTT v3.1.1 for 1510 backward compatibility. 1512 o Clarified Will message. 1514 o Improved consistency in the use of terminology and upper/lower 1515 case. 1517 o Defined Broker and MQTTS. 1519 o Clarified HTTPS use for C-AS and RS-AS communication. Removed 1520 reference to actors document, and clarified the use of client 1521 authorization server. 1523 o Clarified the Connect message payload and Client Identifier. 1525 o Presented different methods for passing the token and PoP. 1527 o Added new figures to explain AUTH packets exchange, updated 1528 CONNECT message figure. 1530 Acknowledgements 1532 The authors would like to thank Ludwig Seitz for his review and his 1533 input on the authorization information endpoint. The authors would 1534 like to thank Paul Fremantle for the initial discussions on MQTT v5.0 1535 support. 1537 Authors' Addresses 1539 Cigdem Sengul 1540 Brunel University 1541 Dept. of Computer Science 1542 Uxbridge UB8 3PH 1543 UK 1545 Email: csengul@acm.org 1547 Anthony Kirby 1548 Oxbotica 1549 1a Milford House, Mayfield Road, Summertown 1550 Oxford OX2 7EL 1551 UK 1553 Email: anthony@anthony.org