Skip to main content

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

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
Authors Cigdem Sengul , Anthony Kirby , Paul Fremantle
Last updated 2017-10-13
Replaces draft-sengul-kirby-ace-mqtt-tls-profile
Replaced by draft-ietf-ace-mqtt-tls-profile, draft-ietf-ace-mqtt-tls-profile, RFC 9431
RFC stream (None)
Formats
Additional resources
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-sengul-ace-mqtt-tls-profile-01
Sengul, et al.           Expires April 15, 2018                 [Page 2]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   operation with the new MQTT v5 - OASIS Specification Draft
   [MQTT-OASIS-Standard-v5] (e.g., improved authentication exchange and
   error reporting).  Both versions are expected to be supported in
   practice, and therefore, covered in this document.

   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.  Clients
   use an access token, 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.

   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

   In Section 2, these exchanges are described based on the MQTT v3.1 -
   OASIS Standard [MQTT-OASIS-Standard].  These exchanges are also
   supported by the new MQTT v5 - OASIS Specification Draft

Sengul, et al.           Expires April 15, 2018                 [Page 3]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   [MQTT-OASIS-Standard-v5].  Section 3 describes how they may be
   improved by the new MQTT v5.

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].

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] or the MQTT v5 - OASIS
   Specification Draft [MQTT-OASIS-Standard-v5].

   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.

Sengul, et al.           Expires April 15, 2018                 [Page 4]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   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
           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 the broker to a client is a CONNACK packet.  CONNACK
           packets contain return codes indicating either a success or
           an error state to a client.

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

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

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

   SUBSCRIBE
           The client subscribe request.

   SUBACK
           Subscribe acknowledgment.

2.  Basic Protocol Interactions

   This section describes the following exchanges between publisher and
   subscriber clients, the broker, and the authorization server
   according to the MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard].
   These exchanges are compatible also with the new MQTT v5 - OASIS
   Specification Draft [MQTT-OASIS-Standard-v5].  In addition, Section 3
   describes how these exchanges may be improved with the MQTT v5.

   o  Authorizing connection establishment between the clients and the
      broker

Sengul, et al.           Expires April 15, 2018                 [Page 5]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   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).

   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 ACE framework
   [I-D.ietf-ace-oauth-authz].

   Figure 1 shows the basic protocol flow during connection
   establishment.

Sengul, et al.           Expires April 15, 2018                 [Page 6]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

                               +----------------+
      +---(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) and Authorization Server (AS)
        Interaction

   The first step in the protocol flow (Figure 1 (A)) is token
   acquisition by the client authorization server (CAS) from the AS.  If
   a client has enough resources and can support HTTPS, or optionally
   the AS supports MQTTS, 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 profile name is 'mqtt_tls'.

   If the access token request has been successfully verified by the AS
   and the client is authorized to obtain a token for the indicated
   audience (e.g., topics) and scopes (e.g., publish/subscribe
   permissions), the AS issues an access token (Figure 1 (B)).  The
   response includes the parameters described in Section 6.2 of the ACE
   framework [I-D.ietf-ace-oauth-authz].  This includes a token, which
   is assumed to be PoP by default.  Hence, a 'cnf' parameter with a

Sengul, et al.           Expires April 15, 2018                 [Page 7]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   symmetric or asymmetric PoP key is returned.  The token may be a
   reference, or a CBOR or JWT web token.  Note that the 'cnf' parameter
   in the web tokens are to be consumed by the resource server and not
   the client.  For more information on Proof of Possession semantics in
   JWTs see RFC 7800 [RFC7800] and for CWTs, see Proof-of-Possession Key
   Semantics for CBOR Web Tokens (CWTs)
   [I-D.ietf-ace-cwt-proof-of-possession].

   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.2.  Client connection request to the broker

   Client on-boarding (Figure 1 (C)) is out of the scope of this
   document.  Once the client acquires the token, it can use it to
   request an MQTT connection to the broker over a TLS session with
   server authentication (Figure 1 (D)).  This section 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 Fremantle et al. [fremantle14].  An improvement
   to this is presented in Section 3 for the MQTT v5 - OASIS
   Specification Draft [MQTT-OASIS-Standard-v5].  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 support /authz-info endpoint via the "authz-info" topic.  Then,
   to transport the token, clients publish to "authz-info" topic
   unauthorized.  The topic "authz-info" MUST be publish-only for
   clients (i.e., the clients are not allowed to subscribe to it).  This
   option is described in more detail in Appendix B.

   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.

