[Docs] [txt|pdf|xml|html] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-sengul-kirby-ace-mqtt-tls-profile) 00 01 02 03 04 draft-ietf-ace-mqtt-tls-profile

ACE Working Group                                              C. Sengul
Internet-Draft                                                  A. Kirby
Intended status: Standards Track                                 Nominet
Expires: July 29, 2017                                  January 25, 2017


                        MQTT-TLS profile of ACE
                  draft-sengul-ace-mqtt-tls-profile-00

Abstract

   This document specifies a profile for the ACE (Authentication and
   Authorization for Constrained Environments) to enable authorization
   in an MQTT-based publish-subscribe messaging system.  Proof-of-
   possession keys, bound to OAuth2.0 access tokens, are used to
   authenticate and authorize publishing and subscribing clients.  The
   protocol relies on TLS for confidentiality and server authentication.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on July 29, 2017.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of




Sengul & Kirby            Expires July 29, 2017                 [Page 1]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   3
     1.2.  ACE-Related Terminology . . . . . . . . . . . . . . . . .   4
     1.3.  MQTT-Related Terminology  . . . . . . . . . . . . . . . .   4
   2.  Protocol Interactions . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Authorizing Connection Establishment  . . . . . . . . . .   6
       2.1.1.  Client Authorization Server (CAS) to Authorization
               Server (AS) . . . . . . . . . . . . . . . . . . . . .   6
       2.1.2.  Authorization Server (AS) to Client Authorization
               Server (CAS)  . . . . . . . . . . . . . . . . . . . .   7
       2.1.3.  Client connection request to the broker . . . . . . .   7
       2.1.4.  Token validation  . . . . . . . . . . . . . . . . . .   9
       2.1.5.  The broker's response to client connection request  .  10
     2.2.  Authorizing PUBLISH messages  . . . . . . . . . . . . . .  10
       2.2.1.  PUBLISH messages from the publisher client to the
               broker  . . . . . . . . . . . . . . . . . . . . . . .  11
       2.2.2.  PUBLISH messages from the broker to the subscriber
               clients . . . . . . . . . . . . . . . . . . . . . . .  12
     2.3.  Authorizing SUBSCRIBE messages  . . . . . . . . . . . . .  12
     2.4.  Token expiration  . . . . . . . . . . . . . . . . . . . .  13
     2.5.  Handling disconnections . . . . . . . . . . . . . . . . .  13
     2.6.  Handling retained messages  . . . . . . . . . . . . . . .  14
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  14
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  14
   5.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  15
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  15
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .  15
     6.2.  Informative References  . . . . . . . . . . . . . . . . .  15
   Appendix A.  Checklist for profile requirements . . . . . . . . .  16
   Appendix B.  The `authorization information' endpoint . . . . . .  16
   Appendix C.  Error handling and token updates . . . . . . . . . .  17
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  18
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  18

1.  Introduction

   This document specifies a profile for the ACE framework
   [I-D.ietf-ace-oauth-authz].  In this profile, clients and a resource
   server use MQTT to communicate.  The protocol relies on TLS for
   communication security between entities.  Protocol interactions
   follow MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard].  Future
   releases may enable improvements to the protocol operation (e.g., by
   allowing MQTT message return codes for authorization errors).



Sengul & Kirby            Expires July 29, 2017                 [Page 2]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   MQTT is a publish-subscribe protocol, and supports two types of
   client operation: publish and subscribe.  Once connected, a client
   can publish to multiple topics, and subscribe to multiple topics;
   however for the purpose of this document these actions are described
   separately.  The MQTT broker is responsible for distributing messages
   published by the publishers to the appropriate subscribers.  Each
   publish message contains a topic, which is used by the broker to
   filter the subscribers for the message.  Subscribers must subscribe
   to the topics to receive the corresponding messages.

   In this document, message topics are treated as resources.  Both
   publisher and subscriber clients use an access token, each bound to a
   key (the proof-of-possession key) to authorize with the MQTT broker
   their connection and publish/subscribe permissions to topics.  In the
   context of this ACE profile, the MQTT broker acts as the resource
   server.  In order to provide communication confidentiality and
   resource server authentication, TLS is used.

   The publisher and subscriber clients use client authorization servers
   [I-D.ietf-ace-actors] to obtain tokens from the authorization server.
   The communication protocol between the client authorization server
   and the authorization server is assumed to be HTTPS.  Also, if the
   broker supports token introspection, it is assumed to use HTTPS to
   communicate with the authorization server.  These interfaces MAY be
   implemented using other protocols e.g., CoAP or MQTT.  This document
   makes the same assumptions as the Section 4 of the ACE framework
   [I-D.ietf-ace-oauth-authz] in terms of client and RS registration
   with the AS and establishing of keying material.

   This document describes authorization of the following exchanges
   between publisher and subscriber clients, and the broker.

   o  Connection establishment between the clients and the broker

   o  Publish messages from the publishers to the broker, and from the
      broker to the subscribers

   o  Subscribe messages from the subscribers to the broker

1.1.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].







Sengul & Kirby            Expires July 29, 2017                 [Page 3]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


1.2.  ACE-Related Terminology

   The terminology for entities in the architecture is defined in OAuth
   2.0 RFC 6749 [RFC6749] and ACE actors [I-D.ietf-ace-actors], such as
   "Client" (C), "Resource Server" (RS) and "Authorization Server" (AS).

   The term "endpoint" is used following its OAuth definition, to denote
   resources such as /token and /introspect at the AS.

   The term "Resource" is used to refer to an MQTT "topic", which is
   defined in Section 1.2.  Hence, the "Resource Owner" is any entity
   that can authoritatively speak for the "topic".

   Certain security-related terms such as "authentication",
   "authorization", "confidentiality", "(data) integrity", "message
   authentication code", and "verify" are taken from RFC 4949 [RFC4949].

1.3.  MQTT-Related Terminology

   The document describes message exchanges as MQTT protocol
   interactions.  For additional information, please refer to the MQTT
   v3.1 - OASIS Standard [MQTT-OASIS-Standard].

   Topic name
           The label attached to an application message, which is
           matched to a subscription.

   Topic filter
           An expression that indicates interest in one or more topic
           names.  Topic filters may include wildcards.

   Subscription
           A subscription comprises of a Topic filter and a maximum
           quality of service (QoS).

   Application Message
           The data carried by the MQTT protocol.  The data has an
           associated QoS level and a Topic name.

   MQTT sends various control messages across a network connection.  The
   following is not an exhaustive list, and the control packets that are
   not relevant for authorization are not explained.  These include, for
   instance, the PUBREL and PUBCOMP packets used in the 4-step handshake
   required for the QoS level 2.

   CONNECT





Sengul & Kirby            Expires July 29, 2017                 [Page 4]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


           Client request to connect to the broker.  After a network
           connection is established, this is the first packet sent by a
           client.

   CONNACK
           The broker connection acknowledgment.  The first packet sent
           from broker to a client is a CONNACK packet.  CONNACK packets
           contain return codes indicating either a success or an error
           state to the client.

   PUBLISH
           Publish packet that can be sent from a client to the broker,
           or from the broker to the client.

   PUBACK
           Response to PUBLISH packet with QoS level 1.  PUBACK can be
           sent from the broker to the client or the client to the
           broker.

   PUBREC
           Response to PUBLISH packet with QoS level 2.  PUBREC can be
           sent from the broker to the client or the client to the
           broker.

   SUBSCRIBE
           The client subscribe request.

   SUBACK
           Subscribe acknowledgment.

2.  Protocol Interactions

   This document describes the following exchanges between publisher and
   subscriber clients, the broker, and the authorization server.

   o  Authorizing connection establishment between the clients and the
      broker

   o  Authorizing publish messages from the publishers to the broker,
      and from the broker to the subscribers

   o  Authorizing subscribe messages from the subscribers to the broker

   Message topics are treated as resources.  The publisher and
   subscriber clients are assumed to have identified the topics of
   interest out-of-band (topic discovery is not a feature of the MQTT
   protocol).




Sengul & Kirby            Expires July 29, 2017                 [Page 5]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   A connection request carries a token specifying the permissions that
   the client has (e.g., publish permission to a given topic).  A
   resource owner can pre-configure policies at the AS that give clients
   publish or subscribe permissions to different topics.

2.1.  Authorizing Connection Establishment

   This section specifies how publishers and subscribers establish an
   authorized connection to an MQTT broker.  The token request and
   response use the /token endpoint of the authorization server, as
   specified in Section 6 of the the ACE framework
   [I-D.ietf-ace-oauth-authz].

   Figure 1 shows the basic protocol flow during connection
   establishment.

                               +----------------+
      +---(A) Token request----| Client         |
      |                        | Authorization  |
      |   +-(B) Access token-->| Server         |
      |   |                    |________________|
      |   |                            |
      |   |                (C) Client On-boarding
      |   |                            |
      |   |                  +---------v-----+
   +--v-------------+        | Publisher or  |
   |                |        | Subscriber    |
   |  Authorization |        |_______________|
   |  Server        |            |       ^
   |________________|            |       |
      |    ^             (D)Connection  (G)Connection
      |    |               request +    response
      |    |               access token  |
      |    |                     |       |
      |    |                 +---v--------------+
      |    |                 |   Broker         |
      |    +(E)Introspection-| Resource Server  |
      |     request          |                  |
      +-(F)Introspection---->|__________________|
           response

                    Figure 1: Connection establishment

2.1.1.  Client Authorization Server (CAS) to Authorization Server (AS)

   The first step in the protocol flow is token acquisition by the
   client authorization server (CAS) from the AS.  If a client has




Sengul & Kirby            Expires July 29, 2017                 [Page 6]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   enough resources and can support HTTPS, or optionally the AS supports
   MQTT, these steps can instead be carried out by a client directly.

   When requesting an access token from the AS, the CAS MAY include
   parameters in its request as defined in Section 6.1 of the ACE
   framework [I-D.ietf-ace-oauth-authz].  The content type is set to
   "application/json".

   The response contains a token and a 'cnf' parameter with a symmetric
   or asymmetric proof-of-possession (PoP) key.

   The token request is similar to the examples presented in
   Section 6.1. of the ACE framework [I-D.ietf-ace-oauth-authz] with a
   modified profile name 'mqtt_tls'.

2.1.2.  Authorization Server (AS) to Client Authorization Server (CAS)

   If the access token request has been successfully verified by the AS
   and the client is authorized to obtain a PoP token for the indicated
   audience (i.e., broker) and scopes (i.e., publish/subscribe to the
   requested topics), the AS issues an access token.  The response
   includes the parameters described in Section 6.2 of the ACE framework
   [I-D.ietf-ace-oauth-authz].

   In the case of an error, the AS returns error responses for HTTP-
   based interactions as ASCII codes in JSON content, as defined in
   Section 5.2 of RFC 6749 [RFC6749].

2.1.3.  Client connection request to the broker

   Having received the token, the client can use it to request an MQTT
   connection to the broker over a TLS session with server
   authentication.  This document describes the client transporting the
   token to the broker (RS) via the CONNECT control message after the
   TLS handshake.  This is similar to an earlier proposal by Freemantle
   et al. [freemantle14].  Alternatively, the token may be used for the
   TLS session establishment as described in the DTLS profile for ACE
   [I-D.gerdes-ace-dtls-authorize].  In this case, both the TLS PSK and
   RPK handshakes MAY be supported.  This may additionally require that
   the client transports the token to the broker before the connection
   establishment.  To this end, the broker MAY allow clients to publish
   to "authz-info" topic unauthorized, and in this case, "authz-info"
   topic SHOULD be publish only (i.e., the clients are not allowed to
   subscribe to it).  Implementation of the public "authz-info" topic is
   discussed in Appendix B.






Sengul & Kirby            Expires July 29, 2017                 [Page 7]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   When the client wishes to connect to the broker, it uses the CONNECT
   message of MQTT.  Figure 2 shows the structure of the MQTT CONNECT
   control message.

          0            8            16            24            32
          +------------------------------------------------------+
          |CPT=1 | Rsvd.|Remaining len.| Protocol  name len. = 4 |
          +------------------------------------------------------+
          |                      'M' 'Q' 'T' 'T'                 |
          +------------------------------------------------------+
          | Proto.level=4|Connect flags|          Keep alive     |
          +------------------------------------------------------+
          |         Payload including User Name (='ACE')         |
          |     Password length and data (=token+mac)   |
          |                           ...                        |
          +------------------------------------------------------+

    Figure 2: MQTT CONNECT control message.  (CPT=Control Packet Type,
               Rsvd=Reserved, len.=length, Proto.=Protocol)

   To communicate the necessary connection parameters, the Client uses
   the appropriate flags of the CONNECT message.  Figure 3 shows how the
   MQTT connect flags MUST be set to initiate a connection with the
   broker.

   +-----------------------------------------------------------+
   |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.|
   | flag    |flag |           |        |         |     |      |
   +-----------------------------------------------------------+
   | 1       | 1   |    X      |   X X  |   X     |  1   |  0  |
   +-----------------------------------------------------------+

              Figure 3: MQTT CONNECT flags.  (Rsvd=Reserved)

   In order to ensure that the client and the broker discard any
   previous session and start a new session, the Clean Session Flag MUST
   be set to 1.

   The Will flag indicates that a Will message needs to be sent when a
   client disconnection occurs.  The situations in which the Will
   message is published include disconnections due to I/O or network
   failures, and the server closing the networking connection due to a
   protocol error.  The client may set the Will flag as desired (marked
   as 'X' in Figure 3).  If the Will flag is set to 1 and the broker
   accepts the connection request, the broker must store the Will
   message, and publish it when the network connection is closed.  The
   Will QoS specifies the QoS level of the Will message, and may be set
   to 0x00, 0x01 or 0x02.  The Will retain flag may be set as desired.



Sengul & Kirby            Expires July 29, 2017                 [Page 8]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   If it is set to 1, the Will message will be delivered to all future
   subscribers whose subscriptions match the Will topic.  Section 2.6
   explains how the broker deals with the RETAINed messages in further
   detail.

   Finally, Username and Password flags MUST be set to 1, which ensures
   that the Payload of the CONNECT message includes both Username and
   Password fields.

   The Username and Password field are used to indicate to the resource
   server that the CONNECT message is carrying an ACE token and the MAC
   of the request.  To this end, the Username is set to 'ACE', and the
   Password field is populated with a JSON object containing the token
   and the MAC.  The Password length field MUST be set to the size of
   the JSON object.  (The maximum size of the password field is defined
   as 65535 bytes by MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard].)

   Figure 4 shows an example for setting the password field in an MQTT
   CONNECT message.

   {
   "token": b64'SLAV32hkKG....,
   "mac": b64'kDZvddkndxvhGRXZhvuDjEWhGeE=,
   }

   Figure 4: Example token and MAC as password data in CONNECT message.

2.1.4.  Token validation

   RS MUST verify the validity of the token.  This validation MAY be
   done locally or the RS MAY send an introspection request to the AS.
   If introspection is used, this section follows similar steps to those
   described in Sections 7.2 and 7.3 of the ACE framework
   [I-D.ietf-ace-oauth-authz].  The communication between AS and RS MAY
   be HTTPS, but it, in every case, MUST be confidential, mutually
   authenticated and integrity protected.

   The broker MUST check if the token is active either using
   'expires_in' parameter of the token or 'active' parameter of the
   introspection response.

   The access token is constructed by the AS such that RS can associate
   the access token with the client key.  This document assumes that the
   Access Token is a PoP token as described in
   [I-D.ietf-ace-oauth-authz].  Therefore, the necessary information is
   contained in the 'cnf' claim of the access token, and may use either
   public or shared key approaches.  The client uses the 'mac' parameter
   in the password field to prove the possession of the key.  The



Sengul & Kirby            Expires July 29, 2017                 [Page 9]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   resource server validates the 'mac' over the contents of the packet,
   authenticating the client.

   The broker uses the scope field in the token (or in the introspection
   result) to determine the publish and subscribe permissions for the
   client.  Scope strings MAY follow an application specific convention
   e.g., 'publish_topic1' or 'subscribe_topic2'.  If the Will flag is
   set, then the broker MUST check that the token allows the publication
   of the Will message too.

   The broker MAY cache the introspection result, because it will need
   to decide whether to accept subsequent PUBLISH and SUBSCRIBE
   messages, and these messages, which are sent after a connection is
   set-up, may not contain tokens.  If the introspection result is not
   cached, then the RS needs to introspect the saved token for each
   request.

2.1.5.  The broker's response to client connection request

   Based on the validation result (obtained either via local inspection
   or using the /introspection interface of the authorization server),
   the broker MUST send a CONNACK message to the client.

   The following responses may be returned to the client.

   o  If the broker accepts the connection, the broker MUST send a
      CONNACK message with Return Code 0x00 indicating 'Connection
      Accepted'.

   o  If the connection is denied, the broker MUST send a CONNACK
      message with 0x05 indicating 'Connection Refused, not authorized'.

   o  If the data in the user name or password is malformed, the broker
      MUST send a CONNACK message with 0x04 indicating 'Connection
      Refused, bad user name or password'.

   It is not possible to support AS discovery via sending a tokenless
   CONNECT message to the broker.  This is because a CONNACK packet does
   not have a payload.  Therefore, AS discovery is assumed to have taken
   place out-of-band.

   If the RS accepts the connection, it MUST store the token.

2.2.  Authorizing PUBLISH messages

   Figure 5 shows the PUBLISH message used in MQTT, which includes fixed
   and variable headers.




Sengul & Kirby            Expires July 29, 2017                [Page 10]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


          0            8            16            24            32
          +------------------------------------------------------+
          |CPT=3|Flags | Length     |             Topic length   |
          +------------------------------------------------------+
          |                        Topic name                    |
          |                              ...                     |
          +------------------------------------------------------+
          |   Packet identifier         |                        |
          +-----------------------------+                        |
          |                                    Payload           |
          +------------------------------------------------------+

    Figure 5: MQTT PUBLISH control message.  (CPT=Control Packet Type)

   The variable header includes flags for QoS and RETAIN.  If RETAIN is
   set to 1, then the broker must store the most recent application
   message per topic, and its QoS, to forward to future subscribers.
   Other fields in the PUBLISH header are topic name and packet
   identifier.  The topic name MUST NOT include wildcard characters
   according to MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard].

2.2.1.  PUBLISH messages from the publisher client to the broker

   The payload of PUBLISH messages contains an application message.  The
   content and the format of the data is application specific.
   Therefore, the client MAY include its token inside the PUBLISH
   messages.  The token could for example be included as:

   {
   "message":"topic message",
   "token": b64'SLAV32hkKG....,
   }

                Figure 6: Example token in PUBLISH payload.

   If the application message contains a token, the broker MAY locally
   inspect the token or MAY use the /introspect interface of the
   authorization server.  The token received in the PUBLISH message MAY
   be different than the one stored after connection handshake.  On
   receiving a new token, the RS discards any previously stored token
   for the client and MUST store the new token as not all PUBLISH
   messages may carry tokens.

   If the application message does not contain a token, the broker MUST
   use the type of message (i.e., PUBLISH) and the topic name in the
   message header to compare against the 'scope' field of the cached
   introspection result for the client.




Sengul & Kirby            Expires July 29, 2017                [Page 11]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   If the client is allowed to publish to the topic, the broker may
   return an acknowledgment message.  This is determined by the QoS
   flags in the Flags field of the PUBLISH header.  If QoS level is 0,
   the RS does not send back a response.  If the QoS level is equal or
   greater than 1, the RS must respond with an acknowledgement message
   (i.e., PUBACK for QoS=1 or PUBREC for QoS=2).  These messages can
   currently only indicate success, and there is no equivalent 'NACK' to
   indicate failure.  Next, the RS must publish the message to all valid
   subscribers to the topic.

   In the case of an authorization error, the broker SHOULD disconnect
   the client.  Otherwise, it MUST silently ignore the message.  In the
   MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], the MQTT DISCONNECT
   messages are only sent from a client to the broker.  So, server
   disconnection needs to take place below the application layer.
   Appendix C describes an alternative method for handling authorization
   errors, possibly avoiding disconnections.

2.2.2.  PUBLISH messages from the broker to the subscriber clients

   To forward PUBLISH messages to the subscribing clients, the broker
   identifies all the subscribers that have matching valid topic
   subscriptions (i.e., the tokens are valid and token scopes allow a
   subscription to the particular topic name).  The broker sends a
   PUBLISH message with the topic name and the topic message to all the
   valid subscribers.

   In MQTT, after connection establishment there is no way to inform a
   client that an authorization error has occurred for previously
   subscribed topics, e.g., token expiry.  In the case of an
   authorization error, the broker has two options: (1) stop forwarding
   PUBLISH messages to the unauthorized client or (2) disconnect the
   client.  In the MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], the
   MQTT DISCONNECT messages are only sent from a client to the broker.
   Therefore, the server disconnection needs to take place below the
   application layer.  Appendix C describes an alternative method, where
   disconnections may be avoided.

2.3.  Authorizing SUBSCRIBE messages

   In MQTT, a SUBSCRIBE message is sent from a client to the broker, to
   create one or more subscriptions to one or more topics.

   Figure 7 shows the MQTT SUBSCRIBE message format.  The SUBSCRIBE
   message may contain multiple topic filters.  The topic filters may
   include wildcard characters.





Sengul & Kirby            Expires July 29, 2017                [Page 12]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


          0            8            16            24            32
          +------------------------------------------------------+
          |CPT=8|Rsvd. | Length     |          Packet Identifier |
          +------------------------------------------------------+
          |      Topic length     |        Topic filter          |
          |-----------------------+                              |
          |        ...                                           |
          +------------------------------------------------------+
          |  Rsvd/QoS  |           ....                          |
          +------------------------------------------------------+

   Figure 7: MQTT SUBSCRIBE control message.  (CPT=Control Packet Type,
                  Rsvd.=Reserved, QoS=Quality of Service)

   The SUBSCRIBE message does not have any field suitable for including
   a token.  Therefore, on receiving the SUBSCRIBE message, the broker
   MUST use the type of message (i.e., SUBSCRIBE) and the topic name in
   the message header to compare against the 'scope' field of the stored
   token or introspection result.

   As a response to the SUBSCRIBE message, the broker issues a SUBACK
   message.  For each topic filter, the SUBACK packet includes a return
   code.  In the case of success, the return code must be either 0x00,
   0x01 or 0x02, matching the QoS level for the corresponding topic
   filter.

   In the case of failure, the return code must be 0x08 indicating
   'Failure'.  There is no other way to signal the reason for an
   authorization failure to the Subscriber, or to communicate further
   detail.  Appendix C describes an alternative method where more
   detailed error messages can be provided to the client.

2.4.  Token expiration

   The broker checks for token expiration whenever a CONNECT, PUBLISH or
   SUBSCRIBE message is received or sent.  The validation is done either
   by checking the 'exp' claim of a CWT/JWT or via performing an
   introspection request with the Authorization server as described in
   the Section 8.2 of the ACE framework [I-D.ietf-ace-oauth-authz].
   Token expirations leads to disconnecting the associated client.
   Appendix C describes an alternative method, where clients are allowed
   to update tokens, avoiding disconnections.

2.5.  Handling disconnections

   According to MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], only
   Client DISCONNECT messages are allowed.  (This is expected to change
   in the future, enabling Server DISCONNECT messages.)  In the case of



Sengul & Kirby            Expires July 29, 2017                [Page 13]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   a Client DISCONNECT, due to the Clean Session flag, the broker
   deletes all session state but MUST keep the retained messages and
   send them according to methodology described in Section 2.6.  The
   broker MUST continue publishing the retained messages as long as the
   associated tokens are valid.

   In case of disconnections due to network errors, or Server
   disconnection due to a protocol error (which includes the
   authorization errors), the Will message must be sent if the client
   supplied a Will in the CONNECT request message (see Figure 3).
   According to the [MQTT-OASIS-Standard], if the CONNECT request is
   accepted, then any WILL message must be stored.  The Will message
   must be published to the Will topic when the network connection is
   closed.

2.6.  Handling retained messages

   The broker treats retained messages according to the
   [MQTT-OASIS-Standard].  By setting a RETAIN flag in a PUBLISH message
   (or in a CONNECT message for the Will message), the publisher
   indicates to the broker that it should store the most recent message
   for the associated topic, so the broker can send the message to any
   future subscribers.  Hence, the new subscribers can receive the last
   sent message from the publisher for that particular topic, without
   waiting for the next PUBLISH message.

   According to the [MQTT-OASIS-Standard], if a publisher client
   disconnects, the retained messages do not form part of the session
   state and must not be deleted by the broker (since the Clean session
   flag set to 1 during the connection request, othersession state is
   deleted).  Therefore, the broker MUST continue publishing retained
   messages for as long as the stored token for the client is valid:
   This applies to both the PUBLISH and WILL messages.  However, if the
   disconnection is triggered by the broker due to an authorisation
   error, the broker MUST stop publishing all retained messages from
   that client.

3.  IANA Considerations

   This memo includes no request to IANA.

4.  Security Considerations

   TBD.







Sengul & Kirby            Expires July 29, 2017                [Page 14]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


5.  Privacy Considerations

   TBD.

6.  References

6.1.  Normative References

   [I-D.gerdes-ace-dtls-authorize]
              Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and
              L. Seitz, "Datagram Transport Layer Security (DTLS)
              Profile for Authentication and Authorization for
              Constrained Environments (ACE)", draft-gerdes-ace-dtls-
              authorize-00 (work in progress), October 2016.

   [I-D.ietf-ace-oauth-authz]
              Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
              H. Tschofenig, "Authentication and Authorization for
              Constrained Environments (ACE)", draft-ietf-ace-oauth-
              authz-04 (work in progress), October 2016.

   [MQTT-OASIS-Standard]
              Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT
              Version 3.1.1 Plus Errata 01", 2015, <http://docs.oasis-
              open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

6.2.  Informative References

   [freemantle14]
              Freemantle, P., Aziz, B., Kopecky, J., and P. Scott,
              "Federated Identity and Access Management for the Internet
              of Things", research International Workshop on Secure
              Internet of Things, September 2014,
              <http://dx.doi.org/10.1109/SIoT.2014.8>.

   [I-D.ietf-ace-actors]
              Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An
              architecture for authorization in constrained
              environments", draft-ietf-ace-actors-04 (work in
              progress), September 2016.






Sengul & Kirby            Expires July 29, 2017                [Page 15]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   [RFC4949]  Shirey, R., "Internet Security Glossary, Version 2",
              FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,
              <http://www.rfc-editor.org/info/rfc4949>.

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <http://www.rfc-editor.org/info/rfc6749>.

Appendix A.  Checklist for profile requirements

   o  AS discovery: The clients/client authorization servers need to be
      configured out-of-band.  RS does not provide any hints to help AS
      discovery.

   o  Communication protocol between the client and RS: MQTT

   o  Security protocol between the client and RS: TLS

   o  Client and RS mutual authentication: RS provides a server
      certificate during TLS handshake.  Client uses token and MAC
      fields in the MQTT connect message.

   o  Content format: For the HTTPS interactions with AS, "application/
      json".  The MQTT payloads may be formatted JSON or CBOR.

   o  PoP protocols: Either symmetric or asymmetric keys can be
      supported.

   o  Unique profile identifier: mqtt_tls

   o  Token introspection: RS uses HTTPS /introspect interface of AS.

   o  Token request: CAS uses HTTPS /token interface of AS.

   o  /authz-info endpoint: It MAY be supported using the method
      described in Appendix B, not protected.

   o  Token transport: In MQTT CONNECT message or using the method
      described in Appendix B.

Appendix B.  The `authorization information' endpoint

   The main document described a method where the access token is
   transported inside the MQTT CONNECT message.  In this section, we
   describe an alternative method to transport the access token.

   The method consists of the MQTT broker providing a public "authz-
   info" topic.  A client using this method MUST first connect to the



