idnits 2.17.1 draft-ietf-tls-tls13-22.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 28 instances of too long lines in the document, the longest one being 5 characters in excess of 72. -- The draft header indicates that this document obsoletes RFC5077, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document obsoletes RFC5246, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC6066, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC5705, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC6961, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC4492, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4492, updated by this document, for RFC5378 checks: 1998-03-18) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 29, 2017) is 2311 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'NewSessionTicket' is mentioned on line 986, but not defined -- Looks like a reference, but probably isn't: '0' on line 1109 -- Looks like a reference, but probably isn't: '1' on line 6518 -- Looks like a reference, but probably isn't: '3' on line 6522 -- Looks like a reference, but probably isn't: '9' on line 1149 -- Looks like a reference, but probably isn't: '2' on line 6520 -- Looks like a reference, but probably isn't: '4' on line 1185 -- Looks like a reference, but probably isn't: '8' on line 1186 -- Looks like a reference, but probably isn't: '10' on line 1302 -- Looks like a reference, but probably isn't: '32' on line 5388 == Unused Reference: 'RFC4681' is defined on line 5052, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DH' -- Possible downref: Non-RFC (?) normative reference: ref. 'GCM' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Obsolete normative reference: RFC 6961 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6962 (Obsoleted by RFC 9162) ** Downref: Normative reference to an Informational RFC: RFC 6979 ** Obsolete normative reference: RFC 7507 (Obsoleted by RFC 8996) ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) ** Downref: Normative reference to an Informational RFC: RFC 7748 ** Downref: Normative reference to an Informational RFC: RFC 8017 ** Downref: Normative reference to an Informational RFC: RFC 8032 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- Possible downref: Non-RFC (?) normative reference: ref. 'X962' -- No information found for draft-10 - is the name correct? -- No information found for draft-10 - is the name correct? -- Duplicate reference: draft-10, mentioned in 'DFGS16', was also mentioned in 'DFGS15'. == Outdated reference: A later version (-05) exists of draft-ietf-tls-iana-registry-updates-02 == Outdated reference: A later version (-07) exists of draft-ietf-tls-tls13-vectors-02 -- Obsolete informational reference (is this intentional?): RFC 4346 (Obsoleted by RFC 5246) -- Obsolete informational reference (is this intentional?): RFC 4366 (Obsoleted by RFC 5246, RFC 6066) -- Obsolete informational reference (is this intentional?): RFC 4492 (Obsoleted by RFC 8422) -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 6555 (Obsoleted by RFC 8305) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 12 errors (**), 0 flaws (~~), 5 warnings (==), 34 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Rescorla 3 Internet-Draft RTFM, Inc. 4 Obsoletes: 5077, 5246 (if approved) November 29, 2017 5 Updates: 4492, 5705, 6066, 6961 (if 6 approved) 7 Intended status: Standards Track 8 Expires: June 2, 2018 10 The Transport Layer Security (TLS) Protocol Version 1.3 11 draft-ietf-tls-tls13-22 13 Abstract 15 This document specifies version 1.3 of the Transport Layer Security 16 (TLS) protocol. TLS allows client/server applications to communicate 17 over the Internet in a way that is designed to prevent eavesdropping, 18 tampering, and message forgery. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on June 2, 2018. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 This document may contain material from IETF Documents or IETF 53 Contributions published or made publicly available before November 54 10, 2008. The person(s) controlling the copyright in some of this 55 material may not have granted the IETF Trust the right to allow 56 modifications of such material outside the IETF Standards Process. 57 Without obtaining an adequate license from the person(s) controlling 58 the copyright in such materials, this document may not be modified 59 outside the IETF Standards Process, and derivative works of it may 60 not be created outside the IETF Standards Process, except to format 61 it for publication as an RFC or to translate it into languages other 62 than English. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 67 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 6 68 1.2. Change Log . . . . . . . . . . . . . . . . . . . . . . . 6 69 1.3. Major Differences from TLS 1.2 . . . . . . . . . . . . . 15 70 1.4. Updates Affecting TLS 1.2 . . . . . . . . . . . . . . . . 16 71 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 16 72 2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . . . 20 73 2.2. Resumption and Pre-Shared Key (PSK) . . . . . . . . . . . 21 74 2.3. 0-RTT Data . . . . . . . . . . . . . . . . . . . . . . . 23 75 3. Presentation Language . . . . . . . . . . . . . . . . . . . . 25 76 3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 25 77 3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 25 78 3.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 26 79 3.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 27 80 3.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 27 81 3.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 28 82 3.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 28 83 3.8. Variants . . . . . . . . . . . . . . . . . . . . . . . . 29 84 4. Handshake Protocol . . . . . . . . . . . . . . . . . . . . . 30 85 4.1. Key Exchange Messages . . . . . . . . . . . . . . . . . . 31 86 4.1.1. Cryptographic Negotiation . . . . . . . . . . . . . . 31 87 4.1.2. Client Hello . . . . . . . . . . . . . . . . . . . . 32 88 4.1.3. Server Hello . . . . . . . . . . . . . . . . . . . . 35 89 4.1.4. Hello Retry Request . . . . . . . . . . . . . . . . . 37 90 4.2. Extensions . . . . . . . . . . . . . . . . . . . . . . . 38 91 4.2.1. Supported Versions . . . . . . . . . . . . . . . . . 42 92 4.2.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . 44 93 4.2.3. Signature Algorithms . . . . . . . . . . . . . . . . 44 94 4.2.4. Certificate Authorities . . . . . . . . . . . . . . . 47 95 4.2.5. OID Filters . . . . . . . . . . . . . . . . . . . . . 48 96 4.2.6. Post-Handshake Client Authentication . . . . . . . . 49 97 4.2.7. Negotiated Groups . . . . . . . . . . . . . . . . . . 49 98 4.2.8. Key Share . . . . . . . . . . . . . . . . . . . . . . 51 99 4.2.9. Pre-Shared Key Exchange Modes . . . . . . . . . . . . 54 100 4.2.10. Early Data Indication . . . . . . . . . . . . . . . . 54 101 4.2.11. Pre-Shared Key Extension . . . . . . . . . . . . . . 57 102 4.3. Server Parameters . . . . . . . . . . . . . . . . . . . . 61 103 4.3.1. Encrypted Extensions . . . . . . . . . . . . . . . . 61 104 4.3.2. Certificate Request . . . . . . . . . . . . . . . . . 62 105 4.4. Authentication Messages . . . . . . . . . . . . . . . . . 62 106 4.4.1. The Transcript Hash . . . . . . . . . . . . . . . . . 64 107 4.4.2. Certificate . . . . . . . . . . . . . . . . . . . . . 65 108 4.4.3. Certificate Verify . . . . . . . . . . . . . . . . . 70 109 4.4.4. Finished . . . . . . . . . . . . . . . . . . . . . . 72 110 4.5. End of Early Data . . . . . . . . . . . . . . . . . . . . 73 111 4.6. Post-Handshake Messages . . . . . . . . . . . . . . . . . 74 112 4.6.1. New Session Ticket Message . . . . . . . . . . . . . 74 113 4.6.2. Post-Handshake Authentication . . . . . . . . . . . . 76 114 4.6.3. Key and IV Update . . . . . . . . . . . . . . . . . . 77 115 5. Record Protocol . . . . . . . . . . . . . . . . . . . . . . . 78 116 5.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 79 117 5.2. Record Payload Protection . . . . . . . . . . . . . . . . 81 118 5.3. Per-Record Nonce . . . . . . . . . . . . . . . . . . . . 83 119 5.4. Record Padding . . . . . . . . . . . . . . . . . . . . . 83 120 5.5. Limits on Key Usage . . . . . . . . . . . . . . . . . . . 85 121 6. Alert Protocol . . . . . . . . . . . . . . . . . . . . . . . 85 122 6.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 86 123 6.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 87 124 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 90 125 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 90 126 7.2. Updating Traffic Keys and IVs . . . . . . . . . . . . . . 93 127 7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 94 128 7.4. (EC)DHE Shared Secret Calculation . . . . . . . . . . . . 94 129 7.4.1. Finite Field Diffie-Hellman . . . . . . . . . . . . . 95 130 7.4.2. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 95 131 7.5. Exporters . . . . . . . . . . . . . . . . . . . . . . . . 96 132 8. 0-RTT and Anti-Replay . . . . . . . . . . . . . . . . . . . . 96 133 8.1. Single-Use Tickets . . . . . . . . . . . . . . . . . . . 98 134 8.2. Client Hello Recording . . . . . . . . . . . . . . . . . 98 135 8.3. Freshness Checks . . . . . . . . . . . . . . . . . . . . 99 136 9. Compliance Requirements . . . . . . . . . . . . . . . . . . . 101 137 9.1. Mandatory-to-Implement Cipher Suites . . . . . . . . . . 101 138 9.2. Mandatory-to-Implement Extensions . . . . . . . . . . . . 101 139 10. Security Considerations . . . . . . . . . . . . . . . . . . . 102 140 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 102 141 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 104 142 12.1. Normative References . . . . . . . . . . . . . . . . . . 104 143 12.2. Informative References . . . . . . . . . . . . . . . . . 106 144 Appendix A. State Machine . . . . . . . . . . . . . . . . . . . 114 145 A.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 114 146 A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 115 147 Appendix B. Protocol Data Structures and Constant Values . . . . 115 148 B.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 116 149 B.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 116 150 B.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 118 151 B.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 118 152 B.3.2. Server Parameters Messages . . . . . . . . . . . . . 123 153 B.3.3. Authentication Messages . . . . . . . . . . . . . . . 124 154 B.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 125 155 B.3.5. Updating Keys . . . . . . . . . . . . . . . . . . . . 125 156 B.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 126 157 Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 127 158 C.1. Random Number Generation and Seeding . . . . . . . . . . 127 159 C.2. Certificates and Authentication . . . . . . . . . . . . . 128 160 C.3. Implementation Pitfalls . . . . . . . . . . . . . . . . . 128 161 C.4. Client Tracking Prevention . . . . . . . . . . . . . . . 129 162 C.5. Unauthenticated Operation . . . . . . . . . . . . . . . . 130 163 Appendix D. Backward Compatibility . . . . . . . . . . . . . . . 130 164 D.1. Negotiating with an older server . . . . . . . . . . . . 131 165 D.2. Negotiating with an older client . . . . . . . . . . . . 132 166 D.3. 0-RTT backwards compatibility . . . . . . . . . . . . . . 132 167 D.4. Middlebox Compatibility Mode . . . . . . . . . . . . . . 132 168 D.5. Backwards Compatibility Security Restrictions . . . . . . 133 169 Appendix E. Overview of Security Properties . . . . . . . . . . 134 170 E.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 134 171 E.1.1. Key Derivation and HKDF . . . . . . . . . . . . . . . 137 172 E.1.2. Client Authentication . . . . . . . . . . . . . . . . 138 173 E.1.3. 0-RTT . . . . . . . . . . . . . . . . . . . . . . . . 138 174 E.1.4. Exporter Independence . . . . . . . . . . . . . . . . 138 175 E.1.5. Post-Compromise Security . . . . . . . . . . . . . . 139 176 E.1.6. External References . . . . . . . . . . . . . . . . . 139 177 E.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 139 178 E.2.1. External References . . . . . . . . . . . . . . . . . 140 179 E.3. Traffic Analysis . . . . . . . . . . . . . . . . . . . . 140 180 E.4. Side Channel Attacks . . . . . . . . . . . . . . . . . . 141 181 E.5. Replay Attacks on 0-RTT . . . . . . . . . . . . . . . . . 142 182 E.5.1. Replay and Exporters . . . . . . . . . . . . . . . . 143 183 Appendix F. Working Group Information . . . . . . . . . . . . . 143 184 Appendix G. Contributors . . . . . . . . . . . . . . . . . . . . 144 185 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 150 187 1. Introduction 189 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 190 draft is maintained in GitHub. Suggested changes should be submitted 191 as pull requests at https://github.com/tlswg/tls13-spec. 192 Instructions are on that page as well. Editorial changes can be 193 managed in GitHub, but any substantive change should be discussed on 194 the TLS mailing list. 196 The primary goal of TLS is to provide a secure channel between two 197 communicating peers. Specifically, the channel should provide the 198 following properties: 200 - Authentication: The server side of the channel is always 201 authenticated; the client side is optionally authenticated. 202 Authentication can happen via asymmetric cryptography (e.g., RSA 203 [RSA], ECDSA [ECDSA], EdDSA [RFC8032]) or a pre-shared key (PSK). 205 - Confidentiality: Data sent over the channel after establishment is 206 only visible to the endpoints. TLS does not hide the length of 207 the data it transmits, though endpoints are able to pad TLS 208 records in order to obscure lengths and improve protection against 209 traffic analysis techniques. 211 - Integrity: Data sent over the channel after establishment cannot 212 be modified by attackers. 214 These properties should be true even in the face of an attacker who 215 has complete control of the network, as described in [RFC3552]. See 216 Appendix E for a more complete statement of the relevant security 217 properties. 219 TLS consists of two primary components: 221 - A handshake protocol (Section 4) that authenticates the 222 communicating parties, negotiates cryptographic modes and 223 parameters, and establishes shared keying material. The handshake 224 protocol is designed to resist tampering; an active attacker 225 should not be able to force the peers to negotiate different 226 parameters than they would if the connection were not under 227 attack. 229 - A record protocol (Section 5) that uses the parameters established 230 by the handshake protocol to protect traffic between the 231 communicating peers. The record protocol divides traffic up into 232 a series of records, each of which is independently protected 233 using the traffic keys. 235 TLS is application protocol independent; higher-level protocols can 236 layer on top of TLS transparently. The TLS standard, however, does 237 not specify how protocols add security with TLS; how to initiate TLS 238 handshaking and how to interpret the authentication certificates 239 exchanged are left to the judgment of the designers and implementors 240 of protocols that run on top of TLS. 242 This document defines TLS version 1.3. While TLS 1.3 is not directly 243 compatible with previous versions, all versions of TLS incorporate a 244 versioning mechanism which allows clients and servers to 245 interoperably negotiate a common version if one is supported by both 246 peers. 248 This document supersedes and obsoletes previous versions of TLS 249 including version 1.2 [RFC5246]. It also obsoletes the TLS ticket 250 mechanism defined in [RFC5077] and replaces it with the mechanism 251 defined in Section 2.2. Section 4.2.7 updates [RFC4492] by modifying 252 the protocol attributes used to negotiate Elliptic Curves. Because 253 TLS 1.3 changes the way keys are derived it updates [RFC5705] as 254 described in Section 7.5 it also changes how OCSP messages are 255 carried and therefore updates [RFC6066] and obsoletes [RFC6961] as 256 described in section Section 4.4.2.1. 258 1.1. Conventions and Terminology 260 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 261 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 262 "OPTIONAL" in this document are to be interpreted as described in RFC 263 2119 [RFC2119]. 265 The following terms are used: 267 client: The endpoint initiating the TLS connection. 269 connection: A transport-layer connection between two endpoints. 271 endpoint: Either the client or server of the connection. 273 handshake: An initial negotiation between client and server that 274 establishes the parameters of their subsequent interactions. 276 peer: An endpoint. When discussing a particular endpoint, "peer" 277 refers to the endpoint that is not the primary subject of discussion. 279 receiver: An endpoint that is receiving records. 281 sender: An endpoint that is transmitting records. 283 server: The endpoint which did not initiate the TLS connection. 285 1.2. Change Log 287 RFC EDITOR PLEASE DELETE THIS SECTION. 289 (*) indicates changes to the wire protocol which may require 290 implementations to update. 292 draft-22 - Implement changes for improved middlebox penetration (*) 294 - Move server_certificate_type to encrypted extensions (*) 296 - Allow resumption with a different SNI (*) 298 - Padding extension can change on HRR (*) 300 - Allow an empty ticket_nonce (*) 302 - Remove requirement to immediately respond to close_notify with 303 close_notify (allowing half-close) 305 draft-21 307 - Add a per-ticket nonce so that each ticket is associated with a 308 different PSK (*). 310 - Clarify that clients should send alerts with the handshake key if 311 possible. 313 - Update state machine to show rekeying events 315 - Add discussion of 0-RTT and replay. Recommend that 316 implementations implement some anti-replay mechanism. 318 draft-20 320 - Add "post_handshake_auth" extension to negotiate post-handshake 321 authentication (*). 323 - Shorten labels for HKDF-Expand-Label so that we can fit within one 324 compression block (*). 326 - Define how RFC 7250 works (*). 328 - Re-enable post-handshake client authentication even when you do 329 PSK. The previous prohibition was editorial error. 331 - Remove cert_type and user_mapping, which don't work on TLS 1.3 332 anyway. 334 - Added the no_application_protocol alert from [RFC7301] to the list 335 of extensions. 337 - Added discussion of traffic analysis and side channel attacks. 339 draft-19 341 - Hash context_value input to Exporters (*) 343 - Add an additional Derive-Secret stage to Exporters (*). 345 - Hash ClientHello1 in the transcript when HRR is used. This 346 reduces the state that needs to be carried in cookies. (*) 348 - Restructure CertificateRequest to have the selectors in 349 extensions. This also allowed defining a 350 "certificate_authorities" extension which can be used by the 351 client instead of trusted_ca_keys (*). 353 - Tighten record framing requirements and require checking of them 354 (*). 356 - Consolidate "ticket_early_data_info" and "early_data" into a 357 single extension (*). 359 - Change end_of_early_data to be a handshake message (*). 361 - Add pre-extract Derive-Secret stages to key schedule (*). 363 - Remove spurious requirement to implement "pre_shared_key". 365 - Clarify location of "early_data" from server (it goes in EE, as 366 indicated by the table in S 10). 368 - Require peer public key validation 370 - Add state machine diagram. 372 draft-18 374 - Remove unnecessary resumption_psk which is the only thing expanded 375 from the resumption master secret. (*). 377 - Fix signature_algorithms entry in extensions table. 379 - Restate rule from RFC 6066 that you can't resume unless SNI is the 380 same. 382 draft-17 383 - Remove 0-RTT Finished and resumption_context, and replace with a 384 psk_binder field in the PSK itself (*) 386 - Restructure PSK key exchange negotiation modes (*) 388 - Add max_early_data_size field to TicketEarlyDataInfo (*) 390 - Add a 0-RTT exporter and change the transcript for the regular 391 exporter (*) 393 - Merge TicketExtensions and Extensions registry. Changes 394 ticket_early_data_info code point (*) 396 - Replace Client.key_shares in response to HRR (*) 398 - Remove redundant labels for traffic key derivation (*) 400 - Harmonize requirements about cipher suite matching: for resumption 401 you need to match KDF but for 0-RTT you need whole cipher suite. 402 This allows PSKs to actually negotiate cipher suites. (*) 404 - Move SCT and OCSP into Certificate.extensions (*) 406 - Explicitly allow non-offered extensions in NewSessionTicket 408 - Explicitly allow predicting client Finished for NST 410 - Clarify conditions for allowing 0-RTT with PSK 412 draft-16 414 - Revise version negotiation (*) 416 - Change RSASSA-PSS and EdDSA SignatureScheme codepoints for better 417 backwards compatibility (*) 419 - Move HelloRetryRequest.selected_group to an extension (*) 421 - Clarify the behavior of no exporter context and make it the same 422 as an empty context.(*) 424 - New KeyUpdate format that allows for requesting/not-requesting an 425 answer. This also means changes to the key schedule to support 426 independent updates (*) 428 - New certificate_required alert (*) 430 - Forbid CertificateRequest with 0-RTT and PSK. 432 - Relax requirement to check SNI for 0-RTT. 434 draft-15 436 - New negotiation syntax as discussed in Berlin (*) 438 - Require CertificateRequest.context to be empty during handshake 439 (*) 441 - Forbid empty tickets (*) 443 - Forbid application data messages in between post-handshake 444 messages from the same flight (*) 446 - Clean up alert guidance (*) 448 - Clearer guidance on what is needed for TLS 1.2. 450 - Guidance on 0-RTT time windows. 452 - Rename a bunch of fields. 454 - Remove old PRNG text. 456 - Explicitly require checking that handshake records not span key 457 changes. 459 draft-14 461 - Allow cookies to be longer (*) 463 - Remove the "context" from EarlyDataIndication as it was undefined 464 and nobody used it (*) 466 - Remove 0-RTT EncryptedExtensions and replace the ticket_age 467 extension with an obfuscated version. Also necessitates a change 468 to NewSessionTicket (*). 470 - Move the downgrade sentinel to the end of ServerHello.Random to 471 accommodate tlsdate (*). 473 - Define ecdsa_sha1 (*). 475 - Allow resumption even after fatal alerts. This matches current 476 practice. 478 - Remove non-closure warning alerts. Require treating unknown 479 alerts as fatal. 481 - Make the rules for accepting 0-RTT less restrictive. 483 - Clarify 0-RTT backward-compatibility rules. 485 - Clarify how 0-RTT and PSK identities interact. 487 - Add a section describing the data limits for each cipher. 489 - Major editorial restructuring. 491 - Replace the Security Analysis section with a WIP draft. 493 draft-13 495 - Allow server to send SupportedGroups. 497 - Remove 0-RTT client authentication 499 - Remove (EC)DHE 0-RTT. 501 - Flesh out 0-RTT PSK mode and shrink EarlyDataIndication 503 - Turn PSK-resumption response into an index to save room 505 - Move CertificateStatus to an extension 507 - Extra fields in NewSessionTicket. 509 - Restructure key schedule and add a resumption_context value. 511 - Require DH public keys and secrets to be zero-padded to the size 512 of the group. 514 - Remove the redundant length fields in KeyShareEntry. 516 - Define a cookie field for HRR. 518 draft-12 520 - Provide a list of the PSK cipher suites. 522 - Remove the ability for the ServerHello to have no extensions (this 523 aligns the syntax with the text). 525 - Clarify that the server can send application data after its first 526 flight (0.5 RTT data) 528 - Revise signature algorithm negotiation to group hash, signature 529 algorithm, and curve together. This is backwards compatible. 531 - Make ticket lifetime mandatory and limit it to a week. 533 - Make the purpose strings lower-case. This matches how people are 534 implementing for interop. 536 - Define exporters. 538 - Editorial cleanup 540 draft-11 542 - Port the CFRG curves & signatures work from RFC4492bis. 544 - Remove sequence number and version from additional_data, which is 545 now empty. 547 - Reorder values in HkdfLabel. 549 - Add support for version anti-downgrade mechanism. 551 - Update IANA considerations section and relax some of the policies. 553 - Unify authentication modes. Add post-handshake client 554 authentication. 556 - Remove early_handshake content type. Terminate 0-RTT data with an 557 alert. 559 - Reset sequence number upon key change (as proposed by Fournet et 560 al.) 562 draft-10 564 - Remove ClientCertificateTypes field from CertificateRequest and 565 add extensions. 567 - Merge client and server key shares into a single extension. 569 draft-09 571 - Change to RSA-PSS signatures for handshake messages. 573 - Remove support for DSA. 575 - Update key schedule per suggestions by Hugo, Hoeteck, and Bjoern 576 Tackmann. 578 - Add support for per-record padding. 580 - Switch to encrypted record ContentType. 582 - Change HKDF labeling to include protocol version and value 583 lengths. 585 - Shift the final decision to abort a handshake due to incompatible 586 certificates to the client rather than having servers abort early. 588 - Deprecate SHA-1 with signatures. 590 - Add MTI algorithms. 592 draft-08 594 - Remove support for weak and lesser used named curves. 596 - Remove support for MD5 and SHA-224 hashes with signatures. 598 - Update lists of available AEAD cipher suites and error alerts. 600 - Reduce maximum permitted record expansion for AEAD from 2048 to 601 256 octets. 603 - Require digital signatures even when a previous configuration is 604 used. 606 - Merge EarlyDataIndication and KnownConfiguration. 608 - Change code point for server_configuration to avoid collision with 609 server_hello_done. 611 - Relax certificate_list ordering requirement to match current 612 practice. 614 draft-07 616 - Integration of semi-ephemeral DH proposal. 618 - Add initial 0-RTT support. 620 - Remove resumption and replace with PSK + tickets. 622 - Move ClientKeyShare into an extension. 624 - Move to HKDF. 626 draft-06 628 - Prohibit RC4 negotiation for backwards compatibility. 630 - Freeze & deprecate record layer version field. 632 - Update format of signatures with context. 634 - Remove explicit IV. 636 draft-05 638 - Prohibit SSL negotiation for backwards compatibility. 640 - Fix which MS is used for exporters. 642 draft-04 644 - Modify key computations to include session hash. 646 - Remove ChangeCipherSpec. 648 - Renumber the new handshake messages to be somewhat more consistent 649 with existing convention and to remove a duplicate registration. 651 - Remove renegotiation. 653 - Remove point format negotiation. 655 draft-03 657 - Remove GMT time. 659 - Merge in support for ECC from RFC 4492 but without explicit 660 curves. 662 - Remove the unnecessary length field from the AD input to AEAD 663 ciphers. 665 - Rename {Client,Server}KeyExchange to {Client,Server}KeyShare. 667 - Add an explicit HelloRetryRequest to reject the client's. 669 draft-02 671 - Increment version number. 673 - Rework handshake to provide 1-RTT mode. 675 - Remove custom DHE groups. 677 - Remove support for compression. 679 - Remove support for static RSA and DH key exchange. 681 - Remove support for non-AEAD ciphers. 683 1.3. Major Differences from TLS 1.2 685 The following is a list of the major functional differences between 686 TLS 1.2 and TLS 1.3. It is not intended to be exhaustive and there 687 are many minor differences. 689 - The list of supported symmetric algorithms has been pruned of all 690 algorithms that are considered legacy. Those that remain all use 691 Authenticated Encryption with Associated Data (AEAD) algorithms. 692 The ciphersuite concept has been changed to separate the 693 authentication and key exchange mechanisms from the record 694 protection algorithm (including secret key length) and a hash to 695 be used with the key derivation function and HMAC. 697 - A 0-RTT mode was added, saving a round-trip at connection setup 698 for some application data, at the cost of certain security 699 properties. 701 - Static RSA and Diffie-Hellman cipher suites have been removed; all 702 public-key based key exchange mechanisms now provide forward 703 secrecy. 705 - All handshake messages after the ServerHello are now encrypted. 706 The newly introduced EncryptedExtension message allows various 707 extensions previously sent in clear in the ServerHello to also 708 enjoy confidentiality protection from active attackers. 710 - The key derivation functions have been re-designed. The new 711 design allows easier analysis by cryptographers due to their 712 improved key separation properties. The HMAC-based Extract-and- 713 Expand Key Derivation Function (HKDF) is used as an underlying 714 primitive. 716 - The handshake state machine has been significantly restructured to 717 be more consistent and to remove superfluous messages such as 718 ChangeCipherSpec. 720 - Elliptic curve algorithms are now in the base spec and includes 721 new signature algorithms, such as ed25519 and ed448. TLS 1.3 722 removed point format negotiation in favor of a single point format 723 for each curve. 725 - Other cryptographic improvements including the removal of 726 compression and custom DHE groups, changing the RSA padding to use 727 PSS, and the removal of DSA. 729 - The TLS 1.2 version negotiation mechanism has been deprecated in 730 favor of a version list in an extension. This increases 731 compatibility with servers which incorrectly implemented version 732 negotiation. 734 - Session resumption with and without server-side state as well as 735 the PSK-based ciphersuites of earlier TLS versions have been 736 replaced by a single new PSK exchange. 738 - Updated references to point to the updated versions of RFCs, as 739 appropriate (e.g., RFC 5280 rather than RFC 3280). 741 1.4. Updates Affecting TLS 1.2 743 This document defines several changes that optionally affect 744 implementations of TLS 1.2: 746 - A version downgrade protection mechanism is described in 747 Section 4.1.3. 749 - RSASSA-PSS signature schemes are defined in Section 4.2.3. 751 - The "supported_versions" ClientHello extension can be used to 752 negotiate the version of TLS to use, in preference to the 753 legacy_version field of the ClientHello. 755 An implementation of TLS 1.3 that also supports TLS 1.2 might need to 756 include changes to support these changes even when TLS 1.3 is not in 757 use. See the referenced sections for more details. 759 2. Protocol Overview 761 The cryptographic parameters used by the secure channel are produced 762 by the TLS handshake protocol. This sub-protocol of TLS is used by 763 the client and server when first communicating with each other. The 764 handshake protocol allows peers to negotiate a protocol version, 765 select cryptographic algorithms, optionally authenticate each other, 766 and establish shared secret keying material. Once the handshake is 767 complete, the peers use the established keys to protect the 768 application layer traffic. 770 A failure of the handshake or other protocol error triggers the 771 termination of the connection, optionally preceded by an alert 772 message (Section 6). 774 TLS supports three basic key exchange modes: 776 - (EC)DHE (Diffie-Hellman over either finite fields or elliptic 777 curves) 779 - PSK-only 781 - PSK with (EC)DHE 783 Figure 1 below shows the basic full TLS handshake: 785 Client Server 787 Key ^ ClientHello 788 Exch | + key_share* 789 | + signature_algorithms* 790 | + psk_key_exchange_modes* 791 v + pre_shared_key* --------> 792 ServerHello ^ Key 793 + key_share* | Exch 794 + pre_shared_key* v 795 {EncryptedExtensions} ^ Server 796 {CertificateRequest*} v Params 797 {Certificate*} ^ 798 {CertificateVerify*} | Auth 799 {Finished} v 800 <-------- [Application Data*] 801 ^ {Certificate*} 802 Auth | {CertificateVerify*} 803 v {Finished} --------> 804 [Application Data] <-------> [Application Data] 806 + Indicates noteworthy extensions sent in the 807 previously noted message. 809 * Indicates optional or situation-dependent 810 messages/extensions that are not always sent. 812 {} Indicates messages protected using keys 813 derived from a [sender]_handshake_traffic_secret. 815 [] Indicates messages protected using keys 816 derived from [sender]_application_traffic_secret_N 818 Figure 1: Message flow for full TLS Handshake 820 The handshake can be thought of as having three phases (indicated in 821 the diagram above): 823 - Key Exchange: Establish shared keying material and select the 824 cryptographic parameters. Everything after this phase is 825 encrypted. 827 - Server Parameters: Establish other handshake parameters (whether 828 the client is authenticated, application layer protocol support, 829 etc.). 831 - Authentication: Authenticate the server (and optionally the 832 client) and provide key confirmation and handshake integrity. 834 In the Key Exchange phase, the client sends the ClientHello 835 (Section 4.1.2) message, which contains a random nonce 836 (ClientHello.random); its offered protocol versions; a list of 837 symmetric cipher/HKDF hash pairs; either a set of Diffie-Hellman key 838 shares (in the "key_share" extension Section 4.2.8), a set of pre- 839 shared key labels (in the "pre_shared_key" extension Section 4.2.11) 840 or both; and potentially additional extensions. 842 The server processes the ClientHello and determines the appropriate 843 cryptographic parameters for the connection. It then responds with 844 its own ServerHello (Section 4.1.3), which indicates the negotiated 845 connection parameters. The combination of the ClientHello and the 846 ServerHello determines the shared keys. If (EC)DHE key establishment 847 is in use, then the ServerHello contains a "key_share" extension with 848 the server's ephemeral Diffie-Hellman share which MUST be in the same 849 group as one of the client's shares. If PSK key establishment is in 850 use, then the ServerHello contains a "pre_shared_key" extension 851 indicating which of the client's offered PSKs was selected. Note 852 that implementations can use (EC)DHE and PSK together, in which case 853 both extensions will be supplied. 855 The server then sends two messages to establish the Server 856 Parameters: 858 EncryptedExtensions: responses to ClientHello extensions that are 859 not required to determine the cryptographic parameters, other than 860 those that are specific to individual certificates. 861 [Section 4.3.1] 863 CertificateRequest: if certificate-based client authentication is 864 desired, the desired parameters for that certificate. This 865 message is omitted if client authentication is not desired. 866 [Section 4.3.2] 868 Finally, the client and server exchange Authentication messages. TLS 869 uses the same set of messages every time that authentication is 870 needed. Specifically: 872 Certificate: the certificate of the endpoint and any per-certificate 873 extensions. This message is omitted by the server if not 874 authenticating with a certificate and by the client if the server 875 did not send CertificateRequest (thus indicating that the client 876 should not authenticate with a certificate). Note that if raw 877 public keys [RFC7250] or the cached information extension 878 [RFC7924] are in use, then this message will not contain a 879 certificate but rather some other value corresponding to the 880 server's long-term key. [Section 4.4.2] 882 CertificateVerify: a signature over the entire handshake using the 883 private key corresponding to the public key in the Certificate 884 message. This message is omitted if the endpoint is not 885 authenticating via a certificate. [Section 4.4.3] 887 Finished: a MAC (Message Authentication Code) over the entire 888 handshake. This message provides key confirmation, binds the 889 endpoint's identity to the exchanged keys, and in PSK mode also 890 authenticates the handshake. [Section 4.4.4] 892 Upon receiving the server's messages, the client responds with its 893 Authentication messages, namely Certificate and CertificateVerify (if 894 requested), and Finished. 896 At this point, the handshake is complete, and the client and server 897 derive the keying material required by the record layer to exchange 898 application-layer data protected through authenticated encryption. 899 Application data MUST NOT be sent prior to sending the Finished 900 message and until the record layer starts using encryption keys. 901 Note that while the server may send application data prior to 902 receiving the client's Authentication messages, any data sent at that 903 point is, of course, being sent to an unauthenticated peer. 905 2.1. Incorrect DHE Share 907 If the client has not provided a sufficient "key_share" extension 908 (e.g., it includes only DHE or ECDHE groups unacceptable to or 909 unsupported by the server), the server corrects the mismatch with a 910 HelloRetryRequest and the client needs to restart the handshake with 911 an appropriate "key_share" extension, as shown in Figure 2. If no 912 common cryptographic parameters can be negotiated, the server MUST 913 abort the handshake with an appropriate alert. 915 Client Server 917 ClientHello 918 + key_share --------> 919 <-------- HelloRetryRequest 920 + key_share 922 ClientHello 923 + key_share --------> 924 ServerHello 925 + key_share 926 {EncryptedExtensions} 927 {CertificateRequest*} 928 {Certificate*} 929 {CertificateVerify*} 930 {Finished} 931 <-------- [Application Data*] 932 {Certificate*} 933 {CertificateVerify*} 934 {Finished} --------> 935 [Application Data] <-------> [Application Data] 937 Figure 2: Message flow for a full handshake with mismatched 938 parameters 940 Note: The handshake transcript includes the initial ClientHello/ 941 HelloRetryRequest exchange; it is not reset with the new ClientHello. 943 TLS also allows several optimized variants of the basic handshake, as 944 described in the following sections. 946 2.2. Resumption and Pre-Shared Key (PSK) 948 Although TLS PSKs can be established out of band, PSKs can also be 949 established in a previous connection and then reused ("session 950 resumption"). Once a handshake has completed, the server can send to 951 the client a PSK identity that corresponds to a unique key derived 952 from the initial handshake (see Section 4.6.1). The client can then 953 use that PSK identity in future handshakes to negotiate the use of 954 the associated PSK. If the server accepts it, then the security 955 context of the new connection is cryptographically tied to the 956 original connection and the key derived from the initial handshake is 957 used to bootstrap the cryptographic state instead of a full 958 handshake. In TLS 1.2 and below, this functionality was provided by 959 "session IDs" and "session tickets" [RFC5077]. Both mechanisms are 960 obsoleted in TLS 1.3. 962 PSKs can be used with (EC)DHE key exchange in order to provide 963 forward secrecy in combination with shared keys, or can be used 964 alone, at the cost of losing forward secrecy for the application 965 data. 967 Figure 3 shows a pair of handshakes in which the first establishes a 968 PSK and the second uses it: 970 Client Server 972 Initial Handshake: 973 ClientHello 974 + key_share --------> 975 ServerHello 976 + key_share 977 {EncryptedExtensions} 978 {CertificateRequest*} 979 {Certificate*} 980 {CertificateVerify*} 981 {Finished} 982 <-------- [Application Data*] 983 {Certificate*} 984 {CertificateVerify*} 985 {Finished} --------> 986 <-------- [NewSessionTicket] 987 [Application Data] <-------> [Application Data] 989 Subsequent Handshake: 990 ClientHello 991 + key_share* 992 + pre_shared_key --------> 993 ServerHello 994 + pre_shared_key 995 + key_share* 996 {EncryptedExtensions} 997 {Finished} 998 <-------- [Application Data*] 999 {Finished} --------> 1000 [Application Data] <-------> [Application Data] 1002 Figure 3: Message flow for resumption and PSK 1004 As the server is authenticating via a PSK, it does not send a 1005 Certificate or a CertificateVerify message. When a client offers 1006 resumption via PSK, it SHOULD also supply a "key_share" extension to 1007 the server to allow the server to decline resumption and fall back to 1008 a full handshake, if needed. The server responds with a 1009 "pre_shared_key" extension to negotiate use of PSK key establishment 1010 and can (as shown here) respond with a "key_share" extension to do 1011 (EC)DHE key establishment, thus providing forward secrecy. 1013 When PSKs are provisioned out of band, the PSK identity and the KDF 1014 hash algorithm to be used with the PSK MUST also be provisioned. 1016 Note: When using an out-of-band provisioned pre-shared secret, a 1017 critical consideration is using sufficient entropy during the key 1018 generation, as discussed in [RFC4086]. Deriving a shared secret 1019 from a password or other low-entropy sources is not secure. A 1020 low-entropy secret, or password, is subject to dictionary attacks 1021 based on the PSK binder. The specified PSK authentication is not 1022 a strong password-based authenticated key exchange even when used 1023 with Diffie-Hellman key establishment. 1025 2.3. 0-RTT Data 1027 When clients and servers share a PSK (either obtained externally or 1028 via a previous handshake), TLS 1.3 allows clients to send data on the 1029 first flight ("early data"). The client uses the PSK to authenticate 1030 the server and to encrypt the early data. 1032 As shown in Figure 4, the 0-RTT data is just added to the 1-RTT 1033 handshake in the first flight. The rest of the handshake uses the 1034 same messages as with a 1-RTT handshake with PSK resumption. 1036 Client Server 1038 ClientHello 1039 + early_data 1040 + key_share* 1041 + psk_key_exchange_modes 1042 + pre_shared_key 1043 (Application Data*) --------> 1044 ServerHello 1045 + pre_shared_key 1046 + key_share* 1047 {EncryptedExtensions} 1048 + early_data* 1049 {Finished} 1050 <-------- [Application Data*] 1051 (EndOfEarlyData) 1052 {Finished} --------> 1054 [Application Data] <-------> [Application Data] 1056 + Indicates noteworthy extensions sent in the 1057 previously noted message. 1059 * Indicates optional or situation-dependent 1060 messages/extensions that are not always sent. 1062 () Indicates messages protected using keys 1063 derived from client_early_traffic_secret. 1065 {} Indicates messages protected using keys 1066 derived from a [sender]_handshake_traffic_secret. 1068 [] Indicates messages protected using keys 1069 derived from [sender]_application_traffic_secret_N 1071 Figure 4: Message flow for a zero round trip handshake 1073 IMPORTANT NOTE: The security properties for 0-RTT data are weaker 1074 than those for other kinds of TLS data. Specifically: 1076 1. This data is not forward secret, as it is encrypted solely under 1077 keys derived using the offered PSK. 1079 2. There are no guarantees of non-replay between connections. 1080 Protection against replay for ordinary TLS 1.3 1-RTT data is 1081 provided via the server's Random value, but 0-RTT data does not 1082 depend on the ServerHello and therefore has weaker guarantees. 1083 This is especially relevant if the data is authenticated either 1084 with TLS client authentication or inside the application 1085 protocol. The same warnings apply to any use of the 1086 early_exporter_master_secret. 1088 0-RTT data cannot be duplicated within a connection (i.e., the server 1089 will not process the same data twice for the same connection) and an 1090 attacker will not be able to make 0-RTT data appear to be 1-RTT data 1091 (because it is protected with different keys.) Appendix E.5 contains 1092 a description of potential attacks and Section 8 describes mechanisms 1093 which the server can use to limit the impact of replay. 1095 3. Presentation Language 1097 This document deals with the formatting of data in an external 1098 representation. The following very basic and somewhat casually 1099 defined presentation syntax will be used. 1101 3.1. Basic Block Size 1103 The representation of all data items is explicitly specified. The 1104 basic data block size is one byte (i.e., 8 bits). Multiple byte data 1105 items are concatenations of bytes, from left to right, from top to 1106 bottom. From the byte stream, a multi-byte item (a numeric in the 1107 example) is formed (using C notation) by: 1109 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 1110 ... | byte[n-1]; 1112 This byte ordering for multi-byte values is the commonplace network 1113 byte order or big-endian format. 1115 3.2. Miscellaneous 1117 Comments begin with "/*" and end with "*/". 1119 Optional components are denoted by enclosing them in "[[ ]]" double 1120 brackets. 1122 Single-byte entities containing uninterpreted data are of type 1123 opaque. 1125 A type alias T' for an existing type T is defined by: 1127 T T'; 1129 3.3. Vectors 1131 A vector (single-dimensioned array) is a stream of homogeneous data 1132 elements. The size of the vector may be specified at documentation 1133 time or left unspecified until runtime. In either case, the length 1134 declares the number of bytes, not the number of elements, in the 1135 vector. The syntax for specifying a new type, T', that is a fixed- 1136 length vector of type T is 1138 T T'[n]; 1140 Here, T' occupies n bytes in the data stream, where n is a multiple 1141 of the size of T. The length of the vector is not included in the 1142 encoded stream. 1144 In the following example, Datum is defined to be three consecutive 1145 bytes that the protocol does not interpret, while Data is three 1146 consecutive Datum, consuming a total of nine bytes. 1148 opaque Datum[3]; /* three uninterpreted bytes */ 1149 Datum Data[9]; /* 3 consecutive 3-byte vectors */ 1151 Variable-length vectors are defined by specifying a subrange of legal 1152 lengths, inclusively, using the notation . When 1153 these are encoded, the actual length precedes the vector's contents 1154 in the byte stream. The length will be in the form of a number 1155 consuming as many bytes as required to hold the vector's specified 1156 maximum (ceiling) length. A variable-length vector with an actual 1157 length field of zero is referred to as an empty vector. 1159 T T'; 1161 In the following example, mandatory is a vector that must contain 1162 between 300 and 400 bytes of type opaque. It can never be empty. 1163 The actual length field consumes two bytes, a uint16, which is 1164 sufficient to represent the value 400 (see Section 3.4). Similarly, 1165 longer can represent up to 800 bytes of data, or 400 uint16 elements, 1166 and it may be empty. Its encoding will include a two-byte actual 1167 length field prepended to the vector. The length of an encoded 1168 vector must be an exact multiple of the length of a single element 1169 (e.g., a 17-byte vector of uint16 would be illegal). 1171 opaque mandatory<300..400>; 1172 /* length field is 2 bytes, cannot be empty */ 1173 uint16 longer<0..800>; 1174 /* zero to 400 16-bit unsigned integers */ 1176 3.4. Numbers 1178 The basic numeric data type is an unsigned byte (uint8). All larger 1179 numeric data types are formed from fixed-length series of bytes 1180 concatenated as described in Section 3.1 and are also unsigned. The 1181 following numeric types are predefined. 1183 uint8 uint16[2]; 1184 uint8 uint24[3]; 1185 uint8 uint32[4]; 1186 uint8 uint64[8]; 1188 All values, here and elsewhere in the specification, are stored in 1189 network byte (big-endian) order; the uint32 represented by the hex 1190 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 1192 3.5. Enumerateds 1194 An additional sparse data type is available called enum. Each 1195 definition is a different type. Only enumerateds of the same type 1196 may be assigned or compared. Every element of an enumerated must be 1197 assigned a value, as demonstrated in the following example. Since 1198 the elements of the enumerated are not ordered, they can be assigned 1199 any unique value, in any order. 1201 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 1203 Future extensions or additions to the protocol may define new values. 1204 Implementations need to be able to parse and ignore unknown values 1205 unless the definition of the field states otherwise. 1207 An enumerated occupies as much space in the byte stream as would its 1208 maximal defined ordinal value. The following definition would cause 1209 one byte to be used to carry fields of type Color. 1211 enum { red(3), blue(5), white(7) } Color; 1213 One may optionally specify a value without its associated tag to 1214 force the width definition without defining a superfluous element. 1216 In the following example, Taste will consume two bytes in the data 1217 stream but can only assume the values 1, 2, or 4 in the current 1218 version of the protocol. 1220 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 1222 The names of the elements of an enumeration are scoped within the 1223 defined type. In the first example, a fully qualified reference to 1224 the second element of the enumeration would be Color.blue. Such 1225 qualification is not required if the target of the assignment is well 1226 specified. 1228 Color color = Color.blue; /* overspecified, legal */ 1229 Color color = blue; /* correct, type implicit */ 1231 The names assigned to enumerateds do not need to be unique. The 1232 numerical value can describe a range over which the same name 1233 applies. The value includes the minimum and maximum inclusive values 1234 in that range, separated by two period characters. This is 1235 principally useful for reserving regions of the space. 1237 enum { sad(0), meh(1..254), happy(255) } Mood; 1239 3.6. Constructed Types 1241 Structure types may be constructed from primitive types for 1242 convenience. Each specification declares a new, unique type. The 1243 syntax for definition is much like that of C. 1245 struct { 1246 T1 f1; 1247 T2 f2; 1248 ... 1249 Tn fn; 1250 } T; 1252 Fixed- and variable-length vector fields are allowed using the 1253 standard vector syntax. Structures V1 and V2 in the variants example 1254 below demonstrate this. 1256 The fields within a structure may be qualified using the type's name, 1257 with a syntax much like that available for enumerateds. For example, 1258 T.f2 refers to the second field of the previous declaration. 1260 3.7. Constants 1262 Fields and variables may be assigned a fixed value using "=", as in: 1264 struct { 1265 T1 f1 = 8; /* T.f1 must always be 8 */ 1266 T2 f2; 1267 } T; 1269 3.8. Variants 1271 Defined structures may have variants based on some knowledge that is 1272 available within the environment. The selector must be an enumerated 1273 type that defines the possible variants the structure defines. Each 1274 arm of the select specifies the type of that variant's field and an 1275 optional field label. The mechanism by which the variant is selected 1276 at runtime is not prescribed by the presentation language. 1278 struct { 1279 T1 f1; 1280 T2 f2; 1281 .... 1282 Tn fn; 1283 select (E) { 1284 case e1: Te1 [[fe1]]; 1285 case e2: Te2 [[fe2]]; 1286 .... 1287 case en: Ten [[fen]]; 1288 }; 1289 } Tv; 1291 For example: 1293 enum { apple(0), orange(1) } VariantTag; 1295 struct { 1296 uint16 number; 1297 opaque string<0..10>; /* variable length */ 1298 } V1; 1300 struct { 1301 uint32 number; 1302 opaque string[10]; /* fixed length */ 1303 } V2; 1305 struct { 1306 VariantTag type; 1307 select (VariantRecord.type) { 1308 case apple: V1; 1309 case orange: V2; 1310 }; 1311 } VariantRecord; 1313 4. Handshake Protocol 1315 The handshake protocol is used to negotiate the security parameters 1316 of a connection. Handshake messages are supplied to the TLS record 1317 layer, where they are encapsulated within one or more TLSPlaintext or 1318 TLSCiphertext structures, which are processed and transmitted as 1319 specified by the current active connection state. 1321 enum { 1322 client_hello(1), 1323 server_hello(2), 1324 new_session_ticket(4), 1325 end_of_early_data(5), 1326 encrypted_extensions(8), 1327 certificate(11), 1328 certificate_request(13), 1329 certificate_verify(15), 1330 finished(20), 1331 key_update(24), 1332 message_hash(254), 1333 (255) 1334 } HandshakeType; 1336 struct { 1337 HandshakeType msg_type; /* handshake type */ 1338 uint24 length; /* bytes in message */ 1339 select (Handshake.msg_type) { 1340 case client_hello: ClientHello; 1341 case server_hello: ServerHello; 1342 case end_of_early_data: EndOfEarlyData; 1343 case encrypted_extensions: EncryptedExtensions; 1344 case certificate_request: CertificateRequest; 1345 case certificate: Certificate; 1346 case certificate_verify: CertificateVerify; 1347 case finished: Finished; 1348 case new_session_ticket: NewSessionTicket; 1349 case key_update: KeyUpdate; 1350 }; 1351 } Handshake; 1353 Protocol messages MUST be sent in the order defined in Section 4.4.1 1354 and shown in the diagrams in Section 2. A peer which receives a 1355 handshake message in an unexpected order MUST abort the handshake 1356 with an "unexpected_message" alert. 1358 New handshake message types are assigned by IANA as described in 1359 Section 11. 1361 4.1. Key Exchange Messages 1363 The key exchange messages are used to determine the security 1364 capabilities of the client and the server and to establish shared 1365 secrets including the traffic keys used to protect the rest of the 1366 handshake and the data. 1368 4.1.1. Cryptographic Negotiation 1370 In TLS, the cryptographic negotiation proceeds by the client offering 1371 the following four sets of options in its ClientHello: 1373 - A list of cipher suites which indicates the AEAD algorithm/HKDF 1374 hash pairs which the client supports. 1376 - A "supported_groups" (Section 4.2.7) extension which indicates the 1377 (EC)DHE groups which the client supports and a "key_share" 1378 (Section 4.2.8) extension which contains (EC)DHE shares for some 1379 or all of these groups. 1381 - A "signature_algorithms" (Section 4.2.3) extension which indicates 1382 the signature algorithms which the client can accept. 1384 - A "pre_shared_key" (Section 4.2.11) extension which contains a 1385 list of symmetric key identities known to the client and a 1386 "psk_key_exchange_modes" (Section 4.2.9) extension which indicates 1387 the key exchange modes that may be used with PSKs. 1389 If the server does not select a PSK, then the first three of these 1390 options are entirely orthogonal: the server independently selects a 1391 cipher suite, an (EC)DHE group and key share for key establishment, 1392 and a signature algorithm/certificate pair to authenticate itself to 1393 the client. If there is no overlap between the received 1394 "supported_groups" and the groups supported by the server then the 1395 server MUST abort the handshake with a "handshake_failure" or an 1396 "insufficient_security" alert. 1398 If the server selects a PSK, then it MUST also select a key 1399 establishment mode from the set indicated by client's 1400 "psk_key_exchange_modes" extension (at present, PSK alone or with 1401 (EC)DHE). Note that if the PSK can be used without (EC)DHE then non- 1402 overlap in the "supported_groups" parameters need not be fatal, as it 1403 is in the non-PSK case discussed in the previous paragraph. 1405 If the server selects an (EC)DHE group and the client did not offer a 1406 compatible "key_share" extension in the initial ClientHello, the 1407 server MUST respond with a HelloRetryRequest (Section 4.1.4) message. 1409 If the server successfully selects parameters and does not require a 1410 HelloRetryRequest, it indicates the selected parameters in the 1411 ServerHello as follows: 1413 - If PSK is being used, then the server will send a "pre_shared_key" 1414 extension indicating the selected key. 1416 - If PSK is not being used, then (EC)DHE and certificate-based 1417 authentication are always used. 1419 - When (EC)DHE is in use, the server will also provide a "key_share" 1420 extension. 1422 - When authenticating via a certificate, the server will send the 1423 Certificate (Section 4.4.2) and CertificateVerify (Section 4.4.3) 1424 messages. In TLS 1.3 as defined by this document, either a PSK or 1425 a certificate is always used, but not both. Future documents may 1426 define how to use them together. 1428 If the server is unable to negotiate a supported set of parameters 1429 (i.e., there is no overlap between the client and server parameters), 1430 it MUST abort the handshake with either a "handshake_failure" or 1431 "insufficient_security" fatal alert (see Section 6). 1433 4.1.2. Client Hello 1435 When a client first connects to a server, it is REQUIRED to send the 1436 ClientHello as its first message. The client will also send a 1437 ClientHello when the server has responded to its ClientHello with a 1438 HelloRetryRequest. In that case, the client MUST send the same 1439 ClientHello (without modification) except: 1441 - If a "key_share" extension was supplied in the HelloRetryRequest, 1442 replacing the list of shares with a list containing a single 1443 KeyShareEntry from the indicated group. 1445 - Removing the "early_data" extension (Section 4.2.10) if one was 1446 present. Early data is not permitted after HelloRetryRequest. 1448 - Including a "cookie" extension if one was provided in the 1449 HelloRetryRequest. 1451 - Updating the "pre_shared_key" extension if present by recomputing 1452 the "obfuscated_ticket_age" and binder values and (optionally) 1453 removing any PSKs which are incompatible with the server's 1454 indicated cipher suite. 1456 - Optionally adding, removing, or changing the length of the 1457 "padding" extension [RFC7685]. 1459 Because TLS 1.3 forbids renegotiation, if a server has negotiated TLS 1460 1.3 and receives a ClientHello at any other time, it MUST terminate 1461 the connection with an "unexpected_message" alert. 1463 If a server established a TLS connection with a previous version of 1464 TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST 1465 retain the previous protocol version. In particular, it MUST NOT 1466 negotiate TLS 1.3. 1468 Structure of this message: 1470 uint16 ProtocolVersion; 1471 opaque Random[32]; 1473 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1475 struct { 1476 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 1477 Random random; 1478 opaque legacy_session_id<0..32>; 1479 CipherSuite cipher_suites<2..2^16-2>; 1480 opaque legacy_compression_methods<1..2^8-1>; 1481 Extension extensions<8..2^16-1>; 1482 } ClientHello; 1484 legacy_version In previous versions of TLS, this field was used for 1485 version negotiation and represented the highest version number 1486 supported by the client. Experience has shown that many servers 1487 do not properly implement version negotiation, leading to "version 1488 intolerance" in which the server rejects an otherwise acceptable 1489 ClientHello with a version number higher than it supports. In TLS 1490 1.3, the client indicates its version preferences in the 1491 "supported_versions" extension (Section 4.2.1) and the 1492 legacy_version field MUST be set to 0x0303, which is the version 1493 number for TLS 1.2. (See Appendix D for details about backward 1494 compatibility.) 1496 random 32 bytes generated by a secure random number generator. See 1497 Appendix C for additional information. 1499 legacy_session_id Versions of TLS before TLS 1.3 supported a 1500 "session resumption" feature which has been merged with Pre-Shared 1501 Keys in this version (see Section 2.2). A client which has a 1502 cached session ID set by a pre-TLS 1.3 server SHOULD set this 1503 field to that value. In compatibility mode (see Appendix D.4) 1504 this field MUST be non-empty, so a client not offering a pre-TLS 1505 1.3 session MUST generate a new 32-byte value. This value need 1506 not be random but SHOULD be unpredictable to avoid ossification. 1507 Otherwise, it MUST be set as a zero length vector (i.e., a single 1508 zero byte length field). 1510 cipher_suites This is a list of the symmetric cipher options 1511 supported by the client, specifically the record protection 1512 algorithm (including secret key length) and a hash to be used with 1513 HKDF, in descending order of client preference. If the list 1514 contains cipher suites that the server does not recognize, support 1515 or wish to use, the server MUST ignore those cipher suites and 1516 process the remaining ones as usual. Values are defined in 1517 Appendix B.4. If the client is attempting a PSK key 1518 establishment, it SHOULD advertise at least one cipher suite 1519 indicating a Hash associated with the PSK. 1521 legacy_compression_methods Versions of TLS before 1.3 supported 1522 compression with the list of supported compression methods being 1523 sent in this field. For every TLS 1.3 ClientHello, this vector 1524 MUST contain exactly one byte set to zero, which corresponds to 1525 the "null" compression method in prior versions of TLS. If a TLS 1526 1.3 ClientHello is received with any other value in this field, 1527 the server MUST abort the handshake with an "illegal_parameter" 1528 alert. Note that TLS 1.3 servers might receive TLS 1.2 or prior 1529 ClientHellos which contain other compression methods and MUST 1530 follow the procedures for the appropriate prior version of TLS. 1531 TLS 1.3 ClientHellos are identified as having a legacy_version of 1532 0x0303 and a supported_versions extension present with 0x0304 as 1533 the highest version indicated therein. 1535 extensions Clients request extended functionality from servers by 1536 sending data in the extensions field. The actual "Extension" 1537 format is defined in Section 4.2. In TLS 1.3, use of certain 1538 extensions is mandatory, as functionality is moved into extensions 1539 to preserve ClientHello compatibility with previous versions of 1540 TLS. Servers MUST ignore unrecognized extensions. 1542 All versions of TLS allow an extensions field to optionally follow 1543 the compression_methods field. TLS 1.3 ClientHello messages always 1544 contain extensions (minimally "supported_versions", otherwise they 1545 will be interpreted as TLS 1.2 ClientHello messages). However, TLS 1546 1.3 servers might receive ClientHello messages without an extensions 1547 field from prior versions of TLS. The presence of extensions can be 1548 detected by determining whether there are bytes following the 1549 compression_methods field at the end of the ClientHello. Note that 1550 this method of detecting optional data differs from the normal TLS 1551 method of having a variable-length field, but it is used for 1552 compatibility with TLS before extensions were defined. TLS 1.3 1553 servers will need to perform this check first and only attempt to 1554 negotiate TLS 1.3 if a "supported_version" extension is present. If 1555 negotiating a version of TLS prior to 1.3, a server MUST check that 1556 the message either contains no data after legacy_compression_methods 1557 or that it contains a valid extensions block with no data following. 1558 If not, then it MUST abort the handshake with a "decode_error" alert. 1560 In the event that a client requests additional functionality using 1561 extensions, and this functionality is not supplied by the server, the 1562 client MAY abort the handshake. 1564 After sending the ClientHello message, the client waits for a 1565 ServerHello or HelloRetryRequest message. If early data is in use, 1566 the client may transmit early application data (Section 2.3) while 1567 waiting for the next handshake message. 1569 4.1.3. Server Hello 1571 The server will send this message in response to a ClientHello 1572 message to proceed with the handshake if it is able to negotiate an 1573 acceptable set of handshake parameters based on the ClientHello. 1575 Structure of this message: 1577 struct { 1578 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 1579 Random random; 1580 opaque legacy_session_id_echo<0..32>; 1581 CipherSuite cipher_suite; 1582 uint8 legacy_compression_method = 0; 1583 Extension extensions<6..2^16-1>; 1584 } ServerHello; 1586 version In previous versions of TLS, this field was used for version 1587 negotiation and represented the selected version number for the 1588 connection. Unfortunately, some middleboxes fail when presented 1589 with new values. In TLS 1.3, the TLS server indicates its version 1590 using the "supported_versions" extension (Section 4.2.1), and the 1591 legacy_version field MUST be set to 0x0303, which is the version 1592 number for TLS 1.2. (See Appendix D for details about backward 1593 compatibility.) 1595 random 32 bytes generated by a secure random number generator. See 1596 Appendix C for additional information. The last eight bytes MUST 1597 be overwritten as described below if negotiating TLS 1.2 or TLS 1598 1.1, but the remaining bytes MUST be random. This structure is 1599 generated by the server and MUST be generated independently of the 1600 ClientHello.random. 1602 legacy_session_id_echo The contents of the client's 1603 legacy_session_id field. Note that this field is echoed even if 1604 the client's value corresponded to a cached pre-TLS 1.3 session 1605 which the server has chosen not to resume. A client which 1606 receives a legacy_session_id field that does not match what it 1607 sent in the ClientHello MUST abort the handshake with an 1608 "illegal_parameter" alert. 1610 cipher_suite The single cipher suite selected by the server from the 1611 list in ClientHello.cipher_suites. A client which receives a 1612 cipher suite that was not offered MUST abort the handshake with an 1613 "illegal_parameter" alert. 1615 legacy_compression_method A single byte which MUST have the value 0. 1617 extensions A list of extensions. The ServerHello MUST only include 1618 extensions which are required to establish the cryptographic 1619 context. Currently the only such extensions are "key_share" and 1620 "pre_shared_key". All current TLS 1.3 ServerHello messages will 1621 contain one of these two extensions, or both when using a PSK with 1622 (EC)DHE key establishment. The remaining extensions are sent 1623 separately in the EncryptedExtensions message. 1625 For backward compatibility reasons with middleboxes (see 1626 Appendix D.4) the HelloRetryRequest message uses the same structure 1627 as the ServerHello, but with Random set to the special value of the 1628 SHA-256 of "HelloRetryRequest": 1630 CF 21 AD 74 E5 9A 61 11 BE 1D 8C 02 1E 65 B8 91 1631 C2 A2 11 16 7A BB 8C 5E 07 9E 09 E2 C8 A8 33 9C 1633 Upon receiving a message with type server_hello, implementations MUST 1634 first examine the Random value and if it matches this value, process 1635 it as described in Section 4.1.4). 1637 TLS 1.3 has a downgrade protection mechanism embedded in the server's 1638 random value. TLS 1.3 servers which negotiate TLS 1.2 or below in 1639 response to a ClientHello MUST set the last eight bytes of their 1640 Random value specially. 1642 If negotiating TLS 1.2, TLS 1.3 servers MUST set the last eight bytes 1643 of their Random value to the bytes: 1645 44 4F 57 4E 47 52 44 01 1647 If negotiating TLS 1.1 or below, TLS 1.3 servers MUST and TLS 1.2 1648 servers SHOULD set the last eight bytes of their Random value to the 1649 bytes: 1651 44 4F 57 4E 47 52 44 00 1653 TLS 1.3 clients receiving a ServerHello indicating TLS 1.2 or below 1654 MUST check that the last eight bytes are not equal to either of these 1655 values. TLS 1.2 clients SHOULD also check that the last eight bytes 1656 are not equal to the second value if the ServerHello indicates TLS 1657 1.1 or below. If a match is found, the client MUST abort the 1658 handshake with an "illegal_parameter" alert. This mechanism provides 1659 limited protection against downgrade attacks over and above what is 1660 provided by the Finished exchange: because the ServerKeyExchange, a 1661 message present in TLS 1.2 and below, includes a signature over both 1662 random values, it is not possible for an active attacker to modify 1663 the random values without detection as long as ephemeral ciphers are 1664 used. It does not provide downgrade protection when static RSA is 1665 used. 1667 Note: This is a change from [RFC5246], so in practice many TLS 1.2 1668 clients and servers will not behave as specified above. 1670 A legacy TLS client performing renegotiation with TLS 1.2 or prior 1671 and which receives a TLS 1.3 ServerHello during renegotiation MUST 1672 abort the handshake with a "protocol_version" alert. Note that 1673 renegotiation is not possible when TLS 1.3 has been negotiated. 1675 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH Implementations of 1676 draft versions (see Section 4.2.1.1) of this specification SHOULD NOT 1677 implement this mechanism on either client and server. A pre-RFC 1678 client connecting to RFC servers, or vice versa, will appear to 1679 downgrade to TLS 1.2. With the mechanism enabled, this will cause an 1680 interoperability failure. 1682 4.1.4. Hello Retry Request 1684 The server will send this message in response to a ClientHello 1685 message if it is able to find an acceptable set of parameters but the 1686 ClientHello does not contain sufficient information to proceed with 1687 the handshake. As discussed in Section 4.1.3, the HelloRetryRequest 1688 has the same format as a ServerHello message, and the legacy_version, 1689 legacy_session_id_echo, cipher_suite, and legacy_compression methods 1690 fields have the same meaning. However, for convenience we discuss 1691 HelloRetryRequest throughout this document as if it were a distinct 1692 message. 1694 The server's extensions MUST contain "supported_versions" and 1695 otherwise the server SHOULD send only the extensions necessary for 1696 the client to generate a correct ClientHello pair. As with 1697 ServerHello, a HelloRetryRequest MUST NOT contain any extensions that 1698 were not first offered by the client in its ClientHello, with the 1699 exception of optionally the "cookie" (see Section 4.2.2) extension. 1701 Upon receipt of a HelloRetryRequest, the client MUST perform the 1702 checks specified in Section 4.1.3 and then process the extensions, 1703 starting with determining the version using "supported_versions". 1704 Clients MUST abort the handshake with an "illegal_parameter" alert if 1705 the HelloRetryRequest would not result in any change in the 1706 ClientHello. If a client receives a second HelloRetryRequest in the 1707 same connection (i.e., where the ClientHello was itself in response 1708 to a HelloRetryRequest), it MUST abort the handshake with an 1709 "unexpected_message" alert. 1711 Otherwise, the client MUST process all extensions in the 1712 HelloRetryRequest and send a second updated ClientHello. The 1713 HelloRetryRequest extensions defined in this specification are: 1715 - supported_versions (see Section 4.2.1) 1717 - cookie (see Section 4.2.2) 1719 - key_share (see Section 4.2.8) 1721 In addition, in its updated ClientHello, the client SHOULD NOT offer 1722 any pre-shared keys associated with a hash other than that of the 1723 selected cipher suite. This allows the client to avoid having to 1724 compute partial hash transcripts for multiple hashes in the second 1725 ClientHello. A client which receives a cipher suite that was not 1726 offered MUST abort the handshake. Servers MUST ensure that they 1727 negotiate the same cipher suite when receiving a conformant updated 1728 ClientHello (if the server selects the cipher suite as the first step 1729 in the negotiation, then this will happen automatically). Upon 1730 receiving the ServerHello, clients MUST check that the cipher suite 1731 supplied in the ServerHello is the same as that in the 1732 HelloRetryRequest and otherwise abort the handshake with an 1733 "illegal_parameter" alert. 1735 4.2. Extensions 1737 A number of TLS messages contain tag-length-value encoded extensions 1738 structures. 1740 struct { 1741 ExtensionType extension_type; 1742 opaque extension_data<0..2^16-1>; 1743 } Extension; 1745 enum { 1746 server_name(0), /* RFC 6066 */ 1747 max_fragment_length(1), /* RFC 6066 */ 1748 status_request(5), /* RFC 6066 */ 1749 supported_groups(10), /* RFC 4492, 7919 */ 1750 signature_algorithms(13), /* [[this document]] */ 1751 use_srtp(14), /* RFC 5764 */ 1752 heartbeat(15), /* RFC 6520 */ 1753 application_layer_protocol_negotiation(16), /* RFC 7301 */ 1754 signed_certificate_timestamp(18), /* RFC 6962 */ 1755 client_certificate_type(19), /* RFC 7250 */ 1756 server_certificate_type(20), /* RFC 7250 */ 1757 padding(21), /* RFC 7685 */ 1758 key_share(40), /* [[this document]] */ 1759 pre_shared_key(41), /* [[this document]] */ 1760 early_data(42), /* [[this document]] */ 1761 supported_versions(43), /* [[this document]] */ 1762 cookie(44), /* [[this document]] */ 1763 psk_key_exchange_modes(45), /* [[this document]] */ 1764 certificate_authorities(47), /* [[this document]] */ 1765 oid_filters(48), /* [[this document]] */ 1766 post_handshake_auth(49), /* [[this document]] */ 1767 (65535) 1768 } ExtensionType; 1770 Here: 1772 - "extension_type" identifies the particular extension type. 1774 - "extension_data" contains information specific to the particular 1775 extension type. 1777 The list of extension types is maintained by IANA as described in 1778 Section 11. 1780 Extensions are generally structured in a request/response fashion, 1781 though some extensions are just indications with no corresponding 1782 response. The client sends its extension requests in the ClientHello 1783 message and the server sends its extension responses in the 1784 ServerHello, EncryptedExtensions, HelloRetryRequest and Certificate 1785 messages. The server sends extension requests in the 1786 CertificateRequest message which a client MAY respond to with a 1787 Certificate message. The server MAY also send unsolicited extensions 1788 in the NewSessionTicket, though the client does not respond directly 1789 to these. 1791 Implementations MUST NOT send extension responses if the remote 1792 endpoint did not send the corresponding extension requests, with the 1793 exception of the "cookie" extension in HelloRetryRequest. Upon 1794 receiving such an extension, an endpoint MUST abort the handshake 1795 with an "unsupported_extension" alert. 1797 The table below indicates the messages where a given extension may 1798 appear, using the following notation: CH (ClientHello), SH 1799 (ServerHello), EE (EncryptedExtensions), CT (Certificate), CR 1800 (CertificateRequest), NST (NewSessionTicket) and HRR 1801 (HelloRetryRequest). If an implementation receives an extension 1802 which it recognizes and which is not specified for the message in 1803 which it appears it MUST abort the handshake with an 1804 "illegal_parameter" alert. 1806 +--------------------------------------------------+-------------+ 1807 | Extension | TLS 1.3 | 1808 +--------------------------------------------------+-------------+ 1809 | server_name [RFC6066] | CH, EE | 1810 | | | 1811 | max_fragment_length [RFC6066] | CH, EE | 1812 | | | 1813 | status_request [RFC6066] | CH, CR, CT | 1814 | | | 1815 | supported_groups [RFC7919] | CH, EE | 1816 | | | 1817 | signature_algorithms [RFC5246] | CH, CR | 1818 | | | 1819 | use_srtp [RFC5764] | CH, EE | 1820 | | | 1821 | heartbeat [RFC6520] | CH, EE | 1822 | | | 1823 | application_layer_protocol_negotiation [RFC7301] | CH, EE | 1824 | | | 1825 | signed_certificate_timestamp [RFC6962] | CH, CR, CT | 1826 | | | 1827 | client_certificate_type [RFC7250] | CH, EE | 1828 | | | 1829 | server_certificate_type [RFC7250] | CH, EE | 1830 | | | 1831 | padding [RFC7685] | CH | 1832 | | | 1833 | key_share [[this document]] | CH, SH, HRR | 1834 | | | 1835 | pre_shared_key [[this document]] | CH, SH | 1836 | | | 1837 | psk_key_exchange_modes [[this document]] | CH | 1838 | | | 1839 | early_data [[this document]] | CH, EE, NST | 1840 | | | 1841 | cookie [[this document]] | CH, HRR | 1842 | | | 1843 | supported_versions [[this document]] | CH, SH, HRR | 1844 | | | 1845 | certificate_authorities [[this document]] | CH, CR | 1846 | | | 1847 | oid_filters [[this document]] | CR | 1848 | | | 1849 | post_handshake_auth [[this document]] | CH | 1850 +--------------------------------------------------+-------------+ 1852 When multiple extensions of different types are present, the 1853 extensions MAY appear in any order, with the exception of 1854 "pre_shared_key" Section 4.2.11 which MUST be the last extension in 1855 the ClientHello. There MUST NOT be more than one extension of the 1856 same type in a given extension block. 1858 In TLS 1.3, unlike TLS 1.2, extensions are negotiated for each 1859 handshake even when in resumption-PSK mode. However, 0-RTT 1860 parameters are those negotiated in the previous handshake; mismatches 1861 may require rejecting 0-RTT (see Section 4.2.10). 1863 There are subtle (and not so subtle) interactions that may occur in 1864 this protocol between new features and existing features which may 1865 result in a significant reduction in overall security. The following 1866 considerations should be taken into account when designing new 1867 extensions: 1869 - Some cases where a server does not agree to an extension are error 1870 conditions, and some are simply refusals to support particular 1871 features. In general, error alerts should be used for the former 1872 and a field in the server extension response for the latter. 1874 - Extensions should, as far as possible, be designed to prevent any 1875 attack that forces use (or non-use) of a particular feature by 1876 manipulation of handshake messages. This principle should be 1877 followed regardless of whether the feature is believed to cause a 1878 security problem. Often the fact that the extension fields are 1879 included in the inputs to the Finished message hashes will be 1880 sufficient, but extreme care is needed when the extension changes 1881 the meaning of messages sent in the handshake phase. Designers 1882 and implementors should be aware of the fact that until the 1883 handshake has been authenticated, active attackers can modify 1884 messages and insert, remove, or replace extensions. 1886 4.2.1. Supported Versions 1888 struct { 1889 select (Handshake.msg_type) { 1890 case client_hello: 1891 ProtocolVersion versions<2..254>; 1893 case server_hello: 1894 ProtocolVersion selected_version; 1895 }; 1896 } SupportedVersions; 1898 The "supported_versions" extension is used by the client to indicate 1899 which versions of TLS it supports and by the server to indicate which 1900 version it is using. The extension contains a list of supported 1901 versions in preference order, with the most preferred version first. 1903 Implementations of this specification MUST send this extension 1904 containing all versions of TLS which they are prepared to negotiate 1905 (for this specification, that means minimally 0x0304, but if previous 1906 versions of TLS are allowed to be negotiated, they MUST be present as 1907 well). 1909 If this extension is not present, servers which are compliant with 1910 this specification MUST negotiate TLS 1.2 or prior as specified in 1911 [RFC5246], even if ClientHello.legacy_version is 0x0304 or later. 1912 Servers MAY abort the handshake upon receiving a ClientHello with 1913 legacy_version 0x0304 or later. 1915 If this extension is present, servers MUST ignore the 1916 ClientHello.legacy_version value and MUST use only the 1917 "supported_versions" extension to determine client preferences. 1918 Servers MUST only select a version of TLS present in that extension 1919 and MUST ignore any unknown versions that are present in that 1920 extension. Note that this mechanism makes it possible to negotiate a 1921 version prior to TLS 1.2 if one side supports a sparse range. 1922 Implementations of TLS 1.3 which choose to support prior versions of 1923 TLS SHOULD support TLS 1.2. Servers should be prepared to receive 1924 ClientHellos that include this extension but do not include 0x0304 in 1925 the list of versions. 1927 A server which negotiates TLS 1.3 MUST respond by sending a 1928 "supported_versions" extension containing the selected version value 1929 (0x0304). It MUST set the ServerHello.legacy_version field to 0x0303 1930 (TLS 1.2). Clients MUST check for this extension prior to processing 1931 the rest of the ServerHello (although they will have to parse the 1932 ServerHello in order to read the extension). If this extension is 1933 present, clients MUST ignore the ServerHello.legacy_version value and 1934 MUST use only the "supported_versions" extension to determine client 1935 preferences. If the "supported_versions" extension contains a 1936 version not offered by the client, the client MUST abort the 1937 handshake with an "illegal_parameter" alert. 1939 4.2.1.1. Draft Version Indicator 1941 RFC EDITOR: PLEASE REMOVE THIS SECTION 1943 While the eventual version indicator for the RFC version of TLS 1.3 1944 will be 0x0304, implementations of draft versions of this 1945 specification SHOULD instead advertise 0x7f00 | draft_version in 1946 ServerHello.version, and HelloRetryRequest.server_version. For 1947 instance, draft-17 would be encoded as the 0x7f11. This allows pre- 1948 RFC implementations to safely negotiate with each other, even if they 1949 would otherwise be incompatible. 1951 4.2.2. Cookie 1953 struct { 1954 opaque cookie<1..2^16-1>; 1955 } Cookie; 1957 Cookies serve two primary purposes: 1959 - Allowing the server to force the client to demonstrate 1960 reachability at their apparent network address (thus providing a 1961 measure of DoS protection). This is primarily useful for non- 1962 connection-oriented transports (see [RFC6347] for an example of 1963 this). 1965 - Allowing the server to offload state to the client, thus allowing 1966 it to send a HelloRetryRequest without storing any state. The 1967 server can do this by storing the hash of the ClientHello in the 1968 HelloRetryRequest cookie (protected with some suitable integrity 1969 algorithm). 1971 When sending a HelloRetryRequest, the server MAY provide a "cookie" 1972 extension to the client (this is an exception to the usual rule that 1973 the only extensions that may be sent are those that appear in the 1974 ClientHello). When sending the new ClientHello, the client MUST copy 1975 the contents of the extension received in the HelloRetryRequest into 1976 a "cookie" extension in the new ClientHello. Clients MUST NOT use 1977 cookies in their initial ClientHello in subsequent connections. 1979 4.2.3. Signature Algorithms 1981 The client uses the "signature_algorithms" extension to indicate to 1982 the server which signature algorithms may be used in digital 1983 signatures. Clients which desire the server to authenticate itself 1984 via a certificate MUST send this extension. If a server is 1985 authenticating via a certificate and the client has not sent a 1986 "signature_algorithms" extension, then the server MUST abort the 1987 handshake with a "missing_extension" alert (see Section 9.2). 1989 The "extension_data" field of this extension in a ClientHello 1990 contains a SignatureSchemeList value: 1992 enum { 1993 /* RSASSA-PKCS1-v1_5 algorithms */ 1994 rsa_pkcs1_sha256(0x0401), 1995 rsa_pkcs1_sha384(0x0501), 1996 rsa_pkcs1_sha512(0x0601), 1998 /* ECDSA algorithms */ 1999 ecdsa_secp256r1_sha256(0x0403), 2000 ecdsa_secp384r1_sha384(0x0503), 2001 ecdsa_secp521r1_sha512(0x0603), 2003 /* RSASSA-PSS algorithms */ 2004 rsa_pss_sha256(0x0804), 2005 rsa_pss_sha384(0x0805), 2006 rsa_pss_sha512(0x0806), 2008 /* EdDSA algorithms */ 2009 ed25519(0x0807), 2010 ed448(0x0808), 2012 /* Legacy algorithms */ 2013 rsa_pkcs1_sha1(0x0201), 2014 ecdsa_sha1(0x0203), 2016 /* Reserved Code Points */ 2017 private_use(0xFE00..0xFFFF), 2018 (0xFFFF) 2019 } SignatureScheme; 2021 struct { 2022 SignatureScheme supported_signature_algorithms<2..2^16-2>; 2023 } SignatureSchemeList; 2025 Note: This enum is named "SignatureScheme" because there is already a 2026 "SignatureAlgorithm" type in TLS 1.2, which this replaces. We use 2027 the term "signature algorithm" throughout the text. 2029 Each SignatureScheme value lists a single signature algorithm that 2030 the client is willing to verify. The values are indicated in 2031 descending order of preference. Note that a signature algorithm 2032 takes as input an arbitrary-length message, rather than a digest. 2033 Algorithms which traditionally act on a digest should be defined in 2034 TLS to first hash the input with a specified hash algorithm and then 2035 proceed as usual. The code point groups listed above have the 2036 following meanings: 2038 RSASSA-PKCS1-v1_5 algorithms Indicates a signature algorithm using 2039 RSASSA-PKCS1-v1_5 [RFC8017] with the corresponding hash algorithm 2040 as defined in [SHS]. These values refer solely to signatures 2041 which appear in certificates (see Section 4.4.2.2) and are not 2042 defined for use in signed TLS handshake messages. 2044 ECDSA algorithms Indicates a signature algorithm using ECDSA 2045 [ECDSA], the corresponding curve as defined in ANSI X9.62 [X962] 2046 and FIPS 186-4 [DSS], and the corresponding hash algorithm as 2047 defined in [SHS]. The signature is represented as a DER-encoded 2048 [X690] ECDSA-Sig-Value structure. 2050 RSASSA-PSS algorithms Indicates a signature algorithm using RSASSA- 2051 PSS [RFC8017] with mask generation function 1. The digest used in 2052 the mask generation function and the digest being signed are both 2053 the corresponding hash algorithm as defined in [SHS]. When used 2054 in signed TLS handshake messages, the length of the salt MUST be 2055 equal to the length of the digest output. This codepoint is new 2056 in this document and is also defined for use with TLS 1.2. 2058 EdDSA algorithms Indicates a signature algorithm using EdDSA as 2059 defined in [RFC8032] or its successors. Note that these 2060 correspond to the "PureEdDSA" algorithms and not the "prehash" 2061 variants. 2063 Legacy algorithms Indicates algorithms which are being deprecated 2064 because they use algorithms with known weaknesses, specifically 2065 SHA-1 which is used in this context with either with RSA using 2066 RSASSA-PKCS1-v1_5 or ECDSA. These values refer solely to 2067 signatures which appear in certificates (see Section 4.4.2.2) and 2068 are not defined for use in signed TLS handshake messages. 2069 Endpoints SHOULD NOT negotiate these algorithms but are permitted 2070 to do so solely for backward compatibility. Clients offering 2071 these values MUST list them as the lowest priority (listed after 2072 all other algorithms in SignatureSchemeList). TLS 1.3 servers 2073 MUST NOT offer a SHA-1 signed certificate unless no valid 2074 certificate chain can be produced without it (see 2075 Section 4.4.2.2). 2077 The signatures on certificates that are self-signed or certificates 2078 that are trust anchors are not validated since they begin a 2079 certification path (see [RFC5280], Section 3.2). A certificate that 2080 begins a certification path MAY use a signature algorithm that is not 2081 advertised as being supported in the "signature_algorithms" 2082 extension. 2084 Note that TLS 1.2 defines this extension differently. TLS 1.3 2085 implementations willing to negotiate TLS 1.2 MUST behave in 2086 accordance with the requirements of [RFC5246] when negotiating that 2087 version. In particular: 2089 - TLS 1.2 ClientHellos MAY omit this extension. 2091 - In TLS 1.2, the extension contained hash/signature pairs. The 2092 pairs are encoded in two octets, so SignatureScheme values have 2093 been allocated to align with TLS 1.2's encoding. Some legacy 2094 pairs are left unallocated. These algorithms are deprecated as of 2095 TLS 1.3. They MUST NOT be offered or negotiated by any 2096 implementation. In particular, MD5 [SLOTH], SHA-224, and DSA MUST 2097 NOT be used. 2099 - ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature 2100 pairs. However, the old semantics did not constrain the signing 2101 curve. If TLS 1.2 is negotiated, implementations MUST be prepared 2102 to accept a signature that uses any curve that they advertised in 2103 the "supported_groups" extension. 2105 - Implementations that advertise support for RSASSA-PSS (which is 2106 mandatory in TLS 1.3), MUST be prepared to accept a signature 2107 using that scheme even when TLS 1.2 is negotiated. In TLS 1.2, 2108 RSASSA-PSS is used with RSA cipher suites. 2110 4.2.4. Certificate Authorities 2112 The "certificate_authorities" extension is used to indicate the 2113 certificate authorities which an endpoint supports and which SHOULD 2114 be used by the receiving endpoint to guide certificate selection. 2116 The body of the "certificate_authorities" extension consists of a 2117 CertificateAuthoritiesExtension structure. 2119 opaque DistinguishedName<1..2^16-1>; 2121 struct { 2122 DistinguishedName authorities<3..2^16-1>; 2123 } CertificateAuthoritiesExtension; 2125 authorities A list of the distinguished names [X501] of acceptable 2126 certificate authorities, represented in DER-encoded [X690] format. 2127 These distinguished names specify a desired distinguished name for 2128 trust anchor or subordinate CA; thus, this message can be used to 2129 describe known trust anchors as well as a desired authorization 2130 space. 2132 The client MAY send the "certificate_authorities" extension in the 2133 ClientHello message. The server MAY send it in the 2134 CertificateRequest message. 2136 The "trusted_ca_keys" extension, which serves a similar purpose 2137 [RFC6066], but is more complicated, is not used in TLS 1.3 (although 2138 it may appear in ClientHello messages from clients which are offering 2139 prior versions of TLS). 2141 4.2.5. OID Filters 2143 The "oid_filters" extension allows servers to provide a set of OID/ 2144 value pairs which it would like the client's certificate to match. 2145 This extension, if provided by the server, MUST only be sent in the 2146 CertificateRequest message. 2148 struct { 2149 opaque certificate_extension_oid<1..2^8-1>; 2150 opaque certificate_extension_values<0..2^16-1>; 2151 } OIDFilter; 2153 struct { 2154 OIDFilter filters<0..2^16-1>; 2155 } OIDFilterExtension; 2157 filters A list of certificate extension OIDs [RFC5280] with their 2158 allowed values and represented in DER-encoded [X690] format. Some 2159 certificate extension OIDs allow multiple values (e.g., Extended 2160 Key Usage). If the server has included a non-empty filters list, 2161 the client certificate included in the response MUST contain all 2162 of the specified extension OIDs that the client recognizes. For 2163 each extension OID recognized by the client, all of the specified 2164 values MUST be present in the client certificate (but the 2165 certificate MAY have other values as well). However, the client 2166 MUST ignore and skip any unrecognized certificate extension OIDs. 2167 If the client ignored some of the required certificate extension 2168 OIDs and supplied a certificate that does not satisfy the request, 2169 the server MAY at its discretion either continue the connection 2170 without client authentication, or abort the handshake with an 2171 "unsupported_certificate" alert. 2173 PKIX RFCs define a variety of certificate extension OIDs and their 2174 corresponding value types. Depending on the type, matching 2175 certificate extension values are not necessarily bitwise-equal. It 2176 is expected that TLS implementations will rely on their PKI libraries 2177 to perform certificate selection using certificate extension OIDs. 2179 This document defines matching rules for two standard certificate 2180 extensions defined in [RFC5280]: 2182 - The Key Usage extension in a certificate matches the request when 2183 all key usage bits asserted in the request are also asserted in 2184 the Key Usage certificate extension. 2186 - The Extended Key Usage extension in a certificate matches the 2187 request when all key purpose OIDs present in the request are also 2188 found in the Extended Key Usage certificate extension. The 2189 special anyExtendedKeyUsage OID MUST NOT be used in the request. 2191 Separate specifications may define matching rules for other 2192 certificate extensions. 2194 4.2.6. Post-Handshake Client Authentication 2196 The "post_handshake_auth" extension is used to indicate that a client 2197 is willing to perform post-handshake authentication Section 4.6.2. 2198 Servers MUST NOT send a post-handshake CertificateRequest to clients 2199 which do not offer this extension. Servers MUST NOT send this 2200 extension. 2202 struct {} PostHandshakeAuth; 2204 The "extension_data" field of the "post_handshake_auth" extension is 2205 zero length. 2207 4.2.7. Negotiated Groups 2209 When sent by the client, the "supported_groups" extension indicates 2210 the named groups which the client supports for key exchange, ordered 2211 from most preferred to least preferred. 2213 Note: In versions of TLS prior to TLS 1.3, this extension was named 2214 "elliptic_curves" and only contained elliptic curve groups. See 2215 [RFC4492] and [RFC7919]. This extension was also used to negotiate 2216 ECDSA curves. Signature algorithms are now negotiated independently 2217 (see Section 4.2.3). 2219 The "extension_data" field of this extension contains a 2220 "NamedGroupList" value: 2222 enum { 2224 /* Elliptic Curve Groups (ECDHE) */ 2225 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 2226 x25519(0x001D), x448(0x001E), 2228 /* Finite Field Groups (DHE) */ 2229 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102), 2230 ffdhe6144(0x0103), ffdhe8192(0x0104), 2232 /* Reserved Code Points */ 2233 ffdhe_private_use(0x01FC..0x01FF), 2234 ecdhe_private_use(0xFE00..0xFEFF), 2235 (0xFFFF) 2236 } NamedGroup; 2238 struct { 2239 NamedGroup named_group_list<2..2^16-1>; 2240 } NamedGroupList; 2242 Elliptic Curve Groups (ECDHE) Indicates support for the 2243 corresponding named curve, defined either in FIPS 186-4 [DSS] or 2244 in [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for 2245 private use. 2247 Finite Field Groups (DHE) Indicates support of the corresponding 2248 finite field group, defined in [RFC7919]. Values 0x01FC through 2249 0x01FF are reserved for private use. 2251 Items in named_group_list are ordered according to the client's 2252 preferences (most preferred choice first). 2254 As of TLS 1.3, servers are permitted to send the "supported_groups" 2255 extension to the client. Clients MUST NOT act upon any information 2256 found in "supported_groups" prior to successful completion of the 2257 handshake but MAY use the information learned from a successfully 2258 completed handshake to change what groups they use in their 2259 "key_share" extension in subsequent connections. If the server has a 2260 group it prefers to the ones in the "key_share" extension but is 2261 still willing to accept the ClientHello, it SHOULD send 2262 "supported_groups" to update the client's view of its preferences; 2263 this extension SHOULD contain all groups the server supports, 2264 regardless of whether they are currently supported by the client. 2266 4.2.8. Key Share 2268 The "key_share" extension contains the endpoint's cryptographic 2269 parameters. 2271 Clients MAY send an empty client_shares vector in order to request 2272 group selection from the server at the cost of an additional round 2273 trip. (see Section 4.1.4) 2275 struct { 2276 NamedGroup group; 2277 opaque key_exchange<1..2^16-1>; 2278 } KeyShareEntry; 2280 group The named group for the key being exchanged. Finite Field 2281 Diffie-Hellman [DH] parameters are described in Section 4.2.8.1; 2282 Elliptic Curve Diffie-Hellman parameters are described in 2283 Section 4.2.8.2. 2285 key_exchange Key exchange information. The contents of this field 2286 are determined by the specified group and its corresponding 2287 definition. 2289 In the ClientHello message, the "extension_data" field of this 2290 extension contains a "KeyShareClientHello" value: 2292 struct { 2293 KeyShareEntry client_shares<0..2^16-1>; 2294 } KeyShareClientHello; 2296 client_shares A list of offered KeyShareEntry values in descending 2297 order of client preference. 2299 This vector MAY be empty if the client is requesting a 2300 HelloRetryRequest. Each KeyShareEntry value MUST correspond to a 2301 group offered in the "supported_groups" extension and MUST appear in 2302 the same order. However, the values MAY be a non-contiguous subset 2303 of the "supported_groups" extension and MAY omit the most preferred 2304 groups. Such a situation could arise if the most preferred groups 2305 are new and unlikely to be supported in enough places to make 2306 pregenerating key shares for them efficient. 2308 Clients can offer an arbitrary number of KeyShareEntry values, each 2309 representing a single set of key exchange parameters. For instance, 2310 a client might offer shares for several elliptic curves or multiple 2311 FFDHE groups. The key_exchange values for each KeyShareEntry MUST be 2312 generated independently. Clients MUST NOT offer multiple 2313 KeyShareEntry values for the same group. Clients MUST NOT offer any 2314 KeyShareEntry values for groups not listed in the client's 2315 "supported_groups" extension. Servers MAY check for violations of 2316 these rules and abort the handshake with an "illegal_parameter" alert 2317 if one is violated. 2319 In a HelloRetryRequest message, the "extension_data" field of this 2320 extension contains a KeyShareHelloRetryRequest value: 2322 struct { 2323 NamedGroup selected_group; 2324 } KeyShareHelloRetryRequest; 2326 selected_group The mutually supported group the server intends to 2327 negotiate and is requesting a retried ClientHello/KeyShare for. 2329 Upon receipt of this extension in a HelloRetryRequest, the client 2330 MUST verify that (1) the selected_group field corresponds to a group 2331 which was provided in the "supported_groups" extension in the 2332 original ClientHello; and (2) the selected_group field does not 2333 correspond to a group which was provided in the "key_share" extension 2334 in the original ClientHello. If either of these checks fails, then 2335 the client MUST abort the handshake with an "illegal_parameter" 2336 alert. Otherwise, when sending the new ClientHello, the client MUST 2337 replace the original "key_share" extension with one containing only a 2338 new KeyShareEntry for the group indicated in the selected_group field 2339 of the triggering HelloRetryRequest. 2341 In a ServerHello message, the "extension_data" field of this 2342 extension contains a KeyShareServerHello value: 2344 struct { 2345 KeyShareEntry server_share; 2346 } KeyShareServerHello; 2348 server_share A single KeyShareEntry value that is in the same group 2349 as one of the client's shares. 2351 If using (EC)DHE key establishment, servers offer exactly one 2352 KeyShareEntry in the ServerHello. This value MUST be in the same 2353 group as the KeyShareEntry value offered by the client that the 2354 server has selected for the negotiated key exchange. Servers MUST 2355 NOT send a KeyShareEntry for any group not indicated in the 2356 "supported_groups" extension and MUST NOT send a KeyShareEntry when 2357 using the "psk_ke" PskKeyExchangeMode. If a HelloRetryRequest was 2358 received by the client, the client MUST verify that the selected 2359 NamedGroup in the ServerHello is the same as that in the 2360 HelloRetryRequest. If this check fails, the client MUST abort the 2361 handshake with an "illegal_parameter" alert. 2363 4.2.8.1. Diffie-Hellman Parameters 2365 Diffie-Hellman [DH] parameters for both clients and servers are 2366 encoded in the opaque key_exchange field of a KeyShareEntry in a 2367 KeyShare structure. The opaque value contains the Diffie-Hellman 2368 public value (Y = g^X mod p) for the specified group (see [RFC7919] 2369 for group definitions) encoded as a big-endian integer and padded to 2370 the left with zeros to the size of p in bytes. 2372 Note: For a given Diffie-Hellman group, the padding results in all 2373 public keys having the same length. 2375 Peers MUST validate each other's public key Y by ensuring that 1 < Y 2376 < p-1. This check ensures that the remote peer is properly behaved 2377 and isn't forcing the local system into a small subgroup. 2379 4.2.8.2. ECDHE Parameters 2381 ECDHE parameters for both clients and servers are encoded in the the 2382 opaque key_exchange field of a KeyShareEntry in a KeyShare structure. 2384 For secp256r1, secp384r1 and secp521r1, the contents are the 2385 serialized value of the following struct: 2387 struct { 2388 uint8 legacy_form = 4; 2389 opaque X[coordinate_length]; 2390 opaque Y[coordinate_length]; 2391 } UncompressedPointRepresentation; 2393 X and Y respectively are the binary representations of the X and Y 2394 values in network byte order. There are no internal length markers, 2395 so each number representation occupies as many octets as implied by 2396 the curve parameters. For P-256 this means that each of X and Y use 2397 32 octets, padded on the left by zeros if necessary. For P-384 they 2398 take 48 octets each, and for P-521 they take 66 octets each. 2400 For the curves secp256r1, secp384r1 and secp521r1, peers MUST 2401 validate each other's public value Y by ensuring that the point is a 2402 valid point on the elliptic curve. The appropriate validation 2403 procedures are defined in Section 4.3.7 of [X962] and alternatively 2404 in Section 5.6.2.3 of [KEYAGREEMENT]. This process consists of three 2405 steps: (1) verify that Y is not the point at infinity (O), (2) verify 2406 that for Y = (x, y) both integers are in the correct interval, (3) 2407 ensure that (x, y) is a correct solution to the elliptic curve 2408 equation. For these curves, implementers do not need to verify 2409 membership in the correct subgroup. 2411 For X25519 and X448, the contents of the public value are the byte 2412 string inputs and outputs of the corresponding functions defined in 2413 [RFC7748], 32 bytes for X25519 and 56 bytes for X448. 2415 Note: Versions of TLS prior to 1.3 permitted point format 2416 negotiation; TLS 1.3 removes this feature in favor of a single point 2417 format for each curve. 2419 4.2.9. Pre-Shared Key Exchange Modes 2421 In order to use PSKs, clients MUST also send a 2422 "psk_key_exchange_modes" extension. The semantics of this extension 2423 are that the client only supports the use of PSKs with these modes, 2424 which restricts both the use of PSKs offered in this ClientHello and 2425 those which the server might supply via NewSessionTicket. 2427 A client MUST provide a "psk_key_exchange_modes" extension if it 2428 offers a "pre_shared_key" extension. If clients offer 2429 "pre_shared_key" without a "psk_key_exchange_modes" extension, 2430 servers MUST abort the handshake. Servers MUST NOT select a key 2431 exchange mode that is not listed by the client. This extension also 2432 restricts the modes for use with PSK resumption; servers SHOULD NOT 2433 send NewSessionTicket with tickets that are not compatible with the 2434 advertised modes; however, if a server does so, the impact will just 2435 be that the client's attempts at resumption fail. 2437 The server MUST NOT send a "psk_key_exchange_modes" extension. 2439 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 2441 struct { 2442 PskKeyExchangeMode ke_modes<1..255>; 2443 } PskKeyExchangeModes; 2445 psk_ke PSK-only key establishment. In this mode, the server MUST 2446 NOT supply a "key_share" value. 2448 psk_dhe_ke PSK with (EC)DHE key establishment. In this mode, the 2449 client and servers MUST supply "key_share" values as described in 2450 Section 4.2.8. 2452 4.2.10. Early Data Indication 2454 When a PSK is used, the client can send application data in its first 2455 flight of messages. If the client opts to do so, it MUST supply both 2456 the "early_data" extension as well as the "pre_shared_key" extension. 2458 The "extension_data" field of this extension contains an 2459 "EarlyDataIndication" value. 2461 struct {} Empty; 2463 struct { 2464 select (Handshake.msg_type) { 2465 case new_session_ticket: uint32 max_early_data_size; 2466 case client_hello: Empty; 2467 case encrypted_extensions: Empty; 2468 }; 2469 } EarlyDataIndication; 2471 See Section 4.6.1 for the use of the max_early_data_size field. 2473 The parameters for the 0-RTT data (version, symmetric cipher suite, 2474 ALPN protocol, etc.) are those associated with the PSK in use. For 2475 externally established PSKs, the associated values are those 2476 provisioned along with the key. For PSKs established via a 2477 NewSessionTicket message, the associated values are those which were 2478 negotiated in the connection which established the PSK. The PSK used 2479 to encrypt the early data MUST be the first PSK listed in the 2480 client's "pre_shared_key" extension. 2482 For PSKs provisioned via NewSessionTicket, a server MUST validate 2483 that the ticket age for the selected PSK identity (computed by 2484 subtracting ticket_age_add from PskIdentity.obfuscated_ticket_age 2485 modulo 2^32) is within a small tolerance of the time since the ticket 2486 was issued (see Section 8). If it is not, the server SHOULD proceed 2487 with the handshake but reject 0-RTT, and SHOULD NOT take any other 2488 action that assumes that this ClientHello is fresh. 2490 0-RTT messages sent in the first flight have the same (encrypted) 2491 content types as their corresponding messages sent in other flights 2492 (handshake and application_data) but are protected under different 2493 keys. After receiving the server's Finished message, if the server 2494 has accepted early data, an EndOfEarlyData message will be sent to 2495 indicate the key change. This message will be encrypted with the 2496 0-RTT traffic keys. 2498 A server which receives an "early_data" extension MUST behave in one 2499 of three ways: 2501 - Ignore the extension and return a regular 1-RTT response. The 2502 server then ignores early data by attempting to decrypt received 2503 records in the handshake traffic keys until it is able to receive 2504 the client's second flight and complete an ordinary 1-RTT 2505 handshake, skipping records that fail to decrypt, up to the 2506 configured max_early_data_size. 2508 - Request that the client send another ClientHello by responding 2509 with a HelloRetryRequest. A client MUST NOT include the 2510 "early_data" extension in its followup ClientHello. The server 2511 then ignores early data by skipping all records with external 2512 content type of "application_data" (indicating that they are 2513 encrypted). 2515 - Return its own extension in EncryptedExtensions, indicating that 2516 it intends to process the early data. It is not possible for the 2517 server to accept only a subset of the early data messages. Even 2518 though the server sends a message accepting early data, the actual 2519 early data itself may already be in flight by the time the server 2520 generates this message. 2522 In order to accept early data, the server MUST have accepted a PSK 2523 cipher suite and selected the first key offered in the client's 2524 "pre_shared_key" extension. In addition, it MUST verify that the 2525 following values are consistent with those associated with the 2526 selected PSK: 2528 - The TLS version number 2530 - The selected cipher suite 2532 - The selected ALPN [RFC7301] protocol, if any 2534 These requirements are a superset of those needed to perform a 1-RTT 2535 handshake using the PSK in question. For externally established 2536 PSKs, the associated values are those provisioned along with the key. 2537 For PSKs established via a NewSessionTicket message, the associated 2538 values are those negotiated in the connection during which the ticket 2539 was established. 2541 Future extensions MUST define their interaction with 0-RTT. 2543 If any of these checks fail, the server MUST NOT respond with the 2544 extension and must discard all the first flight data using one of the 2545 first two mechanisms listed above (thus falling back to 1-RTT or 2546 2-RTT). If the client attempts a 0-RTT handshake but the server 2547 rejects it, the server will generally not have the 0-RTT record 2548 protection keys and must instead use trial decryption (either with 2549 the 1-RTT handshake keys or by looking for a cleartext ClientHello in 2550 the case of HelloRetryRequest) to find the first non-0-RTT message. 2552 If the server chooses to accept the "early_data" extension, then it 2553 MUST comply with the same error handling requirements specified for 2554 all records when processing early data records. Specifically, if the 2555 server fails to decrypt any 0-RTT record following an accepted 2556 "early_data" extension it MUST terminate the connection with a 2557 "bad_record_mac" alert as per Section 5.2. 2559 If the server rejects the "early_data" extension, the client 2560 application MAY opt to retransmit early data once the handshake has 2561 been completed. Note that automatic re-transmission of early data 2562 could result in assumptions about the status of the connection being 2563 incorrect. For instance, when the negotiated connection selects a 2564 different ALPN protocol from what was used for the early data, an 2565 application might need to construct different messages. Similarly, 2566 if early data assumes anything about the connection state, it might 2567 be sent in error after the handshake completes. 2569 A TLS implementation SHOULD NOT automatically re-send early data; 2570 applications are in a better position to decide when re-transmission 2571 is appropriate. A TLS implementation MUST NOT automatically re-send 2572 early data unless the negotiated connection selects the same ALPN 2573 protocol. 2575 4.2.11. Pre-Shared Key Extension 2577 The "pre_shared_key" extension is used to indicate the identity of 2578 the pre-shared key to be used with a given handshake in association 2579 with PSK key establishment. 2581 The "extension_data" field of this extension contains a 2582 "PreSharedKeyExtension" value: 2584 struct { 2585 opaque identity<1..2^16-1>; 2586 uint32 obfuscated_ticket_age; 2587 } PskIdentity; 2589 opaque PskBinderEntry<32..255>; 2591 struct { 2592 PskIdentity identities<7..2^16-1>; 2593 PskBinderEntry binders<33..2^16-1>; 2594 } OfferedPsks; 2596 struct { 2597 select (Handshake.msg_type) { 2598 case client_hello: OfferedPsks; 2599 case server_hello: uint16 selected_identity; 2600 }; 2601 } PreSharedKeyExtension; 2603 identity A label for a key. For instance, a ticket defined in 2604 Appendix B.3.4 or a label for a pre-shared key established 2605 externally. 2607 obfuscated_ticket_age An obfuscated version of the age of the key. 2608 Section 4.2.11.1 describes how to form this value for identities 2609 established via the NewSessionTicket message. For identities 2610 established externally an obfuscated_ticket_age of 0 SHOULD be 2611 used, and servers MUST ignore the value. 2613 identities A list of the identities that the client is willing to 2614 negotiate with the server. If sent alongside the "early_data" 2615 extension (see Section 4.2.10), the first identity is the one used 2616 for 0-RTT data. 2618 binders A series of HMAC values, one for each PSK offered in the 2619 "pre_shared_keys" extension and in the same order, computed as 2620 described below. 2622 selected_identity The server's chosen identity expressed as a 2623 (0-based) index into the identities in the client's list. 2625 Each PSK is associated with a single Hash algorithm. For PSKs 2626 established via the ticket mechanism (Section 4.6.1), this is the KDF 2627 Hash algorithm on the connection where the ticket was established. 2628 For externally established PSKs, the Hash algorithm MUST be set when 2629 the PSK is established, or default to SHA-256 if no such algorithm is 2630 defined. The server MUST ensure that it selects a compatible PSK (if 2631 any) and cipher suite. 2633 In TLS versions prior to TLS 1.3, the Server Name Identification 2634 (SNI) value was intended to be associated with the session (Section 3 2635 of [RFC6066]), with the server being required to enforce that the SNI 2636 value associated with the session matches the one specified in the 2637 resumption handshake. However, in reality the implementations were 2638 not consistent on which of two supplied SNI values they would use, 2639 leading to the consistency requirement being de-facto enforced by the 2640 clients. In TLS 1.3, the SNI value is always explicitly specified in 2641 the resumption handshake, and there is no need for the server to 2642 associate an SNI value with the ticket. Clients, however, SHOULD 2643 store the SNI with the PSK to fulfill the requirements of 2644 Section 4.6.1. 2646 Implementor's note: the most straightforward way to implement the 2647 PSK/cipher suite matching requirements is to negotiate the cipher 2648 suite first and then exclude any incompatible PSKs. Any unknown PSKs 2649 (e.g., they are not in the PSK database or are encrypted with an 2650 unknown key) SHOULD simply be ignored. If no acceptable PSKs are 2651 found, the server SHOULD perform a non-PSK handshake if possible. 2653 Prior to accepting PSK key establishment, the server MUST validate 2654 the corresponding binder value (see Section 4.2.11.2 below). If this 2655 value is not present or does not validate, the server MUST abort the 2656 handshake. Servers SHOULD NOT attempt to validate multiple binders; 2657 rather they SHOULD select a single PSK and validate solely the binder 2658 that corresponds to that PSK. In order to accept PSK key 2659 establishment, the server sends a "pre_shared_key" extension 2660 indicating the selected identity. 2662 Clients MUST verify that the server's selected_identity is within the 2663 range supplied by the client, that the server selected a cipher suite 2664 indicating a Hash associated with the PSK and that a server 2665 "key_share" extension is present if required by the ClientHello 2666 "psk_key_exchange_modes". If these values are not consistent the 2667 client MUST abort the handshake with an "illegal_parameter" alert. 2669 If the server supplies an "early_data" extension, the client MUST 2670 verify that the server's selected_identity is 0. If any other value 2671 is returned, the client MUST abort the handshake with an 2672 "illegal_parameter" alert. 2674 This extension MUST be the last extension in the ClientHello (this 2675 facilitates implementation as described below). Servers MUST check 2676 that it is the last extension and otherwise fail the handshake with 2677 an "illegal_parameter" alert. 2679 4.2.11.1. Ticket Age 2681 The client's view of the age of a ticket is the time since the 2682 receipt of the NewSessionTicket message. Clients MUST NOT attempt to 2683 use tickets which have ages greater than the "ticket_lifetime" value 2684 which was provided with the ticket. The "obfuscated_ticket_age" 2685 field of each PskIdentity contains an obfuscated version of the 2686 ticket age formed by taking the age in milliseconds and adding the 2687 "ticket_age_add" value that was included with the ticket, see 2688 Section 4.6.1 modulo 2^32. This addition prevents passive observers 2689 from correlating connections unless tickets are reused. Note that 2690 the "ticket_lifetime" field in the NewSessionTicket message is in 2691 seconds but the "obfuscated_ticket_age" is in milliseconds. Because 2692 ticket lifetimes are restricted to a week, 32 bits is enough to 2693 represent any plausible age, even in milliseconds. 2695 4.2.11.2. PSK Binder 2697 The PSK binder value forms a binding between a PSK and the current 2698 handshake, as well as between the handshake in which the PSK was 2699 generated (if via a NewSessionTicket message) and the handshake where 2700 it was used. Each entry in the binders list is computed as an HMAC 2701 over a transcript hash (see Section 4.4.1) containing a partial 2702 ClientHello up to and including the PreSharedKeyExtension.identities 2703 field. That is, it includes all of the ClientHello but not the 2704 binders list itself. The length fields for the message (including 2705 the overall length, the length of the extensions block, and the 2706 length of the "pre_shared_key" extension) are all set as if binders 2707 of the correct lengths were present. 2709 The PskBinderEntry is computed in the same way as the Finished 2710 message (Section 4.4.4) but with the BaseKey being the binder_key 2711 derived via the key schedule from the corresponding PSK which is 2712 being offered (see Section 7.1). 2714 If the handshake includes a HelloRetryRequest, the initial 2715 ClientHello and HelloRetryRequest are included in the transcript 2716 along with the new ClientHello. For instance, if the client sends 2717 ClientHello1, its binder will be computed over: 2719 Transcript-Hash(Truncate(ClientHello1)) 2721 Where Truncate() removes the binders list from the ClientHello. 2723 If the server responds with HelloRetryRequest, and the client then 2724 sends ClientHello2, its binder will be computed over: 2726 Transcript-Hash(ClientHello1, 2727 HelloRetryRequest, 2728 Truncate(ClientHello2)) 2730 The full ClientHello1/ClientHello2 is included in all other handshake 2731 hash computations. Note that in the first flight, 2732 Truncate(ClientHello1) is hashed directly, but in the second flight, 2733 ClientHello1 is hashed and then reinjected as a "message_hash" 2734 message, as described in Section 4.4.1. 2736 4.2.11.3. Processing Order 2738 Clients are permitted to "stream" 0-RTT data until they receive the 2739 server's Finished, only then sending the EndOfEarlyData message, 2740 followed by the rest of the handshake. In order to avoid deadlocks, 2741 when accepting "early_data", servers MUST process the client's 2742 ClientHello and then immediately send the ServerHello, rather than 2743 waiting for the client's EndOfEarlyData message. 2745 4.3. Server Parameters 2747 The next two messages from the server, EncryptedExtensions and 2748 CertificateRequest, contain information from the server that 2749 determines the rest of the handshake. These messages are encrypted 2750 with keys derived from the server_handshake_traffic_secret. 2752 4.3.1. Encrypted Extensions 2754 In all handshakes, the server MUST send the EncryptedExtensions 2755 message immediately after the ServerHello message. This is the first 2756 message that is encrypted under keys derived from the 2757 server_handshake_traffic_secret. 2759 The EncryptedExtensions message contains extensions that can be 2760 protected, i.e., any which are not needed to establish the 2761 cryptographic context, but which are not associated with individual 2762 certificates. The client MUST check EncryptedExtensions for the 2763 presence of any forbidden extensions and if any are found MUST abort 2764 the handshake with an "illegal_parameter" alert. 2766 Structure of this message: 2768 struct { 2769 Extension extensions<0..2^16-1>; 2770 } EncryptedExtensions; 2772 extensions A list of extensions. For more information, see the 2773 table in Section 4.2. 2775 4.3.2. Certificate Request 2777 A server which is authenticating with a certificate MAY optionally 2778 request a certificate from the client. This message, if sent, MUST 2779 follow EncryptedExtensions. 2781 Structure of this message: 2783 struct { 2784 opaque certificate_request_context<0..2^8-1>; 2785 Extension extensions<2..2^16-1>; 2786 } CertificateRequest; 2788 certificate_request_context An opaque string which identifies the 2789 certificate request and which will be echoed in the client's 2790 Certificate message. The certificate_request_context MUST be 2791 unique within the scope of this connection (thus preventing replay 2792 of client CertificateVerify messages). This field SHALL be zero 2793 length unless used for the post-handshake authentication exchanges 2794 described in Section 4.6.2. When requesting post-handshake 2795 authentication, the server SHOULD make the context unpredictable 2796 to the client (e.g., by randomly generating it) in order to 2797 prevent an attacker who has temporary access to the client's 2798 private key from pre-computing valid CertificateVerify messages. 2800 extensions A set of extensions describing the parameters of the 2801 certificate being requested. The "signature_algorithms" extension 2802 MUST be specified, and other extensions may optionally be included 2803 if defined for this message. Clients MUST ignore unrecognized 2804 extensions. 2806 In prior versions of TLS, the CertificateRequest message carried a 2807 list of signature algorithms and certificate authorities which the 2808 server would accept. In TLS 1.3 the former is expressed by sending 2809 the "signature_algorithms" extension. The latter is expressed by 2810 sending the "certificate_authorities" extension (see Section 4.2.4). 2812 Servers which are authenticating with a PSK MUST NOT send the 2813 CertificateRequest message in the main handshake, though they MAY 2814 send it in post-handshake authentication (see Section 4.6.2) provided 2815 that the client has sent the "post_handshake_auth" extension (see 2816 Section 4.2.6). 2818 4.4. Authentication Messages 2820 As discussed in Section 2, TLS generally uses a common set of 2821 messages for authentication, key confirmation, and handshake 2822 integrity: Certificate, CertificateVerify, and Finished. (The 2823 PreSharedKey binders also perform key confirmation, in a similar 2824 fashion.) These three messages are always sent as the last messages 2825 in their handshake flight. The Certificate and CertificateVerify 2826 messages are only sent under certain circumstances, as defined below. 2827 The Finished message is always sent as part of the Authentication 2828 block. These messages are encrypted under keys derived from 2829 [sender]_handshake_traffic_secret. 2831 The computations for the Authentication messages all uniformly take 2832 the following inputs: 2834 - The certificate and signing key to be used. 2836 - A Handshake Context consisting of the set of messages to be 2837 included in the transcript hash. 2839 - A base key to be used to compute a MAC key. 2841 Based on these inputs, the messages then contain: 2843 Certificate The certificate to be used for authentication, and any 2844 supporting certificates in the chain. Note that certificate-based 2845 client authentication is not available in 0-RTT mode. 2847 CertificateVerify A signature over the value Transcript- 2848 Hash(Handshake Context, Certificate) 2850 Finished A MAC over the value Transcript-Hash(Handshake Context, 2851 Certificate, CertificateVerify) using a MAC key derived from the 2852 base key. 2854 The following table defines the Handshake Context and MAC Base Key 2855 for each scenario: 2857 +-----------+----------------------------+--------------------------+ 2858 | Mode | Handshake Context | Base Key | 2859 +-----------+----------------------------+--------------------------+ 2860 | Server | ClientHello ... later of E | server_handshake_traffic | 2861 | | ncryptedExtensions/Certifi | _secret | 2862 | | cateRequest | | 2863 | | | | 2864 | Client | ClientHello ... later of | client_handshake_traffic | 2865 | | server | _secret | 2866 | | Finished/EndOfEarlyData | | 2867 | | | | 2868 | Post- | ClientHello ... client | client_application_traff | 2869 | Handshake | Finished + | ic_secret_N | 2870 | | CertificateRequest | | 2871 +-----------+----------------------------+--------------------------+ 2873 4.4.1. The Transcript Hash 2875 Many of the cryptographic computations in TLS make use of a 2876 transcript hash. This value is computed by hashing the concatenation 2877 of each included handshake message, including the handshake message 2878 header carrying the handshake message type and length fields, but not 2879 including record layer headers. I.e., 2881 Transcript-Hash(M1, M2, ... MN) = Hash(M1 || M2 ... MN) 2883 As an exception to this general rule, when the server responds to a 2884 ClientHello with a HelloRetryRequest, the value of ClientHello1 is 2885 replaced with a special synthetic handshake message of handshake type 2886 "message_hash" containing Hash(ClientHello1). I.e., 2888 Transcript-Hash(ClientHello1, HelloRetryRequest, ... MN) = 2889 Hash(message_hash || /* Handshake type */ 2890 00 00 Hash.length || /* Handshake message length (bytes) */ 2891 Hash(ClientHello1) || /* Hash of ClientHello1 */ 2892 HelloRetryRequest ... MN) 2894 The reason for this construction is to allow the server to do a 2895 stateless HelloRetryRequest by storing just the hash of ClientHello1 2896 in the cookie, rather than requiring it to export the entire 2897 intermediate hash state (see Section 4.2.2). 2899 For concreteness, the transcript hash is always taken from the 2900 following sequence of handshake messages, starting at the first 2901 ClientHello and including only those messages that were sent: 2902 ClientHello, HelloRetryRequest, ClientHello, ServerHello, 2903 EncryptedExtensions, server CertificateRequest, server Certificate, 2904 server CertificateVerify, server Finished, EndOfEarlyData, client 2905 Certificate, client CertificateVerify, client Finished. 2907 In general, implementations can implement the transcript by keeping a 2908 running transcript hash value based on the negotiated hash. Note, 2909 however, that subsequent post-handshake authentications do not 2910 include each other, just the messages through the end of the main 2911 handshake. 2913 4.4.2. Certificate 2915 This message conveys the endpoint's certificate chain to the peer. 2917 The server MUST send a Certificate message whenever the agreed-upon 2918 key exchange method uses certificates for authentication (this 2919 includes all key exchange methods defined in this document except 2920 PSK). 2922 The client MUST send a Certificate message if and only if the server 2923 has requested client authentication via a CertificateRequest message 2924 (Section 4.3.2). If the server requests client authentication but no 2925 suitable certificate is available, the client MUST send a Certificate 2926 message containing no certificates (i.e., with the "certificate_list" 2927 field having length 0). 2929 Structure of this message: 2931 enum { 2932 X509(0), 2933 RawPublicKey(2), 2934 (255) 2935 } CertificateType; 2937 struct { 2938 select (certificate_type) { 2939 case RawPublicKey: 2940 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */ 2941 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 2943 case X509: 2944 opaque cert_data<1..2^24-1>; 2945 }; 2946 Extension extensions<0..2^16-1>; 2947 } CertificateEntry; 2949 struct { 2950 opaque certificate_request_context<0..2^8-1>; 2951 CertificateEntry certificate_list<0..2^24-1>; 2952 } Certificate; 2954 certificate_request_context If this message is in response to a 2955 CertificateRequest, the value of certificate_request_context in 2956 that message. Otherwise (in the case of server authentication), 2957 this field SHALL be zero length. 2959 certificate_list This is a sequence (chain) of CertificateEntry 2960 structures, each containing a single certificate and set of 2961 extensions. 2963 extensions: A set of extension values for the CertificateEntry. The 2964 "Extension" format is defined in Section 4.2. Valid extensions 2965 include OCSP Status extension ([RFC6066]) and 2966 SignedCertificateTimestamps ([RFC6962]). An extension MUST only 2967 be present in a Certificate message if the corresponding 2968 ClientHello extension was presented in the initial handshake. If 2969 an extension applies to the entire chain, it SHOULD be included in 2970 the first CertificateEntry. 2972 If the corresponding certificate type extension 2973 ("server_certificate_type" or "client_certificate_type") was not 2974 negotiated in Encrypted Extensions, or the X.509 certificate type was 2975 negotiated, then each CertificateEntry contains an X.509 certificate. 2976 The sender's certificate MUST come in the first CertificateEntry in 2977 the list. Each following certificate SHOULD directly certify one 2978 preceding it. Because certificate validation requires that trust 2979 anchors be distributed independently, a certificate that specifies a 2980 trust anchor MAY be omitted from the chain, provided that supported 2981 peers are known to possess any omitted certificates. 2983 Note: Prior to TLS 1.3, "certificate_list" ordering required each 2984 certificate to certify the one immediately preceding it; however, 2985 some implementations allowed some flexibility. Servers sometimes 2986 send both a current and deprecated intermediate for transitional 2987 purposes, and others are simply configured incorrectly, but these 2988 cases can nonetheless be validated properly. For maximum 2989 compatibility, all implementations SHOULD be prepared to handle 2990 potentially extraneous certificates and arbitrary orderings from any 2991 TLS version, with the exception of the end-entity certificate which 2992 MUST be first. 2994 If the RawPublicKey certificate type was negotiated, then the 2995 certificate_list MUST contain no more than one CertificateEntry, 2996 which contains an ASN1_subjectPublicKeyInfo value as defined in 2997 [RFC7250], Section 3. 2999 The OpenPGP certificate type [RFC6091] MUST NOT be used with TLS 1.3. 3001 The server's certificate_list MUST always be non-empty. A client 3002 will send an empty certificate_list if it does not have an 3003 appropriate certificate to send in response to the server's 3004 authentication request. 3006 4.4.2.1. OCSP Status and SCT Extensions 3008 [RFC6066] and [RFC6961] provide extensions to negotiate the server 3009 sending OCSP responses to the client. In TLS 1.2 and below, the 3010 server replies with an empty extension to indicate negotiation of 3011 this extension and the OCSP information is carried in a 3012 CertificateStatus message. In TLS 1.3, the server's OCSP information 3013 is carried in an extension in the CertificateEntry containing the 3014 associated certificate. Specifically: The body of the 3015 "status_request" extension from the server MUST be a 3016 CertificateStatus structure as defined in [RFC6066], which is 3017 interpreted as defined in [RFC6960]. 3019 Note: status_request_v2 extension ([RFC6961]) is deprecated. TLS 1.3 3020 servers MUST NOT act upon its presence or information in it when 3021 processing Client Hello, in particular they MUST NOT send the 3022 status_request_v2 extension in the Encrypted Extensions, Certificate 3023 Request or the Certificate messages. TLS 1.3 servers MUST be able to 3024 process Client Hello messages that include it, as it MAY be sent by 3025 clients that wish to use it in earlier protocol versions. 3027 A server MAY request that a client present an OCSP response with its 3028 certificate by sending an empty "status_request" extension in its 3029 CertificateRequest message. If the client opts to send an OCSP 3030 response, the body of its "status_request" extension MUST be a 3031 CertificateStatus structure as defined in [RFC6066]. 3033 Similarly, [RFC6962] provides a mechanism for a server to send a 3034 Signed Certificate Timestamp (SCT) as an extension in the ServerHello 3035 in TLS 1.2 and below. In TLS 1.3, the server's SCT information is 3036 carried in an extension in CertificateEntry. 3038 4.4.2.2. Server Certificate Selection 3040 The following rules apply to the certificates sent by the server: 3042 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 3043 negotiated otherwise (e.g., [RFC7250]). 3045 - The server's end-entity certificate's public key (and associated 3046 restrictions) MUST be compatible with the selected authentication 3047 algorithm (currently RSA, ECDSA, or EdDSA). 3049 - The certificate MUST allow the key to be used for signing (i.e., 3050 the digitalSignature bit MUST be set if the Key Usage extension is 3051 present) with a signature scheme indicated in the client's 3052 "signature_algorithms" extension. 3054 - The "server_name" [RFC6066] and "certificate_authorities" 3055 extensions are used to guide certificate selection. As servers 3056 MAY require the presence of the "server_name" extension, clients 3057 SHOULD send this extension, when applicable. 3059 All certificates provided by the server MUST be signed by a signature 3060 algorithm that appears in the "signature_algorithms" extension 3061 provided by the client, if they are able to provide such a chain (see 3062 Section 4.2.3). Certificates that are self-signed or certificates 3063 that are expected to be trust anchors are not validated as part of 3064 the chain and therefore MAY be signed with any algorithm. 3066 If the server cannot produce a certificate chain that is signed only 3067 via the indicated supported algorithms, then it SHOULD continue the 3068 handshake by sending the client a certificate chain of its choice 3069 that may include algorithms that are not known to be supported by the 3070 client. This fallback chain SHOULD NOT use the deprecated SHA-1 hash 3071 algorithm in general, but MAY do so if the "signature_algorithms" 3072 extension provided by the client permits it, and MUST NOT do so 3073 otherwise. 3075 If the client cannot construct an acceptable chain using the provided 3076 certificates and decides to abort the handshake, then it MUST abort 3077 the handshake with an appropriate certificate-related alert (by 3078 default, "unsupported_certificate"; see Section 6.2 for more). 3080 If the server has multiple certificates, it chooses one of them based 3081 on the above-mentioned criteria (in addition to other criteria, such 3082 as transport layer endpoint, local configuration and preferences). 3084 4.4.2.3. Client Certificate Selection 3086 The following rules apply to certificates sent by the client: 3088 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 3089 negotiated otherwise (e.g., [RFC7250]). 3091 - If the "certificate_authorities" extension in the 3092 CertificateRequest message was present, at least one of the 3093 certificates in the certificate chain SHOULD be issued by one of 3094 the listed CAs. 3096 - The certificates MUST be signed using an acceptable signature 3097 algorithm, as described in Section 4.3.2. Note that this relaxes 3098 the constraints on certificate-signing algorithms found in prior 3099 versions of TLS. 3101 - If the CertificateRequest message contained a non-empty 3102 "oid_filters" extension, the end-entity certificate MUST match the 3103 extension OIDs recognized by the client, as described in 3104 Section 4.2.5. 3106 Note that, as with the server certificate, there are certificates 3107 that use algorithm combinations that cannot be currently used with 3108 TLS. 3110 4.4.2.4. Receiving a Certificate Message 3112 In general, detailed certificate validation procedures are out of 3113 scope for TLS (see [RFC5280]). This section provides TLS-specific 3114 requirements. 3116 If the server supplies an empty Certificate message, the client MUST 3117 abort the handshake with a "decode_error" alert. 3119 If the client does not send any certificates, the server MAY at its 3120 discretion either continue the handshake without client 3121 authentication, or abort the handshake with a "certificate_required" 3122 alert. Also, if some aspect of the certificate chain was 3123 unacceptable (e.g., it was not signed by a known, trusted CA), the 3124 server MAY at its discretion either continue the handshake 3125 (considering the client unauthenticated) or abort the handshake. 3127 Any endpoint receiving any certificate which it would need to 3128 validate using any signature algorithm using an MD5 hash MUST abort 3129 the handshake with a "bad_certificate" alert. SHA-1 is deprecated 3130 and it is RECOMMENDED that any endpoint receiving any certificate 3131 which it would need to validate using any signature algorithm using a 3132 SHA-1 hash abort the handshake with a "bad_certificate" alert. For 3133 clarity, this means that endpoints MAY accept these algorithms for 3134 certificates that are self-signed or are trust anchors. 3136 All endpoints are RECOMMENDED to transition to SHA-256 or better as 3137 soon as possible to maintain interoperability with implementations 3138 currently in the process of phasing out SHA-1 support. 3140 Note that a certificate containing a key for one signature algorithm 3141 MAY be signed using a different signature algorithm (for instance, an 3142 RSA key signed with an ECDSA key). 3144 4.4.3. Certificate Verify 3146 This message is used to provide explicit proof that an endpoint 3147 possesses the private key corresponding to its certificate. The 3148 CertificateVerify message also provides integrity for the handshake 3149 up to this point. Servers MUST send this message when authenticating 3150 via a certificate. Clients MUST send this message whenever 3151 authenticating via a certificate (i.e., when the Certificate message 3152 is non-empty). When sent, this message MUST appear immediately after 3153 the Certificate message and immediately prior to the Finished 3154 message. 3156 Structure of this message: 3158 struct { 3159 SignatureScheme algorithm; 3160 opaque signature<0..2^16-1>; 3161 } CertificateVerify; 3163 The algorithm field specifies the signature algorithm used (see 3164 Section 4.2.3 for the definition of this field). The signature is a 3165 digital signature using that algorithm. The content that is covered 3166 under the signature is the hash output as described in Section 4.4, 3167 namely: 3169 Transcript-Hash(Handshake Context, Certificate) 3171 The digital signature is then computed over the concatenation of: 3173 - A string that consists of octet 32 (0x20) repeated 64 times 3175 - The context string 3177 - A single 0 byte which serves as the separator 3179 - The content to be signed 3181 This structure is intended to prevent an attack on previous versions 3182 of TLS in which the ServerKeyExchange format meant that attackers 3183 could obtain a signature of a message with a chosen 32-byte prefix 3184 (ClientHello.random). The initial 64-byte pad clears that prefix 3185 along with the server-controlled ServerHello.random. 3187 The context string for a server signature is "TLS 1.3, server 3188 CertificateVerify" and for a client signature is "TLS 1.3, client 3189 CertificateVerify". It is used to provide separation between 3190 signatures made in different contexts, helping against potential 3191 cross-protocol attacks. 3193 For example, if the transcript hash was 32 bytes of 01 (this length 3194 would make sense for SHA-256), the content covered by the digital 3195 signature for a server CertificateVerify would be: 3197 2020202020202020202020202020202020202020202020202020202020202020 3198 2020202020202020202020202020202020202020202020202020202020202020 3199 544c5320312e332c207365727665722043657274696669636174655665726966 3200 79 3201 00 3202 0101010101010101010101010101010101010101010101010101010101010101 3204 On the sender side the process for computing the signature field of 3205 the CertificateVerify message takes as input: 3207 - The content covered by the digital signature 3209 - The private signing key corresponding to the certificate sent in 3210 the previous message 3212 If the CertificateVerify message is sent by a server, the signature 3213 algorithm MUST be one offered in the client's "signature_algorithms" 3214 extension unless no valid certificate chain can be produced without 3215 unsupported algorithms (see Section 4.2.3). 3217 If sent by a client, the signature algorithm used in the signature 3218 MUST be one of those present in the supported_signature_algorithms 3219 field of the "signature_algorithms" extension in the 3220 CertificateRequest message. 3222 In addition, the signature algorithm MUST be compatible with the key 3223 in the sender's end-entity certificate. RSA signatures MUST use an 3224 RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS1-v1_5 3225 algorithms appear in "signature_algorithms". The SHA-1 algorithm 3226 MUST NOT be used in any signatures of CertificateVerify messages. 3227 All SHA-1 signature algorithms in this specification are defined 3228 solely for use in legacy certificates and are not valid for 3229 CertificateVerify signatures. 3231 The receiver of a CertificateVerify message MUST verify the signature 3232 field. The verification process takes as input: 3234 - The content covered by the digital signature 3236 - The public key contained in the end-entity certificate found in 3237 the associated Certificate message. 3239 - The digital signature received in the signature field of the 3240 CertificateVerify message 3242 If the verification fails, the receiver MUST terminate the handshake 3243 with a "decrypt_error" alert. 3245 4.4.4. Finished 3247 The Finished message is the final message in the authentication 3248 block. It is essential for providing authentication of the handshake 3249 and of the computed keys. 3251 Recipients of Finished messages MUST verify that the contents are 3252 correct and if incorrect MUST terminate the connection with a 3253 "decrypt_error" alert. 3255 Once a side has sent its Finished message and received and validated 3256 the Finished message from its peer, it may begin to send and receive 3257 application data over the connection. There are two settings in 3258 which it is permitted to send data prior to receiving the peer's 3259 Finished: 3261 1. Clients sending 0-RTT data as described in Section 4.2.10. 3263 2. Servers MAY send data after sending their first flight, but 3264 because the handshake is not yet complete, they have no assurance 3265 of either the peer's identity or of its liveness (i.e., the 3266 ClientHello might have been replayed). 3268 The key used to compute the finished message is computed from the 3269 Base key defined in Section 4.4 using HKDF (see Section 7.1). 3270 Specifically: 3272 finished_key = 3273 HKDF-Expand-Label(BaseKey, "finished", "", Hash.length) 3275 Structure of this message: 3277 struct { 3278 opaque verify_data[Hash.length]; 3279 } Finished; 3281 The verify_data value is computed as follows: 3283 verify_data = 3284 HMAC(finished_key, 3285 Transcript-Hash(Handshake Context, 3286 Certificate*, CertificateVerify*)) 3288 * Only included if present. 3290 HMAC [RFC2104] uses the Hash algorithm for the handshake. As noted 3291 above, the HMAC input can generally be implemented by a running hash, 3292 i.e., just the handshake hash at this point. 3294 In previous versions of TLS, the verify_data was always 12 octets 3295 long. In TLS 1.3, it is the size of the HMAC output for the Hash 3296 used for the handshake. 3298 Note: Alerts and any other record types are not handshake messages 3299 and are not included in the hash computations. 3301 Any records following a 1-RTT Finished message MUST be encrypted 3302 under the appropriate application traffic key as described in 3303 Section 7.2. In particular, this includes any alerts sent by the 3304 server in response to client Certificate and CertificateVerify 3305 messages. 3307 4.5. End of Early Data 3309 struct {} EndOfEarlyData; 3311 If the server sent an "early_data" extension, the client MUST send an 3312 EndOfEarlyData message after receiving the server Finished. If the 3313 server does not send an "early_data" extension, then the client MUST 3314 NOT send an EndOfEarlyData message. This message indicates that all 3315 0-RTT application_data messages, if any, have been transmitted and 3316 that the following records are protected under handshake traffic 3317 keys. Servers MUST NOT send this message and clients receiving it 3318 MUST terminate the connection with an "unexpected_message" alert. 3319 This message is encrypted under keys derived from the 3320 client_early_traffic_secret. 3322 4.6. Post-Handshake Messages 3324 TLS also allows other messages to be sent after the main handshake. 3325 These messages use a handshake content type and are encrypted under 3326 the appropriate application traffic key. 3328 4.6.1. New Session Ticket Message 3330 At any time after the server has received the client Finished 3331 message, it MAY send a NewSessionTicket message. This message 3332 creates a unique association between the ticket value and a secret 3333 PSK derived from the resumption master secret. 3335 The client MAY use this PSK for future handshakes by including the 3336 ticket value in the "pre_shared_key" extension in its ClientHello 3337 (Section 4.2.11). Servers MAY send multiple tickets on a single 3338 connection, either immediately after each other or after specific 3339 events (see Appendix C.4). For instance, the server might send a new 3340 ticket after post-handshake authentication in order to encapsulate 3341 the additional client authentication state. Multiple tickets are 3342 useful for clients for a variety of purposes, including: 3344 - Opening multiple parallel HTTP connections. 3346 - Performing connection racing across interfaces and address 3347 families via, e.g., Happy Eyeballs [RFC6555] or related 3348 techniques. 3350 Any ticket MUST only be resumed with a cipher suite that has the same 3351 KDF hash algorithm as that used to establish the original connection. 3353 Clients MUST only resume if the new SNI value is valid for the server 3354 certificate presented in the original session, and SHOULD only resume 3355 if the SNI value matches the one used in the original session. The 3356 latter is a performance optimization: normally, there is no reason to 3357 expect that different servers covered by a single certificate would 3358 be able to accept each other's tickets, hence attempting resumption 3359 in that case would waste a single-use ticket. If such an indication 3360 is provided (externally or by any other means), clients MAY resume 3361 with a different SNI value. 3363 On resumption, if reporting an SNI value to the calling application, 3364 implementations MUST use the value sent in the resumption ClientHello 3365 rather than the value sent in the previous session. Note that if a 3366 server implementation declines all PSK identities with different SNI 3367 values, these two values are always the same. 3369 Note: Although the resumption master secret depends on the client's 3370 second flight, servers which do not request client authentication MAY 3371 compute the remainder of the transcript independently and then send a 3372 NewSessionTicket immediately upon sending its Finished rather than 3373 waiting for the client Finished. This might be appropriate in cases 3374 where the client is expected to open multiple TLS connections in 3375 parallel and would benefit from the reduced overhead of a resumption 3376 handshake, for example. 3378 struct { 3379 uint32 ticket_lifetime; 3380 uint32 ticket_age_add; 3381 opaque ticket_nonce<0..255>; 3382 opaque ticket<1..2^16-1>; 3383 Extension extensions<0..2^16-2>; 3384 } NewSessionTicket; 3386 ticket_lifetime Indicates the lifetime in seconds as a 32-bit 3387 unsigned integer in network byte order from the time of ticket 3388 issuance. Servers MUST NOT use any value greater than 604800 3389 seconds (7 days). The value of zero indicates that the ticket 3390 should be discarded immediately. Clients MUST NOT cache tickets 3391 for longer than 7 days, regardless of the ticket_lifetime, and MAY 3392 delete the ticket earlier based on local policy. A server MAY 3393 treat a ticket as valid for a shorter period of time than what is 3394 stated in the ticket_lifetime. 3396 ticket_age_add A securely generated, random 32-bit value that is 3397 used to obscure the age of the ticket that the client includes in 3398 the "pre_shared_key" extension. The client-side ticket age is 3399 added to this value modulo 2^32 to obtain the value that is 3400 transmitted by the client. The server MUST generate a fresh value 3401 for each ticket it sends. 3403 ticket_nonce A per-ticket value that is unique across all tickets 3404 issued on this connection. 3406 ticket The value of the ticket to be used as the PSK identity. The 3407 ticket itself is an opaque label. It MAY either be a database 3408 lookup key or a self-encrypted and self-authenticated value. 3409 Section 4 of [RFC5077] describes a recommended ticket construction 3410 mechanism. 3412 extensions A set of extension values for the ticket. The 3413 "Extension" format is defined in Section 4.2. Clients MUST ignore 3414 unrecognized extensions. 3416 The sole extension currently defined for NewSessionTicket is 3417 "early_data", indicating that the ticket may be used to send 0-RTT 3418 data (Section 4.2.10)). It contains the following value: 3420 max_early_data_size The maximum amount of 0-RTT data that the client 3421 is allowed to send when using this ticket, in bytes. Only 3422 Application Data payload (i.e., plaintext but not padding or the 3423 inner content type byte) is counted. A server receiving more than 3424 max_early_data_size bytes of 0-RTT data SHOULD terminate the 3425 connection with an "unexpected_message" alert. Note that servers 3426 that reject early data due to lack of cryptographic material will 3427 be unable to differentiate padding from content, so clients SHOULD 3428 NOT depend on being able to send large quantities of padding in 3429 early data records. 3431 The PSK associated with the ticket is computed as: 3433 HKDF-Expand-Label(resumption_master_secret, 3434 "resumption", ticket_nonce, Hash.length) 3436 Because the ticket_nonce value is distinct for each NewSessionTicket 3437 message, a different PSK will be derived for each ticket. 3439 Note that in principle it is possible to continue issuing new tickets 3440 which indefinitely extend the lifetime of the keying material 3441 originally derived from an initial non-PSK handshake (which was most 3442 likely tied to the peer's certificate). It is RECOMMENDED that 3443 implementations place limits on the total lifetime of such keying 3444 material; these limits should take into account the lifetime of the 3445 peer's certificate, the likelihood of intervening revocation, and the 3446 time since the peer's online CertificateVerify signature. 3448 4.6.2. Post-Handshake Authentication 3450 When the client has sent the "post_handshake_auth" extension (see 3451 Section 4.2.6), a server MAY request client authentication at any 3452 time after the handshake has completed by sending a 3453 CertificateRequest message. The client MUST respond with the 3454 appropriate Authentication messages (see Section 4.4). If the client 3455 chooses to authenticate, it MUST send Certificate, CertificateVerify, 3456 and Finished. If it declines, it MUST send a Certificate message 3457 containing no certificates followed by Finished. All of the client's 3458 messages for a given response MUST appear consecutively on the wire 3459 with no intervening messages of other types. 3461 A client that receives a CertificateRequest message without having 3462 sent the "post_handshake_auth" extension MUST send an 3463 "unexpected_message" fatal alert. 3465 Note: Because client authentication could involve prompting the user, 3466 servers MUST be prepared for some delay, including receiving an 3467 arbitrary number of other messages between sending the 3468 CertificateRequest and receiving a response. In addition, clients 3469 which receive multiple CertificateRequests in close succession MAY 3470 respond to them in a different order than they were received (the 3471 certificate_request_context value allows the server to disambiguate 3472 the responses). 3474 4.6.3. Key and IV Update 3476 enum { 3477 update_not_requested(0), update_requested(1), (255) 3478 } KeyUpdateRequest; 3480 struct { 3481 KeyUpdateRequest request_update; 3482 } KeyUpdate; 3484 request_update Indicates whether the recipient of the KeyUpdate 3485 should respond with its own KeyUpdate. If an implementation 3486 receives any other value, it MUST terminate the connection with an 3487 "illegal_parameter" alert. 3489 The KeyUpdate handshake message is used to indicate that the sender 3490 is updating its sending cryptographic keys. This message can be sent 3491 by either peer after it has sent a Finished message. Implementations 3492 that receive a KeyUpdate message prior to receiving a Finished 3493 message MUST terminate the connection with an "unexpected_message" 3494 alert. After sending a KeyUpdate message, the sender SHALL send all 3495 its traffic using the next generation of keys, computed as described 3496 in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update 3497 its receiving keys. 3499 If the request_update field is set to "update_requested" then the 3500 receiver MUST send a KeyUpdate of its own with request_update set to 3501 "update_not_requested" prior to sending its next application data 3502 record. This mechanism allows either side to force an update to the 3503 entire connection, but causes an implementation which receives 3504 multiple KeyUpdates while it is silent to respond with a single 3505 update. Note that implementations may receive an arbitrary number of 3506 messages between sending a KeyUpdate with request_update set to 3507 update_requested and receiving the peer's KeyUpdate, because those 3508 messages may already be in flight. However, because send and receive 3509 keys are derived from independent traffic secrets, retaining the 3510 receive traffic secret does not threaten the forward secrecy of data 3511 sent before the sender changed keys. 3513 If implementations independently send their own KeyUpdates with 3514 request_update set to "update_requested", and they cross in flight, 3515 then each side will also send a response, with the result that each 3516 side increments by two generations. 3518 Both sender and receiver MUST encrypt their KeyUpdate messages with 3519 the old keys. Additionally, both sides MUST enforce that a KeyUpdate 3520 with the old key is received before accepting any messages encrypted 3521 with the new key. Failure to do so may allow message truncation 3522 attacks. 3524 5. Record Protocol 3526 The TLS record protocol takes messages to be transmitted, fragments 3527 the data into manageable blocks, protects the records, and transmits 3528 the result. Received data is verified, decrypted, reassembled, and 3529 then delivered to higher-level clients. 3531 TLS records are typed, which allows multiple higher-level protocols 3532 to be multiplexed over the same record layer. This document 3533 specifies four content types: handshake, application data, alert, and 3534 change_cipher_spec, with the latter being used only for compatibility 3535 purposes (see Appendix D.4). 3537 An implementation may receive an unencrypted record of type 3538 change_cipher_spec consisting of the single byte value 0x01 at any 3539 time during the handshake and MUST simply drop it without further 3540 processing. Note that this record may appear at a point at the 3541 handshake where the implementation is expecting protected records and 3542 so it is necessary to detect this condition prior to attempting to 3543 deprotect the record. An implementation which receives any other 3544 change_cipher_spec value or which receives a protected 3545 change_cipher_spec record MUST abort the handshake with an 3546 "unexpected_message" alert. After the handshake is complete, 3547 change_cipher_spec MUST be treated as an unexpected record type. 3549 Implementations MUST NOT send record types not defined in this 3550 document unless negotiated by some extension. If a TLS 3551 implementation receives an unexpected record type, it MUST terminate 3552 the connection with an "unexpected_message" alert. New record 3553 content type values are assigned by IANA in the TLS Content Type 3554 Registry as described in Section 11. 3556 5.1. Record Layer 3558 The record layer fragments information blocks into TLSPlaintext 3559 records carrying data in chunks of 2^14 bytes or less. Message 3560 boundaries are handled differently depending on the underlying 3561 ContentType. Any future content types MUST specify appropriate 3562 rules. Note that these rules are stricter than what was enforced in 3563 TLS 1.2. 3565 Handshake messages MAY be coalesced into a single TLSPlaintext record 3566 or fragmented across several records, provided that: 3568 - Handshake messages MUST NOT be interleaved with other record 3569 types. That is, if a handshake message is split over two or more 3570 records, there MUST NOT be any other records between them. 3572 - Handshake messages MUST NOT span key changes. Implementations 3573 MUST verify that all messages immediately preceding a key change 3574 align with a record boundary; if not, then they MUST terminate the 3575 connection with an "unexpected_message" alert. Because the 3576 ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate 3577 messages can immediately precede a key change, implementations 3578 MUST send these messages in alignment with a record boundary. 3580 Implementations MUST NOT send zero-length fragments of Handshake 3581 types, even if those fragments contain padding. 3583 Alert messages (Section 6) MUST NOT be fragmented across records and 3584 multiple Alert messages MUST NOT be coalesced into a single 3585 TLSPlaintext record. In other words, a record with an Alert type 3586 MUST contain exactly one message. 3588 Application Data messages contain data that is opaque to TLS. 3589 Application Data messages are always protected. Zero-length 3590 fragments of Application Data MAY be sent as they are potentially 3591 useful as a traffic analysis countermeasure. Application Data 3592 fragments MAY be split across multiple records or coalesced into a 3593 single record. 3595 enum { 3596 invalid(0), 3597 change_cipher_spec(20), 3598 alert(21), 3599 handshake(22), 3600 application_data(23), 3601 (255) 3602 } ContentType; 3604 struct { 3605 ContentType type; 3606 ProtocolVersion legacy_record_version; 3607 uint16 length; 3608 opaque fragment[TLSPlaintext.length]; 3609 } TLSPlaintext; 3611 type The higher-level protocol used to process the enclosed 3612 fragment. 3614 legacy_record_version This value MUST be set to 0x0303 for all 3615 records generated by a TLS 1.3 implementation other than the 3616 ClientHello, where it MAY also be 0x0301 for compatibility 3617 purposes. This field is deprecated and MUST be ignored for all 3618 purposes. Previous versions of TLS would use other values in this 3619 field under some circumstances. 3621 length The length (in bytes) of the following TLSPlaintext.fragment. 3622 The length MUST NOT exceed 2^14 bytes. An endpoint that receives 3623 a record that exceeds this length MUST terminate the connection 3624 with a "record_overflow" alert. 3626 fragment The data being transmitted. This value is transparent and 3627 is treated as an independent block to be dealt with by the higher- 3628 level protocol specified by the type field. 3630 This document describes TLS 1.3, which uses the version 0x0304. This 3631 version value is historical, deriving from the use of 0x0301 for TLS 3632 1.0 and 0x0300 for SSL 3.0. In order to maximize backwards 3633 compatibility, records containing the ClientHello MUST have version 3634 0x0301 and records containing the ServerHello MUST have version 3635 0x0303, reflecting TLS 1.0 and TLS 1.2 respectively. When 3636 negotiating prior versions of TLS, endpoints follow the procedure and 3637 requirements in Appendix D. 3639 When record protection has not yet been engaged, TLSPlaintext 3640 structures are written directly onto the wire. Once record 3641 protection has started, TLSPlaintext records are protected and sent 3642 as described in the following section. 3644 5.2. Record Payload Protection 3646 The record protection functions translate a TLSPlaintext structure 3647 into a TLSCiphertext. The deprotection functions reverse the 3648 process. In TLS 1.3, as opposed to previous versions of TLS, all 3649 ciphers are modeled as "Authenticated Encryption with Additional 3650 Data" (AEAD) [RFC5116]. AEAD functions provide an unified encryption 3651 and authentication operation which turns plaintext into authenticated 3652 ciphertext and back again. Each encrypted record consists of a 3653 plaintext header followed by an encrypted body, which itself contains 3654 a type and optional padding. 3656 struct { 3657 opaque content[TLSPlaintext.length]; 3658 ContentType type; 3659 uint8 zeros[length_of_padding]; 3660 } TLSInnerPlaintext; 3662 struct { 3663 ContentType opaque_type = application_data; /* 23 */ 3664 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */ 3665 uint16 length; 3666 opaque encrypted_record[TLSCiphertext.length]; 3667 } TLSCiphertext; 3669 content The byte encoding of a handshake or an alert message, or the 3670 raw bytes of the application's data to send. 3672 type The content type of the record. 3674 zeros An arbitrary-length run of zero-valued bytes may appear in the 3675 cleartext after the type field. This provides an opportunity for 3676 senders to pad any TLS record by a chosen amount as long as the 3677 total stays within record size limits. See Section 5.4 for more 3678 details. 3680 opaque_type The outer opaque_type field of a TLSCiphertext record is 3681 always set to the value 23 (application_data) for outward 3682 compatibility with middleboxes accustomed to parsing previous 3683 versions of TLS. The actual content type of the record is found 3684 in TLSInnerPlaintext.type after decryption. 3686 legacy_record_version The legacy_record_version field is always 3687 0x0303. TLS 1.3 TLSCiphertexts are not generated until after TLS 3688 1.3 has been negotiated, so there are no historical compatibility 3689 concerns where other values might be received. Implementations 3690 MAY verify that the legacy_record_version field is 0x0303 and 3691 abort the connection if it is not. Note that the handshake 3692 protocol including the ClientHello and ServerHello messages 3693 authenticates the protocol version, so this value is redundant. 3695 length The length (in bytes) of the following 3696 TLSCiphertext.encrypted_record, which is the sum of the lengths of 3697 the content and the padding, plus one for the inner content type, 3698 plus any expansion added by the AEAD algorithm. The length MUST 3699 NOT exceed 2^14 + 256 bytes. An endpoint that receives a record 3700 that exceeds this length MUST terminate the connection with a 3701 "record_overflow" alert. 3703 encrypted_record The AEAD-encrypted form of the serialized 3704 TLSInnerPlaintext structure. 3706 AEAD algorithms take as input a single key, a nonce, a plaintext, and 3707 "additional data" to be included in the authentication check, as 3708 described in Section 2.1 of [RFC5116]. The key is either the 3709 client_write_key or the server_write_key, the nonce is derived from 3710 the sequence number (see Section 5.3) and the client_write_iv or 3711 server_write_iv, and the additional data input is empty (zero 3712 length). Derivation of traffic keys is defined in Section 7.3. 3714 The plaintext input to the AEAD algorithm is the encoded 3715 TLSInnerPlaintext structure. 3717 The AEAD output consists of the ciphertext output from the AEAD 3718 encryption operation. The length of the plaintext is greater than 3719 the corresponding TLSPlaintext.length due to the inclusion of 3720 TLSInnerPlaintext.type and any padding supplied by the sender. The 3721 length of the AEAD output will generally be larger than the 3722 plaintext, but by an amount that varies with the AEAD algorithm. 3723 Since the ciphers might incorporate padding, the amount of overhead 3724 could vary with different lengths of plaintext. Symbolically, 3726 AEADEncrypted = 3727 AEAD-Encrypt(write_key, nonce, plaintext) 3729 In order to decrypt and verify, the cipher takes as input the key, 3730 nonce, and the AEADEncrypted value. The output is either the 3731 plaintext or an error indicating that the decryption failed. There 3732 is no separate integrity check. That is: 3734 plaintext of encrypted_record = 3735 AEAD-Decrypt(peer_write_key, nonce, AEADEncrypted) 3737 If the decryption fails, the receiver MUST terminate the connection 3738 with a "bad_record_mac" alert. 3740 An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion 3741 greater than 255 octets. An endpoint that receives a record from its 3742 peer with TLSCiphertext.length larger than 2^14 + 256 octets MUST 3743 terminate the connection with a "record_overflow" alert. This limit 3744 is derived from the maximum TLSPlaintext length of 2^14 octets + 1 3745 octet for ContentType + the maximum AEAD expansion of 255 octets. 3747 5.3. Per-Record Nonce 3749 A 64-bit sequence number is maintained separately for reading and 3750 writing records. Each sequence number is set to zero at the 3751 beginning of a connection and whenever the key is changed. 3753 The appropriate sequence number is incremented by one after reading 3754 or writing each record. The first record transmitted under a 3755 particular traffic key MUST use sequence number 0. 3757 Because the size of sequence numbers is 64-bit, they should not wrap. 3758 If a TLS implementation would need to wrap a sequence number, it MUST 3759 either re-key (Section 4.6.3) or terminate the connection. 3761 Each AEAD algorithm will specify a range of possible lengths for the 3762 per-record nonce, from N_MIN bytes to N_MAX bytes of input 3763 ([RFC5116]). The length of the TLS per-record nonce (iv_length) is 3764 set to the larger of 8 bytes and N_MIN for the AEAD algorithm (see 3765 [RFC5116] Section 4). An AEAD algorithm where N_MAX is less than 8 3766 bytes MUST NOT be used with TLS. The per-record nonce for the AEAD 3767 construction is formed as follows: 3769 1. The 64-bit record sequence number is encoded in network byte 3770 order and padded to the left with zeros to iv_length. 3772 2. The padded sequence number is XORed with the static 3773 client_write_iv or server_write_iv, depending on the role. 3775 The resulting quantity (of length iv_length) is used as the per- 3776 record nonce. 3778 Note: This is a different construction from that in TLS 1.2, which 3779 specified a partially explicit nonce. 3781 5.4. Record Padding 3783 All encrypted TLS records can be padded to inflate the size of the 3784 TLSCiphertext. This allows the sender to hide the size of the 3785 traffic from an observer. 3787 When generating a TLSCiphertext record, implementations MAY choose to 3788 pad. An unpadded record is just a record with a padding length of 3789 zero. Padding is a string of zero-valued bytes appended to the 3790 ContentType field before encryption. Implementations MUST set the 3791 padding octets to all zeros before encrypting. 3793 Application Data records may contain a zero-length 3794 TLSInnerPlaintext.content if the sender desires. This permits 3795 generation of plausibly-sized cover traffic in contexts where the 3796 presence or absence of activity may be sensitive. Implementations 3797 MUST NOT send Handshake or Alert records that have a zero-length 3798 TLSInnerPlaintext.content; if such a message is received, the 3799 receiving implementation MUST terminate the connection with an 3800 "unexpected_message" alert. 3802 The padding sent is automatically verified by the record protection 3803 mechanism; upon successful decryption of a 3804 TLSCiphertext.encrypted_record, the receiving implementation scans 3805 the field from the end toward the beginning until it finds a non-zero 3806 octet. This non-zero octet is the content type of the message. This 3807 padding scheme was selected because it allows padding of any 3808 encrypted TLS record by an arbitrary size (from zero up to TLS record 3809 size limits) without introducing new content types. The design also 3810 enforces all-zero padding octets, which allows for quick detection of 3811 padding errors. 3813 Implementations MUST limit their scanning to the cleartext returned 3814 from the AEAD decryption. If a receiving implementation does not 3815 find a non-zero octet in the cleartext, it MUST terminate the 3816 connection with an "unexpected_message" alert. 3818 The presence of padding does not change the overall record size 3819 limitations - the full encoded TLSInnerPlaintext MUST NOT exceed 2^14 3820 + 1 octets. If the maximum fragment length is reduced, as for 3821 example by the max_fragment_length extension from [RFC6066], then the 3822 reduced limit applies to the full plaintext, including the content 3823 type and padding. 3825 Selecting a padding policy that suggests when and how much to pad is 3826 a complex topic and is beyond the scope of this specification. If 3827 the application layer protocol on top of TLS has its own padding, it 3828 may be preferable to pad application_data TLS records within the 3829 application layer. Padding for encrypted handshake and alert TLS 3830 records must still be handled at the TLS layer, though. Later 3831 documents may define padding selection algorithms or define a padding 3832 policy request mechanism through TLS extensions or some other means. 3834 5.5. Limits on Key Usage 3836 There are cryptographic limits on the amount of plaintext which can 3837 be safely encrypted under a given set of keys. [AEAD-LIMITS] 3838 provides an analysis of these limits under the assumption that the 3839 underlying primitive (AES or ChaCha20) has no weaknesses. 3840 Implementations SHOULD do a key update as described in Section 4.6.3 3841 prior to reaching these limits. 3843 For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be 3844 encrypted on a given connection while keeping a safety margin of 3845 approximately 2^-57 for Authenticated Encryption (AE) security. For 3846 ChaCha20/Poly1305, the record sequence number would wrap before the 3847 safety limit is reached. 3849 6. Alert Protocol 3851 One of the content types supported by the TLS record layer is the 3852 alert type. Like other messages, alert messages are encrypted as 3853 specified by the current connection state. 3855 Alert messages convey a description of the alert and a legacy field 3856 that conveyed the severity of the message in previous versions of 3857 TLS. In TLS 1.3, the severity is implicit in the type of alert being 3858 sent, and the 'level' field can safely be ignored. The 3859 "close_notify" alert is used to indicate orderly closure of one 3860 direction of the connection. Upon receiving such an alert, the TLS 3861 implementation SHOULD indicate end-of-data to the application. 3863 Error alerts indicate abortive closure of the connection (see 3864 Section 6.2). Upon receiving an error alert, the TLS implementation 3865 SHOULD indicate an error to the application and MUST NOT allow any 3866 further data to be sent or received on the connection. Servers and 3867 clients MUST forget keys and secrets associated with a failed 3868 connection. Stateful implementations of tickets (as in many clients) 3869 SHOULD discard tickets associated with failed connections. 3871 All the alerts listed in Section 6.2 MUST be sent as fatal and MUST 3872 be treated as fatal regardless of the AlertLevel in the message. 3873 Unknown alert types MUST be treated as fatal. 3875 Note: TLS defines two generic alerts (see Section 6) to use upon 3876 failure to parse a message. Peers which receive a message which 3877 cannot be parsed according to the syntax (e.g., have a length 3878 extending beyond the message boundary or contain an out-of-range 3879 length) MUST terminate the connection with a "decode_error" alert. 3880 Peers which receive a message which is syntactically correct but 3881 semantically invalid (e.g., a DHE share of p - 1, or an invalid enum) 3882 MUST terminate the connection with an "illegal_parameter" alert. 3884 enum { warning(1), fatal(2), (255) } AlertLevel; 3886 enum { 3887 close_notify(0), 3888 unexpected_message(10), 3889 bad_record_mac(20), 3890 record_overflow(22), 3891 handshake_failure(40), 3892 bad_certificate(42), 3893 unsupported_certificate(43), 3894 certificate_revoked(44), 3895 certificate_expired(45), 3896 certificate_unknown(46), 3897 illegal_parameter(47), 3898 unknown_ca(48), 3899 access_denied(49), 3900 decode_error(50), 3901 decrypt_error(51), 3902 protocol_version(70), 3903 insufficient_security(71), 3904 internal_error(80), 3905 inappropriate_fallback(86), 3906 user_canceled(90), 3907 missing_extension(109), 3908 unsupported_extension(110), 3909 certificate_unobtainable(111), 3910 unrecognized_name(112), 3911 bad_certificate_status_response(113), 3912 bad_certificate_hash_value(114), 3913 unknown_psk_identity(115), 3914 certificate_required(116), 3915 no_application_protocol(120), 3916 (255) 3917 } AlertDescription; 3919 struct { 3920 AlertLevel level; 3921 AlertDescription description; 3922 } Alert; 3924 6.1. Closure Alerts 3926 The client and the server must share knowledge that the connection is 3927 ending in order to avoid a truncation attack. 3929 close_notify This alert notifies the recipient that the sender will 3930 not send any more messages on this connection. Any data received 3931 after a closure alert has been received MUST be ignored. 3933 user_canceled This alert notifies the recipient that the sender is 3934 canceling the handshake for some reason unrelated to a protocol 3935 failure. If a user cancels an operation after the handshake is 3936 complete, just closing the connection by sending a "close_notify" 3937 is more appropriate. This alert SHOULD be followed by a 3938 "close_notify". This alert is generally a warning. 3940 Either party MAY initiate a close of its write side of the connection 3941 by sending a "close_notify" alert. Any data received after a closure 3942 alert has been received MUST be ignored. If a transport-level close 3943 is received prior to a "close_notify", the receiver cannot know that 3944 all the data that was sent has been received. 3946 Each party MUST send a "close_notify" alert before closing its write 3947 side of the connection, unless it has already sent some other fatal 3948 alert. This does not have any effect on its read side of the 3949 connection. Note that this is a change from versions of TLS prior to 3950 TLS 1.3 in which implementations were required to react to a 3951 "close_notify" by discarding pending writes and sending an immediate 3952 "close_notify" alert of their own. That previous requirement could 3953 cause truncation in the read side. Both parties need not wait to 3954 receive a "close_notify" alert before closing their read side of the 3955 connection. 3957 If the application protocol using TLS provides that any data may be 3958 carried over the underlying transport after the TLS connection is 3959 closed, the TLS implementation MUST receive a "close_notify" alert 3960 before indicating end-of-data to the application-layer. No part of 3961 this standard should be taken to dictate the manner in which a usage 3962 profile for TLS manages its data transport, including when 3963 connections are opened or closed. 3965 Note: It is assumed that closing the write side of a connection 3966 reliably delivers pending data before destroying the transport. 3968 6.2. Error Alerts 3970 Error handling in the TLS Handshake Protocol is very simple. When an 3971 error is detected, the detecting party sends a message to its peer. 3972 Upon transmission or receipt of a fatal alert message, both parties 3973 MUST immediately close the connection. 3975 Whenever an implementation encounters a fatal error condition, it 3976 SHOULD send an appropriate fatal alert and MUST close the connection 3977 without sending or receiving any additional data. In the rest of 3978 this specification, when the phrases "terminate the connection" and 3979 "abort the handshake" are used without a specific alert it means that 3980 the implementation SHOULD send the alert indicated by the 3981 descriptions below. The phrases "terminate the connection with a X 3982 alert" and "abort the handshake with a X alert" mean that the 3983 implementation MUST send alert X if it sends any alert. All alerts 3984 defined in this section below, as well as all unknown alerts, are 3985 universally considered fatal as of TLS 1.3 (see Section 6). The 3986 implementation SHOULD provide a way to facilitate logging the sending 3987 and receiving of alerts. 3989 The following error alerts are defined: 3991 unexpected_message An inappropriate message (e.g., the wrong 3992 handshake message, premature application data, etc.) was received. 3993 This alert should never be observed in communication between 3994 proper implementations. 3996 bad_record_mac This alert is returned if a record is received which 3997 cannot be deprotected. Because AEAD algorithms combine decryption 3998 and verification, and also to avoid side channel attacks, this 3999 alert is used for all deprotection failures. This alert should 4000 never be observed in communication between proper implementations, 4001 except when messages were corrupted in the network. 4003 record_overflow A TLSCiphertext record was received that had a 4004 length more than 2^14 + 256 bytes, or a record decrypted to a 4005 TLSPlaintext record with more than 2^14 bytes. This alert should 4006 never be observed in communication between proper implementations, 4007 except when messages were corrupted in the network. 4009 handshake_failure Receipt of a "handshake_failure" alert message 4010 indicates that the sender was unable to negotiate an acceptable 4011 set of security parameters given the options available. 4013 bad_certificate A certificate was corrupt, contained signatures that 4014 did not verify correctly, etc. 4016 unsupported_certificate A certificate was of an unsupported type. 4018 certificate_revoked A certificate was revoked by its signer. 4020 certificate_expired A certificate has expired or is not currently 4021 valid. 4023 certificate_unknown Some other (unspecified) issue arose in 4024 processing the certificate, rendering it unacceptable. 4026 illegal_parameter A field in the handshake was incorrect or 4027 inconsistent with other fields. This alert is used for errors 4028 which conform to the formal protocol syntax but are otherwise 4029 incorrect. 4031 unknown_ca A valid certificate chain or partial chain was received, 4032 but the certificate was not accepted because the CA certificate 4033 could not be located or could not be matched with a known trust 4034 anchor. 4036 access_denied A valid certificate or PSK was received, but when 4037 access control was applied, the sender decided not to proceed with 4038 negotiation. 4040 decode_error A message could not be decoded because some field was 4041 out of the specified range or the length of the message was 4042 incorrect. This alert is used for errors where the message does 4043 not conform to the formal protocol syntax. This alert should 4044 never be observed in communication between proper implementations, 4045 except when messages were corrupted in the network. 4047 decrypt_error A handshake (not record-layer) cryptographic operation 4048 failed, including being unable to correctly verify a signature or 4049 validate a Finished message or a PSK binder. 4051 protocol_version The protocol version the peer has attempted to 4052 negotiate is recognized but not supported. (see Appendix D) 4054 insufficient_security Returned instead of "handshake_failure" when a 4055 negotiation has failed specifically because the server requires 4056 parameters more secure than those supported by the client. 4058 internal_error An internal error unrelated to the peer or the 4059 correctness of the protocol (such as a memory allocation failure) 4060 makes it impossible to continue. 4062 inappropriate_fallback Sent by a server in response to an invalid 4063 connection retry attempt from a client (see [RFC7507]). 4065 missing_extension Sent by endpoints that receive a hello message not 4066 containing an extension that is mandatory to send for the offered 4067 TLS version or other negotiated parameters. 4069 unsupported_extension Sent by endpoints receiving any hello message 4070 containing an extension known to be prohibited for inclusion in 4071 the given hello message, or including any extensions in a 4072 ServerHello or Certificate not first offered in the corresponding 4073 ClientHello. 4075 certificate_unobtainable Sent by servers when unable to obtain a 4076 certificate from a URL provided by the client via the 4077 "client_certificate_url" extension (see [RFC6066]). 4079 unrecognized_name Sent by servers when no server exists identified 4080 by the name provided by the client via the "server_name" extension 4081 (see [RFC6066]). 4083 bad_certificate_status_response Sent by clients when an invalid or 4084 unacceptable OCSP response is provided by the server via the 4085 "status_request" extension (see [RFC6066]). 4087 bad_certificate_hash_value Sent by servers when a retrieved object 4088 does not have the correct hash provided by the client via the 4089 "client_certificate_url" extension (see [RFC6066]). 4091 unknown_psk_identity Sent by servers when PSK key establishment is 4092 desired but no acceptable PSK identity is provided by the client. 4093 Sending this alert is OPTIONAL; servers MAY instead choose to send 4094 a "decrypt_error" alert to merely indicate an invalid PSK 4095 identity. 4097 certificate_required Sent by servers when a client certificate is 4098 desired but none was provided by the client. 4100 no_application_protocol Sent by servers when a client 4101 "application_layer_protocol_negotiation" extension advertises only 4102 protocols that the server does not support (see [RFC7301]). 4104 New Alert values are assigned by IANA as described in Section 11. 4106 7. Cryptographic Computations 4108 The TLS handshake establishes one or more input secrets which are 4109 combined to create the actual working keying material, as detailed 4110 below. The key derivation process incorporates both the input 4111 secrets and the handshake transcript. Note that because the 4112 handshake transcript includes the random values from the Hello 4113 messages, any given handshake will have different traffic secrets, 4114 even if the same input secrets are used, as is the case when the same 4115 PSK is used for multiple connections. 4117 7.1. Key Schedule 4119 The key derivation process makes use of the HKDF-Extract and HKDF- 4120 Expand functions as defined for HKDF [RFC5869], as well as the 4121 functions defined below: 4123 HKDF-Expand-Label(Secret, Label, Context, Length) = 4124 HKDF-Expand(Secret, HkdfLabel, Length) 4126 Where HkdfLabel is specified as: 4128 struct { 4129 uint16 length = Length; 4130 opaque label<7..255> = "tls13 " + Label; 4131 opaque context<0..255> = Context; 4132 } HkdfLabel; 4134 Derive-Secret(Secret, Label, Messages) = 4135 HKDF-Expand-Label(Secret, Label, 4136 Transcript-Hash(Messages), Hash.length) 4138 The Hash function used by Transcript-Hash and HKDF is the cipher 4139 suite hash algorithm. Hash.length is its output length in bytes. 4140 Messages are the concatenation of the indicated handshake messages, 4141 including the handshake message type and length fields, but not 4142 including record layer headers. Note that in some cases a zero- 4143 length Context (indicated by "") is passed to HKDF-Expand-Label. The 4144 Labels specified in this document are all ASCII strings, and do not 4145 include a trailing NUL byte. 4147 Note: with common hash functions, any label longer than 12 characters 4148 requires an additional iteration of the hash function to compute. 4149 The labels in this specification have all been chosen to fit within 4150 this limit. 4152 Given a set of n InputSecrets, the final "master secret" is computed 4153 by iteratively invoking HKDF-Extract with InputSecret_1, 4154 InputSecret_2, etc. The initial secret is simply a string of 4155 Hash.length bytes set to zeros. Concretely, for the present version 4156 of TLS 1.3, secrets are added in the following order: 4158 - PSK (a pre-shared key established externally or derived from the 4159 resumption_master_secret value from a previous connection) 4161 - (EC)DHE shared secret (Section 7.4) 4163 This produces a full key derivation schedule shown in the diagram 4164 below. In this diagram, the following formatting conventions apply: 4166 - HKDF-Extract is drawn as taking the Salt argument from the top and 4167 the IKM argument from the left. 4169 - Derive-Secret's Secret argument is indicated by the incoming 4170 arrow. For instance, the Early Secret is the Secret for 4171 generating the client_early_traffic_secret. 4173 0 4174 | 4175 v 4176 PSK -> HKDF-Extract = Early Secret 4177 | 4178 +-----> Derive-Secret(., 4179 | "ext binder" | 4180 | "res binder", 4181 | "") 4182 | = binder_key 4183 | 4184 +-----> Derive-Secret(., "c e traffic", 4185 | ClientHello) 4186 | = client_early_traffic_secret 4187 | 4188 +-----> Derive-Secret(., "e exp master", 4189 | ClientHello) 4190 | = early_exporter_master_secret 4191 v 4192 Derive-Secret(., "derived", "") 4193 | 4194 v 4195 (EC)DHE -> HKDF-Extract = Handshake Secret 4196 | 4197 +-----> Derive-Secret(., "c hs traffic", 4198 | ClientHello...ServerHello) 4199 | = client_handshake_traffic_secret 4200 | 4201 +-----> Derive-Secret(., "s hs traffic", 4202 | ClientHello...ServerHello) 4203 | = server_handshake_traffic_secret 4204 v 4205 Derive-Secret(., "derived", "") 4206 | 4207 v 4208 0 -> HKDF-Extract = Master Secret 4209 | 4210 +-----> Derive-Secret(., "c ap traffic", 4211 | ClientHello...server Finished) 4212 | = client_application_traffic_secret_0 4213 | 4214 +-----> Derive-Secret(., "s ap traffic", 4215 | ClientHello...server Finished) 4216 | = server_application_traffic_secret_0 4217 | 4218 +-----> Derive-Secret(., "exp master", 4219 | ClientHello...server Finished) 4220 | = exporter_master_secret 4221 | 4222 +-----> Derive-Secret(., "res master", 4223 ClientHello...client Finished) 4224 = resumption_master_secret 4226 The general pattern here is that the secrets shown down the left side 4227 of the diagram are just raw entropy without context, whereas the 4228 secrets down the right side include handshake context and therefore 4229 can be used to derive working keys without additional context. Note 4230 that the different calls to Derive-Secret may take different Messages 4231 arguments, even with the same secret. In a 0-RTT exchange, Derive- 4232 Secret is called with four distinct transcripts; in a 1-RTT-only 4233 exchange with three distinct transcripts. 4235 If a given secret is not available, then the 0-value consisting of a 4236 string of Hash.length bytes set to zeros is used. Note that this 4237 does not mean skipping rounds, so if PSK is not in use Early Secret 4238 will still be HKDF-Extract(0, 0). For the computation of the 4239 binder_secret, the label is "ext binder" for external PSKs (those 4240 provisioned outside of TLS) and "res binder" for resumption PSKs 4241 (those provisioned as the resumption master secret of a previous 4242 handshake). The different labels prevent the substitution of one 4243 type of PSK for the other. 4245 There are multiple potential Early Secret values depending on which 4246 PSK the server ultimately selects. The client will need to compute 4247 one for each potential PSK; if no PSK is selected, it will then need 4248 to compute the early secret corresponding to the zero PSK. 4250 Once all the values which are to be derived from a given secret have 4251 been computed, that secret SHOULD be erased. 4253 7.2. Updating Traffic Keys and IVs 4255 Once the handshake is complete, it is possible for either side to 4256 update its sending traffic keys using the KeyUpdate handshake message 4257 defined in Section 4.6.3. The next generation of traffic keys is 4258 computed by generating client_/server_application_traffic_secret_N+1 4259 from client_/server_application_traffic_secret_N as described in this 4260 section then re-deriving the traffic keys as described in 4261 Section 7.3. 4263 The next-generation application_traffic_secret is computed as: 4265 application_traffic_secret_N+1 = 4266 HKDF-Expand-Label(application_traffic_secret_N, 4267 "traffic upd", "", Hash.length) 4269 Once client/server_application_traffic_secret_N+1 and its associated 4270 traffic keys have been computed, implementations SHOULD delete 4271 client_/server_application_traffic_secret_N and its associated 4272 traffic keys. 4274 7.3. Traffic Key Calculation 4276 The traffic keying material is generated from the following input 4277 values: 4279 - A secret value 4281 - A purpose value indicating the specific value being generated 4283 - The length of the key 4285 The traffic keying material is generated from an input traffic secret 4286 value using: 4288 [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) 4289 [sender]_write_iv = HKDF-Expand-Label(Secret, "iv" , "", iv_length) 4291 [sender] denotes the sending side. The Secret value for each record 4292 type is shown in the table below. 4294 +-------------------+---------------------------------------+ 4295 | Record Type | Secret | 4296 +-------------------+---------------------------------------+ 4297 | 0-RTT Application | client_early_traffic_secret | 4298 | | | 4299 | Handshake | [sender]_handshake_traffic_secret | 4300 | | | 4301 | Application Data | [sender]_application_traffic_secret_N | 4302 +-------------------+---------------------------------------+ 4304 All the traffic keying material is recomputed whenever the underlying 4305 Secret changes (e.g., when changing from the handshake to application 4306 data keys or upon a key update). 4308 7.4. (EC)DHE Shared Secret Calculation 4309 7.4.1. Finite Field Diffie-Hellman 4311 For finite field groups, a conventional Diffie-Hellman computation is 4312 performed. The negotiated key (Z) is converted to a byte string by 4313 encoding in big-endian and padded with zeros up to the size of the 4314 prime. This byte string is used as the shared secret in the key 4315 schedule as specified above. 4317 Note that this construction differs from previous versions of TLS 4318 which remove leading zeros. 4320 7.4.2. Elliptic Curve Diffie-Hellman 4322 For secp256r1, secp384r1 and secp521r1, ECDH calculations (including 4323 parameter and key generation as well as the shared secret 4324 calculation) are performed according to [IEEE1363] using the ECKAS- 4325 DH1 scheme with the identity map as key derivation function (KDF), so 4326 that the shared secret is the x-coordinate of the ECDH shared secret 4327 elliptic curve point represented as an octet string. Note that this 4328 octet string (Z in IEEE 1363 terminology) as output by FE2OSP, the 4329 Field Element to Octet String Conversion Primitive, has constant 4330 length for any given field; leading zeros found in this octet string 4331 MUST NOT be truncated. 4333 (Note that this use of the identity KDF is a technicality. The 4334 complete picture is that ECDH is employed with a non-trivial KDF 4335 because TLS does not directly use this secret for anything other than 4336 for computing other secrets.) 4338 ECDH functions are used as follows: 4340 - The public key to put into the KeyShareEntry.key_exchange 4341 structure is the result of applying the ECDH scalar multiplication 4342 function to the secret key of appropriate length (into scalar 4343 input) and the standard public basepoint (into u-coordinate point 4344 input). 4346 - The ECDH shared secret is the result of applying the ECDH scalar 4347 multiplication function to the secret key (into scalar input) and 4348 the peer's public key (into u-coordinate point input). The output 4349 is used raw, with no processing. 4351 For X25519 and X448, implementations SHOULD use the approach 4352 specified in [RFC7748] to calculate the Diffie-Hellman shared secret. 4353 Implementations MUST check whether the computed Diffie-Hellman shared 4354 secret is the all-zero value and abort if so, as described in 4355 Section 6 of [RFC7748]. If implementers use an alternative 4356 implementation of these elliptic curves, they SHOULD perform the 4357 additional checks specified in Section 7 of [RFC7748]. 4359 7.5. Exporters 4361 [RFC5705] defines keying material exporters for TLS in terms of the 4362 TLS pseudorandom function (PRF). This document replaces the PRF with 4363 HKDF, thus requiring a new construction. The exporter interface 4364 remains the same. 4366 The exporter value is computed as: 4368 TLS-Exporter(label, context_value, key_length) = 4369 HKDF-Expand-Label(Derive-Secret(Secret, label, ""), 4370 "exporter", Hash(context_value), key_length) 4372 Where Secret is either the early_exporter_master_secret or the 4373 exporter_master_secret. Implementations MUST use the 4374 exporter_master_secret unless explicitly specified by the 4375 application. The early_exporter_master_secret is defined for use in 4376 settings where an exporter is needed for 0-RTT data. A separate 4377 interface for the early exporter is RECOMMENDED, especially on a 4378 server where a single interface can make the early exporter 4379 inaccessible. 4381 If no context is provided, the context_value is zero-length. 4382 Consequently, providing no context computes the same value as 4383 providing an empty context. This is a change from previous versions 4384 of TLS where an empty context produced a different output to an 4385 absent context. As of this document's publication, no allocated 4386 exporter label is used both with and without a context. Future 4387 specifications MUST NOT define a use of exporters that permit both an 4388 empty context and no context with the same label. New uses of 4389 exporters SHOULD provide a context in all exporter computations, 4390 though the value could be empty. 4392 Requirements for the format of exporter labels are defined in section 4393 4 of [RFC5705]. 4395 8. 0-RTT and Anti-Replay 4397 As noted in Section 2.3 and Appendix E.5, TLS does not provide 4398 inherent replay protections for 0-RTT data. There are two potential 4399 threats to be concerned with: 4401 - Network attackers who mount a replay attack by simply duplicating 4402 a flight of 0-RTT data. 4404 - Network attackers who take advantage of client retry behavior to 4405 arrange for the server to receive multiple copies of an 4406 application message. This threat already exists to some extent 4407 because clients that value robustness respond to network errors by 4408 attempting to retry requests. However, 0-RTT adds an additional 4409 dimension for any server system which does not maintain globally 4410 consistent server state. Specifically, if a server system has 4411 multiple zones where tickets from zone A will not be accepted in 4412 zone B, then an attacker can duplicate a ClientHello and early 4413 data intended for A to both A and B. At A, the data will be 4414 accepted in 0-RTT, but at B the server will reject 0-RTT data and 4415 instead force a full handshake. If the attacker blocks the 4416 ServerHello from A, then the client will complete the handshake 4417 with B and probably retry the request, leading to duplication on 4418 the server system as a whole. 4420 The first class of attack can be prevented by sharing state to 4421 guarantee that the 0-RTT data is accepted at most once. Servers 4422 SHOULD provide that level of replay safety, by implementing one of 4423 the methods described in this section or by equivalent means. It is 4424 understood, however, that due to operational concerns not all 4425 deployments will maintain state at that level. Therefore, in normal 4426 operation, clients will not know which, if any, of these mechanisms 4427 servers actually implement and hence MUST only send early data which 4428 they deem safe to be replayed. 4430 In addition to the direct effects of replays, there is a class of 4431 attacks where even operations normally considered idempotent could be 4432 exploited by a large number of replays (timing attacks, resource 4433 limit exhaustion and others described in Appendix E.5). Those can be 4434 mitigated by ensuring that every 0-RTT payload can be replayed only a 4435 limited number of times. The server MUST ensure that any instance of 4436 it (be it a machine, a thread or any other entity within the relevant 4437 serving infrastructure) would accept 0-RTT for the same 0-RTT 4438 handshake at most once; this limits the number of replays to the 4439 number of server instances in the deployment. Such a guarantee can 4440 be accomplished by locally recording data from recently-received 4441 ClientHellos and rejecting repeats, or by any other method that 4442 provides the same or a stronger guarantee. The "at most once per 4443 server instance" guarantee is a minimum requirement; servers SHOULD 4444 limit 0-RTT replays further when feasible. 4446 The second class of attack cannot be prevented at the TLS layer and 4447 MUST be dealt with by any application. Note that any application 4448 whose clients implement any kind of retry behavior already needs to 4449 implement some sort of anti-replay defense. 4451 8.1. Single-Use Tickets 4453 The simplest form of anti-replay defense is for the server to only 4454 allow each session ticket to be used once. For instance, the server 4455 can maintain a database of all outstanding valid tickets; deleting 4456 each ticket from the database as it is used. If an unknown ticket is 4457 provided, the server would then fall back to a full handshake. 4459 If the tickets are not self-contained but rather are database keys, 4460 and the corresponding PSKs are deleted upon use, then connections 4461 established using one PSK enjoy forward secrecy. This improves 4462 security for all 0-RTT data and PSK usage when PSK is used without 4463 (EC)DHE. 4465 Because this mechanism requires sharing the session database between 4466 server nodes in environments with multiple distributed servers, it 4467 may be hard to achieve high rates of successful PSK 0-RTT connections 4468 when compared to self-encrypted tickets. Unlike session databases, 4469 session tickets can successfully do PSK-based session establishment 4470 even without consistent storage, though when 0-RTT is allowed they 4471 still require consistent storage for anti-replay of 0-RTT data, as 4472 detailed in the following section. 4474 8.2. Client Hello Recording 4476 An alternative form of anti-replay is to record a unique value 4477 derived from the ClientHello (generally either the random value or 4478 the PSK binder) and reject duplicates. Recording all ClientHellos 4479 causes state to grow without bound, but a server can instead record 4480 ClientHellos within a given time window and use the 4481 "obfuscated_ticket_age" to ensure that tickets aren't reused outside 4482 that window. 4484 In order to implement this, when a ClientHello is received, the 4485 server first verifies the PSK binder as described Section 4.2.11. It 4486 then computes the expected_arrival_time as described in the next 4487 section and rejects 0-RTT if it is outside the recording window, 4488 falling back to the 1-RTT handshake. 4490 If the expected arrival time is in the window, then the server checks 4491 to see if it has recorded a matching ClientHello. If one is found, 4492 it either aborts the handshake with an "illegal_parameter" alert or 4493 accepts the PSK but reject 0-RTT. If no matching ClientHello is 4494 found, then it accepts 0-RTT and then stores the ClientHello for as 4495 long as the expected_arrival_time is inside the window. Servers MAY 4496 also implement data stores with false positives, such as Bloom 4497 filters, in which case they MUST respond to apparent replay by 4498 rejecting 0-RTT but MUST NOT abort the handshake. 4500 The server MUST derive the storage key only from validated sections 4501 of the ClientHello. If the ClientHello contains multiple PSK 4502 identities, then an attacker can create multiple ClientHellos with 4503 different binder values for the less-preferred identity on the 4504 assumption that the server will not verify it, as recommended by 4505 Section 4.2.11. I.e., if the client sends PSKs A and B but the 4506 server prefers A, then the attacker can change the binder for B 4507 without affecting the binder for A. This will cause the ClientHello 4508 to be accepted, and may cause side effects such as replay cache 4509 pollution, although any 0-RTT data will not be decryptable because it 4510 will use different keys. If the validated binder or the 4511 ClientHello.random are used as the storage key, then this attack is 4512 not possible. 4514 Because this mechanism does not require storing all outstanding 4515 tickets, it may be easier to implement in distributed systems with 4516 high rates of resumption and 0-RTT, at the cost of potentially weaker 4517 anti-replay defense because of the difficulty of reliably storing and 4518 retrieving the received ClientHello messages. In many such systems, 4519 it is impractical to have globally consistent storage of all the 4520 received ClientHellos. In this case, the best anti-replay protection 4521 is provided by having a single storage zone be authoritative for a 4522 given ticket and refusing 0-RTT for that ticket in any other zone. 4523 This approach prevents simple replay by the attacker because only one 4524 zone will accept 0-RTT data. A weaker design is to implement 4525 separate storage for each zone but allow 0-RTT in any zone. This 4526 approach limits the number of replays to once per zone. Application 4527 message duplication of course remains possible with either design. 4529 When implementations are freshly started, they SHOULD reject 0-RTT as 4530 long as any portion of their recording window overlaps the startup 4531 time. Otherwise, they run the risk of accepting replays which were 4532 originally sent during that period. 4534 Note: If the client's clock is running much faster than the server's 4535 then a ClientHello may be received that is outside the window in the 4536 future, in which case it might be accepted for 1-RTT, causing a 4537 client retry, and then acceptable later for 0-RTT. This is another 4538 variant of the second form of attack described above. 4540 8.3. Freshness Checks 4542 Because the ClientHello indicates the time at which the client sent 4543 it, it is possible to efficiently determine whether a ClientHello was 4544 likely sent reasonably recently and only accept 0-RTT for such a 4545 ClientHello, otherwise falling back to a 1-RTT handshake. This is 4546 necessary for the ClientHello storage mechanism described in 4547 Section 8.2 because otherwise the server needs to store an unlimited 4548 number of ClientHellos and is a useful optimization for single-use 4549 tickets because it allows efficient rejection of ClientHellos which 4550 cannot be used for 0-RTT. 4552 In order to implement this mechanism, a server needs to store the 4553 time that the server generated the session ticket, offset by an 4554 estimate of the round trip time between client and server. I.e., 4556 adjusted_creation_time = creation_time + estimated_RTT 4558 This value can be encoded in the ticket, thus avoiding the need to 4559 keep state for each outstanding ticket. The server can determine the 4560 client's view of the age of the ticket by subtracting the ticket's 4561 "ticket_age_add value" from the "obfuscated_ticket_age" parameter in 4562 the client's "pre_shared_key" extension. The server can determine 4563 the "expected arrival time" of the ClientHello as: 4565 expected_arrival_time = adjusted_creation_time + clients_ticket_age 4567 When a new ClientHello is received, the expected_arrival_time is then 4568 compared against the current server wall clock time and if they 4569 differ by more than a certain amount, 0-RTT is rejected, though the 4570 1-RTT handshake can be allowed to complete. 4572 There are several potential sources of error that might cause 4573 mismatches between the expected arrival time and the measured time. 4574 Variations in client and server clock rates are likely to be minimal, 4575 though potentially with gross time corrections. Network propagation 4576 delays are the most likely causes of a mismatch in legitimate values 4577 for elapsed time. Both the NewSessionTicket and ClientHello messages 4578 might be retransmitted and therefore delayed, which might be hidden 4579 by TCP. For clients on the Internet, this implies windows on the 4580 order of ten seconds to account for errors in clocks and variations 4581 in measurements; other deployment scenarios may have different needs. 4582 Clock skew distributions are not symmetric, so the optimal tradeoff 4583 may involve an asymmetric range of permissible mismatch values. 4585 Note that freshness checking alone is not sufficient to prevent 4586 replays because it does not detect them during the error window, 4587 which, depending on bandwidth and system capacity could include 4588 billions of replays in real-world settings. In addition, this 4589 freshness checking is only done at the time the ClientHello is 4590 received, and not when later early application data records are 4591 received. After early data is accepted, records may continue to be 4592 streamed to the server over a longer time period. 4594 9. Compliance Requirements 4596 9.1. Mandatory-to-Implement Cipher Suites 4598 In the absence of an application profile standard specifying 4599 otherwise, a TLS-compliant application MUST implement the 4600 TLS_AES_128_GCM_SHA256 [GCM] cipher suite and SHOULD implement the 4601 TLS_AES_256_GCM_SHA384 [GCM] and TLS_CHACHA20_POLY1305_SHA256 4602 [RFC7539] cipher suites. (see Appendix B.4) 4604 A TLS-compliant application MUST support digital signatures with 4605 rsa_pkcs1_sha256 (for certificates), rsa_pss_sha256 (for 4606 CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A 4607 TLS-compliant application MUST support key exchange with secp256r1 4608 (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748]. 4610 9.2. Mandatory-to-Implement Extensions 4612 In the absence of an application profile standard specifying 4613 otherwise, a TLS-compliant application MUST implement the following 4614 TLS extensions: 4616 - Supported Versions ("supported_versions"; Section 4.2.1) 4618 - Cookie ("cookie"; Section 4.2.2) 4620 - Signature Algorithms ("signature_algorithms"; Section 4.2.3) 4622 - Negotiated Groups ("supported_groups"; Section 4.2.7) 4624 - Key Share ("key_share"; Section 4.2.8) 4626 - Server Name Indication ("server_name"; Section 3 of [RFC6066]) 4628 All implementations MUST send and use these extensions when offering 4629 applicable features: 4631 - "supported_versions" is REQUIRED for all ClientHello, ServerHello 4632 and HelloRetryRequest messages. 4634 - "signature_algorithms" is REQUIRED for certificate authentication. 4636 - "supported_groups" is REQUIRED for ClientHello messages using DHE 4637 or ECDHE key exchange. 4639 - "key_share" is REQUIRED for DHE or ECDHE key exchange. 4641 - "pre_shared_key" is REQUIRED for PSK key agreement. 4643 A client is considered to be attempting to negotiate using this 4644 specification if the ClientHello contains a "supported_versions" 4645 extension with 0x0304 as the highest version number contained in its 4646 body. Such a ClientHello message MUST meet the following 4647 requirements: 4649 - If not containing a "pre_shared_key" extension, it MUST contain 4650 both a "signature_algorithms" extension and a "supported_groups" 4651 extension. 4653 - If containing a "supported_groups" extension, it MUST also contain 4654 a "key_share" extension, and vice versa. An empty 4655 KeyShare.client_shares vector is permitted. 4657 Servers receiving a ClientHello which does not conform to these 4658 requirements MUST abort the handshake with a "missing_extension" 4659 alert. 4661 Additionally, all implementations MUST support use of the 4662 "server_name" extension with applications capable of using it. 4663 Servers MAY require clients to send a valid "server_name" extension. 4664 Servers requiring this extension SHOULD respond to a ClientHello 4665 lacking a "server_name" extension by terminating the connection with 4666 a "missing_extension" alert. 4668 10. Security Considerations 4670 Security issues are discussed throughout this memo, especially in 4671 Appendix C, Appendix D, and Appendix E. 4673 11. IANA Considerations 4675 This document uses several registries that were originally created in 4676 [RFC4346]. IANA has updated these to reference this document. The 4677 registries and their allocation policies are below: 4679 - TLS Cipher Suite Registry: values with the first byte in the range 4680 0-254 (decimal) are assigned via Specification Required [RFC5226]. 4681 Values with the first byte 255 (decimal) are reserved for Private 4682 Use [RFC5226]. 4684 IANA [SHALL add/has added] the cipher suites listed in 4685 Appendix B.4 to the registry. The "Value" and "Description" 4686 columns are taken from the table. The "DTLS-OK" and "Recommended" 4687 columns are both marked as "Yes" for each new cipher suite. 4688 [[This assumes [I-D.ietf-tls-iana-registry-updates] has been 4689 applied.]] 4691 - TLS ContentType Registry: Future values are allocated via 4692 Standards Action [RFC5226]. 4694 - TLS Alert Registry: Future values are allocated via Standards 4695 Action [RFC5226]. IANA [SHALL update/has updated] this registry 4696 to include values for "missing_extension" and 4697 "certificate_required". 4699 - TLS HandshakeType Registry: Future values are allocated via 4700 Standards Action [RFC5226]. IANA [SHALL update/has updated] this 4701 registry to rename item 4 from "NewSessionTicket" to 4702 "new_session_ticket" and to add the 4703 "hello_retry_request_RESERVED", "encrypted_extensions", 4704 "end_of_early_data", "key_update", and "message_hash" values. 4706 This document also uses the TLS ExtensionType Registry originally 4707 created in [RFC4366]. IANA has updated it to reference this 4708 document. The registry and its allocation policy is listed below: 4710 - IANA [SHALL update/has updated] this registry to include the 4711 "key_share", "pre_shared_key", "psk_key_exchange_modes", 4712 "early_data", "cookie", "supported_versions", 4713 "certificate_authorities", "oid_filters", and 4714 "post_handshake_auth" extensions with the values defined in this 4715 document and the Recommended value of "Yes". 4717 - IANA [SHALL update/has updated] this registry to include a "TLS 4718 1.3" column which lists the messages in which the extension may 4719 appear. This column [SHALL be/has been] initially populated from 4720 the table in Section 4.2 with any extension not listed there 4721 marked as "-" to indicate that it is not used by TLS 1.3. 4723 In addition, this document defines a new registry to be maintained by 4724 IANA: 4726 - TLS SignatureScheme Registry: Values with the first byte in the 4727 range 0-253 (decimal) are assigned via Specification Required 4728 [RFC5226]. Values with the first byte 254 or 255 (decimal) are 4729 reserved for Private Use [RFC5226]. Values with the first byte in 4730 the range 0-6 or with the second byte in the range 0-3 that are 4731 not currently allocated are reserved for backwards compatibility. 4732 This registry SHALL have a "Recommended" column. The registry 4733 [shall be/ has been] initially populated with the values described 4734 in Section 4.2.3. The following values SHALL be marked as 4735 "Recommended": ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, 4736 rsa_pss_sha256, rsa_pss_sha384, rsa_pss_sha512, ed25519. 4738 12. References 4740 12.1. Normative References 4742 [DH] Diffie, W. and M. Hellman, "New Directions in 4743 Cryptography", IEEE Transactions on Information Theory, 4744 V.IT-22 n.6 , June 1977. 4746 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 4747 Operation: Galois/Counter Mode (GCM) and GMAC", 4748 NIST Special Publication 800-38D, November 2007. 4750 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4751 Hashing for Message Authentication", RFC 2104, 4752 DOI 10.17487/RFC2104, February 1997, 4753 . 4755 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4756 Requirement Levels", BCP 14, RFC 2119, 4757 DOI 10.17487/RFC2119, March 1997, 4758 . 4760 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4761 IANA Considerations Section in RFCs", RFC 5226, 4762 DOI 10.17487/RFC5226, May 2008, 4763 . 4765 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4766 Housley, R., and W. Polk, "Internet X.509 Public Key 4767 Infrastructure Certificate and Certificate Revocation List 4768 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4769 . 4771 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 4772 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 4773 March 2010, . 4775 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 4776 Key Derivation Function (HKDF)", RFC 5869, 4777 DOI 10.17487/RFC5869, May 2010, 4778 . 4780 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4781 Extensions: Extension Definitions", RFC 6066, 4782 DOI 10.17487/RFC6066, January 2011, 4783 . 4785 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4786 Transport Layer Security (TLS)", RFC 6655, 4787 DOI 10.17487/RFC6655, July 2012, 4788 . 4790 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 4791 Galperin, S., and C. Adams, "X.509 Internet Public Key 4792 Infrastructure Online Certificate Status Protocol - OCSP", 4793 RFC 6960, DOI 10.17487/RFC6960, June 2013, 4794 . 4796 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 4797 Multiple Certificate Status Request Extension", RFC 6961, 4798 DOI 10.17487/RFC6961, June 2013, 4799 . 4801 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 4802 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 4803 . 4805 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4806 Algorithm (DSA) and Elliptic Curve Digital Signature 4807 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4808 2013, . 4810 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 4811 "Transport Layer Security (TLS) Application-Layer Protocol 4812 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 4813 July 2014, . 4815 [RFC7507] Moeller, B. and A. Langley, "TLS Fallback Signaling Cipher 4816 Suite Value (SCSV) for Preventing Protocol Downgrade 4817 Attacks", RFC 7507, DOI 10.17487/RFC7507, April 2015, 4818 . 4820 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 4821 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 4822 . 4824 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 4825 for Security", RFC 7748, DOI 10.17487/RFC7748, January 4826 2016, . 4828 [RFC7919] Gillmor, D., "Negotiated Finite Field Diffie-Hellman 4829 Ephemeral Parameters for Transport Layer Security (TLS)", 4830 RFC 7919, DOI 10.17487/RFC7919, August 2016, 4831 . 4833 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 4834 "PKCS #1: RSA Cryptography Specifications Version 2.2", 4835 RFC 8017, DOI 10.17487/RFC8017, November 2016, 4836 . 4838 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 4839 Signature Algorithm (EdDSA)", RFC 8032, 4840 DOI 10.17487/RFC8032, January 2017, 4841 . 4843 [SHS] Dang, Q., "Secure Hash Standard", National Institute of 4844 Standards and Technology report, 4845 DOI 10.6028/nist.fips.180-4, July 2015. 4847 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 4848 Specification of Basic Encoding Rules (BER), Canonical 4849 Encoding Rules (CER) and Distinguished Encoding Rules 4850 (DER)", ISO/IEC 8825-1:2002, 2002. 4852 [X962] ANSI, "Public Key Cryptography For The Financial Services 4853 Industry: The Elliptic Curve Digital Signature Algorithm 4854 (ECDSA)", ANSI X9.62, 1998. 4856 12.2. Informative References 4858 [AEAD-LIMITS] 4859 Luykx, A. and K. Paterson, "Limits on Authenticated 4860 Encryption Use in TLS", 2016, 4861 . 4863 [BBFKZG16] 4864 Bhargavan, K., Brzuska, C., Fournet, C., Kohlweiss, M., 4865 Zanella-Beguelin, S., and M. Green, "Downgrade Resilience 4866 in Key-Exchange Protocols", Proceedings of IEEE Symposium 4867 on Security and Privacy (Oakland) 2016 , 2016. 4869 [BBK17] Bhargavan, K., Blanchet, B., and N. Kobeissi, "Verified 4870 Models and Reference Implementations for the TLS 1.3 4871 Standard Candidate", Proceedings of IEEE Symposium on 4872 Security and Privacy (Oakland) 2017 , 2017. 4874 [BDFKPPRSZZ16] 4875 Bhargavan, K., Delignat-Lavaud, A., Fournet, C., 4876 Kohlweiss, M., Pan, J., Protzenko, J., Rastogi, A., Swamy, 4877 N., Zanella-Beguelin, S., and J. Zinzindohoue, 4878 "Implementing and Proving the TLS 1.3 Record Layer", 4879 Proceedings of IEEE Symposium on Security and Privacy 4880 (Oakland) 2017 , December 2016, 4881 . 4883 [BMMT15] Badertscher, C., Matt, C., Maurer, U., and B. Tackmann, 4884 "Augmented Secure Channels and the Goal of the TLS 1.3 4885 Record Layer", ProvSec 2015 , September 2015, 4886 . 4888 [BT16] Bellare, M. and B. Tackmann, "The Multi-User Security of 4889 Authenticated Encryption: AES-GCM in TLS 1.3", Proceedings 4890 of CRYPTO 2016 , 2016, . 4892 [CCG16] Cohn-Gordon, K., Cremers, C., and L. Garratt, "On Post- 4893 Compromise Security", IEEE Computer Security Foundations 4894 Symposium , 2015. 4896 [CHECKOWAY] 4897 Checkoway, S., Shacham, H., Maskiewicz, J., Garman, C., 4898 Fried, J., Cohney, S., Green, M., Heninger, N., Weinmann, 4899 R., and E. Rescorla, "A Systematic Analysis of the Juniper 4900 Dual EC Incident", Proceedings of the 2016 ACM SIGSAC 4901 Conference on Computer and Communications Security 4902 - CCS'16, DOI 10.1145/2976749.2978395, 2016. 4904 [CHHSV17] Cremers, C., Horvat, M., Hoyland, J., van der Merwe, T., 4905 and S. Scott, "Awkward Handshake: Possible mismatch of 4906 client/server view on client authentication in post- 4907 handshake mode in Revision 18", 2017, 4908 . 4911 [CHSV16] Cremers, C., Horvat, M., Scott, S., and T. van der Merwe, 4912 "Automated Analysis and Verification of TLS 1.3: 0-RTT, 4913 Resumption and Delayed Authentication", Proceedings of 4914 IEEE Symposium on Security and Privacy (Oakland) 2016 , 4915 2016, . 4917 [CK01] Canetti, R. and H. Krawczyk, "Analysis of Key-Exchange 4918 Protocols and Their Use for Building Secure Channels", 4919 Proceedings of Eurocrypt 2001 , 2001. 4921 [CLINIC] Miller, B., Huang, L., Joseph, A., and J. Tygar, "I Know 4922 Why You Went to the Clinic: Risks and Realization of HTTPS 4923 Traffic Analysis", Privacy Enhancing Technologies pp. 4924 143-163, DOI 10.1007/978-3-319-08506-7_8, 2014. 4926 [DFGS15] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 4927 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 4928 Pre-shared Key Handshake Protocol", Proceedings of ACM CCS 4929 2015 , 2015, . 4931 [DFGS16] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 4932 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 4933 Pre-shared Key Handshake Protocol", TRON 2016 , 2016, 4934 . 4936 [DOW92] Diffie, W., van Oorschot, P., and M. Wiener, 4937 ""Authentication and authenticated key exchanges"", 4938 Designs, Codes and Cryptography , 1992. 4940 [DSS] National Institute of Standards and Technology, U.S. 4941 Department of Commerce, "Digital Signature Standard, 4942 version 4", NIST FIPS PUB 186-4, 2013. 4944 [ECDSA] American National Standards Institute, "Public Key 4945 Cryptography for the Financial Services Industry: The 4946 Elliptic Curve Digital Signature Algorithm (ECDSA)", 4947 ANSI ANS X9.62-2005, November 2005. 4949 [FG17] Fischlin, M. and F. Guenther, "Replay Attacks on Zero 4950 Round-Trip Time: The Case of the TLS 1.3 Handshake 4951 Candidates", Proceedings of Euro S"P 2017 , 2017, 4952 . 4954 [FGSW16] Fischlin, M., Guenther, F., Schmidt, B., and B. Warinschi, 4955 "Key Confirmation in Key Exchange: A Formal Treatment and 4956 Implications for TLS 1.3", Proceedings of IEEE Symposium 4957 on Security and Privacy (Oakland) 2016 , 2016, 4958 . 4960 [FW15] Florian Weimer, ., "Factoring RSA Keys With TLS Perfect 4961 Forward Secrecy", September 2015. 4963 [HCJ16] Husak, M., Čermak, M., Jirsik, T., and P. 4964 Čeleda, "HTTPS traffic analysis and client 4965 identification using passive SSL/TLS fingerprinting", 4966 EURASIP Journal on Information Security Vol. 2016, 4967 DOI 10.1186/s13635-016-0030-7, February 2016. 4969 [HGFS15] Hlauschek, C., Gruber, M., Fankhauser, F., and C. Schanes, 4970 "Prying Open Pandora's Box: KCI Attacks against TLS", 4971 Proceedings of USENIX Workshop on Offensive Technologies , 4972 2015. 4974 [I-D.ietf-tls-iana-registry-updates] 4975 Salowey, J. and S. Turner, "IANA Registry Updates for TLS 4976 and DTLS", draft-ietf-tls-iana-registry-updates-02 (work 4977 in progress), October 2017. 4979 [I-D.ietf-tls-tls13-vectors] 4980 Thomson, M., "Example Handshake Traces for TLS 1.3", 4981 draft-ietf-tls-tls13-vectors-02 (work in progress), July 4982 2017. 4984 [IEEE1363] 4985 IEEE, "Standard Specifications for Public Key 4986 Cryptography", IEEE 1363 , 2000. 4988 [KEYAGREEMENT] 4989 Barker, E., Chen, L., Roginsky, A., and M. Smid, 4990 "Recommendation for Pair-Wise Key Establishment Schemes 4991 Using Discrete Logarithm Cryptography", National Institute 4992 of Standards and Technology report, 4993 DOI 10.6028/nist.sp.800-56ar2, May 2013. 4995 [Kraw10] Krawczyk, H., "Cryptographic Extraction and Key 4996 Derivation: The HKDF Scheme", Proceedings of CRYPTO 2010 , 4997 2010, . 4999 [Kraw16] Krawczyk, H., "A Unilateral-to-Mutual Authentication 5000 Compiler for Key Exchange (with Applications to Client 5001 Authentication in TLS 1.3", Proceedings of ACM CCS 2016 , 5002 2016, . 5004 [KW16] Krawczyk, H. and H. Wee, "The OPTLS Protocol and TLS 1.3", 5005 Proceedings of Euro S"P 2016 , 2016, 5006 . 5008 [LXZFH16] Li, X., Xu, J., Feng, D., Zhang, Z., and H. Hu, "Multiple 5009 Handshakes Security of TLS 1.3 Candidates", Proceedings of 5010 IEEE Symposium on Security and Privacy (Oakland) 2016 , 5011 2016, . 5013 [Mac17] MacCarthaigh, C., "Security Review of TLS1.3 0-RTT", 2017, 5014 . 5016 [PSK-FINISHED] 5017 Cremers, C., Horvat, M., van der Merwe, T., and S. Scott, 5018 "Revision 10: possible attack if client authentication is 5019 allowed during PSK", 2015, . 5022 [REKEY] Abdalla, M. and M. Bellare, "Increasing the Lifetime of a 5023 Key: A Comparative Analysis of the Security of Re-keying 5024 Techniques", ASIACRYPT2000 , October 2000. 5026 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 5027 Text on Security Considerations", BCP 72, RFC 3552, 5028 DOI 10.17487/RFC3552, July 2003, 5029 . 5031 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 5032 "Randomness Requirements for Security", BCP 106, RFC 4086, 5033 DOI 10.17487/RFC4086, June 2005, 5034 . 5036 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 5037 (TLS) Protocol Version 1.1", RFC 4346, 5038 DOI 10.17487/RFC4346, April 2006, 5039 . 5041 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 5042 and T. Wright, "Transport Layer Security (TLS) 5043 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006, 5044 . 5046 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 5047 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 5048 for Transport Layer Security (TLS)", RFC 4492, 5049 DOI 10.17487/RFC4492, May 2006, 5050 . 5052 [RFC4681] Santesson, S., Medvinsky, A., and J. Ball, "TLS User 5053 Mapping Extension", RFC 4681, DOI 10.17487/RFC4681, 5054 October 2006, . 5056 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 5057 "Transport Layer Security (TLS) Session Resumption without 5058 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 5059 January 2008, . 5061 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 5062 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 5063 . 5065 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 5066 (TLS) Protocol Version 1.2", RFC 5246, 5067 DOI 10.17487/RFC5246, August 2008, 5068 . 5070 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 5071 Security (DTLS) Extension to Establish Keys for the Secure 5072 Real-time Transport Protocol (SRTP)", RFC 5764, 5073 DOI 10.17487/RFC5764, May 2010, 5074 . 5076 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 5077 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010, 5078 . 5080 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys 5081 for Transport Layer Security (TLS) Authentication", 5082 RFC 6091, DOI 10.17487/RFC6091, February 2011, 5083 . 5085 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 5086 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176, March 5087 2011, . 5089 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 5090 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 5091 January 2012, . 5093 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 5094 Layer Security (TLS) and Datagram Transport Layer Security 5095 (DTLS) Heartbeat Extension", RFC 6520, 5096 DOI 10.17487/RFC6520, February 2012, 5097 . 5099 [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with 5100 Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April 5101 2012, . 5103 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 5104 Protocol (HTTP/1.1): Message Syntax and Routing", 5105 RFC 7230, DOI 10.17487/RFC7230, June 2014, 5106 . 5108 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 5109 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 5110 Transport Layer Security (TLS) and Datagram Transport 5111 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 5112 June 2014, . 5114 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 5115 DOI 10.17487/RFC7465, February 2015, 5116 . 5118 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 5119 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 5120 DOI 10.17487/RFC7568, June 2015, 5121 . 5123 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 5124 Langley, A., and M. Ray, "Transport Layer Security (TLS) 5125 Session Hash and Extended Master Secret Extension", 5126 RFC 7627, DOI 10.17487/RFC7627, September 2015, 5127 . 5129 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello 5130 Padding Extension", RFC 7685, DOI 10.17487/RFC7685, 5131 October 2015, . 5133 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 5134 (TLS) Cached Information Extension", RFC 7924, 5135 DOI 10.17487/RFC7924, July 2016, 5136 . 5138 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 5139 Obtaining Digital Signatures and Public-Key 5140 Cryptosystems", Communications of the ACM v. 21, n. 2, pp. 5141 120-126., February 1978. 5143 [SIGMA] Krawczyk, H., "SIGMA: the 'SIGn-and-MAc' approach to 5144 authenticated Diffie-Hellman and its use in the IKE 5145 protocols", Proceedings of CRYPTO 2003 , 2003. 5147 [SLOTH] Bhargavan, K. and G. Leurent, "Transcript Collision 5148 Attacks: Breaking Authentication in TLS, IKE, and SSH", 5149 Network and Distributed System Security Symposium (NDSS 5150 2016) , 2016. 5152 [SSL2] Hickman, K., "The SSL Protocol", February 1995. 5154 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 5155 Protocol", November 1996. 5157 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 5158 practical", USENIX Security Symposium, 2003. 5160 [X501] "Information Technology - Open Systems Interconnection - 5161 The Directory: Models", ITU-T X.501, 1993. 5163 12.3. URIs 5165 [1] mailto:tls@ietf.org 5167 [2] https://www.ietf.org/mailman/listinfo/tls 5169 [3] https://www.ietf.org/mail-archive/web/tls/current/index.html 5171 Appendix A. State Machine 5173 This section provides a summary of the legal state transitions for 5174 the client and server handshakes. State names (in all capitals, 5175 e.g., START) have no formal meaning but are provided for ease of 5176 comprehension. Actions which are taken only in certain circumstances 5177 are indicated in []. The notation "K_{send,recv} = foo" means "set 5178 the send/recv key to the given key". 5180 A.1. Client 5182 START <----+ 5183 Send ClientHello | | Recv HelloRetryRequest 5184 [K_send = early data] | | 5185 v | 5186 / WAIT_SH ----+ 5187 | | Recv ServerHello 5188 | | K_recv = handshake 5189 Can | V 5190 send | WAIT_EE 5191 early | | Recv EncryptedExtensions 5192 data | +--------+--------+ 5193 | Using | | Using certificate 5194 | PSK | v 5195 | | WAIT_CERT_CR 5196 | | Recv | | Recv CertificateRequest 5197 | | Certificate | v 5198 | | | WAIT_CERT 5199 | | | | Recv Certificate 5200 | | v v 5201 | | WAIT_CV 5202 | | | Recv CertificateVerify 5203 | +> WAIT_FINISHED <+ 5204 | | Recv Finished 5205 \ | [Send EndOfEarlyData] 5206 | K_send = handshake 5207 | [Send Certificate [+ CertificateVerify]] 5208 Can send | Send Finished 5209 app data --> | K_send = K_recv = application 5210 after here v 5211 CONNECTED 5213 Note that with the transitions as shown above, clients may send 5214 alerts that derive from post-ServerHello messages in the clear or 5215 with the early data keys. If clients need to send such alerts, they 5216 SHOULD first rekey to the handshake keys if possible. 5218 A.2. Server 5220 START <-----+ 5221 Recv ClientHello | | Send HelloRetryRequest 5222 v | 5223 RECVD_CH ----+ 5224 | Select parameters 5225 v 5226 NEGOTIATED 5227 | Send ServerHello 5228 | K_send = handshake 5229 | Send EncryptedExtensions 5230 | [Send CertificateRequest] 5231 Can send | [Send Certificate + CertificateVerify] 5232 app data | Send Finished 5233 after --> | K_send = application 5234 here +--------+--------+ 5235 No 0-RTT | | 0-RTT 5236 | | 5237 K_recv = handshake | | K_recv = early data 5238 [Skip decrypt errors] | +------> WAIT_EOED -+ 5239 | | Recv | | Recv EndOfEarlyData 5240 | | early data | | K_recv = handshake 5241 | +------------+ | 5242 | | 5243 +> WAIT_FLIGHT2 <--------+ 5244 | 5245 +--------+--------+ 5246 No auth | | Client auth 5247 | | 5248 | v 5249 | WAIT_CERT 5250 | Recv | | Recv Certificate 5251 | empty | v 5252 | Certificate | WAIT_CV 5253 | | | Recv 5254 | v | CertificateVerify 5255 +-> WAIT_FINISHED <---+ 5256 | Recv Finished 5257 | K_recv = application 5258 v 5259 CONNECTED 5261 Appendix B. Protocol Data Structures and Constant Values 5263 This section describes protocol types and constants. Values listed 5264 as _RESERVED were used in previous versions of TLS and are listed 5265 here for completeness. TLS 1.3 implementations MUST NOT send them 5266 but might receive them from older TLS implementations. 5268 B.1. Record Layer 5270 enum { 5271 invalid(0), 5272 change_cipher_spec(20), 5273 alert(21), 5274 handshake(22), 5275 application_data(23), 5276 (255) 5277 } ContentType; 5279 struct { 5280 ContentType type; 5281 ProtocolVersion legacy_record_version; 5282 uint16 length; 5283 opaque fragment[TLSPlaintext.length]; 5284 } TLSPlaintext; 5286 struct { 5287 opaque content[TLSPlaintext.length]; 5288 ContentType type; 5289 uint8 zeros[length_of_padding]; 5290 } TLSInnerPlaintext; 5292 struct { 5293 ContentType opaque_type = application_data; /* 23 */ 5294 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */ 5295 uint16 length; 5296 opaque encrypted_record[TLSCiphertext.length]; 5297 } TLSCiphertext; 5299 B.2. Alert Messages 5300 enum { warning(1), fatal(2), (255) } AlertLevel; 5302 enum { 5303 close_notify(0), 5304 unexpected_message(10), 5305 bad_record_mac(20), 5306 decryption_failed_RESERVED(21), 5307 record_overflow(22), 5308 decompression_failure_RESERVED(30), 5309 handshake_failure(40), 5310 no_certificate_RESERVED(41), 5311 bad_certificate(42), 5312 unsupported_certificate(43), 5313 certificate_revoked(44), 5314 certificate_expired(45), 5315 certificate_unknown(46), 5316 illegal_parameter(47), 5317 unknown_ca(48), 5318 access_denied(49), 5319 decode_error(50), 5320 decrypt_error(51), 5321 export_restriction_RESERVED(60), 5322 protocol_version(70), 5323 insufficient_security(71), 5324 internal_error(80), 5325 inappropriate_fallback(86), 5326 user_canceled(90), 5327 no_renegotiation_RESERVED(100), 5328 missing_extension(109), 5329 unsupported_extension(110), 5330 certificate_unobtainable(111), 5331 unrecognized_name(112), 5332 bad_certificate_status_response(113), 5333 bad_certificate_hash_value(114), 5334 unknown_psk_identity(115), 5335 certificate_required(116), 5336 no_application_protocol(120), 5337 (255) 5338 } AlertDescription; 5340 struct { 5341 AlertLevel level; 5342 AlertDescription description; 5343 } Alert; 5345 B.3. Handshake Protocol 5347 enum { 5348 hello_request_RESERVED(0), 5349 client_hello(1), 5350 server_hello(2), 5351 hello_verify_request_RESERVED(3), 5352 new_session_ticket(4), 5353 end_of_early_data(5), 5354 hello_retry_request_RESERVED(6), 5355 encrypted_extensions(8), 5356 certificate(11), 5357 server_key_exchange_RESERVED(12), 5358 certificate_request(13), 5359 server_hello_done_RESERVED(14), 5360 certificate_verify(15), 5361 client_key_exchange_RESERVED(16), 5362 finished(20), 5363 key_update(24), 5364 message_hash(254), 5365 (255) 5366 } HandshakeType; 5368 struct { 5369 HandshakeType msg_type; /* handshake type */ 5370 uint24 length; /* bytes in message */ 5371 select (Handshake.msg_type) { 5372 case client_hello: ClientHello; 5373 case server_hello: ServerHello; 5374 case end_of_early_data: EndOfEarlyData; 5375 case encrypted_extensions: EncryptedExtensions; 5376 case certificate_request: CertificateRequest; 5377 case certificate: Certificate; 5378 case certificate_verify: CertificateVerify; 5379 case finished: Finished; 5380 case new_session_ticket: NewSessionTicket; 5381 case key_update: KeyUpdate; 5382 }; 5383 } Handshake; 5385 B.3.1. Key Exchange Messages 5387 uint16 ProtocolVersion; 5388 opaque Random[32]; 5390 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 5392 struct { 5393 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 5394 Random random; 5395 opaque legacy_session_id<0..32>; 5396 CipherSuite cipher_suites<2..2^16-2>; 5397 opaque legacy_compression_methods<1..2^8-1>; 5398 Extension extensions<8..2^16-1>; 5399 } ClientHello; 5401 struct { 5402 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 5403 Random random; 5404 opaque legacy_session_id_echo<0..32>; 5405 CipherSuite cipher_suite; 5406 uint8 legacy_compression_method = 0; 5407 Extension extensions<6..2^16-1>; 5408 } ServerHello; 5410 struct { 5411 ExtensionType extension_type; 5412 opaque extension_data<0..2^16-1>; 5413 } Extension; 5415 enum { 5416 server_name(0), /* RFC 6066 */ 5417 max_fragment_length(1), /* RFC 6066 */ 5418 status_request(5), /* RFC 6066 */ 5419 supported_groups(10), /* RFC 4492, 7919 */ 5420 signature_algorithms(13), /* [[this document]] */ 5421 use_srtp(14), /* RFC 5764 */ 5422 heartbeat(15), /* RFC 6520 */ 5423 application_layer_protocol_negotiation(16), /* RFC 7301 */ 5424 signed_certificate_timestamp(18), /* RFC 6962 */ 5425 client_certificate_type(19), /* RFC 7250 */ 5426 server_certificate_type(20), /* RFC 7250 */ 5427 padding(21), /* RFC 7685 */ 5428 key_share(40), /* [[this document]] */ 5429 pre_shared_key(41), /* [[this document]] */ 5430 early_data(42), /* [[this document]] */ 5431 supported_versions(43), /* [[this document]] */ 5432 cookie(44), /* [[this document]] */ 5433 psk_key_exchange_modes(45), /* [[this document]] */ 5434 certificate_authorities(47), /* [[this document]] */ 5435 oid_filters(48), /* [[this document]] */ 5436 post_handshake_auth(49), /* [[this document]] */ 5437 (65535) 5438 } ExtensionType; 5440 struct { 5441 NamedGroup group; 5442 opaque key_exchange<1..2^16-1>; 5443 } KeyShareEntry; 5445 struct { 5446 KeyShareEntry client_shares<0..2^16-1>; 5447 } KeyShareClientHello; 5449 struct { 5450 NamedGroup selected_group; 5451 } KeyShareHelloRetryRequest; 5453 struct { 5454 KeyShareEntry server_share; 5455 } KeyShareServerHello; 5457 struct { 5458 uint8 legacy_form = 4; 5459 opaque X[coordinate_length]; 5460 opaque Y[coordinate_length]; 5461 } UncompressedPointRepresentation; 5463 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 5465 struct { 5466 PskKeyExchangeMode ke_modes<1..255>; 5467 } PskKeyExchangeModes; 5469 struct {} Empty; 5471 struct { 5472 select (Handshake.msg_type) { 5473 case new_session_ticket: uint32 max_early_data_size; 5474 case client_hello: Empty; 5475 case encrypted_extensions: Empty; 5476 }; 5477 } EarlyDataIndication; 5479 struct { 5480 opaque identity<1..2^16-1>; 5481 uint32 obfuscated_ticket_age; 5482 } PskIdentity; 5484 opaque PskBinderEntry<32..255>; 5486 struct { 5487 PskIdentity identities<7..2^16-1>; 5488 PskBinderEntry binders<33..2^16-1>; 5490 } OfferedPsks; 5492 struct { 5493 select (Handshake.msg_type) { 5494 case client_hello: OfferedPsks; 5495 case server_hello: uint16 selected_identity; 5496 }; 5497 } PreSharedKeyExtension; 5499 B.3.1.1. Version Extension 5501 struct { 5502 select (Handshake.msg_type) { 5503 case client_hello: 5504 ProtocolVersion versions<2..254>; 5506 case server_hello: 5507 ProtocolVersion selected_version; 5508 }; 5509 } SupportedVersions; 5511 B.3.1.2. Cookie Extension 5513 struct { 5514 opaque cookie<1..2^16-1>; 5515 } Cookie; 5517 B.3.1.3. Signature Algorithm Extension 5518 enum { 5519 /* RSASSA-PKCS1-v1_5 algorithms */ 5520 rsa_pkcs1_sha256(0x0401), 5521 rsa_pkcs1_sha384(0x0501), 5522 rsa_pkcs1_sha512(0x0601), 5524 /* ECDSA algorithms */ 5525 ecdsa_secp256r1_sha256(0x0403), 5526 ecdsa_secp384r1_sha384(0x0503), 5527 ecdsa_secp521r1_sha512(0x0603), 5529 /* RSASSA-PSS algorithms */ 5530 rsa_pss_sha256(0x0804), 5531 rsa_pss_sha384(0x0805), 5532 rsa_pss_sha512(0x0806), 5534 /* EdDSA algorithms */ 5535 ed25519(0x0807), 5536 ed448(0x0808), 5538 /* Legacy algorithms */ 5539 rsa_pkcs1_sha1(0x0201), 5540 ecdsa_sha1(0x0203), 5542 /* Reserved Code Points */ 5543 obsolete_RESERVED(0x0000..0x0200), 5544 dsa_sha1_RESERVED(0x0202), 5545 obsolete_RESERVED(0x0204..0x0400), 5546 dsa_sha256_RESERVED(0x0402), 5547 obsolete_RESERVED(0x0404..0x0500), 5548 dsa_sha384_RESERVED(0x0502), 5549 obsolete_RESERVED(0x0504..0x0600), 5550 dsa_sha512_RESERVED(0x0602), 5551 obsolete_RESERVED(0x0604..0x06FF), 5552 private_use(0xFE00..0xFFFF), 5553 (0xFFFF) 5554 } SignatureScheme; 5556 struct { 5557 SignatureScheme supported_signature_algorithms<2..2^16-2>; 5558 } SignatureSchemeList; 5560 B.3.1.4. Supported Groups Extension 5561 enum { 5562 unallocated_RESERVED(0x0000), 5564 /* Elliptic Curve Groups (ECDHE) */ 5565 obsolete_RESERVED(0x0001..0x0016), 5566 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 5567 obsolete_RESERVED(0x001A..0x001C), 5568 x25519(0x001D), x448(0x001E), 5570 /* Finite Field Groups (DHE) */ 5571 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102), 5572 ffdhe6144(0x0103), ffdhe8192(0x0104), 5574 /* Reserved Code Points */ 5575 ffdhe_private_use(0x01FC..0x01FF), 5576 ecdhe_private_use(0xFE00..0xFEFF), 5577 obsolete_RESERVED(0xFF01..0xFF02), 5578 (0xFFFF) 5579 } NamedGroup; 5581 struct { 5582 NamedGroup named_group_list<2..2^16-1>; 5583 } NamedGroupList; 5585 Values within "obsolete_RESERVED" ranges are used in previous 5586 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3 5587 implementations. The obsolete curves have various known/theoretical 5588 weaknesses or have had very little usage, in some cases only due to 5589 unintentional server configuration issues. They are no longer 5590 considered appropriate for general use and should be assumed to be 5591 potentially unsafe. The set of curves specified here is sufficient 5592 for interoperability with all currently deployed and properly 5593 configured TLS implementations. 5595 B.3.2. Server Parameters Messages 5596 opaque DistinguishedName<1..2^16-1>; 5598 struct { 5599 DistinguishedName authorities<3..2^16-1>; 5600 } CertificateAuthoritiesExtension; 5602 struct { 5603 opaque certificate_extension_oid<1..2^8-1>; 5604 opaque certificate_extension_values<0..2^16-1>; 5605 } OIDFilter; 5607 struct { 5608 OIDFilter filters<0..2^16-1>; 5609 } OIDFilterExtension; 5611 struct {} PostHandshakeAuth; 5613 struct { 5614 Extension extensions<0..2^16-1>; 5615 } EncryptedExtensions; 5617 struct { 5618 opaque certificate_request_context<0..2^8-1>; 5619 Extension extensions<2..2^16-1>; 5620 } CertificateRequest; 5622 B.3.3. Authentication Messages 5623 enum { 5624 X509(0), 5625 OpenPGP_RESERVED(1), 5626 RawPublicKey(2), 5627 (255) 5628 } CertificateType; 5630 struct { 5631 select (certificate_type) { 5632 case RawPublicKey: 5633 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */ 5634 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 5636 case X509: 5637 opaque cert_data<1..2^24-1>; 5638 }; 5639 Extension extensions<0..2^16-1>; 5640 } CertificateEntry; 5642 struct { 5643 opaque certificate_request_context<0..2^8-1>; 5644 CertificateEntry certificate_list<0..2^24-1>; 5645 } Certificate; 5647 struct { 5648 SignatureScheme algorithm; 5649 opaque signature<0..2^16-1>; 5650 } CertificateVerify; 5652 struct { 5653 opaque verify_data[Hash.length]; 5654 } Finished; 5656 B.3.4. Ticket Establishment 5658 struct { 5659 uint32 ticket_lifetime; 5660 uint32 ticket_age_add; 5661 opaque ticket_nonce<0..255>; 5662 opaque ticket<1..2^16-1>; 5663 Extension extensions<0..2^16-2>; 5664 } NewSessionTicket; 5666 B.3.5. Updating Keys 5667 struct {} EndOfEarlyData; 5669 enum { 5670 update_not_requested(0), update_requested(1), (255) 5671 } KeyUpdateRequest; 5673 struct { 5674 KeyUpdateRequest request_update; 5675 } KeyUpdate; 5677 B.4. Cipher Suites 5679 A symmetric cipher suite defines the pair of the AEAD algorithm and 5680 hash algorithm to be used with HKDF. Cipher suite names follow the 5681 naming convention: 5683 CipherSuite TLS_AEAD_HASH = VALUE; 5685 +-----------+------------------------------------------------+ 5686 | Component | Contents | 5687 +-----------+------------------------------------------------+ 5688 | TLS | The string "TLS" | 5689 | | | 5690 | AEAD | The AEAD algorithm used for record protection | 5691 | | | 5692 | HASH | The hash algorithm used with HKDF | 5693 | | | 5694 | VALUE | The two byte ID assigned for this cipher suite | 5695 +-----------+------------------------------------------------+ 5697 This specification defines the following cipher suites for use with 5698 TLS 1.3. 5700 +------------------------------+-------------+ 5701 | Description | Value | 5702 +------------------------------+-------------+ 5703 | TLS_AES_128_GCM_SHA256 | {0x13,0x01} | 5704 | | | 5705 | TLS_AES_256_GCM_SHA384 | {0x13,0x02} | 5706 | | | 5707 | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} | 5708 | | | 5709 | TLS_AES_128_CCM_SHA256 | {0x13,0x04} | 5710 | | | 5711 | TLS_AES_128_CCM_8_SHA256 | {0x13,0x05} | 5712 +------------------------------+-------------+ 5714 The corresponding AEAD algorithms AEAD_AES_128_GCM, AEAD_AES_256_GCM, 5715 and AEAD_AES_128_CCM are defined in [RFC5116]. 5716 AEAD_CHACHA20_POLY1305 is defined in [RFC7539]. AEAD_AES_128_CCM_8 5717 is defined in [RFC6655]. The corresponding hash algorithms are 5718 defined in [SHS]. 5720 Although TLS 1.3 uses the same cipher suite space as previous 5721 versions of TLS, TLS 1.3 cipher suites are defined differently, only 5722 specifying the symmetric ciphers, and cannot be used for TLS 1.2. 5723 Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 5724 1.3. 5726 New cipher suite values are assigned by IANA as described in 5727 Section 11. 5729 Appendix C. Implementation Notes 5731 The TLS protocol cannot prevent many common security mistakes. This 5732 section provides several recommendations to assist implementors. 5733 [I-D.ietf-tls-tls13-vectors] provides test vectors for TLS 1.3 5734 handshakes. 5736 C.1. Random Number Generation and Seeding 5738 TLS requires a cryptographically secure pseudorandom number generator 5739 (CSPRNG). In most cases, the operating system provides an 5740 appropriate facility such as /dev/urandom, which should be used 5741 absent other (performance) concerns. It is RECOMMENDED to use an 5742 existing CSPRNG implementation in preference to crafting a new one. 5743 Many adequate cryptographic libraries are already available under 5744 favorable license terms. Should those prove unsatisfactory, 5745 [RFC4086] provides guidance on the generation of random values. 5747 TLS uses random values both in public protocol fields such as the 5748 public Random values in the ClientHello and ServerHello and to 5749 generate keying material. With a properly functioning CSPRNG, this 5750 does not present a security problem as it is not feasible to 5751 determine the CSPRNG state from its output. However, with a broken 5752 CSPRNG, it may be possible for an attacker to use the public output 5753 to determine the CSPRNG internal state and thereby predict the keying 5754 material, as documented in [CHECKOWAY]. Implementations can provide 5755 extra security against this form of attack by using separate CSPRNGs 5756 to generate public and private values. 5758 C.2. Certificates and Authentication 5760 Implementations are responsible for verifying the integrity of 5761 certificates and should generally support certificate revocation 5762 messages. Absent a specific indication from an application profile, 5763 Certificates should always be verified to ensure proper signing by a 5764 trusted Certificate Authority (CA). The selection and addition of 5765 trust anchors should be done very carefully. Users should be able to 5766 view information about the certificate and trust anchor. 5767 Applications SHOULD also enforce minimum and maximum key sizes. For 5768 example, certification paths containing keys or signatures weaker 5769 than 2048-bit RSA or 224-bit ECDSA are not appropriate for secure 5770 applications. 5772 C.3. Implementation Pitfalls 5774 Implementation experience has shown that certain parts of earlier TLS 5775 specifications are not easy to understand and have been a source of 5776 interoperability and security problems. Many of these areas have 5777 been clarified in this document but this appendix contains a short 5778 list of the most important things that require special attention from 5779 implementors. 5781 TLS protocol issues: 5783 - Do you correctly handle handshake messages that are fragmented to 5784 multiple TLS records (see Section 5.1)? Including corner cases 5785 like a ClientHello that is split to several small fragments? Do 5786 you fragment handshake messages that exceed the maximum fragment 5787 size? In particular, the Certificate and CertificateRequest 5788 handshake messages can be large enough to require fragmentation. 5790 - Do you ignore the TLS record layer version number in all 5791 unencrypted TLS records? (see Appendix D) 5793 - Have you ensured that all support for SSL, RC4, EXPORT ciphers, 5794 and MD5 (via the "signature_algorithms" extension) is completely 5795 removed from all possible configurations that support TLS 1.3 or 5796 later, and that attempts to use these obsolete capabilities fail 5797 correctly? (see Appendix D) 5799 - Do you handle TLS extensions in ClientHello correctly, including 5800 unknown extensions? 5802 - When the server has requested a client certificate, but no 5803 suitable certificate is available, do you correctly send an empty 5804 Certificate message, instead of omitting the whole message (see 5805 Section 4.4.2.3)? 5807 - When processing the plaintext fragment produced by AEAD-Decrypt 5808 and scanning from the end for the ContentType, do you avoid 5809 scanning past the start of the cleartext in the event that the 5810 peer has sent a malformed plaintext of all-zeros? 5812 - Do you properly ignore unrecognized cipher suites (Section 4.1.2), 5813 hello extensions (Section 4.2), named groups (Section 4.2.7), key 5814 shares (Section 4.2.8), supported versions (Section 4.2.1), and 5815 signature algorithms (Section 4.2.3) in the ClientHello? 5817 - As a server, do you send a HelloRetryRequest to clients which 5818 support a compatible (EC)DHE group but do not predict it in the 5819 "key_share" extension? As a client, do you correctly handle a 5820 HelloRetryRequest from the server? 5822 Cryptographic details: 5824 - What countermeasures do you use to prevent timing attacks 5825 [TIMING]? 5827 - When using Diffie-Hellman key exchange, do you correctly preserve 5828 leading zero bytes in the negotiated key (see Section 7.4.1)? 5830 - Does your TLS client check that the Diffie-Hellman parameters sent 5831 by the server are acceptable, (see Section 4.2.8.1)? 5833 - Do you use a strong and, most importantly, properly seeded random 5834 number generator (see Appendix C.1) when generating Diffie-Hellman 5835 private values, the ECDSA "k" parameter, and other security- 5836 critical values? It is RECOMMENDED that implementations implement 5837 "deterministic ECDSA" as specified in [RFC6979]. 5839 - Do you zero-pad Diffie-Hellman public key values to the group size 5840 (see Section 4.2.8.1)? 5842 - Do you verify signatures after making them to protect against RSA- 5843 CRT key leaks? [FW15] 5845 C.4. Client Tracking Prevention 5847 Clients SHOULD NOT reuse a ticket for multiple connections. Reuse of 5848 a ticket allows passive observers to correlate different connections. 5849 Servers that issue tickets SHOULD offer at least as many tickets as 5850 the number of connections that a client might use; for example, a web 5851 browser using HTTP/1.1 [RFC7230] might open six connections to a 5852 server. Servers SHOULD issue new tickets with every connection. 5853 This ensures that clients are always able to use a new ticket when 5854 creating a new connection. 5856 C.5. Unauthenticated Operation 5858 Previous versions of TLS offered explicitly unauthenticated cipher 5859 suites based on anonymous Diffie-Hellman. These modes have been 5860 deprecated in TLS 1.3. However, it is still possible to negotiate 5861 parameters that do not provide verifiable server authentication by 5862 several methods, including: 5864 - Raw public keys [RFC7250]. 5866 - Using a public key contained in a certificate but without 5867 validation of the certificate chain or any of its contents. 5869 Either technique used alone is vulnerable to man-in-the-middle 5870 attacks and therefore unsafe for general use. However, it is also 5871 possible to bind such connections to an external authentication 5872 mechanism via out-of-band validation of the server's public key, 5873 trust on first use, or a mechanism such as channel bindings (though 5874 the channel bindings described in [RFC5929] are not defined for TLS 5875 1.3). If no such mechanism is used, then the connection has no 5876 protection against active man-in-the-middle attack; applications MUST 5877 NOT use TLS in such a way absent explicit configuration or a specific 5878 application profile. 5880 Appendix D. Backward Compatibility 5882 The TLS protocol provides a built-in mechanism for version 5883 negotiation between endpoints potentially supporting different 5884 versions of TLS. 5886 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 5887 also handle clients trying to use future versions of TLS as long as 5888 the ClientHello format remains compatible and the client supports the 5889 highest protocol version available in the server. 5891 Prior versions of TLS used the record layer version number for 5892 various purposes. (TLSPlaintext.legacy_record_version and 5893 TLSCiphertext.legacy_record_version) As of TLS 1.3, this field is 5894 deprecated. The value of TLSPlaintext.legacy_record_version MUST be 5895 ignored by all implementations. The value of 5896 TLSCiphertext.legacy_record_version MAY be ignored, or MAY be 5897 validated to match the fixed constant value. Version negotiation is 5898 performed using only the handshake versions 5899 (ClientHello.legacy_version, ClientHello "supported_versions" 5900 extension, and ServerHello.version). In order to maximize 5901 interoperability with older endpoints, implementations that negotiate 5902 the use of TLS 1.0-1.2 SHOULD set the record layer version number to 5903 the negotiated version for the ServerHello and all records 5904 thereafter. 5906 For maximum compatibility with previously non-standard behavior and 5907 misconfigured deployments, all implementations SHOULD support 5908 validation of certification paths based on the expectations in this 5909 document, even when handling prior TLS versions' handshakes. (see 5910 Section 4.4.2.2) 5912 TLS 1.2 and prior supported an "Extended Master Secret" [RFC7627] 5913 extension which digested large parts of the handshake transcript into 5914 the master secret. Because TLS 1.3 always hashes in the transcript 5915 up to the server CertificateVerify, implementations which support 5916 both TLS 1.3 and earlier versions SHOULD indicate the use of the 5917 Extended Master Secret extension in their APIs whenever TLS 1.3 is 5918 used. 5920 D.1. Negotiating with an older server 5922 A TLS 1.3 client who wishes to negotiate with servers that do not 5923 support TLS 1.3 will send a normal TLS 1.3 ClientHello containing 5924 0x0303 (TLS 1.2) in ClientHello.legacy_version but with the correct 5925 version(s) in the "supported_versions" extension. If the server does 5926 not support TLS 1.3 it will respond with a ServerHello containing an 5927 older version number. If the client agrees to use this version, the 5928 negotiation will proceed as appropriate for the negotiated protocol. 5929 A client using a ticket for resumption SHOULD initiate the connection 5930 using the version that was previously negotiated. 5932 Note that 0-RTT data is not compatible with older servers and SHOULD 5933 NOT be sent absent knowledge that the server supports TLS 1.3. See 5934 Appendix D.3. 5936 If the version chosen by the server is not supported by the client 5937 (or not acceptable), the client MUST abort the handshake with a 5938 "protocol_version" alert. 5940 Some legacy server implementations are known to not implement the TLS 5941 specification properly and might abort connections upon encountering 5942 TLS extensions or versions which they are not aware of. 5943 Interoperability with buggy servers is a complex topic beyond the 5944 scope of this document. Multiple connection attempts may be required 5945 in order to negotiate a backwards compatible connection; however, 5946 this practice is vulnerable to downgrade attacks and is NOT 5947 RECOMMENDED. 5949 D.2. Negotiating with an older client 5951 A TLS server can also receive a ClientHello indicating a version 5952 number smaller than its highest supported version. If the 5953 "supported_versions" extension is present, the server MUST negotiate 5954 using that extension as described in Section 4.2.1. If the 5955 "supported_versions" extension is not present, the server MUST 5956 negotiate the minimum of ClientHello.legacy_version and TLS 1.2. For 5957 example, if the server supports TLS 1.0, 1.1, and 1.2, and 5958 legacy_version is TLS 1.0, the server will proceed with a TLS 1.0 5959 ServerHello. If the "supported_versions" extension is absent and the 5960 server only supports versions greater than 5961 ClientHello.legacy_version, the server MUST abort the handshake with 5962 a "protocol_version" alert. 5964 Note that earlier versions of TLS did not clearly specify the record 5965 layer version number value in all cases 5966 (TLSPlaintext.legacy_record_version). Servers will receive various 5967 TLS 1.x versions in this field, but its value MUST always be ignored. 5969 D.3. 0-RTT backwards compatibility 5971 0-RTT data is not compatible with older servers. An older server 5972 will respond to the ClientHello with an older ServerHello, but it 5973 will not correctly skip the 0-RTT data and will fail to complete the 5974 handshake. This can cause issues when a client attempts to use 5975 0-RTT, particularly against multi-server deployments. For example, a 5976 deployment could deploy TLS 1.3 gradually with some servers 5977 implementing TLS 1.3 and some implementing TLS 1.2, or a TLS 1.3 5978 deployment could be downgraded to TLS 1.2. 5980 A client that attempts to send 0-RTT data MUST fail a connection if 5981 it receives a ServerHello with TLS 1.2 or older. A client that 5982 attempts to repair this error SHOULD NOT send a TLS 1.2 ClientHello, 5983 but instead send a TLS 1.3 ClientHello without 0-RTT data. 5985 To avoid this error condition, multi-server deployments SHOULD ensure 5986 a uniform and stable deployment of TLS 1.3 without 0-RTT prior to 5987 enabling 0-RTT. 5989 D.4. Middlebox Compatibility Mode 5991 Field measurements have found that a significant number of 5992 middleboxes misbehave when a TLS client/server pair negotiates TLS 5993 1.3. Implementations can increase the chance of making connections 5994 through those middleboxes by making the TLS 1.3 handshake look more 5995 like a TLS 1.2 handshake: 5997 - The client always provides a non-empty session ID in the 5998 ClientHello. 6000 - If not offering early data, the client sends a dummy 6001 change_cipher_spec record immediately before its second flight. 6002 This may either be before its second ClientHello or before its 6003 encrypted handshake flight. If offering early data, the record is 6004 placed immediately after the first ClientHello. 6006 - The server sends a dummy change_cipher_spec record immediately 6007 after its first handshake message. This may either be after a 6008 ServerHello or a HelloRetryRequest. 6010 When put together, these changes make the TLS 1.3 handshake resemble 6011 TLS 1.2 session resumption, which improves the chance of successfully 6012 connecting through middleboxes. This "compatibility mode" is not 6013 explicitly negotiated. The client can opt to provide a session ID or 6014 not and the server has to echo it. Either side can send 6015 change_cipher_spec at any time during the handshake, as they must be 6016 ignored by the peer. 6018 D.5. Backwards Compatibility Security Restrictions 6020 Implementations negotiating use of older versions of TLS SHOULD 6021 prefer forward secret and AEAD cipher suites, when available. 6023 The security of RC4 cipher suites is considered insufficient for the 6024 reasons cited in [RFC7465]. Implementations MUST NOT offer or 6025 negotiate RC4 cipher suites for any version of TLS for any reason. 6027 Old versions of TLS permitted the use of very low strength ciphers. 6028 Ciphers with a strength less than 112 bits MUST NOT be offered or 6029 negotiated for any version of TLS for any reason. 6031 The security of SSL 3.0 [SSL3] is considered insufficient for the 6032 reasons enumerated in [RFC7568], and MUST NOT be negotiated for any 6033 reason. 6035 The security of SSL 2.0 [SSL2] is considered insufficient for the 6036 reasons enumerated in [RFC6176], and MUST NOT be negotiated for any 6037 reason. 6039 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 6040 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 6041 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 6042 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 6043 order to negotiate older versions of TLS. 6045 Implementations MUST NOT send a ClientHello.legacy_version or 6046 ServerHello.version set to 0x0300 or less. Any endpoint receiving a 6047 Hello message with ClientHello.legacy_version or ServerHello.version 6048 set to 0x0300 MUST abort the handshake with a "protocol_version" 6049 alert. 6051 Implementations MUST NOT send any records with a version less than 6052 0x0300. Implementations SHOULD NOT accept any records with a version 6053 less than 0x0300 (but may inadvertently do so if the record version 6054 number is ignored completely). 6056 Implementations MUST NOT use the Truncated HMAC extension, defined in 6057 Section 7 of [RFC6066], as it is not applicable to AEAD algorithms 6058 and has been shown to be insecure in some scenarios. 6060 Appendix E. Overview of Security Properties 6062 A complete security analysis of TLS is outside the scope of this 6063 document. In this section, we provide an informal description the 6064 desired properties as well as references to more detailed work in the 6065 research literature which provides more formal definitions. 6067 We cover properties of the handshake separately from those of the 6068 record layer. 6070 E.1. Handshake 6072 The TLS handshake is an Authenticated Key Exchange (AKE) protocol 6073 which is intended to provide both one-way authenticated (server-only) 6074 and mutually authenticated (client and server) functionality. At the 6075 completion of the handshake, each side outputs its view of the 6076 following values: 6078 - A set of "session keys" (the various secrets derived from the 6079 master secret) from which can be derived a set of working keys. 6081 - A set of cryptographic parameters (algorithms, etc.) 6083 - The identities of the communicating parties. 6085 We assume the attacker to be an active network attacker, which means 6086 it has complete control over the network used to communicate between 6087 the parties [RFC3552]. Even under these conditions, the handshake 6088 should provide the properties listed below. Note that these 6089 properties are not necessarily independent, but reflect the protocol 6090 consumers' needs. 6092 Establishing the same session keys. The handshake needs to output 6093 the same set of session keys on both sides of the handshake, 6094 provided that it completes successfully on each endpoint (See 6095 [CK01]; defn 1, part 1). 6097 Secrecy of the session keys. The shared session keys should be known 6098 only to the communicating parties and not to the attacker (See 6099 [CK01]; defn 1, part 2). Note that in a unilaterally 6100 authenticated connection, the attacker can establish its own 6101 session keys with the server, but those session keys are distinct 6102 from those established by the client. 6104 Peer Authentication. The client's view of the peer identity should 6105 reflect the server's identity. If the client is authenticated, 6106 the server's view of the peer identity should match the client's 6107 identity. 6109 Uniqueness of the session keys: Any two distinct handshakes should 6110 produce distinct, unrelated session keys. Individual session keys 6111 produced by a handshake should also be distinct and unrelated. 6113 Downgrade protection. The cryptographic parameters should be the 6114 same on both sides and should be the same as if the peers had been 6115 communicating in the absence of an attack (See [BBFKZG16]; defns 8 6116 and 9}). 6118 Forward secret with respect to long-term keys If the long-term 6119 keying material (in this case the signature keys in certificate- 6120 based authentication modes or the external/resumption PSK in PSK 6121 with (EC)DHE modes) is compromised after the handshake is 6122 complete, this does not compromise the security of the session key 6123 (See [DOW92]), as long as the session key itself has been erased. 6124 The forward secrecy property is not satisfied when PSK is used in 6125 the "psk_ke" PskKeyExchangeMode. 6127 Key Compromise Impersonation (KCI) resistance In a mutually- 6128 authenticated connection with certificates, peer authentication 6129 should hold even if the local long-term secret was compromised 6130 before the connection was established (see [HGFS15]). For 6131 example, if a client's signature key is compromised, it should not 6132 be possible to impersonate arbitrary servers to that client in 6133 subsequent handshakes. 6135 Protection of endpoint identities. The server's identity 6136 (certificate) should be protected against passive attackers. The 6137 client's identity should be protected against both passive and 6138 active attackers. 6140 Informally, the signature-based modes of TLS 1.3 provide for the 6141 establishment of a unique, secret, shared key established by an 6142 (EC)DHE key exchange and authenticated by the server's signature over 6143 the handshake transcript, as well as tied to the server's identity by 6144 a MAC. If the client is authenticated by a certificate, it also 6145 signs over the handshake transcript and provides a MAC tied to both 6146 identities. [SIGMA] describes the design and analysis of this type 6147 of key exchange protocol. If fresh (EC)DHE keys are used for each 6148 connection, then the output keys are forward secret. 6150 The external PSK and resumption PSK bootstrap from a long-term shared 6151 secret into a unique per-connection set of short-term session keys. 6152 This secret may have been established in a previous handshake. If 6153 PSK with (EC)DHE key establishment is used, these session keys will 6154 also be forward secret. The resumption PSK has been designed so that 6155 the resumption master secret computed by connection N and needed to 6156 form connection N+1 is separate from the traffic keys used by 6157 connection N, thus providing forward secrecy between the connections. 6158 In addition, if multiple tickets are established on the same 6159 connection, they are associated with different keys, so compromise of 6160 the PSK associated with one ticket does not lead to the compromise of 6161 connections established with PSKs associated with other tickets. 6162 This property is most interesting if tickets are stored in a database 6163 (and so can be deleted) rather than if they are self-encrypted. 6165 The PSK binder value forms a binding between a PSK and the current 6166 handshake, as well as between the session where the PSK was 6167 established and the session where it was used. This binding 6168 transitively includes the original handshake transcript, because that 6169 transcript is digested into the values which produce the Resumption 6170 Master Secret. This requires that both the KDF used to produce the 6171 resumption master secret and the MAC used to compute the binder be 6172 collision resistant. See Appendix E.1.1 for more on this. Note: The 6173 binder does not cover the binder values from other PSKs, though they 6174 are included in the Finished MAC. 6176 Note: TLS does not currently permit the server to send a 6177 certificate_request message in non-certificate-based handshakes 6178 (e.g., PSK). If this restriction were to be relaxed in future, the 6179 client's signature would not cover the server's certificate directly. 6180 However, if the PSK was established through a NewSessionTicket, the 6181 client's signature would transitively cover the server's certificate 6182 through the PSK binder. [PSK-FINISHED] describes a concrete attack 6183 on constructions that do not bind to the server's certificate (see 6184 also [Kraw16]). It is unsafe to use certificate-based client 6185 authentication when the client might potentially share the same PSK/ 6186 key-id pair with two different endpoints. Implementations MUST NOT 6187 combine external PSKs with certificate-based authentication of either 6188 the client or the server. 6190 If an exporter is used, then it produces values which are unique and 6191 secret (because they are generated from a unique session key). 6192 Exporters computed with different labels and contexts are 6193 computationally independent, so it is not feasible to compute one 6194 from another or the session secret from the exported value. Note: 6195 exporters can produce arbitrary-length values. If exporters are to 6196 be used as channel bindings, the exported value MUST be large enough 6197 to provide collision resistance. The exporters provided in TLS 1.3 6198 are derived from the same handshake contexts as the early traffic 6199 keys and the application traffic keys respectively, and thus have 6200 similar security properties. Note that they do not include the 6201 client's certificate; future applications which wish to bind to the 6202 client's certificate may need to define a new exporter that includes 6203 the full handshake transcript. 6205 For all handshake modes, the Finished MAC (and where present, the 6206 signature), prevents downgrade attacks. In addition, the use of 6207 certain bytes in the random nonces as described in Section 4.1.3 6208 allows the detection of downgrade to previous TLS versions. See 6209 [BBFKZG16] for more detail on TLS 1.3 and downgrade. 6211 As soon as the client and the server have exchanged enough 6212 information to establish shared keys, the remainder of the handshake 6213 is encrypted, thus providing protection against passive attackers, 6214 even if the computed shared key is not authenticated. Because the 6215 server authenticates before the client, the client can ensure that if 6216 it authenticates to the server, it only reveals its identity to an 6217 authenticated server. Note that implementations must use the 6218 provided record padding mechanism during the handshake to avoid 6219 leaking information about the identities due to length. The client's 6220 proposed PSK identities are not encrypted, nor is the one that the 6221 server selects. 6223 E.1.1. Key Derivation and HKDF 6225 Key derivation in TLS 1.3 uses the HKDF function defined in [RFC5869] 6226 and its two components, HKDF-Extract and HKDF-Expand. The full 6227 rationale for the HKDF construction can be found in [Kraw10] and the 6228 rationale for the way it is used in TLS 1.3 in [KW16]. Throughout 6229 this document, each application of HKDF-Extract is followed by one or 6230 more invocations of HKDF-Expand. This ordering should always be 6231 followed (including in future revisions of this document), in 6232 particular, one SHOULD NOT use an output of HKDF-Extract as an input 6233 to another application of HKDF-Extract without an HKDF-Expand in 6234 between. Consecutive applications of HKDF-Expand are allowed as long 6235 as these are differentiated via the key and/or the labels. 6237 Note that HKDF-Expand implements a pseudorandom function (PRF) with 6238 both inputs and outputs of variable length. In some of the uses of 6239 HKDF in this document (e.g., for generating exporters and the 6240 resumption_master_secret), it is necessary that the application of 6241 HKDF-Expand be collision-resistant, namely, it should be infeasible 6242 to find two different inputs to HKDF-Expand that output the same 6243 value. This requires the underlying hash function to be collision 6244 resistant and the output length from HKDF-Expand to be of size at 6245 least 256 bits (or as much as needed for the hash function to prevent 6246 finding collisions). 6248 E.1.2. Client Authentication 6250 A client that has sent authentication data to a server, either during 6251 the handshake or in post-handshake authentication, cannot be sure if 6252 the server afterwards considers the client to be authenticated or 6253 not. If the client needs to determine if the server considers the 6254 connection to be unilaterally or mutually authenticated, this has to 6255 be provisioned by the application layer. See [CHHSV17] for details. 6256 In addition, the analysis of post-handshake authentication from 6257 [Kraw16] shows that the client identified by the certificate sent in 6258 the post-handshake phase possesses the traffic key. This party is 6259 therefore the client that participated in the original handshake or 6260 one to whom the original client delegated the traffic key (assuming 6261 that the traffic key has not been compromised). 6263 E.1.3. 0-RTT 6265 The 0-RTT mode of operation generally provides similar security 6266 properties as 1-RTT data, with the two exceptions that the 0-RTT 6267 encryption keys do not provide full forward secrecy and that the 6268 server is not able to guarantee uniqueness of the handshake (non- 6269 replayability) without keeping potentially undue amounts of state. 6270 See Section 4.2.10 for one mechanism to limit the exposure to replay. 6272 E.1.4. Exporter Independence 6274 The exporter_master_secret and early_exporter_master_secret are 6275 derived to be independent of the traffic keys and therefore do not 6276 represent a threat to the security of traffic encrypted with those 6277 keys. However, because these secrets can be used to compute any 6278 exporter value, they SHOULD be erased as soon as possible. If the 6279 total set of exporter labels is known, then implementations SHOULD 6280 pre-compute the inner Derive-Secret stage of the exporter computation 6281 for all those labels, then erase the [early_]exporter_master_secret, 6282 followed by each inner values as soon as it is known that it will not 6283 be needed again. 6285 E.1.5. Post-Compromise Security 6287 TLS does not provide security for handshakes which take place after 6288 the peer's long-term secret (signature key or external PSK) is 6289 compromised. It therefore does not provide post-compromise security 6290 [CCG16], sometimes also referred to as backwards or future secrecy. 6291 This is in contrast to KCI resistance, which describes the security 6292 guarantees that a party has after its own long-term secret has been 6293 compromised. 6295 E.1.6. External References 6297 The reader should refer to the following references for analysis of 6298 the TLS handshake: [DFGS15] [CHSV16] [DFGS16] [KW16] [Kraw16] 6299 [FGSW16] [LXZFH16] [FG17] [BBK17]. 6301 E.2. Record Layer 6303 The record layer depends on the handshake producing strong traffic 6304 secrets which can be used to derive bidirectional encryption keys and 6305 nonces. Assuming that is true, and the keys are used for no more 6306 data than indicated in Section 5.5 then the record layer should 6307 provide the following guarantees: 6309 Confidentiality. An attacker should not be able to determine the 6310 plaintext contents of a given record. 6312 Integrity. An attacker should not be able to craft a new record 6313 which is different from an existing record which will be accepted 6314 by the receiver. 6316 Order protection/non-replayability An attacker should not be able to 6317 cause the receiver to accept a record which it has already 6318 accepted or cause the receiver to accept record N+1 without having 6319 first processed record N. 6321 Length concealment. Given a record with a given external length, the 6322 attacker should not be able to determine the amount of the record 6323 that is content versus padding. 6325 Forward secrecy after key change. If the traffic key update 6326 mechanism described in Section 4.6.3 has been used and the 6327 previous generation key is deleted, an attacker who compromises 6328 the endpoint should not be able to decrypt traffic encrypted with 6329 the old key. 6331 Informally, TLS 1.3 provides these properties by AEAD-protecting the 6332 plaintext with a strong key. AEAD encryption [RFC5116] provides 6333 confidentiality and integrity for the data. Non-replayability is 6334 provided by using a separate nonce for each record, with the nonce 6335 being derived from the record sequence number (Section 5.3), with the 6336 sequence number being maintained independently at both sides thus 6337 records which are delivered out of order result in AEAD deprotection 6338 failures. In order to prevent mass cryptanalysis when the same 6339 plaintext is repeatedly encrypted by different users under the same 6340 key (as is commonly the case for HTTP), the nonce is formed by mixing 6341 the sequence number with a secret per-connection initialization 6342 vector derived along with the traffic keys. See [BT16] for analysis 6343 of this construction. 6345 The re-keying technique in TLS 1.3 (see Section 7.2) follows the 6346 construction of the serial generator in [REKEY], which shows that re- 6347 keying can allow keys to be used for a larger number of encryptions 6348 than without re-keying. This relies on the security of the HKDF- 6349 Expand-Label function as a pseudorandom function (PRF). In addition, 6350 as long as this function is truly one way, it is not possible to 6351 compute traffic keys from prior to a key change (forward secrecy). 6353 TLS does not provide security for data which is communicated on a 6354 connection after a traffic secret of that connection is compromised. 6355 That is, TLS does not provide post-compromise security/future 6356 secrecy/backward secrecy with respect to the traffic secret. Indeed, 6357 an attacker who learns a traffic secret can compute all future 6358 traffic secrets on that connection. Systems which want such 6359 guarantees need to do a fresh handshake and establish a new 6360 connection with an (EC)DHE exchange. 6362 E.2.1. External References 6364 The reader should refer to the following references for analysis of 6365 the TLS record layer: [BMMT15] [BT16] [BDFKPPRSZZ16] [BBK17]. 6367 E.3. Traffic Analysis 6369 TLS is susceptible to a variety of traffic analysis attacks based on 6370 observing the length and timing of encrypted packets [CLINIC] 6371 [HCJ16]. This is particularly easy when there is a small set of 6372 possible messages to be distinguished, such as for a video server 6373 hosting a fixed corpus of content, but still provides usable 6374 information even in more complicated scenarios. 6376 TLS does not provide any specific defenses against this form of 6377 attack but does include a padding mechanism for use by applications: 6378 The plaintext protected by the AEAD function consists of content plus 6379 variable-length padding, which allows the application to produce 6380 arbitrary length encrypted records as well as padding-only cover 6381 traffic to conceal the difference between periods of transmission and 6382 periods of silence. Because the padding is encrypted alongside the 6383 actual content, an attacker cannot directly determine the length of 6384 the padding, but may be able to measure it indirectly by the use of 6385 timing channels exposed during record processing (i.e., seeing how 6386 long it takes to process a record or trickling in records to see 6387 which ones elicit a response from the server). In general, it is not 6388 known how to remove all of these channels because even a constant 6389 time padding removal function will likely feed the content into data- 6390 dependent functions. At minimum, a fully constant time server or 6391 client would require close cooperation with the application layer 6392 protocol implementation, including making that higher level protocol 6393 constant time. 6395 Note: Robust traffic analysis defences will likely lead to inferior 6396 performance due to delay in transmitting packets and increased 6397 traffic volume. 6399 E.4. Side Channel Attacks 6401 In general, TLS does not have specific defenses against side-channel 6402 attacks (i.e., those which attack the communications via secondary 6403 channels such as timing) leaving those to the implementation of the 6404 relevant cryptographic primitives. However, certain features of TLS 6405 are designed to make it easier to write side-channel resistant code: 6407 - Unlike previous versions of TLS which used a composite MAC-then- 6408 encrypt structure, TLS 1.3 only uses AEAD algorithms, allowing 6409 implementations to use self-contained constant-time 6410 implementations of those primitives. 6412 - TLS uses a uniform "bad_record_mac" alert for all decryption 6413 errors, which is intended to prevent an attacker from gaining 6414 piecewise insight into portions of the message. Additional 6415 resistance is provided by terminating the connection on such 6416 errors; a new connection will have different cryptographic 6417 material, preventing attacks against the cryptographic primitives 6418 that require multiple trials. 6420 Information leakage through side channels can occur at layers above 6421 TLS, in application protocols and the applications that use them. 6422 Resistance to side-channel attacks depends on applications and 6423 application protocols separately ensuring that confidential 6424 information is not inadvertently leaked. 6426 E.5. Replay Attacks on 0-RTT 6428 Replayable 0-RTT data presents a number of security threats to TLS- 6429 using applications, unless those applications are specifically 6430 engineered to be safe under replay (minimally, this means idempotent, 6431 but in many cases may also require other stronger conditions, such as 6432 constant-time response). Potential attacks include: 6434 - Duplication of actions which cause side effects (e.g., purchasing 6435 an item or transferring money) to be duplicated, thus harming the 6436 site or the user. 6438 - Attackers can store and replay 0-RTT messages in order to re-order 6439 them with respect to other messages (e.g., moving a delete to 6440 after a create). 6442 - Exploiting cache timing behavior to discover the content of 0-RTT 6443 messages by replaying a 0-RTT message to a different cache node 6444 and then using a separate connection to measure request latency, 6445 to see if the two requests address the same resource. 6447 If data can be replayed a large number of times, additional attacks 6448 become possible, such as making repeated measurements of the the 6449 speed of cryptographic operations. In addition, they may be able to 6450 overload rate-limiting systems. For further description of these 6451 attacks, see [Mac17]. 6453 Ultimately, servers have the responsibility to protect themselves 6454 against attacks employing 0-RTT data replication. The mechanisms 6455 described in Section 8 are intended to prevent replay at the TLS 6456 layer but do not provide complete protection against receiving 6457 multiple copies of client data. TLS 1.3 falls back to the 1-RTT 6458 handshake when the server does not have any information about the 6459 client, e.g., because it is in a different cluster which does not 6460 share state or because the ticket has been deleted as described in 6461 Section 8.1. If the application layer protocol retransmits data in 6462 this setting, then it is possible for an attacker to induce message 6463 duplication by sending the ClientHello to both the original cluster 6464 (which processes the data immediately) and another cluster which will 6465 fall back to 1-RTT and process the data upon application layer 6466 replay. The scale of this attack is limited by the client's 6467 willingness to retry transactions and therefore only allows a limited 6468 amount of duplication, with each copy appearing as a new connection 6469 at the server. 6471 If implemented correctly, the mechanisms described in Section 8.1 and 6472 Section 8.2 prevent a replayed ClientHello and its associated 0-RTT 6473 data from being accepted multiple times by any cluster with 6474 consistent state; for servers which limit the use of 0-RTT to one 6475 cluster for a single ticket, then a given ClientHello and its 6476 associated 0-RTT data will only be accepted once. However, if state 6477 is not completely consistent, then an attacker might be able to have 6478 multiple copies of the data be accepted during the replication 6479 window. Because clients do not know the exact details of server 6480 behavior, they MUST NOT send messages in early data which are not 6481 safe to have replayed and which they would not be willing to retry 6482 across multiple 1-RTT connections. 6484 Application protocols MUST NOT use 0-RTT data without a profile that 6485 defines its use. That profile needs to identify which messages or 6486 interactions are safe to use with 0-RTT and how to handle the 6487 situation when the server rejects 0-RTT and falls back to 1-RTT. 6489 In addition, to avoid accidental misuse, TLS implementations MUST NOT 6490 enable 0-RTT (either sending or accepting) unless specifically 6491 requested by the application and MUST NOT automatically resend 0-RTT 6492 data if it is rejected by the server unless instructed by the 6493 application. Server-side applications may wish to implement special 6494 processing for 0-RTT data for some kinds of application traffic 6495 (e.g., abort the connection, request that data be resent at the 6496 application layer, or delay processing until the handshake 6497 completes). In order to allow applications to implement this kind of 6498 processing, TLS implementations MUST provide a way for the 6499 application to determine if the handshake has completed. 6501 E.5.1. Replay and Exporters 6503 Replays of the ClientHello produce the same early exporter, thus 6504 requiring additional care by applications which use these exporters. 6505 In particular, if these exporters are used as an authentication 6506 channel binding (e.g., by signing the output of the exporter) an 6507 attacker who compromises the PSK can transplant authenticators 6508 between connections without compromising the authentication key. 6510 In addition, the early exporter SHOULD NOT be used to generate 6511 server-to-client encryption keys because that would entail the reuse 6512 of those keys. This parallels the use of the early application 6513 traffic keys only in the client-to-server direction. 6515 Appendix F. Working Group Information 6517 The discussion list for the IETF TLS working group is located at the 6518 e-mail address tls@ietf.org [1]. Information on the group and 6519 information on how to subscribe to the list is at 6520 https://www.ietf.org/mailman/listinfo/tls [2] 6521 Archives of the list can be found at: https://www.ietf.org/mail- 6522 archive/web/tls/current/index.html [3] 6524 Appendix G. Contributors 6526 - Martin Abadi 6527 University of California, Santa Cruz 6528 abadi@cs.ucsc.edu 6530 - Christopher Allen (co-editor of TLS 1.0) 6531 Alacrity Ventures 6532 ChristopherA@AlacrityManagement.com 6534 - Richard Barnes 6535 Cisco 6536 rlb@ipv.sx 6538 - Steven M. Bellovin 6539 Columbia University 6540 smb@cs.columbia.edu 6542 - David Benjamin 6543 Google 6544 davidben@google.com 6546 - Benjamin Beurdouche 6547 INRIA & Microsoft Research 6548 benjamin.beurdouche@ens.fr 6550 - Karthikeyan Bhargavan (co-author of [RFC7627]) 6551 INRIA 6552 karthikeyan.bhargavan@inria.fr 6554 - Simon Blake-Wilson (co-author of [RFC4492]) 6555 BCI 6556 sblakewilson@bcisse.com 6558 - Nelson Bolyard (co-author of [RFC4492]) 6559 Sun Microsystems, Inc. 6560 nelson@bolyard.com 6562 - Ran Canetti 6563 IBM 6564 canetti@watson.ibm.com 6566 - Matt Caswell 6567 OpenSSL 6568 matt@openssl.org 6570 - Stephen Checkoway 6571 University of Illinois at Chicago 6572 sfc@uic.edu 6574 - Pete Chown 6575 Skygate Technology Ltd 6576 pc@skygate.co.uk 6578 - Katriel Cohn-Gordon 6579 University of Oxford 6580 me@katriel.co.uk 6582 - Cas Cremers 6583 University of Oxford 6584 cas.cremers@cs.ox.ac.uk 6586 - Antoine Delignat-Lavaud (co-author of [RFC7627]) 6587 INRIA 6588 antoine.delignat-lavaud@inria.fr 6590 - Tim Dierks (co-editor of TLS 1.0, 1.1, and 1.2) 6591 Independent 6592 tim@dierks.org 6594 - Taher Elgamal 6595 Securify 6596 taher@securify.com 6598 - Pasi Eronen 6599 Nokia 6600 pasi.eronen@nokia.com 6602 - Cedric Fournet 6603 Microsoft 6604 fournet@microsoft.com 6606 - Anil Gangolli 6607 anil@busybuddha.org 6609 - David M. Garrett 6610 dave@nulldereference.com 6612 - Alessandro Ghedini 6613 Cloudflare Inc. 6614 alessandro@cloudflare.com 6616 - Daniel Kahn Gillmor 6617 ACLU 6618 dkg@fifthhorseman.net 6620 - Matthew Green 6621 Johns Hopkins University 6622 mgreen@cs.jhu.edu 6624 - Jens Guballa 6625 ETAS 6626 jens.guballa@etas.com 6628 - Felix Guenther 6629 TU Darmstadt 6630 mail@felixguenther.info 6632 - Vipul Gupta (co-author of [RFC4492]) 6633 Sun Microsystems Laboratories 6634 vipul.gupta@sun.com 6636 - Chris Hawk (co-author of [RFC4492]) 6637 Corriente Networks LLC 6638 chris@corriente.net 6640 - Kipp Hickman 6642 - Alfred Hoenes 6644 - David Hopwood 6645 Independent Consultant 6646 david.hopwood@blueyonder.co.uk 6648 - Marko Horvat 6649 MPI-SWS 6650 mhorvat@mpi-sws.org 6652 - Jonathan Hoyland 6653 Royal Holloway, University of London 6655 - Subodh Iyengar 6656 Facebook 6657 subodh@fb.com 6659 - Benjamin Kaduk 6660 Akamai 6661 kaduk@mit.edu 6663 - Hubert Kario 6664 Red Hat Inc. 6665 hkario@redhat.com 6667 - Phil Karlton (co-author of SSL 3.0) 6669 - Leon Klingele 6670 Independent 6671 mail@leonklingele.de 6673 - Paul Kocher (co-author of SSL 3.0) 6674 Cryptography Research 6675 paul@cryptography.com 6677 - Hugo Krawczyk 6678 IBM 6679 hugokraw@us.ibm.com 6681 - Adam Langley (co-author of [RFC7627]) 6682 Google 6683 agl@google.com 6685 - Olivier Levillain 6686 ANSSI 6687 olivier.levillain@ssi.gouv.fr 6689 - Xiaoyin Liu 6690 University of North Carolina at Chapel Hill 6691 xiaoyin.l@outlook.com 6693 - Ilari Liusvaara 6694 Independent 6695 ilariliusvaara@welho.com 6697 - Atul Luykx 6698 K.U. Leuven 6699 atul.luykx@kuleuven.be 6701 - Colm MacCarthaigh 6702 Amazon Web Services 6703 colm@allcosts.net 6705 - Carl Mehner 6706 USAA 6707 carl.mehner@usaa.com 6709 - Jan Mikkelsen 6710 Transactionware 6711 janm@transactionware.com 6713 - Bodo Moeller (co-author of [RFC4492]) 6714 Google 6715 bodo@openssl.org 6717 - Kyle Nekritz 6718 Facebook 6719 knekritz@fb.com 6721 - Erik Nygren 6722 Akamai Technologies 6723 erik+ietf@nygren.org 6725 - Magnus Nystrom 6726 Microsoft 6727 mnystrom@microsoft.com 6729 - Kazuho Oku 6730 DeNA Co., Ltd. 6731 kazuhooku@gmail.com 6733 - Kenny Paterson 6734 Royal Holloway, University of London 6735 kenny.paterson@rhul.ac.uk 6737 - Alfredo Pironti (co-author of [RFC7627]) 6738 INRIA 6739 alfredo.pironti@inria.fr 6741 - Andrei Popov 6742 Microsoft 6743 andrei.popov@microsoft.com 6745 - Marsh Ray (co-author of [RFC7627]) 6746 Microsoft 6747 maray@microsoft.com 6749 - Robert Relyea 6750 Netscape Communications 6751 relyea@netscape.com 6753 - Kyle Rose 6754 Akamai Technologies 6755 krose@krose.org 6757 - Jim Roskind 6758 Amazon 6759 jroskind@amazon.com 6761 - Michael Sabin 6762 - Joe Salowey 6763 Tableau Software 6764 joe@salowey.net 6766 - Rich Salz 6767 Akamai 6768 rsalz@akamai.com 6770 - David Schinazi 6771 Apple Inc. 6772 dschinazi@apple.com 6774 - Sam Scott 6775 Royal Holloway, University of London 6776 me@samjs.co.uk 6778 - Dan Simon 6779 Microsoft, Inc. 6780 dansimon@microsoft.com 6782 - Brian Smith 6783 Independent 6784 brian@briansmith.org 6786 - Brian Sniffen 6787 Akamai Technologies 6788 ietf@bts.evenmere.org 6790 - Nick Sullivan 6791 Cloudflare Inc. 6792 nick@cloudflare.com 6794 - Bjoern Tackmann 6795 University of California, San Diego 6796 btackmann@eng.ucsd.edu 6798 - Tim Taubert 6799 Mozilla 6800 ttaubert@mozilla.com 6802 - Martin Thomson 6803 Mozilla 6804 mt@mozilla.com 6806 - Sean Turner 6807 sn3rd 6808 sean@sn3rd.com 6810 - Steven Valdez 6811 Google 6812 svaldez@google.com 6814 - Filippo Valsorda 6815 Cloudflare Inc. 6816 filippo@cloudflare.com 6818 - Thyla van der Merwe 6819 Royal Holloway, University of London 6820 tjvdmerwe@gmail.com 6822 - Victor Vasiliev 6823 Google 6824 vasilvv@google.com 6826 - Tom Weinstein 6828 - Hoeteck Wee 6829 Ecole Normale Superieure, Paris 6830 hoeteck@alum.mit.edu 6832 - David Wong 6833 NCC Group 6834 david.wong@nccgroup.trust 6836 - Tim Wright 6837 Vodafone 6838 timothy.wright@vodafone.com 6840 - Peter Wu 6841 Independent 6842 peter@lekensteyn.nl 6844 - Kazu Yamamoto 6845 Internet Initiative Japan Inc. 6846 kazu@iij.ad.jp 6848 Author's Address 6850 Eric Rescorla 6851 RTFM, Inc. 6853 EMail: ekr@rtfm.com