-
Notifications
You must be signed in to change notification settings - Fork 9
/
draft-ietf-tokbind-https-18.xml
1351 lines (1207 loc) · 69.1 KB
/
draft-ietf-tokbind-https-18.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="utf-8"?>
<!-- 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 RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC8174 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml">
<!ENTITY RFC2818 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2818.xml">
<!ENTITY RFC3864 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3864.xml">
<!ENTITY RFC4492 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4492.xml">
<!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">
<!ENTITY RFC5246 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml">
<!ENTITY RFC5705 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5705.xml">
<!ENTITY RFC5746 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5746.xml">
<!ENTITY RFC5929 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5929.xml">
<!ENTITY RFC6265 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6265.xml">
<!ENTITY RFC6749 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml">
<!ENTITY RFC7230 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7230.xml">
<!ENTITY RFC7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
<!ENTITY RFC7301 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7301.xml">
<!ENTITY RFC7540 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7540.xml">
<!ENTITY RFC7541 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7541.xml">
<!ENTITY RFC7627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7627.xml">
<!ENTITY OpenID.Core SYSTEM "https://openid.net/bibxml/reference.OpenID.Core.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-ietf-tokbind-https-18" ipr="trust200902">
<!-- category values: std, bcp, info, exp, and historic
ipr values: full3667, noModification3667, noDerivatives3667
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>Token Binding over HTTP</title>
<!-- add 'role="editor"' below for the editors if appropriate -->
<!-- Another author who claims to be an editor -->
<author fullname="Andrei Popov" initials="A."
surname="Popov">
<organization>Microsoft Corp.</organization>
<address>
<postal>
<street></street>
<!-- Reorder these if your country does things differently -->
<city></city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="Magnus Nyström" initials="M."
surname="Nyström">
<organization>Microsoft Corp.</organization>
<address>
<postal>
<street></street>
<!-- Reorder these if your country does things differently -->
<city></city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="Dirk Balfanz" initials="D."
surname="Balfanz" role="editor">
<organization>Google Inc.</organization>
<address>
<postal>
<street></street>
<!-- Reorder these if your country does things differently -->
<city></city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="Nick Harper" initials="N."
surname="Harper">
<organization>Google Inc.</organization>
<address>
<postal>
<street></street>
<!-- Reorder these if your country does things differently -->
<city></city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="Jeff Hodges" initials="J."
surname="Hodges">
<organization>PayPal</organization>
<address>
<postal>
<street></street>
<!-- Reorder these if your country does things differently -->
<city></city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<date year="2018" />
<!-- 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>General</area>
<workgroup>Internet Engineering Task Force</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>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 describes a collection of mechanisms that allow
HTTP servers to cryptographically bind security tokens
(such as cookies and OAuth tokens) to TLS connections.</t>
<t>We describe both first-party and
federated scenarios. In a first-party
scenario, an HTTP server is able to cryptographically bind the security
tokens it issues to a client, and which the client
subsequently returns to the server, to the TLS connection
between the client and server. Such bound security tokens are
protected from misuse since the server can generally detect if they are
replayed inappropriately, e.g., over other TLS connections.</t>
<t>Federated token bindings, on the other hand, allow servers to
cryptographically bind security tokens to a TLS
connection that the client has with
a different server than the one
issuing the token.</t>
<t>This document is a companion document to The Token Binding Protocol.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t><xref target="I-D.ietf-tokbind-protocol">The Token Binding Protocol</xref>
defines a Token Binding ID for a TLS connection between a client
and a server. The Token Binding ID of a TLS connection is constructed using the
public key of a private-public key pair.
The client proves possession of the corresponding private key.
This Token Binding key pair is long-lived.
I.e., subsequent TLS connections
between the same client and server have the same Token Binding
ID, unless specifically reset, e.g., by the user.
When issuing a security token (e.g., an HTTP cookie or an
OAuth token <xref target="RFC6749"/>) to a client, the server can include the Token
Binding ID in the token, thus cryptographically binding the
token to TLS connections between that particular client and
server, and inoculating the token against abuse (re-use,
attempted impersonation, etc.) by attackers.</t>
<t>While the <xref target="I-D.ietf-tokbind-protocol">Token Binding
Protocol</xref> defines a message format for establishing a
Token Binding ID, it does not specify how this message is
embedded in higher-level protocols. The purpose of this
specification is to define how TokenBindingMessages are embedded
in HTTP (both versions <xref target="RFC7230">1.1</xref> and
<xref target="RFC7540">2</xref>). Note that
TokenBindingMessages are only defined if the underlying
transport uses TLS. This means that Token Binding over HTTP is
only defined when the HTTP protocol is layered on top of TLS
(commonly referred to as <xref target="RFC2818">HTTPS</xref>).</t>
<t>HTTP clients establish a Token Binding ID with a server by
including a special HTTP header field in HTTP requests. The HTTP
header field value is a base64url-encoded TokenBindingMessage.</t>
<t>TokenBindingMessages allow clients to establish multiple
Token Binding IDs with the server, by including multiple
TokenBinding structures in the TokenBindingMessage. By default,
a client will establish a provided
Token Binding ID with the server, indicating a Token Binding ID
that the client will persistently use with the server. Under
certain conditions, the client can also include a referred
Token Binding ID in the
TokenBindingMessage, indicating a Token Binding ID that the
client is using with a different
server than the one that the TokenBindingMessage is sent
to. This is useful in federation scenarios.</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 target="RFC8174" />
when, and only when, they appear in all capitals, as shown here.</t>
</section>
</section>
<section title="The Sec-Token-Binding HTTP Request Header Field" anchor="sctn-secTB-header">
<t>Once a client and server have negotiated the Token Binding
Protocol with HTTP/1.1 or HTTP/2 (see <xref
target="I-D.ietf-tokbind-protocol"/> and <xref
target="I-D.ietf-tokbind-negotiation"/>), clients
MUST include a Sec-Token-Binding header field in their HTTP requests, and MUST include only
one such header field per HTTP request. Also,
The Sec-Token-Binding header field MUST NOT
be included in HTTP responses.
The ABNF of the Sec-Token-Binding header field is (in
<xref target="RFC7230"/> style, see also Section 8.3 of <xref target="RFC7231"/>):
</t>
<figure><artwork><![CDATA[
Sec-Token-Binding = EncodedTokenBindingMessage
]]></artwork></figure>
<t>The header field name is Sec-Token-Binding and its single
value, EncodedTokenBindingMessage, is a base64url encoding of a single TokenBindingMessage,
as defined in <xref target="I-D.ietf-tokbind-protocol"/>. The base64url encoding uses the URL- and filename-safe
character set described in Section 5 of <xref target="RFC4648"/>, with all trailing padding
characters '=' omitted and without the inclusion of any line breaks, whitespace, or other
additional characters.</t>
<t>For example:</t>
<figure><artwork><![CDATA[
Sec-Token-Binding: AIkAAgBBQFzK4_bhAqLDwRQxqJWte33d7hZ0hZWHwk-miKPg4E\
9fcgs7gBPoz-9RfuDfN9WCw6keHEw1ZPQMGs9CxpuHm-YAQM_j\
aOwwej6a-cQBGU7CJpUHOvXG4VvjNq8jDsvta9Y8_bPEPj25Gg\
mKiPjhJEtZA6mJ_9SNifLvVBTi7fR9wSAAAA
]]></artwork></figure>
<t>(Note that the backslashes and line breaks are provided to ease readability,
they are not part of the actual encoded message.)</t>
<t>If the server receives more than one Sec-Token-Binding header field
in an HTTP request, then the server MUST reject the message with a
400 (Bad Request) HTTP status code. Additionally, the Sec-Token-Binding
header field:
<list>
<t>SHOULD NOT be stored by origin servers on PUT requests,</t>
<t>MAY be listed by a server in a Vary response header field, and,</t>
<t>MUST NOT be used in HTTP trailers.</t>
</list>
</t>
<t>The TokenBindingMessage MUST contain exactly one TokenBinding structure
with TokenBindingType of provided_token_binding, which MUST be signed
with the Token Binding private key used by the client for connections
between itself and the server that the HTTP request is sent to
(clients use different Token Binding key pairs for different
servers, see <xref target="sctn-keypair-scope"/> below).
The Token Binding ID established by this TokenBinding
is called a Provided Token Binding ID.</t>
<t>The TokenBindingMessage MAY also contain exactly one TokenBinding structure
with TokenBindingType of referred_token_binding, as specified in
<xref target="sctn-http-redir"/>. In addition to the latter,
or rather than the latter, the TokenBindingMessage
MAY contain other TokenBinding structures. This is use case-specific,
and such use cases are outside the scope of this
specification.</t>
<t>A TokenBindingMessage is validated by the server as described in Section
4.2 ("Server Processing Rules") of <xref target="I-D.ietf-tokbind-protocol"/>.
If validation fails and a Token Binding is rejected, any associated bound
tokens MUST also be rejected by the server. HTTP requests containing invalid
tokens MUST be rejected. In this case, the server application MAY return HTTP
status code 400 (Bad Request) or proceed with an application-specific invalid
token response (e.g., directing the client to re-authenticate and present a
different token), or terminate the connection.</t>
<t>In HTTP/2, the client SHOULD use <xref
target="RFC7541">Header
Compression</xref> to avoid the overhead of repeating the same
header field in subsequent HTTP requests.</t>
<section title="HTTPS Token Binding Key Pair Scoping"
anchor="sctn-keypair-scope">
<t>HTTPS is used in conjunction with various application
protocols and application contexts, in various ways.
For example, general-purpose Web browsing is one such HTTP-based
application context. Within that context, HTTP cookies
<xref target="RFC6265"/> are typically utilized for state management,
including client authentication.
A related, though distinct, example of other HTTP-based
application contexts is where OAuth tokens <xref target="RFC6749"/>
are utilized to manage
authorization for third-party application access to resources.
The token scoping rules of these two
examples can differ: the scoping rules for cookies are concisely
specified in <xref target="RFC6265"/>, whereas OAuth is
a framework and defines various
token types with various scopings, some of which are determined by
the encompassing application.
</t>
<t>The scoping of Token Binding key pairs generated by Web browsers for the purpose of
binding HTTP cookies MUST be no wider than the granularity of a "registered domain"
(also known as "effective top-level domain + 1", or "eTLD+1"). An origin's "registered domain"
is the origin's host's public suffix plus the label to its left, with the term
"public suffix" being defined in a note in Section 5.3 of
<xref target="RFC6265"/> as "a domain that is controlled by a public registry".
For example, for "https://www.example.com", the public suffix (eTLD) is "com", and the
registered domain (eTLD+1) is "example.com". User agents SHOULD use an
up-to-date public suffix list, such as the one maintained by Mozilla <xref target="PSL"/>.</t>
<t>This means that in practice the scope of a Token Binding key pair is no larger
than the scope of a cookie allowed by a Web browser. If a Web browser restricts
cookies to a narrower scope than registered domains, the scope of Token Binding
key pairs MAY also be more narrow. This applies to the use
of Token Binding key pairs in first-party use cases, as well as in federation use cases defined
in this specification (<xref target="federation"/>).</t>
<t>Key pairs used to bind other application
tokens, such as OAuth tokens or OpenID Connect ID Tokens, SHOULD
adhere to the above eTLD+1
scoping requirement for those tokens being employed in first-party
or federation scenarios. Applications other than Web
browsers MAY use different key pair scoping rules. See also <xref
target="sctn-priv-tbkey-scoping"/>, below.</t>
<t>Scoping rules for other HTTP-based application contexts are outside the scope of
this specification.</t>
</section>
</section>
<section title="TLS Renegotiation">
<t>Token Binding over HTTP/1.1 <xref target="RFC7230"/> can be performed in combination with
TLS renegotiation. In this case, renegotiation MUST only occur between a client's HTTP
request and the server's response, the client MUST NOT send any pipelined requests, and the
client MUST NOT initiate renegotiation. (I.e., the client may only send a renegotiation
ClientHello in response to the server's HelloRequest.) These conditions ensure that both the
client and the server can clearly identify which TLS Exported Keying Material value
<xref target="RFC5705" /> to use when generating or verifying the TokenBindingMessage. This
also prevents a TokenBindingMessage from being split across TLS renegotiation boundaries.
(I.e., due to TLS message fragmentation - see Section 6.2.1 of <xref target="RFC5246"/>.)</t>
</section>
<section title="First-Party Use Cases">
<t>In a first-party use case (also known as a
"same-site" use case), an HTTP server issues a security token
such as a cookie (or similar) to a client, and expects the client to return
the security token at a later time, e.g., in order
to authenticate. Binding the security token to the TLS connection between
client and server protects the security token from misuse,
since the server can detect if the security token is
replayed inappropriately, e.g., over other TLS connections.</t>
<t>See Section 5 of <xref target="I-D.ietf-tokbind-protocol"/> for
general guidance regarding binding of security tokens and their
subsequent validation.</t>
</section>
<section title="Federation Use Cases" anchor="federation">
<section title="Introduction">
<t>For privacy reasons, clients use different Token Binding key pairs to
establish Provided Token Binding IDs with different
servers. As a result, a server cannot bind a security token
(such as an OAuth token or an OpenID Connect ID Token <xref target="OpenID.Core"/>)
to a TLS connection that the client has with a different
server. This is, however, a common requirement in federation
scenarios: For example, an Identity Provider may wish to issue
an identity token to a client and cryptographically bind that
token to the TLS connection between the client and a Relying
Party.</t>
<t>In this section, we describe mechanisms to achieve this. The
common idea among these mechanisms is that a server (called
the Token Consumer in this
document) signals to the client that it should reveal the Provided
Token Binding ID that is used between the client and itself
to another server (called the Token
Provider in this document). Also common across the
mechanisms is how the Token Binding ID is revealed to the
Token Provider: The client uses the <xref
target="I-D.ietf-tokbind-protocol">Token Binding Protocol</xref>, and
includes a TokenBinding structure in the Sec-Token-Binding HTTP
header field defined above. What differs between the various
mechanisms is how the Token
Consumer signals to the client that it should reveal the Token Binding ID
to the Token Provider. Below, we specify one such mechanism, which is
suitable for redirect-based interactions between Token Consumers and
Token Providers.</t>
<figure><artwork><![CDATA[
Client Token Consumer Token Provider
+--------+ +----+ +-----+
| Client | | TC | | TP |
+--------+ +----+ +-----+
| | |
| | |
| | |
| Client interacts w/TC | |
| using TokenBindingID TBID1: | |
| TBMSG[[provided_token_binding,| |
| TBID1, signature]] | |
|------------------------------>| |
| | |
| Client interacts w/TP |
| using TokenBindingID TBID2: |
| TBMSG[[provided_token_binding, |
| TBID2, signature]] |
|----------------------------------------------------->|
| |
| | |
| TC signals permission to | |
| reveal TBID1 to TP | |
|<------------------------------| |
| | |
| |
| Client interacts w/TP |
| using TokenBindingID TBID1 and TBID2: |
| TBMSG[[provided_token_binding, |
| TBID2, signature], |
| [referred_token_binding, |
| TBID1, signature]] |
|----------------------------------------------------->|
| |
| | |
| | |
]]></artwork></figure>
</section>
<section title="Overview">
<t>In a Federated Sign-On protocol, an Identity Provider issues
an identity token to a client, which sends the identity token
to a Relying Party to authenticate itself. Examples of this
include OpenID Connect (in which the identity token is called an "ID
Token") and <xref target="OASIS.saml-core-2.0-os">SAML</xref>
(in which the identity token is a SAML assertion).</t>
<t>To better protect the security of the identity token, the
Identity Provider may wish to bind the identity token to the TLS
connection between the client and the Relying Party, thus
ensuring that only said client can use the identity token. The
Relying Party will compare the Token Binding ID (or a cryptographic
hash of it) in the identity token with the Token Binding ID (or a hash
thereof) of the TLS connection between this Relying Party and the client.</t>
<t>This is an example of a federation scenario, which more
generally can be described as follows:
<list style="symbols">
<t>A Token Consumer causes the client to issue a token request
to the Token Provider. The goal is for the client to obtain a
token and then use it with the Token Consumer.</t>
<t>The client delivers the token request to the Token
Provider.</t>
<t>The Token Provider issues the token. The token is issued
for the specific Token Consumer who requested it (thus
preventing malicious Token Consumers from using tokens with
other Token Consumers). The token is, however, typically a
bearer token, meaning that any client can use it with the
Token Consumer, not just the client to which it was
issued.</t>
<t>Therefore, in the previous step, the Token Provider may
want to include in the token the Token Binding ID (or a
cryptographic hash of it) that the client
uses when communicating with the Token Consumer, thus
binding the token to the client's Token Binding
key pair. The client
proves possession of the private key when communicating with
the Token Consumer through the <xref target="I-D.ietf-tokbind-protocol">Token
Binding Protocol</xref>, and uses the corresponding public key of this
key pair as a component of the Token Binding ID. Comparing the Token Binding ID from the
token to the Token Binding ID established with the client allows the Token
Consumer to verify that the token was sent to it by the legitimate
client.</t>
<t>To allow the Token Provider to include the Token Binding ID in
the token, the Token Binding ID between client and Token Consumer must
therefore be communicated to the Token Provider along with the token
request. Communicating a Token Binding ID involves proving possession of a
private key and is described in the <xref target="I-D.ietf-tokbind-protocol">Token
Binding Protocol</xref>.</t>
</list>
</t>
<t>The client will perform this last operation only if the Token
Consumer requests the client to do so.</t>
<t>Below, we specify how Token Consumers can signal this request in
redirect-based federation protocols. Note that this assumes that the federated
sign-on flow starts at the Token Consumer, or at the very least, includes a redirect
from the Token Consumer to the Token Provider. It is outside the scope of this
document to specify similar mechanisms for flows that do not include such redirects.</t>
</section>
<section title="HTTP Redirects" anchor="sctn-http-redir">
<t>When a Token Consumer redirects the client to a Token Provider as a means to deliver the token
request, it SHOULD include an Include-Referred-Token-Binding-ID HTTP response header field in its
HTTP response. The ABNF of the Include-Referred-Token-Binding-ID header is (in <xref
target="RFC7230"/> style, see also Section 8.3 of <xref target="RFC7231"/>):</t>
<figure><artwork><![CDATA[
Include-Referred-Token-Binding-ID = "true"
]]></artwork></figure>
<t>Where the header field name is "Include-Referred-Token-Binding-ID", and the
field-value of "true" is case-insensitive. For example:</t>
<figure><artwork><![CDATA[
Include-Referred-Token-Binding-ID: true
]]></artwork></figure>
<t>Including this response header field signals to the client that it
should reveal, to the Token Provider, the Token Binding ID used between itself and
the Token Consumer. In the absence of this
response header field, the client will not disclose any information
about the Token Binding used between the client and the Token
Consumer to the Token Provider.</t>
<t>As illustrated in <xref target="sctn-fed-example"/>, when a client
receives this header field, it should take the TokenBindingID
of the provided TokenBinding from the referrer and create a referred TokenBinding
with it to include in the TokenBindingMessage on the redirect request. In other
words, the Token Binding message in the redirect request to the Token Provider
now includes one provided binding and one referred binding, the latter constructed
from the binding between the client and the Token Consumer.</t>
<t>When a client receives the Include-Referred-Token-Binding-ID header, it includes the
referred token binding even if both the Token Provider and the Token Consumer fall
under the same eTLD+1 and the provided and referred token binding IDs are the same.</t>
<t>The referred token binding is sent only on the initial request resulting from the
HTTP response that included the Include-Referred-Token-Binding-ID header.
Should the response to that initial request be a further redirect, the original referred
token binding is no longer included in subsequent requests. (A new referred token binding may be
included if the redirecting endpoint itself responded with a Include-Referred-Token-Binding-ID
response header.)</t>
<t>If the Include-Referred-Token-Binding-ID header field is received in response to a
request that did not include the Token-Binding header field, the client MUST ignore
the Include-Referred-Token-Binding-ID header field.</t>
<t>This header field has only meaning if the HTTP status code is a redirection code (300-399),
and MUST be ignored by the client for any other status
codes. If the client supports the Token Binding Protocol, and
has negotiated the Token Binding Protocol with both the Token
Consumer and the Token Provider, it already sends the
Sec-Token-Binding header field to the Token Provider with each HTTP
request (as described in <xref target="sctn-secTB-header"/> above).</t>
<t>The TokenBindingMessage included in the redirect request to the Token Provider SHOULD contain a TokenBinding with
TokenBindingType referred_token_binding. If included, this
TokenBinding MUST be signed
with the Token Binding private key used by the client for connections
between itself and the Token Consumer (more specifically, the
server that issued the Include-Referred-Token-Binding-ID
response header field). The Token Binding ID established by this
TokenBinding is called a Referred Token
Binding ID.</t>
<t>As described above, the TokenBindingMessage MUST
additionally contain a Provided Token Binding ID, i.e., a
TokenBinding structure with TokenBindingType of
provided_token_binding, which MUST be signed with the Token
Binding private key used by the client for connections between itself
and the Token Provider (more specifically, the server that
the token request is being sent to).
</t>
<t>If, for some deployment-specific reason, the initial
Token Provider ("TP1") needs to redirect the
client to another Token Provider ("TP2"), rather than
directly back to the Token Consumer, it can be
accommodated using the header fields defined in this
specification in the following fashion ("the
redirect-chain approach"):
<list>
<t>Initially, the client is redirected to TP1 by the Token Consumer ("TC"), as described above.
Upon receiving the client's request, containing a TokenBindingMessage which contains both provided
and referred TokenBindings (for TP1 and TC, respectively), TP1 responds to the client with a
redirect response containing the Include-Referred-Token-Binding-ID header field and directing the
client to send a request to TP2. This causes the client to follow the same pattern and send a
request containing a TokenBindingMessage which contains both provided and referred TokenBindings
(for TP2 and TP1, respectively) to TP2. Note that this pattern can continue to further Token
Providers. In this case, TP2 issues a security token, bound to the client's TokenBinding with TP1,
and sends a redirect response to the client pointing to TP1. TP1 in turn constructs a security
token for the Token Consumer, bound to the TC's referred TokenBinding which had been conveyed
earlier, and sends a redirect response pointing to the TC, containing the bound security token, to
the client.</t>
</list>
The above is intended as only a non-normative example. Details are specific to deployment
contexts. Other approaches are possible, but are outside the scope of this specification.</t>
</section>
<section title="Negotiated Key Parameters">
<t>The <xref target="I-D.ietf-tokbind-negotiation">TLS Extension
for Token Binding Protocol Negotiation</xref> allows the server and
client to negotiate the parameters (signature algorithm, length)
of the Token Binding key pair. It is possible that the Token
Binding ID used between the client and the Token Consumer, and
the Token Binding ID used between the client and Token Provider,
use different key parameters. The client MUST use the
key parameters negotiated with the Token Consumer in the
referred_token_binding TokenBinding of the TokenBindingMessage,
even if those key parameters are different from the ones
negotiated with the server that the header field is sent to.</t>
<t>Token Providers SHOULD support all the Token Binding key parameters
specified in <xref target="I-D.ietf-tokbind-protocol"/>.
If a token provider does not support the key parameters
specified in the referred_token_binding TokenBinding in the
TokenBindingMessage, it MUST NOT issue a bound token.</t>
</section>
<section title="Federation Example" anchor="sctn-fed-example">
<t> The diagram below shows a
typical HTTP Redirect-based Web Browser SSO Profile
(no artifact, no callbacks), featuring binding of,
e.g., a TLS Token Binding ID into an OpenID Connect ID Token.
</t>
<texttable>
<preamble>Legend:</preamble>
<ttcol></ttcol><ttcol></ttcol>
<c>EKM:</c> <c>TLS Exported Keying Material [RFC5705]</c>
<c>{EKMn}Ksm:</c> <c>EKM for server "n", signed by private key of TBID "m",
where "n" must represent server receiving the ETBMSG.
If a conveyed TB's type is provided_token_binding, then
m = n, else if TB's type is referred_token_binding, then
m != n. E.g., see step 1b in diagram below.</c>
<c>ETBMSG:</c> <c>"Sec-Token-Binding" HTTP header field conveying an
EncodedTokenBindingMessage, in turn conveying
TokenBinding (TB)struct(s), e.g.:
ETBMSG[[TB]] or ETBMSG[[TB1],[TB2]]</c>
<c>ID Token:</c> <c>the ID Token in OpenID Connect, it is the semantic equivalent
of a SAML "authentication assertion". "ID Token w/TBIDn"
denotes a "token bound" ID Token containing TBIDn.</c>
<c>Ks & Kp:</c> <c>private (aka secret) key, and public key, respectively,
of client-side Token Binding key pair</c>
<c>OIDC:</c> <c>OpenID Connect</c>
<c>TB:</c> <c>TokenBinding struct containing signed EKM, TBID, and
TB type, e.g.: [{EKM1}Ks1,TBID1,provided_token_binding]</c>
<c>TBIDn:</c> <c>Token Binding ID for client and server n's token-bound
TLS association. TBIDn contains Kpn.</c>
</texttable>
<figure><artwork><![CDATA[
Client, Token Consumer, Token Provider,
aka: aka: aka:
User Agent OpenID Client, OpenID Provider,
OIDC Relying Party, OIDC Provider,
SAML Relying Party SAML Identity Provider
[ server "1" ] [ server "2" ]
+--------+ +----+ +-----+
| Client | | TC | | TP |
+--------+ +----+ +-----+
| | |
| | |
| | |
| 0. Client interacts w/TC | |
| over HTTPS, establishes Ks1 & Kp1, TBID1 |
| ETBMSG[[{EKM1}Ks1,TBID1,provided_token_binding]] |
|------------------------------>| |
| | |
| | |
| | |
| 1a. OIDC ID Token request, aka| |
| "Authentication Request", conveyed with |
| HTTP response header field of: |
| Include-Referred-Token-Binding-ID:true |
| any security-relevant cookies | |
| should contain TBID1 | |
+<- - - - - - - - - - - - - - - - | |
. | (redirect to TP via 301, 302, | |
. | 303, 307, or 308) | |
. | | |
+------------------------------------------------------->|
| 1b. opens HTTPS w/TP, |
| establishes Ks2, Kp2, TBID2; |
| sends GET or POST with |
| ETBMSG[[{EKM2}Ks2,TBID2,provided_token_binding], |
| [{EKM2}Ks1,TBID1,referred_token_binding]] |
| as well as the ID Token request |
| | |
| | |
| | |
| 2. user authentication (if applicable, |
| methods vary, particulars are out of scope) |
|<====================================================>|
| (TP generates ID Token for TC containing TBID1, may |
| also set cookie(s) containing TBID2 and/or TBID1, |
| details vary, particulars are out of scope) |
| | |
| | |
| | |
| 3a. ID Token containing Kp1, issued for TC, |
| conveyed via OIDC "Authentication Response" |
+<- - - - - - - - - - - - - - - - - - - - - - - - - - - -|
. | (redirect to TC) | |
. | | |
. | | |
+-------------------------------->| |
| 3b. HTTPS GET or POST with |
| ETBMSG[[{EKM1}Ks1,TBID1,provided_token_binding]] |
| conveying Authn Response containing |
| ID Token w/TBID1, issued for TC |
| | |
| | |
| | |
| 4. user is signed-on, any security-relevant cookie(s)|
| that are set SHOULD contain TBID1 |
|<------------------------------| |
| | |
| | |
]]></artwork></figure>
</section>
</section>
<section title="Implementation Considerations" anchor="impl-cons">
<t>
HTTPS-based applications may have multi-party use
cases other than, or in addition to, the HTTP redirect-based
signaling-and-conveyance of referred token bindings, as
presented above in <xref target="sctn-http-redir"/>.
</t>
<t>
Thus, Token Binding implementations should provide APIs for such applications to generate
Token Binding messages containing Token Binding IDs of various application-specified Token
Binding types, to be conveyed by the Sec-Token-Binding header field.
</t>
<t>
However, Token Binding implementations MUST only convey Token Binding IDs to servers if
signaled to do so by an application. For example, a server can return an
Include-Referred-Token-Binding-ID HTTP response header field to an application, which then
signals to the Token Binding implementation that it intends to convey the Token Binding ID
used with this server to another server. Other signaling mechanisms are possible, and are
specific to the application layer protocol, but are outside the scope of this
specification.
<list style="hanging" hangIndent="7">
<t hangText="NOTE:">
See <xref target="privacy-cons"/>
("<xref target="privacy-cons" format="title"/>"),
for privacy guidance regarding the use of this functionality.
</t>
</list>
</t>
</section>
<section anchor="Security" title="Security Considerations">
<section title="Security Token Replay">
<t>The goal of the Federated Token Binding mechanisms is to
prevent attackers from exporting and replaying tokens used in
protocols between the client and Token Consumer, thereby
impersonating legitimate users and gaining access to protected
resources. Although bound tokens can still be replayed by any malware
present in clients (which may be undetectable by a server),
in order to export bound tokens to
other machines and successfully replay them, attackers also
need to export the corresponding Token Binding private keys. Token
Binding private keys are therefore high-value assets and SHOULD
be strongly protected, ideally by generating them in a hardware
security module that prevents key export.</t>
<t>This consideration is a special case of the Security Token Replay security
consideration laid out in the <xref target="I-D.ietf-tokbind-protocol">The
Token Binding Protocol</xref> specification.
</t>
</section>
<section title="Sensitivity of the Sec-Token-Binding Header">
<t>
The purpose of the Token Binding protocol is to convince the server
that the client that initiated the TLS connection controls a certain
key pair. For the server to correctly draw this conclusion after
processing the Sec-Token-Binding header field, certain secrecy and integrity
requirements must be met.
</t>
<t>
For example, the client's Token Binding private key must be kept
secret by the client. If the private key is not secret, then another
actor in the system could create a valid Token Binding header field,
impersonating the client. This can render the main purpose of the
protocol - to bind bearer tokens to certain clients - moot. Consider,
for example, an attacker who obtained (perhaps through a network
intrusion) an authentication cookie that a client uses with a certain
server. Consider further that the server bound that cookie to the
client's Token Binding ID precisely to thwart misuse of the cookie. If the
attacker were to come into possession of the client's private key, he
could then establish a TLS connection with the server and craft a
Sec-Token-Binding header field that matches the binding present in the cookie,
thus successfully authenticating as the client, and gaining access to
the client's data at the server. The Token Binding protocol, in this
case, did not successfully bind the cookie to the client.
</t>
<t>
Likewise, we need integrity protection of the Sec-Token-Binding header field. A
client should not be tricked into sending a Sec-Token-Binding header field to a
server that contains Token Binding messages about key pairs that the
client does not control. Consider an attacker A that somehow has
knowledge of the exported keying material (EKM) for a TLS connection
between a client C and a server S. (While that is somewhat unlikely,
it is also not entirely out of the question, since the client might
not treat the EKM as a secret - after all, a pre-image-resistant hash
function has been applied to the TLS master secret, making it
impossible for someone knowing the EKM to recover the TLS master
secret. Such considerations might lead some clients to not treat the
EKM as a secret.) Such an attacker A could craft a Sec-Token-Binding
header field with A's key pair over C's EKM. If the attacker could now
trick C into sending such a header field to S, it would appear to S as if C
controls a certain key pair, when in fact it does not (the attacker A
controls the key pair).
</t>
<t>
If A has a pre-existing relationship with S (perhaps has an account
on S), it now appears to the server S as if A is connecting to it,
even though it is really C. (If the server S does not simply use Token
Binding IDs to identify clients, but also uses bound authentication
cookies, then A would also have to trick C into sending one of A's
cookies to S, which it can do through a variety of means - inserting
cookies through Javascript APIs, setting cookies through
related-domain attacks, etc.) In other words, A tricked C into
logging into A's account on S. This could lead to a loss of privacy
for C, since A presumably has some other way to also access the
account, and can thus indirectly observe C's behavior (for example,
if S has a feature that lets account holders see their activity
history on S).
</t>
<t>
Therefore, we need to protect the integrity of the Sec-Token-Binding
header field. One eTLD+1 should not be able to set the Sec-Token-Binding header field
(through a DOM API or otherwise) that the User Agent uses with
another eTLD+1. Employing the "Sec-" header field prefix helps to meet this
requirement by denoting the header field name to be a "forbidden header name",
see <xref target="fetch-spec"/>.
</t>
</section>
<section title="Securing Federated Sign-On Protocols">
<t>
As explained above, in a federated sign-in scenario, a client will prove possession of two
different Token Binding private keys to a Token Provider: One private key corresponds to
the "provided" Token Binding ID (which the client normally uses with the Token Provider),
and the other is the Token Binding private key corresponding to the "referred" Token
Binding ID (which the client normally uses with the Token Consumer). The Token Provider is
expected to issue a token that is bound to the referred Token Binding ID.
</t>
<t>
Both proofs (that of the provided Token Binding private key and that of the
referred Token Binding private key) are necessary. To show this, consider the
following scenario:
<list style="symbols">
<t>
The client has an authentication token with the Token Provider
that is bound to the client's Token Binding ID used with that
Token Provider.
</t>
<t>
The client wants to establish a secure (i.e., free of
men-in-the-middle) authenticated session with the Token Consumer,
but has not done so yet (in other words, we are about to run the
federated sign-on protocol).
</t>
<t>
A man-in-the-middle is allowed to intercept the connection
between client and Token Consumer or between Client and Token
Provider (or both).
</t>
</list>
The goal is to detect the presence of the man-in-the-middle in these
scenarios.
</t>
<t>
First, consider a man-in-the-middle between the client and the Token
Provider. Recall that we assume that the client possesses a bound
authentication token (e.g., cookie) for the Token Provider. The
man-in-the-middle can intercept and modify any message sent by the
client to the Token Provider, and any message sent by the Token
Provider to the client. (This means, among other things, that the
man-in-the-middle controls the Javascript running at the client in
the origin of the Token Provider.) It is not, however, in possession
of the client's Token Binding private key. Therefore, it can either choose to
replace the Token Binding ID in requests from the client to the
Token Provider, and create a Sec-Token-Binding header field that matches the
TLS connection between the man-in-the-middle and the Token Provider,
or it can choose to leave the Sec-Token-Binding header field unchanged. If it
chooses the latter, the signature in the Token Binding message
(created by the original client on the exported keying material (EKM)
for the connection between client and man-in-the-middle) will not
match a signature on the EKM between man-in-the-middle and the Token Provider. If it
chooses the former (and creates its own signature, using its own Token
Binding private key, over the EKM for the connection between itself, the
man-in-the-middle, and Token Provider), then the Token Binding message