Sengul & Kirby            Expires July 29, 2017                [Page 16]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   broker, and publish the access token using the "authz-info" topic.
   The broker must verify the validity of the token (i.e., through local
   validation or introspection).  After publishing the token, the client
   disconnects from the broker and is expected to try reconnecting over
   TLS.

   After the client published to the "authz-info" topic, it is not
   possible for the broker to communicate the result of the
   verification.  The response to a PUBLISH message may be a PUBACK or
   PUBREC, and these messages indicate successful reception of the
   PUBLISH message and cannot communicate authorization errors.
   However, the token failure will affect the TLS handshake, which may
   be used to prompt the client to obtain a valid token.  In Appendix C,
   an alternative method for error handling is discussed.

Appendix C.  Error handling and token updates

   Section 2.1.3 uses the CONNECT message to transfer the PoP token to
   the broker.  This is simple, with only two states: 'Disconnected' and
   'Authorized' (see Figure 8).  However, the result of an authorization
   error is a server side disconnection without any feedback or error
   message.

                                | State
                                |      0             1
          Events                | Disconnected   Authorized
          ----------------------+---------------------------
          CONNECT success       |      1             -
          CONNECT failure       |      0             -
          Authorization expires |      -             0
          other disconnection   |

          Figure 8: Client state machine - simple token transport

   To enable token updates during the lifetime of a connection, and also
   to allow the broker to send error messages to a client, this section
   proposes using a client-specific "authz-info-${ClientId}" topic.
   This case requires three states: 'Disconnected', 'Connected' and
   'Authorized', shown in Figure 9.

   In the Disconnected state, as before, the client needs to transport
   the token and attempt to establish a connection.  Token transport MAY
   be done using any of the methods mentioned in this document.  The
   CONNECT payload SHOULD include a unique client identifier: Although
   in MQTT a broker may accept 0-byte client identifiers, in this use
   case the client would not be aware of its client identifier, so would
   be unable to update its token, or subscribe to the "authz-
   info-${ClientId}" topic to receive error messages.



