idnits 2.17.1 draft-sengul-ace-mqtt-tls-profile-01.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 355 has weird spacing: '...rotocol name ...' == Line 619 has weird spacing: '...rotocol name ...' -- The document date (October 12, 2017) is 2381 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) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-07 -- 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 (-07) exists of draft-ietf-ace-actors-05 == Outdated reference: A later version (-11) exists of draft-ietf-ace-cwt-proof-of-possession-00 Summary: 0 errors (**), 0 flaws (~~), 6 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 A. Kirby 4 Intended status: Standards Track Nominet 5 Expires: April 15, 2018 P. Fremantle 6 University of Portsmouth 7 October 12, 2017 9 MQTT-TLS profile of ACE 10 draft-sengul-ace-mqtt-tls-profile-01 12 Abstract 14 This document specifies a profile for the ACE (Authentication and 15 Authorization for Constrained Environments) to enable authorization 16 in an MQTT-based publish-subscribe messaging system. Proof-of- 17 possession keys, bound to OAuth2.0 access tokens, are used to 18 authenticate and authorize publishing and subscribing clients. The 19 protocol relies on TLS for confidentiality and server authentication. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on April 15, 2018. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 57 1.2. ACE-Related Terminology . . . . . . . . . . . . . . . . . 4 58 1.3. MQTT-Related Terminology . . . . . . . . . . . . . . . . 4 59 2. Basic Protocol Interactions . . . . . . . . . . . . . . . . . 5 60 2.1. Authorizing Connection Establishment . . . . . . . . . . 6 61 2.1.1. Client Authorization Server (CAS) and Authorization 62 Server (AS) Interaction . . . . . . . . . . . . . . . 7 63 2.1.2. Client connection request to the broker . . . . . . . 8 64 2.1.3. Token validation . . . . . . . . . . . . . . . . . . 10 65 2.1.4. The broker's response to client connection request . 11 66 2.2. Authorizing PUBLISH messages . . . . . . . . . . . . . . 11 67 2.2.1. PUBLISH messages from the publisher client to the 68 broker . . . . . . . . . . . . . . . . . . . . . . . 11 69 2.2.2. PUBLISH messages from the broker to the subscriber 70 clients . . . . . . . . . . . . . . . . . . . . . . . 12 71 2.3. Authorizing SUBSCRIBE messages . . . . . . . . . . . . . 12 72 2.4. Token expiration . . . . . . . . . . . . . . . . . . . . 13 73 2.5. Handling disconnections and retained messages . . . . . . 13 74 3. Improved Protocol Interactions with MQTT v5 . . . . . . . . . 14 75 3.1. Token Transport via Authentication Exchange (AUTH) . . . 14 76 3.2. Authorization Errors and Client Re-authentication . . . . 16 77 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 78 5. Security Considerations . . . . . . . . . . . . . . . . . . . 16 79 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 81 7.1. Normative References . . . . . . . . . . . . . . . . . . 17 82 7.2. Informative References . . . . . . . . . . . . . . . . . 17 83 Appendix A. Checklist for profile requirements . . . . . . . . . 18 84 Appendix B. The authorization information endpoint . . . . . . . 19 85 Appendix C. Document Updates . . . . . . . . . . . . . . . . . . 19 86 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 20 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 89 1. Introduction 91 This document specifies a profile for the ACE framework 92 [I-D.ietf-ace-oauth-authz]. In this profile, clients and a resource 93 server use MQTT to communicate. The protocol relies on TLS for 94 communication security between entities. The basic protocol 95 interactions follow MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard]. 96 This document also describes improvements to the basic protocol 97 operation with the new MQTT v5 - OASIS Specification Draft 98 [MQTT-OASIS-Standard-v5] (e.g., improved authentication exchange and 99 error reporting). Both versions are expected to be supported in 100 practice, and therefore, covered in this document. 102 MQTT is a publish-subscribe protocol and supports two types of client 103 operation: publish and subscribe. Once connected, a client can 104 publish to multiple topics, and subscribe to multiple topics; 105 however, for the purpose of this document these actions are described 106 separately. The MQTT broker is responsible for distributing messages 107 published by the publishers to the appropriate subscribers. Each 108 publish message contains a topic, which is used by the broker to 109 filter the subscribers for the message. Subscribers must subscribe 110 to the topics to receive the corresponding messages. 112 In this document, message topics are treated as resources. Clients 113 use an access token, bound to a key (the proof-of-possession key) to 114 authorize with the MQTT broker their connection and publish/subscribe 115 permissions to topics. In the context of this ACE profile, the MQTT 116 broker acts as the resource server. In order to provide 117 communication confidentiality and resource server authentication, TLS 118 is used. 120 Clients use client authorization servers [I-D.ietf-ace-actors] to 121 obtain tokens from the authorization server. The communication 122 protocol between the client authorization server and the 123 authorization server is assumed to be HTTPS. Also, if the broker 124 supports token introspection, it is assumed to use HTTPS to 125 communicate with the authorization server. These interfaces MAY be 126 implemented using other protocols e.g., CoAP or MQTT. This document 127 makes the same assumptions as the Section 4 of the ACE framework 128 [I-D.ietf-ace-oauth-authz] in terms of client and RS registration 129 with the AS and establishing of keying material. 131 This document describes authorization of the following exchanges 132 between publisher and subscriber clients, and the broker. 134 o Connection establishment between the clients and the broker 136 o Publish messages from the publishers to the broker, and from the 137 broker to the subscribers 139 o Subscribe messages from the subscribers to the broker 141 In Section 2, these exchanges are described based on the MQTT v3.1 - 142 OASIS Standard [MQTT-OASIS-Standard]. These exchanges are also 143 supported by the new MQTT v5 - OASIS Specification Draft 145 [MQTT-OASIS-Standard-v5]. Section 3 describes how they may be 146 improved by the new MQTT v5. 148 1.1. Requirements Language 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 152 document are to be interpreted as described in RFC 2119 [RFC2119]. 154 1.2. ACE-Related Terminology 156 The terminology for entities in the architecture is defined in OAuth 157 2.0 RFC 6749 [RFC6749] and ACE actors [I-D.ietf-ace-actors], such as 158 "Client" (C), "Resource Server" (RS) and "Authorization Server" (AS). 160 The term "endpoint" is used following its OAuth definition, to denote 161 resources such as /token and /introspect at the AS. 163 The term "Resource" is used to refer to an MQTT "topic", which is 164 defined in Section 1.2. Hence, the "Resource Owner" is any entity 165 that can authoritatively speak for the "topic". 167 Certain security-related terms such as "authentication", 168 "authorization", "confidentiality", "(data) integrity", "message 169 authentication code", and "verify" are taken from RFC 4949 [RFC4949]. 171 1.3. MQTT-Related Terminology 173 The document describes message exchanges as MQTT protocol 174 interactions. For additional information, please refer to the MQTT 175 v3.1 - OASIS Standard [MQTT-OASIS-Standard] or the MQTT v5 - OASIS 176 Specification Draft [MQTT-OASIS-Standard-v5]. 178 Topic name 179 The label attached to an application message, which is 180 matched to a subscription. 182 Topic filter 183 An expression that indicates interest in one or more topic 184 names. Topic filters may include wildcards. 186 Subscription 187 A subscription comprises of a Topic filter and a maximum 188 quality of service (QoS). 190 Application Message 191 The data carried by the MQTT protocol. The data has an 192 associated QoS level and a Topic name. 194 MQTT sends various control messages across a network connection. The 195 following is not an exhaustive list and the control packets that are 196 not relevant for authorization are not explained. These include, for 197 instance, the PUBREL and PUBCOMP packets used in the 4-step handshake 198 required for the QoS level 2. 200 CONNECT 201 Client request to connect to the broker. After a network 202 connection is established, this is the first packet sent by a 203 client. 205 CONNACK 206 The broker connection acknowledgment. The first packet sent 207 from the broker to a client is a CONNACK packet. CONNACK 208 packets contain return codes indicating either a success or 209 an error state to a client. 211 PUBLISH 212 Publish packet that can be sent from a client to the broker, 213 or from the broker to a client. 215 PUBACK 216 Response to PUBLISH packet with QoS level 1. PUBACK can be 217 sent from the broker to a client or a client to the broker. 219 PUBREC 220 Response to PUBLISH packet with QoS level 2. PUBREC can be 221 sent from the broker to a client or a client to the broker. 223 SUBSCRIBE 224 The client subscribe request. 226 SUBACK 227 Subscribe acknowledgment. 229 2. Basic Protocol Interactions 231 This section describes the following exchanges between publisher and 232 subscriber clients, the broker, and the authorization server 233 according to the MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard]. 234 These exchanges are compatible also with the new MQTT v5 - OASIS 235 Specification Draft [MQTT-OASIS-Standard-v5]. In addition, Section 3 236 describes how these exchanges may be improved with the MQTT v5. 238 o Authorizing connection establishment between the clients and the 239 broker 241 o Authorizing publish messages from the publishers to the broker, 242 and from the broker to the subscribers 244 o Authorizing subscribe messages from the subscribers to the broker 246 Message topics are treated as resources. The publisher and 247 subscriber clients are assumed to have identified the topics of 248 interest out-of-band (topic discovery is not a feature of the MQTT 249 protocol). 251 A connection request carries a token specifying the permissions that 252 the client has (e.g., publish permission to a given topic). A 253 resource owner can pre-configure policies at the AS that give clients 254 publish or subscribe permissions to different topics. 256 2.1. Authorizing Connection Establishment 258 This section specifies how publishers and subscribers establish an 259 authorized connection to an MQTT broker. The token request and 260 response use the /token endpoint of the authorization server, as 261 specified in Section 6 of the ACE framework 262 [I-D.ietf-ace-oauth-authz]. 264 Figure 1 shows the basic protocol flow during connection 265 establishment. 267 +----------------+ 268 +---(A) Token request----| Client | 269 | | Authorization | 270 | +-(B) Access token-->| Server | 271 | | |________________| 272 | | | 273 | | (C) Client On-boarding 274 | | | 275 | | +---------v-----+ 276 +--v-------------+ | Publisher or | 277 | | | Subscriber | 278 | Authorization | |_______________| 279 | Server | | ^ 280 |________________| | | 281 | ^ (D)Connection (G)Connection 282 | | request + response 283 | | access token | 284 | | | | 285 | | +---v--------------+ 286 | | | Broker | 287 | +(E)Introspection-| Resource Server | 288 | request | | 289 +-(F)Introspection---->|__________________| 290 response 292 Figure 1: Connection establishment 294 2.1.1. Client Authorization Server (CAS) and Authorization Server (AS) 295 Interaction 297 The first step in the protocol flow (Figure 1 (A)) is token 298 acquisition by the client authorization server (CAS) from the AS. If 299 a client has enough resources and can support HTTPS, or optionally 300 the AS supports MQTTS, these steps can instead be carried out by a 301 client directly. 303 When requesting an access token from the AS, the CAS MAY include 304 parameters in its request as defined in Section 6.1 of the ACE 305 framework [I-D.ietf-ace-oauth-authz]. The content type is set to 306 "application/json". The profile name is 'mqtt_tls'. 308 If the access token request has been successfully verified by the AS 309 and the client is authorized to obtain a token for the indicated 310 audience (e.g., topics) and scopes (e.g., publish/subscribe 311 permissions), the AS issues an access token (Figure 1 (B)). The 312 response includes the parameters described in Section 6.2 of the ACE 313 framework [I-D.ietf-ace-oauth-authz]. This includes a token, which 314 is assumed to be PoP by default. Hence, a 'cnf' parameter with a 315 symmetric or asymmetric PoP key is returned. The token may be a 316 reference, or a CBOR or JWT web token. Note that the 'cnf' parameter 317 in the web tokens are to be consumed by the resource server and not 318 the client. For more information on Proof of Possession semantics in 319 JWTs see RFC 7800 [RFC7800] and for CWTs, see Proof-of-Possession Key 320 Semantics for CBOR Web Tokens (CWTs) 321 [I-D.ietf-ace-cwt-proof-of-possession]. 323 In the case of an error, the AS returns error responses for HTTP- 324 based interactions as ASCII codes in JSON content, as defined in 325 Section 5.2 of RFC 6749 [RFC6749]. 327 2.1.2. Client connection request to the broker 329 Client on-boarding (Figure 1 (C)) is out of the scope of this 330 document. Once the client acquires the token, it can use it to 331 request an MQTT connection to the broker over a TLS session with 332 server authentication (Figure 1 (D)). This section describes the 333 client transporting the token to the broker (RS) via the CONNECT 334 control message after the TLS handshake. This is similar to an 335 earlier proposal by Fremantle et al. [fremantle14]. An improvement 336 to this is presented in Section 3 for the MQTT v5 - OASIS 337 Specification Draft [MQTT-OASIS-Standard-v5]. Alternatively, the 338 token may be used for the TLS session establishment as described in 339 the DTLS profile for ACE [I-D.gerdes-ace-dtls-authorize]. In this 340 case, both the TLS PSK and RPK handshakes MAY be supported. This may 341 additionally require that the client transports the token to the 342 broker before the connection establishment. To this end, the broker 343 MAY support /authz-info endpoint via the "authz-info" topic. Then, 344 to transport the token, clients publish to "authz-info" topic 345 unauthorized. The topic "authz-info" MUST be publish-only for 346 clients (i.e., the clients are not allowed to subscribe to it). This 347 option is described in more detail in Appendix B. 349 When the client wishes to connect to the broker, it uses the CONNECT 350 message of MQTT. Figure 2 shows the structure of the MQTT CONNECT 351 control message. 353 0 8 16 24 32 354 +------------------------------------------------------+ 355 |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | 356 +------------------------------------------------------+ 357 | 'M' 'Q' 'T' 'T' | 358 +------------------------------------------------------+ 359 | Proto.level=4|Connect flags| Keep alive | 360 +------------------------------------------------------+ 361 | Payload including User Name (='token') | 362 | Password length and data (=signature/MAC) | 363 | ... | 364 +------------------------------------------------------+ 366 Figure 2: MQTT CONNECT control message. (CPT=Control Packet Type, 367 Rsvd=Reserved, len.=length, Proto.=Protocol) 369 To communicate the necessary connection parameters, the Client uses 370 the appropriate flags of the CONNECT message. Figure 3 shows how the 371 MQTT connect flags MUST be set to initiate a connection with the 372 broker. 374 +-----------------------------------------------------------+ 375 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 376 | flag |flag | | | | | | 377 +-----------------------------------------------------------+ 378 | 1 | 1 | X | X X | X | 1 | 0 | 379 +-----------------------------------------------------------+ 381 Figure 3: MQTT CONNECT flags. (Rsvd=Reserved) 383 In order to ensure that the client and the broker discard any 384 previous session and start a new session, the Clean Session Flag MUST 385 be set to 1. 387 The Will flag indicates that a Will message needs to be sent when a 388 client disconnection occurs. The situations in which the Will 389 message is published include disconnections due to I/O or network 390 failures, and the server closing the networking connection due to a 391 protocol error. The client may set the Will flag as desired (marked 392 as 'X' in Figure 3). If the Will flag is set to 1 and the broker 393 accepts the connection request, the broker must store the Will 394 message, and publish it when the network connection is closed 395 according to Will QoS and Will retain parameters, and MQTT Will 396 management rules. Section 2.5 explains how the broker deals with the 397 retained messages in further detail. 399 Finally, Username and Password flags MUST be set to 1 to ensure that 400 the Payload of the CONNECT message includes both Username and 401 Password fields. 403 The CONNECT message defaults to ACE for authentication and 404 authorization. For the basic operation described in this section, 405 the Username field MUST be set to the token. The Password field MUST 406 be set to the keyed message digest (MAC) or signature. The client 407 MAY apply the PoP key either to the token or the entire request by 408 computing a keyed message digest (for symmetric key) or a digital 409 signature (for asymmetric key). (The Username field is a UTF-8 410 encoded string, which is prefixed with a two-byte length field and 411 can have any length in the range of 0 and 65535. Similarly, the 412 password field contains 0 to 65535 bytes of binary data, prefixed by 413 a two-byte length field.) 415 2.1.3. Token validation 417 RS MUST verify the validity of the token. This validation MAY be 418 done locally (e.g., in the case of a self-contained token) or the RS 419 MAY send an introspection request to the AS. If introspection is 420 used, this section follows similar steps to those described in 421 Sections 7.2 and 7.3 of the ACE framework [I-D.ietf-ace-oauth-authz]. 422 The communication between AS and RS MAY be HTTPS, but it, in every 423 case, MUST be confidential, mutually authenticated and integrity 424 protected. 426 The broker MUST check if the token is active either using 427 'expires_in' parameter of the token or 'active' parameter of the 428 introspection response. 430 The access token is constructed by the AS such that RS can associate 431 the access token with the client key. This document assumes that the 432 Access Token is a PoP token as described in 433 [I-D.ietf-ace-oauth-authz]. Therefore, the necessary information is 434 contained in the 'cnf' claim of the access token and may use either 435 public or shared key approaches. The client uses the signature or 436 the MAC in the password field to prove the possession of the key. 437 Depending on the chosen implementation, the resource server validates 438 the signature or the MAC over the token or the contents of the 439 packet, authenticating the client. 441 The broker uses the scope field in the token (or in the introspection 442 result) to determine the publish and subscribe permissions for the 443 client. If the Will flag is set, then the broker MUST check that the 444 token allows the publication of the Will message too. 446 The broker MAY cache the introspection result because it will need to 447 decide whether to accept subsequent PUBLISH and SUBSCRIBE messages 448 and these messages, which are sent after a connection is set-up, do 449 not contain tokens. If the introspection result is not cached, then 450 the RS needs to introspect the saved token for each request. 452 Note: Scope strings MAY follow an application specific convention. 453 One option is to encode the permission and the topics it applies into 454 the scope string e.g., 'publish_topic1' or 'subscribe_topic2'. A 455 second option is to simply use the keywords 'publish' or 'subscribe' 456 as scope strings and use the 'aud' field to define the topic. 457 Another option is to use topic names as scope strings and use the 458 'aud' field to define whether the 'publish' or 'subscribe' permission 459 applies to these scopes. The choice is left to the implementer and 460 depends on how the following trade-off is expected to be handled: 461 token simplicity versus the number of tokens the broker is expected 462 to handle per client. 464 2.1.4. The broker's response to client connection request 466 Based on the validation result (obtained either via local inspection 467 or using the /introspection interface of the AS), the broker MUST 468 send a CONNACK message to the client. 470 The broker responses may follow either the MQTT v3.1 - OASIS Standard 471 [MQTT-OASIS-Standard] or the MQTT v5 - OASIS Specification Draft 472 [MQTT-OASIS-Standard-v5], depending on which version(s) the broker 473 supports. 475 In MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], it is not 476 possible to support AS discovery via sending a tokenless CONNECT 477 message to the broker. This is because a CONNACK packet does not 478 include a means to provide additional information to the client. 479 Therefore, AS discovery needs to take place out-of-band. This is 480 remedied in the MQTT v5 - OASIS Specification Draft 481 [MQTT-OASIS-Standard-v5] and a solution is described in Section 3. 483 If the RS accepts the connection, it MUST store the token. 485 2.2. Authorizing PUBLISH messages 487 2.2.1. PUBLISH messages from the publisher client to the broker 489 On receiving the PUBLISH message, the broker MUST use the type of 490 message (i.e., PUBLISH) and the topic name in the message header to 491 compare against the cached token or its introspection result 492 (depending on the implementation, different fields of the token or 493 the introspection result may be checked, see the Note in 494 Section 2.1.3). 496 If the client is allowed to publish to the topic, the RS must publish 497 the message to all valid subscribers of the topic. The broker may 498 also return an acknowledgment message if the QoS level is greater 499 than or equal to 1. 501 In case of a failure, it is not possible to return an error in MQTT 502 v3.1 - OASIS Standard [MQTT-OASIS-Standard]. The return of 503 acknowledgement messages only indicates success. In the case of an 504 authorization error, the broker SHOULD disconnect the client. 505 Otherwise, it MUST ignore the PUBLISH message. Also, DISCONNECT 506 messages are only sent from a client to the broker. So, server 507 disconnection needs to take place below the application layer. 508 However, in MQTT v5 - OASIS Specification Draft 509 [MQTT-OASIS-Standard-v5], it is possible to indicate failure and 510 provide a reason code. Section 3 describes in more detail how 511 PUBLISH authorization errors are handled. 513 2.2.2. PUBLISH messages from the broker to the subscriber clients 515 To forward PUBLISH messages to the subscribing clients, the broker 516 identifies all the subscribers that have matching valid topic 517 subscriptions (i.e., the tokens are valid and token scopes allow a 518 subscription to the particular topic name). The broker sends a 519 PUBLISH message with the topic name and the topic message to all the 520 valid subscribers. 522 In MQTT, after connection establishment, there is no way to inform a 523 client that an authorization error has occurred for previously 524 subscribed topics, e.g., token expiry. In the case of an 525 authorization error, the broker has two options: (1) stop forwarding 526 PUBLISH messages to the unauthorized client or (2) disconnect the 527 client. In the MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], the 528 MQTT DISCONNECT messages are only sent from a client to the broker. 529 Therefore, the server disconnection needs to take place below the 530 application layer. In MQTT v5 - OASIS Specification Draft 531 [MQTT-OASIS-Standard-v5], server-side DISCONNECT messages are 532 possible, and are described in Section 3. 534 2.3. Authorizing SUBSCRIBE messages 536 In MQTT, a SUBSCRIBE message is sent from a client to the broker to 537 create one or more subscriptions to one or more topics. The 538 SUBSCRIBE message may contain multiple topic filters. The topic 539 filters may include wildcard characters. 541 On receiving the SUBSCRIBE message, the broker MUST use the type of 542 message (i.e., SUBSCRIBE) and the topic filter in the message header 543 to compare against the stored token or introspection result 544 (depending on the implementation, different fields of the token or 545 introspection result may be checked, see the Note in Section 2.1.3). 547 As a response to the SUBSCRIBE message, the broker issues a SUBACK 548 message. For each topic filter, the SUBACK packet includes a return 549 code matching the QoS level for the corresponding topic filter. In 550 the case of failure, the return code, in MQTT v3.1, must be 0x80 551 indicating 'Failure'. In MQTT v5, the appropriate return code is 552 0x87, indicating that the client is 'Not authorized'. Note that, in 553 both MQTT versions, a reason code is returned for each topic filter. 554 Therefore, the client may receive success codes for a subset of its 555 topic filters, while being unauthorized for the rest. 557 2.4. Token expiration 559 The broker checks for token expiration whenever a CONNECT, PUBLISH or 560 SUBSCRIBE message is received or sent. The validation is done either 561 by checking the 'exp' claim of a CWT/JWT or via performing an 562 introspection request with the Authorization server as described in 563 Section 8.2 of the ACE framework [I-D.ietf-ace-oauth-authz]. In the 564 basic operation, token expirations MAY lead to disconnecting the 565 associated client. However, in MQTT v5 - OASIS Specification Draft 566 [MQTT-OASIS-Standard-v5], better error handling and re-authentication 567 are possible. This is explained in more detail in Section 3. 569 2.5. Handling disconnections and retained messages 571 According to MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], only 572 Client DISCONNECT messages are allowed. In MQTT v5 - OASIS 573 Specification Draft [MQTT-OASIS-Standard-v5], server-side DISCONNECT 574 messages are possible, allowing to return '0x87 Not Authorized' 575 return code to the client. 577 In the case of a DISCONNECT, due to the Clean Session flag, the 578 broker deletes all session state but MUST keep the retained messages. 579 By setting a RETAIN flag in a PUBLISH message the publisher indicates 580 to the broker that it should store the most recent message for the 581 associated topic. Hence, the new subscribers can receive the last 582 sent message from the publisher for that particular topic, without 583 waiting for the next PUBLISH message. In the case of a 584 disconnection, the broker MUST continue publishing the retained 585 messages as long as the associated tokens are valid. 587 In case of disconnections due to network errors, or server 588 disconnection due to a protocol error (which includes authorization 589 errors), the Will message must be sent if the client supplied a Will 590 in the CONNECT request message. The token provided in the CONNECT 591 request must cover the Will topic. The Will message MUST be 592 published to the Will topic when the network connection is closed 593 regardless of whether the corresponding token has expired. 595 3. Improved Protocol Interactions with MQTT v5 597 In the new MQTT v5 - OASIS Specification Draft 598 [MQTT-OASIS-Standard-v5], several new capabilities are introduced, 599 which enables better integration with the ACE standards. For 600 instance, the new enhanced authentication and re-authentication 601 methods support a much wider range of authentication flows beyond 602 username and password. With the MQTT v5, there is a clearly defined 603 approach for using token-based approaches. Similarly, in MQTT v5, it 604 is possible for a client to request a re-authentication. Finally, 605 MQTT v5 generally improves error reporting, enabling better response 606 to authorization failures during publishing and forwarding of 607 messages to the subscribers. 609 3.1. Token Transport via Authentication Exchange (AUTH) 611 To initiate the authentication and authorization flow, as before, the 612 CAS initiates the token request as in Section 2.1. When the client 613 wishes to connect to the RS (broker), it uses the CONNECT message of 614 MQTT. Figure 4 shows the structure of the MQTT CONNECT control 615 message used in MQTT v5. 617 0 8 16 24 32 618 +------------------------------------------------------+ 619 |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | 620 +------------------------------------------------------+ 621 | 'M' 'Q' 'T' 'T' | 622 +------------------------------------------------------+ 623 | Proto.level=5|Connect flags| Keep alive | 624 +------------------------------------------------------+ 625 | Property length | 626 | Auth. Method (0x15) | 'ace_mqtt_tls' | 627 | Auth. Data (0x16) | empty or token | 628 | | 629 +------------------------------------------------------+ 631 Figure 4: MQTT CONNECT control message. (CPT=Control Packet Type, 632 Rsvd=Reserved, len.=length, Proto.=Protocol) 634 To communicate the necessary connection parameters, the client uses 635 the appropriate flags of the CONNECT message. To achieve a clean 636 session (i.e., the session should start without an existing session), 637 the new MQTT v5 session flags MUST be set appropriately. More 638 specifically, the Clean Start Flag MUST be set to 1 and Session 639 Expiry Interval MUST be set to 0. 641 With the enhanced authentication capabilities, it is no more 642 necessary to overload the username and password fields in the CONNECT 643 message for ACE authentication. Nevertheless, the RS MUST support 644 both methods for supporting the token: (1) Token transport via 645 username and password and (2) using the new AUTH (Authentication 646 Exchange) method. The token transport via username and password is 647 as described in Section 2.1.2. The rest of this section describes 648 the AUTH method. 650 To use the AUTH method, the username flag MUST be set to 0 and the 651 password flag MUST be set to 0. The client can set the 652 Authentication Method as a property of a CONNECT packet by setting 653 Auth Properties (with the property identifier 0x15). The client must 654 MUST set the UTF-8 encoded string containing the name of the 655 authentication method as 'ace_mqtt_tls'. If the RS does not support 656 this profile, it sends a CONNACK with a Reason Code of '0x8C (Bad 657 authentication method)' 659 Authentication Method is followed with Authentication Data, which has 660 a property identifier 0x16. Authentication data is binary data and 661 is defined by the authentication method. The RS MAY support 662 different implementations for transporting the authentication data. 663 The first option is that Authentication data contains both the token 664 and the keyed message digest (MAC) or signature as described in 665 Section 2.1.2. In this case, the token validation proceeds as 666 described in Section 2.1.3 and the the server responds with a 667 CONNACK. The reason code of the CONNACK '0x00 (Success)' if the 668 authentication is successful. In case of an invalid PoP token, the 669 CONNACK reason code is '0x87 (Not Authorized)'. 671 The second option that RS may accept is a challenge/response 672 protocol. If the Authentication Data only includes the token, the RS 673 MUST respond with an AUTH packet, with the Authenticate Reason Code 674 set to '0x18 (Continue Authentication)'. This packet includes the 675 Authentication Method, which MUST be set to 'ace_mqtt_tls' and 676 Authentication Data. The Authentication Data MUST NOT be empty and 677 contains a challenge for the client. The client responds to this 678 with an AUTH packet, with a reason code '0x18 (Continue 679 Authentication)'. Similarly, the client packet sets the 680 Authentication Method to 'ace_mqtt_tls'. The Authentication Data in 681 the client's response contains the signature or MAC computed over the 682 RS's challenge. To this, the server responds with a CONNACK and a 683 return code of '0x00 (Success)' if the authentication is successful. 685 In case of an invalid PoP token, the CONNACK reason code is '0x87 686 (Not Authorized)'. 688 Finally, this document allows the CONNECT message to have an empty 689 Authentication Data field. This is the AS discovery option and the 690 RS responds with a CONNACK reason code '0x87 (Not Authorized)' and 691 includes a User Property set to the address of the AS. 693 3.2. Authorization Errors and Client Re-authentication 695 MQTT v5 allows better error reporting. To take advantage of this for 696 PUBLISH messages, the QoS level should be set to greater than or 697 equal to 1. This guarantees the RS to respond with either a PUBACK 698 or PUBREC packet, with a reason code '0x87 (Not authorized)' in the 699 case of an authorization error. Similarly, for the SUBSCRIBE case, 700 the SUBACK packet will have a reason code set to '0x87 (Not 701 authorized)' for the unauthorized topic(s). When RS is forwarding 702 PUBLISH messages to the subscribed clients, it may discover that some 703 of the subscribers are no more authorized due to expired tokens. In 704 this case, the RS SHOULD send a DISCONNECT message with the reason 705 code '0x87 (Not authorized)'. Note that the server-side DISCONNECT 706 is a new feature of MQTT v5 (in MQTT v3.1 server needed to drop the 707 connection). RS MUST stop forwarding messages to these unauthorized 708 subscribers. 710 In the case of a PUBACK with '0x87 (Not authorized)', the client can 711 update its token using the Re-authentication feature of MQTT v5. 712 Also, the clients can proactively update their tokens, without 713 waiting for such a PUBACK. To re-authenticate, the client sends an 714 AUTH packet with a reason code '0x19 (Re-authentication)'. The 715 client MUST send the authentication method as 'ace_mqtt_tls' and 716 transports the new token in the Authentication Data. The client and 717 the RS go through the same steps for proof of possession validation 718 described in the previous section. This flow ends with either re- 719 authentication is complete or re-authentication fails. If the re- 720 authentication fails, the server MUST send a DISCONNECT with the 721 reason code '0x87 (Not Authorized)'. 723 4. IANA Considerations 725 This memo includes no request to IANA. 727 5. Security Considerations 729 The security considerations outlined in [I-D.ietf-ace-oauth-authz] 730 apply to this work. 732 6. Privacy Considerations 734 The privacy considerations outlined in [I-D.ietf-ace-oauth-authz] 735 apply to this work. Furthermore, the RS is a central trusted party 736 and may forward potentially sensitive information between clients. 738 7. References 740 7.1. Normative References 742 [I-D.gerdes-ace-dtls-authorize] 743 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 744 L. Seitz, "Datagram Transport Layer Security (DTLS) 745 Profile for Authentication and Authorization for 746 Constrained Environments (ACE)", draft-gerdes-ace-dtls- 747 authorize-01 (work in progress), March 2017. 749 [I-D.ietf-ace-oauth-authz] 750 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 751 H. Tschofenig, "Authentication and Authorization for 752 Constrained Environments (ACE)", draft-ietf-ace-oauth- 753 authz-07 (work in progress), August 2017. 755 [MQTT-OASIS-Standard] 756 Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT 757 Version 3.1.1 Plus Errata 01", 2015, . 760 [MQTT-OASIS-Standard-v5] 761 Banks, A., Ed., Briggs, E., Ed., Borgendale, K., Ed., and 762 R. Gupta, Ed., "OASIS Public Review Draft 01 MQTT Version 763 5.0", 2017, . 766 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 767 Requirement Levels", BCP 14, RFC 2119, 768 DOI 10.17487/RFC2119, March 1997, 769 . 771 7.2. Informative References 773 [fremantle14] 774 Fremantle, P., Aziz, B., Kopecky, J., and P. Scott, 775 "Federated Identity and Access Management for the Internet 776 of Things", research International Workshop on Secure 777 Internet of Things, September 2014, 778 . 780 [I-D.ietf-ace-actors] 781 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 782 architecture for authorization in constrained 783 environments", draft-ietf-ace-actors-05 (work in 784 progress), March 2017. 786 [I-D.ietf-ace-cwt-proof-of-possession] 787 Jones, M., Seitz, L., Selander, G., Wahlstroem, E., 788 Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key 789 Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt- 790 proof-of-possession-00 (work in progress), September 2017. 792 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 793 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 794 . 796 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 797 RFC 6749, DOI 10.17487/RFC6749, October 2012, 798 . 800 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 801 Possession Key Semantics for JSON Web Tokens (JWTs)", 802 RFC 7800, DOI 10.17487/RFC7800, April 2016, 803 . 805 Appendix A. Checklist for profile requirements 807 o AS discovery: For the basic protocol using either MQTT v3.1 or 808 MQTT v5, the clients/client authorization servers need to be 809 configured out-of-band. RS does not provide any hints to help AS 810 discovery. AS discovery is possible with the MQTT v5 extensions 811 described in Section 3. 813 o Communication protocol between the client and RS: MQTT 815 o Security protocol between the client and RS: TLS 817 o Client and RS mutual authentication: RS provides a server 818 certificate during TLS handshake. Client transports token and MAC 819 via the MQTT CONNECT message. 821 o Content format: For the HTTPS interactions with AS, "application/ 822 json". The MQTT payloads may be formatted JSON or CBOR. 824 o PoP protocols: Either symmetric or asymmetric keys can be 825 supported. 827 o Unique profile identifier: mqtt_tls 828 o Token introspection: RS uses HTTPS /introspect interface of AS. 830 o Token request: CAS uses HTTPS /token interface of AS. 832 o /authz-info endpoint: It MAY be supported using the method 833 described in Appendix B, not protected. 835 o Token transport: In MQTT CONNECT message or using the AUTH 836 extensions for MQTT v5 described in Section 3. 838 Appendix B. The authorization information endpoint 840 The main document described a method for transporting tokens inside 841 MQTT CONNECT messages. In this section, we describe an alternative 842 method to transport an access token. 844 The method consists of the MQTT broker accepting PUBLISH messages to 845 a public "authz-info" topic. A client using this method MUST first 846 connect to the broker, and publish the access token using the "authz- 847 info" topic. The broker must verify the validity of the token (i.e., 848 through local validation or introspection). After publishing the 849 token, the client disconnects from the broker and is expected to try 850 reconnecting over TLS. 852 In MQTT v3.1, after the client published to the "authz-info" topic, 853 it is not possible for the broker to communicate the result of the 854 token verification. In MQTT v5, the broker can return 'Not 855 authorized' error to a PUBLISH request for QoS greater or equal to 1. 856 In any case, any token authorization failure will affect the TLS 857 handshake, which can prompt the client to obtain a valid token. 859 Appendix C. Document Updates 861 This new version updates the expired document (July 29, 2017) as 862 follows: 864 o Adds Section 3 to describe improvements to the basic protocol 865 operation with the new MQTT v5 - OASIS Specification Draft 866 [MQTT-OASIS-Standard-v5], including improved authentication 867 exchange and error reporting. 869 o Condenses background information specific to MQTT in Section 2. 871 o Clarifies token transport and token structure in Section 2.1.2 and 872 Section 2.1.3. 874 o Removes Appendix on error reporting as this is now handled with 875 MQTT v5. 877 Acknowledgements 879 The authors would like to thank Ludwig Seitz for his input on the 880 authorization information endpoint, presented in the appendix. 882 Authors' Addresses 884 Cigdem Sengul 885 Nominet 886 2 Kingdom Street 887 London W2 6BD 888 UK 890 Email: Cigdem.Sengul@nominet.uk 892 Anthony Kirby 893 Nominet 894 Minerva House, Edmund Halley Road 895 Oxford OX4 4DQ 896 UK 898 Email: Anthony.Kirby@nominet.uk 900 Paul Fremantle 901 University of Portsmouth 902 School of Computing, Buckingham House 903 Portsmouth PO1 3HE 904 UK 906 Email: paul.fremantle@port.ac.uk