1
2
3
4
5
6
7Internet Engineering Task Force (IETF) E. Rescorla
8Request for Comments: 8446 Mozilla
9Obsoletes: 5077, 5246, 6961 August 2018
10Updates: 5705, 6066
11Category: Standards Track
12ISSN: 2070-1721
13
14
15 The Transport Layer Security (TLS) Protocol Version 1.3
16
17Abstract
18
19 This document specifies version 1.3 of the Transport Layer Security
20 (TLS) protocol. TLS allows client/server applications to communicate
21 over the Internet in a way that is designed to prevent eavesdropping,
22 tampering, and message forgery.
23
24 This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077,
25 5246, and 6961. This document also specifies new requirements for
26 TLS 1.2 implementations.
27
28Status of This Memo
29
30 This is an Internet Standards Track document.
31
32 This document is a product of the Internet Engineering Task Force
33 (IETF). It represents the consensus of the IETF community. It has
34 received public review and has been approved for publication by the
35 Internet Engineering Steering Group (IESG). Further information on
36 Internet Standards is available in Section 2 of RFC 7841.
37
38 Information about the current status of this document, any errata,
39 and how to provide feedback on it may be obtained at
40 https://www.rfc-editor.org/info/rfc8446.
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58Rescorla Standards Track [Page 1]
59
60RFC 8446 TLS August 2018
61
62
63Copyright Notice
64
65 Copyright (c) 2018 IETF Trust and the persons identified as the
66 document authors. All rights reserved.
67
68 This document is subject to BCP 78 and the IETF Trust's Legal
69 Provisions Relating to IETF Documents
70 (https://trustee.ietf.org/license-info) in effect on the date of
71 publication of this document. Please review these documents
72 carefully, as they describe your rights and restrictions with respect
73 to this document. Code Components extracted from this document must
74 include Simplified BSD License text as described in Section 4.e of
75 the Trust Legal Provisions and are provided without warranty as
76 described in the Simplified BSD License.
77
78 This document may contain material from IETF Documents or IETF
79 Contributions published or made publicly available before November
80 10, 2008. The person(s) controlling the copyright in some of this
81 material may not have granted the IETF Trust the right to allow
82 modifications of such material outside the IETF Standards Process.
83 Without obtaining an adequate license from the person(s) controlling
84 the copyright in such materials, this document may not be modified
85 outside the IETF Standards Process, and derivative works of it may
86 not be created outside the IETF Standards Process, except to format
87 it for publication as an RFC or to translate it into languages other
88 than English.
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
114Rescorla Standards Track [Page 2]
115
116RFC 8446 TLS August 2018
117
118
119Table of Contents
120
121 1. Introduction ....................................................6
122 1.1. Conventions and Terminology ................................7
123 1.2. Major Differences from TLS 1.2 .............................8
124 1.3. Updates Affecting TLS 1.2 ..................................9
125 2. Protocol Overview ..............................................10
126 2.1. Incorrect DHE Share .......................................14
127 2.2. Resumption and Pre-Shared Key (PSK) .......................15
128 2.3. 0-RTT Data ................................................17
129 3. Presentation Language ..........................................19
130 3.1. Basic Block Size ..........................................19
131 3.2. Miscellaneous .............................................20
132 3.3. Numbers ...................................................20
133 3.4. Vectors ...................................................20
134 3.5. Enumerateds ...............................................21
135 3.6. Constructed Types .........................................22
136 3.7. Constants .................................................23
137 3.8. Variants ..................................................23
138 4. Handshake Protocol .............................................24
139 4.1. Key Exchange Messages .....................................25
140 4.1.1. Cryptographic Negotiation ..........................26
141 4.1.2. Client Hello .......................................27
142 4.1.3. Server Hello .......................................31
143 4.1.4. Hello Retry Request ................................33
144 4.2. Extensions ................................................35
145 4.2.1. Supported Versions .................................39
146 4.2.2. Cookie .............................................40
147 4.2.3. Signature Algorithms ...............................41
148 4.2.4. Certificate Authorities ............................45
149 4.2.5. OID Filters ........................................45
150 4.2.6. Post-Handshake Client Authentication ...............47
151 4.2.7. Supported Groups ...................................47
152 4.2.8. Key Share ..........................................48
153 4.2.9. Pre-Shared Key Exchange Modes ......................51
154 4.2.10. Early Data Indication .............................52
155 4.2.11. Pre-Shared Key Extension ..........................55
156 4.3. Server Parameters .........................................59
157 4.3.1. Encrypted Extensions ...............................60
158 4.3.2. Certificate Request ................................60
159 4.4. Authentication Messages ...................................61
160 4.4.1. The Transcript Hash ................................63
161 4.4.2. Certificate ........................................64
162 4.4.3. Certificate Verify .................................69
163 4.4.4. Finished ...........................................71
164 4.5. End of Early Data .........................................72
165
166
167
168
169
170Rescorla Standards Track [Page 3]
171
172RFC 8446 TLS August 2018
173
174
175 4.6. Post-Handshake Messages ...................................73
176 4.6.1. New Session Ticket Message .........................73
177 4.6.2. Post-Handshake Authentication ......................75
178 4.6.3. Key and Initialization Vector Update ...............76
179 5. Record Protocol ................................................77
180 5.1. Record Layer ..............................................78
181 5.2. Record Payload Protection .................................80
182 5.3. Per-Record Nonce ..........................................82
183 5.4. Record Padding ............................................83
184 5.5. Limits on Key Usage .......................................84
185 6. Alert Protocol .................................................85
186 6.1. Closure Alerts ............................................87
187 6.2. Error Alerts ..............................................88
188 7. Cryptographic Computations .....................................90
189 7.1. Key Schedule ..............................................91
190 7.2. Updating Traffic Secrets ..................................94
191 7.3. Traffic Key Calculation ...................................95
192 7.4. (EC)DHE Shared Secret Calculation .........................95
193 7.4.1. Finite Field Diffie-Hellman ........................95
194 7.4.2. Elliptic Curve Diffie-Hellman ......................96
195 7.5. Exporters .................................................97
196 8. 0-RTT and Anti-Replay ..........................................98
197 8.1. Single-Use Tickets ........................................99
198 8.2. Client Hello Recording ....................................99
199 8.3. Freshness Checks .........................................101
200 9. Compliance Requirements .......................................102
201 9.1. Mandatory-to-Implement Cipher Suites .....................102
202 9.2. Mandatory-to-Implement Extensions ........................103
203 9.3. Protocol Invariants ......................................104
204 10. Security Considerations ......................................106
205 11. IANA Considerations ..........................................106
206 12. References ...................................................109
207 12.1. Normative References ....................................109
208 12.2. Informative References ..................................112
209 Appendix A. State Machine ........................................120
210 A.1. Client ....................................................120
211 A.2. Server ....................................................121
212 Appendix B. Protocol Data Structures and Constant Values .........122
213 B.1. Record Layer ..............................................122
214 B.2. Alert Messages ............................................123
215 B.3. Handshake Protocol ........................................124
216 B.3.1. Key Exchange Messages .................................125
217 B.3.2. Server Parameters Messages ............................131
218 B.3.3. Authentication Messages ...............................132
219 B.3.4. Ticket Establishment ..................................132
220 B.3.5. Updating Keys .........................................133
221 B.4. Cipher Suites .............................................133
222
223
224
225
226Rescorla Standards Track [Page 4]
227
228RFC 8446 TLS August 2018
229
230
231 Appendix C. Implementation Notes .................................134
232 C.1. Random Number Generation and Seeding ......................134
233 C.2. Certificates and Authentication ...........................135
234 C.3. Implementation Pitfalls ...................................135
235 C.4. Client Tracking Prevention ................................137
236 C.5. Unauthenticated Operation .................................137
237 Appendix D. Backward Compatibility ...............................138
238 D.1. Negotiating with an Older Server ..........................139
239 D.2. Negotiating with an Older Client ..........................139
240 D.3. 0-RTT Backward Compatibility ..............................140
241 D.4. Middlebox Compatibility Mode ..............................140
242 D.5. Security Restrictions Related to Backward Compatibility ...141
243 Appendix E. Overview of Security Properties ......................142
244 E.1. Handshake .................................................142
245 E.1.1. Key Derivation and HKDF ...............................145
246 E.1.2. Client Authentication .................................146
247 E.1.3. 0-RTT .................................................146
248 E.1.4. Exporter Independence .................................146
249 E.1.5. Post-Compromise Security ..............................146
250 E.1.6. External References ...................................147
251 E.2. Record Layer ..............................................147
252 E.2.1. External References ...................................148
253 E.3. Traffic Analysis ..........................................148
254 E.4. Side-Channel Attacks ......................................149
255 E.5. Replay Attacks on 0-RTT ...................................150
256 E.5.1. Replay and Exporters ..................................151
257 E.6. PSK Identity Exposure .....................................152
258 E.7. Sharing PSKs ..............................................152
259 E.8. Attacks on Static RSA .....................................152
260 Contributors .....................................................153
261 Author's Address .................................................160
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282Rescorla Standards Track [Page 5]
283
284RFC 8446 TLS August 2018
285
286
2871. Introduction
288
289 The primary goal of TLS is to provide a secure channel between two
290 communicating peers; the only requirement from the underlying
291 transport is a reliable, in-order data stream. Specifically, the
292 secure channel should provide the following properties:
293
294 - Authentication: The server side of the channel is always
295 authenticated; the client side is optionally authenticated.
296 Authentication can happen via asymmetric cryptography (e.g., RSA
297 [RSA], the Elliptic Curve Digital Signature Algorithm (ECDSA)
298 [ECDSA], or the Edwards-Curve Digital Signature Algorithm (EdDSA)
299 [RFC8032]) or a symmetric pre-shared key (PSK).
300
301 - Confidentiality: Data sent over the channel after establishment is
302 only visible to the endpoints. TLS does not hide the length of
303 the data it transmits, though endpoints are able to pad TLS
304 records in order to obscure lengths and improve protection against
305 traffic analysis techniques.
306
307 - Integrity: Data sent over the channel after establishment cannot
308 be modified by attackers without detection.
309
310 These properties should be true even in the face of an attacker who
311 has complete control of the network, as described in [RFC3552]. See
312 Appendix E for a more complete statement of the relevant security
313 properties.
314
315 TLS consists of two primary components:
316
317 - A handshake protocol (Section 4) that authenticates the
318 communicating parties, negotiates cryptographic modes and
319 parameters, and establishes shared keying material. The handshake
320 protocol is designed to resist tampering; an active attacker
321 should not be able to force the peers to negotiate different
322 parameters than they would if the connection were not under
323 attack.
324
325 - A record protocol (Section 5) that uses the parameters established
326 by the handshake protocol to protect traffic between the
327 communicating peers. The record protocol divides traffic up into
328 a series of records, each of which is independently protected
329 using the traffic keys.
330
331
332
333
334
335
336
337
338Rescorla Standards Track [Page 6]
339
340RFC 8446 TLS August 2018
341
342
343 TLS is application protocol independent; higher-level protocols can
344 layer on top of TLS transparently. The TLS standard, however, does
345 not specify how protocols add security with TLS; how to initiate TLS
346 handshaking and how to interpret the authentication certificates
347 exchanged are left to the judgment of the designers and implementors
348 of protocols that run on top of TLS.
349
350 This document defines TLS version 1.3. While TLS 1.3 is not directly
351 compatible with previous versions, all versions of TLS incorporate a
352 versioning mechanism which allows clients and servers to
353 interoperably negotiate a common version if one is supported by both
354 peers.
355
356 This document supersedes and obsoletes previous versions of TLS,
357 including version 1.2 [RFC5246]. It also obsoletes the TLS ticket
358 mechanism defined in [RFC5077] and replaces it with the mechanism
359 defined in Section 2.2. Because TLS 1.3 changes the way keys are
360 derived, it updates [RFC5705] as described in Section 7.5. It also
361 changes how Online Certificate Status Protocol (OCSP) messages are
362 carried and therefore updates [RFC6066] and obsoletes [RFC6961] as
363 described in Section 4.4.2.1.
364
3651.1. Conventions and Terminology
366
367 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
368 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
369 "OPTIONAL" in this document are to be interpreted as described in
370 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
371 capitals, as shown here.
372
373 The following terms are used:
374
375 client: The endpoint initiating the TLS connection.
376
377 connection: A transport-layer connection between two endpoints.
378
379 endpoint: Either the client or server of the connection.
380
381 handshake: An initial negotiation between client and server that
382 establishes the parameters of their subsequent interactions
383 within TLS.
384
385 peer: An endpoint. When discussing a particular endpoint, "peer"
386 refers to the endpoint that is not the primary subject of
387 discussion.
388
389
390
391
392
393
394Rescorla Standards Track [Page 7]
395
396RFC 8446 TLS August 2018
397
398
399 receiver: An endpoint that is receiving records.
400
401 sender: An endpoint that is transmitting records.
402
403 server: The endpoint that did not initiate the TLS connection.
404
4051.2. Major Differences from TLS 1.2
406
407 The following is a list of the major functional differences between
408 TLS 1.2 and TLS 1.3. It is not intended to be exhaustive, and there
409 are many minor differences.
410
411 - The list of supported symmetric encryption algorithms has been
412 pruned of all algorithms that are considered legacy. Those that
413 remain are all Authenticated Encryption with Associated Data
414 (AEAD) algorithms. The cipher suite concept has been changed to
415 separate the authentication and key exchange mechanisms from the
416 record protection algorithm (including secret key length) and a
417 hash to be used with both the key derivation function and
418 handshake message authentication code (MAC).
419
420 - A zero round-trip time (0-RTT) mode was added, saving a round trip
421 at connection setup for some application data, at the cost of
422 certain security properties.
423
424 - Static RSA and Diffie-Hellman cipher suites have been removed; all
425 public-key based key exchange mechanisms now provide forward
426 secrecy.
427
428 - All handshake messages after the ServerHello are now encrypted.
429 The newly introduced EncryptedExtensions message allows various
430 extensions previously sent in the clear in the ServerHello to also
431 enjoy confidentiality protection.
432
433 - The key derivation functions have been redesigned. The new design
434 allows easier analysis by cryptographers due to their improved key
435 separation properties. The HMAC-based Extract-and-Expand Key
436 Derivation Function (HKDF) is used as an underlying primitive.
437
438 - The handshake state machine has been significantly restructured to
439 be more consistent and to remove superfluous messages such as
440 ChangeCipherSpec (except when needed for middlebox compatibility).
441
442 - Elliptic curve algorithms are now in the base spec, and new
443 signature algorithms, such as EdDSA, are included. TLS 1.3
444 removed point format negotiation in favor of a single point format
445 for each curve.
446
447
448
449
450Rescorla Standards Track [Page 8]
451
452RFC 8446 TLS August 2018
453
454
455 - Other cryptographic improvements were made, including changing the
456 RSA padding to use the RSA Probabilistic Signature Scheme
457 (RSASSA-PSS), and the removal of compression, the Digital
458 Signature Algorithm (DSA), and custom Ephemeral Diffie-Hellman
459 (DHE) groups.
460
461 - The TLS 1.2 version negotiation mechanism has been deprecated in
462 favor of a version list in an extension. This increases
463 compatibility with existing servers that incorrectly implemented
464 version negotiation.
465
466 - Session resumption with and without server-side state as well as
467 the PSK-based cipher suites of earlier TLS versions have been
468 replaced by a single new PSK exchange.
469
470 - References have been updated to point to the updated versions of
471 RFCs, as appropriate (e.g., RFC 5280 rather than RFC 3280).
472
4731.3. Updates Affecting TLS 1.2
474
475 This document defines several changes that optionally affect
476 implementations of TLS 1.2, including those which do not also support
477 TLS 1.3:
478
479 - A version downgrade protection mechanism is described in
480 Section 4.1.3.
481
482 - RSASSA-PSS signature schemes are defined in Section 4.2.3.
483
484 - The "supported_versions" ClientHello extension can be used to
485 negotiate the version of TLS to use, in preference to the
486 legacy_version field of the ClientHello.
487
488 - The "signature_algorithms_cert" extension allows a client to
489 indicate which signature algorithms it can validate in X.509
490 certificates.
491
492 Additionally, this document clarifies some compliance requirements
493 for earlier versions of TLS; see Section 9.3.
494
495
496
497
498
499
500
501
502
503
504
505
506Rescorla Standards Track [Page 9]
507
508RFC 8446 TLS August 2018
509
510
5112. Protocol Overview
512
513 The cryptographic parameters used by the secure channel are produced
514 by the TLS handshake protocol. This sub-protocol of TLS is used by
515 the client and server when first communicating with each other. The
516 handshake protocol allows peers to negotiate a protocol version,
517 select cryptographic algorithms, optionally authenticate each other,
518 and establish shared secret keying material. Once the handshake is
519 complete, the peers use the established keys to protect the
520 application-layer traffic.
521
522 A failure of the handshake or other protocol error triggers the
523 termination of the connection, optionally preceded by an alert
524 message (Section 6).
525
526 TLS supports three basic key exchange modes:
527
528 - (EC)DHE (Diffie-Hellman over either finite fields or elliptic
529 curves)
530
531 - PSK-only
532
533 - PSK with (EC)DHE
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
562Rescorla Standards Track [Page 10]
563
564RFC 8446 TLS August 2018
565
566
567 Figure 1 below shows the basic full TLS handshake:
568
569 Client Server
570
571Key ^ ClientHello
572Exch | + key_share*
573 | + signature_algorithms*
574 | + psk_key_exchange_modes*
575 v + pre_shared_key* -------->
576 ServerHello ^ Key
577 + key_share* | Exch
578 + pre_shared_key* v
579 {EncryptedExtensions} ^ Server
580 {CertificateRequest*} v Params
581 {Certificate*} ^
582 {CertificateVerify*} | Auth
583 {Finished} v
584 <-------- [Application Data*]
585 ^ {Certificate*}
586Auth | {CertificateVerify*}
587 v {Finished} -------->
588 [Application Data] <-------> [Application Data]
589
590 + Indicates noteworthy extensions sent in the
591 previously noted message.
592
593 * Indicates optional or situation-dependent
594 messages/extensions that are not always sent.
595
596 {} Indicates messages protected using keys
597 derived from a [sender]_handshake_traffic_secret.
598
599 [] Indicates messages protected using keys
600 derived from [sender]_application_traffic_secret_N.
601
602 Figure 1: Message Flow for Full TLS Handshake
603
604 The handshake can be thought of as having three phases (indicated in
605 the diagram above):
606
607 - Key Exchange: Establish shared keying material and select the
608 cryptographic parameters. Everything after this phase is
609 encrypted.
610
611 - Server Parameters: Establish other handshake parameters
612 (whether the client is authenticated, application-layer protocol
613 support, etc.).
614
615
616
617
618Rescorla Standards Track [Page 11]
619
620RFC 8446 TLS August 2018
621
622
623 - Authentication: Authenticate the server (and, optionally, the
624 client) and provide key confirmation and handshake integrity.
625
626 In the Key Exchange phase, the client sends the ClientHello
627 (Section 4.1.2) message, which contains a random nonce
628 (ClientHello.random); its offered protocol versions; a list of
629 symmetric cipher/HKDF hash pairs; either a set of Diffie-Hellman key
630 shares (in the "key_share" (Section 4.2.8) extension), a set of
631 pre-shared key labels (in the "pre_shared_key" (Section 4.2.11)
632 extension), or both; and potentially additional extensions.
633 Additional fields and/or messages may also be present for middlebox
634 compatibility.
635
636 The server processes the ClientHello and determines the appropriate
637 cryptographic parameters for the connection. It then responds with
638 its own ServerHello (Section 4.1.3), which indicates the negotiated
639 connection parameters. The combination of the ClientHello and the
640 ServerHello determines the shared keys. If (EC)DHE key establishment
641 is in use, then the ServerHello contains a "key_share" extension with
642 the server's ephemeral Diffie-Hellman share; the server's share MUST
643 be in the same group as one of the client's shares. If PSK key
644 establishment is in use, then the ServerHello contains a
645 "pre_shared_key" extension indicating which of the client's offered
646 PSKs was selected. Note that implementations can use (EC)DHE and PSK
647 together, in which case both extensions will be supplied.
648
649 The server then sends two messages to establish the Server
650 Parameters:
651
652 EncryptedExtensions: responses to ClientHello extensions that are
653 not required to determine the cryptographic parameters, other than
654 those that are specific to individual certificates.
655 [Section 4.3.1]
656
657 CertificateRequest: if certificate-based client authentication is
658 desired, the desired parameters for that certificate. This
659 message is omitted if client authentication is not desired.
660 [Section 4.3.2]
661
662
663
664
665
666
667
668
669
670
671
672
673
674Rescorla Standards Track [Page 12]
675
676RFC 8446 TLS August 2018
677
678
679 Finally, the client and server exchange Authentication messages. TLS
680 uses the same set of messages every time that certificate-based
681 authentication is needed. (PSK-based authentication happens as a
682 side effect of key exchange.) Specifically:
683
684 Certificate: The certificate of the endpoint and any per-certificate
685 extensions. This message is omitted by the server if not
686 authenticating with a certificate and by the client if the server
687 did not send CertificateRequest (thus indicating that the client
688 should not authenticate with a certificate). Note that if raw
689 public keys [RFC7250] or the cached information extension
690 [RFC7924] are in use, then this message will not contain a
691 certificate but rather some other value corresponding to the
692 server's long-term key. [Section 4.4.2]
693
694 CertificateVerify: A signature over the entire handshake using the
695 private key corresponding to the public key in the Certificate
696 message. This message is omitted if the endpoint is not
697 authenticating via a certificate. [Section 4.4.3]
698
699 Finished: A MAC (Message Authentication Code) over the entire
700 handshake. This message provides key confirmation, binds the
701 endpoint's identity to the exchanged keys, and in PSK mode also
702 authenticates the handshake. [Section 4.4.4]
703
704 Upon receiving the server's messages, the client responds with its
705 Authentication messages, namely Certificate and CertificateVerify (if
706 requested), and Finished.
707
708 At this point, the handshake is complete, and the client and server
709 derive the keying material required by the record layer to exchange
710 application-layer data protected through authenticated encryption.
711 Application Data MUST NOT be sent prior to sending the Finished
712 message, except as specified in Section 2.3. Note that while the
713 server may send Application Data prior to receiving the client's
714 Authentication messages, any data sent at that point is, of course,
715 being sent to an unauthenticated peer.
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730Rescorla Standards Track [Page 13]
731
732RFC 8446 TLS August 2018
733
734
7352.1. Incorrect DHE Share
736
737 If the client has not provided a sufficient "key_share" extension
738 (e.g., it includes only DHE or ECDHE groups unacceptable to or
739 unsupported by the server), the server corrects the mismatch with a
740 HelloRetryRequest and the client needs to restart the handshake with
741 an appropriate "key_share" extension, as shown in Figure 2. If no
742 common cryptographic parameters can be negotiated, the server MUST
743 abort the handshake with an appropriate alert.
744
745 Client Server
746
747 ClientHello
748 + key_share -------->
749 HelloRetryRequest
750 <-------- + key_share
751 ClientHello
752 + key_share -------->
753 ServerHello
754 + key_share
755 {EncryptedExtensions}
756 {CertificateRequest*}
757 {Certificate*}
758 {CertificateVerify*}
759 {Finished}
760 <-------- [Application Data*]
761 {Certificate*}
762 {CertificateVerify*}
763 {Finished} -------->
764 [Application Data] <-------> [Application Data]
765
766 Figure 2: Message Flow for a Full Handshake with
767 Mismatched Parameters
768
769 Note: The handshake transcript incorporates the initial
770 ClientHello/HelloRetryRequest exchange; it is not reset with the
771 new ClientHello.
772
773 TLS also allows several optimized variants of the basic handshake, as
774 described in the following sections.
775
776
777
778
779
780
781
782
783
784
785
786Rescorla Standards Track [Page 14]
787
788RFC 8446 TLS August 2018
789
790
7912.2. Resumption and Pre-Shared Key (PSK)
792
793 Although TLS PSKs can be established out of band, PSKs can also be
794 established in a previous connection and then used to establish a new
795 connection ("session resumption" or "resuming" with a PSK). Once a
796 handshake has completed, the server can send the client a PSK
797 identity that corresponds to a unique key derived from the initial
798 handshake (see Section 4.6.1). The client can then use that PSK
799 identity in future handshakes to negotiate the use of the associated
800 PSK. If the server accepts the PSK, then the security context of the
801 new connection is cryptographically tied to the original connection
802 and the key derived from the initial handshake is used to bootstrap
803 the cryptographic state instead of a full handshake. In TLS 1.2 and
804 below, this functionality was provided by "session IDs" and "session
805 tickets" [RFC5077]. Both mechanisms are obsoleted in TLS 1.3.
806
807 PSKs can be used with (EC)DHE key exchange in order to provide
808 forward secrecy in combination with shared keys, or can be used
809 alone, at the cost of losing forward secrecy for the application
810 data.
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
842Rescorla Standards Track [Page 15]
843
844RFC 8446 TLS August 2018
845
846
847 Figure 3 shows a pair of handshakes in which the first handshake
848 establishes a PSK and the second handshake uses it:
849
850 Client Server
851
852 Initial Handshake:
853 ClientHello
854 + key_share -------->
855 ServerHello
856 + key_share
857 {EncryptedExtensions}
858 {CertificateRequest*}
859 {Certificate*}
860 {CertificateVerify*}
861 {Finished}
862 <-------- [Application Data*]
863 {Certificate*}
864 {CertificateVerify*}
865 {Finished} -------->
866 <-------- [NewSessionTicket]
867 [Application Data] <-------> [Application Data]
868
869
870 Subsequent Handshake:
871 ClientHello
872 + key_share*
873 + pre_shared_key -------->
874 ServerHello
875 + pre_shared_key
876 + key_share*
877 {EncryptedExtensions}
878 {Finished}
879 <-------- [Application Data*]
880 {Finished} -------->
881 [Application Data] <-------> [Application Data]
882
883 Figure 3: Message Flow for Resumption and PSK
884
885 As the server is authenticating via a PSK, it does not send a
886 Certificate or a CertificateVerify message. When a client offers
887 resumption via a PSK, it SHOULD also supply a "key_share" extension
888 to the server to allow the server to decline resumption and fall back
889 to a full handshake, if needed. The server responds with a
890 "pre_shared_key" extension to negotiate the use of PSK key
891 establishment and can (as shown here) respond with a "key_share"
892 extension to do (EC)DHE key establishment, thus providing forward
893 secrecy.
894
895
896
897
898Rescorla Standards Track [Page 16]
899
900RFC 8446 TLS August 2018
901
902
903 When PSKs are provisioned out of band, the PSK identity and the KDF
904 hash algorithm to be used with the PSK MUST also be provisioned.
905
906 Note: When using an out-of-band provisioned pre-shared secret, a
907 critical consideration is using sufficient entropy during the key
908 generation, as discussed in [RFC4086]. Deriving a shared secret
909 from a password or other low-entropy sources is not secure. A
910 low-entropy secret, or password, is subject to dictionary attacks
911 based on the PSK binder. The specified PSK authentication is not
912 a strong password-based authenticated key exchange even when used
913 with Diffie-Hellman key establishment. Specifically, it does not
914 prevent an attacker that can observe the handshake from performing
915 a brute-force attack on the password/pre-shared key.
916
9172.3. 0-RTT Data
918
919 When clients and servers share a PSK (either obtained externally or
920 via a previous handshake), TLS 1.3 allows clients to send data on the
921 first flight ("early data"). The client uses the PSK to authenticate
922 the server and to encrypt the early data.
923
924 As shown in Figure 4, the 0-RTT data is just added to the 1-RTT
925 handshake in the first flight. The rest of the handshake uses the
926 same messages as for a 1-RTT handshake with PSK resumption.
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
954Rescorla Standards Track [Page 17]
955
956RFC 8446 TLS August 2018
957
958
959 Client Server
960
961 ClientHello
962 + early_data
963 + key_share*
964 + psk_key_exchange_modes
965 + pre_shared_key
966 (Application Data*) -------->
967 ServerHello
968 + pre_shared_key
969 + key_share*
970 {EncryptedExtensions}
971 + early_data*
972 {Finished}
973 <-------- [Application Data*]
974 (EndOfEarlyData)
975 {Finished} -------->
976 [Application Data] <-------> [Application Data]
977
978 + Indicates noteworthy extensions sent in the
979 previously noted message.
980
981 * Indicates optional or situation-dependent
982 messages/extensions that are not always sent.
983
984 () Indicates messages protected using keys
985 derived from a client_early_traffic_secret.
986
987 {} Indicates messages protected using keys
988 derived from a [sender]_handshake_traffic_secret.
989
990 [] Indicates messages protected using keys
991 derived from [sender]_application_traffic_secret_N.
992
993 Figure 4: Message Flow for a 0-RTT Handshake
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010Rescorla Standards Track [Page 18]
1011
1012RFC 8446 TLS August 2018
1013
1014
1015 IMPORTANT NOTE: The security properties for 0-RTT data are weaker
1016 than those for other kinds of TLS data. Specifically:
1017
1018 1. This data is not forward secret, as it is encrypted solely under
1019 keys derived using the offered PSK.
1020
1021 2. There are no guarantees of non-replay between connections.
1022 Protection against replay for ordinary TLS 1.3 1-RTT data is
1023 provided via the server's Random value, but 0-RTT data does not
1024 depend on the ServerHello and therefore has weaker guarantees.
1025 This is especially relevant if the data is authenticated either
1026 with TLS client authentication or inside the application
1027 protocol. The same warnings apply to any use of the
1028 early_exporter_master_secret.
1029
1030 0-RTT data cannot be duplicated within a connection (i.e., the server
1031 will not process the same data twice for the same connection), and an
1032 attacker will not be able to make 0-RTT data appear to be 1-RTT data
1033 (because it is protected with different keys). Appendix E.5 contains
1034 a description of potential attacks, and Section 8 describes
1035 mechanisms which the server can use to limit the impact of replay.
1036
10373. Presentation Language
1038
1039 This document deals with the formatting of data in an external
1040 representation. The following very basic and somewhat casually
1041 defined presentation syntax will be used.
1042
10433.1. Basic Block Size
1044
1045 The representation of all data items is explicitly specified. The
1046 basic data block size is one byte (i.e., 8 bits). Multiple-byte data
1047 items are concatenations of bytes, from left to right, from top to
1048 bottom. From the byte stream, a multi-byte item (a numeric in the
1049 following example) is formed (using C notation) by:
1050
1051 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) |
1052 ... | byte[n-1];
1053
1054 This byte ordering for multi-byte values is the commonplace network
1055 byte order or big-endian format.
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066Rescorla Standards Track [Page 19]
1067
1068RFC 8446 TLS August 2018
1069
1070
10713.2. Miscellaneous
1072
1073 Comments begin with "/*" and end with "*/".
1074
1075 Optional components are denoted by enclosing them in "[[ ]]" (double
1076 brackets).
1077
1078 Single-byte entities containing uninterpreted data are of
1079 type opaque.
1080
1081 A type alias T' for an existing type T is defined by:
1082
1083 T T';
1084
10853.3. Numbers
1086
1087 The basic numeric data type is an unsigned byte (uint8). All larger
1088 numeric data types are constructed from a fixed-length series of
1089 bytes concatenated as described in Section 3.1 and are also unsigned.
1090 The following numeric types are predefined.
1091
1092 uint8 uint16[2];
1093 uint8 uint24[3];
1094 uint8 uint32[4];
1095 uint8 uint64[8];
1096
1097 All values, here and elsewhere in the specification, are transmitted
1098 in network byte (big-endian) order; the uint32 represented by the hex
1099 bytes 01 02 03 04 is equivalent to the decimal value 16909060.
1100
11013.4. Vectors
1102
1103 A vector (single-dimensioned array) is a stream of homogeneous data
1104 elements. The size of the vector may be specified at documentation
1105 time or left unspecified until runtime. In either case, the length
1106 declares the number of bytes, not the number of elements, in the
1107 vector. The syntax for specifying a new type, T', that is a fixed-
1108 length vector of type T is
1109
1110 T T'[n];
1111
1112 Here, T' occupies n bytes in the data stream, where n is a multiple
1113 of the size of T. The length of the vector is not included in the
1114 encoded stream.
1115
1116
1117
1118
1119
1120
1121
1122Rescorla Standards Track [Page 20]
1123
1124RFC 8446 TLS August 2018
1125
1126
1127 In the following example, Datum is defined to be three consecutive
1128 bytes that the protocol does not interpret, while Data is three
1129 consecutive Datum, consuming a total of nine bytes.
1130
1131 opaque Datum[3]; /* three uninterpreted bytes */
1132 Datum Data[9]; /* three consecutive 3-byte vectors */
1133
1134 Variable-length vectors are defined by specifying a subrange of legal
1135 lengths, inclusively, using the notation <floor..ceiling>. When
1136 these are encoded, the actual length precedes the vector's contents
1137 in the byte stream. The length will be in the form of a number
1138 consuming as many bytes as required to hold the vector's specified
1139 maximum (ceiling) length. A variable-length vector with an actual
1140 length field of zero is referred to as an empty vector.
1141
1142 T T'<floor..ceiling>;
1143
1144 In the following example, "mandatory" is a vector that must contain
1145 between 300 and 400 bytes of type opaque. It can never be empty.
1146 The actual length field consumes two bytes, a uint16, which is
1147 sufficient to represent the value 400 (see Section 3.3). Similarly,
1148 "longer" can represent up to 800 bytes of data, or 400 uint16
1149 elements, and it may be empty. Its encoding will include a two-byte
1150 actual length field prepended to the vector. The length of an
1151 encoded vector must be an exact multiple of the length of a single
1152 element (e.g., a 17-byte vector of uint16 would be illegal).
1153
1154 opaque mandatory<300..400>;
1155 /* length field is two bytes, cannot be empty */
1156 uint16 longer<0..800>;
1157 /* zero to 400 16-bit unsigned integers */
1158
11593.5. Enumerateds
1160
1161 An additional sparse data type, called "enum" or "enumerated", is
1162 available. Each definition is a different type. Only enumerateds of
1163 the same type may be assigned or compared. Every element of an
1164 enumerated must be assigned a value, as demonstrated in the following
1165 example. Since the elements of the enumerated are not ordered, they
1166 can be assigned any unique value, in any order.
1167
1168 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te;
1169
1170 Future extensions or additions to the protocol may define new values.
1171 Implementations need to be able to parse and ignore unknown values
1172 unless the definition of the field states otherwise.
1173
1174
1175
1176
1177
1178Rescorla Standards Track [Page 21]
1179
1180RFC 8446 TLS August 2018
1181
1182
1183 An enumerated occupies as much space in the byte stream as would its
1184 maximal defined ordinal value. The following definition would cause
1185 one byte to be used to carry fields of type Color.
1186
1187 enum { red(3), blue(5), white(7) } Color;
1188
1189 One may optionally specify a value without its associated tag to
1190 force the width definition without defining a superfluous element.
1191
1192 In the following example, Taste will consume two bytes in the data
1193 stream but can only assume the values 1, 2, or 4 in the current
1194 version of the protocol.
1195
1196 enum { sweet(1), sour(2), bitter(4), (32000) } Taste;
1197
1198 The names of the elements of an enumeration are scoped within the
1199 defined type. In the first example, a fully qualified reference to
1200 the second element of the enumeration would be Color.blue. Such
1201 qualification is not required if the target of the assignment is well
1202 specified.
1203
1204 Color color = Color.blue; /* overspecified, legal */
1205 Color color = blue; /* correct, type implicit */
1206
1207 The names assigned to enumerateds do not need to be unique. The
1208 numerical value can describe a range over which the same name
1209 applies. The value includes the minimum and maximum inclusive values
1210 in that range, separated by two period characters. This is
1211 principally useful for reserving regions of the space.
1212
1213 enum { sad(0), meh(1..254), happy(255) } Mood;
1214
12153.6. Constructed Types
1216
1217 Structure types may be constructed from primitive types for
1218 convenience. Each specification declares a new, unique type. The
1219 syntax used for definitions is much like that of C.
1220
1221 struct {
1222 T1 f1;
1223 T2 f2;
1224 ...
1225 Tn fn;
1226 } T;
1227
1228 Fixed- and variable-length vector fields are allowed using the
1229 standard vector syntax. Structures V1 and V2 in the variants example
1230 (Section 3.8) demonstrate this.
1231
1232
1233
1234Rescorla Standards Track [Page 22]
1235
1236RFC 8446 TLS August 2018
1237
1238
1239 The fields within a structure may be qualified using the type's name,
1240 with a syntax much like that available for enumerateds. For example,
1241 T.f2 refers to the second field of the previous declaration.
1242
12433.7. Constants
1244
1245 Fields and variables may be assigned a fixed value using "=", as in:
1246
1247 struct {
1248 T1 f1 = 8; /* T.f1 must always be 8 */
1249 T2 f2;
1250 } T;
1251
12523.8. Variants
1253
1254 Defined structures may have variants based on some knowledge that is
1255 available within the environment. The selector must be an enumerated
1256 type that defines the possible variants the structure defines. Each
1257 arm of the select (below) specifies the type of that variant's field
1258 and an optional field label. The mechanism by which the variant is
1259 selected at runtime is not prescribed by the presentation language.
1260
1261 struct {
1262 T1 f1;
1263 T2 f2;
1264 ....
1265 Tn fn;
1266 select (E) {
1267 case e1: Te1 [[fe1]];
1268 case e2: Te2 [[fe2]];
1269 ....
1270 case en: Ten [[fen]];
1271 };
1272 } Tv;
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290Rescorla Standards Track [Page 23]
1291
1292RFC 8446 TLS August 2018
1293
1294
1295 For example:
1296
1297 enum { apple(0), orange(1) } VariantTag;
1298
1299 struct {
1300 uint16 number;
1301 opaque string<0..10>; /* variable length */
1302 } V1;
1303
1304 struct {
1305 uint32 number;
1306 opaque string[10]; /* fixed length */
1307 } V2;
1308
1309 struct {
1310 VariantTag type;
1311 select (VariantRecord.type) {
1312 case apple: V1;
1313 case orange: V2;
1314 };
1315 } VariantRecord;
1316
13174. Handshake Protocol
1318
1319 The handshake protocol is used to negotiate the security parameters
1320 of a connection. Handshake messages are supplied to the TLS record
1321 layer, where they are encapsulated within one or more TLSPlaintext or
1322 TLSCiphertext structures which are processed and transmitted as
1323 specified by the current active connection state.
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346Rescorla Standards Track [Page 24]
1347
1348RFC 8446 TLS August 2018
1349
1350
1351 enum {
1352 client_hello(1),
1353 server_hello(2),
1354 new_session_ticket(4),
1355 end_of_early_data(5),
1356 encrypted_extensions(8),
1357 certificate(11),
1358 certificate_request(13),
1359 certificate_verify(15),
1360 finished(20),
1361 key_update(24),
1362 message_hash(254),
1363 (255)
1364 } HandshakeType;
1365
1366 struct {
1367 HandshakeType msg_type; /* handshake type */
1368 uint24 length; /* remaining bytes in message */
1369 select (Handshake.msg_type) {
1370 case client_hello: ClientHello;
1371 case server_hello: ServerHello;
1372 case end_of_early_data: EndOfEarlyData;
1373 case encrypted_extensions: EncryptedExtensions;
1374 case certificate_request: CertificateRequest;
1375 case certificate: Certificate;
1376 case certificate_verify: CertificateVerify;
1377 case finished: Finished;
1378 case new_session_ticket: NewSessionTicket;
1379 case key_update: KeyUpdate;
1380 };
1381 } Handshake;
1382
1383 Protocol messages MUST be sent in the order defined in Section 4.4.1
1384 and shown in the diagrams in Section 2. A peer which receives a
1385 handshake message in an unexpected order MUST abort the handshake
1386 with an "unexpected_message" alert.
1387
1388 New handshake message types are assigned by IANA as described in
1389 Section 11.
1390
13914.1. Key Exchange Messages
1392
1393 The key exchange messages are used to determine the security
1394 capabilities of the client and the server and to establish shared
1395 secrets, including the traffic keys used to protect the rest of the
1396 handshake and the data.
1397
1398
1399
1400
1401
1402Rescorla Standards Track [Page 25]
1403
1404RFC 8446 TLS August 2018
1405
1406
14074.1.1. Cryptographic Negotiation
1408
1409 In TLS, the cryptographic negotiation proceeds by the client offering
1410 the following four sets of options in its ClientHello:
1411
1412 - A list of cipher suites which indicates the AEAD algorithm/HKDF
1413 hash pairs which the client supports.
1414
1415 - A "supported_groups" (Section 4.2.7) extension which indicates the
1416 (EC)DHE groups which the client supports and a "key_share"
1417 (Section 4.2.8) extension which contains (EC)DHE shares for some
1418 or all of these groups.
1419
1420 - A "signature_algorithms" (Section 4.2.3) extension which indicates
1421 the signature algorithms which the client can accept. A
1422 "signature_algorithms_cert" extension (Section 4.2.3) may also be
1423 added to indicate certificate-specific signature algorithms.
1424
1425 - A "pre_shared_key" (Section 4.2.11) extension which contains a
1426 list of symmetric key identities known to the client and a
1427 "psk_key_exchange_modes" (Section 4.2.9) extension which indicates
1428 the key exchange modes that may be used with PSKs.
1429
1430 If the server does not select a PSK, then the first three of these
1431 options are entirely orthogonal: the server independently selects a
1432 cipher suite, an (EC)DHE group and key share for key establishment,
1433 and a signature algorithm/certificate pair to authenticate itself to
1434 the client. If there is no overlap between the received
1435 "supported_groups" and the groups supported by the server, then the
1436 server MUST abort the handshake with a "handshake_failure" or an
1437 "insufficient_security" alert.
1438
1439 If the server selects a PSK, then it MUST also select a key
1440 establishment mode from the set indicated by the client's
1441 "psk_key_exchange_modes" extension (at present, PSK alone or with
1442 (EC)DHE). Note that if the PSK can be used without (EC)DHE, then
1443 non-overlap in the "supported_groups" parameters need not be fatal,
1444 as it is in the non-PSK case discussed in the previous paragraph.
1445
1446 If the server selects an (EC)DHE group and the client did not offer a
1447 compatible "key_share" extension in the initial ClientHello, the
1448 server MUST respond with a HelloRetryRequest (Section 4.1.4) message.
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458Rescorla Standards Track [Page 26]
1459
1460RFC 8446 TLS August 2018
1461
1462
1463 If the server successfully selects parameters and does not require a
1464 HelloRetryRequest, it indicates the selected parameters in the
1465 ServerHello as follows:
1466
1467 - If PSK is being used, then the server will send a "pre_shared_key"
1468 extension indicating the selected key.
1469
1470 - When (EC)DHE is in use, the server will also provide a "key_share"
1471 extension. If PSK is not being used, then (EC)DHE and
1472 certificate-based authentication are always used.
1473
1474 - When authenticating via a certificate, the server will send the
1475 Certificate (Section 4.4.2) and CertificateVerify (Section 4.4.3)
1476 messages. In TLS 1.3 as defined by this document, either a PSK or
1477 a certificate is always used, but not both. Future documents may
1478 define how to use them together.
1479
1480 If the server is unable to negotiate a supported set of parameters
1481 (i.e., there is no overlap between the client and server parameters),
1482 it MUST abort the handshake with either a "handshake_failure" or
1483 "insufficient_security" fatal alert (see Section 6).
1484
14854.1.2. Client Hello
1486
1487 When a client first connects to a server, it is REQUIRED to send the
1488 ClientHello as its first TLS message. The client will also send a
1489 ClientHello when the server has responded to its ClientHello with a
1490 HelloRetryRequest. In that case, the client MUST send the same
1491 ClientHello without modification, except as follows:
1492
1493 - If a "key_share" extension was supplied in the HelloRetryRequest,
1494 replacing the list of shares with a list containing a single
1495 KeyShareEntry from the indicated group.
1496
1497 - Removing the "early_data" extension (Section 4.2.10) if one was
1498 present. Early data is not permitted after a HelloRetryRequest.
1499
1500 - Including a "cookie" extension if one was provided in the
1501 HelloRetryRequest.
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514Rescorla Standards Track [Page 27]
1515
1516RFC 8446 TLS August 2018
1517
1518
1519 - Updating the "pre_shared_key" extension if present by recomputing
1520 the "obfuscated_ticket_age" and binder values and (optionally)
1521 removing any PSKs which are incompatible with the server's
1522 indicated cipher suite.
1523
1524 - Optionally adding, removing, or changing the length of the
1525 "padding" extension [RFC7685].
1526
1527 - Other modifications that may be allowed by an extension defined in
1528 the future and present in the HelloRetryRequest.
1529
1530 Because TLS 1.3 forbids renegotiation, if a server has negotiated
1531 TLS 1.3 and receives a ClientHello at any other time, it MUST
1532 terminate the connection with an "unexpected_message" alert.
1533
1534 If a server established a TLS connection with a previous version of
1535 TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST
1536 retain the previous protocol version. In particular, it MUST NOT
1537 negotiate TLS 1.3.
1538
1539 Structure of this message:
1540
1541 uint16 ProtocolVersion;
1542 opaque Random[32];
1543
1544 uint8 CipherSuite[2]; /* Cryptographic suite selector */
1545
1546 struct {
1547 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */
1548 Random random;
1549 opaque legacy_session_id<0..32>;
1550 CipherSuite cipher_suites<2..2^16-2>;
1551 opaque legacy_compression_methods<1..2^8-1>;
1552 Extension extensions<8..2^16-1>;
1553 } ClientHello;
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570Rescorla Standards Track [Page 28]
1571
1572RFC 8446 TLS August 2018
1573
1574
1575 legacy_version: In previous versions of TLS, this field was used for
1576 version negotiation and represented the highest version number
1577 supported by the client. Experience has shown that many servers
1578 do not properly implement version negotiation, leading to "version
1579 intolerance" in which the server rejects an otherwise acceptable
1580 ClientHello with a version number higher than it supports. In
1581 TLS 1.3, the client indicates its version preferences in the
1582 "supported_versions" extension (Section 4.2.1) and the
1583 legacy_version field MUST be set to 0x0303, which is the version
1584 number for TLS 1.2. TLS 1.3 ClientHellos are identified as having
1585 a legacy_version of 0x0303 and a supported_versions extension
1586 present with 0x0304 as the highest version indicated therein.
1587 (See Appendix D for details about backward compatibility.)
1588
1589 random: 32 bytes generated by a secure random number generator. See
1590 Appendix C for additional information.
1591
1592 legacy_session_id: Versions of TLS before TLS 1.3 supported a
1593 "session resumption" feature which has been merged with pre-shared
1594 keys in this version (see Section 2.2). A client which has a
1595 cached session ID set by a pre-TLS 1.3 server SHOULD set this
1596 field to that value. In compatibility mode (see Appendix D.4),
1597 this field MUST be non-empty, so a client not offering a
1598 pre-TLS 1.3 session MUST generate a new 32-byte value. This value
1599 need not be random but SHOULD be unpredictable to avoid
1600 implementations fixating on a specific value (also known as
1601 ossification). Otherwise, it MUST be set as a zero-length vector
1602 (i.e., a zero-valued single byte length field).
1603
1604 cipher_suites: A list of the symmetric cipher options supported by
1605 the client, specifically the record protection algorithm
1606 (including secret key length) and a hash to be used with HKDF, in
1607 descending order of client preference. Values are defined in
1608 Appendix B.4. If the list contains cipher suites that the server
1609 does not recognize, support, or wish to use, the server MUST
1610 ignore those cipher suites and process the remaining ones as
1611 usual. If the client is attempting a PSK key establishment, it
1612 SHOULD advertise at least one cipher suite indicating a Hash
1613 associated with the PSK.
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626Rescorla Standards Track [Page 29]
1627
1628RFC 8446 TLS August 2018
1629
1630
1631 legacy_compression_methods: Versions of TLS before 1.3 supported
1632 compression with the list of supported compression methods being
1633 sent in this field. For every TLS 1.3 ClientHello, this vector
1634 MUST contain exactly one byte, set to zero, which corresponds to
1635 the "null" compression method in prior versions of TLS. If a
1636 TLS 1.3 ClientHello is received with any other value in this
1637 field, the server MUST abort the handshake with an
1638 "illegal_parameter" alert. Note that TLS 1.3 servers might
1639 receive TLS 1.2 or prior ClientHellos which contain other
1640 compression methods and (if negotiating such a prior version) MUST
1641 follow the procedures for the appropriate prior version of TLS.
1642
1643 extensions: Clients request extended functionality from servers by
1644 sending data in the extensions field. The actual "Extension"
1645 format is defined in Section 4.2. In TLS 1.3, the use of certain
1646 extensions is mandatory, as functionality has moved into
1647 extensions to preserve ClientHello compatibility with previous
1648 versions of TLS. Servers MUST ignore unrecognized extensions.
1649
1650 All versions of TLS allow an extensions field to optionally follow
1651 the compression_methods field. TLS 1.3 ClientHello messages always
1652 contain extensions (minimally "supported_versions", otherwise, they
1653 will be interpreted as TLS 1.2 ClientHello messages). However,
1654 TLS 1.3 servers might receive ClientHello messages without an
1655 extensions field from prior versions of TLS. The presence of
1656 extensions can be detected by determining whether there are bytes
1657 following the compression_methods field at the end of the
1658 ClientHello. Note that this method of detecting optional data
1659 differs from the normal TLS method of having a variable-length field,
1660 but it is used for compatibility with TLS before extensions were
1661 defined. TLS 1.3 servers will need to perform this check first and
1662 only attempt to negotiate TLS 1.3 if the "supported_versions"
1663 extension is present. If negotiating a version of TLS prior to 1.3,
1664 a server MUST check that the message either contains no data after
1665 legacy_compression_methods or that it contains a valid extensions
1666 block with no data following. If not, then it MUST abort the
1667 handshake with a "decode_error" alert.
1668
1669 In the event that a client requests additional functionality using
1670 extensions and this functionality is not supplied by the server, the
1671 client MAY abort the handshake.
1672
1673 After sending the ClientHello message, the client waits for a
1674 ServerHello or HelloRetryRequest message. If early data is in use,
1675 the client may transmit early Application Data (Section 2.3) while
1676 waiting for the next handshake message.
1677
1678
1679
1680
1681
1682Rescorla Standards Track [Page 30]
1683
1684RFC 8446 TLS August 2018
1685
1686
16874.1.3. Server Hello
1688
1689 The server will send this message in response to a ClientHello
1690 message to proceed with the handshake if it is able to negotiate an
1691 acceptable set of handshake parameters based on the ClientHello.
1692
1693 Structure of this message:
1694
1695 struct {
1696 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */
1697 Random random;
1698 opaque legacy_session_id_echo<0..32>;
1699 CipherSuite cipher_suite;
1700 uint8 legacy_compression_method = 0;
1701 Extension extensions<6..2^16-1>;
1702 } ServerHello;
1703
1704 legacy_version: In previous versions of TLS, this field was used for
1705 version negotiation and represented the selected version number
1706 for the connection. Unfortunately, some middleboxes fail when
1707 presented with new values. In TLS 1.3, the TLS server indicates
1708 its version using the "supported_versions" extension
1709 (Section 4.2.1), and the legacy_version field MUST be set to
1710 0x0303, which is the version number for TLS 1.2. (See Appendix D
1711 for details about backward compatibility.)
1712
1713 random: 32 bytes generated by a secure random number generator. See
1714 Appendix C for additional information. The last 8 bytes MUST be
1715 overwritten as described below if negotiating TLS 1.2 or TLS 1.1,
1716 but the remaining bytes MUST be random. This structure is
1717 generated by the server and MUST be generated independently of the
1718 ClientHello.random.
1719
1720 legacy_session_id_echo: The contents of the client's
1721 legacy_session_id field. Note that this field is echoed even if
1722 the client's value corresponded to a cached pre-TLS 1.3 session
1723 which the server has chosen not to resume. A client which
1724 receives a legacy_session_id_echo field that does not match what
1725 it sent in the ClientHello MUST abort the handshake with an
1726 "illegal_parameter" alert.
1727
1728 cipher_suite: The single cipher suite selected by the server from
1729 the list in ClientHello.cipher_suites. A client which receives a
1730 cipher suite that was not offered MUST abort the handshake with an
1731 "illegal_parameter" alert.
1732
1733 legacy_compression_method: A single byte which MUST have the
1734 value 0.
1735
1736
1737
1738Rescorla Standards Track [Page 31]
1739
1740RFC 8446 TLS August 2018
1741
1742
1743 extensions: A list of extensions. The ServerHello MUST only include
1744 extensions which are required to establish the cryptographic
1745 context and negotiate the protocol version. All TLS 1.3
1746 ServerHello messages MUST contain the "supported_versions"
1747 extension. Current ServerHello messages additionally contain
1748 either the "pre_shared_key" extension or the "key_share"
1749 extension, or both (when using a PSK with (EC)DHE key
1750 establishment). Other extensions (see Section 4.2) are sent
1751 separately in the EncryptedExtensions message.
1752
1753 For reasons of backward compatibility with middleboxes (see
1754 Appendix D.4), the HelloRetryRequest message uses the same structure
1755 as the ServerHello, but with Random set to the special value of the
1756 SHA-256 of "HelloRetryRequest":
1757
1758 CF 21 AD 74 E5 9A 61 11 BE 1D 8C 02 1E 65 B8 91
1759 C2 A2 11 16 7A BB 8C 5E 07 9E 09 E2 C8 A8 33 9C
1760
1761 Upon receiving a message with type server_hello, implementations MUST
1762 first examine the Random value and, if it matches this value, process
1763 it as described in Section 4.1.4).
1764
1765 TLS 1.3 has a downgrade protection mechanism embedded in the server's
1766 random value. TLS 1.3 servers which negotiate TLS 1.2 or below in
1767 response to a ClientHello MUST set the last 8 bytes of their Random
1768 value specially in their ServerHello.
1769
1770 If negotiating TLS 1.2, TLS 1.3 servers MUST set the last 8 bytes of
1771 their Random value to the bytes:
1772
1773 44 4F 57 4E 47 52 44 01
1774
1775 If negotiating TLS 1.1 or below, TLS 1.3 servers MUST, and TLS 1.2
1776 servers SHOULD, set the last 8 bytes of their ServerHello.Random
1777 value to the bytes:
1778
1779 44 4F 57 4E 47 52 44 00
1780
1781 TLS 1.3 clients receiving a ServerHello indicating TLS 1.2 or below
1782 MUST check that the last 8 bytes are not equal to either of these
1783 values. TLS 1.2 clients SHOULD also check that the last 8 bytes are
1784 not equal to the second value if the ServerHello indicates TLS 1.1 or
1785 below. If a match is found, the client MUST abort the handshake with
1786 an "illegal_parameter" alert. This mechanism provides limited
1787 protection against downgrade attacks over and above what is provided
1788 by the Finished exchange: because the ServerKeyExchange, a message
1789 present in TLS 1.2 and below, includes a signature over both random
1790 values, it is not possible for an active attacker to modify the
1791
1792
1793
1794Rescorla Standards Track [Page 32]
1795
1796RFC 8446 TLS August 2018
1797
1798
1799 random values without detection as long as ephemeral ciphers are
1800 used. It does not provide downgrade protection when static RSA
1801 is used.
1802
1803 Note: This is a change from [RFC5246], so in practice many TLS 1.2
1804 clients and servers will not behave as specified above.
1805
1806 A legacy TLS client performing renegotiation with TLS 1.2 or prior
1807 and which receives a TLS 1.3 ServerHello during renegotiation MUST
1808 abort the handshake with a "protocol_version" alert. Note that
1809 renegotiation is not possible when TLS 1.3 has been negotiated.
1810
18114.1.4. Hello Retry Request
1812
1813 The server will send this message in response to a ClientHello
1814 message if it is able to find an acceptable set of parameters but the
1815 ClientHello does not contain sufficient information to proceed with
1816 the handshake. As discussed in Section 4.1.3, the HelloRetryRequest
1817 has the same format as a ServerHello message, and the legacy_version,
1818 legacy_session_id_echo, cipher_suite, and legacy_compression_method
1819 fields have the same meaning. However, for convenience we discuss
1820 "HelloRetryRequest" throughout this document as if it were a distinct
1821 message.
1822
1823 The server's extensions MUST contain "supported_versions".
1824 Additionally, it SHOULD contain the minimal set of extensions
1825 necessary for the client to generate a correct ClientHello pair. As
1826 with the ServerHello, a HelloRetryRequest MUST NOT contain any
1827 extensions that were not first offered by the client in its
1828 ClientHello, with the exception of optionally the "cookie" (see
1829 Section 4.2.2) extension.
1830
1831 Upon receipt of a HelloRetryRequest, the client MUST check the
1832 legacy_version, legacy_session_id_echo, cipher_suite, and
1833 legacy_compression_method as specified in Section 4.1.3 and then
1834 process the extensions, starting with determining the version using
1835 "supported_versions". Clients MUST abort the handshake with an
1836 "illegal_parameter" alert if the HelloRetryRequest would not result
1837 in any change in the ClientHello. If a client receives a second
1838 HelloRetryRequest in the same connection (i.e., where the ClientHello
1839 was itself in response to a HelloRetryRequest), it MUST abort the
1840 handshake with an "unexpected_message" alert.
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850Rescorla Standards Track [Page 33]
1851
1852RFC 8446 TLS August 2018
1853
1854
1855 Otherwise, the client MUST process all extensions in the
1856 HelloRetryRequest and send a second updated ClientHello. The
1857 HelloRetryRequest extensions defined in this specification are:
1858
1859 - supported_versions (see Section 4.2.1)
1860
1861 - cookie (see Section 4.2.2)
1862
1863 - key_share (see Section 4.2.8)
1864
1865 A client which receives a cipher suite that was not offered MUST
1866 abort the handshake. Servers MUST ensure that they negotiate the
1867 same cipher suite when receiving a conformant updated ClientHello (if
1868 the server selects the cipher suite as the first step in the
1869 negotiation, then this will happen automatically). Upon receiving
1870 the ServerHello, clients MUST check that the cipher suite supplied in
1871 the ServerHello is the same as that in the HelloRetryRequest and
1872 otherwise abort the handshake with an "illegal_parameter" alert.
1873
1874 In addition, in its updated ClientHello, the client SHOULD NOT offer
1875 any pre-shared keys associated with a hash other than that of the
1876 selected cipher suite. This allows the client to avoid having to
1877 compute partial hash transcripts for multiple hashes in the second
1878 ClientHello.
1879
1880 The value of selected_version in the HelloRetryRequest
1881 "supported_versions" extension MUST be retained in the ServerHello,
1882 and a client MUST abort the handshake with an "illegal_parameter"
1883 alert if the value changes.
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906Rescorla Standards Track [Page 34]
1907
1908RFC 8446 TLS August 2018
1909
1910
19114.2. Extensions
1912
1913 A number of TLS messages contain tag-length-value encoded extensions
1914 structures.
1915
1916 struct {
1917 ExtensionType extension_type;
1918 opaque extension_data<0..2^16-1>;
1919 } Extension;
1920
1921 enum {
1922 server_name(0), /* RFC 6066 */
1923 max_fragment_length(1), /* RFC 6066 */
1924 status_request(5), /* RFC 6066 */
1925 supported_groups(10), /* RFC 8422, 7919 */
1926 signature_algorithms(13), /* RFC 8446 */
1927 use_srtp(14), /* RFC 5764 */
1928 heartbeat(15), /* RFC 6520 */
1929 application_layer_protocol_negotiation(16), /* RFC 7301 */
1930 signed_certificate_timestamp(18), /* RFC 6962 */
1931 client_certificate_type(19), /* RFC 7250 */
1932 server_certificate_type(20), /* RFC 7250 */
1933 padding(21), /* RFC 7685 */
1934 pre_shared_key(41), /* RFC 8446 */
1935 early_data(42), /* RFC 8446 */
1936 supported_versions(43), /* RFC 8446 */
1937 cookie(44), /* RFC 8446 */
1938 psk_key_exchange_modes(45), /* RFC 8446 */
1939 certificate_authorities(47), /* RFC 8446 */
1940 oid_filters(48), /* RFC 8446 */
1941 post_handshake_auth(49), /* RFC 8446 */
1942 signature_algorithms_cert(50), /* RFC 8446 */
1943 key_share(51), /* RFC 8446 */
1944 (65535)
1945 } ExtensionType;
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962Rescorla Standards Track [Page 35]
1963
1964RFC 8446 TLS August 2018
1965
1966
1967 Here:
1968
1969 - "extension_type" identifies the particular extension type.
1970
1971 - "extension_data" contains information specific to the particular
1972 extension type.
1973
1974 The list of extension types is maintained by IANA as described in
1975 Section 11.
1976
1977 Extensions are generally structured in a request/response fashion,
1978 though some extensions are just indications with no corresponding
1979 response. The client sends its extension requests in the ClientHello
1980 message, and the server sends its extension responses in the
1981 ServerHello, EncryptedExtensions, HelloRetryRequest, and Certificate
1982 messages. The server sends extension requests in the
1983 CertificateRequest message which a client MAY respond to with a
1984 Certificate message. The server MAY also send unsolicited extensions
1985 in the NewSessionTicket, though the client does not respond directly
1986 to these.
1987
1988 Implementations MUST NOT send extension responses if the remote
1989 endpoint did not send the corresponding extension requests, with the
1990 exception of the "cookie" extension in the HelloRetryRequest. Upon
1991 receiving such an extension, an endpoint MUST abort the handshake
1992 with an "unsupported_extension" alert.
1993
1994 The table below indicates the messages where a given extension may
1995 appear, using the following notation: CH (ClientHello),
1996 SH (ServerHello), EE (EncryptedExtensions), CT (Certificate),
1997 CR (CertificateRequest), NST (NewSessionTicket), and
1998 HRR (HelloRetryRequest). If an implementation receives an extension
1999 which it recognizes and which is not specified for the message in
2000 which it appears, it MUST abort the handshake with an
2001 "illegal_parameter" alert.
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018Rescorla Standards Track [Page 36]
2019
2020RFC 8446 TLS August 2018
2021
2022
2023 +--------------------------------------------------+-------------+
2024 | Extension | TLS 1.3 |
2025 +--------------------------------------------------+-------------+
2026 | server_name [RFC6066] | CH, EE |
2027 | | |
2028 | max_fragment_length [RFC6066] | CH, EE |
2029 | | |
2030 | status_request [RFC6066] | CH, CR, CT |
2031 | | |
2032 | supported_groups [RFC7919] | CH, EE |
2033 | | |
2034 | signature_algorithms (RFC 8446) | CH, CR |
2035 | | |
2036 | use_srtp [RFC5764] | CH, EE |
2037 | | |
2038 | heartbeat [RFC6520] | CH, EE |
2039 | | |
2040 | application_layer_protocol_negotiation [RFC7301] | CH, EE |
2041 | | |
2042 | signed_certificate_timestamp [RFC6962] | CH, CR, CT |
2043 | | |
2044 | client_certificate_type [RFC7250] | CH, EE |
2045 | | |
2046 | server_certificate_type [RFC7250] | CH, EE |
2047 | | |
2048 | padding [RFC7685] | CH |
2049 | | |
2050 | key_share (RFC 8446) | CH, SH, HRR |
2051 | | |
2052 | pre_shared_key (RFC 8446) | CH, SH |
2053 | | |
2054 | psk_key_exchange_modes (RFC 8446) | CH |
2055 | | |
2056 | early_data (RFC 8446) | CH, EE, NST |
2057 | | |
2058 | cookie (RFC 8446) | CH, HRR |
2059 | | |
2060 | supported_versions (RFC 8446) | CH, SH, HRR |
2061 | | |
2062 | certificate_authorities (RFC 8446) | CH, CR |
2063 | | |
2064 | oid_filters (RFC 8446) | CR |
2065 | | |
2066 | post_handshake_auth (RFC 8446) | CH |
2067 | | |
2068 | signature_algorithms_cert (RFC 8446) | CH, CR |
2069 +--------------------------------------------------+-------------+
2070
2071
2072
2073
2074Rescorla Standards Track [Page 37]
2075
2076RFC 8446 TLS August 2018
2077
2078
2079 When multiple extensions of different types are present, the
2080 extensions MAY appear in any order, with the exception of
2081 "pre_shared_key" (Section 4.2.11) which MUST be the last extension in
2082 the ClientHello (but can appear anywhere in the ServerHello
2083 extensions block). There MUST NOT be more than one extension of the
2084 same type in a given extension block.
2085
2086 In TLS 1.3, unlike TLS 1.2, extensions are negotiated for each
2087 handshake even when in resumption-PSK mode. However, 0-RTT
2088 parameters are those negotiated in the previous handshake; mismatches
2089 may require rejecting 0-RTT (see Section 4.2.10).
2090
2091 There are subtle (and not so subtle) interactions that may occur in
2092 this protocol between new features and existing features which may
2093 result in a significant reduction in overall security. The following
2094 considerations should be taken into account when designing new
2095 extensions:
2096
2097 - Some cases where a server does not agree to an extension are error
2098 conditions (e.g., the handshake cannot continue), and some are
2099 simply refusals to support particular features. In general, error
2100 alerts should be used for the former and a field in the server
2101 extension response for the latter.
2102
2103 - Extensions should, as far as possible, be designed to prevent any
2104 attack that forces use (or non-use) of a particular feature by
2105 manipulation of handshake messages. This principle should be
2106 followed regardless of whether the feature is believed to cause a
2107 security problem. Often the fact that the extension fields are
2108 included in the inputs to the Finished message hashes will be
2109 sufficient, but extreme care is needed when the extension changes
2110 the meaning of messages sent in the handshake phase. Designers
2111 and implementors should be aware of the fact that until the
2112 handshake has been authenticated, active attackers can modify
2113 messages and insert, remove, or replace extensions.
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130Rescorla Standards Track [Page 38]
2131
2132RFC 8446 TLS August 2018
2133
2134
21354.2.1. Supported Versions
2136
2137 struct {
2138 select (Handshake.msg_type) {
2139 case client_hello:
2140 ProtocolVersion versions<2..254>;
2141
2142 case server_hello: /* and HelloRetryRequest */
2143 ProtocolVersion selected_version;
2144 };
2145 } SupportedVersions;
2146
2147 The "supported_versions" extension is used by the client to indicate
2148 which versions of TLS it supports and by the server to indicate which
2149 version it is using. The extension contains a list of supported
2150 versions in preference order, with the most preferred version first.
2151 Implementations of this specification MUST send this extension in the
2152 ClientHello containing all versions of TLS which they are prepared to
2153 negotiate (for this specification, that means minimally 0x0304, but
2154 if previous versions of TLS are allowed to be negotiated, they MUST
2155 be present as well).
2156
2157 If this extension is not present, servers which are compliant with
2158 this specification and which also support TLS 1.2 MUST negotiate
2159 TLS 1.2 or prior as specified in [RFC5246], even if
2160 ClientHello.legacy_version is 0x0304 or later. Servers MAY abort the
2161 handshake upon receiving a ClientHello with legacy_version 0x0304 or
2162 later.
2163
2164 If this extension is present in the ClientHello, servers MUST NOT use
2165 the ClientHello.legacy_version value for version negotiation and MUST
2166 use only the "supported_versions" extension to determine client
2167 preferences. Servers MUST only select a version of TLS present in
2168 that extension and MUST ignore any unknown versions that are present
2169 in that extension. Note that this mechanism makes it possible to
2170 negotiate a version prior to TLS 1.2 if one side supports a sparse
2171 range. Implementations of TLS 1.3 which choose to support prior
2172 versions of TLS SHOULD support TLS 1.2. Servers MUST be prepared to
2173 receive ClientHellos that include this extension but do not include
2174 0x0304 in the list of versions.
2175
2176 A server which negotiates a version of TLS prior to TLS 1.3 MUST set
2177 ServerHello.version and MUST NOT send the "supported_versions"
2178 extension. A server which negotiates TLS 1.3 MUST respond by sending
2179 a "supported_versions" extension containing the selected version
2180 value (0x0304). It MUST set the ServerHello.legacy_version field to
2181 0x0303 (TLS 1.2). Clients MUST check for this extension prior to
2182 processing the rest of the ServerHello (although they will have to
2183
2184
2185
2186Rescorla Standards Track [Page 39]
2187
2188RFC 8446 TLS August 2018
2189
2190
2191 parse the ServerHello in order to read the extension). If this
2192 extension is present, clients MUST ignore the
2193 ServerHello.legacy_version value and MUST use only the
2194 "supported_versions" extension to determine the selected version. If
2195 the "supported_versions" extension in the ServerHello contains a
2196 version not offered by the client or contains a version prior to
2197 TLS 1.3, the client MUST abort the handshake with an
2198 "illegal_parameter" alert.
2199
22004.2.2. Cookie
2201
2202 struct {
2203 opaque cookie<1..2^16-1>;
2204 } Cookie;
2205
2206 Cookies serve two primary purposes:
2207
2208 - Allowing the server to force the client to demonstrate
2209 reachability at their apparent network address (thus providing a
2210 measure of DoS protection). This is primarily useful for
2211 non-connection-oriented transports (see [RFC6347] for an example
2212 of this).
2213
2214 - Allowing the server to offload state to the client, thus allowing
2215 it to send a HelloRetryRequest without storing any state. The
2216 server can do this by storing the hash of the ClientHello in the
2217 HelloRetryRequest cookie (protected with some suitable integrity
2218 protection algorithm).
2219
2220 When sending a HelloRetryRequest, the server MAY provide a "cookie"
2221 extension to the client (this is an exception to the usual rule that
2222 the only extensions that may be sent are those that appear in the
2223 ClientHello). When sending the new ClientHello, the client MUST copy
2224 the contents of the extension received in the HelloRetryRequest into
2225 a "cookie" extension in the new ClientHello. Clients MUST NOT use
2226 cookies in their initial ClientHello in subsequent connections.
2227
2228 When a server is operating statelessly, it may receive an unprotected
2229 record of type change_cipher_spec between the first and second
2230 ClientHello (see Section 5). Since the server is not storing any
2231 state, this will appear as if it were the first message to be
2232 received. Servers operating statelessly MUST ignore these records.
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242Rescorla Standards Track [Page 40]
2243
2244RFC 8446 TLS August 2018
2245
2246
22474.2.3. Signature Algorithms
2248
2249 TLS 1.3 provides two extensions for indicating which signature
2250 algorithms may be used in digital signatures. The
2251 "signature_algorithms_cert" extension applies to signatures in
2252 certificates, and the "signature_algorithms" extension, which
2253 originally appeared in TLS 1.2, applies to signatures in
2254 CertificateVerify messages. The keys found in certificates MUST also
2255 be of appropriate type for the signature algorithms they are used
2256 with. This is a particular issue for RSA keys and PSS signatures, as
2257 described below. If no "signature_algorithms_cert" extension is
2258 present, then the "signature_algorithms" extension also applies to
2259 signatures appearing in certificates. Clients which desire the
2260 server to authenticate itself via a certificate MUST send the
2261 "signature_algorithms" extension. If a server is authenticating via
2262 a certificate and the client has not sent a "signature_algorithms"
2263 extension, then the server MUST abort the handshake with a
2264 "missing_extension" alert (see Section 9.2).
2265
2266 The "signature_algorithms_cert" extension was added to allow
2267 implementations which supported different sets of algorithms for
2268 certificates and in TLS itself to clearly signal their capabilities.
2269 TLS 1.2 implementations SHOULD also process this extension.
2270 Implementations which have the same policy in both cases MAY omit the
2271 "signature_algorithms_cert" extension.
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298Rescorla Standards Track [Page 41]
2299
2300RFC 8446 TLS August 2018
2301
2302
2303 The "extension_data" field of these extensions contains a
2304 SignatureSchemeList value:
2305
2306 enum {
2307 /* RSASSA-PKCS1-v1_5 algorithms */
2308 rsa_pkcs1_sha256(0x0401),
2309 rsa_pkcs1_sha384(0x0501),
2310 rsa_pkcs1_sha512(0x0601),
2311
2312 /* ECDSA algorithms */
2313 ecdsa_secp256r1_sha256(0x0403),
2314 ecdsa_secp384r1_sha384(0x0503),
2315 ecdsa_secp521r1_sha512(0x0603),
2316
2317 /* RSASSA-PSS algorithms with public key OID rsaEncryption */
2318 rsa_pss_rsae_sha256(0x0804),
2319 rsa_pss_rsae_sha384(0x0805),
2320 rsa_pss_rsae_sha512(0x0806),
2321
2322 /* EdDSA algorithms */
2323 ed25519(0x0807),
2324 ed448(0x0808),
2325
2326 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */
2327 rsa_pss_pss_sha256(0x0809),
2328 rsa_pss_pss_sha384(0x080a),
2329 rsa_pss_pss_sha512(0x080b),
2330
2331 /* Legacy algorithms */
2332 rsa_pkcs1_sha1(0x0201),
2333 ecdsa_sha1(0x0203),
2334
2335 /* Reserved Code Points */
2336 private_use(0xFE00..0xFFFF),
2337 (0xFFFF)
2338 } SignatureScheme;
2339
2340 struct {
2341 SignatureScheme supported_signature_algorithms<2..2^16-2>;
2342 } SignatureSchemeList;
2343
2344 Note: This enum is named "SignatureScheme" because there is already a
2345 "SignatureAlgorithm" type in TLS 1.2, which this replaces. We use
2346 the term "signature algorithm" throughout the text.
2347
2348
2349
2350
2351
2352
2353
2354Rescorla Standards Track [Page 42]
2355
2356RFC 8446 TLS August 2018
2357
2358
2359 Each SignatureScheme value lists a single signature algorithm that
2360 the client is willing to verify. The values are indicated in
2361 descending order of preference. Note that a signature algorithm
2362 takes as input an arbitrary-length message, rather than a digest.
2363 Algorithms which traditionally act on a digest should be defined in
2364 TLS to first hash the input with a specified hash algorithm and then
2365 proceed as usual. The code point groups listed above have the
2366 following meanings:
2367
2368 RSASSA-PKCS1-v1_5 algorithms: Indicates a signature algorithm using
2369 RSASSA-PKCS1-v1_5 [RFC8017] with the corresponding hash algorithm
2370 as defined in [SHS]. These values refer solely to signatures
2371 which appear in certificates (see Section 4.4.2.2) and are not
2372 defined for use in signed TLS handshake messages, although they
2373 MAY appear in "signature_algorithms" and
2374 "signature_algorithms_cert" for backward compatibility with
2375 TLS 1.2.
2376
2377 ECDSA algorithms: Indicates a signature algorithm using ECDSA
2378 [ECDSA], the corresponding curve as defined in ANSI X9.62 [ECDSA]
2379 and FIPS 186-4 [DSS], and the corresponding hash algorithm as
2380 defined in [SHS]. The signature is represented as a DER-encoded
2381 [X690] ECDSA-Sig-Value structure.
2382
2383 RSASSA-PSS RSAE algorithms: Indicates a signature algorithm using
2384 RSASSA-PSS [RFC8017] with mask generation function 1. The digest
2385 used in the mask generation function and the digest being signed
2386 are both the corresponding hash algorithm as defined in [SHS].
2387 The length of the Salt MUST be equal to the length of the output
2388 of the digest algorithm. If the public key is carried in an X.509
2389 certificate, it MUST use the rsaEncryption OID [RFC5280].
2390
2391 EdDSA algorithms: Indicates a signature algorithm using EdDSA as
2392 defined in [RFC8032] or its successors. Note that these
2393 correspond to the "PureEdDSA" algorithms and not the "prehash"
2394 variants.
2395
2396 RSASSA-PSS PSS algorithms: Indicates a signature algorithm using
2397 RSASSA-PSS [RFC8017] with mask generation function 1. The digest
2398 used in the mask generation function and the digest being signed
2399 are both the corresponding hash algorithm as defined in [SHS].
2400 The length of the Salt MUST be equal to the length of the digest
2401 algorithm. If the public key is carried in an X.509 certificate,
2402 it MUST use the RSASSA-PSS OID [RFC5756]. When used in
2403 certificate signatures, the algorithm parameters MUST be DER
2404 encoded. If the corresponding public key's parameters are
2405 present, then the parameters in the signature MUST be identical to
2406 those in the public key.
2407
2408
2409
2410Rescorla Standards Track [Page 43]
2411
2412RFC 8446 TLS August 2018
2413
2414
2415 Legacy algorithms: Indicates algorithms which are being deprecated
2416 because they use algorithms with known weaknesses, specifically
2417 SHA-1 which is used in this context with either (1) RSA using
2418 RSASSA-PKCS1-v1_5 or (2) ECDSA. These values refer solely to
2419 signatures which appear in certificates (see Section 4.4.2.2) and
2420 are not defined for use in signed TLS handshake messages, although
2421 they MAY appear in "signature_algorithms" and
2422 "signature_algorithms_cert" for backward compatibility with
2423 TLS 1.2. Endpoints SHOULD NOT negotiate these algorithms but are
2424 permitted to do so solely for backward compatibility. Clients
2425 offering these values MUST list them as the lowest priority
2426 (listed after all other algorithms in SignatureSchemeList).
2427 TLS 1.3 servers MUST NOT offer a SHA-1 signed certificate unless
2428 no valid certificate chain can be produced without it (see
2429 Section 4.4.2.2).
2430
2431 The signatures on certificates that are self-signed or certificates
2432 that are trust anchors are not validated, since they begin a
2433 certification path (see [RFC5280], Section 3.2). A certificate that
2434 begins a certification path MAY use a signature algorithm that is not
2435 advertised as being supported in the "signature_algorithms"
2436 extension.
2437
2438 Note that TLS 1.2 defines this extension differently. TLS 1.3
2439 implementations willing to negotiate TLS 1.2 MUST behave in
2440 accordance with the requirements of [RFC5246] when negotiating that
2441 version. In particular:
2442
2443 - TLS 1.2 ClientHellos MAY omit this extension.
2444
2445 - In TLS 1.2, the extension contained hash/signature pairs. The
2446 pairs are encoded in two octets, so SignatureScheme values have
2447 been allocated to align with TLS 1.2's encoding. Some legacy
2448 pairs are left unallocated. These algorithms are deprecated as of
2449 TLS 1.3. They MUST NOT be offered or negotiated by any
2450 implementation. In particular, MD5 [SLOTH], SHA-224, and DSA
2451 MUST NOT be used.
2452
2453 - ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature
2454 pairs. However, the old semantics did not constrain the signing
2455 curve. If TLS 1.2 is negotiated, implementations MUST be prepared
2456 to accept a signature that uses any curve that they advertised in
2457 the "supported_groups" extension.
2458
2459 - Implementations that advertise support for RSASSA-PSS (which is
2460 mandatory in TLS 1.3) MUST be prepared to accept a signature using
2461 that scheme even when TLS 1.2 is negotiated. In TLS 1.2,
2462 RSASSA-PSS is used with RSA cipher suites.
2463
2464
2465
2466Rescorla Standards Track [Page 44]
2467
2468RFC 8446 TLS August 2018
2469
2470
24714.2.4. Certificate Authorities
2472
2473 The "certificate_authorities" extension is used to indicate the
2474 certificate authorities (CAs) which an endpoint supports and which
2475 SHOULD be used by the receiving endpoint to guide certificate
2476 selection.
2477
2478 The body of the "certificate_authorities" extension consists of a
2479 CertificateAuthoritiesExtension structure.
2480
2481 opaque DistinguishedName<1..2^16-1>;
2482
2483 struct {
2484 DistinguishedName authorities<3..2^16-1>;
2485 } CertificateAuthoritiesExtension;
2486
2487 authorities: A list of the distinguished names [X501] of acceptable
2488 certificate authorities, represented in DER-encoded [X690] format.
2489 These distinguished names specify a desired distinguished name for
2490 a trust anchor or subordinate CA; thus, this message can be used
2491 to describe known trust anchors as well as a desired authorization
2492 space.
2493
2494 The client MAY send the "certificate_authorities" extension in the
2495 ClientHello message. The server MAY send it in the
2496 CertificateRequest message.
2497
2498 The "trusted_ca_keys" extension [RFC6066], which serves a similar
2499 purpose but is more complicated, is not used in TLS 1.3 (although it
2500 may appear in ClientHello messages from clients which are offering
2501 prior versions of TLS).
2502
25034.2.5. OID Filters
2504
2505 The "oid_filters" extension allows servers to provide a set of
2506 OID/value pairs which it would like the client's certificate to
2507 match. This extension, if provided by the server, MUST only be sent
2508 in the CertificateRequest message.
2509
2510 struct {
2511 opaque certificate_extension_oid<1..2^8-1>;
2512 opaque certificate_extension_values<0..2^16-1>;
2513 } OIDFilter;
2514
2515 struct {
2516 OIDFilter filters<0..2^16-1>;
2517 } OIDFilterExtension;
2518
2519
2520
2521
2522Rescorla Standards Track [Page 45]
2523
2524RFC 8446 TLS August 2018
2525
2526
2527 filters: A list of certificate extension OIDs [RFC5280] with their
2528 allowed value(s) and represented in DER-encoded [X690] format.
2529 Some certificate extension OIDs allow multiple values (e.g.,
2530 Extended Key Usage). If the server has included a non-empty
2531 filters list, the client certificate included in the response MUST
2532 contain all of the specified extension OIDs that the client
2533 recognizes. For each extension OID recognized by the client, all
2534 of the specified values MUST be present in the client certificate
2535 (but the certificate MAY have other values as well). However, the
2536 client MUST ignore and skip any unrecognized certificate extension
2537 OIDs. If the client ignored some of the required certificate
2538 extension OIDs and supplied a certificate that does not satisfy
2539 the request, the server MAY at its discretion either continue the
2540 connection without client authentication or abort the handshake
2541 with an "unsupported_certificate" alert. Any given OID MUST NOT
2542 appear more than once in the filters list.
2543
2544 PKIX RFCs define a variety of certificate extension OIDs and their
2545 corresponding value types. Depending on the type, matching
2546 certificate extension values are not necessarily bitwise-equal. It
2547 is expected that TLS implementations will rely on their PKI libraries
2548 to perform certificate selection using certificate extension OIDs.
2549
2550 This document defines matching rules for two standard certificate
2551 extensions defined in [RFC5280]:
2552
2553 - The Key Usage extension in a certificate matches the request when
2554 all key usage bits asserted in the request are also asserted in
2555 the Key Usage certificate extension.
2556
2557 - The Extended Key Usage extension in a certificate matches the
2558 request when all key purpose OIDs present in the request are also
2559 found in the Extended Key Usage certificate extension. The
2560 special anyExtendedKeyUsage OID MUST NOT be used in the request.
2561
2562 Separate specifications may define matching rules for other
2563 certificate extensions.
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578Rescorla Standards Track [Page 46]
2579
2580RFC 8446 TLS August 2018
2581
2582
25834.2.6. Post-Handshake Client Authentication
2584
2585 The "post_handshake_auth" extension is used to indicate that a client
2586 is willing to perform post-handshake authentication (Section 4.6.2).
2587 Servers MUST NOT send a post-handshake CertificateRequest to clients
2588 which do not offer this extension. Servers MUST NOT send this
2589 extension.
2590
2591 struct {} PostHandshakeAuth;
2592
2593 The "extension_data" field of the "post_handshake_auth" extension is
2594 zero length.
2595
25964.2.7. Supported Groups
2597
2598 When sent by the client, the "supported_groups" extension indicates
2599 the named groups which the client supports for key exchange, ordered
2600 from most preferred to least preferred.
2601
2602 Note: In versions of TLS prior to TLS 1.3, this extension was named
2603 "elliptic_curves" and only contained elliptic curve groups. See
2604 [RFC8422] and [RFC7919]. This extension was also used to negotiate
2605 ECDSA curves. Signature algorithms are now negotiated independently
2606 (see Section 4.2.3).
2607
2608 The "extension_data" field of this extension contains a
2609 "NamedGroupList" value:
2610
2611 enum {
2612
2613 /* Elliptic Curve Groups (ECDHE) */
2614 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019),
2615 x25519(0x001D), x448(0x001E),
2616
2617 /* Finite Field Groups (DHE) */
2618 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102),
2619 ffdhe6144(0x0103), ffdhe8192(0x0104),
2620
2621 /* Reserved Code Points */
2622 ffdhe_private_use(0x01FC..0x01FF),
2623 ecdhe_private_use(0xFE00..0xFEFF),
2624 (0xFFFF)
2625 } NamedGroup;
2626
2627 struct {
2628 NamedGroup named_group_list<2..2^16-1>;
2629 } NamedGroupList;
2630
2631
2632
2633
2634Rescorla Standards Track [Page 47]
2635
2636RFC 8446 TLS August 2018
2637
2638
2639 Elliptic Curve Groups (ECDHE): Indicates support for the
2640 corresponding named curve, defined in either FIPS 186-4 [DSS] or
2641 [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for
2642 Private Use [RFC8126].
2643
2644 Finite Field Groups (DHE): Indicates support for the corresponding
2645 finite field group, defined in [RFC7919]. Values 0x01FC through
2646 0x01FF are reserved for Private Use.
2647
2648 Items in named_group_list are ordered according to the sender's
2649 preferences (most preferred choice first).
2650
2651 As of TLS 1.3, servers are permitted to send the "supported_groups"
2652 extension to the client. Clients MUST NOT act upon any information
2653 found in "supported_groups" prior to successful completion of the
2654 handshake but MAY use the information learned from a successfully
2655 completed handshake to change what groups they use in their
2656 "key_share" extension in subsequent connections. If the server has a
2657 group it prefers to the ones in the "key_share" extension but is
2658 still willing to accept the ClientHello, it SHOULD send
2659 "supported_groups" to update the client's view of its preferences;
2660 this extension SHOULD contain all groups the server supports,
2661 regardless of whether they are currently supported by the client.
2662
26634.2.8. Key Share
2664
2665 The "key_share" extension contains the endpoint's cryptographic
2666 parameters.
2667
2668 Clients MAY send an empty client_shares vector in order to request
2669 group selection from the server, at the cost of an additional round
2670 trip (see Section 4.1.4).
2671
2672 struct {
2673 NamedGroup group;
2674 opaque key_exchange<1..2^16-1>;
2675 } KeyShareEntry;
2676
2677 group: The named group for the key being exchanged.
2678
2679 key_exchange: Key exchange information. The contents of this field
2680 are determined by the specified group and its corresponding
2681 definition. Finite Field Diffie-Hellman [DH76] parameters are
2682 described in Section 4.2.8.1; Elliptic Curve Diffie-Hellman
2683 parameters are described in Section 4.2.8.2.
2684
2685
2686
2687
2688
2689
2690Rescorla Standards Track [Page 48]
2691
2692RFC 8446 TLS August 2018
2693
2694
2695 In the ClientHello message, the "extension_data" field of this
2696 extension contains a "KeyShareClientHello" value:
2697
2698 struct {
2699 KeyShareEntry client_shares<0..2^16-1>;
2700 } KeyShareClientHello;
2701
2702 client_shares: A list of offered KeyShareEntry values in descending
2703 order of client preference.
2704
2705 This vector MAY be empty if the client is requesting a
2706 HelloRetryRequest. Each KeyShareEntry value MUST correspond to a
2707 group offered in the "supported_groups" extension and MUST appear in
2708 the same order. However, the values MAY be a non-contiguous subset
2709 of the "supported_groups" extension and MAY omit the most preferred
2710 groups. Such a situation could arise if the most preferred groups
2711 are new and unlikely to be supported in enough places to make
2712 pregenerating key shares for them efficient.
2713
2714 Clients can offer as many KeyShareEntry values as the number of
2715 supported groups it is offering, each representing a single set of
2716 key exchange parameters. For instance, a client might offer shares
2717 for several elliptic curves or multiple FFDHE groups. The
2718 key_exchange values for each KeyShareEntry MUST be generated
2719 independently. Clients MUST NOT offer multiple KeyShareEntry values
2720 for the same group. Clients MUST NOT offer any KeyShareEntry values
2721 for groups not listed in the client's "supported_groups" extension.
2722 Servers MAY check for violations of these rules and abort the
2723 handshake with an "illegal_parameter" alert if one is violated.
2724
2725 In a HelloRetryRequest message, the "extension_data" field of this
2726 extension contains a KeyShareHelloRetryRequest value:
2727
2728 struct {
2729 NamedGroup selected_group;
2730 } KeyShareHelloRetryRequest;
2731
2732 selected_group: The mutually supported group the server intends to
2733 negotiate and is requesting a retried ClientHello/KeyShare for.
2734
2735 Upon receipt of this extension in a HelloRetryRequest, the client
2736 MUST verify that (1) the selected_group field corresponds to a group
2737 which was provided in the "supported_groups" extension in the
2738 original ClientHello and (2) the selected_group field does not
2739 correspond to a group which was provided in the "key_share" extension
2740 in the original ClientHello. If either of these checks fails, then
2741 the client MUST abort the handshake with an "illegal_parameter"
2742 alert. Otherwise, when sending the new ClientHello, the client MUST
2743
2744
2745
2746Rescorla Standards Track [Page 49]
2747
2748RFC 8446 TLS August 2018
2749
2750
2751 replace the original "key_share" extension with one containing only a
2752 new KeyShareEntry for the group indicated in the selected_group field
2753 of the triggering HelloRetryRequest.
2754
2755 In a ServerHello message, the "extension_data" field of this
2756 extension contains a KeyShareServerHello value:
2757
2758 struct {
2759 KeyShareEntry server_share;
2760 } KeyShareServerHello;
2761
2762 server_share: A single KeyShareEntry value that is in the same group
2763 as one of the client's shares.
2764
2765 If using (EC)DHE key establishment, servers offer exactly one
2766 KeyShareEntry in the ServerHello. This value MUST be in the same
2767 group as the KeyShareEntry value offered by the client that the
2768 server has selected for the negotiated key exchange. Servers
2769 MUST NOT send a KeyShareEntry for any group not indicated in the
2770 client's "supported_groups" extension and MUST NOT send a
2771 KeyShareEntry when using the "psk_ke" PskKeyExchangeMode. If using
2772 (EC)DHE key establishment and a HelloRetryRequest containing a
2773 "key_share" extension was received by the client, the client MUST
2774 verify that the selected NamedGroup in the ServerHello is the same as
2775 that in the HelloRetryRequest. If this check fails, the client MUST
2776 abort the handshake with an "illegal_parameter" alert.
2777
27784.2.8.1. Diffie-Hellman Parameters
2779
2780 Diffie-Hellman [DH76] parameters for both clients and servers are
2781 encoded in the opaque key_exchange field of a KeyShareEntry in a
2782 KeyShare structure. The opaque value contains the Diffie-Hellman
2783 public value (Y = g^X mod p) for the specified group (see [RFC7919]
2784 for group definitions) encoded as a big-endian integer and padded to
2785 the left with zeros to the size of p in bytes.
2786
2787 Note: For a given Diffie-Hellman group, the padding results in all
2788 public keys having the same length.
2789
2790 Peers MUST validate each other's public key Y by ensuring that 1 < Y
2791 < p-1. This check ensures that the remote peer is properly behaved
2792 and isn't forcing the local system into a small subgroup.
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802Rescorla Standards Track [Page 50]
2803
2804RFC 8446 TLS August 2018
2805
2806
28074.2.8.2. ECDHE Parameters
2808
2809 ECDHE parameters for both clients and servers are encoded in the
2810 opaque key_exchange field of a KeyShareEntry in a KeyShare structure.
2811
2812 For secp256r1, secp384r1, and secp521r1, the contents are the
2813 serialized value of the following struct:
2814
2815 struct {
2816 uint8 legacy_form = 4;
2817 opaque X[coordinate_length];
2818 opaque Y[coordinate_length];
2819 } UncompressedPointRepresentation;
2820
2821 X and Y, respectively, are the binary representations of the x and y
2822 values in network byte order. There are no internal length markers,
2823 so each number representation occupies as many octets as implied by
2824 the curve parameters. For P-256, this means that each of X and Y use
2825 32 octets, padded on the left by zeros if necessary. For P-384, they
2826 take 48 octets each. For P-521, they take 66 octets each.
2827
2828 For the curves secp256r1, secp384r1, and secp521r1, peers MUST
2829 validate each other's public value Q by ensuring that the point is a
2830 valid point on the elliptic curve. The appropriate validation
2831 procedures are defined in Section 4.3.7 of [ECDSA] and alternatively
2832 in Section 5.6.2.3 of [KEYAGREEMENT]. This process consists of three
2833 steps: (1) verify that Q is not the point at infinity (O), (2) verify
2834 that for Q = (x, y) both integers x and y are in the correct
2835 interval, and (3) ensure that (x, y) is a correct solution to the
2836 elliptic curve equation. For these curves, implementors do not need
2837 to verify membership in the correct subgroup.
2838
2839 For X25519 and X448, the contents of the public value are the byte
2840 string inputs and outputs of the corresponding functions defined in
2841 [RFC7748]: 32 bytes for X25519 and 56 bytes for X448.
2842
2843 Note: Versions of TLS prior to 1.3 permitted point format
2844 negotiation; TLS 1.3 removes this feature in favor of a single point
2845 format for each curve.
2846
28474.2.9. Pre-Shared Key Exchange Modes
2848
2849 In order to use PSKs, clients MUST also send a
2850 "psk_key_exchange_modes" extension. The semantics of this extension
2851 are that the client only supports the use of PSKs with these modes,
2852 which restricts both the use of PSKs offered in this ClientHello and
2853 those which the server might supply via NewSessionTicket.
2854
2855
2856
2857
2858Rescorla Standards Track [Page 51]
2859
2860RFC 8446 TLS August 2018
2861
2862
2863 A client MUST provide a "psk_key_exchange_modes" extension if it
2864 offers a "pre_shared_key" extension. If clients offer
2865 "pre_shared_key" without a "psk_key_exchange_modes" extension,
2866 servers MUST abort the handshake. Servers MUST NOT select a key
2867 exchange mode that is not listed by the client. This extension also
2868 restricts the modes for use with PSK resumption. Servers SHOULD NOT
2869 send NewSessionTicket with tickets that are not compatible with the
2870 advertised modes; however, if a server does so, the impact will just
2871 be that the client's attempts at resumption fail.
2872
2873 The server MUST NOT send a "psk_key_exchange_modes" extension.
2874
2875 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode;
2876
2877 struct {
2878 PskKeyExchangeMode ke_modes<1..255>;
2879 } PskKeyExchangeModes;
2880
2881 psk_ke: PSK-only key establishment. In this mode, the server
2882 MUST NOT supply a "key_share" value.
2883
2884 psk_dhe_ke: PSK with (EC)DHE key establishment. In this mode, the
2885 client and server MUST supply "key_share" values as described in
2886 Section 4.2.8.
2887
2888 Any future values that are allocated must ensure that the transmitted
2889 protocol messages unambiguously identify which mode was selected by
2890 the server; at present, this is indicated by the presence of the
2891 "key_share" in the ServerHello.
2892
28934.2.10. Early Data Indication
2894
2895 When a PSK is used and early data is allowed for that PSK, the client
2896 can send Application Data in its first flight of messages. If the
2897 client opts to do so, it MUST supply both the "pre_shared_key" and
2898 "early_data" extensions.
2899
2900 The "extension_data" field of this extension contains an
2901 "EarlyDataIndication" value.
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914Rescorla Standards Track [Page 52]
2915
2916RFC 8446 TLS August 2018
2917
2918
2919 struct {} Empty;
2920
2921 struct {
2922 select (Handshake.msg_type) {
2923 case new_session_ticket: uint32 max_early_data_size;
2924 case client_hello: Empty;
2925 case encrypted_extensions: Empty;
2926 };
2927 } EarlyDataIndication;
2928
2929 See Section 4.6.1 for details regarding the use of the
2930 max_early_data_size field.
2931
2932 The parameters for the 0-RTT data (version, symmetric cipher suite,
2933 Application-Layer Protocol Negotiation (ALPN) [RFC7301] protocol,
2934 etc.) are those associated with the PSK in use. For externally
2935 provisioned PSKs, the associated values are those provisioned along
2936 with the key. For PSKs established via a NewSessionTicket message,
2937 the associated values are those which were negotiated in the
2938 connection which established the PSK. The PSK used to encrypt the
2939 early data MUST be the first PSK listed in the client's
2940 "pre_shared_key" extension.
2941
2942 For PSKs provisioned via NewSessionTicket, a server MUST validate
2943 that the ticket age for the selected PSK identity (computed by
2944 subtracting ticket_age_add from PskIdentity.obfuscated_ticket_age
2945 modulo 2^32) is within a small tolerance of the time since the ticket
2946 was issued (see Section 8). If it is not, the server SHOULD proceed
2947 with the handshake but reject 0-RTT, and SHOULD NOT take any other
2948 action that assumes that this ClientHello is fresh.
2949
2950 0-RTT messages sent in the first flight have the same (encrypted)
2951 content types as messages of the same type sent in other flights
2952 (handshake and application_data) but are protected under different
2953 keys. After receiving the server's Finished message, if the server
2954 has accepted early data, an EndOfEarlyData message will be sent to
2955 indicate the key change. This message will be encrypted with the
2956 0-RTT traffic keys.
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970Rescorla Standards Track [Page 53]
2971
2972RFC 8446 TLS August 2018
2973
2974
2975 A server which receives an "early_data" extension MUST behave in one
2976 of three ways:
2977
2978 - Ignore the extension and return a regular 1-RTT response. The
2979 server then skips past early data by attempting to deprotect
2980 received records using the handshake traffic key, discarding
2981 records which fail deprotection (up to the configured
2982 max_early_data_size). Once a record is deprotected successfully,
2983 it is treated as the start of the client's second flight and the
2984 server proceeds as with an ordinary 1-RTT handshake.
2985
2986 - Request that the client send another ClientHello by responding
2987 with a HelloRetryRequest. A client MUST NOT include the
2988 "early_data" extension in its followup ClientHello. The server
2989 then ignores early data by skipping all records with an external
2990 content type of "application_data" (indicating that they are
2991 encrypted), up to the configured max_early_data_size.
2992
2993 - Return its own "early_data" extension in EncryptedExtensions,
2994 indicating that it intends to process the early data. It is not
2995 possible for the server to accept only a subset of the early data
2996 messages. Even though the server sends a message accepting early
2997 data, the actual early data itself may already be in flight by the
2998 time the server generates this message.
2999
3000 In order to accept early data, the server MUST have accepted a PSK
3001 cipher suite and selected the first key offered in the client's
3002 "pre_shared_key" extension. In addition, it MUST verify that the
3003 following values are the same as those associated with the
3004 selected PSK:
3005
3006 - The TLS version number
3007
3008 - The selected cipher suite
3009
3010 - The selected ALPN [RFC7301] protocol, if any
3011
3012 These requirements are a superset of those needed to perform a 1-RTT
3013 handshake using the PSK in question. For externally established
3014 PSKs, the associated values are those provisioned along with the key.
3015 For PSKs established via a NewSessionTicket message, the associated
3016 values are those negotiated in the connection during which the ticket
3017 was established.
3018
3019 Future extensions MUST define their interaction with 0-RTT.
3020
3021
3022
3023
3024
3025
3026Rescorla Standards Track [Page 54]
3027
3028RFC 8446 TLS August 2018
3029
3030
3031 If any of these checks fail, the server MUST NOT respond with the
3032 extension and must discard all the first-flight data using one of the
3033 first two mechanisms listed above (thus falling back to 1-RTT or
3034 2-RTT). If the client attempts a 0-RTT handshake but the server
3035 rejects it, the server will generally not have the 0-RTT record
3036 protection keys and must instead use trial decryption (either with
3037 the 1-RTT handshake keys or by looking for a cleartext ClientHello in
3038 the case of a HelloRetryRequest) to find the first non-0-RTT message.
3039
3040 If the server chooses to accept the "early_data" extension, then it
3041 MUST comply with the same error-handling requirements specified for
3042 all records when processing early data records. Specifically, if the
3043 server fails to decrypt a 0-RTT record following an accepted
3044 "early_data" extension, it MUST terminate the connection with a
3045 "bad_record_mac" alert as per Section 5.2.
3046
3047 If the server rejects the "early_data" extension, the client
3048 application MAY opt to retransmit the Application Data previously
3049 sent in early data once the handshake has been completed. Note that
3050 automatic retransmission of early data could result in incorrect
3051 assumptions regarding the status of the connection. For instance,
3052 when the negotiated connection selects a different ALPN protocol from
3053 what was used for the early data, an application might need to
3054 construct different messages. Similarly, if early data assumes
3055 anything about the connection state, it might be sent in error after
3056 the handshake completes.
3057
3058 A TLS implementation SHOULD NOT automatically resend early data;
3059 applications are in a better position to decide when retransmission
3060 is appropriate. A TLS implementation MUST NOT automatically resend
3061 early data unless the negotiated connection selects the same ALPN
3062 protocol.
3063
30644.2.11. Pre-Shared Key Extension
3065
3066 The "pre_shared_key" extension is used to negotiate the identity of
3067 the pre-shared key to be used with a given handshake in association
3068 with PSK key establishment.
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082Rescorla Standards Track [Page 55]
3083
3084RFC 8446 TLS August 2018
3085
3086
3087 The "extension_data" field of this extension contains a
3088 "PreSharedKeyExtension" value:
3089
3090 struct {
3091 opaque identity<1..2^16-1>;
3092 uint32 obfuscated_ticket_age;
3093 } PskIdentity;
3094
3095 opaque PskBinderEntry<32..255>;
3096
3097 struct {
3098 PskIdentity identities<7..2^16-1>;
3099 PskBinderEntry binders<33..2^16-1>;
3100 } OfferedPsks;
3101
3102 struct {
3103 select (Handshake.msg_type) {
3104 case client_hello: OfferedPsks;
3105 case server_hello: uint16 selected_identity;
3106 };
3107 } PreSharedKeyExtension;
3108
3109 identity: A label for a key. For instance, a ticket (as defined in
3110 Appendix B.3.4) or a label for a pre-shared key established
3111 externally.
3112
3113 obfuscated_ticket_age: An obfuscated version of the age of the key.
3114 Section 4.2.11.1 describes how to form this value for identities
3115 established via the NewSessionTicket message. For identities
3116 established externally, an obfuscated_ticket_age of 0 SHOULD be
3117 used, and servers MUST ignore the value.
3118
3119 identities: A list of the identities that the client is willing to
3120 negotiate with the server. If sent alongside the "early_data"
3121 extension (see Section 4.2.10), the first identity is the one used
3122 for 0-RTT data.
3123
3124 binders: A series of HMAC values, one for each value in the
3125 identities list and in the same order, computed as described
3126 below.
3127
3128 selected_identity: The server's chosen identity expressed as a
3129 (0-based) index into the identities in the client's list.
3130
3131 Each PSK is associated with a single Hash algorithm. For PSKs
3132 established via the ticket mechanism (Section 4.6.1), this is the KDF
3133 Hash algorithm on the connection where the ticket was established.
3134 For externally established PSKs, the Hash algorithm MUST be set when
3135
3136
3137
3138Rescorla Standards Track [Page 56]
3139
3140RFC 8446 TLS August 2018
3141
3142
3143 the PSK is established or default to SHA-256 if no such algorithm is
3144 defined. The server MUST ensure that it selects a compatible PSK
3145 (if any) and cipher suite.
3146
3147 In TLS versions prior to TLS 1.3, the Server Name Identification
3148 (SNI) value was intended to be associated with the session (Section 3
3149 of [RFC6066]), with the server being required to enforce that the SNI
3150 value associated with the session matches the one specified in the
3151 resumption handshake. However, in reality the implementations were
3152 not consistent on which of two supplied SNI values they would use,
3153 leading to the consistency requirement being de facto enforced by the
3154 clients. In TLS 1.3, the SNI value is always explicitly specified in
3155 the resumption handshake, and there is no need for the server to
3156 associate an SNI value with the ticket. Clients, however, SHOULD
3157 store the SNI with the PSK to fulfill the requirements of
3158 Section 4.6.1.
3159
3160 Implementor's note: When session resumption is the primary use case
3161 of PSKs, the most straightforward way to implement the PSK/cipher
3162 suite matching requirements is to negotiate the cipher suite first
3163 and then exclude any incompatible PSKs. Any unknown PSKs (e.g., ones
3164 not in the PSK database or encrypted with an unknown key) SHOULD
3165 simply be ignored. If no acceptable PSKs are found, the server
3166 SHOULD perform a non-PSK handshake if possible. If backward
3167 compatibility is important, client-provided, externally established
3168 PSKs SHOULD influence cipher suite selection.
3169
3170 Prior to accepting PSK key establishment, the server MUST validate
3171 the corresponding binder value (see Section 4.2.11.2 below). If this
3172 value is not present or does not validate, the server MUST abort the
3173 handshake. Servers SHOULD NOT attempt to validate multiple binders;
3174 rather, they SHOULD select a single PSK and validate solely the
3175 binder that corresponds to that PSK. See Section 8.2 and
3176 Appendix E.6 for the security rationale for this requirement. In
3177 order to accept PSK key establishment, the server sends a
3178 "pre_shared_key" extension indicating the selected identity.
3179
3180 Clients MUST verify that the server's selected_identity is within the
3181 range supplied by the client, that the server selected a cipher suite
3182 indicating a Hash associated with the PSK, and that a server
3183 "key_share" extension is present if required by the ClientHello
3184 "psk_key_exchange_modes" extension. If these values are not
3185 consistent, the client MUST abort the handshake with an
3186 "illegal_parameter" alert.
3187
3188
3189
3190
3191
3192
3193
3194Rescorla Standards Track [Page 57]
3195
3196RFC 8446 TLS August 2018
3197
3198
3199 If the server supplies an "early_data" extension, the client MUST
3200 verify that the server's selected_identity is 0. If any other value
3201 is returned, the client MUST abort the handshake with an
3202 "illegal_parameter" alert.
3203
3204 The "pre_shared_key" extension MUST be the last extension in the
3205 ClientHello (this facilitates implementation as described below).
3206 Servers MUST check that it is the last extension and otherwise fail
3207 the handshake with an "illegal_parameter" alert.
3208
32094.2.11.1. Ticket Age
3210
3211 The client's view of the age of a ticket is the time since the
3212 receipt of the NewSessionTicket message. Clients MUST NOT attempt to
3213 use tickets which have ages greater than the "ticket_lifetime" value
3214 which was provided with the ticket. The "obfuscated_ticket_age"
3215 field of each PskIdentity contains an obfuscated version of the
3216 ticket age formed by taking the age in milliseconds and adding the
3217 "ticket_age_add" value that was included with the ticket (see
3218 Section 4.6.1), modulo 2^32. This addition prevents passive
3219 observers from correlating connections unless tickets are reused.
3220 Note that the "ticket_lifetime" field in the NewSessionTicket message
3221 is in seconds but the "obfuscated_ticket_age" is in milliseconds.
3222 Because ticket lifetimes are restricted to a week, 32 bits is enough
3223 to represent any plausible age, even in milliseconds.
3224
32254.2.11.2. PSK Binder
3226
3227 The PSK binder value forms a binding between a PSK and the current
3228 handshake, as well as a binding between the handshake in which the
3229 PSK was generated (if via a NewSessionTicket message) and the current
3230 handshake. Each entry in the binders list is computed as an HMAC
3231 over a transcript hash (see Section 4.4.1) containing a partial
3232 ClientHello up to and including the PreSharedKeyExtension.identities
3233 field. That is, it includes all of the ClientHello but not the
3234 binders list itself. The length fields for the message (including
3235 the overall length, the length of the extensions block, and the
3236 length of the "pre_shared_key" extension) are all set as if binders
3237 of the correct lengths were present.
3238
3239 The PskBinderEntry is computed in the same way as the Finished
3240 message (Section 4.4.4) but with the BaseKey being the binder_key
3241 derived via the key schedule from the corresponding PSK which is
3242 being offered (see Section 7.1).
3243
3244
3245
3246
3247
3248
3249
3250Rescorla Standards Track [Page 58]
3251
3252RFC 8446 TLS August 2018
3253
3254
3255 If the handshake includes a HelloRetryRequest, the initial
3256 ClientHello and HelloRetryRequest are included in the transcript
3257 along with the new ClientHello. For instance, if the client sends
3258 ClientHello1, its binder will be computed over:
3259
3260 Transcript-Hash(Truncate(ClientHello1))
3261
3262 Where Truncate() removes the binders list from the ClientHello.
3263
3264 If the server responds with a HelloRetryRequest and the client then
3265 sends ClientHello2, its binder will be computed over:
3266
3267 Transcript-Hash(ClientHello1,
3268 HelloRetryRequest,
3269 Truncate(ClientHello2))
3270
3271 The full ClientHello1/ClientHello2 is included in all other handshake
3272 hash computations. Note that in the first flight,
3273 Truncate(ClientHello1) is hashed directly, but in the second flight,
3274 ClientHello1 is hashed and then reinjected as a "message_hash"
3275 message, as described in Section 4.4.1.
3276
32774.2.11.3. Processing Order
3278
3279 Clients are permitted to "stream" 0-RTT data until they receive the
3280 server's Finished, only then sending the EndOfEarlyData message,
3281 followed by the rest of the handshake. In order to avoid deadlocks,
3282 when accepting "early_data", servers MUST process the client's
3283 ClientHello and then immediately send their flight of messages,
3284 rather than waiting for the client's EndOfEarlyData message before
3285 sending its ServerHello.
3286
32874.3. Server Parameters
3288
3289 The next two messages from the server, EncryptedExtensions and
3290 CertificateRequest, contain information from the server that
3291 determines the rest of the handshake. These messages are encrypted
3292 with keys derived from the server_handshake_traffic_secret.
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306Rescorla Standards Track [Page 59]
3307
3308RFC 8446 TLS August 2018
3309
3310
33114.3.1. Encrypted Extensions
3312
3313 In all handshakes, the server MUST send the EncryptedExtensions
3314 message immediately after the ServerHello message. This is the first
3315 message that is encrypted under keys derived from the
3316 server_handshake_traffic_secret.
3317
3318 The EncryptedExtensions message contains extensions that can be
3319 protected, i.e., any which are not needed to establish the
3320 cryptographic context but which are not associated with individual
3321 certificates. The client MUST check EncryptedExtensions for the
3322 presence of any forbidden extensions and if any are found MUST abort
3323 the handshake with an "illegal_parameter" alert.
3324
3325 Structure of this message:
3326
3327 struct {
3328 Extension extensions<0..2^16-1>;
3329 } EncryptedExtensions;
3330
3331 extensions: A list of extensions. For more information, see the
3332 table in Section 4.2.
3333
33344.3.2. Certificate Request
3335
3336 A server which is authenticating with a certificate MAY optionally
3337 request a certificate from the client. This message, if sent, MUST
3338 follow EncryptedExtensions.
3339
3340 Structure of this message:
3341
3342 struct {
3343 opaque certificate_request_context<0..2^8-1>;
3344 Extension extensions<2..2^16-1>;
3345 } CertificateRequest;
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362Rescorla Standards Track [Page 60]
3363
3364RFC 8446 TLS August 2018
3365
3366
3367 certificate_request_context: An opaque string which identifies the
3368 certificate request and which will be echoed in the client's
3369 Certificate message. The certificate_request_context MUST be
3370 unique within the scope of this connection (thus preventing replay
3371 of client CertificateVerify messages). This field SHALL be zero
3372 length unless used for the post-handshake authentication exchanges
3373 described in Section 4.6.2. When requesting post-handshake
3374 authentication, the server SHOULD make the context unpredictable
3375 to the client (e.g., by randomly generating it) in order to
3376 prevent an attacker who has temporary access to the client's
3377 private key from pre-computing valid CertificateVerify messages.
3378
3379 extensions: A set of extensions describing the parameters of the
3380 certificate being requested. The "signature_algorithms" extension
3381 MUST be specified, and other extensions may optionally be included
3382 if defined for this message. Clients MUST ignore unrecognized
3383 extensions.
3384
3385 In prior versions of TLS, the CertificateRequest message carried a
3386 list of signature algorithms and certificate authorities which the
3387 server would accept. In TLS 1.3, the former is expressed by sending
3388 the "signature_algorithms" and optionally "signature_algorithms_cert"
3389 extensions. The latter is expressed by sending the
3390 "certificate_authorities" extension (see Section 4.2.4).
3391
3392 Servers which are authenticating with a PSK MUST NOT send the
3393 CertificateRequest message in the main handshake, though they MAY
3394 send it in post-handshake authentication (see Section 4.6.2) provided
3395 that the client has sent the "post_handshake_auth" extension (see
3396 Section 4.2.6).
3397
33984.4. Authentication Messages
3399
3400 As discussed in Section 2, TLS generally uses a common set of
3401 messages for authentication, key confirmation, and handshake
3402 integrity: Certificate, CertificateVerify, and Finished. (The PSK
3403 binders also perform key confirmation, in a similar fashion.) These
3404 three messages are always sent as the last messages in their
3405 handshake flight. The Certificate and CertificateVerify messages are
3406 only sent under certain circumstances, as defined below. The
3407 Finished message is always sent as part of the Authentication Block.
3408 These messages are encrypted under keys derived from the
3409 [sender]_handshake_traffic_secret.
3410
3411
3412
3413
3414
3415
3416
3417
3418Rescorla Standards Track [Page 61]
3419
3420RFC 8446 TLS August 2018
3421
3422
3423 The computations for the Authentication messages all uniformly take
3424 the following inputs:
3425
3426 - The certificate and signing key to be used.
3427
3428 - A Handshake Context consisting of the set of messages to be
3429 included in the transcript hash.
3430
3431 - A Base Key to be used to compute a MAC key.
3432
3433 Based on these inputs, the messages then contain:
3434
3435 Certificate: The certificate to be used for authentication, and any
3436 supporting certificates in the chain. Note that certificate-based
3437 client authentication is not available in PSK handshake flows
3438 (including 0-RTT).
3439
3440 CertificateVerify: A signature over the value
3441 Transcript-Hash(Handshake Context, Certificate).
3442
3443 Finished: A MAC over the value Transcript-Hash(Handshake Context,
3444 Certificate, CertificateVerify) using a MAC key derived from the
3445 Base Key.
3446
3447 The following table defines the Handshake Context and MAC Base Key
3448 for each scenario:
3449
3450 +-----------+-------------------------+-----------------------------+
3451 | Mode | Handshake Context | Base Key |
3452 +-----------+-------------------------+-----------------------------+
3453 | Server | ClientHello ... later | server_handshake_traffic_ |
3454 | | of EncryptedExtensions/ | secret |
3455 | | CertificateRequest | |
3456 | | | |
3457 | Client | ClientHello ... later | client_handshake_traffic_ |
3458 | | of server | secret |
3459 | | Finished/EndOfEarlyData | |
3460 | | | |
3461 | Post- | ClientHello ... client | client_application_traffic_ |
3462 | Handshake | Finished + | secret_N |
3463 | | CertificateRequest | |
3464 +-----------+-------------------------+-----------------------------+
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474Rescorla Standards Track [Page 62]
3475
3476RFC 8446 TLS August 2018
3477
3478
34794.4.1. The Transcript Hash
3480
3481 Many of the cryptographic computations in TLS make use of a
3482 transcript hash. This value is computed by hashing the concatenation
3483 of each included handshake message, including the handshake message
3484 header carrying the handshake message type and length fields, but not
3485 including record layer headers. I.e.,
3486
3487 Transcript-Hash(M1, M2, ... Mn) = Hash(M1 || M2 || ... || Mn)
3488
3489 As an exception to this general rule, when the server responds to a
3490 ClientHello with a HelloRetryRequest, the value of ClientHello1 is
3491 replaced with a special synthetic handshake message of handshake type
3492 "message_hash" containing Hash(ClientHello1). I.e.,
3493
3494 Transcript-Hash(ClientHello1, HelloRetryRequest, ... Mn) =
3495 Hash(message_hash || /* Handshake type */
3496 00 00 Hash.length || /* Handshake message length (bytes) */
3497 Hash(ClientHello1) || /* Hash of ClientHello1 */
3498 HelloRetryRequest || ... || Mn)
3499
3500 The reason for this construction is to allow the server to do a
3501 stateless HelloRetryRequest by storing just the hash of ClientHello1
3502 in the cookie, rather than requiring it to export the entire
3503 intermediate hash state (see Section 4.2.2).
3504
3505 For concreteness, the transcript hash is always taken from the
3506 following sequence of handshake messages, starting at the first
3507 ClientHello and including only those messages that were sent:
3508 ClientHello, HelloRetryRequest, ClientHello, ServerHello,
3509 EncryptedExtensions, server CertificateRequest, server Certificate,
3510 server CertificateVerify, server Finished, EndOfEarlyData, client
3511 Certificate, client CertificateVerify, client Finished.
3512
3513 In general, implementations can implement the transcript by keeping a
3514 running transcript hash value based on the negotiated hash. Note,
3515 however, that subsequent post-handshake authentications do not
3516 include each other, just the messages through the end of the main
3517 handshake.
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530Rescorla Standards Track [Page 63]
3531
3532RFC 8446 TLS August 2018
3533
3534
35354.4.2. Certificate
3536
3537 This message conveys the endpoint's certificate chain to the peer.
3538
3539 The server MUST send a Certificate message whenever the agreed-upon
3540 key exchange method uses certificates for authentication (this
3541 includes all key exchange methods defined in this document
3542 except PSK).
3543
3544 The client MUST send a Certificate message if and only if the server
3545 has requested client authentication via a CertificateRequest message
3546 (Section 4.3.2). If the server requests client authentication but no
3547 suitable certificate is available, the client MUST send a Certificate
3548 message containing no certificates (i.e., with the "certificate_list"
3549 field having length 0). A Finished message MUST be sent regardless
3550 of whether the Certificate message is empty.
3551
3552 Structure of this message:
3553
3554 enum {
3555 X509(0),
3556 RawPublicKey(2),
3557 (255)
3558 } CertificateType;
3559
3560 struct {
3561 select (certificate_type) {
3562 case RawPublicKey:
3563 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */
3564 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>;
3565
3566 case X509:
3567 opaque cert_data<1..2^24-1>;
3568 };
3569 Extension extensions<0..2^16-1>;
3570 } CertificateEntry;
3571
3572 struct {
3573 opaque certificate_request_context<0..2^8-1>;
3574 CertificateEntry certificate_list<0..2^24-1>;
3575 } Certificate;
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586Rescorla Standards Track [Page 64]
3587
3588RFC 8446 TLS August 2018
3589
3590
3591 certificate_request_context: If this message is in response to a
3592 CertificateRequest, the value of certificate_request_context in
3593 that message. Otherwise (in the case of server authentication),
3594 this field SHALL be zero length.
3595
3596 certificate_list: A sequence (chain) of CertificateEntry structures,
3597 each containing a single certificate and set of extensions.
3598
3599 extensions: A set of extension values for the CertificateEntry. The
3600 "Extension" format is defined in Section 4.2. Valid extensions
3601 for server certificates at present include the OCSP Status
3602 extension [RFC6066] and the SignedCertificateTimestamp extension
3603 [RFC6962]; future extensions may be defined for this message as
3604 well. Extensions in the Certificate message from the server MUST
3605 correspond to ones from the ClientHello message. Extensions in
3606 the Certificate message from the client MUST correspond to
3607 extensions in the CertificateRequest message from the server. If
3608 an extension applies to the entire chain, it SHOULD be included in
3609 the first CertificateEntry.
3610
3611 If the corresponding certificate type extension
3612 ("server_certificate_type" or "client_certificate_type") was not
3613 negotiated in EncryptedExtensions, or the X.509 certificate type was
3614 negotiated, then each CertificateEntry contains a DER-encoded X.509
3615 certificate. The sender's certificate MUST come in the first
3616 CertificateEntry in the list. Each following certificate SHOULD
3617 directly certify the one immediately preceding it. Because
3618 certificate validation requires that trust anchors be distributed
3619 independently, a certificate that specifies a trust anchor MAY be
3620 omitted from the chain, provided that supported peers are known to
3621 possess any omitted certificates.
3622
3623 Note: Prior to TLS 1.3, "certificate_list" ordering required each
3624 certificate to certify the one immediately preceding it; however,
3625 some implementations allowed some flexibility. Servers sometimes
3626 send both a current and deprecated intermediate for transitional
3627 purposes, and others are simply configured incorrectly, but these
3628 cases can nonetheless be validated properly. For maximum
3629 compatibility, all implementations SHOULD be prepared to handle
3630 potentially extraneous certificates and arbitrary orderings from any
3631 TLS version, with the exception of the end-entity certificate which
3632 MUST be first.
3633
3634 If the RawPublicKey certificate type was negotiated, then the
3635 certificate_list MUST contain no more than one CertificateEntry,
3636 which contains an ASN1_subjectPublicKeyInfo value as defined in
3637 [RFC7250], Section 3.
3638
3639
3640
3641
3642Rescorla Standards Track [Page 65]
3643
3644RFC 8446 TLS August 2018
3645
3646
3647 The OpenPGP certificate type [RFC6091] MUST NOT be used with TLS 1.3.
3648
3649 The server's certificate_list MUST always be non-empty. A client
3650 will send an empty certificate_list if it does not have an
3651 appropriate certificate to send in response to the server's
3652 authentication request.
3653
36544.4.2.1. OCSP Status and SCT Extensions
3655
3656 [RFC6066] and [RFC6961] provide extensions to negotiate the server
3657 sending OCSP responses to the client. In TLS 1.2 and below, the
3658 server replies with an empty extension to indicate negotiation of
3659 this extension and the OCSP information is carried in a
3660 CertificateStatus message. In TLS 1.3, the server's OCSP information
3661 is carried in an extension in the CertificateEntry containing the
3662 associated certificate. Specifically, the body of the
3663 "status_request" extension from the server MUST be a
3664 CertificateStatus structure as defined in [RFC6066], which is
3665 interpreted as defined in [RFC6960].
3666
3667 Note: The status_request_v2 extension [RFC6961] is deprecated.
3668 TLS 1.3 servers MUST NOT act upon its presence or information in it
3669 when processing ClientHello messages; in particular, they MUST NOT
3670 send the status_request_v2 extension in the EncryptedExtensions,
3671 CertificateRequest, or Certificate messages. TLS 1.3 servers MUST be
3672 able to process ClientHello messages that include it, as it MAY be
3673 sent by clients that wish to use it in earlier protocol versions.
3674
3675 A server MAY request that a client present an OCSP response with its
3676 certificate by sending an empty "status_request" extension in its
3677 CertificateRequest message. If the client opts to send an OCSP
3678 response, the body of its "status_request" extension MUST be a
3679 CertificateStatus structure as defined in [RFC6066].
3680
3681 Similarly, [RFC6962] provides a mechanism for a server to send a
3682 Signed Certificate Timestamp (SCT) as an extension in the ServerHello
3683 in TLS 1.2 and below. In TLS 1.3, the server's SCT information is
3684 carried in an extension in the CertificateEntry.
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698Rescorla Standards Track [Page 66]
3699
3700RFC 8446 TLS August 2018
3701
3702
37034.4.2.2. Server Certificate Selection
3704
3705 The following rules apply to the certificates sent by the server:
3706
3707 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly
3708 negotiated otherwise (e.g., [RFC7250]).
3709
3710 - The server's end-entity certificate's public key (and associated
3711 restrictions) MUST be compatible with the selected authentication
3712 algorithm from the client's "signature_algorithms" extension
3713 (currently RSA, ECDSA, or EdDSA).
3714
3715 - The certificate MUST allow the key to be used for signing (i.e.,
3716 the digitalSignature bit MUST be set if the Key Usage extension is
3717 present) with a signature scheme indicated in the client's
3718 "signature_algorithms"/"signature_algorithms_cert" extensions (see
3719 Section 4.2.3).
3720
3721 - The "server_name" [RFC6066] and "certificate_authorities"
3722 extensions are used to guide certificate selection. As servers
3723 MAY require the presence of the "server_name" extension, clients
3724 SHOULD send this extension, when applicable.
3725
3726 All certificates provided by the server MUST be signed by a signature
3727 algorithm advertised by the client if it is able to provide such a
3728 chain (see Section 4.2.3). Certificates that are self-signed or
3729 certificates that are expected to be trust anchors are not validated
3730 as part of the chain and therefore MAY be signed with any algorithm.
3731
3732 If the server cannot produce a certificate chain that is signed only
3733 via the indicated supported algorithms, then it SHOULD continue the
3734 handshake by sending the client a certificate chain of its choice
3735 that may include algorithms that are not known to be supported by the
3736 client. This fallback chain SHOULD NOT use the deprecated SHA-1 hash
3737 algorithm in general, but MAY do so if the client's advertisement
3738 permits it, and MUST NOT do so otherwise.
3739
3740 If the client cannot construct an acceptable chain using the provided
3741 certificates and decides to abort the handshake, then it MUST abort
3742 the handshake with an appropriate certificate-related alert (by
3743 default, "unsupported_certificate"; see Section 6.2 for more
3744 information).
3745
3746 If the server has multiple certificates, it chooses one of them based
3747 on the above-mentioned criteria (in addition to other criteria, such
3748 as transport-layer endpoint, local configuration, and preferences).
3749
3750
3751
3752
3753
3754Rescorla Standards Track [Page 67]
3755
3756RFC 8446 TLS August 2018
3757
3758
37594.4.2.3. Client Certificate Selection
3760
3761 The following rules apply to certificates sent by the client:
3762
3763 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly
3764 negotiated otherwise (e.g., [RFC7250]).
3765
3766 - If the "certificate_authorities" extension in the
3767 CertificateRequest message was present, at least one of the
3768 certificates in the certificate chain SHOULD be issued by one of
3769 the listed CAs.
3770
3771 - The certificates MUST be signed using an acceptable signature
3772 algorithm, as described in Section 4.3.2. Note that this relaxes
3773 the constraints on certificate-signing algorithms found in prior
3774 versions of TLS.
3775
3776 - If the CertificateRequest message contained a non-empty
3777 "oid_filters" extension, the end-entity certificate MUST match the
3778 extension OIDs that are recognized by the client, as described in
3779 Section 4.2.5.
3780
37814.4.2.4. Receiving a Certificate Message
3782
3783 In general, detailed certificate validation procedures are out of
3784 scope for TLS (see [RFC5280]). This section provides TLS-specific
3785 requirements.
3786
3787 If the server supplies an empty Certificate message, the client MUST
3788 abort the handshake with a "decode_error" alert.
3789
3790 If the client does not send any certificates (i.e., it sends an empty
3791 Certificate message), the server MAY at its discretion either
3792 continue the handshake without client authentication or abort the
3793 handshake with a "certificate_required" alert. Also, if some aspect
3794 of the certificate chain was unacceptable (e.g., it was not signed by
3795 a known, trusted CA), the server MAY at its discretion either
3796 continue the handshake (considering the client unauthenticated) or
3797 abort the handshake.
3798
3799 Any endpoint receiving any certificate which it would need to
3800 validate using any signature algorithm using an MD5 hash MUST abort
3801 the handshake with a "bad_certificate" alert. SHA-1 is deprecated,
3802 and it is RECOMMENDED that any endpoint receiving any certificate
3803 which it would need to validate using any signature algorithm using a
3804 SHA-1 hash abort the handshake with a "bad_certificate" alert. For
3805 clarity, this means that endpoints can accept these algorithms for
3806 certificates that are self-signed or are trust anchors.
3807
3808
3809
3810Rescorla Standards Track [Page 68]
3811
3812RFC 8446 TLS August 2018
3813
3814
3815 All endpoints are RECOMMENDED to transition to SHA-256 or better as
3816 soon as possible to maintain interoperability with implementations
3817 currently in the process of phasing out SHA-1 support.
3818
3819 Note that a certificate containing a key for one signature algorithm
3820 MAY be signed using a different signature algorithm (for instance, an
3821 RSA key signed with an ECDSA key).
3822
38234.4.3. Certificate Verify
3824
3825 This message is used to provide explicit proof that an endpoint
3826 possesses the private key corresponding to its certificate. The
3827 CertificateVerify message also provides integrity for the handshake
3828 up to this point. Servers MUST send this message when authenticating
3829 via a certificate. Clients MUST send this message whenever
3830 authenticating via a certificate (i.e., when the Certificate message
3831 is non-empty). When sent, this message MUST appear immediately after
3832 the Certificate message and immediately prior to the Finished
3833 message.
3834
3835 Structure of this message:
3836
3837 struct {
3838 SignatureScheme algorithm;
3839 opaque signature<0..2^16-1>;
3840 } CertificateVerify;
3841
3842 The algorithm field specifies the signature algorithm used (see
3843 Section 4.2.3 for the definition of this type). The signature is a
3844 digital signature using that algorithm. The content that is covered
3845 under the signature is the hash output as described in Section 4.4.1,
3846 namely:
3847
3848 Transcript-Hash(Handshake Context, Certificate)
3849
3850 The digital signature is then computed over the concatenation of:
3851
3852 - A string that consists of octet 32 (0x20) repeated 64 times
3853
3854 - The context string
3855
3856 - A single 0 byte which serves as the separator
3857
3858 - The content to be signed
3859
3860
3861
3862
3863
3864
3865
3866Rescorla Standards Track [Page 69]
3867
3868RFC 8446 TLS August 2018
3869
3870
3871 This structure is intended to prevent an attack on previous versions
3872 of TLS in which the ServerKeyExchange format meant that attackers
3873 could obtain a signature of a message with a chosen 32-byte prefix
3874 (ClientHello.random). The initial 64-byte pad clears that prefix
3875 along with the server-controlled ServerHello.random.
3876
3877 The context string for a server signature is
3878 "TLS 1.3, server CertificateVerify". The context string for a
3879 client signature is "TLS 1.3, client CertificateVerify". It is
3880 used to provide separation between signatures made in different
3881 contexts, helping against potential cross-protocol attacks.
3882
3883 For example, if the transcript hash was 32 bytes of 01 (this length
3884 would make sense for SHA-256), the content covered by the digital
3885 signature for a server CertificateVerify would be:
3886
3887 2020202020202020202020202020202020202020202020202020202020202020
3888 2020202020202020202020202020202020202020202020202020202020202020
3889 544c5320312e332c207365727665722043657274696669636174655665726966
3890 79
3891 00
3892 0101010101010101010101010101010101010101010101010101010101010101
3893
3894 On the sender side, the process for computing the signature field of
3895 the CertificateVerify message takes as input:
3896
3897 - The content covered by the digital signature
3898
3899 - The private signing key corresponding to the certificate sent in
3900 the previous message
3901
3902 If the CertificateVerify message is sent by a server, the signature
3903 algorithm MUST be one offered in the client's "signature_algorithms"
3904 extension unless no valid certificate chain can be produced without
3905 unsupported algorithms (see Section 4.2.3).
3906
3907 If sent by a client, the signature algorithm used in the signature
3908 MUST be one of those present in the supported_signature_algorithms
3909 field of the "signature_algorithms" extension in the
3910 CertificateRequest message.
3911
3912 In addition, the signature algorithm MUST be compatible with the key
3913 in the sender's end-entity certificate. RSA signatures MUST use an
3914 RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS1-v1_5
3915 algorithms appear in "signature_algorithms". The SHA-1 algorithm
3916 MUST NOT be used in any signatures of CertificateVerify messages.
3917
3918
3919
3920
3921
3922Rescorla Standards Track [Page 70]
3923
3924RFC 8446 TLS August 2018
3925
3926
3927 All SHA-1 signature algorithms in this specification are defined
3928 solely for use in legacy certificates and are not valid for
3929 CertificateVerify signatures.
3930
3931 The receiver of a CertificateVerify message MUST verify the signature
3932 field. The verification process takes as input:
3933
3934 - The content covered by the digital signature
3935
3936 - The public key contained in the end-entity certificate found in
3937 the associated Certificate message
3938
3939 - The digital signature received in the signature field of the
3940 CertificateVerify message
3941
3942 If the verification fails, the receiver MUST terminate the handshake
3943 with a "decrypt_error" alert.
3944
39454.4.4. Finished
3946
3947 The Finished message is the final message in the Authentication
3948 Block. It is essential for providing authentication of the handshake
3949 and of the computed keys.
3950
3951 Recipients of Finished messages MUST verify that the contents are
3952 correct and if incorrect MUST terminate the connection with a
3953 "decrypt_error" alert.
3954
3955 Once a side has sent its Finished message and has received and
3956 validated the Finished message from its peer, it may begin to send
3957 and receive Application Data over the connection. There are two
3958 settings in which it is permitted to send data prior to receiving the
3959 peer's Finished:
3960
3961 1. Clients sending 0-RTT data as described in Section 4.2.10.
3962
3963 2. Servers MAY send data after sending their first flight, but
3964 because the handshake is not yet complete, they have no assurance
3965 of either the peer's identity or its liveness (i.e., the
3966 ClientHello might have been replayed).
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978Rescorla Standards Track [Page 71]
3979
3980RFC 8446 TLS August 2018
3981
3982
3983 The key used to compute the Finished message is computed from the
3984 Base Key defined in Section 4.4 using HKDF (see Section 7.1).
3985 Specifically:
3986
3987 finished_key =
3988 HKDF-Expand-Label(BaseKey, "finished", "", Hash.length)
3989
3990 Structure of this message:
3991
3992 struct {
3993 opaque verify_data[Hash.length];
3994 } Finished;
3995
3996 The verify_data value is computed as follows:
3997
3998 verify_data =
3999 HMAC(finished_key,
4000 Transcript-Hash(Handshake Context,
4001 Certificate*, CertificateVerify*))
4002
4003 * Only included if present.
4004
4005 HMAC [RFC2104] uses the Hash algorithm for the handshake. As noted
4006 above, the HMAC input can generally be implemented by a running hash,
4007 i.e., just the handshake hash at this point.
4008
4009 In previous versions of TLS, the verify_data was always 12 octets
4010 long. In TLS 1.3, it is the size of the HMAC output for the Hash
4011 used for the handshake.
4012
4013 Note: Alerts and any other non-handshake record types are not
4014 handshake messages and are not included in the hash computations.
4015
4016 Any records following a Finished message MUST be encrypted under the
4017 appropriate application traffic key as described in Section 7.2. In
4018 particular, this includes any alerts sent by the server in response
4019 to client Certificate and CertificateVerify messages.
4020
40214.5. End of Early Data
4022
4023 struct {} EndOfEarlyData;
4024
4025 If the server sent an "early_data" extension in EncryptedExtensions,
4026 the client MUST send an EndOfEarlyData message after receiving the
4027 server Finished. If the server does not send an "early_data"
4028 extension in EncryptedExtensions, then the client MUST NOT send an
4029 EndOfEarlyData message. This message indicates that all 0-RTT
4030 application_data messages, if any, have been transmitted and that the
4031
4032
4033
4034Rescorla Standards Track [Page 72]
4035
4036RFC 8446 TLS August 2018
4037
4038
4039 following records are protected under handshake traffic keys.
4040 Servers MUST NOT send this message, and clients receiving it MUST
4041 terminate the connection with an "unexpected_message" alert. This
4042 message is encrypted under keys derived from the
4043 client_early_traffic_secret.
4044
40454.6. Post-Handshake Messages
4046
4047 TLS also allows other messages to be sent after the main handshake.
4048 These messages use a handshake content type and are encrypted under
4049 the appropriate application traffic key.
4050
40514.6.1. New Session Ticket Message
4052
4053 At any time after the server has received the client Finished
4054 message, it MAY send a NewSessionTicket message. This message
4055 creates a unique association between the ticket value and a secret
4056 PSK derived from the resumption master secret (see Section 7).
4057
4058 The client MAY use this PSK for future handshakes by including the
4059 ticket value in the "pre_shared_key" extension in its ClientHello
4060 (Section 4.2.11). Servers MAY send multiple tickets on a single
4061 connection, either immediately after each other or after specific
4062 events (see Appendix C.4). For instance, the server might send a new
4063 ticket after post-handshake authentication in order to encapsulate
4064 the additional client authentication state. Multiple tickets are
4065 useful for clients for a variety of purposes, including:
4066
4067 - Opening multiple parallel HTTP connections.
4068
4069 - Performing connection racing across interfaces and address
4070 families via (for example) Happy Eyeballs [RFC8305] or related
4071 techniques.
4072
4073 Any ticket MUST only be resumed with a cipher suite that has the same
4074 KDF hash algorithm as that used to establish the original connection.
4075
4076 Clients MUST only resume if the new SNI value is valid for the server
4077 certificate presented in the original session and SHOULD only resume
4078 if the SNI value matches the one used in the original session. The
4079 latter is a performance optimization: normally, there is no reason to
4080 expect that different servers covered by a single certificate would
4081 be able to accept each other's tickets; hence, attempting resumption
4082 in that case would waste a single-use ticket. If such an indication
4083 is provided (externally or by any other means), clients MAY resume
4084 with a different SNI value.
4085
4086
4087
4088
4089
4090Rescorla Standards Track [Page 73]
4091
4092RFC 8446 TLS August 2018
4093
4094
4095 On resumption, if reporting an SNI value to the calling application,
4096 implementations MUST use the value sent in the resumption ClientHello
4097 rather than the value sent in the previous session. Note that if a
4098 server implementation declines all PSK identities with different SNI
4099 values, these two values are always the same.
4100
4101 Note: Although the resumption master secret depends on the client's
4102 second flight, a server which does not request client authentication
4103 MAY compute the remainder of the transcript independently and then
4104 send a NewSessionTicket immediately upon sending its Finished rather
4105 than waiting for the client Finished. This might be appropriate in
4106 cases where the client is expected to open multiple TLS connections
4107 in parallel and would benefit from the reduced overhead of a
4108 resumption handshake, for example.
4109
4110 struct {
4111 uint32 ticket_lifetime;
4112 uint32 ticket_age_add;
4113 opaque ticket_nonce<0..255>;
4114 opaque ticket<1..2^16-1>;
4115 Extension extensions<0..2^16-2>;
4116 } NewSessionTicket;
4117
4118 ticket_lifetime: Indicates the lifetime in seconds as a 32-bit
4119 unsigned integer in network byte order from the time of ticket
4120 issuance. Servers MUST NOT use any value greater than
4121 604800 seconds (7 days). The value of zero indicates that the
4122 ticket should be discarded immediately. Clients MUST NOT cache
4123 tickets for longer than 7 days, regardless of the ticket_lifetime,
4124 and MAY delete tickets earlier based on local policy. A server
4125 MAY treat a ticket as valid for a shorter period of time than what
4126 is stated in the ticket_lifetime.
4127
4128 ticket_age_add: A securely generated, random 32-bit value that is
4129 used to obscure the age of the ticket that the client includes in
4130 the "pre_shared_key" extension. The client-side ticket age is
4131 added to this value modulo 2^32 to obtain the value that is
4132 transmitted by the client. The server MUST generate a fresh value
4133 for each ticket it sends.
4134
4135 ticket_nonce: A per-ticket value that is unique across all tickets
4136 issued on this connection.
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146Rescorla Standards Track [Page 74]
4147
4148RFC 8446 TLS August 2018
4149
4150
4151 ticket: The value of the ticket to be used as the PSK identity. The
4152 ticket itself is an opaque label. It MAY be either a database
4153 lookup key or a self-encrypted and self-authenticated value.
4154
4155 extensions: A set of extension values for the ticket. The
4156 "Extension" format is defined in Section 4.2. Clients MUST ignore
4157 unrecognized extensions.
4158
4159 The sole extension currently defined for NewSessionTicket is
4160 "early_data", indicating that the ticket may be used to send 0-RTT
4161 data (Section 4.2.10). It contains the following value:
4162
4163 max_early_data_size: The maximum amount of 0-RTT data that the
4164 client is allowed to send when using this ticket, in bytes. Only
4165 Application Data payload (i.e., plaintext but not padding or the
4166 inner content type byte) is counted. A server receiving more than
4167 max_early_data_size bytes of 0-RTT data SHOULD terminate the
4168 connection with an "unexpected_message" alert. Note that servers
4169 that reject early data due to lack of cryptographic material will
4170 be unable to differentiate padding from content, so clients
4171 SHOULD NOT depend on being able to send large quantities of
4172 padding in early data records.
4173
4174 The PSK associated with the ticket is computed as:
4175
4176 HKDF-Expand-Label(resumption_master_secret,
4177 "resumption", ticket_nonce, Hash.length)
4178
4179 Because the ticket_nonce value is distinct for each NewSessionTicket
4180 message, a different PSK will be derived for each ticket.
4181
4182 Note that in principle it is possible to continue issuing new tickets
4183 which indefinitely extend the lifetime of the keying material
4184 originally derived from an initial non-PSK handshake (which was most
4185 likely tied to the peer's certificate). It is RECOMMENDED that
4186 implementations place limits on the total lifetime of such keying
4187 material; these limits should take into account the lifetime of the
4188 peer's certificate, the likelihood of intervening revocation, and the
4189 time since the peer's online CertificateVerify signature.
4190
41914.6.2. Post-Handshake Authentication
4192
4193 When the client has sent the "post_handshake_auth" extension (see
4194 Section 4.2.6), a server MAY request client authentication at any
4195 time after the handshake has completed by sending a
4196 CertificateRequest message. The client MUST respond with the
4197 appropriate Authentication messages (see Section 4.4). If the client
4198 chooses to authenticate, it MUST send Certificate, CertificateVerify,
4199
4200
4201
4202Rescorla Standards Track [Page 75]
4203
4204RFC 8446 TLS August 2018
4205
4206
4207 and Finished. If it declines, it MUST send a Certificate message
4208 containing no certificates followed by Finished. All of the client's
4209 messages for a given response MUST appear consecutively on the wire
4210 with no intervening messages of other types.
4211
4212 A client that receives a CertificateRequest message without having
4213 sent the "post_handshake_auth" extension MUST send an
4214 "unexpected_message" fatal alert.
4215
4216 Note: Because client authentication could involve prompting the user,
4217 servers MUST be prepared for some delay, including receiving an
4218 arbitrary number of other messages between sending the
4219 CertificateRequest and receiving a response. In addition, clients
4220 which receive multiple CertificateRequests in close succession MAY
4221 respond to them in a different order than they were received (the
4222 certificate_request_context value allows the server to disambiguate
4223 the responses).
4224
42254.6.3. Key and Initialization Vector Update
4226
4227 The KeyUpdate handshake message is used to indicate that the sender
4228 is updating its sending cryptographic keys. This message can be sent
4229 by either peer after it has sent a Finished message. Implementations
4230 that receive a KeyUpdate message prior to receiving a Finished
4231 message MUST terminate the connection with an "unexpected_message"
4232 alert. After sending a KeyUpdate message, the sender SHALL send all
4233 its traffic using the next generation of keys, computed as described
4234 in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update
4235 its receiving keys.
4236
4237 enum {
4238 update_not_requested(0), update_requested(1), (255)
4239 } KeyUpdateRequest;
4240
4241 struct {
4242 KeyUpdateRequest request_update;
4243 } KeyUpdate;
4244
4245 request_update: Indicates whether the recipient of the KeyUpdate
4246 should respond with its own KeyUpdate. If an implementation
4247 receives any other value, it MUST terminate the connection with an
4248 "illegal_parameter" alert.
4249
4250 If the request_update field is set to "update_requested", then the
4251 receiver MUST send a KeyUpdate of its own with request_update set to
4252 "update_not_requested" prior to sending its next Application Data
4253 record. This mechanism allows either side to force an update to the
4254 entire connection, but causes an implementation which receives
4255
4256
4257
4258Rescorla Standards Track [Page 76]
4259
4260RFC 8446 TLS August 2018
4261
4262
4263 multiple KeyUpdates while it is silent to respond with a single
4264 update. Note that implementations may receive an arbitrary number of
4265 messages between sending a KeyUpdate with request_update set to
4266 "update_requested" and receiving the peer's KeyUpdate, because those
4267 messages may already be in flight. However, because send and receive
4268 keys are derived from independent traffic secrets, retaining the
4269 receive traffic secret does not threaten the forward secrecy of data
4270 sent before the sender changed keys.
4271
4272 If implementations independently send their own KeyUpdates with
4273 request_update set to "update_requested" and they cross in flight,
4274 then each side will also send a response, with the result that each
4275 side increments by two generations.
4276
4277 Both sender and receiver MUST encrypt their KeyUpdate messages with
4278 the old keys. Additionally, both sides MUST enforce that a KeyUpdate
4279 with the old key is received before accepting any messages encrypted
4280 with the new key. Failure to do so may allow message truncation
4281 attacks.
4282
42835. Record Protocol
4284
4285 The TLS record protocol takes messages to be transmitted, fragments
4286 the data into manageable blocks, protects the records, and transmits
4287 the result. Received data is verified, decrypted, reassembled, and
4288 then delivered to higher-level clients.
4289
4290 TLS records are typed, which allows multiple higher-level protocols
4291 to be multiplexed over the same record layer. This document
4292 specifies four content types: handshake, application_data, alert, and
4293 change_cipher_spec. The change_cipher_spec record is used only for
4294 compatibility purposes (see Appendix D.4).
4295
4296 An implementation may receive an unencrypted record of type
4297 change_cipher_spec consisting of the single byte value 0x01 at any
4298 time after the first ClientHello message has been sent or received
4299 and before the peer's Finished message has been received and MUST
4300 simply drop it without further processing. Note that this record may
4301 appear at a point at the handshake where the implementation is
4302 expecting protected records, and so it is necessary to detect this
4303 condition prior to attempting to deprotect the record. An
4304 implementation which receives any other change_cipher_spec value or
4305 which receives a protected change_cipher_spec record MUST abort the
4306 handshake with an "unexpected_message" alert. If an implementation
4307 detects a change_cipher_spec record received before the first
4308 ClientHello message or after the peer's Finished message, it MUST be
4309 treated as an unexpected record type (though stateless servers may
4310 not be able to distinguish these cases from allowed cases).
4311
4312
4313
4314Rescorla Standards Track [Page 77]
4315
4316RFC 8446 TLS August 2018
4317
4318
4319 Implementations MUST NOT send record types not defined in this
4320 document unless negotiated by some extension. If a TLS
4321 implementation receives an unexpected record type, it MUST terminate
4322 the connection with an "unexpected_message" alert. New record
4323 content type values are assigned by IANA in the TLS ContentType
4324 registry as described in Section 11.
4325
43265.1. Record Layer
4327
4328 The record layer fragments information blocks into TLSPlaintext
4329 records carrying data in chunks of 2^14 bytes or less. Message
4330 boundaries are handled differently depending on the underlying
4331 ContentType. Any future content types MUST specify appropriate
4332 rules. Note that these rules are stricter than what was enforced in
4333 TLS 1.2.
4334
4335 Handshake messages MAY be coalesced into a single TLSPlaintext record
4336 or fragmented across several records, provided that:
4337
4338 - Handshake messages MUST NOT be interleaved with other record
4339 types. That is, if a handshake message is split over two or more
4340 records, there MUST NOT be any other records between them.
4341
4342 - Handshake messages MUST NOT span key changes. Implementations
4343 MUST verify that all messages immediately preceding a key change
4344 align with a record boundary; if not, then they MUST terminate the
4345 connection with an "unexpected_message" alert. Because the
4346 ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate
4347 messages can immediately precede a key change, implementations
4348 MUST send these messages in alignment with a record boundary.
4349
4350 Implementations MUST NOT send zero-length fragments of Handshake
4351 types, even if those fragments contain padding.
4352
4353 Alert messages (Section 6) MUST NOT be fragmented across records, and
4354 multiple alert messages MUST NOT be coalesced into a single
4355 TLSPlaintext record. In other words, a record with an Alert type
4356 MUST contain exactly one message.
4357
4358 Application Data messages contain data that is opaque to TLS.
4359 Application Data messages are always protected. Zero-length
4360 fragments of Application Data MAY be sent, as they are potentially
4361 useful as a traffic analysis countermeasure. Application Data
4362 fragments MAY be split across multiple records or coalesced into a
4363 single record.
4364
4365
4366
4367
4368
4369
4370Rescorla Standards Track [Page 78]
4371
4372RFC 8446 TLS August 2018
4373
4374
4375 enum {
4376 invalid(0),
4377 change_cipher_spec(20),
4378 alert(21),
4379 handshake(22),
4380 application_data(23),
4381 (255)
4382 } ContentType;
4383
4384 struct {
4385 ContentType type;
4386 ProtocolVersion legacy_record_version;
4387 uint16 length;
4388 opaque fragment[TLSPlaintext.length];
4389 } TLSPlaintext;
4390
4391 type: The higher-level protocol used to process the enclosed
4392 fragment.
4393
4394 legacy_record_version: MUST be set to 0x0303 for all records
4395 generated by a TLS 1.3 implementation other than an initial
4396 ClientHello (i.e., one not generated after a HelloRetryRequest),
4397 where it MAY also be 0x0301 for compatibility purposes. This
4398 field is deprecated and MUST be ignored for all purposes.
4399 Previous versions of TLS would use other values in this field
4400 under some circumstances.
4401
4402 length: The length (in bytes) of the following
4403 TLSPlaintext.fragment. The length MUST NOT exceed 2^14 bytes. An
4404 endpoint that receives a record that exceeds this length MUST
4405 terminate the connection with a "record_overflow" alert.
4406
4407 fragment: The data being transmitted. This value is transparent and
4408 is treated as an independent block to be dealt with by the higher-
4409 level protocol specified by the type field.
4410
4411 This document describes TLS 1.3, which uses the version 0x0304. This
4412 version value is historical, deriving from the use of 0x0301 for
4413 TLS 1.0 and 0x0300 for SSL 3.0. In order to maximize backward
4414 compatibility, a record containing an initial ClientHello SHOULD have
4415 version 0x0301 (reflecting TLS 1.0) and a record containing a second
4416 ClientHello or a ServerHello MUST have version 0x0303 (reflecting
4417 TLS 1.2). When negotiating prior versions of TLS, endpoints follow
4418 the procedure and requirements provided in Appendix D.
4419
4420
4421
4422
4423
4424
4425
4426Rescorla Standards Track [Page 79]
4427
4428RFC 8446 TLS August 2018
4429
4430
4431 When record protection has not yet been engaged, TLSPlaintext
4432 structures are written directly onto the wire. Once record
4433 protection has started, TLSPlaintext records are protected and sent
4434 as described in the following section. Note that Application Data
4435 records MUST NOT be written to the wire unprotected (see Section 2
4436 for details).
4437
44385.2. Record Payload Protection
4439
4440 The record protection functions translate a TLSPlaintext structure
4441 into a TLSCiphertext structure. The deprotection functions reverse
4442 the process. In TLS 1.3, as opposed to previous versions of TLS, all
4443 ciphers are modeled as "Authenticated Encryption with Associated
4444 Data" (AEAD) [RFC5116]. AEAD functions provide a unified encryption
4445 and authentication operation which turns plaintext into authenticated
4446 ciphertext and back again. Each encrypted record consists of a
4447 plaintext header followed by an encrypted body, which itself contains
4448 a type and optional padding.
4449
4450 struct {
4451 opaque content[TLSPlaintext.length];
4452 ContentType type;
4453 uint8 zeros[length_of_padding];
4454 } TLSInnerPlaintext;
4455
4456 struct {
4457 ContentType opaque_type = application_data; /* 23 */
4458 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */
4459 uint16 length;
4460 opaque encrypted_record[TLSCiphertext.length];
4461 } TLSCiphertext;
4462
4463 content: The TLSPlaintext.fragment value, containing the byte
4464 encoding of a handshake or an alert message, or the raw bytes of
4465 the application's data to send.
4466
4467 type: The TLSPlaintext.type value containing the content type of the
4468 record.
4469
4470 zeros: An arbitrary-length run of zero-valued bytes may appear in
4471 the cleartext after the type field. This provides an opportunity
4472 for senders to pad any TLS record by a chosen amount as long as
4473 the total stays within record size limits. See Section 5.4 for
4474 more details.
4475
4476
4477
4478
4479
4480
4481
4482Rescorla Standards Track [Page 80]
4483
4484RFC 8446 TLS August 2018
4485
4486
4487 opaque_type: The outer opaque_type field of a TLSCiphertext record
4488 is always set to the value 23 (application_data) for outward
4489 compatibility with middleboxes accustomed to parsing previous
4490 versions of TLS. The actual content type of the record is found
4491 in TLSInnerPlaintext.type after decryption.
4492
4493 legacy_record_version: The legacy_record_version field is always
4494 0x0303. TLS 1.3 TLSCiphertexts are not generated until after
4495 TLS 1.3 has been negotiated, so there are no historical
4496 compatibility concerns where other values might be received. Note
4497 that the handshake protocol, including the ClientHello and
4498 ServerHello messages, authenticates the protocol version, so this
4499 value is redundant.
4500
4501 length: The length (in bytes) of the following
4502 TLSCiphertext.encrypted_record, which is the sum of the lengths of
4503 the content and the padding, plus one for the inner content type,
4504 plus any expansion added by the AEAD algorithm. The length
4505 MUST NOT exceed 2^14 + 256 bytes. An endpoint that receives a
4506 record that exceeds this length MUST terminate the connection with
4507 a "record_overflow" alert.
4508
4509 encrypted_record: The AEAD-encrypted form of the serialized
4510 TLSInnerPlaintext structure.
4511
4512 AEAD algorithms take as input a single key, a nonce, a plaintext, and
4513 "additional data" to be included in the authentication check, as
4514 described in Section 2.1 of [RFC5116]. The key is either the
4515 client_write_key or the server_write_key, the nonce is derived from
4516 the sequence number and the client_write_iv or server_write_iv (see
4517 Section 5.3), and the additional data input is the record header.
4518
4519 I.e.,
4520
4521 additional_data = TLSCiphertext.opaque_type ||
4522 TLSCiphertext.legacy_record_version ||
4523 TLSCiphertext.length
4524
4525 The plaintext input to the AEAD algorithm is the encoded
4526 TLSInnerPlaintext structure. Derivation of traffic keys is defined
4527 in Section 7.3.
4528
4529 The AEAD output consists of the ciphertext output from the AEAD
4530 encryption operation. The length of the plaintext is greater than
4531 the corresponding TLSPlaintext.length due to the inclusion of
4532 TLSInnerPlaintext.type and any padding supplied by the sender. The
4533 length of the AEAD output will generally be larger than the
4534 plaintext, but by an amount that varies with the AEAD algorithm.
4535
4536
4537
4538Rescorla Standards Track [Page 81]
4539
4540RFC 8446 TLS August 2018
4541
4542
4543 Since the ciphers might incorporate padding, the amount of overhead
4544 could vary with different lengths of plaintext. Symbolically,
4545
4546 AEADEncrypted =
4547 AEAD-Encrypt(write_key, nonce, additional_data, plaintext)
4548
4549 The encrypted_record field of TLSCiphertext is set to AEADEncrypted.
4550
4551 In order to decrypt and verify, the cipher takes as input the key,
4552 nonce, additional data, and the AEADEncrypted value. The output is
4553 either the plaintext or an error indicating that the decryption
4554 failed. There is no separate integrity check. Symbolically,
4555
4556 plaintext of encrypted_record =
4557 AEAD-Decrypt(peer_write_key, nonce,
4558 additional_data, AEADEncrypted)
4559
4560 If the decryption fails, the receiver MUST terminate the connection
4561 with a "bad_record_mac" alert.
4562
4563 An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion
4564 greater than 255 octets. An endpoint that receives a record from its
4565 peer with TLSCiphertext.length larger than 2^14 + 256 octets MUST
4566 terminate the connection with a "record_overflow" alert. This limit
4567 is derived from the maximum TLSInnerPlaintext length of 2^14 octets +
4568 1 octet for ContentType + the maximum AEAD expansion of 255 octets.
4569
45705.3. Per-Record Nonce
4571
4572 A 64-bit sequence number is maintained separately for reading and
4573 writing records. The appropriate sequence number is incremented by
4574 one after reading or writing each record. Each sequence number is
4575 set to zero at the beginning of a connection and whenever the key is
4576 changed; the first record transmitted under a particular traffic key
4577 MUST use sequence number 0.
4578
4579 Because the size of sequence numbers is 64-bit, they should not wrap.
4580 If a TLS implementation would need to wrap a sequence number, it MUST
4581 either rekey (Section 4.6.3) or terminate the connection.
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594Rescorla Standards Track [Page 82]
4595
4596RFC 8446 TLS August 2018
4597
4598
4599 Each AEAD algorithm will specify a range of possible lengths for the
4600 per-record nonce, from N_MIN bytes to N_MAX bytes of input [RFC5116].
4601 The length of the TLS per-record nonce (iv_length) is set to the
4602 larger of 8 bytes and N_MIN for the AEAD algorithm (see [RFC5116],
4603 Section 4). An AEAD algorithm where N_MAX is less than 8 bytes
4604 MUST NOT be used with TLS. The per-record nonce for the AEAD
4605 construction is formed as follows:
4606
4607 1. The 64-bit record sequence number is encoded in network byte
4608 order and padded to the left with zeros to iv_length.
4609
4610 2. The padded sequence number is XORed with either the static
4611 client_write_iv or server_write_iv (depending on the role).
4612
4613 The resulting quantity (of length iv_length) is used as the
4614 per-record nonce.
4615
4616 Note: This is a different construction from that in TLS 1.2, which
4617 specified a partially explicit nonce.
4618
46195.4. Record Padding
4620
4621 All encrypted TLS records can be padded to inflate the size of the
4622 TLSCiphertext. This allows the sender to hide the size of the
4623 traffic from an observer.
4624
4625 When generating a TLSCiphertext record, implementations MAY choose to
4626 pad. An unpadded record is just a record with a padding length of
4627 zero. Padding is a string of zero-valued bytes appended to the
4628 ContentType field before encryption. Implementations MUST set the
4629 padding octets to all zeros before encrypting.
4630
4631 Application Data records may contain a zero-length
4632 TLSInnerPlaintext.content if the sender desires. This permits
4633 generation of plausibly sized cover traffic in contexts where the
4634 presence or absence of activity may be sensitive. Implementations
4635 MUST NOT send Handshake and Alert records that have a zero-length
4636 TLSInnerPlaintext.content; if such a message is received, the
4637 receiving implementation MUST terminate the connection with an
4638 "unexpected_message" alert.
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650Rescorla Standards Track [Page 83]
4651
4652RFC 8446 TLS August 2018
4653
4654
4655 The padding sent is automatically verified by the record protection
4656 mechanism; upon successful decryption of a
4657 TLSCiphertext.encrypted_record, the receiving implementation scans
4658 the field from the end toward the beginning until it finds a non-zero
4659 octet. This non-zero octet is the content type of the message. This
4660 padding scheme was selected because it allows padding of any
4661 encrypted TLS record by an arbitrary size (from zero up to TLS record
4662 size limits) without introducing new content types. The design also
4663 enforces all-zero padding octets, which allows for quick detection of
4664 padding errors.
4665
4666 Implementations MUST limit their scanning to the cleartext returned
4667 from the AEAD decryption. If a receiving implementation does not
4668 find a non-zero octet in the cleartext, it MUST terminate the
4669 connection with an "unexpected_message" alert.
4670
4671 The presence of padding does not change the overall record size
4672 limitations: the full encoded TLSInnerPlaintext MUST NOT exceed 2^14
4673 + 1 octets. If the maximum fragment length is reduced -- as, for
4674 example, by the record_size_limit extension from [RFC8449] -- then
4675 the reduced limit applies to the full plaintext, including the
4676 content type and padding.
4677
4678 Selecting a padding policy that suggests when and how much to pad is
4679 a complex topic and is beyond the scope of this specification. If
4680 the application-layer protocol on top of TLS has its own padding, it
4681 may be preferable to pad Application Data TLS records within the
4682 application layer. Padding for encrypted Handshake or Alert records
4683 must still be handled at the TLS layer, though. Later documents may
4684 define padding selection algorithms or define a padding policy
4685 request mechanism through TLS extensions or some other means.
4686
46875.5. Limits on Key Usage
4688
4689 There are cryptographic limits on the amount of plaintext which can
4690 be safely encrypted under a given set of keys. [AEAD-LIMITS]
4691 provides an analysis of these limits under the assumption that the
4692 underlying primitive (AES or ChaCha20) has no weaknesses.
4693 Implementations SHOULD do a key update as described in Section 4.6.3
4694 prior to reaching these limits.
4695
4696 For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be
4697 encrypted on a given connection while keeping a safety margin of
4698 approximately 2^-57 for Authenticated Encryption (AE) security. For
4699 ChaCha20/Poly1305, the record sequence number would wrap before the
4700 safety limit is reached.
4701
4702
4703
4704
4705
4706Rescorla Standards Track [Page 84]
4707
4708RFC 8446 TLS August 2018
4709
4710
47116. Alert Protocol
4712
4713 TLS provides an Alert content type to indicate closure information
4714 and errors. Like other messages, alert messages are encrypted as
4715 specified by the current connection state.
4716
4717 Alert messages convey a description of the alert and a legacy field
4718 that conveyed the severity level of the message in previous versions
4719 of TLS. Alerts are divided into two classes: closure alerts and
4720 error alerts. In TLS 1.3, the severity is implicit in the type of
4721 alert being sent, and the "level" field can safely be ignored. The
4722 "close_notify" alert is used to indicate orderly closure of one
4723 direction of the connection. Upon receiving such an alert, the TLS
4724 implementation SHOULD indicate end-of-data to the application.
4725
4726 Error alerts indicate abortive closure of the connection (see
4727 Section 6.2). Upon receiving an error alert, the TLS implementation
4728 SHOULD indicate an error to the application and MUST NOT allow any
4729 further data to be sent or received on the connection. Servers and
4730 clients MUST forget the secret values and keys established in failed
4731 connections, with the exception of the PSKs associated with session
4732 tickets, which SHOULD be discarded if possible.
4733
4734 All the alerts listed in Section 6.2 MUST be sent with
4735 AlertLevel=fatal and MUST be treated as error alerts when received
4736 regardless of the AlertLevel in the message. Unknown Alert types
4737 MUST be treated as error alerts.
4738
4739 Note: TLS defines two generic alerts (see Section 6) to use upon
4740 failure to parse a message. Peers which receive a message which
4741 cannot be parsed according to the syntax (e.g., have a length
4742 extending beyond the message boundary or contain an out-of-range
4743 length) MUST terminate the connection with a "decode_error" alert.
4744 Peers which receive a message which is syntactically correct but
4745 semantically invalid (e.g., a DHE share of p - 1, or an invalid enum)
4746 MUST terminate the connection with an "illegal_parameter" alert.
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762Rescorla Standards Track [Page 85]
4763
4764RFC 8446 TLS August 2018
4765
4766
4767 enum { warning(1), fatal(2), (255) } AlertLevel;
4768
4769 enum {
4770 close_notify(0),
4771 unexpected_message(10),
4772 bad_record_mac(20),
4773 record_overflow(22),
4774 handshake_failure(40),
4775 bad_certificate(42),
4776 unsupported_certificate(43),
4777 certificate_revoked(44),
4778 certificate_expired(45),
4779 certificate_unknown(46),
4780 illegal_parameter(47),
4781 unknown_ca(48),
4782 access_denied(49),
4783 decode_error(50),
4784 decrypt_error(51),
4785 protocol_version(70),
4786 insufficient_security(71),
4787 internal_error(80),
4788 inappropriate_fallback(86),
4789 user_canceled(90),
4790 missing_extension(109),
4791 unsupported_extension(110),
4792 unrecognized_name(112),
4793 bad_certificate_status_response(113),
4794 unknown_psk_identity(115),
4795 certificate_required(116),
4796 no_application_protocol(120),
4797 (255)
4798 } AlertDescription;
4799
4800 struct {
4801 AlertLevel level;
4802 AlertDescription description;
4803 } Alert;
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818Rescorla Standards Track [Page 86]
4819
4820RFC 8446 TLS August 2018
4821
4822
48236.1. Closure Alerts
4824
4825 The client and the server must share knowledge that the connection is
4826 ending in order to avoid a truncation attack.
4827
4828 close_notify: This alert notifies the recipient that the sender will
4829 not send any more messages on this connection. Any data received
4830 after a closure alert has been received MUST be ignored.
4831
4832 user_canceled: This alert notifies the recipient that the sender is
4833 canceling the handshake for some reason unrelated to a protocol
4834 failure. If a user cancels an operation after the handshake is
4835 complete, just closing the connection by sending a "close_notify"
4836 is more appropriate. This alert SHOULD be followed by a
4837 "close_notify". This alert generally has AlertLevel=warning.
4838
4839 Either party MAY initiate a close of its write side of the connection
4840 by sending a "close_notify" alert. Any data received after a closure
4841 alert has been received MUST be ignored. If a transport-level close
4842 is received prior to a "close_notify", the receiver cannot know that
4843 all the data that was sent has been received.
4844
4845 Each party MUST send a "close_notify" alert before closing its write
4846 side of the connection, unless it has already sent some error alert.
4847 This does not have any effect on its read side of the connection.
4848 Note that this is a change from versions of TLS prior to TLS 1.3 in
4849 which implementations were required to react to a "close_notify" by
4850 discarding pending writes and sending an immediate "close_notify"
4851 alert of their own. That previous requirement could cause truncation
4852 in the read side. Both parties need not wait to receive a
4853 "close_notify" alert before closing their read side of the
4854 connection, though doing so would introduce the possibility of
4855 truncation.
4856
4857 If the application protocol using TLS provides that any data may be
4858 carried over the underlying transport after the TLS connection is
4859 closed, the TLS implementation MUST receive a "close_notify" alert
4860 before indicating end-of-data to the application layer. No part of
4861 this standard should be taken to dictate the manner in which a usage
4862 profile for TLS manages its data transport, including when
4863 connections are opened or closed.
4864
4865 Note: It is assumed that closing the write side of a connection
4866 reliably delivers pending data before destroying the transport.
4867
4868
4869
4870
4871
4872
4873
4874Rescorla Standards Track [Page 87]
4875
4876RFC 8446 TLS August 2018
4877
4878
48796.2. Error Alerts
4880
4881 Error handling in TLS is very simple. When an error is detected, the
4882 detecting party sends a message to its peer. Upon transmission or
4883 receipt of a fatal alert message, both parties MUST immediately close
4884 the connection.
4885
4886 Whenever an implementation encounters a fatal error condition, it
4887 SHOULD send an appropriate fatal alert and MUST close the connection
4888 without sending or receiving any additional data. In the rest of
4889 this specification, when the phrases "terminate the connection" and
4890 "abort the handshake" are used without a specific alert it means that
4891 the implementation SHOULD send the alert indicated by the
4892 descriptions below. The phrases "terminate the connection with an X
4893 alert" and "abort the handshake with an X alert" mean that the
4894 implementation MUST send alert X if it sends any alert. All alerts
4895 defined below in this section, as well as all unknown alerts, are
4896 universally considered fatal as of TLS 1.3 (see Section 6). The
4897 implementation SHOULD provide a way to facilitate logging the sending
4898 and receiving of alerts.
4899
4900 The following error alerts are defined:
4901
4902 unexpected_message: An inappropriate message (e.g., the wrong
4903 handshake message, premature Application Data, etc.) was received.
4904 This alert should never be observed in communication between
4905 proper implementations.
4906
4907 bad_record_mac: This alert is returned if a record is received which
4908 cannot be deprotected. Because AEAD algorithms combine decryption
4909 and verification, and also to avoid side-channel attacks, this
4910 alert is used for all deprotection failures. This alert should
4911 never be observed in communication between proper implementations,
4912 except when messages were corrupted in the network.
4913
4914 record_overflow: A TLSCiphertext record was received that had a
4915 length more than 2^14 + 256 bytes, or a record decrypted to a
4916 TLSPlaintext record with more than 2^14 bytes (or some other
4917 negotiated limit). This alert should never be observed in
4918 communication between proper implementations, except when messages
4919 were corrupted in the network.
4920
4921 handshake_failure: Receipt of a "handshake_failure" alert message
4922 indicates that the sender was unable to negotiate an acceptable
4923 set of security parameters given the options available.
4924
4925 bad_certificate: A certificate was corrupt, contained signatures
4926 that did not verify correctly, etc.
4927
4928
4929
4930Rescorla Standards Track [Page 88]
4931
4932RFC 8446 TLS August 2018
4933
4934
4935 unsupported_certificate: A certificate was of an unsupported type.
4936
4937 certificate_revoked: A certificate was revoked by its signer.
4938
4939 certificate_expired: A certificate has expired or is not currently
4940 valid.
4941
4942 certificate_unknown: Some other (unspecified) issue arose in
4943 processing the certificate, rendering it unacceptable.
4944
4945 illegal_parameter: A field in the handshake was incorrect or
4946 inconsistent with other fields. This alert is used for errors
4947 which conform to the formal protocol syntax but are otherwise
4948 incorrect.
4949
4950 unknown_ca: A valid certificate chain or partial chain was received,
4951 but the certificate was not accepted because the CA certificate
4952 could not be located or could not be matched with a known trust
4953 anchor.
4954
4955 access_denied: A valid certificate or PSK was received, but when
4956 access control was applied, the sender decided not to proceed with
4957 negotiation.
4958
4959 decode_error: A message could not be decoded because some field was
4960 out of the specified range or the length of the message was
4961 incorrect. This alert is used for errors where the message does
4962 not conform to the formal protocol syntax. This alert should
4963 never be observed in communication between proper implementations,
4964 except when messages were corrupted in the network.
4965
4966 decrypt_error: A handshake (not record layer) cryptographic
4967 operation failed, including being unable to correctly verify a
4968 signature or validate a Finished message or a PSK binder.
4969
4970 protocol_version: The protocol version the peer has attempted to
4971 negotiate is recognized but not supported (see Appendix D).
4972
4973 insufficient_security: Returned instead of "handshake_failure" when
4974 a negotiation has failed specifically because the server requires
4975 parameters more secure than those supported by the client.
4976
4977 internal_error: An internal error unrelated to the peer or the
4978 correctness of the protocol (such as a memory allocation failure)
4979 makes it impossible to continue.
4980
4981 inappropriate_fallback: Sent by a server in response to an invalid
4982 connection retry attempt from a client (see [RFC7507]).
4983
4984
4985
4986Rescorla Standards Track [Page 89]
4987
4988RFC 8446 TLS August 2018
4989
4990
4991 missing_extension: Sent by endpoints that receive a handshake
4992 message not containing an extension that is mandatory to send for
4993 the offered TLS version or other negotiated parameters.
4994
4995 unsupported_extension: Sent by endpoints receiving any handshake
4996 message containing an extension known to be prohibited for
4997 inclusion in the given handshake message, or including any
4998 extensions in a ServerHello or Certificate not first offered in
4999 the corresponding ClientHello or CertificateRequest.
5000
5001 unrecognized_name: Sent by servers when no server exists identified
5002 by the name provided by the client via the "server_name" extension
5003 (see [RFC6066]).
5004
5005 bad_certificate_status_response: Sent by clients when an invalid or
5006 unacceptable OCSP response is provided by the server via the
5007 "status_request" extension (see [RFC6066]).
5008
5009 unknown_psk_identity: Sent by servers when PSK key establishment is
5010 desired but no acceptable PSK identity is provided by the client.
5011 Sending this alert is OPTIONAL; servers MAY instead choose to send
5012 a "decrypt_error" alert to merely indicate an invalid PSK
5013 identity.
5014
5015 certificate_required: Sent by servers when a client certificate is
5016 desired but none was provided by the client.
5017
5018 no_application_protocol: Sent by servers when a client
5019 "application_layer_protocol_negotiation" extension advertises only
5020 protocols that the server does not support (see [RFC7301]).
5021
5022 New Alert values are assigned by IANA as described in Section 11.
5023
50247. Cryptographic Computations
5025
5026 The TLS handshake establishes one or more input secrets which are
5027 combined to create the actual working keying material, as detailed
5028 below. The key derivation process incorporates both the input
5029 secrets and the handshake transcript. Note that because the
5030 handshake transcript includes the random values from the Hello
5031 messages, any given handshake will have different traffic secrets,
5032 even if the same input secrets are used, as is the case when the same
5033 PSK is used for multiple connections.
5034
5035
5036
5037
5038
5039
5040
5041
5042Rescorla Standards Track [Page 90]
5043
5044RFC 8446 TLS August 2018
5045
5046
50477.1. Key Schedule
5048
5049 The key derivation process makes use of the HKDF-Extract and
5050 HKDF-Expand functions as defined for HKDF [RFC5869], as well as the
5051 functions defined below:
5052
5053 HKDF-Expand-Label(Secret, Label, Context, Length) =
5054 HKDF-Expand(Secret, HkdfLabel, Length)
5055
5056 Where HkdfLabel is specified as:
5057
5058 struct {
5059 uint16 length = Length;
5060 opaque label<7..255> = "tls13 " + Label;
5061 opaque context<0..255> = Context;
5062 } HkdfLabel;
5063
5064 Derive-Secret(Secret, Label, Messages) =
5065 HKDF-Expand-Label(Secret, Label,
5066 Transcript-Hash(Messages), Hash.length)
5067
5068 The Hash function used by Transcript-Hash and HKDF is the cipher
5069 suite hash algorithm. Hash.length is its output length in bytes.
5070 Messages is the concatenation of the indicated handshake messages,
5071 including the handshake message type and length fields, but not
5072 including record layer headers. Note that in some cases a zero-
5073 length Context (indicated by "") is passed to HKDF-Expand-Label. The
5074 labels specified in this document are all ASCII strings and do not
5075 include a trailing NUL byte.
5076
5077 Note: With common hash functions, any label longer than 12 characters
5078 requires an additional iteration of the hash function to compute.
5079 The labels in this specification have all been chosen to fit within
5080 this limit.
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098Rescorla Standards Track [Page 91]
5099
5100RFC 8446 TLS August 2018
5101
5102
5103 Keys are derived from two input secrets using the HKDF-Extract and
5104 Derive-Secret functions. The general pattern for adding a new secret
5105 is to use HKDF-Extract with the Salt being the current secret state
5106 and the Input Keying Material (IKM) being the new secret to be added.
5107 In this version of TLS 1.3, the two input secrets are:
5108
5109 - PSK (a pre-shared key established externally or derived from the
5110 resumption_master_secret value from a previous connection)
5111
5112 - (EC)DHE shared secret (Section 7.4)
5113
5114 This produces a full key derivation schedule shown in the diagram
5115 below. In this diagram, the following formatting conventions apply:
5116
5117 - HKDF-Extract is drawn as taking the Salt argument from the top and
5118 the IKM argument from the left, with its output to the bottom and
5119 the name of the output on the right.
5120
5121 - Derive-Secret's Secret argument is indicated by the incoming
5122 arrow. For instance, the Early Secret is the Secret for
5123 generating the client_early_traffic_secret.
5124
5125 - "0" indicates a string of Hash.length bytes set to zero.
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154Rescorla Standards Track [Page 92]
5155
5156RFC 8446 TLS August 2018
5157
5158
5159 0
5160 |
5161 v
5162 PSK -> HKDF-Extract = Early Secret
5163 |
5164 +-----> Derive-Secret(., "ext binder" | "res binder", "")
5165 | = binder_key
5166 |
5167 +-----> Derive-Secret(., "c e traffic", ClientHello)
5168 | = client_early_traffic_secret
5169 |
5170 +-----> Derive-Secret(., "e exp master", ClientHello)
5171 | = early_exporter_master_secret
5172 v
5173 Derive-Secret(., "derived", "")
5174 |
5175 v
5176 (EC)DHE -> HKDF-Extract = Handshake Secret
5177 |
5178 +-----> Derive-Secret(., "c hs traffic",
5179 | ClientHello...ServerHello)
5180 | = client_handshake_traffic_secret
5181 |
5182 +-----> Derive-Secret(., "s hs traffic",
5183 | ClientHello...ServerHello)
5184 | = server_handshake_traffic_secret
5185 v
5186 Derive-Secret(., "derived", "")
5187 |
5188 v
5189 0 -> HKDF-Extract = Master Secret
5190 |
5191 +-----> Derive-Secret(., "c ap traffic",
5192 | ClientHello...server Finished)
5193 | = client_application_traffic_secret_0
5194 |
5195 +-----> Derive-Secret(., "s ap traffic",
5196 | ClientHello...server Finished)
5197 | = server_application_traffic_secret_0
5198 |
5199 +-----> Derive-Secret(., "exp master",
5200 | ClientHello...server Finished)
5201 | = exporter_master_secret
5202 |
5203 +-----> Derive-Secret(., "res master",
5204 ClientHello...client Finished)
5205 = resumption_master_secret
5206
5207
5208
5209
5210Rescorla Standards Track [Page 93]
5211
5212RFC 8446 TLS August 2018
5213
5214
5215 The general pattern here is that the secrets shown down the left side
5216 of the diagram are just raw entropy without context, whereas the
5217 secrets down the right side include Handshake Context and therefore
5218 can be used to derive working keys without additional context. Note
5219 that the different calls to Derive-Secret may take different Messages
5220 arguments, even with the same secret. In a 0-RTT exchange,
5221 Derive-Secret is called with four distinct transcripts; in a
5222 1-RTT-only exchange, it is called with three distinct transcripts.
5223
5224 If a given secret is not available, then the 0-value consisting of a
5225 string of Hash.length bytes set to zeros is used. Note that this
5226 does not mean skipping rounds, so if PSK is not in use, Early Secret
5227 will still be HKDF-Extract(0, 0). For the computation of the
5228 binder_key, the label is "ext binder" for external PSKs (those
5229 provisioned outside of TLS) and "res binder" for resumption PSKs
5230 (those provisioned as the resumption master secret of a previous
5231 handshake). The different labels prevent the substitution of one
5232 type of PSK for the other.
5233
5234 There are multiple potential Early Secret values, depending on which
5235 PSK the server ultimately selects. The client will need to compute
5236 one for each potential PSK; if no PSK is selected, it will then need
5237 to compute the Early Secret corresponding to the zero PSK.
5238
5239 Once all the values which are to be derived from a given secret have
5240 been computed, that secret SHOULD be erased.
5241
52427.2. Updating Traffic Secrets
5243
5244 Once the handshake is complete, it is possible for either side to
5245 update its sending traffic keys using the KeyUpdate handshake message
5246 defined in Section 4.6.3. The next generation of traffic keys is
5247 computed by generating client_/server_application_traffic_secret_N+1
5248 from client_/server_application_traffic_secret_N as described in this
5249 section and then re-deriving the traffic keys as described in
5250 Section 7.3.
5251
5252 The next-generation application_traffic_secret is computed as:
5253
5254 application_traffic_secret_N+1 =
5255 HKDF-Expand-Label(application_traffic_secret_N,
5256 "traffic upd", "", Hash.length)
5257
5258 Once client_/server_application_traffic_secret_N+1 and its associated
5259 traffic keys have been computed, implementations SHOULD delete
5260 client_/server_application_traffic_secret_N and its associated
5261 traffic keys.
5262
5263
5264
5265
5266Rescorla Standards Track [Page 94]
5267
5268RFC 8446 TLS August 2018
5269
5270
52717.3. Traffic Key Calculation
5272
5273 The traffic keying material is generated from the following input
5274 values:
5275
5276 - A secret value
5277
5278 - A purpose value indicating the specific value being generated
5279
5280 - The length of the key being generated
5281
5282 The traffic keying material is generated from an input traffic secret
5283 value using:
5284
5285 [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length)
5286 [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)
5287
5288 [sender] denotes the sending side. The value of Secret for each
5289 record type is shown in the table below.
5290
5291 +-------------------+---------------------------------------+
5292 | Record Type | Secret |
5293 +-------------------+---------------------------------------+
5294 | 0-RTT Application | client_early_traffic_secret |
5295 | | |
5296 | Handshake | [sender]_handshake_traffic_secret |
5297 | | |
5298 | Application Data | [sender]_application_traffic_secret_N |
5299 +-------------------+---------------------------------------+
5300
5301 All the traffic keying material is recomputed whenever the underlying
5302 Secret changes (e.g., when changing from the handshake to Application
5303 Data keys or upon a key update).
5304
53057.4. (EC)DHE Shared Secret Calculation
5306
53077.4.1. Finite Field Diffie-Hellman
5308
5309 For finite field groups, a conventional Diffie-Hellman [DH76]
5310 computation is performed. The negotiated key (Z) is converted to a
5311 byte string by encoding in big-endian form and left-padded with zeros
5312 up to the size of the prime. This byte string is used as the shared
5313 secret in the key schedule as specified above.
5314
5315 Note that this construction differs from previous versions of TLS
5316 which removed leading zeros.
5317
5318
5319
5320
5321
5322Rescorla Standards Track [Page 95]
5323
5324RFC 8446 TLS August 2018
5325
5326
53277.4.2. Elliptic Curve Diffie-Hellman
5328
5329 For secp256r1, secp384r1, and secp521r1, ECDH calculations (including
5330 parameter and key generation as well as the shared secret
5331 calculation) are performed according to [IEEE1363] using the
5332 ECKAS-DH1 scheme with the identity map as the key derivation function
5333 (KDF), so that the shared secret is the x-coordinate of the ECDH
5334 shared secret elliptic curve point represented as an octet string.
5335 Note that this octet string ("Z" in IEEE 1363 terminology) as output
5336 by FE2OSP (the Field Element to Octet String Conversion Primitive)
5337 has constant length for any given field; leading zeros found in this
5338 octet string MUST NOT be truncated.
5339
5340 (Note that this use of the identity KDF is a technicality. The
5341 complete picture is that ECDH is employed with a non-trivial KDF
5342 because TLS does not directly use this secret for anything other than
5343 for computing other secrets.)
5344
5345 For X25519 and X448, the ECDH calculations are as follows:
5346
5347 - The public key to put into the KeyShareEntry.key_exchange
5348 structure is the result of applying the ECDH scalar multiplication
5349 function to the secret key of appropriate length (into scalar
5350 input) and the standard public basepoint (into u-coordinate point
5351 input).
5352
5353 - The ECDH shared secret is the result of applying the ECDH scalar
5354 multiplication function to the secret key (into scalar input) and
5355 the peer's public key (into u-coordinate point input). The output
5356 is used raw, with no processing.
5357
5358 For these curves, implementations SHOULD use the approach specified
5359 in [RFC7748] to calculate the Diffie-Hellman shared secret.
5360 Implementations MUST check whether the computed Diffie-Hellman shared
5361 secret is the all-zero value and abort if so, as described in
5362 Section 6 of [RFC7748]. If implementors use an alternative
5363 implementation of these elliptic curves, they SHOULD perform the
5364 additional checks specified in Section 7 of [RFC7748].
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378Rescorla Standards Track [Page 96]
5379
5380RFC 8446 TLS August 2018
5381
5382
53837.5. Exporters
5384
5385 [RFC5705] defines keying material exporters for TLS in terms of the 8446:5405 ../scram/scram.go:115
5386 TLS pseudorandom function (PRF). This document replaces the PRF with
5387 HKDF, thus requiring a new construction. The exporter interface
5388 remains the same.
5389
5390 The exporter value is computed as:
5391
5392 TLS-Exporter(label, context_value, key_length) =
5393 HKDF-Expand-Label(Derive-Secret(Secret, label, ""),
5394 "exporter", Hash(context_value), key_length)
5395
5396 Where Secret is either the early_exporter_master_secret or the
5397 exporter_master_secret. Implementations MUST use the
5398 exporter_master_secret unless explicitly specified by the
5399 application. The early_exporter_master_secret is defined for use in
5400 settings where an exporter is needed for 0-RTT data. A separate
5401 interface for the early exporter is RECOMMENDED; this avoids the
5402 exporter user accidentally using an early exporter when a regular one
5403 is desired or vice versa.
5404
5405 If no context is provided, the context_value is zero length. 8446:5385 ../scram/scram.go:115
5406 Consequently, providing no context computes the same value as
5407 providing an empty context. This is a change from previous versions
5408 of TLS where an empty context produced a different output than an
5409 absent context. As of this document's publication, no allocated
5410 exporter label is used both with and without a context. Future
5411 specifications MUST NOT define a use of exporters that permit both an
5412 empty context and no context with the same label. New uses of
5413 exporters SHOULD provide a context in all exporter computations,
5414 though the value could be empty.
5415
5416 Requirements for the format of exporter labels are defined in
5417 Section 4 of [RFC5705].
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434Rescorla Standards Track [Page 97]
5435
5436RFC 8446 TLS August 2018
5437
5438
54398. 0-RTT and Anti-Replay
5440
5441 As noted in Section 2.3 and Appendix E.5, TLS does not provide
5442 inherent replay protections for 0-RTT data. There are two potential
5443 threats to be concerned with:
5444
5445 - Network attackers who mount a replay attack by simply duplicating
5446 a flight of 0-RTT data.
5447
5448 - Network attackers who take advantage of client retry behavior to
5449 arrange for the server to receive multiple copies of an
5450 application message. This threat already exists to some extent
5451 because clients that value robustness respond to network errors by
5452 attempting to retry requests. However, 0-RTT adds an additional
5453 dimension for any server system which does not maintain globally
5454 consistent server state. Specifically, if a server system has
5455 multiple zones where tickets from zone A will not be accepted in
5456 zone B, then an attacker can duplicate a ClientHello and early
5457 data intended for A to both A and B. At A, the data will be
5458 accepted in 0-RTT, but at B the server will reject 0-RTT data and
5459 instead force a full handshake. If the attacker blocks the
5460 ServerHello from A, then the client will complete the handshake
5461 with B and probably retry the request, leading to duplication on
5462 the server system as a whole.
5463
5464 The first class of attack can be prevented by sharing state to
5465 guarantee that the 0-RTT data is accepted at most once. Servers
5466 SHOULD provide that level of replay safety by implementing one of the
5467 methods described in this section or by equivalent means. It is
5468 understood, however, that due to operational concerns not all
5469 deployments will maintain state at that level. Therefore, in normal
5470 operation, clients will not know which, if any, of these mechanisms
5471 servers actually implement and hence MUST only send early data which
5472 they deem safe to be replayed.
5473
5474 In addition to the direct effects of replays, there is a class of
5475 attacks where even operations normally considered idempotent could be
5476 exploited by a large number of replays (timing attacks, resource
5477 limit exhaustion and others, as described in Appendix E.5). Those
5478 can be mitigated by ensuring that every 0-RTT payload can be replayed
5479 only a limited number of times. The server MUST ensure that any
5480 instance of it (be it a machine, a thread, or any other entity within
5481 the relevant serving infrastructure) would accept 0-RTT for the same
5482 0-RTT handshake at most once; this limits the number of replays to
5483 the number of server instances in the deployment. Such a guarantee
5484 can be accomplished by locally recording data from recently received
5485 ClientHellos and rejecting repeats, or by any other method that
5486
5487
5488
5489
5490Rescorla Standards Track [Page 98]
5491
5492RFC 8446 TLS August 2018
5493
5494
5495 provides the same or a stronger guarantee. The "at most once per
5496 server instance" guarantee is a minimum requirement; servers SHOULD
5497 limit 0-RTT replays further when feasible.
5498
5499 The second class of attack cannot be prevented at the TLS layer and
5500 MUST be dealt with by any application. Note that any application
5501 whose clients implement any kind of retry behavior already needs to
5502 implement some sort of anti-replay defense.
5503
55048.1. Single-Use Tickets
5505
5506 The simplest form of anti-replay defense is for the server to only
5507 allow each session ticket to be used once. For instance, the server
5508 can maintain a database of all outstanding valid tickets, deleting
5509 each ticket from the database as it is used. If an unknown ticket is
5510 provided, the server would then fall back to a full handshake.
5511
5512 If the tickets are not self-contained but rather are database keys,
5513 and the corresponding PSKs are deleted upon use, then connections
5514 established using PSKs enjoy forward secrecy. This improves security
5515 for all 0-RTT data and PSK usage when PSK is used without (EC)DHE.
5516
5517 Because this mechanism requires sharing the session database between
5518 server nodes in environments with multiple distributed servers, it
5519 may be hard to achieve high rates of successful PSK 0-RTT connections
5520 when compared to self-encrypted tickets. Unlike session databases,
5521 session tickets can successfully do PSK-based session establishment
5522 even without consistent storage, though when 0-RTT is allowed they
5523 still require consistent storage for anti-replay of 0-RTT data, as
5524 detailed in the following section.
5525
55268.2. Client Hello Recording
5527
5528 An alternative form of anti-replay is to record a unique value
5529 derived from the ClientHello (generally either the random value or
5530 the PSK binder) and reject duplicates. Recording all ClientHellos
5531 causes state to grow without bound, but a server can instead record
5532 ClientHellos within a given time window and use the
5533 "obfuscated_ticket_age" to ensure that tickets aren't reused outside
5534 that window.
5535
5536 In order to implement this, when a ClientHello is received, the
5537 server first verifies the PSK binder as described in Section 4.2.11.
5538 It then computes the expected_arrival_time as described in the next
5539 section and rejects 0-RTT if it is outside the recording window,
5540 falling back to the 1-RTT handshake.
5541
5542
5543
5544
5545
5546Rescorla Standards Track [Page 99]
5547
5548RFC 8446 TLS August 2018
5549
5550
5551 If the expected_arrival_time is in the window, then the server checks
5552 to see if it has recorded a matching ClientHello. If one is found,
5553 it either aborts the handshake with an "illegal_parameter" alert or
5554 accepts the PSK but rejects 0-RTT. If no matching ClientHello is
5555 found, then it accepts 0-RTT and then stores the ClientHello for as
5556 long as the expected_arrival_time is inside the window. Servers MAY
5557 also implement data stores with false positives, such as Bloom
5558 filters, in which case they MUST respond to apparent replay by
5559 rejecting 0-RTT but MUST NOT abort the handshake.
5560
5561 The server MUST derive the storage key only from validated sections
5562 of the ClientHello. If the ClientHello contains multiple PSK
5563 identities, then an attacker can create multiple ClientHellos with
5564 different binder values for the less-preferred identity on the
5565 assumption that the server will not verify it (as recommended by
5566 Section 4.2.11). I.e., if the client sends PSKs A and B but the
5567 server prefers A, then the attacker can change the binder for B
5568 without affecting the binder for A. If the binder for B is part of
5569 the storage key, then this ClientHello will not appear as a
5570 duplicate, which will cause the ClientHello to be accepted, and may
5571 cause side effects such as replay cache pollution, although any 0-RTT
5572 data will not be decryptable because it will use different keys. If
5573 the validated binder or the ClientHello.random is used as the storage
5574 key, then this attack is not possible.
5575
5576 Because this mechanism does not require storing all outstanding
5577 tickets, it may be easier to implement in distributed systems with
5578 high rates of resumption and 0-RTT, at the cost of potentially weaker
5579 anti-replay defense because of the difficulty of reliably storing and
5580 retrieving the received ClientHello messages. In many such systems,
5581 it is impractical to have globally consistent storage of all the
5582 received ClientHellos. In this case, the best anti-replay protection
5583 is provided by having a single storage zone be authoritative for a
5584 given ticket and refusing 0-RTT for that ticket in any other zone.
5585 This approach prevents simple replay by the attacker because only one
5586 zone will accept 0-RTT data. A weaker design is to implement
5587 separate storage for each zone but allow 0-RTT in any zone. This
5588 approach limits the number of replays to once per zone. Application
5589 message duplication of course remains possible with either design.
5590
5591 When implementations are freshly started, they SHOULD reject 0-RTT as
5592 long as any portion of their recording window overlaps the startup
5593 time. Otherwise, they run the risk of accepting replays which were
5594 originally sent during that period.
5595
5596
5597
5598
5599
5600
5601
5602Rescorla Standards Track [Page 100]
5603
5604RFC 8446 TLS August 2018
5605
5606
5607 Note: If the client's clock is running much faster than the server's,
5608 then a ClientHello may be received that is outside the window in the
5609 future, in which case it might be accepted for 1-RTT, causing a
5610 client retry, and then acceptable later for 0-RTT. This is another
5611 variant of the second form of attack described in Section 8.
5612
56138.3. Freshness Checks
5614
5615 Because the ClientHello indicates the time at which the client sent
5616 it, it is possible to efficiently determine whether a ClientHello was
5617 likely sent reasonably recently and only accept 0-RTT for such a
5618 ClientHello, otherwise falling back to a 1-RTT handshake. This is
5619 necessary for the ClientHello storage mechanism described in
5620 Section 8.2 because otherwise the server needs to store an unlimited
5621 number of ClientHellos, and is a useful optimization for self-
5622 contained single-use tickets because it allows efficient rejection of
5623 ClientHellos which cannot be used for 0-RTT.
5624
5625 In order to implement this mechanism, a server needs to store the
5626 time that the server generated the session ticket, offset by an
5627 estimate of the round-trip time between client and server. I.e.,
5628
5629 adjusted_creation_time = creation_time + estimated_RTT
5630
5631 This value can be encoded in the ticket, thus avoiding the need to
5632 keep state for each outstanding ticket. The server can determine the
5633 client's view of the age of the ticket by subtracting the ticket's
5634 "ticket_age_add" value from the "obfuscated_ticket_age" parameter in
5635 the client's "pre_shared_key" extension. The server can determine
5636 the expected_arrival_time of the ClientHello as:
5637
5638 expected_arrival_time = adjusted_creation_time + clients_ticket_age
5639
5640 When a new ClientHello is received, the expected_arrival_time is then
5641 compared against the current server wall clock time and if they
5642 differ by more than a certain amount, 0-RTT is rejected, though the
5643 1-RTT handshake can be allowed to complete.
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658Rescorla Standards Track [Page 101]
5659
5660RFC 8446 TLS August 2018
5661
5662
5663 There are several potential sources of error that might cause
5664 mismatches between the expected_arrival_time and the measured time.
5665 Variations in client and server clock rates are likely to be minimal,
5666 though potentially the absolute times may be off by large values.
5667 Network propagation delays are the most likely causes of a mismatch
5668 in legitimate values for elapsed time. Both the NewSessionTicket and
5669 ClientHello messages might be retransmitted and therefore delayed,
5670 which might be hidden by TCP. For clients on the Internet, this
5671 implies windows on the order of ten seconds to account for errors in
5672 clocks and variations in measurements; other deployment scenarios may
5673 have different needs. Clock skew distributions are not symmetric, so
5674 the optimal tradeoff may involve an asymmetric range of permissible
5675 mismatch values.
5676
5677 Note that freshness checking alone is not sufficient to prevent
5678 replays because it does not detect them during the error window,
5679 which -- depending on bandwidth and system capacity -- could include
5680 billions of replays in real-world settings. In addition, this
5681 freshness checking is only done at the time the ClientHello is
5682 received and not when subsequent early Application Data records are
5683 received. After early data is accepted, records may continue to be
5684 streamed to the server over a longer time period.
5685
56869. Compliance Requirements
5687
56889.1. Mandatory-to-Implement Cipher Suites
5689
5690 In the absence of an application profile standard specifying
5691 otherwise:
5692
5693 A TLS-compliant application MUST implement the TLS_AES_128_GCM_SHA256
5694 [GCM] cipher suite and SHOULD implement the TLS_AES_256_GCM_SHA384
5695 [GCM] and TLS_CHACHA20_POLY1305_SHA256 [RFC8439] cipher suites (see
5696 Appendix B.4).
5697
5698 A TLS-compliant application MUST support digital signatures with
5699 rsa_pkcs1_sha256 (for certificates), rsa_pss_rsae_sha256 (for
5700 CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A
5701 TLS-compliant application MUST support key exchange with secp256r1
5702 (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748].
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714Rescorla Standards Track [Page 102]
5715
5716RFC 8446 TLS August 2018
5717
5718
57199.2. Mandatory-to-Implement Extensions
5720
5721 In the absence of an application profile standard specifying
5722 otherwise, a TLS-compliant application MUST implement the following
5723 TLS extensions:
5724
5725 - Supported Versions ("supported_versions"; Section 4.2.1)
5726
5727 - Cookie ("cookie"; Section 4.2.2)
5728
5729 - Signature Algorithms ("signature_algorithms"; Section 4.2.3)
5730
5731 - Signature Algorithms Certificate ("signature_algorithms_cert";
5732 Section 4.2.3)
5733
5734 - Negotiated Groups ("supported_groups"; Section 4.2.7)
5735
5736 - Key Share ("key_share"; Section 4.2.8)
5737
5738 - Server Name Indication ("server_name"; Section 3 of [RFC6066])
5739
5740 All implementations MUST send and use these extensions when offering
5741 applicable features:
5742
5743 - "supported_versions" is REQUIRED for all ClientHello, ServerHello,
5744 and HelloRetryRequest messages.
5745
5746 - "signature_algorithms" is REQUIRED for certificate authentication.
5747
5748 - "supported_groups" is REQUIRED for ClientHello messages using DHE
5749 or ECDHE key exchange.
5750
5751 - "key_share" is REQUIRED for DHE or ECDHE key exchange.
5752
5753 - "pre_shared_key" is REQUIRED for PSK key agreement.
5754
5755 - "psk_key_exchange_modes" is REQUIRED for PSK key agreement.
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767
5768
5769
5770Rescorla Standards Track [Page 103]
5771
5772RFC 8446 TLS August 2018
5773
5774
5775 A client is considered to be attempting to negotiate using this
5776 specification if the ClientHello contains a "supported_versions"
5777 extension with 0x0304 contained in its body. Such a ClientHello
5778 message MUST meet the following requirements:
5779
5780 - If not containing a "pre_shared_key" extension, it MUST contain
5781 both a "signature_algorithms" extension and a "supported_groups"
5782 extension.
5783
5784 - If containing a "supported_groups" extension, it MUST also contain
5785 a "key_share" extension, and vice versa. An empty
5786 KeyShare.client_shares vector is permitted.
5787
5788 Servers receiving a ClientHello which does not conform to these
5789 requirements MUST abort the handshake with a "missing_extension"
5790 alert.
5791
5792 Additionally, all implementations MUST support the use of the
5793 "server_name" extension with applications capable of using it.
5794 Servers MAY require clients to send a valid "server_name" extension.
5795 Servers requiring this extension SHOULD respond to a ClientHello
5796 lacking a "server_name" extension by terminating the connection with
5797 a "missing_extension" alert.
5798
57999.3. Protocol Invariants
5800
5801 This section describes invariants that TLS endpoints and middleboxes
5802 MUST follow. It also applies to earlier versions of TLS.
5803
5804 TLS is designed to be securely and compatibly extensible. Newer
5805 clients or servers, when communicating with newer peers, should
5806 negotiate the most preferred common parameters. The TLS handshake
5807 provides downgrade protection: Middleboxes passing traffic between a
5808 newer client and newer server without terminating TLS should be
5809 unable to influence the handshake (see Appendix E.1). At the same
5810 time, deployments update at different rates, so a newer client or
5811 server MAY continue to support older parameters, which would allow it
5812 to interoperate with older endpoints.
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823
5824
5825
5826Rescorla Standards Track [Page 104]
5827
5828RFC 8446 TLS August 2018
5829
5830
5831 For this to work, implementations MUST correctly handle extensible
5832 fields:
5833
5834 - A client sending a ClientHello MUST support all parameters
5835 advertised in it. Otherwise, the server may fail to interoperate
5836 by selecting one of those parameters.
5837
5838 - A server receiving a ClientHello MUST correctly ignore all
5839 unrecognized cipher suites, extensions, and other parameters.
5840 Otherwise, it may fail to interoperate with newer clients. In
5841 TLS 1.3, a client receiving a CertificateRequest or
5842 NewSessionTicket MUST also ignore all unrecognized extensions.
5843
5844 - A middlebox which terminates a TLS connection MUST behave as a
5845 compliant TLS server (to the original client), including having a
5846 certificate which the client is willing to accept, and also as a
5847 compliant TLS client (to the original server), including verifying
5848 the original server's certificate. In particular, it MUST
5849 generate its own ClientHello containing only parameters it
5850 understands, and it MUST generate a fresh ServerHello random
5851 value, rather than forwarding the endpoint's value.
5852
5853 Note that TLS's protocol requirements and security analysis only
5854 apply to the two connections separately. Safely deploying a TLS
5855 terminator requires additional security considerations which are
5856 beyond the scope of this document.
5857
5858 - A middlebox which forwards ClientHello parameters it does not
5859 understand MUST NOT process any messages beyond that ClientHello.
5860 It MUST forward all subsequent traffic unmodified. Otherwise, it
5861 may fail to interoperate with newer clients and servers.
5862
5863 Forwarded ClientHellos may contain advertisements for features not
5864 supported by the middlebox, so the response may include future TLS
5865 additions the middlebox does not recognize. These additions MAY
5866 change any message beyond the ClientHello arbitrarily. In
5867 particular, the values sent in the ServerHello might change, the
5868 ServerHello format might change, and the TLSCiphertext format
5869 might change.
5870
5871 The design of TLS 1.3 was constrained by widely deployed
5872 non-compliant TLS middleboxes (see Appendix D.4); however, it does
5873 not relax the invariants. Those middleboxes continue to be
5874 non-compliant.
5875
5876
5877
5878
5879
5880
5881
5882Rescorla Standards Track [Page 105]
5883
5884RFC 8446 TLS August 2018
5885
5886
588710. Security Considerations
5888
5889 Security issues are discussed throughout this memo, especially in
5890 Appendices C, D, and E.
5891
589211. IANA Considerations
5893
5894 This document uses several registries that were originally created in
5895 [RFC4346] and updated in [RFC8447]. IANA has updated these to
5896 reference this document. The registries and their allocation
5897 policies are below:
5898
5899 - TLS Cipher Suites registry: values with the first byte in the
5900 range 0-254 (decimal) are assigned via Specification Required
5901 [RFC8126]. Values with the first byte 255 (decimal) are reserved
5902 for Private Use [RFC8126].
5903
5904 IANA has added the cipher suites listed in Appendix B.4 to the
5905 registry. The "Value" and "Description" columns are taken from
5906 the table. The "DTLS-OK" and "Recommended" columns are both
5907 marked as "Y" for each new cipher suite.
5908
5909 - TLS ContentType registry: Future values are allocated via
5910 Standards Action [RFC8126].
5911
5912 - TLS Alerts registry: Future values are allocated via Standards
5913 Action [RFC8126]. IANA has populated this registry with the
5914 values from Appendix B.2. The "DTLS-OK" column is marked as "Y"
5915 for all such values. Values marked as "_RESERVED" have comments
5916 describing their previous usage.
5917
5918 - TLS HandshakeType registry: Future values are allocated via
5919 Standards Action [RFC8126]. IANA has updated this registry to
5920 rename item 4 from "NewSessionTicket" to "new_session_ticket" and
5921 populated this registry with the values from Appendix B.3. The
5922 "DTLS-OK" column is marked as "Y" for all such values. Values
5923 marked "_RESERVED" have comments describing their previous or
5924 temporary usage.
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938Rescorla Standards Track [Page 106]
5939
5940RFC 8446 TLS August 2018
5941
5942
5943 This document also uses the TLS ExtensionType Values registry
5944 originally created in [RFC4366]. IANA has updated it to reference
5945 this document. Changes to the registry follow:
5946
5947 - IANA has updated the registration policy as follows:
5948
5949 Values with the first byte in the range 0-254 (decimal) are
5950 assigned via Specification Required [RFC8126]. Values with the
5951 first byte 255 (decimal) are reserved for Private Use [RFC8126].
5952
5953 - IANA has updated this registry to include the "key_share",
5954 "pre_shared_key", "psk_key_exchange_modes", "early_data",
5955 "cookie", "supported_versions", "certificate_authorities",
5956 "oid_filters", "post_handshake_auth", and
5957 "signature_algorithms_cert" extensions with the values defined in
5958 this document and the "Recommended" value of "Y".
5959
5960 - IANA has updated this registry to include a "TLS 1.3" column which
5961 lists the messages in which the extension may appear. This column
5962 has been initially populated from the table in Section 4.2, with
5963 any extension not listed there marked as "-" to indicate that it
5964 is not used by TLS 1.3.
5965
5966 This document updates an entry in the TLS Certificate Types registry
5967 originally created in [RFC6091] and updated in [RFC8447]. IANA has
5968 updated the entry for value 1 to have the name "OpenPGP_RESERVED",
5969 "Recommended" value "N", and comment "Used in TLS versions prior
5970 to 1.3."
5971
5972 This document updates an entry in the TLS Certificate Status Types
5973 registry originally created in [RFC6961]. IANA has updated the entry
5974 for value 2 to have the name "ocsp_multi_RESERVED" and comment "Used
5975 in TLS versions prior to 1.3".
5976
5977 This document updates two entries in the TLS Supported Groups
5978 registry (created under a different name by [RFC4492]; now maintained
5979 by [RFC8422]) and updated by [RFC7919] and [RFC8447]. The entries
5980 for values 29 and 30 (x25519 and x448) have been updated to also
5981 refer to this document.
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994Rescorla Standards Track [Page 107]
5995
5996RFC 8446 TLS August 2018
5997
5998
5999 In addition, this document defines two new registries that are
6000 maintained by IANA:
6001
6002 - TLS SignatureScheme registry: Values with the first byte in the
6003 range 0-253 (decimal) are assigned via Specification Required
6004 [RFC8126]. Values with the first byte 254 or 255 (decimal) are
6005 reserved for Private Use [RFC8126]. Values with the first byte in
6006 the range 0-6 or with the second byte in the range 0-3 that are
6007 not currently allocated are reserved for backward compatibility.
6008 This registry has a "Recommended" column. The registry has been
6009 initially populated with the values described in Section 4.2.3.
6010 The following values are marked as "Recommended":
6011 ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384,
6012 rsa_pss_rsae_sha256, rsa_pss_rsae_sha384, rsa_pss_rsae_sha512,
6013 rsa_pss_pss_sha256, rsa_pss_pss_sha384, rsa_pss_pss_sha512, and
6014 ed25519. The "Recommended" column is assigned a value of "N"
6015 unless explicitly requested, and adding a value with a
6016 "Recommended" value of "Y" requires Standards Action [RFC8126].
6017 IESG Approval is REQUIRED for a Y->N transition.
6018
6019 - TLS PskKeyExchangeMode registry: Values in the range 0-253
6020 (decimal) are assigned via Specification Required [RFC8126].
6021 The values 254 and 255 (decimal) are reserved for Private Use
6022 [RFC8126]. This registry has a "Recommended" column. The
6023 registry has been initially populated with psk_ke (0) and
6024 psk_dhe_ke (1). Both are marked as "Recommended". The
6025 "Recommended" column is assigned a value of "N" unless explicitly
6026 requested, and adding a value with a "Recommended" value of "Y"
6027 requires Standards Action [RFC8126]. IESG Approval is REQUIRED
6028 for a Y->N transition.
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050Rescorla Standards Track [Page 108]
6051
6052RFC 8446 TLS August 2018
6053
6054
605512. References
6056
605712.1. Normative References
6058
6059 [DH76] Diffie, W. and M. Hellman, "New directions in
6060 cryptography", IEEE Transactions on Information
6061 Theory, Vol. 22 No. 6, pp. 644-654,
6062 DOI 10.1109/TIT.1976.1055638, November 1976.
6063
6064 [ECDSA] American National Standards Institute, "Public Key
6065 Cryptography for the Financial Services Industry: The
6066 Elliptic Curve Digital Signature Algorithm (ECDSA)",
6067 ANSI ANS X9.62-2005, November 2005.
6068
6069 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of
6070 Operation: Galois/Counter Mode (GCM) and GMAC",
6071 NIST Special Publication 800-38D,
6072 DOI 10.6028/NIST.SP.800-38D, November 2007.
6073
6074 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
6075 Hashing for Message Authentication", RFC 2104,
6076 DOI 10.17487/RFC2104, February 1997,
6077 <https://www.rfc-editor.org/info/rfc2104>.
6078
6079 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
6080 Requirement Levels", BCP 14, RFC 2119,
6081 DOI 10.17487/RFC2119, March 1997,
6082 <https://www.rfc-editor.org/info/rfc2119>.
6083
6084 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
6085 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
6086 <https://www.rfc-editor.org/info/rfc5116>.
6087
6088 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
6089 Housley, R., and W. Polk, "Internet X.509 Public Key
6090 Infrastructure Certificate and Certificate Revocation List
6091 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
6092 <https://www.rfc-editor.org/info/rfc5280>.
6093
6094 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport
6095 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705,
6096 March 2010, <https://www.rfc-editor.org/info/rfc5705>.
6097
6098 [RFC5756] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk,
6099 "Updates for RSAES-OAEP and RSASSA-PSS Algorithm
6100 Parameters", RFC 5756, DOI 10.17487/RFC5756, January 2010,
6101 <https://www.rfc-editor.org/info/rfc5756>.
6102
6103
6104
6105
6106Rescorla Standards Track [Page 109]
6107
6108RFC 8446 TLS August 2018
6109
6110
6111 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
6112 Key Derivation Function (HKDF)", RFC 5869,
6113 DOI 10.17487/RFC5869, May 2010,
6114 <https://www.rfc-editor.org/info/rfc5869>.
6115
6116 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS)
6117 Extensions: Extension Definitions", RFC 6066,
6118 DOI 10.17487/RFC6066, January 2011,
6119 <https://www.rfc-editor.org/info/rfc6066>.
6120
6121 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for
6122 Transport Layer Security (TLS)", RFC 6655,
6123 DOI 10.17487/RFC6655, July 2012,
6124 <https://www.rfc-editor.org/info/rfc6655>.
6125
6126 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A.,
6127 Galperin, S., and C. Adams, "X.509 Internet Public Key
6128 Infrastructure Online Certificate Status Protocol - OCSP",
6129 RFC 6960, DOI 10.17487/RFC6960, June 2013,
6130 <https://www.rfc-editor.org/info/rfc6960>.
6131
6132 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS)
6133 Multiple Certificate Status Request Extension", RFC 6961,
6134 DOI 10.17487/RFC6961, June 2013,
6135 <https://www.rfc-editor.org/info/rfc6961>.
6136
6137 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate
6138 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013,
6139 <https://www.rfc-editor.org/info/rfc6962>.
6140
6141 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature
6142 Algorithm (DSA) and Elliptic Curve Digital Signature
6143 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979,
6144 August 2013, <https://www.rfc-editor.org/info/rfc6979>.
6145
6146 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,
6147 "Transport Layer Security (TLS) Application-Layer Protocol
6148 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
6149 July 2014, <https://www.rfc-editor.org/info/rfc7301>.
6150
6151 [RFC7507] Moeller, B. and A. Langley, "TLS Fallback Signaling Cipher
6152 Suite Value (SCSV) for Preventing Protocol Downgrade
6153 Attacks", RFC 7507, DOI 10.17487/RFC7507, April 2015,
6154 <https://www.rfc-editor.org/info/rfc7507>.
6155
6156 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves
6157 for Security", RFC 7748, DOI 10.17487/RFC7748,
6158 January 2016, <https://www.rfc-editor.org/info/rfc7748>.
6159
6160
6161
6162Rescorla Standards Track [Page 110]
6163
6164RFC 8446 TLS August 2018
6165
6166
6167 [RFC7919] Gillmor, D., "Negotiated Finite Field Diffie-Hellman
6168 Ephemeral Parameters for Transport Layer Security (TLS)",
6169 RFC 7919, DOI 10.17487/RFC7919, August 2016,
6170 <https://www.rfc-editor.org/info/rfc7919>.
6171
6172 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch,
6173 "PKCS #1: RSA Cryptography Specifications Version 2.2",
6174 RFC 8017, DOI 10.17487/RFC8017, November 2016,
6175 <https://www.rfc-editor.org/info/rfc8017>.
6176
6177 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital
6178 Signature Algorithm (EdDSA)", RFC 8032,
6179 DOI 10.17487/RFC8032, January 2017,
6180 <https://www.rfc-editor.org/info/rfc8032>.
6181
6182 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
6183 Writing an IANA Considerations Section in RFCs", BCP 26,
6184 RFC 8126, DOI 10.17487/RFC8126, June 2017,
6185 <https://www.rfc-editor.org/info/rfc8126>.
6186
6187 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in
6188 RFC 2119 Key Words", BCP 14, RFC 8174,
6189 DOI 10.17487/RFC8174, May 2017,
6190 <https://www.rfc-editor.org/info/rfc8174>.
6191
6192 [RFC8439] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF
6193 Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018,
6194 <https://www.rfc-editor.org/info/rfc8439>.
6195
6196 [SHS] Dang, Q., "Secure Hash Standard (SHS)", National Institute
6197 of Standards and Technology report,
6198 DOI 10.6028/NIST.FIPS.180-4, August 2015.
6199
6200 [X690] ITU-T, "Information technology -- ASN.1 encoding rules:
6201 Specification of Basic Encoding Rules (BER), Canonical
6202 Encoding Rules (CER) and Distinguished Encoding Rules
6203 (DER)", ISO/IEC 8825-1:2015, November 2015.
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218Rescorla Standards Track [Page 111]
6219
6220RFC 8446 TLS August 2018
6221
6222
622312.2. Informative References
6224
6225 [AEAD-LIMITS]
6226 Luykx, A. and K. Paterson, "Limits on Authenticated
6227 Encryption Use in TLS", August 2017,
6228 <http://www.isg.rhul.ac.uk/~kp/TLS-AEbounds.pdf>.
6229
6230 [BBFGKZ16]
6231 Bhargavan, K., Brzuska, C., Fournet, C., Green, M.,
6232 Kohlweiss, M., and S. Zanella-Beguelin, "Downgrade
6233 Resilience in Key-Exchange Protocols", Proceedings of IEEE
6234 Symposium on Security and Privacy (San Jose),
6235 DOI 10.1109/SP.2016.37, May 2016.
6236
6237 [BBK17] Bhargavan, K., Blanchet, B., and N. Kobeissi, "Verified
6238 Models and Reference Implementations for the TLS 1.3
6239 Standard Candidate", Proceedings of IEEE Symposium on
6240 Security and Privacy (San Jose), DOI 10.1109/SP.2017.26,
6241 May 2017.
6242
6243 [BDFKPPRSZZ16]
6244 Bhargavan, K., Delignat-Lavaud, A., Fournet, C.,
6245 Kohlweiss, M., Pan, J., Protzenko, J., Rastogi, A., Swamy,
6246 N., Zanella-Beguelin, S., and J. Zinzindohoue,
6247 "Implementing and Proving the TLS 1.3 Record Layer",
6248 Proceedings of IEEE Symposium on Security and Privacy (San
6249 Jose), May 2017, <https://eprint.iacr.org/2016/1178>.
6250
6251 [Ben17a] Benjamin, D., "Presentation before the TLS WG at
6252 IETF 100", November 2017,
6253 <https://datatracker.ietf.org/meeting/100/materials/
6254 slides-100-tls-sessa-tls13/>.
6255
6256 [Ben17b] Benjamin, D., "Additional TLS 1.3 results from Chrome",
6257 message to the TLS mailing list, 18 December 2017,
6258 <https://www.ietf.org/mail-archive/web/tls/current/
6259 msg25168.html>.
6260
6261 [Blei98] Bleichenbacher, D., "Chosen Ciphertext Attacks against
6262 Protocols Based on RSA Encryption Standard PKCS #1",
6263 Proceedings of CRYPTO '98, 1998.
6264
6265 [BMMRT15] Badertscher, C., Matt, C., Maurer, U., Rogaway, P., and B.
6266 Tackmann, "Augmented Secure Channels and the Goal of the
6267 TLS 1.3 Record Layer", ProvSec 2015, September 2015,
6268 <https://eprint.iacr.org/2015/394>.
6269
6270
6271
6272
6273
6274Rescorla Standards Track [Page 112]
6275
6276RFC 8446 TLS August 2018
6277
6278
6279 [BT16] Bellare, M. and B. Tackmann, "The Multi-User Security of
6280 Authenticated Encryption: AES-GCM in TLS 1.3", Proceedings
6281 of CRYPTO 2016, July 2016,
6282 <https://eprint.iacr.org/2016/564>.
6283
6284 [CCG16] Cohn-Gordon, K., Cremers, C., and L. Garratt, "On
6285 Post-compromise Security", IEEE Computer Security
6286 Foundations Symposium, DOI 10.1109/CSF.2016.19, July 2015.
6287
6288 [CHECKOWAY]
6289 Checkoway, S., Maskiewicz, J., Garman, C., Fried, J.,
6290 Cohney, S., Green, M., Heninger, N., Weinmann, R.,
6291 Rescorla, E., and H. Shacham, "A Systematic Analysis of
6292 the Juniper Dual EC Incident", Proceedings of the 2016 ACM
6293 SIGSAC Conference on Computer and Communications Security
6294 - CCS '16, DOI 10.1145/2976749.2978395, October 2016.
6295
6296 [CHHSV17] Cremers, C., Horvat, M., Hoyland, J., Scott, S., and T.
6297 van der Merwe, "Awkward Handshake: Possible mismatch of
6298 client/server view on client authentication in
6299 post-handshake mode in Revision 18", message to the TLS
6300 mailing list, 10 February 2017, <https://www.ietf.org/
6301 mail-archive/web/tls/current/msg22382.html>.
6302
6303 [CHSV16] Cremers, C., Horvat, M., Scott, S., and T. van der Merwe,
6304 "Automated Analysis and Verification of TLS 1.3: 0-RTT,
6305 Resumption and Delayed Authentication", Proceedings of
6306 IEEE Symposium on Security and Privacy (San Jose),
6307 DOI 10.1109/SP.2016.35, May 2016,
6308 <https://ieeexplore.ieee.org/document/7546518/>.
6309
6310 [CK01] Canetti, R. and H. Krawczyk, "Analysis of Key-Exchange
6311 Protocols and Their Use for Building Secure Channels",
6312 Proceedings of Eurocrypt 2001,
6313 DOI 10.1007/3-540-44987-6_28, April 2001.
6314
6315 [CLINIC] Miller, B., Huang, L., Joseph, A., and J. Tygar, "I Know
6316 Why You Went to the Clinic: Risks and Realization of HTTPS
6317 Traffic Analysis", Privacy Enhancing Technologies, pp.
6318 143-163, DOI 10.1007/978-3-319-08506-7_8, 2014.
6319
6320 [DFGS15] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila,
6321 "A Cryptographic Analysis of the TLS 1.3 Handshake
6322 Protocol Candidates", Proceedings of ACM CCS 2015,
6323 October 2015, <https://eprint.iacr.org/2015/914>.
6324
6325
6326
6327
6328
6329
6330Rescorla Standards Track [Page 113]
6331
6332RFC 8446 TLS August 2018
6333
6334
6335 [DFGS16] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila,
6336 "A Cryptographic Analysis of the TLS 1.3 Full and
6337 Pre-shared Key Handshake Protocol", TRON 2016,
6338 February 2016, <https://eprint.iacr.org/2016/081>.
6339
6340 [DOW92] Diffie, W., van Oorschot, P., and M. Wiener,
6341 "Authentication and authenticated key exchanges", Designs,
6342 Codes and Cryptography, DOI 10.1007/BF00124891, June 1992.
6343
6344 [DSS] National Institute of Standards and Technology, U.S.
6345 Department of Commerce, "Digital Signature Standard
6346 (DSS)", NIST FIPS PUB 186-4, DOI 10.6028/NIST.FIPS.186-4,
6347 July 2013.
6348
6349 [FG17] Fischlin, M. and F. Guenther, "Replay Attacks on Zero
6350 Round-Trip Time: The Case of the TLS 1.3 Handshake
6351 Candidates", Proceedings of EuroS&P 2017, April 2017,
6352 <https://eprint.iacr.org/2017/082>.
6353
6354 [FGSW16] Fischlin, M., Guenther, F., Schmidt, B., and B. Warinschi,
6355 "Key Confirmation in Key Exchange: A Formal Treatment and
6356 Implications for TLS 1.3", Proceedings of IEEE Symposium
6357 on Security and Privacy (San Jose),
6358 DOI 10.1109/SP.2016.34, May 2016,
6359 <https://ieeexplore.ieee.org/document/7546517/>.
6360
6361 [FW15] Weimer, F., "Factoring RSA Keys With TLS Perfect Forward
6362 Secrecy", September 2015.
6363
6364 [HCJC16] Husak, M., Cermak, M., Jirsik, T., and P. Celeda, "HTTPS
6365 traffic analysis and client identification using passive
6366 SSL/TLS fingerprinting", EURASIP Journal on Information
6367 Security, Vol. 2016, DOI 10.1186/s13635-016-0030-7,
6368 February 2016.
6369
6370 [HGFS15] Hlauschek, C., Gruber, M., Fankhauser, F., and C. Schanes,
6371 "Prying Open Pandora's Box: KCI Attacks against TLS",
6372 Proceedings of USENIX Workshop on Offensive Technologies,
6373 August 2015.
6374
6375 [IEEE1363]
6376 IEEE, "IEEE Standard Specifications for Public Key
6377 Cryptography", IEEE Std. 1363-2000,
6378 DOI 10.1109/IEEESTD.2000.92292.
6379
6380
6381
6382
6383
6384
6385
6386Rescorla Standards Track [Page 114]
6387
6388RFC 8446 TLS August 2018
6389
6390
6391 [JSS15] Jager, T., Schwenk, J., and J. Somorovsky, "On the
6392 Security of TLS 1.3 and QUIC Against Weaknesses in PKCS#1
6393 v1.5 Encryption", Proceedings of ACM CCS 2015,
6394 DOI 10.1145/2810103.2813657, October 2015,
6395 <https://www.nds.rub.de/media/nds/
6396 veroeffentlichungen/2015/08/21/Tls13QuicAttacks.pdf>.
6397
6398 [KEYAGREEMENT]
6399 Barker, E., Chen, L., Roginsky, A., Vassilev, A., and R.
6400 Davis, "Recommendation for Pair-Wise Key Establishment
6401 Schemes Using Discrete Logarithm Cryptography", National
6402 Institute of Standards and Technology,
6403 DOI 10.6028/NIST.SP.800-56Ar3, April 2018.
6404
6405 [Kraw10] Krawczyk, H., "Cryptographic Extraction and Key
6406 Derivation: The HKDF Scheme", Proceedings of CRYPTO 2010,
6407 August 2010, <https://eprint.iacr.org/2010/264>.
6408
6409 [Kraw16] Krawczyk, H., "A Unilateral-to-Mutual Authentication
6410 Compiler for Key Exchange (with Applications to Client
6411 Authentication in TLS 1.3", Proceedings of ACM CCS 2016,
6412 October 2016, <https://eprint.iacr.org/2016/711>.
6413
6414 [KW16] Krawczyk, H. and H. Wee, "The OPTLS Protocol and TLS 1.3",
6415 Proceedings of EuroS&P 2016, March 2016,
6416 <https://eprint.iacr.org/2015/978>.
6417
6418 [LXZFH16] Li, X., Xu, J., Zhang, Z., Feng, D., and H. Hu, "Multiple
6419 Handshakes Security of TLS 1.3 Candidates", Proceedings of
6420 IEEE Symposium on Security and Privacy (San Jose),
6421 DOI 10.1109/SP.2016.36, May 2016,
6422 <https://ieeexplore.ieee.org/document/7546519/>.
6423
6424 [Mac17] MacCarthaigh, C., "Security Review of TLS1.3 0-RTT",
6425 March 2017, <https://github.com/tlswg/tls13-spec/
6426 issues/1001>.
6427
6428 [PS18] Patton, C. and T. Shrimpton, "Partially specified
6429 channels: The TLS 1.3 record layer without elision", 2018,
6430 <https://eprint.iacr.org/2018/634>.
6431
6432 [PSK-FINISHED]
6433 Scott, S., Cremers, C., Horvat, M., and T. van der Merwe,
6434 "Revision 10: possible attack if client authentication is
6435 allowed during PSK", message to the TLS mailing list,
6436 31 October 2015, <https://www.ietf.org/
6437 mail-archive/web/tls/current/msg18215.html>.
6438
6439
6440
6441
6442Rescorla Standards Track [Page 115]
6443
6444RFC 8446 TLS August 2018
6445
6446
6447 [REKEY] Abdalla, M. and M. Bellare, "Increasing the Lifetime of a
6448 Key: A Comparative Analysis of the Security of Re-keying
6449 Techniques", ASIACRYPT 2000, DOI 10.1007/3-540-44448-3_42,
6450 October 2000.
6451
6452 [Res17a] Rescorla, E., "Preliminary data on Firefox TLS 1.3
6453 Middlebox experiment", message to the TLS mailing list,
6454 5 December 2017, <https://www.ietf.org/
6455 mail-archive/web/tls/current/msg25091.html>.
6456
6457 [Res17b] Rescorla, E., "More compatibility measurement results",
6458 message to the TLS mailing list, 22 December 2017,
6459 <https://www.ietf.org/mail-archive/web/tls/current/
6460 msg25179.html>.
6461
6462 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
6463 Text on Security Considerations", BCP 72, RFC 3552,
6464 DOI 10.17487/RFC3552, July 2003,
6465 <https://www.rfc-editor.org/info/rfc3552>.
6466
6467 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker,
6468 "Randomness Requirements for Security", BCP 106, RFC 4086,
6469 DOI 10.17487/RFC4086, June 2005,
6470 <https://www.rfc-editor.org/info/rfc4086>.
6471
6472 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security
6473 (TLS) Protocol Version 1.1", RFC 4346,
6474 DOI 10.17487/RFC4346, April 2006,
6475 <https://www.rfc-editor.org/info/rfc4346>.
6476
6477 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J.,
6478 and T. Wright, "Transport Layer Security (TLS)
6479 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006,
6480 <https://www.rfc-editor.org/info/rfc4366>.
6481
6482 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B.
6483 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites
6484 for Transport Layer Security (TLS)", RFC 4492,
6485 DOI 10.17487/RFC4492, May 2006,
6486 <https://www.rfc-editor.org/info/rfc4492>.
6487
6488 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig,
6489 "Transport Layer Security (TLS) Session Resumption without
6490 Server-Side State", RFC 5077, DOI 10.17487/RFC5077,
6491 January 2008, <https://www.rfc-editor.org/info/rfc5077>.
6492
6493
6494
6495
6496
6497
6498Rescorla Standards Track [Page 116]
6499
6500RFC 8446 TLS August 2018
6501
6502
6503 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
6504 (TLS) Protocol Version 1.2", RFC 5246,
6505 DOI 10.17487/RFC5246, August 2008,
6506 <https://www.rfc-editor.org/info/rfc5246>.
6507
6508 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer
6509 Security (DTLS) Extension to Establish Keys for the Secure
6510 Real-time Transport Protocol (SRTP)", RFC 5764,
6511 DOI 10.17487/RFC5764, May 2010,
6512 <https://www.rfc-editor.org/info/rfc5764>.
6513
6514 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings
6515 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010,
6516 <https://www.rfc-editor.org/info/rfc5929>.
6517
6518 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys
6519 for Transport Layer Security (TLS) Authentication",
6520 RFC 6091, DOI 10.17487/RFC6091, February 2011,
6521 <https://www.rfc-editor.org/info/rfc6091>.
6522
6523 [RFC6101] Freier, A., Karlton, P., and P. Kocher, "The Secure
6524 Sockets Layer (SSL) Protocol Version 3.0", RFC 6101,
6525 DOI 10.17487/RFC6101, August 2011,
6526 <https://www.rfc-editor.org/info/rfc6101>.
6527
6528 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer
6529 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176,
6530 March 2011, <https://www.rfc-editor.org/info/rfc6176>.
6531
6532 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
6533 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
6534 January 2012, <https://www.rfc-editor.org/info/rfc6347>.
6535
6536 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport
6537 Layer Security (TLS) and Datagram Transport Layer Security
6538 (DTLS) Heartbeat Extension", RFC 6520,
6539 DOI 10.17487/RFC6520, February 2012,
6540 <https://www.rfc-editor.org/info/rfc6520>.
6541
6542 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
6543 Protocol (HTTP/1.1): Message Syntax and Routing",
6544 RFC 7230, DOI 10.17487/RFC7230, June 2014,
6545 <https://www.rfc-editor.org/info/rfc7230>.
6546
6547
6548
6549
6550
6551
6552
6553
6554Rescorla Standards Track [Page 117]
6555
6556RFC 8446 TLS August 2018
6557
6558
6559 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J.,
6560 Weiler, S., and T. Kivinen, "Using Raw Public Keys in
6561 Transport Layer Security (TLS) and Datagram Transport
6562 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250,
6563 June 2014, <https://www.rfc-editor.org/info/rfc7250>.
6564
6565 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465,
6566 DOI 10.17487/RFC7465, February 2015,
6567 <https://www.rfc-editor.org/info/rfc7465>.
6568
6569 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley,
6570 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568,
6571 DOI 10.17487/RFC7568, June 2015,
6572 <https://www.rfc-editor.org/info/rfc7568>.
6573
6574 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A.,
6575 Langley, A., and M. Ray, "Transport Layer Security (TLS)
6576 Session Hash and Extended Master Secret Extension",
6577 RFC 7627, DOI 10.17487/RFC7627, September 2015,
6578 <https://www.rfc-editor.org/info/rfc7627>.
6579
6580 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello
6581 Padding Extension", RFC 7685, DOI 10.17487/RFC7685,
6582 October 2015, <https://www.rfc-editor.org/info/rfc7685>.
6583
6584 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security
6585 (TLS) Cached Information Extension", RFC 7924,
6586 DOI 10.17487/RFC7924, July 2016,
6587 <https://www.rfc-editor.org/info/rfc7924>.
6588
6589 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2:
6590 Better Connectivity Using Concurrency", RFC 8305,
6591 DOI 10.17487/RFC8305, December 2017,
6592 <https://www.rfc-editor.org/info/rfc8305>.
6593
6594 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic
6595 Curve Cryptography (ECC) Cipher Suites for Transport Layer
6596 Security (TLS) Versions 1.2 and Earlier", RFC 8422,
6597 DOI 10.17487/RFC8422, August 2018,
6598 <https://www.rfc-editor.org/info/rfc8422>.
6599
6600 [RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS
6601 and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018,
6602 <https://www.rfc-editor.org/info/rfc8447>.
6603
6604 [RFC8449] Thomson, M., "Record Size Limit Extension for TLS",
6605 RFC 8449, DOI 10.17487/RFC8449, August 2018,
6606 <https://www.rfc-editor.org/info/rfc8449>.
6607
6608
6609
6610Rescorla Standards Track [Page 118]
6611
6612RFC 8446 TLS August 2018
6613
6614
6615 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for
6616 Obtaining Digital Signatures and Public-Key
6617 Cryptosystems", Communications of the ACM, Vol. 21 No. 2,
6618 pp. 120-126, DOI 10.1145/359340.359342, February 1978.
6619
6620 [SIGMA] Krawczyk, H., "SIGMA: The 'SIGn-and-MAc' Approach to
6621 Authenticated Diffie-Hellman and its Use in the IKE
6622 Protocols", Proceedings of CRYPTO 2003,
6623 DOI 10.1007/978-3-540-45146-4_24, August 2003.
6624
6625 [SLOTH] Bhargavan, K. and G. Leurent, "Transcript Collision
6626 Attacks: Breaking Authentication in TLS, IKE, and SSH",
6627 Network and Distributed System Security
6628 Symposium (NDSS 2016), DOI 10.14722/ndss.2016.23418,
6629 February 2016.
6630
6631 [SSL2] Hickman, K., "The SSL Protocol", February 1995.
6632
6633 [TIMING] Boneh, D. and D. Brumley, "Remote Timing Attacks Are
6634 Practical", USENIX Security Symposium, August 2003.
6635
6636 [TLS13-TRACES]
6637 Thomson, M., "Example Handshake Traces for TLS 1.3", Work
6638 in Progress, draft-ietf-tls-tls13-vectors-06, July 2018.
6639
6640 [X501] ITU-T, "Information Technology - Open Systems
6641 Interconnection - The Directory: Models", ITU-T X.501,
6642 October 2016, <https://www.itu.int/rec/T-REC-X.501/en>.
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666Rescorla Standards Track [Page 119]
6667
6668RFC 8446 TLS August 2018
6669
6670
6671Appendix A. State Machine
6672
6673 This appendix provides a summary of the legal state transitions for
6674 the client and server handshakes. State names (in all capitals,
6675 e.g., START) have no formal meaning but are provided for ease of
6676 comprehension. Actions which are taken only in certain circumstances
6677 are indicated in []. The notation "K_{send,recv} = foo" means "set
6678 the send/recv key to the given key".
6679
6680A.1. Client
6681
6682 START <----+
6683 Send ClientHello | | Recv HelloRetryRequest
6684 [K_send = early data] | |
6685 v |
6686 / WAIT_SH ----+
6687 | | Recv ServerHello
6688 | | K_recv = handshake
6689 Can | V
6690 send | WAIT_EE
6691 early | | Recv EncryptedExtensions
6692 data | +--------+--------+
6693 | Using | | Using certificate
6694 | PSK | v
6695 | | WAIT_CERT_CR
6696 | | Recv | | Recv CertificateRequest
6697 | | Certificate | v
6698 | | | WAIT_CERT
6699 | | | | Recv Certificate
6700 | | v v
6701 | | WAIT_CV
6702 | | | Recv CertificateVerify
6703 | +> WAIT_FINISHED <+
6704 | | Recv Finished
6705 \ | [Send EndOfEarlyData]
6706 | K_send = handshake
6707 | [Send Certificate [+ CertificateVerify]]
6708 Can send | Send Finished
6709 app data --> | K_send = K_recv = application
6710 after here v
6711 CONNECTED
6712
6713 Note that with the transitions as shown above, clients may send
6714 alerts that derive from post-ServerHello messages in the clear or
6715 with the early data keys. If clients need to send such alerts, they
6716 SHOULD first rekey to the handshake keys if possible.
6717
6718
6719
6720
6721
6722Rescorla Standards Track [Page 120]
6723
6724RFC 8446 TLS August 2018
6725
6726
6727A.2. Server
6728
6729 START <-----+
6730 Recv ClientHello | | Send HelloRetryRequest
6731 v |
6732 RECVD_CH ----+
6733 | Select parameters
6734 v
6735 NEGOTIATED
6736 | Send ServerHello
6737 | K_send = handshake
6738 | Send EncryptedExtensions
6739 | [Send CertificateRequest]
6740 Can send | [Send Certificate + CertificateVerify]
6741 app data | Send Finished
6742 after --> | K_send = application
6743 here +--------+--------+
6744 No 0-RTT | | 0-RTT
6745 | |
6746 K_recv = handshake | | K_recv = early data
6747 [Skip decrypt errors] | +------> WAIT_EOED -+
6748 | | Recv | | Recv EndOfEarlyData
6749 | | early data | | K_recv = handshake
6750 | +------------+ |
6751 | |
6752 +> WAIT_FLIGHT2 <--------+
6753 |
6754 +--------+--------+
6755 No auth | | Client auth
6756 | |
6757 | v
6758 | WAIT_CERT
6759 | Recv | | Recv Certificate
6760 | empty | v
6761 | Certificate | WAIT_CV
6762 | | | Recv
6763 | v | CertificateVerify
6764 +-> WAIT_FINISHED <---+
6765 | Recv Finished
6766 | K_recv = application
6767 v
6768 CONNECTED
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778Rescorla Standards Track [Page 121]
6779
6780RFC 8446 TLS August 2018
6781
6782
6783Appendix B. Protocol Data Structures and Constant Values
6784
6785 This appendix provides the normative protocol types and the
6786 definitions for constants. Values listed as "_RESERVED" were used in
6787 previous versions of TLS and are listed here for completeness.
6788 TLS 1.3 implementations MUST NOT send them but might receive them
6789 from older TLS implementations.
6790
6791B.1. Record Layer
6792
6793 enum {
6794 invalid(0),
6795 change_cipher_spec(20),
6796 alert(21),
6797 handshake(22),
6798 application_data(23),
6799 heartbeat(24), /* RFC 6520 */
6800 (255)
6801 } ContentType;
6802
6803 struct {
6804 ContentType type;
6805 ProtocolVersion legacy_record_version;
6806 uint16 length;
6807 opaque fragment[TLSPlaintext.length];
6808 } TLSPlaintext;
6809
6810 struct {
6811 opaque content[TLSPlaintext.length];
6812 ContentType type;
6813 uint8 zeros[length_of_padding];
6814 } TLSInnerPlaintext;
6815
6816 struct {
6817 ContentType opaque_type = application_data; /* 23 */
6818 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */
6819 uint16 length;
6820 opaque encrypted_record[TLSCiphertext.length];
6821 } TLSCiphertext;
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834Rescorla Standards Track [Page 122]
6835
6836RFC 8446 TLS August 2018
6837
6838
6839B.2. Alert Messages
6840
6841 enum { warning(1), fatal(2), (255) } AlertLevel;
6842
6843 enum {
6844 close_notify(0),
6845 unexpected_message(10),
6846 bad_record_mac(20),
6847 decryption_failed_RESERVED(21),
6848 record_overflow(22),
6849 decompression_failure_RESERVED(30),
6850 handshake_failure(40),
6851 no_certificate_RESERVED(41),
6852 bad_certificate(42),
6853 unsupported_certificate(43),
6854 certificate_revoked(44),
6855 certificate_expired(45),
6856 certificate_unknown(46),
6857 illegal_parameter(47),
6858 unknown_ca(48),
6859 access_denied(49),
6860 decode_error(50),
6861 decrypt_error(51),
6862 export_restriction_RESERVED(60),
6863 protocol_version(70),
6864 insufficient_security(71),
6865 internal_error(80),
6866 inappropriate_fallback(86),
6867 user_canceled(90),
6868 no_renegotiation_RESERVED(100),
6869 missing_extension(109),
6870 unsupported_extension(110),
6871 certificate_unobtainable_RESERVED(111),
6872 unrecognized_name(112),
6873 bad_certificate_status_response(113),
6874 bad_certificate_hash_value_RESERVED(114),
6875 unknown_psk_identity(115),
6876 certificate_required(116),
6877 no_application_protocol(120),
6878 (255)
6879 } AlertDescription;
6880
6881 struct {
6882 AlertLevel level;
6883 AlertDescription description;
6884 } Alert;
6885
6886
6887
6888
6889
6890Rescorla Standards Track [Page 123]
6891
6892RFC 8446 TLS August 2018
6893
6894
6895B.3. Handshake Protocol
6896
6897 enum {
6898 hello_request_RESERVED(0),
6899 client_hello(1),
6900 server_hello(2),
6901 hello_verify_request_RESERVED(3),
6902 new_session_ticket(4),
6903 end_of_early_data(5),
6904 hello_retry_request_RESERVED(6),
6905 encrypted_extensions(8),
6906 certificate(11),
6907 server_key_exchange_RESERVED(12),
6908 certificate_request(13),
6909 server_hello_done_RESERVED(14),
6910 certificate_verify(15),
6911 client_key_exchange_RESERVED(16),
6912 finished(20),
6913 certificate_url_RESERVED(21),
6914 certificate_status_RESERVED(22),
6915 supplemental_data_RESERVED(23),
6916 key_update(24),
6917 message_hash(254),
6918 (255)
6919 } HandshakeType;
6920
6921 struct {
6922 HandshakeType msg_type; /* handshake type */
6923 uint24 length; /* bytes in message */
6924 select (Handshake.msg_type) {
6925 case client_hello: ClientHello;
6926 case server_hello: ServerHello;
6927 case end_of_early_data: EndOfEarlyData;
6928 case encrypted_extensions: EncryptedExtensions;
6929 case certificate_request: CertificateRequest;
6930 case certificate: Certificate;
6931 case certificate_verify: CertificateVerify;
6932 case finished: Finished;
6933 case new_session_ticket: NewSessionTicket;
6934 case key_update: KeyUpdate;
6935 };
6936 } Handshake;
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946Rescorla Standards Track [Page 124]
6947
6948RFC 8446 TLS August 2018
6949
6950
6951B.3.1. Key Exchange Messages
6952
6953 uint16 ProtocolVersion;
6954 opaque Random[32];
6955
6956 uint8 CipherSuite[2]; /* Cryptographic suite selector */
6957
6958 struct {
6959 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */
6960 Random random;
6961 opaque legacy_session_id<0..32>;
6962 CipherSuite cipher_suites<2..2^16-2>;
6963 opaque legacy_compression_methods<1..2^8-1>;
6964 Extension extensions<8..2^16-1>;
6965 } ClientHello;
6966
6967 struct {
6968 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */
6969 Random random;
6970 opaque legacy_session_id_echo<0..32>;
6971 CipherSuite cipher_suite;
6972 uint8 legacy_compression_method = 0;
6973 Extension extensions<6..2^16-1>;
6974 } ServerHello;
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002Rescorla Standards Track [Page 125]
7003
7004RFC 8446 TLS August 2018
7005
7006
7007 struct {
7008 ExtensionType extension_type;
7009 opaque extension_data<0..2^16-1>;
7010 } Extension;
7011
7012 enum {
7013 server_name(0), /* RFC 6066 */
7014 max_fragment_length(1), /* RFC 6066 */
7015 status_request(5), /* RFC 6066 */
7016 supported_groups(10), /* RFC 8422, 7919 */
7017 signature_algorithms(13), /* RFC 8446 */
7018 use_srtp(14), /* RFC 5764 */
7019 heartbeat(15), /* RFC 6520 */
7020 application_layer_protocol_negotiation(16), /* RFC 7301 */
7021 signed_certificate_timestamp(18), /* RFC 6962 */
7022 client_certificate_type(19), /* RFC 7250 */
7023 server_certificate_type(20), /* RFC 7250 */
7024 padding(21), /* RFC 7685 */
7025 RESERVED(40), /* Used but never
7026 assigned */
7027 pre_shared_key(41), /* RFC 8446 */
7028 early_data(42), /* RFC 8446 */
7029 supported_versions(43), /* RFC 8446 */
7030 cookie(44), /* RFC 8446 */
7031 psk_key_exchange_modes(45), /* RFC 8446 */
7032 RESERVED(46), /* Used but never
7033 assigned */
7034 certificate_authorities(47), /* RFC 8446 */
7035 oid_filters(48), /* RFC 8446 */
7036 post_handshake_auth(49), /* RFC 8446 */
7037 signature_algorithms_cert(50), /* RFC 8446 */
7038 key_share(51), /* RFC 8446 */
7039 (65535)
7040 } ExtensionType;
7041
7042 struct {
7043 NamedGroup group;
7044 opaque key_exchange<1..2^16-1>;
7045 } KeyShareEntry;
7046
7047 struct {
7048 KeyShareEntry client_shares<0..2^16-1>;
7049 } KeyShareClientHello;
7050
7051 struct {
7052 NamedGroup selected_group;
7053 } KeyShareHelloRetryRequest;
7054
7055
7056
7057
7058Rescorla Standards Track [Page 126]
7059
7060RFC 8446 TLS August 2018
7061
7062
7063 struct {
7064 KeyShareEntry server_share;
7065 } KeyShareServerHello;
7066
7067 struct {
7068 uint8 legacy_form = 4;
7069 opaque X[coordinate_length];
7070 opaque Y[coordinate_length];
7071 } UncompressedPointRepresentation;
7072
7073 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode;
7074
7075 struct {
7076 PskKeyExchangeMode ke_modes<1..255>;
7077 } PskKeyExchangeModes;
7078
7079 struct {} Empty;
7080
7081 struct {
7082 select (Handshake.msg_type) {
7083 case new_session_ticket: uint32 max_early_data_size;
7084 case client_hello: Empty;
7085 case encrypted_extensions: Empty;
7086 };
7087 } EarlyDataIndication;
7088
7089 struct {
7090 opaque identity<1..2^16-1>;
7091 uint32 obfuscated_ticket_age;
7092 } PskIdentity;
7093
7094 opaque PskBinderEntry<32..255>;
7095
7096 struct {
7097 PskIdentity identities<7..2^16-1>;
7098 PskBinderEntry binders<33..2^16-1>;
7099 } OfferedPsks;
7100
7101 struct {
7102 select (Handshake.msg_type) {
7103 case client_hello: OfferedPsks;
7104 case server_hello: uint16 selected_identity;
7105 };
7106 } PreSharedKeyExtension;
7107
7108
7109
7110
7111
7112
7113
7114Rescorla Standards Track [Page 127]
7115
7116RFC 8446 TLS August 2018
7117
7118
7119B.3.1.1. Version Extension
7120
7121 struct {
7122 select (Handshake.msg_type) {
7123 case client_hello:
7124 ProtocolVersion versions<2..254>;
7125
7126 case server_hello: /* and HelloRetryRequest */
7127 ProtocolVersion selected_version;
7128 };
7129 } SupportedVersions;
7130
7131B.3.1.2. Cookie Extension
7132
7133 struct {
7134 opaque cookie<1..2^16-1>;
7135 } Cookie;
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170Rescorla Standards Track [Page 128]
7171
7172RFC 8446 TLS August 2018
7173
7174
7175B.3.1.3. Signature Algorithm Extension
7176
7177 enum {
7178 /* RSASSA-PKCS1-v1_5 algorithms */
7179 rsa_pkcs1_sha256(0x0401),
7180 rsa_pkcs1_sha384(0x0501),
7181 rsa_pkcs1_sha512(0x0601),
7182
7183 /* ECDSA algorithms */
7184 ecdsa_secp256r1_sha256(0x0403),
7185 ecdsa_secp384r1_sha384(0x0503),
7186 ecdsa_secp521r1_sha512(0x0603),
7187
7188 /* RSASSA-PSS algorithms with public key OID rsaEncryption */
7189 rsa_pss_rsae_sha256(0x0804),
7190 rsa_pss_rsae_sha384(0x0805),
7191 rsa_pss_rsae_sha512(0x0806),
7192
7193 /* EdDSA algorithms */
7194 ed25519(0x0807),
7195 ed448(0x0808),
7196
7197 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */
7198 rsa_pss_pss_sha256(0x0809),
7199 rsa_pss_pss_sha384(0x080a),
7200 rsa_pss_pss_sha512(0x080b),
7201
7202 /* Legacy algorithms */
7203 rsa_pkcs1_sha1(0x0201),
7204 ecdsa_sha1(0x0203),
7205
7206 /* Reserved Code Points */
7207 obsolete_RESERVED(0x0000..0x0200),
7208 dsa_sha1_RESERVED(0x0202),
7209 obsolete_RESERVED(0x0204..0x0400),
7210 dsa_sha256_RESERVED(0x0402),
7211 obsolete_RESERVED(0x0404..0x0500),
7212 dsa_sha384_RESERVED(0x0502),
7213 obsolete_RESERVED(0x0504..0x0600),
7214 dsa_sha512_RESERVED(0x0602),
7215 obsolete_RESERVED(0x0604..0x06FF),
7216 private_use(0xFE00..0xFFFF),
7217 (0xFFFF)
7218 } SignatureScheme;
7219
7220 struct {
7221 SignatureScheme supported_signature_algorithms<2..2^16-2>;
7222 } SignatureSchemeList;
7223
7224
7225
7226Rescorla Standards Track [Page 129]
7227
7228RFC 8446 TLS August 2018
7229
7230
7231B.3.1.4. Supported Groups Extension
7232
7233 enum {
7234 unallocated_RESERVED(0x0000),
7235
7236 /* Elliptic Curve Groups (ECDHE) */
7237 obsolete_RESERVED(0x0001..0x0016),
7238 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019),
7239 obsolete_RESERVED(0x001A..0x001C),
7240 x25519(0x001D), x448(0x001E),
7241
7242 /* Finite Field Groups (DHE) */
7243 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102),
7244 ffdhe6144(0x0103), ffdhe8192(0x0104),
7245
7246 /* Reserved Code Points */
7247 ffdhe_private_use(0x01FC..0x01FF),
7248 ecdhe_private_use(0xFE00..0xFEFF),
7249 obsolete_RESERVED(0xFF01..0xFF02),
7250 (0xFFFF)
7251 } NamedGroup;
7252
7253 struct {
7254 NamedGroup named_group_list<2..2^16-1>;
7255 } NamedGroupList;
7256
7257 Values within "obsolete_RESERVED" ranges are used in previous
7258 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3
7259 implementations. The obsolete curves have various known/theoretical
7260 weaknesses or have had very little usage, in some cases only due to
7261 unintentional server configuration issues. They are no longer
7262 considered appropriate for general use and should be assumed to be
7263 potentially unsafe. The set of curves specified here is sufficient
7264 for interoperability with all currently deployed and properly
7265 configured TLS implementations.
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282Rescorla Standards Track [Page 130]
7283
7284RFC 8446 TLS August 2018
7285
7286
7287B.3.2. Server Parameters Messages
7288
7289 opaque DistinguishedName<1..2^16-1>;
7290
7291 struct {
7292 DistinguishedName authorities<3..2^16-1>;
7293 } CertificateAuthoritiesExtension;
7294
7295 struct {
7296 opaque certificate_extension_oid<1..2^8-1>;
7297 opaque certificate_extension_values<0..2^16-1>;
7298 } OIDFilter;
7299
7300 struct {
7301 OIDFilter filters<0..2^16-1>;
7302 } OIDFilterExtension;
7303
7304 struct {} PostHandshakeAuth;
7305
7306 struct {
7307 Extension extensions<0..2^16-1>;
7308 } EncryptedExtensions;
7309
7310 struct {
7311 opaque certificate_request_context<0..2^8-1>;
7312 Extension extensions<2..2^16-1>;
7313 } CertificateRequest;
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338Rescorla Standards Track [Page 131]
7339
7340RFC 8446 TLS August 2018
7341
7342
7343B.3.3. Authentication Messages
7344
7345 enum {
7346 X509(0),
7347 OpenPGP_RESERVED(1),
7348 RawPublicKey(2),
7349 (255)
7350 } CertificateType;
7351
7352 struct {
7353 select (certificate_type) {
7354 case RawPublicKey:
7355 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */
7356 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>;
7357
7358 case X509:
7359 opaque cert_data<1..2^24-1>;
7360 };
7361 Extension extensions<0..2^16-1>;
7362 } CertificateEntry;
7363
7364 struct {
7365 opaque certificate_request_context<0..2^8-1>;
7366 CertificateEntry certificate_list<0..2^24-1>;
7367 } Certificate;
7368
7369 struct {
7370 SignatureScheme algorithm;
7371 opaque signature<0..2^16-1>;
7372 } CertificateVerify;
7373
7374 struct {
7375 opaque verify_data[Hash.length];
7376 } Finished;
7377
7378B.3.4. Ticket Establishment
7379
7380 struct {
7381 uint32 ticket_lifetime;
7382 uint32 ticket_age_add;
7383 opaque ticket_nonce<0..255>;
7384 opaque ticket<1..2^16-1>;
7385 Extension extensions<0..2^16-2>;
7386 } NewSessionTicket;
7387
7388
7389
7390
7391
7392
7393
7394Rescorla Standards Track [Page 132]
7395
7396RFC 8446 TLS August 2018
7397
7398
7399B.3.5. Updating Keys
7400
7401 struct {} EndOfEarlyData;
7402
7403 enum {
7404 update_not_requested(0), update_requested(1), (255)
7405 } KeyUpdateRequest;
7406
7407 struct {
7408 KeyUpdateRequest request_update;
7409 } KeyUpdate;
7410
7411B.4. Cipher Suites
7412
7413 A symmetric cipher suite defines the pair of the AEAD algorithm and
7414 hash algorithm to be used with HKDF. Cipher suite names follow the
7415 naming convention:
7416
7417 CipherSuite TLS_AEAD_HASH = VALUE;
7418
7419 +-----------+------------------------------------------------+
7420 | Component | Contents |
7421 +-----------+------------------------------------------------+
7422 | TLS | The string "TLS" |
7423 | | |
7424 | AEAD | The AEAD algorithm used for record protection |
7425 | | |
7426 | HASH | The hash algorithm used with HKDF |
7427 | | |
7428 | VALUE | The two-byte ID assigned for this cipher suite |
7429 +-----------+------------------------------------------------+
7430
7431 This specification defines the following cipher suites for use with
7432 TLS 1.3.
7433
7434 +------------------------------+-------------+
7435 | Description | Value |
7436 +------------------------------+-------------+
7437 | TLS_AES_128_GCM_SHA256 | {0x13,0x01} |
7438 | | |
7439 | TLS_AES_256_GCM_SHA384 | {0x13,0x02} |
7440 | | |
7441 | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} |
7442 | | |
7443 | TLS_AES_128_CCM_SHA256 | {0x13,0x04} |
7444 | | |
7445 | TLS_AES_128_CCM_8_SHA256 | {0x13,0x05} |
7446 +------------------------------+-------------+
7447
7448
7449
7450Rescorla Standards Track [Page 133]
7451
7452RFC 8446 TLS August 2018
7453
7454
7455 The corresponding AEAD algorithms AEAD_AES_128_GCM, AEAD_AES_256_GCM,
7456 and AEAD_AES_128_CCM are defined in [RFC5116].
7457 AEAD_CHACHA20_POLY1305 is defined in [RFC8439]. AEAD_AES_128_CCM_8
7458 is defined in [RFC6655]. The corresponding hash algorithms are
7459 defined in [SHS].
7460
7461 Although TLS 1.3 uses the same cipher suite space as previous
7462 versions of TLS, TLS 1.3 cipher suites are defined differently, only
7463 specifying the symmetric ciphers, and cannot be used for TLS 1.2.
7464 Similarly, cipher suites for TLS 1.2 and lower cannot be used with
7465 TLS 1.3.
7466
7467 New cipher suite values are assigned by IANA as described in
7468 Section 11.
7469
7470Appendix C. Implementation Notes
7471
7472 The TLS protocol cannot prevent many common security mistakes. This
7473 appendix provides several recommendations to assist implementors.
7474 [TLS13-TRACES] provides test vectors for TLS 1.3 handshakes.
7475
7476C.1. Random Number Generation and Seeding
7477
7478 TLS requires a cryptographically secure pseudorandom number generator
7479 (CSPRNG). In most cases, the operating system provides an
7480 appropriate facility such as /dev/urandom, which should be used
7481 absent other (e.g., performance) concerns. It is RECOMMENDED to use
7482 an existing CSPRNG implementation in preference to crafting a new
7483 one. Many adequate cryptographic libraries are already available
7484 under favorable license terms. Should those prove unsatisfactory,
7485 [RFC4086] provides guidance on the generation of random values.
7486
7487 TLS uses random values (1) in public protocol fields such as the
7488 public Random values in the ClientHello and ServerHello and (2) to
7489 generate keying material. With a properly functioning CSPRNG, this
7490 does not present a security problem, as it is not feasible to
7491 determine the CSPRNG state from its output. However, with a broken
7492 CSPRNG, it may be possible for an attacker to use the public output
7493 to determine the CSPRNG internal state and thereby predict the keying
7494 material, as documented in [CHECKOWAY]. Implementations can provide
7495 extra security against this form of attack by using separate CSPRNGs
7496 to generate public and private values.
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506Rescorla Standards Track [Page 134]
7507
7508RFC 8446 TLS August 2018
7509
7510
7511C.2. Certificates and Authentication
7512
7513 Implementations are responsible for verifying the integrity of
7514 certificates and should generally support certificate revocation
7515 messages. Absent a specific indication from an application profile,
7516 certificates should always be verified to ensure proper signing by a
7517 trusted certificate authority (CA). The selection and addition of
7518 trust anchors should be done very carefully. Users should be able to
7519 view information about the certificate and trust anchor.
7520 Applications SHOULD also enforce minimum and maximum key sizes. For
7521 example, certification paths containing keys or signatures weaker
7522 than 2048-bit RSA or 224-bit ECDSA are not appropriate for secure
7523 applications.
7524
7525C.3. Implementation Pitfalls
7526
7527 Implementation experience has shown that certain parts of earlier TLS
7528 specifications are not easy to understand and have been a source of
7529 interoperability and security problems. Many of these areas have
7530 been clarified in this document, but this appendix contains a short
7531 list of the most important things that require special attention from
7532 implementors.
7533
7534 TLS protocol issues:
7535
7536 - Do you correctly handle handshake messages that are fragmented to
7537 multiple TLS records (see Section 5.1)? Do you correctly handle
7538 corner cases like a ClientHello that is split into several small
7539 fragments? Do you fragment handshake messages that exceed the
7540 maximum fragment size? In particular, the Certificate and
7541 CertificateRequest handshake messages can be large enough to
7542 require fragmentation.
7543
7544 - Do you ignore the TLS record layer version number in all
7545 unencrypted TLS records (see Appendix D)?
7546
7547 - Have you ensured that all support for SSL, RC4, EXPORT ciphers,
7548 and MD5 (via the "signature_algorithms" extension) is completely
7549 removed from all possible configurations that support TLS 1.3 or
7550 later, and that attempts to use these obsolete capabilities fail
7551 correctly (see Appendix D)?
7552
7553 - Do you handle TLS extensions in ClientHellos correctly, including
7554 unknown extensions?
7555
7556
7557
7558
7559
7560
7561
7562Rescorla Standards Track [Page 135]
7563
7564RFC 8446 TLS August 2018
7565
7566
7567 - When the server has requested a client certificate but no suitable
7568 certificate is available, do you correctly send an empty
7569 Certificate message, instead of omitting the whole message (see
7570 Section 4.4.2)?
7571
7572 - When processing the plaintext fragment produced by AEAD-Decrypt
7573 and scanning from the end for the ContentType, do you avoid
7574 scanning past the start of the cleartext in the event that the
7575 peer has sent a malformed plaintext of all zeros?
7576
7577 - Do you properly ignore unrecognized cipher suites (Section 4.1.2),
7578 hello extensions (Section 4.2), named groups (Section 4.2.7), key
7579 shares (Section 4.2.8), supported versions (Section 4.2.1), and
7580 signature algorithms (Section 4.2.3) in the ClientHello?
7581
7582 - As a server, do you send a HelloRetryRequest to clients which
7583 support a compatible (EC)DHE group but do not predict it in the
7584 "key_share" extension? As a client, do you correctly handle a
7585 HelloRetryRequest from the server?
7586
7587 Cryptographic details:
7588
7589 - What countermeasures do you use to prevent timing attacks
7590 [TIMING]?
7591
7592 - When using Diffie-Hellman key exchange, do you correctly preserve
7593 leading zero bytes in the negotiated key (see Section 7.4.1)?
7594
7595 - Does your TLS client check that the Diffie-Hellman parameters sent
7596 by the server are acceptable (see Section 4.2.8.1)?
7597
7598 - Do you use a strong and, most importantly, properly seeded random
7599 number generator (see Appendix C.1) when generating Diffie-Hellman
7600 private values, the ECDSA "k" parameter, and other security-
7601 critical values? It is RECOMMENDED that implementations implement
7602 "deterministic ECDSA" as specified in [RFC6979].
7603
7604 - Do you zero-pad Diffie-Hellman public key values and shared
7605 secrets to the group size (see Section 4.2.8.1 and Section 7.4.1)?
7606
7607 - Do you verify signatures after making them, to protect against
7608 RSA-CRT key leaks [FW15]?
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618Rescorla Standards Track [Page 136]
7619
7620RFC 8446 TLS August 2018
7621
7622
7623C.4. Client Tracking Prevention
7624
7625 Clients SHOULD NOT reuse a ticket for multiple connections. Reuse of
7626 a ticket allows passive observers to correlate different connections.
7627 Servers that issue tickets SHOULD offer at least as many tickets as
7628 the number of connections that a client might use; for example, a web
7629 browser using HTTP/1.1 [RFC7230] might open six connections to a
7630 server. Servers SHOULD issue new tickets with every connection.
7631 This ensures that clients are always able to use a new ticket when
7632 creating a new connection.
7633
7634C.5. Unauthenticated Operation
7635
7636 Previous versions of TLS offered explicitly unauthenticated cipher
7637 suites based on anonymous Diffie-Hellman. These modes have been
7638 deprecated in TLS 1.3. However, it is still possible to negotiate
7639 parameters that do not provide verifiable server authentication by
7640 several methods, including:
7641
7642 - Raw public keys [RFC7250].
7643
7644 - Using a public key contained in a certificate but without
7645 validation of the certificate chain or any of its contents.
7646
7647 Either technique used alone is vulnerable to man-in-the-middle
7648 attacks and therefore unsafe for general use. However, it is also
7649 possible to bind such connections to an external authentication
7650 mechanism via out-of-band validation of the server's public key,
7651 trust on first use, or a mechanism such as channel bindings (though
7652 the channel bindings described in [RFC5929] are not defined for
7653 TLS 1.3). If no such mechanism is used, then the connection has no
7654 protection against active man-in-the-middle attack; applications
7655 MUST NOT use TLS in such a way absent explicit configuration or a
7656 specific application profile.
7657
7658
7659
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671
7672
7673
7674Rescorla Standards Track [Page 137]
7675
7676RFC 8446 TLS August 2018
7677
7678
7679Appendix D. Backward Compatibility
7680
7681 The TLS protocol provides a built-in mechanism for version
7682 negotiation between endpoints potentially supporting different
7683 versions of TLS.
7684
7685 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can
7686 also handle clients trying to use future versions of TLS as long as
7687 the ClientHello format remains compatible and there is at least one
7688 protocol version supported by both the client and the server.
7689
7690 Prior versions of TLS used the record layer version number
7691 (TLSPlaintext.legacy_record_version and
7692 TLSCiphertext.legacy_record_version) for various purposes. As of
7693 TLS 1.3, this field is deprecated. The value of
7694 TLSPlaintext.legacy_record_version MUST be ignored by all
7695 implementations. The value of TLSCiphertext.legacy_record_version is
7696 included in the additional data for deprotection but MAY otherwise be
7697 ignored or MAY be validated to match the fixed constant value.
7698 Version negotiation is performed using only the handshake versions
7699 (ClientHello.legacy_version and ServerHello.legacy_version, as well
7700 as the ClientHello, HelloRetryRequest, and ServerHello
7701 "supported_versions" extensions). In order to maximize
7702 interoperability with older endpoints, implementations that negotiate
7703 the use of TLS 1.0-1.2 SHOULD set the record layer version number to
7704 the negotiated version for the ServerHello and all records
7705 thereafter.
7706
7707 For maximum compatibility with previously non-standard behavior and
7708 misconfigured deployments, all implementations SHOULD support
7709 validation of certification paths based on the expectations in this
7710 document, even when handling prior TLS versions' handshakes (see
7711 Section 4.4.2.2).
7712
7713 TLS 1.2 and prior supported an "Extended Master Secret" [RFC7627]
7714 extension which digested large parts of the handshake transcript into
7715 the master secret. Because TLS 1.3 always hashes in the transcript
7716 up to the server Finished, implementations which support both TLS 1.3
7717 and earlier versions SHOULD indicate the use of the Extended Master
7718 Secret extension in their APIs whenever TLS 1.3 is used.
7719
7720
7721
7722
7723
7724
7725
7726
7727
7728
7729
7730Rescorla Standards Track [Page 138]
7731
7732RFC 8446 TLS August 2018
7733
7734
7735D.1. Negotiating with an Older Server
7736
7737 A TLS 1.3 client who wishes to negotiate with servers that do not
7738 support TLS 1.3 will send a normal TLS 1.3 ClientHello containing
7739 0x0303 (TLS 1.2) in ClientHello.legacy_version but with the correct
7740 version(s) in the "supported_versions" extension. If the server does
7741 not support TLS 1.3, it will respond with a ServerHello containing an
7742 older version number. If the client agrees to use this version, the
7743 negotiation will proceed as appropriate for the negotiated protocol.
7744 A client using a ticket for resumption SHOULD initiate the connection
7745 using the version that was previously negotiated.
7746
7747 Note that 0-RTT data is not compatible with older servers and
7748 SHOULD NOT be sent absent knowledge that the server supports TLS 1.3.
7749 See Appendix D.3.
7750
7751 If the version chosen by the server is not supported by the client
7752 (or is not acceptable), the client MUST abort the handshake with a
7753 "protocol_version" alert.
7754
7755 Some legacy server implementations are known to not implement the TLS
7756 specification properly and might abort connections upon encountering
7757 TLS extensions or versions which they are not aware of.
7758 Interoperability with buggy servers is a complex topic beyond the
7759 scope of this document. Multiple connection attempts may be required
7760 in order to negotiate a backward-compatible connection; however, this
7761 practice is vulnerable to downgrade attacks and is NOT RECOMMENDED.
7762
7763D.2. Negotiating with an Older Client
7764
7765 A TLS server can also receive a ClientHello indicating a version
7766 number smaller than its highest supported version. If the
7767 "supported_versions" extension is present, the server MUST negotiate
7768 using that extension as described in Section 4.2.1. If the
7769 "supported_versions" extension is not present, the server MUST
7770 negotiate the minimum of ClientHello.legacy_version and TLS 1.2. For
7771 example, if the server supports TLS 1.0, 1.1, and 1.2, and
7772 legacy_version is TLS 1.0, the server will proceed with a TLS 1.0
7773 ServerHello. If the "supported_versions" extension is absent and the
7774 server only supports versions greater than
7775 ClientHello.legacy_version, the server MUST abort the handshake with
7776 a "protocol_version" alert.
7777
7778 Note that earlier versions of TLS did not clearly specify the record
7779 layer version number value in all cases
7780 (TLSPlaintext.legacy_record_version). Servers will receive various
7781 TLS 1.x versions in this field, but its value MUST always be ignored.
7782
7783
7784
7785
7786Rescorla Standards Track [Page 139]
7787
7788RFC 8446 TLS August 2018
7789
7790
7791D.3. 0-RTT Backward Compatibility
7792
7793 0-RTT data is not compatible with older servers. An older server
7794 will respond to the ClientHello with an older ServerHello, but it
7795 will not correctly skip the 0-RTT data and will fail to complete the
7796 handshake. This can cause issues when a client attempts to use
7797 0-RTT, particularly against multi-server deployments. For example, a
7798 deployment could deploy TLS 1.3 gradually with some servers
7799 implementing TLS 1.3 and some implementing TLS 1.2, or a TLS 1.3
7800 deployment could be downgraded to TLS 1.2.
7801
7802 A client that attempts to send 0-RTT data MUST fail a connection if
7803 it receives a ServerHello with TLS 1.2 or older. It can then retry
7804 the connection with 0-RTT disabled. To avoid a downgrade attack, the
7805 client SHOULD NOT disable TLS 1.3, only 0-RTT.
7806
7807 To avoid this error condition, multi-server deployments SHOULD ensure
7808 a uniform and stable deployment of TLS 1.3 without 0-RTT prior to
7809 enabling 0-RTT.
7810
7811D.4. Middlebox Compatibility Mode
7812
7813 Field measurements [Ben17a] [Ben17b] [Res17a] [Res17b] have found
7814 that a significant number of middleboxes misbehave when a TLS
7815 client/server pair negotiates TLS 1.3. Implementations can increase
7816 the chance of making connections through those middleboxes by making
7817 the TLS 1.3 handshake look more like a TLS 1.2 handshake:
7818
7819 - The client always provides a non-empty session ID in the
7820 ClientHello, as described in the legacy_session_id section of
7821 Section 4.1.2.
7822
7823 - If not offering early data, the client sends a dummy
7824 change_cipher_spec record (see the third paragraph of Section 5)
7825 immediately before its second flight. This may either be before
7826 its second ClientHello or before its encrypted handshake flight.
7827 If offering early data, the record is placed immediately after the
7828 first ClientHello.
7829
7830 - The server sends a dummy change_cipher_spec record immediately
7831 after its first handshake message. This may either be after a
7832 ServerHello or a HelloRetryRequest.
7833
7834 When put together, these changes make the TLS 1.3 handshake resemble
7835 TLS 1.2 session resumption, which improves the chance of successfully
7836 connecting through middleboxes. This "compatibility mode" is
7837 partially negotiated: the client can opt to provide a session ID or
7838 not, and the server has to echo it. Either side can send
7839
7840
7841
7842Rescorla Standards Track [Page 140]
7843
7844RFC 8446 TLS August 2018
7845
7846
7847 change_cipher_spec at any time during the handshake, as they must be
7848 ignored by the peer, but if the client sends a non-empty session ID,
7849 the server MUST send the change_cipher_spec as described in this
7850 appendix.
7851
7852D.5. Security Restrictions Related to Backward Compatibility
7853
7854 Implementations negotiating the use of older versions of TLS SHOULD
7855 prefer forward secret and AEAD cipher suites, when available.
7856
7857 The security of RC4 cipher suites is considered insufficient for the
7858 reasons cited in [RFC7465]. Implementations MUST NOT offer or
7859 negotiate RC4 cipher suites for any version of TLS for any reason.
7860
7861 Old versions of TLS permitted the use of very low strength ciphers.
7862 Ciphers with a strength less than 112 bits MUST NOT be offered or
7863 negotiated for any version of TLS for any reason.
7864
7865 The security of SSL 3.0 [RFC6101] is considered insufficient for the
7866 reasons enumerated in [RFC7568], and it MUST NOT be negotiated for
7867 any reason.
7868
7869 The security of SSL 2.0 [SSL2] is considered insufficient for the
7870 reasons enumerated in [RFC6176], and it MUST NOT be negotiated for
7871 any reason.
7872
7873 Implementations MUST NOT send an SSL version 2.0 compatible
7874 CLIENT-HELLO. Implementations MUST NOT negotiate TLS 1.3 or later
7875 using an SSL version 2.0 compatible CLIENT-HELLO. Implementations
7876 are NOT RECOMMENDED to accept an SSL version 2.0 compatible
7877 CLIENT-HELLO in order to negotiate older versions of TLS.
7878
7879 Implementations MUST NOT send a ClientHello.legacy_version or
7880 ServerHello.legacy_version set to 0x0300 or less. Any endpoint
7881 receiving a Hello message with ClientHello.legacy_version or
7882 ServerHello.legacy_version set to 0x0300 MUST abort the handshake
7883 with a "protocol_version" alert.
7884
7885 Implementations MUST NOT send any records with a version less than
7886 0x0300. Implementations SHOULD NOT accept any records with a version
7887 less than 0x0300 (but may inadvertently do so if the record version
7888 number is ignored completely).
7889
7890 Implementations MUST NOT use the Truncated HMAC extension, defined in
7891 Section 7 of [RFC6066], as it is not applicable to AEAD algorithms
7892 and has been shown to be insecure in some scenarios.
7893
7894
7895
7896
7897
7898Rescorla Standards Track [Page 141]
7899
7900RFC 8446 TLS August 2018
7901
7902
7903Appendix E. Overview of Security Properties
7904
7905 A complete security analysis of TLS is outside the scope of this
7906 document. In this appendix, we provide an informal description of
7907 the desired properties as well as references to more detailed work in
7908 the research literature which provides more formal definitions.
7909
7910 We cover properties of the handshake separately from those of the
7911 record layer.
7912
7913E.1. Handshake
7914
7915 The TLS handshake is an Authenticated Key Exchange (AKE) protocol
7916 which is intended to provide both one-way authenticated (server-only)
7917 and mutually authenticated (client and server) functionality. At the
7918 completion of the handshake, each side outputs its view of the
7919 following values:
7920
7921 - A set of "session keys" (the various secrets derived from the
7922 master secret) from which can be derived a set of working keys.
7923
7924 - A set of cryptographic parameters (algorithms, etc.).
7925
7926 - The identities of the communicating parties.
7927
7928 We assume the attacker to be an active network attacker, which means
7929 it has complete control over the network used to communicate between
7930 the parties [RFC3552]. Even under these conditions, the handshake
7931 should provide the properties listed below. Note that these
7932 properties are not necessarily independent, but reflect the protocol
7933 consumers' needs.
7934
7935 Establishing the same session keys: The handshake needs to output
7936 the same set of session keys on both sides of the handshake,
7937 provided that it completes successfully on each endpoint (see
7938 [CK01], Definition 1, part 1).
7939
7940 Secrecy of the session keys: The shared session keys should be known
7941 only to the communicating parties and not to the attacker (see
7942 [CK01], Definition 1, part 2). Note that in a unilaterally
7943 authenticated connection, the attacker can establish its own
7944 session keys with the server, but those session keys are distinct
7945 from those established by the client.
7946
7947 Peer authentication: The client's view of the peer identity should
7948 reflect the server's identity. If the client is authenticated,
7949 the server's view of the peer identity should match the client's
7950 identity.
7951
7952
7953
7954Rescorla Standards Track [Page 142]
7955
7956RFC 8446 TLS August 2018
7957
7958
7959 Uniqueness of the session keys: Any two distinct handshakes should
7960 produce distinct, unrelated session keys. Individual session keys
7961 produced by a handshake should also be distinct and independent.
7962
7963 Downgrade protection: The cryptographic parameters should be the
7964 same on both sides and should be the same as if the peers had been
7965 communicating in the absence of an attack (see [BBFGKZ16],
7966 Definitions 8 and 9).
7967
7968 Forward secret with respect to long-term keys: If the long-term
7969 keying material (in this case the signature keys in certificate-
7970 based authentication modes or the external/resumption PSK in PSK
7971 with (EC)DHE modes) is compromised after the handshake is
7972 complete, this does not compromise the security of the session key
7973 (see [DOW92]), as long as the session key itself has been erased.
7974 The forward secrecy property is not satisfied when PSK is used in
7975 the "psk_ke" PskKeyExchangeMode.
7976
7977 Key Compromise Impersonation (KCI) resistance: In a mutually
7978 authenticated connection with certificates, compromising the
7979 long-term secret of one actor should not break that actor's
7980 authentication of their peer in the given connection (see
7981 [HGFS15]). For example, if a client's signature key is
7982 compromised, it should not be possible to impersonate arbitrary
7983 servers to that client in subsequent handshakes.
7984
7985 Protection of endpoint identities: The server's identity
7986 (certificate) should be protected against passive attackers. The
7987 client's identity should be protected against both passive and
7988 active attackers.
7989
7990 Informally, the signature-based modes of TLS 1.3 provide for the
7991 establishment of a unique, secret, shared key established by an
7992 (EC)DHE key exchange and authenticated by the server's signature over
7993 the handshake transcript, as well as tied to the server's identity by
7994 a MAC. If the client is authenticated by a certificate, it also
7995 signs over the handshake transcript and provides a MAC tied to both
7996 identities. [SIGMA] describes the design and analysis of this type
7997 of key exchange protocol. If fresh (EC)DHE keys are used for each
7998 connection, then the output keys are forward secret.
7999
8000 The external PSK and resumption PSK bootstrap from a long-term shared
8001 secret into a unique per-connection set of short-term session keys.
8002 This secret may have been established in a previous handshake. If
8003 PSK with (EC)DHE key establishment is used, these session keys will
8004 also be forward secret. The resumption PSK has been designed so that
8005 the resumption master secret computed by connection N and needed to
8006 form connection N+1 is separate from the traffic keys used by
8007
8008
8009
8010Rescorla Standards Track [Page 143]
8011
8012RFC 8446 TLS August 2018
8013
8014
8015 connection N, thus providing forward secrecy between the connections.
8016 In addition, if multiple tickets are established on the same
8017 connection, they are associated with different keys, so compromise of
8018 the PSK associated with one ticket does not lead to the compromise of
8019 connections established with PSKs associated with other tickets.
8020 This property is most interesting if tickets are stored in a database
8021 (and so can be deleted) rather than if they are self-encrypted.
8022
8023 The PSK binder value forms a binding between a PSK and the current
8024 handshake, as well as between the session where the PSK was
8025 established and the current session. This binding transitively
8026 includes the original handshake transcript, because that transcript
8027 is digested into the values which produce the resumption master
8028 secret. This requires that both the KDF used to produce the
8029 resumption master secret and the MAC used to compute the binder be
8030 collision resistant. See Appendix E.1.1 for more on this. Note: The
8031 binder does not cover the binder values from other PSKs, though they
8032 are included in the Finished MAC.
8033
8034 TLS does not currently permit the server to send a
8035 certificate_request message in non-certificate-based handshakes
8036 (e.g., PSK). If this restriction were to be relaxed in future, the
8037 client's signature would not cover the server's certificate directly.
8038 However, if the PSK was established through a NewSessionTicket, the
8039 client's signature would transitively cover the server's certificate
8040 through the PSK binder. [PSK-FINISHED] describes a concrete attack
8041 on constructions that do not bind to the server's certificate (see
8042 also [Kraw16]). It is unsafe to use certificate-based client
8043 authentication when the client might potentially share the same
8044 PSK/key-id pair with two different endpoints. Implementations
8045 MUST NOT combine external PSKs with certificate-based authentication
8046 of either the client or the server unless negotiated by some
8047 extension.
8048
8049 If an exporter is used, then it produces values which are unique and
8050 secret (because they are generated from a unique session key).
8051 Exporters computed with different labels and contexts are
8052 computationally independent, so it is not feasible to compute one
8053 from another or the session secret from the exported value.
8054 Note: Exporters can produce arbitrary-length values; if exporters are
8055 to be used as channel bindings, the exported value MUST be large
8056 enough to provide collision resistance. The exporters provided in
8057 TLS 1.3 are derived from the same Handshake Contexts as the early
8058 traffic keys and the application traffic keys, respectively, and thus
8059 have similar security properties. Note that they do not include the
8060 client's certificate; future applications which wish to bind to the
8061 client's certificate may need to define a new exporter that includes
8062 the full handshake transcript.
8063
8064
8065
8066Rescorla Standards Track [Page 144]
8067
8068RFC 8446 TLS August 2018
8069
8070
8071 For all handshake modes, the Finished MAC (and, where present, the
8072 signature) prevents downgrade attacks. In addition, the use of
8073 certain bytes in the random nonces as described in Section 4.1.3
8074 allows the detection of downgrade to previous TLS versions. See
8075 [BBFGKZ16] for more details on TLS 1.3 and downgrade.
8076
8077 As soon as the client and the server have exchanged enough
8078 information to establish shared keys, the remainder of the handshake
8079 is encrypted, thus providing protection against passive attackers,
8080 even if the computed shared key is not authenticated. Because the
8081 server authenticates before the client, the client can ensure that if
8082 it authenticates to the server, it only reveals its identity to an
8083 authenticated server. Note that implementations must use the
8084 provided record-padding mechanism during the handshake to avoid
8085 leaking information about the identities due to length. The client's
8086 proposed PSK identities are not encrypted, nor is the one that the
8087 server selects.
8088
8089E.1.1. Key Derivation and HKDF
8090
8091 Key derivation in TLS 1.3 uses HKDF as defined in [RFC5869] and its
8092 two components, HKDF-Extract and HKDF-Expand. The full rationale for
8093 the HKDF construction can be found in [Kraw10] and the rationale for
8094 the way it is used in TLS 1.3 in [KW16]. Throughout this document,
8095 each application of HKDF-Extract is followed by one or more
8096 invocations of HKDF-Expand. This ordering should always be followed
8097 (including in future revisions of this document); in particular, one
8098 SHOULD NOT use an output of HKDF-Extract as an input to another
8099 application of HKDF-Extract without an HKDF-Expand in between.
8100 Multiple applications of HKDF-Expand to some of the same inputs are
8101 allowed as long as these are differentiated via the key and/or the
8102 labels.
8103
8104 Note that HKDF-Expand implements a pseudorandom function (PRF) with
8105 both inputs and outputs of variable length. In some of the uses of
8106 HKDF in this document (e.g., for generating exporters and the
8107 resumption_master_secret), it is necessary that the application of
8108 HKDF-Expand be collision resistant; namely, it should be infeasible
8109 to find two different inputs to HKDF-Expand that output the same
8110 value. This requires the underlying hash function to be collision
8111 resistant and the output length from HKDF-Expand to be of size at
8112 least 256 bits (or as much as needed for the hash function to prevent
8113 finding collisions).
8114
8115
8116
8117
8118
8119
8120
8121
8122Rescorla Standards Track [Page 145]
8123
8124RFC 8446 TLS August 2018
8125
8126
8127E.1.2. Client Authentication
8128
8129 A client that has sent authentication data to a server, either during
8130 the handshake or in post-handshake authentication, cannot be sure
8131 whether the server afterwards considers the client to be
8132 authenticated or not. If the client needs to determine if the server
8133 considers the connection to be unilaterally or mutually
8134 authenticated, this has to be provisioned by the application layer.
8135 See [CHHSV17] for details. In addition, the analysis of
8136 post-handshake authentication from [Kraw16] shows that the client
8137 identified by the certificate sent in the post-handshake phase
8138 possesses the traffic key. This party is therefore the client that
8139 participated in the original handshake or one to whom the original
8140 client delegated the traffic key (assuming that the traffic key has
8141 not been compromised).
8142
8143E.1.3. 0-RTT
8144
8145 The 0-RTT mode of operation generally provides security properties
8146 similar to those of 1-RTT data, with the two exceptions that the
8147 0-RTT encryption keys do not provide full forward secrecy and that
8148 the server is not able to guarantee uniqueness of the handshake
8149 (non-replayability) without keeping potentially undue amounts of
8150 state. See Section 8 for mechanisms to limit the exposure to replay.
8151
8152E.1.4. Exporter Independence
8153
8154 The exporter_master_secret and early_exporter_master_secret are
8155 derived to be independent of the traffic keys and therefore do not
8156 represent a threat to the security of traffic encrypted with those
8157 keys. However, because these secrets can be used to compute any
8158 exporter value, they SHOULD be erased as soon as possible. If the
8159 total set of exporter labels is known, then implementations SHOULD
8160 pre-compute the inner Derive-Secret stage of the exporter computation
8161 for all those labels, then erase the [early_]exporter_master_secret,
8162 followed by each inner value as soon as it is known that it will not
8163 be needed again.
8164
8165E.1.5. Post-Compromise Security
8166
8167 TLS does not provide security for handshakes which take place after
8168 the peer's long-term secret (signature key or external PSK) is
8169 compromised. It therefore does not provide post-compromise security
8170 [CCG16], sometimes also referred to as backward or future secrecy.
8171 This is in contrast to KCI resistance, which describes the security
8172 guarantees that a party has after its own long-term secret has been
8173 compromised.
8174
8175
8176
8177
8178Rescorla Standards Track [Page 146]
8179
8180RFC 8446 TLS August 2018
8181
8182
8183E.1.6. External References
8184
8185 The reader should refer to the following references for analysis of
8186 the TLS handshake: [DFGS15], [CHSV16], [DFGS16], [KW16], [Kraw16],
8187 [FGSW16], [LXZFH16], [FG17], and [BBK17].
8188
8189E.2. Record Layer
8190
8191 The record layer depends on the handshake producing strong traffic
8192 secrets which can be used to derive bidirectional encryption keys and
8193 nonces. Assuming that is true, and the keys are used for no more
8194 data than indicated in Section 5.5, then the record layer should
8195 provide the following guarantees:
8196
8197 Confidentiality: An attacker should not be able to determine the
8198 plaintext contents of a given record.
8199
8200 Integrity: An attacker should not be able to craft a new record
8201 which is different from an existing record which will be accepted
8202 by the receiver.
8203
8204 Order protection/non-replayability: An attacker should not be able
8205 to cause the receiver to accept a record which it has already
8206 accepted or cause the receiver to accept record N+1 without having
8207 first processed record N.
8208
8209 Length concealment: Given a record with a given external length, the
8210 attacker should not be able to determine the amount of the record
8211 that is content versus padding.
8212
8213 Forward secrecy after key change: If the traffic key update
8214 mechanism described in Section 4.6.3 has been used and the
8215 previous generation key is deleted, an attacker who compromises
8216 the endpoint should not be able to decrypt traffic encrypted with
8217 the old key.
8218
8219 Informally, TLS 1.3 provides these properties by AEAD-protecting the
8220 plaintext with a strong key. AEAD encryption [RFC5116] provides
8221 confidentiality and integrity for the data. Non-replayability is
8222 provided by using a separate nonce for each record, with the nonce
8223 being derived from the record sequence number (Section 5.3), with the
8224 sequence number being maintained independently at both sides; thus,
8225 records which are delivered out of order result in AEAD deprotection
8226 failures. In order to prevent mass cryptanalysis when the same
8227 plaintext is repeatedly encrypted by different users under the same
8228 key (as is commonly the case for HTTP), the nonce is formed by mixing
8229
8230
8231
8232
8233
8234Rescorla Standards Track [Page 147]
8235
8236RFC 8446 TLS August 2018
8237
8238
8239 the sequence number with a secret per-connection initialization
8240 vector derived along with the traffic keys. See [BT16] for analysis
8241 of this construction.
8242
8243 The rekeying technique in TLS 1.3 (see Section 7.2) follows the
8244 construction of the serial generator as discussed in [REKEY], which
8245 shows that rekeying can allow keys to be used for a larger number of
8246 encryptions than without rekeying. This relies on the security of
8247 the HKDF-Expand-Label function as a pseudorandom function (PRF). In
8248 addition, as long as this function is truly one way, it is not
8249 possible to compute traffic keys from prior to a key change (forward
8250 secrecy).
8251
8252 TLS does not provide security for data which is communicated on a
8253 connection after a traffic secret of that connection is compromised.
8254 That is, TLS does not provide post-compromise security/future
8255 secrecy/backward secrecy with respect to the traffic secret. Indeed,
8256 an attacker who learns a traffic secret can compute all future
8257 traffic secrets on that connection. Systems which want such
8258 guarantees need to do a fresh handshake and establish a new
8259 connection with an (EC)DHE exchange.
8260
8261E.2.1. External References
8262
8263 The reader should refer to the following references for analysis of
8264 the TLS record layer: [BMMRT15], [BT16], [BDFKPPRSZZ16], [BBK17], and
8265 [PS18].
8266
8267E.3. Traffic Analysis
8268
8269 TLS is susceptible to a variety of traffic analysis attacks based on
8270 observing the length and timing of encrypted packets [CLINIC]
8271 [HCJC16]. This is particularly easy when there is a small set of
8272 possible messages to be distinguished, such as for a video server
8273 hosting a fixed corpus of content, but still provides usable
8274 information even in more complicated scenarios.
8275
8276 TLS does not provide any specific defenses against this form of
8277 attack but does include a padding mechanism for use by applications:
8278 The plaintext protected by the AEAD function consists of content plus
8279 variable-length padding, which allows the application to produce
8280 arbitrary-length encrypted records as well as padding-only cover
8281 traffic to conceal the difference between periods of transmission and
8282 periods of silence. Because the padding is encrypted alongside the
8283 actual content, an attacker cannot directly determine the length of
8284 the padding but may be able to measure it indirectly by the use of
8285 timing channels exposed during record processing (i.e., seeing how
8286 long it takes to process a record or trickling in records to see
8287
8288
8289
8290Rescorla Standards Track [Page 148]
8291
8292RFC 8446 TLS August 2018
8293
8294
8295 which ones elicit a response from the server). In general, it is not
8296 known how to remove all of these channels because even a
8297 constant-time padding removal function will likely feed the content
8298 into data-dependent functions. At minimum, a fully constant-time
8299 server or client would require close cooperation with the
8300 application-layer protocol implementation, including making that
8301 higher-level protocol constant time.
8302
8303 Note: Robust traffic analysis defenses will likely lead to inferior
8304 performance due to delays in transmitting packets and increased
8305 traffic volume.
8306
8307E.4. Side-Channel Attacks
8308
8309 In general, TLS does not have specific defenses against side-channel
8310 attacks (i.e., those which attack the communications via secondary
8311 channels such as timing), leaving those to the implementation of the
8312 relevant cryptographic primitives. However, certain features of TLS
8313 are designed to make it easier to write side-channel resistant code:
8314
8315 - Unlike previous versions of TLS which used a composite MAC-then-
8316 encrypt structure, TLS 1.3 only uses AEAD algorithms, allowing
8317 implementations to use self-contained constant-time
8318 implementations of those primitives.
8319
8320 - TLS uses a uniform "bad_record_mac" alert for all decryption
8321 errors, which is intended to prevent an attacker from gaining
8322 piecewise insight into portions of the message. Additional
8323 resistance is provided by terminating the connection on such
8324 errors; a new connection will have different cryptographic
8325 material, preventing attacks against the cryptographic primitives
8326 that require multiple trials.
8327
8328 Information leakage through side channels can occur at layers above
8329 TLS, in application protocols and the applications that use them.
8330 Resistance to side-channel attacks depends on applications and
8331 application protocols separately ensuring that confidential
8332 information is not inadvertently leaked.
8333
8334
8335
8336
8337
8338
8339
8340
8341
8342
8343
8344
8345
8346Rescorla Standards Track [Page 149]
8347
8348RFC 8446 TLS August 2018
8349
8350
8351E.5. Replay Attacks on 0-RTT
8352
8353 Replayable 0-RTT data presents a number of security threats to TLS-
8354 using applications, unless those applications are specifically
8355 engineered to be safe under replay (minimally, this means idempotent,
8356 but in many cases may also require other stronger conditions, such as
8357 constant-time response). Potential attacks include:
8358
8359 - Duplication of actions which cause side effects (e.g., purchasing
8360 an item or transferring money) to be duplicated, thus harming the
8361 site or the user.
8362
8363 - Attackers can store and replay 0-RTT messages in order to reorder
8364 them with respect to other messages (e.g., moving a delete to
8365 after a create).
8366
8367 - Exploiting cache timing behavior to discover the content of 0-RTT
8368 messages by replaying a 0-RTT message to a different cache node
8369 and then using a separate connection to measure request latency,
8370 to see if the two requests address the same resource.
8371
8372 If data can be replayed a large number of times, additional attacks
8373 become possible, such as making repeated measurements of the speed of
8374 cryptographic operations. In addition, they may be able to overload
8375 rate-limiting systems. For a further description of these attacks,
8376 see [Mac17].
8377
8378 Ultimately, servers have the responsibility to protect themselves
8379 against attacks employing 0-RTT data replication. The mechanisms
8380 described in Section 8 are intended to prevent replay at the TLS
8381 layer but do not provide complete protection against receiving
8382 multiple copies of client data. TLS 1.3 falls back to the 1-RTT
8383 handshake when the server does not have any information about the
8384 client, e.g., because it is in a different cluster which does not
8385 share state or because the ticket has been deleted as described in
8386 Section 8.1. If the application-layer protocol retransmits data in
8387 this setting, then it is possible for an attacker to induce message
8388 duplication by sending the ClientHello to both the original cluster
8389 (which processes the data immediately) and another cluster which will
8390 fall back to 1-RTT and process the data upon application-layer
8391 replay. The scale of this attack is limited by the client's
8392 willingness to retry transactions and therefore only allows a limited
8393 amount of duplication, with each copy appearing as a new connection
8394 at the server.
8395
8396
8397
8398
8399
8400
8401
8402Rescorla Standards Track [Page 150]
8403
8404RFC 8446 TLS August 2018
8405
8406
8407 If implemented correctly, the mechanisms described in Sections 8.1
8408 and 8.2 prevent a replayed ClientHello and its associated 0-RTT data
8409 from being accepted multiple times by any cluster with consistent
8410 state; for servers which limit the use of 0-RTT to one cluster for a
8411 single ticket, then a given ClientHello and its associated 0-RTT data
8412 will only be accepted once. However, if state is not completely
8413 consistent, then an attacker might be able to have multiple copies of
8414 the data be accepted during the replication window. Because clients
8415 do not know the exact details of server behavior, they MUST NOT send
8416 messages in early data which are not safe to have replayed and which
8417 they would not be willing to retry across multiple 1-RTT connections.
8418
8419 Application protocols MUST NOT use 0-RTT data without a profile that
8420 defines its use. That profile needs to identify which messages or
8421 interactions are safe to use with 0-RTT and how to handle the
8422 situation when the server rejects 0-RTT and falls back to 1-RTT.
8423
8424 In addition, to avoid accidental misuse, TLS implementations MUST NOT
8425 enable 0-RTT (either sending or accepting) unless specifically
8426 requested by the application and MUST NOT automatically resend 0-RTT
8427 data if it is rejected by the server unless instructed by the
8428 application. Server-side applications may wish to implement special
8429 processing for 0-RTT data for some kinds of application traffic
8430 (e.g., abort the connection, request that data be resent at the
8431 application layer, or delay processing until the handshake
8432 completes). In order to allow applications to implement this kind of
8433 processing, TLS implementations MUST provide a way for the
8434 application to determine if the handshake has completed.
8435
8436E.5.1. Replay and Exporters
8437
8438 Replays of the ClientHello produce the same early exporter, thus
8439 requiring additional care by applications which use these exporters.
8440 In particular, if these exporters are used as an authentication
8441 channel binding (e.g., by signing the output of the exporter), an
8442 attacker who compromises the PSK can transplant authenticators
8443 between connections without compromising the authentication key.
8444
8445 In addition, the early exporter SHOULD NOT be used to generate
8446 server-to-client encryption keys because that would entail the reuse
8447 of those keys. This parallels the use of the early application
8448 traffic keys only in the client-to-server direction.
8449
8450
8451
8452
8453
8454
8455
8456
8457
8458Rescorla Standards Track [Page 151]
8459
8460RFC 8446 TLS August 2018
8461
8462
8463E.6. PSK Identity Exposure
8464
8465 Because implementations respond to an invalid PSK binder by aborting
8466 the handshake, it may be possible for an attacker to verify whether a
8467 given PSK identity is valid. Specifically, if a server accepts both
8468 external-PSK handshakes and certificate-based handshakes, a valid PSK
8469 identity will result in a failed handshake, whereas an invalid
8470 identity will just be skipped and result in a successful certificate
8471 handshake. Servers which solely support PSK handshakes may be able
8472 to resist this form of attack by treating the cases where there is no
8473 valid PSK identity and where there is an identity but it has an
8474 invalid binder identically.
8475
8476E.7. Sharing PSKs
8477
8478 TLS 1.3 takes a conservative approach to PSKs by binding them to a
8479 specific KDF. By contrast, TLS 1.2 allows PSKs to be used with any
8480 hash function and the TLS 1.2 PRF. Thus, any PSK which is used with
8481 both TLS 1.2 and TLS 1.3 must be used with only one hash in TLS 1.3,
8482 which is less than optimal if users want to provision a single PSK.
8483 The constructions in TLS 1.2 and TLS 1.3 are different, although they
8484 are both based on HMAC. While there is no known way in which the
8485 same PSK might produce related output in both versions, only limited
8486 analysis has been done. Implementations can ensure safety from
8487 cross-protocol related output by not reusing PSKs between TLS 1.3 and
8488 TLS 1.2.
8489
8490E.8. Attacks on Static RSA
8491
8492 Although TLS 1.3 does not use RSA key transport and so is not
8493 directly susceptible to Bleichenbacher-type attacks [Blei98], if TLS
8494 1.3 servers also support static RSA in the context of previous
8495 versions of TLS, then it may be possible to impersonate the server
8496 for TLS 1.3 connections [JSS15]. TLS 1.3 implementations can prevent
8497 this attack by disabling support for static RSA across all versions
8498 of TLS. In principle, implementations might also be able to separate
8499 certificates with different keyUsage bits for static RSA decryption
8500 and RSA signature, but this technique relies on clients refusing to
8501 accept signatures using keys in certificates that do not have the
8502 digitalSignature bit set, and many clients do not enforce this
8503 restriction.
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
8514Rescorla Standards Track [Page 152]
8515
8516RFC 8446 TLS August 2018
8517
8518
8519Contributors
8520
8521 Martin Abadi
8522 University of California, Santa Cruz
8523 abadi@cs.ucsc.edu
8524
8525 Christopher Allen
8526 (co-editor of TLS 1.0)
8527 Alacrity Ventures
8528 ChristopherA@AlacrityManagement.com
8529
8530 Richard Barnes
8531 Cisco
8532 rlb@ipv.sx
8533
8534 Steven M. Bellovin
8535 Columbia University
8536 smb@cs.columbia.edu
8537
8538 David Benjamin
8539 Google
8540 davidben@google.com
8541
8542 Benjamin Beurdouche
8543 INRIA & Microsoft Research
8544 benjamin.beurdouche@ens.fr
8545
8546 Karthikeyan Bhargavan
8547 (editor of [RFC7627])
8548 INRIA
8549 karthikeyan.bhargavan@inria.fr
8550
8551 Simon Blake-Wilson
8552 (co-author of [RFC4492])
8553 BCI
8554 sblakewilson@bcisse.com
8555
8556 Nelson Bolyard
8557 (co-author of [RFC4492])
8558 Sun Microsystems, Inc.
8559 nelson@bolyard.com
8560
8561 Ran Canetti
8562 IBM
8563 canetti@watson.ibm.com
8564
8565
8566
8567
8568
8569
8570Rescorla Standards Track [Page 153]
8571
8572RFC 8446 TLS August 2018
8573
8574
8575 Matt Caswell
8576 OpenSSL
8577 matt@openssl.org
8578
8579 Stephen Checkoway
8580 University of Illinois at Chicago
8581 sfc@uic.edu
8582
8583 Pete Chown
8584 Skygate Technology Ltd
8585 pc@skygate.co.uk
8586
8587 Katriel Cohn-Gordon
8588 University of Oxford
8589 me@katriel.co.uk
8590
8591 Cas Cremers
8592 University of Oxford
8593 cas.cremers@cs.ox.ac.uk
8594
8595 Antoine Delignat-Lavaud
8596 (co-author of [RFC7627])
8597 INRIA
8598 antdl@microsoft.com
8599
8600 Tim Dierks
8601 (co-author of TLS 1.0, co-editor of TLS 1.1 and 1.2)
8602 Independent
8603 tim@dierks.org
8604
8605 Roelof DuToit
8606 Symantec Corporation
8607 roelof_dutoit@symantec.com
8608
8609 Taher Elgamal
8610 Securify
8611 taher@securify.com
8612
8613 Pasi Eronen
8614 Nokia
8615 pasi.eronen@nokia.com
8616
8617 Cedric Fournet
8618 Microsoft
8619 fournet@microsoft.com
8620
8621
8622
8623
8624
8625
8626Rescorla Standards Track [Page 154]
8627
8628RFC 8446 TLS August 2018
8629
8630
8631 Anil Gangolli
8632 anil@busybuddha.org
8633
8634 David M. Garrett
8635 dave@nulldereference.com
8636
8637 Illya Gerasymchuk
8638 Independent
8639 illya@iluxonchik.me
8640
8641 Alessandro Ghedini
8642 Cloudflare Inc.
8643 alessandro@cloudflare.com
8644
8645 Daniel Kahn Gillmor
8646 ACLU
8647 dkg@fifthhorseman.net
8648
8649 Matthew Green
8650 Johns Hopkins University
8651 mgreen@cs.jhu.edu
8652
8653 Jens Guballa
8654 ETAS
8655 jens.guballa@etas.com
8656
8657 Felix Guenther
8658 TU Darmstadt
8659 mail@felixguenther.info
8660
8661 Vipul Gupta
8662 (co-author of [RFC4492])
8663 Sun Microsystems Laboratories
8664 vipul.gupta@sun.com
8665
8666 Chris Hawk
8667 (co-author of [RFC4492])
8668 Corriente Networks LLC
8669 chris@corriente.net
8670
8671 Kipp Hickman
8672
8673 Alfred Hoenes
8674
8675 David Hopwood
8676 Independent Consultant
8677 david.hopwood@blueyonder.co.uk
8678
8679
8680
8681
8682Rescorla Standards Track [Page 155]
8683
8684RFC 8446 TLS August 2018
8685
8686
8687 Marko Horvat
8688 MPI-SWS
8689 mhorvat@mpi-sws.org
8690
8691 Jonathan Hoyland
8692 Royal Holloway, University of London
8693 jonathan.hoyland@gmail.com
8694
8695 Subodh Iyengar
8696 Facebook
8697 subodh@fb.com
8698
8699 Benjamin Kaduk
8700 Akamai Technologies
8701 kaduk@mit.edu
8702
8703 Hubert Kario
8704 Red Hat Inc.
8705 hkario@redhat.com
8706
8707 Phil Karlton
8708 (co-author of SSL 3.0)
8709
8710 Leon Klingele
8711 Independent
8712 mail@leonklingele.de
8713
8714 Paul Kocher
8715 (co-author of SSL 3.0)
8716 Cryptography Research
8717 paul@cryptography.com
8718
8719 Hugo Krawczyk
8720 IBM
8721 hugokraw@us.ibm.com
8722
8723 Adam Langley
8724 (co-author of [RFC7627])
8725 Google
8726 agl@google.com
8727
8728 Olivier Levillain
8729 ANSSI
8730 olivier.levillain@ssi.gouv.fr
8731
8732
8733
8734
8735
8736
8737
8738Rescorla Standards Track [Page 156]
8739
8740RFC 8446 TLS August 2018
8741
8742
8743 Xiaoyin Liu
8744 University of North Carolina at Chapel Hill
8745 xiaoyin.l@outlook.com
8746
8747 Ilari Liusvaara
8748 Independent
8749 ilariliusvaara@welho.com
8750
8751 Atul Luykx
8752 K.U. Leuven
8753 atul.luykx@kuleuven.be
8754
8755 Colm MacCarthaigh
8756 Amazon Web Services
8757 colm@allcosts.net
8758
8759 Carl Mehner
8760 USAA
8761 carl.mehner@usaa.com
8762
8763 Jan Mikkelsen
8764 Transactionware
8765 janm@transactionware.com
8766
8767 Bodo Moeller
8768 (co-author of [RFC4492])
8769 Google
8770 bodo@acm.org
8771
8772 Kyle Nekritz
8773 Facebook
8774 knekritz@fb.com
8775
8776 Erik Nygren
8777 Akamai Technologies
8778 erik+ietf@nygren.org
8779
8780 Magnus Nystrom
8781 Microsoft
8782 mnystrom@microsoft.com
8783
8784 Kazuho Oku
8785 DeNA Co., Ltd.
8786 kazuhooku@gmail.com
8787
8788
8789
8790
8791
8792
8793
8794Rescorla Standards Track [Page 157]
8795
8796RFC 8446 TLS August 2018
8797
8798
8799 Kenny Paterson
8800 Royal Holloway, University of London
8801 kenny.paterson@rhul.ac.uk
8802
8803 Christopher Patton
8804 University of Florida
8805 cjpatton@ufl.edu
8806
8807 Alfredo Pironti
8808 (co-author of [RFC7627])
8809 INRIA
8810 alfredo.pironti@inria.fr
8811
8812 Andrei Popov
8813 Microsoft
8814 andrei.popov@microsoft.com
8815
8816 Marsh Ray
8817 (co-author of [RFC7627])
8818 Microsoft
8819 maray@microsoft.com
8820
8821 Robert Relyea
8822 Netscape Communications
8823 relyea@netscape.com
8824
8825 Kyle Rose
8826 Akamai Technologies
8827 krose@krose.org
8828
8829 Jim Roskind
8830 Amazon
8831 jroskind@amazon.com
8832
8833 Michael Sabin
8834
8835 Joe Salowey
8836 Tableau Software
8837 joe@salowey.net
8838
8839 Rich Salz
8840 Akamai
8841 rsalz@akamai.com
8842
8843 David Schinazi
8844 Apple Inc.
8845 dschinazi@apple.com
8846
8847
8848
8849
8850Rescorla Standards Track [Page 158]
8851
8852RFC 8446 TLS August 2018
8853
8854
8855 Sam Scott
8856 Royal Holloway, University of London
8857 me@samjs.co.uk
8858
8859 Thomas Shrimpton
8860 University of Florida
8861 teshrim@ufl.edu
8862
8863 Dan Simon
8864 Microsoft, Inc.
8865 dansimon@microsoft.com
8866
8867 Brian Smith
8868 Independent
8869 brian@briansmith.org
8870
8871 Brian Sniffen
8872 Akamai Technologies
8873 ietf@bts.evenmere.org
8874
8875 Nick Sullivan
8876 Cloudflare Inc.
8877 nick@cloudflare.com
8878
8879 Bjoern Tackmann
8880 University of California, San Diego
8881 btackmann@eng.ucsd.edu
8882
8883 Tim Taubert
8884 Mozilla
8885 ttaubert@mozilla.com
8886
8887 Martin Thomson
8888 Mozilla
8889 mt@mozilla.com
8890
8891 Hannes Tschofenig
8892 Arm Limited
8893 Hannes.Tschofenig@arm.com
8894
8895 Sean Turner
8896 sn3rd
8897 sean@sn3rd.com
8898
8899 Steven Valdez
8900 Google
8901 svaldez@google.com
8902
8903
8904
8905
8906Rescorla Standards Track [Page 159]
8907
8908RFC 8446 TLS August 2018
8909
8910
8911 Filippo Valsorda
8912 Cloudflare Inc.
8913 filippo@cloudflare.com
8914
8915 Thyla van der Merwe
8916 Royal Holloway, University of London
8917 tjvdmerwe@gmail.com
8918
8919 Victor Vasiliev
8920 Google
8921 vasilvv@google.com
8922
8923 Hoeteck Wee
8924 Ecole Normale Superieure, Paris
8925 hoeteck@alum.mit.edu
8926
8927 Tom Weinstein
8928
8929 David Wong
8930 NCC Group
8931 david.wong@nccgroup.trust
8932
8933 Christopher A. Wood
8934 Apple Inc.
8935 cawood@apple.com
8936
8937 Tim Wright
8938 Vodafone
8939 timothy.wright@vodafone.com
8940
8941 Peter Wu
8942 Independent
8943 peter@lekensteyn.nl
8944
8945 Kazu Yamamoto
8946 Internet Initiative Japan Inc.
8947 kazu@iij.ad.jp
8948
8949Author's Address
8950
8951 Eric Rescorla
8952 Mozilla
8953
8954 Email: ekr@rtfm.com
8955
8956
8957
8958
8959
8960
8961
8962Rescorla Standards Track [Page 160]
8963
8964