Sengul & Kirby            Expires July 29, 2017                [Page 17]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   If the CONNECT succeeds, then the client moves to the Authorized
   state.  It SHOULD also subscribe to the topic "authz-
   info-${ClientId}" to be able to receive authorization errors.  The
   subscription MUST fail if the topic name does not contain the
   ClientId established during the CONNECT handshake.

   If the token validation fails,the broker MUST publish an
   authorization error to "authz-info-${ClientId}" and the client moves
   to the Connected state.  In this state, the client MAY publish a new
   token or it MAY disconnect.  If a new token is published, then the
   broker MUST verify the token and send an authorization response to
   "authz-info-${ClientId}" indicating success or failure.  In case of
   success, the client moves to the "Authorized" state.  In the case of
   failure, the client remains in "Connected" state but will not be able
   to publish or receive message from its subscribed topics due to
   authorisation problems.  It MAY be able to publish/subscribe to
   public topics.

                                  | State
                                  |      0            1          2
        Events                    | Disconnected  Connected  Authorized
        --------------------------+-------------------------------------
        CONNECT success           |      2            -          -
        CONNECT failure           |      0            -          -
        PUBLISH new token success |      -            2          2
        PUBLISH new token failure |      -            1          1
        Authorization expires     |      -            -          1
        Other disconnection       |      -            0          0

   Figure 9: Client state machine - with error handling and token update

   While this solution allows better authorization error feedback, it is
   a more complex solution.  The broker needs to maintain separate
   authz-info topics for separate clients.

Acknowledgements

   The authors would like to thank Ludwig Seitz for his input on the
   authorisation information endpoint, error handling and token updates
   presented in the appendices.

Authors' Addresses









Sengul & Kirby            Expires July 29, 2017                [Page 18]


Internet-Draft           MQTT-TLS profile of ACE            January 2017


   Cigdem Sengul
   Nominet
   1 Sekforde Street
   London  EC1R 0BE
   UK

   Email: Cigdem.Sengul@nominet.uk


   Anthony Kirby
   Nominet
   Minerva House, Edmund Halley Road
   Oxford  OX4 4DQ
   UK

   Email: Anthony.Kirby@nominet.uk



































Sengul & Kirby            Expires July 29, 2017                [Page 19]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/