idnits 2.17.1 draft-ietf-ace-mqtt-tls-profile-07.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 == Line 497 has weird spacing: '...rotocol name ...' == Line 901 has weird spacing: '...rotocol name ...' == 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 (August 25, 2020) is 1339 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 1019, but not defined == Unused Reference: 'RFC7250' is defined on line 1135, but no explicit reference was found in the text ** Downref: Normative reference to an Informational draft: draft-bormann-core-ace-aif (ref. 'I-D.bormann-core-ace-aif') == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-35 == 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-06 -- Possible downref: Non-RFC (?) normative reference: ref. 'MQTT-OASIS-Standard' -- Possible downref: Non-RFC (?) normative reference: ref. 'MQTT-OASIS-Standard-v5' == Outdated reference: A later version (-18) exists of draft-ietf-ace-dtls-authorize-12 == Outdated reference: A later version (-09) exists of draft-ietf-ace-pubsub-profile-01 Summary: 1 error (**), 0 flaws (~~), 11 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: February 26, 2021 Oxbotica 6 P. Fremantle 7 University of Portsmouth 8 August 25, 2020 10 Message Queuing Telemetry Transport (MQTT)-TLS profile of Authentication 11 and Authorization for Constrained Environments (ACE) Framework 12 draft-ietf-ace-mqtt-tls-profile-07 14 Abstract 16 This document specifies a profile for the ACE (Authentication and 17 Authorization for Constrained Environments) framework to enable 18 authorization in an Message Queuing Telemetry Transport (MQTT)-based 19 publish-subscribe messaging system. Proof-of-possession keys, bound 20 to OAuth2.0 access tokens, are used to authenticate and authorize 21 MQTT Clients. The protocol relies on TLS for confidentiality and 22 MQTT server (broker) authentication. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on February 26, 2021. 41 Copyright Notice 43 Copyright (c) 2020 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 60 1.2. ACE-Related Terminology . . . . . . . . . . . . . . . . . 4 61 1.3. MQTT-Related Terminology . . . . . . . . . . . . . . . . 5 62 2. Authorizing Connection Requests . . . . . . . . . . . . . . . 7 63 2.1. Client Token Request to the Authorization Server (AS) . . 8 64 2.2. Client Connection Request to the Broker (C) . . . . . . . 9 65 2.2.1. Client-Server Authentication over TLS and MQTT . . . 9 66 2.2.2. authz-info: The Authorization Information Topic . . . 10 67 2.2.3. Transporting Access Token Inside the MQTT CONNECT . . 11 68 2.2.4. Authentication Using AUTH Property . . . . . . . . . 14 69 2.2.4.1. Proof-of-Possession Using a Challenge from the 70 TLS session . . . . . . . . . . . . . . . . . . . 14 71 2.2.4.2. Proof-of-Possession via Broker-generated 72 Challenge/Response . . . . . . . . . . . . . . . 14 73 2.2.5. Token Validation . . . . . . . . . . . . . . . . . . 15 74 2.2.6. The Broker's Response to Client Connection Request . 16 75 2.2.6.1. Unauthorised Request: Authorisation Server 76 Discovery . . . . . . . . . . . . . . . . . . . . 16 77 2.2.6.2. Authorisation Success . . . . . . . . . . . . . . 16 78 3. Authorizing PUBLISH and SUBSCRIBE Messages . . . . . . . . . 16 79 3.1. PUBLISH Messages from the Publisher Client to the Broker 17 80 3.2. PUBLISH Messages from the Broker to the Subscriber 81 Clients . . . . . . . . . . . . . . . . . . . . . . . . . 18 82 3.3. Authorizing SUBSCRIBE Messages . . . . . . . . . . . . . 18 83 4. Token Expiration and Reauthentication . . . . . . . . . . . . 18 84 5. Handling Disconnections and Retained Messages . . . . . . . . 19 85 6. Reduced Protocol Interactions for MQTT v3.1.1 . . . . . . . . 19 86 6.1. Token Transport . . . . . . . . . . . . . . . . . . . . . 20 87 6.2. Handling Authorization Errors . . . . . . . . . . . . . . 21 88 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 89 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 90 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 24 91 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 10.1. Normative References . . . . . . . . . . . . . . . . . . 24 93 10.2. Informative References . . . . . . . . . . . . . . . . . 26 94 Appendix A. Checklist for profile requirements . . . . . . . . . 26 95 Appendix B. Document Updates . . . . . . . . . . . . . . . . . . 27 96 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 31 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 99 1. Introduction 101 This document specifies a profile for the ACE framework 102 [I-D.ietf-ace-oauth-authz]. In this profile, Clients and Servers 103 (Brokers) use MQTT to exchange Application Messages. The protocol 104 relies on TLS for communication security between entities. The MQTT 105 protocol interactions are described based on the MQTT v5.0 - the 106 OASIS Standard [MQTT-OASIS-Standard-v5]. Since it is expected that 107 MQTT deployments will continue to support MQTT v3.1.1 clients, this 108 document also describes a reduced set of protocol interactions for 109 MQTT v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard]. However, 110 MQTT v5.0 is the RECOMMENDED version as it works more naturally with 111 ACE-style authentication and authorization. 113 MQTT is a publish-subscribe protocol and after connecting to the MQTT 114 Server (Broker), a Client can publish and subscribe to multiple 115 topics. The Broker, which acts as the Resource Server (RS), is 116 responsible for distributing messages published by the publishers to 117 their subscribers. In the rest of the document the terms "RS", "MQTT 118 Server" and "Broker" are used interchangeably. 120 Messages are published under a Topic Name, and subscribers must 121 subscribe to the Topic Names to receive the corresponding messages. 122 The Broker uses the Topic Name in a published message to determine 123 which subscribers to relay the messages. In this document, topics, 124 more specifically, Topic Names, are treated as resources. The 125 Clients are assumed to have identified the publish/subscribe topics 126 of interest out-of-band (topic discovery is not a feature of the MQTT 127 protocol). A Resource Owner can pre-configure policies at the 128 Authorisation Server (AS) that give Clients publish or subscribe 129 permissions to different topics. 131 Clients prove their permission to publish and subscribe to topics 132 hosted on an MQTT broker using an access token, bound to a proof-of- 133 possession (PoP) key. This document describes how to authorize the 134 following exchanges between the Clients and the Broker. 136 o Connection requests from the Clients to the Broker 138 o Publish requests from the Clients to the Broker, and from the 139 Broker to the Clients 141 o Subscribe requests from Clients to the Broker 143 Clients use MQTT PUBLISH message to publish to a topic. This 144 document does not protect the payload of the PUBLISH message from the 145 Broker. Hence, the payload is not signed or encrypted specifically 146 for the subscribers. This functionality may be implemented using the 147 proposal outlined in the ACE Pub-Sub Profile 148 [I-D.ietf-ace-pubsub-profile]. 150 To provide communication confidentiality and RS authentication, TLS 151 is used, and TLS 1.3 is RECOMMENDED. This document makes the same 152 assumptions as Section 4 of the ACE framework 153 [I-D.ietf-ace-oauth-authz] regarding Client and RS registration with 154 the AS and setting up keying material. While the Client-Broker 155 exchanges are only over MQTT, the required Client-AS and RS-AS 156 interactions are described for HTTPS-based communication, using 157 'application/ace+json' content type, and unless otherwise specified, 158 using JSON encoding. The token may be a reference or JSON Web Token 159 (JWT). For JWTs, this document follows RFC 7800 [RFC7800] for PoP 160 semantics for JWTs. The Client-AS and RS-AS MAY also use protocols 161 other than HTTP, e.g. Constrained Application Protocol (CoAP) or 162 MQTT. Implementations MAY also use 'application/ace+cbor' content 163 type, and CBOR encoding, and CBOR Web Token (CWT) and associated PoP 164 semantics to reduce the protocol memory and bandwidth requirements. 165 For more information, see Proof-of-Possession Key Semantics for CBOR 166 Web Tokens (CWTs) [RFC8747]. 168 1.1. Requirements Language 170 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 171 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 172 "OPTIONAL" in this document are to be interpreted as described in BCP 173 14 [RFC2119] [RFC8174], when, and only when, they appear in all 174 capitals, as shown here. 176 1.2. ACE-Related Terminology 178 The terminology for entities in the architecture is defined in OAuth 179 2.0 RFC 6749 [RFC6749] such as "Client" (C), "Resource Server" (RS) 180 and "Authorization Server" (AS). 182 The term "resource" is used to refer to an MQTT Topic Name, which is 183 defined in Section 1.3. Hence, the "Resource Owner" is any entity 184 that can authoritatively speak for the topic. 186 Certain security-related terms such as "authentication", 187 "authorization", "confidentiality", "(data) integrity", "message 188 authentication code", and "verify" are taken from RFC 4949 [RFC4949]. 190 1.3. MQTT-Related Terminology 192 The document describes message exchanges as MQTT protocol 193 interactions. The Clients are MQTT Clients, which connect to the 194 Broker to publish and subscribe to Application Messages, labelled 195 with their topics. For additional information, please refer to the 196 MQTT v5.0 - the OASIS Standard [MQTT-OASIS-Standard-v5] or the MQTT 197 v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard]. 199 MQTTS 200 Secured transport profile of MQTT. MQTTS runs over TLS. 202 Broker 203 The Server in MQTT. It acts as an intermediary between the 204 Clients that publish Application Messages, and the Clients 205 that made Subscriptions. The Broker acts as the Resource 206 Server for the Clients. 208 Client 209 A device or program that uses MQTT. 211 Session 212 A stateful interaction between a Client and a Broker. Some 213 Sessions last only as long as the network connection, others 214 can span multiple network connections. 216 Application Message 217 The data carried by the MQTT protocol. The data has an 218 associated Quality-of-Service (QoS) level and a Topic Name. 220 QoS level 221 The level of assurance for the delivery of an Application 222 Message. The QoS level can be 0-2, where "0" indicates "At 223 most once delivery", "1" "At least once delivery", and "2" 224 "Exactly once delivery". 226 Topic Name 227 The label attached to an Application Message, which is 228 matched to a Subscription. 230 Subscription 231 A Subscription comprises a Topic Filter and a maximum QoS. A 232 Subscription is associated with a single session. 234 Topic Filter 235 An expression that indicates interest in one or more Topic 236 Names. Topic Filters may include wildcards. 238 MQTT sends various control messages across a network connection. The 239 following is not an exhaustive list and the control packets that are 240 not relevant for authorization are not explained. These include, for 241 instance, the PUBREL and PUBCOMP packets used in the 4-step handshake 242 required for QoS level 2. 244 CONNECT 245 Client request to connect to the Broker. This is the first 246 packet sent by a Client. 248 CONNACK 249 The Broker connection acknowledgment. CONNACK packets 250 contain return codes indicating either a success or an error 251 state in response to a Client's CONNECT packet. 253 AUTH 254 Authentication Exchange. An AUTH control packet is sent from 255 the Client to the Broker or from the Broker to the Client as 256 part of an extended authentication exchange. AUTH Properties 257 include Authentication Method and Authentication Data. The 258 Authentication Method is set in the CONNECT packet, and 259 consequent AUTH packets follow the same Authentication 260 Method. The contents of the Authentication Data are defined 261 by the Authentication Method. 263 PUBLISH 264 Publish request sent from a publishing Client to the Broker, 265 or from the Broker to a subscribing Client. 267 PUBACK 268 Response to a PUBLISH request with QoS level 1. A PUBACK can 269 be sent from the Broker to a Client or from a Client to the 270 Broker. 272 PUBREC 273 Response to PUBLISH request with QoS level 2. PUBREC can be 274 sent from the Broker to a Client or from a Client to the 275 Broker. 277 SUBSCRIBE 278 Subscribe request sent from a Client. 280 SUBACK 281 Subscribe acknowledgment. 283 PINGREQ 284 A ping request sent from a Client to the Broker. It signals 285 to the Broker that the Client is alive, and is used to 286 confirm that the Broker is also alive. The "Keep Alive" 287 period is set in the CONNECT message. 289 PINGRESP 290 Response sent by the Broker to the Client in response to 291 PINGREQ. It indicates the Broker is alive. 293 Will 294 If the network connection is not closed normally, the Broker 295 sends a last Will message for the Client, if the Client 296 provided one in its CONNECT message. If the Will Flag is 297 set, then the payload of the CONNECT message includes 298 information about the Will. The information consists of the 299 Will Properties, Will Topic, and Will Payload fields. 301 2. Authorizing Connection Requests 303 This section specifies how Client connections are authorized by the 304 MQTT Broker. Figure 1 shows the basic protocol flow during 305 connection set-up. The token request and response use the token 306 endpoint at the AS, specified in Section 5.6 of the ACE framework 307 [I-D.ietf-ace-oauth-authz]. Steps (D) and (E) are optional and use 308 the introspection endpoint, specified in Section 5.7 of the ACE 309 framework. The Client and the Broker use HTTPS to communicate to AS 310 via these endpoints. The Client and the Broker use MQTT to 311 communicate between them. 313 If the Client is resource-constrained, a Client Authorisation Server 314 may carry out the token request on behalf of the Client, and later, 315 onboard the Client with the token. Also, the C-AS and Broker-AS 316 interfaces may be implemented using protocols other than HTTPS, e.g. 317 CoAP or MQTT. The interactions between a Client and its Client 318 Authorization Server for token onboarding, and support for MQTTS- 319 based token requests at the AS are out of scope of this document. 321 +---------------------+ 322 | Client | 323 | | 324 +---(A) Token request--| Client - | 325 | | Authorization | 326 | +-(B) Access token-> Server Interface | 327 | | | (HTTPS) | 328 | | |_____________________| 329 | | | | 330 +--v-------------+ | Pub/Sub Interface | 331 | Authorization | | (MQTTS) | 332 | Server | +-----------^---------+ 333 |________________| | | 334 | ^ (C)Connection (F)Connection 335 | | request + response 336 | | access token | 337 | | | | 338 | | +---v--------------+ 339 | | | Broker (MQTTS) | 340 | | |__________________| 341 | +(D)Introspection-| | 342 | request (optional) | RS-AS interface | 343 | | (HTTPS) | 344 +-(E)Introspection---->|__________________| 345 response (optional) 347 Figure 1: Connection set-up 349 2.1. Client Token Request to the Authorization Server (AS) 351 The first step in the protocol flow (Figure 1 (A)) is the token 352 acquisition by the Client from the AS. The Client and the AS MUST 353 perform mutual authentication. The Client requests an access token 354 from the AS as described in Section 5.6.1 of the ACE framework 355 [I-D.ietf-ace-oauth-authz], however, it MUST set the profile 356 parameter to 'mqtt_tls'. The media format is 'application/ace+json'. 357 The AS uses JSON in the payload of its responses to both to the 358 Client and the RS. 360 If the AS successfully verifies the access token request and 361 authorizes the Client for the indicated audience (i.e. RS) and 362 scopes (i.e. publish/subscribe permissions over topics), the AS 363 issues an access token (Figure 1 (B)). The response includes the 364 parameters described in Section 5.6.2 of the ACE framework 365 [I-D.ietf-ace-oauth-authz]. The returned token is a Proof-of- 366 Possession (PoP) token by default. This document follows RFC 7800 367 [RFC7800] for PoP semantics for JWTs. The PoP token includes a 'cnf' 368 parameter with a symmetric or asymmetric PoP key. Note that the 369 'cnf' parameter in the web tokens are to be consumed by the RS and 370 not the Client. For the asymmetric case, the PoP token may include 371 the 'rs_cnf' parameter containing the information about the public 372 key to be used by the RS to authenticate as described in 373 [I-D.ietf-ace-oauth-params]. 375 The AS returns error responses for JSON-based interactions following 376 Section 5.2 of RFC 6749 [RFC6749]. When CBOR is used, the 377 interactions must implement Section 5.6.3 of the ACE framework 378 [I-D.ietf-ace-oauth-authz]. 380 2.2. Client Connection Request to the Broker (C) 382 2.2.1. Client-Server Authentication over TLS and MQTT 384 The Client and the Broker MUST perform mutual authentication. The 385 Client MUST authenticate to the Broker either over MQTT or TLS. For 386 MQTT, the options are "None" and "ace". For TLS, the options are 387 "Anon" for an anonymous client, and "Known(RPK/PSK)" for Raw Public 388 Keys (RPK) and Pre-Shared Keys (PSK), respectively. Combined, client 389 authentication has the following options: 391 o "TLS:Anon-MQTT:None": This option is used only for the topics that 392 do not require authorization, including the "authz-info" topic. 393 Publishing to the "authz-info" topic is described in 394 Section 2.2.2. 396 o "TLS:Anon-MQTT:ace": The token is transported inside the CONNECT 397 message, and MUST be validated using one of the methods described 398 in Section 2.2.2. This option also supports a tokenless 399 connection request for AS discovery. 401 o "TLS:Known(RPK/PSK)-MQTT:none": For the RPK, the token MUST have 402 been published to the "authz-info" topic. For the PSK, the token 403 MAY be, alternatively, provided in the "psk_identity". The TLS 404 session set-up is as described in DTLS profile for ACE 405 [I-D.ietf-ace-dtls-authorize]. 407 o "TLS:Known(RPK/PSK)-MQTT:ace": This option SHOULD NOT be chosen. 408 In any case, the token transported in the CONNECT overwrites any 409 permissions passed during the TLS authentication. 411 It is RECOMMENDED that the Client follows TLS:Anon-MQTT:ace. 413 The Broker MUST be authenticated during the TLS handshake. If the 414 Client authentication uses TLS:Known(RPK/PSK), then the Broker is 415 authenticated using the respective method. Otherwise, to 416 authenticate the Broker, the client MUST validate a public key from a 417 X.509 certificate or an RPK from the Broker against the 'rs_cnf' 418 parameter in the token response. The AS MAY include the thumbprint 419 of the RS's X.509 certificate in the 'rs_cnf' (thumbprint as defined 420 in [I-D.ietf-cose-x509]). In this case, the client MUST validate the 421 RS certificate against this thumbprint. 423 2.2.2. authz-info: The Authorization Information Topic 425 In the cases when the Client MUST transport the token to the Broker 426 first, the Client connects to the Broker to publish its token to the 427 "authz-info" topic. The "authz-info" topic MUST be publish-only 428 (i.e. the Clients are not allowed to subscribe to it). "authz-info" 429 is not protected, and hence, the Client uses the "TLS:Anon-MQTT:None" 430 option over a TLS connection. After publishing the token, the Client 431 disconnects from the Broker and is expected to reconnect using client 432 authentication over TLS (i.e. TLS:Known(RPK/PSK)-MQTT:none). 434 The Broker stores and indexes all tokens received to the "authz-info" 435 topic in its key store (similar to DTLS profile for ACE 436 [I-D.ietf-ace-dtls-authorize]). This profile follows the 437 recommendation of Section 5.8.1 of the ACE framework 438 [I-D.ietf-ace-oauth-authz], and expects that the Broker stores only 439 one token per proof-of-possession key, and any other token linked to 440 the same key overwrites an existing token. 442 The Broker MUST verify the validity of the token (i.e. through local 443 validation or introspection, if the token is a reference) as 444 described in Section 2.2.5. If the token is not valid, the Broker 445 MUST discard the token. Depending on the QoS level of the PUBLISH 446 message, the Broker returns the error response as a PUBACK or a 447 DISCONNECT message as explained below. 449 If the QoS level is equal to 0, and the token is invalid or the 450 claims cannot be obtained in the case of an introspected token, the 451 Broker MUST send a DISCONNECT message with the reason code '0x87 (Not 452 authorized)'. If the PUBLISH payload does not parse to a token, the 453 RS MUST send a DISCONNECT with the reason code '0x99 (Payload format 454 invalid)'. 456 If the QoS level of the PUBLISH message is greater than or equal to 457 1, the Broker MUST return 'Not authorized' in PUBACK. If the PUBLISH 458 payload does not parse to a token, the PUBACK reason code is '0x99 459 (Payload format invalid)'. 461 It must be noted that when the RS sends the 'Not authorized' 462 response, this corresponds to the token being invalid, and not that 463 the actual PUBLISH message was not authorized. Given that the 464 "authz-info" is a public topic, this response is not expected to 465 cause confusion. 467 2.2.3. Transporting Access Token Inside the MQTT CONNECT 469 This section describes how the Client transports the token to the 470 Broker (RS) inside the CONNECT message. If this method is used, the 471 Client TLS connection is expected to be anonymous, and the Broker is 472 authenticated during the TLS connection set-up. The approach 473 described in this section is similar to an earlier proposal by 474 Fremantle et al [fremantle14]. 476 After sending the CONNECT, the client MUST NOT send any packets other 477 than DISCONNECT or AUTH that is in response to the broker AUTH until 478 it has received a CONNACK. Similarly, the server MUST NOT process 479 any packets other than DISCONNECT or an AUTH that is sent in response 480 to its AUTH before it has sent a CONNACK. 482 Figure 2 shows the structure of the MQTT CONNECT message used in MQTT 483 v5.0. A CONNECT message is composed of a fixed header, a variable 484 header and a payload. The fixed header contains the Control Packet 485 Type (CPT), Reserved, and Remaining Length fields. The Variable 486 Header contains the Protocol Name, Protocol Level, Connect Flags, 487 Keep Alive, and Properties fields. The Connect Flags in the variable 488 header specify the properties of the MQTT session. It also indicates 489 the presence or absence of some fields in the Payload. The payload 490 contains one or more encoded fields, namely a unique Client 491 identifier for the Client, a Will Topic, Will Payload, User Name and 492 Password. All but the Client identifier can be omitted depending on 493 the flags in the Variable Header. 495 0 8 16 24 32 496 +------------------------------------------------------+ 497 |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | 498 +------------------------------------------------------+ 499 | 'M' 'Q' 'T' 'T' | 500 +------------------------------------------------------+ 501 | Proto.level=5|Connect flags| Keep alive | 502 +------------------------------------------------------+ 503 | Property length | 504 | Auth. Method (0x15) | 'ace' | 505 | Auth. Data (0x16) | token or | 506 | token + PoP data | 507 +------------------------------------------------------+ 508 | Payload | 509 +------------------------------------------------------+ 511 Figure 2: MQTT v5 CONNECT control message with ACE authentication. 512 (CPT=Control Packet Type) 514 The CONNECT message flags are Username, Password, Will retain, Will 515 QoS, Will Flag, Clean Start, and Reserved. Figure 8 shows how the 516 flags MUST be set to use AUTH packets for authentication and 517 authorisation, i.e. the username and password flags MUST be set to 0. 518 An MQTT v5.0 RS MAY also support token transport using Username and 519 Password to provide a security option for MQTT v3.1.1 clients, as 520 described in Section 6. 522 +-----------------------------------------------------------+ 523 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 524 | Flag |Flag | | | |Start| | 525 +-----------------------------------------------------------+ 526 | 0 | 0 | X | X X | X | X | 0 | 527 +-----------------------------------------------------------+ 529 Figure 3: CONNECT flags for AUTH 531 The Will Flag indicates that a Will message needs to be sent if the 532 network connection is not closed normally. The situations in which 533 the Will message is published include disconnections due to I/O or 534 network failures, and the server closing the network connection due 535 to a protocol error. The Client may set the Will Flag as desired 536 (marked as 'X' in Figure 3). If the Will Flag is set to 1 and the 537 Broker accepts the connection request, the Broker must store the Will 538 message and publish it when the network connection is closed 539 according to Will QoS and Will retain parameters and MQTT Will 540 management rules. To avoid publishing Will Messages in the case of 541 temporary network disconnections, the Client may specify a Will Delay 542 Interval in the Will Properties. Section 5 explains how the Broker 543 deals with the retained messages in further detail. 545 In MQTT v5.0, the Client signals a clean session (i.e. the session 546 does not continue an existing session), by setting the Clean Start 547 Flag to 1 and, the Session Expiry Interval to 0 in the CONNECT 548 message. In this profile, the Broker SHOULD always start with a 549 clean session regardless of how these parameters are set. Starting a 550 clean session helps the Broker avoid keeping unnecessary session 551 state for unauthorised clients. If the Broker starts a clean 552 session, the Broker MUST set the Session Present flag to 0 in the 553 CONNACK packet to signal this to the Client. 555 If necessary, the Broker MAY support session continuation, and hence, 556 maintain and use client state from the existing session. The session 557 state kept at the server MAY include token and its introspection 558 result (for reference tokens) in addition to the MQTT session state. 559 The MQTT session state is identified by the Client identifier and 560 includes state on client subscriptions, QoS 1 and QoS 2 messages 561 which have have not been completely acknowledged or pending 562 transmission to the Client, and if the Session is currently not 563 connected, the time at which the Session will end and Session State 564 will be discarded. 566 When reconnecting to a Broker that supports session continuation, the 567 Client MUST still provide a token, in addition to using the same 568 Client identifier, setting the Clean Start to 0 and supplying a 569 Session Expiry interval in the CONNECT message. The Broker MUST 570 perform proof-of-possession validation on the provided token. If the 571 token matches the stored state, the Broker MAY skip introspecting a 572 token by reference, and use the stored introspection result. The 573 Broker MUST also verify the Client is authorized to receive or send 574 packets that are pending transmission. When a Client connects with a 575 long Session Expiry Interval, the Broker may need to maintain 576 Client's MQTT session state after it disconnects for an extended 577 period. Brokers SHOULD implement administrative policies to limit 578 misuse. 580 Note that, according to the MQTT standard, the Broker must use the 581 Client identifier to identify the session state. In the case of a 582 Client identifier collision, a client may take over another client's 583 session. Given that clients provide a token at each connection, 584 clients will only send or receive messages to their authorized 585 topics. Therefore, while this issue is not expected to affect 586 security, it may affect QoS (i.e. PUBLISH or QoS messages saved for 587 Client A may be delivered to a Client B). In addition, if this 588 Client identifier represents a Client already connected to the 589 Broker, the Broker sends a DISCONNECT packet to the existing Client 590 with Reason Code of '0x8E (Session taken over)', and closes the 591 connection to the client. 593 2.2.4. Authentication Using AUTH Property 595 To use AUTH, the Client MUST set the Authentication Method as a 596 property of a CONNECT packet by using the property identifier 21 597 (0x15). This is followed by a UTF-8 Encoded String containing the 598 name of the Authentication Method, which MUST be set to 'ace'. If 599 the RS does not support this profile, it sends a CONNACK with a 600 Reason Code of '0x8C (Bad authentication method)'. 602 The Authentication Method is followed by the Authentication Data, 603 which has a property identifier 22 (0x16) and is binary data. The 604 binary data in MQTT is represented by a two-byte integer length, 605 which indicates the number of data bytes, followed by that number of 606 bytes. Based on the Authentication Data, this profile allows: 608 o Proof-of-Possession using a challenge from the TLS session 610 o Proof-of-Possession via Broker generated challenge/response 612 2.2.4.1. Proof-of-Possession Using a Challenge from the TLS session 614 For this option, the Authentication Data MUST contain the two-byte 615 integer token length, the token, and the keyed message digest (MAC) 616 or the Client signature. The content to calculate the keyed message 617 digest (MAC) or the Client signature (for the proof-of-possession) is 618 obtained using a TLS exporter ([RFC5705] for TLS 1.2 and for TLS 1.3, 619 Section 7.5 of [RFC8446]). The content is exported from TLS using 620 the exporter label 'EXPORTER-ACE-MQTT-Sign-Challenge', an empty 621 context, and length of 32 bytes. The token is also validated as 622 described in Section 2.2.5 and, the server responds with a CONNACK 623 with the appropriate response code. The client cannot reauthenticate 624 using this method during the same session ( see Section 4). ) 626 2.2.4.2. Proof-of-Possession via Broker-generated Challenge/Response 628 For this option, the RS follows a Broker-generated challenge/response 629 protocol. The success case is illustrated in Figure 4. If the 630 Authentication Data contains only the two-byte integer token length 631 and the token, the RS MUST respond with an AUTH packet, with the 632 Authenticate Reason Code set to '0x18 (Continue Authentication)'. 633 This packet includes the Authentication Method, which MUST be set to 634 'ace' and Authentication Data. The Authentication Data MUST NOT be 635 empty and contains an 8-byte nonce as a challenge for the Client. 636 The Client responds to this with an AUTH packet with a reason code 637 '0x18 (Continue Authentication)'. Similarly, the Client packet sets 638 the Authentication Method to 'ace'. The Authentication Data in the 639 Client's response is formatted as the client nonce length, the client 640 nonce, and the signature or MAC computed over the RS nonce 641 concatenated with the client nonce. Next, the token is validated as 642 described in Section 2.2.5. 644 The client MAY also re-authenticate using this challenge-response 645 flow, as described in Section 4. 647 Resource 648 Client Server 649 | | 650 |<===========>| TLS connection set-up 651 | | 652 | | 653 +------------>| CONNECT with Authentication Data 654 | | contains only token 655 | | 656 <-------------+ AUTH '0x18 (Cont. Authentication)' 657 | | 8-byte nonce as RS challenge 658 | | 659 |------------>| AUTH '0x18 (Cont. Authentication)' 660 | | 8-byte client nonce + signature/MAC 661 | | 662 | |---+ Token validation 663 | | | (may involve introspection) 664 | |<--+ 665 | | 666 |<------------+ CONNACK '0x00 (Success)' 668 Figure 4: PoP Challenge/Response Protocol Flow - Success 670 2.2.5. Token Validation 672 The RS MUST verify the validity of the token either locally (e.g. in 673 the case of a self-contained token) or the RS MAY send an 674 introspection request to the AS. RS MUST verify the claims according 675 to the rules set in the Section 5.8.1.1 of the ACE framework 676 [I-D.ietf-ace-oauth-authz]. 678 To authenticate the Client, the RS validates the signature or the 679 MAC, depending on how the PoP protocol is implemented. HS256 and 680 Ed25519 are mandatory to implement depending on the choice of 681 symmetric or asymmetric validation. Validation of the signature or 682 MAC MUST fail if the signature algorithm is set to "none", when the 683 key used for the signature algorithm cannot be determined, or the 684 computed and received signature/MAC do not match. 686 2.2.6. The Broker's Response to Client Connection Request 688 Based on the validation result (obtained either via local inspection 689 or using the /introspection interface of the AS), the Broker MUST 690 send a CONNACK message to the Client. 692 2.2.6.1. Unauthorised Request: Authorisation Server Discovery 694 If the Client does not provide a valid token or omits the 695 Authentication Data field, the Broker triggers AS discovery. The 696 Broker responds with the CONNACK reason code '0x87 (Not Authorized)' 697 and includes a User Property (identified by 38 (0x26)) for the AS 698 Request Creation Hints. The User Property is a UTF-8 string pair, 699 composed of a name and a value. The name of the User Property MUST 700 be set to "ace_as_hint". The value of the user property is a UTF-8 701 encoded JSON string containing the mandatory "AS" parameter, and the 702 optional parameters "audience", "kid", "cnonce", and "scope" as 703 defined in Section 5.1.2 of the ACE framework 704 [I-D.ietf-ace-oauth-authz]. 706 2.2.6.2. Authorisation Success 708 On success, the reason code of the CONNACK is '0x00 (Success)'. If 709 the Broker starts a new session, it MUST also set Session Present to 710 0 in the CONNACK packet to signal a clean session to the Client. 711 Otherwise, it MUST set Session Present to 1. In case of an invalid 712 PoP token, the CONNACK reason code is '0x87 (Not Authorized)'. 714 If the Broker accepts the connection, it MUST store the token until 715 the end of the connection. On Client or Broker disconnection, the 716 Client is expected to transport a token again on the next connection 717 attempt. 719 If the token is not self-contained and the Broker uses token 720 introspection, it MAY cache the validation result to authorize the 721 subsequent PUBLISH and SUBSCRIBE messages. PUBLISH and SUBSCRIBE 722 messages, which are sent after a connection set-up, do not contain 723 access tokens. If the introspection result is not cached, then the 724 RS needs to introspect the saved token for each request. The Broker 725 SHOULD also use a cache time out to introspect tokens regularly. 727 3. Authorizing PUBLISH and SUBSCRIBE Messages 729 To authorize a Client's PUBLISH and SUBSCRIBE messages, the Broker 730 uses the scope field in the token (or in the introspection result). 731 The scope field contains the publish and subscribe permissions for 732 the Client. The scope is a JSON array, each item following the 733 Authorization Information Format (AIF) for ACE 734 [I-D.bormann-core-ace-aif]. The specific data model for MQTT is: 736 AIF-MQTT = AIF-Generic 737 AIF-Generic = [* [topic_filter,permissions]] 738 topic_filter = tstr 739 permissions = [+permission] 740 permission = "pub"/"sub" 742 Figure 5: AIF-MQTT data model 744 Topic filters are implemented according to Section 4.7 of MQTT v5.0 - 745 the OASIS Standard [MQTT-OASIS-Standard-v5] and includes special 746 wildcard characters. The multi-level wildcard, '#', matches any 747 number of levels within a topic, and the single-level wildcard, '+', 748 matches one topic level. 750 An example scope field may contain: 752 [["topic1", ["pub","sub"]], ["topic2/#",["pub"]], ["+/topic3",["sub"]]] 754 Figure 6: Example scope 756 This access token gives publish ("pub") and subscribe ("sub") 757 permissions to the 'topic1', publish permission to all the subtopics 758 of 'topic2', and subscribe permission to all topic3, skipping one 759 level. If the Will Flag is set, then the Broker MUST check that the 760 token allows the publication of the Will message (i.e. the Will Topic 761 filter is found in the scope). 763 3.1. PUBLISH Messages from the Publisher Client to the Broker 765 On receiving the PUBLISH message, the Broker MUST use the type of 766 message (i.e. PUBLISH) and the Topic name in the message header to 767 match against the scope array items in the cached token or its 768 introspection result. Following the example in the previous section, 769 a client sending a PUBLISH message to 'topic2/a' would be allowed, as 770 the scope array includes the '["topic2/#",["pub"]]'. 772 If the Client is allowed to publish to the topic, the Broker must 773 publish the message to all valid subscribers of the topic. In the 774 case of an authorization failure, the Broker MUST return an error, if 775 the Client has set the QoS level of the PUBLISH message to greater 776 than or equal to 1. Depending on the QoS level, the Broker responds 777 with either a PUBACK or PUBREC packet with reason code '0x87 (Not 778 authorized)'. On receiving an acknowledgement with '0x87 (Not 779 authorized)', the Client MAY reauthenticate by providing a new token 780 as described in Section 4. 782 For QoS level 0, the Broker sends a DISCONNECT with reason code '0x87 783 (Not authorized)' and closes the network connection. Note that the 784 server-side DISCONNECT is a new feature of MQTT v5.0 (in MQTT v3.1.1, 785 the server needs to drop the connection). 787 3.2. PUBLISH Messages from the Broker to the Subscriber Clients 789 To forward PUBLISH messages to the subscribing Clients, the Broker 790 identifies all the subscribers that have valid matching topic 791 subscriptions (i.e. the tokens are valid, and token scopes allow a 792 subscription to the particular topic). The Broker sends a PUBLISH 793 message with the Topic name to all the valid subscribers. 795 The Broker MUST NOT forward messages to the unauthorized subscribers. 796 There is no way to inform the Clients with invalid tokens that an 797 authorization error has occurred other than sending a DISCONNECT 798 message. The Broker SHOULD send a DISCONNECT message with the reason 799 code '0x87 (Not authorized)'. 801 3.3. Authorizing SUBSCRIBE Messages 803 In MQTT, a SUBSCRIBE message is sent from a Client to the Broker to 804 create one or more subscriptions to one or more topics. The 805 SUBSCRIBE message may contain multiple Topic Filters. The Topic 806 Filters may include wildcard characters. 808 On receiving the SUBSCRIBE message, the Broker MUST use the type of 809 message (i.e. SUBSCRIBE) and the Topic Filter in the message header 810 to match against the scope field of the stored token or introspection 811 result. The Topic Filters MUST be equal or a subset of at least one 812 of the 'topic_filter' fields in the scope array found in the Client's 813 token. 815 As a response to the SUBSCRIBE message, the Broker issues a SUBACK 816 message. For each Topic Filter, the SUBACK packet includes a return 817 code matching the QoS level for the corresponding Topic Filter. In 818 the case of failure, the return code is 0x87, indicating that the 819 Client is 'Not authorized'. A reason code is returned for each Topic 820 Filter. Therefore, the Client may receive success codes for a subset 821 of its Topic Filters while being unauthorized for the rest. 823 4. Token Expiration and Reauthentication 825 The Broker MUST check for token expiration whenever a CONNECT, 826 PUBLISH or SUBSCRIBE message is received or sent. The Broker SHOULD 827 check for token expiration on receiving a PINGREQUEST message. The 828 Broker MAY also check for token expiration periodically, e.g. every 829 hour. This may allow for early detection of a token expiry. 831 The token expiration is checked by checking the 'exp' claim of a JWT 832 or introspection response, or via performing an introspection request 833 with the AS as described in Section 5.7 of the ACE framework 834 [I-D.ietf-ace-oauth-authz]. Token expirations may trigger the RS to 835 send PUBACK, SUBACK and DISCONNECT messages with return code set to 836 'Not authorized'. After sending a DISCONNECT message, the network 837 connection is closed, and no more messages can be sent. However, as 838 a response to the PUBACK and SUBACK, the Client MAY reauthenticate. 839 The Clients MAY also proactively update their tokens, i.e. before 840 they receive a message with a 'Not authorized' return code. 842 To start reauthentication, the Client MUST send an AUTH packet with 843 the reason code '0x19 (Re-authentication)'. The Client MUST set the 844 Authentication Method as 'ace' and transport the new token in the 845 Authentication Data. The Broker accepts reauthentication requests if 846 the Client has already submitted a token (may be expired) and 847 validated via the challenge-response PoP as defined in 848 Section 2.2.4.2. The Client MUST use the challenge-response PoP. 849 Otherwise, the Broker MUST deny the request. If the reauthentication 850 fails, the Broker MUST send a DISCONNECT with the reason code '0x87 851 (Not Authorized)'. 853 5. Handling Disconnections and Retained Messages 855 In the case of a Client DISCONNECT, the Broker deletes all the 856 session state but MUST keep the retained messages. By setting a 857 RETAIN flag in a PUBLISH message, the publisher indicates to the 858 Broker that it should store the most recent message for the 859 associated topic. Hence, the new subscribers can receive the last 860 sent message from the publisher for that particular topic without 861 waiting for the next PUBLISH message. The Broker MUST continue 862 publishing the retained messages as long as the associated tokens are 863 valid. 865 In case of disconnections due to network errors or server 866 disconnection due to a protocol error (which includes authorization 867 errors), the Will message must be sent if the Client supplied a Will 868 in the CONNECT message. The Client's token scope array MUST include 869 the Will Topic. The Will message MUST be published to the Will Topic 870 regardless of whether the corresponding token has expired. In the 871 case of a server-side DISCONNECT, the server returns the '0x87 Not 872 Authorized' return code to the Client. 874 6. Reduced Protocol Interactions for MQTT v3.1.1 876 This section describes a reduced set of protocol interactions for the 877 MQTT v3.1.1 Clients. An MQTT v5.0 Broker MAY implement these 878 interactions for the MQTT v3.1.1 clients; MQTT v5.0 clients are NOT 879 RECOMMENDED to use the flows described in this section. Brokers that 880 do not support MQTT v3.1.1 clients return a CONNACK packet with 881 Reason Code '0x84 (Unsupported Protocol Version)' in response to the 882 connection requests. 884 6.1. Token Transport 886 As in MQTT v5.0, The Token MAY either be transported before by 887 publishing to the "authz-info" topic, or inside the CONNECT message. 889 In MQTT v3.1.1, after the Client published to the "authz-info" topic, 890 the Broker cannot communicate the result of the token validation as 891 PUBACK reason codes or server-side DISCONNECT messages are not 892 supported. In any case, an invalid token would fail the subsequent 893 TLS handshake, which can prompt the Client to obtain a valid token. 895 To transport the token to the Broker inside the CONNECT message, the 896 Client uses the username and password fields. Figure 7 shows the 897 structure of the MQTT CONNECT message. 899 0 8 16 24 32 900 +------------------------------------------------------+ 901 |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | 902 +------------------------------------------------------+ 903 | 'M' 'Q' 'T' 'T' | 904 +------------------------------------------------------+ 905 | Proto.level=4|Connect flags| Keep alive | 906 +------------------------------------------------------+ 907 | Payload | 908 | Client Identifier | 909 | Username as access token (UTF-8) | 910 | Password length (2 Bytes) | 911 | Password data as signature/MAC (binary) | 912 +------------------------------------------------------+ 914 Figure 7: MQTT CONNECT control message. (CPT=Control Packet Type, 915 Rsvd=Reserved, len.=length, Proto.=Protocol) 917 Figure 8 shows how the MQTT connect flags MUST be set to initiate a 918 connection with the Broker. 920 +-----------------------------------------------------------+ 921 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 922 | flag |flag | | | | | | 923 +-----------------------------------------------------------+ 924 | 1 | 1 | X | X X | X | X | 0 | 925 +-----------------------------------------------------------+ 927 Figure 8: MQTT CONNECT flags. (Rsvd=Reserved) 929 The Broker SHOULD NOT accept session continuation. To this end, the 930 Broker ignores how the Clean Session Flag is set, and on connection 931 success, the Broker MUST set the Session Present flag to 0 in the 932 CONNACK packet to indicate a clean session to the Client. If the 933 Broker wishes to support session continuation, it MUST still perform 934 proof-of-possession validation on the provided Client token. MQTT 935 v3.1.1 does not use a Session Expiry Interval, and the Client expects 936 that the Broker maintains the session state after it disconnects. 937 However, stored Session state can be discarded as a result of 938 administrator policies, and Brokers SHOULD implement the necessary 939 policies to limit misuse. 941 The Client may set the Will Flag as desired (marked as 'X' in 942 Figure 8). Username and Password flags MUST be set to 1 to ensure 943 that the Payload of the CONNECT message includes both Username and 944 Password fields. 946 The CONNECT in MQTT v3.1.1 does not have a field to indicate the 947 authentication method. To signal that the Username field contains an 948 ACE token, this field MUST be prefixed with 'ace' keyword, which is 949 followed by the access token. The Password field MUST be set to the 950 keyed message digest (MAC) or signature associated with the access 951 token for proof-of-possession. The Client MUST apply the PoP key on 952 the challenge derived from the TLS session as described in 953 Section 2.2.4.1. 955 In MQTT v3.1.1, the MQTT Username as a UTF-8 encoded string (i.e. is 956 prefixed by a 2-byte length field followed by UTF-8 encoded character 957 data) and may be up to 65535 bytes. Therefore, an access token that 958 is not a valid UTF-8 MUST be Base64 [RFC4648] encoded. (The MQTT 959 Password allows binary data up to 65535 bytes.) 961 6.2. Handling Authorization Errors 963 Handling errors are more primitive in MQTT v3.1.1 due to not having 964 appropriate error fields, error codes, and server-side DISCONNECTs. 965 Therefore, the broker will disconnect on almost any error and may not 966 keep session state, necessitating clients to make a greater effort to 967 ensure that tokens remain valid and not attempt to publish to topics 968 that they do not have permissions for. The following lists how the 969 broker responds to specific errors. 971 o CONNECT without a token: It is not possible to support AS 972 discovery via sending a tokenless CONNECT message to the Broker. 973 This is because a CONNACK packet in MQTT v3.1.1 does not include a 974 means to provide additional information to the Client. Therefore, 975 AS discovery needs to take place out-of-band. CONNECT attempt 976 MUST fail. 978 o Client-RS PUBLISH authorization failure: In the case of a failure, 979 it is not possible to return an error in MQTT v3.1.1. 980 Acknowledgement messages only indicate success. In the case of an 981 authorization error, the Broker SHOULD disconnect the Client. 982 Otherwise, it MUST ignore the PUBLISH message. Also, as 983 DISCONNECT messages are only sent from a Client to the Broker, the 984 server disconnection needs to take place below the application 985 layer. 987 o SUBSCRIBE authorization failure: In the SUBACK packet, the return 988 code must be 0x80 indicating 'Failure' for the unauthorized 989 topic(s). Note that, in both MQTT versions, a reason code is 990 returned for each Topic Filter. 992 o RS-Client PUBLISH authorization failure: When RS is forwarding 993 PUBLISH messages to the subscribed Clients, it may discover that 994 some of the subscribers are no more authorized due to expired 995 tokens. These token expirations SHOULD lead to disconnecting the 996 Client rather than silently dropping messages. 998 7. IANA Considerations 1000 This document registers 'EXPORTER-ACE-MQTT-Sign-Challenge' from 1001 Section 2.2.4.1 in the TLS Exporter Label Registry TLS-REGISTRIES 1002 [RFC8447]. 1004 In addition, the following registrations are done for the ACE OAuth 1005 Profile Registry following the procedure specified in 1006 [I-D.ietf-ace-oauth-authz]. 1008 Note to the RFC editor: Please replace all occurrences of "[RFC- 1009 XXXX]" with the RFC number of this specification and delete this 1010 paragraph. 1012 Name: mqtt_tls 1013 Description: Profile for delegating Client authentication and 1014 authorization using MQTT as the application protocol and TLS For 1015 transport layer security. 1017 CBOR Value: 1019 Reference: [RFC-XXXX] 1021 8. Security Considerations 1023 This document specifies a profile for the Authentication and 1024 Authorization for Constrained Environments (ACE) framework 1025 [I-D.ietf-ace-oauth-authz]. Therefore, the security considerations 1026 outlined in [I-D.ietf-ace-oauth-authz] apply to this work. 1028 In addition, the security considerations outlined in MQTT v5.0 - the 1029 OASIS Standard [MQTT-OASIS-Standard-v5] and MQTT v3.1.1 - the OASIS 1030 Standard [MQTT-OASIS-Standard] apply. Mainly, this document provides 1031 an authorization solution for MQTT, the responsibility of which is 1032 left to the specific implementation in the MQTT standards. In the 1033 following, we comment on a few relevant issues based on the current 1034 MQTT specifications. 1036 After the RS validates an access token and accepts a connection from 1037 a client, it caches the token to authorize a Client's publish and 1038 subscribe requests in an ongoing session. RS does not cache any 1039 invalid tokens. If a client's permissions get revoked but the access 1040 token has not expired, the RS may still grant publish/subscribe to 1041 revoked topics. If the RS caches the token introspection responses, 1042 then the RS should use a reasonable cache timeout to introspect 1043 tokens regularly. When permissions change dynamically, it is 1044 expected that AS also follows a reasonable expiration strategy for 1045 the access tokens. 1047 The RS may monitor Client behaviour to detect potential security 1048 problems, especially those affecting availability. These include 1049 repeated token transfer attempts to the public "authz-info" topic, 1050 repeated connection attempts, abnormal terminations, and Clients that 1051 connect but do not send any data. If the RS supports the public 1052 "authz-info" topic, described in Section 2.2.2, then this may be 1053 vulnerable to a DDoS attack, where many Clients use the "authz-info" 1054 public topic to transport fictitious tokens, which RS may need to 1055 store indefinitely. 1057 For MQTT v5.0, when a Client connects with a long Session Expiry 1058 Interval, the RS may need to maintain Client's MQTT session state 1059 after it disconnects for an extended period. For MQTT v3.1.1, the 1060 session state may need to be stored indefinitely, as it does not have 1061 a Session Expiry Interval feature. The RS SHOULD implement 1062 administrative policies to limit misuse of the session continuation 1063 by the Client. 1065 9. Privacy Considerations 1067 The privacy considerations outlined in [I-D.ietf-ace-oauth-authz] 1068 apply to this work. 1070 In MQTT, the RS is a central trusted party and may forward 1071 potentially sensitive information between Clients. This document 1072 does not protect the contents of the PUBLISH message from the Broker, 1073 and hence, the content of the PUBLISH message is not signed or 1074 encrypted separately for the subscribers. This functionality may be 1075 implemented using the proposal outlined in the ACE Pub-Sub Profile 1076 [I-D.ietf-ace-pubsub-profile]. However, this solution would still 1077 not provide privacy for other properties of the message such as Topic 1078 Name. 1080 10. References 1082 10.1. Normative References 1084 [I-D.bormann-core-ace-aif] 1085 Bormann, C., "An Authorization Information Format (AIF) 1086 for ACE", draft-bormann-core-ace-aif-09 (work in 1087 progress), June 2020. 1089 [I-D.ietf-ace-oauth-authz] 1090 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1091 H. Tschofenig, "Authentication and Authorization for 1092 Constrained Environments (ACE) using the OAuth 2.0 1093 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-35 1094 (work in progress), June 2020. 1096 [I-D.ietf-ace-oauth-params] 1097 Seitz, L., "Additional OAuth Parameters for Authorization 1098 in Constrained Environments (ACE)", draft-ietf-ace-oauth- 1099 params-13 (work in progress), April 2020. 1101 [I-D.ietf-cose-x509] 1102 Schaad, J., "CBOR Object Signing and Encryption (COSE): 1103 Header parameters for carrying and referencing X.509 1104 certificates", draft-ietf-cose-x509-06 (work in progress), 1105 March 2020. 1107 [MQTT-OASIS-Standard] 1108 Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT 1109 Version 3.1.1 Plus Errata 01", 2015, . 1112 [MQTT-OASIS-Standard-v5] 1113 Banks, A., Ed., Briggs, E., Ed., Borgendale, K., Ed., and 1114 R. Gupta, Ed., "OASIS Standard MQTT Version 5.0", 2017, 1115 . 1118 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1119 Requirement Levels", BCP 14, RFC 2119, 1120 DOI 10.17487/RFC2119, March 1997, 1121 . 1123 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1124 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1125 . 1127 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 1128 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 1129 March 2010, . 1131 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1132 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1133 . 1135 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 1136 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 1137 Transport Layer Security (TLS) and Datagram Transport 1138 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 1139 June 2014, . 1141 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1142 Possession Key Semantics for JSON Web Tokens (JWTs)", 1143 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1144 . 1146 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1147 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1148 May 2017, . 1150 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1151 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1152 . 1154 [RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS 1155 and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018, 1156 . 1158 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 1159 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 1160 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 1161 2020, . 1163 10.2. Informative References 1165 [fremantle14] 1166 Fremantle, P., Aziz, B., Kopecky, J., and P. Scott, 1167 "Federated Identity and Access Management for the Internet 1168 of Things", research International Workshop on Secure 1169 Internet of Things, September 2014, 1170 . 1172 [I-D.ietf-ace-dtls-authorize] 1173 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 1174 L. Seitz, "Datagram Transport Layer Security (DTLS) 1175 Profile for Authentication and Authorization for 1176 Constrained Environments (ACE)", draft-ietf-ace-dtls- 1177 authorize-12 (work in progress), July 2020. 1179 [I-D.ietf-ace-pubsub-profile] 1180 Palombini, F., "Pub-Sub Profile for Authentication and 1181 Authorization for Constrained Environments (ACE)", draft- 1182 ietf-ace-pubsub-profile-01 (work in progress), July 2020. 1184 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1185 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1186 . 1188 Appendix A. Checklist for profile requirements 1190 o AS discovery: AS discovery is possible with the MQTT v5.0 1191 described in Section 2.2. 1193 o The communication protocol between the Client and RS: MQTT 1195 o The security protocol between the Client and RS: TLS 1197 o Client and RS mutual authentication: Several options are possible 1198 and described in Section 2.2.1. 1200 o Content format: For the HTTPS interactions with AS, "application/ 1201 ace+json". 1203 o PoP protocols: Either symmetric or asymmetric keys can be 1204 supported. 1206 o Unique profile identifier: mqtt_tls 1208 o Token introspection: RS uses HTTPS /introspect interface of AS. 1210 o Token request: Client or its Client AS uses HTTPS /token interface 1211 of AS. 1213 o /authz-info endpoint: It MAY be supported using the method 1214 described in Section 2.2.2, but is not protected. 1216 o Token transport: Via "authz-info" topic, or in MQTT CONNECT 1217 message for both versions of MQTT. AUTH extensions also used for 1218 authentication and re-authentication for MQTT v5.0 as described in 1219 Section 2.2 and in Section 4. 1221 Appendix B. Document Updates 1223 Version 06 to 07: 1225 o Corrected the title. 1227 o In Section 2.2.3, added the constraint on which packets the Client 1228 can send, and the server can process after CONNECT before CONNACK. 1230 o In Section 2.2.3, clarified that session state is identified by 1231 Client Identifier, and listed its content. 1233 o In Section 2.2.3, clarified the issue of Client Identifier 1234 collision, when the broker supports session continuation. 1236 o Corrected the buggy scope example in Section 3.1. 1238 Version 05 to 06: 1240 o Replace the originally proposed scope format with AIF model. 1241 Defined the AIF-MQTT, gave an example with a JSON array. Added a 1242 normative reference to the AIF draft. 1244 o Clarified client connection after submitting token via "authz- 1245 info" topic as TLS:Known(RPK/PSK)-MQTT:none. 1247 o Expanded acronyms on their first use including the ones in the 1248 title. 1250 o Added a definition for "Session". 1252 o Corrected "CONNACK" definition, which earlier said it's the first 1253 packet sent by the broker. 1255 o Added a statement that the the broker will disconnect on almost 1256 any error and may not keep session state. 1258 o Clarified that the broker does not cache invalid tokens. 1260 Version 04 to 05: 1262 o Reorganised Section 2 such that "Unauthorised Request: 1263 Authorisation Server Discovery" is presented under Section 2. 1265 o Fixed Figure 2 to remove the "empty" word. 1267 o Clarified that MQTT v5.0 Brokers may implement username/password 1268 option for transporting the ACE token only for MQTT v.3.1.1 1269 clients. This option is not recommended for MQTT v.5.0 clients. 1271 o Changed Clean Session requirement both for MQTT v.5.0 and v.3.1.1. 1272 The Broker SHOULD NOT, instead of MUST NOT, continue sessions. 1273 Clarified expected behaviour if session continuation is supported. 1274 Added to the Security Considerations the potential misuse of 1275 session continuation. 1277 o Fixed the Authentication Data to include token length for the 1278 Challenge/Response PoP. 1280 o Added that Authorisation Server Discovery is triggered if a token 1281 is invalid and not only missing. 1283 o Clarified that the Broker should not accept any other packets from 1284 Client after CONNECT and before sending CONNACK. 1286 o Added that client reauthentication is accepted only for the 1287 challenge/response PoP. 1289 o Added Ed25519 as mandatory to implement. 1291 o Fixed typos. 1293 Version 03 to 04: 1295 o Linked the terms Broker and MQTT server more at the introduction 1296 of the document. 1298 o Clarified support for MQTTv3.1.1 and removed phrases that might be 1299 considered as MQTTv5 is backwards compatible with MQTTv3.1.1 1301 o Corrected the Informative and Normative references. 1303 o For AS discovery, clarified the CONNECT message omits the 1304 Authentication Data field. Specified the User Property MUST be 1305 set to "ace_as_hint" for AS Request Creation Hints. 1307 o Added that MQTT v5 brokers MAY also implement reduced interactions 1308 described for MQTTv3.1.1. 1310 o Added to Section 3.1, in case of an authorisation failure and QoS 1311 level 0, the RS sends a DISCONNECT with reason code '0x87 (Not 1312 authorized)'. 1314 o Added a pointer to section 4.7 of MQTTv5 spec for more information 1315 on topic names and filters. 1317 o Added HS256 and RSA256 are mandatory to implement depending on the 1318 choice of symmetric or asymmetric validation. 1320 o Added MQTT to the TLS exporter label to make it application 1321 specific: 'EXPORTER-ACE-MQTT-Sign-Challenge'. 1323 o Added a format for Authentication Data so that length values 1324 prefix the token (or client nonce) when Authentication Data 1325 contains more than one piece of information. 1327 o Clarified clients still connect over TLS (server-side) for the 1328 authz-info flow. 1330 Version 02 to 03: 1332 o Added the option of Broker certificate thumbprint in the 'rs_cnf' 1333 sent to the Client. 1335 o Clarified the use of a random nonce from the TLS Exporter for PoP, 1336 added to the IANA requirements that the label should be 1337 registered. 1339 o Added a client nonce, when Challenge/Response Authentication is 1340 used between Client and Broker. 1342 o Clarified the use of the "authz-info" topic and the error response 1343 if token validation fails. 1345 o Added clarification on wildcard use in scopes for publish/ 1346 subscribe permissions 1348 o Reorganised sections so that token authorisation for publish/ 1349 subscribe messages are better placed. 1351 Version 01 to 02: 1353 o Clarified protection of Application Message payload as out of 1354 scope, and cited draft-palombini-ace-coap-pubsub-profile for a 1355 potential solution 1357 o Expanded Client connection authorization to capture different 1358 options for Client and Broker authentication over TLS and MQTT 1360 o Removed Payload (and specifically Client Identifier) from proof- 1361 of-possession in favor of using tls-exporter for a TLS-session 1362 based challenge. 1364 o Moved token transport via "authz-info" topic from the Appendix to 1365 the main text. 1367 o Clarified Will scope. 1369 o Added MQTT AUTH to terminology. 1371 o Typo fixes, and simplification of figures. 1373 Version 00 to 01: 1375 o Present the MQTTv5 as the RECOMMENDED version, and MQTT v3.1.1 for 1376 backward compatibility. 1378 o Clarified Will message. 1380 o Improved consistency in the use of terminology and upper/lower 1381 case. 1383 o Defined Broker and MQTTS. 1385 o Clarified HTTPS use for C-AS and RS-AS communication. Removed 1386 reference to actors document, and clarified the use of client 1387 authorization server. 1389 o Clarified the Connect message payload and Client Identifier. 1391 o Presented different methods for passing the token and PoP. 1393 o Added new figures to explain AUTH packets exchange, updated 1394 CONNECT message figure. 1396 Acknowledgements 1398 The authors would like to thank Ludwig Seitz for his review and his 1399 input on the authorization information endpoint, presented in the 1400 appendix. 1402 Authors' Addresses 1404 Cigdem Sengul 1405 Brunel University 1406 Dept. of Computer Science 1407 Uxbridge UB8 3PH 1408 UK 1410 Email: csengul@acm.org 1412 Anthony Kirby 1413 Oxbotica 1414 1a Milford House, Mayfield Road, Summertown 1415 Oxford OX2 7EL 1416 UK 1418 Email: anthony@anthony.org 1420 Paul Fremantle 1421 University of Portsmouth 1422 School of Computing, Buckingham House 1423 Portsmouth PO1 3HE 1424 UK 1426 Email: paul.fremantle@port.ac.uk