-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-sengul-ace-mqtt-tls-profile-04.xml
1120 lines (1025 loc) · 63.9 KB
/
draft-sengul-ace-mqtt-tls-profile-04.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
There has to be one entity for each item to be referenced.
An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC8174 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC4949 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4949.xml">
<!ENTITY RFC6749 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml">
<!ENTITY RFC7800 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7800.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
(Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
(using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" docName="draft-sengul-ace-mqtt-tls-profile-04" ipr="trust200902">
<!-- category values: std, bcp, info, exp, and historic
ipr values: trust200902, noModificationTrust200902, noDerivativesTrust200902,
or pre5378Trust200902
you can add the attributes updates="NNNN" and obsoletes="NNNN"
they will automatically be output with "(if approved)" -->
<!-- ***** FRONT MATTER ***** -->
<front>
<!-- The abbreviated title is used in the page header - it is only necessary if the
full title is longer than 39 characters -->
<title abbrev="MQTT-TLS profile of ACE">MQTT-TLS profile of ACE
</title>
<!-- add 'role="editor"' below for the editors if appropriate -->
<!-- Author 1-->
<author fullname="Cigdem Sengul" initials="C.S."
surname="Sengul">
<organization>Nominet</organization>
<address>
<postal>
<street>2 Kingdom Street</street>
<!-- Reorder these if your country does things differently -->
<city>London</city>
<code>W2 6BD</code>
<country>UK</country>
</postal>
<email>Cigdem.Sengul@nominet.uk</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<!-- Author 2-->
<author fullname="Anthony Kirby" initials="A.K"
surname="Kirby">
<organization>Oxbotica</organization>
<address>
<postal>
<street>1a Milford House, Mayfield Road, Summertown</street>
<!-- Reorder these if your country does things differently -->
<city>Oxford</city>
<code>OX2 7EL</code>
<country>UK</country>
</postal>
<email>anthony@anthony.org</email>
</address>
</author>
<!-- Author 3 -->
<author fullname="Paul Fremantle" initials="P.F"
surname="Fremantle">
<organization>University of Portsmouth</organization>
<address>
<postal>
<street>School of Computing, Buckingham House</street>
<city>Portsmouth</city>
<code>PO1 3HE</code>
<country>UK</country>
</postal>
<email>paul.fremantle@port.ac.uk</email>
</address>
</author>
<date year="2019"/>
<!-- If the month and year are both specified and are the current ones, xml2rfc will fill
in the current day for you. If only the current year is specified, xml2rfc will fill
in the current day and month for you. If the year is not the current one, it is
necessary to specify at least a month (xml2rfc assumes day="1" if not specified for the
purpose of calculating the expiry date). With drafts it is normally sufficient to
specify just the year. -->
<!-- Meta-data Declarations -->
<area>Security</area>
<workgroup>ACE Working Group</workgroup>
<!-- WG name at the upperleft corner of the doc,
IETF is fine for individual submissions.
If this element is not present, the default is "Network Working Group",
which is used by the RFC Editor as a nod to the history of the IETF. -->
<keyword>Internet-Draft</keyword>
<!-- Keywords will be incorporated into HTML output
files in a meta tag but they have no effect on text or nroff
output. If you submit your draft to the RFC Editor, the
keywords will be used for the search engine. -->
<abstract>
<t>
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
publisher and subscriber clients.
The protocol relies on TLS for confidentiality and server authentication.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
This document specifies a profile for the ACE framework <xref target="I-D.ietf-ace-oauth-authz"></xref>.
In this profile, clients and a resource server use MQTT to communicate. The protocol relies on TLS for
communication security between entities.
The basic protocol interactions follow <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>.
In addition, this document describes improvements to the basic protocol with the new
<xref target="MQTT-OASIS-Standard-v5">MQTT v5.0 - the OASIS Standard</xref> (e.g., improved authentication
exchange and error reporting). Both versions are expected to be supported in practice, and therefore, covered
in this document.
</t>
<t>
MQTT is a publish-subscribe protocol and supports two main types of client operation: publish and subscribe.
Once connected,
a client can publish to multiple topics, and subscribe to multiple topics; however, for 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.
</t>
<t>
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.
To provide communication confidentiality and resource server authentication, TLS is used.
</t>
<t>
Clients use client authorization servers <xref
target="I-D.ietf-ace-actors"></xref> 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
<xref target="I-D.ietf-ace-oauth-authz"> the
ACE framework</xref> regarding client and RS registration with the AS and establishing of keying material.
</t>
<t>This document describes the authorization of the following exchanges between publisher and subscriber
clients, and the broker.
</t>
<t>
<list style="symbols">
<t>Connection establishment between the clients and the broker</t>
<t>Publish messages from the publishers to the broker, and from the broker to the subscribers</t>
<t>Subscribe messages from the subscribers to the broker</t>
</list>
</t>
<t>
In <xref target="basic-protocol"></xref>, these exchanges are described based on the
<xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>. These exchanges are also supported by the
new <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>.
<xref target="MQTTv5"></xref> describes how they
may be improved by the new MQTT v5.
</t>
<section title="Requirements Language">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 <xref target="RFC2119"></xref> <xref target="RFC8174"></xref>, when, and only when, they appear in all capitals, as shown here.
</t>
</section>
<section title="ACE-Related Terminology">
<t>
The terminology for entities in the architecture is defined in OAuth 2.0 <xref target="RFC6749">RFC
6749
</xref> and <xref target="I-D.ietf-ace-actors">ACE actors</xref>, such as "Client" (C), "Resource
Server" (RS) and "Authorization Server" (AS).
</t>
<t>
The term "endpoint" is used following its OAuth definition, to denote resources such as /token and
/introspect at the AS.
</t>
<t>
The term "Resource" is used to refer to an MQTT "topic name," which is defined in <xref target="mqtt-defs"></xref>.
Hence, the "Resource Owner" is any entity that can authoritatively speak for the "topic".
</t>
<t>
Certain security-related terms such as "authentication", "authorization", "confidentiality", "(data)
integrity",
"message authentication code", and "verify" are taken from <xref target="RFC4949">RFC 4949</xref>.
</t>
</section>
<section title="MQTT-Related Terminology" anchor="mqtt-defs">
<t>
The document describes message exchanges as MQTT protocol interactions. For additional information,
please refer to the <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref> or the
<xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>.
</t>
<t>
<list hangIndent="8" style="hanging">
<t hangText="Topic name">
<vspace blankLines="0"/>
The label attached to an application message, which is matched to a subscription.
</t>
<t hangText="Topic filter">
<vspace blankLines="0"/>
An expression that indicates interest in one or more topic names. Topic filters may include
wildcards.
</t>
<t hangText="Subscription">
<vspace blankLines="0"/>
A subscription comprises a Topic filter and a maximum quality of service (QoS).
</t>
<t hangText="Application Message">
<vspace blankLines="0"/>
The data carried by the MQTT protocol. The data has an associated QoS level and a Topic
name.
</t>
</list>
</t>
<t>
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.
<list hangIndent="8" style="hanging">
<t hangText="CONNECT">
<vspace blankLines="0"/>
Client request to connect to the broker. After a network connection is established, this is
the first packet sent by a client.
</t>
<t hangText="CONNACK">
<vspace blankLines="0"/>
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.
</t>
<t hangText="PUBLISH">
<vspace blankLines="0"/>
Publish packet that can be sent from a client to the broker, or from the broker to a
client.
</t>
<t hangText="PUBACK">
<vspace blankLines="0"/>
Response to PUBLISH packet with QoS level 1. PUBACK can be sent from the broker to a
client or a client to the broker.
</t>
<t hangText="PUBREC">
<vspace blankLines="0"/>
Response to PUBLISH packet with QoS level 2. PUBREC can be sent from the broker to a
client or a client to the broker.
</t>
<t hangText="SUBSCRIBE">
<vspace blankLines="0"/>
The client subscribe request.
</t>
<t hangText="SUBACK">
<vspace blankLines="0"/>
Subscribe acknowledgment.
</t>
<t hangText="PINGREQ">
A ping request sent from a client to the broker. It signals to the broker that the client is alive, and
is used to confirm that the broker is still alive.
</t>
</list>
</t>
</section>
</section>
<section title="Basic Protocol Interactions" anchor="basic-protocol">
<t> This section describes the following exchanges between publisher and subscriber clients, the broker, and
the authorization server according to the <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>.
These exchanges are compatible also with the new <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard
</xref>. In addition, <xref target="MQTTv5"></xref> describes how these exchanges may be improved with the
MQTT v5.
</t>
<t>
<list style="symbols">
<t>Authorizing connection establishment between the clients and the broker</t>
<t>Authorizing publish messages from the publishers to the broker, and from the broker to the
subscribers
</t>
<t>Authorizing subscribe messages from the subscribers to the broker</t>
</list>
</t>
<t>
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).
</t>
<t>
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.
</t>
<section title="Authorizing Connection Establishment" anchor="token_acquisition">
<t>
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 5 of the <xref
target="I-D.ietf-ace-oauth-authz">ACE framework</xref>.
</t>
<t>
<xref target="basic_protocol_flow"></xref> shows the basic protocol flow during connection
establishment. The step (C), client onboarding, is out of the scope of this document.
Steps (E) and (F) are optional.
</t>
<figure align="center" anchor="basic_protocol_flow" title="Connection establishment">
<artwork align="left"><![CDATA[
+----------------+
+---(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 (optional) | |
+-(F)Introspection---->|__________________|
response (optional)
]]></artwork>
</figure>
<section title="Client Authorization Server (CAS) and Authorization Server (AS) Interaction">
<t>
The first step in the protocol flow (Figure 1 (A)) is the 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.
</t>
<t>
When requesting an access token from the AS, the CAS MAY include parameters in its request as
defined in Section 5.6.1
of <xref target="I-D.ietf-ace-oauth-authz">the ACE framework</xref>.
The content type is set to
"application/json". The profile parameter is set to 'mqtt_tls'.
</t>
<t>
If the AS successfully verifies the access token request and authorizes the client for the
indicated audience (e.g., RS) and scopes (e.g., publish/subscribe permissions over topics),
the AS issues an access token (Figure 1 (B)).
The response includes the parameters described in Section 5.6.2 of <xref
target="I-D.ietf-ace-oauth-authz">the ACE framework</xref>.
The included token is assumed to be Proof-of-Possession (PoP) token by default. Hence, a 'cnf' parameter with a
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 <xref target="RFC7800">RFC 7800</xref> and for CWTs,
see <xref target="I-D.ietf-ace-cwt-proof-of-possession">Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)</xref>.
</t>
<t>
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 <xref target="RFC6749">RFC 6749</xref>.
</t>
</section>
<section title="Client Connection Request to the Broker" anchor="connect_v31">
<t>
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. <xref target="fremantle14"></xref>. An improvement to this is presented in <xref target="MQTTv5"></xref>
for the <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>.
Alternatively, the token may be used for the TLS session establishment as described in
the <xref target="I-D.gerdes-ace-dtls-authorize">DTLS profile for ACE</xref>. 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
<xref target="app-authzinfo"></xref>.
</t>
<t>
When the client wishes to connect to the broker, it uses the CONNECT message of MQTT.
<xref target="mqtt_connect_message"></xref>
shows the structure of the MQTT CONNECT control message.
</t>
<figure align="center" anchor="mqtt_connect_message"
title="MQTT CONNECT control message. (CPT=Control Packet Type, Rsvd=Reserved, len.=length, Proto.=Protocol)">
<artwork align="left"><![CDATA[
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 |
| Username as access token (UTF-8) |
| Password length (2 Bytes) |
| Password data as signature/MAC (binary) |
| ... |
+------------------------------------------------------+
]]></artwork>
</figure>
<t>
To communicate the necessary connection parameters, the Client uses the appropriate flags of the
CONNECT message.
<xref target="mqtt_connect_flags"></xref>
shows how the MQTT connect flags MUST be set to initiate a connection with the broker.
</t>
<figure align="center" anchor="mqtt_connect_flags" title="MQTT CONNECT flags. (Rsvd=Reserved)">
<artwork align="left"><![CDATA[
+-----------------------------------------------------------+
|User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.|
| flag |flag | | | | | |
+-----------------------------------------------------------+
| 1 | 1 | X | X X | X | 1 | 0 |
+-----------------------------------------------------------+
]]></artwork>
</figure>
<t>
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.
</t>
<t>
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 <xref
target="mqtt_connect_flags"></xref>).
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.
<xref target="disconnections"></xref>
explains how the broker deals with the retained messages in further detail.
</t>
<t>
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.
</t>
<t>
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 access token.
The Password field MUST be set to the keyed message digest (MAC) or signature associated with the access token
for proof-of-possession.
The client MAY apply the PoP key either to the entire request by computing a keyed message digest
(for symmetric key) or a digital signature (for asymmetric key).
The CONNECT message is assumed to have enough randomness in the payload, and
inside a TLS session (excluding the 0-RTT case) will not be exposed to a replay attack.
When either cannot be guaranteed, the Password MAY also contain a nonce.
<!--In addition, <xref target="MQTTv5"></xref>
describes request-response protocol, which is possible under MQTT v5 and enables
the RS to send a challenge to the client. -->
</t>
<t>
Section 3.1.3 of <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref> defines the MQTT Username
as a UTF-8 encoded string, which is prefixed by a 2-byte length field followed by UTF-8 encoded character data
up to 65535 bytes. Therefore an access token that is not a valid UTF-8 MUST be Base64 <xref target="RFC4648"></xref> encoded.
<!--If the access token is in a UTF-8 text format, for example, a JWT, it SHOULD be supplied as-is,
in which case it can be up to 65535 bytes.
If the access token is binary, for example, a CWT, it MUST be encoded using Base64 <xref target="RFC4648"></xref>;
this limits the (binary) token to 49149 bytes.
A JWT is distinguishable from Base64 encoded data, so the MQTT server can infer whether the data is encoded or not, and there
is no need for a flag to distinguish encoded from unencoded data.-->
(The MQTT Password allows binary data up to 65535 bytes, and so, does not require encoding.)
</t>
</section>
<section title="Token Validation" anchor="token_validation">
<t>
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 5.7
of <xref target="I-D.ietf-ace-oauth-authz">the ACE framework</xref>.
The communication between AS and RS MAY be HTTPS, but it, in every case, MUST be confidential,
mutually authenticated and integrity protected.
</t>
<t>
The broker MUST check if the token is
active either using 'exp' claim of the token or 'active'
parameter of the introspection response.
</t>
<t>
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 <xref target="I-D.ietf-ace-oauth-authz"></xref>.
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.
The resource server validates the signature or the MAC
over the contents of the packet, authenticating the client.
</t>
<t>
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.
</t>
<t>
If the token is not self-contained and the broker uses token introspection,
it MAY cache the validation result to decide whether to accept
subsequent PUBLISH and SUBSCRIBE messages as
these messages, which are sent after a connection set-up, do not contain access tokens.
If the introspection result is not cached, then the RS needs to introspect the saved token for
each request.
</t>
<t>
Scope strings SHOULD be encoded as a permission, followed by an underscore, followed by a topic filter.
Two permissions apply to topics: 'publish' and 'subscribe'.
An example scope field may contain multiple such strings, space delimited, e.g., 'publish_topic1 subscribe_topic2/#'.
Hence, this access token would give 'publish' permission to the 'topic1',
'subscribe' permission to all the subtopics of 'topic2'.
<!--If there is a single RS, then scope strings MAY be simply the keywords 'publish' or 'subscribe,' and the 'aud'
field in the access token MAY be used to define the topic filter.-->
</t>
<t>
Also, if present in the access token, RS must check that the 'iss' corresponds to AS,
the 'aud' field (if not used to define topics) corresponds to RS. It also has to check whether 'nbf' and 'iat' claims are present and valid.
</t>
</section>
<section title="The Broker's Response to Client Connection Request">
<t>
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.
</t>
<t>
The broker responses may follow either the <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref> or the
<xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>, depending on which version(s) the broker supports.
</t>
<t>
In <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>, 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 <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref> and a solution is described in <xref target="MQTTv5"></xref>.
</t>
<t>
If the RS accepts the connection, it MUST store the token.
</t>
</section>
</section>
<section title="Authorizing PUBLISH Messages">
<section title="PUBLISH Messages from the Publisher Client to the Broker">
<t>
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 the introspection
result may be checked, see <xref target="token_validation"></xref>).-->
</t>
<t>
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.
</t>
<t>
In case of a failure, it is not possible to return an error in
<xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>.
Acknowledgement messages only indicate 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 <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>,
it is possible to indicate failure and provide a reason code.
<xref target="MQTTv5"></xref> describes in more detail how MQTT v5 handles
PUBLISH authorization errors.
</t>
</section>
<section title="PUBLISH Messages from the Broker to the Subscriber Clients">
<t>To forward PUBLISH messages to the subscribing clients, the broker identifies all the
subscribers that have valid matching 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.
</t>
<t>
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 disconnects the client.
In the <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>, 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 <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>, a server-side DISCONNECT
message is possible and described in <xref target="MQTTv5"></xref>.
</t>
</section>
</section>
<section title="Authorizing SUBSCRIBE Messages">
<t>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.
</t>
<t>
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 <xref target="token_validation"></xref>).-->
</t>
<t>
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.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.
</t>
</section>
<section title="Token Expiration">
<t>
The broker MUST check for token expiration whenever a CONNECT, PUBLISH or SUBSCRIBE message is received
or sent. The broker SHOULD check for token expiration on receiving a PINGREQUEST message. This may allow
for early detection of a token expiry.
</t>
<t>
The token expiration is checked by checking the 'exp' claim of a CWT/JWT or via performing an
introspection request with the Authorization server as described in Section 5.7 of <xref
target="I-D.ietf-ace-oauth-authz">the ACE framework</xref>.
In the basic operation, token expirations MAY lead to disconnecting the associated client.
However, in <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>,
better error handling and re-authentication are possible.
This is explained in more detail in <xref target="MQTTv5"></xref>.
</t>
</section>
<section title="Handling Disconnections and Retained Messages" anchor="disconnections">
<t>
According to <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>, only Client
DISCONNECT messages are allowed. In <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>,
server-side DISCONNECT messages are possible, allowing to return '0x87 Not Authorized' return code
to the client.
</t>
<t>
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.
</t>
<t>
In case of disconnections due to network errors or server disconnection due to a protocol error
(which includes authorization 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.
</t>
</section>
</section>
<section anchor="MQTTv5" title="Improved Protocol Interactions with MQTT v5">
<t>
In the new <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>,
several new capabilities are introduced, which enable better integration with ACE.
The newly enhanced authentication and re-authentication methods support a wider range of authentication flows
beyond username and password. With the MQTT v5, there is a
clearly defined approach for using token-based authorization. Also, it is possible for a client to request a re-authentication
avoiding disconnection.
Finally, MQTT v5 generally improves error reporting, enabling better response to authorization failures during
publishing messages to the subscribers.
</t>
<section anchor="token_transport_v5" title="Token Transport via Authentication Exchange (AUTH)">
<t>
To initiate the authentication and authorization flow,
as before, the CAS initiates the token request as in <xref target="token_acquisition"></xref>.
When the client wishes to connect to the RS (broker), it uses the CONNECT message of MQTT.
<xref target="mqtt5_connect_message"></xref>
shows the structure of the MQTT CONNECT control message used in MQTT v5.
</t>
<figure align="center" anchor="mqtt5_connect_message"
title="MQTT CONNECT control message. (CPT=Control Packet Type, Rsvd=Reserved, len.=length, Proto.=Protocol)">
<artwork align="left"><![CDATA[
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' |
| Auth. Data (0x16) | empty or token or |
| token + PoP data |
+------------------------------------------------------+
]]></artwork>
</figure>
<t>
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), the new MQTT v5
session flags MUST be set appropriately: the Clean Start Flag MUST be set to 1
and Session Expiry Interval MUST be set to 0.
</t>
<t>
With the enhanced authentication capabilities, it is not 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 <xref target="connect_v31"></xref>.
The rest of this section describes the AUTH method.
</t>
<t>
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'. If the RS does not support this profile, it sends a CONNACK with a
Reason Code of '0x8C (Bad authentication method)'
</t>
<t>
The Authentication Method is followed by the 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 <xref target="connect_v31"></xref>.
The encoding of this field MAY use CBOR and COSE.
In this case, the token validation proceeds as described in <xref target="token_validation"></xref> and the
server responds with a CONNACK. The reason code of the CONNACK is '0x00 (Success)' if the authentication is successful.
In case of an invalid PoP token, the CONNACK reason code is '0x87 (Not Authorized)'.
</t>
<t>
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' 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'.
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 return code '0x00 (Success)' if the authentication is successful.
In case of an invalid PoP token, the CONNACK reason code is '0x87 (Not Authorized)'.
</t>
<t>
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 the CONNACK reason code '0x87 (Not Authorized)' and includes a User Property for the AS information.
AS Information contains the absolute URI of AS, and MAY also contain a cnonce as described in the Section 5.1 of <xref target="I-D.ietf-ace-oauth-authz">the ACE framework</xref>.
This information MAY be CBOR encoded.
</t>
</section>
<section anchor="improved_error_messaging" title="Authorization Errors and Client Re-authentication">
<t>
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 that RS responds with either a PUBACK or PUBREC packet with reason code
'0x87 (Not authorized)' in the case of an authorization error.
Similarly, for the SUBSCRIBE case, the SUBACK packet has 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.1,
the server needed to drop the connection).
RS MUST stop forwarding messages to the unauthorized subscribers.
</t>
<t>
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 reason code '0x19 (Re-authentication)'. The client MUST
set the authentication method as 'ace' and transport the new token in the Authentication Data.
The client and the RS go through the same steps for proof of possession validation as described in the previous section.
If the re-authentication fails, the server
MUST send a DISCONNECT with the reason code '0x87 (Not Authorized)'.
</t>
</section>
</section>
<!-- This PI places the pagebreak correctly (before the section title) in the text output. -->
<!--<?rfc needLines="8" ?>-->
<!-- Possibly a 'Acknowledgements'/ 'Contributors' section ... -->
<section anchor="IANA" title="IANA Considerations">
<t>The following registrations are done for the ACE OAuth Profile Registry following the procedure specified in
<xref target="I-D.ietf-ace-oauth-authz"></xref>.
</t>
<t>Note to the RFC editor: Please replace all occurrences of "[RFC-XXXX]" with the RFC number of this specification
and delete this paragraph.
</t>
<t>Profile name: mqtt_tls</t>
<t>Profile description: Profile for delegating client authentication and authorization using MQTT as the application protocol
and TLS For transport layer security.</t>
<t>Profile ID: </t>
<t>Change controller: IESG </t>
<t>Reference: [RFC-XXXX]</t>
</section>
<section anchor="Security" title="Security Considerations">
<t> This document specifies a profile for the Authentication and Authorization for Constrained Environments (ACE) framework
<xref target="I-D.ietf-ace-oauth-authz"></xref>. Therefore, the security considerations outlined
in <xref target="I-D.ietf-ace-oauth-authz"></xref> apply to this work.
</t>
<t> In addition, the security considerations outlined in <xref target="MQTT-OASIS-Standard">MQTT v3.1.1 - the OASIS Standard</xref>
and <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>
apply. Mainly, this document provides an authorization solution for MQTT,
the responsibility of which is left to the specific implementation in <xref target="MQTT-OASIS-Standard-v5">MQTT v5 - the OASIS Standard</xref>.
In the following, we comment on a few relevant issues based on the current MQTT specifications.
</t>
<t>In this document, RS uses the PoP access token to authenticate the client. If the client is able, TLS certificates
sent from the client can be used by the RS to authenticate the client.
The TLS certificate from the RS MUST be used by the client to authenticate the RS.
</t>
<t>To authorize a client's publish and subscribe requests in an ongoing session, the RS caches the access token after accepting the
connection from the client. However, if some permissions are revoked in the meantime,
the RS may still grant publish/subscribe to revoked topics until the session ends or the token expires.
When permissions change dynamically, it is expected that AS follows a reasonable expiration strategy for the access tokens.
</t>
<t> The RS may monitor client behaviour to detect potential security problems, especially those affecting availability.
These include repeated token transfer attempts to the public "authz-info" topic, repeated connection attempts,
abnormal terminations, and clients that connect but do not send any data.
If the RS supports the public "authz-info" topic, described in <xref target="app-authzinfo"></xref>,
then this may be vulnerable to a DDoS attack, where many clients use the "authz-info" public topic to transport fictitious tokens,
which RS may need to store indefinitely.</t>
</section>
<section anchor="Privacy" title="Privacy Considerations">
<t>The privacy considerations outlined in <xref target="I-D.ietf-ace-oauth-authz"></xref> apply to this work.
</t>
<t>In MQTT, the RS is a central trusted party and may forward potentially sensitive information
between clients. Clients may choose to encrypt the payload of their messages.
However, this would not provide privacy for other properties of the message such as topic name.
</t>
</section>
</middle>
<!-- *****BACK MATTER ***** -->
<back>
<!-- References split into informative and normative -->
<!-- There are 2 ways to insert reference entries from the citation libraries:
1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
(for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")
Both are cited textually in the same manner: by using xref elements.
If you use the PI option, xml2rfc will, by default, try to find included files in the same
directory as the including file. You can also define the XML_LIBRARY environment variable
with a value containing a set of directories to search. These can be either in the local
filing system or remote ones accessed by http (http://domain/dir/... ).-->
<references title="Normative References">
<!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?-->
&RFC2119;
&RFC4648;
&RFC8174;
<reference anchor="MQTT-OASIS-Standard"
target="http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">
<front>
<title>
OASIS Standard MQTT Version 3.1.1 Plus Errata 01
</title>
<author initials="A." surname="Banks" role="editor">
<organization>IBM</organization>
</author>
<author initials="R." surname="Gupta" role="editor">
<organization>IBM</organization>
</author>
<date year="2015"/>
</front>
</reference>
<reference anchor="MQTT-OASIS-Standard-v5"
target="http://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html">
<front>
<title>
OASIS Standard MQTT Version 5.0
</title>
<author initials="A." surname="Banks" role="editor">
<organization>IBM</organization>
</author>
<author initials="E." surname="Briggs" role="editor">
<organization>Microsoft</organization>
</author>
<author initials="K." surname="Borgendale" role="editor">
<organization>IBM</organization>
</author>
<author initials="R." surname="Gupta" role="editor">
<organization>IBM</organization>
</author>
<date year="2017"/>
</front>
</reference>
<?rfc include="reference.I-D.ietf-ace-oauth-authz.xml"?>
<?rfc include="reference.I-D.gerdes-ace-dtls-authorize.xml"?>
</references>
<references title="Informative References">
<!-- Here we use entities that we defined at the beginning. -->
<!-- A reference written by by an organization not a person. -->
<?rfc include="reference.I-D.ietf-ace-actors.xml"?>
<?rfc include="reference.I-D.ietf-ace-cwt-proof-of-possession.xml"?>
&RFC4949;