-
Notifications
You must be signed in to change notification settings - Fork 12
/
index.html
1107 lines (1045 loc) · 55.2 KB
/
index.html
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
<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<link rel="stylesheet" href="tablestyle.css">
<meta charset="utf-8" />
<title>Web of Things (WoT) Security Best Practices</title>
<script class="remove" async="" src="https://www.w3.org/Tools/respec/respec-w3c"></script>
<script class="remove">
var respecConfig = {
specStatus: "ED"
, noRecTrack: "true"
, processVersion: 2017
, shortName: "wot-security-best-practices"
, copyrightStart: 2017
, group: "wg/wot"
, edDraftURI: "https://w3c.github.io/wot-security-best-practices/"
, githubAPI: "https://api.github.com/repos/w3c/wot-security-best-practices"
, issueBase: "https://www.github.com/w3c/wot-security-best-practices/issues/"
, editors: [
{
name: "Elena Reshetova"
, w3cid: "99327"
, company: "Intel Corp."
, companyURL: "https://www.intel.com/"
},
{
name: "Michael McCool"
, w3cid: "93137"
, company: "Intel Corp."
, companyURL: "https://www.intel.com/"
}
]
, otherLinks: [
{
key: "Contributors"
, data: [
{
value: "In the GitHub repository"
, href: "https://github.com/w3c/wot-security-best-practices/graphs/contributors"
}
]
}
, {
key: "Repository",
data: [
{
value: "We are on GitHub",
href: "https://github.com/w3c/wot-security-best-practices/"
}
, {
value: "File a bug",
href: "https://github.com/w3c/wot-security-best-practices/issues"
}
, {
value: "Contribute",
href: "https://github.com/w3c/wot-security-best-practices/pulls"
}
]
}
]
, localBiblio: {
"CoRE-RD": {
href: "https://tools.ietf.org/html/draft-ietf-core-resource-directory-11"
, title: "CoRE Resource Directory"
, status: "Internet-Draft"
, publisher: "IETF"
, date: "03 July 2017"
},
"Ocf17": {
href: "https://openconnectivity.org/specs/OCF_Security_Specification_v1.0.0.pdf"
, title: "The OCF Security Specification, version 1.0.0"
, publisher: "OCF"
, date: "June 2017"
},
"Bel89": {
authors: ["S. Bellovin"]
, href: "https://cseweb.ucsd.edu/classes/sp99/cse227/ipext.pdf"
, title: "Security Problems in the TCP-IP Protocol Suite"
, publisher: "Computer Communication Review, Vol. 19, No. 2"
, pages: "32-48"
, date: "April 1989"
},
"Bel13": {
authors: ["S. Bellovin"]
, href: "https://csrc.nist.gov/csrc/media/events/workshop-on-improving-trust-in-the-online-marketpl/documents/presentations/bellovin_ca-workshop2013.pdf"
, title: "Web Security in the Real World"
, publisher: "Workshop on Improving Trust in the Online Marketplace, NIST"
, date: "April 2013"
},
"Ber14": {
authors: ["V. Bertocci"]
, href: "http://www.cloudidentity.com/blog/2014/04/22/authentication-protocols-web-ux-and-web-api/"
, title: "Authentication Protocols, Web UX and Web API"
, date: "April 2014"
},
"Bor14": {
authors: ["C. Bormann", "et al."]
, href: "https://tools.ietf.org/rfc/rfc7228.txt"
, title: "Terminology for Constrained-Node Networks"
, publisher: "IETF RFC 7228"
, date: "May 2014"
},
"Bru14": {
authors: ["C. Brubaker", "et al."]
, href: "https://www.cs.utexas.edu/~shmat/shmat_oak14.pdf"
, title: "Using Frankencerts for Automated Adversarial Testing of Certificate Validation in SSL/TLS Implementations"
, publisher: "IEEE Security Privacy"
, date: "2014"
, pages: "114-129"
},
"Coo13": {
authors: ["A. Cooper", "et al"]
, href: "https://tools.ietf.org/html/rfc6973"
, title: "Privacy Considerations for Internet Protocols"
, publisher: "IETF RFC 6973 (IAB Guideline)"
, date: "July 2013"
},
"Lea05": {
authors: ["P. Leach", "et al"]
, href: "https://tools.ietf.org/html/rfc4122"
, title: "A Universally Unique IDentifier (UUID) URN Namespace"
, publisher: "IETF RFC 4122"
, date: "July 2005"
},
"Dur13": {
authors: ["Z. Durumeric", "et al."]
, href: "https://conferences.sigcomm.org/imc/2013/papers/imc257-durumericAemb.pdf"
, title: "Analysis of the HTTPS Certificate Ecosystem"
, publisher: "Proc. of the 2013 conference on Internet measurement conference"
, date: "October 2013"
},
"Ell00": {
authors: ["C. Ellison", "B. Schneier"]
, href: "https://www.schneier.com/paper-pki.pdf"
, title: "Ten Risks of PKI: What You’re not Being Told about Public Key Infrastructure"
, publisher: "Computer Security Journal, v 16, n 1,"
, date: "2000"
, pages: "1-7"
},
"Fu01": {
authors: ["K. Fu", "et al."]
, href: "https://pdos.csail.mit.edu/papers/webauth:sec10.pdf"
, title: "Dos and Don’ts of Client Authentication on the Web"
, publisher: "Proc. 10th USENIX Security Symposium"
, date: "August 2001"
},
"Garcia17": {
authors: ["O. Garcia-Morchon", "S. Kumar", "M. Sethi"]
, title: "State-of-the-Art and Challenges for the Internet of Things Security"
, href: "https://datatracker.ietf.org/doc/draft-irtf-t2trg-iot-seccons/"
},
"Geo12": {
authors: ["M. Georgiev", "et al."]
, href: "https://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf"
, title: "The Most Dangerous Code in the World: Validating SSL Certificates in Non-Browser Software"
, publisher: "Proc. of the 2012 ACM conference on Computer and communications security"
, date: "2012"
, pages: "38-49"
},
"Gol03": {
authors: ["O. Goldreich"]
, href: "http://www.wisdom.weizmann.ac.il/~oded/foc-sur01.html"
, title: "Cryptography and Cryptographic Protocols"
, publisher: "Distributed Computing, vol. 16"
, pages: "177-199"
, date: "2003"
},
"Gre14": {
authors: ["M. Green"]
, href: "https://blog.cryptographyengineering.com/2014/03/19/how-do-you-know-if-rng-is-working/"
, title: "How do you know if an RNG is working?"
, date: "March 2014"
},
"Gut02": {
authors: ["P. Gutman"]
, href: "https://www.cs.auckland.ac.nz/~pgut001/pubs/notdead.pdf"
, title: "PKI: It’s Not Dead, Just Resting"
, publisher: "IEEE Computer, vol. 35, no. 8"
, date: "Aug. 2002"
, pages: "41-49"
},
"Hea13": {
authors: ["M. Hearn"]
, href: "https://googleblog.blogspot.de/2013/02/an-update-on-our-war-against-account.html"
, title: "An update on our war against account hijackers"
, date: "Feb 2013"
},
"IETFACE": {
title: "IETF Authentication and Authorization for Constrained Environments (ACE)"
, href: "https://tools.ietf.org/wg/ace/"
},
"Iic15": {
authors: ["Industrial Internet Consortium"]
, href: "http://www.iiconsortium.org/IIRA.htm"
, title: "Industrial Internet Reference Architecture"
, date: "June 2015"
},
"IicRA17": {
authors: ["Industrial Internet Consortium"]
, href: "https://www.iiconsortium.org/IIRA.htm"
, title: "The Industrial Internet of Things Volume G1: Reference Architecture"
, publisher: "IIC:PUB:G1:V1.80:20170131"
, date: "Jan 2017"
},
"IicSF16": {
authors: ["Industrial Internet Consortium"]
, href: "https://www.iiconsortium.org/IISF.htm"
, title: "The Industrial Internet of Things Volume G4: Security Framework"
, publisher: "IIC:PUB:G4:V1.0:PB:20160926"
, date: "Sept 2016"
},
"ISF17": {
authors: ["IoT Security Foundation"]
, href: "https://iotsecurityfoundation.org/best-practice-guidelines/"
, title: "IoT Security Foundation Best Practice Guidelines"
, date: "May 2017"
},
"Jon14": {
authors: ["M. Jones"]
, href: "http://www.niso.org/sites/default/files/stories/2017-08/SP_Jones_JSON_isqv26no3.pdf"
, title: "A JSON-Based Identity Protocol Suite"
, publisher: "Information Standards Quarterly, vol. 26, no. 3"
, date: "2014"
, pages: "19–22"
},
"Ken03": {
authors: ["S. Kent", "L. Millet"]
, href: "https://www.nap.edu/read/10656/chapter/1"
, title: "Who Goes There? Authentication Through the Lens of Privacy"
, publisher: "The National Academies Press, Washington D.C."
, date: "2003"
},
"Lam04": {
authors: ["B. Lampson"]
, href: "https://pdfs.semanticscholar.org/6fe5/ba7a096e391d985e7818fef9d0f0636210a0.pdf"
, title: "Computer Security in the Real World"
, publisher: "IEEE Computer, vol. 37, no. 6"
, date: "June 2004"
, pages: "37-46"
},
"Loc05": {
authors: ["H. Lockhart"]
, href: "http://www.oracle.com/technetwork/testcontent/saml-084342.html"
, title: "Demystifying SAML"
, date: "May 2005"
},
"Mel15": {
authors: ["D. Melzer"]
, href: "https://c.ymcdn.com/sites/www.issa.org/resource/resmgr/journalpdfs/feature0615.pdf"
, title: "Securing the Industrial Internet of Things"
, date: "June 2015"
},
"Mic17": {
authors: ["Microsoft"]
, href: "https://docs.microsoft.com/en-us/azure/iot-suite/iot-security-architecture"
, title: "Internet of Things security architecture"
, publisher: "STRIDE threat model for IoT"
, date: "Jan 2017"
},
"Moo02": {
authors: ["T. Moors"]
, href: "https://www.csd.uoc.gr/~hy435/material/moors.pdf"
, title: "A critical review of End-to-end arguments in system design"
, publisher: "Proc. of the IEEE International Conference on Communications"
, date: "2002"
},
"Nis15": {
authors: ["NIST"]
, title: "Guide to Industrial Control Systems (ICS) Security"
, publisher: "NIST Special Publication 800-82"
},
"Oos10": {
authors: ["M. Oosdijk", "et al."]
, href: "https://tnc2011.terena.org/getfile/696"
, title: "Provisioning scenarios in identity federations"
, publisher: "Surfnet Research Paper"
, date: "2010"
},
"Owa17": {
authors: ["OWASP"]
, href: "https://www.owasp.org/index.php/Threat_Risk_Modeling"
, title: "Threat Risk Modeling"
, publisher: "OWASP"
, date: "Jan 2017"
},
"Res03": {
authors: ["E. Rescorla", "et al."]
, href: "https://tools.ietf.org/html/rfc3552"
, title: "Guidelines for Writing RFC Text on Security Considerations"
, publisher: "IETF RFC 3552 (IAB Guideline)"
, date: "2003"
},
"Sch14": {
authors: ["B. Schneier"]
, href: "https://www.wired.com/2014/01/theres-no-good-way-to-patch-the-internet-of-things-and-thats-a-huge-problem/"
, title: "The Internet of Things Is Wildly Insecure — And Often Unpatchable"
, publisher: "Wired"
, date: "Jan. 2014"
},
"Sch99": {
authors: ["B. Scheier", "A. Shostack"]
, href: "https://www.schneier.com/paper-smart-card-threats.pdf"
, title: "Breaking Up Is Hard To Do: Modeling Security Threats for Smart Cards"
, publisher: "USENIX Workshop on Smart Card Technology, USENIX Press"
, date: "1999"
, pages: "175-185"
},
"She14": {
authors: ["Z. Shelby", "et al."]
, href: "https://tools.ietf.org/rfc/rfc7252.txt"
, title: "The Constrained Application Protocol (CoAP)"
, publisher: "IETF RFC 7252"
, date: "June 2014"
},
"Vol00": {
authors: ["J. Vollbrecht", "et al."]
, href: "https://tools.ietf.org/rfc/rfc2904.txt"
, title: "AAA Authorization Framework"
, publisher: "IETF RFC 2904"
, date: "Aug. 2000"
},
"Yeg11": {
authors: ["S. Yegge"]
, href: "https://plus.google.com/+RipRowan/posts/eVeouesvaVX"
, title: "Stevey's Google Platforms Rant"
, publisher: "Blog"
, date: "Oct. 2011"
}
}
};
</script>
</head>
<body>
<section id="abstract">
<p>
This document provides non-normative guidance on
how to implement Web of Things (WoT) using best practices
for security and privacy.
When doing security testing, use of these best practices is assumed.
</p>
</section>
<section id="sotd">
<p class="ednote" title="The W3C WoT WG is asking for feedback">
Please contribute to this draft using the
<a href="https://github.com/w3c/wot-security-best-practices/issues">GitHub Issue</a>
feature of the <a href="https://github.com/w3c/wot-security-best-practices/">WoT
Security Best Practices</a> repository.
</p>
</section>
<section>
<h1>Introduction</h1>
<p>
For a general discussion of WoT security and privacy issues, see the
<a href="https://www.w3.org/TR/2018/NOTE-wot-security-20181203/">WoT
Security and Privacy Guidelines</a> document.
</p>
<p>For details on the Web of Things architecture, please refer to the following:
<ul>
<li>the <a href="https://www.w3.org/WoT/IG/">Interest Group</a> web site</li>
<li>the <a href="https://www.w3.org/WoT/WG/">Working Group</a> web site</li>
<li>the <a href="https://www.w3.org/TR/2017/WD-wot-architecture-20170914/">WoT Architecture</a>
document,</li>
<li>the <a href="https://www.w3.org/TR/2017/WD-wot-thing-description-20170914/">WoT Thing Description</a>
document,</li>
<li>the <a href="https://w3c.github.io/wot-binding-templates/">WoT Binding Templates</a>
document, and</li>
<li>the <a href="https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/">WoT Scripting API</a>
document.</li>
</ul>
</p>
</section>
<section>
<h1>Secure Transport</h1>
<p>Secure transport is the foundation of many other security mechanisms, which are
vulnerable if it is not used. For example, basic/digest passports and bearer tokens
(used in OAuth2) can be intercepted by attackers on the network if transport is not encrypted.
Enabling secure transport is essential despite the challenges of using it
especially in isolated or local networks.
</p>
<p>In general, the recommendation is to use the latest version of
TLS and DTLS available, consistent with interoperability requirements.
Currently, the latest version of TLS is 1.3 but as this is not yet
widely deployed, for interoperability a system may have to be based on
TLS 1.2.
However, as TLS 1.3 addresses several vulnerabilities in TLS 1.2
in general a migration plan should be in place to TLS 1.3 and new
implementations should target TLS 1.3 if possible.
</p>
<p>Systems should implement the following for each of the given protocols:
<dl>
<dt>HTTPS:</dt><dd><p>HTTP + TLS 1.3</p></dd>
<dt>CoAPS:</dt><dd><p>CoAP + DTLS. See also:
<ul>
<li><a href="https://tools.ietf.org/html/rfc7925">IETF RFC7925:</a>
Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS)
Profiles for the Internet of Things</li>
<li><a href="https://tools.ietf.org/html/rfc7252">IETF RFC7252:</a>
The Constrained Application Protocol (CoAP)</li>
</ul></p></dd>
<dt>MQTTS:</dt><dd><p>MQTT + TLS 1.3. See also:
<ul>
<li><a href="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=mqtt">
OASIS Message Queuing Telemetry Transport (MQTT) TC</a></li>
<li><a href="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=mqtt-security">
MQTT Security Subcommittee</a></li>
<li>Standard URL scheme for "mqtts://..."
(Note: a draft IETF RFC for the MQTT URL scheme is being discussed)</li>
</ul></p></dd>
</dl>
<section id="secure-transport-local">
<h2>Global Networks</h2>
<p>To do. Use of public URLs, certificates, and CA.
<p>
</section>
<section id="secure-transport-local">
<h2>Offline and Local Networks</h2>
<p>We define a local network as one in which not all endpoints are visible to the rest of the internet.
This can include both fully offline isolated networks, such as those often used for factory automation,
and networks behind a NAT or firewall, as are common for home or business networks. In these cases,
establishing the identity of endpoints based on publically visible URLs and the CA system is not
possible.
</p><p>In order to secure HTTP and COAP with TLS/DTLS in local networks, we highly recommend
the usage of TLS 1.3 with Raw Public Keys as specified in <a href="https://datatracker.ietf.org/doc/html/rfc8446">RFC8446</a> and
<a href="https://datatracker.ietf.org/doc/html/rfc7250">RFC7250</a>.
However, the keys still need to be assigned and the identities of endpoints established.
In local networks, this should be accomplished using an onboarding process, discussed in the next section.
</p>
<p class="ednote" title="Local Security Best Practices Under Discussion">
Best practices for local security are still
<a href="https://github.com/w3c/wot-security-best-practices/issues/13">under discussion.</a>
</p>
</p><p>
Unfortunately it may not be possible in general to use some useful consumers, in particular browsers,
with this infrastructure. The best option is to include client devices in the onboarding practice
and register a certificate that the browser can use. This is the only option for fully isolated networks.
The second best option, usable only for segmented networks with a NAT and/or firewall, is to expose a limited
number of secure endpoints, for example a "dashboard" service on a home hub, to the internet, and give
it a public URL and certificate. This can be accomplished using either STUN/TURN to set up a tunnel
through the NAT and a system such as DynDNS to establish the public IP, or a cloud-based (reverse) proxy.
Of course such exposed endpoints should have strong authentication
requirements (OAuth2 is recommended). Individual IoT devices in such a system should generally
not be directly exposed to the internet.
</p>
</section>
</section>
<section>
<h1>Onboarding</h1>
<p>Onboarding is the process of establishing trust with new endpoints in a network, which includes
establishing a way to confirm their identities and establishing a mechanism to share encryption keys.
This process is essential in order to establish secure transport between endpoints.
For systems that are globally visible on the internet, the CA (Certificate Authority) service can
be considered an onboarding process that assigns certificates to endpoints. The URL used to access
endpoints then becomes the endpoints' identity, and is encrypted into the certificate that is provided.
For devices on local networks, keys can be assigned during the onboarding process, but a mechanism
to establish the identities of endpoints is also needed.
</p><p>
See the following ITRF/IETF references:
<a href="https://datatracker.ietf.org/doc/html/draft-sarikaya-t2trg-sbootstrapping">Terminology and processes for initial security setup of IoT devices</a>,
<a href="https://www.ietf.org/id/draft-nordmark-iotops-onboarding-00.html">Different Aspects of Onboarding for IoT/Edge Devices</a>,
<a href="https://datatracker.ietf.org/doc/html/rfc8995">BRSKI</a>,
and
<a href="https://datatracker.ietf.org/doc/html/rfc8257">SZTP</a>.
Some related work in the W3C is also relavant, in particular
<a href="https://www.w3.org/TR/did-core/">Decentralized Identifiers (DID)</a> and
<a href="https://www.w3.org/TR/vc-data-model/">Verifiable Credentials (VC)</a>.
</p>
<p class="issue" data-number="29" title="Scripting API Issues Related to Security">
The WoT Scripting API needs to establish a secure environment for a script to run in and also needs to
expose and consume secure network endpoints.
Several of the
<a href="https://github.com/w3c/wot-security-best-practices/issues/29">open issues in the WoT Scripting API</a>
depend on the need for
secure onboarding, specifically the provision and management of keys and identities.
</p>
</section>
<section>
<h1>Authentication and Access Control</h1>
<p>
The best practices for authentication and access control depend on the protocol.
In most cases, authentication schemes should only be considered
secure when used in combination with secure transport.
We recommend the following combinations:
<ul>
<li>HTTPS with one of oauth2, bearer, basic, or digest security schemes.</li>
<li>CoAPS with one of psk, public, or cert security schemes.</li>
<li>MQTTS with basic AND psk (MQTT native username/password with psk for encrypted communication)</li>
</ul>
</p>
<p>In addition, TDs with HTTP/nosec and CoAP/nosec should be tested and properly handled.
They are useful in conjunction with proxies that layer on one of the above secure
transport and authentication schemes.
</p>
<p>"Local HTTPS" is still a topic of discussion. In addition to the above schemes,
using HTTPS with psk, public, or cert schemes to share keys to be used for TLS transport
is also acceptable for machine-to-machine communication. However, currently such schemes may
require the user to manually install or accept keys or certificates when using a browser.
</p>
<section id="oauth-flows">
<h2>OAuth2 Flows</h2>
OAuth 2.0 is an authorization protocol widely known for its usage across several web services.
It enables third-party applications to obtain limited access to HTTP services on behalf of the resource
owner
or of itself.
The protocol defines the following actors:
<ul>
<li>Client: an application that wants to use a resource owned by the resource owner. </li>
<li>Authorization Server: An intermediary that authorizes the client for a particular `scope`. </li>
<li>Resource: a web resource </li>
<li>Resource Server: the server where the resource is stored</li>
<li>Resource Owner: the owner of a particular web resource. If it is a human is usually referred to as an
end-user. More specifically from the RFC:</li>
<ul>
<li>An entity capable of granting access to a protected resource.</li>
</ul>
</ul>
These actors can be mapped to WoT entities:
<ul>
<li>Client is a WoT Consumer</li>
<li>Authorization Server is a third-party service</li>
<li>Resource is an interaction affordance</li>
<li>Resource Server is a Thing described by a Thing Description acting as a server. </li>
May be a device or a service.
<li>Resource Owner might be different in each use case.
A Thing Description may also combine resources from different owners or web server.</li>
</ul>
<div class="ednote" id="issue-container-generatedID">
<div role="heading" class="ednote-title marker" id="h-ednote"
aria-level="2">
<span>Editor's note</span><span style=
"text-transform: none">: Check the OAuth 2.0 spec to determine exactly how Resource Owner is defined.</span>
</div>
<p class="">Is it the actual owner of the resource (eg running the web server) or simply someone
with the rights to access that resource?</p>
</div>
The OAuth 2.0 protocol specifies an authorization layer that separates the client from the resource owner.
The basic steps of this protocol are summarized in the following diagram:
<pre>
+--------+ +---------------+
| |--(A)- Authorization Request ->| Resource |
| | | Owner |
| |<-(B)-- Authorization Grant ---| |
| | +---------------+
| |
| | +---------------+
| |--(C)-- Authorization Grant -->| Authorization |
| Client | | Server |
| |<-(D)----- Access Token -------| |
| | +---------------+
| |
| | +---------------+
| |--(E)----- Access Token ------>| Resource |
| | | Server |
| |<-(F)--- Protected Resource ---| |
+--------+ +---------------+
</pre>
<p>
Steps A and B defines what is known as authorization grant type or flow.
What is important to realize here is that not all of these interactions
are meant to take place over a network protocol.
In some cases,
interaction with with a human through a user interface may be intended.
OAuth2.0 defines 4 basic flows plus an extension mechanism.
The most common of which are:
<ul>
<li>`code`</li>
<li>`implicit`</li>
<li>`password` (of resource owner)</li>
<li>`client` (credentials of the client)</li>
</ul>
</p>
<p>
In addition, a particular extension which is of interest to IoT is the `device` flow.
Further information about the OAuth 2.0 protocol can be found in
<a href="https://tools.ietf.org/html/rfc6749#section-1">IETF RFC6749</a>.
In addition to the flows, OAuth 2.0 also supports scopes.
Scopes are identifiers which can be attached to tokens.
These can be used to limit authorizations to
particular roles or actions in an API.
Each token carries a set of scopes and these can be checked when an interaction
is attempted and access can be denied if the token does not include a scope
required by the interaction.
This document describes relevant use cases for each of the OAuth 2.0 authorization flows.
</p>
<section>
<h3>Expected Devices</h3>
<dl>
<dd>
To support OAuth 2.0, all devices must have the capability of:
<ul>
<li>Both the producer and consumer must be able to create and participate in a TLS connection.</li>
<li>The producer must be able to verify an access (bearer) token (i.e. have sufficient computational
power/connectivity). </li>
</ul>
Comment:
<ul>
<li>Investigate whether DTLS can be used.</li>
Certainly the connection needs to be encrypted; this is required in the OAuth 2.0 specification.
<li>Investigate whether protocols other than HTTP can be used, e.g. CoAP.</li>
<ul>
<li>found an interesting IETF draft RFC about CoAP support(encrypted using various mechanisms like DTLS
or
CBOR Object Signing and Encryption): <a
href="https://tools.ietf.org/html/draft-ietf-ace-oauth-authz-35">draft-ietf-ace-oauth</a></li>
</ul>
</ul>
</dd>
</dl>
</section>
<section>
<h3>Expected Data</h3>
<dl>
<dd>
Depending on the OAuth 2.0 flow specified, various URLs and elements need to be specified,
for example, the location of an authorization token server.
OAuth 2.0 is also based on bearer tokens and so
needs to include the same data as those, for example, expected encryption suite.
Finally,
OAuth 2.0 supports scopes so these need to be defined in the security scheme and specified in
the form.
</dd>
</dl>
</section>
<section>
<h3>Affected WoT deliverables and/or work items</h3>
<dl>
<dd>
Thing Description, Scripting API, Discovery, and Security.
</dd>
</dl>
</section>
<section>
<h3>Description</h3>
<dl>
<dd>
A general use case for OAuth 2.0 is when a WoT consumer wants to access restricted interaction
affordances.
In particular, when those affordances have a specific resource owner which
may grant some temporary permissions to the consumer.
The WoT consumer can either be hosted in a remote device or interact directly with the end-user inside an
application.
</dd>
</dl>
</section>
<section>
<h3>Variants</h3>
<dl>
<dd>
For each OAuth 2.0 flow, there is a corresponding use case variant.
We also include the experimental "device" flow for consideration.
<br>
<br>
code
A natural application of this protocol is when the end-user wants to interact directly with the consumed
thing or to grant his authorization to a remote device. In fact from the <a
href="https://tools.ietf.org/html/rfc6749#section-4.1">RFC6749</a>
<ul>
<li>
Since this is a redirection-based flow, the client must be capable of
interacting with the resource owner's user-agent (typically a web
browser) and capable of receiving incoming requests (via redirection)
from the authorization server.
</li>
</ul>
This implies that the code flow can be only used when the resource owner interacts directly with the WoT
consumer at least once. Typical scenarios are:
<ul>
<li>In a home automation context, a device owner uses a third party software to interact
with/orchestrate one or more devices</li>
<li>Similarly, in a smart farm, the device owner might delegate its authorization to third party
services.</li>
<li>In a smart home scenario, Thing Description Directories might be deployed using this authorization
mechanism. In particular, the list of the registered TDs might require an explicit read authorization
request to the device owner (i.e. an human who has bought the device and installed it). </li>
<li>... </li>
</ul>
The following diagram shows the steps of the protocol adapted to WoT idioms and entities. In this
scenario, the WoT Consumer has read the Thing Description of a Remote Device and want to access one of its
WoT Affordances protected with OAuth 2.0 code flow.
<pre>
+-----------+
+----------+ | |
| Resource | | Remote |
| Owner | | Device +<-------+
| | | | |
+----+-----+ +-----------+ |
^ |
| |
(B) |
+------------+ Client Identifier +---------------+ |
| ------(A)-- & Redirection URI ---->+ | |
| User- | | Authorization | |
| Agent ------(B)-- User authenticates --->+ Server | |
| | | | |
| ------(C)-- Authorization Code ---<+ | |
+---+----+---+ +---+------+----+ |
| | ^ v |
(A) (C) | | |
| | | | |
^ v | | |
+---+----+---+ | | |
| |>-+(D)-- Authorization Code ---------' | |
| WoT | & Redirection URI | |
| Consumer | | |
| |<-+(E)----- Access Token -------------------' |
+-----+------+ (w/ Optional Refresh Token) |
v |
| |
+-----------(F)----- Access WoT --------------------------------+
Affordance
</pre>
Notice that steps (A), (B) and (C) are broken in two parts as they pass through the User-Agent.
<p>device</p>
The device flow (IETF <a href="https://tools.ietf.org/html/rfc8628">RFC 8628</a>) is a variant of the code
flow for browserless and
input-constrained devices. Similarly, to its <i>parent</i> flow, it requires a close interaction between the
resource owner and the WoT consumer. Therefore, the use cases for this flow are the same as the code
authorization grant but restricted to all devices that do not have a rich means to interact with the
resource owner. However, differently from `code`, RFC 8628 states explicitly that one of the actors of
the protocol is an <b>end-user</b> interacting with a <b>browser</b> (even if <a
href="https://tools.ietf.org/html/rfc8628#section-6.2">section-6.2</a>
briefly describes an authentication using a companion app and BLE), as shown in the following (slightly
adapted) diagram:
<pre>
+----------+
| |
| Remote |
| Device |
| |
+----^-----+
|
| (G) Access WoT Affordance
|
+----+-----+ +----------------+
| +>---(A)-- Client Identifier ---v+ |
| | | |
| +<---(B)-- Device Code, ---<+ |
| | User Code, | |
| WoT | & Verification URI | |
| Consumer | | |
| | [polling] | |
| +>---(E)-- Device Code --->+ |
| | & Client Identifier | |
| | | Authorization |
| +<---(F)-- Access Token ---<+ Server |
+-----+----+ (& Optional Refresh Token) | |
v | |
: | |
(C) User Code & Verification URI | |
: | |
^ | |
+-----+----+ | |
| End User | | |
| at +<---(D)-- End user reviews --->+ |
| Browser | authorization request | |
+----------+ +----------------+
</pre>
Notable mentions:
<ul>
<li>the protocol is heavily end-user oriented. In fact, the RFC states the following</li>
<ul>
<li>Due to the polling nature of this protocol (as specified in Section 3.4), care is needed to avoid
overloading the capacity of the token endpoint. To avoid unneeded requests on the token endpoint, the
client SHOULD only commence a device authorization request when <b>prompted by the user and not
automatically</b>, such as when the app starts or when the previous authorization session expires or
failAs.</li>
</ul>
<li>TLS is required both between WoT Consumer/Authorization Server and between Browser/Authorization
Server</li>
<li>Other user interactions methods may be used but are left out of scope</li>
</ul>
<p>client credential</p>
The Client Credentials grant type is used by clients to obtain an access token outside of the context of
an end-user. From <a href="https://tools.ietf.org/html/rfc6749#section-4.4">RFC6749</a>:
<ul>
<li>The client can request an access token using only its client
credentials (or other supported means of authentication) when
the client is requesting access to the protected resources under its
control, or <b>those of another resource owner that has been previously
arranged with the authorization server</b> (the method of which is beyond
the scope of this specification).</li>
</ul>
Therefore the client credential grant can be used:
<ul>
<li>When the resource owner is a public authority. For example, in a smart city context, the authority
provides a web service where to register an application id.</li>
<li>Companion application</li>
<li>Industrial IoT. Consider a smart factory where the devices or services are provisioned with client
credentials. </li>
<li>...</li>
</ul>
The Client Credentials flow is illustrated in the following diagram. Notice how the Resource Owner is not
present.
<pre>
+----------+
| |
| Remote |
| Device |
| |
+----^-----+
|
| (C) Access WoT Affordance
^
+----+-----+ +---------------+
| | | |
| +>--(A)- Client Authentication --->+ Authorization |
| WoT | | Server |
| Consumer +<--(B)---- Access Token ---------<+ |
| | | |
| | +---------------+
+----------+
</pre>
Comment: Usually client credentials are distributed using an external service which is used by humans to
register a particular application. For example, the `npm` cli has a companion dashboard where a developer
requests the generation of a token that is then passed to the cli. The token is used to verify the
publishing process of `npm` packages in the registry. Further examples are Docker cli and OpenId Connect
Client Credentials.
<p>implicit</p>
<b>Deprecated</b>
From <a href="https://tools.ietf.org/html/draft-ietf-oauth-security-topics-15#section-2.1.2">OAuth 2.0
Security Best Current Practice</a>:
<ul>
<li>
In order to avoid these issues, clients SHOULD NOT use the implicit
grant (response type "token") or other response types issuing access
tokens in the authorization response, unless access token injection
in the authorization, response is prevented and the aforementioned
token leakage vectors are mitigated.
</li>
</ul>
The RFC above suggests using `code` flow with Proof Key for Code Exchange (PKCE) instead.
<br>
The implicit flow was designed for public clients typically implemented inside a browser (i.e. javascript
clients). As the `code` is a redirection-based flow and it requires direct interaction with the resource's
owner user-agent. However, it requires one less step to obtain a token as it is returned directly in the
authentication request (see the diagram below).
<br>
Considering the WoT context this flow is not particularly different from `code` grant and it can be used
in the same scenarios.
<br>
Comment: even if the `implicit` flow is deprecated existing services may still using it.
<pre>
+----------+
| Resource |
| Owner |
| |
+----+-----+
^
|
(B)
+----------+ Client Identifier +---------------+
| ------(A)-- & Redirection URI --->+ |
| User- | | Authorization |
| Agent ------(B)-- User authenticates -->+ Server |
| | | |
| +<---(C)--- Redirection URI ----<+ |
| | with Access Token +---------------+
| | in Fragment
| | +---------------+
| +----(D)--- Redirection URI ---->+ Web-Hosted |
| | without Fragment | Client |
| | | Resource |
| (F) +<---(E)------- Script ---------<+ |
| | +---------------+
+-+----+---+
| |
(A) (G) Access Token
| |
^ v
+-+----+---+ +----------+
| | | Remote |
| WoT +>---------(H)--Access WoT--------->+ Device |
| Consumer | Affordance | |
| | +----------+
+----------+
</pre>
<p>resource owner password</p>
<b>Deprecated</b> From <a
href="https://tools.ietf.org/html/draft-ietf-oauth-security-topics-15#section-2.1.2">OAuth 2.0 Security
Best Current Practice</a>:
<ul>
<li>The resource owner password credentials grant MUST NOT be used. This
grant type insecurely exposes the credentials of the resource owner
to the client. Even if the client is benign, this results in an
increased attack surface (credentials can leak in more places than
just the AS) and users are trained to enter their credentials in
places other than the AS.</li>
</ul>
For completeness the diagram flow is reported below.
<pre>
+----------+
| Resource |
| Owner |
| |
+----+-----+
v
| Resource Owner
(A) Password Credentials
|
v
+-----+----+ +---------------+
| +>--(B)---- Resource Owner ------->+ |
| | Password Credentials | Authorization |
| WoT | | Server |
| Consumer +<--(C)---- Access Token ---------<+ |
| | (w/ Optional Refresh Token) | |
+-----+----+ +---------------+
|
| (D) Access WoT Affordance
|
+----v-----+
| Remote |
| Device |
| |
+----------+
</pre>
</dd>
</dl>
</section>
<section>
<h3>Security Considerations</h3>
<dl>
<dd>
See OAuth 2.0 security considerations in <a
href="https://tools.ietf.org/html/rfc6749#section-10">RFC6749</a>.
See also <a href="https://tools.ietf.org/html/rfc8628#section-5">RFC 8628 section 5</a> for `device` flow.
</dd>
</dl>
</section>
<section>
<h3>Comments</h3>
<p>
Notice that the OAuth 2.0 protocol is not an authentication protocol, however <a
href="https://openid.net/connect/">OpenID</a> defines an authentication layer on top of OAuth 2.0.
</p>
</section>
</section>
</section>
<section>
<h1>Thing Directories</h1>
<p>Directory services are often used in WoT systems to store TDs and provide discovery
services. This is especially useful for devices that need to sleep to conserve battery
life. Rather than watching for and responding to discovery requests themselves, they
can register their TDs with a directory service which can then respond on their behalf.
Directories can either run locally on a gateway (behind a firewall, on the same