Sengul, et al.           Expires April 15, 2018                 [Page 8]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

          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 (='token')       |
          |     Password length and data (=signature/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
   according to Will QoS and Will retain parameters, and MQTT Will
   management rules.  Section 2.5 explains how the broker deals with the
   retained messages in further detail.

Sengul, et al.           Expires April 15, 2018                 [Page 9]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

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

   The CONNECT message defaults to ACE for authentication and
   authorization.  For the basic operation described in this section,
   the Username field MUST be set to the token.  The Password field MUST
   be set to the keyed message digest (MAC) or signature.  The client
   MAY apply the PoP key either to the token or the entire request by
   computing a keyed message digest (for symmetric key) or a digital
   signature (for asymmetric key).  (The Username field is a UTF-8
   encoded string, which is prefixed with a two-byte length field and
   can have any length in the range of 0 and 65535.  Similarly, the
   password field contains 0 to 65535 bytes of binary data, prefixed by
   a two-byte length field.)

2.1.3.  Token validation

   RS MUST verify the validity of the token.  This validation MAY be
   done locally (e.g., in the case of a self-contained token) 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 signature or
   the MAC in the password field to prove the possession of the key.
   Depending on the chosen implementation, the resource server validates
   the signature or the MAC over the token or 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.  If the Will flag is set, then the broker MUST check that the
   token allows the publication of the Will message too.

Sengul, et al.           Expires April 15, 2018                [Page 10]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   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, do
   not contain tokens.  If the introspection result is not cached, then
   the RS needs to introspect the saved token for each request.

   Note: Scope strings MAY follow an application specific convention.
   One option is to encode the permission and the topics it applies into
   the scope string e.g., 'publish_topic1' or 'subscribe_topic2'.  A
   second option is to simply use the keywords 'publish' or 'subscribe'
   as scope strings and use the 'aud' field to define the topic.
   Another option is to use topic names as scope strings and use the
   'aud' field to define whether the 'publish' or 'subscribe' permission
   applies to these scopes.  The choice is left to the implementer and
   depends on how the following trade-off is expected to be handled:
   token simplicity versus the number of tokens the broker is expected
   to handle per client.

2.1.4.  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 AS), the broker MUST
   send a CONNACK message to the client.

   The broker responses may follow either the MQTT v3.1 - OASIS Standard
   [MQTT-OASIS-Standard] or the MQTT v5 - OASIS Specification Draft
   [MQTT-OASIS-Standard-v5], depending on which version(s) the broker
   supports.

   In MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], 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
   include a means to provide additional information to the client.
   Therefore, AS discovery needs to take place out-of-band.  This is
   remedied in the MQTT v5 - OASIS Specification Draft
   [MQTT-OASIS-Standard-v5] and a solution is described in Section 3.

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

2.2.  Authorizing PUBLISH messages

2.2.1.  PUBLISH messages from the publisher client to the broker

   On receiving the PUBLISH message, the broker MUST use the type of
   message (i.e., PUBLISH) and the topic name in the message header to
   compare against the cached token or its introspection result
   (depending on the implementation, different fields of the token or

Sengul, et al.           Expires April 15, 2018                [Page 11]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   the introspection result may be checked, see the Note in
   Section 2.1.3).

   If the client is allowed to publish to the topic, the RS must publish
   the message to all valid subscribers of the topic.  The broker may
   also return an acknowledgment message if the QoS level is greater
   than or equal to 1.

   In case of a failure, it is not possible to return an error in MQTT
   v3.1 - OASIS Standard [MQTT-OASIS-Standard].  The return of
   acknowledgement messages only indicates success.  In the case of an
   authorization error, the broker SHOULD disconnect the client.
   Otherwise, it MUST ignore the PUBLISH message.  Also, DISCONNECT
   messages are only sent from a client to the broker.  So, server
   disconnection needs to take place below the application layer.
   However, in MQTT v5 - OASIS Specification Draft
   [MQTT-OASIS-Standard-v5], it is possible to indicate failure and
   provide a reason code.  Section 3 describes in more detail how
   PUBLISH authorization errors are handled.

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.  In MQTT v5 - OASIS Specification Draft
   [MQTT-OASIS-Standard-v5], server-side DISCONNECT messages are
   possible, and are described in Section 3.

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.  The
   SUBSCRIBE message may contain multiple topic filters.  The topic
   filters may include wildcard characters.

