idnits 2.17.1 draft-sengul-ace-mqtt-tls-profile-00.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 335 has weird spacing: '...rotocol name ...' -- The document date (January 25, 2017) is 2648 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 (-01) exists of draft-gerdes-ace-dtls-authorize-00 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-04 -- Possible downref: Non-RFC (?) normative reference: ref. 'MQTT-OASIS-Standard' == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-04 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 2 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: July 29, 2017 January 25, 2017 7 MQTT-TLS profile of ACE 8 draft-sengul-ace-mqtt-tls-profile-00 10 Abstract 12 This document specifies a profile for the ACE (Authentication and 13 Authorization for Constrained Environments) to enable authorization 14 in an MQTT-based publish-subscribe messaging system. Proof-of- 15 possession keys, bound to OAuth2.0 access tokens, are used to 16 authenticate and authorize publishing and subscribing clients. The 17 protocol relies on TLS for confidentiality and server authentication. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on July 29, 2017. 36 Copyright Notice 38 Copyright (c) 2017 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 1.2. ACE-Related Terminology . . . . . . . . . . . . . . . . . 4 56 1.3. MQTT-Related Terminology . . . . . . . . . . . . . . . . 4 57 2. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 5 58 2.1. Authorizing Connection Establishment . . . . . . . . . . 6 59 2.1.1. Client Authorization Server (CAS) to Authorization 60 Server (AS) . . . . . . . . . . . . . . . . . . . . . 6 61 2.1.2. Authorization Server (AS) to Client Authorization 62 Server (CAS) . . . . . . . . . . . . . . . . . . . . 7 63 2.1.3. Client connection request to the broker . . . . . . . 7 64 2.1.4. Token validation . . . . . . . . . . . . . . . . . . 9 65 2.1.5. The broker's response to client connection request . 10 66 2.2. Authorizing PUBLISH messages . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . 13 74 2.6. Handling retained messages . . . . . . . . . . . . . . . 14 75 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 76 4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 77 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 78 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 79 6.1. Normative References . . . . . . . . . . . . . . . . . . 15 80 6.2. Informative References . . . . . . . . . . . . . . . . . 15 81 Appendix A. Checklist for profile requirements . . . . . . . . . 16 82 Appendix B. The `authorization information' endpoint . . . . . . 16 83 Appendix C. Error handling and token updates . . . . . . . . . . 17 84 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 18 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 87 1. Introduction 89 This document specifies a profile for the ACE framework 90 [I-D.ietf-ace-oauth-authz]. In this profile, clients and a resource 91 server use MQTT to communicate. The protocol relies on TLS for 92 communication security between entities. Protocol interactions 93 follow MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard]. Future 94 releases may enable improvements to the protocol operation (e.g., by 95 allowing MQTT message return codes for authorization errors). 97 MQTT is a publish-subscribe protocol, and supports two types of 98 client operation: publish and subscribe. Once connected, a client 99 can publish to multiple topics, and subscribe to multiple topics; 100 however for the purpose of this document these actions are described 101 separately. The MQTT broker is responsible for distributing messages 102 published by the publishers to the appropriate subscribers. Each 103 publish message contains a topic, which is used by the broker to 104 filter the subscribers for the message. Subscribers must subscribe 105 to the topics to receive the corresponding messages. 107 In this document, message topics are treated as resources. Both 108 publisher and subscriber clients use an access token, each bound to a 109 key (the proof-of-possession key) to authorize with the MQTT broker 110 their connection and publish/subscribe permissions to topics. In the 111 context of this ACE profile, the MQTT broker acts as the resource 112 server. In order to provide communication confidentiality and 113 resource server authentication, TLS is used. 115 The publisher and subscriber clients use client authorization servers 116 [I-D.ietf-ace-actors] to obtain tokens from the authorization server. 117 The communication protocol between the client authorization server 118 and the authorization server is assumed to be HTTPS. Also, if the 119 broker supports token introspection, it is assumed to use HTTPS to 120 communicate with the authorization server. These interfaces MAY be 121 implemented using other protocols e.g., CoAP or MQTT. This document 122 makes the same assumptions as the Section 4 of the ACE framework 123 [I-D.ietf-ace-oauth-authz] in terms of client and RS registration 124 with the AS and establishing of keying material. 126 This document describes authorization of the following exchanges 127 between publisher and subscriber clients, and the broker. 129 o Connection establishment between the clients and the broker 131 o Publish messages from the publishers to the broker, and from the 132 broker to the subscribers 134 o Subscribe messages from the subscribers to the broker 136 1.1. Requirements Language 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 140 document are to be interpreted as described in RFC 2119 [RFC2119]. 142 1.2. ACE-Related Terminology 144 The terminology for entities in the architecture is defined in OAuth 145 2.0 RFC 6749 [RFC6749] and ACE actors [I-D.ietf-ace-actors], such as 146 "Client" (C), "Resource Server" (RS) and "Authorization Server" (AS). 148 The term "endpoint" is used following its OAuth definition, to denote 149 resources such as /token and /introspect at the AS. 151 The term "Resource" is used to refer to an MQTT "topic", which is 152 defined in Section 1.2. Hence, the "Resource Owner" is any entity 153 that can authoritatively speak for the "topic". 155 Certain security-related terms such as "authentication", 156 "authorization", "confidentiality", "(data) integrity", "message 157 authentication code", and "verify" are taken from RFC 4949 [RFC4949]. 159 1.3. MQTT-Related Terminology 161 The document describes message exchanges as MQTT protocol 162 interactions. For additional information, please refer to the MQTT 163 v3.1 - OASIS Standard [MQTT-OASIS-Standard]. 165 Topic name 166 The label attached to an application message, which is 167 matched to a subscription. 169 Topic filter 170 An expression that indicates interest in one or more topic 171 names. Topic filters may include wildcards. 173 Subscription 174 A subscription comprises of a Topic filter and a maximum 175 quality of service (QoS). 177 Application Message 178 The data carried by the MQTT protocol. The data has an 179 associated QoS level and a Topic name. 181 MQTT sends various control messages across a network connection. The 182 following is not an exhaustive list, and the control packets that are 183 not relevant for authorization are not explained. These include, for 184 instance, the PUBREL and PUBCOMP packets used in the 4-step handshake 185 required for the QoS level 2. 187 CONNECT 188 Client request to connect to the broker. After a network 189 connection is established, this is the first packet sent by a 190 client. 192 CONNACK 193 The broker connection acknowledgment. The first packet sent 194 from broker to a client is a CONNACK packet. CONNACK packets 195 contain return codes indicating either a success or an error 196 state to the client. 198 PUBLISH 199 Publish packet that can be sent from a client to the broker, 200 or from the broker to the client. 202 PUBACK 203 Response to PUBLISH packet with QoS level 1. PUBACK can be 204 sent from the broker to the client or the client to the 205 broker. 207 PUBREC 208 Response to PUBLISH packet with QoS level 2. PUBREC can be 209 sent from the broker to the client or the client to the 210 broker. 212 SUBSCRIBE 213 The client subscribe request. 215 SUBACK 216 Subscribe acknowledgment. 218 2. Protocol Interactions 220 This document describes the following exchanges between publisher and 221 subscriber clients, the broker, and the authorization server. 223 o Authorizing connection establishment between the clients and the 224 broker 226 o Authorizing publish messages from the publishers to the broker, 227 and from the broker to the subscribers 229 o Authorizing subscribe messages from the subscribers to the broker 231 Message topics are treated as resources. The publisher and 232 subscriber clients are assumed to have identified the topics of 233 interest out-of-band (topic discovery is not a feature of the MQTT 234 protocol). 236 A connection request carries a token specifying the permissions that 237 the client has (e.g., publish permission to a given topic). A 238 resource owner can pre-configure policies at the AS that give clients 239 publish or subscribe permissions to different topics. 241 2.1. Authorizing Connection Establishment 243 This section specifies how publishers and subscribers establish an 244 authorized connection to an MQTT broker. The token request and 245 response use the /token endpoint of the authorization server, as 246 specified in Section 6 of the the ACE framework 247 [I-D.ietf-ace-oauth-authz]. 249 Figure 1 shows the basic protocol flow during connection 250 establishment. 252 +----------------+ 253 +---(A) Token request----| Client | 254 | | Authorization | 255 | +-(B) Access token-->| Server | 256 | | |________________| 257 | | | 258 | | (C) Client On-boarding 259 | | | 260 | | +---------v-----+ 261 +--v-------------+ | Publisher or | 262 | | | Subscriber | 263 | Authorization | |_______________| 264 | Server | | ^ 265 |________________| | | 266 | ^ (D)Connection (G)Connection 267 | | request + response 268 | | access token | 269 | | | | 270 | | +---v--------------+ 271 | | | Broker | 272 | +(E)Introspection-| Resource Server | 273 | request | | 274 +-(F)Introspection---->|__________________| 275 response 277 Figure 1: Connection establishment 279 2.1.1. Client Authorization Server (CAS) to Authorization Server (AS) 281 The first step in the protocol flow is token acquisition by the 282 client authorization server (CAS) from the AS. If a client has 283 enough resources and can support HTTPS, or optionally the AS supports 284 MQTT, these steps can instead be carried out by a client directly. 286 When requesting an access token from the AS, the CAS MAY include 287 parameters in its request as defined in Section 6.1 of the ACE 288 framework [I-D.ietf-ace-oauth-authz]. The content type is set to 289 "application/json". 291 The response contains a token and a 'cnf' parameter with a symmetric 292 or asymmetric proof-of-possession (PoP) key. 294 The token request is similar to the examples presented in 295 Section 6.1. of the ACE framework [I-D.ietf-ace-oauth-authz] with a 296 modified profile name 'mqtt_tls'. 298 2.1.2. Authorization Server (AS) to Client Authorization Server (CAS) 300 If the access token request has been successfully verified by the AS 301 and the client is authorized to obtain a PoP token for the indicated 302 audience (i.e., broker) and scopes (i.e., publish/subscribe to the 303 requested topics), the AS issues an access token. The response 304 includes the parameters described in Section 6.2 of the ACE framework 305 [I-D.ietf-ace-oauth-authz]. 307 In the case of an error, the AS returns error responses for HTTP- 308 based interactions as ASCII codes in JSON content, as defined in 309 Section 5.2 of RFC 6749 [RFC6749]. 311 2.1.3. Client connection request to the broker 313 Having received the token, the client can use it to request an MQTT 314 connection to the broker over a TLS session with server 315 authentication. This document describes the client transporting the 316 token to the broker (RS) via the CONNECT control message after the 317 TLS handshake. This is similar to an earlier proposal by Freemantle 318 et al. [freemantle14]. Alternatively, the token may be used for the 319 TLS session establishment as described in the DTLS profile for ACE 320 [I-D.gerdes-ace-dtls-authorize]. In this case, both the TLS PSK and 321 RPK handshakes MAY be supported. This may additionally require that 322 the client transports the token to the broker before the connection 323 establishment. To this end, the broker MAY allow clients to publish 324 to "authz-info" topic unauthorized, and in this case, "authz-info" 325 topic SHOULD be publish only (i.e., the clients are not allowed to 326 subscribe to it). Implementation of the public "authz-info" topic is 327 discussed in Appendix B. 329 When the client wishes to connect to the broker, it uses the CONNECT 330 message of MQTT. Figure 2 shows the structure of the MQTT CONNECT 331 control message. 333 0 8 16 24 32 334 +------------------------------------------------------+ 335 |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | 336 +------------------------------------------------------+ 337 | 'M' 'Q' 'T' 'T' | 338 +------------------------------------------------------+ 339 | Proto.level=4|Connect flags| Keep alive | 340 +------------------------------------------------------+ 341 | Payload including User Name (='ACE') | 342 | Password length and data (=token+mac) | 343 | ... | 344 +------------------------------------------------------+ 346 Figure 2: MQTT CONNECT control message. (CPT=Control Packet Type, 347 Rsvd=Reserved, len.=length, Proto.=Protocol) 349 To communicate the necessary connection parameters, the Client uses 350 the appropriate flags of the CONNECT message. Figure 3 shows how the 351 MQTT connect flags MUST be set to initiate a connection with the 352 broker. 354 +-----------------------------------------------------------+ 355 |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| 356 | flag |flag | | | | | | 357 +-----------------------------------------------------------+ 358 | 1 | 1 | X | X X | X | 1 | 0 | 359 +-----------------------------------------------------------+ 361 Figure 3: MQTT CONNECT flags. (Rsvd=Reserved) 363 In order to ensure that the client and the broker discard any 364 previous session and start a new session, the Clean Session Flag MUST 365 be set to 1. 367 The Will flag indicates that a Will message needs to be sent when a 368 client disconnection occurs. The situations in which the Will 369 message is published include disconnections due to I/O or network 370 failures, and the server closing the networking connection due to a 371 protocol error. The client may set the Will flag as desired (marked 372 as 'X' in Figure 3). If the Will flag is set to 1 and the broker 373 accepts the connection request, the broker must store the Will 374 message, and publish it when the network connection is closed. The 375 Will QoS specifies the QoS level of the Will message, and may be set 376 to 0x00, 0x01 or 0x02. The Will retain flag may be set as desired. 378 If it is set to 1, the Will message will be delivered to all future 379 subscribers whose subscriptions match the Will topic. Section 2.6 380 explains how the broker deals with the RETAINed messages in further 381 detail. 383 Finally, Username and Password flags MUST be set to 1, which ensures 384 that the Payload of the CONNECT message includes both Username and 385 Password fields. 387 The Username and Password field are used to indicate to the resource 388 server that the CONNECT message is carrying an ACE token and the MAC 389 of the request. To this end, the Username is set to 'ACE', and the 390 Password field is populated with a JSON object containing the token 391 and the MAC. The Password length field MUST be set to the size of 392 the JSON object. (The maximum size of the password field is defined 393 as 65535 bytes by MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard].) 395 Figure 4 shows an example for setting the password field in an MQTT 396 CONNECT message. 398 { 399 "token": b64'SLAV32hkKG...., 400 "mac": b64'kDZvddkndxvhGRXZhvuDjEWhGeE=, 401 } 403 Figure 4: Example token and MAC as password data in CONNECT message. 405 2.1.4. Token validation 407 RS MUST verify the validity of the token. This validation MAY be 408 done locally or the RS MAY send an introspection request to the AS. 409 If introspection is used, this section follows similar steps to those 410 described in Sections 7.2 and 7.3 of the ACE framework 411 [I-D.ietf-ace-oauth-authz]. The communication between AS and RS MAY 412 be HTTPS, but it, in every case, MUST be confidential, mutually 413 authenticated and integrity protected. 415 The broker MUST check if the token is active either using 416 'expires_in' parameter of the token or 'active' parameter of the 417 introspection response. 419 The access token is constructed by the AS such that RS can associate 420 the access token with the client key. This document assumes that the 421 Access Token is a PoP token as described in 422 [I-D.ietf-ace-oauth-authz]. Therefore, the necessary information is 423 contained in the 'cnf' claim of the access token, and may use either 424 public or shared key approaches. The client uses the 'mac' parameter 425 in the password field to prove the possession of the key. The 426 resource server validates the 'mac' over the contents of the packet, 427 authenticating the client. 429 The broker uses the scope field in the token (or in the introspection 430 result) to determine the publish and subscribe permissions for the 431 client. Scope strings MAY follow an application specific convention 432 e.g., 'publish_topic1' or 'subscribe_topic2'. If the Will flag is 433 set, then the broker MUST check that the token allows the publication 434 of the Will message too. 436 The broker MAY cache the introspection result, because it will need 437 to decide whether to accept subsequent PUBLISH and SUBSCRIBE 438 messages, and these messages, which are sent after a connection is 439 set-up, may not contain tokens. If the introspection result is not 440 cached, then the RS needs to introspect the saved token for each 441 request. 443 2.1.5. The broker's response to client connection request 445 Based on the validation result (obtained either via local inspection 446 or using the /introspection interface of the authorization server), 447 the broker MUST send a CONNACK message to the client. 449 The following responses may be returned to the client. 451 o If the broker accepts the connection, the broker MUST send a 452 CONNACK message with Return Code 0x00 indicating 'Connection 453 Accepted'. 455 o If the connection is denied, the broker MUST send a CONNACK 456 message with 0x05 indicating 'Connection Refused, not authorized'. 458 o If the data in the user name or password is malformed, the broker 459 MUST send a CONNACK message with 0x04 indicating 'Connection 460 Refused, bad user name or password'. 462 It is not possible to support AS discovery via sending a tokenless 463 CONNECT message to the broker. This is because a CONNACK packet does 464 not have a payload. Therefore, AS discovery is assumed to have taken 465 place out-of-band. 467 If the RS accepts the connection, it MUST store the token. 469 2.2. Authorizing PUBLISH messages 471 Figure 5 shows the PUBLISH message used in MQTT, which includes fixed 472 and variable headers. 474 0 8 16 24 32 475 +------------------------------------------------------+ 476 |CPT=3|Flags | Length | Topic length | 477 +------------------------------------------------------+ 478 | Topic name | 479 | ... | 480 +------------------------------------------------------+ 481 | Packet identifier | | 482 +-----------------------------+ | 483 | Payload | 484 +------------------------------------------------------+ 486 Figure 5: MQTT PUBLISH control message. (CPT=Control Packet Type) 488 The variable header includes flags for QoS and RETAIN. If RETAIN is 489 set to 1, then the broker must store the most recent application 490 message per topic, and its QoS, to forward to future subscribers. 491 Other fields in the PUBLISH header are topic name and packet 492 identifier. The topic name MUST NOT include wildcard characters 493 according to MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard]. 495 2.2.1. PUBLISH messages from the publisher client to the broker 497 The payload of PUBLISH messages contains an application message. The 498 content and the format of the data is application specific. 499 Therefore, the client MAY include its token inside the PUBLISH 500 messages. The token could for example be included as: 502 { 503 "message":"topic message", 504 "token": b64'SLAV32hkKG...., 505 } 507 Figure 6: Example token in PUBLISH payload. 509 If the application message contains a token, the broker MAY locally 510 inspect the token or MAY use the /introspect interface of the 511 authorization server. The token received in the PUBLISH message MAY 512 be different than the one stored after connection handshake. On 513 receiving a new token, the RS discards any previously stored token 514 for the client and MUST store the new token as not all PUBLISH 515 messages may carry tokens. 517 If the application message does not contain a token, the broker MUST 518 use the type of message (i.e., PUBLISH) and the topic name in the 519 message header to compare against the 'scope' field of the cached 520 introspection result for the client. 522 If the client is allowed to publish to the topic, the broker may 523 return an acknowledgment message. This is determined by the QoS 524 flags in the Flags field of the PUBLISH header. If QoS level is 0, 525 the RS does not send back a response. If the QoS level is equal or 526 greater than 1, the RS must respond with an acknowledgement message 527 (i.e., PUBACK for QoS=1 or PUBREC for QoS=2). These messages can 528 currently only indicate success, and there is no equivalent 'NACK' to 529 indicate failure. Next, the RS must publish the message to all valid 530 subscribers to the topic. 532 In the case of an authorization error, the broker SHOULD disconnect 533 the client. Otherwise, it MUST silently ignore the message. In the 534 MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], the MQTT DISCONNECT 535 messages are only sent from a client to the broker. So, server 536 disconnection needs to take place below the application layer. 537 Appendix C describes an alternative method for handling authorization 538 errors, possibly avoiding disconnections. 540 2.2.2. PUBLISH messages from the broker to the subscriber clients 542 To forward PUBLISH messages to the subscribing clients, the broker 543 identifies all the subscribers that have matching valid topic 544 subscriptions (i.e., the tokens are valid and token scopes allow a 545 subscription to the particular topic name). The broker sends a 546 PUBLISH message with the topic name and the topic message to all the 547 valid subscribers. 549 In MQTT, after connection establishment there is no way to inform a 550 client that an authorization error has occurred for previously 551 subscribed topics, e.g., token expiry. In the case of an 552 authorization error, the broker has two options: (1) stop forwarding 553 PUBLISH messages to the unauthorized client or (2) disconnect the 554 client. In the MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], the 555 MQTT DISCONNECT messages are only sent from a client to the broker. 556 Therefore, the server disconnection needs to take place below the 557 application layer. Appendix C describes an alternative method, where 558 disconnections may be avoided. 560 2.3. Authorizing SUBSCRIBE messages 562 In MQTT, a SUBSCRIBE message is sent from a client to the broker, to 563 create one or more subscriptions to one or more topics. 565 Figure 7 shows the MQTT SUBSCRIBE message format. The SUBSCRIBE 566 message may contain multiple topic filters. The topic filters may 567 include wildcard characters. 569 0 8 16 24 32 570 +------------------------------------------------------+ 571 |CPT=8|Rsvd. | Length | Packet Identifier | 572 +------------------------------------------------------+ 573 | Topic length | Topic filter | 574 |-----------------------+ | 575 | ... | 576 +------------------------------------------------------+ 577 | Rsvd/QoS | .... | 578 +------------------------------------------------------+ 580 Figure 7: MQTT SUBSCRIBE control message. (CPT=Control Packet Type, 581 Rsvd.=Reserved, QoS=Quality of Service) 583 The SUBSCRIBE message does not have any field suitable for including 584 a token. Therefore, on receiving the SUBSCRIBE message, the broker 585 MUST use the type of message (i.e., SUBSCRIBE) and the topic name in 586 the message header to compare against the 'scope' field of the stored 587 token or introspection result. 589 As a response to the SUBSCRIBE message, the broker issues a SUBACK 590 message. For each topic filter, the SUBACK packet includes a return 591 code. In the case of success, the return code must be either 0x00, 592 0x01 or 0x02, matching the QoS level for the corresponding topic 593 filter. 595 In the case of failure, the return code must be 0x08 indicating 596 'Failure'. There is no other way to signal the reason for an 597 authorization failure to the Subscriber, or to communicate further 598 detail. Appendix C describes an alternative method where more 599 detailed error messages can be provided to the client. 601 2.4. Token expiration 603 The broker checks for token expiration whenever a CONNECT, PUBLISH or 604 SUBSCRIBE message is received or sent. The validation is done either 605 by checking the 'exp' claim of a CWT/JWT or via performing an 606 introspection request with the Authorization server as described in 607 the Section 8.2 of the ACE framework [I-D.ietf-ace-oauth-authz]. 608 Token expirations leads to disconnecting the associated client. 609 Appendix C describes an alternative method, where clients are allowed 610 to update tokens, avoiding disconnections. 612 2.5. Handling disconnections 614 According to MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], only 615 Client DISCONNECT messages are allowed. (This is expected to change 616 in the future, enabling Server DISCONNECT messages.) In the case of 617 a Client DISCONNECT, due to the Clean Session flag, the broker 618 deletes all session state but MUST keep the retained messages and 619 send them according to methodology described in Section 2.6. The 620 broker MUST continue publishing the retained messages as long as the 621 associated tokens are valid. 623 In case of disconnections due to network errors, or Server 624 disconnection due to a protocol error (which includes the 625 authorization errors), the Will message must be sent if the client 626 supplied a Will in the CONNECT request message (see Figure 3). 627 According to the [MQTT-OASIS-Standard], if the CONNECT request is 628 accepted, then any WILL message must be stored. The Will message 629 must be published to the Will topic when the network connection is 630 closed. 632 2.6. Handling retained messages 634 The broker treats retained messages according to the 635 [MQTT-OASIS-Standard]. By setting a RETAIN flag in a PUBLISH message 636 (or in a CONNECT message for the Will message), the publisher 637 indicates to the broker that it should store the most recent message 638 for the associated topic, so the broker can send the message to any 639 future subscribers. Hence, the new subscribers can receive the last 640 sent message from the publisher for that particular topic, without 641 waiting for the next PUBLISH message. 643 According to the [MQTT-OASIS-Standard], if a publisher client 644 disconnects, the retained messages do not form part of the session 645 state and must not be deleted by the broker (since the Clean session 646 flag set to 1 during the connection request, othersession state is 647 deleted). Therefore, the broker MUST continue publishing retained 648 messages for as long as the stored token for the client is valid: 649 This applies to both the PUBLISH and WILL messages. However, if the 650 disconnection is triggered by the broker due to an authorisation 651 error, the broker MUST stop publishing all retained messages from 652 that client. 654 3. IANA Considerations 656 This memo includes no request to IANA. 658 4. Security Considerations 660 TBD. 662 5. Privacy Considerations 664 TBD. 666 6. References 668 6.1. Normative References 670 [I-D.gerdes-ace-dtls-authorize] 671 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 672 L. Seitz, "Datagram Transport Layer Security (DTLS) 673 Profile for Authentication and Authorization for 674 Constrained Environments (ACE)", draft-gerdes-ace-dtls- 675 authorize-00 (work in progress), October 2016. 677 [I-D.ietf-ace-oauth-authz] 678 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 679 H. Tschofenig, "Authentication and Authorization for 680 Constrained Environments (ACE)", draft-ietf-ace-oauth- 681 authz-04 (work in progress), October 2016. 683 [MQTT-OASIS-Standard] 684 Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT 685 Version 3.1.1 Plus Errata 01", 2015, . 688 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 689 Requirement Levels", BCP 14, RFC 2119, 690 DOI 10.17487/RFC2119, March 1997, 691 . 693 6.2. Informative References 695 [freemantle14] 696 Freemantle, P., Aziz, B., Kopecky, J., and P. Scott, 697 "Federated Identity and Access Management for the Internet 698 of Things", research International Workshop on Secure 699 Internet of Things, September 2014, 700 . 702 [I-D.ietf-ace-actors] 703 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 704 architecture for authorization in constrained 705 environments", draft-ietf-ace-actors-04 (work in 706 progress), September 2016. 708 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 709 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 710 . 712 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 713 RFC 6749, DOI 10.17487/RFC6749, October 2012, 714 . 716 Appendix A. Checklist for profile requirements 718 o AS discovery: The clients/client authorization servers need to be 719 configured out-of-band. RS does not provide any hints to help AS 720 discovery. 722 o Communication protocol between the client and RS: MQTT 724 o Security protocol between the client and RS: TLS 726 o Client and RS mutual authentication: RS provides a server 727 certificate during TLS handshake. Client uses token and MAC 728 fields in the MQTT connect message. 730 o Content format: For the HTTPS interactions with AS, "application/ 731 json". The MQTT payloads may be formatted JSON or CBOR. 733 o PoP protocols: Either symmetric or asymmetric keys can be 734 supported. 736 o Unique profile identifier: mqtt_tls 738 o Token introspection: RS uses HTTPS /introspect interface of AS. 740 o Token request: CAS uses HTTPS /token interface of AS. 742 o /authz-info endpoint: It MAY be supported using the method 743 described in Appendix B, not protected. 745 o Token transport: In MQTT CONNECT message or using the method 746 described in Appendix B. 748 Appendix B. The `authorization information' endpoint 750 The main document described a method where the access token is 751 transported inside the MQTT CONNECT message. In this section, we 752 describe an alternative method to transport the access token. 754 The method consists of the MQTT broker providing a public "authz- 755 info" topic. A client using this method MUST first connect to the 756 broker, and publish the access token using the "authz-info" topic. 757 The broker must verify the validity of the token (i.e., through local 758 validation or introspection). After publishing the token, the client 759 disconnects from the broker and is expected to try reconnecting over 760 TLS. 762 After the client published to the "authz-info" topic, it is not 763 possible for the broker to communicate the result of the 764 verification. The response to a PUBLISH message may be a PUBACK or 765 PUBREC, and these messages indicate successful reception of the 766 PUBLISH message and cannot communicate authorization errors. 767 However, the token failure will affect the TLS handshake, which may 768 be used to prompt the client to obtain a valid token. In Appendix C, 769 an alternative method for error handling is discussed. 771 Appendix C. Error handling and token updates 773 Section 2.1.3 uses the CONNECT message to transfer the PoP token to 774 the broker. This is simple, with only two states: 'Disconnected' and 775 'Authorized' (see Figure 8). However, the result of an authorization 776 error is a server side disconnection without any feedback or error 777 message. 779 | State 780 | 0 1 781 Events | Disconnected Authorized 782 ----------------------+--------------------------- 783 CONNECT success | 1 - 784 CONNECT failure | 0 - 785 Authorization expires | - 0 786 other disconnection | 788 Figure 8: Client state machine - simple token transport 790 To enable token updates during the lifetime of a connection, and also 791 to allow the broker to send error messages to a client, this section 792 proposes using a client-specific "authz-info-${ClientId}" topic. 793 This case requires three states: 'Disconnected', 'Connected' and 794 'Authorized', shown in Figure 9. 796 In the Disconnected state, as before, the client needs to transport 797 the token and attempt to establish a connection. Token transport MAY 798 be done using any of the methods mentioned in this document. The 799 CONNECT payload SHOULD include a unique client identifier: Although 800 in MQTT a broker may accept 0-byte client identifiers, in this use 801 case the client would not be aware of its client identifier, so would 802 be unable to update its token, or subscribe to the "authz- 803 info-${ClientId}" topic to receive error messages. 805 If the CONNECT succeeds, then the client moves to the Authorized 806 state. It SHOULD also subscribe to the topic "authz- 807 info-${ClientId}" to be able to receive authorization errors. The 808 subscription MUST fail if the topic name does not contain the 809 ClientId established during the CONNECT handshake. 811 If the token validation fails,the broker MUST publish an 812 authorization error to "authz-info-${ClientId}" and the client moves 813 to the Connected state. In this state, the client MAY publish a new 814 token or it MAY disconnect. If a new token is published, then the 815 broker MUST verify the token and send an authorization response to 816 "authz-info-${ClientId}" indicating success or failure. In case of 817 success, the client moves to the "Authorized" state. In the case of 818 failure, the client remains in "Connected" state but will not be able 819 to publish or receive message from its subscribed topics due to 820 authorisation problems. It MAY be able to publish/subscribe to 821 public topics. 823 | State 824 | 0 1 2 825 Events | Disconnected Connected Authorized 826 --------------------------+------------------------------------- 827 CONNECT success | 2 - - 828 CONNECT failure | 0 - - 829 PUBLISH new token success | - 2 2 830 PUBLISH new token failure | - 1 1 831 Authorization expires | - - 1 832 Other disconnection | - 0 0 834 Figure 9: Client state machine - with error handling and token update 836 While this solution allows better authorization error feedback, it is 837 a more complex solution. The broker needs to maintain separate 838 authz-info topics for separate clients. 840 Acknowledgements 842 The authors would like to thank Ludwig Seitz for his input on the 843 authorisation information endpoint, error handling and token updates 844 presented in the appendices. 846 Authors' Addresses 847 Cigdem Sengul 848 Nominet 849 1 Sekforde Street 850 London EC1R 0BE 851 UK 853 Email: Cigdem.Sengul@nominet.uk 855 Anthony Kirby 856 Nominet 857 Minerva House, Edmund Halley Road 858 Oxford OX4 4DQ 859 UK 861 Email: Anthony.Kirby@nominet.uk