idnits 2.17.1 draft-rescorla-tls-rfc8446-bis-00.txt: -(4842): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 9 instances of too long lines in the document, the longest one being 8 characters in excess of 72. -- The draft header indicates that this document obsoletes RFC6961, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document obsoletes RFC8446, 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 (11 August 2020) is 1354 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 611, but not defined -- Looks like a reference, but probably isn't: '0' on line 736 -- Looks like a reference, but probably isn't: '1' on line 736 -- Looks like a reference, but probably isn't: '2' on line 5295 -- Looks like a reference, but probably isn't: '3' on line 792 -- Looks like a reference, but probably isn't: '4' on line 765 -- Looks like a reference, but probably isn't: '8' on line 766 -- Looks like a reference, but probably isn't: '9' on line 793 -- Looks like a reference, but probably isn't: '10' on line 930 -- Looks like a reference, but probably isn't: '32' on line 5293 == Unused Reference: 'Blei98' is defined on line 4753, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DH76' -- Possible downref: Non-RFC (?) normative reference: ref. 'ECDSA' -- Possible downref: Non-RFC (?) normative reference: ref. 'GCM' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE1363' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** 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) ** 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 ** Downref: Normative reference to an Informational RFC: RFC 8439 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- 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'. -- 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 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 11 errors (**), 0 flaws (~~), 4 warnings (==), 31 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Rescorla 3 Internet-Draft Mozilla 4 Obsoletes: 5077, 5246, 6961, 8446 (if approved) 11 August 2020 5 Updates: 4492, 5705, 6066 (if approved) 6 Intended status: Standards Track 7 Expires: 12 February 2021 9 The Transport Layer Security (TLS) Protocol Version 1.3 10 draft-rescorla-tls-rfc8446-bis-00 12 Abstract 14 This document specifies version 1.3 of the Transport Layer Security 15 (TLS) protocol. TLS allows client/server applications to communicate 16 over the Internet in a way that is designed to prevent eavesdropping, 17 tampering, and message forgery. 19 This document updates RFCs 5705 and 6066 and obsoletes RFCs 5077, 20 5246, and 6961. This document also specifies new requirements for 21 TLS 1.2 implementations. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 12 February 2021. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 This document may contain material from IETF Documents or IETF 55 Contributions published or made publicly available before November 56 10, 2008. The person(s) controlling the copyright in some of this 57 material may not have granted the IETF Trust the right to allow 58 modifications of such material outside the IETF Standards Process. 59 Without obtaining an adequate license from the person(s) controlling 60 the copyright in such materials, this document may not be modified 61 outside the IETF Standards Process, and derivative works of it may 62 not be created outside the IETF Standards Process, except to format 63 it for publication as an RFC or to translate it into languages other 64 than English. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 69 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 6 70 1.2. Relationship to RFC 8446 . . . . . . . . . . . . . . . . 7 71 1.3. Major Differences from TLS 1.2 . . . . . . . . . . . . . 7 72 1.4. Updates Affecting TLS 1.2 . . . . . . . . . . . . . . . . 8 73 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 9 74 2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . . . 12 75 2.2. Resumption and Pre-Shared Key (PSK) . . . . . . . . . . . 13 76 2.3. 0-RTT Data . . . . . . . . . . . . . . . . . . . . . . . 15 77 3. Presentation Language . . . . . . . . . . . . . . . . . . . . 17 78 3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 17 79 3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 17 80 3.3. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 18 81 3.4. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 18 82 3.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 19 83 3.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 20 84 3.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 20 85 3.8. Variants . . . . . . . . . . . . . . . . . . . . . . . . 21 86 4. Handshake Protocol . . . . . . . . . . . . . . . . . . . . . 22 87 4.1. Key Exchange Messages . . . . . . . . . . . . . . . . . . 23 88 4.1.1. Cryptographic Negotiation . . . . . . . . . . . . . . 23 89 4.1.2. Client Hello . . . . . . . . . . . . . . . . . . . . 24 90 4.1.3. Server Hello . . . . . . . . . . . . . . . . . . . . 27 91 4.1.4. Hello Retry Request . . . . . . . . . . . . . . . . . 30 92 4.2. Extensions . . . . . . . . . . . . . . . . . . . . . . . 31 93 4.2.1. Supported Versions . . . . . . . . . . . . . . . . . 35 94 4.2.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . 36 95 4.2.3. Signature Algorithms . . . . . . . . . . . . . . . . 37 96 4.2.4. Certificate Authorities . . . . . . . . . . . . . . . 41 97 4.2.5. OID Filters . . . . . . . . . . . . . . . . . . . . . 41 98 4.2.6. Post-Handshake Client Authentication . . . . . . . . 42 99 4.2.7. Supported Groups . . . . . . . . . . . . . . . . . . 43 100 4.2.8. Key Share . . . . . . . . . . . . . . . . . . . . . . 44 101 4.2.9. Pre-Shared Key Exchange Modes . . . . . . . . . . . . 47 102 4.2.10. Early Data Indication . . . . . . . . . . . . . . . . 48 103 4.2.11. Pre-Shared Key Extension . . . . . . . . . . . . . . 51 104 4.3. Server Parameters . . . . . . . . . . . . . . . . . . . . 55 105 4.3.1. Encrypted Extensions . . . . . . . . . . . . . . . . 55 106 4.3.2. Certificate Request . . . . . . . . . . . . . . . . . 55 107 4.4. Authentication Messages . . . . . . . . . . . . . . . . . 56 108 4.4.1. The Transcript Hash . . . . . . . . . . . . . . . . . 58 109 4.4.2. Certificate . . . . . . . . . . . . . . . . . . . . . 59 110 4.4.3. Certificate Verify . . . . . . . . . . . . . . . . . 64 111 4.4.4. Finished . . . . . . . . . . . . . . . . . . . . . . 66 112 4.5. End of Early Data . . . . . . . . . . . . . . . . . . . . 68 113 4.6. Post-Handshake Messages . . . . . . . . . . . . . . . . . 68 114 4.6.1. New Session Ticket Message . . . . . . . . . . . . . 68 115 4.6.2. Post-Handshake Authentication . . . . . . . . . . . . 71 116 4.6.3. Key and Initialization Vector Update . . . . . . . . 71 117 5. Record Protocol . . . . . . . . . . . . . . . . . . . . . . . 72 118 5.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 73 119 5.2. Record Payload Protection . . . . . . . . . . . . . . . . 75 120 5.3. Per-Record Nonce . . . . . . . . . . . . . . . . . . . . 77 121 5.4. Record Padding . . . . . . . . . . . . . . . . . . . . . 78 122 5.5. Limits on Key Usage . . . . . . . . . . . . . . . . . . . 79 123 6. Alert Protocol . . . . . . . . . . . . . . . . . . . . . . . 79 124 6.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 81 125 6.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 82 126 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 85 127 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 85 128 7.2. Updating Traffic Secrets . . . . . . . . . . . . . . . . 89 129 7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 89 130 7.4. (EC)DHE Shared Secret Calculation . . . . . . . . . . . . 90 131 7.4.1. Finite Field Diffie-Hellman . . . . . . . . . . . . . 90 132 7.4.2. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 90 133 7.5. Exporters . . . . . . . . . . . . . . . . . . . . . . . . 91 134 8. 0-RTT and Anti-Replay . . . . . . . . . . . . . . . . . . . . 92 135 8.1. Single-Use Tickets . . . . . . . . . . . . . . . . . . . 93 136 8.2. Client Hello Recording . . . . . . . . . . . . . . . . . 93 137 8.3. Freshness Checks . . . . . . . . . . . . . . . . . . . . 95 138 9. Compliance Requirements . . . . . . . . . . . . . . . . . . . 96 139 9.1. Mandatory-to-Implement Cipher Suites . . . . . . . . . . 96 140 9.2. Mandatory-to-Implement Extensions . . . . . . . . . . . . 96 141 9.3. Protocol Invariants . . . . . . . . . . . . . . . . . . . 98 142 10. Security Considerations . . . . . . . . . . . . . . . . . . . 99 143 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 99 144 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 101 145 12.1. Normative References . . . . . . . . . . . . . . . . . . 101 146 12.2. Informative References . . . . . . . . . . . . . . . . . 104 147 Appendix A. State Machine . . . . . . . . . . . . . . . . . . . 112 148 A.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 112 149 A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 113 150 Appendix B. Protocol Data Structures and Constant Values . . . . 114 151 B.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 115 152 B.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 115 153 B.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 116 154 B.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 117 155 B.3.2. Server Parameters Messages . . . . . . . . . . . . . 122 156 B.3.3. Authentication Messages . . . . . . . . . . . . . . . 123 157 B.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 124 158 B.3.5. Updating Keys . . . . . . . . . . . . . . . . . . . . 124 159 B.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 125 160 Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 126 161 C.1. Random Number Generation and Seeding . . . . . . . . . . 126 162 C.2. Certificates and Authentication . . . . . . . . . . . . . 127 163 C.3. Implementation Pitfalls . . . . . . . . . . . . . . . . . 127 164 C.4. Client Tracking Prevention . . . . . . . . . . . . . . . 129 165 C.5. Unauthenticated Operation . . . . . . . . . . . . . . . . 129 166 Appendix D. Backward Compatibility . . . . . . . . . . . . . . . 129 167 D.1. Negotiating with an Older Server . . . . . . . . . . . . 130 168 D.2. Negotiating with an Older Client . . . . . . . . . . . . 131 169 D.3. 0-RTT Backward Compatibility . . . . . . . . . . . . . . 131 170 D.4. Middlebox Compatibility Mode . . . . . . . . . . . . . . 132 171 D.5. Security Restrictions Related to Backward 172 Compatibility . . . . . . . . . . . . . . . . . . . . . . 132 173 Appendix E. Overview of Security Properties . . . . . . . . . . 133 174 E.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 134 175 E.1.1. Key Derivation and HKDF . . . . . . . . . . . . . . . 137 176 E.1.2. Client Authentication . . . . . . . . . . . . . . . . 137 177 E.1.3. 0-RTT . . . . . . . . . . . . . . . . . . . . . . . . 138 178 E.1.4. Exporter Independence . . . . . . . . . . . . . . . . 138 179 E.1.5. Post-Compromise Security . . . . . . . . . . . . . . 138 180 E.1.6. External References . . . . . . . . . . . . . . . . . 138 181 E.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 139 182 E.2.1. External References . . . . . . . . . . . . . . . . . 140 183 E.3. Traffic Analysis . . . . . . . . . . . . . . . . . . . . 140 184 E.4. Side Channel Attacks . . . . . . . . . . . . . . . . . . 141 185 E.5. Replay Attacks on 0-RTT . . . . . . . . . . . . . . . . . 141 186 E.5.1. Replay and Exporters . . . . . . . . . . . . . . . . 143 187 E.6. PSK Identity Exposure . . . . . . . . . . . . . . . . . . 143 188 E.7. Sharing PSKs . . . . . . . . . . . . . . . . . . . . . . 143 189 E.8. Attacks on Static RSA . . . . . . . . . . . . . . . . . . 144 190 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 144 191 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 152 193 1. Introduction 195 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 196 draft is maintained in GitHub. Suggested changes should be submitted 197 as pull requests at https://github.com/ekr/tls13-spec. Instructions 198 are on that page as well. 200 The primary goal of TLS is to provide a secure channel between two 201 communicating peers; the only requirement from the underlying 202 transport is a reliable, in-order, data stream. Specifically, the 203 secure channel should provide the following properties: 205 * Authentication: The server side of the channel is always 206 authenticated; the client side is optionally authenticated. 207 Authentication can happen via asymmetric cryptography (e.g., RSA 208 [RSA], the Elliptic Curve Digital Signature Algorithm (ECDSA) 209 [ECDSA], or the Edwards-Curve Digital Signature Algorithm (EdDSA) 210 [RFC8032]) or a symmetric pre-shared key (PSK). 212 * Confidentiality: Data sent over the channel after establishment is 213 only visible to the endpoints. TLS does not hide the length of 214 the data it transmits, though endpoints are able to pad TLS 215 records in order to obscure lengths and improve protection against 216 traffic analysis techniques. 218 * Integrity: Data sent over the channel after establishment cannot 219 be modified by attackers without detection. 221 These properties should be true even in the face of an attacker who 222 has complete control of the network, as described in [RFC3552]. See 223 Appendix E for a more complete statement of the relevant security 224 properties. 226 TLS consists of two primary components: 228 * A handshake protocol (Section 4) that authenticates the 229 communicating parties, negotiates cryptographic modes and 230 parameters, and establishes shared keying material. The handshake 231 protocol is designed to resist tampering; an active attacker 232 should not be able to force the peers to negotiate different 233 parameters than they would if the connection were not under 234 attack. 236 * A record protocol (Section 5) that uses the parameters established 237 by the handshake protocol to protect traffic between the 238 communicating peers. The record protocol divides traffic up into 239 a series of records, each of which is independently protected 240 using the traffic keys. 242 TLS is application protocol independent; higher-level protocols can 243 layer on top of TLS transparently. The TLS standard, however, does 244 not specify how protocols add security with TLS; how to initiate TLS 245 handshaking and how to interpret the authentication certificates 246 exchanged are left to the judgment of the designers and implementors 247 of protocols that run on top of TLS. 249 This document defines TLS version 1.3. While TLS 1.3 is not directly 250 compatible with previous versions, all versions of TLS incorporate a 251 versioning mechanism which allows clients and servers to 252 interoperably negotiate a common version if one is supported by both 253 peers. 255 This document supersedes and obsoletes previous versions of TLS, 256 including version 1.2 [RFC5246]. It also obsoletes the TLS ticket 257 mechanism defined in [RFC5077] and replaces it with the mechanism 258 defined in Section 2.2. Because TLS 1.3 changes the way keys are 259 derived, it updates [RFC5705] as described in Section 7.5. It also 260 changes how Online Certificate Status Protocol (OCSP) messages are 261 carried and therefore updates [RFC6066] and obsoletes [RFC6961] as 262 described in Section 4.4.2.1. 264 1.1. Conventions and Terminology 266 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 267 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 268 "OPTIONAL" in this document are to be interpreted as described in BCP 269 14 [RFC2119] [RFC8174] when, and only when, they appear in all 270 capitals, as shown here. 272 The following terms are used: 274 client: The endpoint initiating the TLS connection. 276 connection: A transport-layer connection between two endpoints. 278 endpoint: Either the client or server of the connection. 280 handshake: An initial negotiation between client and server that 281 establishes the parameters of their subsequent interactions within 282 TLS. 284 peer: An endpoint. When discussing a particular endpoint, "peer" 285 refers to the endpoint that is not the primary subject of discussion. 287 receiver: An endpoint that is receiving records. 289 sender: An endpoint that is transmitting records. 291 server: The endpoint that did not initiate the TLS connection. 293 1.2. Relationship to RFC 8446 295 TLS 1.3 was originally specified in [RFC8446]. This document is 296 solely an editorial update. It contains updated text in areas which 297 were found to be unclear as well as other editorial improvements. In 298 addition, it removes the use of the term "master" as applied to 299 secrets in favor of the term "main". 301 1.3. Major Differences from TLS 1.2 303 The following is a list of the major functional differences between 304 TLS 1.2 and TLS 1.3. It is not intended to be exhaustive, and there 305 are many minor differences. 307 * The list of supported symmetric encryption algorithms has been 308 pruned of all algorithms that are considered legacy. Those that 309 remain are all Authenticated Encryption with Associated Data 310 (AEAD) algorithms. The cipher suite concept has been changed to 311 separate the authentication and key exchange mechanisms from the 312 record protection algorithm (including secret key length) and a 313 hash to be used with both the key derivation function and 314 handshake message authentication code (MAC). 316 * A zero round-trip time (0-RTT) mode was added, saving a round trip 317 at connection setup for some application data, at the cost of 318 certain security properties. 320 * Static RSA and Diffie-Hellman cipher suites have been removed; all 321 public-key based key exchange mechanisms now provide forward 322 secrecy. 324 * All handshake messages after the ServerHello are now encrypted. 325 The newly introduced EncryptedExtensions message allows various 326 extensions previously sent in the clear in the ServerHello to also 327 enjoy confidentiality protection. 329 * The key derivation function has been redesigned. The new design 330 allows easier analysis by cryptographers due to their improved key 331 separation properties. The HMAC-based Extract-and-Expand Key 332 Derivation Function (HKDF) is used as an underlying primitive. 334 * The handshake state machine has been significantly restructured to 335 be more consistent and to remove superfluous messages such as 336 ChangeCipherSpec (except when needed for middlebox compatibility). 338 * Elliptic curve algorithms are now in the base spec, and new 339 signature algorithms, such as EdDSA, are included. TLS 1.3 340 removed point format negotiation in favor of a single point format 341 for each curve. 343 * Other cryptographic improvements were made, including changing the 344 RSA padding to use the RSA Probabilistic Signature Scheme (RSASSA- 345 PSS), and the removal of compression, the Digital Signature 346 Algorithm (DSA), and custom Ephemeral Diffie-Hellman (DHE) groups. 348 * The TLS 1.2 version negotiation mechanism has been deprecated in 349 favor of a version list in an extension. This increases 350 compatibility with existing servers that incorrectly implemented 351 version negotiation. 353 * Session resumption with and without server-side state as well as 354 the PSK-based cipher suites of earlier TLS versions have been 355 replaced by a single new PSK exchange. 357 * References have been updated to point to the updated versions of 358 RFCs, as appropriate (e.g., RFC 5280 rather than RFC 3280). 360 1.4. Updates Affecting TLS 1.2 362 This document defines several changes that optionally affect 363 implementations of TLS 1.2, including those which do not also support 364 TLS 1.3: 366 * A version downgrade protection mechanism is described in 367 Section 4.1.3. 369 * RSASSA-PSS signature schemes are defined in Section 4.2.3. 371 * The "supported_versions" ClientHello extension can be used to 372 negotiate the version of TLS to use, in preference to the 373 legacy_version field of the ClientHello. 375 * The "signature_algorithms_cert" extension allows a client to 376 indicate which signature algorithms it can validate in X.509 377 certificates. 379 Additionally, this document clarifies some compliance requirements 380 for earlier versions of TLS; see Section 9.3. 382 2. Protocol Overview 384 The cryptographic parameters used by the secure channel are produced 385 by the TLS handshake protocol. This sub-protocol of TLS is used by 386 the client and server when first communicating with each other. The 387 handshake protocol allows peers to negotiate a protocol version, 388 select cryptographic algorithms, authenticate each other (with client 389 authentication being optional), and establish shared secret keying 390 material. Once the handshake is complete, the peers use the 391 established keys to protect the application-layer traffic. 393 A failure of the handshake or other protocol error triggers the 394 termination of the connection, optionally preceded by an alert 395 message (Section 6). 397 TLS supports three basic key exchange modes: 399 * (EC)DHE (Diffie-Hellman over either finite fields or elliptic 400 curves) 402 * PSK-only 404 * PSK with (EC)DHE 406 Figure 1 below shows the basic full TLS handshake: 408 Client Server 410 Key ^ ClientHello 411 Exch | + key_share* 412 | + signature_algorithms* 413 | + psk_key_exchange_modes* 414 v + pre_shared_key* --------> 415 ServerHello ^ Key 416 + key_share* | Exch 417 + pre_shared_key* v 418 {EncryptedExtensions} ^ Server 419 {CertificateRequest*} v Params 420 {Certificate*} ^ 421 {CertificateVerify*} | Auth 422 {Finished} v 423 <-------- [Application Data*] 424 ^ {Certificate*} 425 Auth | {CertificateVerify*} 426 v {Finished} --------> 427 [Application Data] <-------> [Application Data] 429 + Indicates noteworthy extensions sent in the 430 previously noted message. 432 * Indicates optional or situation-dependent 433 messages/extensions that are not always sent. 435 {} Indicates messages protected using keys 436 derived from a [sender]_handshake_traffic_secret. 438 [] Indicates messages protected using keys 439 derived from [sender]_application_traffic_secret_N. 441 Figure 1: Message Flow for Full TLS Handshake 443 The handshake can be thought of as having three phases (indicated in 444 the diagram above): 446 * Key Exchange: Establish shared keying material and select the 447 cryptographic parameters. Everything after this phase is 448 encrypted. 450 * Server Parameters: Establish other handshake parameters (whether 451 the client is authenticated, application-layer protocol support, 452 etc.). 454 * Authentication: Authenticate the server (and, optionally, the 455 client) and provide key confirmation and handshake integrity. 457 In the Key Exchange phase, the client sends the ClientHello 458 (Section 4.1.2) message, which contains a random nonce 459 (ClientHello.random); its offered protocol versions; a list of 460 symmetric cipher/HKDF hash pairs; either a list of Diffie-Hellman key 461 shares (in the "key_share" (Section 4.2.8) extension), a list of pre- 462 shared key labels (in the "pre_shared_key" (Section 4.2.11) 463 extension), or both; and potentially additional extensions. 464 Additional fields and/or messages may also be present for middlebox 465 compatibility. 467 The server processes the ClientHello and determines the appropriate 468 cryptographic parameters for the connection. It then responds with 469 its own ServerHello (Section 4.1.3), which indicates the negotiated 470 connection parameters. The combination of the ClientHello and the 471 ServerHello determines the shared keys. If (EC)DHE key establishment 472 is in use, then the ServerHello contains a "key_share" extension with 473 the server's ephemeral Diffie-Hellman share; the server's share MUST 474 be in the same group as one of the client's shares. If PSK key 475 establishment is in use, then the ServerHello contains a 476 "pre_shared_key" extension indicating which of the client's offered 477 PSKs was selected. Note that implementations can use (EC)DHE and PSK 478 together, in which case both extensions will be supplied. 480 The server then sends two messages to establish the Server 481 Parameters: 483 EncryptedExtensions: responses to ClientHello extensions that are 484 not required to determine the cryptographic parameters, other than 485 those that are specific to individual certificates. 486 [Section 4.3.1] 488 CertificateRequest: if certificate-based client authentication is 489 desired, the desired parameters for that certificate. This 490 message is omitted if client authentication is not desired. 491 [Section 4.3.2] 493 Finally, the client and server exchange Authentication messages. TLS 494 uses the same set of messages every time that certificate-based 495 authentication is needed. (PSK-based authentication happens as a 496 side effect of key exchange.) Specifically: 498 Certificate: The certificate of the endpoint and any per-certificate 499 extensions. This message is omitted by the server if not 500 authenticating with a certificate and by the client if the server 501 did not send CertificateRequest (thus indicating that the client 502 should not authenticate with a certificate). Note that if raw 503 public keys [RFC7250] or the cached information extension 504 [RFC7924] are in use, then this message will not contain a 505 certificate but rather some other value corresponding to the 506 server's long-term key. [Section 4.4.2] 508 CertificateVerify: A signature over the entire handshake using the 509 private key corresponding to the public key in the Certificate 510 message. This message is omitted if the endpoint is not 511 authenticating via a certificate. [Section 4.4.3] 513 Finished: A MAC (Message Authentication Code) over the entire 514 handshake. This message provides key confirmation, binds the 515 endpoint's identity to the exchanged keys, and in PSK mode also 516 authenticates the handshake. [Section 4.4.4] 518 Upon receiving the server's messages, the client responds with its 519 Authentication messages, namely Certificate and CertificateVerify (if 520 requested), and Finished. 522 At this point, the handshake is complete, and the client and server 523 derive the keying material required by the record layer to exchange 524 application-layer data protected through authenticated encryption. 525 Application Data MUST NOT be sent prior to sending the Finished 526 message, except as specified in Section 2.3. Note that while the 527 server may send Application Data prior to receiving the client's 528 Authentication messages, any data sent at that point is, of course, 529 being sent to an unauthenticated peer. 531 2.1. Incorrect DHE Share 533 If the client has not provided a sufficient "key_share" extension 534 (e.g., it includes only DHE or ECDHE groups unacceptable to or 535 unsupported by the server), the server corrects the mismatch with a 536 HelloRetryRequest and the client needs to restart the handshake with 537 an appropriate "key_share" extension, as shown in Figure 2. If no 538 common cryptographic parameters can be negotiated, the server MUST 539 abort the handshake with an appropriate alert. 541 Client Server 543 ClientHello 544 + key_share --------> 545 HelloRetryRequest 546 <-------- + key_share 547 ClientHello 548 + key_share --------> 549 ServerHello 550 + key_share 551 {EncryptedExtensions} 552 {CertificateRequest*} 553 {Certificate*} 554 {CertificateVerify*} 555 {Finished} 556 <-------- [Application Data*] 557 {Certificate*} 558 {CertificateVerify*} 559 {Finished} --------> 560 [Application Data] <-------> [Application Data] 562 Figure 2: Message Flow for a Full Handshake with Mismatched 563 Parameters 565 Note: The handshake transcript incorporates the initial ClientHello/ 566 HelloRetryRequest exchange; it is not reset with the new ClientHello. 568 TLS also allows several optimized variants of the basic handshake, as 569 described in the following sections. 571 2.2. Resumption and Pre-Shared Key (PSK) 573 Although TLS PSKs can be established externally, PSKs can also be 574 established in a previous connection and then used to establish a new 575 connection ("session resumption" or "resuming" with a PSK). Once a 576 handshake has completed, the server can send the client a PSK 577 identity that corresponds to a unique key derived from the initial 578 handshake (see Section 4.6.1). The client can then use that PSK 579 identity in future handshakes to negotiate the use of the associated 580 PSK. If the server accepts the PSK, then the security context of the 581 new connection is cryptographically tied to the original connection 582 and the key derived from the initial handshake is used to bootstrap 583 the cryptographic state instead of a full handshake. In TLS 1.2 and 584 below, this functionality was provided by "session IDs" and "session 585 tickets" [RFC5077]. Both mechanisms are obsoleted in TLS 1.3. 587 PSKs can be used with (EC)DHE key exchange in order to provide 588 forward secrecy in combination with shared keys, or can be used 589 alone, at the cost of losing forward secrecy for the application 590 data. 592 Figure 3 shows a pair of handshakes in which the first handshake 593 establishes a PSK and the second handshake uses it: 595 Client Server 597 Initial Handshake: 598 ClientHello 599 + key_share --------> 600 ServerHello 601 + key_share 602 {EncryptedExtensions} 603 {CertificateRequest*} 604 {Certificate*} 605 {CertificateVerify*} 606 {Finished} 607 <-------- [Application Data*] 608 {Certificate*} 609 {CertificateVerify*} 610 {Finished} --------> 611 <-------- [NewSessionTicket] 612 [Application Data] <-------> [Application Data] 614 Subsequent Handshake: 615 ClientHello 616 + key_share* 617 + pre_shared_key --------> 618 ServerHello 619 + pre_shared_key 620 + key_share* 621 {EncryptedExtensions} 622 {Finished} 623 <-------- [Application Data*] 624 {Finished} --------> 625 [Application Data] <-------> [Application Data] 627 Figure 3: Message Flow for Resumption and PSK 629 As the server is authenticating via a PSK, it does not send a 630 Certificate or a CertificateVerify message. When a client offers 631 resumption via a PSK, it SHOULD also supply a "key_share" extension 632 to the server to allow the server to decline resumption and fall back 633 to a full handshake, if needed. The server responds with a 634 "pre_shared_key" extension to negotiate the use of PSK key 635 establishment and can (as shown here) respond with a "key_share" 636 extension to do (EC)DHE key establishment, thus providing forward 637 secrecy. 639 When PSKs are provisioned externally, the PSK identity and the KDF 640 hash algorithm to be used with the PSK MUST also be provisioned. 642 Note: When using an externally provisioned pre-shared secret, a 643 critical consideration is using sufficient entropy during the key 644 generation, as discussed in [RFC4086]. Deriving a shared secret 645 from a password or other low-entropy sources is not secure. A 646 low-entropy secret, or password, is subject to dictionary attacks 647 based on the PSK binder. The specified PSK authentication is not 648 a strong password-based authenticated key exchange even when used 649 with Diffie-Hellman key establishment. Specifically, it does not 650 prevent an attacker that can observe the handshake from performing 651 a brute-force attack on the password/pre-shared key. 653 2.3. 0-RTT Data 655 When clients and servers share a PSK (either obtained externally or 656 via a previous handshake), TLS 1.3 allows clients to send data on the 657 first flight ("early data"). The client uses the PSK to authenticate 658 the server and to encrypt the early data. 660 As shown in Figure 4, the 0-RTT data is just added to the 1-RTT 661 handshake in the first flight. The rest of the handshake uses the 662 same messages as for a 1-RTT handshake with PSK resumption. 664 Client Server 666 ClientHello 667 + early_data 668 + key_share* 669 + psk_key_exchange_modes 670 + pre_shared_key 671 (Application Data*) --------> 672 ServerHello 673 + pre_shared_key 674 + key_share* 675 {EncryptedExtensions} 676 + early_data* 677 {Finished} 678 <-------- [Application Data*] 679 (EndOfEarlyData) 680 {Finished} --------> 681 [Application Data] <-------> [Application Data] 683 + Indicates noteworthy extensions sent in the 684 previously noted message. 686 * Indicates optional or situation-dependent 687 messages/extensions that are not always sent. 689 () Indicates messages protected using keys 690 derived from a client_early_traffic_secret. 692 {} Indicates messages protected using keys 693 derived from a [sender]_handshake_traffic_secret. 695 [] Indicates messages protected using keys 696 derived from [sender]_application_traffic_secret_N. 698 Figure 4: Message Flow for a 0-RTT Handshake 700 IMPORTANT NOTE: The security properties for 0-RTT data are weaker 701 than those for other kinds of TLS data. Specifically: 703 1. This data is not forward secret, as it is encrypted solely under 704 keys derived using the offered PSK. 706 2. There are no guarantees of non-replay between connections. 707 Protection against replay for ordinary TLS 1.3 1-RTT data is 708 provided via the server's Random value, but 0-RTT data does not 709 depend on the ServerHello and therefore has weaker guarantees. 710 This is especially relevant if the data is authenticated either 711 with TLS client authentication or inside the application 712 protocol. The same warnings apply to any use of the 713 early_exporter_main_secret. 715 0-RTT data cannot be duplicated within a connection (i.e., the server 716 will not process the same data twice for the same connection), and an 717 attacker will not be able to make 0-RTT data appear to be 1-RTT data 718 (because it is protected with different keys). Appendix E.5 contains 719 a description of potential attacks, and Section 8 describes 720 mechanisms which the server can use to limit the impact of replay. 722 3. Presentation Language 724 This document deals with the formatting of data in an external 725 representation. The following very basic and somewhat casually 726 defined presentation syntax will be used. 728 3.1. Basic Block Size 730 The representation of all data items is explicitly specified. The 731 basic data block size is one byte (i.e., 8 bits). Multiple-byte data 732 items are concatenations of bytes, from left to right, from top to 733 bottom. From the byte stream, a multi-byte item (a numeric in the 734 following example) is formed (using C notation) by: 736 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 737 ... | byte[n-1]; 739 This byte ordering for multi-byte values is the commonplace network 740 byte order or big-endian format. 742 3.2. Miscellaneous 744 Comments begin with "/*" and end with "*/". 746 Optional components are denoted by enclosing them in "[[ ]]" (double 747 brackets). 749 Single-byte entities containing uninterpreted data are of type 750 opaque. 752 A type alias T' for an existing type T is defined by: 754 T T'; 756 3.3. Numbers 758 The basic numeric data type is an unsigned byte (uint8). All larger 759 numeric data types are constructed from a fixed-length series of 760 bytes concatenated as described in Section 3.1 and are also unsigned. 761 The following numeric types are predefined. 763 uint8 uint16[2]; 764 uint8 uint24[3]; 765 uint8 uint32[4]; 766 uint8 uint64[8]; 768 All values, here and elsewhere in the specification, are transmitted 769 in network byte (big-endian) order; the uint32 represented by the hex 770 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 772 3.4. Vectors 774 A vector (single-dimensioned array) is a stream of homogeneous data 775 elements. For presentation purposes, this specification refers to 776 vectors as lists. The size of the vector may be specified at 777 documentation time or left unspecified until runtime. In either 778 case, the length declares the number of bytes, not the number of 779 elements, in the vector. The syntax for specifying a new type, T', 780 that is a fixed-length vector of type T is 782 T T'[n]; 784 Here, T' occupies n bytes in the data stream, where n is a multiple 785 of the size of T. The length of the vector is not included in the 786 encoded stream. 788 In the following example, Datum is defined to be three consecutive 789 bytes that the protocol does not interpret, while Data is three 790 consecutive Datum, consuming a total of nine bytes. 792 opaque Datum[3]; /* three uninterpreted bytes */ 793 Datum Data[9]; /* three consecutive 3-byte vectors */ 795 Variable-length vectors are defined by specifying a subrange of legal 796 lengths, inclusively, using the notation . When 797 these are encoded, the actual length precedes the vector's contents 798 in the byte stream. The length will be in the form of a number 799 consuming as many bytes as required to hold the vector's specified 800 maximum (ceiling) length. A variable-length vector with an actual 801 length field of zero is referred to as an empty vector. 803 T T'; 805 In the following example, "mandatory" is a vector that must contain 806 between 300 and 400 bytes of type opaque. It can never be empty. 807 The actual length field consumes two bytes, a uint16, which is 808 sufficient to represent the value 400 (see Section 3.3). Similarly, 809 "longer" can represent up to 800 bytes of data, or 400 uint16 810 elements, and it may be empty. Its encoding will include a two-byte 811 actual length field prepended to the vector. The length of an 812 encoded vector must be an exact multiple of the length of a single 813 element (e.g., a 17-byte vector of uint16 would be illegal). 815 opaque mandatory<300..400>; 816 /* length field is two bytes, cannot be empty */ 817 uint16 longer<0..800>; 818 /* zero to 400 16-bit unsigned integers */ 820 3.5. Enumerateds 822 An additional sparse data type, called "enum" or "enumerated", is 823 available. Each definition is a different type. Only enumerateds of 824 the same type may be assigned or compared. Every element of an 825 enumerated must be assigned a value, as demonstrated in the following 826 example. Since the elements of the enumerated are not ordered, they 827 can be assigned any unique value, in any order. 829 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 831 Future extensions or additions to the protocol may define new values. 832 Implementations need to be able to parse and ignore unknown values 833 unless the definition of the field states otherwise. 835 An enumerated occupies as much space in the byte stream as would its 836 maximal defined ordinal value. The following definition would cause 837 one byte to be used to carry fields of type Color. 839 enum { red(3), blue(5), white(7) } Color; 841 One may optionally specify a value without its associated tag to 842 force the width definition without defining a superfluous element. 844 In the following example, Taste will consume two bytes in the data 845 stream but can only assume the values 1, 2, or 4 in the current 846 version of the protocol. 848 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 850 The names of the elements of an enumeration are scoped within the 851 defined type. In the first example, a fully qualified reference to 852 the second element of the enumeration would be Color.blue. Such 853 qualification is not required if the target of the assignment is well 854 specified. 856 Color color = Color.blue; /* overspecified, legal */ 857 Color color = blue; /* correct, type implicit */ 859 The names assigned to enumerateds do not need to be unique. The 860 numerical value can describe a range over which the same name 861 applies. The value includes the minimum and maximum inclusive values 862 in that range, separated by two period characters. This is 863 principally useful for reserving regions of the space. 865 enum { sad(0), meh(1..254), happy(255) } Mood; 867 3.6. Constructed Types 869 Structure types may be constructed from primitive types for 870 convenience. Each specification declares a new, unique type. The 871 syntax used for definitions is much like that of C. 873 struct { 874 T1 f1; 875 T2 f2; 876 ... 877 Tn fn; 878 } T; 880 Fixed- and variable-length list (vector) fields are allowed using the 881 standard list syntax. Structures V1 and V2 in the variants example 882 (Section 3.8) demonstrate this. 884 The fields within a structure may be qualified using the type's name, 885 with a syntax much like that available for enumerateds. For example, 886 T.f2 refers to the second field of the previous declaration. 888 3.7. Constants 890 Fields and variables may be assigned a fixed value using "=", as in: 892 struct { 893 T1 f1 = 8; /* T.f1 must always be 8 */ 894 T2 f2; 895 } T; 897 3.8. Variants 899 Defined structures may have variants based on some knowledge that is 900 available within the environment. The selector must be an enumerated 901 type that defines the possible variants the structure defines. Each 902 arm of the select (below) specifies the type of that variant's field 903 and an optional field label. The mechanism by which the variant is 904 selected at runtime is not prescribed by the presentation language. 906 struct { 907 T1 f1; 908 T2 f2; 909 .... 910 Tn fn; 911 select (E) { 912 case e1: Te1 [[fe1]]; 913 case e2: Te2 [[fe2]]; 914 .... 915 case en: Ten [[fen]]; 916 }; 917 } Tv; 919 For example: 921 enum { apple(0), orange(1) } VariantTag; 923 struct { 924 uint16 number; 925 opaque string<0..10>; /* variable length */ 926 } V1; 928 struct { 929 uint32 number; 930 opaque string[10]; /* fixed length */ 931 } V2; 933 struct { 934 VariantTag type; 935 select (VariantRecord.type) { 936 case apple: V1; 937 case orange: V2; 938 }; 939 } VariantRecord; 941 4. Handshake Protocol 943 The handshake protocol is used to negotiate the security parameters 944 of a connection. Handshake messages are supplied to the TLS record 945 layer, where they are encapsulated within one or more TLSPlaintext or 946 TLSCiphertext structures which are processed and transmitted as 947 specified by the current active connection state. 949 enum { 950 client_hello(1), 951 server_hello(2), 952 new_session_ticket(4), 953 end_of_early_data(5), 954 encrypted_extensions(8), 955 certificate(11), 956 certificate_request(13), 957 certificate_verify(15), 958 finished(20), 959 key_update(24), 960 message_hash(254), 961 (255) 962 } HandshakeType; 964 struct { 965 HandshakeType msg_type; /* handshake type */ 966 uint24 length; /* remaining bytes in message */ 967 select (Handshake.msg_type) { 968 case client_hello: ClientHello; 969 case server_hello: ServerHello; 970 case end_of_early_data: EndOfEarlyData; 971 case encrypted_extensions: EncryptedExtensions; 972 case certificate_request: CertificateRequest; 973 case certificate: Certificate; 974 case certificate_verify: CertificateVerify; 975 case finished: Finished; 976 case new_session_ticket: NewSessionTicket; 977 case key_update: KeyUpdate; 978 }; 979 } Handshake; 981 Protocol messages MUST be sent in the order defined in Section 4.4.1 982 and shown in the diagrams in Section 2. A peer which receives a 983 handshake message in an unexpected order MUST abort the handshake 984 with an "unexpected_message" alert. 986 New handshake message types are assigned by IANA as described in 987 Section 11. 989 4.1. Key Exchange Messages 991 The key exchange messages are used to determine the security 992 capabilities of the client and the server and to establish shared 993 secrets, including the traffic keys used to protect the rest of the 994 handshake and the data. 996 4.1.1. Cryptographic Negotiation 998 In TLS, the cryptographic negotiation proceeds by the client offering 999 the following four sets of options in its ClientHello: 1001 * A list of cipher suites which indicates the AEAD algorithm/HKDF 1002 hash pairs which the client supports. 1004 * A "supported_groups" (Section 4.2.7) extension which indicates the 1005 (EC)DHE groups which the client supports and a "key_share" 1006 (Section 4.2.8) extension which contains (EC)DHE shares for some 1007 or all of these groups. 1009 * A "signature_algorithms" (Section 4.2.3) extension which indicates 1010 the signature algorithms which the client can accept. A 1011 "signature_algorithms_cert" extension (Section 4.2.3) may also be 1012 added to indicate certificate-specific signature algorithms. 1014 * A "pre_shared_key" (Section 4.2.11) extension which contains a 1015 list of symmetric key identities known to the client and a 1016 "psk_key_exchange_modes" (Section 4.2.9) extension which indicates 1017 the key exchange modes that may be used with PSKs. 1019 If the server does not select a PSK, then the first three of these 1020 options are entirely orthogonal: the server independently selects a 1021 cipher suite, an (EC)DHE group and key share for key establishment, 1022 and a signature algorithm/certificate pair to authenticate itself to 1023 the client. If there is no overlap between the received 1024 "supported_groups" and the groups supported by the server, then the 1025 server MUST abort the handshake with a "handshake_failure" or an 1026 "insufficient_security" alert. 1028 If the server selects a PSK, then it MUST also select a key 1029 establishment mode from the list indicated by the client's 1030 "psk_key_exchange_modes" extension (at present, PSK alone or with 1031 (EC)DHE). Note that if the PSK can be used without (EC)DHE, then 1032 non-overlap in the "supported_groups" parameters need not be fatal, 1033 as it is in the non-PSK case discussed in the previous paragraph. 1035 If the server selects an (EC)DHE group and the client did not offer a 1036 compatible "key_share" extension in the initial ClientHello, the 1037 server MUST respond with a HelloRetryRequest (Section 4.1.4) message. 1039 If the server successfully selects parameters and does not require a 1040 HelloRetryRequest, it indicates the selected parameters in the 1041 ServerHello as follows: 1043 * If PSK is being used, then the server will send a "pre_shared_key" 1044 extension indicating the selected key. 1046 * When (EC)DHE is in use, the server will also provide a "key_share" 1047 extension. If PSK is not being used, then (EC)DHE and 1048 certificate-based authentication are always used. 1050 * When authenticating via a certificate, the server will send the 1051 Certificate (Section 4.4.2) and CertificateVerify (Section 4.4.3) 1052 messages. In TLS 1.3 as defined by this document, either a PSK or 1053 a certificate is always used, but not both. Future documents may 1054 define how to use them together. 1056 If the server is unable to negotiate a supported set of parameters 1057 (i.e., there is no overlap between the client and server parameters), 1058 it MUST abort the handshake with either a "handshake_failure" or 1059 "insufficient_security" fatal alert (see Section 6). 1061 4.1.2. Client Hello 1063 When a client first connects to a server, it is REQUIRED to send the 1064 ClientHello as its first TLS message. The client will also send a 1065 ClientHello when the server has responded to its ClientHello with a 1066 HelloRetryRequest. In that case, the client MUST send the same 1067 ClientHello without modification, except as follows: 1069 * If a "key_share" extension was supplied in the HelloRetryRequest, 1070 replacing the list of shares with a list containing a single 1071 KeyShareEntry from the indicated group. 1073 * Removing the "early_data" extension (Section 4.2.10) if one was 1074 present. Early data is not permitted after a HelloRetryRequest. 1076 * Including a "cookie" extension if one was provided in the 1077 HelloRetryRequest. 1079 * Updating the "pre_shared_key" extension if present by recomputing 1080 the "obfuscated_ticket_age" and binder values and (optionally) 1081 removing any PSKs which are incompatible with the server's 1082 indicated cipher suite. 1084 * Optionally adding, removing, or changing the length of the 1085 "padding" extension [RFC7685]. 1087 * Other modifications that may be allowed by an extension defined in 1088 the future and present in the HelloRetryRequest. 1090 Because TLS 1.3 forbids renegotiation, if a server has negotiated TLS 1091 1.3 and receives a ClientHello at any other time, it MUST terminate 1092 the connection with an "unexpected_message" alert. 1094 If a server established a TLS connection with a previous version of 1095 TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST 1096 retain the previous protocol version. In particular, it MUST NOT 1097 negotiate TLS 1.3. 1099 Structure of this message: 1101 uint16 ProtocolVersion; 1102 opaque Random[32]; 1104 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1106 struct { 1107 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 1108 Random random; 1109 opaque legacy_session_id<0..32>; 1110 CipherSuite cipher_suites<2..2^16-2>; 1111 opaque legacy_compression_methods<1..2^8-1>; 1112 Extension extensions<8..2^16-1>; 1113 } ClientHello; 1115 legacy_version: In previous versions of TLS, this field was used for 1116 version negotiation and represented the highest version number 1117 supported by the client. Experience has shown that many servers 1118 do not properly implement version negotiation, leading to "version 1119 intolerance" in which the server rejects an otherwise acceptable 1120 ClientHello with a version number higher than it supports. In TLS 1121 1.3, the client indicates its version preferences in the 1122 "supported_versions" extension (Section 4.2.1) and the 1123 legacy_version field MUST be set to 0x0303, which is the version 1124 number for TLS 1.2. TLS 1.3 ClientHellos are identified as having 1125 a legacy_version of 0x0303 and a supported_versions extension 1126 present with 0x0304 as the highest version indicated therein. 1127 (See Appendix D for details about backward compatibility.) A 1128 server which receives a legacy_version value not equal to 0x0303 1129 MUST abort the handshake with an "illegal_parameter" alert. 1131 random: 32 bytes generated by a secure random number generator. See 1132 Appendix C for additional information. 1134 legacy_session_id: Versions of TLS before TLS 1.3 supported a 1135 "session resumption" feature which has been merged with pre-shared 1136 keys in this version (see Section 2.2). A client which has a 1137 cached session ID set by a pre-TLS 1.3 server SHOULD set this 1138 field to that value. In compatibility mode (see Appendix D.4), 1139 this field MUST be non-empty, so a client not offering a pre-TLS 1140 1.3 session MUST generate a new 32-byte value. This value need 1141 not be random but SHOULD be unpredictable to avoid implementations 1142 fixating on a specific value (also known as ossification). 1143 Otherwise, it MUST be set as a zero-length list (i.e., a zero- 1144 valued single byte length field). 1146 cipher_suites: A list of the symmetric cipher options supported by 1147 the client, specifically the record protection algorithm 1148 (including secret key length) and a hash to be used with HKDF, in 1149 descending order of client preference. Values are defined in 1150 Appendix B.4. If the list contains cipher suites that the server 1151 does not recognize, support, or wish to use, the server MUST 1152 ignore those cipher suites and process the remaining ones as 1153 usual. If the client is attempting a PSK key establishment, it 1154 SHOULD advertise at least one cipher suite indicating a Hash 1155 associated with the PSK. 1157 legacy_compression_methods: Versions of TLS before 1.3 supported 1158 compression with the list of supported compression methods being 1159 sent in this field. For every TLS 1.3 ClientHello, this list MUST 1160 contain exactly one byte, set to zero, which corresponds to the 1161 "null" compression method in prior versions of TLS. If a TLS 1.3 1162 ClientHello is received with any other value in this field, the 1163 server MUST abort the handshake with an "illegal_parameter" alert. 1164 Note that TLS 1.3 servers might receive TLS 1.2 or prior 1165 ClientHellos which contain other compression methods and (if 1166 negotiating such a prior version) MUST follow the procedures for 1167 the appropriate prior version of TLS. 1169 extensions: Clients request extended functionality from servers by 1170 sending data in the extensions field. The actual "Extension" 1171 format is defined in Section 4.2. In TLS 1.3, the use of certain 1172 extensions is mandatory, as functionality has moved into 1173 extensions to preserve ClientHello compatibility with previous 1174 versions of TLS. Servers MUST ignore unrecognized extensions. 1176 All versions of TLS allow an extensions field to optionally follow 1177 the compression_methods field. TLS 1.3 ClientHello messages always 1178 contain extensions (minimally "supported_versions", otherwise, they 1179 will be interpreted as TLS 1.2 ClientHello messages). However, TLS 1180 1.3 servers might receive ClientHello messages without an extensions 1181 field from prior versions of TLS. The presence of extensions can be 1182 detected by determining whether there are bytes following the 1183 compression_methods field at the end of the ClientHello. Note that 1184 this method of detecting optional data differs from the normal TLS 1185 method of having a variable-length field, but it is used for 1186 compatibility with TLS before extensions were defined. TLS 1.3 1187 servers will need to perform this check first and only attempt to 1188 negotiate TLS 1.3 if the "supported_versions" extension is present. 1189 If negotiating a version of TLS prior to 1.3, a server MUST check 1190 that the message either contains no data after 1191 legacy_compression_methods or that it contains a valid extensions 1192 block with no data following. If not, then it MUST abort the 1193 handshake with a "decode_error" alert. 1195 In the event that a client requests additional functionality using 1196 extensions and this functionality is not supplied by the server, the 1197 client MAY abort the handshake. 1199 After sending the ClientHello message, the client waits for a 1200 ServerHello or HelloRetryRequest message. If early data is in use, 1201 the client may transmit early Application Data (Section 2.3) while 1202 waiting for the next handshake message. 1204 4.1.3. Server Hello 1206 The server will send this message in response to a ClientHello 1207 message to proceed with the handshake if it is able to negotiate an 1208 acceptable set of handshake parameters based on the ClientHello. 1210 Structure of this message: 1212 struct { 1213 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 1214 Random random; 1215 opaque legacy_session_id_echo<0..32>; 1216 CipherSuite cipher_suite; 1217 uint8 legacy_compression_method = 0; 1218 Extension extensions<6..2^16-1>; 1219 } ServerHello; 1221 legacy_version: In previous versions of TLS, this field was used for 1222 version negotiation and represented the selected version number 1223 for the connection. Unfortunately, some middleboxes fail when 1224 presented with new values. In TLS 1.3, the TLS server indicates 1225 its version using the "supported_versions" extension 1226 (Section 4.2.1), and the legacy_version field MUST be set to 1227 0x0303, which is the version number for TLS 1.2. (See Appendix D 1228 for details about backward compatibility.) 1230 random: 32 bytes generated by a secure random number generator. See 1231 Appendix C for additional information. The last 8 bytes MUST be 1232 overwritten as described below if negotiating TLS 1.2 or TLS 1.1, 1233 but the remaining bytes MUST be random. This structure is 1234 generated by the server and MUST be generated independently of the 1235 ClientHello.random. 1237 legacy_session_id_echo: The contents of the client's 1238 legacy_session_id field. Note that this field is echoed even if 1239 the client's value corresponded to a cached pre-TLS 1.3 session 1240 which the server has chosen not to resume. A client which 1241 receives a legacy_session_id_echo field that does not match what 1242 it sent in the ClientHello MUST abort the handshake with an 1243 "illegal_parameter" alert. 1245 cipher_suite: The single cipher suite selected by the server from 1246 the ClientHello.cipher_suites list. A client which receives a 1247 cipher suite that was not offered MUST abort the handshake with an 1248 "illegal_parameter" alert. 1250 legacy_compression_method: A single byte which MUST have the value 1251 0. 1253 extensions: A list of extensions. The ServerHello MUST only include 1254 extensions which are required to establish the cryptographic 1255 context and negotiate the protocol version. All TLS 1.3 1256 ServerHello messages MUST contain the "supported_versions" 1257 extension. Current ServerHello messages additionally contain 1258 either the "pre_shared_key" extension or the "key_share" 1259 extension, or both (when using a PSK with (EC)DHE key 1260 establishment). Other extensions (see Section 4.2) are sent 1261 separately in the EncryptedExtensions message. 1263 For reasons of backward compatibility with middleboxes (see 1264 Appendix D.4), the HelloRetryRequest message uses the same structure 1265 as the ServerHello, but with Random set to the special value of the 1266 SHA-256 of "HelloRetryRequest": 1268 CF 21 AD 74 E5 9A 61 11 BE 1D 8C 02 1E 65 B8 91 1269 C2 A2 11 16 7A BB 8C 5E 07 9E 09 E2 C8 A8 33 9C 1271 Upon receiving a message with type server_hello, implementations MUST 1272 first examine the Random value and, if it matches this value, process 1273 it as described in Section 4.1.4). 1275 TLS 1.3 has a downgrade protection mechanism embedded in the server's 1276 random value. TLS 1.3 servers which negotiate TLS 1.2 or below in 1277 response to a ClientHello MUST set the last 8 bytes of their Random 1278 value specially in their ServerHello. 1280 If negotiating TLS 1.2, TLS 1.3 servers MUST set the last 8 bytes of 1281 their Random value to the bytes: 1283 44 4F 57 4E 47 52 44 01 1285 If negotiating TLS 1.1 or below, TLS 1.3 servers MUST, and TLS 1.2 1286 servers SHOULD, set the last 8 bytes of their ServerHello.Random 1287 value to the bytes: 1289 44 4F 57 4E 47 52 44 00 1291 TLS 1.3 clients receiving a ServerHello indicating TLS 1.2 or below 1292 MUST check that the last 8 bytes are not equal to either of these 1293 values. TLS 1.2 clients SHOULD also check that the last 8 bytes are 1294 not equal to the second value if the ServerHello indicates TLS 1.1 or 1295 below. If a match is found, the client MUST abort the handshake with 1296 an "illegal_parameter" alert. This mechanism provides limited 1297 protection against downgrade attacks over and above what is provided 1298 by the Finished exchange: because the ServerKeyExchange, a message 1299 present in TLS 1.2 and below, includes a signature over both random 1300 values, it is not possible for an active attacker to modify the 1301 random values without detection as long as ephemeral ciphers are 1302 used. It does not provide downgrade protection when static RSA is 1303 used. 1305 Note: This is a change from [RFC5246], so in practice many TLS 1.2 1306 clients and servers will not behave as specified above. 1308 A legacy TLS client performing renegotiation with TLS 1.2 or prior 1309 and which receives a TLS 1.3 ServerHello during renegotiation MUST 1310 abort the handshake with a "protocol_version" alert. Note that 1311 renegotiation is not possible when TLS 1.3 has been negotiated. 1313 4.1.4. Hello Retry Request 1315 The server will send this message in response to a ClientHello 1316 message if it is able to find an acceptable set of parameters but the 1317 ClientHello does not contain sufficient information to proceed with 1318 the handshake. As discussed in Section 4.1.3, the HelloRetryRequest 1319 has the same format as a ServerHello message, and the legacy_version, 1320 legacy_session_id_echo, cipher_suite, and legacy_compression_method 1321 fields have the same meaning. However, for convenience we discuss 1322 "HelloRetryRequest" throughout this document as if it were a distinct 1323 message. 1325 The server's extensions MUST contain "supported_versions". 1326 Additionally, it SHOULD contain the minimal set of extensions 1327 necessary for the client to generate a correct ClientHello pair. As 1328 with the ServerHello, a HelloRetryRequest MUST NOT contain any 1329 extensions that were not first offered by the client in its 1330 ClientHello, with the exception of optionally the "cookie" (see 1331 Section 4.2.2) extension. 1333 Upon receipt of a HelloRetryRequest, the client MUST check the 1334 legacy_version, legacy_session_id_echo, cipher_suite, and 1335 legacy_compression_method as specified in Section 4.1.3 and then 1336 process the extensions, starting with determining the version using 1337 "supported_versions". Clients MUST abort the handshake with an 1338 "illegal_parameter" alert if the HelloRetryRequest would not result 1339 in any change in the ClientHello. If a client receives a second 1340 HelloRetryRequest in the same connection (i.e., where the ClientHello 1341 was itself in response to a HelloRetryRequest), it MUST abort the 1342 handshake with an "unexpected_message" alert. 1344 Otherwise, the client MUST process all extensions in the 1345 HelloRetryRequest and send a second updated ClientHello. The 1346 HelloRetryRequest extensions defined in this specification are: 1348 * supported_versions (see Section 4.2.1) 1350 * cookie (see Section 4.2.2) 1352 * key_share (see Section 4.2.8) 1353 A client which receives a cipher suite that was not offered MUST 1354 abort the handshake. Servers MUST ensure that they negotiate the 1355 same cipher suite when receiving a conformant updated ClientHello (if 1356 the server selects the cipher suite as the first step in the 1357 negotiation, then this will happen automatically). Upon receiving 1358 the ServerHello, clients MUST check that the cipher suite supplied in 1359 the ServerHello is the same as that in the HelloRetryRequest and 1360 otherwise abort the handshake with an "illegal_parameter" alert. 1362 In addition, in its updated ClientHello, the client SHOULD NOT offer 1363 any pre-shared keys associated with a hash other than that of the 1364 selected cipher suite. This allows the client to avoid having to 1365 compute partial hash transcripts for multiple hashes in the second 1366 ClientHello. 1368 The value of selected_version in the HelloRetryRequest 1369 "supported_versions" extension MUST be retained in the ServerHello, 1370 and a client MUST abort the handshake with an "illegal_parameter" 1371 alert if the value changes. 1373 4.2. Extensions 1375 A number of TLS messages contain tag-length-value encoded extensions 1376 structures. 1378 struct { 1379 ExtensionType extension_type; 1380 opaque extension_data<0..2^16-1>; 1381 } Extension; 1383 enum { 1384 server_name(0), /* RFC 6066 */ 1385 max_fragment_length(1), /* RFC 6066 */ 1386 status_request(5), /* RFC 6066 */ 1387 supported_groups(10), /* RFC 8422, 7919 */ 1388 signature_algorithms(13), /* RFC 8446 */ 1389 use_srtp(14), /* RFC 5764 */ 1390 heartbeat(15), /* RFC 6520 */ 1391 application_layer_protocol_negotiation(16), /* RFC 7301 */ 1392 signed_certificate_timestamp(18), /* RFC 6962 */ 1393 client_certificate_type(19), /* RFC 7250 */ 1394 server_certificate_type(20), /* RFC 7250 */ 1395 padding(21), /* RFC 7685 */ 1396 pre_shared_key(41), /* RFC 8446 */ 1397 early_data(42), /* RFC 8446 */ 1398 supported_versions(43), /* RFC 8446 */ 1399 cookie(44), /* RFC 8446 */ 1400 psk_key_exchange_modes(45), /* RFC 8446 */ 1401 certificate_authorities(47), /* RFC 8446 */ 1402 oid_filters(48), /* RFC 8446 */ 1403 post_handshake_auth(49), /* RFC 8446 */ 1404 signature_algorithms_cert(50), /* RFC 8446 */ 1405 key_share(51), /* RFC 8446 */ 1406 (65535) 1407 } ExtensionType; 1409 Here: 1411 * "extension_type" identifies the particular extension type. 1413 * "extension_data" contains information specific to the particular 1414 extension type. 1416 The list of extension types is maintained by IANA as described in 1417 Section 11. 1419 Extensions are generally structured in a request/response fashion, 1420 though some extensions are just indications with no corresponding 1421 response. The client sends its extension requests in the ClientHello 1422 message, and the server sends its extension responses in the 1423 ServerHello, EncryptedExtensions, HelloRetryRequest, and Certificate 1424 messages. The server sends extension requests in the 1425 CertificateRequest message which a client MAY respond to with a 1426 Certificate message. The server MAY also send unsolicited extensions 1427 in the NewSessionTicket, though the client does not respond directly 1428 to these. 1430 Implementations MUST NOT send extension responses if the remote 1431 endpoint did not send the corresponding extension requests, with the 1432 exception of the "cookie" extension in the HelloRetryRequest. Upon 1433 receiving such an extension, an endpoint MUST abort the handshake 1434 with an "unsupported_extension" alert. 1436 The table below indicates the messages where a given extension may 1437 appear, using the following notation: CH (ClientHello), SH 1438 (ServerHello), EE (EncryptedExtensions), CT (Certificate), CR 1439 (CertificateRequest), NST (NewSessionTicket), and HRR 1440 (HelloRetryRequest). If an implementation receives an extension 1441 which it recognizes and which is not specified for the message in 1442 which it appears, it MUST abort the handshake with an 1443 "illegal_parameter" alert. 1445 +==================================================+=============+ 1446 | Extension | TLS 1.3 | 1447 +==================================================+=============+ 1448 | server_name [RFC6066] | CH, EE | 1449 +--------------------------------------------------+-------------+ 1450 | max_fragment_length [RFC6066] | CH, EE | 1451 +--------------------------------------------------+-------------+ 1452 | status_request [RFC6066] | CH, CR, CT | 1453 +--------------------------------------------------+-------------+ 1454 | supported_groups [RFC7919] | CH, EE | 1455 +--------------------------------------------------+-------------+ 1456 | signature_algorithms (RFC8446) | CH, CR | 1457 +--------------------------------------------------+-------------+ 1458 | use_srtp [RFC5764] | CH, EE | 1459 +--------------------------------------------------+-------------+ 1460 | heartbeat [RFC6520] | CH, EE | 1461 +--------------------------------------------------+-------------+ 1462 | application_layer_protocol_negotiation [RFC7301] | CH, EE | 1463 +--------------------------------------------------+-------------+ 1464 | signed_certificate_timestamp [RFC6962] | CH, CR, CT | 1465 +--------------------------------------------------+-------------+ 1466 | client_certificate_type [RFC7250] | CH, EE | 1467 +--------------------------------------------------+-------------+ 1468 | server_certificate_type [RFC7250] | CH, EE | 1469 +--------------------------------------------------+-------------+ 1470 | padding [RFC7685] | CH | 1471 +--------------------------------------------------+-------------+ 1472 | key_share (RFC 8446) | CH, SH, HRR | 1473 +--------------------------------------------------+-------------+ 1474 | pre_shared_key (RFC 8446) | CH, SH | 1475 +--------------------------------------------------+-------------+ 1476 | psk_key_exchange_modes (RFC 8446) | CH | 1477 +--------------------------------------------------+-------------+ 1478 | early_data (RFC 8446) | CH, EE, NST | 1479 +--------------------------------------------------+-------------+ 1480 | cookie (RFC 8446) | CH, HRR | 1481 +--------------------------------------------------+-------------+ 1482 | supported_versions (RFC 8446) | CH, SH, HRR | 1483 +--------------------------------------------------+-------------+ 1484 | certificate_authorities (RFC 8446) | CH, CR | 1485 +--------------------------------------------------+-------------+ 1486 | oid_filters (RFC 8446) | CR | 1487 +--------------------------------------------------+-------------+ 1488 | post_handshake_auth (RFC 8446) | CH | 1489 +--------------------------------------------------+-------------+ 1490 | signature_algorithms_cert (RFC 8446) | CH, CR | 1491 +--------------------------------------------------+-------------+ 1493 Table 1: TLS Extensions 1495 When multiple extensions of different types are present, the 1496 extensions MAY appear in any order, with the exception of 1497 "pre_shared_key" (Section 4.2.11) which MUST be the last extension in 1498 the ClientHello (but can appear anywhere in the ServerHello 1499 extensions block). There MUST NOT be more than one extension of the 1500 same type in a given extension block. 1502 In TLS 1.3, unlike TLS 1.2, extensions are negotiated for each 1503 handshake even when in resumption-PSK mode. However, 0-RTT 1504 parameters are those negotiated in the previous handshake; mismatches 1505 may require rejecting 0-RTT (see Section 4.2.10). 1507 There are subtle (and not so subtle) interactions that may occur in 1508 this protocol between new features and existing features which may 1509 result in a significant reduction in overall security. The following 1510 considerations should be taken into account when designing new 1511 extensions: 1513 * Some cases where a server does not agree to an extension are error 1514 conditions (e.g., the handshake cannot continue), and some are 1515 simply refusals to support particular features. In general, error 1516 alerts should be used for the former and a field in the server 1517 extension response for the latter. 1519 * Extensions should, as far as possible, be designed to prevent any 1520 attack that forces use (or non-use) of a particular feature by 1521 manipulation of handshake messages. This principle should be 1522 followed regardless of whether the feature is believed to cause a 1523 security problem. Often the fact that the extension fields are 1524 included in the inputs to the Finished message hashes will be 1525 sufficient, but extreme care is needed when the extension changes 1526 the meaning of messages sent in the handshake phase. Designers 1527 and implementors should be aware of the fact that until the 1528 handshake has been authenticated, active attackers can modify 1529 messages and insert, remove, or replace extensions. 1531 4.2.1. Supported Versions 1533 struct { 1534 select (Handshake.msg_type) { 1535 case client_hello: 1536 ProtocolVersion versions<2..254>; 1538 case server_hello: /* and HelloRetryRequest */ 1539 ProtocolVersion selected_version; 1540 }; 1541 } SupportedVersions; 1543 The "supported_versions" extension is used by the client to indicate 1544 which versions of TLS it supports and by the server to indicate which 1545 version it is using. The extension contains a list of supported 1546 versions in preference order, with the most preferred version first. 1547 Implementations of this specification MUST send this extension in the 1548 ClientHello containing all versions of TLS which they are prepared to 1549 negotiate (for this specification, that means minimally 0x0304, but 1550 if previous versions of TLS are allowed to be negotiated, they MUST 1551 be present as well). 1553 If this extension is not present, servers which are compliant with 1554 this specification and which also support TLS 1.2 MUST negotiate TLS 1555 1.2 or prior as specified in [RFC5246], even if 1556 ClientHello.legacy_version is 0x0304 or later. Servers MAY abort the 1557 handshake upon receiving a ClientHello with legacy_version 0x0304 or 1558 later. 1560 If this extension is present in the ClientHello, servers MUST NOT use 1561 the ClientHello.legacy_version value for version negotiation and MUST 1562 use only the "supported_versions" extension to determine client 1563 preferences. Servers MUST only select a version of TLS present in 1564 that extension and MUST ignore any unknown versions that are present 1565 in that extension. Note that this mechanism makes it possible to 1566 negotiate a version prior to TLS 1.2 if one side supports a sparse 1567 range. Implementations of TLS 1.3 which choose to support prior 1568 versions of TLS SHOULD support TLS 1.2. Servers MUST be prepared to 1569 receive ClientHellos that include this extension but do not include 1570 0x0304 in the list of versions. 1572 A server which negotiates a version of TLS prior to TLS 1.3 MUST set 1573 ServerHello.version and MUST NOT send the "supported_versions" 1574 extension. A server which negotiates TLS 1.3 MUST respond by sending 1575 a "supported_versions" extension containing the selected version 1576 value (0x0304). It MUST set the ServerHello.legacy_version field to 1577 0x0303 (TLS 1.2). 1579 After checking ServerHello.random to determine if the server 1580 handshake message is a ServerHello or HelloRetryRequest, clients MUST 1581 check for this extension prior to processing the rest of the 1582 ServerHello. This will require clients to parse the ServerHello in 1583 order to read the extension. If this extension is present, clients 1584 MUST ignore the ServerHello.legacy_version value and MUST use only 1585 the "supported_versions" extension to determine the selected version. 1586 If the "supported_versions" extension in the ServerHello contains a 1587 version not offered by the client or contains a version prior to TLS 1588 1.3, the client MUST abort the handshake with an "illegal_parameter" 1589 alert. 1591 4.2.2. Cookie 1593 struct { 1594 opaque cookie<1..2^16-1>; 1595 } Cookie; 1597 Cookies serve two primary purposes: 1599 * Allowing the server to force the client to demonstrate 1600 reachability at their apparent network address (thus providing a 1601 measure of DoS protection). This is primarily useful for non- 1602 connection-oriented transports (see [RFC6347] for an example of 1603 this). 1605 * Allowing the server to offload state to the client, thus allowing 1606 it to send a HelloRetryRequest without storing any state. The 1607 server can do this by storing the hash of the ClientHello in the 1608 HelloRetryRequest cookie (protected with some suitable integrity 1609 protection algorithm). 1611 When sending a HelloRetryRequest, the server MAY provide a "cookie" 1612 extension to the client (this is an exception to the usual rule that 1613 the only extensions that may be sent are those that appear in the 1614 ClientHello). When sending the new ClientHello, the client MUST copy 1615 the contents of the extension received in the HelloRetryRequest into 1616 a "cookie" extension in the new ClientHello. Clients MUST NOT use 1617 cookies in their initial ClientHello in subsequent connections. 1619 When a server is operating statelessly, it may receive an unprotected 1620 record of type change_cipher_spec between the first and second 1621 ClientHello (see Section 5). Since the server is not storing any 1622 state, this will appear as if it were the first message to be 1623 received. Servers operating statelessly MUST ignore these records. 1625 4.2.3. Signature Algorithms 1627 TLS 1.3 provides two extensions for indicating which signature 1628 algorithms may be used in digital signatures. The 1629 "signature_algorithms_cert" extension applies to signatures in 1630 certificates, and the "signature_algorithms" extension, which 1631 originally appeared in TLS 1.2, applies to signatures in 1632 CertificateVerify messages. The keys found in certificates MUST also 1633 be of appropriate type for the signature algorithms they are used 1634 with. This is a particular issue for RSA keys and PSS signatures, as 1635 described below. If no "signature_algorithms_cert" extension is 1636 present, then the "signature_algorithms" extension also applies to 1637 signatures appearing in certificates. Clients which desire the 1638 server to authenticate itself via a certificate MUST send the 1639 "signature_algorithms" extension. If a server is authenticating via 1640 a certificate and the client has not sent a "signature_algorithms" 1641 extension, then the server MUST abort the handshake with a 1642 "missing_extension" alert (see Section 9.2). 1644 The "signature_algorithms_cert" extension was added to allow 1645 implementations which supported different sets of algorithms for 1646 certificates and in TLS itself to clearly signal their capabilities. 1647 TLS 1.2 implementations SHOULD also process this extension. 1648 Implementations which have the same policy in both cases MAY omit the 1649 "signature_algorithms_cert" extension. 1651 The "extension_data" field of these extensions contains a 1652 SignatureSchemeList value: 1654 enum { 1655 /* RSASSA-PKCS1-v1_5 algorithms */ 1656 rsa_pkcs1_sha256(0x0401), 1657 rsa_pkcs1_sha384(0x0501), 1658 rsa_pkcs1_sha512(0x0601), 1660 /* ECDSA algorithms */ 1661 ecdsa_secp256r1_sha256(0x0403), 1662 ecdsa_secp384r1_sha384(0x0503), 1663 ecdsa_secp521r1_sha512(0x0603), 1665 /* RSASSA-PSS algorithms with public key OID rsaEncryption */ 1666 rsa_pss_rsae_sha256(0x0804), 1667 rsa_pss_rsae_sha384(0x0805), 1668 rsa_pss_rsae_sha512(0x0806), 1670 /* EdDSA algorithms */ 1671 ed25519(0x0807), 1672 ed448(0x0808), 1674 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */ 1675 rsa_pss_pss_sha256(0x0809), 1676 rsa_pss_pss_sha384(0x080a), 1677 rsa_pss_pss_sha512(0x080b), 1679 /* Legacy algorithms */ 1680 rsa_pkcs1_sha1(0x0201), 1681 ecdsa_sha1(0x0203), 1683 /* Reserved Code Points */ 1684 private_use(0xFE00..0xFFFF), 1685 (0xFFFF) 1686 } SignatureScheme; 1688 struct { 1689 SignatureScheme supported_signature_algorithms<2..2^16-2>; 1690 } SignatureSchemeList; 1692 Note: This enum is named "SignatureScheme" because there is already a 1693 "SignatureAlgorithm" type in TLS 1.2, which this replaces. We use 1694 the term "signature algorithm" throughout the text. 1696 Each SignatureScheme value lists a single signature algorithm that 1697 the client is willing to verify. The values are indicated in 1698 descending order of preference. Note that a signature algorithm 1699 takes as input an arbitrary-length message, rather than a digest. 1700 Algorithms which traditionally act on a digest should be defined in 1701 TLS to first hash the input with a specified hash algorithm and then 1702 proceed as usual. The code point groups listed above have the 1703 following meanings: 1705 RSASSA-PKCS1-v1_5 algorithms: Indicates a signature algorithm using 1706 RSASSA-PKCS1-v1_5 [RFC8017] with the corresponding hash algorithm 1707 as defined in [SHS]. These values refer solely to signatures 1708 which appear in certificates (see Section 4.4.2.2) and are not 1709 defined for use in signed TLS handshake messages, although they 1710 MAY appear in "signature_algorithms" and 1711 "signature_algorithms_cert" for backward compatibility with TLS 1712 1.2. 1714 ECDSA algorithms: Indicates a signature algorithm using ECDSA 1715 [ECDSA], the corresponding curve as defined in ANSI X9.62 [ECDSA] 1716 and FIPS 186-4 [DSS], and the corresponding hash algorithm as 1717 defined in [SHS]. The signature is represented as a DER-encoded 1718 [X690] ECDSA-Sig-Value structure as defined in [RFC4492]. 1720 RSASSA-PSS RSAE algorithms: Indicates a signature algorithm using 1721 RSASSA-PSS [RFC8017] with mask generation function 1. The digest 1722 used in the mask generation function and the digest being signed 1723 are both the corresponding hash algorithm as defined in [SHS]. 1724 The length of the Salt MUST be equal to the length of the output 1725 of the digest algorithm. If the public key is carried in an X.509 1726 certificate, it MUST use the rsaEncryption OID [RFC5280]. 1728 EdDSA algorithms: Indicates a signature algorithm using EdDSA as 1729 defined in [RFC8032] or its successors. Note that these 1730 correspond to the "PureEdDSA" algorithms and not the "prehash" 1731 variants. 1733 RSASSA-PSS PSS algorithms: Indicates a signature algorithm using 1734 RSASSA-PSS [RFC8017] with mask generation function 1. The digest 1735 used in the mask generation function and the digest being signed 1736 are both the corresponding hash algorithm as defined in [SHS]. 1737 The length of the Salt MUST be equal to the length of the digest 1738 algorithm. If the public key is carried in an X.509 certificate, 1739 it MUST use the RSASSA-PSS OID [RFC5756]. When used in 1740 certificate signatures, the algorithm parameters MUST be DER 1741 encoded. If the corresponding public key's parameters are 1742 present, then the parameters in the signature MUST be identical to 1743 those in the public key. 1745 Legacy algorithms: Indicates algorithms which are being deprecated 1746 because they use algorithms with known weaknesses, specifically 1747 SHA-1 which is used in this context with either (1) RSA using 1748 RSASSA-PKCS1-v1_5 or (2) ECDSA. These values refer solely to 1749 signatures which appear in certificates (see Section 4.4.2.2) and 1750 are not defined for use in signed TLS handshake messages, although 1751 they MAY appear in "signature_algorithms" and 1752 "signature_algorithms_cert" for backward compatibility with TLS 1753 1.2. Endpoints SHOULD NOT negotiate these algorithms but are 1754 permitted to do so solely for backward compatibility. Clients 1755 offering these values MUST list them as the lowest priority 1756 (listed after all other algorithms in SignatureSchemeList). TLS 1757 1.3 servers MUST NOT offer a SHA-1 signed certificate unless no 1758 valid certificate chain can be produced without it (see 1759 Section 4.4.2.2). 1761 The signatures on certificates that are self-signed or certificates 1762 that are trust anchors are not validated, since they begin a 1763 certification path (see [RFC5280], Section 3.2). A certificate that 1764 begins a certification path MAY use a signature algorithm that is not 1765 advertised as being supported in the "signature_algorithms" 1766 extension. 1768 Note that TLS 1.2 defines this extension differently. TLS 1.3 1769 implementations willing to negotiate TLS 1.2 MUST behave in 1770 accordance with the requirements of [RFC5246] when negotiating that 1771 version. In particular: 1773 * TLS 1.2 ClientHellos MAY omit this extension. 1775 * In TLS 1.2, the extension contained hash/signature pairs. The 1776 pairs are encoded in two octets, so SignatureScheme values have 1777 been allocated to align with TLS 1.2's encoding. Some legacy 1778 pairs are left unallocated. These algorithms are deprecated as of 1779 TLS 1.3. They MUST NOT be offered or negotiated by any 1780 implementation. In particular, MD5 [SLOTH], SHA-224, and DSA MUST 1781 NOT be used. 1783 * ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature 1784 pairs. However, the old semantics did not constrain the signing 1785 curve. If TLS 1.2 is negotiated, implementations MUST be prepared 1786 to accept a signature that uses any curve that they advertised in 1787 the "supported_groups" extension. 1789 * Implementations that advertise support for RSASSA-PSS (which is 1790 mandatory in TLS 1.3) MUST be prepared to accept a signature using 1791 that scheme even when TLS 1.2 is negotiated. In TLS 1.2, RSASSA- 1792 PSS is used with RSA cipher suites. 1794 4.2.4. Certificate Authorities 1796 The "certificate_authorities" extension is used to indicate the 1797 certificate authorities (CAs) which an endpoint supports and which 1798 SHOULD be used by the receiving endpoint to guide certificate 1799 selection. 1801 The body of the "certificate_authorities" extension consists of a 1802 CertificateAuthoritiesExtension structure. 1804 opaque DistinguishedName<1..2^16-1>; 1806 struct { 1807 DistinguishedName authorities<3..2^16-1>; 1808 } CertificateAuthoritiesExtension; 1810 authorities: A list of the distinguished names [X501] of acceptable 1811 certificate authorities, represented in DER-encoded [X690] format. 1812 These distinguished names specify a desired distinguished name for 1813 a trust anchor or subordinate CA; thus, this message can be used 1814 to describe known trust anchors as well as a desired authorization 1815 space. 1817 The client MAY send the "certificate_authorities" extension in the 1818 ClientHello message. The server MAY send it in the 1819 CertificateRequest message. 1821 The "trusted_ca_keys" extension [RFC6066], which serves a similar 1822 purpose, but is more complicated, is not used in TLS 1.3 (although it 1823 may appear in ClientHello messages from clients which are offering 1824 prior versions of TLS). 1826 4.2.5. OID Filters 1828 The "oid_filters" extension allows servers to provide a list of OID/ 1829 value pairs which it would like the client's certificate to match. 1830 This extension, if provided by the server, MUST only be sent in the 1831 CertificateRequest message. 1833 struct { 1834 opaque certificate_extension_oid<1..2^8-1>; 1835 opaque certificate_extension_values<0..2^16-1>; 1836 } OIDFilter; 1838 struct { 1839 OIDFilter filters<0..2^16-1>; 1840 } OIDFilterExtension; 1842 filters: A list of certificate extension OIDs [RFC5280] with their 1843 allowed value(s) and represented in DER-encoded [X690] format. 1844 Some certificate extension OIDs allow multiple values (e.g., 1845 Extended Key Usage). If the server has included a non-empty 1846 filters list, the client certificate included in the response MUST 1847 contain all of the specified extension OIDs that the client 1848 recognizes. For each extension OID recognized by the client, all 1849 of the specified values MUST be present in the client certificate 1850 (but the certificate MAY have other values as well). However, the 1851 client MUST ignore and skip any unrecognized certificate extension 1852 OIDs. If the client ignored some of the required certificate 1853 extension OIDs and supplied a certificate that does not satisfy 1854 the request, the server MAY at its discretion either continue the 1855 connection without client authentication or abort the handshake 1856 with an "unsupported_certificate" alert. Any given OID MUST NOT 1857 appear more than once in the filters list. 1859 PKIX RFCs define a variety of certificate extension OIDs and their 1860 corresponding value types. Depending on the type, matching 1861 certificate extension values are not necessarily bitwise-equal. It 1862 is expected that TLS implementations will rely on their PKI libraries 1863 to perform certificate selection using certificate extension OIDs. 1865 This document defines matching rules for two standard certificate 1866 extensions defined in [RFC5280]: 1868 * The Key Usage extension in a certificate matches the request when 1869 all key usage bits asserted in the request are also asserted in 1870 the Key Usage certificate extension. 1872 * The Extended Key Usage extension in a certificate matches the 1873 request when all key purpose OIDs present in the request are also 1874 found in the Extended Key Usage certificate extension. The 1875 special anyExtendedKeyUsage OID MUST NOT be used in the request. 1877 Separate specifications may define matching rules for other 1878 certificate extensions. 1880 4.2.6. Post-Handshake Client Authentication 1882 The "post_handshake_auth" extension is used to indicate that a client 1883 is willing to perform post-handshake authentication (Section 4.6.2). 1884 Servers MUST NOT send a post-handshake CertificateRequest to clients 1885 which do not offer this extension. Servers MUST NOT send this 1886 extension. 1888 struct {} PostHandshakeAuth; 1890 The "extension_data" field of the "post_handshake_auth" extension is 1891 zero length. 1893 4.2.7. Supported Groups 1895 When sent by the client, the "supported_groups" extension indicates 1896 the named groups which the client supports for key exchange, ordered 1897 from most preferred to least preferred. 1899 Note: In versions of TLS prior to TLS 1.3, this extension was named 1900 "elliptic_curves" and only contained elliptic curve groups. See 1901 [RFC8422] and [RFC7919]. This extension was also used to negotiate 1902 ECDSA curves. Signature algorithms are now negotiated independently 1903 (see Section 4.2.3). 1905 The "extension_data" field of this extension contains a 1906 "NamedGroupList" value: 1908 enum { 1910 /* Elliptic Curve Groups (ECDHE) */ 1911 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 1912 x25519(0x001D), x448(0x001E), 1914 /* Finite Field Groups (DHE) */ 1915 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102), 1916 ffdhe6144(0x0103), ffdhe8192(0x0104), 1918 /* Reserved Code Points */ 1919 ffdhe_private_use(0x01FC..0x01FF), 1920 ecdhe_private_use(0xFE00..0xFEFF), 1921 (0xFFFF) 1922 } NamedGroup; 1924 struct { 1925 NamedGroup named_group_list<2..2^16-1>; 1926 } NamedGroupList; 1928 Elliptic Curve Groups (ECDHE): Indicates support for the 1929 corresponding named curve, defined in either FIPS 186-4 [DSS] or 1930 in [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for 1931 Private Use [RFC8126]. 1933 Finite Field Groups (DHE): Indicates support for the corresponding 1934 finite field group, defined in [RFC7919]. Values 0x01FC through 1935 0x01FF are reserved for Private Use. 1937 Items in "named_group_list" are ordered according to the sender's 1938 preferences (most preferred choice first). 1940 As of TLS 1.3, servers are permitted to send the "supported_groups" 1941 extension to the client. Clients MUST NOT act upon any information 1942 found in "supported_groups" prior to successful completion of the 1943 handshake but MAY use the information learned from a successfully 1944 completed handshake to change what groups they use in their 1945 "key_share" extension in subsequent connections. If the server has a 1946 group it prefers to the ones in the "key_share" extension but is 1947 still willing to accept the ClientHello, it SHOULD send 1948 "supported_groups" to update the client's view of its preferences; 1949 this extension SHOULD contain all groups the server supports, 1950 regardless of whether they are currently supported by the client. 1952 4.2.8. Key Share 1954 The "key_share" extension contains the endpoint's cryptographic 1955 parameters. 1957 Clients MAY send an empty client_shares list in order to request 1958 group selection from the server, at the cost of an additional round 1959 trip (see Section 4.1.4). 1961 struct { 1962 NamedGroup group; 1963 opaque key_exchange<1..2^16-1>; 1964 } KeyShareEntry; 1966 group: The named group for the key being exchanged. 1968 key_exchange: Key exchange information. The contents of this field 1969 are determined by the specified group and its corresponding 1970 definition. Finite Field Diffie-Hellman [DH76] parameters are 1971 described in Section 4.2.8.1; Elliptic Curve Diffie-Hellman 1972 parameters are described in Section 4.2.8.2. 1974 In the ClientHello message, the "extension_data" field of this 1975 extension contains a "KeyShareClientHello" value: 1977 struct { 1978 KeyShareEntry client_shares<0..2^16-1>; 1979 } KeyShareClientHello; 1981 client_shares: A list of offered KeyShareEntry values in descending 1982 order of client preference. 1984 This list MAY be empty if the client is requesting a 1985 HelloRetryRequest. Each KeyShareEntry value MUST correspond to a 1986 group offered in the "supported_groups" extension and MUST appear in 1987 the same order. However, the values MAY be a non-contiguous subset 1988 of the "supported_groups" extension and MAY omit the most preferred 1989 groups. Such a situation could arise if the most preferred groups 1990 are new and unlikely to be supported in enough places to make 1991 pregenerating key shares for them efficient. 1993 Clients can offer as many KeyShareEntry values as the number of 1994 supported groups it is offering, each representing a single set of 1995 key exchange parameters. For instance, a client might offer shares 1996 for several elliptic curves or multiple FFDHE groups. The 1997 key_exchange values for each KeyShareEntry MUST be generated 1998 independently. Clients MUST NOT offer multiple KeyShareEntry values 1999 for the same group. Clients MUST NOT offer any KeyShareEntry values 2000 for groups not listed in the client's "supported_groups" extension. 2001 Servers MAY check for violations of these rules and abort the 2002 handshake with an "illegal_parameter" alert if one is violated. 2004 In a HelloRetryRequest message, the "extension_data" field of this 2005 extension contains a KeyShareHelloRetryRequest value: 2007 struct { 2008 NamedGroup selected_group; 2009 } KeyShareHelloRetryRequest; 2011 selected_group: The mutually supported group the server intends to 2012 negotiate and is requesting a retried ClientHello/KeyShare for. 2014 Upon receipt of this extension in a HelloRetryRequest, the client 2015 MUST verify that (1) the selected_group field corresponds to a group 2016 which was provided in the "supported_groups" extension in the 2017 original ClientHello and (2) the selected_group field does not 2018 correspond to a group which was provided in the "key_share" extension 2019 in the original ClientHello. If either of these checks fails, then 2020 the client MUST abort the handshake with an "illegal_parameter" 2021 alert. Otherwise, when sending the new ClientHello, the client MUST 2022 replace the original "key_share" extension with one containing only a 2023 new KeyShareEntry for the group indicated in the selected_group field 2024 of the triggering HelloRetryRequest. 2026 In a ServerHello message, the "extension_data" field of this 2027 extension contains a KeyShareServerHello value: 2029 struct { 2030 KeyShareEntry server_share; 2031 } KeyShareServerHello; 2033 server_share: A single KeyShareEntry value that is in the same group 2034 as one of the client's shares. 2036 If using (EC)DHE key establishment, servers offer exactly one 2037 KeyShareEntry in the ServerHello. This value MUST be in the same 2038 group as the KeyShareEntry value offered by the client that the 2039 server has selected for the negotiated key exchange. Servers MUST 2040 NOT send a KeyShareEntry for any group not indicated in the client's 2041 "supported_groups" extension and MUST NOT send a KeyShareEntry when 2042 using the "psk_ke" PskKeyExchangeMode. If using (EC)DHE key 2043 establishment and a HelloRetryRequest containing a "key_share" 2044 extension was received by the client, the client MUST verify that the 2045 selected NamedGroup in the ServerHello is the same as that in the 2046 HelloRetryRequest. If this check fails, the client MUST abort the 2047 handshake with an "illegal_parameter" alert. 2049 4.2.8.1. Diffie-Hellman Parameters 2051 Diffie-Hellman [DH76] parameters for both clients and servers are 2052 encoded in the opaque key_exchange field of a KeyShareEntry in a 2053 KeyShare structure. The opaque value contains the Diffie-Hellman 2054 public value (Y = g^X mod p) for the specified group (see [RFC7919] 2055 for group definitions) encoded as a big-endian integer and padded to 2056 the left with zeros to the size of p in bytes. 2058 Note: For a given Diffie-Hellman group, the padding results in all 2059 public keys having the same length. 2061 Peers MUST validate each other's public key Y by ensuring that 1 < Y 2062 < p-1. This check ensures that the remote peer is properly behaved 2063 and isn't forcing the local system into a small subgroup. 2065 4.2.8.2. ECDHE Parameters 2067 ECDHE parameters for both clients and servers are encoded in the 2068 opaque key_exchange field of a KeyShareEntry in a KeyShare structure. 2070 For secp256r1, secp384r1, and secp521r1, the contents are the 2071 serialized value of the following struct: 2073 struct { 2074 uint8 legacy_form = 4; 2075 opaque X[coordinate_length]; 2076 opaque Y[coordinate_length]; 2077 } UncompressedPointRepresentation; 2079 X and Y, respectively, are the binary representations of the x and y 2080 values in network byte order. There are no internal length markers, 2081 so each number representation occupies as many octets as implied by 2082 the curve parameters. For P-256, this means that each of X and Y use 2083 32 octets, padded on the left by zeros if necessary. For P-384, they 2084 take 48 octets each. For P-521, they take 66 octets each. 2086 For the curves secp256r1, secp384r1, and secp521r1, peers MUST 2087 validate each other's public value Q by ensuring that the point is a 2088 valid point on the elliptic curve. The appropriate validation 2089 procedures are defined in Section 4.3.7 of [ECDSA] and alternatively 2090 in Section 5.6.2.3 of [KEYAGREEMENT]. This process consists of three 2091 steps: (1) verify that Q is not the point at infinity (O), (2) verify 2092 that for Q = (x, y) both integers x and y are in the correct 2093 interval, and (3) ensure that (x, y) is a correct solution to the 2094 elliptic curve equation. For these curves, implementors do not need 2095 to verify membership in the correct subgroup. 2097 For X25519 and X448, the contents of the public value is the K_A or 2098 K_B value described in Section 6 of [RFC7748]. This is 32 bytes for 2099 X25519 and 56 bytes for X448. 2101 Note: Versions of TLS prior to 1.3 permitted point format 2102 negotiation; TLS 1.3 removes this feature in favor of a single point 2103 format for each curve. 2105 4.2.9. Pre-Shared Key Exchange Modes 2107 In order to use PSKs, clients MUST also send a 2108 "psk_key_exchange_modes" extension. The semantics of this extension 2109 are that the client only supports the use of PSKs with these modes, 2110 which restricts both the use of PSKs offered in this ClientHello and 2111 those which the server might supply via NewSessionTicket. 2113 A client MUST provide a "psk_key_exchange_modes" extension if it 2114 offers a "pre_shared_key" extension. If clients offer 2115 "pre_shared_key" without a "psk_key_exchange_modes" extension, 2116 servers MUST abort the handshake. Servers MUST NOT select a key 2117 exchange mode that is not listed by the client. This extension also 2118 restricts the modes for use with PSK resumption. Servers SHOULD NOT 2119 send NewSessionTicket with tickets that are not compatible with the 2120 advertised modes; however, if a server does so, the impact will just 2121 be that the client's attempts at resumption fail. 2123 The server MUST NOT send a "psk_key_exchange_modes" extension. 2125 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 2127 struct { 2128 PskKeyExchangeMode ke_modes<1..255>; 2129 } PskKeyExchangeModes; 2131 psk_ke: PSK-only key establishment. In this mode, the server MUST 2132 NOT supply a "key_share" value. 2134 psk_dhe_ke: PSK with (EC)DHE key establishment. In this mode, the 2135 client and server MUST supply "key_share" values as described in 2136 Section 4.2.8. 2138 Any future values that are allocated must ensure that the transmitted 2139 protocol messages unambiguously identify which mode was selected by 2140 the server; at present, this is indicated by the presence of the 2141 "key_share" in the ServerHello. 2143 4.2.10. Early Data Indication 2145 When a PSK is used and early data is allowed for that PSK (see for 2146 instance Appendix B.3.4), the client can send Application Data in its 2147 first flight of messages. If the client opts to do so, it MUST 2148 supply both the "pre_shared_key" and "early_data" extensions. 2150 The "extension_data" field of this extension contains an 2151 "EarlyDataIndication" value. 2153 struct {} Empty; 2155 struct { 2156 select (Handshake.msg_type) { 2157 case new_session_ticket: uint32 max_early_data_size; 2158 case client_hello: Empty; 2159 case encrypted_extensions: Empty; 2160 }; 2161 } EarlyDataIndication; 2163 See Section 4.6.1 for details regarding the use of the 2164 max_early_data_size field. 2166 The parameters for the 0-RTT data (version, symmetric cipher suite, 2167 Application-Layer Protocol Negotiation (ALPN) [RFC7301] protocol, 2168 etc.) are those associated with the PSK in use. For externally 2169 provisioned PSKs, the associated values are those provisioned along 2170 with the key. For PSKs established via a NewSessionTicket message, 2171 the associated values are those which were negotiated in the 2172 connection which established the PSK. The PSK used to encrypt the 2173 early data MUST be the first PSK listed in the client's 2174 "pre_shared_key" extension. 2176 For PSKs provisioned via NewSessionTicket, a server MUST validate 2177 that the ticket age for the selected PSK identity (computed by 2178 subtracting ticket_age_add from PskIdentity.obfuscated_ticket_age 2179 modulo 2^32) is within a small tolerance of the time since the ticket 2180 was issued (see Section 8). If it is not, the server SHOULD proceed 2181 with the handshake but reject 0-RTT, and SHOULD NOT take any other 2182 action that assumes that this ClientHello is fresh. 2184 0-RTT messages sent in the first flight have the same (encrypted) 2185 content types as messages of the same type sent in other flights 2186 (handshake and application_data) but are protected under different 2187 keys. After receiving the server's Finished message, if the server 2188 has accepted early data, an EndOfEarlyData message will be sent to 2189 indicate the key change. This message will be encrypted with the 2190 0-RTT traffic keys. 2192 A server which receives an "early_data" extension MUST behave in one 2193 of three ways: 2195 * Ignore the extension and return a regular 1-RTT response. The 2196 server then skips past early data by attempting to deprotect 2197 received records using the handshake traffic key, discarding 2198 records which fail deprotection (up to the configured 2199 max_early_data_size). Once a record is deprotected successfully, 2200 it is treated as the start of the client's second flight and the 2201 server proceeds as with an ordinary 1-RTT handshake. 2203 * Request that the client send another ClientHello by responding 2204 with a HelloRetryRequest. A client MUST NOT include the 2205 "early_data" extension in its followup ClientHello. The server 2206 then ignores early data by skipping all records with an external 2207 content type of "application_data" (indicating that they are 2208 encrypted), up to the configured max_early_data_size. 2210 * Return its own "early_data" extension in EncryptedExtensions, 2211 indicating that it intends to process the early data. It is not 2212 possible for the server to accept only a subset of the early data 2213 messages. Even though the server sends a message accepting early 2214 data, the actual early data itself may already be in flight by the 2215 time the server generates this message. 2217 In order to accept early data, the server MUST have selected the 2218 first key offered in the client's "pre_shared_key" extension. In 2219 addition, it MUST verify that the following values are the same as 2220 those associated with the selected PSK: 2222 * The selected TLS version number 2224 * The selected cipher suite 2226 * The selected ALPN [RFC7301] protocol, if any 2228 These requirements are a superset of those needed to perform a 1-RTT 2229 handshake using the PSK in question. 2231 Future extensions MUST define their interaction with 0-RTT. 2233 If any of these checks fail, the server MUST NOT respond with the 2234 extension and must discard all the first-flight data using one of the 2235 first two mechanisms listed above (thus falling back to 1-RTT or 2236 2-RTT). If the client attempts a 0-RTT handshake but the server 2237 rejects it, the server will generally not have the 0-RTT record 2238 protection keys and must instead use trial decryption (either with 2239 the 1-RTT handshake keys or by looking for a cleartext ClientHello in 2240 the case of a HelloRetryRequest) to find the first non-0-RTT message. 2242 If the server chooses to accept the "early_data" extension, then it 2243 MUST comply with the same error-handling requirements specified for 2244 all records when processing early data records. Specifically, if the 2245 server fails to decrypt a 0-RTT record following an accepted 2246 "early_data" extension, it MUST terminate the connection with a 2247 "bad_record_mac" alert as per Section 5.2. 2249 If the server rejects the "early_data" extension, the client 2250 application MAY opt to retransmit the Application Data previously 2251 sent in early data once the handshake has been completed. Note that 2252 automatic retransmission of early data could result in incorrect 2253 assumptions regarding the status of the connection. For instance, 2254 when the negotiated connection selects a different ALPN protocol from 2255 what was used for the early data, an application might need to 2256 construct different messages. Similarly, if early data assumes 2257 anything about the connection state, it might be sent in error after 2258 the handshake completes. 2260 A TLS implementation SHOULD NOT automatically resend early data; 2261 applications are in a better position to decide when retransmission 2262 is appropriate. A TLS implementation MUST NOT automatically resend 2263 early data unless the negotiated connection selects the same ALPN 2264 protocol. 2266 4.2.11. Pre-Shared Key Extension 2268 The "pre_shared_key" extension is used to negotiate the identity of 2269 the pre-shared key to be used with a given handshake in association 2270 with PSK key establishment. 2272 The "extension_data" field of this extension contains a 2273 "PreSharedKeyExtension" value: 2275 struct { 2276 opaque identity<1..2^16-1>; 2277 uint32 obfuscated_ticket_age; 2278 } PskIdentity; 2280 opaque PskBinderEntry<32..255>; 2282 struct { 2283 PskIdentity identities<7..2^16-1>; 2284 PskBinderEntry binders<33..2^16-1>; 2285 } OfferedPsks; 2287 struct { 2288 select (Handshake.msg_type) { 2289 case client_hello: OfferedPsks; 2290 case server_hello: uint16 selected_identity; 2291 }; 2292 } PreSharedKeyExtension; 2294 identity: A label for a key. For instance, a ticket (as defined in 2295 Appendix B.3.4) or a label for a pre-shared key established 2296 externally. 2298 obfuscated_ticket_age: An obfuscated version of the age of the key. 2299 Section 4.2.11.1 describes how to form this value for identities 2300 established via the NewSessionTicket message. For identities 2301 established externally, an obfuscated_ticket_age of 0 SHOULD be 2302 used, and servers MUST ignore the value. 2304 identities: A list of the identities that the client is willing to 2305 negotiate with the server. If sent alongside the "early_data" 2306 extension (see Section 4.2.10), the first identity is the one used 2307 for 0-RTT data. 2309 binders: A series of HMAC values, one for each value in the 2310 identities list and in the same order, computed as described 2311 below. 2313 selected_identity: The server's chosen identity expressed as a 2314 (0-based) index into the identities in the client's 2315 "OfferedPsks.identities" list. 2317 Each PSK is associated with a single Hash algorithm. For PSKs 2318 established via the ticket mechanism (Section 4.6.1), this is the KDF 2319 Hash algorithm on the connection where the ticket was established. 2320 For externally established PSKs, the Hash algorithm MUST be set when 2321 the PSK is established or default to SHA-256 if no such algorithm is 2322 defined. The server MUST ensure that it selects a compatible PSK (if 2323 any) and cipher suite. 2325 In TLS versions prior to TLS 1.3, the Server Name Indication (SNI) 2326 value was intended to be associated with the session (Section 3 of 2327 [RFC6066]), with the server being required to enforce that the SNI 2328 value associated with the session matches the one specified in the 2329 resumption handshake. However, in reality the implementations were 2330 not consistent on which of two supplied SNI values they would use, 2331 leading to the consistency requirement being de facto enforced by the 2332 clients. In TLS 1.3, the SNI value is always explicitly specified in 2333 the resumption handshake, and there is no need for the server to 2334 associate an SNI value with the ticket. Clients, however, SHOULD 2335 store the SNI with the PSK to fulfill the requirements of 2336 Section 4.6.1. 2338 Implementor's note: When session resumption is the primary use case 2339 of PSKs, the most straightforward way to implement the PSK/cipher 2340 suite matching requirements is to negotiate the cipher suite first 2341 and then exclude any incompatible PSKs. Any unknown PSKs (e.g., ones 2342 not in the PSK database or encrypted with an unknown key) SHOULD 2343 simply be ignored. If no acceptable PSKs are found, the server 2344 SHOULD perform a non-PSK handshake if possible. If backward 2345 compatibility is important, client-provided, externally established 2346 PSKs SHOULD influence cipher suite selection. 2348 Prior to accepting PSK key establishment, the server MUST validate 2349 the corresponding binder value (see Section 4.2.11.2 below). If this 2350 value is not present or does not validate, the server MUST abort the 2351 handshake. Servers SHOULD NOT attempt to validate multiple binders; 2352 rather, they SHOULD select a single PSK and validate solely the 2353 binder that corresponds to that PSK. See Section 8.2 and 2354 Appendix E.6 for the security rationale for this requirement. In 2355 order to accept PSK key establishment, the server sends a 2356 "pre_shared_key" extension indicating the selected identity. 2358 Clients MUST verify that the server's selected_identity is within the 2359 range supplied by the client, that the server selected a cipher suite 2360 indicating a Hash associated with the PSK, and that a server 2361 "key_share" extension is present if required by the ClientHello 2362 "psk_key_exchange_modes" extension. If these values are not 2363 consistent, the client MUST abort the handshake with an 2364 "illegal_parameter" alert. 2366 If the server supplies an "early_data" extension, the client MUST 2367 verify that the server's selected_identity is 0. If any other value 2368 is returned, the client MUST abort the handshake with an 2369 "illegal_parameter" alert. 2371 The "pre_shared_key" extension MUST be the last extension in the 2372 ClientHello (this facilitates implementation as described below). 2373 Servers MUST check that it is the last extension and otherwise fail 2374 the handshake with an "illegal_parameter" alert. 2376 4.2.11.1. Ticket Age 2378 The client's view of the age of a ticket is the time since the 2379 receipt of the NewSessionTicket message. Clients MUST NOT attempt to 2380 use tickets which have ages greater than the "ticket_lifetime" value 2381 which was provided with the ticket. The "obfuscated_ticket_age" 2382 field of each PskIdentity contains an obfuscated version of the 2383 ticket age formed by taking the age in milliseconds and adding the 2384 "ticket_age_add" value that was included with the ticket (see 2385 Section 4.6.1), modulo 2^32. This addition prevents passive 2386 observers from correlating connections unless tickets are reused. 2387 Note that the "ticket_lifetime" field in the NewSessionTicket message 2388 is in seconds but the "obfuscated_ticket_age" is in milliseconds. 2389 Because ticket lifetimes are restricted to a week, 32 bits is enough 2390 to represent any plausible age, even in milliseconds. 2392 4.2.11.2. PSK Binder 2394 The PSK binder value forms a binding between a PSK and the current 2395 handshake, as well as a binding between the handshake in which the 2396 PSK was generated (if via a NewSessionTicket message) and the current 2397 handshake. Each entry in the binders list is computed as an HMAC 2398 over a transcript hash (see Section 4.4.1) containing a partial 2399 ClientHello up to and including the PreSharedKeyExtension.identities 2400 field. That is, it includes all of the ClientHello but not the 2401 binders list itself. The length fields for the message (including 2402 the overall length, the length of the extensions block, and the 2403 length of the "pre_shared_key" extension) are all set as if binders 2404 of the correct lengths were present. 2406 The PskBinderEntry is computed in the same way as the Finished 2407 message (Section 4.4.4) but with the BaseKey being the binder_key 2408 derived via the key schedule from the corresponding PSK which is 2409 being offered (see Section 7.1). 2411 If the handshake includes a HelloRetryRequest, the initial 2412 ClientHello and HelloRetryRequest are included in the transcript 2413 along with the new ClientHello. For instance, if the client sends 2414 ClientHello1, its binder will be computed over: 2416 Transcript-Hash(Truncate(ClientHello1)) 2418 Where Truncate() removes the binders list from the ClientHello. 2420 If the server responds with a HelloRetryRequest and the client then 2421 sends ClientHello2, its binder will be computed over: 2423 Transcript-Hash(ClientHello1, 2424 HelloRetryRequest, 2425 Truncate(ClientHello2)) 2427 The full ClientHello1/ClientHello2 is included in all other handshake 2428 hash computations. Note that in the first flight, 2429 Truncate(ClientHello1) is hashed directly, but in the second flight, 2430 ClientHello1 is hashed and then reinjected as a "message_hash" 2431 message, as described in Section 4.4.1. 2433 4.2.11.3. Processing Order 2435 Clients are permitted to "stream" 0-RTT data until they receive the 2436 server's Finished, only then sending the EndOfEarlyData message, 2437 followed by the rest of the handshake. In order to avoid deadlocks, 2438 when accepting "early_data", servers MUST process the client's 2439 ClientHello and then immediately send their flight of messages, 2440 rather than waiting for the client's EndOfEarlyData message before 2441 sending its ServerHello. 2443 4.3. Server Parameters 2445 The next two messages from the server, EncryptedExtensions and 2446 CertificateRequest, contain information from the server that 2447 determines the rest of the handshake. These messages are encrypted 2448 with keys derived from the server_handshake_traffic_secret. 2450 4.3.1. Encrypted Extensions 2452 In all handshakes, the server MUST send the EncryptedExtensions 2453 message immediately after the ServerHello message. This is the first 2454 message that is encrypted under keys derived from the 2455 server_handshake_traffic_secret. 2457 The EncryptedExtensions message contains extensions that can be 2458 protected, i.e., any which are not needed to establish the 2459 cryptographic context but which are not associated with individual 2460 certificates. The client MUST check EncryptedExtensions for the 2461 presence of any forbidden extensions and if any are found MUST abort 2462 the handshake with an "illegal_parameter" alert. 2464 Structure of this message: 2466 struct { 2467 Extension extensions<0..2^16-1>; 2468 } EncryptedExtensions; 2470 extensions: A list of extensions. For more information, see the 2471 table in Section 4.2. 2473 4.3.2. Certificate Request 2475 A server which is authenticating with a certificate MAY optionally 2476 request a certificate from the client. This message, if sent, MUST 2477 follow EncryptedExtensions. 2479 Structure of this message: 2481 struct { 2482 opaque certificate_request_context<0..2^8-1>; 2483 Extension extensions<0..2^16-1>; 2484 } CertificateRequest; 2486 certificate_request_context: An opaque string which identifies the 2487 certificate request and which will be echoed in the client's 2488 Certificate message. The certificate_request_context MUST be 2489 unique within the scope of this connection (thus preventing replay 2490 of client CertificateVerify messages). This field SHALL be zero 2491 length unless used for the post-handshake authentication exchanges 2492 described in Section 4.6.2. When requesting post-handshake 2493 authentication, the server SHOULD make the context unpredictable 2494 to the client (e.g., by randomly generating it) in order to 2495 prevent an attacker who has temporary access to the client's 2496 private key from pre-computing valid CertificateVerify messages. 2498 extensions: A list of extensions describing the parameters of the 2499 certificate being requested. The "signature_algorithms" extension 2500 MUST be specified, and other extensions may optionally be included 2501 if defined for this message. Clients MUST ignore unrecognized 2502 extensions. 2504 In prior versions of TLS, the CertificateRequest message carried a 2505 list of signature algorithms and certificate authorities which the 2506 server would accept. In TLS 1.3, the former is expressed by sending 2507 the "signature_algorithms" and optionally "signature_algorithms_cert" 2508 extensions. The latter is expressed by sending the 2509 "certificate_authorities" extension (see Section 4.2.4). 2511 Servers which are authenticating with a resumption PSK MUST NOT send 2512 the CertificateRequest message in the main handshake, though they MAY 2513 send it in post-handshake authentication (see Section 4.6.2) provided 2514 that the client has sent the "post_handshake_auth" extension (see 2515 Section 4.2.6). Servers which are authenticating with an external 2516 PSK MUST NOT send the CertificateRequest message either in the main 2517 handshake or request post-handshake authentication. Future 2518 specifications MAY provide an extension to permit this. 2520 4.4. Authentication Messages 2522 As discussed in Section 2, TLS generally uses a common set of 2523 messages for authentication, key confirmation, and handshake 2524 integrity: Certificate, CertificateVerify, and Finished. (The PSK 2525 binders also perform key confirmation, in a similar fashion.) These 2526 three messages are always sent as the last messages in their 2527 handshake flight. The Certificate and CertificateVerify messages are 2528 only sent under certain circumstances, as defined below. The 2529 Finished message is always sent as part of the Authentication Block. 2530 These messages are encrypted under keys derived from the 2531 [sender]_handshake_traffic_secret. 2533 The computations for the Authentication messages all uniformly take 2534 the following inputs: 2536 * The certificate and signing key to be used. 2538 * A Handshake Context consisting of the list of messages to be 2539 included in the transcript hash. 2541 * A Base Key to be used to compute a MAC key. 2543 Based on these inputs, the messages then contain: 2545 Certificate The certificate to be used for authentication, and any 2546 supporting certificates in the chain. Note that certificate-based 2547 client authentication is not available in PSK handshake flows 2548 (including 0-RTT). 2550 CertificateVerify: A signature over the value Transcript- 2551 Hash(Handshake Context, Certificate) 2553 Finished: A MAC over the value Transcript-Hash(Handshake Context, 2554 Certificate, CertificateVerify) using a MAC key derived from the 2555 Base Key. 2557 The following table defines the Handshake Context and MAC Base Key 2558 for each scenario: 2560 +=========+====================+====================================+ 2561 | Mode | Handshake Context | Base Key | 2562 +=========+====================+====================================+ 2563 | Server | ClientHello ... | server_handshake_traffic_secret | 2564 | | later of | | 2565 | |EncryptedExtensions/| | 2566 | | CertificateRequest | | 2567 +---------+--------------------+------------------------------------+ 2568 | Client | ClientHello ... | client_handshake_traffic_secret | 2569 | | later of server | | 2570 | | Finished/ | | 2571 | | EndOfEarlyData | | 2572 +---------+--------------------+------------------------------------+ 2573 | Post- | ClientHello ... |client_application_traffic_secret_N | 2574 |Handshake| client Finished + | | 2575 | | CertificateRequest | | 2576 +---------+--------------------+------------------------------------+ 2578 Table 2: Authentication Inputs 2580 4.4.1. The Transcript Hash 2582 Many of the cryptographic computations in TLS make use of a 2583 transcript hash. This value is computed by hashing the concatenation 2584 of each included handshake message, including the handshake message 2585 header carrying the handshake message type and length fields, but not 2586 including record layer headers. I.e., 2588 Transcript-Hash(M1, M2, ... Mn) = Hash(M1 || M2 || ... || Mn) 2590 As an exception to this general rule, when the server responds to a 2591 ClientHello with a HelloRetryRequest, the value of ClientHello1 is 2592 replaced with a special synthetic handshake message of handshake type 2593 "message_hash" containing Hash(ClientHello1). I.e., 2595 Transcript-Hash(ClientHello1, HelloRetryRequest, ... Mn) = 2596 Hash(message_hash || /* Handshake type */ 2597 00 00 Hash.length || /* Handshake message length (bytes) */ 2598 Hash(ClientHello1) || /* Hash of ClientHello1 */ 2599 HelloRetryRequest || ... || Mn) 2601 The reason for this construction is to allow the server to do a 2602 stateless HelloRetryRequest by storing just the hash of ClientHello1 2603 in the cookie, rather than requiring it to export the entire 2604 intermediate hash state (see Section 4.2.2). 2606 For concreteness, the transcript hash is always taken from the 2607 following sequence of handshake messages, starting at the first 2608 ClientHello and including only those messages that were sent: 2609 ClientHello, HelloRetryRequest, ClientHello, ServerHello, 2610 EncryptedExtensions, server CertificateRequest, server Certificate, 2611 server CertificateVerify, server Finished, EndOfEarlyData, client 2612 Certificate, client CertificateVerify, client Finished. 2614 In general, implementations can implement the transcript by keeping a 2615 running transcript hash value based on the negotiated hash. Note, 2616 however, that subsequent post-handshake authentications do not 2617 include each other, just the messages through the end of the main 2618 handshake. 2620 4.4.2. Certificate 2622 This message conveys the endpoint's certificate chain to the peer. 2624 The server MUST send a Certificate message whenever the agreed-upon 2625 key exchange method uses certificates for authentication (this 2626 includes all key exchange methods defined in this document except 2627 PSK). 2629 The client MUST send a Certificate message if and only if the server 2630 has requested client authentication via a CertificateRequest message 2631 (Section 4.3.2). If the server requests client authentication but no 2632 suitable certificate is available, the client MUST send a Certificate 2633 message containing no certificates (i.e., with the "certificate_list" 2634 field having length 0). A Finished message MUST be sent regardless 2635 of whether the Certificate message is empty. 2637 Structure of this message: 2639 enum { 2640 X509(0), 2641 RawPublicKey(2), 2642 (255) 2643 } CertificateType; 2645 struct { 2646 select (certificate_type) { 2647 case RawPublicKey: 2648 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */ 2649 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 2651 case X509: 2652 opaque cert_data<1..2^24-1>; 2653 }; 2654 Extension extensions<0..2^16-1>; 2655 } CertificateEntry; 2657 struct { 2658 opaque certificate_request_context<0..2^8-1>; 2659 CertificateEntry certificate_list<0..2^24-1>; 2660 } Certificate; 2662 certificate_request_context: If this message is in response to a 2663 CertificateRequest, the value of certificate_request_context in 2664 that message. Otherwise (in the case of server authentication), 2665 this field SHALL be zero length. 2667 certificate_list: A list (chain) of CertificateEntry structures, 2668 each containing a single certificate and list of extensions. 2670 extensions: A list of extension values for the CertificateEntry. 2671 The "Extension" format is defined in Section 4.2. Valid 2672 extensions for server certificates at present include the OCSP 2673 Status extension [RFC6066] and the SignedCertificateTimestamp 2674 extension [RFC6962]; future extensions may be defined for this 2675 message as well. Extensions in the Certificate message from the 2676 server MUST correspond to ones from the ClientHello message. 2677 Extensions in the Certificate message from the client MUST 2678 correspond to extensions in the CertificateRequest message from 2679 the server. If an extension applies to the entire chain, it 2680 SHOULD be included in the first CertificateEntry. 2682 If the corresponding certificate type extension 2683 ("server_certificate_type" or "client_certificate_type") was not 2684 negotiated in EncryptedExtensions, or the X.509 certificate type was 2685 negotiated, then each CertificateEntry contains a DER-encoded X.509 2686 certificate. The sender's certificate MUST come in the first 2687 CertificateEntry in the list. Each following certificate SHOULD 2688 directly certify the one immediately preceding it. Because 2689 certificate validation requires that trust anchors be distributed 2690 independently, a certificate that specifies a trust anchor MAY be 2691 omitted from the chain, provided that supported peers are known to 2692 possess any omitted certificates. 2694 Note: Prior to TLS 1.3, "certificate_list" ordering required each 2695 certificate to certify the one immediately preceding it; however, 2696 some implementations allowed some flexibility. Servers sometimes 2697 send both a current and deprecated intermediate for transitional 2698 purposes, and others are simply configured incorrectly, but these 2699 cases can nonetheless be validated properly. For maximum 2700 compatibility, all implementations SHOULD be prepared to handle 2701 potentially extraneous certificates and arbitrary orderings from any 2702 TLS version, with the exception of the end-entity certificate which 2703 MUST be first. 2705 If the RawPublicKey certificate type was negotiated, then the 2706 certificate_list MUST contain no more than one CertificateEntry, 2707 which contains an ASN1_subjectPublicKeyInfo value as defined in 2708 [RFC7250], Section 3. 2710 The OpenPGP certificate type [RFC6091] MUST NOT be used with TLS 1.3. 2712 The server's certificate_list MUST always be non-empty. A client 2713 will send an empty certificate_list if it does not have an 2714 appropriate certificate to send in response to the server's 2715 authentication request. 2717 4.4.2.1. OCSP Status and SCT Extensions 2719 [RFC6066] and [RFC6961] provide extensions to negotiate the server 2720 sending OCSP responses to the client. In TLS 1.2 and below, the 2721 server replies with an empty extension to indicate negotiation of 2722 this extension and the OCSP information is carried in a 2723 CertificateStatus message. In TLS 1.3, the server's OCSP information 2724 is carried in an extension in the CertificateEntry containing the 2725 associated certificate. Specifically, the body of the 2726 "status_request" extension from the server MUST be a 2727 CertificateStatus structure as defined in [RFC6066], which is 2728 interpreted as defined in [RFC6960]. 2730 Note: The status_request_v2 extension [RFC6961] is deprecated. TLS 2731 1.3 servers MUST NOT act upon its presence or information in it when 2732 processing ClientHello messages; in particular, they MUST NOT send 2733 the status_request_v2 extension in the EncryptedExtensions, 2734 CertificateRequest, or Certificate messages. TLS 1.3 servers MUST be 2735 able to process ClientHello messages that include it, as it MAY be 2736 sent by clients that wish to use it in earlier protocol versions. 2738 A server MAY request that a client present an OCSP response with its 2739 certificate by sending an empty "status_request" extension in its 2740 CertificateRequest message. If the client opts to send an OCSP 2741 response, the body of its "status_request" extension MUST be a 2742 CertificateStatus structure as defined in [RFC6066]. 2744 Similarly, [RFC6962] provides a mechanism for a server to send a 2745 Signed Certificate Timestamp (SCT) as an extension in the ServerHello 2746 in TLS 1.2 and below. In TLS 1.3, the server's SCT information is 2747 carried in an extension in the CertificateEntry. 2749 4.4.2.2. Server Certificate Selection 2751 The following rules apply to the certificates sent by the server: 2753 * The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2754 negotiated otherwise (e.g., [RFC7250]). 2756 * The server's end-entity certificate's public key (and associated 2757 restrictions) MUST be compatible with the selected authentication 2758 algorithm from the client's "signature_algorithms" extension 2759 (currently RSA, ECDSA, or EdDSA). 2761 * The certificate MUST allow the key to be used for signing (i.e., 2762 the digitalSignature bit MUST be set if the Key Usage extension is 2763 present) with a signature scheme indicated in the client's 2764 "signature_algorithms"/"signature_algorithms_cert" extensions (see 2765 Section 4.2.3). 2767 * The "server_name" [RFC6066] and "certificate_authorities" 2768 extensions are used to guide certificate selection. As servers 2769 MAY require the presence of the "server_name" extension, clients 2770 SHOULD send this extension when the server is identified by name. 2772 All certificates provided by the server MUST be signed by a signature 2773 algorithm advertised by the client, if it is able to provide such a 2774 chain (see Section 4.2.3). Certificates that are self-signed or 2775 certificates that are expected to be trust anchors are not validated 2776 as part of the chain and therefore MAY be signed with any algorithm. 2778 If the server cannot produce a certificate chain that is signed only 2779 via the indicated supported algorithms, then it SHOULD continue the 2780 handshake by sending the client a certificate chain of its choice 2781 that may include algorithms that are not known to be supported by the 2782 client. This fallback chain SHOULD NOT use the deprecated SHA-1 hash 2783 algorithm in general, but MAY do so if the client's advertisement 2784 permits it, and MUST NOT do so otherwise. 2786 If the client cannot construct an acceptable chain using the provided 2787 certificates and decides to abort the handshake, then it MUST abort 2788 the handshake with an appropriate certificate-related alert (by 2789 default, "unsupported_certificate"; see Section 6.2 for more 2790 information). 2792 If the server has multiple certificates, it chooses one of them based 2793 on the above-mentioned criteria (in addition to other criteria, such 2794 as transport-layer endpoint, local configuration, and preferences). 2796 4.4.2.3. Client Certificate Selection 2798 The following rules apply to certificates sent by the client: 2800 * The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2801 negotiated otherwise (e.g., [RFC7250]). 2803 * If the "certificate_authorities" extension in the 2804 CertificateRequest message was present, at least one of the 2805 certificates in the certificate chain SHOULD be issued by one of 2806 the listed CAs. 2808 * The certificates MUST be signed using an acceptable signature 2809 algorithm, as described in Section 4.3.2. Note that this relaxes 2810 the constraints on certificate-signing algorithms found in prior 2811 versions of TLS. 2813 * If the CertificateRequest message contained a non-empty 2814 "oid_filters" extension, the end-entity certificate MUST match the 2815 extension OIDs that are recognized by the client, as described in 2816 Section 4.2.5. 2818 4.4.2.4. Receiving a Certificate Message 2820 In general, detailed certificate validation procedures are out of 2821 scope for TLS (see [RFC5280]). This section provides TLS-specific 2822 requirements. 2824 If the server supplies an empty Certificate message, the client MUST 2825 abort the handshake with a "decode_error" alert. 2827 If the client does not send any certificates (i.e., it sends an empty 2828 Certificate message), the server MAY at its discretion either 2829 continue the handshake without client authentication, or abort the 2830 handshake with a "certificate_required" alert. Also, if some aspect 2831 of the certificate chain was unacceptable (e.g., it was not signed by 2832 a known, trusted CA), the server MAY at its discretion either 2833 continue the handshake (considering the client unauthenticated) or 2834 abort the handshake. 2836 Any endpoint receiving any certificate which it would need to 2837 validate using any signature algorithm using an MD5 hash MUST abort 2838 the handshake with a "bad_certificate" alert. SHA-1 is deprecated 2839 and it is RECOMMENDED that any endpoint receiving any certificate 2840 which it would need to validate using any signature algorithm using a 2841 SHA-1 hash abort the handshake with a "bad_certificate" alert. For 2842 clarity, this means that endpoints can accept these algorithms for 2843 certificates that are self-signed or are trust anchors. 2845 All endpoints are RECOMMENDED to transition to SHA-256 or better as 2846 soon as possible to maintain interoperability with implementations 2847 currently in the process of phasing out SHA-1 support. 2849 Note that a certificate containing a key for one signature algorithm 2850 MAY be signed using a different signature algorithm (for instance, an 2851 RSA key signed with an ECDSA key). 2853 4.4.3. Certificate Verify 2855 This message is used to provide explicit proof that an endpoint 2856 possesses the private key corresponding to its certificate. The 2857 CertificateVerify message also provides integrity for the handshake 2858 up to this point. Servers MUST send this message when authenticating 2859 via a certificate. Clients MUST send this message whenever 2860 authenticating via a certificate (i.e., when the Certificate message 2861 is non-empty). When sent, this message MUST appear immediately after 2862 the Certificate message and immediately prior to the Finished 2863 message. 2865 Structure of this message: 2867 struct { 2868 SignatureScheme algorithm; 2869 opaque signature<0..2^16-1>; 2870 } CertificateVerify; 2872 The algorithm field specifies the signature algorithm used (see 2873 Section 4.2.3 for the definition of this type). The signature is a 2874 digital signature using that algorithm. The content that is covered 2875 under the signature is the hash output as described in Section 4.4.1, 2876 namely: 2878 Transcript-Hash(Handshake Context, Certificate) 2880 The digital signature is then computed over the concatenation of: 2882 * A string that consists of octet 32 (0x20) repeated 64 times 2884 * The context string (defined below) 2886 * A single 0 byte which serves as the separator 2888 * The content to be signed 2890 This structure is intended to prevent an attack on previous versions 2891 of TLS in which the ServerKeyExchange format meant that attackers 2892 could obtain a signature of a message with a chosen 32-byte prefix 2893 (ClientHello.random). The initial 64-byte pad clears that prefix 2894 along with the server-controlled ServerHello.random. 2896 The context string for a server signature is "TLS 1.3, server 2897 CertificateVerify" The context string for a client signature is "TLS 2898 1.3, client CertificateVerify" It is used to provide separation 2899 between signatures made in different contexts, helping against 2900 potential cross-protocol attacks. 2902 For example, if the transcript hash was 32 bytes of 01 (this length 2903 would make sense for SHA-256), the content covered by the digital 2904 signature for a server CertificateVerify would be: 2906 2020202020202020202020202020202020202020202020202020202020202020 2907 2020202020202020202020202020202020202020202020202020202020202020 2908 544c5320312e332c207365727665722043657274696669636174655665726966 2909 79 2910 00 2911 0101010101010101010101010101010101010101010101010101010101010101 2913 On the sender side, the process for computing the signature field of 2914 the CertificateVerify message takes as input: 2916 * The content covered by the digital signature 2918 * The private signing key corresponding to the certificate sent in 2919 the previous message 2921 If the CertificateVerify message is sent by a server, the signature 2922 algorithm MUST be one offered in the client's "signature_algorithms" 2923 extension unless no valid certificate chain can be produced without 2924 unsupported algorithms (see Section 4.2.3). 2926 If sent by a client, the signature algorithm used in the signature 2927 MUST be one of those present in the supported_signature_algorithms 2928 field of the "signature_algorithms" extension in the 2929 CertificateRequest message. 2931 In addition, the signature algorithm MUST be compatible with the key 2932 in the sender's end-entity certificate. RSA signatures MUST use an 2933 RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS1-v1_5 2934 algorithms appear in "signature_algorithms". The SHA-1 algorithm 2935 MUST NOT be used in any signatures of CertificateVerify messages. 2936 All SHA-1 signature algorithms in this specification are defined 2937 solely for use in legacy certificates and are not valid for 2938 CertificateVerify signatures. 2940 The receiver of a CertificateVerify message MUST verify the signature 2941 field. The verification process takes as input: 2943 * The content covered by the digital signature 2945 * The public key contained in the end-entity certificate found in 2946 the associated Certificate message 2948 * The digital signature received in the signature field of the 2949 CertificateVerify message 2951 If the verification fails, the receiver MUST terminate the handshake 2952 with a "decrypt_error" alert. 2954 4.4.4. Finished 2956 The Finished message is the final message in the Authentication 2957 Block. It is essential for providing authentication of the handshake 2958 and of the computed keys. 2960 Recipients of Finished messages MUST verify that the contents are 2961 correct and if incorrect MUST terminate the connection with a 2962 "decrypt_error" alert. 2964 Once a side has sent its Finished message and has received and 2965 validated the Finished message from its peer, it may begin to send 2966 and receive Application Data over the connection. There are two 2967 settings in which it is permitted to send data prior to receiving the 2968 peer's Finished: 2970 1. Clients sending 0-RTT data as described in Section 4.2.10. 2972 2. Servers MAY send data after sending their first flight, but 2973 because the handshake is not yet complete, they have no assurance 2974 of either the peer's identity or its liveness (i.e., the 2975 ClientHello might have been replayed). 2977 The key used to compute the Finished message is computed from the 2978 Base Key defined in Section 4.4 using HKDF (see Section 7.1). 2979 Specifically: 2981 finished_key = 2982 HKDF-Expand-Label(BaseKey, "finished", "", Hash.length) 2984 Structure of this message: 2986 struct { 2987 opaque verify_data[Hash.length]; 2988 } Finished; 2990 The verify_data value is computed as follows: 2992 verify_data = 2993 HMAC(finished_key, 2994 Transcript-Hash(Handshake Context, 2995 Certificate*, CertificateVerify*)) 2997 * Only included if present. 2999 HMAC [RFC2104] uses the Hash algorithm for the handshake. As noted 3000 above, the HMAC input can generally be implemented by a running hash, 3001 i.e., just the handshake hash at this point. 3003 In previous versions of TLS, the verify_data was always 12 octets 3004 long. In TLS 1.3, it is the size of the HMAC output for the Hash 3005 used for the handshake. 3007 Note: Alerts and any other non-handshake record types are not 3008 handshake messages and are not included in the hash computations. 3010 Any records following a Finished message MUST be encrypted under the 3011 appropriate application traffic key as described in Section 7.2. In 3012 particular, this includes any alerts sent by the server in response 3013 to client Certificate and CertificateVerify messages. 3015 4.5. End of Early Data 3017 struct {} EndOfEarlyData; 3019 If the server sent an "early_data" extension in EncryptedExtensions, 3020 the client MUST send an EndOfEarlyData message after receiving the 3021 server Finished. If the server does not send an "early_data" 3022 extension in EncryptedExtensions, then the client MUST NOT send an 3023 EndOfEarlyData message. This message indicates that all 0-RTT 3024 application_data messages, if any, have been transmitted and that the 3025 following records are protected under handshake traffic keys. 3026 Servers MUST NOT send this message, and clients receiving it MUST 3027 terminate the connection with an "unexpected_message" alert. This 3028 message is encrypted under keys derived from the 3029 client_early_traffic_secret. 3031 4.6. Post-Handshake Messages 3033 TLS also allows other messages to be sent after the main handshake. 3034 These messages use a handshake content type and are encrypted under 3035 the appropriate application traffic key. 3037 4.6.1. New Session Ticket Message 3039 At any time after the server has received the client Finished 3040 message, it MAY send a NewSessionTicket message. This message 3041 creates a unique association between the ticket value and a secret 3042 PSK derived from the resumption main secret (see Section 7). 3044 The client MAY use this PSK for future handshakes by including the 3045 ticket value in the "pre_shared_key" extension in its ClientHello 3046 (Section 4.2.11). Servers MAY send multiple tickets on a single 3047 connection, either immediately after each other or after specific 3048 events (see Appendix C.4). For instance, the server might send a new 3049 ticket after post-handshake authentication in order to encapsulate 3050 the additional client authentication state. Multiple tickets are 3051 useful for clients for a variety of purposes, including: 3053 * Opening multiple parallel HTTP connections. 3055 * Performing connection racing across interfaces and address 3056 families via (for example) Happy Eyeballs [RFC8305] or related 3057 techniques. 3059 Any ticket MUST only be resumed with a cipher suite that has the same 3060 KDF hash algorithm as that used to establish the original connection. 3062 Clients MUST only resume if the new SNI value is valid for the server 3063 certificate presented in the original session, and SHOULD only resume 3064 if the SNI value matches the one used in the original session. The 3065 latter is a performance optimization: normally, there is no reason to 3066 expect that different servers covered by a single certificate would 3067 be able to accept each other's tickets; hence, attempting resumption 3068 in that case would waste a single-use ticket. If such an indication 3069 is provided (externally or by any other means), clients MAY resume 3070 with a different SNI value. 3072 On resumption, if reporting an SNI value to the calling application, 3073 implementations MUST use the value sent in the resumption ClientHello 3074 rather than the value sent in the previous session. Note that if a 3075 server implementation declines all PSK identities with different SNI 3076 values, these two values are always the same. 3078 Note: Although the resumption main secret depends on the client's 3079 second flight, a server which does not request client authentication 3080 MAY compute the remainder of the transcript independently and then 3081 send a NewSessionTicket immediately upon sending its Finished rather 3082 than waiting for the client Finished. This might be appropriate in 3083 cases where the client is expected to open multiple TLS connections 3084 in parallel and would benefit from the reduced overhead of a 3085 resumption handshake, for example. 3087 struct { 3088 uint32 ticket_lifetime; 3089 uint32 ticket_age_add; 3090 opaque ticket_nonce<0..255>; 3091 opaque ticket<1..2^16-1>; 3092 Extension extensions<0..2^16-2>; 3093 } NewSessionTicket; 3095 ticket_lifetime: Indicates the lifetime in seconds as a 32-bit 3096 unsigned integer in network byte order from the time of ticket 3097 issuance. Servers MUST NOT use any value greater than 604800 3098 seconds (7 days). The value of zero indicates that the ticket 3099 should be discarded immediately. Clients MUST NOT use tickets for 3100 longer than 7 days after issuance, regardless of the 3101 ticket_lifetime, and MAY delete tickets earlier based on local 3102 policy. A server MAY treat a ticket as valid for a shorter period 3103 of time than what is stated in the ticket_lifetime. 3105 ticket_age_add: A securely generated, random 32-bit value that is 3106 used to obscure the age of the ticket that the client includes in 3107 the "pre_shared_key" extension. The client-side ticket age is 3108 added to this value modulo 2^32 to obtain the value that is 3109 transmitted by the client. The server MUST generate a fresh value 3110 for each ticket it sends. 3112 ticket_nonce: A per-ticket value that is unique across all tickets 3113 issued on this connection. 3115 ticket: The value of the ticket to be used as the PSK identity. The 3116 ticket itself is an opaque label. It MAY be either a database 3117 lookup key or a self-encrypted and self-authenticated value. 3119 extensions: A list of extension values for the ticket. The 3120 "Extension" format is defined in Section 4.2. Clients MUST ignore 3121 unrecognized extensions. 3123 The sole extension currently defined for NewSessionTicket is 3124 "early_data", indicating that the ticket may be used to send 0-RTT 3125 data (Section 4.2.10). It contains the following value: 3127 max_early_data_size: The maximum amount of 0-RTT data that the 3128 client is allowed to send when using this ticket, in bytes. Only 3129 Application Data payload (i.e., plaintext but not padding or the 3130 inner content type byte) is counted. A server receiving more than 3131 max_early_data_size bytes of 0-RTT data SHOULD terminate the 3132 connection with an "unexpected_message" alert. Note that servers 3133 that reject early data due to lack of cryptographic material will 3134 be unable to differentiate padding from content, so clients SHOULD 3135 NOT depend on being able to send large quantities of padding in 3136 early data records. 3138 The PSK associated with the ticket is computed as: 3140 HKDF-Expand-Label(resumption_main_secret, 3141 "resumption", ticket_nonce, Hash.length) 3143 Because the ticket_nonce value is distinct for each NewSessionTicket 3144 message, a different PSK will be derived for each ticket. 3146 Note that in principle it is possible to continue issuing new tickets 3147 which indefinitely extend the lifetime of the keying material 3148 originally derived from an initial non-PSK handshake (which was most 3149 likely tied to the peer's certificate). It is RECOMMENDED that 3150 implementations place limits on the total lifetime of such keying 3151 material; these limits should take into account the lifetime of the 3152 peer's certificate, the likelihood of intervening revocation, and the 3153 time since the peer's online CertificateVerify signature. 3155 4.6.2. Post-Handshake Authentication 3157 When the client has sent the "post_handshake_auth" extension (see 3158 Section 4.2.6), a server MAY request client authentication at any 3159 time after the handshake has completed by sending a 3160 CertificateRequest message. The client MUST respond with the 3161 appropriate Authentication messages (see Section 4.4). If the client 3162 chooses to authenticate, it MUST send Certificate, CertificateVerify, 3163 and Finished. If it declines, it MUST send a Certificate message 3164 containing no certificates followed by Finished. All of the client's 3165 messages for a given response MUST appear consecutively on the wire 3166 with no intervening messages of other types. 3168 A client that receives a CertificateRequest message without having 3169 sent the "post_handshake_auth" extension MUST send an 3170 "unexpected_message" fatal alert. 3172 Note: Because client authentication could involve prompting the user, 3173 servers MUST be prepared for some delay, including receiving an 3174 arbitrary number of other messages between sending the 3175 CertificateRequest and receiving a response. In addition, clients 3176 which receive multiple CertificateRequests in close succession MAY 3177 respond to them in a different order than they were received (the 3178 certificate_request_context value allows the server to disambiguate 3179 the responses). 3181 4.6.3. Key and Initialization Vector Update 3183 The KeyUpdate handshake message is used to indicate that the sender 3184 is updating its sending cryptographic keys. This message can be sent 3185 by either peer after it has sent a Finished message. Implementations 3186 that receive a KeyUpdate message prior to receiving a Finished 3187 message MUST terminate the connection with an "unexpected_message" 3188 alert. After sending a KeyUpdate message, the sender SHALL send all 3189 its traffic using the next generation of keys, computed as described 3190 in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update 3191 its receiving keys. 3193 enum { 3194 update_not_requested(0), update_requested(1), (255) 3195 } KeyUpdateRequest; 3197 struct { 3198 KeyUpdateRequest request_update; 3199 } KeyUpdate; 3201 request_update: Indicates whether the recipient of the KeyUpdate 3202 should respond with its own KeyUpdate. If an implementation 3203 receives any other value, it MUST terminate the connection with an 3204 "illegal_parameter" alert. 3206 If the request_update field is set to "update_requested", then the 3207 receiver MUST send a KeyUpdate of its own with request_update set to 3208 "update_not_requested" prior to sending its next Application Data 3209 record. This mechanism allows either side to force an update to the 3210 entire connection, but causes an implementation which receives 3211 multiple KeyUpdates while it is silent to respond with a single 3212 update. Note that implementations may receive an arbitrary number of 3213 messages between sending a KeyUpdate with request_update set to 3214 "update_requested" and receiving the peer's KeyUpdate, because those 3215 messages may already be in flight. However, because send and receive 3216 keys are derived from independent traffic secrets, retaining the 3217 receive traffic secret does not threaten the forward secrecy of data 3218 sent before the sender changed keys. 3220 If implementations independently send their own KeyUpdates with 3221 request_update set to "update_requested", and they cross in flight, 3222 then each side will also send a response, with the result that each 3223 side increments by two generations. 3225 Both sender and receiver MUST encrypt their KeyUpdate messages with 3226 the old keys. Additionally, both sides MUST enforce that a KeyUpdate 3227 with the old key is received before accepting any messages encrypted 3228 with the new key. Failure to do so may allow message truncation 3229 attacks. 3231 5. Record Protocol 3233 The TLS record protocol takes messages to be transmitted, fragments 3234 the data into manageable blocks, protects the records, and transmits 3235 the result. Received data is verified, decrypted, reassembled, and 3236 then delivered to higher-level clients. 3238 TLS records are typed, which allows multiple higher-level protocols 3239 to be multiplexed over the same record layer. This document 3240 specifies four content types: handshake, application_data, alert, and 3241 change_cipher_spec. The change_cipher_spec record is used only for 3242 compatibility purposes (see Appendix D.4). 3244 An implementation may receive an unencrypted record of type 3245 change_cipher_spec consisting of the single byte value 0x01 at any 3246 time after the first ClientHello message has been sent or received 3247 and before the peer's Finished message has been received and MUST 3248 simply drop it without further processing. Note that this record may 3249 appear at a point at the handshake where the implementation is 3250 expecting protected records, and so it is necessary to detect this 3251 condition prior to attempting to deprotect the record. An 3252 implementation which receives any other change_cipher_spec value or 3253 which receives a protected change_cipher_spec record MUST abort the 3254 handshake with an "unexpected_message" alert. If an implementation 3255 detects a change_cipher_spec record received before the first 3256 ClientHello message or after the peer's Finished message, it MUST be 3257 treated as an unexpected record type (though stateless servers may 3258 not be able to distinguish these cases from allowed cases). 3260 Implementations MUST NOT send record types not defined in this 3261 document unless negotiated by some extension. If a TLS 3262 implementation receives an unexpected record type, it MUST terminate 3263 the connection with an "unexpected_message" alert. New record 3264 content type values are assigned by IANA in the TLS ContentType 3265 registry as described in Section 11. 3267 5.1. Record Layer 3269 The record layer fragments information blocks into TLSPlaintext 3270 records carrying data in chunks of 2^14 bytes or less. Message 3271 boundaries are handled differently depending on the underlying 3272 ContentType. Any future content types MUST specify appropriate 3273 rules. Note that these rules are stricter than what was enforced in 3274 TLS 1.2. 3276 Handshake messages MAY be coalesced into a single TLSPlaintext record 3277 or fragmented across several records, provided that: 3279 * Handshake messages MUST NOT be interleaved with other record 3280 types. That is, if a handshake message is split over two or more 3281 records, there MUST NOT be any other records between them. 3283 * Handshake messages MUST NOT span key changes. Implementations 3284 MUST verify that all messages immediately preceding a key change 3285 align with a record boundary; if not, then they MUST terminate the 3286 connection with an "unexpected_message" alert. Because the 3287 ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate 3288 messages can immediately precede a key change, implementations 3289 MUST send these messages in alignment with a record boundary. 3291 Implementations MUST NOT send zero-length fragments of Handshake 3292 types, even if those fragments contain padding. 3294 Alert messages (Section 6) MUST NOT be fragmented across records, and 3295 multiple alert messages MUST NOT be coalesced into a single 3296 TLSPlaintext record. In other words, a record with an Alert type 3297 MUST contain exactly one message. 3299 Application Data messages contain data that is opaque to TLS. 3300 Application Data messages are always protected. Zero-length 3301 fragments of Application Data MAY be sent, as they are potentially 3302 useful as a traffic analysis countermeasure. Application Data 3303 fragments MAY be split across multiple records or coalesced into a 3304 single record. 3306 enum { 3307 invalid(0), 3308 change_cipher_spec(20), 3309 alert(21), 3310 handshake(22), 3311 application_data(23), 3312 (255) 3313 } ContentType; 3315 struct { 3316 ContentType type; 3317 ProtocolVersion legacy_record_version; 3318 uint16 length; 3319 opaque fragment[TLSPlaintext.length]; 3320 } TLSPlaintext; 3322 type: The higher-level protocol used to process the enclosed 3323 fragment. 3325 legacy_record_version: MUST be set to 0x0303 for all records 3326 generated by a TLS 1.3 implementation other than an initial 3327 ClientHello (i.e., one not generated after a HelloRetryRequest), 3328 where it MAY also be 0x0301 for compatibility purposes. This 3329 field is deprecated and MUST be ignored for all purposes. 3330 Previous versions of TLS would use other values in this field 3331 under some circumstances. 3333 length: The length (in bytes) of the following 3334 TLSPlaintext.fragment. The length MUST NOT exceed 2^14 bytes. An 3335 endpoint that receives a record that exceeds this length MUST 3336 terminate the connection with a "record_overflow" alert. 3338 fragment The data being transmitted. This value is transparent and 3339 is treated as an independent block to be dealt with by the higher- 3340 level protocol specified by the type field. 3342 This document describes TLS 1.3, which uses the version 0x0304. This 3343 version value is historical, deriving from the use of 0x0301 for TLS 3344 1.0 and 0x0300 for SSL 3.0. In order to maximize backward 3345 compatibility, a record containing an initial ClientHello SHOULD have 3346 version 0x0301 (reflecting TLS 1.0) and a record containing a second 3347 ClientHello or a ServerHello MUST have version 0x0303 (reflecting TLS 3348 1.2). When negotiating prior versions of TLS, endpoints follow the 3349 procedure and requirements provided in Appendix D. 3351 When record protection has not yet been engaged, TLSPlaintext 3352 structures are written directly onto the wire. Once record 3353 protection has started, TLSPlaintext records are protected and sent 3354 as described in the following section. Note that Application Data 3355 records MUST NOT be written to the wire unprotected (see Section 2 3356 for details). 3358 5.2. Record Payload Protection 3360 The record protection functions translate a TLSPlaintext structure 3361 into a TLSCiphertext structure. The deprotection functions reverse 3362 the process. In TLS 1.3, as opposed to previous versions of TLS, all 3363 ciphers are modeled as "Authenticated Encryption with Associated 3364 Data" (AEAD) [RFC5116]. AEAD functions provide a unified encryption 3365 and authentication operation which turns plaintext into authenticated 3366 ciphertext and back again. Each encrypted record consists of a 3367 plaintext header followed by an encrypted body, which itself contains 3368 a type and optional padding. 3370 struct { 3371 opaque content[TLSPlaintext.length]; 3372 ContentType type; 3373 uint8 zeros[length_of_padding]; 3374 } TLSInnerPlaintext; 3376 struct { 3377 ContentType opaque_type = application_data; /* 23 */ 3378 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */ 3379 uint16 length; 3380 opaque encrypted_record[TLSCiphertext.length]; 3381 } TLSCiphertext; 3383 content: The TLSPlaintext.fragment value, containing the byte 3384 encoding of a handshake or an alert message, or the raw bytes of 3385 the application's data to send. 3387 type: The TLSPlaintext.type value containing the content type of the 3388 record. 3390 zeros: An arbitrary-length run of zero-valued bytes may appear in 3391 the cleartext after the type field. This provides an opportunity 3392 for senders to pad any TLS record by a chosen amount as long as 3393 the total stays within record size limits. See Section 5.4 for 3394 more details. 3396 opaque_type: The outer opaque_type field of a TLSCiphertext record 3397 is always set to the value 23 (application_data) for outward 3398 compatibility with middleboxes accustomed to parsing previous 3399 versions of TLS. The actual content type of the record is found 3400 in TLSInnerPlaintext.type after decryption. 3402 legacy_record_version: The legacy_record_version field is always 3403 0x0303. TLS 1.3 TLSCiphertexts are not generated until after TLS 3404 1.3 has been negotiated, so there are no historical compatibility 3405 concerns where other values might be received. Note that the 3406 handshake protocol, including the ClientHello and ServerHello 3407 messages, authenticates the protocol version, so this value is 3408 redundant. 3410 length: The length (in bytes) of the following 3411 TLSCiphertext.encrypted_record, which is the sum of the lengths of 3412 the content and the padding, plus one for the inner content type, 3413 plus any expansion added by the AEAD algorithm. The length MUST 3414 NOT exceed 2^14 + 256 bytes. An endpoint that receives a record 3415 that exceeds this length MUST terminate the connection with a 3416 "record_overflow" alert. 3418 encrypted_record: The AEAD-encrypted form of the serialized 3419 TLSInnerPlaintext structure. 3421 AEAD algorithms take as input a single key, a nonce, a plaintext, and 3422 "additional data" to be included in the authentication check, as 3423 described in Section 2.1 of [RFC5116]. The key is either the 3424 client_write_key or the server_write_key, the nonce is derived from 3425 the sequence number and the client_write_iv or server_write_iv (see 3426 Section 5.3), and the additional data input is the record header. 3427 I.e., 3429 additional_data = TLSCiphertext.opaque_type || 3430 TLSCiphertext.legacy_record_version || 3431 TLSCiphertext.length 3433 The plaintext input to the AEAD algorithm is the encoded 3434 TLSInnerPlaintext structure. Derivation of traffic keys is defined 3435 in Section 7.3. 3437 The AEAD output consists of the ciphertext output from the AEAD 3438 encryption operation. The length of the plaintext is greater than 3439 the corresponding TLSPlaintext.length due to the inclusion of 3440 TLSInnerPlaintext.type and any padding supplied by the sender. The 3441 length of the AEAD output will generally be larger than the 3442 plaintext, but by an amount that varies with the AEAD algorithm. 3443 Since the ciphers might incorporate padding, the amount of overhead 3444 could vary with different lengths of plaintext. Symbolically, 3446 AEADEncrypted = 3447 AEAD-Encrypt(write_key, nonce, additional_data, plaintext) 3449 The encrypted_record field of TLSCiphertext is set to AEADEncrypted. 3451 In order to decrypt and verify, the cipher takes as input the key, 3452 nonce, additional data, and the AEADEncrypted value. The output is 3453 either the plaintext or an error indicating that the decryption 3454 failed. There is no separate integrity check. Symbolically, 3456 plaintext of encrypted_record = 3457 AEAD-Decrypt(peer_write_key, nonce, additional_data, AEADEncrypted) 3459 If the decryption fails, the receiver MUST terminate the connection 3460 with a "bad_record_mac" alert. 3462 An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion 3463 greater than 255 octets. An endpoint that receives a record from its 3464 peer with TLSCiphertext.length larger than 2^14 + 256 octets MUST 3465 terminate the connection with a "record_overflow" alert. This limit 3466 is derived from the maximum TLSInnerPlaintext length of 2^14 octets + 3467 1 octet for ContentType + the maximum AEAD expansion of 255 octets. 3469 5.3. Per-Record Nonce 3471 A 64-bit sequence number is maintained separately for reading and 3472 writing records. The appropriate sequence number is incremented by 3473 one after reading or writing each record. Each sequence number is 3474 set to zero at the beginning of a connection and whenever the key is 3475 changed; the first record transmitted under a particular traffic key 3476 MUST use sequence number 0. 3478 Because the size of sequence numbers is 64-bit, they should not wrap. 3479 If a TLS implementation would need to wrap a sequence number, it MUST 3480 either rekey (Section 4.6.3) or terminate the connection. 3482 Each AEAD algorithm will specify a range of possible lengths for the 3483 per-record nonce, from N_MIN bytes to N_MAX bytes of input [RFC5116]. 3484 The length of the TLS per-record nonce (iv_length) is set to the 3485 larger of 8 bytes and N_MIN for the AEAD algorithm (see [RFC5116], 3486 Section 4). An AEAD algorithm where N_MAX is less than 8 bytes MUST 3487 NOT be used with TLS. The per-record nonce for the AEAD construction 3488 is formed as follows: 3490 1. The 64-bit record sequence number is encoded in network byte 3491 order and padded to the left with zeros to iv_length. 3493 2. The padded sequence number is XORed with either the static 3494 client_write_iv or server_write_iv (depending on the role). 3496 The resulting quantity (of length iv_length) is used as the per- 3497 record nonce. 3499 Note: This is a different construction from that in TLS 1.2, which 3500 specified a partially explicit nonce. 3502 5.4. Record Padding 3504 All encrypted TLS records can be padded to inflate the size of the 3505 TLSCiphertext. This allows the sender to hide the size of the 3506 traffic from an observer. 3508 When generating a TLSCiphertext record, implementations MAY choose to 3509 pad. An unpadded record is just a record with a padding length of 3510 zero. Padding is a string of zero-valued bytes appended to the 3511 ContentType field before encryption. Implementations MUST set the 3512 padding octets to all zeros before encrypting. 3514 Application Data records may contain a zero-length 3515 TLSInnerPlaintext.content if the sender desires. This permits 3516 generation of plausibly sized cover traffic in contexts where the 3517 presence or absence of activity may be sensitive. Implementations 3518 MUST NOT send Handshake and Alert records that have a zero-length 3519 TLSInnerPlaintext.content; if such a message is received, the 3520 receiving implementation MUST terminate the connection with an 3521 "unexpected_message" alert. 3523 The padding sent is automatically verified by the record protection 3524 mechanism; upon successful decryption of a 3525 TLSCiphertext.encrypted_record, the receiving implementation scans 3526 the field from the end toward the beginning until it finds a non-zero 3527 octet. This non-zero octet is the content type of the message. This 3528 padding scheme was selected because it allows padding of any 3529 encrypted TLS record by an arbitrary size (from zero up to TLS record 3530 size limits) without introducing new content types. The design also 3531 enforces all-zero padding octets, which allows for quick detection of 3532 padding errors. 3534 Implementations MUST limit their scanning to the cleartext returned 3535 from the AEAD decryption. If a receiving implementation does not 3536 find a non-zero octet in the cleartext, it MUST terminate the 3537 connection with an "unexpected_message" alert. 3539 The presence of padding does not change the overall record size 3540 limitations: the full encoded TLSInnerPlaintext MUST NOT exceed 2^14 3541 + 1 octets. If the maximum fragment length is reduced - as for 3542 example by the record_size_limit extension from [RFC8449] - then the 3543 reduced limit applies to the full plaintext, including the content 3544 type and padding. 3546 Selecting a padding policy that suggests when and how much to pad is 3547 a complex topic and is beyond the scope of this specification. If 3548 the application-layer protocol on top of TLS has its own padding, it 3549 may be preferable to pad Application Data TLS records within the 3550 application layer. Padding for encrypted Handshake or Alert records 3551 must still be handled at the TLS layer, though. Later documents may 3552 define padding selection algorithms or define a padding policy 3553 request mechanism through TLS extensions or some other means. 3555 5.5. Limits on Key Usage 3557 There are cryptographic limits on the amount of plaintext which can 3558 be safely encrypted under a given set of keys. [AEAD-LIMITS] 3559 provides an analysis of these limits under the assumption that the 3560 underlying primitive (AES or ChaCha20) has no weaknesses. 3561 Implementations SHOULD do a key update as described in Section 4.6.3 3562 prior to reaching these limits. 3564 For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be 3565 encrypted on a given connection while keeping a safety margin of 3566 approximately 2^-57 for Authenticated Encryption (AE) security. For 3567 ChaCha20/Poly1305, the record sequence number would wrap before the 3568 safety limit is reached. 3570 6. Alert Protocol 3572 TLS provides an Alert content type to indicate closure information 3573 and errors. Like other messages, alert messages are encrypted as 3574 specified by the current connection state. 3576 Alert messages convey a description of the alert and a legacy field 3577 that conveyed the severity level of the message in previous versions 3578 of TLS. Alerts are divided into two classes: closure alerts and 3579 error alerts. In TLS 1.3, the severity is implicit in the type of 3580 alert being sent, and the "level" field can safely be ignored. The 3581 "close_notify" alert is used to indicate orderly closure of one 3582 direction of the connection. Upon receiving such an alert, the TLS 3583 implementation SHOULD indicate end-of-data to the application. 3585 Error alerts indicate abortive closure of the connection (see 3586 Section 6.2). Upon receiving an error alert, the TLS implementation 3587 SHOULD indicate an error to the application and MUST NOT allow any 3588 further data to be sent or received on the connection. Servers and 3589 clients MUST forget the secret values and keys established in failed 3590 connections, with the exception of the PSKs associated with session 3591 tickets, which SHOULD be discarded if possible. 3593 All the alerts listed in Section 6.2 MUST be sent with 3594 AlertLevel=fatal and MUST be treated as error alerts when received 3595 regardless of the AlertLevel in the message. Unknown Alert types 3596 MUST be treated as error alerts. 3598 Note: TLS defines two generic alerts (see Section 6) to use upon 3599 failure to parse a message. Peers which receive a message which 3600 cannot be parsed according to the syntax (e.g., have a length 3601 extending beyond the message boundary or contain an out-of-range 3602 length) MUST terminate the connection with a "decode_error" alert. 3603 Peers which receive a message which is syntactically correct but 3604 semantically invalid (e.g., a DHE share of p - 1, or an invalid enum) 3605 MUST terminate the connection with an "illegal_parameter" alert. 3607 enum { warning(1), fatal(2), (255) } AlertLevel; 3609 enum { 3610 close_notify(0), 3611 unexpected_message(10), 3612 bad_record_mac(20), 3613 record_overflow(22), 3614 handshake_failure(40), 3615 bad_certificate(42), 3616 unsupported_certificate(43), 3617 certificate_revoked(44), 3618 certificate_expired(45), 3619 certificate_unknown(46), 3620 illegal_parameter(47), 3621 unknown_ca(48), 3622 access_denied(49), 3623 decode_error(50), 3624 decrypt_error(51), 3625 protocol_version(70), 3626 insufficient_security(71), 3627 internal_error(80), 3628 inappropriate_fallback(86), 3629 user_canceled(90), 3630 missing_extension(109), 3631 unsupported_extension(110), 3632 unrecognized_name(112), 3633 bad_certificate_status_response(113), 3634 unknown_psk_identity(115), 3635 certificate_required(116), 3636 no_application_protocol(120), 3637 (255) 3638 } AlertDescription; 3640 struct { 3641 AlertLevel level; 3642 AlertDescription description; 3643 } Alert; 3645 6.1. Closure Alerts 3647 The client and the server must share knowledge that the connection is 3648 ending in order to avoid a truncation attack. 3650 close_notify: This alert notifies the recipient that the sender will 3651 not send any more messages on this connection. Any data received 3652 after a closure alert has been received MUST be ignored. 3654 user_canceled: This alert notifies the recipient that the sender is 3655 canceling the handshake for some reason unrelated to a protocol 3656 failure. If a user cancels an operation after the handshake is 3657 complete, just closing the connection by sending a "close_notify" 3658 is more appropriate. This alert SHOULD be followed by a 3659 "close_notify". This alert generally has AlertLevel=warning. 3661 Either party MAY initiate a close of its write side of the connection 3662 by sending a "close_notify" alert. Any data received after a closure 3663 alert has been received MUST be ignored. If a transport-level close 3664 is received prior to a "close_notify", the receiver cannot know that 3665 all the data that was sent has been received. 3667 Each party MUST send a "close_notify" alert before closing its write 3668 side of the connection, unless it has already sent some error alert. 3669 This does not have any effect on its read side of the connection. 3670 Note that this is a change from versions of TLS prior to TLS 1.3 in 3671 which implementations were required to react to a "close_notify" by 3672 discarding pending writes and sending an immediate "close_notify" 3673 alert of their own. That previous requirement could cause truncation 3674 in the read side. Both parties need not wait to receive a 3675 "close_notify" alert before closing their read side of the 3676 connection, though doing so would introduce the possibility of 3677 truncation. 3679 If the application protocol using TLS provides that any data may be 3680 carried over the underlying transport after the TLS connection is 3681 closed, the TLS implementation MUST receive a "close_notify" alert 3682 before indicating end-of-data to the application layer. No part of 3683 this standard should be taken to dictate the manner in which a usage 3684 profile for TLS manages its data transport, including when 3685 connections are opened or closed. 3687 Note: It is assumed that closing the write side of a connection 3688 reliably delivers pending data before destroying the transport. 3690 6.2. Error Alerts 3692 Error handling in TLS is very simple. When an error is detected, the 3693 detecting party sends a message to its peer. Upon transmission or 3694 receipt of a fatal alert message, both parties MUST immediately close 3695 the connection. 3697 Whenever an implementation encounters a fatal error condition, it 3698 SHOULD send an appropriate fatal alert and MUST close the connection 3699 without sending or receiving any additional data. Throughout this 3700 specification, when the phrases "terminate the connection" and "abort 3701 the handshake" are used without a specific alert it means that the 3702 implementation SHOULD send the alert indicated by the descriptions 3703 below. The phrases "terminate the connection with an X alert" and 3704 "abort the handshake with an X alert" mean that the implementation 3705 MUST send alert X if it sends any alert. All alerts defined below in 3706 this section, as well as all unknown alerts, are universally 3707 considered fatal as of TLS 1.3 (see Section 6). The implementation 3708 SHOULD provide a way to facilitate logging the sending and receiving 3709 of alerts. 3711 The following error alerts are defined: 3713 unexpected_message: An inappropriate message (e.g., the wrong 3714 handshake message, premature Application Data, etc.) was received. 3715 This alert should never be observed in communication between 3716 proper implementations. 3718 bad_record_mac: This alert is returned if a record is received which 3719 cannot be deprotected. Because AEAD algorithms combine decryption 3720 and verification, and also to avoid side-channel attacks, this 3721 alert is used for all deprotection failures. This alert should 3722 never be observed in communication between proper implementations, 3723 except when messages were corrupted in the network. 3725 record_overflow: A TLSCiphertext record was received that had a 3726 length more than 2^14 + 256 bytes, or a record decrypted to a 3727 TLSPlaintext record with more than 2^14 bytes (or some other 3728 negotiated limit). This alert should never be observed in 3729 communication between proper implementations, except when messages 3730 were corrupted in the network. 3732 handshake_failure: Receipt of a "handshake_failure" alert message 3733 indicates that the sender was unable to negotiate an acceptable 3734 set of security parameters given the options available. 3736 bad_certificate: A certificate was corrupt, contained signatures 3737 that did not verify correctly, etc. 3739 unsupported_certificate: A certificate was of an unsupported type. 3741 certificate_revoked: A certificate was revoked by its signer. 3743 certificate_expired: A certificate has expired or is not currently 3744 valid. 3746 certificate_unknown: Some other (unspecified) issue arose in 3747 processing the certificate, rendering it unacceptable. 3749 illegal_parameter: A field in the handshake was incorrect or 3750 inconsistent with other fields. This alert is used for errors 3751 which conform to the formal protocol syntax but are otherwise 3752 incorrect. 3754 unknown_ca: A valid certificate chain or partial chain was received, 3755 but the certificate was not accepted because the CA certificate 3756 could not be located or could not be matched with a known trust 3757 anchor. 3759 access_denied: A valid certificate or PSK was received, but when 3760 access control was applied, the sender decided not to proceed with 3761 negotiation. 3763 decode_error: A message could not be decoded because some field was 3764 out of the specified range or the length of the message was 3765 incorrect. This alert is used for errors where the message does 3766 not conform to the formal protocol syntax. This alert should 3767 never be observed in communication between proper implementations, 3768 except when messages were corrupted in the network. 3770 decrypt_error: A handshake (not record layer) cryptographic 3771 operation failed, including being unable to correctly verify a 3772 signature or validate a Finished message or a PSK binder. 3774 protocol_version: The protocol version the peer has attempted to 3775 negotiate is recognized but not supported (see Appendix D). 3777 insufficient_security: Returned instead of "handshake_failure" when 3778 a negotiation has failed specifically because the server requires 3779 parameters more secure than those supported by the client. 3781 internal_error: An internal error unrelated to the peer or the 3782 correctness of the protocol (such as a memory allocation failure) 3783 makes it impossible to continue. 3785 inappropriate_fallback: Sent by a server in response to an invalid 3786 connection retry attempt from a client (see [RFC7507]). 3788 missing_extension: Sent by endpoints that receive a handshake 3789 message not containing an extension that is mandatory to send for 3790 the offered TLS version or other negotiated parameters. 3792 unsupported_extension: Sent by endpoints receiving any handshake 3793 message containing an extension known to be prohibited for 3794 inclusion in the given handshake message, or including any 3795 extensions in a ServerHello or Certificate not first offered in 3796 the corresponding ClientHello or CertificateRequest. 3798 unrecognized_name: Sent by servers when no server exists identified 3799 by the name provided by the client via the "server_name" extension 3800 (see [RFC6066]). 3802 bad_certificate_status_response: Sent by clients when an invalid or 3803 unacceptable OCSP response is provided by the server via the 3804 "status_request" extension (see [RFC6066]). 3806 unknown_psk_identity: Sent by servers when PSK key establishment is 3807 desired but no acceptable PSK identity is provided by the client. 3808 Sending this alert is OPTIONAL; servers MAY instead choose to send 3809 a "decrypt_error" alert to merely indicate an invalid PSK 3810 identity. 3812 certificate_required: Sent by servers when a client certificate is 3813 desired but none was provided by the client. 3815 no_application_protocol: Sent by servers when a client 3816 "application_layer_protocol_negotiation" extension advertises only 3817 protocols that the server does not support (see [RFC7301]). 3819 New Alert values are assigned by IANA as described in Section 11. 3821 7. Cryptographic Computations 3823 The TLS handshake establishes one or more input secrets which are 3824 combined to create the actual working keying material, as detailed 3825 below. The key derivation process incorporates both the input 3826 secrets and the handshake transcript. Note that because the 3827 handshake transcript includes the random values from the Hello 3828 messages, any given handshake will have different traffic secrets, 3829 even if the same input secrets are used, as is the case when the same 3830 PSK is used for multiple connections. 3832 7.1. Key Schedule 3834 The key derivation process makes use of the HKDF-Extract and HKDF- 3835 Expand functions as defined for HKDF [RFC5869], as well as the 3836 functions defined below: 3838 HKDF-Expand-Label(Secret, Label, Context, Length) = 3839 HKDF-Expand(Secret, HkdfLabel, Length) 3841 Where HkdfLabel is specified as: 3843 struct { 3844 uint16 length = Length; 3845 opaque label<7..255> = "tls13 " + Label; 3846 opaque context<0..255> = Context; 3847 } HkdfLabel; 3849 Derive-Secret(Secret, Label, Messages) = 3850 HKDF-Expand-Label(Secret, Label, 3851 Transcript-Hash(Messages), Hash.length) 3853 The Hash function used by Transcript-Hash and HKDF is the cipher 3854 suite hash algorithm. Hash.length is its output length in bytes. 3855 Messages is the concatenation of the indicated handshake messages, 3856 including the handshake message type and length fields, but not 3857 including record layer headers. Note that in some cases a zero- 3858 length Context (indicated by "") is passed to HKDF-Expand-Label. The 3859 labels specified in this document are all ASCII strings and do not 3860 include a trailing NUL byte. 3862 Note: With common hash functions, any label longer than 12 characters 3863 requires an additional iteration of the hash function to compute. 3864 The labels in this specification have all been chosen to fit within 3865 this limit. 3867 Keys are derived from two input secrets using the HKDF-Extract and 3868 Derive-Secret functions. The general pattern for adding a new secret 3869 is to use HKDF-Extract with the Salt being the current secret state 3870 and the Input Keying Material (IKM) being the new secret to be added. 3871 In this version of TLS 1.3, the two input secrets are: 3873 * PSK (a pre-shared key established externally or derived from the 3874 resumption_main_secret value from a previous connection) 3876 * (EC)DHE shared secret (Section 7.4) 3878 This produces a full key derivation schedule shown in the diagram 3879 below. In this diagram, the following formatting conventions apply: 3881 * HKDF-Extract is drawn as taking the Salt argument from the top and 3882 the IKM argument from the left, with its output to the bottom and 3883 the name of the output on the right. 3885 * Derive-Secret's Secret argument is indicated by the incoming 3886 arrow. For instance, the Early Secret is the Secret for 3887 generating the client_early_traffic_secret. 3889 * "0" indicates a string of Hash.length bytes set to zero. 3891 Note: the key derivation labels use the string "master" even though 3892 the values are referred to as "main" secrets. This mismatch is a 3893 result of renaming the values while retaining compatibility. 3895 [[OPEN ISSUE: Replace the strings with hex value?]] 3897 0 3898 | 3899 v 3900 PSK -> HKDF-Extract = Early Secret 3901 | 3902 +-----> Derive-Secret(., 3903 | "ext binder" | 3904 | "res binder", 3905 | "") 3906 | = binder_key 3907 | 3908 +-----> Derive-Secret(., "c e traffic", 3909 | ClientHello) 3910 | = client_early_traffic_secret 3911 | 3912 +-----> Derive-Secret(., "e exp master", 3913 | ClientHello) 3914 | = early_exporter_main_secret 3915 v 3916 Derive-Secret(., "derived", "") 3917 | 3918 v 3919 (EC)DHE -> HKDF-Extract = Handshake Secret 3920 | 3921 +-----> Derive-Secret(., "c hs traffic", 3922 | ClientHello...ServerHello) 3923 | = client_handshake_traffic_secret 3924 | 3925 +-----> Derive-Secret(., "s hs traffic", 3926 | ClientHello...ServerHello) 3927 | = server_handshake_traffic_secret 3928 v 3929 Derive-Secret(., "derived", "") 3930 | 3931 v 3932 0 -> HKDF-Extract = Main Secret 3933 | 3934 +-----> Derive-Secret(., "c ap traffic", 3935 | ClientHello...server Finished) 3936 | = client_application_traffic_secret_0 3937 | 3938 +-----> Derive-Secret(., "s ap traffic", 3939 | ClientHello...server Finished) 3940 | = server_application_traffic_secret_0 3941 | 3942 +-----> Derive-Secret(., "exp master", 3943 | ClientHello...server Finished) 3944 | = exporter_main_secret 3945 | 3946 +-----> Derive-Secret(., "res master", 3947 ClientHello...client Finished) 3948 = resumption_main_secret 3950 The general pattern here is that the secrets shown down the left side 3951 of the diagram are just raw entropy without context, whereas the 3952 secrets down the right side include Handshake Context and therefore 3953 can be used to derive working keys without additional context. Note 3954 that the different calls to Derive-Secret may take different Messages 3955 arguments, even with the same secret. In a 0-RTT exchange, Derive- 3956 Secret is called with four distinct transcripts; in a 1-RTT-only 3957 exchange, it is called with three distinct transcripts. 3959 If a given secret is not available, then the 0-value consisting of a 3960 string of Hash.length bytes set to zeros is used. Note that this 3961 does not mean skipping rounds, so if PSK is not in use, Early Secret 3962 will still be HKDF-Extract(0, 0). For the computation of the 3963 binder_key, the label is "ext binder" for external PSKs (those 3964 provisioned outside of TLS) and "res binder" for resumption PSKs 3965 (those provisioned as the resumption main secret of a previous 3966 handshake). The different labels prevent the substitution of one 3967 type of PSK for the other. 3969 There are multiple potential Early Secret values, depending on which 3970 PSK the server ultimately selects. The client will need to compute 3971 one for each potential PSK; if no PSK is selected, it will then need 3972 to compute the Early Secret corresponding to the zero PSK. 3974 Once all the values which are to be derived from a given secret have 3975 been computed, that secret SHOULD be erased. 3977 7.2. Updating Traffic Secrets 3979 Once the handshake is complete, it is possible for either side to 3980 update its sending traffic keys using the KeyUpdate handshake message 3981 defined in Section 4.6.3. The next generation of traffic keys is 3982 computed by generating client_/server_application_traffic_secret_N+1 3983 from client_/server_application_traffic_secret_N as described in this 3984 section and then re-deriving the traffic keys as described in 3985 Section 7.3. 3987 The next-generation application_traffic_secret is computed as: 3989 application_traffic_secret_N+1 = 3990 HKDF-Expand-Label(application_traffic_secret_N, 3991 "traffic upd", "", Hash.length) 3993 Once client_/server_application_traffic_secret_N+1 and its associated 3994 traffic keys have been computed, implementations SHOULD delete 3995 client_/server_application_traffic_secret_N and its associated 3996 traffic keys. 3998 7.3. Traffic Key Calculation 4000 The traffic keying material is generated from the following input 4001 values: 4003 * A secret value 4005 * A purpose value indicating the specific value being generated 4007 * The length of the key being generated 4009 The traffic keying material is generated from an input traffic secret 4010 value using: 4012 [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) 4013 [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length) 4015 [sender] denotes the sending side. The value of Secret for each 4016 record type is shown in the table below. 4018 +===================+=======================================+ 4019 | Record Type | Secret | 4020 +===================+=======================================+ 4021 | 0-RTT Application | client_early_traffic_secret | 4022 +-------------------+---------------------------------------+ 4023 | Handshake | [sender]_handshake_traffic_secret | 4024 +-------------------+---------------------------------------+ 4025 | Application Data | [sender]_application_traffic_secret_N | 4026 +-------------------+---------------------------------------+ 4028 Table 3: Secrets for Traffic Keys 4030 All the traffic keying material is recomputed whenever the underlying 4031 Secret changes (e.g., when changing from the handshake to Application 4032 Data keys or upon a key update). 4034 7.4. (EC)DHE Shared Secret Calculation 4036 7.4.1. Finite Field Diffie-Hellman 4038 For finite field groups, a conventional Diffie-Hellman [DH76] 4039 computation is performed. The negotiated key (Z) is converted to a 4040 byte string by encoding in big-endian form and left-padded with zeros 4041 up to the size of the prime. This byte string is used as the shared 4042 secret in the key schedule as specified above. 4044 Note that this construction differs from previous versions of TLS 4045 which remove leading zeros. 4047 7.4.2. Elliptic Curve Diffie-Hellman 4049 For secp256r1, secp384r1 and secp521r1, ECDH calculations (including 4050 parameter and key generation as well as the shared secret 4051 calculation) are performed according to [IEEE1363] using the ECKAS- 4052 DH1 scheme with the identity map as the key derivation function 4053 (KDF), so that the shared secret is the x-coordinate of the ECDH 4054 shared secret elliptic curve point represented as an octet string. 4055 Note that this octet string ("Z" in IEEE 1363 terminology) as output 4056 by FE2OSP (the Field Element to Octet String Conversion Primitive) 4057 has constant length for any given field; leading zeros found in this 4058 octet string MUST NOT be truncated. 4060 (Note that this use of the identity KDF is a technicality. The 4061 complete picture is that ECDH is employed with a non-trivial KDF 4062 because TLS does not directly use this secret for anything other than 4063 for computing other secrets.) 4065 For X25519 and X448, the ECDH calculations are as follows: 4067 * The public key to put into the KeyShareEntry.key_exchange 4068 structure is the result of applying the ECDH scalar multiplication 4069 function to the secret key of appropriate length (into scalar 4070 input) and the standard public basepoint (into u-coordinate point 4071 input). 4073 * The ECDH shared secret is the result of applying the ECDH scalar 4074 multiplication function to the secret key (into scalar input) and 4075 the peer's public key (into u-coordinate point input). The output 4076 is used raw, with no processing. 4078 For these curves, implementations SHOULD use the approach specified 4079 in [RFC7748] to calculate the Diffie-Hellman shared secret. 4080 Implementations MUST check whether the computed Diffie-Hellman shared 4081 secret is the all-zero value and abort if so, as described in 4082 Section 6 of [RFC7748]. If implementors use an alternative 4083 implementation of these elliptic curves, they SHOULD perform the 4084 additional checks specified in Section 7 of [RFC7748]. 4086 7.5. Exporters 4088 [RFC5705] defines keying material exporters for TLS in terms of the 4089 TLS pseudorandom function (PRF). This document replaces the PRF with 4090 HKDF, thus requiring a new construction. The exporter interface 4091 remains the same. 4093 The exporter value is computed as: 4095 TLS-Exporter(label, context_value, key_length) = 4096 HKDF-Expand-Label(Derive-Secret(Secret, label, ""), 4097 "exporter", Hash(context_value), key_length) 4099 Where Secret is either the early_exporter_main_secret or the 4100 exporter_main_secret. Implementations MUST use the 4101 exporter_main_secret unless explicitly specified by the application. 4102 The early_exporter_main_secret is defined for use in settings where 4103 an exporter is needed for 0-RTT data. A separate interface for the 4104 early exporter is RECOMMENDED; this avoids the exporter user 4105 accidentally using an early exporter when a regular one is desired or 4106 vice versa. 4108 If no context is provided, the context_value is zero length. 4109 Consequently, providing no context computes the same value as 4110 providing an empty context. This is a change from previous versions 4111 of TLS where an empty context produced a different output than an 4112 absent context. As of this document's publication, no allocated 4113 exporter label is used both with and without a context. Future 4114 specifications MUST NOT define a use of exporters that permit both an 4115 empty context and no context with the same label. New uses of 4116 exporters SHOULD provide a context in all exporter computations, 4117 though the value could be empty. 4119 Requirements for the format of exporter labels are defined in 4120 Section 4 of [RFC5705]. 4122 8. 0-RTT and Anti-Replay 4124 As noted in Section 2.3 and Appendix E.5, TLS does not provide 4125 inherent replay protections for 0-RTT data. There are two potential 4126 threats to be concerned with: 4128 * Network attackers who mount a replay attack by simply duplicating 4129 a flight of 0-RTT data. 4131 * Network attackers who take advantage of client retry behavior to 4132 arrange for the server to receive multiple copies of an 4133 application message. This threat already exists to some extent 4134 because clients that value robustness respond to network errors by 4135 attempting to retry requests. However, 0-RTT adds an additional 4136 dimension for any server system which does not maintain globally 4137 consistent server state. Specifically, if a server system has 4138 multiple zones where tickets from zone A will not be accepted in 4139 zone B, then an attacker can duplicate a ClientHello and early 4140 data intended for A to both A and B. At A, the data will be 4141 accepted in 0-RTT, but at B the server will reject 0-RTT data and 4142 instead force a full handshake. If the attacker blocks the 4143 ServerHello from A, then the client will complete the handshake 4144 with B and probably retry the request, leading to duplication on 4145 the server system as a whole. 4147 The first class of attack can be prevented by sharing state to 4148 guarantee that the 0-RTT data is accepted at most once. Servers 4149 SHOULD provide that level of replay safety by implementing one of the 4150 methods described in this section or by equivalent means. It is 4151 understood, however, that due to operational concerns not all 4152 deployments will maintain state at that level. Therefore, in normal 4153 operation, clients will not know which, if any, of these mechanisms 4154 servers actually implement and hence MUST only send early data which 4155 they deem safe to be replayed. 4157 In addition to the direct effects of replays, there is a class of 4158 attacks where even operations normally considered idempotent could be 4159 exploited by a large number of replays (timing attacks, resource 4160 limit exhaustion and others, as described in Appendix E.5). Those 4161 can be mitigated by ensuring that every 0-RTT payload can be replayed 4162 only a limited number of times. The server MUST ensure that any 4163 instance of it (be it a machine, a thread, or any other entity within 4164 the relevant serving infrastructure) would accept 0-RTT for the same 4165 0-RTT handshake at most once; this limits the number of replays to 4166 the number of server instances in the deployment. Such a guarantee 4167 can be accomplished by locally recording data from recently received 4168 ClientHellos and rejecting repeats, or by any other method that 4169 provides the same or a stronger guarantee. The "at most once per 4170 server instance" guarantee is a minimum requirement; servers SHOULD 4171 limit 0-RTT replays further when feasible. 4173 The second class of attack cannot be prevented at the TLS layer and 4174 MUST be dealt with by any application. Note that any application 4175 whose clients implement any kind of retry behavior already needs to 4176 implement some sort of anti-replay defense. 4178 8.1. Single-Use Tickets 4180 The simplest form of anti-replay defense is for the server to only 4181 allow each session ticket to be used once. For instance, the server 4182 can maintain a database of all outstanding valid tickets, deleting 4183 each ticket from the database as it is used. If an unknown ticket is 4184 provided, the server would then fall back to a full handshake. 4186 If the tickets are not self-contained but rather are database keys, 4187 and the corresponding PSKs are deleted upon use, then connections 4188 established using PSKs enjoy forward secrecy. This improves security 4189 for all 0-RTT data and PSK usage when PSK is used without (EC)DHE. 4191 Because this mechanism requires sharing the session database between 4192 server nodes in environments with multiple distributed servers, it 4193 may be hard to achieve high rates of successful PSK 0-RTT connections 4194 when compared to self-encrypted tickets. Unlike session databases, 4195 session tickets can successfully do PSK-based session establishment 4196 even without consistent storage, though when 0-RTT is allowed they 4197 still require consistent storage for anti-replay of 0-RTT data, as 4198 detailed in the following section. 4200 8.2. Client Hello Recording 4202 An alternative form of anti-replay is to record a unique value 4203 derived from the ClientHello (generally either the random value or 4204 the PSK binder) and reject duplicates. Recording all ClientHellos 4205 causes state to grow without bound, but a server can instead record 4206 ClientHellos within a given time window and use the 4207 "obfuscated_ticket_age" to ensure that tickets aren't reused outside 4208 that window. 4210 In order to implement this, when a ClientHello is received, the 4211 server first verifies the PSK binder as described in Section 4.2.11. 4212 It then computes the expected_arrival_time as described in the next 4213 section and rejects 0-RTT if it is outside the recording window, 4214 falling back to the 1-RTT handshake. 4216 If the expected_arrival_time is in the window, then the server checks 4217 to see if it has recorded a matching ClientHello. If one is found, 4218 it either aborts the handshake with an "illegal_parameter" alert or 4219 accepts the PSK but rejects 0-RTT. If no matching ClientHello is 4220 found, then it accepts 0-RTT and then stores the ClientHello for as 4221 long as the expected_arrival_time is inside the window. Servers MAY 4222 also implement data stores with false positives, such as Bloom 4223 filters, in which case they MUST respond to apparent replay by 4224 rejecting 0-RTT but MUST NOT abort the handshake. 4226 The server MUST derive the storage key only from validated sections 4227 of the ClientHello. If the ClientHello contains multiple PSK 4228 identities, then an attacker can create multiple ClientHellos with 4229 different binder values for the less-preferred identity on the 4230 assumption that the server will not verify it (as recommended by 4231 Section 4.2.11). I.e., if the client sends PSKs A and B but the 4232 server prefers A, then the attacker can change the binder for B 4233 without affecting the binder for A. If the binder for B is part of 4234 the storage key, then this ClientHello will not appear as a 4235 duplicate, which will cause the ClientHello to be accepted, and may 4236 cause side effects such as replay cache pollution, although any 0-RTT 4237 data will not be decryptable because it will use different keys. If 4238 the validated binder or the ClientHello.random is used as the storage 4239 key, then this attack is not possible. 4241 Because this mechanism does not require storing all outstanding 4242 tickets, it may be easier to implement in distributed systems with 4243 high rates of resumption and 0-RTT, at the cost of potentially weaker 4244 anti-replay defense because of the difficulty of reliably storing and 4245 retrieving the received ClientHello messages. In many such systems, 4246 it is impractical to have globally consistent storage of all the 4247 received ClientHellos. In this case, the best anti-replay protection 4248 is provided by having a single storage zone be authoritative for a 4249 given ticket and refusing 0-RTT for that ticket in any other zone. 4250 This approach prevents simple replay by the attacker because only one 4251 zone will accept 0-RTT data. A weaker design is to implement 4252 separate storage for each zone but allow 0-RTT in any zone. This 4253 approach limits the number of replays to once per zone. Application 4254 message duplication of course remains possible with either design. 4256 When implementations are freshly started, they SHOULD reject 0-RTT as 4257 long as any portion of their recording window overlaps the startup 4258 time. Otherwise, they run the risk of accepting replays which were 4259 originally sent during that period. 4261 Note: If the client's clock is running much faster than the server's, 4262 then a ClientHello may be received that is outside the window in the 4263 future, in which case it might be accepted for 1-RTT, causing a 4264 client retry, and then acceptable later for 0-RTT. This is another 4265 variant of the second form of attack described in Section 8. 4267 8.3. Freshness Checks 4269 Because the ClientHello indicates the time at which the client sent 4270 it, it is possible to efficiently determine whether a ClientHello was 4271 likely sent reasonably recently and only accept 0-RTT for such a 4272 ClientHello, otherwise falling back to a 1-RTT handshake. This is 4273 necessary for the ClientHello storage mechanism described in 4274 Section 8.2 because otherwise the server needs to store an unlimited 4275 number of ClientHellos, and is a useful optimization for self- 4276 contained single-use tickets because it allows efficient rejection of 4277 ClientHellos which cannot be used for 0-RTT. 4279 In order to implement this mechanism, a server needs to store the 4280 time that the server generated the session ticket, offset by an 4281 estimate of the round-trip time between client and server. I.e., 4283 adjusted_creation_time = creation_time + estimated_RTT 4285 This value can be encoded in the ticket, thus avoiding the need to 4286 keep state for each outstanding ticket. The server can determine the 4287 client's view of the age of the ticket by subtracting the ticket's 4288 "ticket_age_add" value from the "obfuscated_ticket_age" parameter in 4289 the client's "pre_shared_key" extension. The server can determine 4290 the expected_arrival_time of the ClientHello as: 4292 expected_arrival_time = adjusted_creation_time + clients_ticket_age 4294 When a new ClientHello is received, the expected_arrival_time is then 4295 compared against the current server wall clock time and if they 4296 differ by more than a certain amount, 0-RTT is rejected, though the 4297 1-RTT handshake can be allowed to complete. 4299 There are several potential sources of error that might cause 4300 mismatches between the expected_arrival_time and the measured time. 4301 Variations in client and server clock rates are likely to be minimal, 4302 though potentially the absolute times may be off by large values. 4303 Network propagation delays are the most likely causes of a mismatch 4304 in legitimate values for elapsed time. Both the NewSessionTicket and 4305 ClientHello messages might be retransmitted and therefore delayed, 4306 which might be hidden by TCP. For clients on the Internet, this 4307 implies windows on the order of ten seconds to account for errors in 4308 clocks and variations in measurements; other deployment scenarios may 4309 have different needs. Clock skew distributions are not symmetric, so 4310 the optimal tradeoff may involve an asymmetric range of permissible 4311 mismatch values. 4313 Note that freshness checking alone is not sufficient to prevent 4314 replays because it does not detect them during the error window, 4315 which - depending on bandwidth and system capacity - could include 4316 billions of replays in real-world settings. In addition, this 4317 freshness checking is only done at the time the ClientHello is 4318 received, and not when subsequent early Application Data records are 4319 received. After early data is accepted, records may continue to be 4320 streamed to the server over a longer time period. 4322 9. Compliance Requirements 4324 9.1. Mandatory-to-Implement Cipher Suites 4326 In the absence of an application profile standard specifying 4327 otherwise: 4329 A TLS-compliant application MUST implement the TLS_AES_128_GCM_SHA256 4330 [GCM] cipher suite and SHOULD implement the TLS_AES_256_GCM_SHA384 4331 [GCM] and TLS_CHACHA20_POLY1305_SHA256 [RFC8439] cipher suites (see 4332 Appendix B.4). 4334 A TLS-compliant application MUST support digital signatures with 4335 rsa_pkcs1_sha256 (for certificates), rsa_pss_rsae_sha256 (for 4336 CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A 4337 TLS-compliant application MUST support key exchange with secp256r1 4338 (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748]. 4340 9.2. Mandatory-to-Implement Extensions 4342 In the absence of an application profile standard specifying 4343 otherwise, a TLS-compliant application MUST implement the following 4344 TLS extensions: 4346 * Supported Versions ("supported_versions"; Section 4.2.1) 4348 * Cookie ("cookie"; Section 4.2.2) 4350 * Signature Algorithms ("signature_algorithms"; Section 4.2.3) 4351 * Signature Algorithms Certificate ("signature_algorithms_cert"; 4352 Section 4.2.3) 4354 * Negotiated Groups ("supported_groups"; Section 4.2.7) 4356 * Key Share ("key_share"; Section 4.2.8) 4358 * Server Name Indication ("server_name"; Section 3 of [RFC6066]) 4360 All implementations MUST send and use these extensions when offering 4361 applicable features: 4363 * "supported_versions" is REQUIRED for all ClientHello, ServerHello, 4364 and HelloRetryRequest messages. 4366 * "signature_algorithms" is REQUIRED for certificate authentication. 4368 * "supported_groups" is REQUIRED for ClientHello messages using DHE 4369 or ECDHE key exchange. 4371 * "key_share" is REQUIRED for DHE or ECDHE key exchange. 4373 * "pre_shared_key" is REQUIRED for PSK key agreement. 4375 * "psk_key_exchange_modes" is REQUIRED for PSK key agreement. 4377 A client is considered to be attempting to negotiate using this 4378 specification if the ClientHello contains a "supported_versions" 4379 extension with 0x0304 contained in its body. Such a ClientHello 4380 message MUST meet the following requirements: 4382 * If not containing a "pre_shared_key" extension, it MUST contain 4383 both a "signature_algorithms" extension and a "supported_groups" 4384 extension. 4386 * If containing a "supported_groups" extension, it MUST also contain 4387 a "key_share" extension, and vice versa. An empty 4388 KeyShare.client_shares list is permitted. 4390 Servers receiving a ClientHello which does not conform to these 4391 requirements MUST abort the handshake with a "missing_extension" 4392 alert. 4394 Additionally, all implementations MUST support the use of the 4395 "server_name" extension with applications capable of using it. 4396 Servers MAY require clients to send a valid "server_name" extension. 4397 Servers requiring this extension SHOULD respond to a ClientHello 4398 lacking a "server_name" extension by terminating the connection with 4399 a "missing_extension" alert. 4401 9.3. Protocol Invariants 4403 This section describes invariants that TLS endpoints and middleboxes 4404 MUST follow. It also applies to earlier versions of TLS. 4406 TLS is designed to be securely and compatibly extensible. Newer 4407 clients or servers, when communicating with newer peers, should 4408 negotiate the most preferred common parameters. The TLS handshake 4409 provides downgrade protection: Middleboxes passing traffic between a 4410 newer client and newer server without terminating TLS should be 4411 unable to influence the handshake (see Appendix E.1). At the same 4412 time, deployments update at different rates, so a newer client or 4413 server MAY continue to support older parameters, which would allow it 4414 to interoperate with older endpoints. 4416 For this to work, implementations MUST correctly handle extensible 4417 fields: 4419 * A client sending a ClientHello MUST support all parameters 4420 advertised in it. Otherwise, the server may fail to interoperate 4421 by selecting one of those parameters. 4423 * A server receiving a ClientHello MUST correctly ignore all 4424 unrecognized cipher suites, extensions, and other parameters. 4425 Otherwise, it may fail to interoperate with newer clients. In TLS 4426 1.3, a client receiving a CertificateRequest or NewSessionTicket 4427 MUST also ignore all unrecognized extensions. 4429 * A middlebox which terminates a TLS connection MUST behave as a 4430 compliant TLS server (to the original client), including having a 4431 certificate which the client is willing to accept, and also as a 4432 compliant TLS client (to the original server), including verifying 4433 the original server's certificate. In particular, it MUST 4434 generate its own ClientHello containing only parameters it 4435 understands, and it MUST generate a fresh ServerHello random 4436 value, rather than forwarding the endpoint's value. 4438 Note that TLS's protocol requirements and security analysis only 4439 apply to the two connections separately. Safely deploying a TLS 4440 terminator requires additional security considerations which are 4441 beyond the scope of this document. 4443 * A middlebox which forwards ClientHello parameters it does not 4444 understand MUST NOT process any messages beyond that ClientHello. 4445 It MUST forward all subsequent traffic unmodified. Otherwise, it 4446 may fail to interoperate with newer clients and servers. 4448 Forwarded ClientHellos may contain advertisements for features not 4449 supported by the middlebox, so the response may include future TLS 4450 additions the middlebox does not recognize. These additions MAY 4451 change any message beyond the ClientHello arbitrarily. In 4452 particular, the values sent in the ServerHello might change, the 4453 ServerHello format might change, and the TLSCiphertext format 4454 might change. 4456 The design of TLS 1.3 was constrained by widely deployed non- 4457 compliant TLS middleboxes (see Appendix D.4); however, it does not 4458 relax the invariants. Those middleboxes continue to be non- 4459 compliant. 4461 10. Security Considerations 4463 Security issues are discussed throughout this memo, especially in 4464 Appendix C, Appendix D, and Appendix E. 4466 11. IANA Considerations 4468 [[OPEN ISSUE: Should we remove this? I am reluctant to create a 4469 situation where one needs to read 8446 to process this document.]] 4471 This document uses several registries that were originally created in 4472 [RFC4346] and updated in [RFC8447]. IANA has updated these to 4473 reference this document. The registries and their allocation 4474 policies are below: 4476 * TLS Cipher Suites registry: values with the first byte in the 4477 range 0-254 (decimal) are assigned via Specification Required 4478 [RFC8126]. Values with the first byte 255 (decimal) are reserved 4479 for Private Use [RFC8126]. 4481 IANA has added the cipher suites listed in Appendix B.4 to the 4482 registry. The "Value" and "Description" columns are taken from 4483 the table. The "DTLS-OK" and "Recommended" columns are both 4484 marked as "Y" for each new cipher suite. 4486 * TLS ContentType registry: Future values are allocated via 4487 Standards Action [RFC8126]. 4489 * TLS Alerts registry: Future values are allocated via Standards 4490 Action [RFC8126]. IANA has populated this registry with the 4491 values from Appendix B.2. The "DTLS-OK" column is marked as "Y" 4492 for all such values. Values marked as "_RESERVED" have comments 4493 describing their previous usage. 4495 * TLS HandshakeType registry: Future values are allocated via 4496 Standards Action [RFC8126]. IANA has updated this registry to 4497 rename item 4 from "NewSessionTicket" to "new_session_ticket" and 4498 populated this registry with the values from Appendix B.3. The 4499 "DTLS-OK" column is marked as "Y" for all such values. Values 4500 marked "_RESERVED" have comments describing their previous or 4501 temporary usage. 4503 This document also uses the TLS ExtensionType Values registry 4504 originally created in [RFC4366]. IANA has updated it to reference 4505 this document. Changes to the registry follow: 4507 * IANA has updated the registration policy as follows: 4509 Values with the first byte in the range 0-254 (decimal) are 4510 assigned via Specification Required [RFC8126]. Values with the 4511 first byte 255 (decimal) are reserved for Private Use [RFC8126]. 4513 * IANA has updated this registry to include the "key_share", 4514 "pre_shared_key", "psk_key_exchange_modes", "early_data", 4515 "cookie", "supported_versions", "certificate_authorities", 4516 "oid_filters", "post_handshake_auth", and 4517 "signature_algorithms_cert" extensions with the values defined in 4518 this document and the "Recommended" value of "Y". 4520 * IANA has updated this registry to include a "TLS 1.3" column which 4521 lists the messages in which the extension may appear. This column 4522 has been initially populated from the table in Section 4.2, with 4523 any extension not listed there marked as "-" to indicate that it 4524 is not used by TLS 1.3. 4526 This document updates an entry in the TLS Certificate Types registry 4527 originally created in [RFC6091] and updated in [RFC8447]. IANA has 4528 updated the entry for value 1 to have the name "OpenPGP_RESERVED", 4529 "Recommended" value "N", and comment "Used in TLS versions prior to 4530 1.3." IANA has updated the entry for value 0 to have the name 4531 "X509", "Recommended" value "Y", and comment "Was X.509 before TLS 4532 1.3". 4534 This document updates an entry in the TLS Certificate Status Types 4535 registry originally created in [RFC6961]. IANA has updated the entry 4536 for value 2 to have the name "ocsp_multi_RESERVED" and comment "Used 4537 in TLS versions prior to 1.3". 4539 This document updates two entries in the TLS Supported Groups 4540 registry (created under a different name by [RFC4492]; now maintained 4541 by [RFC8422]) and updated by [RFC7919] and [RFC8447]. The entries 4542 for values 29 and 30 (x25519 and x448) have been updated to also 4543 refer to this document. 4545 In addition, this document defines two new registries that are 4546 maintained by IANA: 4548 * TLS SignatureScheme registry: Values with the first byte in the 4549 range 0-253 (decimal) are assigned via Specification Required 4550 [RFC8126]. Values with the first byte 254 or 255 (decimal) are 4551 reserved for Private Use [RFC8126]. Values with the first byte in 4552 the range 0-6 or with the second byte in the range 0-3 that are 4553 not currently allocated are reserved for backward compatibility. 4554 This registry has a "Recommended" column. The registry has been 4555 initially populated with the values described in Section 4.2.3. 4556 The following values are marked as "Recommended": 4557 ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, 4558 rsa_pss_rsae_sha256, rsa_pss_rsae_sha384, rsa_pss_rsae_sha512, 4559 rsa_pss_pss_sha256, rsa_pss_pss_sha384, rsa_pss_pss_sha512, and 4560 ed25519. The "Recommended" column is assigned a value of "N" 4561 unless explicitly requested, and adding a value with a 4562 "Recommended" value of "Y" requires Standards Action [RFC8126]. 4563 IESG Approval is REQUIRED for a Y->N transition. 4565 * TLS PskKeyExchangeMode registry: Values in the range 0-253 4566 (decimal) are assigned via Specification Required [RFC8126]. The 4567 values 254 and 255 (decimal) are reserved for Private Use 4568 [RFC8126]. This registry has a "Recommended" column. The 4569 registry has been initially populated with psk_ke (0) and 4570 psk_dhe_ke (1). Both are marked as "Recommended". The 4571 "Recommended" column is assigned a value of "N" unless explicitly 4572 requested, and adding a value with a "Recommended" value of "Y" 4573 requires Standards Action [RFC8126]. IESG Approval is REQUIRED 4574 for a Y->N transition. 4576 12. References 4578 12.1. Normative References 4580 [DH76] Diffie, W. and M. Hellman, "New directions in 4581 cryptography", DOI 10.1109/tit.1976.1055638, IEEE 4582 Transactions on Information Theory Vol. 22, pp. 644-654, 4583 November 1976, . 4585 [ECDSA] American National Standards Institute, "Public Key 4586 Cryptography for the Financial Services Industry: The 4587 Elliptic Curve Digital Signature Algorithm (ECDSA)", 4588 ANSI ANS X9.62-2005, November 2005. 4590 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 4591 Operation: Galois/Counter Mode (GCM) and GMAC", 4592 NIST Special Publication 800-38D, November 2007. 4594 [IEEE1363] "IEEE Standard Specifications for Public-Key 4595 Cryptography", DOI 10.1109/ieeestd.2000.92292, 4596 IEEE standard, n.d., 4597 . 4599 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4600 Hashing for Message Authentication", RFC 2104, 4601 DOI 10.17487/RFC2104, February 1997, 4602 . 4604 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4605 Requirement Levels", BCP 14, RFC 2119, 4606 DOI 10.17487/RFC2119, March 1997, 4607 . 4609 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 4610 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 4611 . 4613 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4614 Housley, R., and W. Polk, "Internet X.509 Public Key 4615 Infrastructure Certificate and Certificate Revocation List 4616 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4617 . 4619 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 4620 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 4621 March 2010, . 4623 [RFC5756] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 4624 "Updates for RSAES-OAEP and RSASSA-PSS Algorithm 4625 Parameters", RFC 5756, DOI 10.17487/RFC5756, January 2010, 4626 . 4628 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 4629 Key Derivation Function (HKDF)", RFC 5869, 4630 DOI 10.17487/RFC5869, May 2010, 4631 . 4633 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4634 Extensions: Extension Definitions", RFC 6066, 4635 DOI 10.17487/RFC6066, January 2011, 4636 . 4638 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4639 Transport Layer Security (TLS)", RFC 6655, 4640 DOI 10.17487/RFC6655, July 2012, 4641 . 4643 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 4644 Galperin, S., and C. Adams, "X.509 Internet Public Key 4645 Infrastructure Online Certificate Status Protocol - OCSP", 4646 RFC 6960, DOI 10.17487/RFC6960, June 2013, 4647 . 4649 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 4650 Multiple Certificate Status Request Extension", RFC 6961, 4651 DOI 10.17487/RFC6961, June 2013, 4652 . 4654 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 4655 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 4656 . 4658 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4659 Algorithm (DSA) and Elliptic Curve Digital Signature 4660 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4661 2013, . 4663 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 4664 "Transport Layer Security (TLS) Application-Layer Protocol 4665 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 4666 July 2014, . 4668 [RFC7507] Moeller, B. and A. Langley, "TLS Fallback Signaling Cipher 4669 Suite Value (SCSV) for Preventing Protocol Downgrade 4670 Attacks", RFC 7507, DOI 10.17487/RFC7507, April 2015, 4671 . 4673 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 4674 for Security", RFC 7748, DOI 10.17487/RFC7748, January 4675 2016, . 4677 [RFC7919] Gillmor, D., "Negotiated Finite Field Diffie-Hellman 4678 Ephemeral Parameters for Transport Layer Security (TLS)", 4679 RFC 7919, DOI 10.17487/RFC7919, August 2016, 4680 . 4682 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 4683 "PKCS #1: RSA Cryptography Specifications Version 2.2", 4684 RFC 8017, DOI 10.17487/RFC8017, November 2016, 4685 . 4687 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 4688 Signature Algorithm (EdDSA)", RFC 8032, 4689 DOI 10.17487/RFC8032, January 2017, 4690 . 4692 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4693 Writing an IANA Considerations Section in RFCs", BCP 26, 4694 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4695 . 4697 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4698 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4699 May 2017, . 4701 [RFC8439] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 4702 Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018, 4703 . 4705 [SHS] Dang, Q., "Secure Hash Standard", 4706 DOI 10.6028/nist.fips.180-4, National Institute of 4707 Standards and Technology report, July 2015, 4708 . 4710 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 4711 Specification of Basic Encoding Rules (BER), Canonical 4712 Encoding Rules (CER) and Distinguished Encoding Rules 4713 (DER)", ISO/IEC 8825-1:2002, November 2015. 4715 12.2. Informative References 4717 [AEAD-LIMITS] 4718 Luykx, A. and K. Paterson, "Limits on Authenticated 4719 Encryption Use in TLS", August 2017, 4720 . 4722 [BBFGKZ16] Bhargavan, K., Brzuska, C., Fournet, C., Green, M., 4723 Kohlweiss, M., and S. Zanella-Beguelin, "Downgrade 4724 Resilience in Key-Exchange Protocols", 4725 DOI 10.1109/sp.2016.37, 2016 IEEE Symposium on Security 4726 and Privacy (SP), May 2016, 4727 . 4729 [BBK17] Bhargavan, K., Blanchet, B., and N. Kobeissi, "Verified 4730 Models and Reference Implementations for the TLS 1.3 4731 Standard Candidate", DOI 10.1109/sp.2017.26, 2017 IEEE 4732 Symposium on Security and Privacy (SP), May 2017, 4733 . 4735 [BDFKPPRSZZ16] 4736 Bhargavan, K., Delignat-Lavaud, A., Fournet, C., 4737 Kohlweiss, M., Pan, J., Protzenko, J., Rastogi, A., Swamy, 4738 N., Zanella-Beguelin, S., and J. Zinzindohoue, 4739 "Implementing and Proving the TLS 1.3 Record Layer", 4740 Proceedings of IEEE Symposium on Security and Privacy (San 4741 Jose) 2017 , December 2016, 4742 . 4744 [Ben17a] Benjamin, D., "Presentation before the TLS WG at IETF 4745 100", 2017, 4746 . 4749 [Ben17b] Benjamin, D., "Additional TLS 1.3 results from Chrome", 4750 2017, . 4753 [Blei98] Bleichenbacher, D., "Chosen Ciphertext Attacks against 4754 Protocols Based on RSA Encryption Standard PKCS #1", 4755 Proceedings of CRYPTO '98 , 1998. 4757 [BMMRT15] Badertscher, C., Matt, C., Maurer, U., Rogaway, P., and B. 4758 Tackmann, "Augmented Secure Channels and the Goal of the 4759 TLS 1.3 Record Layer", ProvSec 2015 , September 2015, 4760 . 4762 [BT16] Bellare, M. and B. Tackmann, "The Multi-User Security of 4763 Authenticated Encryption: AES-GCM in TLS 1.3", Proceedings 4764 of CRYPTO 2016 , July 2016, 4765 . 4767 [CCG16] Cohn-Gordon, K., Cremers, C., and L. Garratt, "On Post- 4768 compromise Security", DOI 10.1109/csf.2016.19, 2016 IEEE 4769 29th Computer Security Foundations Symposium (CSF), June 4770 2016, . 4772 [CHECKOWAY] 4773 Checkoway, S., Maskiewicz, J., Garman, C., Fried, J., 4774 Cohney, S., Green, M., Heninger, N., Weinmann, R., 4775 Rescorla, E., and H. Shacham, "A Systematic Analysis of 4776 the Juniper Dual EC Incident", 4777 DOI 10.1145/2976749.2978395, Proceedings of the 2016 ACM 4778 SIGSAC Conference on Computer and Communications Security, 4779 October 2016, . 4781 [CHHSV17] Cremers, C., Horvat, M., Hoyland, J., van der Merwe, T., 4782 and S. Scott, "Awkward Handshake: Possible mismatch of 4783 client/server view on client authentication in post- 4784 handshake mode in Revision 18", message to the TLS mailing 4785 list , February 2017, . 4788 [CHSV16] Cremers, C., Horvat, M., Scott, S., and T. van der Merwe, 4789 "Automated Analysis and Verification of TLS 1.3: 0-RTT, 4790 Resumption and Delayed Authentication", 4791 DOI 10.1109/sp.2016.35, 2016 IEEE Symposium on Security 4792 and Privacy (SP), May 2016, 4793 . 4795 [CK01] Canetti, R. and H. Krawczyk, "Analysis of Key-Exchange 4796 Protocols and Their Use for Building Secure Channels", 4797 DOI 10.1007/3-540-44987-6_28, Lecture Notes in Computer 4798 Science pp. 453-474, 2001, 4799 . 4801 [CLINIC] Miller, B., Huang, L., Joseph, A., and J. Tygar, "I Know 4802 Why You Went to the Clinic: Risks and Realization of HTTPS 4803 Traffic Analysis", DOI 10.1007/978-3-319-08506-7_8, 4804 Privacy Enhancing Technologies pp. 143-163, 2014, 4805 . 4807 [DFGS15] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 4808 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 4809 Pre-shared Key Handshake Protocol", Proceedings of ACM CCS 4810 2015 , October 2016, . 4812 [DFGS16] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 4813 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 4814 Pre-shared Key Handshake Protocol", TRON 2016 , February 4815 2016, . 4817 [DOW92] Diffie, W., Van Oorschot, P., and M. Wiener, 4818 "Authentication and authenticated key exchanges", 4819 DOI 10.1007/bf00124891, Designs, Codes and 4820 Cryptography Vol. 2, pp. 107-125, June 1992, 4821 . 4823 [DSS] "Digital Signature Standard (DSS)", 4824 DOI 10.6028/nist.fips.186-4, National Institute of 4825 Standards and Technology report, July 2013, 4826 . 4828 [FG17] Fischlin, M. and F. Guenther, "Replay Attacks on Zero 4829 Round-Trip Time: The Case of the TLS 1.3 Handshake 4830 Candidates", Proceedings of Euro S&P 2017 , 2017, 4831 . 4833 [FGSW16] Fischlin, M., Guenther, F., Schmidt, B., and B. Warinschi, 4834 "Key Confirmation in Key Exchange: A Formal Treatment and 4835 Implications for TLS 1.3", Proceedings of IEEE Symposium 4836 on Security and Privacy (Oakland) 2016 , 2016, 4837 . 4839 [FW15] Weimer, F., "Factoring RSA Keys With TLS Perfect Forward 4840 Secrecy", September 2015. 4842 [HCJC16] Husák, M., Čermák, M., Jirsík, T., and P. Čeleda, "HTTPS 4843 traffic analysis and client identification using passive 4844 SSL/TLS fingerprinting", DOI 10.1186/s13635-016-0030-7, 4845 EURASIP Journal on Information Security Vol. 2016, 4846 February 2016, 4847 . 4849 [HGFS15] Hlauschek, C., Gruber, M., Fankhauser, F., and C. Schanes, 4850 "Prying Open Pandora's Box: KCI Attacks against TLS", 4851 Proceedings of USENIX Workshop on Offensive Technologies , 4852 2015. 4854 [JSS15] Jager, T., Schwenk, J., and J. Somorovsky, "On the 4855 Security of TLS 1.3 and QUIC Against Weaknesses in PKCS#1 4856 v1.5 Encryption", DOI 10.1145/2810103.2813657, Proceedings 4857 of the 22nd ACM SIGSAC Conference on Computer and 4858 Communications Security - CCS '15, 2015, 4859 . 4861 [KEYAGREEMENT] 4862 Barker, E., Chen, L., Roginsky, A., and M. Smid, 4863 "Recommendation for Pair-Wise Key Establishment Schemes 4864 Using Discrete Logarithm Cryptography", 4865 DOI 10.6028/nist.sp.800-56ar2, National Institute of 4866 Standards and Technology report, May 2013, 4867 . 4869 [Kraw10] Krawczyk, H., "Cryptographic Extraction and Key 4870 Derivation: The HKDF Scheme", Proceedings of CRYPTO 2010 , 4871 2010, . 4873 [Kraw16] Krawczyk, H., "A Unilateral-to-Mutual Authentication 4874 Compiler for Key Exchange (with Applications to Client 4875 Authentication in TLS 1.3", Proceedings of ACM CCS 2016 , 4876 October 2016, . 4878 [KW16] Krawczyk, H. and H. Wee, "The OPTLS Protocol and TLS 1.3", 4879 Proceedings of Euro S&P 2016 , 2016, 4880 . 4882 [LXZFH16] Li, X., Xu, J., Zhang, Z., Feng, D., and H. Hu, "Multiple 4883 Handshakes Security of TLS 1.3 Candidates", 4884 DOI 10.1109/sp.2016.36, 2016 IEEE Symposium on Security 4885 and Privacy (SP), May 2016, 4886 . 4888 [Mac17] MacCarthaigh, C., "Security Review of TLS1.3 0-RTT", March 4889 2017, . 4891 [PS18] Patton, C. and T. Shrimpton, "Partially specified 4892 channels: The TLS 1.3 record layer without elision", 2018, 4893 . 4895 [PSK-FINISHED] 4896 Cremers, C., Horvat, M., van der Merwe, T., and S. Scott, 4897 "Revision 10: possible attack if client authentication is 4898 allowed during PSK", message to the TLS mailing list, , 4899 2015, . 4902 [REKEY] Abdalla, M. and M. Bellare, "Increasing the Lifetime of a 4903 Key: A Comparative Analysis of the Security of Re-keying 4904 Techniques", DOI 10.1007/3-540-44448-3_42, Advances in 4905 Cryptology - ASIACRYPT 2000 pp. 546-559, 2000, 4906 . 4908 [Res17a] Rescorla, E., "Preliminary data on Firefox TLS 1.3 4909 Middlebox experiment", message to the TLS mailing list , 4910 2017, . 4913 [Res17b] Rescorla, E., "More compatibility measurement results", 4914 message to the TLS mailing list , December 2017, 4915 . 4918 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 4919 Text on Security Considerations", BCP 72, RFC 3552, 4920 DOI 10.17487/RFC3552, July 2003, 4921 . 4923 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 4924 "Randomness Requirements for Security", BCP 106, RFC 4086, 4925 DOI 10.17487/RFC4086, June 2005, 4926 . 4928 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 4929 (TLS) Protocol Version 1.1", RFC 4346, 4930 DOI 10.17487/RFC4346, April 2006, 4931 . 4933 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 4934 and T. Wright, "Transport Layer Security (TLS) 4935 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006, 4936 . 4938 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4939 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4940 for Transport Layer Security (TLS)", RFC 4492, 4941 DOI 10.17487/RFC4492, May 2006, 4942 . 4944 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 4945 "Transport Layer Security (TLS) Session Resumption without 4946 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 4947 January 2008, . 4949 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4950 (TLS) Protocol Version 1.2", RFC 5246, 4951 DOI 10.17487/RFC5246, August 2008, 4952 . 4954 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 4955 Security (DTLS) Extension to Establish Keys for the Secure 4956 Real-time Transport Protocol (SRTP)", RFC 5764, 4957 DOI 10.17487/RFC5764, May 2010, 4958 . 4960 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 4961 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010, 4962 . 4964 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys 4965 for Transport Layer Security (TLS) Authentication", 4966 RFC 6091, DOI 10.17487/RFC6091, February 2011, 4967 . 4969 [RFC6101] Freier, A., Karlton, P., and P. Kocher, "The Secure 4970 Sockets Layer (SSL) Protocol Version 3.0", RFC 6101, 4971 DOI 10.17487/RFC6101, August 2011, 4972 . 4974 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 4975 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176, March 4976 2011, . 4978 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4979 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4980 January 2012, . 4982 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 4983 Layer Security (TLS) and Datagram Transport Layer Security 4984 (DTLS) Heartbeat Extension", RFC 6520, 4985 DOI 10.17487/RFC6520, February 2012, 4986 . 4988 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 4989 Protocol (HTTP/1.1): Message Syntax and Routing", 4990 RFC 7230, DOI 10.17487/RFC7230, June 2014, 4991 . 4993 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4994 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4995 Transport Layer Security (TLS) and Datagram Transport 4996 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4997 June 2014, . 4999 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 5000 DOI 10.17487/RFC7465, February 2015, 5001 . 5003 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 5004 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 5005 DOI 10.17487/RFC7568, June 2015, 5006 . 5008 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 5009 Langley, A., and M. Ray, "Transport Layer Security (TLS) 5010 Session Hash and Extended Master Secret Extension", 5011 RFC 7627, DOI 10.17487/RFC7627, September 2015, 5012 . 5014 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello 5015 Padding Extension", RFC 7685, DOI 10.17487/RFC7685, 5016 October 2015, . 5018 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 5019 (TLS) Cached Information Extension", RFC 7924, 5020 DOI 10.17487/RFC7924, July 2016, 5021 . 5023 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 5024 Better Connectivity Using Concurrency", RFC 8305, 5025 DOI 10.17487/RFC8305, December 2017, 5026 . 5028 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 5029 Curve Cryptography (ECC) Cipher Suites for Transport Layer 5030 Security (TLS) Versions 1.2 and Earlier", RFC 8422, 5031 DOI 10.17487/RFC8422, August 2018, 5032 . 5034 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 5035 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 5036 . 5038 [RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS 5039 and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018, 5040 . 5042 [RFC8448] Thomson, M., "Example Handshake Traces for TLS 1.3", 5043 RFC 8448, DOI 10.17487/RFC8448, January 2019, 5044 . 5046 [RFC8449] Thomson, M., "Record Size Limit Extension for TLS", 5047 RFC 8449, DOI 10.17487/RFC8449, August 2018, 5048 . 5050 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A method for 5051 obtaining digital signatures and public-key 5052 cryptosystems", DOI 10.1145/359340.359342, Communications 5053 of the ACM Vol. 21, pp. 120-126, February 1978, 5054 . 5056 [SIGMA] Krawczyk, H., "SIGMA: The 'SIGn-and-MAc' Approach to 5057 Authenticated Diffie-Hellman and Its Use in the IKE 5058 Protocols", DOI 10.1007/978-3-540-45146-4_24, Advances in 5059 Cryptology - CRYPTO 2003 pp. 400-425, 2003, 5060 . 5062 [SLOTH] Bhargavan, K. and G. Leurent, "Transcript Collision 5063 Attacks: Breaking Authentication in TLS, IKE, and SSH", 5064 DOI 10.14722/ndss.2016.23418, Proceedings 2016 Network and 5065 Distributed System Security Symposium, 2016, 5066 . 5068 [SSL2] Hickman, K., "The SSL Protocol", 9 February 1995. 5070 [TIMING] Boneh, D. and D. Brumley, "Remote Timing Attacks Are 5071 Practical", USENIX Security Symposium, 2003. 5073 [X501] "Information Technology - Open Systems Interconnection - 5074 The Directory: Models", ITU-T X.501, 1993. 5076 Appendix A. State Machine 5078 This appendix provides a summary of the legal state transitions for 5079 the client and server handshakes. State names (in all capitals, 5080 e.g., START) have no formal meaning but are provided for ease of 5081 comprehension. Actions which are taken only in certain circumstances 5082 are indicated in []. The notation "K_{send,recv} = foo" means "set 5083 the send/recv key to the given key". 5085 A.1. Client 5086 START <----+ 5087 Send ClientHello | | Recv HelloRetryRequest 5088 [K_send = early data] | | 5089 v | 5090 / WAIT_SH ----+ 5091 | | Recv ServerHello 5092 | | K_recv = handshake 5093 Can | V 5094 send | WAIT_EE 5095 early | | Recv EncryptedExtensions 5096 data | +--------+--------+ 5097 | Using | | Using certificate 5098 | PSK | v 5099 | | WAIT_CERT_CR 5100 | | Recv | | Recv CertificateRequest 5101 | | Certificate | v 5102 | | | WAIT_CERT 5103 | | | | Recv Certificate 5104 | | v v 5105 | | WAIT_CV 5106 | | | Recv CertificateVerify 5107 | +> WAIT_FINISHED <+ 5108 | | Recv Finished 5109 \ | [Send EndOfEarlyData] 5110 | K_send = handshake 5111 | [Send Certificate [+ CertificateVerify]] 5112 Can send | Send Finished 5113 app data --> | K_send = K_recv = application 5114 after here v 5115 CONNECTED 5117 Note that with the transitions as shown above, clients may send 5118 alerts that derive from post-ServerHello messages in the clear or 5119 with the early data keys. If clients need to send such alerts, they 5120 SHOULD first rekey to the handshake keys if possible. 5122 A.2. Server 5123 START <-----+ 5124 Recv ClientHello | | Send HelloRetryRequest 5125 v | 5126 RECVD_CH ----+ 5127 | Select parameters 5128 v 5129 NEGOTIATED 5130 | Send ServerHello 5131 | K_send = handshake 5132 | Send EncryptedExtensions 5133 | [Send CertificateRequest] 5134 Can send | [Send Certificate + CertificateVerify] 5135 app data | Send Finished 5136 after --> | K_send = application 5137 here +--------+--------+ 5138 No 0-RTT | | 0-RTT 5139 | | 5140 K_recv = handshake | | K_recv = early data 5141 [Skip decrypt errors] | +------> WAIT_EOED -+ 5142 | | Recv | | Recv EndOfEarlyData 5143 | | early data | | K_recv = handshake 5144 | +------------+ | 5145 | | 5146 +> WAIT_FLIGHT2 <--------+ 5147 | 5148 +--------+--------+ 5149 No auth | | Client auth 5150 | | 5151 | v 5152 | WAIT_CERT 5153 | Recv | | Recv Certificate 5154 | empty | v 5155 | Certificate | WAIT_CV 5156 | | | Recv 5157 | v | CertificateVerify 5158 +-> WAIT_FINISHED <---+ 5159 | Recv Finished 5160 | K_recv = application 5161 v 5162 CONNECTED 5164 Appendix B. Protocol Data Structures and Constant Values 5166 This appendix provides the normative protocol types and the 5167 definitions for constants. Values listed as "_RESERVED" were used in 5168 previous versions of TLS and are listed here for completeness. TLS 5169 1.3 implementations MUST NOT send them but might receive them from 5170 older TLS implementations. 5172 B.1. Record Layer 5174 enum { 5175 invalid(0), 5176 change_cipher_spec(20), 5177 alert(21), 5178 handshake(22), 5179 application_data(23), 5180 (255) 5181 } ContentType; 5183 struct { 5184 ContentType type; 5185 ProtocolVersion legacy_record_version; 5186 uint16 length; 5187 opaque fragment[TLSPlaintext.length]; 5188 } TLSPlaintext; 5190 struct { 5191 opaque content[TLSPlaintext.length]; 5192 ContentType type; 5193 uint8 zeros[length_of_padding]; 5194 } TLSInnerPlaintext; 5196 struct { 5197 ContentType opaque_type = application_data; /* 23 */ 5198 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */ 5199 uint16 length; 5200 opaque encrypted_record[TLSCiphertext.length]; 5201 } TLSCiphertext; 5203 B.2. Alert Messages 5204 enum { warning(1), fatal(2), (255) } AlertLevel; 5206 enum { 5207 close_notify(0), 5208 unexpected_message(10), 5209 bad_record_mac(20), 5210 decryption_failed_RESERVED(21), 5211 record_overflow(22), 5212 decompression_failure_RESERVED(30), 5213 handshake_failure(40), 5214 no_certificate_RESERVED(41), 5215 bad_certificate(42), 5216 unsupported_certificate(43), 5217 certificate_revoked(44), 5218 certificate_expired(45), 5219 certificate_unknown(46), 5220 illegal_parameter(47), 5221 unknown_ca(48), 5222 access_denied(49), 5223 decode_error(50), 5224 decrypt_error(51), 5225 export_restriction_RESERVED(60), 5226 protocol_version(70), 5227 insufficient_security(71), 5228 internal_error(80), 5229 inappropriate_fallback(86), 5230 user_canceled(90), 5231 no_renegotiation_RESERVED(100), 5232 missing_extension(109), 5233 unsupported_extension(110), 5234 certificate_unobtainable_RESERVED(111), 5235 unrecognized_name(112), 5236 bad_certificate_status_response(113), 5237 bad_certificate_hash_value_RESERVED(114), 5238 unknown_psk_identity(115), 5239 certificate_required(116), 5240 no_application_protocol(120), 5241 (255) 5242 } AlertDescription; 5244 struct { 5245 AlertLevel level; 5246 AlertDescription description; 5247 } Alert; 5249 B.3. Handshake Protocol 5250 enum { 5251 hello_request_RESERVED(0), 5252 client_hello(1), 5253 server_hello(2), 5254 hello_verify_request_RESERVED(3), 5255 new_session_ticket(4), 5256 end_of_early_data(5), 5257 hello_retry_request_RESERVED(6), 5258 encrypted_extensions(8), 5259 certificate(11), 5260 server_key_exchange_RESERVED(12), 5261 certificate_request(13), 5262 server_hello_done_RESERVED(14), 5263 certificate_verify(15), 5264 client_key_exchange_RESERVED(16), 5265 finished(20), 5266 certificate_url_RESERVED(21), 5267 certificate_status_RESERVED(22), 5268 supplemental_data_RESERVED(23), 5269 key_update(24), 5270 message_hash(254), 5271 (255) 5272 } HandshakeType; 5274 struct { 5275 HandshakeType msg_type; /* handshake type */ 5276 uint24 length; /* remaining bytes in message */ 5277 select (Handshake.msg_type) { 5278 case client_hello: ClientHello; 5279 case server_hello: ServerHello; 5280 case end_of_early_data: EndOfEarlyData; 5281 case encrypted_extensions: EncryptedExtensions; 5282 case certificate_request: CertificateRequest; 5283 case certificate: Certificate; 5284 case certificate_verify: CertificateVerify; 5285 case finished: Finished; 5286 case new_session_ticket: NewSessionTicket; 5287 case key_update: KeyUpdate; 5288 }; 5289 } Handshake; 5291 B.3.1. Key Exchange Messages 5292 uint16 ProtocolVersion; 5293 opaque Random[32]; 5295 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 5297 struct { 5298 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 5299 Random random; 5300 opaque legacy_session_id<0..32>; 5301 CipherSuite cipher_suites<2..2^16-2>; 5302 opaque legacy_compression_methods<1..2^8-1>; 5303 Extension extensions<8..2^16-1>; 5304 } ClientHello; 5306 struct { 5307 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 5308 Random random; 5309 opaque legacy_session_id_echo<0..32>; 5310 CipherSuite cipher_suite; 5311 uint8 legacy_compression_method = 0; 5312 Extension extensions<6..2^16-1>; 5313 } ServerHello; 5315 struct { 5316 ExtensionType extension_type; 5317 opaque extension_data<0..2^16-1>; 5318 } Extension; 5320 enum { 5321 server_name(0), /* RFC 6066 */ 5322 max_fragment_length(1), /* RFC 6066 */ 5323 status_request(5), /* RFC 6066 */ 5324 supported_groups(10), /* RFC 8422, 7919 */ 5325 signature_algorithms(13), /* RFC 8446 */ 5326 use_srtp(14), /* RFC 5764 */ 5327 heartbeat(15), /* RFC 6520 */ 5328 application_layer_protocol_negotiation(16), /* RFC 7301 */ 5329 signed_certificate_timestamp(18), /* RFC 6962 */ 5330 client_certificate_type(19), /* RFC 7250 */ 5331 server_certificate_type(20), /* RFC 7250 */ 5332 padding(21), /* RFC 7685 */ 5333 pre_shared_key(41), /* RFC 8446 */ 5334 early_data(42), /* RFC 8446 */ 5335 supported_versions(43), /* RFC 8446 */ 5336 cookie(44), /* RFC 8446 */ 5337 psk_key_exchange_modes(45), /* RFC 8446 */ 5338 certificate_authorities(47), /* RFC 8446 */ 5339 oid_filters(48), /* RFC 8446 */ 5340 post_handshake_auth(49), /* RFC 8446 */ 5341 signature_algorithms_cert(50), /* RFC 8446 */ 5342 key_share(51), /* RFC 8446 */ 5343 (65535) 5344 } ExtensionType; 5346 struct { 5347 NamedGroup group; 5348 opaque key_exchange<1..2^16-1>; 5349 } KeyShareEntry; 5351 struct { 5352 KeyShareEntry client_shares<0..2^16-1>; 5353 } KeyShareClientHello; 5355 struct { 5356 NamedGroup selected_group; 5357 } KeyShareHelloRetryRequest; 5359 struct { 5360 KeyShareEntry server_share; 5361 } KeyShareServerHello; 5363 struct { 5364 uint8 legacy_form = 4; 5365 opaque X[coordinate_length]; 5366 opaque Y[coordinate_length]; 5367 } UncompressedPointRepresentation; 5369 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 5371 struct { 5372 PskKeyExchangeMode ke_modes<1..255>; 5373 } PskKeyExchangeModes; 5375 struct {} Empty; 5377 struct { 5378 select (Handshake.msg_type) { 5379 case new_session_ticket: uint32 max_early_data_size; 5380 case client_hello: Empty; 5381 case encrypted_extensions: Empty; 5382 }; 5383 } EarlyDataIndication; 5385 struct { 5386 opaque identity<1..2^16-1>; 5387 uint32 obfuscated_ticket_age; 5389 } PskIdentity; 5391 opaque PskBinderEntry<32..255>; 5393 struct { 5394 PskIdentity identities<7..2^16-1>; 5395 PskBinderEntry binders<33..2^16-1>; 5396 } OfferedPsks; 5398 struct { 5399 select (Handshake.msg_type) { 5400 case client_hello: OfferedPsks; 5401 case server_hello: uint16 selected_identity; 5402 }; 5403 } PreSharedKeyExtension; 5405 B.3.1.1. Version Extension 5407 struct { 5408 select (Handshake.msg_type) { 5409 case client_hello: 5410 ProtocolVersion versions<2..254>; 5412 case server_hello: /* and HelloRetryRequest */ 5413 ProtocolVersion selected_version; 5414 }; 5415 } SupportedVersions; 5417 B.3.1.2. Cookie Extension 5419 struct { 5420 opaque cookie<1..2^16-1>; 5421 } Cookie; 5423 B.3.1.3. Signature Algorithm Extension 5424 enum { 5425 /* RSASSA-PKCS1-v1_5 algorithms */ 5426 rsa_pkcs1_sha256(0x0401), 5427 rsa_pkcs1_sha384(0x0501), 5428 rsa_pkcs1_sha512(0x0601), 5430 /* ECDSA algorithms */ 5431 ecdsa_secp256r1_sha256(0x0403), 5432 ecdsa_secp384r1_sha384(0x0503), 5433 ecdsa_secp521r1_sha512(0x0603), 5435 /* RSASSA-PSS algorithms with public key OID rsaEncryption */ 5436 rsa_pss_rsae_sha256(0x0804), 5437 rsa_pss_rsae_sha384(0x0805), 5438 rsa_pss_rsae_sha512(0x0806), 5440 /* EdDSA algorithms */ 5441 ed25519(0x0807), 5442 ed448(0x0808), 5444 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */ 5445 rsa_pss_pss_sha256(0x0809), 5446 rsa_pss_pss_sha384(0x080a), 5447 rsa_pss_pss_sha512(0x080b), 5449 /* Legacy algorithms */ 5450 rsa_pkcs1_sha1(0x0201), 5451 ecdsa_sha1(0x0203), 5453 /* Reserved Code Points */ 5454 obsolete_RESERVED(0x0000..0x0200), 5455 dsa_sha1_RESERVED(0x0202), 5456 obsolete_RESERVED(0x0204..0x0400), 5457 dsa_sha256_RESERVED(0x0402), 5458 obsolete_RESERVED(0x0404..0x0500), 5459 dsa_sha384_RESERVED(0x0502), 5460 obsolete_RESERVED(0x0504..0x0600), 5461 dsa_sha512_RESERVED(0x0602), 5462 obsolete_RESERVED(0x0604..0x06FF), 5463 private_use(0xFE00..0xFFFF), 5464 (0xFFFF) 5465 } SignatureScheme; 5467 struct { 5468 SignatureScheme supported_signature_algorithms<2..2^16-2>; 5469 } SignatureSchemeList; 5471 B.3.1.4. Supported Groups Extension 5473 enum { 5474 unallocated_RESERVED(0x0000), 5476 /* Elliptic Curve Groups (ECDHE) */ 5477 obsolete_RESERVED(0x0001..0x0016), 5478 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 5479 obsolete_RESERVED(0x001A..0x001C), 5480 x25519(0x001D), x448(0x001E), 5482 /* Finite Field Groups (DHE) */ 5483 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102), 5484 ffdhe6144(0x0103), ffdhe8192(0x0104), 5486 /* Reserved Code Points */ 5487 ffdhe_private_use(0x01FC..0x01FF), 5488 ecdhe_private_use(0xFE00..0xFEFF), 5489 obsolete_RESERVED(0xFF01..0xFF02), 5490 (0xFFFF) 5491 } NamedGroup; 5493 struct { 5494 NamedGroup named_group_list<2..2^16-1>; 5495 } NamedGroupList; 5497 Values within "obsolete_RESERVED" ranges are used in previous 5498 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3 5499 implementations. The obsolete curves have various known/theoretical 5500 weaknesses or have had very little usage, in some cases only due to 5501 unintentional server configuration issues. They are no longer 5502 considered appropriate for general use and should be assumed to be 5503 potentially unsafe. The set of curves specified here is sufficient 5504 for interoperability with all currently deployed and properly 5505 configured TLS implementations. 5507 B.3.2. Server Parameters Messages 5508 opaque DistinguishedName<1..2^16-1>; 5510 struct { 5511 DistinguishedName authorities<3..2^16-1>; 5512 } CertificateAuthoritiesExtension; 5514 struct { 5515 opaque certificate_extension_oid<1..2^8-1>; 5516 opaque certificate_extension_values<0..2^16-1>; 5517 } OIDFilter; 5519 struct { 5520 OIDFilter filters<0..2^16-1>; 5521 } OIDFilterExtension; 5523 struct {} PostHandshakeAuth; 5525 struct { 5526 Extension extensions<0..2^16-1>; 5527 } EncryptedExtensions; 5529 struct { 5530 opaque certificate_request_context<0..2^8-1>; 5531 Extension extensions<0..2^16-1>; 5532 } CertificateRequest; 5534 B.3.3. Authentication Messages 5535 enum { 5536 X509(0), 5537 OpenPGP_RESERVED(1), 5538 RawPublicKey(2), 5539 (255) 5540 } CertificateType; 5542 struct { 5543 select (certificate_type) { 5544 case RawPublicKey: 5545 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */ 5546 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 5548 case X509: 5549 opaque cert_data<1..2^24-1>; 5550 }; 5551 Extension extensions<0..2^16-1>; 5552 } CertificateEntry; 5554 struct { 5555 opaque certificate_request_context<0..2^8-1>; 5556 CertificateEntry certificate_list<0..2^24-1>; 5557 } Certificate; 5559 struct { 5560 SignatureScheme algorithm; 5561 opaque signature<0..2^16-1>; 5562 } CertificateVerify; 5564 struct { 5565 opaque verify_data[Hash.length]; 5566 } Finished; 5568 B.3.4. Ticket Establishment 5570 struct { 5571 uint32 ticket_lifetime; 5572 uint32 ticket_age_add; 5573 opaque ticket_nonce<0..255>; 5574 opaque ticket<1..2^16-1>; 5575 Extension extensions<0..2^16-2>; 5576 } NewSessionTicket; 5578 B.3.5. Updating Keys 5579 struct {} EndOfEarlyData; 5581 enum { 5582 update_not_requested(0), update_requested(1), (255) 5583 } KeyUpdateRequest; 5585 struct { 5586 KeyUpdateRequest request_update; 5587 } KeyUpdate; 5589 B.4. Cipher Suites 5591 A cipher suite defines the pair of the AEAD algorithm and hash 5592 algorithm to be used with HKDF. Cipher suite names follow the naming 5593 convention: 5595 CipherSuite TLS_AEAD_HASH = VALUE; 5597 +===========+================================================+ 5598 | Component | Contents | 5599 +===========+================================================+ 5600 | TLS | The string "TLS" | 5601 +-----------+------------------------------------------------+ 5602 | AEAD | The AEAD algorithm used for record protection | 5603 +-----------+------------------------------------------------+ 5604 | HASH | The hash algorithm used with HKDF | 5605 +-----------+------------------------------------------------+ 5606 | VALUE | The two byte ID assigned for this cipher suite | 5607 +-----------+------------------------------------------------+ 5609 Table 4: Cipher Suite Name Structure 5611 This specification defines the following cipher suites for use with 5612 TLS 1.3. 5614 +==============================+=============+ 5615 | Description | Value | 5616 +==============================+=============+ 5617 | TLS_AES_128_GCM_SHA256 | {0x13,0x01} | 5618 +------------------------------+-------------+ 5619 | TLS_AES_256_GCM_SHA384 | {0x13,0x02} | 5620 +------------------------------+-------------+ 5621 | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} | 5622 +------------------------------+-------------+ 5623 | TLS_AES_128_CCM_SHA256 | {0x13,0x04} | 5624 +------------------------------+-------------+ 5625 | TLS_AES_128_CCM_8_SHA256 | {0x13,0x05} | 5626 +------------------------------+-------------+ 5628 Table 5: Cipher Suite List 5630 The corresponding AEAD algorithms AEAD_AES_128_GCM, AEAD_AES_256_GCM, 5631 and AEAD_AES_128_CCM are defined in [RFC5116]. 5632 AEAD_CHACHA20_POLY1305 is defined in [RFC8439]. AEAD_AES_128_CCM_8 5633 is defined in [RFC6655]. The corresponding hash algorithms are 5634 defined in [SHS]. 5636 Although TLS 1.3 uses the same cipher suite space as previous 5637 versions of TLS, TLS 1.3 cipher suites are defined differently, only 5638 specifying the symmetric ciphers, and cannot be used for TLS 1.2. 5639 Similarly, cipher suites for TLS 1.2 and lower cannot be used with 5640 TLS 1.3. 5642 New cipher suite values are assigned by IANA as described in 5643 Section 11. 5645 Appendix C. Implementation Notes 5647 The TLS protocol cannot prevent many common security mistakes. This 5648 appendix provides several recommendations to assist implementors. 5649 [RFC8448] provides test vectors for TLS 1.3 handshakes. 5651 C.1. Random Number Generation and Seeding 5653 TLS requires a cryptographically secure pseudorandom number generator 5654 (CSPRNG). In most cases, the operating system provides an 5655 appropriate facility such as /dev/urandom, which should be used 5656 absent other (e.g., performance) concerns. It is RECOMMENDED to use 5657 an existing CSPRNG implementation in preference to crafting a new 5658 one. Many adequate cryptographic libraries are already available 5659 under favorable license terms. Should those prove unsatisfactory, 5660 [RFC4086] provides guidance on the generation of random values. 5662 TLS uses random values (1) in public protocol fields such as the 5663 public Random values in the ClientHello and ServerHello and (2) to 5664 generate keying material. With a properly functioning CSPRNG, this 5665 does not present a security problem, as it is not feasible to 5666 determine the CSPRNG state from its output. However, with a broken 5667 CSPRNG, it may be possible for an attacker to use the public output 5668 to determine the CSPRNG internal state and thereby predict the keying 5669 material, as documented in [CHECKOWAY]. Implementations can provide 5670 extra security against this form of attack by using separate CSPRNGs 5671 to generate public and private values. 5673 C.2. Certificates and Authentication 5675 Implementations are responsible for verifying the integrity of 5676 certificates and should generally support certificate revocation 5677 messages. Absent a specific indication from an application profile, 5678 certificates should always be verified to ensure proper signing by a 5679 trusted certificate authority (CA). The selection and addition of 5680 trust anchors should be done very carefully. Users should be able to 5681 view information about the certificate and trust anchor. 5682 Applications SHOULD also enforce minimum and maximum key sizes. For 5683 example, certification paths containing keys or signatures weaker 5684 than 2048-bit RSA or 224-bit ECDSA are not appropriate for secure 5685 applications. 5687 C.3. Implementation Pitfalls 5689 Implementation experience has shown that certain parts of earlier TLS 5690 specifications are not easy to understand and have been a source of 5691 interoperability and security problems. Many of these areas have 5692 been clarified in this document but this appendix contains a short 5693 list of the most important things that require special attention from 5694 implementors. 5696 TLS protocol issues: 5698 * Do you correctly handle handshake messages that are fragmented to 5699 multiple TLS records (see Section 5.1)? Do you correctly handle 5700 corner cases like a ClientHello that is split into several small 5701 fragments? Do you fragment handshake messages that exceed the 5702 maximum fragment size? In particular, the Certificate and 5703 CertificateRequest handshake messages can be large enough to 5704 require fragmentation. 5706 * Do you ignore the TLS record layer version number in all 5707 unencrypted TLS records (see Appendix D)? 5709 * Have you ensured that all support for SSL, RC4, EXPORT ciphers, 5710 and MD5 (via the "signature_algorithms" extension) is completely 5711 removed from all possible configurations that support TLS 1.3 or 5712 later, and that attempts to use these obsolete capabilities fail 5713 correctly? (see Appendix D)? 5715 * Do you handle TLS extensions in ClientHellos correctly, including 5716 unknown extensions? 5718 * When the server has requested a client certificate but no suitable 5719 certificate is available, do you correctly send an empty 5720 Certificate message, instead of omitting the whole message (see 5721 Section 4.4.2)? 5723 * When processing the plaintext fragment produced by AEAD-Decrypt 5724 and scanning from the end for the ContentType, do you avoid 5725 scanning past the start of the cleartext in the event that the 5726 peer has sent a malformed plaintext of all zeros? 5728 * Do you properly ignore unrecognized cipher suites (Section 4.1.2), 5729 hello extensions (Section 4.2), named groups (Section 4.2.7), key 5730 shares (Section 4.2.8), supported versions (Section 4.2.1), and 5731 signature algorithms (Section 4.2.3) in the ClientHello? 5733 * As a server, do you send a HelloRetryRequest to clients which 5734 support a compatible (EC)DHE group but do not predict it in the 5735 "key_share" extension? As a client, do you correctly handle a 5736 HelloRetryRequest from the server? 5738 Cryptographic details: 5740 * What countermeasures do you use to prevent timing attacks 5741 [TIMING]? 5743 * When using Diffie-Hellman key exchange, do you correctly preserve 5744 leading zero bytes in the negotiated key (see Section 7.4.1)? 5746 * Does your TLS client check that the Diffie-Hellman parameters sent 5747 by the server are acceptable (see Section 4.2.8.1)? 5749 * Do you use a strong and, most importantly, properly seeded random 5750 number generator (see Appendix C.1) when generating Diffie-Hellman 5751 private values, the ECDSA "k" parameter, and other security- 5752 critical values? It is RECOMMENDED that implementations implement 5753 "deterministic ECDSA" as specified in [RFC6979]. 5755 * Do you zero-pad Diffie-Hellman public key values and shared 5756 secrets to the group size (see Section 4.2.8.1 and Section 7.4.1)? 5758 * Do you verify signatures after making them, to protect against 5759 RSA-CRT key leaks [FW15]? 5761 C.4. Client Tracking Prevention 5763 Clients SHOULD NOT reuse a ticket for multiple connections. Reuse of 5764 a ticket allows passive observers to correlate different connections. 5765 Servers that issue tickets SHOULD offer at least as many tickets as 5766 the number of connections that a client might use; for example, a web 5767 browser using HTTP/1.1 [RFC7230] might open six connections to a 5768 server. Servers SHOULD issue new tickets with every connection. 5769 This ensures that clients are always able to use a new ticket when 5770 creating a new connection. 5772 C.5. Unauthenticated Operation 5774 Previous versions of TLS offered explicitly unauthenticated cipher 5775 suites based on anonymous Diffie-Hellman. These modes have been 5776 deprecated in TLS 1.3. However, it is still possible to negotiate 5777 parameters that do not provide verifiable server authentication by 5778 several methods, including: 5780 * Raw public keys [RFC7250]. 5782 * Using a public key contained in a certificate but without 5783 validation of the certificate chain or any of its contents. 5785 Either technique used alone is vulnerable to man-in-the-middle 5786 attacks and therefore unsafe for general use. However, it is also 5787 possible to bind such connections to an external authentication 5788 mechanism via out-of-band validation of the server's public key, 5789 trust on first use, or a mechanism such as channel bindings (though 5790 the channel bindings described in [RFC5929] are not defined for TLS 5791 1.3). If no such mechanism is used, then the connection has no 5792 protection against active man-in-the-middle attack; applications MUST 5793 NOT use TLS in such a way absent explicit configuration or a specific 5794 application profile. 5796 Appendix D. Backward Compatibility 5798 The TLS protocol provides a built-in mechanism for version 5799 negotiation between endpoints potentially supporting different 5800 versions of TLS. 5802 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 5803 also handle clients trying to use future versions of TLS as long as 5804 the ClientHello format remains compatible and there is at least one 5805 protocol version supported by both the client and the server. 5807 Prior versions of TLS used the record layer version number 5808 (TLSPlaintext.legacy_record_version and 5809 TLSCiphertext.legacy_record_version) for various purposes. As of TLS 5810 1.3, this field is deprecated. The value of 5811 TLSPlaintext.legacy_record_version MUST be ignored by all 5812 implementations. The value of TLSCiphertext.legacy_record_version is 5813 included in the additional data for deprotection but MAY otherwise be 5814 ignored or MAY be validated to match the fixed constant value. 5815 Version negotiation is performed using only the handshake versions 5816 (ClientHello.legacy_version and ServerHello.legacy_version, as well 5817 as the ClientHello, HelloRetryRequest, and ServerHello 5818 "supported_versions" extensions). In order to maximize 5819 interoperability with older endpoints, implementations that negotiate 5820 the use of TLS 1.0-1.2 SHOULD set the record layer version number to 5821 the negotiated version for the ServerHello and all records 5822 thereafter. 5824 For maximum compatibility with previously non-standard behavior and 5825 misconfigured deployments, all implementations SHOULD support 5826 validation of certification paths based on the expectations in this 5827 document, even when handling prior TLS versions' handshakes (see 5828 Section 4.4.2.2). 5830 TLS 1.2 and prior supported an "Extended Master Secret" [RFC7627] 5831 extension which digested large parts of the handshake transcript into 5832 the secret and derived keys. Because TLS 1.3 always hashes in the 5833 transcript up to the server Finished, implementations which support 5834 both TLS 1.3 and earlier versions SHOULD indicate the use of the 5835 Extended Master Secret extension in their APIs whenever TLS 1.3 is 5836 used. 5838 D.1. Negotiating with an Older Server 5840 A TLS 1.3 client who wishes to negotiate with servers that do not 5841 support TLS 1.3 will send a normal TLS 1.3 ClientHello containing 5842 0x0303 (TLS 1.2) in ClientHello.legacy_version but with the correct 5843 version(s) in the "supported_versions" extension. If the server does 5844 not support TLS 1.3, it will respond with a ServerHello containing an 5845 older version number. If the client agrees to use this version, the 5846 negotiation will proceed as appropriate for the negotiated protocol. 5847 A client using a ticket for resumption SHOULD initiate the connection 5848 using the version that was previously negotiated. 5850 Note that 0-RTT data is not compatible with older servers and SHOULD 5851 NOT be sent absent knowledge that the server supports TLS 1.3. See 5852 Appendix D.3. 5854 If the version chosen by the server is not supported by the client 5855 (or is not acceptable), the client MUST abort the handshake with a 5856 "protocol_version" alert. 5858 Some legacy server implementations are known to not implement the TLS 5859 specification properly and might abort connections upon encountering 5860 TLS extensions or versions which they are not aware of. 5861 Interoperability with buggy servers is a complex topic beyond the 5862 scope of this document. Multiple connection attempts may be required 5863 in order to negotiate a backward-compatible connection; however, this 5864 practice is vulnerable to downgrade attacks and is NOT RECOMMENDED. 5866 D.2. Negotiating with an Older Client 5868 A TLS server can also receive a ClientHello indicating a version 5869 number smaller than its highest supported version. If the 5870 "supported_versions" extension is present, the server MUST negotiate 5871 using that extension as described in Section 4.2.1. If the 5872 "supported_versions" extension is not present, the server MUST 5873 negotiate the minimum of ClientHello.legacy_version and TLS 1.2. For 5874 example, if the server supports TLS 1.0, 1.1, and 1.2, and 5875 legacy_version is TLS 1.0, the server will proceed with a TLS 1.0 5876 ServerHello. If the "supported_versions" extension is absent and the 5877 server only supports versions greater than 5878 ClientHello.legacy_version, the server MUST abort the handshake with 5879 a "protocol_version" alert. 5881 Note that earlier versions of TLS did not clearly specify the record 5882 layer version number value in all cases 5883 (TLSPlaintext.legacy_record_version). Servers will receive various 5884 TLS 1.x versions in this field, but its value MUST always be ignored. 5886 D.3. 0-RTT Backward Compatibility 5888 0-RTT data is not compatible with older servers. An older server 5889 will respond to the ClientHello with an older ServerHello, but it 5890 will not correctly skip the 0-RTT data and will fail to complete the 5891 handshake. This can cause issues when a client attempts to use 5892 0-RTT, particularly against multi-server deployments. For example, a 5893 deployment could deploy TLS 1.3 gradually with some servers 5894 implementing TLS 1.3 and some implementing TLS 1.2, or a TLS 1.3 5895 deployment could be downgraded to TLS 1.2. 5897 A client that attempts to send 0-RTT data MUST fail a connection if 5898 it receives a ServerHello with TLS 1.2 or older. It can then retry 5899 the connection with 0-RTT disabled. To avoid a downgrade attack, the 5900 client SHOULD NOT disable TLS 1.3, only 0-RTT. 5902 To avoid this error condition, multi-server deployments SHOULD ensure 5903 a uniform and stable deployment of TLS 1.3 without 0-RTT prior to 5904 enabling 0-RTT. 5906 D.4. Middlebox Compatibility Mode 5908 Field measurements [Ben17a] [Ben17b] [Res17a] [Res17b] have found 5909 that a significant number of middleboxes misbehave when a TLS client/ 5910 server pair negotiates TLS 1.3. Implementations can increase the 5911 chance of making connections through those middleboxes by making the 5912 TLS 1.3 handshake look more like a TLS 1.2 handshake: 5914 * The client always provides a non-empty session ID in the 5915 ClientHello, as described in the legacy_session_id section of 5916 Section 4.1.2. 5918 * If not offering early data, the client sends a dummy 5919 change_cipher_spec record (see the third paragraph of Section 5) 5920 immediately before its second flight. This may either be before 5921 its second ClientHello or before its encrypted handshake flight. 5922 If offering early data, the record is placed immediately after the 5923 first ClientHello. 5925 * The server sends a dummy change_cipher_spec record immediately 5926 after its first handshake message. This may either be after a 5927 ServerHello or a HelloRetryRequest. 5929 When put together, these changes make the TLS 1.3 handshake resemble 5930 TLS 1.2 session resumption, which improves the chance of successfully 5931 connecting through middleboxes. This "compatibility mode" is 5932 partially negotiated: the client can opt to provide a session ID or 5933 not, and the server has to echo it. Either side can send 5934 change_cipher_spec at any time during the handshake, as they must be 5935 ignored by the peer, but if the client sends a non-empty session ID, 5936 the server MUST send the change_cipher_spec as described in this 5937 appendix. 5939 D.5. Security Restrictions Related to Backward Compatibility 5941 Implementations negotiating the use of older versions of TLS SHOULD 5942 prefer forward secret and AEAD cipher suites, when available. 5944 The security of RC4 cipher suites is considered insufficient for the 5945 reasons cited in [RFC7465]. Implementations MUST NOT offer or 5946 negotiate RC4 cipher suites for any version of TLS for any reason. 5948 Old versions of TLS permitted the use of very low strength ciphers. 5949 Ciphers with a strength less than 112 bits MUST NOT be offered or 5950 negotiated for any version of TLS for any reason. 5952 The security of SSL 3.0 [RFC6101] is considered insufficient for the 5953 reasons enumerated in [RFC7568], and it MUST NOT be negotiated for 5954 any reason. 5956 The security of SSL 2.0 [SSL2] is considered insufficient for the 5957 reasons enumerated in [RFC6176], and it MUST NOT be negotiated for 5958 any reason. 5960 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 5961 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 5962 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 5963 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 5964 order to negotiate older versions of TLS. 5966 Implementations MUST NOT send a ClientHello.legacy_version or 5967 ServerHello.legacy_version set to 0x0300 or less. Any endpoint 5968 receiving a Hello message with ClientHello.legacy_version or 5969 ServerHello.legacy_version set to 0x0300 MUST abort the handshake 5970 with a "protocol_version" alert. 5972 Implementations MUST NOT send any records with a version less than 5973 0x0300. Implementations SHOULD NOT accept any records with a version 5974 less than 0x0300 (but may inadvertently do so if the record version 5975 number is ignored completely). 5977 Implementations MUST NOT use the Truncated HMAC extension, defined in 5978 Section 7 of [RFC6066], as it is not applicable to AEAD algorithms 5979 and has been shown to be insecure in some scenarios. 5981 Appendix E. Overview of Security Properties 5983 A complete security analysis of TLS is outside the scope of this 5984 document. In this appendix, we provide an informal description of 5985 the desired properties as well as references to more detailed work in 5986 the research literature which provides more formal definitions. 5988 We cover properties of the handshake separately from those of the 5989 record layer. 5991 E.1. Handshake 5993 The TLS handshake is an Authenticated Key Exchange (AKE) protocol 5994 which is intended to provide both one-way authenticated (server-only) 5995 and mutually authenticated (client and server) functionality. At the 5996 completion of the handshake, each side outputs its view of the 5997 following values: 5999 * A set of "session keys" (the various secrets derived from the main 6000 secret) from which can be derived a set of working keys. 6002 * A set of cryptographic parameters (algorithms, etc.). 6004 * The identities of the communicating parties. 6006 We assume the attacker to be an active network attacker, which means 6007 it has complete control over the network used to communicate between 6008 the parties [RFC3552]. Even under these conditions, the handshake 6009 should provide the properties listed below. Note that these 6010 properties are not necessarily independent, but reflect the protocol 6011 consumers' needs. 6013 Establishing the same session keys: The handshake needs to output 6014 the same set of session keys on both sides of the handshake, 6015 provided that it completes successfully on each endpoint (see 6016 [CK01]; Definition 1, part 1). 6018 Secrecy of the session keys: The shared session keys should be known 6019 only to the communicating parties and not to the attacker (see 6020 [CK01]; Definition 1, part 2). Note that in a unilaterally 6021 authenticated connection, the attacker can establish its own 6022 session keys with the server, but those session keys are distinct 6023 from those established by the client. 6025 Peer Authentication: The client's view of the peer identity should 6026 reflect the server's identity. If the client is authenticated, 6027 the server's view of the peer identity should match the client's 6028 identity. 6030 Uniqueness of the session keys: Any two distinct handshakes should 6031 produce distinct, unrelated session keys. Individual session keys 6032 produced by a handshake should also be distinct and independent. 6034 Downgrade Protection: The cryptographic parameters should be the 6035 same on both sides and should be the same as if the peers had been 6036 communicating in the absence of an attack (see [BBFGKZ16]; 6037 Definitions 8 and 9). 6039 Forward secret with respect to long-term keys: If the long-term 6040 keying material (in this case the signature keys in certificate- 6041 based authentication modes or the external/resumption PSK in PSK 6042 with (EC)DHE modes) is compromised after the handshake is 6043 complete, this does not compromise the security of the session key 6044 (see [DOW92]), as long as the session key itself has been erased. 6045 The forward secrecy property is not satisfied when PSK is used in 6046 the "psk_ke" PskKeyExchangeMode. 6048 Key Compromise Impersonation (KCI) resistance: In a mutually 6049 authenticated connection with certificates, compromising the long- 6050 term secret of one actor should not break that actor's 6051 authentication of their peer in the given connection (see 6052 [HGFS15]). For example, if a client's signature key is 6053 compromised, it should not be possible to impersonate arbitrary 6054 servers to that client in subsequent handshakes. 6056 Protection of endpoint identities: The server's identity 6057 (certificate) should be protected against passive attackers. The 6058 client's identity should be protected against both passive and 6059 active attackers. 6061 Informally, the signature-based modes of TLS 1.3 provide for the 6062 establishment of a unique, secret, shared key established by an 6063 (EC)DHE key exchange and authenticated by the server's signature over 6064 the handshake transcript, as well as tied to the server's identity by 6065 a MAC. If the client is authenticated by a certificate, it also 6066 signs over the handshake transcript and provides a MAC tied to both 6067 identities. [SIGMA] describes the design and analysis of this type 6068 of key exchange protocol. If fresh (EC)DHE keys are used for each 6069 connection, then the output keys are forward secret. 6071 The external PSK and resumption PSK bootstrap from a long-term shared 6072 secret into a unique per-connection set of short-term session keys. 6073 This secret may have been established in a previous handshake. If 6074 PSK with (EC)DHE key establishment is used, these session keys will 6075 also be forward secret. The resumption PSK has been designed so that 6076 the resumption main secret computed by connection N and needed to 6077 form connection N+1 is separate from the traffic keys used by 6078 connection N, thus providing forward secrecy between the connections. 6079 In addition, if multiple tickets are established on the same 6080 connection, they are associated with different keys, so compromise of 6081 the PSK associated with one ticket does not lead to the compromise of 6082 connections established with PSKs associated with other tickets. 6083 This property is most interesting if tickets are stored in a database 6084 (and so can be deleted) rather than if they are self-encrypted. 6086 The PSK binder value forms a binding between a PSK and the current 6087 handshake, as well as between the session where the PSK was 6088 established and the current session. This binding transitively 6089 includes the original handshake transcript, because that transcript 6090 is digested into the values which produce the resumption main secret. 6091 This requires that both the KDF used to produce the resumption main 6092 secret and the MAC used to compute the binder be collision resistant. 6093 See Appendix E.1.1 for more on this. Note: The binder does not cover 6094 the binder values from other PSKs, though they are included in the 6095 Finished MAC. 6097 Note: TLS does not currently permit the server to send a 6098 certificate_request message in non-certificate-based handshakes 6099 (e.g., PSK). If this restriction were to be relaxed in future, the 6100 client's signature would not cover the server's certificate directly. 6101 However, if the PSK was established through a NewSessionTicket, the 6102 client's signature would transitively cover the server's certificate 6103 through the PSK binder. [PSK-FINISHED] describes a concrete attack 6104 on constructions that do not bind to the server's certificate (see 6105 also [Kraw16]). It is unsafe to use certificate-based client 6106 authentication when the client might potentially share the same PSK/ 6107 key-id pair with two different endpoints. Implementations MUST NOT 6108 combine external PSKs with certificate-based authentication of either 6109 the client or server. Future specifications MAY provide an extension 6110 to permit this. 6112 If an exporter is used, then it produces values which are unique and 6113 secret (because they are generated from a unique session key). 6114 Exporters computed with different labels and contexts are 6115 computationally independent, so it is not feasible to compute one 6116 from another or the session secret from the exported value. Note: 6117 Exporters can produce arbitrary-length values; if exporters are to be 6118 used as channel bindings, the exported value MUST be large enough to 6119 provide collision resistance. The exporters provided in TLS 1.3 are 6120 derived from the same Handshake Contexts as the early traffic keys 6121 and the application traffic keys, respectively, and thus have similar 6122 security properties. Note that they do not include the client's 6123 certificate; future applications which wish to bind to the client's 6124 certificate may need to define a new exporter that includes the full 6125 handshake transcript. 6127 For all handshake modes, the Finished MAC (and, where present, the 6128 signature) prevents downgrade attacks. In addition, the use of 6129 certain bytes in the random nonces as described in Section 4.1.3 6130 allows the detection of downgrade to previous TLS versions. See 6131 [BBFGKZ16] for more details on TLS 1.3 and downgrade. 6133 As soon as the client and the server have exchanged enough 6134 information to establish shared keys, the remainder of the handshake 6135 is encrypted, thus providing protection against passive attackers, 6136 even if the computed shared key is not authenticated. Because the 6137 server authenticates before the client, the client can ensure that if 6138 it authenticates to the server, it only reveals its identity to an 6139 authenticated server. Note that implementations must use the 6140 provided record-padding mechanism during the handshake to avoid 6141 leaking information about the identities due to length. The client's 6142 proposed PSK identities are not encrypted, nor is the one that the 6143 server selects. 6145 E.1.1. Key Derivation and HKDF 6147 Key derivation in TLS 1.3 uses HKDF as defined in [RFC5869] and its 6148 two components, HKDF-Extract and HKDF-Expand. The full rationale for 6149 the HKDF construction can be found in [Kraw10] and the rationale for 6150 the way it is used in TLS 1.3 in [KW16]. Throughout this document, 6151 each application of HKDF-Extract is followed by one or more 6152 invocations of HKDF-Expand. This ordering should always be followed 6153 (including in future revisions of this document); in particular, one 6154 SHOULD NOT use an output of HKDF-Extract as an input to another 6155 application of HKDF-Extract without an HKDF-Expand in between. 6156 Multiple applications of HKDF-Expand to some of the same inputs are 6157 allowed as long as these are differentiated via the key and/or the 6158 labels. 6160 Note that HKDF-Expand implements a pseudorandom function (PRF) with 6161 both inputs and outputs of variable length. In some of the uses of 6162 HKDF in this document (e.g., for generating exporters and the 6163 resumption_main_secret), it is necessary that the application of 6164 HKDF-Expand be collision resistant; namely, it should be infeasible 6165 to find two different inputs to HKDF-Expand that output the same 6166 value. This requires the underlying hash function to be collision 6167 resistant and the output length from HKDF-Expand to be of size at 6168 least 256 bits (or as much as needed for the hash function to prevent 6169 finding collisions). 6171 E.1.2. Client Authentication 6173 A client that has sent authentication data to a server, either during 6174 the handshake or in post-handshake authentication, cannot be sure 6175 whether the server afterwards considers the client to be 6176 authenticated or not. If the client needs to determine if the server 6177 considers the connection to be unilaterally or mutually 6178 authenticated, this has to be provisioned by the application layer. 6179 See [CHHSV17] for details. In addition, the analysis of post- 6180 handshake authentication from [Kraw16] shows that the client 6181 identified by the certificate sent in the post-handshake phase 6182 possesses the traffic key. This party is therefore the client that 6183 participated in the original handshake or one to whom the original 6184 client delegated the traffic key (assuming that the traffic key has 6185 not been compromised). 6187 E.1.3. 0-RTT 6189 The 0-RTT mode of operation generally provides security properties 6190 similar to those of 1-RTT data, with the two exceptions that the 6191 0-RTT encryption keys do not provide full forward secrecy and that 6192 the server is not able to guarantee uniqueness of the handshake (non- 6193 replayability) without keeping potentially undue amounts of state. 6194 See Section 8 for mechanisms to limit the exposure to replay. 6196 E.1.4. Exporter Independence 6198 The exporter_main_secret and early_exporter_main_secret are derived 6199 to be independent of the traffic keys and therefore do not represent 6200 a threat to the security of traffic encrypted with those keys. 6201 However, because these secrets can be used to compute any exporter 6202 value, they SHOULD be erased as soon as possible. If the total set 6203 of exporter labels is known, then implementations SHOULD pre-compute 6204 the inner Derive-Secret stage of the exporter computation for all 6205 those labels, then erase the [early_]exporter_main_secret, followed 6206 by each inner values as soon as it is known that it will not be 6207 needed again. 6209 E.1.5. Post-Compromise Security 6211 TLS does not provide security for handshakes which take place after 6212 the peer's long-term secret (signature key or external PSK) is 6213 compromised. It therefore does not provide post-compromise security 6214 [CCG16], sometimes also referred to as backwards or future secrecy. 6215 This is in contrast to KCI resistance, which describes the security 6216 guarantees that a party has after its own long-term secret has been 6217 compromised. 6219 E.1.6. External References 6221 The reader should refer to the following references for analysis of 6222 the TLS handshake: [DFGS15], [CHSV16], [DFGS16], [KW16], [Kraw16], 6223 [FGSW16], [LXZFH16], [FG17], and [BBK17]. 6225 E.2. Record Layer 6227 The record layer depends on the handshake producing strong traffic 6228 secrets which can be used to derive bidirectional encryption keys and 6229 nonces. Assuming that is true, and the keys are used for no more 6230 data than indicated in Section 5.5, then the record layer should 6231 provide the following guarantees: 6233 Confidentiality: An attacker should not be able to determine the 6234 plaintext contents of a given record. 6236 Integrity: An attacker should not be able to craft a new record 6237 which is different from an existing record which will be accepted 6238 by the receiver. 6240 Order protection/non-replayability: An attacker should not be able 6241 to cause the receiver to accept a record which it has already 6242 accepted or cause the receiver to accept record N+1 without having 6243 first processed record N. 6245 Length concealment: Given a record with a given external length, the 6246 attacker should not be able to determine the amount of the record 6247 that is content versus padding. 6249 Forward secrecy after key change: If the traffic key update 6250 mechanism described in Section 4.6.3 has been used and the 6251 previous generation key is deleted, an attacker who compromises 6252 the endpoint should not be able to decrypt traffic encrypted with 6253 the old key. 6255 Informally, TLS 1.3 provides these properties by AEAD-protecting the 6256 plaintext with a strong key. AEAD encryption [RFC5116] provides 6257 confidentiality and integrity for the data. Non-replayability is 6258 provided by using a separate nonce for each record, with the nonce 6259 being derived from the record sequence number (Section 5.3), with the 6260 sequence number being maintained independently at both sides; thus 6261 records which are delivered out of order result in AEAD deprotection 6262 failures. In order to prevent mass cryptanalysis when the same 6263 plaintext is repeatedly encrypted by different users under the same 6264 key (as is commonly the case for HTTP), the nonce is formed by mixing 6265 the sequence number with a secret per-connection initialization 6266 vector derived along with the traffic keys. See [BT16] for analysis 6267 of this construction. 6269 The rekeying technique in TLS 1.3 (see Section 7.2) follows the 6270 construction of the serial generator as discussed in [REKEY], which 6271 shows that rekeying can allow keys to be used for a larger number of 6272 encryptions than without rekeying. This relies on the security of 6273 the HKDF-Expand-Label function as a pseudorandom function (PRF). In 6274 addition, as long as this function is truly one way, it is not 6275 possible to compute traffic keys from prior to a key change (forward 6276 secrecy). 6278 TLS does not provide security for data which is communicated on a 6279 connection after a traffic secret of that connection is compromised. 6280 That is, TLS does not provide post-compromise security/future 6281 secrecy/backward secrecy with respect to the traffic secret. Indeed, 6282 an attacker who learns a traffic secret can compute all future 6283 traffic secrets on that connection. Systems which want such 6284 guarantees need to do a fresh handshake and establish a new 6285 connection with an (EC)DHE exchange. 6287 E.2.1. External References 6289 The reader should refer to the following references for analysis of 6290 the TLS record layer: [BMMRT15], [BT16], [BDFKPPRSZZ16], [BBK17], and 6291 [PS18]. 6293 E.3. Traffic Analysis 6295 TLS is susceptible to a variety of traffic analysis attacks based on 6296 observing the length and timing of encrypted packets [CLINIC] 6297 [HCJC16]. This is particularly easy when there is a small set of 6298 possible messages to be distinguished, such as for a video server 6299 hosting a fixed corpus of content, but still provides usable 6300 information even in more complicated scenarios. 6302 TLS does not provide any specific defenses against this form of 6303 attack but does include a padding mechanism for use by applications: 6304 The plaintext protected by the AEAD function consists of content plus 6305 variable-length padding, which allows the application to produce 6306 arbitrary-length encrypted records as well as padding-only cover 6307 traffic to conceal the difference between periods of transmission and 6308 periods of silence. Because the padding is encrypted alongside the 6309 actual content, an attacker cannot directly determine the length of 6310 the padding, but may be able to measure it indirectly by the use of 6311 timing channels exposed during record processing (i.e., seeing how 6312 long it takes to process a record or trickling in records to see 6313 which ones elicit a response from the server). In general, it is not 6314 known how to remove all of these channels because even a constant- 6315 time padding removal function will likely feed the content into data- 6316 dependent functions. At minimum, a fully constant-time server or 6317 client would require close cooperation with the application-layer 6318 protocol implementation, including making that higher-level protocol 6319 constant time. 6321 Note: Robust traffic analysis defenses will likely lead to inferior 6322 performance due to delays in transmitting packets and increased 6323 traffic volume. 6325 E.4. Side Channel Attacks 6327 In general, TLS does not have specific defenses against side-channel 6328 attacks (i.e., those which attack the communications via secondary 6329 channels such as timing), leaving those to the implementation of the 6330 relevant cryptographic primitives. However, certain features of TLS 6331 are designed to make it easier to write side-channel resistant code: 6333 * Unlike previous versions of TLS which used a composite MAC-then- 6334 encrypt structure, TLS 1.3 only uses AEAD algorithms, allowing 6335 implementations to use self-contained constant-time 6336 implementations of those primitives. 6338 * TLS uses a uniform "bad_record_mac" alert for all decryption 6339 errors, which is intended to prevent an attacker from gaining 6340 piecewise insight into portions of the message. Additional 6341 resistance is provided by terminating the connection on such 6342 errors; a new connection will have different cryptographic 6343 material, preventing attacks against the cryptographic primitives 6344 that require multiple trials. 6346 Information leakage through side channels can occur at layers above 6347 TLS, in application protocols and the applications that use them. 6348 Resistance to side-channel attacks depends on applications and 6349 application protocols separately ensuring that confidential 6350 information is not inadvertently leaked. 6352 E.5. Replay Attacks on 0-RTT 6354 Replayable 0-RTT data presents a number of security threats to TLS- 6355 using applications, unless those applications are specifically 6356 engineered to be safe under replay (minimally, this means idempotent, 6357 but in many cases may also require other stronger conditions, such as 6358 constant-time response). Potential attacks include: 6360 * Duplication of actions which cause side effects (e.g., purchasing 6361 an item or transferring money) to be duplicated, thus harming the 6362 site or the user. 6364 * Attackers can store and replay 0-RTT messages in order to reorder 6365 them with respect to other messages (e.g., moving a delete to 6366 after a create). 6368 * Exploiting cache timing behavior to discover the content of 0-RTT 6369 messages by replaying a 0-RTT message to a different cache node 6370 and then using a separate connection to measure request latency, 6371 to see if the two requests address the same resource. 6373 If data can be replayed a large number of times, additional attacks 6374 become possible, such as making repeated measurements of the speed of 6375 cryptographic operations. In addition, they may be able to overload 6376 rate-limiting systems. For a further description of these attacks, 6377 see [Mac17]. 6379 Ultimately, servers have the responsibility to protect themselves 6380 against attacks employing 0-RTT data replication. The mechanisms 6381 described in Section 8 are intended to prevent replay at the TLS 6382 layer but do not provide complete protection against receiving 6383 multiple copies of client data. TLS 1.3 falls back to the 1-RTT 6384 handshake when the server does not have any information about the 6385 client, e.g., because it is in a different cluster which does not 6386 share state or because the ticket has been deleted as described in 6387 Section 8.1. If the application-layer protocol retransmits data in 6388 this setting, then it is possible for an attacker to induce message 6389 duplication by sending the ClientHello to both the original cluster 6390 (which processes the data immediately) and another cluster which will 6391 fall back to 1-RTT and process the data upon application-layer 6392 replay. The scale of this attack is limited by the client's 6393 willingness to retry transactions and therefore only allows a limited 6394 amount of duplication, with each copy appearing as a new connection 6395 at the server. 6397 If implemented correctly, the mechanisms described in Section 8.1 and 6398 Section 8.2 prevent a replayed ClientHello and its associated 0-RTT 6399 data from being accepted multiple times by any cluster with 6400 consistent state; for servers which limit the use of 0-RTT to one 6401 cluster for a single ticket, then a given ClientHello and its 6402 associated 0-RTT data will only be accepted once. However, if state 6403 is not completely consistent, then an attacker might be able to have 6404 multiple copies of the data be accepted during the replication 6405 window. Because clients do not know the exact details of server 6406 behavior, they MUST NOT send messages in early data which are not 6407 safe to have replayed and which they would not be willing to retry 6408 across multiple 1-RTT connections. 6410 Application protocols MUST NOT use 0-RTT data without a profile that 6411 defines its use. That profile needs to identify which messages or 6412 interactions are safe to use with 0-RTT and how to handle the 6413 situation when the server rejects 0-RTT and falls back to 1-RTT. 6415 In addition, to avoid accidental misuse, TLS implementations MUST NOT 6416 enable 0-RTT (either sending or accepting) unless specifically 6417 requested by the application and MUST NOT automatically resend 0-RTT 6418 data if it is rejected by the server unless instructed by the 6419 application. Server-side applications may wish to implement special 6420 processing for 0-RTT data for some kinds of application traffic 6421 (e.g., abort the connection, request that data be resent at the 6422 application layer, or delay processing until the handshake 6423 completes). In order to allow applications to implement this kind of 6424 processing, TLS implementations MUST provide a way for the 6425 application to determine if the handshake has completed. 6427 E.5.1. Replay and Exporters 6429 Replays of the ClientHello produce the same early exporter, thus 6430 requiring additional care by applications which use these exporters. 6431 In particular, if these exporters are used as an authentication 6432 channel binding (e.g., by signing the output of the exporter) an 6433 attacker who compromises the PSK can transplant authenticators 6434 between connections without compromising the authentication key. 6436 In addition, the early exporter SHOULD NOT be used to generate 6437 server-to-client encryption keys because that would entail the reuse 6438 of those keys. This parallels the use of the early application 6439 traffic keys only in the client-to-server direction. 6441 E.6. PSK Identity Exposure 6443 Because implementations respond to an invalid PSK binder by aborting 6444 the handshake, it may be possible for an attacker to verify whether a 6445 given PSK identity is valid. Specifically, if a server accepts both 6446 external-PSK and certificate-based handshakes, a valid PSK identity 6447 will result in a failed handshake, whereas an invalid identity will 6448 just be skipped and result in a successful certificate handshake. 6449 Servers which solely support PSK handshakes may be able to resist 6450 this form of attack by treating the cases where there is no valid PSK 6451 identity and where there is an identity but it has an invalid binder 6452 identically. 6454 E.7. Sharing PSKs 6456 TLS 1.3 takes a conservative approach to PSKs by binding them to a 6457 specific KDF. By contrast, TLS 1.2 allows PSKs to be used with any 6458 hash function and the TLS 1.2 PRF. Thus, any PSK which is used with 6459 both TLS 1.2 and TLS 1.3 must be used with only one hash in TLS 1.3, 6460 which is less than optimal if users want to provision a single PSK. 6461 The constructions in TLS 1.2 and TLS 1.3 are different, although they 6462 are both based on HMAC. While there is no known way in which the 6463 same PSK might produce related output in both versions, only limited 6464 analysis has been done. Implementations can ensure safety from 6465 cross-protocol related output by not reusing PSKs between TLS 1.3 and 6466 TLS 1.2. 6468 E.8. Attacks on Static RSA 6470 Although TLS 1.3 does not use RSA key transport and so is not 6471 directly susceptible to Bleichenbacher-type attacks [Blei98]if TLS 6472 1.3 servers also support static RSA in the context of previous 6473 versions of TLS, then it may be possible to impersonate the server 6474 for TLS 1.3 connections [JSS15]. TLS 1.3 implementations can prevent 6475 this attack by disabling support for static RSA across all versions 6476 of TLS. In principle, implementations might also be able to separate 6477 certificates with different keyUsage bits for static RSA decryption 6478 and RSA signature, but this technique relies on clients refusing to 6479 accept signatures using keys in certificates that do not have the 6480 digitalSignature bit set, and many clients do not enforce this 6481 restriction. 6483 Contributors 6485 Martin Abadi 6486 University of California, Santa Cruz 6487 abadi@cs.ucsc.edu 6489 Christopher Allen 6490 (co-editor of TLS 1.0) 6491 Alacrity Ventures 6492 ChristopherA@AlacrityManagement.com 6494 Richard Barnes 6495 Cisco 6496 rlb@ipv.sx 6498 Steven M. Bellovin 6499 Columbia University 6500 smb@cs.columbia.edu 6502 David Benjamin 6503 Google 6504 davidben@google.com 6506 Benjamin Beurdouche 6507 INRIA & Microsoft Research 6508 benjamin.beurdouche@ens.fr 6510 Karthikeyan Bhargavan 6511 (editor of [RFC7627]) 6512 INRIA 6513 karthikeyan.bhargavan@inria.fr 6515 Simon Blake-Wilson 6516 (co-author of [RFC4492]) 6517 BCI 6518 sblakewilson@bcisse.com 6520 Nelson Bolyard 6521 (co-author of [RFC4492]) 6522 Sun Microsystems, Inc. 6523 nelson@bolyard.com 6525 Ran Canetti 6526 IBM 6527 canetti@watson.ibm.com 6529 Matt Caswell 6530 OpenSSL 6531 matt@openssl.org 6533 Stephen Checkoway 6534 University of Illinois at Chicago 6535 sfc@uic.edu 6537 Pete Chown 6538 Skygate Technology Ltd 6539 pc@skygate.co.uk 6541 Katriel Cohn-Gordon 6542 University of Oxford 6543 me@katriel.co.uk 6545 Cas Cremers 6546 University of Oxford 6547 cas.cremers@cs.ox.ac.uk 6549 Antoine Delignat-Lavaud 6550 (co-author of [RFC7627]) 6551 INRIA 6552 antdl@microsoft.com 6554 Tim Dierks 6555 (co-author of TLS 1.0, co-editor of TLS 1.1 and 1.2) 6556 Independent 6557 tim@dierks.org 6558 Roelof DuToit 6559 Symantec Corporation 6560 roelof_dutoit@symantec.com 6562 Taher Elgamal 6563 Securify 6564 taher@securify.com 6566 Pasi Eronen 6567 Nokia 6568 pasi.eronen@nokia.com 6570 Cedric Fournet 6571 Microsoft 6572 fournet@microsoft.com 6574 Anil Gangolli 6575 anil@busybuddha.org 6577 David M. Garrett 6578 dave@nulldereference.com 6580 Illya Gerasymchuk 6581 Independent 6582 illya@iluxonchik.me 6584 Alessandro Ghedini 6585 Cloudflare Inc. 6586 alessandro@cloudflare.com 6588 Daniel Kahn Gillmor 6589 ACLU 6590 dkg@fifthhorseman.net 6592 Matthew Green 6593 Johns Hopkins University 6594 mgreen@cs.jhu.edu 6596 Jens Guballa 6597 ETAS 6598 jens.guballa@etas.com 6600 Felix Guenther 6601 TU Darmstadt 6602 mail@felixguenther.info 6604 Vipul Gupta 6605 (co-author of [RFC4492]) 6606 Sun Microsystems Laboratories 6607 vipul.gupta@sun.com 6609 Chris Hawk 6610 (co-author of [RFC4492]) 6611 Corriente Networks LLC 6612 chris@corriente.net 6614 Kipp Hickman 6616 Alfred Hoenes 6618 David Hopwood 6619 Independent Consultant 6620 david.hopwood@blueyonder.co.uk 6622 Marko Horvat 6623 MPI-SWS 6624 mhorvat@mpi-sws.org 6626 Jonathan Hoyland 6627 Royal Holloway, University of London 6628 jonathan.hoyland@gmail.com 6630 Subodh Iyengar 6631 Facebook 6632 subodh@fb.com 6634 Benjamin Kaduk 6635 Akamai Technologies 6636 kaduk@mit.edu 6638 Hubert Kario 6639 Red Hat Inc. 6640 hkario@redhat.com 6642 Phil Karlton 6643 (co-author of SSL 3.0) 6645 Leon Klingele 6646 Independent 6647 mail@leonklingele.de 6649 Paul Kocher 6650 (co-author of SSL 3.0) 6651 Cryptography Research 6652 paul@cryptography.com 6653 Hugo Krawczyk 6654 IBM 6655 hugokraw@us.ibm.com 6657 Adam Langley 6658 (co-author of [RFC7627]) 6659 Google 6660 agl@google.com 6662 Olivier Levillain 6663 ANSSI 6664 olivier.levillain@ssi.gouv.fr 6666 Xiaoyin Liu 6667 University of North Carolina at Chapel Hill 6668 xiaoyin.l@outlook.com 6670 Ilari Liusvaara 6671 Independent 6672 ilariliusvaara@welho.com 6674 Atul Luykx 6675 K.U. Leuven 6676 atul.luykx@kuleuven.be 6678 Colm MacCarthaigh 6679 Amazon Web Services 6680 colm@allcosts.net 6682 Carl Mehner 6683 USAA 6684 carl.mehner@usaa.com 6686 Jan Mikkelsen 6687 Transactionware 6688 janm@transactionware.com 6690 Bodo Moeller 6691 (co-author of [RFC4492]) 6692 Google 6693 bodo@acm.org 6695 Kyle Nekritz 6696 Facebook 6697 knekritz@fb.com 6699 Erik Nygren 6700 Akamai Technologies 6701 erik+ietf@nygren.org 6703 Magnus Nystrom 6704 Microsoft 6705 mnystrom@microsoft.com 6707 Kazuho Oku 6708 DeNA Co., Ltd. 6709 kazuhooku@gmail.com 6711 Kenny Paterson 6712 Royal Holloway, University of London 6713 kenny.paterson@rhul.ac.uk 6715 Christopher Patton 6716 University of Florida 6717 cjpatton@ufl.edu 6719 Alfredo Pironti 6720 (co-author of [RFC7627]) 6721 INRIA 6722 alfredo.pironti@inria.fr 6724 Andrei Popov 6725 Microsoft 6726 andrei.popov@microsoft.com 6728 Marsh Ray 6729 (co-author of [RFC7627]) 6730 Microsoft 6731 maray@microsoft.com 6733 Robert Relyea 6734 Netscape Communications 6735 relyea@netscape.com 6737 Kyle Rose 6738 Akamai Technologies 6739 krose@krose.org 6741 Jim Roskind 6742 Amazon 6743 jroskind@amazon.com 6745 Michael Sabin 6747 Joe Salowey 6748 Tableau Software 6749 joe@salowey.net 6751 Rich Salz 6752 Akamai 6753 rsalz@akamai.com 6755 David Schinazi 6756 Apple Inc. 6757 dschinazi@apple.com 6759 Sam Scott 6760 Royal Holloway, University of London 6761 me@samjs.co.uk 6763 Thomas Shrimpton 6764 University of Florida 6765 teshrim@ufl.edu 6767 Dan Simon 6768 Microsoft, Inc. 6769 dansimon@microsoft.com 6771 Brian Smith 6772 Independent 6773 brian@briansmith.org 6775 Brian Sniffen 6776 Akamai Technologies 6777 ietf@bts.evenmere.org 6779 Nick Sullivan 6780 Cloudflare Inc. 6781 nick@cloudflare.com 6783 Bjoern Tackmann 6784 University of California, San Diego 6785 btackmann@eng.ucsd.edu 6787 Tim Taubert 6788 Mozilla 6789 ttaubert@mozilla.com 6791 Martin Thomson 6792 Mozilla 6793 mt@mozilla.com 6795 Hannes Tschofenig 6796 Arm Limited 6797 Hannes.Tschofenig@arm.com 6799 Sean Turner 6800 sn3rd 6801 sean@sn3rd.com 6803 Steven Valdez 6804 Google 6805 svaldez@google.com 6807 Filippo Valsorda 6808 Cloudflare Inc. 6809 filippo@cloudflare.com 6811 Thyla van der Merwe 6812 Royal Holloway, University of London 6813 tjvdmerwe@gmail.com 6815 Victor Vasiliev 6816 Google 6817 vasilvv@google.com 6819 Hoeteck Wee 6820 Ecole Normale Superieure, Paris 6821 hoeteck@alum.mit.edu 6823 Tom Weinstein 6825 David Wong 6826 NCC Group 6827 david.wong@nccgroup.trust 6829 Christopher A. Wood 6830 Apple Inc. 6831 cawood@apple.com 6833 Tim Wright 6834 Vodafone 6835 timothy.wright@vodafone.com 6837 Peter Wu 6838 Independent 6839 peter@lekensteyn.nl 6841 Kazu Yamamoto 6842 Internet Initiative Japan Inc. 6843 kazu@iij.ad.jp 6845 Author's Address 6847 Eric Rescorla 6848 Mozilla 6850 Email: ekr@rtfm.com