Sengul, et al.           Expires April 15, 2018                [Page 12]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   On receiving the SUBSCRIBE message, the broker MUST use the type of
   message (i.e., SUBSCRIBE) and the topic filter in the message header
   to compare against the stored token or introspection result
   (depending on the implementation, different fields of the token or
   introspection result may be checked, see the Note in Section 2.1.3).

   As a response to the SUBSCRIBE message, the broker issues a SUBACK
   message.  For each topic filter, the SUBACK packet includes a return
   code matching the QoS level for the corresponding topic filter.  In
   the case of failure, the return code, in MQTT v3.1, must be 0x80
   indicating 'Failure'.  In MQTT v5, the appropriate return code is
   0x87, indicating that the client is 'Not authorized'.  Note that, in
   both MQTT versions, a reason code is returned for each topic filter.
   Therefore, the client may receive success codes for a subset of its
   topic filters, while being unauthorized for the rest.

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
   Section 8.2 of the ACE framework [I-D.ietf-ace-oauth-authz].  In the
   basic operation, token expirations MAY lead to disconnecting the
   associated client.  However, in MQTT v5 - OASIS Specification Draft
   [MQTT-OASIS-Standard-v5], better error handling and re-authentication
   are possible.  This is explained in more detail in Section 3.

2.5.  Handling disconnections and retained messages

   According to MQTT v3.1 - OASIS Standard [MQTT-OASIS-Standard], only
   Client DISCONNECT messages are allowed.  In MQTT v5 - OASIS
   Specification Draft [MQTT-OASIS-Standard-v5], server-side DISCONNECT
   messages are possible, allowing to return '0x87 Not Authorized'
   return code to the client.

   In the case of a DISCONNECT, due to the Clean Session flag, the
   broker deletes all session state but MUST keep the retained messages.
   By setting a RETAIN flag in a PUBLISH message the publisher indicates
   to the broker that it should store the most recent message for the
   associated topic.  Hence, the new subscribers can receive the last
   sent message from the publisher for that particular topic, without
   waiting for the next PUBLISH message.  In the case of a
   disconnection, 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 authorization

Sengul, et al.           Expires April 15, 2018                [Page 13]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   errors), the Will message must be sent if the client supplied a Will
   in the CONNECT request message.  The token provided in the CONNECT
   request must cover the Will topic.  The Will message MUST be
   published to the Will topic when the network connection is closed
   regardless of whether the corresponding token has expired.

3.  Improved Protocol Interactions with MQTT v5

   In the new MQTT v5 - OASIS Specification Draft
   [MQTT-OASIS-Standard-v5], several new capabilities are introduced,
   which enables better integration with the ACE standards.  For
   instance, the new enhanced authentication and re-authentication
   methods support a much wider range of authentication flows beyond
   username and password.  With the MQTT v5, there is a clearly defined
   approach for using token-based approaches.  Similarly, in MQTT v5, it
   is possible for a client to request a re-authentication.  Finally,
   MQTT v5 generally improves error reporting, enabling better response
   to authorization failures during publishing and forwarding of
   messages to the subscribers.

3.1.  Token Transport via Authentication Exchange (AUTH)

   To initiate the authentication and authorization flow, as before, the
   CAS initiates the token request as in Section 2.1.  When the client
   wishes to connect to the RS (broker), it uses the CONNECT message of
   MQTT.  Figure 4 shows the structure of the MQTT CONNECT control
   message used in MQTT v5.

          0            8            16            24            32
          +------------------------------------------------------+
          |CPT=1 | Rsvd.|Remaining len.| Protocol  name len. = 4 |
          +------------------------------------------------------+
          |                      'M' 'Q' 'T' 'T'                 |
          +------------------------------------------------------+
          | Proto.level=5|Connect flags|          Keep alive     |
          +------------------------------------------------------+
          |                 Property length                      |
          |              Auth. Method (0x15) | 'ace_mqtt_tls'    |
          |          Auth. Data (0x16)   | empty or token        |
          |                                                      |
          +------------------------------------------------------+

    Figure 4: 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.  To achieve a clean
   session (i.e., the session should start without an existing session),

Sengul, et al.           Expires April 15, 2018                [Page 14]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   the new MQTT v5 session flags MUST be set appropriately.  More
   specifically, the Clean Start Flag MUST be set to 1 and Session
   Expiry Interval MUST be set to 0.

   With the enhanced authentication capabilities, it is no more
   necessary to overload the username and password fields in the CONNECT
   message for ACE authentication.  Nevertheless, the RS MUST support
   both methods for supporting the token: (1) Token transport via
   username and password and (2) using the new AUTH (Authentication
   Exchange) method.  The token transport via username and password is
   as described in Section 2.1.2.  The rest of this section describes
   the AUTH method.

   To use the AUTH method, the username flag MUST be set to 0 and the
   password flag MUST be set to 0.  The client can set the
   Authentication Method as a property of a CONNECT packet by setting
   Auth Properties (with the property identifier 0x15).  The client must
   MUST set the UTF-8 encoded string containing the name of the
   authentication method as 'ace_mqtt_tls'.  If the RS does not support
   this profile, it sends a CONNACK with a Reason Code of '0x8C (Bad
   authentication method)'

   Authentication Method is followed with Authentication Data, which has
   a property identifier 0x16.  Authentication data is binary data and
   is defined by the authentication method.  The RS MAY support
   different implementations for transporting the authentication data.
   The first option is that Authentication data contains both the token
   and the keyed message digest (MAC) or signature as described in
   Section 2.1.2.  In this case, the token validation proceeds as
   described in Section 2.1.3 and the the server responds with a
   CONNACK.  The reason code of the CONNACK '0x00 (Success)' if the
   authentication is successful.  In case of an invalid PoP token, the
   CONNACK reason code is '0x87 (Not Authorized)'.

   The second option that RS may accept is a challenge/response
   protocol.  If the Authentication Data only includes the token, the RS
   MUST respond with an AUTH packet, with the Authenticate Reason Code
   set to '0x18 (Continue Authentication)'.  This packet includes the
   Authentication Method, which MUST be set to 'ace_mqtt_tls' and
   Authentication Data.  The Authentication Data MUST NOT be empty and
   contains a challenge for the client.  The client responds to this
   with an AUTH packet, with a reason code '0x18 (Continue
   Authentication)'.  Similarly, the client packet sets the
   Authentication Method to 'ace_mqtt_tls'.  The Authentication Data in
   the client's response contains the signature or MAC computed over the
   RS's challenge.  To this, the server responds with a CONNACK and a
   return code of '0x00 (Success)' if the authentication is successful.

Sengul, et al.           Expires April 15, 2018                [Page 15]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   In case of an invalid PoP token, the CONNACK reason code is '0x87
   (Not Authorized)'.

   Finally, this document allows the CONNECT message to have an empty
   Authentication Data field.  This is the AS discovery option and the
   RS responds with a CONNACK reason code '0x87 (Not Authorized)' and
   includes a User Property set to the address of the AS.

3.2.  Authorization Errors and Client Re-authentication

   MQTT v5 allows better error reporting.  To take advantage of this for
   PUBLISH messages, the QoS level should be set to greater than or
   equal to 1.  This guarantees the RS to respond with either a PUBACK
   or PUBREC packet, with a reason code '0x87 (Not authorized)' in the
   case of an authorization error.  Similarly, for the SUBSCRIBE case,
   the SUBACK packet will have a reason code set to '0x87 (Not
   authorized)' for the unauthorized topic(s).  When RS is forwarding
   PUBLISH messages to the subscribed clients, it may discover that some
   of the subscribers are no more authorized due to expired tokens.  In
   this case, the RS SHOULD send a DISCONNECT message with the reason
   code '0x87 (Not authorized)'.  Note that the server-side DISCONNECT
   is a new feature of MQTT v5 (in MQTT v3.1 server needed to drop the
   connection).  RS MUST stop forwarding messages to these unauthorized
   subscribers.

   In the case of a PUBACK with '0x87 (Not authorized)', the client can
   update its token using the Re-authentication feature of MQTT v5.
   Also, the clients can proactively update their tokens, without
   waiting for such a PUBACK.  To re-authenticate, the client sends an
   AUTH packet with a reason code '0x19 (Re-authentication)'.  The
   client MUST send the authentication method as 'ace_mqtt_tls' and
   transports the new token in the Authentication Data.  The client and
   the RS go through the same steps for proof of possession validation
   described in the previous section.  This flow ends with either re-
   authentication is complete or re-authentication fails.  If the re-
   authentication fails, the server MUST send a DISCONNECT with the
   reason code '0x87 (Not Authorized)'.

4.  IANA Considerations

   This memo includes no request to IANA.

5.  Security Considerations

   The security considerations outlined in [I-D.ietf-ace-oauth-authz]
   apply to this work.

Sengul, et al.           Expires April 15, 2018                [Page 16]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

6.  Privacy Considerations

   The privacy considerations outlined in [I-D.ietf-ace-oauth-authz]
   apply to this work.  Furthermore, the RS is a central trusted party
   and may forward potentially sensitive information between clients.

7.  References

7.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-01 (work in progress), March 2017.

   [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-07 (work in progress), August 2017.

   [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>.

   [MQTT-OASIS-Standard-v5]
              Banks, A., Ed., Briggs, E., Ed., Borgendale, K., Ed., and
              R. Gupta, Ed., "OASIS Public Review Draft 01 MQTT Version
              5.0", 2017, <http://docs.oasis-
              open.org/mqtt/mqtt/v5.0/csprd01/mqtt-v5.0-csprd01.html>.

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

7.2.  Informative References

   [fremantle14]
              Fremantle, 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>.

Sengul, et al.           Expires April 15, 2018                [Page 17]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   [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-05 (work in
              progress), March 2017.

   [I-D.ietf-ace-cwt-proof-of-possession]
              Jones, M., Seitz, L., Selander, G., Wahlstroem, E.,
              Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key
              Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt-
              proof-of-possession-00 (work in progress), September 2017.

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

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

   [RFC7800]  Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-
              Possession Key Semantics for JSON Web Tokens (JWTs)",
              RFC 7800, DOI 10.17487/RFC7800, April 2016,
              <https://www.rfc-editor.org/info/rfc7800>.

Appendix A.  Checklist for profile requirements

   o  AS discovery: For the basic protocol using either MQTT v3.1 or
      MQTT v5, the clients/client authorization servers need to be
      configured out-of-band.  RS does not provide any hints to help AS
      discovery.  AS discovery is possible with the MQTT v5 extensions
      described in Section 3.

   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 transports token and MAC
      via 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

Sengul, et al.           Expires April 15, 2018                [Page 18]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

   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 AUTH
      extensions for MQTT v5 described in Section 3.

Appendix B.  The authorization information endpoint

   The main document described a method for transporting tokens inside
   MQTT CONNECT messages.  In this section, we describe an alternative
   method to transport an access token.

   The method consists of the MQTT broker accepting PUBLISH messages to
   a public "authz-info" topic.  A client using this method MUST first
   connect to the 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.

   In MQTT v3.1, after the client published to the "authz-info" topic,
   it is not possible for the broker to communicate the result of the
   token verification.  In MQTT v5, the broker can return 'Not
   authorized' error to a PUBLISH request for QoS greater or equal to 1.
   In any case, any token authorization failure will affect the TLS
   handshake, which can prompt the client to obtain a valid token.

Appendix C.  Document Updates

   This new version updates the expired document (July 29, 2017) as
   follows:

   o  Adds Section 3 to describe improvements to the basic protocol
      operation with the new MQTT v5 - OASIS Specification Draft
      [MQTT-OASIS-Standard-v5], including improved authentication
      exchange and error reporting.

   o  Condenses background information specific to MQTT in Section 2.

   o  Clarifies token transport and token structure in Section 2.1.2 and
      Section 2.1.3.

   o  Removes Appendix on error reporting as this is now handled with
      MQTT v5.

Sengul, et al.           Expires April 15, 2018                [Page 19]
Internet-Draft           MQTT-TLS profile of ACE            October 2017

Acknowledgements

   The authors would like to thank Ludwig Seitz for his input on the
   authorization information endpoint, presented in the appendix.

Authors' Addresses

   Cigdem Sengul
   Nominet
   2 Kingdom Street
   London  W2 6BD
   UK

   Email: Cigdem.Sengul@nominet.uk

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

   Email: Anthony.Kirby@nominet.uk

   Paul Fremantle
   University of Portsmouth
   School of Computing, Buckingham House
   Portsmouth  PO1 3HE
   UK

   Email: paul.fremantle@port.ac.uk

Sengul, et al.           Expires April 15, 2018                [Page 20]