idnits 2.17.1 draft-ietf-tls-tls13-26.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 33 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 RFC5077, but the abstract doesn't seem to mention this, which it should. -- 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 RFC5246, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC6066, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC5705, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates 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 (March 04, 2018) is 2245 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 1014, but not defined -- Looks like a reference, but probably isn't: '0' on line 1137 -- Looks like a reference, but probably isn't: '1' on line 6755 -- Looks like a reference, but probably isn't: '3' on line 1212 -- Looks like a reference, but probably isn't: '9' on line 1177 -- Looks like a reference, but probably isn't: '2' on line 5597 -- Looks like a reference, but probably isn't: '4' on line 1213 -- Looks like a reference, but probably isn't: '8' on line 1214 -- Looks like a reference, but probably isn't: '10' on line 1330 -- Looks like a reference, but probably isn't: '32' on line 5595 -- Possible downref: Non-RFC (?) normative reference: ref. 'DH' -- Possible downref: Non-RFC (?) normative reference: ref. 'GCM' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Obsolete normative reference: RFC 6961 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6962 (Obsoleted by RFC 9162) ** Downref: Normative reference to an Informational RFC: RFC 6979 ** Obsolete normative reference: RFC 7507 (Obsoleted by RFC 8996) ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) ** Downref: Normative reference to an Informational RFC: RFC 7748 ** Downref: Normative reference to an Informational RFC: RFC 8017 ** Downref: Normative reference to an Informational RFC: RFC 8032 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- Possible downref: Non-RFC (?) normative reference: ref. 'X962' -- No information found for draft-10 - is the name correct? -- No information found for draft-10 - is the name correct? -- Duplicate reference: draft-10, mentioned in 'DFGS16', was also mentioned in 'DFGS15'. == Outdated reference: A later version (-05) exists of draft-ietf-tls-iana-registry-updates-04 == Outdated reference: A later version (-07) exists of draft-ietf-tls-tls13-vectors-03 -- 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 (==), 33 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Rescorla 3 Internet-Draft RTFM, Inc. 4 Obsoletes: 5077, 5246, 6961 (if March 04, 2018 5 approved) 6 Updates: 4492, 5705, 6066 (if approved) 7 Intended status: Standards Track 8 Expires: September 5, 2018 10 The Transport Layer Security (TLS) Protocol Version 1.3 11 draft-ietf-tls-tls13-26 13 Abstract 15 This document specifies version 1.3 of the Transport Layer Security 16 (TLS) protocol. TLS allows client/server applications to communicate 17 over the Internet in a way that is designed to prevent eavesdropping, 18 tampering, and message forgery. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 5, 2018. 37 Copyright Notice 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 This document may contain material from IETF Documents or IETF 53 Contributions published or made publicly available before November 54 10, 2008. The person(s) controlling the copyright in some of this 55 material may not have granted the IETF Trust the right to allow 56 modifications of such material outside the IETF Standards Process. 57 Without obtaining an adequate license from the person(s) controlling 58 the copyright in such materials, this document may not be modified 59 outside the IETF Standards Process, and derivative works of it may 60 not be created outside the IETF Standards Process, except to format 61 it for publication as an RFC or to translate it into languages other 62 than English. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 67 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 6 68 1.2. Change Log . . . . . . . . . . . . . . . . . . . . . . . 7 69 1.3. Major Differences from TLS 1.2 . . . . . . . . . . . . . 15 70 1.4. Updates Affecting TLS 1.2 . . . . . . . . . . . . . . . . 17 71 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 17 72 2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . . . 20 73 2.2. Resumption and Pre-Shared Key (PSK) . . . . . . . . . . . 21 74 2.3. 0-RTT Data . . . . . . . . . . . . . . . . . . . . . . . 23 75 3. Presentation Language . . . . . . . . . . . . . . . . . . . . 25 76 3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 25 77 3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 25 78 3.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 26 79 3.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 27 80 3.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 27 81 3.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 28 82 3.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 28 83 3.8. Variants . . . . . . . . . . . . . . . . . . . . . . . . 29 84 4. Handshake Protocol . . . . . . . . . . . . . . . . . . . . . 30 85 4.1. Key Exchange Messages . . . . . . . . . . . . . . . . . . 31 86 4.1.1. Cryptographic Negotiation . . . . . . . . . . . . . . 31 87 4.1.2. Client Hello . . . . . . . . . . . . . . . . . . . . 32 88 4.1.3. Server Hello . . . . . . . . . . . . . . . . . . . . 35 89 4.1.4. Hello Retry Request . . . . . . . . . . . . . . . . . 37 90 4.2. Extensions . . . . . . . . . . . . . . . . . . . . . . . 39 91 4.2.1. Supported Versions . . . . . . . . . . . . . . . . . 42 92 4.2.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . 44 93 4.2.3. Signature Algorithms . . . . . . . . . . . . . . . . 44 94 4.2.4. Certificate Authorities . . . . . . . . . . . . . . . 48 95 4.2.5. OID Filters . . . . . . . . . . . . . . . . . . . . . 49 96 4.2.6. Post-Handshake Client Authentication . . . . . . . . 50 97 4.2.7. Negotiated Groups . . . . . . . . . . . . . . . . . . 50 98 4.2.8. Key Share . . . . . . . . . . . . . . . . . . . . . . 52 99 4.2.9. Pre-Shared Key Exchange Modes . . . . . . . . . . . . 55 100 4.2.10. Early Data Indication . . . . . . . . . . . . . . . . 56 101 4.2.11. Pre-Shared Key Extension . . . . . . . . . . . . . . 58 102 4.3. Server Parameters . . . . . . . . . . . . . . . . . . . . 62 103 4.3.1. Encrypted Extensions . . . . . . . . . . . . . . . . 62 104 4.3.2. Certificate Request . . . . . . . . . . . . . . . . . 63 105 4.4. Authentication Messages . . . . . . . . . . . . . . . . . 64 106 4.4.1. The Transcript Hash . . . . . . . . . . . . . . . . . 65 107 4.4.2. Certificate . . . . . . . . . . . . . . . . . . . . . 66 108 4.4.3. Certificate Verify . . . . . . . . . . . . . . . . . 71 109 4.4.4. Finished . . . . . . . . . . . . . . . . . . . . . . 73 110 4.5. End of Early Data . . . . . . . . . . . . . . . . . . . . 75 111 4.6. Post-Handshake Messages . . . . . . . . . . . . . . . . . 75 112 4.6.1. New Session Ticket Message . . . . . . . . . . . . . 75 113 4.6.2. Post-Handshake Authentication . . . . . . . . . . . . 78 114 4.6.3. Key and IV Update . . . . . . . . . . . . . . . . . . 78 115 5. Record Protocol . . . . . . . . . . . . . . . . . . . . . . . 79 116 5.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 80 117 5.2. Record Payload Protection . . . . . . . . . . . . . . . . 82 118 5.3. Per-Record Nonce . . . . . . . . . . . . . . . . . . . . 84 119 5.4. Record Padding . . . . . . . . . . . . . . . . . . . . . 85 120 5.5. Limits on Key Usage . . . . . . . . . . . . . . . . . . . 86 121 6. Alert Protocol . . . . . . . . . . . . . . . . . . . . . . . 86 122 6.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 88 123 6.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 89 124 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 92 125 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 92 126 7.2. Updating Traffic Keys and IVs . . . . . . . . . . . . . . 95 127 7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 96 128 7.4. (EC)DHE Shared Secret Calculation . . . . . . . . . . . . 96 129 7.4.1. Finite Field Diffie-Hellman . . . . . . . . . . . . . 97 130 7.4.2. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 97 131 7.5. Exporters . . . . . . . . . . . . . . . . . . . . . . . . 98 132 8. 0-RTT and Anti-Replay . . . . . . . . . . . . . . . . . . . . 98 133 8.1. Single-Use Tickets . . . . . . . . . . . . . . . . . . . 100 134 8.2. Client Hello Recording . . . . . . . . . . . . . . . . . 100 135 8.3. Freshness Checks . . . . . . . . . . . . . . . . . . . . 101 136 9. Compliance Requirements . . . . . . . . . . . . . . . . . . . 103 137 9.1. Mandatory-to-Implement Cipher Suites . . . . . . . . . . 103 138 9.2. Mandatory-to-Implement Extensions . . . . . . . . . . . . 103 139 9.3. Protocol Invariants . . . . . . . . . . . . . . . . . . . 104 140 10. Security Considerations . . . . . . . . . . . . . . . . . . . 106 141 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 106 142 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 107 143 12.1. Normative References . . . . . . . . . . . . . . . . . . 107 144 12.2. Informative References . . . . . . . . . . . . . . . . . 110 146 Appendix A. State Machine . . . . . . . . . . . . . . . . . . . 118 147 A.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 118 148 A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 119 149 Appendix B. Protocol Data Structures and Constant Values . . . . 119 150 B.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 120 151 B.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 120 152 B.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 122 153 B.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 122 154 B.3.2. Server Parameters Messages . . . . . . . . . . . . . 127 155 B.3.3. Authentication Messages . . . . . . . . . . . . . . . 128 156 B.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 129 157 B.3.5. Updating Keys . . . . . . . . . . . . . . . . . . . . 129 158 B.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 130 159 Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 131 160 C.1. Random Number Generation and Seeding . . . . . . . . . . 131 161 C.2. Certificates and Authentication . . . . . . . . . . . . . 132 162 C.3. Implementation Pitfalls . . . . . . . . . . . . . . . . . 132 163 C.4. Client Tracking Prevention . . . . . . . . . . . . . . . 133 164 C.5. Unauthenticated Operation . . . . . . . . . . . . . . . . 134 165 Appendix D. Backward Compatibility . . . . . . . . . . . . . . . 134 166 D.1. Negotiating with an older server . . . . . . . . . . . . 135 167 D.2. Negotiating with an older client . . . . . . . . . . . . 136 168 D.3. 0-RTT backwards compatibility . . . . . . . . . . . . . . 136 169 D.4. Middlebox Compatibility Mode . . . . . . . . . . . . . . 136 170 D.5. Backwards Compatibility Security Restrictions . . . . . . 137 171 Appendix E. Overview of Security Properties . . . . . . . . . . 138 172 E.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 138 173 E.1.1. Key Derivation and HKDF . . . . . . . . . . . . . . . 141 174 E.1.2. Client Authentication . . . . . . . . . . . . . . . . 142 175 E.1.3. 0-RTT . . . . . . . . . . . . . . . . . . . . . . . . 142 176 E.1.4. Exporter Independence . . . . . . . . . . . . . . . . 142 177 E.1.5. Post-Compromise Security . . . . . . . . . . . . . . 143 178 E.1.6. External References . . . . . . . . . . . . . . . . . 143 179 E.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 143 180 E.2.1. External References . . . . . . . . . . . . . . . . . 144 181 E.3. Traffic Analysis . . . . . . . . . . . . . . . . . . . . 144 182 E.4. Side Channel Attacks . . . . . . . . . . . . . . . . . . 145 183 E.5. Replay Attacks on 0-RTT . . . . . . . . . . . . . . . . . 146 184 E.5.1. Replay and Exporters . . . . . . . . . . . . . . . . 147 185 E.6. Attacks on Static RSA . . . . . . . . . . . . . . . . . . 148 186 Appendix F. Working Group Information . . . . . . . . . . . . . 148 187 Appendix G. Contributors . . . . . . . . . . . . . . . . . . . . 148 188 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 155 190 1. Introduction 192 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 193 draft is maintained in GitHub. Suggested changes should be submitted 194 as pull requests at https://github.com/tlswg/tls13-spec. 195 Instructions are on that page as well. Editorial changes can be 196 managed in GitHub, but any substantive change should be discussed on 197 the TLS mailing list. 199 The primary goal of TLS is to provide a secure channel between two 200 communicating peers. Specifically, the channel should provide the 201 following properties: 203 - Authentication: The server side of the channel is always 204 authenticated; the client side is optionally authenticated. 205 Authentication can happen via asymmetric cryptography (e.g., RSA 206 [RSA], ECDSA [ECDSA], EdDSA [RFC8032]) or a pre-shared key (PSK). 208 - Confidentiality: Data sent over the channel after establishment is 209 only visible to the endpoints. TLS does not hide the length of 210 the data it transmits, though endpoints are able to pad TLS 211 records in order to obscure lengths and improve protection against 212 traffic analysis techniques. 214 - Integrity: Data sent over the channel after establishment cannot 215 be modified by attackers. 217 These properties should be true even in the face of an attacker who 218 has complete control of the network, as described in [RFC3552]. See 219 Appendix E for a more complete statement of the relevant security 220 properties. 222 TLS consists of two primary components: 224 - A handshake protocol (Section 4) that authenticates the 225 communicating parties, negotiates cryptographic modes and 226 parameters, and establishes shared keying material. The handshake 227 protocol is designed to resist tampering; an active attacker 228 should not be able to force the peers to negotiate different 229 parameters than they would if the connection were not under 230 attack. 232 - A record protocol (Section 5) that uses the parameters established 233 by the handshake protocol to protect traffic between the 234 communicating peers. The record protocol divides traffic up into 235 a series of records, each of which is independently protected 236 using the traffic keys. 238 TLS is application protocol independent; higher-level protocols can 239 layer on top of TLS transparently. The TLS standard, however, does 240 not specify how protocols add security with TLS; how to initiate TLS 241 handshaking and how to interpret the authentication certificates 242 exchanged are left to the judgment of the designers and implementors 243 of protocols that run on top of TLS. 245 This document defines TLS version 1.3. While TLS 1.3 is not directly 246 compatible with previous versions, all versions of TLS incorporate a 247 versioning mechanism which allows clients and servers to 248 interoperably negotiate a common version if one is supported by both 249 peers. 251 This document supersedes and obsoletes previous versions of TLS 252 including version 1.2 [RFC5246]. It also obsoletes the TLS ticket 253 mechanism defined in [RFC5077] and replaces it with the mechanism 254 defined in Section 2.2. Section 4.2.7 updates [RFC4492] by modifying 255 the protocol attributes used to negotiate Elliptic Curves. Because 256 TLS 1.3 changes the way keys are derived it updates [RFC5705] as 257 described in Section 7.5 it also changes how OCSP messages are 258 carried and therefore updates [RFC6066] and obsoletes [RFC6961] as 259 described in section Section 4.4.2.1. 261 1.1. Conventions and Terminology 263 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 264 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 265 "OPTIONAL" in this document are to be interpreted as described in BCP 266 14 [RFC2119] [RFC8174] when, and only when, they appear in all 267 capitals, as shown here. 269 The following terms are used: 271 client: The endpoint initiating the TLS connection. 273 connection: A transport-layer connection between two endpoints. 275 endpoint: Either the client or server of the connection. 277 handshake: An initial negotiation between client and server that 278 establishes the parameters of their subsequent interactions. 280 peer: An endpoint. When discussing a particular endpoint, "peer" 281 refers to the endpoint that is not the primary subject of discussion. 283 receiver: An endpoint that is receiving records. 285 sender: An endpoint that is transmitting records. 287 server: The endpoint which did not initiate the TLS connection. 289 1.2. Change Log 291 RFC EDITOR PLEASE DELETE THIS SECTION. 293 (*) indicates changes to the wire protocol which may require 294 implementations to update. 296 draft-26 - Clarify that you can't negotiate pre-TLS 1.3 with 297 supported_versions. 299 draft-25 - Add the header to additional data (*) 301 - Minor clarifications. 303 - IANA cleanup. 305 draft-24 307 - Require that CH2 have version 0303 (*) 309 - Some clarifications 311 draft-23 - Renumber key_share (*) 313 - Add a new extension and new code points to allow negotiating PSS 314 separately for certificates and CertificateVerify (*) 316 - Slightly restrict when CCS must be accepted to make implementation 317 easier. 319 - Document protocol invariants 321 - Add some text on the security of static RSA. 323 draft-22 - Implement changes for improved middlebox penetration (*) 325 - Move server_certificate_type to encrypted extensions (*) 327 - Allow resumption with a different SNI (*) 329 - Padding extension can change on HRR (*) 331 - Allow an empty ticket_nonce (*) 333 - Remove requirement to immediately respond to close_notify with 334 close_notify (allowing half-close) 336 - Add a per-ticket nonce so that each ticket is associated with a 337 different PSK (*). 339 - Clarify that clients should send alerts with the handshake key if 340 possible. 342 - Update state machine to show rekeying events 344 - Add discussion of 0-RTT and replay. Recommend that 345 implementations implement some anti-replay mechanism. 347 draft-20 349 - Add "post_handshake_auth" extension to negotiate post-handshake 350 authentication (*). 352 - Shorten labels for HKDF-Expand-Label so that we can fit within one 353 compression block (*). 355 - Define how RFC 7250 works (*). 357 - Re-enable post-handshake client authentication even when you do 358 PSK. The previous prohibition was editorial error. 360 - Remove cert_type and user_mapping, which don't work on TLS 1.3 361 anyway. 363 - Added the no_application_protocol alert from [RFC7301] to the list 364 of extensions. 366 - Added discussion of traffic analysis and side channel attacks. 368 draft-19 370 - Hash context_value input to Exporters (*) 372 - Add an additional Derive-Secret stage to Exporters (*). 374 - Hash ClientHello1 in the transcript when HRR is used. This 375 reduces the state that needs to be carried in cookies. (*) 377 - Restructure CertificateRequest to have the selectors in 378 extensions. This also allowed defining a 379 "certificate_authorities" extension which can be used by the 380 client instead of trusted_ca_keys (*). 382 - Tighten record framing requirements and require checking of them 383 (*). 385 - Consolidate "ticket_early_data_info" and "early_data" into a 386 single extension (*). 388 - Change end_of_early_data to be a handshake message (*). 390 - Add pre-extract Derive-Secret stages to key schedule (*). 392 - Remove spurious requirement to implement "pre_shared_key". 394 - Clarify location of "early_data" from server (it goes in EE, as 395 indicated by the table in S 10). 397 - Require peer public key validation 399 - Add state machine diagram. 401 draft-18 403 - Remove unnecessary resumption_psk which is the only thing expanded 404 from the resumption master secret. (*). 406 - Fix signature_algorithms entry in extensions table. 408 - Restate rule from RFC 6066 that you can't resume unless SNI is the 409 same. 411 draft-17 413 - Remove 0-RTT Finished and resumption_context, and replace with a 414 psk_binder field in the PSK itself (*) 416 - Restructure PSK key exchange negotiation modes (*) 418 - Add max_early_data_size field to TicketEarlyDataInfo (*) 420 - Add a 0-RTT exporter and change the transcript for the regular 421 exporter (*) 423 - Merge TicketExtensions and Extensions registry. Changes 424 ticket_early_data_info code point (*) 426 - Replace Client.key_shares in response to HRR (*) 428 - Remove redundant labels for traffic key derivation (*) 429 - Harmonize requirements about cipher suite matching: for resumption 430 you need to match KDF but for 0-RTT you need whole cipher suite. 431 This allows PSKs to actually negotiate cipher suites. (*) 433 - Move SCT and OCSP into Certificate.extensions (*) 435 - Explicitly allow non-offered extensions in NewSessionTicket 437 - Explicitly allow predicting client Finished for NST 439 - Clarify conditions for allowing 0-RTT with PSK 441 draft-16 443 - Revise version negotiation (*) 445 - Change RSASSA-PSS and EdDSA SignatureScheme codepoints for better 446 backwards compatibility (*) 448 - Move HelloRetryRequest.selected_group to an extension (*) 450 - Clarify the behavior of no exporter context and make it the same 451 as an empty context.(*) 453 - New KeyUpdate format that allows for requesting/not-requesting an 454 answer. This also means changes to the key schedule to support 455 independent updates (*) 457 - New certificate_required alert (*) 459 - Forbid CertificateRequest with 0-RTT and PSK. 461 - Relax requirement to check SNI for 0-RTT. 463 draft-15 465 - New negotiation syntax as discussed in Berlin (*) 467 - Require CertificateRequest.context to be empty during handshake 468 (*) 470 - Forbid empty tickets (*) 472 - Forbid application data messages in between post-handshake 473 messages from the same flight (*) 475 - Clean up alert guidance (*) 476 - Clearer guidance on what is needed for TLS 1.2. 478 - Guidance on 0-RTT time windows. 480 - Rename a bunch of fields. 482 - Remove old PRNG text. 484 - Explicitly require checking that handshake records not span key 485 changes. 487 draft-14 489 - Allow cookies to be longer (*) 491 - Remove the "context" from EarlyDataIndication as it was undefined 492 and nobody used it (*) 494 - Remove 0-RTT EncryptedExtensions and replace the ticket_age 495 extension with an obfuscated version. Also necessitates a change 496 to NewSessionTicket (*). 498 - Move the downgrade sentinel to the end of ServerHello.Random to 499 accommodate tlsdate (*). 501 - Define ecdsa_sha1 (*). 503 - Allow resumption even after fatal alerts. This matches current 504 practice. 506 - Remove non-closure warning alerts. Require treating unknown 507 alerts as fatal. 509 - Make the rules for accepting 0-RTT less restrictive. 511 - Clarify 0-RTT backward-compatibility rules. 513 - Clarify how 0-RTT and PSK identities interact. 515 - Add a section describing the data limits for each cipher. 517 - Major editorial restructuring. 519 - Replace the Security Analysis section with a WIP draft. 521 draft-13 523 - Allow server to send SupportedGroups. 525 - Remove 0-RTT client authentication 527 - Remove (EC)DHE 0-RTT. 529 - Flesh out 0-RTT PSK mode and shrink EarlyDataIndication 531 - Turn PSK-resumption response into an index to save room 533 - Move CertificateStatus to an extension 535 - Extra fields in NewSessionTicket. 537 - Restructure key schedule and add a resumption_context value. 539 - Require DH public keys and secrets to be zero-padded to the size 540 of the group. 542 - Remove the redundant length fields in KeyShareEntry. 544 - Define a cookie field for HRR. 546 draft-12 548 - Provide a list of the PSK cipher suites. 550 - Remove the ability for the ServerHello to have no extensions (this 551 aligns the syntax with the text). 553 - Clarify that the server can send application data after its first 554 flight (0.5 RTT data) 556 - Revise signature algorithm negotiation to group hash, signature 557 algorithm, and curve together. This is backwards compatible. 559 - Make ticket lifetime mandatory and limit it to a week. 561 - Make the purpose strings lower-case. This matches how people are 562 implementing for interop. 564 - Define exporters. 566 - Editorial cleanup 568 draft-11 570 - Port the CFRG curves & signatures work from RFC4492bis. 572 - Remove sequence number and version from additional_data, which is 573 now empty. 575 - Reorder values in HkdfLabel. 577 - Add support for version anti-downgrade mechanism. 579 - Update IANA considerations section and relax some of the policies. 581 - Unify authentication modes. Add post-handshake client 582 authentication. 584 - Remove early_handshake content type. Terminate 0-RTT data with an 585 alert. 587 - Reset sequence number upon key change (as proposed by Fournet et 588 al.) 590 draft-10 592 - Remove ClientCertificateTypes field from CertificateRequest and 593 add extensions. 595 - Merge client and server key shares into a single extension. 597 draft-09 599 - Change to RSA-PSS signatures for handshake messages. 601 - Remove support for DSA. 603 - Update key schedule per suggestions by Hugo, Hoeteck, and Bjoern 604 Tackmann. 606 - Add support for per-record padding. 608 - Switch to encrypted record ContentType. 610 - Change HKDF labeling to include protocol version and value 611 lengths. 613 - Shift the final decision to abort a handshake due to incompatible 614 certificates to the client rather than having servers abort early. 616 - Deprecate SHA-1 with signatures. 618 - Add MTI algorithms. 620 - Remove support for weak and lesser used named curves. 622 - Remove support for MD5 and SHA-224 hashes with signatures. 624 - Update lists of available AEAD cipher suites and error alerts. 626 - Reduce maximum permitted record expansion for AEAD from 2048 to 627 256 octets. 629 - Require digital signatures even when a previous configuration is 630 used. 632 - Merge EarlyDataIndication and KnownConfiguration. 634 - Change code point for server_configuration to avoid collision with 635 server_hello_done. 637 - Relax certificate_list ordering requirement to match current 638 practice. 640 draft-07 642 - Integration of semi-ephemeral DH proposal. 644 - Add initial 0-RTT support. 646 - Remove resumption and replace with PSK + tickets. 648 - Move ClientKeyShare into an extension. 650 - Move to HKDF. 652 draft-06 654 - Prohibit RC4 negotiation for backwards compatibility. 656 - Freeze & deprecate record layer version field. 658 - Update format of signatures with context. 660 - Remove explicit IV. 662 draft-05 664 - Prohibit SSL negotiation for backwards compatibility. 666 - Fix which MS is used for exporters. 668 draft-04 670 - Modify key computations to include session hash. 672 - Remove ChangeCipherSpec. 674 - Renumber the new handshake messages to be somewhat more consistent 675 with existing convention and to remove a duplicate registration. 677 - Remove renegotiation. 679 - Remove point format negotiation. 681 draft-03 683 - Remove GMT time. 685 - Merge in support for ECC from RFC 4492 but without explicit 686 curves. 688 - Remove the unnecessary length field from the AD input to AEAD 689 ciphers. 691 - Rename {Client,Server}KeyExchange to {Client,Server}KeyShare. 693 - Add an explicit HelloRetryRequest to reject the client's. 695 draft-02 697 - Increment version number. 699 - Rework handshake to provide 1-RTT mode. 701 - Remove custom DHE groups. 703 - Remove support for compression. 705 - Remove support for static RSA and DH key exchange. 707 - Remove support for non-AEAD ciphers. 709 1.3. Major Differences from TLS 1.2 711 The following is a list of the major functional differences between 712 TLS 1.2 and TLS 1.3. It is not intended to be exhaustive and there 713 are many minor differences. 715 - The list of supported symmetric algorithms has been pruned of all 716 algorithms that are considered legacy. Those that remain all use 717 Authenticated Encryption with Associated Data (AEAD) algorithms. 718 The ciphersuite concept has been changed to separate the 719 authentication and key exchange mechanisms from the record 720 protection algorithm (including secret key length) and a hash to 721 be used with the key derivation function and HMAC. 723 - A 0-RTT mode was added, saving a round-trip at connection setup 724 for some application data, at the cost of certain security 725 properties. 727 - Static RSA and Diffie-Hellman cipher suites have been removed; all 728 public-key based key exchange mechanisms now provide forward 729 secrecy. 731 - All handshake messages after the ServerHello are now encrypted. 732 The newly introduced EncryptedExtension message allows various 733 extensions previously sent in clear in the ServerHello to also 734 enjoy confidentiality protection from active attackers. 736 - The key derivation functions have been re-designed. The new 737 design allows easier analysis by cryptographers due to their 738 improved key separation properties. The HMAC-based Extract-and- 739 Expand Key Derivation Function (HKDF) is used as an underlying 740 primitive. 742 - The handshake state machine has been significantly restructured to 743 be more consistent and to remove superfluous messages such as 744 ChangeCipherSpec. 746 - Elliptic curve algorithms are now in the base spec and includes 747 new signature algorithms, such as ed25519 and ed448. TLS 1.3 748 removed point format negotiation in favor of a single point format 749 for each curve. 751 - Other cryptographic improvements including the removal of 752 compression and custom DHE groups, changing the RSA padding to use 753 PSS, and the removal of DSA. 755 - The TLS 1.2 version negotiation mechanism has been deprecated in 756 favor of a version list in an extension. This increases 757 compatibility with servers which incorrectly implemented version 758 negotiation. 760 - Session resumption with and without server-side state as well as 761 the PSK-based ciphersuites of earlier TLS versions have been 762 replaced by a single new PSK exchange. 764 - Updated references to point to the updated versions of RFCs, as 765 appropriate (e.g., RFC 5280 rather than RFC 3280). 767 1.4. Updates Affecting TLS 1.2 769 This document defines several changes that optionally affect 770 implementations of TLS 1.2: 772 - A version downgrade protection mechanism is described in 773 Section 4.1.3. 775 - RSASSA-PSS signature schemes are defined in Section 4.2.3. 777 - The "supported_versions" ClientHello extension can be used to 778 negotiate the version of TLS to use, in preference to the 779 legacy_version field of the ClientHello. 781 An implementation of TLS 1.3 that also supports TLS 1.2 might need to 782 include changes to support these changes even when TLS 1.3 is not in 783 use. See the referenced sections for more details. 785 Additionally, this document clarifies some compliance requirements 786 for earlier versions of TLS; see Section 9.3. 788 2. Protocol Overview 790 The cryptographic parameters used by the secure channel are produced 791 by the TLS handshake protocol. This sub-protocol of TLS is used by 792 the client and server when first communicating with each other. The 793 handshake protocol allows peers to negotiate a protocol version, 794 select cryptographic algorithms, optionally authenticate each other, 795 and establish shared secret keying material. Once the handshake is 796 complete, the peers use the established keys to protect the 797 application layer traffic. 799 A failure of the handshake or other protocol error triggers the 800 termination of the connection, optionally preceded by an alert 801 message (Section 6). 803 TLS supports three basic key exchange modes: 805 - (EC)DHE (Diffie-Hellman over either finite fields or elliptic 806 curves) 808 - PSK-only 810 - PSK with (EC)DHE 811 Figure 1 below shows the basic full TLS handshake: 813 Client Server 815 Key ^ ClientHello 816 Exch | + key_share* 817 | + signature_algorithms* 818 | + psk_key_exchange_modes* 819 v + pre_shared_key* --------> 820 ServerHello ^ Key 821 + key_share* | Exch 822 + pre_shared_key* v 823 {EncryptedExtensions} ^ Server 824 {CertificateRequest*} v Params 825 {Certificate*} ^ 826 {CertificateVerify*} | Auth 827 {Finished} v 828 <-------- [Application Data*] 829 ^ {Certificate*} 830 Auth | {CertificateVerify*} 831 v {Finished} --------> 832 [Application Data] <-------> [Application Data] 834 + Indicates noteworthy extensions sent in the 835 previously noted message. 837 * Indicates optional or situation-dependent 838 messages/extensions that are not always sent. 840 {} Indicates messages protected using keys 841 derived from a [sender]_handshake_traffic_secret. 843 [] Indicates messages protected using keys 844 derived from [sender]_application_traffic_secret_N 846 Figure 1: Message flow for full TLS Handshake 848 The handshake can be thought of as having three phases (indicated in 849 the diagram above): 851 - Key Exchange: Establish shared keying material and select the 852 cryptographic parameters. Everything after this phase is 853 encrypted. 855 - Server Parameters: Establish other handshake parameters (whether 856 the client is authenticated, application layer protocol support, 857 etc.). 859 - Authentication: Authenticate the server (and optionally the 860 client) and provide key confirmation and handshake integrity. 862 In the Key Exchange phase, the client sends the ClientHello 863 (Section 4.1.2) message, which contains a random nonce 864 (ClientHello.random); its offered protocol versions; a list of 865 symmetric cipher/HKDF hash pairs; either a set of Diffie-Hellman key 866 shares (in the "key_share" extension Section 4.2.8), a set of pre- 867 shared key labels (in the "pre_shared_key" extension Section 4.2.11) 868 or both; and potentially additional extensions. 870 The server processes the ClientHello and determines the appropriate 871 cryptographic parameters for the connection. It then responds with 872 its own ServerHello (Section 4.1.3), which indicates the negotiated 873 connection parameters. The combination of the ClientHello and the 874 ServerHello determines the shared keys. If (EC)DHE key establishment 875 is in use, then the ServerHello contains a "key_share" extension with 876 the server's ephemeral Diffie-Hellman share which MUST be in the same 877 group as one of the client's shares. If PSK key establishment is in 878 use, then the ServerHello contains a "pre_shared_key" extension 879 indicating which of the client's offered PSKs was selected. Note 880 that implementations can use (EC)DHE and PSK together, in which case 881 both extensions will be supplied. 883 The server then sends two messages to establish the Server 884 Parameters: 886 EncryptedExtensions: responses to ClientHello extensions that are 887 not required to determine the cryptographic parameters, other than 888 those that are specific to individual certificates. 889 [Section 4.3.1] 891 CertificateRequest: if certificate-based client authentication is 892 desired, the desired parameters for that certificate. This 893 message is omitted if client authentication is not desired. 894 [Section 4.3.2] 896 Finally, the client and server exchange Authentication messages. TLS 897 uses the same set of messages every time that authentication is 898 needed. Specifically: 900 Certificate: the certificate of the endpoint and any per-certificate 901 extensions. This message is omitted by the server if not 902 authenticating with a certificate and by the client if the server 903 did not send CertificateRequest (thus indicating that the client 904 should not authenticate with a certificate). Note that if raw 905 public keys [RFC7250] or the cached information extension 906 [RFC7924] are in use, then this message will not contain a 907 certificate but rather some other value corresponding to the 908 server's long-term key. [Section 4.4.2] 910 CertificateVerify: a signature over the entire handshake using the 911 private key corresponding to the public key in the Certificate 912 message. This message is omitted if the endpoint is not 913 authenticating via a certificate. [Section 4.4.3] 915 Finished: a MAC (Message Authentication Code) over the entire 916 handshake. This message provides key confirmation, binds the 917 endpoint's identity to the exchanged keys, and in PSK mode also 918 authenticates the handshake. [Section 4.4.4] 920 Upon receiving the server's messages, the client responds with its 921 Authentication messages, namely Certificate and CertificateVerify (if 922 requested), and Finished. 924 At this point, the handshake is complete, and the client and server 925 derive the keying material required by the record layer to exchange 926 application-layer data protected through authenticated encryption. 927 Application data MUST NOT be sent prior to sending the Finished 928 message and until the record layer starts using encryption keys. 929 Note that while the server may send application data prior to 930 receiving the client's Authentication messages, any data sent at that 931 point is, of course, being sent to an unauthenticated peer. 933 2.1. Incorrect DHE Share 935 If the client has not provided a sufficient "key_share" extension 936 (e.g., it includes only DHE or ECDHE groups unacceptable to or 937 unsupported by the server), the server corrects the mismatch with a 938 HelloRetryRequest and the client needs to restart the handshake with 939 an appropriate "key_share" extension, as shown in Figure 2. If no 940 common cryptographic parameters can be negotiated, the server MUST 941 abort the handshake with an appropriate alert. 943 Client Server 945 ClientHello 946 + key_share --------> 947 <-------- HelloRetryRequest 948 + key_share 950 ClientHello 951 + key_share --------> 952 ServerHello 953 + key_share 954 {EncryptedExtensions} 955 {CertificateRequest*} 956 {Certificate*} 957 {CertificateVerify*} 958 {Finished} 959 <-------- [Application Data*] 960 {Certificate*} 961 {CertificateVerify*} 962 {Finished} --------> 963 [Application Data] <-------> [Application Data] 965 Figure 2: Message flow for a full handshake with mismatched 966 parameters 968 Note: The handshake transcript includes the initial ClientHello/ 969 HelloRetryRequest exchange; it is not reset with the new ClientHello. 971 TLS also allows several optimized variants of the basic handshake, as 972 described in the following sections. 974 2.2. Resumption and Pre-Shared Key (PSK) 976 Although TLS PSKs can be established out of band, PSKs can also be 977 established in a previous connection and then reused ("session 978 resumption"). Once a handshake has completed, the server can send to 979 the client a PSK identity that corresponds to a unique key derived 980 from the initial handshake (see Section 4.6.1). The client can then 981 use that PSK identity in future handshakes to negotiate the use of 982 the associated PSK. If the server accepts it, then the security 983 context of the new connection is cryptographically tied to the 984 original connection and the key derived from the initial handshake is 985 used to bootstrap the cryptographic state instead of a full 986 handshake. In TLS 1.2 and below, this functionality was provided by 987 "session IDs" and "session tickets" [RFC5077]. Both mechanisms are 988 obsoleted in TLS 1.3. 990 PSKs can be used with (EC)DHE key exchange in order to provide 991 forward secrecy in combination with shared keys, or can be used 992 alone, at the cost of losing forward secrecy for the application 993 data. 995 Figure 3 shows a pair of handshakes in which the first establishes a 996 PSK and the second uses it: 998 Client Server 1000 Initial Handshake: 1001 ClientHello 1002 + key_share --------> 1003 ServerHello 1004 + key_share 1005 {EncryptedExtensions} 1006 {CertificateRequest*} 1007 {Certificate*} 1008 {CertificateVerify*} 1009 {Finished} 1010 <-------- [Application Data*] 1011 {Certificate*} 1012 {CertificateVerify*} 1013 {Finished} --------> 1014 <-------- [NewSessionTicket] 1015 [Application Data] <-------> [Application Data] 1017 Subsequent Handshake: 1018 ClientHello 1019 + key_share* 1020 + pre_shared_key --------> 1021 ServerHello 1022 + pre_shared_key 1023 + key_share* 1024 {EncryptedExtensions} 1025 {Finished} 1026 <-------- [Application Data*] 1027 {Finished} --------> 1028 [Application Data] <-------> [Application Data] 1030 Figure 3: Message flow for resumption and PSK 1032 As the server is authenticating via a PSK, it does not send a 1033 Certificate or a CertificateVerify message. When a client offers 1034 resumption via PSK, it SHOULD also supply a "key_share" extension to 1035 the server to allow the server to decline resumption and fall back to 1036 a full handshake, if needed. The server responds with a 1037 "pre_shared_key" extension to negotiate use of PSK key establishment 1038 and can (as shown here) respond with a "key_share" extension to do 1039 (EC)DHE key establishment, thus providing forward secrecy. 1041 When PSKs are provisioned out of band, the PSK identity and the KDF 1042 hash algorithm to be used with the PSK MUST also be provisioned. 1044 Note: When using an out-of-band provisioned pre-shared secret, a 1045 critical consideration is using sufficient entropy during the key 1046 generation, as discussed in [RFC4086]. Deriving a shared secret 1047 from a password or other low-entropy sources is not secure. A 1048 low-entropy secret, or password, is subject to dictionary attacks 1049 based on the PSK binder. The specified PSK authentication is not 1050 a strong password-based authenticated key exchange even when used 1051 with Diffie-Hellman key establishment. 1053 2.3. 0-RTT Data 1055 When clients and servers share a PSK (either obtained externally or 1056 via a previous handshake), TLS 1.3 allows clients to send data on the 1057 first flight ("early data"). The client uses the PSK to authenticate 1058 the server and to encrypt the early data. 1060 As shown in Figure 4, the 0-RTT data is just added to the 1-RTT 1061 handshake in the first flight. The rest of the handshake uses the 1062 same messages as with a 1-RTT handshake with PSK resumption. 1064 Client Server 1066 ClientHello 1067 + early_data 1068 + key_share* 1069 + psk_key_exchange_modes 1070 + pre_shared_key 1071 (Application Data*) --------> 1072 ServerHello 1073 + pre_shared_key 1074 + key_share* 1075 {EncryptedExtensions} 1076 + early_data* 1077 {Finished} 1078 <-------- [Application Data*] 1079 (EndOfEarlyData) 1080 {Finished} --------> 1082 [Application Data] <-------> [Application Data] 1084 + Indicates noteworthy extensions sent in the 1085 previously noted message. 1087 * Indicates optional or situation-dependent 1088 messages/extensions that are not always sent. 1090 () Indicates messages protected using keys 1091 derived from client_early_traffic_secret. 1093 {} Indicates messages protected using keys 1094 derived from a [sender]_handshake_traffic_secret. 1096 [] Indicates messages protected using keys 1097 derived from [sender]_application_traffic_secret_N 1099 Figure 4: Message flow for a zero round trip handshake 1101 IMPORTANT NOTE: The security properties for 0-RTT data are weaker 1102 than those for other kinds of TLS data. Specifically: 1104 1. This data is not forward secret, as it is encrypted solely under 1105 keys derived using the offered PSK. 1107 2. There are no guarantees of non-replay between connections. 1108 Protection against replay for ordinary TLS 1.3 1-RTT data is 1109 provided via the server's Random value, but 0-RTT data does not 1110 depend on the ServerHello and therefore has weaker guarantees. 1111 This is especially relevant if the data is authenticated either 1112 with TLS client authentication or inside the application 1113 protocol. The same warnings apply to any use of the 1114 early_exporter_master_secret. 1116 0-RTT data cannot be duplicated within a connection (i.e., the server 1117 will not process the same data twice for the same connection) and an 1118 attacker will not be able to make 0-RTT data appear to be 1-RTT data 1119 (because it is protected with different keys.) Appendix E.5 contains 1120 a description of potential attacks and Section 8 describes mechanisms 1121 which the server can use to limit the impact of replay. 1123 3. Presentation Language 1125 This document deals with the formatting of data in an external 1126 representation. The following very basic and somewhat casually 1127 defined presentation syntax will be used. 1129 3.1. Basic Block Size 1131 The representation of all data items is explicitly specified. The 1132 basic data block size is one byte (i.e., 8 bits). Multiple byte data 1133 items are concatenations of bytes, from left to right, from top to 1134 bottom. From the byte stream, a multi-byte item (a numeric in the 1135 example) is formed (using C notation) by: 1137 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 1138 ... | byte[n-1]; 1140 This byte ordering for multi-byte values is the commonplace network 1141 byte order or big-endian format. 1143 3.2. Miscellaneous 1145 Comments begin with "/*" and end with "*/". 1147 Optional components are denoted by enclosing them in "[[ ]]" double 1148 brackets. 1150 Single-byte entities containing uninterpreted data are of type 1151 opaque. 1153 A type alias T' for an existing type T is defined by: 1155 T T'; 1157 3.3. Vectors 1159 A vector (single-dimensioned array) is a stream of homogeneous data 1160 elements. The size of the vector may be specified at documentation 1161 time or left unspecified until runtime. In either case, the length 1162 declares the number of bytes, not the number of elements, in the 1163 vector. The syntax for specifying a new type, T', that is a fixed- 1164 length vector of type T is 1166 T T'[n]; 1168 Here, T' occupies n bytes in the data stream, where n is a multiple 1169 of the size of T. The length of the vector is not included in the 1170 encoded stream. 1172 In the following example, Datum is defined to be three consecutive 1173 bytes that the protocol does not interpret, while Data is three 1174 consecutive Datum, consuming a total of nine bytes. 1176 opaque Datum[3]; /* three uninterpreted bytes */ 1177 Datum Data[9]; /* 3 consecutive 3-byte vectors */ 1179 Variable-length vectors are defined by specifying a subrange of legal 1180 lengths, inclusively, using the notation . When 1181 these are encoded, the actual length precedes the vector's contents 1182 in the byte stream. The length will be in the form of a number 1183 consuming as many bytes as required to hold the vector's specified 1184 maximum (ceiling) length. A variable-length vector with an actual 1185 length field of zero is referred to as an empty vector. 1187 T T'; 1189 In the following example, mandatory is a vector that must contain 1190 between 300 and 400 bytes of type opaque. It can never be empty. 1191 The actual length field consumes two bytes, a uint16, which is 1192 sufficient to represent the value 400 (see Section 3.4). Similarly, 1193 longer can represent up to 800 bytes of data, or 400 uint16 elements, 1194 and it may be empty. Its encoding will include a two-byte actual 1195 length field prepended to the vector. The length of an encoded 1196 vector must be an exact multiple of the length of a single element 1197 (e.g., a 17-byte vector of uint16 would be illegal). 1199 opaque mandatory<300..400>; 1200 /* length field is 2 bytes, cannot be empty */ 1201 uint16 longer<0..800>; 1202 /* zero to 400 16-bit unsigned integers */ 1204 3.4. Numbers 1206 The basic numeric data type is an unsigned byte (uint8). All larger 1207 numeric data types are formed from fixed-length series of bytes 1208 concatenated as described in Section 3.1 and are also unsigned. The 1209 following numeric types are predefined. 1211 uint8 uint16[2]; 1212 uint8 uint24[3]; 1213 uint8 uint32[4]; 1214 uint8 uint64[8]; 1216 All values, here and elsewhere in the specification, are stored in 1217 network byte (big-endian) order; the uint32 represented by the hex 1218 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 1220 3.5. Enumerateds 1222 An additional sparse data type is available called enum. Each 1223 definition is a different type. Only enumerateds of the same type 1224 may be assigned or compared. Every element of an enumerated must be 1225 assigned a value, as demonstrated in the following example. Since 1226 the elements of the enumerated are not ordered, they can be assigned 1227 any unique value, in any order. 1229 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 1231 Future extensions or additions to the protocol may define new values. 1232 Implementations need to be able to parse and ignore unknown values 1233 unless the definition of the field states otherwise. 1235 An enumerated occupies as much space in the byte stream as would its 1236 maximal defined ordinal value. The following definition would cause 1237 one byte to be used to carry fields of type Color. 1239 enum { red(3), blue(5), white(7) } Color; 1241 One may optionally specify a value without its associated tag to 1242 force the width definition without defining a superfluous element. 1244 In the following example, Taste will consume two bytes in the data 1245 stream but can only assume the values 1, 2, or 4 in the current 1246 version of the protocol. 1248 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 1250 The names of the elements of an enumeration are scoped within the 1251 defined type. In the first example, a fully qualified reference to 1252 the second element of the enumeration would be Color.blue. Such 1253 qualification is not required if the target of the assignment is well 1254 specified. 1256 Color color = Color.blue; /* overspecified, legal */ 1257 Color color = blue; /* correct, type implicit */ 1259 The names assigned to enumerateds do not need to be unique. The 1260 numerical value can describe a range over which the same name 1261 applies. The value includes the minimum and maximum inclusive values 1262 in that range, separated by two period characters. This is 1263 principally useful for reserving regions of the space. 1265 enum { sad(0), meh(1..254), happy(255) } Mood; 1267 3.6. Constructed Types 1269 Structure types may be constructed from primitive types for 1270 convenience. Each specification declares a new, unique type. The 1271 syntax for definition is much like that of C. 1273 struct { 1274 T1 f1; 1275 T2 f2; 1276 ... 1277 Tn fn; 1278 } T; 1280 Fixed- and variable-length vector fields are allowed using the 1281 standard vector syntax. Structures V1 and V2 in the variants example 1282 below demonstrate this. 1284 The fields within a structure may be qualified using the type's name, 1285 with a syntax much like that available for enumerateds. For example, 1286 T.f2 refers to the second field of the previous declaration. 1288 3.7. Constants 1290 Fields and variables may be assigned a fixed value using "=", as in: 1292 struct { 1293 T1 f1 = 8; /* T.f1 must always be 8 */ 1294 T2 f2; 1295 } T; 1297 3.8. Variants 1299 Defined structures may have variants based on some knowledge that is 1300 available within the environment. The selector must be an enumerated 1301 type that defines the possible variants the structure defines. Each 1302 arm of the select specifies the type of that variant's field and an 1303 optional field label. The mechanism by which the variant is selected 1304 at runtime is not prescribed by the presentation language. 1306 struct { 1307 T1 f1; 1308 T2 f2; 1309 .... 1310 Tn fn; 1311 select (E) { 1312 case e1: Te1 [[fe1]]; 1313 case e2: Te2 [[fe2]]; 1314 .... 1315 case en: Ten [[fen]]; 1316 }; 1317 } Tv; 1319 For example: 1321 enum { apple(0), orange(1) } VariantTag; 1323 struct { 1324 uint16 number; 1325 opaque string<0..10>; /* variable length */ 1326 } V1; 1328 struct { 1329 uint32 number; 1330 opaque string[10]; /* fixed length */ 1331 } V2; 1333 struct { 1334 VariantTag type; 1335 select (VariantRecord.type) { 1336 case apple: V1; 1337 case orange: V2; 1338 }; 1339 } VariantRecord; 1341 4. Handshake Protocol 1343 The handshake protocol is used to negotiate the security parameters 1344 of a connection. Handshake messages are supplied to the TLS record 1345 layer, where they are encapsulated within one or more TLSPlaintext or 1346 TLSCiphertext structures, which are processed and transmitted as 1347 specified by the current active connection state. 1349 enum { 1350 client_hello(1), 1351 server_hello(2), 1352 new_session_ticket(4), 1353 end_of_early_data(5), 1354 encrypted_extensions(8), 1355 certificate(11), 1356 certificate_request(13), 1357 certificate_verify(15), 1358 finished(20), 1359 key_update(24), 1360 message_hash(254), 1361 (255) 1362 } HandshakeType; 1364 struct { 1365 HandshakeType msg_type; /* handshake type */ 1366 uint24 length; /* bytes in message */ 1367 select (Handshake.msg_type) { 1368 case client_hello: ClientHello; 1369 case server_hello: ServerHello; 1370 case end_of_early_data: EndOfEarlyData; 1371 case encrypted_extensions: EncryptedExtensions; 1372 case certificate_request: CertificateRequest; 1373 case certificate: Certificate; 1374 case certificate_verify: CertificateVerify; 1375 case finished: Finished; 1376 case new_session_ticket: NewSessionTicket; 1377 case key_update: KeyUpdate; 1378 }; 1379 } Handshake; 1381 Protocol messages MUST be sent in the order defined in Section 4.4.1 1382 and shown in the diagrams in Section 2. A peer which receives a 1383 handshake message in an unexpected order MUST abort the handshake 1384 with an "unexpected_message" alert. 1386 New handshake message types are assigned by IANA as described in 1387 Section 11. 1389 4.1. Key Exchange Messages 1391 The key exchange messages are used to determine the security 1392 capabilities of the client and the server and to establish shared 1393 secrets including the traffic keys used to protect the rest of the 1394 handshake and the data. 1396 4.1.1. Cryptographic Negotiation 1398 In TLS, the cryptographic negotiation proceeds by the client offering 1399 the following four sets of options in its ClientHello: 1401 - A list of cipher suites which indicates the AEAD algorithm/HKDF 1402 hash pairs which the client supports. 1404 - A "supported_groups" (Section 4.2.7) extension which indicates the 1405 (EC)DHE groups which the client supports and a "key_share" 1406 (Section 4.2.8) extension which contains (EC)DHE shares for some 1407 or all of these groups. 1409 - A "signature_algorithms" (Section 4.2.3) extension which indicates 1410 the signature algorithms which the client can accept. 1412 - A "pre_shared_key" (Section 4.2.11) extension which contains a 1413 list of symmetric key identities known to the client and a 1414 "psk_key_exchange_modes" (Section 4.2.9) extension which indicates 1415 the key exchange modes that may be used with PSKs. 1417 If the server does not select a PSK, then the first three of these 1418 options are entirely orthogonal: the server independently selects a 1419 cipher suite, an (EC)DHE group and key share for key establishment, 1420 and a signature algorithm/certificate pair to authenticate itself to 1421 the client. If there is no overlap between the received 1422 "supported_groups" and the groups supported by the server then the 1423 server MUST abort the handshake with a "handshake_failure" or an 1424 "insufficient_security" alert. 1426 If the server selects a PSK, then it MUST also select a key 1427 establishment mode from the set indicated by client's 1428 "psk_key_exchange_modes" extension (at present, PSK alone or with 1429 (EC)DHE). Note that if the PSK can be used without (EC)DHE then non- 1430 overlap in the "supported_groups" parameters need not be fatal, as it 1431 is in the non-PSK case discussed in the previous paragraph. 1433 If the server selects an (EC)DHE group and the client did not offer a 1434 compatible "key_share" extension in the initial ClientHello, the 1435 server MUST respond with a HelloRetryRequest (Section 4.1.4) message. 1437 If the server successfully selects parameters and does not require a 1438 HelloRetryRequest, it indicates the selected parameters in the 1439 ServerHello as follows: 1441 - If PSK is being used, then the server will send a "pre_shared_key" 1442 extension indicating the selected key. 1444 - If PSK is not being used, then (EC)DHE and certificate-based 1445 authentication are always used. 1447 - When (EC)DHE is in use, the server will also provide a "key_share" 1448 extension. 1450 - When authenticating via a certificate, the server will send the 1451 Certificate (Section 4.4.2) and CertificateVerify (Section 4.4.3) 1452 messages. In TLS 1.3 as defined by this document, either a PSK or 1453 a certificate is always used, but not both. Future documents may 1454 define how to use them together. 1456 If the server is unable to negotiate a supported set of parameters 1457 (i.e., there is no overlap between the client and server parameters), 1458 it MUST abort the handshake with either a "handshake_failure" or 1459 "insufficient_security" fatal alert (see Section 6). 1461 4.1.2. Client Hello 1463 When a client first connects to a server, it is REQUIRED to send the 1464 ClientHello as its first message. The client will also send a 1465 ClientHello when the server has responded to its ClientHello with a 1466 HelloRetryRequest. In that case, the client MUST send the same 1467 ClientHello (without modification) except: 1469 - If a "key_share" extension was supplied in the HelloRetryRequest, 1470 replacing the list of shares with a list containing a single 1471 KeyShareEntry from the indicated group. 1473 - Removing the "early_data" extension (Section 4.2.10) if one was 1474 present. Early data is not permitted after HelloRetryRequest. 1476 - Including a "cookie" extension if one was provided in the 1477 HelloRetryRequest. 1479 - Updating the "pre_shared_key" extension if present by recomputing 1480 the "obfuscated_ticket_age" and binder values and (optionally) 1481 removing any PSKs which are incompatible with the server's 1482 indicated cipher suite. 1484 - Optionally adding, removing, or changing the length of the 1485 "padding" extension [RFC7685]. 1487 Because TLS 1.3 forbids renegotiation, if a server has negotiated TLS 1488 1.3 and receives a ClientHello at any other time, it MUST terminate 1489 the connection with an "unexpected_message" alert. 1491 If a server established a TLS connection with a previous version of 1492 TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST 1493 retain the previous protocol version. In particular, it MUST NOT 1494 negotiate TLS 1.3. 1496 Structure of this message: 1498 uint16 ProtocolVersion; 1499 opaque Random[32]; 1501 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1503 struct { 1504 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 1505 Random random; 1506 opaque legacy_session_id<0..32>; 1507 CipherSuite cipher_suites<2..2^16-2>; 1508 opaque legacy_compression_methods<1..2^8-1>; 1509 Extension extensions<8..2^16-1>; 1510 } ClientHello; 1512 legacy_version In previous versions of TLS, this field was used for 1513 version negotiation and represented the highest version number 1514 supported by the client. Experience has shown that many servers 1515 do not properly implement version negotiation, leading to "version 1516 intolerance" in which the server rejects an otherwise acceptable 1517 ClientHello with a version number higher than it supports. In TLS 1518 1.3, the client indicates its version preferences in the 1519 "supported_versions" extension (Section 4.2.1) and the 1520 legacy_version field MUST be set to 0x0303, which is the version 1521 number for TLS 1.2. (See Appendix D for details about backward 1522 compatibility.) 1524 random 32 bytes generated by a secure random number generator. See 1525 Appendix C for additional information. 1527 legacy_session_id Versions of TLS before TLS 1.3 supported a 1528 "session resumption" feature which has been merged with Pre-Shared 1529 Keys in this version (see Section 2.2). A client which has a 1530 cached session ID set by a pre-TLS 1.3 server SHOULD set this 1531 field to that value. In compatibility mode (see Appendix D.4) 1532 this field MUST be non-empty, so a client not offering a pre-TLS 1533 1.3 session MUST generate a new 32-byte value. This value need 1534 not be random but SHOULD be unpredictable to avoid implementations 1535 fixating on a specific value (also known as ossification). 1536 Otherwise, it MUST be set as a zero length vector (i.e., a single 1537 zero byte length field). 1539 cipher_suites This is a list of the symmetric cipher options 1540 supported by the client, specifically the record protection 1541 algorithm (including secret key length) and a hash to be used with 1542 HKDF, in descending order of client preference. If the list 1543 contains cipher suites that the server does not recognize, support 1544 or wish to use, the server MUST ignore those cipher suites and 1545 process the remaining ones as usual. Values are defined in 1546 Appendix B.4. If the client is attempting a PSK key 1547 establishment, it SHOULD advertise at least one cipher suite 1548 indicating a Hash associated with the PSK. 1550 legacy_compression_methods Versions of TLS before 1.3 supported 1551 compression with the list of supported compression methods being 1552 sent in this field. For every TLS 1.3 ClientHello, this vector 1553 MUST contain exactly one byte set to zero, which corresponds to 1554 the "null" compression method in prior versions of TLS. If a TLS 1555 1.3 ClientHello is received with any other value in this field, 1556 the server MUST abort the handshake with an "illegal_parameter" 1557 alert. Note that TLS 1.3 servers might receive TLS 1.2 or prior 1558 ClientHellos which contain other compression methods and MUST 1559 follow the procedures for the appropriate prior version of TLS. 1560 TLS 1.3 ClientHellos are identified as having a legacy_version of 1561 0x0303 and a supported_versions extension present with 0x0304 as 1562 the highest version indicated therein. 1564 extensions Clients request extended functionality from servers by 1565 sending data in the extensions field. The actual "Extension" 1566 format is defined in Section 4.2. In TLS 1.3, use of certain 1567 extensions is mandatory, as functionality is moved into extensions 1568 to preserve ClientHello compatibility with previous versions of 1569 TLS. Servers MUST ignore unrecognized extensions. 1571 All versions of TLS allow an extensions field to optionally follow 1572 the compression_methods field. TLS 1.3 ClientHello messages always 1573 contain extensions (minimally "supported_versions", otherwise they 1574 will be interpreted as TLS 1.2 ClientHello messages). However, TLS 1575 1.3 servers might receive ClientHello messages without an extensions 1576 field from prior versions of TLS. The presence of extensions can be 1577 detected by determining whether there are bytes following the 1578 compression_methods field at the end of the ClientHello. Note that 1579 this method of detecting optional data differs from the normal TLS 1580 method of having a variable-length field, but it is used for 1581 compatibility with TLS before extensions were defined. TLS 1.3 1582 servers will need to perform this check first and only attempt to 1583 negotiate TLS 1.3 if the "supported_versions" extension is present. 1584 If negotiating a version of TLS prior to 1.3, a server MUST check 1585 that the message either contains no data after 1586 legacy_compression_methods or that it contains a valid extensions 1587 block with no data following. If not, then it MUST abort the 1588 handshake with a "decode_error" alert. 1590 In the event that a client requests additional functionality using 1591 extensions, and this functionality is not supplied by the server, the 1592 client MAY abort the handshake. 1594 After sending the ClientHello message, the client waits for a 1595 ServerHello or HelloRetryRequest message. If early data is in use, 1596 the client may transmit early application data (Section 2.3) while 1597 waiting for the next handshake message. 1599 4.1.3. Server Hello 1601 The server will send this message in response to a ClientHello 1602 message to proceed with the handshake if it is able to negotiate an 1603 acceptable set of handshake parameters based on the ClientHello. 1605 Structure of this message: 1607 struct { 1608 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 1609 Random random; 1610 opaque legacy_session_id_echo<0..32>; 1611 CipherSuite cipher_suite; 1612 uint8 legacy_compression_method = 0; 1613 Extension extensions<6..2^16-1>; 1614 } ServerHello; 1616 legacy_version In previous versions of TLS, this field was used for 1617 version negotiation and represented the selected version number 1618 for the connection. Unfortunately, some middleboxes fail when 1619 presented with new values. In TLS 1.3, the TLS server indicates 1620 its version using the "supported_versions" extension 1621 (Section 4.2.1), and the legacy_version field MUST be set to 1622 0x0303, which is the version number for TLS 1.2. (See Appendix D 1623 for details about backward compatibility.) 1625 random 32 bytes generated by a secure random number generator. See 1626 Appendix C for additional information. The last eight bytes MUST 1627 be overwritten as described below if negotiating TLS 1.2 or TLS 1628 1.1, but the remaining bytes MUST be random. This structure is 1629 generated by the server and MUST be generated independently of the 1630 ClientHello.random. 1632 legacy_session_id_echo The contents of the client's 1633 legacy_session_id field. Note that this field is echoed even if 1634 the client's value corresponded to a cached pre-TLS 1.3 session 1635 which the server has chosen not to resume. A client which 1636 receives a legacy_session_id field that does not match what it 1637 sent in the ClientHello MUST abort the handshake with an 1638 "illegal_parameter" alert. 1640 cipher_suite The single cipher suite selected by the server from the 1641 list in ClientHello.cipher_suites. A client which receives a 1642 cipher suite that was not offered MUST abort the handshake with an 1643 "illegal_parameter" alert. 1645 legacy_compression_method A single byte which MUST have the value 0. 1647 extensions A list of extensions. The ServerHello MUST only include 1648 extensions which are required to establish the cryptographic 1649 context and negotiate the protocol version. All TLS 1.3 1650 ServerHello messages MUST contain the "supported_versions" 1651 extension. Current ServerHello messages contain either the 1652 "pre_shared_key" or "key_share" extensions, or both when using a 1653 PSK with (EC)DHE key establishment. The remaining extensions are 1654 sent separately in the EncryptedExtensions message. 1656 For backward compatibility reasons with middleboxes (see 1657 Appendix D.4) the HelloRetryRequest message uses the same structure 1658 as the ServerHello, but with Random set to the special value of the 1659 SHA-256 of "HelloRetryRequest": 1661 CF 21 AD 74 E5 9A 61 11 BE 1D 8C 02 1E 65 B8 91 1662 C2 A2 11 16 7A BB 8C 5E 07 9E 09 E2 C8 A8 33 9C 1664 Upon receiving a message with type server_hello, implementations MUST 1665 first examine the Random value and if it matches this value, process 1666 it as described in Section 4.1.4). 1668 TLS 1.3 has a downgrade protection mechanism embedded in the server's 1669 random value. TLS 1.3 servers which negotiate TLS 1.2 or below in 1670 response to a ClientHello MUST set the last eight bytes of their 1671 Random value specially. 1673 If negotiating TLS 1.2, TLS 1.3 servers MUST set the last eight bytes 1674 of their Random value to the bytes: 1676 44 4F 57 4E 47 52 44 01 1678 If negotiating TLS 1.1 or below, TLS 1.3 servers MUST and TLS 1.2 1679 servers SHOULD set the last eight bytes of their Random value to the 1680 bytes: 1682 44 4F 57 4E 47 52 44 00 1684 TLS 1.3 clients receiving a ServerHello indicating TLS 1.2 or below 1685 MUST check that the last eight bytes are not equal to either of these 1686 values. TLS 1.2 clients SHOULD also check that the last eight bytes 1687 are not equal to the second value if the ServerHello indicates TLS 1688 1.1 or below. If a match is found, the client MUST abort the 1689 handshake with an "illegal_parameter" alert. This mechanism provides 1690 limited protection against downgrade attacks over and above what is 1691 provided by the Finished exchange: because the ServerKeyExchange, a 1692 message present in TLS 1.2 and below, includes a signature over both 1693 random values, it is not possible for an active attacker to modify 1694 the random values without detection as long as ephemeral ciphers are 1695 used. It does not provide downgrade protection when static RSA is 1696 used. 1698 Note: This is a change from [RFC5246], so in practice many TLS 1.2 1699 clients and servers will not behave as specified above. 1701 A legacy TLS client performing renegotiation with TLS 1.2 or prior 1702 and which receives a TLS 1.3 ServerHello during renegotiation MUST 1703 abort the handshake with a "protocol_version" alert. Note that 1704 renegotiation is not possible when TLS 1.3 has been negotiated. 1706 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH Implementations of 1707 draft versions (see Section 4.2.1.1) of this specification SHOULD NOT 1708 implement this mechanism on either client and server. A pre-RFC 1709 client connecting to RFC servers, or vice versa, will appear to 1710 downgrade to TLS 1.2. With the mechanism enabled, this will cause an 1711 interoperability failure. 1713 4.1.4. Hello Retry Request 1715 The server will send this message in response to a ClientHello 1716 message if it is able to find an acceptable set of parameters but the 1717 ClientHello does not contain sufficient information to proceed with 1718 the handshake. As discussed in Section 4.1.3, the HelloRetryRequest 1719 has the same format as a ServerHello message, and the legacy_version, 1720 legacy_session_id_echo, cipher_suite, and legacy_compression methods 1721 fields have the same meaning. However, for convenience we discuss 1722 HelloRetryRequest throughout this document as if it were a distinct 1723 message. 1725 The server's extensions MUST contain "supported_versions" and 1726 otherwise the server SHOULD send only the extensions necessary for 1727 the client to generate a correct ClientHello pair. As with 1728 ServerHello, a HelloRetryRequest MUST NOT contain any extensions that 1729 were not first offered by the client in its ClientHello, with the 1730 exception of optionally the "cookie" (see Section 4.2.2) extension. 1732 Upon receipt of a HelloRetryRequest, the client MUST perform the 1733 checks specified in Section 4.1.3 and then process the extensions, 1734 starting with determining the version using "supported_versions". 1735 Clients MUST abort the handshake with an "illegal_parameter" alert if 1736 the HelloRetryRequest would not result in any change in the 1737 ClientHello. If a client receives a second HelloRetryRequest in the 1738 same connection (i.e., where the ClientHello was itself in response 1739 to a HelloRetryRequest), it MUST abort the handshake with an 1740 "unexpected_message" alert. 1742 Otherwise, the client MUST process all extensions in the 1743 HelloRetryRequest and send a second updated ClientHello. The 1744 HelloRetryRequest extensions defined in this specification are: 1746 - supported_versions (see Section 4.2.1) 1748 - cookie (see Section 4.2.2) 1750 - key_share (see Section 4.2.8) 1752 In addition, in its updated ClientHello, the client SHOULD NOT offer 1753 any pre-shared keys associated with a hash other than that of the 1754 selected cipher suite. This allows the client to avoid having to 1755 compute partial hash transcripts for multiple hashes in the second 1756 ClientHello. A client which receives a cipher suite that was not 1757 offered MUST abort the handshake. Servers MUST ensure that they 1758 negotiate the same cipher suite when receiving a conformant updated 1759 ClientHello (if the server selects the cipher suite as the first step 1760 in the negotiation, then this will happen automatically). Upon 1761 receiving the ServerHello, clients MUST check that the cipher suite 1762 supplied in the ServerHello is the same as that in the 1763 HelloRetryRequest and otherwise abort the handshake with an 1764 "illegal_parameter" alert. 1766 The value of selected_version in the HelloRetryRequest 1767 "supported_versions" extension MUST be retained in the ServerHello, 1768 and a client MUST abort the handshake with an "illegal_parameter" 1769 alert if the value changes. 1771 4.2. Extensions 1773 A number of TLS messages contain tag-length-value encoded extensions 1774 structures. 1776 struct { 1777 ExtensionType extension_type; 1778 opaque extension_data<0..2^16-1>; 1779 } Extension; 1781 enum { 1782 server_name(0), /* RFC 6066 */ 1783 max_fragment_length(1), /* RFC 6066 */ 1784 status_request(5), /* RFC 6066 */ 1785 supported_groups(10), /* RFC 4492, 7919 */ 1786 signature_algorithms(13), /* [[this document]] */ 1787 use_srtp(14), /* RFC 5764 */ 1788 heartbeat(15), /* RFC 6520 */ 1789 application_layer_protocol_negotiation(16), /* RFC 7301 */ 1790 signed_certificate_timestamp(18), /* RFC 6962 */ 1791 client_certificate_type(19), /* RFC 7250 */ 1792 server_certificate_type(20), /* RFC 7250 */ 1793 padding(21), /* RFC 7685 */ 1794 pre_shared_key(41), /* [[this document]] */ 1795 early_data(42), /* [[this document]] */ 1796 supported_versions(43), /* [[this document]] */ 1797 cookie(44), /* [[this document]] */ 1798 psk_key_exchange_modes(45), /* [[this document]] */ 1799 certificate_authorities(47), /* [[this document]] */ 1800 oid_filters(48), /* [[this document]] */ 1801 post_handshake_auth(49), /* [[this document]] */ 1802 signature_algorithms_cert(50), /* [[this document]] */ 1803 key_share(51), /* [[this document]] */ 1804 (65535) 1805 } ExtensionType; 1807 Here: 1809 - "extension_type" identifies the particular extension type. 1811 - "extension_data" contains information specific to the particular 1812 extension type. 1814 The list of extension types is maintained by IANA as described in 1815 Section 11. 1817 Extensions are generally structured in a request/response fashion, 1818 though some extensions are just indications with no corresponding 1819 response. The client sends its extension requests in the ClientHello 1820 message and the server sends its extension responses in the 1821 ServerHello, EncryptedExtensions, HelloRetryRequest and Certificate 1822 messages. The server sends extension requests in the 1823 CertificateRequest message which a client MAY respond to with a 1824 Certificate message. The server MAY also send unsolicited extensions 1825 in the NewSessionTicket, though the client does not respond directly 1826 to these. 1828 Implementations MUST NOT send extension responses if the remote 1829 endpoint did not send the corresponding extension requests, with the 1830 exception of the "cookie" extension in HelloRetryRequest. Upon 1831 receiving such an extension, an endpoint MUST abort the handshake 1832 with an "unsupported_extension" alert. 1834 The table below indicates the messages where a given extension may 1835 appear, using the following notation: CH (ClientHello), SH 1836 (ServerHello), EE (EncryptedExtensions), CT (Certificate), CR 1837 (CertificateRequest), NST (NewSessionTicket) and HRR 1838 (HelloRetryRequest). If an implementation receives an extension 1839 which it recognizes and which is not specified for the message in 1840 which it appears it MUST abort the handshake with an 1841 "illegal_parameter" alert. 1843 +--------------------------------------------------+-------------+ 1844 | Extension | TLS 1.3 | 1845 +--------------------------------------------------+-------------+ 1846 | server_name [RFC6066] | CH, EE | 1847 | | | 1848 | max_fragment_length [RFC6066] | CH, EE | 1849 | | | 1850 | status_request [RFC6066] | CH, CR, CT | 1851 | | | 1852 | supported_groups [RFC7919] | CH, EE | 1853 | | | 1854 | signature_algorithms [RFC5246] | CH, CR | 1855 | | | 1856 | use_srtp [RFC5764] | CH, EE | 1857 | | | 1858 | heartbeat [RFC6520] | CH, EE | 1859 | | | 1860 | application_layer_protocol_negotiation [RFC7301] | CH, EE | 1861 | | | 1862 | signed_certificate_timestamp [RFC6962] | CH, CR, CT | 1863 | | | 1864 | client_certificate_type [RFC7250] | CH, EE | 1865 | | | 1866 | server_certificate_type [RFC7250] | CH, EE | 1867 | | | 1868 | padding [RFC7685] | CH | 1869 | | | 1870 | key_share [[this document]] | CH, SH, HRR | 1871 | | | 1872 | pre_shared_key [[this document]] | CH, SH | 1873 | | | 1874 | psk_key_exchange_modes [[this document]] | CH | 1875 | | | 1876 | early_data [[this document]] | CH, EE, NST | 1877 | | | 1878 | cookie [[this document]] | CH, HRR | 1879 | | | 1880 | supported_versions [[this document]] | CH, SH, HRR | 1881 | | | 1882 | certificate_authorities [[this document]] | CH, CR | 1883 | | | 1884 | oid_filters [[this document]] | CR | 1885 | | | 1886 | post_handshake_auth [[this document]] | CH | 1887 | | | 1888 | signature_algorithms_cert [[this document]] | CH, CR | 1889 +--------------------------------------------------+-------------+ 1891 When multiple extensions of different types are present, the 1892 extensions MAY appear in any order, with the exception of 1893 "pre_shared_key" Section 4.2.11 which MUST be the last extension in 1894 the ClientHello. There MUST NOT be more than one extension of the 1895 same type in a given extension block. 1897 In TLS 1.3, unlike TLS 1.2, extensions are negotiated for each 1898 handshake even when in resumption-PSK mode. However, 0-RTT 1899 parameters are those negotiated in the previous handshake; mismatches 1900 may require rejecting 0-RTT (see Section 4.2.10). 1902 There are subtle (and not so subtle) interactions that may occur in 1903 this protocol between new features and existing features which may 1904 result in a significant reduction in overall security. The following 1905 considerations should be taken into account when designing new 1906 extensions: 1908 - Some cases where a server does not agree to an extension are error 1909 conditions, and some are simply refusals to support particular 1910 features. In general, error alerts should be used for the former 1911 and a field in the server extension response for the latter. 1913 - Extensions should, as far as possible, be designed to prevent any 1914 attack that forces use (or non-use) of a particular feature by 1915 manipulation of handshake messages. This principle should be 1916 followed regardless of whether the feature is believed to cause a 1917 security problem. Often the fact that the extension fields are 1918 included in the inputs to the Finished message hashes will be 1919 sufficient, but extreme care is needed when the extension changes 1920 the meaning of messages sent in the handshake phase. Designers 1921 and implementors should be aware of the fact that until the 1922 handshake has been authenticated, active attackers can modify 1923 messages and insert, remove, or replace extensions. 1925 4.2.1. Supported Versions 1927 struct { 1928 select (Handshake.msg_type) { 1929 case client_hello: 1930 ProtocolVersion versions<2..254>; 1932 case server_hello: /* and HelloRetryRequest */ 1933 ProtocolVersion selected_version; 1934 }; 1935 } SupportedVersions; 1937 The "supported_versions" extension is used by the client to indicate 1938 which versions of TLS it supports and by the server to indicate which 1939 version it is using. The extension contains a list of supported 1940 versions in preference order, with the most preferred version first. 1941 Implementations of this specification MUST send this extension 1942 containing all versions of TLS which they are prepared to negotiate 1943 (for this specification, that means minimally 0x0304, but if previous 1944 versions of TLS are allowed to be negotiated, they MUST be present as 1945 well). 1947 If this extension is not present, servers which are compliant with 1948 this specification MUST negotiate TLS 1.2 or prior as specified in 1949 [RFC5246], even if ClientHello.legacy_version is 0x0304 or later. 1950 Servers MAY abort the handshake upon receiving a ClientHello with 1951 legacy_version 0x0304 or later. 1953 If this extension is present, servers MUST ignore the 1954 ClientHello.legacy_version value and MUST use only the 1955 "supported_versions" extension to determine client preferences. 1956 Servers MUST only select a version of TLS present in that extension 1957 and MUST ignore any unknown versions that are present in that 1958 extension. Note that this mechanism makes it possible to negotiate a 1959 version prior to TLS 1.2 if one side supports a sparse range. 1960 Implementations of TLS 1.3 which choose to support prior versions of 1961 TLS SHOULD support TLS 1.2. Servers should be prepared to receive 1962 ClientHellos that include this extension but do not include 0x0304 in 1963 the list of versions. 1965 A server which negotiates a version of TLS prior to TLS 1.3 MUST set 1966 ServerHello.version and MUST NOT send the "supported_versions" 1967 extension. A server which negotiates TLS 1.3 MUST respond by sending 1968 a "supported_versions" extension containing the selected version 1969 value (0x0304). It MUST set the ServerHello.legacy_version field to 1970 0x0303 (TLS 1.2). Clients MUST check for this extension prior to 1971 processing the rest of the ServerHello (although they will have to 1972 parse the ServerHello in order to read the extension). If this 1973 extension is present, clients MUST ignore the 1974 ServerHello.legacy_version value and MUST use only the 1975 "supported_versions" extension to determine the selected version. If 1976 the "supported_versions" extension contains a version not offered by 1977 the client or contains a version prior to TLS 1.3, the client MUST 1978 abort the handshake with an "illegal_parameter" alert. 1980 4.2.1.1. Draft Version Indicator 1982 RFC EDITOR: PLEASE REMOVE THIS SECTION 1984 While the eventual version indicator for the RFC version of TLS 1.3 1985 will be 0x0304, implementations of draft versions of this 1986 specification SHOULD instead advertise 0x7f00 | draft_version in the 1987 ServerHello and HelloRetryRequest "supported_versions" extension. 1988 For instance, draft-17 would be encoded as the 0x7f11. This allows 1989 pre-RFC implementations to safely negotiate with each other, even if 1990 they would otherwise be incompatible. 1992 4.2.2. Cookie 1994 struct { 1995 opaque cookie<1..2^16-1>; 1996 } Cookie; 1998 Cookies serve two primary purposes: 2000 - Allowing the server to force the client to demonstrate 2001 reachability at their apparent network address (thus providing a 2002 measure of DoS protection). This is primarily useful for non- 2003 connection-oriented transports (see [RFC6347] for an example of 2004 this). 2006 - Allowing the server to offload state to the client, thus allowing 2007 it to send a HelloRetryRequest without storing any state. The 2008 server can do this by storing the hash of the ClientHello in the 2009 HelloRetryRequest cookie (protected with some suitable integrity 2010 algorithm). 2012 When sending a HelloRetryRequest, the server MAY provide a "cookie" 2013 extension to the client (this is an exception to the usual rule that 2014 the only extensions that may be sent are those that appear in the 2015 ClientHello). When sending the new ClientHello, the client MUST copy 2016 the contents of the extension received in the HelloRetryRequest into 2017 a "cookie" extension in the new ClientHello. Clients MUST NOT use 2018 cookies in their initial ClientHello in subsequent connections. 2020 When a server is operating statelessly it may receive an unprotected 2021 record of type change_cipher_spec between the first and second 2022 ClientHello (see Section 5). Since the server is not storing any 2023 state this will appear as if it were the first message to be 2024 received. Servers operating statelessly MUST ignore these records. 2026 4.2.3. Signature Algorithms 2028 TLS 1.3 provides two extensions for indicating which signature 2029 algorithms may be used in digital signatures. The 2030 "signature_algorithms_cert" extension applies to signatures in 2031 certificates and the "signature_algorithms" extension, which 2032 originally appeared in TLS 1.2, applies to signatures in 2033 CertificateVerify messages. The keys found in certificates MUST also 2034 be of appropriate type for the signature algorithms they are used 2035 with. This is a particular issue for RSA keys and PSS signatures, as 2036 described below. If no "signature_algorithms_cert" extension is 2037 present, then the "signature_algorithms" extension also applies to 2038 signatures appearing in certificates. Clients which desire the 2039 server to authenticate itself via a certificate MUST send 2040 "signature_algorithms". If a server is authenticating via a 2041 certificate and the client has not sent a "signature_algorithms" 2042 extension, then the server MUST abort the handshake with a 2043 "missing_extension" alert (see Section 9.2). 2045 The "signature_algorithms_cert" extension was added to allow 2046 implementations which supported different sets of algorithms for 2047 certificates and in TLS itself to clearly signal their capabilities. 2048 TLS 1.2 implementations SHOULD also process this extension. 2049 Implementations which have the same policy in both cases MAY omit the 2050 "signature_algorithms_cert" extension. 2052 The "extension_data" field of these extension contains a 2053 SignatureSchemeList value: 2055 enum { 2056 /* RSASSA-PKCS1-v1_5 algorithms */ 2057 rsa_pkcs1_sha256(0x0401), 2058 rsa_pkcs1_sha384(0x0501), 2059 rsa_pkcs1_sha512(0x0601), 2061 /* ECDSA algorithms */ 2062 ecdsa_secp256r1_sha256(0x0403), 2063 ecdsa_secp384r1_sha384(0x0503), 2064 ecdsa_secp521r1_sha512(0x0603), 2066 /* RSASSA-PSS algorithms with public key OID rsaEncryption */ 2067 rsa_pss_rsae_sha256(0x0804), 2068 rsa_pss_rsae_sha384(0x0805), 2069 rsa_pss_rsae_sha512(0x0806), 2071 /* EdDSA algorithms */ 2072 ed25519(0x0807), 2073 ed448(0x0808), 2075 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */ 2076 rsa_pss_pss_sha256(0x0809), 2077 rsa_pss_pss_sha384(0x080a), 2078 rsa_pss_pss_sha512(0x080b), 2080 /* Legacy algorithms */ 2081 rsa_pkcs1_sha1(0x0201), 2082 ecdsa_sha1(0x0203), 2084 /* Reserved Code Points */ 2085 private_use(0xFE00..0xFFFF), 2086 (0xFFFF) 2087 } SignatureScheme; 2089 struct { 2090 SignatureScheme supported_signature_algorithms<2..2^16-2>; 2091 } SignatureSchemeList; 2093 Note: This enum is named "SignatureScheme" because there is already a 2094 "SignatureAlgorithm" type in TLS 1.2, which this replaces. We use 2095 the term "signature algorithm" throughout the text. 2097 Each SignatureScheme value lists a single signature algorithm that 2098 the client is willing to verify. The values are indicated in 2099 descending order of preference. Note that a signature algorithm 2100 takes as input an arbitrary-length message, rather than a digest. 2101 Algorithms which traditionally act on a digest should be defined in 2102 TLS to first hash the input with a specified hash algorithm and then 2103 proceed as usual. The code point groups listed above have the 2104 following meanings: 2106 RSASSA-PKCS1-v1_5 algorithms Indicates a signature algorithm using 2107 RSASSA-PKCS1-v1_5 [RFC8017] with the corresponding hash algorithm 2108 as defined in [SHS]. These values refer solely to signatures 2109 which appear in certificates (see Section 4.4.2.2) and are not 2110 defined for use in signed TLS handshake messages, although they 2111 MAY appear in "signature_algorithms" and 2112 "signature_algorithms_cert" for backward compatibility with TLS 2113 1.2, 2115 ECDSA algorithms Indicates a signature algorithm using ECDSA 2116 [ECDSA], the corresponding curve as defined in ANSI X9.62 [X962] 2117 and FIPS 186-4 [DSS], and the corresponding hash algorithm as 2118 defined in [SHS]. The signature is represented as a DER-encoded 2119 [X690] ECDSA-Sig-Value structure. 2121 RSASSA-PSS RSAE algorithms Indicates a signature algorithm using 2122 RSASSA-PSS [RFC8017] with mask generation function 1. The digest 2123 used in the mask generation function and the digest being signed 2124 are both the corresponding hash algorithm as defined in [SHS]. 2125 The length of the salt MUST be equal to the length of the digest 2126 algorithm. If the public key is carried in an X.509 certificate, 2127 it MUST use the rsaEncryption OID [RFC5280]. 2129 EdDSA algorithms Indicates a signature algorithm using EdDSA as 2130 defined in [RFC8032] or its successors. Note that these 2131 correspond to the "PureEdDSA" algorithms and not the "prehash" 2132 variants. 2134 RSASSA-PSS PSS algorithms Indicates a signature algorithm using 2135 RSASSA-PSS [RFC8017] with mask generation function 1. The digest 2136 used in the mask generation function and the digest being signed 2137 are both the corresponding hash algorithm as defined in [SHS]. 2138 The length of the salt MUST be equal to the length of the digest 2139 algorithm. If the public key is carried in an X.509 certificate, 2140 it MUST use the RSASSA-PSS OID [RFC5756]. When used in 2141 certificate signatures, the algorithm parameters MUST be DER 2142 encoded. If the corresponding public key's parameters present, 2143 then the parameters in the signature MUST be identical to those in 2144 the public key. 2146 Legacy algorithms Indicates algorithms which are being deprecated 2147 because they use algorithms with known weaknesses, specifically 2148 SHA-1 which is used in this context with either with RSA using 2149 RSASSA-PKCS1-v1_5 or ECDSA. These values refer solely to 2150 signatures which appear in certificates (see Section 4.4.2.2) and 2151 are not defined for use in signed TLS handshake messages, even if 2152 they appear in the "signature_algorithms" list (this is necessary 2153 for backward compatibility with TLS 1.2). Endpoints SHOULD NOT 2154 negotiate these algorithms but are permitted to do so solely for 2155 backward compatibility. Clients offering these values MUST list 2156 them as the lowest priority (listed after all other algorithms in 2157 SignatureSchemeList). TLS 1.3 servers MUST NOT offer a SHA-1 2158 signed certificate unless no valid certificate chain can be 2159 produced without it (see Section 4.4.2.2). 2161 The signatures on certificates that are self-signed or certificates 2162 that are trust anchors are not validated since they begin a 2163 certification path (see [RFC5280], Section 3.2). A certificate that 2164 begins a certification path MAY use a signature algorithm that is not 2165 advertised as being supported in the "signature_algorithms" 2166 extension. 2168 Note that TLS 1.2 defines this extension differently. TLS 1.3 2169 implementations willing to negotiate TLS 1.2 MUST behave in 2170 accordance with the requirements of [RFC5246] when negotiating that 2171 version. In particular: 2173 - TLS 1.2 ClientHellos MAY omit this extension. 2175 - In TLS 1.2, the extension contained hash/signature pairs. The 2176 pairs are encoded in two octets, so SignatureScheme values have 2177 been allocated to align with TLS 1.2's encoding. Some legacy 2178 pairs are left unallocated. These algorithms are deprecated as of 2179 TLS 1.3. They MUST NOT be offered or negotiated by any 2180 implementation. In particular, MD5 [SLOTH], SHA-224, and DSA MUST 2181 NOT be used. 2183 - ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature 2184 pairs. However, the old semantics did not constrain the signing 2185 curve. If TLS 1.2 is negotiated, implementations MUST be prepared 2186 to accept a signature that uses any curve that they advertised in 2187 the "supported_groups" extension. 2189 - Implementations that advertise support for RSASSA-PSS (which is 2190 mandatory in TLS 1.3), MUST be prepared to accept a signature 2191 using that scheme even when TLS 1.2 is negotiated. In TLS 1.2, 2192 RSASSA-PSS is used with RSA cipher suites. 2194 4.2.4. Certificate Authorities 2196 The "certificate_authorities" extension is used to indicate the 2197 certificate authorities which an endpoint supports and which SHOULD 2198 be used by the receiving endpoint to guide certificate selection. 2200 The body of the "certificate_authorities" extension consists of a 2201 CertificateAuthoritiesExtension structure. 2203 opaque DistinguishedName<1..2^16-1>; 2205 struct { 2206 DistinguishedName authorities<3..2^16-1>; 2207 } CertificateAuthoritiesExtension; 2209 authorities A list of the distinguished names [X501] of acceptable 2210 certificate authorities, represented in DER-encoded [X690] format. 2211 These distinguished names specify a desired distinguished name for 2212 trust anchor or subordinate CA; thus, this message can be used to 2213 describe known trust anchors as well as a desired authorization 2214 space. 2216 The client MAY send the "certificate_authorities" extension in the 2217 ClientHello message. The server MAY send it in the 2218 CertificateRequest message. 2220 The "trusted_ca_keys" extension, which serves a similar purpose 2221 [RFC6066], but is more complicated, is not used in TLS 1.3 (although 2222 it may appear in ClientHello messages from clients which are offering 2223 prior versions of TLS). 2225 4.2.5. OID Filters 2227 The "oid_filters" extension allows servers to provide a set of OID/ 2228 value pairs which it would like the client's certificate to match. 2229 This extension, if provided by the server, MUST only be sent in the 2230 CertificateRequest message. 2232 struct { 2233 opaque certificate_extension_oid<1..2^8-1>; 2234 opaque certificate_extension_values<0..2^16-1>; 2235 } OIDFilter; 2237 struct { 2238 OIDFilter filters<0..2^16-1>; 2239 } OIDFilterExtension; 2241 filters A list of certificate extension OIDs [RFC5280] with their 2242 allowed values and represented in DER-encoded [X690] format. Some 2243 certificate extension OIDs allow multiple values (e.g., Extended 2244 Key Usage). If the server has included a non-empty filters list, 2245 the client certificate included in the response MUST contain all 2246 of the specified extension OIDs that the client recognizes. For 2247 each extension OID recognized by the client, all of the specified 2248 values MUST be present in the client certificate (but the 2249 certificate MAY have other values as well). However, the client 2250 MUST ignore and skip any unrecognized certificate extension OIDs. 2251 If the client ignored some of the required certificate extension 2252 OIDs and supplied a certificate that does not satisfy the request, 2253 the server MAY at its discretion either continue the connection 2254 without client authentication, or abort the handshake with an 2255 "unsupported_certificate" alert. 2257 PKIX RFCs define a variety of certificate extension OIDs and their 2258 corresponding value types. Depending on the type, matching 2259 certificate extension values are not necessarily bitwise-equal. It 2260 is expected that TLS implementations will rely on their PKI libraries 2261 to perform certificate selection using certificate extension OIDs. 2263 This document defines matching rules for two standard certificate 2264 extensions defined in [RFC5280]: 2266 - The Key Usage extension in a certificate matches the request when 2267 all key usage bits asserted in the request are also asserted in 2268 the Key Usage certificate extension. 2270 - The Extended Key Usage extension in a certificate matches the 2271 request when all key purpose OIDs present in the request are also 2272 found in the Extended Key Usage certificate extension. The 2273 special anyExtendedKeyUsage OID MUST NOT be used in the request. 2275 Separate specifications may define matching rules for other 2276 certificate extensions. 2278 4.2.6. Post-Handshake Client Authentication 2280 The "post_handshake_auth" extension is used to indicate that a client 2281 is willing to perform post-handshake authentication Section 4.6.2. 2282 Servers MUST NOT send a post-handshake CertificateRequest to clients 2283 which do not offer this extension. Servers MUST NOT send this 2284 extension. 2286 struct {} PostHandshakeAuth; 2288 The "extension_data" field of the "post_handshake_auth" extension is 2289 zero length. 2291 4.2.7. Negotiated Groups 2293 When sent by the client, the "supported_groups" extension indicates 2294 the named groups which the client supports for key exchange, ordered 2295 from most preferred to least preferred. 2297 Note: In versions of TLS prior to TLS 1.3, this extension was named 2298 "elliptic_curves" and only contained elliptic curve groups. See 2299 [RFC4492] and [RFC7919]. This extension was also used to negotiate 2300 ECDSA curves. Signature algorithms are now negotiated independently 2301 (see Section 4.2.3). 2303 The "extension_data" field of this extension contains a 2304 "NamedGroupList" value: 2306 enum { 2308 /* Elliptic Curve Groups (ECDHE) */ 2309 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 2310 x25519(0x001D), x448(0x001E), 2312 /* Finite Field Groups (DHE) */ 2313 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102), 2314 ffdhe6144(0x0103), ffdhe8192(0x0104), 2316 /* Reserved Code Points */ 2317 ffdhe_private_use(0x01FC..0x01FF), 2318 ecdhe_private_use(0xFE00..0xFEFF), 2319 (0xFFFF) 2320 } NamedGroup; 2322 struct { 2323 NamedGroup named_group_list<2..2^16-1>; 2324 } NamedGroupList; 2326 Elliptic Curve Groups (ECDHE) Indicates support for the 2327 corresponding named curve, defined either in FIPS 186-4 [DSS] or 2328 in [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for 2329 private use. 2331 Finite Field Groups (DHE) Indicates support of the corresponding 2332 finite field group, defined in [RFC7919]. Values 0x01FC through 2333 0x01FF are reserved for private use. 2335 Items in named_group_list are ordered according to the client's 2336 preferences (most preferred choice first). 2338 As of TLS 1.3, servers are permitted to send the "supported_groups" 2339 extension to the client. Clients MUST NOT act upon any information 2340 found in "supported_groups" prior to successful completion of the 2341 handshake but MAY use the information learned from a successfully 2342 completed handshake to change what groups they use in their 2343 "key_share" extension in subsequent connections. If the server has a 2344 group it prefers to the ones in the "key_share" extension but is 2345 still willing to accept the ClientHello, it SHOULD send 2346 "supported_groups" to update the client's view of its preferences; 2347 this extension SHOULD contain all groups the server supports, 2348 regardless of whether they are currently supported by the client. 2350 4.2.8. Key Share 2352 The "key_share" extension contains the endpoint's cryptographic 2353 parameters. 2355 Clients MAY send an empty client_shares vector in order to request 2356 group selection from the server at the cost of an additional round 2357 trip. (see Section 4.1.4) 2359 struct { 2360 NamedGroup group; 2361 opaque key_exchange<1..2^16-1>; 2362 } KeyShareEntry; 2364 group The named group for the key being exchanged. Finite Field 2365 Diffie-Hellman [DH] parameters are described in Section 4.2.8.1; 2366 Elliptic Curve Diffie-Hellman parameters are described in 2367 Section 4.2.8.2. 2369 key_exchange Key exchange information. The contents of this field 2370 are determined by the specified group and its corresponding 2371 definition. 2373 In the ClientHello message, the "extension_data" field of this 2374 extension contains a "KeyShareClientHello" value: 2376 struct { 2377 KeyShareEntry client_shares<0..2^16-1>; 2378 } KeyShareClientHello; 2380 client_shares A list of offered KeyShareEntry values in descending 2381 order of client preference. 2383 This vector MAY be empty if the client is requesting a 2384 HelloRetryRequest. Each KeyShareEntry value MUST correspond to a 2385 group offered in the "supported_groups" extension and MUST appear in 2386 the same order. However, the values MAY be a non-contiguous subset 2387 of the "supported_groups" extension and MAY omit the most preferred 2388 groups. Such a situation could arise if the most preferred groups 2389 are new and unlikely to be supported in enough places to make 2390 pregenerating key shares for them efficient. 2392 Clients can offer an arbitrary number of KeyShareEntry values, each 2393 representing a single set of key exchange parameters. For instance, 2394 a client might offer shares for several elliptic curves or multiple 2395 FFDHE groups. The key_exchange values for each KeyShareEntry MUST be 2396 generated independently. Clients MUST NOT offer multiple 2397 KeyShareEntry values for the same group. Clients MUST NOT offer any 2398 KeyShareEntry values for groups not listed in the client's 2399 "supported_groups" extension. Servers MAY check for violations of 2400 these rules and abort the handshake with an "illegal_parameter" alert 2401 if one is violated. 2403 In a HelloRetryRequest message, the "extension_data" field of this 2404 extension contains a KeyShareHelloRetryRequest value: 2406 struct { 2407 NamedGroup selected_group; 2408 } KeyShareHelloRetryRequest; 2410 selected_group The mutually supported group the server intends to 2411 negotiate and is requesting a retried ClientHello/KeyShare for. 2413 Upon receipt of this extension in a HelloRetryRequest, the client 2414 MUST verify that (1) the selected_group field corresponds to a group 2415 which was provided in the "supported_groups" extension in the 2416 original ClientHello; and (2) the selected_group field does not 2417 correspond to a group which was provided in the "key_share" extension 2418 in the original ClientHello. If either of these checks fails, then 2419 the client MUST abort the handshake with an "illegal_parameter" 2420 alert. Otherwise, when sending the new ClientHello, the client MUST 2421 replace the original "key_share" extension with one containing only a 2422 new KeyShareEntry for the group indicated in the selected_group field 2423 of the triggering HelloRetryRequest. 2425 In a ServerHello message, the "extension_data" field of this 2426 extension contains a KeyShareServerHello value: 2428 struct { 2429 KeyShareEntry server_share; 2430 } KeyShareServerHello; 2432 server_share A single KeyShareEntry value that is in the same group 2433 as one of the client's shares. 2435 If using (EC)DHE key establishment, servers offer exactly one 2436 KeyShareEntry in the ServerHello. This value MUST be in the same 2437 group as the KeyShareEntry value offered by the client that the 2438 server has selected for the negotiated key exchange. Servers MUST 2439 NOT send a KeyShareEntry for any group not indicated in the 2440 "supported_groups" extension and MUST NOT send a KeyShareEntry when 2441 using the "psk_ke" PskKeyExchangeMode. If using (EC)DHE key 2442 establishment, and a HelloRetryRequest containing a "key_share" 2443 extension was received by the client, the client MUST verify that the 2444 selected NamedGroup in the ServerHello is the same as that in the 2445 HelloRetryRequest. If this check fails, the client MUST abort the 2446 handshake with an "illegal_parameter" alert. 2448 4.2.8.1. Diffie-Hellman Parameters 2450 Diffie-Hellman [DH] parameters for both clients and servers are 2451 encoded in the opaque key_exchange field of a KeyShareEntry in a 2452 KeyShare structure. The opaque value contains the Diffie-Hellman 2453 public value (Y = g^X mod p) for the specified group (see [RFC7919] 2454 for group definitions) encoded as a big-endian integer and padded to 2455 the left with zeros to the size of p in bytes. 2457 Note: For a given Diffie-Hellman group, the padding results in all 2458 public keys having the same length. 2460 Peers MUST validate each other's public key Y by ensuring that 1 < Y 2461 < p-1. This check ensures that the remote peer is properly behaved 2462 and isn't forcing the local system into a small subgroup. 2464 4.2.8.2. ECDHE Parameters 2466 ECDHE parameters for both clients and servers are encoded in the the 2467 opaque key_exchange field of a KeyShareEntry in a KeyShare structure. 2469 For secp256r1, secp384r1 and secp521r1, the contents are the 2470 serialized value of the following struct: 2472 struct { 2473 uint8 legacy_form = 4; 2474 opaque X[coordinate_length]; 2475 opaque Y[coordinate_length]; 2476 } UncompressedPointRepresentation; 2478 X and Y respectively are the binary representations of the X and Y 2479 values in network byte order. There are no internal length markers, 2480 so each number representation occupies as many octets as implied by 2481 the curve parameters. For P-256 this means that each of X and Y use 2482 32 octets, padded on the left by zeros if necessary. For P-384 they 2483 take 48 octets each, and for P-521 they take 66 octets each. 2485 For the curves secp256r1, secp384r1 and secp521r1, peers MUST 2486 validate each other's public value Y by ensuring that the point is a 2487 valid point on the elliptic curve. The appropriate validation 2488 procedures are defined in Section 4.3.7 of [X962] and alternatively 2489 in Section 5.6.2.3 of [KEYAGREEMENT]. This process consists of three 2490 steps: (1) verify that Y is not the point at infinity (O), (2) verify 2491 that for Y = (x, y) both integers are in the correct interval, (3) 2492 ensure that (x, y) is a correct solution to the elliptic curve 2493 equation. For these curves, implementers do not need to verify 2494 membership in the correct subgroup. 2496 For X25519 and X448, the contents of the public value are the byte 2497 string inputs and outputs of the corresponding functions defined in 2498 [RFC7748], 32 bytes for X25519 and 56 bytes for X448. 2500 Note: Versions of TLS prior to 1.3 permitted point format 2501 negotiation; TLS 1.3 removes this feature in favor of a single point 2502 format for each curve. 2504 4.2.9. Pre-Shared Key Exchange Modes 2506 In order to use PSKs, clients MUST also send a 2507 "psk_key_exchange_modes" extension. The semantics of this extension 2508 are that the client only supports the use of PSKs with these modes, 2509 which restricts both the use of PSKs offered in this ClientHello and 2510 those which the server might supply via NewSessionTicket. 2512 A client MUST provide a "psk_key_exchange_modes" extension if it 2513 offers a "pre_shared_key" extension. If clients offer 2514 "pre_shared_key" without a "psk_key_exchange_modes" extension, 2515 servers MUST abort the handshake. Servers MUST NOT select a key 2516 exchange mode that is not listed by the client. This extension also 2517 restricts the modes for use with PSK resumption; servers SHOULD NOT 2518 send NewSessionTicket with tickets that are not compatible with the 2519 advertised modes; however, if a server does so, the impact will just 2520 be that the client's attempts at resumption fail. 2522 The server MUST NOT send a "psk_key_exchange_modes" extension. 2524 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 2526 struct { 2527 PskKeyExchangeMode ke_modes<1..255>; 2528 } PskKeyExchangeModes; 2530 psk_ke PSK-only key establishment. In this mode, the server MUST 2531 NOT supply a "key_share" value. 2533 psk_dhe_ke PSK with (EC)DHE key establishment. In this mode, the 2534 client and servers MUST supply "key_share" values as described in 2535 Section 4.2.8. 2537 4.2.10. Early Data Indication 2539 When a PSK is used, the client can send application data in its first 2540 flight of messages. If the client opts to do so, it MUST supply both 2541 the "early_data" extension as well as the "pre_shared_key" extension. 2543 The "extension_data" field of this extension contains an 2544 "EarlyDataIndication" value. 2546 struct {} Empty; 2548 struct { 2549 select (Handshake.msg_type) { 2550 case new_session_ticket: uint32 max_early_data_size; 2551 case client_hello: Empty; 2552 case encrypted_extensions: Empty; 2553 }; 2554 } EarlyDataIndication; 2556 See Section 4.6.1 for the use of the max_early_data_size field. 2558 The parameters for the 0-RTT data (version, symmetric cipher suite, 2559 ALPN protocol, etc.) are those associated with the PSK in use. For 2560 externally established PSKs, the associated values are those 2561 provisioned along with the key. For PSKs established via a 2562 NewSessionTicket message, the associated values are those which were 2563 negotiated in the connection which established the PSK. The PSK used 2564 to encrypt the early data MUST be the first PSK listed in the 2565 client's "pre_shared_key" extension. 2567 For PSKs provisioned via NewSessionTicket, a server MUST validate 2568 that the ticket age for the selected PSK identity (computed by 2569 subtracting ticket_age_add from PskIdentity.obfuscated_ticket_age 2570 modulo 2^32) is within a small tolerance of the time since the ticket 2571 was issued (see Section 8). If it is not, the server SHOULD proceed 2572 with the handshake but reject 0-RTT, and SHOULD NOT take any other 2573 action that assumes that this ClientHello is fresh. 2575 0-RTT messages sent in the first flight have the same (encrypted) 2576 content types as their corresponding messages sent in other flights 2577 (handshake and application_data) but are protected under different 2578 keys. After receiving the server's Finished message, if the server 2579 has accepted early data, an EndOfEarlyData message will be sent to 2580 indicate the key change. This message will be encrypted with the 2581 0-RTT traffic keys. 2583 A server which receives an "early_data" extension MUST behave in one 2584 of three ways: 2586 - Ignore the extension and return a regular 1-RTT response. The 2587 server then ignores early data by attempting to decrypt received 2588 records in the handshake traffic keys until it is able to receive 2589 the client's second flight and complete an ordinary 1-RTT 2590 handshake, skipping records that fail to decrypt, up to the 2591 configured max_early_data_size. 2593 - Request that the client send another ClientHello by responding 2594 with a HelloRetryRequest. A client MUST NOT include the 2595 "early_data" extension in its followup ClientHello. The server 2596 then ignores early data by skipping all records with external 2597 content type of "application_data" (indicating that they are 2598 encrypted). 2600 - Return its own extension in EncryptedExtensions, indicating that 2601 it intends to process the early data. It is not possible for the 2602 server to accept only a subset of the early data messages. Even 2603 though the server sends a message accepting early data, the actual 2604 early data itself may already be in flight by the time the server 2605 generates this message. 2607 In order to accept early data, the server MUST have accepted a PSK 2608 cipher suite and selected the first key offered in the client's 2609 "pre_shared_key" extension. In addition, it MUST verify that the 2610 following values are consistent with those associated with the 2611 selected PSK: 2613 - The TLS version number 2615 - The selected cipher suite 2617 - The selected ALPN [RFC7301] protocol, if any 2619 These requirements are a superset of those needed to perform a 1-RTT 2620 handshake using the PSK in question. For externally established 2621 PSKs, the associated values are those provisioned along with the key. 2622 For PSKs established via a NewSessionTicket message, the associated 2623 values are those negotiated in the connection during which the ticket 2624 was established. 2626 Future extensions MUST define their interaction with 0-RTT. 2628 If any of these checks fail, the server MUST NOT respond with the 2629 extension and must discard all the first flight data using one of the 2630 first two mechanisms listed above (thus falling back to 1-RTT or 2631 2-RTT). If the client attempts a 0-RTT handshake but the server 2632 rejects it, the server will generally not have the 0-RTT record 2633 protection keys and must instead use trial decryption (either with 2634 the 1-RTT handshake keys or by looking for a cleartext ClientHello in 2635 the case of HelloRetryRequest) to find the first non-0-RTT message. 2637 If the server chooses to accept the "early_data" extension, then it 2638 MUST comply with the same error handling requirements specified for 2639 all records when processing early data records. Specifically, if the 2640 server fails to decrypt any 0-RTT record following an accepted 2641 "early_data" extension it MUST terminate the connection with a 2642 "bad_record_mac" alert as per Section 5.2. 2644 If the server rejects the "early_data" extension, the client 2645 application MAY opt to retransmit early data once the handshake has 2646 been completed. Note that automatic re-transmission of early data 2647 could result in assumptions about the status of the connection being 2648 incorrect. For instance, when the negotiated connection selects a 2649 different ALPN protocol from what was used for the early data, an 2650 application might need to construct different messages. Similarly, 2651 if early data assumes anything about the connection state, it might 2652 be sent in error after the handshake completes. 2654 A TLS implementation SHOULD NOT automatically re-send early data; 2655 applications are in a better position to decide when re-transmission 2656 is appropriate. A TLS implementation MUST NOT automatically re-send 2657 early data unless the negotiated connection selects the same ALPN 2658 protocol. 2660 4.2.11. Pre-Shared Key Extension 2662 The "pre_shared_key" extension is used to indicate the identity of 2663 the pre-shared key to be used with a given handshake in association 2664 with PSK key establishment. 2666 The "extension_data" field of this extension contains a 2667 "PreSharedKeyExtension" value: 2669 struct { 2670 opaque identity<1..2^16-1>; 2671 uint32 obfuscated_ticket_age; 2672 } PskIdentity; 2674 opaque PskBinderEntry<32..255>; 2676 struct { 2677 PskIdentity identities<7..2^16-1>; 2678 PskBinderEntry binders<33..2^16-1>; 2679 } OfferedPsks; 2681 struct { 2682 select (Handshake.msg_type) { 2683 case client_hello: OfferedPsks; 2684 case server_hello: uint16 selected_identity; 2685 }; 2686 } PreSharedKeyExtension; 2688 identity A label for a key. For instance, a ticket defined in 2689 Appendix B.3.4 or a label for a pre-shared key established 2690 externally. 2692 obfuscated_ticket_age An obfuscated version of the age of the key. 2693 Section 4.2.11.1 describes how to form this value for identities 2694 established via the NewSessionTicket message. For identities 2695 established externally an obfuscated_ticket_age of 0 SHOULD be 2696 used, and servers MUST ignore the value. 2698 identities A list of the identities that the client is willing to 2699 negotiate with the server. If sent alongside the "early_data" 2700 extension (see Section 4.2.10), the first identity is the one used 2701 for 0-RTT data. 2703 binders A series of HMAC values, one for each PSK offered in the 2704 "pre_shared_keys" extension and in the same order, computed as 2705 described below. 2707 selected_identity The server's chosen identity expressed as a 2708 (0-based) index into the identities in the client's list. 2710 Each PSK is associated with a single Hash algorithm. For PSKs 2711 established via the ticket mechanism (Section 4.6.1), this is the KDF 2712 Hash algorithm on the connection where the ticket was established. 2713 For externally established PSKs, the Hash algorithm MUST be set when 2714 the PSK is established, or default to SHA-256 if no such algorithm is 2715 defined. The server MUST ensure that it selects a compatible PSK (if 2716 any) and cipher suite. 2718 In TLS versions prior to TLS 1.3, the Server Name Identification 2719 (SNI) value was intended to be associated with the session (Section 3 2720 of [RFC6066]), with the server being required to enforce that the SNI 2721 value associated with the session matches the one specified in the 2722 resumption handshake. However, in reality the implementations were 2723 not consistent on which of two supplied SNI values they would use, 2724 leading to the consistency requirement being de-facto enforced by the 2725 clients. In TLS 1.3, the SNI value is always explicitly specified in 2726 the resumption handshake, and there is no need for the server to 2727 associate an SNI value with the ticket. Clients, however, SHOULD 2728 store the SNI with the PSK to fulfill the requirements of 2729 Section 4.6.1. 2731 Implementor's note: when session resumption is the primary use case 2732 of PSKs the most straightforward way to implement the PSK/cipher 2733 suite matching requirements is to negotiate the cipher suite first 2734 and then exclude any incompatible PSKs. Any unknown PSKs (e.g., they 2735 are not in the PSK database or are encrypted with an unknown key) 2736 SHOULD simply be ignored. If no acceptable PSKs are found, the 2737 server SHOULD perform a non-PSK handshake if possible. If backwards 2738 compatibility is important, client provided, externally established 2739 PSKs SHOULD influence cipher suite selection. 2741 Prior to accepting PSK key establishment, the server MUST validate 2742 the corresponding binder value (see Section 4.2.11.2 below). If this 2743 value is not present or does not validate, the server MUST abort the 2744 handshake. Servers SHOULD NOT attempt to validate multiple binders; 2745 rather they SHOULD select a single PSK and validate solely the binder 2746 that corresponds to that PSK. In order to accept PSK key 2747 establishment, the server sends a "pre_shared_key" extension 2748 indicating the selected identity. 2750 Clients MUST verify that the server's selected_identity is within the 2751 range supplied by the client, that the server selected a cipher suite 2752 indicating a Hash associated with the PSK and that a server 2753 "key_share" extension is present if required by the ClientHello 2754 "psk_key_exchange_modes". If these values are not consistent the 2755 client MUST abort the handshake with an "illegal_parameter" alert. 2757 If the server supplies an "early_data" extension, the client MUST 2758 verify that the server's selected_identity is 0. If any other value 2759 is returned, the client MUST abort the handshake with an 2760 "illegal_parameter" alert. 2762 This extension MUST be the last extension in the ClientHello (this 2763 facilitates implementation as described below). Servers MUST check 2764 that it is the last extension and otherwise fail the handshake with 2765 an "illegal_parameter" alert. 2767 4.2.11.1. Ticket Age 2769 The client's view of the age of a ticket is the time since the 2770 receipt of the NewSessionTicket message. Clients MUST NOT attempt to 2771 use tickets which have ages greater than the "ticket_lifetime" value 2772 which was provided with the ticket. The "obfuscated_ticket_age" 2773 field of each PskIdentity contains an obfuscated version of the 2774 ticket age formed by taking the age in milliseconds and adding the 2775 "ticket_age_add" value that was included with the ticket, see 2776 Section 4.6.1 modulo 2^32. This addition prevents passive observers 2777 from correlating connections unless tickets are reused. Note that 2778 the "ticket_lifetime" field in the NewSessionTicket message is in 2779 seconds but the "obfuscated_ticket_age" is in milliseconds. Because 2780 ticket lifetimes are restricted to a week, 32 bits is enough to 2781 represent any plausible age, even in milliseconds. 2783 4.2.11.2. PSK Binder 2785 The PSK binder value forms a binding between a PSK and the current 2786 handshake, as well as between the handshake in which the PSK was 2787 generated (if via a NewSessionTicket message) and the handshake where 2788 it was used. Each entry in the binders list is computed as an HMAC 2789 over a transcript hash (see Section 4.4.1) containing a partial 2790 ClientHello up to and including the PreSharedKeyExtension.identities 2791 field. That is, it includes all of the ClientHello but not the 2792 binders list itself. The length fields for the message (including 2793 the overall length, the length of the extensions block, and the 2794 length of the "pre_shared_key" extension) are all set as if binders 2795 of the correct lengths were present. 2797 The PskBinderEntry is computed in the same way as the Finished 2798 message (Section 4.4.4) but with the BaseKey being the binder_key 2799 derived via the key schedule from the corresponding PSK which is 2800 being offered (see Section 7.1). 2802 If the handshake includes a HelloRetryRequest, the initial 2803 ClientHello and HelloRetryRequest are included in the transcript 2804 along with the new ClientHello. For instance, if the client sends 2805 ClientHello1, its binder will be computed over: 2807 Transcript-Hash(Truncate(ClientHello1)) 2809 Where Truncate() removes the binders list from the ClientHello. 2811 If the server responds with HelloRetryRequest, and the client then 2812 sends ClientHello2, its binder will be computed over: 2814 Transcript-Hash(ClientHello1, 2815 HelloRetryRequest, 2816 Truncate(ClientHello2)) 2818 The full ClientHello1/ClientHello2 is included in all other handshake 2819 hash computations. Note that in the first flight, 2820 Truncate(ClientHello1) is hashed directly, but in the second flight, 2821 ClientHello1 is hashed and then reinjected as a "message_hash" 2822 message, as described in Section 4.4.1. 2824 4.2.11.3. Processing Order 2826 Clients are permitted to "stream" 0-RTT data until they receive the 2827 server's Finished, only then sending the EndOfEarlyData message, 2828 followed by the rest of the handshake. In order to avoid deadlocks, 2829 when accepting "early_data", servers MUST process the client's 2830 ClientHello and then immediately send the ServerHello, rather than 2831 waiting for the client's EndOfEarlyData message. 2833 4.3. Server Parameters 2835 The next two messages from the server, EncryptedExtensions and 2836 CertificateRequest, contain information from the server that 2837 determines the rest of the handshake. These messages are encrypted 2838 with keys derived from the server_handshake_traffic_secret. 2840 4.3.1. Encrypted Extensions 2842 In all handshakes, the server MUST send the EncryptedExtensions 2843 message immediately after the ServerHello message. This is the first 2844 message that is encrypted under keys derived from the 2845 server_handshake_traffic_secret. 2847 The EncryptedExtensions message contains extensions that can be 2848 protected, i.e., any which are not needed to establish the 2849 cryptographic context, but which are not associated with individual 2850 certificates. The client MUST check EncryptedExtensions for the 2851 presence of any forbidden extensions and if any are found MUST abort 2852 the handshake with an "illegal_parameter" alert. 2854 Structure of this message: 2856 struct { 2857 Extension extensions<0..2^16-1>; 2858 } EncryptedExtensions; 2860 extensions A list of extensions. For more information, see the 2861 table in Section 4.2. 2863 4.3.2. Certificate Request 2865 A server which is authenticating with a certificate MAY optionally 2866 request a certificate from the client. This message, if sent, MUST 2867 follow EncryptedExtensions. 2869 Structure of this message: 2871 struct { 2872 opaque certificate_request_context<0..2^8-1>; 2873 Extension extensions<2..2^16-1>; 2874 } CertificateRequest; 2876 certificate_request_context An opaque string which identifies the 2877 certificate request and which will be echoed in the client's 2878 Certificate message. The certificate_request_context MUST be 2879 unique within the scope of this connection (thus preventing replay 2880 of client CertificateVerify messages). This field SHALL be zero 2881 length unless used for the post-handshake authentication exchanges 2882 described in Section 4.6.2. When requesting post-handshake 2883 authentication, the server SHOULD make the context unpredictable 2884 to the client (e.g., by randomly generating it) in order to 2885 prevent an attacker who has temporary access to the client's 2886 private key from pre-computing valid CertificateVerify messages. 2888 extensions A set of extensions describing the parameters of the 2889 certificate being requested. The "signature_algorithms" extension 2890 MUST be specified, and other extensions may optionally be included 2891 if defined for this message. Clients MUST ignore unrecognized 2892 extensions. 2894 In prior versions of TLS, the CertificateRequest message carried a 2895 list of signature algorithms and certificate authorities which the 2896 server would accept. In TLS 1.3 the former is expressed by sending 2897 the "signature_algorithms" and "signature_algorithms_cert" 2898 extensions. The latter is expressed by sending the 2899 "certificate_authorities" extension (see Section 4.2.4). 2901 Servers which are authenticating with a PSK MUST NOT send the 2902 CertificateRequest message in the main handshake, though they MAY 2903 send it in post-handshake authentication (see Section 4.6.2) provided 2904 that the client has sent the "post_handshake_auth" extension (see 2905 Section 4.2.6). 2907 4.4. Authentication Messages 2909 As discussed in Section 2, TLS generally uses a common set of 2910 messages for authentication, key confirmation, and handshake 2911 integrity: Certificate, CertificateVerify, and Finished. (The 2912 PreSharedKey binders also perform key confirmation, in a similar 2913 fashion.) These three messages are always sent as the last messages 2914 in their handshake flight. The Certificate and CertificateVerify 2915 messages are only sent under certain circumstances, as defined below. 2916 The Finished message is always sent as part of the Authentication 2917 block. These messages are encrypted under keys derived from 2918 [sender]_handshake_traffic_secret. 2920 The computations for the Authentication messages all uniformly take 2921 the following inputs: 2923 - The certificate and signing key to be used. 2925 - A Handshake Context consisting of the set of messages to be 2926 included in the transcript hash. 2928 - A base key to be used to compute a MAC key. 2930 Based on these inputs, the messages then contain: 2932 Certificate The certificate to be used for authentication, and any 2933 supporting certificates in the chain. Note that certificate-based 2934 client authentication is not available in 0-RTT mode. 2936 CertificateVerify A signature over the value Transcript- 2937 Hash(Handshake Context, Certificate) 2939 Finished A MAC over the value Transcript-Hash(Handshake Context, 2940 Certificate, CertificateVerify) using a MAC key derived from the 2941 base key. 2943 The following table defines the Handshake Context and MAC Base Key 2944 for each scenario: 2946 +-----------+----------------------------+--------------------------+ 2947 | Mode | Handshake Context | Base Key | 2948 +-----------+----------------------------+--------------------------+ 2949 | Server | ClientHello ... later of E | server_handshake_traffic | 2950 | | ncryptedExtensions/Certifi | _secret | 2951 | | cateRequest | | 2952 | | | | 2953 | Client | ClientHello ... later of | client_handshake_traffic | 2954 | | server | _secret | 2955 | | Finished/EndOfEarlyData | | 2956 | | | | 2957 | Post- | ClientHello ... client | client_application_traff | 2958 | Handshake | Finished + | ic_secret_N | 2959 | | CertificateRequest | | 2960 +-----------+----------------------------+--------------------------+ 2962 4.4.1. The Transcript Hash 2964 Many of the cryptographic computations in TLS make use of a 2965 transcript hash. This value is computed by hashing the concatenation 2966 of each included handshake message, including the handshake message 2967 header carrying the handshake message type and length fields, but not 2968 including record layer headers. I.e., 2970 Transcript-Hash(M1, M2, ... MN) = Hash(M1 || M2 ... MN) 2972 As an exception to this general rule, when the server responds to a 2973 ClientHello with a HelloRetryRequest, the value of ClientHello1 is 2974 replaced with a special synthetic handshake message of handshake type 2975 "message_hash" containing Hash(ClientHello1). I.e., 2977 Transcript-Hash(ClientHello1, HelloRetryRequest, ... MN) = 2978 Hash(message_hash || /* Handshake type */ 2979 00 00 Hash.length || /* Handshake message length (bytes) */ 2980 Hash(ClientHello1) || /* Hash of ClientHello1 */ 2981 HelloRetryRequest ... MN) 2983 The reason for this construction is to allow the server to do a 2984 stateless HelloRetryRequest by storing just the hash of ClientHello1 2985 in the cookie, rather than requiring it to export the entire 2986 intermediate hash state (see Section 4.2.2). 2988 For concreteness, the transcript hash is always taken from the 2989 following sequence of handshake messages, starting at the first 2990 ClientHello and including only those messages that were sent: 2991 ClientHello, HelloRetryRequest, ClientHello, ServerHello, 2992 EncryptedExtensions, server CertificateRequest, server Certificate, 2993 server CertificateVerify, server Finished, EndOfEarlyData, client 2994 Certificate, client CertificateVerify, client Finished. 2996 In general, implementations can implement the transcript by keeping a 2997 running transcript hash value based on the negotiated hash. Note, 2998 however, that subsequent post-handshake authentications do not 2999 include each other, just the messages through the end of the main 3000 handshake. 3002 4.4.2. Certificate 3004 This message conveys the endpoint's certificate chain to the peer. 3006 The server MUST send a Certificate message whenever the agreed-upon 3007 key exchange method uses certificates for authentication (this 3008 includes all key exchange methods defined in this document except 3009 PSK). 3011 The client MUST send a Certificate message if and only if the server 3012 has requested client authentication via a CertificateRequest message 3013 (Section 4.3.2). If the server requests client authentication but no 3014 suitable certificate is available, the client MUST send a Certificate 3015 message containing no certificates (i.e., with the "certificate_list" 3016 field having length 0). 3018 Structure of this message: 3020 enum { 3021 X509(0), 3022 RawPublicKey(2), 3023 (255) 3024 } CertificateType; 3026 struct { 3027 select (certificate_type) { 3028 case RawPublicKey: 3029 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */ 3030 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 3032 case X509: 3033 opaque cert_data<1..2^24-1>; 3034 }; 3035 Extension extensions<0..2^16-1>; 3036 } CertificateEntry; 3038 struct { 3039 opaque certificate_request_context<0..2^8-1>; 3040 CertificateEntry certificate_list<0..2^24-1>; 3041 } Certificate; 3043 certificate_request_context If this message is in response to a 3044 CertificateRequest, the value of certificate_request_context in 3045 that message. Otherwise (in the case of server authentication), 3046 this field SHALL be zero length. 3048 certificate_list This is a sequence (chain) of CertificateEntry 3049 structures, each containing a single certificate and set of 3050 extensions. 3052 extensions: A set of extension values for the CertificateEntry. The 3053 "Extension" format is defined in Section 4.2. Valid extensions 3054 for server certificates include OCSP Status extension ([RFC6066]) 3055 and SignedCertificateTimestamps ([RFC6962]). Extensions in the 3056 Certificate message from the server MUST correspond to one from 3057 the ClientHello message. Extensions in the Certificate from the 3058 client MUST correspond with an extension in the CertificateRequest 3059 message from the server. If an extension applies to the entire 3060 chain, it SHOULD be included in the first CertificateEntry. 3062 If the corresponding certificate type extension 3063 ("server_certificate_type" or "client_certificate_type") was not 3064 negotiated in Encrypted Extensions, or the X.509 certificate type was 3065 negotiated, then each CertificateEntry contains a DER-encoded X.509 3066 certificate. The sender's certificate MUST come in the first 3067 CertificateEntry in the list. Each following certificate SHOULD 3068 directly certify one preceding it. Because certificate validation 3069 requires that trust anchors be distributed independently, a 3070 certificate that specifies a trust anchor MAY be omitted from the 3071 chain, provided that supported peers are known to possess any omitted 3072 certificates. 3074 Note: Prior to TLS 1.3, "certificate_list" ordering required each 3075 certificate to certify the one immediately preceding it; however, 3076 some implementations allowed some flexibility. Servers sometimes 3077 send both a current and deprecated intermediate for transitional 3078 purposes, and others are simply configured incorrectly, but these 3079 cases can nonetheless be validated properly. For maximum 3080 compatibility, all implementations SHOULD be prepared to handle 3081 potentially extraneous certificates and arbitrary orderings from any 3082 TLS version, with the exception of the end-entity certificate which 3083 MUST be first. 3085 If the RawPublicKey certificate type was negotiated, then the 3086 certificate_list MUST contain no more than one CertificateEntry, 3087 which contains an ASN1_subjectPublicKeyInfo value as defined in 3088 [RFC7250], Section 3. 3090 The OpenPGP certificate type [RFC6091] MUST NOT be used with TLS 1.3. 3092 The server's certificate_list MUST always be non-empty. A client 3093 will send an empty certificate_list if it does not have an 3094 appropriate certificate to send in response to the server's 3095 authentication request. 3097 4.4.2.1. OCSP Status and SCT Extensions 3099 [RFC6066] and [RFC6961] provide extensions to negotiate the server 3100 sending OCSP responses to the client. In TLS 1.2 and below, the 3101 server replies with an empty extension to indicate negotiation of 3102 this extension and the OCSP information is carried in a 3103 CertificateStatus message. In TLS 1.3, the server's OCSP information 3104 is carried in an extension in the CertificateEntry containing the 3105 associated certificate. Specifically: The body of the 3106 "status_request" extension from the server MUST be a 3107 CertificateStatus structure as defined in [RFC6066], which is 3108 interpreted as defined in [RFC6960]. 3110 Note: status_request_v2 extension ([RFC6961]) is deprecated. TLS 1.3 3111 servers MUST NOT act upon its presence or information in it when 3112 processing Client Hello, in particular they MUST NOT send the 3113 status_request_v2 extension in the Encrypted Extensions, Certificate 3114 Request or the Certificate messages. TLS 1.3 servers MUST be able to 3115 process Client Hello messages that include it, as it MAY be sent by 3116 clients that wish to use it in earlier protocol versions. 3118 A server MAY request that a client present an OCSP response with its 3119 certificate by sending an empty "status_request" extension in its 3120 CertificateRequest message. If the client opts to send an OCSP 3121 response, the body of its "status_request" extension MUST be a 3122 CertificateStatus structure as defined in [RFC6066]. 3124 Similarly, [RFC6962] provides a mechanism for a server to send a 3125 Signed Certificate Timestamp (SCT) as an extension in the ServerHello 3126 in TLS 1.2 and below. In TLS 1.3, the server's SCT information is 3127 carried in an extension in CertificateEntry. 3129 4.4.2.2. Server Certificate Selection 3131 The following rules apply to the certificates sent by the server: 3133 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 3134 negotiated otherwise (e.g., [RFC7250]). 3136 - The server's end-entity certificate's public key (and associated 3137 restrictions) MUST be compatible with the selected authentication 3138 algorithm (currently RSA, ECDSA, or EdDSA). 3140 - The certificate MUST allow the key to be used for signing (i.e., 3141 the digitalSignature bit MUST be set if the Key Usage extension is 3142 present) with a signature scheme indicated in the client's 3143 "signature_algorithms"/"signature_algorithms_cert" extensions (see 3144 Section 4.2.3). 3146 - The "server_name" [RFC6066] and "certificate_authorities" 3147 extensions are used to guide certificate selection. As servers 3148 MAY require the presence of the "server_name" extension, clients 3149 SHOULD send this extension, when applicable. 3151 All certificates provided by the server MUST be signed by a signature 3152 algorithm advertised by the client, if they are able to provide such 3153 a chain (see Section 4.2.3). Certificates that are self-signed or 3154 certificates that are expected to be trust anchors are not validated 3155 as part of the chain and therefore MAY be signed with any algorithm. 3157 If the server cannot produce a certificate chain that is signed only 3158 via the indicated supported algorithms, then it SHOULD continue the 3159 handshake by sending the client a certificate chain of its choice 3160 that may include algorithms that are not known to be supported by the 3161 client. This fallback chain SHOULD NOT use the deprecated SHA-1 hash 3162 algorithm in general, but MAY do so if the client's advertisement 3163 permits it, and MUST NOT do so otherwise. 3165 If the client cannot construct an acceptable chain using the provided 3166 certificates and decides to abort the handshake, then it MUST abort 3167 the handshake with an appropriate certificate-related alert (by 3168 default, "unsupported_certificate"; see Section 6.2 for more). 3170 If the server has multiple certificates, it chooses one of them based 3171 on the above-mentioned criteria (in addition to other criteria, such 3172 as transport layer endpoint, local configuration and preferences). 3174 4.4.2.3. Client Certificate Selection 3176 The following rules apply to certificates sent by the client: 3178 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 3179 negotiated otherwise (e.g., [RFC7250]). 3181 - If the "certificate_authorities" extension in the 3182 CertificateRequest message was present, at least one of the 3183 certificates in the certificate chain SHOULD be issued by one of 3184 the listed CAs. 3186 - The certificates MUST be signed using an acceptable signature 3187 algorithm, as described in Section 4.3.2. Note that this relaxes 3188 the constraints on certificate-signing algorithms found in prior 3189 versions of TLS. 3191 - If the CertificateRequest message contained a non-empty 3192 "oid_filters" extension, the end-entity certificate MUST match the 3193 extension OIDs recognized by the client, as described in 3194 Section 4.2.5. 3196 Note that, as with the server certificate, there are certificates 3197 that use algorithm combinations that cannot be currently used with 3198 TLS. 3200 4.4.2.4. Receiving a Certificate Message 3202 In general, detailed certificate validation procedures are out of 3203 scope for TLS (see [RFC5280]). This section provides TLS-specific 3204 requirements. 3206 If the server supplies an empty Certificate message, the client MUST 3207 abort the handshake with a "decode_error" alert. 3209 If the client does not send any certificates, the server MAY at its 3210 discretion either continue the handshake without client 3211 authentication, or abort the handshake with a "certificate_required" 3212 alert. Also, if some aspect of the certificate chain was 3213 unacceptable (e.g., it was not signed by a known, trusted CA), the 3214 server MAY at its discretion either continue the handshake 3215 (considering the client unauthenticated) or abort the handshake. 3217 Any endpoint receiving any certificate which it would need to 3218 validate using any signature algorithm using an MD5 hash MUST abort 3219 the handshake with a "bad_certificate" alert. SHA-1 is deprecated 3220 and it is RECOMMENDED that any endpoint receiving any certificate 3221 which it would need to validate using any signature algorithm using a 3222 SHA-1 hash abort the handshake with a "bad_certificate" alert. For 3223 clarity, this means that endpoints MAY accept these algorithms for 3224 certificates that are self-signed or are trust anchors. 3226 All endpoints are RECOMMENDED to transition to SHA-256 or better as 3227 soon as possible to maintain interoperability with implementations 3228 currently in the process of phasing out SHA-1 support. 3230 Note that a certificate containing a key for one signature algorithm 3231 MAY be signed using a different signature algorithm (for instance, an 3232 RSA key signed with an ECDSA key). 3234 4.4.3. Certificate Verify 3236 This message is used to provide explicit proof that an endpoint 3237 possesses the private key corresponding to its certificate. The 3238 CertificateVerify message also provides integrity for the handshake 3239 up to this point. Servers MUST send this message when authenticating 3240 via a certificate. Clients MUST send this message whenever 3241 authenticating via a certificate (i.e., when the Certificate message 3242 is non-empty). When sent, this message MUST appear immediately after 3243 the Certificate message and immediately prior to the Finished 3244 message. 3246 Structure of this message: 3248 struct { 3249 SignatureScheme algorithm; 3250 opaque signature<0..2^16-1>; 3251 } CertificateVerify; 3253 The algorithm field specifies the signature algorithm used (see 3254 Section 4.2.3 for the definition of this field). The signature is a 3255 digital signature using that algorithm. The content that is covered 3256 under the signature is the hash output as described in Section 4.4.1, 3257 namely: 3259 Transcript-Hash(Handshake Context, Certificate) 3261 The digital signature is then computed over the concatenation of: 3263 - A string that consists of octet 32 (0x20) repeated 64 times 3265 - The context string 3267 - A single 0 byte which serves as the separator 3269 - The content to be signed 3271 This structure is intended to prevent an attack on previous versions 3272 of TLS in which the ServerKeyExchange format meant that attackers 3273 could obtain a signature of a message with a chosen 32-byte prefix 3274 (ClientHello.random). The initial 64-byte pad clears that prefix 3275 along with the server-controlled ServerHello.random. 3277 The context string for a server signature is "TLS 1.3, server 3278 CertificateVerify" and for a client signature is "TLS 1.3, client 3279 CertificateVerify". It is used to provide separation between 3280 signatures made in different contexts, helping against potential 3281 cross-protocol attacks. 3283 For example, if the transcript hash was 32 bytes of 01 (this length 3284 would make sense for SHA-256), the content covered by the digital 3285 signature for a server CertificateVerify would be: 3287 2020202020202020202020202020202020202020202020202020202020202020 3288 2020202020202020202020202020202020202020202020202020202020202020 3289 544c5320312e332c207365727665722043657274696669636174655665726966 3290 79 3291 00 3292 0101010101010101010101010101010101010101010101010101010101010101 3294 On the sender side the process for computing the signature field of 3295 the CertificateVerify message takes as input: 3297 - The content covered by the digital signature 3299 - The private signing key corresponding to the certificate sent in 3300 the previous message 3302 If the CertificateVerify message is sent by a server, the signature 3303 algorithm MUST be one offered in the client's "signature_algorithms" 3304 extension unless no valid certificate chain can be produced without 3305 unsupported algorithms (see Section 4.2.3). 3307 If sent by a client, the signature algorithm used in the signature 3308 MUST be one of those present in the supported_signature_algorithms 3309 field of the "signature_algorithms" extension in the 3310 CertificateRequest message. 3312 In addition, the signature algorithm MUST be compatible with the key 3313 in the sender's end-entity certificate. RSA signatures MUST use an 3314 RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS1-v1_5 3315 algorithms appear in "signature_algorithms". The SHA-1 algorithm 3316 MUST NOT be used in any signatures of CertificateVerify messages. 3317 All SHA-1 signature algorithms in this specification are defined 3318 solely for use in legacy certificates and are not valid for 3319 CertificateVerify signatures. 3321 The receiver of a CertificateVerify message MUST verify the signature 3322 field. The verification process takes as input: 3324 - The content covered by the digital signature 3326 - The public key contained in the end-entity certificate found in 3327 the associated Certificate message. 3329 - The digital signature received in the signature field of the 3330 CertificateVerify message 3332 If the verification fails, the receiver MUST terminate the handshake 3333 with a "decrypt_error" alert. 3335 4.4.4. Finished 3337 The Finished message is the final message in the authentication 3338 block. It is essential for providing authentication of the handshake 3339 and of the computed keys. 3341 Recipients of Finished messages MUST verify that the contents are 3342 correct and if incorrect MUST terminate the connection with a 3343 "decrypt_error" alert. 3345 Once a side has sent its Finished message and received and validated 3346 the Finished message from its peer, it may begin to send and receive 3347 application data over the connection. There are two settings in 3348 which it is permitted to send data prior to receiving the peer's 3349 Finished: 3351 1. Clients sending 0-RTT data as described in Section 4.2.10. 3353 2. Servers MAY send data after sending their first flight, but 3354 because the handshake is not yet complete, they have no assurance 3355 of either the peer's identity or of its liveness (i.e., the 3356 ClientHello might have been replayed). 3358 The key used to compute the finished message is computed from the 3359 Base key defined in Section 4.4 using HKDF (see Section 7.1). 3360 Specifically: 3362 finished_key = 3363 HKDF-Expand-Label(BaseKey, "finished", "", Hash.length) 3365 Structure of this message: 3367 struct { 3368 opaque verify_data[Hash.length]; 3369 } Finished; 3371 The verify_data value is computed as follows: 3373 verify_data = 3374 HMAC(finished_key, 3375 Transcript-Hash(Handshake Context, 3376 Certificate*, CertificateVerify*)) 3378 * Only included if present. 3380 HMAC [RFC2104] uses the Hash algorithm for the handshake. As noted 3381 above, the HMAC input can generally be implemented by a running hash, 3382 i.e., just the handshake hash at this point. 3384 In previous versions of TLS, the verify_data was always 12 octets 3385 long. In TLS 1.3, it is the size of the HMAC output for the Hash 3386 used for the handshake. 3388 Note: Alerts and any other record types are not handshake messages 3389 and are not included in the hash computations. 3391 Any records following a 1-RTT Finished message MUST be encrypted 3392 under the appropriate application traffic key as described in 3393 Section 7.2. In particular, this includes any alerts sent by the 3394 server in response to client Certificate and CertificateVerify 3395 messages. 3397 4.5. End of Early Data 3399 struct {} EndOfEarlyData; 3401 If the server sent an "early_data" extension, the client MUST send an 3402 EndOfEarlyData message after receiving the server Finished. If the 3403 server does not send an "early_data" extension, then the client MUST 3404 NOT send an EndOfEarlyData message. This message indicates that all 3405 0-RTT application_data messages, if any, have been transmitted and 3406 that the following records are protected under handshake traffic 3407 keys. Servers MUST NOT send this message and clients receiving it 3408 MUST terminate the connection with an "unexpected_message" alert. 3409 This message is encrypted under keys derived from the 3410 client_early_traffic_secret. 3412 4.6. Post-Handshake Messages 3414 TLS also allows other messages to be sent after the main handshake. 3415 These messages use a handshake content type and are encrypted under 3416 the appropriate application traffic key. 3418 4.6.1. New Session Ticket Message 3420 At any time after the server has received the client Finished 3421 message, it MAY send a NewSessionTicket message. This message 3422 creates a unique association between the ticket value and a secret 3423 PSK derived from the resumption master secret. 3425 The client MAY use this PSK for future handshakes by including the 3426 ticket value in the "pre_shared_key" extension in its ClientHello 3427 (Section 4.2.11). Servers MAY send multiple tickets on a single 3428 connection, either immediately after each other or after specific 3429 events (see Appendix C.4). For instance, the server might send a new 3430 ticket after post-handshake authentication in order to encapsulate 3431 the additional client authentication state. Multiple tickets are 3432 useful for clients for a variety of purposes, including: 3434 - Opening multiple parallel HTTP connections. 3436 - Performing connection racing across interfaces and address 3437 families via, e.g., Happy Eyeballs [RFC8305] or related 3438 techniques. 3440 Any ticket MUST only be resumed with a cipher suite that has the same 3441 KDF hash algorithm as that used to establish the original connection. 3443 Clients MUST only resume if the new SNI value is valid for the server 3444 certificate presented in the original session, and SHOULD only resume 3445 if the SNI value matches the one used in the original session. The 3446 latter is a performance optimization: normally, there is no reason to 3447 expect that different servers covered by a single certificate would 3448 be able to accept each other's tickets, hence attempting resumption 3449 in that case would waste a single-use ticket. If such an indication 3450 is provided (externally or by any other means), clients MAY resume 3451 with a different SNI value. 3453 On resumption, if reporting an SNI value to the calling application, 3454 implementations MUST use the value sent in the resumption ClientHello 3455 rather than the value sent in the previous session. Note that if a 3456 server implementation declines all PSK identities with different SNI 3457 values, these two values are always the same. 3459 Note: Although the resumption master secret depends on the client's 3460 second flight, servers which do not request client authentication MAY 3461 compute the remainder of the transcript independently and then send a 3462 NewSessionTicket immediately upon sending its Finished rather than 3463 waiting for the client Finished. This might be appropriate in cases 3464 where the client is expected to open multiple TLS connections in 3465 parallel and would benefit from the reduced overhead of a resumption 3466 handshake, for example. 3468 struct { 3469 uint32 ticket_lifetime; 3470 uint32 ticket_age_add; 3471 opaque ticket_nonce<0..255>; 3472 opaque ticket<1..2^16-1>; 3473 Extension extensions<0..2^16-2>; 3474 } NewSessionTicket; 3476 ticket_lifetime Indicates the lifetime in seconds as a 32-bit 3477 unsigned integer in network byte order from the time of ticket 3478 issuance. Servers MUST NOT use any value greater than 604800 3479 seconds (7 days). The value of zero indicates that the ticket 3480 should be discarded immediately. Clients MUST NOT cache tickets 3481 for longer than 7 days, regardless of the ticket_lifetime, and MAY 3482 delete the ticket earlier based on local policy. A server MAY 3483 treat a ticket as valid for a shorter period of time than what is 3484 stated in the ticket_lifetime. 3486 ticket_age_add A securely generated, random 32-bit value that is 3487 used to obscure the age of the ticket that the client includes in 3488 the "pre_shared_key" extension. The client-side ticket age is 3489 added to this value modulo 2^32 to obtain the value that is 3490 transmitted by the client. The server MUST generate a fresh value 3491 for each ticket it sends. 3493 ticket_nonce A per-ticket value that is unique across all tickets 3494 issued on this connection. 3496 ticket The value of the ticket to be used as the PSK identity. The 3497 ticket itself is an opaque label. It MAY either be a database 3498 lookup key or a self-encrypted and self-authenticated value. 3499 Section 4 of [RFC5077] describes a recommended ticket construction 3500 mechanism. 3502 extensions A set of extension values for the ticket. The 3503 "Extension" format is defined in Section 4.2. Clients MUST ignore 3504 unrecognized extensions. 3506 The sole extension currently defined for NewSessionTicket is 3507 "early_data", indicating that the ticket may be used to send 0-RTT 3508 data (Section 4.2.10)). It contains the following value: 3510 max_early_data_size The maximum amount of 0-RTT data that the client 3511 is allowed to send when using this ticket, in bytes. Only 3512 Application Data payload (i.e., plaintext but not padding or the 3513 inner content type byte) is counted. A server receiving more than 3514 max_early_data_size bytes of 0-RTT data SHOULD terminate the 3515 connection with an "unexpected_message" alert. Note that servers 3516 that reject early data due to lack of cryptographic material will 3517 be unable to differentiate padding from content, so clients SHOULD 3518 NOT depend on being able to send large quantities of padding in 3519 early data records. 3521 The PSK associated with the ticket is computed as: 3523 HKDF-Expand-Label(resumption_master_secret, 3524 "resumption", ticket_nonce, Hash.length) 3526 Because the ticket_nonce value is distinct for each NewSessionTicket 3527 message, a different PSK will be derived for each ticket. 3529 Note that in principle it is possible to continue issuing new tickets 3530 which indefinitely extend the lifetime of the keying material 3531 originally derived from an initial non-PSK handshake (which was most 3532 likely tied to the peer's certificate). It is RECOMMENDED that 3533 implementations place limits on the total lifetime of such keying 3534 material; these limits should take into account the lifetime of the 3535 peer's certificate, the likelihood of intervening revocation, and the 3536 time since the peer's online CertificateVerify signature. 3538 4.6.2. Post-Handshake Authentication 3540 When the client has sent the "post_handshake_auth" extension (see 3541 Section 4.2.6), a server MAY request client authentication at any 3542 time after the handshake has completed by sending a 3543 CertificateRequest message. The client MUST respond with the 3544 appropriate Authentication messages (see Section 4.4). If the client 3545 chooses to authenticate, it MUST send Certificate, CertificateVerify, 3546 and Finished. If it declines, it MUST send a Certificate message 3547 containing no certificates followed by Finished. All of the client's 3548 messages for a given response MUST appear consecutively on the wire 3549 with no intervening messages of other types. 3551 A client that receives a CertificateRequest message without having 3552 sent the "post_handshake_auth" extension MUST send an 3553 "unexpected_message" fatal alert. 3555 Note: Because client authentication could involve prompting the user, 3556 servers MUST be prepared for some delay, including receiving an 3557 arbitrary number of other messages between sending the 3558 CertificateRequest and receiving a response. In addition, clients 3559 which receive multiple CertificateRequests in close succession MAY 3560 respond to them in a different order than they were received (the 3561 certificate_request_context value allows the server to disambiguate 3562 the responses). 3564 4.6.3. Key and IV Update 3566 enum { 3567 update_not_requested(0), update_requested(1), (255) 3568 } KeyUpdateRequest; 3570 struct { 3571 KeyUpdateRequest request_update; 3572 } KeyUpdate; 3574 request_update Indicates whether the recipient of the KeyUpdate 3575 should respond with its own KeyUpdate. If an implementation 3576 receives any other value, it MUST terminate the connection with an 3577 "illegal_parameter" alert. 3579 The KeyUpdate handshake message is used to indicate that the sender 3580 is updating its sending cryptographic keys. This message can be sent 3581 by either peer after it has sent a Finished message. Implementations 3582 that receive a KeyUpdate message prior to receiving a Finished 3583 message MUST terminate the connection with an "unexpected_message" 3584 alert. After sending a KeyUpdate message, the sender SHALL send all 3585 its traffic using the next generation of keys, computed as described 3586 in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update 3587 its receiving keys. 3589 If the request_update field is set to "update_requested" then the 3590 receiver MUST send a KeyUpdate of its own with request_update set to 3591 "update_not_requested" prior to sending its next application data 3592 record. This mechanism allows either side to force an update to the 3593 entire connection, but causes an implementation which receives 3594 multiple KeyUpdates while it is silent to respond with a single 3595 update. Note that implementations may receive an arbitrary number of 3596 messages between sending a KeyUpdate with request_update set to 3597 update_requested and receiving the peer's KeyUpdate, because those 3598 messages may already be in flight. However, because send and receive 3599 keys are derived from independent traffic secrets, retaining the 3600 receive traffic secret does not threaten the forward secrecy of data 3601 sent before the sender changed keys. 3603 If implementations independently send their own KeyUpdates with 3604 request_update set to "update_requested", and they cross in flight, 3605 then each side will also send a response, with the result that each 3606 side increments by two generations. 3608 Both sender and receiver MUST encrypt their KeyUpdate messages with 3609 the old keys. Additionally, both sides MUST enforce that a KeyUpdate 3610 with the old key is received before accepting any messages encrypted 3611 with the new key. Failure to do so may allow message truncation 3612 attacks. 3614 5. Record Protocol 3616 The TLS record protocol takes messages to be transmitted, fragments 3617 the data into manageable blocks, protects the records, and transmits 3618 the result. Received data is verified, decrypted, reassembled, and 3619 then delivered to higher-level clients. 3621 TLS records are typed, which allows multiple higher-level protocols 3622 to be multiplexed over the same record layer. This document 3623 specifies four content types: handshake, application data, alert, and 3624 change_cipher_spec. The change_cipher_spec record is used only for 3625 compatibility purposes (see Appendix D.4). 3627 An implementation may receive an unencrypted record of type 3628 change_cipher_spec consisting of the single byte value 0x01 at any 3629 time after the first ClientHello message has been sent or received 3630 and before the peer's Finished message has been received and MUST 3631 simply drop it without further processing. Note that this record may 3632 appear at a point at the handshake where the implementation is 3633 expecting protected records and so it is necessary to detect this 3634 condition prior to attempting to deprotect the record. An 3635 implementation which receives any other change_cipher_spec value or 3636 which receives a protected change_cipher_spec record MUST abort the 3637 handshake with an "unexpected_message" alert. A change_cipher_spec 3638 record received before the first ClientHello message or after the 3639 peer's Finished message MUST be treated as an unexpected record type. 3641 Implementations MUST NOT send record types not defined in this 3642 document unless negotiated by some extension. If a TLS 3643 implementation receives an unexpected record type, it MUST terminate 3644 the connection with an "unexpected_message" alert. New record 3645 content type values are assigned by IANA in the TLS Content Type 3646 Registry as described in Section 11. 3648 5.1. Record Layer 3650 The record layer fragments information blocks into TLSPlaintext 3651 records carrying data in chunks of 2^14 bytes or less. Message 3652 boundaries are handled differently depending on the underlying 3653 ContentType. Any future content types MUST specify appropriate 3654 rules. Note that these rules are stricter than what was enforced in 3655 TLS 1.2. 3657 Handshake messages MAY be coalesced into a single TLSPlaintext record 3658 or fragmented across several records, provided that: 3660 - Handshake messages MUST NOT be interleaved with other record 3661 types. That is, if a handshake message is split over two or more 3662 records, there MUST NOT be any other records between them. 3664 - Handshake messages MUST NOT span key changes. Implementations 3665 MUST verify that all messages immediately preceding a key change 3666 align with a record boundary; if not, then they MUST terminate the 3667 connection with an "unexpected_message" alert. Because the 3668 ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate 3669 messages can immediately precede a key change, implementations 3670 MUST send these messages in alignment with a record boundary. 3672 Implementations MUST NOT send zero-length fragments of Handshake 3673 types, even if those fragments contain padding. 3675 Alert messages (Section 6) MUST NOT be fragmented across records and 3676 multiple Alert messages MUST NOT be coalesced into a single 3677 TLSPlaintext record. In other words, a record with an Alert type 3678 MUST contain exactly one message. 3680 Application Data messages contain data that is opaque to TLS. 3681 Application Data messages are always protected. Zero-length 3682 fragments of Application Data MAY be sent as they are potentially 3683 useful as a traffic analysis countermeasure. Application Data 3684 fragments MAY be split across multiple records or coalesced into a 3685 single record. 3687 enum { 3688 invalid(0), 3689 change_cipher_spec(20), 3690 alert(21), 3691 handshake(22), 3692 application_data(23), 3693 (255) 3694 } ContentType; 3696 struct { 3697 ContentType type; 3698 ProtocolVersion legacy_record_version; 3699 uint16 length; 3700 opaque fragment[TLSPlaintext.length]; 3701 } TLSPlaintext; 3703 type The higher-level protocol used to process the enclosed 3704 fragment. 3706 legacy_record_version This value MUST be set to 0x0303 for all 3707 records generated by a TLS 1.3 implementation other than an 3708 initial ClientHello (i.e., one not generated after a 3709 HelloRetryRequest), where it MAY also be 0x0301 for compatibility 3710 purposes. This field is deprecated and MUST be ignored for all 3711 purposes. Previous versions of TLS would use other values in this 3712 field under some circumstances. 3714 length The length (in bytes) of the following TLSPlaintext.fragment. 3715 The length MUST NOT exceed 2^14 bytes. An endpoint that receives 3716 a record that exceeds this length MUST terminate the connection 3717 with a "record_overflow" alert. 3719 fragment The data being transmitted. This value is transparent and 3720 is treated as an independent block to be dealt with by the higher- 3721 level protocol specified by the type field. 3723 This document describes TLS 1.3, which uses the version 0x0304. This 3724 version value is historical, deriving from the use of 0x0301 for TLS 3725 1.0 and 0x0300 for SSL 3.0. In order to maximize backwards 3726 compatibility, records containing an initial ClientHello SHOULD have 3727 version 0x0301 and a record containing a second ClientHello or a 3728 ServerHello MUST have version 0x0303, reflecting TLS 1.0 and TLS 1.2 3729 respectively. When negotiating prior versions of TLS, endpoints 3730 follow the procedure and requirements in Appendix D. 3732 When record protection has not yet been engaged, TLSPlaintext 3733 structures are written directly onto the wire. Once record 3734 protection has started, TLSPlaintext records are protected and sent 3735 as described in the following section. 3737 5.2. Record Payload Protection 3739 The record protection functions translate a TLSPlaintext structure 3740 into a TLSCiphertext. The deprotection functions reverse the 3741 process. In TLS 1.3, as opposed to previous versions of TLS, all 3742 ciphers are modeled as "Authenticated Encryption with Additional 3743 Data" (AEAD) [RFC5116]. AEAD functions provide an unified encryption 3744 and authentication operation which turns plaintext into authenticated 3745 ciphertext and back again. Each encrypted record consists of a 3746 plaintext header followed by an encrypted body, which itself contains 3747 a type and optional padding. 3749 struct { 3750 opaque content[TLSPlaintext.length]; 3751 ContentType type; 3752 uint8 zeros[length_of_padding]; 3753 } TLSInnerPlaintext; 3755 struct { 3756 ContentType opaque_type = application_data; /* 23 */ 3757 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */ 3758 uint16 length; 3759 opaque encrypted_record[TLSCiphertext.length]; 3760 } TLSCiphertext; 3762 content The byte encoding of a handshake or an alert message, or the 3763 raw bytes of the application's data to send. 3765 type The content type of the record. 3767 zeros An arbitrary-length run of zero-valued bytes may appear in the 3768 cleartext after the type field. This provides an opportunity for 3769 senders to pad any TLS record by a chosen amount as long as the 3770 total stays within record size limits. See Section 5.4 for more 3771 details. 3773 opaque_type The outer opaque_type field of a TLSCiphertext record is 3774 always set to the value 23 (application_data) for outward 3775 compatibility with middleboxes accustomed to parsing previous 3776 versions of TLS. The actual content type of the record is found 3777 in TLSInnerPlaintext.type after decryption. 3779 legacy_record_version The legacy_record_version field is always 3780 0x0303. TLS 1.3 TLSCiphertexts are not generated until after TLS 3781 1.3 has been negotiated, so there are no historical compatibility 3782 concerns where other values might be received. Note that the 3783 handshake protocol including the ClientHello and ServerHello 3784 messages authenticates the protocol version, so this value is 3785 redundant. 3787 length The length (in bytes) of the following 3788 TLSCiphertext.encrypted_record, which is the sum of the lengths of 3789 the content and the padding, plus one for the inner content type, 3790 plus any expansion added by the AEAD algorithm. The length MUST 3791 NOT exceed 2^14 + 256 bytes. An endpoint that receives a record 3792 that exceeds this length MUST terminate the connection with a 3793 "record_overflow" alert. 3795 encrypted_record The AEAD-encrypted form of the serialized 3796 TLSInnerPlaintext structure. 3798 AEAD algorithms take as input a single key, a nonce, a plaintext, and 3799 "additional data" to be included in the authentication check, as 3800 described in Section 2.1 of [RFC5116]. The key is either the 3801 client_write_key or the server_write_key, the nonce is derived from 3802 the sequence number (see Section 5.3) and the client_write_iv or 3803 server_write_iv, and the additional data input is the record header. 3804 I.e., 3806 additional_data = TLSCiphertext.opaque_type || 3807 TLSCiphertext.legacy_record_version || 3808 TLSCiphertext.length 3810 The plaintext input to the AEAD algorithm is the encoded 3811 TLSInnerPlaintext structure. Derivation of traffic keys is defined 3812 in Section 7.3. 3814 The AEAD output consists of the ciphertext output from the AEAD 3815 encryption operation. The length of the plaintext is greater than 3816 the corresponding TLSPlaintext.length due to the inclusion of 3817 TLSInnerPlaintext.type and any padding supplied by the sender. The 3818 length of the AEAD output will generally be larger than the 3819 plaintext, but by an amount that varies with the AEAD algorithm. 3820 Since the ciphers might incorporate padding, the amount of overhead 3821 could vary with different lengths of plaintext. Symbolically, 3822 AEADEncrypted = 3823 AEAD-Encrypt(write_key, nonce, additional_data, plaintext) 3825 Then the encrypted_record field of TLSCiphertext is set to 3826 AEADEncrypted. 3828 In order to decrypt and verify, the cipher takes as input the key, 3829 nonce, additional data, and the AEADEncrypted value. The output is 3830 either the plaintext or an error indicating that the decryption 3831 failed. There is no separate integrity check. That is: 3833 plaintext of encrypted_record = 3834 AEAD-Decrypt(peer_write_key, nonce, additional_data, AEADEncrypted) 3836 If the decryption fails, the receiver MUST terminate the connection 3837 with a "bad_record_mac" alert. 3839 An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion 3840 greater than 255 octets. An endpoint that receives a record from its 3841 peer with TLSCiphertext.length larger than 2^14 + 256 octets MUST 3842 terminate the connection with a "record_overflow" alert. This limit 3843 is derived from the maximum TLSPlaintext length of 2^14 octets + 1 3844 octet for ContentType + the maximum AEAD expansion of 255 octets. 3846 5.3. Per-Record Nonce 3848 A 64-bit sequence number is maintained separately for reading and 3849 writing records. Each sequence number is set to zero at the 3850 beginning of a connection and whenever the key is changed. 3852 The appropriate sequence number is incremented by one after reading 3853 or writing each record. The first record transmitted under a 3854 particular traffic key MUST use sequence number 0. 3856 Because the size of sequence numbers is 64-bit, they should not wrap. 3857 If a TLS implementation would need to wrap a sequence number, it MUST 3858 either re-key (Section 4.6.3) or terminate the connection. 3860 Each AEAD algorithm will specify a range of possible lengths for the 3861 per-record nonce, from N_MIN bytes to N_MAX bytes of input 3862 ([RFC5116]). The length of the TLS per-record nonce (iv_length) is 3863 set to the larger of 8 bytes and N_MIN for the AEAD algorithm (see 3864 [RFC5116] Section 4). An AEAD algorithm where N_MAX is less than 8 3865 bytes MUST NOT be used with TLS. The per-record nonce for the AEAD 3866 construction is formed as follows: 3868 1. The 64-bit record sequence number is encoded in network byte 3869 order and padded to the left with zeros to iv_length. 3871 2. The padded sequence number is XORed with the static 3872 client_write_iv or server_write_iv, depending on the role. 3874 The resulting quantity (of length iv_length) is used as the per- 3875 record nonce. 3877 Note: This is a different construction from that in TLS 1.2, which 3878 specified a partially explicit nonce. 3880 5.4. Record Padding 3882 All encrypted TLS records can be padded to inflate the size of the 3883 TLSCiphertext. This allows the sender to hide the size of the 3884 traffic from an observer. 3886 When generating a TLSCiphertext record, implementations MAY choose to 3887 pad. An unpadded record is just a record with a padding length of 3888 zero. Padding is a string of zero-valued bytes appended to the 3889 ContentType field before encryption. Implementations MUST set the 3890 padding octets to all zeros before encrypting. 3892 Application Data records may contain a zero-length 3893 TLSInnerPlaintext.content if the sender desires. This permits 3894 generation of plausibly-sized cover traffic in contexts where the 3895 presence or absence of activity may be sensitive. Implementations 3896 MUST NOT send Handshake or Alert records that have a zero-length 3897 TLSInnerPlaintext.content; if such a message is received, the 3898 receiving implementation MUST terminate the connection with an 3899 "unexpected_message" alert. 3901 The padding sent is automatically verified by the record protection 3902 mechanism; upon successful decryption of a 3903 TLSCiphertext.encrypted_record, the receiving implementation scans 3904 the field from the end toward the beginning until it finds a non-zero 3905 octet. This non-zero octet is the content type of the message. This 3906 padding scheme was selected because it allows padding of any 3907 encrypted TLS record by an arbitrary size (from zero up to TLS record 3908 size limits) without introducing new content types. The design also 3909 enforces all-zero padding octets, which allows for quick detection of 3910 padding errors. 3912 Implementations MUST limit their scanning to the cleartext returned 3913 from the AEAD decryption. If a receiving implementation does not 3914 find a non-zero octet in the cleartext, it MUST terminate the 3915 connection with an "unexpected_message" alert. 3917 The presence of padding does not change the overall record size 3918 limitations - the full encoded TLSInnerPlaintext MUST NOT exceed 2^14 3919 + 1 octets. If the maximum fragment length is reduced, as for 3920 example by the max_fragment_length extension from [RFC6066], then the 3921 reduced limit applies to the full plaintext, including the content 3922 type and padding. 3924 Selecting a padding policy that suggests when and how much to pad is 3925 a complex topic and is beyond the scope of this specification. If 3926 the application layer protocol on top of TLS has its own padding, it 3927 may be preferable to pad application_data TLS records within the 3928 application layer. Padding for encrypted handshake and alert TLS 3929 records must still be handled at the TLS layer, though. Later 3930 documents may define padding selection algorithms or define a padding 3931 policy request mechanism through TLS extensions or some other means. 3933 5.5. Limits on Key Usage 3935 There are cryptographic limits on the amount of plaintext which can 3936 be safely encrypted under a given set of keys. [AEAD-LIMITS] 3937 provides an analysis of these limits under the assumption that the 3938 underlying primitive (AES or ChaCha20) has no weaknesses. 3939 Implementations SHOULD do a key update as described in Section 4.6.3 3940 prior to reaching these limits. 3942 For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be 3943 encrypted on a given connection while keeping a safety margin of 3944 approximately 2^-57 for Authenticated Encryption (AE) security. For 3945 ChaCha20/Poly1305, the record sequence number would wrap before the 3946 safety limit is reached. 3948 6. Alert Protocol 3950 One of the content types supported by the TLS record layer is the 3951 alert type. Like other messages, alert messages are encrypted as 3952 specified by the current connection state. 3954 Alert messages convey a description of the alert and a legacy field 3955 that conveyed the severity of the message in previous versions of 3956 TLS. In TLS 1.3, the severity is implicit in the type of alert being 3957 sent, and the 'level' field can safely be ignored. The 3958 "close_notify" alert is used to indicate orderly closure of one 3959 direction of the connection. Upon receiving such an alert, the TLS 3960 implementation SHOULD indicate end-of-data to the application. 3962 Error alerts indicate abortive closure of the connection (see 3963 Section 6.2). Upon receiving an error alert, the TLS implementation 3964 SHOULD indicate an error to the application and MUST NOT allow any 3965 further data to be sent or received on the connection. Servers and 3966 clients MUST forget keys and secrets associated with a failed 3967 connection. Stateful implementations of tickets (as in many clients) 3968 SHOULD discard tickets associated with failed connections. 3970 All the alerts listed in Section 6.2 MUST be sent as fatal and MUST 3971 be treated as fatal regardless of the AlertLevel in the message. 3972 Unknown alert types MUST be treated as fatal. 3974 Note: TLS defines two generic alerts (see Section 6) to use upon 3975 failure to parse a message. Peers which receive a message which 3976 cannot be parsed according to the syntax (e.g., have a length 3977 extending beyond the message boundary or contain an out-of-range 3978 length) MUST terminate the connection with a "decode_error" alert. 3979 Peers which receive a message which is syntactically correct but 3980 semantically invalid (e.g., a DHE share of p - 1, or an invalid enum) 3981 MUST terminate the connection with an "illegal_parameter" alert. 3983 enum { warning(1), fatal(2), (255) } AlertLevel; 3985 enum { 3986 close_notify(0), 3987 unexpected_message(10), 3988 bad_record_mac(20), 3989 record_overflow(22), 3990 handshake_failure(40), 3991 bad_certificate(42), 3992 unsupported_certificate(43), 3993 certificate_revoked(44), 3994 certificate_expired(45), 3995 certificate_unknown(46), 3996 illegal_parameter(47), 3997 unknown_ca(48), 3998 access_denied(49), 3999 decode_error(50), 4000 decrypt_error(51), 4001 protocol_version(70), 4002 insufficient_security(71), 4003 internal_error(80), 4004 inappropriate_fallback(86), 4005 user_canceled(90), 4006 missing_extension(109), 4007 unsupported_extension(110), 4008 certificate_unobtainable(111), 4009 unrecognized_name(112), 4010 bad_certificate_status_response(113), 4011 bad_certificate_hash_value(114), 4012 unknown_psk_identity(115), 4013 certificate_required(116), 4014 no_application_protocol(120), 4015 (255) 4016 } AlertDescription; 4018 struct { 4019 AlertLevel level; 4020 AlertDescription description; 4021 } Alert; 4023 6.1. Closure Alerts 4025 The client and the server must share knowledge that the connection is 4026 ending in order to avoid a truncation attack. 4028 close_notify This alert notifies the recipient that the sender will 4029 not send any more messages on this connection. Any data received 4030 after a closure alert has been received MUST be ignored. 4032 user_canceled This alert notifies the recipient that the sender is 4033 canceling the handshake for some reason unrelated to a protocol 4034 failure. If a user cancels an operation after the handshake is 4035 complete, just closing the connection by sending a "close_notify" 4036 is more appropriate. This alert SHOULD be followed by a 4037 "close_notify". This alert is generally a warning. 4039 Either party MAY initiate a close of its write side of the connection 4040 by sending a "close_notify" alert. Any data received after a closure 4041 alert has been received MUST be ignored. If a transport-level close 4042 is received prior to a "close_notify", the receiver cannot know that 4043 all the data that was sent has been received. 4045 Each party MUST send a "close_notify" alert before closing its write 4046 side of the connection, unless it has already sent some other fatal 4047 alert. This does not have any effect on its read side of the 4048 connection. Note that this is a change from versions of TLS prior to 4049 TLS 1.3 in which implementations were required to react to a 4050 "close_notify" by discarding pending writes and sending an immediate 4051 "close_notify" alert of their own. That previous requirement could 4052 cause truncation in the read side. Both parties need not wait to 4053 receive a "close_notify" alert before closing their read side of the 4054 connection. 4056 If the application protocol using TLS provides that any data may be 4057 carried over the underlying transport after the TLS connection is 4058 closed, the TLS implementation MUST receive a "close_notify" alert 4059 before indicating end-of-data to the application-layer. No part of 4060 this standard should be taken to dictate the manner in which a usage 4061 profile for TLS manages its data transport, including when 4062 connections are opened or closed. 4064 Note: It is assumed that closing the write side of a connection 4065 reliably delivers pending data before destroying the transport. 4067 6.2. Error Alerts 4069 Error handling in the TLS Handshake Protocol is very simple. When an 4070 error is detected, the detecting party sends a message to its peer. 4071 Upon transmission or receipt of a fatal alert message, both parties 4072 MUST immediately close the connection. 4074 Whenever an implementation encounters a fatal error condition, it 4075 SHOULD send an appropriate fatal alert and MUST close the connection 4076 without sending or receiving any additional data. In the rest of 4077 this specification, when the phrases "terminate the connection" and 4078 "abort the handshake" are used without a specific alert it means that 4079 the implementation SHOULD send the alert indicated by the 4080 descriptions below. The phrases "terminate the connection with a X 4081 alert" and "abort the handshake with a X alert" mean that the 4082 implementation MUST send alert X if it sends any alert. All alerts 4083 defined in this section below, as well as all unknown alerts, are 4084 universally considered fatal as of TLS 1.3 (see Section 6). The 4085 implementation SHOULD provide a way to facilitate logging the sending 4086 and receiving of alerts. 4088 The following error alerts are defined: 4090 unexpected_message An inappropriate message (e.g., the wrong 4091 handshake message, premature application data, etc.) was received. 4092 This alert should never be observed in communication between 4093 proper implementations. 4095 bad_record_mac This alert is returned if a record is received which 4096 cannot be deprotected. Because AEAD algorithms combine decryption 4097 and verification, and also to avoid side channel attacks, this 4098 alert is used for all deprotection failures. This alert should 4099 never be observed in communication between proper implementations, 4100 except when messages were corrupted in the network. 4102 record_overflow A TLSCiphertext record was received that had a 4103 length more than 2^14 + 256 bytes, or a record decrypted to a 4104 TLSPlaintext record with more than 2^14 bytes. This alert should 4105 never be observed in communication between proper implementations, 4106 except when messages were corrupted in the network. 4108 handshake_failure Receipt of a "handshake_failure" alert message 4109 indicates that the sender was unable to negotiate an acceptable 4110 set of security parameters given the options available. 4112 bad_certificate A certificate was corrupt, contained signatures that 4113 did not verify correctly, etc. 4115 unsupported_certificate A certificate was of an unsupported type. 4117 certificate_revoked A certificate was revoked by its signer. 4119 certificate_expired A certificate has expired or is not currently 4120 valid. 4122 certificate_unknown Some other (unspecified) issue arose in 4123 processing the certificate, rendering it unacceptable. 4125 illegal_parameter A field in the handshake was incorrect or 4126 inconsistent with other fields. This alert is used for errors 4127 which conform to the formal protocol syntax but are otherwise 4128 incorrect. 4130 unknown_ca A valid certificate chain or partial chain was received, 4131 but the certificate was not accepted because the CA certificate 4132 could not be located or could not be matched with a known trust 4133 anchor. 4135 access_denied A valid certificate or PSK was received, but when 4136 access control was applied, the sender decided not to proceed with 4137 negotiation. 4139 decode_error A message could not be decoded because some field was 4140 out of the specified range or the length of the message was 4141 incorrect. This alert is used for errors where the message does 4142 not conform to the formal protocol syntax. This alert should 4143 never be observed in communication between proper implementations, 4144 except when messages were corrupted in the network. 4146 decrypt_error A handshake (not record-layer) cryptographic operation 4147 failed, including being unable to correctly verify a signature or 4148 validate a Finished message or a PSK binder. 4150 protocol_version The protocol version the peer has attempted to 4151 negotiate is recognized but not supported. (see Appendix D) 4153 insufficient_security Returned instead of "handshake_failure" when a 4154 negotiation has failed specifically because the server requires 4155 parameters more secure than those supported by the client. 4157 internal_error An internal error unrelated to the peer or the 4158 correctness of the protocol (such as a memory allocation failure) 4159 makes it impossible to continue. 4161 inappropriate_fallback Sent by a server in response to an invalid 4162 connection retry attempt from a client (see [RFC7507]). 4164 missing_extension Sent by endpoints that receive a hello message not 4165 containing an extension that is mandatory to send for the offered 4166 TLS version or other negotiated parameters. 4168 unsupported_extension Sent by endpoints receiving any hello message 4169 containing an extension known to be prohibited for inclusion in 4170 the given hello message, or including any extensions in a 4171 ServerHello or Certificate not first offered in the corresponding 4172 ClientHello. 4174 certificate_unobtainable Sent by servers when unable to obtain a 4175 certificate from a URL provided by the client via the 4176 "client_certificate_url" extension (see [RFC6066]). 4178 unrecognized_name Sent by servers when no server exists identified 4179 by the name provided by the client via the "server_name" extension 4180 (see [RFC6066]). 4182 bad_certificate_status_response Sent by clients when an invalid or 4183 unacceptable OCSP response is provided by the server via the 4184 "status_request" extension (see [RFC6066]). 4186 bad_certificate_hash_value Sent by servers when a retrieved object 4187 does not have the correct hash provided by the client via the 4188 "client_certificate_url" extension (see [RFC6066]). 4190 unknown_psk_identity Sent by servers when PSK key establishment is 4191 desired but no acceptable PSK identity is provided by the client. 4192 Sending this alert is OPTIONAL; servers MAY instead choose to send 4193 a "decrypt_error" alert to merely indicate an invalid PSK 4194 identity. 4196 certificate_required Sent by servers when a client certificate is 4197 desired but none was provided by the client. 4199 no_application_protocol Sent by servers when a client 4200 "application_layer_protocol_negotiation" extension advertises only 4201 protocols that the server does not support (see [RFC7301]). 4203 New Alert values are assigned by IANA as described in Section 11. 4205 7. Cryptographic Computations 4207 The TLS handshake establishes one or more input secrets which are 4208 combined to create the actual working keying material, as detailed 4209 below. The key derivation process incorporates both the input 4210 secrets and the handshake transcript. Note that because the 4211 handshake transcript includes the random values from the Hello 4212 messages, any given handshake will have different traffic secrets, 4213 even if the same input secrets are used, as is the case when the same 4214 PSK is used for multiple connections. 4216 7.1. Key Schedule 4218 The key derivation process makes use of the HKDF-Extract and HKDF- 4219 Expand functions as defined for HKDF [RFC5869], as well as the 4220 functions defined below: 4222 HKDF-Expand-Label(Secret, Label, Context, Length) = 4223 HKDF-Expand(Secret, HkdfLabel, Length) 4225 Where HkdfLabel is specified as: 4227 struct { 4228 uint16 length = Length; 4229 opaque label<7..255> = "tls13 " + Label; 4230 opaque context<0..255> = Context; 4231 } HkdfLabel; 4233 Derive-Secret(Secret, Label, Messages) = 4234 HKDF-Expand-Label(Secret, Label, 4235 Transcript-Hash(Messages), Hash.length) 4237 The Hash function used by Transcript-Hash and HKDF is the cipher 4238 suite hash algorithm. Hash.length is its output length in bytes. 4239 Messages are the concatenation of the indicated handshake messages, 4240 including the handshake message type and length fields, but not 4241 including record layer headers. Note that in some cases a zero- 4242 length Context (indicated by "") is passed to HKDF-Expand-Label. The 4243 Labels specified in this document are all ASCII strings, and do not 4244 include a trailing NUL byte. 4246 Note: with common hash functions, any label longer than 12 characters 4247 requires an additional iteration of the hash function to compute. 4248 The labels in this specification have all been chosen to fit within 4249 this limit. 4251 Given a set of n InputSecrets, the final "master secret" is computed 4252 by iteratively invoking HKDF-Extract with InputSecret_1, 4253 InputSecret_2, etc. The initial secret is simply a string of 4254 Hash.length bytes set to zeros. Concretely, for the present version 4255 of TLS 1.3, secrets are added in the following order: 4257 - PSK (a pre-shared key established externally or derived from the 4258 resumption_master_secret value from a previous connection) 4260 - (EC)DHE shared secret (Section 7.4) 4262 This produces a full key derivation schedule shown in the diagram 4263 below. In this diagram, the following formatting conventions apply: 4265 - HKDF-Extract is drawn as taking the Salt argument from the top and 4266 the IKM argument from the left. 4268 - Derive-Secret's Secret argument is indicated by the incoming 4269 arrow. For instance, the Early Secret is the Secret for 4270 generating the client_early_traffic_secret. 4272 0 4273 | 4274 v 4275 PSK -> HKDF-Extract = Early Secret 4276 | 4277 +-----> Derive-Secret(., 4278 | "ext binder" | 4279 | "res binder", 4280 | "") 4281 | = binder_key 4282 | 4283 +-----> Derive-Secret(., "c e traffic", 4284 | ClientHello) 4285 | = client_early_traffic_secret 4286 | 4287 +-----> Derive-Secret(., "e exp master", 4288 | ClientHello) 4289 | = early_exporter_master_secret 4290 v 4291 Derive-Secret(., "derived", "") 4292 | 4293 v 4294 (EC)DHE -> HKDF-Extract = Handshake Secret 4295 | 4296 +-----> Derive-Secret(., "c hs traffic", 4297 | ClientHello...ServerHello) 4298 | = client_handshake_traffic_secret 4299 | 4300 +-----> Derive-Secret(., "s hs traffic", 4301 | ClientHello...ServerHello) 4302 | = server_handshake_traffic_secret 4303 v 4304 Derive-Secret(., "derived", "") 4305 | 4306 v 4307 0 -> HKDF-Extract = Master Secret 4308 | 4309 +-----> Derive-Secret(., "c ap traffic", 4310 | ClientHello...server Finished) 4311 | = client_application_traffic_secret_0 4312 | 4313 +-----> Derive-Secret(., "s ap traffic", 4314 | ClientHello...server Finished) 4315 | = server_application_traffic_secret_0 4316 | 4317 +-----> Derive-Secret(., "exp master", 4318 | ClientHello...server Finished) 4319 | = exporter_master_secret 4320 | 4321 +-----> Derive-Secret(., "res master", 4322 ClientHello...client Finished) 4323 = resumption_master_secret 4325 The general pattern here is that the secrets shown down the left side 4326 of the diagram are just raw entropy without context, whereas the 4327 secrets down the right side include handshake context and therefore 4328 can be used to derive working keys without additional context. Note 4329 that the different calls to Derive-Secret may take different Messages 4330 arguments, even with the same secret. In a 0-RTT exchange, Derive- 4331 Secret is called with four distinct transcripts; in a 1-RTT-only 4332 exchange with three distinct transcripts. 4334 If a given secret is not available, then the 0-value consisting of a 4335 string of Hash.length bytes set to zeros is used. Note that this 4336 does not mean skipping rounds, so if PSK is not in use Early Secret 4337 will still be HKDF-Extract(0, 0). For the computation of the 4338 binder_secret, the label is "ext binder" for external PSKs (those 4339 provisioned outside of TLS) and "res binder" for resumption PSKs 4340 (those provisioned as the resumption master secret of a previous 4341 handshake). The different labels prevent the substitution of one 4342 type of PSK for the other. 4344 There are multiple potential Early Secret values depending on which 4345 PSK the server ultimately selects. The client will need to compute 4346 one for each potential PSK; if no PSK is selected, it will then need 4347 to compute the early secret corresponding to the zero PSK. 4349 Once all the values which are to be derived from a given secret have 4350 been computed, that secret SHOULD be erased. 4352 7.2. Updating Traffic Keys and IVs 4354 Once the handshake is complete, it is possible for either side to 4355 update its sending traffic keys using the KeyUpdate handshake message 4356 defined in Section 4.6.3. The next generation of traffic keys is 4357 computed by generating client_/server_application_traffic_secret_N+1 4358 from client_/server_application_traffic_secret_N as described in this 4359 section then re-deriving the traffic keys as described in 4360 Section 7.3. 4362 The next-generation application_traffic_secret is computed as: 4364 application_traffic_secret_N+1 = 4365 HKDF-Expand-Label(application_traffic_secret_N, 4366 "traffic upd", "", Hash.length) 4368 Once client/server_application_traffic_secret_N+1 and its associated 4369 traffic keys have been computed, implementations SHOULD delete 4370 client_/server_application_traffic_secret_N and its associated 4371 traffic keys. 4373 7.3. Traffic Key Calculation 4375 The traffic keying material is generated from the following input 4376 values: 4378 - A secret value 4380 - A purpose value indicating the specific value being generated 4382 - The length of the key 4384 The traffic keying material is generated from an input traffic secret 4385 value using: 4387 [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) 4388 [sender]_write_iv = HKDF-Expand-Label(Secret, "iv" , "", iv_length) 4390 [sender] denotes the sending side. The Secret value for each record 4391 type is shown in the table below. 4393 +-------------------+---------------------------------------+ 4394 | Record Type | Secret | 4395 +-------------------+---------------------------------------+ 4396 | 0-RTT Application | client_early_traffic_secret | 4397 | | | 4398 | Handshake | [sender]_handshake_traffic_secret | 4399 | | | 4400 | Application Data | [sender]_application_traffic_secret_N | 4401 +-------------------+---------------------------------------+ 4403 All the traffic keying material is recomputed whenever the underlying 4404 Secret changes (e.g., when changing from the handshake to application 4405 data keys or upon a key update). 4407 7.4. (EC)DHE Shared Secret Calculation 4408 7.4.1. Finite Field Diffie-Hellman 4410 For finite field groups, a conventional Diffie-Hellman computation is 4411 performed. The negotiated key (Z) is converted to a byte string by 4412 encoding in big-endian and padded with zeros up to the size of the 4413 prime. This byte string is used as the shared secret in the key 4414 schedule as specified above. 4416 Note that this construction differs from previous versions of TLS 4417 which remove leading zeros. 4419 7.4.2. Elliptic Curve Diffie-Hellman 4421 For secp256r1, secp384r1 and secp521r1, ECDH calculations (including 4422 parameter and key generation as well as the shared secret 4423 calculation) are performed according to [IEEE1363] using the ECKAS- 4424 DH1 scheme with the identity map as key derivation function (KDF), so 4425 that the shared secret is the x-coordinate of the ECDH shared secret 4426 elliptic curve point represented as an octet string. Note that this 4427 octet string (Z in IEEE 1363 terminology) as output by FE2OSP, the 4428 Field Element to Octet String Conversion Primitive, has constant 4429 length for any given field; leading zeros found in this octet string 4430 MUST NOT be truncated. 4432 (Note that this use of the identity KDF is a technicality. The 4433 complete picture is that ECDH is employed with a non-trivial KDF 4434 because TLS does not directly use this secret for anything other than 4435 for computing other secrets.) 4437 ECDH functions are used as follows: 4439 - The public key to put into the KeyShareEntry.key_exchange 4440 structure is the result of applying the ECDH scalar multiplication 4441 function to the secret key of appropriate length (into scalar 4442 input) and the standard public basepoint (into u-coordinate point 4443 input). 4445 - The ECDH shared secret is the result of applying the ECDH scalar 4446 multiplication function to the secret key (into scalar input) and 4447 the peer's public key (into u-coordinate point input). The output 4448 is used raw, with no processing. 4450 For X25519 and X448, implementations SHOULD use the approach 4451 specified in [RFC7748] to calculate the Diffie-Hellman shared secret. 4452 Implementations MUST check whether the computed Diffie-Hellman shared 4453 secret is the all-zero value and abort if so, as described in 4454 Section 6 of [RFC7748]. If implementers use an alternative 4455 implementation of these elliptic curves, they SHOULD perform the 4456 additional checks specified in Section 7 of [RFC7748]. 4458 7.5. Exporters 4460 [RFC5705] defines keying material exporters for TLS in terms of the 4461 TLS pseudorandom function (PRF). This document replaces the PRF with 4462 HKDF, thus requiring a new construction. The exporter interface 4463 remains the same. 4465 The exporter value is computed as: 4467 TLS-Exporter(label, context_value, key_length) = 4468 HKDF-Expand-Label(Derive-Secret(Secret, label, ""), 4469 "exporter", Hash(context_value), key_length) 4471 Where Secret is either the early_exporter_master_secret or the 4472 exporter_master_secret. Implementations MUST use the 4473 exporter_master_secret unless explicitly specified by the 4474 application. The early_exporter_master_secret is defined for use in 4475 settings where an exporter is needed for 0-RTT data. A separate 4476 interface for the early exporter is RECOMMENDED, especially on a 4477 server where a single interface can make the early exporter 4478 inaccessible. 4480 If no context is provided, the context_value is zero-length. 4481 Consequently, providing no context computes the same value as 4482 providing an empty context. This is a change from previous versions 4483 of TLS where an empty context produced a different output to an 4484 absent context. As of this document's publication, no allocated 4485 exporter label is used both with and without a context. Future 4486 specifications MUST NOT define a use of exporters that permit both an 4487 empty context and no context with the same label. New uses of 4488 exporters SHOULD provide a context in all exporter computations, 4489 though the value could be empty. 4491 Requirements for the format of exporter labels are defined in section 4492 4 of [RFC5705]. 4494 8. 0-RTT and Anti-Replay 4496 As noted in Section 2.3 and Appendix E.5, TLS does not provide 4497 inherent replay protections for 0-RTT data. There are two potential 4498 threats to be concerned with: 4500 - Network attackers who mount a replay attack by simply duplicating 4501 a flight of 0-RTT data. 4503 - Network attackers who take advantage of client retry behavior to 4504 arrange for the server to receive multiple copies of an 4505 application message. This threat already exists to some extent 4506 because clients that value robustness respond to network errors by 4507 attempting to retry requests. However, 0-RTT adds an additional 4508 dimension for any server system which does not maintain globally 4509 consistent server state. Specifically, if a server system has 4510 multiple zones where tickets from zone A will not be accepted in 4511 zone B, then an attacker can duplicate a ClientHello and early 4512 data intended for A to both A and B. At A, the data will be 4513 accepted in 0-RTT, but at B the server will reject 0-RTT data and 4514 instead force a full handshake. If the attacker blocks the 4515 ServerHello from A, then the client will complete the handshake 4516 with B and probably retry the request, leading to duplication on 4517 the server system as a whole. 4519 The first class of attack can be prevented by sharing state to 4520 guarantee that the 0-RTT data is accepted at most once. Servers 4521 SHOULD provide that level of replay safety, by implementing one of 4522 the methods described in this section or by equivalent means. It is 4523 understood, however, that due to operational concerns not all 4524 deployments will maintain state at that level. Therefore, in normal 4525 operation, clients will not know which, if any, of these mechanisms 4526 servers actually implement and hence MUST only send early data which 4527 they deem safe to be replayed. 4529 In addition to the direct effects of replays, there is a class of 4530 attacks where even operations normally considered idempotent could be 4531 exploited by a large number of replays (timing attacks, resource 4532 limit exhaustion and others described in Appendix E.5). Those can be 4533 mitigated by ensuring that every 0-RTT payload can be replayed only a 4534 limited number of times. The server MUST ensure that any instance of 4535 it (be it a machine, a thread or any other entity within the relevant 4536 serving infrastructure) would accept 0-RTT for the same 0-RTT 4537 handshake at most once; this limits the number of replays to the 4538 number of server instances in the deployment. Such a guarantee can 4539 be accomplished by locally recording data from recently-received 4540 ClientHellos and rejecting repeats, or by any other method that 4541 provides the same or a stronger guarantee. The "at most once per 4542 server instance" guarantee is a minimum requirement; servers SHOULD 4543 limit 0-RTT replays further when feasible. 4545 The second class of attack cannot be prevented at the TLS layer and 4546 MUST be dealt with by any application. Note that any application 4547 whose clients implement any kind of retry behavior already needs to 4548 implement some sort of anti-replay defense. 4550 8.1. Single-Use Tickets 4552 The simplest form of anti-replay defense is for the server to only 4553 allow each session ticket to be used once. For instance, the server 4554 can maintain a database of all outstanding valid tickets; deleting 4555 each ticket from the database as it is used. If an unknown ticket is 4556 provided, the server would then fall back to a full handshake. 4558 If the tickets are not self-contained but rather are database keys, 4559 and the corresponding PSKs are deleted upon use, then connections 4560 established using one PSK enjoy forward secrecy. This improves 4561 security for all 0-RTT data and PSK usage when PSK is used without 4562 (EC)DHE. 4564 Because this mechanism requires sharing the session database between 4565 server nodes in environments with multiple distributed servers, it 4566 may be hard to achieve high rates of successful PSK 0-RTT connections 4567 when compared to self-encrypted tickets. Unlike session databases, 4568 session tickets can successfully do PSK-based session establishment 4569 even without consistent storage, though when 0-RTT is allowed they 4570 still require consistent storage for anti-replay of 0-RTT data, as 4571 detailed in the following section. 4573 8.2. Client Hello Recording 4575 An alternative form of anti-replay is to record a unique value 4576 derived from the ClientHello (generally either the random value or 4577 the PSK binder) and reject duplicates. Recording all ClientHellos 4578 causes state to grow without bound, but a server can instead record 4579 ClientHellos within a given time window and use the 4580 "obfuscated_ticket_age" to ensure that tickets aren't reused outside 4581 that window. 4583 In order to implement this, when a ClientHello is received, the 4584 server first verifies the PSK binder as described Section 4.2.11. It 4585 then computes the expected_arrival_time as described in the next 4586 section and rejects 0-RTT if it is outside the recording window, 4587 falling back to the 1-RTT handshake. 4589 If the expected arrival time is in the window, then the server checks 4590 to see if it has recorded a matching ClientHello. If one is found, 4591 it either aborts the handshake with an "illegal_parameter" alert or 4592 accepts the PSK but reject 0-RTT. If no matching ClientHello is 4593 found, then it accepts 0-RTT and then stores the ClientHello for as 4594 long as the expected_arrival_time is inside the window. Servers MAY 4595 also implement data stores with false positives, such as Bloom 4596 filters, in which case they MUST respond to apparent replay by 4597 rejecting 0-RTT but MUST NOT abort the handshake. 4599 The server MUST derive the storage key only from validated sections 4600 of the ClientHello. If the ClientHello contains multiple PSK 4601 identities, then an attacker can create multiple ClientHellos with 4602 different binder values for the less-preferred identity on the 4603 assumption that the server will not verify it, as recommended by 4604 Section 4.2.11. I.e., if the client sends PSKs A and B but the 4605 server prefers A, then the attacker can change the binder for B 4606 without affecting the binder for A. This will cause the ClientHello 4607 to be accepted, and may cause side effects such as replay cache 4608 pollution, although any 0-RTT data will not be decryptable because it 4609 will use different keys. If the validated binder or the 4610 ClientHello.random are used as the storage key, then this attack is 4611 not possible. 4613 Because this mechanism does not require storing all outstanding 4614 tickets, it may be easier to implement in distributed systems with 4615 high rates of resumption and 0-RTT, at the cost of potentially weaker 4616 anti-replay defense because of the difficulty of reliably storing and 4617 retrieving the received ClientHello messages. In many such systems, 4618 it is impractical to have globally consistent storage of all the 4619 received ClientHellos. In this case, the best anti-replay protection 4620 is provided by having a single storage zone be authoritative for a 4621 given ticket and refusing 0-RTT for that ticket in any other zone. 4622 This approach prevents simple replay by the attacker because only one 4623 zone will accept 0-RTT data. A weaker design is to implement 4624 separate storage for each zone but allow 0-RTT in any zone. This 4625 approach limits the number of replays to once per zone. Application 4626 message duplication of course remains possible with either design. 4628 When implementations are freshly started, they SHOULD reject 0-RTT as 4629 long as any portion of their recording window overlaps the startup 4630 time. Otherwise, they run the risk of accepting replays which were 4631 originally sent during that period. 4633 Note: If the client's clock is running much faster than the server's 4634 then a ClientHello may be received that is outside the window in the 4635 future, in which case it might be accepted for 1-RTT, causing a 4636 client retry, and then acceptable later for 0-RTT. This is another 4637 variant of the second form of attack described above. 4639 8.3. Freshness Checks 4641 Because the ClientHello indicates the time at which the client sent 4642 it, it is possible to efficiently determine whether a ClientHello was 4643 likely sent reasonably recently and only accept 0-RTT for such a 4644 ClientHello, otherwise falling back to a 1-RTT handshake. This is 4645 necessary for the ClientHello storage mechanism described in 4646 Section 8.2 because otherwise the server needs to store an unlimited 4647 number of ClientHellos and is a useful optimization for single-use 4648 tickets because it allows efficient rejection of ClientHellos which 4649 cannot be used for 0-RTT. 4651 In order to implement this mechanism, a server needs to store the 4652 time that the server generated the session ticket, offset by an 4653 estimate of the round trip time between client and server. I.e., 4655 adjusted_creation_time = creation_time + estimated_RTT 4657 This value can be encoded in the ticket, thus avoiding the need to 4658 keep state for each outstanding ticket. The server can determine the 4659 client's view of the age of the ticket by subtracting the ticket's 4660 "ticket_age_add value" from the "obfuscated_ticket_age" parameter in 4661 the client's "pre_shared_key" extension. The server can determine 4662 the "expected arrival time" of the ClientHello as: 4664 expected_arrival_time = adjusted_creation_time + clients_ticket_age 4666 When a new ClientHello is received, the expected_arrival_time is then 4667 compared against the current server wall clock time and if they 4668 differ by more than a certain amount, 0-RTT is rejected, though the 4669 1-RTT handshake can be allowed to complete. 4671 There are several potential sources of error that might cause 4672 mismatches between the expected arrival time and the measured time. 4673 Variations in client and server clock rates are likely to be minimal, 4674 though potentially with gross time corrections. Network propagation 4675 delays are the most likely causes of a mismatch in legitimate values 4676 for elapsed time. Both the NewSessionTicket and ClientHello messages 4677 might be retransmitted and therefore delayed, which might be hidden 4678 by TCP. For clients on the Internet, this implies windows on the 4679 order of ten seconds to account for errors in clocks and variations 4680 in measurements; other deployment scenarios may have different needs. 4681 Clock skew distributions are not symmetric, so the optimal tradeoff 4682 may involve an asymmetric range of permissible mismatch values. 4684 Note that freshness checking alone is not sufficient to prevent 4685 replays because it does not detect them during the error window, 4686 which, depending on bandwidth and system capacity could include 4687 billions of replays in real-world settings. In addition, this 4688 freshness checking is only done at the time the ClientHello is 4689 received, and not when later early application data records are 4690 received. After early data is accepted, records may continue to be 4691 streamed to the server over a longer time period. 4693 9. Compliance Requirements 4695 9.1. Mandatory-to-Implement Cipher Suites 4697 In the absence of an application profile standard specifying 4698 otherwise, a TLS-compliant application MUST implement the 4699 TLS_AES_128_GCM_SHA256 [GCM] cipher suite and SHOULD implement the 4700 TLS_AES_256_GCM_SHA384 [GCM] and TLS_CHACHA20_POLY1305_SHA256 4701 [RFC7539] cipher suites. (see Appendix B.4) 4703 A TLS-compliant application MUST support digital signatures with 4704 rsa_pkcs1_sha256 (for certificates), rsa_pss_rsae_sha256 (for 4705 CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A 4706 TLS-compliant application MUST support key exchange with secp256r1 4707 (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748]. 4709 9.2. Mandatory-to-Implement Extensions 4711 In the absence of an application profile standard specifying 4712 otherwise, a TLS-compliant application MUST implement the following 4713 TLS extensions: 4715 - Supported Versions ("supported_versions"; Section 4.2.1) 4717 - Cookie ("cookie"; Section 4.2.2) 4719 - Signature Algorithms ("signature_algorithms"; Section 4.2.3) 4721 - Signature Algorithms Certificate ("signature_algorithms_cert"; 4722 Section 4.2.3) 4724 - Negotiated Groups ("supported_groups"; Section 4.2.7) 4726 - Key Share ("key_share"; Section 4.2.8) 4728 - Server Name Indication ("server_name"; Section 3 of [RFC6066]) 4730 All implementations MUST send and use these extensions when offering 4731 applicable features: 4733 - "supported_versions" is REQUIRED for all ClientHello, ServerHello 4734 and HelloRetryRequest messages. 4736 - "signature_algorithms" is REQUIRED for certificate authentication. 4738 - "supported_groups" is REQUIRED for ClientHello messages using DHE 4739 or ECDHE key exchange. 4741 - "key_share" is REQUIRED for DHE or ECDHE key exchange. 4743 - "pre_shared_key" is REQUIRED for PSK key agreement. 4745 - "psk_key_exchange_modes" is REQUIRED for PSK key agreement. 4747 A client is considered to be attempting to negotiate using this 4748 specification if the ClientHello contains a "supported_versions" 4749 extension with 0x0304 as the highest version number contained in its 4750 body. Such a ClientHello message MUST meet the following 4751 requirements: 4753 - If not containing a "pre_shared_key" extension, it MUST contain 4754 both a "signature_algorithms" extension and a "supported_groups" 4755 extension. 4757 - If containing a "supported_groups" extension, it MUST also contain 4758 a "key_share" extension, and vice versa. An empty 4759 KeyShare.client_shares vector is permitted. 4761 Servers receiving a ClientHello which does not conform to these 4762 requirements MUST abort the handshake with a "missing_extension" 4763 alert. 4765 Additionally, all implementations MUST support use of the 4766 "server_name" extension with applications capable of using it. 4767 Servers MAY require clients to send a valid "server_name" extension. 4768 Servers requiring this extension SHOULD respond to a ClientHello 4769 lacking a "server_name" extension by terminating the connection with 4770 a "missing_extension" alert. 4772 9.3. Protocol Invariants 4774 This section describes invariants that TLS endpoints and middleboxes 4775 MUST follow. It also applies to earlier versions, which assumed 4776 these rules but did not document them. 4778 TLS is designed to be securely and compatibly extensible. Newer 4779 clients or servers, when communicating with newer peers, SHOULD 4780 negotiate the most preferred common parameters. The TLS handshake 4781 provides downgrade protection: Middleboxes passing traffic between a 4782 newer client and newer server without terminating TLS should be 4783 unable to influence the handshake (see Appendix E.1). At the same 4784 time, deployments update at different rates, so a newer client or 4785 server MAY continue to support older parameters, which would allow it 4786 to interoperate with older endpoints. 4788 For this to work, implementations MUST correctly handle extensible 4789 fields: 4791 - A client sending a ClientHello MUST support all parameters 4792 advertised in it. Otherwise, the server may fail to interoperate 4793 by selecting one of those parameters. 4795 - A server receiving a ClientHello MUST correctly ignore all 4796 unrecognized cipher suites, extensions, and other parameters. 4797 Otherwise, it may fail to interoperate with newer clients. In TLS 4798 1.3, a client receiving a CertificateRequest or NewSessionTicket 4799 MUST also ignore all unrecognized extensions. 4801 - A middlebox which terminates a TLS connection MUST behave as a 4802 compliant TLS server (to the original client), including having a 4803 certificate which the client is willing to accept, and as a 4804 compliant TLS client (to the original server), including verifying 4805 the original server's certificate. In particular, it MUST 4806 generate its own ClientHello containing only parameters it 4807 understands, and it MUST generate a fresh ServerHello random 4808 value, rather than forwarding the endpoint's value. 4810 Note that TLS's protocol requirements and security analysis only 4811 apply to the two connections separately. Safely deploying a TLS 4812 terminator requires additional security considerations which are 4813 beyond the scope of this document. 4815 - An middlebox which forwards ClientHello parameters it does not 4816 understand MUST NOT process any messages beyond that ClientHello. 4817 It MUST forward all subsequent traffic unmodified. Otherwise, it 4818 may fail to interoperate with newer clients and servers. 4820 Forwarded ClientHellos may contain advertisements for features not 4821 supported by the middlebox, so the response may include future TLS 4822 additions the middlebox does not recognize. These additions MAY 4823 change any message beyond the ClientHello arbitrarily. In 4824 particular, the values sent in the ServerHello might change, the 4825 ServerHello format might change, and the TLSCiphertext format 4826 might change. 4828 The design of TLS 1.3 was constrained by widely-deployed non- 4829 compliant TLS middleboxes (see Appendix D.4), however it does not 4830 relax the invariants. Those middleboxes continue to be non- 4831 compliant. 4833 10. Security Considerations 4835 Security issues are discussed throughout this memo, especially in 4836 Appendix C, Appendix D, and Appendix E. 4838 11. IANA Considerations 4840 This document uses several registries that were originally created in 4841 [RFC4346]. IANA [SHALL update/has updated] these to reference this 4842 document. The registries and their allocation policies are below: 4844 - TLS Cipher Suite Registry: values with the first byte in the range 4845 0-254 (decimal) are assigned via Specification Required [RFC8126]. 4846 Values with the first byte 255 (decimal) are reserved for Private 4847 Use [RFC8126]. 4849 IANA [SHALL add/has added] the cipher suites listed in 4850 Appendix B.4 to the registry. The "Value" and "Description" 4851 columns are taken from the table. The "DTLS-OK" and "Recommended" 4852 columns are both marked as "Yes" for each new cipher suite. 4853 [[This assumes [I-D.ietf-tls-iana-registry-updates] has been 4854 applied.]] 4856 - TLS ContentType Registry: Future values are allocated via 4857 Standards Action [RFC8126]. 4859 - TLS Alert Registry: Future values are allocated via Standards 4860 Action [RFC8126]. IANA [SHALL update/has updated] this registry 4861 to include values for "missing_extension" and 4862 "certificate_required". The "DTLS-OK" column is marked as "Yes" 4863 for each new alert. 4865 - TLS HandshakeType Registry: Future values are allocated via 4866 Standards Action [RFC8126]. IANA [SHALL update/has updated] this 4867 registry to rename item 4 from "NewSessionTicket" to 4868 "new_session_ticket" and to add the 4869 "hello_retry_request_RESERVED", "encrypted_extensions", 4870 "end_of_early_data", "key_update", and "message_hash" values. The 4871 "DTLS-OK" are marked as "Yes" for each of these additions. 4873 This document also uses the TLS ExtensionType Registry originally 4874 created in [RFC4366]. IANA has updated it to reference this 4875 document. Changes to the registry follow: 4877 - IANA [SHALL update/has updated] the registration policy as 4878 follows: 4880 Values with the first byte in the range 0-254 (decimal) are 4881 assigned via Specification Required [RFC8126]. Values with the 4882 first byte 255 (decimal) are reserved for Private Use [RFC8126]. 4884 - IANA [SHALL update/has updated] this registry to include the 4885 "key_share", "pre_shared_key", "psk_key_exchange_modes", 4886 "early_data", "cookie", "supported_versions", 4887 "certificate_authorities", "oid_filters", "post_handshake_auth", 4888 and "signature_algorithms_cert", extensions with the values 4889 defined in this document and the Recommended value of "Yes". 4891 - IANA [SHALL update/has updated] this registry to include a "TLS 4892 1.3" column which lists the messages in which the extension may 4893 appear. This column [SHALL be/has been] initially populated from 4894 the table in Section 4.2 with any extension not listed there 4895 marked as "-" to indicate that it is not used by TLS 1.3. 4897 In addition, this document defines a new registry to be maintained by 4898 IANA: 4900 - TLS SignatureScheme Registry: Values with the first byte in the 4901 range 0-253 (decimal) are assigned via Specification Required 4902 [RFC8126]. Values with the first byte 254 or 255 (decimal) are 4903 reserved for Private Use [RFC8126]. Values with the first byte in 4904 the range 0-6 or with the second byte in the range 0-3 that are 4905 not currently allocated are reserved for backwards compatibility. 4906 This registry SHALL have a "Recommended" column. The registry 4907 [shall be/ has been] initially populated with the values described 4908 in Section 4.2.3. The following values SHALL be marked as 4909 "Recommended": ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, 4910 rsa_pss_rsae_sha256, rsa_pss_rsae_sha384, rsa_pss_rsae_sha512, 4911 rsa_pss_pss_sha256, rsa_pss_pss_sha384, rsa_pss_pss_sha512, and 4912 ed25519. 4914 12. References 4916 12.1. Normative References 4918 [DH] Diffie, W. and M. Hellman, "New Directions in 4919 Cryptography", IEEE Transactions on Information Theory, 4920 V.IT-22 n.6 , June 1977. 4922 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 4923 Operation: Galois/Counter Mode (GCM) and GMAC", 4924 NIST Special Publication 800-38D, November 2007. 4926 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4927 Hashing for Message Authentication", RFC 2104, 4928 DOI 10.17487/RFC2104, February 1997, . 4931 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4932 Requirement Levels", BCP 14, RFC 2119, 4933 DOI 10.17487/RFC2119, March 1997, . 4936 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4937 Housley, R., and W. Polk, "Internet X.509 Public Key 4938 Infrastructure Certificate and Certificate Revocation List 4939 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4940 . 4942 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 4943 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 4944 March 2010, . 4946 [RFC5756] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 4947 "Updates for RSAES-OAEP and RSASSA-PSS Algorithm 4948 Parameters", RFC 5756, DOI 10.17487/RFC5756, January 2010, 4949 . 4951 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 4952 Key Derivation Function (HKDF)", RFC 5869, 4953 DOI 10.17487/RFC5869, May 2010, . 4956 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4957 Extensions: Extension Definitions", RFC 6066, 4958 DOI 10.17487/RFC6066, January 2011, . 4961 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4962 Transport Layer Security (TLS)", RFC 6655, 4963 DOI 10.17487/RFC6655, July 2012, . 4966 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 4967 Galperin, S., and C. Adams, "X.509 Internet Public Key 4968 Infrastructure Online Certificate Status Protocol - OCSP", 4969 RFC 6960, DOI 10.17487/RFC6960, June 2013, 4970 . 4972 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 4973 Multiple Certificate Status Request Extension", RFC 6961, 4974 DOI 10.17487/RFC6961, June 2013, . 4977 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 4978 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 4979 . 4981 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4982 Algorithm (DSA) and Elliptic Curve Digital Signature 4983 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4984 2013, . 4986 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 4987 "Transport Layer Security (TLS) Application-Layer Protocol 4988 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 4989 July 2014, . 4991 [RFC7507] Moeller, B. and A. Langley, "TLS Fallback Signaling Cipher 4992 Suite Value (SCSV) for Preventing Protocol Downgrade 4993 Attacks", RFC 7507, DOI 10.17487/RFC7507, April 2015, 4994 . 4996 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 4997 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 4998 . 5000 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 5001 for Security", RFC 7748, DOI 10.17487/RFC7748, January 5002 2016, . 5004 [RFC7919] Gillmor, D., "Negotiated Finite Field Diffie-Hellman 5005 Ephemeral Parameters for Transport Layer Security (TLS)", 5006 RFC 7919, DOI 10.17487/RFC7919, August 2016, 5007 . 5009 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 5010 "PKCS #1: RSA Cryptography Specifications Version 2.2", 5011 RFC 8017, DOI 10.17487/RFC8017, November 2016, 5012 . 5014 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 5015 Signature Algorithm (EdDSA)", RFC 8032, 5016 DOI 10.17487/RFC8032, January 2017, . 5019 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 5020 Writing an IANA Considerations Section in RFCs", BCP 26, 5021 RFC 8126, DOI 10.17487/RFC8126, June 2017, 5022 . 5024 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 5025 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 5026 May 2017, . 5028 [SHS] Dang, Q., "Secure Hash Standard", National Institute of 5029 Standards and Technology report, 5030 DOI 10.6028/nist.fips.180-4, July 2015. 5032 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 5033 Specification of Basic Encoding Rules (BER), Canonical 5034 Encoding Rules (CER) and Distinguished Encoding Rules 5035 (DER)", ISO/IEC 8825-1:2002, 2002. 5037 [X962] ANSI, "Public Key Cryptography For The Financial Services 5038 Industry: The Elliptic Curve Digital Signature Algorithm 5039 (ECDSA)", ANSI X9.62, 1998. 5041 12.2. Informative References 5043 [AEAD-LIMITS] 5044 Luykx, A. and K. Paterson, "Limits on Authenticated 5045 Encryption Use in TLS", 2016, 5046 . 5048 [Anon18] Anonymous, A., "Secure Channels for Multiplexed Data 5049 Streams: Analyzing the TLS 1.3 Record Layer Without 5050 Elision", In submission to CRYPTO 2018. RFC EDITOR: PLEASE 5051 UPDATE THIS REFERENCE AFTER FINAL NOTIFICATION 5052 (2018-4-29). , 2018. 5054 [BBFKZG16] 5055 Bhargavan, K., Brzuska, C., Fournet, C., Kohlweiss, M., 5056 Zanella-Beguelin, S., and M. Green, "Downgrade Resilience 5057 in Key-Exchange Protocols", Proceedings of IEEE Symposium 5058 on Security and Privacy (Oakland) 2016 , 2016. 5060 [BBK17] Bhargavan, K., Blanchet, B., and N. Kobeissi, "Verified 5061 Models and Reference Implementations for the TLS 1.3 5062 Standard Candidate", Proceedings of IEEE Symposium on 5063 Security and Privacy (Oakland) 2017 , 2017. 5065 [BDFKPPRSZZ16] 5066 Bhargavan, K., Delignat-Lavaud, A., Fournet, C., 5067 Kohlweiss, M., Pan, J., Protzenko, J., Rastogi, A., Swamy, 5068 N., Zanella-Beguelin, S., and J. Zinzindohoue, 5069 "Implementing and Proving the TLS 1.3 Record Layer", 5070 Proceedings of IEEE Symposium on Security and Privacy 5071 (Oakland) 2017 , December 2016, 5072 . 5074 [Ben17a] Benjamin, D., "Presentation before the TLS WG at IETF 5075 100", 2017, 5076 . 5079 [Ben17b] Benjamin, D., "Additional TLS 1.3 results from Chrome", 5080 2017, . 5083 [BMMT15] Badertscher, C., Matt, C., Maurer, U., and B. Tackmann, 5084 "Augmented Secure Channels and the Goal of the TLS 1.3 5085 Record Layer", ProvSec 2015 , September 2015, 5086 . 5088 [BT16] Bellare, M. and B. Tackmann, "The Multi-User Security of 5089 Authenticated Encryption: AES-GCM in TLS 1.3", Proceedings 5090 of CRYPTO 2016 , 2016, . 5092 [CCG16] Cohn-Gordon, K., Cremers, C., and L. Garratt, "On Post- 5093 Compromise Security", IEEE Computer Security Foundations 5094 Symposium , 2015. 5096 [CHECKOWAY] 5097 Checkoway, S., Shacham, H., Maskiewicz, J., Garman, C., 5098 Fried, J., Cohney, S., Green, M., Heninger, N., Weinmann, 5099 R., and E. Rescorla, "A Systematic Analysis of the Juniper 5100 Dual EC Incident", Proceedings of the 2016 ACM SIGSAC 5101 Conference on Computer and Communications Security 5102 - CCS'16, DOI 10.1145/2976749.2978395, 2016. 5104 [CHHSV17] Cremers, C., Horvat, M., Hoyland, J., van der Merwe, T., 5105 and S. Scott, "Awkward Handshake: Possible mismatch of 5106 client/server view on client authentication in post- 5107 handshake mode in Revision 18", 2017, 5108 . 5111 [CHSV16] Cremers, C., Horvat, M., Scott, S., and T. van der Merwe, 5112 "Automated Analysis and Verification of TLS 1.3: 0-RTT, 5113 Resumption and Delayed Authentication", Proceedings of 5114 IEEE Symposium on Security and Privacy (Oakland) 2016 , 5115 2016, . 5117 [CK01] Canetti, R. and H. Krawczyk, "Analysis of Key-Exchange 5118 Protocols and Their Use for Building Secure Channels", 5119 Proceedings of Eurocrypt 2001 , 2001. 5121 [CLINIC] Miller, B., Huang, L., Joseph, A., and J. Tygar, "I Know 5122 Why You Went to the Clinic: Risks and Realization of HTTPS 5123 Traffic Analysis", Privacy Enhancing Technologies pp. 5124 143-163, DOI 10.1007/978-3-319-08506-7_8, 2014. 5126 [DFGS15] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 5127 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 5128 Pre-shared Key Handshake Protocol", Proceedings of ACM CCS 5129 2015 , 2015, . 5131 [DFGS16] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 5132 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 5133 Pre-shared Key Handshake Protocol", TRON 2016 , 2016, 5134 . 5136 [DOW92] Diffie, W., van Oorschot, P., and M. Wiener, 5137 ""Authentication and authenticated key exchanges"", 5138 Designs, Codes and Cryptography , 1992. 5140 [DSS] National Institute of Standards and Technology, U.S. 5141 Department of Commerce, "Digital Signature Standard, 5142 version 4", NIST FIPS PUB 186-4, 2013. 5144 [ECDSA] American National Standards Institute, "Public Key 5145 Cryptography for the Financial Services Industry: The 5146 Elliptic Curve Digital Signature Algorithm (ECDSA)", 5147 ANSI ANS X9.62-2005, November 2005. 5149 [FG17] Fischlin, M. and F. Guenther, "Replay Attacks on Zero 5150 Round-Trip Time: The Case of the TLS 1.3 Handshake 5151 Candidates", Proceedings of Euro S"P 2017 , 2017, 5152 . 5154 [FGSW16] Fischlin, M., Guenther, F., Schmidt, B., and B. Warinschi, 5155 "Key Confirmation in Key Exchange: A Formal Treatment and 5156 Implications for TLS 1.3", Proceedings of IEEE Symposium 5157 on Security and Privacy (Oakland) 2016 , 2016, 5158 . 5160 [FW15] Florian Weimer, ., "Factoring RSA Keys With TLS Perfect 5161 Forward Secrecy", September 2015. 5163 [HCJ16] Husak, M., Čermak, M., Jirsik, T., and P. 5164 Čeleda, "HTTPS traffic analysis and client 5165 identification using passive SSL/TLS fingerprinting", 5166 EURASIP Journal on Information Security Vol. 2016, 5167 DOI 10.1186/s13635-016-0030-7, February 2016. 5169 [HGFS15] Hlauschek, C., Gruber, M., Fankhauser, F., and C. Schanes, 5170 "Prying Open Pandora's Box: KCI Attacks against TLS", 5171 Proceedings of USENIX Workshop on Offensive Technologies , 5172 2015. 5174 [I-D.ietf-tls-iana-registry-updates] 5175 Salowey, J. and S. Turner, "IANA Registry Updates for TLS 5176 and DTLS", draft-ietf-tls-iana-registry-updates-04 (work 5177 in progress), February 2018. 5179 [I-D.ietf-tls-tls13-vectors] 5180 Thomson, M., "Example Handshake Traces for TLS 1.3", 5181 draft-ietf-tls-tls13-vectors-03 (work in progress), 5182 December 2017. 5184 [IEEE1363] 5185 IEEE, "Standard Specifications for Public Key 5186 Cryptography", IEEE 1363 , 2000. 5188 [JSS15] Jager, T., Schwenk, J., and J. Somorovsky, "On the 5189 Security of TLS 1.3 and QUIC Against Weaknesses in PKCS#1 5190 v1.5 Encryption", Proceedings of ACM CCS 2015 , 2015, 5191 . 5194 [KEYAGREEMENT] 5195 Barker, E., Chen, L., Roginsky, A., and M. Smid, 5196 "Recommendation for Pair-Wise Key Establishment Schemes 5197 Using Discrete Logarithm Cryptography", National Institute 5198 of Standards and Technology report, 5199 DOI 10.6028/nist.sp.800-56ar2, May 2013. 5201 [Kraw10] Krawczyk, H., "Cryptographic Extraction and Key 5202 Derivation: The HKDF Scheme", Proceedings of CRYPTO 2010 , 5203 2010, . 5205 [Kraw16] Krawczyk, H., "A Unilateral-to-Mutual Authentication 5206 Compiler for Key Exchange (with Applications to Client 5207 Authentication in TLS 1.3", Proceedings of ACM CCS 2016 , 5208 2016, . 5210 [KW16] Krawczyk, H. and H. Wee, "The OPTLS Protocol and TLS 1.3", 5211 Proceedings of Euro S"P 2016 , 2016, 5212 . 5214 [LXZFH16] Li, X., Xu, J., Feng, D., Zhang, Z., and H. Hu, "Multiple 5215 Handshakes Security of TLS 1.3 Candidates", Proceedings of 5216 IEEE Symposium on Security and Privacy (Oakland) 2016 , 5217 2016, . 5219 [Mac17] MacCarthaigh, C., "Security Review of TLS1.3 0-RTT", 2017, 5220 . 5222 [PSK-FINISHED] 5223 Cremers, C., Horvat, M., van der Merwe, T., and S. Scott, 5224 "Revision 10: possible attack if client authentication is 5225 allowed during PSK", 2015, . 5228 [REKEY] Abdalla, M. and M. Bellare, "Increasing the Lifetime of a 5229 Key: A Comparative Analysis of the Security of Re-keying 5230 Techniques", ASIACRYPT2000 , October 2000. 5232 [Res17a] Rescorla, E., "Preliminary data on Firefox TLS 1.3 5233 Middlebox experiment", 2017, . 5236 [Res17b] Rescorla, E., "More compatibility measurement results", 5237 2017, . 5240 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 5241 Text on Security Considerations", BCP 72, RFC 3552, 5242 DOI 10.17487/RFC3552, July 2003, . 5245 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 5246 "Randomness Requirements for Security", BCP 106, RFC 4086, 5247 DOI 10.17487/RFC4086, June 2005, . 5250 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 5251 (TLS) Protocol Version 1.1", RFC 4346, 5252 DOI 10.17487/RFC4346, April 2006, . 5255 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 5256 and T. Wright, "Transport Layer Security (TLS) 5257 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006, 5258 . 5260 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 5261 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 5262 for Transport Layer Security (TLS)", RFC 4492, 5263 DOI 10.17487/RFC4492, May 2006, . 5266 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 5267 "Transport Layer Security (TLS) Session Resumption without 5268 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 5269 January 2008, . 5271 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 5272 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 5273 . 5275 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 5276 (TLS) Protocol Version 1.2", RFC 5246, 5277 DOI 10.17487/RFC5246, August 2008, . 5280 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 5281 Security (DTLS) Extension to Establish Keys for the Secure 5282 Real-time Transport Protocol (SRTP)", RFC 5764, 5283 DOI 10.17487/RFC5764, May 2010, . 5286 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 5287 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010, 5288 . 5290 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys 5291 for Transport Layer Security (TLS) Authentication", 5292 RFC 6091, DOI 10.17487/RFC6091, February 2011, 5293 . 5295 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 5296 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176, March 5297 2011, . 5299 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 5300 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 5301 January 2012, . 5303 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 5304 Layer Security (TLS) and Datagram Transport Layer Security 5305 (DTLS) Heartbeat Extension", RFC 6520, 5306 DOI 10.17487/RFC6520, February 2012, . 5309 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 5310 Protocol (HTTP/1.1): Message Syntax and Routing", 5311 RFC 7230, DOI 10.17487/RFC7230, June 2014, 5312 . 5314 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 5315 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 5316 Transport Layer Security (TLS) and Datagram Transport 5317 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 5318 June 2014, . 5320 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 5321 DOI 10.17487/RFC7465, February 2015, . 5324 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 5325 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 5326 DOI 10.17487/RFC7568, June 2015, . 5329 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 5330 Langley, A., and M. Ray, "Transport Layer Security (TLS) 5331 Session Hash and Extended Master Secret Extension", 5332 RFC 7627, DOI 10.17487/RFC7627, September 2015, 5333 . 5335 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello 5336 Padding Extension", RFC 7685, DOI 10.17487/RFC7685, 5337 October 2015, . 5339 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 5340 (TLS) Cached Information Extension", RFC 7924, 5341 DOI 10.17487/RFC7924, July 2016, . 5344 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 5345 Better Connectivity Using Concurrency", RFC 8305, 5346 DOI 10.17487/RFC8305, December 2017, . 5349 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 5350 Obtaining Digital Signatures and Public-Key 5351 Cryptosystems", Communications of the ACM v. 21, n. 2, pp. 5352 120-126., February 1978. 5354 [SIGMA] Krawczyk, H., "SIGMA: the 'SIGn-and-MAc' approach to 5355 authenticated Diffie-Hellman and its use in the IKE 5356 protocols", Proceedings of CRYPTO 2003 , 2003. 5358 [SLOTH] Bhargavan, K. and G. Leurent, "Transcript Collision 5359 Attacks: Breaking Authentication in TLS, IKE, and SSH", 5360 Network and Distributed System Security Symposium (NDSS 5361 2016) , 2016. 5363 [SSL2] Hickman, K., "The SSL Protocol", February 1995. 5365 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 5366 Protocol", November 1996. 5368 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 5369 practical", USENIX Security Symposium, 2003. 5371 [X501] "Information Technology - Open Systems Interconnection - 5372 The Directory: Models", ITU-T X.501, 1993. 5374 12.3. URIs 5376 [1] mailto:tls@ietf.org 5378 Appendix A. State Machine 5380 This section provides a summary of the legal state transitions for 5381 the client and server handshakes. State names (in all capitals, 5382 e.g., START) have no formal meaning but are provided for ease of 5383 comprehension. Actions which are taken only in certain circumstances 5384 are indicated in []. The notation "K_{send,recv} = foo" means "set 5385 the send/recv key to the given key". 5387 A.1. Client 5389 START <----+ 5390 Send ClientHello | | Recv HelloRetryRequest 5391 [K_send = early data] | | 5392 v | 5393 / WAIT_SH ----+ 5394 | | Recv ServerHello 5395 | | K_recv = handshake 5396 Can | V 5397 send | WAIT_EE 5398 early | | Recv EncryptedExtensions 5399 data | +--------+--------+ 5400 | Using | | Using certificate 5401 | PSK | v 5402 | | WAIT_CERT_CR 5403 | | Recv | | Recv CertificateRequest 5404 | | Certificate | v 5405 | | | WAIT_CERT 5406 | | | | Recv Certificate 5407 | | v v 5408 | | WAIT_CV 5409 | | | Recv CertificateVerify 5410 | +> WAIT_FINISHED <+ 5411 | | Recv Finished 5412 \ | [Send EndOfEarlyData] 5413 | K_send = handshake 5414 | [Send Certificate [+ CertificateVerify]] 5415 Can send | Send Finished 5416 app data --> | K_send = K_recv = application 5417 after here v 5418 CONNECTED 5420 Note that with the transitions as shown above, clients may send 5421 alerts that derive from post-ServerHello messages in the clear or 5422 with the early data keys. If clients need to send such alerts, they 5423 SHOULD first rekey to the handshake keys if possible. 5425 A.2. Server 5427 START <-----+ 5428 Recv ClientHello | | Send HelloRetryRequest 5429 v | 5430 RECVD_CH ----+ 5431 | Select parameters 5432 v 5433 NEGOTIATED 5434 | Send ServerHello 5435 | K_send = handshake 5436 | Send EncryptedExtensions 5437 | [Send CertificateRequest] 5438 Can send | [Send Certificate + CertificateVerify] 5439 app data | Send Finished 5440 after --> | K_send = application 5441 here +--------+--------+ 5442 No 0-RTT | | 0-RTT 5443 | | 5444 K_recv = handshake | | K_recv = early data 5445 [Skip decrypt errors] | +------> WAIT_EOED -+ 5446 | | Recv | | Recv EndOfEarlyData 5447 | | early data | | K_recv = handshake 5448 | +------------+ | 5449 | | 5450 +> WAIT_FLIGHT2 <--------+ 5451 | 5452 +--------+--------+ 5453 No auth | | Client auth 5454 | | 5455 | v 5456 | WAIT_CERT 5457 | Recv | | Recv Certificate 5458 | empty | v 5459 | Certificate | WAIT_CV 5460 | | | Recv 5461 | v | CertificateVerify 5462 +-> WAIT_FINISHED <---+ 5463 | Recv Finished 5464 | K_recv = application 5465 v 5466 CONNECTED 5468 Appendix B. Protocol Data Structures and Constant Values 5470 This section describes protocol types and constants. Values listed 5471 as _RESERVED were used in previous versions of TLS and are listed 5472 here for completeness. TLS 1.3 implementations MUST NOT send them 5473 but might receive them from older TLS implementations. 5475 B.1. Record Layer 5477 enum { 5478 invalid(0), 5479 change_cipher_spec(20), 5480 alert(21), 5481 handshake(22), 5482 application_data(23), 5483 (255) 5484 } ContentType; 5486 struct { 5487 ContentType type; 5488 ProtocolVersion legacy_record_version; 5489 uint16 length; 5490 opaque fragment[TLSPlaintext.length]; 5491 } TLSPlaintext; 5493 struct { 5494 opaque content[TLSPlaintext.length]; 5495 ContentType type; 5496 uint8 zeros[length_of_padding]; 5497 } TLSInnerPlaintext; 5499 struct { 5500 ContentType opaque_type = application_data; /* 23 */ 5501 ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */ 5502 uint16 length; 5503 opaque encrypted_record[TLSCiphertext.length]; 5504 } TLSCiphertext; 5506 B.2. Alert Messages 5507 enum { warning(1), fatal(2), (255) } AlertLevel; 5509 enum { 5510 close_notify(0), 5511 unexpected_message(10), 5512 bad_record_mac(20), 5513 decryption_failed_RESERVED(21), 5514 record_overflow(22), 5515 decompression_failure_RESERVED(30), 5516 handshake_failure(40), 5517 no_certificate_RESERVED(41), 5518 bad_certificate(42), 5519 unsupported_certificate(43), 5520 certificate_revoked(44), 5521 certificate_expired(45), 5522 certificate_unknown(46), 5523 illegal_parameter(47), 5524 unknown_ca(48), 5525 access_denied(49), 5526 decode_error(50), 5527 decrypt_error(51), 5528 export_restriction_RESERVED(60), 5529 protocol_version(70), 5530 insufficient_security(71), 5531 internal_error(80), 5532 inappropriate_fallback(86), 5533 user_canceled(90), 5534 no_renegotiation_RESERVED(100), 5535 missing_extension(109), 5536 unsupported_extension(110), 5537 certificate_unobtainable(111), 5538 unrecognized_name(112), 5539 bad_certificate_status_response(113), 5540 bad_certificate_hash_value(114), 5541 unknown_psk_identity(115), 5542 certificate_required(116), 5543 no_application_protocol(120), 5544 (255) 5545 } AlertDescription; 5547 struct { 5548 AlertLevel level; 5549 AlertDescription description; 5550 } Alert; 5552 B.3. Handshake Protocol 5554 enum { 5555 hello_request_RESERVED(0), 5556 client_hello(1), 5557 server_hello(2), 5558 hello_verify_request_RESERVED(3), 5559 new_session_ticket(4), 5560 end_of_early_data(5), 5561 hello_retry_request_RESERVED(6), 5562 encrypted_extensions(8), 5563 certificate(11), 5564 server_key_exchange_RESERVED(12), 5565 certificate_request(13), 5566 server_hello_done_RESERVED(14), 5567 certificate_verify(15), 5568 client_key_exchange_RESERVED(16), 5569 finished(20), 5570 key_update(24), 5571 message_hash(254), 5572 (255) 5573 } HandshakeType; 5575 struct { 5576 HandshakeType msg_type; /* handshake type */ 5577 uint24 length; /* bytes in message */ 5578 select (Handshake.msg_type) { 5579 case client_hello: ClientHello; 5580 case server_hello: ServerHello; 5581 case end_of_early_data: EndOfEarlyData; 5582 case encrypted_extensions: EncryptedExtensions; 5583 case certificate_request: CertificateRequest; 5584 case certificate: Certificate; 5585 case certificate_verify: CertificateVerify; 5586 case finished: Finished; 5587 case new_session_ticket: NewSessionTicket; 5588 case key_update: KeyUpdate; 5589 }; 5590 } Handshake; 5592 B.3.1. Key Exchange Messages 5594 uint16 ProtocolVersion; 5595 opaque Random[32]; 5597 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 5599 struct { 5600 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 5601 Random random; 5602 opaque legacy_session_id<0..32>; 5603 CipherSuite cipher_suites<2..2^16-2>; 5604 opaque legacy_compression_methods<1..2^8-1>; 5605 Extension extensions<8..2^16-1>; 5606 } ClientHello; 5608 struct { 5609 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 5610 Random random; 5611 opaque legacy_session_id_echo<0..32>; 5612 CipherSuite cipher_suite; 5613 uint8 legacy_compression_method = 0; 5614 Extension extensions<6..2^16-1>; 5615 } ServerHello; 5617 struct { 5618 ExtensionType extension_type; 5619 opaque extension_data<0..2^16-1>; 5620 } Extension; 5622 enum { 5623 server_name(0), /* RFC 6066 */ 5624 max_fragment_length(1), /* RFC 6066 */ 5625 status_request(5), /* RFC 6066 */ 5626 supported_groups(10), /* RFC 4492, 7919 */ 5627 signature_algorithms(13), /* [[this document]] */ 5628 use_srtp(14), /* RFC 5764 */ 5629 heartbeat(15), /* RFC 6520 */ 5630 application_layer_protocol_negotiation(16), /* RFC 7301 */ 5631 signed_certificate_timestamp(18), /* RFC 6962 */ 5632 client_certificate_type(19), /* RFC 7250 */ 5633 server_certificate_type(20), /* RFC 7250 */ 5634 padding(21), /* RFC 7685 */ 5635 RESERVED(40), /* Used but never assigned */ 5636 pre_shared_key(41), /* [[this document]] */ 5637 early_data(42), /* [[this document]] */ 5638 supported_versions(43), /* [[this document]] */ 5639 cookie(44), /* [[this document]] */ 5640 psk_key_exchange_modes(45), /* [[this document]] */ 5641 RESERVED(46), /* Used but never assigned */ 5642 certificate_authorities(47), /* [[this document]] */ 5643 oid_filters(48), /* [[this document]] */ 5644 post_handshake_auth(49), /* [[this document]] */ 5645 signature_algorithms_cert(50), /* [[this document]] */ 5646 key_share(51), /* [[this document]] */ 5647 (65535) 5649 } ExtensionType; 5651 struct { 5652 NamedGroup group; 5653 opaque key_exchange<1..2^16-1>; 5654 } KeyShareEntry; 5656 struct { 5657 KeyShareEntry client_shares<0..2^16-1>; 5658 } KeyShareClientHello; 5660 struct { 5661 NamedGroup selected_group; 5662 } KeyShareHelloRetryRequest; 5664 struct { 5665 KeyShareEntry server_share; 5666 } KeyShareServerHello; 5668 struct { 5669 uint8 legacy_form = 4; 5670 opaque X[coordinate_length]; 5671 opaque Y[coordinate_length]; 5672 } UncompressedPointRepresentation; 5674 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 5676 struct { 5677 PskKeyExchangeMode ke_modes<1..255>; 5678 } PskKeyExchangeModes; 5680 struct {} Empty; 5682 struct { 5683 select (Handshake.msg_type) { 5684 case new_session_ticket: uint32 max_early_data_size; 5685 case client_hello: Empty; 5686 case encrypted_extensions: Empty; 5687 }; 5688 } EarlyDataIndication; 5690 struct { 5691 opaque identity<1..2^16-1>; 5692 uint32 obfuscated_ticket_age; 5693 } PskIdentity; 5695 opaque PskBinderEntry<32..255>; 5696 struct { 5697 PskIdentity identities<7..2^16-1>; 5698 PskBinderEntry binders<33..2^16-1>; 5699 } OfferedPsks; 5701 struct { 5702 select (Handshake.msg_type) { 5703 case client_hello: OfferedPsks; 5704 case server_hello: uint16 selected_identity; 5705 }; 5706 } PreSharedKeyExtension; 5708 B.3.1.1. Version Extension 5710 struct { 5711 select (Handshake.msg_type) { 5712 case client_hello: 5713 ProtocolVersion versions<2..254>; 5715 case server_hello: /* and HelloRetryRequest */ 5716 ProtocolVersion selected_version; 5717 }; 5718 } SupportedVersions; 5720 B.3.1.2. Cookie Extension 5722 struct { 5723 opaque cookie<1..2^16-1>; 5724 } Cookie; 5726 B.3.1.3. Signature Algorithm Extension 5727 enum { 5728 /* RSASSA-PKCS1-v1_5 algorithms */ 5729 rsa_pkcs1_sha256(0x0401), 5730 rsa_pkcs1_sha384(0x0501), 5731 rsa_pkcs1_sha512(0x0601), 5733 /* ECDSA algorithms */ 5734 ecdsa_secp256r1_sha256(0x0403), 5735 ecdsa_secp384r1_sha384(0x0503), 5736 ecdsa_secp521r1_sha512(0x0603), 5738 /* RSASSA-PSS algorithms with public key OID rsaEncryption */ 5739 rsa_pss_rsae_sha256(0x0804), 5740 rsa_pss_rsae_sha384(0x0805), 5741 rsa_pss_rsae_sha512(0x0806), 5743 /* EdDSA algorithms */ 5744 ed25519(0x0807), 5745 ed448(0x0808), 5747 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */ 5748 rsa_pss_pss_sha256(0x0809), 5749 rsa_pss_pss_sha384(0x080a), 5750 rsa_pss_pss_sha512(0x080b), 5752 /* Legacy algorithms */ 5753 rsa_pkcs1_sha1(0x0201), 5754 ecdsa_sha1(0x0203), 5756 /* Reserved Code Points */ 5757 obsolete_RESERVED(0x0000..0x0200), 5758 dsa_sha1_RESERVED(0x0202), 5759 obsolete_RESERVED(0x0204..0x0400), 5760 dsa_sha256_RESERVED(0x0402), 5761 obsolete_RESERVED(0x0404..0x0500), 5762 dsa_sha384_RESERVED(0x0502), 5763 obsolete_RESERVED(0x0504..0x0600), 5764 dsa_sha512_RESERVED(0x0602), 5765 obsolete_RESERVED(0x0604..0x06FF), 5766 private_use(0xFE00..0xFFFF), 5767 (0xFFFF) 5768 } SignatureScheme; 5770 struct { 5771 SignatureScheme supported_signature_algorithms<2..2^16-2>; 5772 } SignatureSchemeList; 5774 B.3.1.4. Supported Groups Extension 5776 enum { 5777 unallocated_RESERVED(0x0000), 5779 /* Elliptic Curve Groups (ECDHE) */ 5780 obsolete_RESERVED(0x0001..0x0016), 5781 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 5782 obsolete_RESERVED(0x001A..0x001C), 5783 x25519(0x001D), x448(0x001E), 5785 /* Finite Field Groups (DHE) */ 5786 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102), 5787 ffdhe6144(0x0103), ffdhe8192(0x0104), 5789 /* Reserved Code Points */ 5790 ffdhe_private_use(0x01FC..0x01FF), 5791 ecdhe_private_use(0xFE00..0xFEFF), 5792 obsolete_RESERVED(0xFF01..0xFF02), 5793 (0xFFFF) 5794 } NamedGroup; 5796 struct { 5797 NamedGroup named_group_list<2..2^16-1>; 5798 } NamedGroupList; 5800 Values within "obsolete_RESERVED" ranges are used in previous 5801 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3 5802 implementations. The obsolete curves have various known/theoretical 5803 weaknesses or have had very little usage, in some cases only due to 5804 unintentional server configuration issues. They are no longer 5805 considered appropriate for general use and should be assumed to be 5806 potentially unsafe. The set of curves specified here is sufficient 5807 for interoperability with all currently deployed and properly 5808 configured TLS implementations. 5810 B.3.2. Server Parameters Messages 5811 opaque DistinguishedName<1..2^16-1>; 5813 struct { 5814 DistinguishedName authorities<3..2^16-1>; 5815 } CertificateAuthoritiesExtension; 5817 struct { 5818 opaque certificate_extension_oid<1..2^8-1>; 5819 opaque certificate_extension_values<0..2^16-1>; 5820 } OIDFilter; 5822 struct { 5823 OIDFilter filters<0..2^16-1>; 5824 } OIDFilterExtension; 5826 struct {} PostHandshakeAuth; 5828 struct { 5829 Extension extensions<0..2^16-1>; 5830 } EncryptedExtensions; 5832 struct { 5833 opaque certificate_request_context<0..2^8-1>; 5834 Extension extensions<2..2^16-1>; 5835 } CertificateRequest; 5837 B.3.3. Authentication Messages 5838 enum { 5839 X509(0), 5840 OpenPGP_RESERVED(1), 5841 RawPublicKey(2), 5842 (255) 5843 } CertificateType; 5845 struct { 5846 select (certificate_type) { 5847 case RawPublicKey: 5848 /* From RFC 7250 ASN.1_subjectPublicKeyInfo */ 5849 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 5851 case X509: 5852 opaque cert_data<1..2^24-1>; 5853 }; 5854 Extension extensions<0..2^16-1>; 5855 } CertificateEntry; 5857 struct { 5858 opaque certificate_request_context<0..2^8-1>; 5859 CertificateEntry certificate_list<0..2^24-1>; 5860 } Certificate; 5862 struct { 5863 SignatureScheme algorithm; 5864 opaque signature<0..2^16-1>; 5865 } CertificateVerify; 5867 struct { 5868 opaque verify_data[Hash.length]; 5869 } Finished; 5871 B.3.4. Ticket Establishment 5873 struct { 5874 uint32 ticket_lifetime; 5875 uint32 ticket_age_add; 5876 opaque ticket_nonce<0..255>; 5877 opaque ticket<1..2^16-1>; 5878 Extension extensions<0..2^16-2>; 5879 } NewSessionTicket; 5881 B.3.5. Updating Keys 5882 struct {} EndOfEarlyData; 5884 enum { 5885 update_not_requested(0), update_requested(1), (255) 5886 } KeyUpdateRequest; 5888 struct { 5889 KeyUpdateRequest request_update; 5890 } KeyUpdate; 5892 B.4. Cipher Suites 5894 A symmetric cipher suite defines the pair of the AEAD algorithm and 5895 hash algorithm to be used with HKDF. Cipher suite names follow the 5896 naming convention: 5898 CipherSuite TLS_AEAD_HASH = VALUE; 5900 +-----------+------------------------------------------------+ 5901 | Component | Contents | 5902 +-----------+------------------------------------------------+ 5903 | TLS | The string "TLS" | 5904 | | | 5905 | AEAD | The AEAD algorithm used for record protection | 5906 | | | 5907 | HASH | The hash algorithm used with HKDF | 5908 | | | 5909 | VALUE | The two byte ID assigned for this cipher suite | 5910 +-----------+------------------------------------------------+ 5912 This specification defines the following cipher suites for use with 5913 TLS 1.3. 5915 +------------------------------+-------------+ 5916 | Description | Value | 5917 +------------------------------+-------------+ 5918 | TLS_AES_128_GCM_SHA256 | {0x13,0x01} | 5919 | | | 5920 | TLS_AES_256_GCM_SHA384 | {0x13,0x02} | 5921 | | | 5922 | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} | 5923 | | | 5924 | TLS_AES_128_CCM_SHA256 | {0x13,0x04} | 5925 | | | 5926 | TLS_AES_128_CCM_8_SHA256 | {0x13,0x05} | 5927 +------------------------------+-------------+ 5929 The corresponding AEAD algorithms AEAD_AES_128_GCM, AEAD_AES_256_GCM, 5930 and AEAD_AES_128_CCM are defined in [RFC5116]. 5931 AEAD_CHACHA20_POLY1305 is defined in [RFC7539]. AEAD_AES_128_CCM_8 5932 is defined in [RFC6655]. The corresponding hash algorithms are 5933 defined in [SHS]. 5935 Although TLS 1.3 uses the same cipher suite space as previous 5936 versions of TLS, TLS 1.3 cipher suites are defined differently, only 5937 specifying the symmetric ciphers, and cannot be used for TLS 1.2. 5938 Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 5939 1.3. 5941 New cipher suite values are assigned by IANA as described in 5942 Section 11. 5944 Appendix C. Implementation Notes 5946 The TLS protocol cannot prevent many common security mistakes. This 5947 section provides several recommendations to assist implementors. 5948 [I-D.ietf-tls-tls13-vectors] provides test vectors for TLS 1.3 5949 handshakes. 5951 C.1. Random Number Generation and Seeding 5953 TLS requires a cryptographically secure pseudorandom number generator 5954 (CSPRNG). In most cases, the operating system provides an 5955 appropriate facility such as /dev/urandom, which should be used 5956 absent other (performance) concerns. It is RECOMMENDED to use an 5957 existing CSPRNG implementation in preference to crafting a new one. 5958 Many adequate cryptographic libraries are already available under 5959 favorable license terms. Should those prove unsatisfactory, 5960 [RFC4086] provides guidance on the generation of random values. 5962 TLS uses random values both in public protocol fields such as the 5963 public Random values in the ClientHello and ServerHello and to 5964 generate keying material. With a properly functioning CSPRNG, this 5965 does not present a security problem as it is not feasible to 5966 determine the CSPRNG state from its output. However, with a broken 5967 CSPRNG, it may be possible for an attacker to use the public output 5968 to determine the CSPRNG internal state and thereby predict the keying 5969 material, as documented in [CHECKOWAY]. Implementations can provide 5970 extra security against this form of attack by using separate CSPRNGs 5971 to generate public and private values. 5973 C.2. Certificates and Authentication 5975 Implementations are responsible for verifying the integrity of 5976 certificates and should generally support certificate revocation 5977 messages. Absent a specific indication from an application profile, 5978 Certificates should always be verified to ensure proper signing by a 5979 trusted Certificate Authority (CA). The selection and addition of 5980 trust anchors should be done very carefully. Users should be able to 5981 view information about the certificate and trust anchor. 5982 Applications SHOULD also enforce minimum and maximum key sizes. For 5983 example, certification paths containing keys or signatures weaker 5984 than 2048-bit RSA or 224-bit ECDSA are not appropriate for secure 5985 applications. 5987 C.3. Implementation Pitfalls 5989 Implementation experience has shown that certain parts of earlier TLS 5990 specifications are not easy to understand and have been a source of 5991 interoperability and security problems. Many of these areas have 5992 been clarified in this document but this appendix contains a short 5993 list of the most important things that require special attention from 5994 implementors. 5996 TLS protocol issues: 5998 - Do you correctly handle handshake messages that are fragmented to 5999 multiple TLS records (see Section 5.1)? Including corner cases 6000 like a ClientHello that is split to several small fragments? Do 6001 you fragment handshake messages that exceed the maximum fragment 6002 size? In particular, the Certificate and CertificateRequest 6003 handshake messages can be large enough to require fragmentation. 6005 - Do you ignore the TLS record layer version number in all 6006 unencrypted TLS records? (see Appendix D) 6008 - Have you ensured that all support for SSL, RC4, EXPORT ciphers, 6009 and MD5 (via the "signature_algorithms" extension) is completely 6010 removed from all possible configurations that support TLS 1.3 or 6011 later, and that attempts to use these obsolete capabilities fail 6012 correctly? (see Appendix D) 6014 - Do you handle TLS extensions in ClientHello correctly, including 6015 unknown extensions? 6017 - When the server has requested a client certificate, but no 6018 suitable certificate is available, do you correctly send an empty 6019 Certificate message, instead of omitting the whole message (see 6020 Section 4.4.2.3)? 6022 - When processing the plaintext fragment produced by AEAD-Decrypt 6023 and scanning from the end for the ContentType, do you avoid 6024 scanning past the start of the cleartext in the event that the 6025 peer has sent a malformed plaintext of all-zeros? 6027 - Do you properly ignore unrecognized cipher suites (Section 4.1.2), 6028 hello extensions (Section 4.2), named groups (Section 4.2.7), key 6029 shares (Section 4.2.8), supported versions (Section 4.2.1), and 6030 signature algorithms (Section 4.2.3) in the ClientHello? 6032 - As a server, do you send a HelloRetryRequest to clients which 6033 support a compatible (EC)DHE group but do not predict it in the 6034 "key_share" extension? As a client, do you correctly handle a 6035 HelloRetryRequest from the server? 6037 Cryptographic details: 6039 - What countermeasures do you use to prevent timing attacks 6040 [TIMING]? 6042 - When using Diffie-Hellman key exchange, do you correctly preserve 6043 leading zero bytes in the negotiated key (see Section 7.4.1)? 6045 - Does your TLS client check that the Diffie-Hellman parameters sent 6046 by the server are acceptable, (see Section 4.2.8.1)? 6048 - Do you use a strong and, most importantly, properly seeded random 6049 number generator (see Appendix C.1) when generating Diffie-Hellman 6050 private values, the ECDSA "k" parameter, and other security- 6051 critical values? It is RECOMMENDED that implementations implement 6052 "deterministic ECDSA" as specified in [RFC6979]. 6054 - Do you zero-pad Diffie-Hellman public key values to the group size 6055 (see Section 4.2.8.1)? 6057 - Do you verify signatures after making them to protect against RSA- 6058 CRT key leaks? [FW15] 6060 C.4. Client Tracking Prevention 6062 Clients SHOULD NOT reuse a ticket for multiple connections. Reuse of 6063 a ticket allows passive observers to correlate different connections. 6064 Servers that issue tickets SHOULD offer at least as many tickets as 6065 the number of connections that a client might use; for example, a web 6066 browser using HTTP/1.1 [RFC7230] might open six connections to a 6067 server. Servers SHOULD issue new tickets with every connection. 6068 This ensures that clients are always able to use a new ticket when 6069 creating a new connection. 6071 C.5. Unauthenticated Operation 6073 Previous versions of TLS offered explicitly unauthenticated cipher 6074 suites based on anonymous Diffie-Hellman. These modes have been 6075 deprecated in TLS 1.3. However, it is still possible to negotiate 6076 parameters that do not provide verifiable server authentication by 6077 several methods, including: 6079 - Raw public keys [RFC7250]. 6081 - Using a public key contained in a certificate but without 6082 validation of the certificate chain or any of its contents. 6084 Either technique used alone is vulnerable to man-in-the-middle 6085 attacks and therefore unsafe for general use. However, it is also 6086 possible to bind such connections to an external authentication 6087 mechanism via out-of-band validation of the server's public key, 6088 trust on first use, or a mechanism such as channel bindings (though 6089 the channel bindings described in [RFC5929] are not defined for TLS 6090 1.3). If no such mechanism is used, then the connection has no 6091 protection against active man-in-the-middle attack; applications MUST 6092 NOT use TLS in such a way absent explicit configuration or a specific 6093 application profile. 6095 Appendix D. Backward Compatibility 6097 The TLS protocol provides a built-in mechanism for version 6098 negotiation between endpoints potentially supporting different 6099 versions of TLS. 6101 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 6102 also handle clients trying to use future versions of TLS as long as 6103 the ClientHello format remains compatible and and there is at least 6104 one protocol version supported by both the client and the server. 6106 Prior versions of TLS used the record layer version number for 6107 various purposes. (TLSPlaintext.legacy_record_version and 6108 TLSCiphertext.legacy_record_version) As of TLS 1.3, this field is 6109 deprecated. The value of TLSPlaintext.legacy_record_version MUST be 6110 ignored by all implementations. The value of 6111 TLSCiphertext.legacy_record_version is included in the additional 6112 data for deprotection but MAY otherwise be ignored or MAY be 6113 validated to match the fixed constant value. Version negotiation is 6114 performed using only the handshake versions 6115 (ClientHello.legacy_version, ServerHello.legacy_version, as well as 6116 the ClientHello, HelloRetryRequest and ServerHello 6117 "supported_versions" extensions). In order to maximize 6118 interoperability with older endpoints, implementations that negotiate 6119 the use of TLS 1.0-1.2 SHOULD set the record layer version number to 6120 the negotiated version for the ServerHello and all records 6121 thereafter. 6123 For maximum compatibility with previously non-standard behavior and 6124 misconfigured deployments, all implementations SHOULD support 6125 validation of certification paths based on the expectations in this 6126 document, even when handling prior TLS versions' handshakes. (see 6127 Section 4.4.2.2) 6129 TLS 1.2 and prior supported an "Extended Master Secret" [RFC7627] 6130 extension which digested large parts of the handshake transcript into 6131 the master secret. Because TLS 1.3 always hashes in the transcript 6132 up to the server CertificateVerify, implementations which support 6133 both TLS 1.3 and earlier versions SHOULD indicate the use of the 6134 Extended Master Secret extension in their APIs whenever TLS 1.3 is 6135 used. 6137 D.1. Negotiating with an older server 6139 A TLS 1.3 client who wishes to negotiate with servers that do not 6140 support TLS 1.3 will send a normal TLS 1.3 ClientHello containing 6141 0x0303 (TLS 1.2) in ClientHello.legacy_version but with the correct 6142 version(s) in the "supported_versions" extension. If the server does 6143 not support TLS 1.3 it will respond with a ServerHello containing an 6144 older version number. If the client agrees to use this version, the 6145 negotiation will proceed as appropriate for the negotiated protocol. 6146 A client using a ticket for resumption SHOULD initiate the connection 6147 using the version that was previously negotiated. 6149 Note that 0-RTT data is not compatible with older servers and SHOULD 6150 NOT be sent absent knowledge that the server supports TLS 1.3. See 6151 Appendix D.3. 6153 If the version chosen by the server is not supported by the client 6154 (or not acceptable), the client MUST abort the handshake with a 6155 "protocol_version" alert. 6157 Some legacy server implementations are known to not implement the TLS 6158 specification properly and might abort connections upon encountering 6159 TLS extensions or versions which they are not aware of. 6160 Interoperability with buggy servers is a complex topic beyond the 6161 scope of this document. Multiple connection attempts may be required 6162 in order to negotiate a backwards compatible connection; however, 6163 this practice is vulnerable to downgrade attacks and is NOT 6164 RECOMMENDED. 6166 D.2. Negotiating with an older client 6168 A TLS server can also receive a ClientHello indicating a version 6169 number smaller than its highest supported version. If the 6170 "supported_versions" extension is present, the server MUST negotiate 6171 using that extension as described in Section 4.2.1. If the 6172 "supported_versions" extension is not present, the server MUST 6173 negotiate the minimum of ClientHello.legacy_version and TLS 1.2. For 6174 example, if the server supports TLS 1.0, 1.1, and 1.2, and 6175 legacy_version is TLS 1.0, the server will proceed with a TLS 1.0 6176 ServerHello. If the "supported_versions" extension is absent and the 6177 server only supports versions greater than 6178 ClientHello.legacy_version, the server MUST abort the handshake with 6179 a "protocol_version" alert. 6181 Note that earlier versions of TLS did not clearly specify the record 6182 layer version number value in all cases 6183 (TLSPlaintext.legacy_record_version). Servers will receive various 6184 TLS 1.x versions in this field, but its value MUST always be ignored. 6186 D.3. 0-RTT backwards compatibility 6188 0-RTT data is not compatible with older servers. An older server 6189 will respond to the ClientHello with an older ServerHello, but it 6190 will not correctly skip the 0-RTT data and will fail to complete the 6191 handshake. This can cause issues when a client attempts to use 6192 0-RTT, particularly against multi-server deployments. For example, a 6193 deployment could deploy TLS 1.3 gradually with some servers 6194 implementing TLS 1.3 and some implementing TLS 1.2, or a TLS 1.3 6195 deployment could be downgraded to TLS 1.2. 6197 A client that attempts to send 0-RTT data MUST fail a connection if 6198 it receives a ServerHello with TLS 1.2 or older. A client that 6199 attempts to repair this error SHOULD NOT send a TLS 1.2 ClientHello, 6200 but instead send a TLS 1.3 ClientHello without 0-RTT data. 6202 To avoid this error condition, multi-server deployments SHOULD ensure 6203 a uniform and stable deployment of TLS 1.3 without 0-RTT prior to 6204 enabling 0-RTT. 6206 D.4. Middlebox Compatibility Mode 6208 Field measurements [Ben17a], [Ben17b], [Res17a], [Res17b] have found 6209 that a significant number of middleboxes misbehave when a TLS client/ 6210 server pair negotiates TLS 1.3. Implementations can increase the 6211 chance of making connections through those middleboxes by making the 6212 TLS 1.3 handshake look more like a TLS 1.2 handshake: 6214 - The client always provides a non-empty session ID in the 6215 ClientHello, as described in the legacy_session_id section of 6216 Section 4.1.2. 6218 - If not offering early data, the client sends a dummy 6219 change_cipher_spec record (see the third paragraph of Section 5.1) 6220 immediately before its second flight. This may either be before 6221 its second ClientHello or before its encrypted handshake flight. 6222 If offering early data, the record is placed immediately after the 6223 first ClientHello. 6225 - The server sends a dummy change_cipher_spec record immediately 6226 after its first handshake message. This may either be after a 6227 ServerHello or a HelloRetryRequest. 6229 When put together, these changes make the TLS 1.3 handshake resemble 6230 TLS 1.2 session resumption, which improves the chance of successfully 6231 connecting through middleboxes. This "compatibility mode" is 6232 partially negotiated: The client can opt to provide a session ID or 6233 not and the server has to echo it. Either side can send 6234 change_cipher_spec at any time during the handshake, as they must be 6235 ignored by the peer, but if the client sends a non-empty session ID, 6236 the server MUST send the change_cipher_spec as described in this 6237 section. 6239 D.5. Backwards Compatibility Security Restrictions 6241 Implementations negotiating use of older versions of TLS SHOULD 6242 prefer forward secret and AEAD cipher suites, when available. 6244 The security of RC4 cipher suites is considered insufficient for the 6245 reasons cited in [RFC7465]. Implementations MUST NOT offer or 6246 negotiate RC4 cipher suites for any version of TLS for any reason. 6248 Old versions of TLS permitted the use of very low strength ciphers. 6249 Ciphers with a strength less than 112 bits MUST NOT be offered or 6250 negotiated for any version of TLS for any reason. 6252 The security of SSL 3.0 [SSL3] is considered insufficient for the 6253 reasons enumerated in [RFC7568], and MUST NOT be negotiated for any 6254 reason. 6256 The security of SSL 2.0 [SSL2] is considered insufficient for the 6257 reasons enumerated in [RFC6176], and MUST NOT be negotiated for any 6258 reason. 6260 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 6261 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 6262 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 6263 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 6264 order to negotiate older versions of TLS. 6266 Implementations MUST NOT send a ClientHello.legacy_version or 6267 ServerHello.legacy_version set to 0x0300 or less. Any endpoint 6268 receiving a Hello message with ClientHello.legacy_version or 6269 ServerHello.legacy_version set to 0x0300 MUST abort the handshake 6270 with a "protocol_version" alert. 6272 Implementations MUST NOT send any records with a version less than 6273 0x0300. Implementations SHOULD NOT accept any records with a version 6274 less than 0x0300 (but may inadvertently do so if the record version 6275 number is ignored completely). 6277 Implementations MUST NOT use the Truncated HMAC extension, defined in 6278 Section 7 of [RFC6066], as it is not applicable to AEAD algorithms 6279 and has been shown to be insecure in some scenarios. 6281 Appendix E. Overview of Security Properties 6283 A complete security analysis of TLS is outside the scope of this 6284 document. In this section, we provide an informal description the 6285 desired properties as well as references to more detailed work in the 6286 research literature which provides more formal definitions. 6288 We cover properties of the handshake separately from those of the 6289 record layer. 6291 E.1. Handshake 6293 The TLS handshake is an Authenticated Key Exchange (AKE) protocol 6294 which is intended to provide both one-way authenticated (server-only) 6295 and mutually authenticated (client and server) functionality. At the 6296 completion of the handshake, each side outputs its view of the 6297 following values: 6299 - A set of "session keys" (the various secrets derived from the 6300 master secret) from which can be derived a set of working keys. 6302 - A set of cryptographic parameters (algorithms, etc.) 6304 - The identities of the communicating parties. 6306 We assume the attacker to be an active network attacker, which means 6307 it has complete control over the network used to communicate between 6308 the parties [RFC3552]. Even under these conditions, the handshake 6309 should provide the properties listed below. Note that these 6310 properties are not necessarily independent, but reflect the protocol 6311 consumers' needs. 6313 Establishing the same session keys. The handshake needs to output 6314 the same set of session keys on both sides of the handshake, 6315 provided that it completes successfully on each endpoint (See 6316 [CK01]; defn 1, part 1). 6318 Secrecy of the session keys. The shared session keys should be known 6319 only to the communicating parties and not to the attacker (See 6320 [CK01]; defn 1, part 2). Note that in a unilaterally 6321 authenticated connection, the attacker can establish its own 6322 session keys with the server, but those session keys are distinct 6323 from those established by the client. 6325 Peer Authentication. The client's view of the peer identity should 6326 reflect the server's identity. If the client is authenticated, 6327 the server's view of the peer identity should match the client's 6328 identity. 6330 Uniqueness of the session keys: Any two distinct handshakes should 6331 produce distinct, unrelated session keys. Individual session keys 6332 produced by a handshake should also be distinct and unrelated. 6334 Downgrade protection. The cryptographic parameters should be the 6335 same on both sides and should be the same as if the peers had been 6336 communicating in the absence of an attack (See [BBFKZG16]; defns 8 6337 and 9}). 6339 Forward secret with respect to long-term keys If the long-term 6340 keying material (in this case the signature keys in certificate- 6341 based authentication modes or the external/resumption PSK in PSK 6342 with (EC)DHE modes) is compromised after the handshake is 6343 complete, this does not compromise the security of the session key 6344 (See [DOW92]), as long as the session key itself has been erased. 6345 The forward secrecy property is not satisfied when PSK is used in 6346 the "psk_ke" PskKeyExchangeMode. 6348 Key Compromise Impersonation (KCI) resistance In a mutually- 6349 authenticated connection with certificates, compromising the long- 6350 term secret of one actor should not break that actor's 6351 authentication of their peer in the given connection (see 6352 [HGFS15]). For example, if a client's signature key is 6353 compromised, it should not be possible to impersonate arbitrary 6354 servers to that client in subsequent handshakes. 6356 Protection of endpoint identities. The server's identity 6357 (certificate) should be protected against passive attackers. The 6358 client's identity should be protected against both passive and 6359 active attackers. 6361 Informally, the signature-based modes of TLS 1.3 provide for the 6362 establishment of a unique, secret, shared key established by an 6363 (EC)DHE key exchange and authenticated by the server's signature over 6364 the handshake transcript, as well as tied to the server's identity by 6365 a MAC. If the client is authenticated by a certificate, it also 6366 signs over the handshake transcript and provides a MAC tied to both 6367 identities. [SIGMA] describes the design and analysis of this type 6368 of key exchange protocol. If fresh (EC)DHE keys are used for each 6369 connection, then the output keys are forward secret. 6371 The external PSK and resumption PSK bootstrap from a long-term shared 6372 secret into a unique per-connection set of short-term session keys. 6373 This secret may have been established in a previous handshake. If 6374 PSK with (EC)DHE key establishment is used, these session keys will 6375 also be forward secret. The resumption PSK has been designed so that 6376 the resumption master secret computed by connection N and needed to 6377 form connection N+1 is separate from the traffic keys used by 6378 connection N, thus providing forward secrecy between the connections. 6379 In addition, if multiple tickets are established on the same 6380 connection, they are associated with different keys, so compromise of 6381 the PSK associated with one ticket does not lead to the compromise of 6382 connections established with PSKs associated with other tickets. 6383 This property is most interesting if tickets are stored in a database 6384 (and so can be deleted) rather than if they are self-encrypted. 6386 The PSK binder value forms a binding between a PSK and the current 6387 handshake, as well as between the session where the PSK was 6388 established and the session where it was used. This binding 6389 transitively includes the original handshake transcript, because that 6390 transcript is digested into the values which produce the Resumption 6391 Master Secret. This requires that both the KDF used to produce the 6392 resumption master secret and the MAC used to compute the binder be 6393 collision resistant. See Appendix E.1.1 for more on this. Note: The 6394 binder does not cover the binder values from other PSKs, though they 6395 are included in the Finished MAC. 6397 Note: TLS does not currently permit the server to send a 6398 certificate_request message in non-certificate-based handshakes 6399 (e.g., PSK). If this restriction were to be relaxed in future, the 6400 client's signature would not cover the server's certificate directly. 6401 However, if the PSK was established through a NewSessionTicket, the 6402 client's signature would transitively cover the server's certificate 6403 through the PSK binder. [PSK-FINISHED] describes a concrete attack 6404 on constructions that do not bind to the server's certificate (see 6405 also [Kraw16]). It is unsafe to use certificate-based client 6406 authentication when the client might potentially share the same PSK/ 6407 key-id pair with two different endpoints. Implementations MUST NOT 6408 combine external PSKs with certificate-based authentication of either 6409 the client or the server unless negotiated by some extension. 6411 If an exporter is used, then it produces values which are unique and 6412 secret (because they are generated from a unique session key). 6413 Exporters computed with different labels and contexts are 6414 computationally independent, so it is not feasible to compute one 6415 from another or the session secret from the exported value. Note: 6416 exporters can produce arbitrary-length values. If exporters are to 6417 be used as channel bindings, the exported value MUST be large enough 6418 to provide collision resistance. The exporters provided in TLS 1.3 6419 are derived from the same handshake contexts as the early traffic 6420 keys and the application traffic keys respectively, and thus have 6421 similar security properties. Note that they do not include the 6422 client's certificate; future applications which wish to bind to the 6423 client's certificate may need to define a new exporter that includes 6424 the full handshake transcript. 6426 For all handshake modes, the Finished MAC (and where present, the 6427 signature), prevents downgrade attacks. In addition, the use of 6428 certain bytes in the random nonces as described in Section 4.1.3 6429 allows the detection of downgrade to previous TLS versions. See 6430 [BBFKZG16] for more detail on TLS 1.3 and downgrade. 6432 As soon as the client and the server have exchanged enough 6433 information to establish shared keys, the remainder of the handshake 6434 is encrypted, thus providing protection against passive attackers, 6435 even if the computed shared key is not authenticated. Because the 6436 server authenticates before the client, the client can ensure that if 6437 it authenticates to the server, it only reveals its identity to an 6438 authenticated server. Note that implementations must use the 6439 provided record padding mechanism during the handshake to avoid 6440 leaking information about the identities due to length. The client's 6441 proposed PSK identities are not encrypted, nor is the one that the 6442 server selects. 6444 E.1.1. Key Derivation and HKDF 6446 Key derivation in TLS 1.3 uses the HKDF function defined in [RFC5869] 6447 and its two components, HKDF-Extract and HKDF-Expand. The full 6448 rationale for the HKDF construction can be found in [Kraw10] and the 6449 rationale for the way it is used in TLS 1.3 in [KW16]. Throughout 6450 this document, each application of HKDF-Extract is followed by one or 6451 more invocations of HKDF-Expand. This ordering should always be 6452 followed (including in future revisions of this document), in 6453 particular, one SHOULD NOT use an output of HKDF-Extract as an input 6454 to another application of HKDF-Extract without an HKDF-Expand in 6455 between. Consecutive applications of HKDF-Expand are allowed as long 6456 as these are differentiated via the key and/or the labels. 6458 Note that HKDF-Expand implements a pseudorandom function (PRF) with 6459 both inputs and outputs of variable length. In some of the uses of 6460 HKDF in this document (e.g., for generating exporters and the 6461 resumption_master_secret), it is necessary that the application of 6462 HKDF-Expand be collision-resistant, namely, it should be infeasible 6463 to find two different inputs to HKDF-Expand that output the same 6464 value. This requires the underlying hash function to be collision 6465 resistant and the output length from HKDF-Expand to be of size at 6466 least 256 bits (or as much as needed for the hash function to prevent 6467 finding collisions). 6469 E.1.2. Client Authentication 6471 A client that has sent authentication data to a server, either during 6472 the handshake or in post-handshake authentication, cannot be sure if 6473 the server afterwards considers the client to be authenticated or 6474 not. If the client needs to determine if the server considers the 6475 connection to be unilaterally or mutually authenticated, this has to 6476 be provisioned by the application layer. See [CHHSV17] for details. 6477 In addition, the analysis of post-handshake authentication from 6478 [Kraw16] shows that the client identified by the certificate sent in 6479 the post-handshake phase possesses the traffic key. This party is 6480 therefore the client that participated in the original handshake or 6481 one to whom the original client delegated the traffic key (assuming 6482 that the traffic key has not been compromised). 6484 E.1.3. 0-RTT 6486 The 0-RTT mode of operation generally provides similar security 6487 properties as 1-RTT data, with the two exceptions that the 0-RTT 6488 encryption keys do not provide full forward secrecy and that the 6489 server is not able to guarantee uniqueness of the handshake (non- 6490 replayability) without keeping potentially undue amounts of state. 6491 See Section 4.2.10 for one mechanism to limit the exposure to replay. 6493 E.1.4. Exporter Independence 6495 The exporter_master_secret and early_exporter_master_secret are 6496 derived to be independent of the traffic keys and therefore do not 6497 represent a threat to the security of traffic encrypted with those 6498 keys. However, because these secrets can be used to compute any 6499 exporter value, they SHOULD be erased as soon as possible. If the 6500 total set of exporter labels is known, then implementations SHOULD 6501 pre-compute the inner Derive-Secret stage of the exporter computation 6502 for all those labels, then erase the [early_]exporter_master_secret, 6503 followed by each inner values as soon as it is known that it will not 6504 be needed again. 6506 E.1.5. Post-Compromise Security 6508 TLS does not provide security for handshakes which take place after 6509 the peer's long-term secret (signature key or external PSK) is 6510 compromised. It therefore does not provide post-compromise security 6511 [CCG16], sometimes also referred to as backwards or future secrecy. 6512 This is in contrast to KCI resistance, which describes the security 6513 guarantees that a party has after its own long-term secret has been 6514 compromised. 6516 E.1.6. External References 6518 The reader should refer to the following references for analysis of 6519 the TLS handshake: [DFGS15] [CHSV16] [DFGS16] [KW16] [Kraw16] 6520 [FGSW16] [LXZFH16] [FG17] [BBK17]. 6522 E.2. Record Layer 6524 The record layer depends on the handshake producing strong traffic 6525 secrets which can be used to derive bidirectional encryption keys and 6526 nonces. Assuming that is true, and the keys are used for no more 6527 data than indicated in Section 5.5 then the record layer should 6528 provide the following guarantees: 6530 Confidentiality. An attacker should not be able to determine the 6531 plaintext contents of a given record. 6533 Integrity. An attacker should not be able to craft a new record 6534 which is different from an existing record which will be accepted 6535 by the receiver. 6537 Order protection/non-replayability An attacker should not be able to 6538 cause the receiver to accept a record which it has already 6539 accepted or cause the receiver to accept record N+1 without having 6540 first processed record N. 6542 Length concealment. Given a record with a given external length, the 6543 attacker should not be able to determine the amount of the record 6544 that is content versus padding. 6546 Forward secrecy after key change. If the traffic key update 6547 mechanism described in Section 4.6.3 has been used and the 6548 previous generation key is deleted, an attacker who compromises 6549 the endpoint should not be able to decrypt traffic encrypted with 6550 the old key. 6552 Informally, TLS 1.3 provides these properties by AEAD-protecting the 6553 plaintext with a strong key. AEAD encryption [RFC5116] provides 6554 confidentiality and integrity for the data. Non-replayability is 6555 provided by using a separate nonce for each record, with the nonce 6556 being derived from the record sequence number (Section 5.3), with the 6557 sequence number being maintained independently at both sides thus 6558 records which are delivered out of order result in AEAD deprotection 6559 failures. In order to prevent mass cryptanalysis when the same 6560 plaintext is repeatedly encrypted by different users under the same 6561 key (as is commonly the case for HTTP), the nonce is formed by mixing 6562 the sequence number with a secret per-connection initialization 6563 vector derived along with the traffic keys. See [BT16] for analysis 6564 of this construction. 6566 The re-keying technique in TLS 1.3 (see Section 7.2) follows the 6567 construction of the serial generator in [REKEY], which shows that re- 6568 keying can allow keys to be used for a larger number of encryptions 6569 than without re-keying. This relies on the security of the HKDF- 6570 Expand-Label function as a pseudorandom function (PRF). In addition, 6571 as long as this function is truly one way, it is not possible to 6572 compute traffic keys from prior to a key change (forward secrecy). 6574 TLS does not provide security for data which is communicated on a 6575 connection after a traffic secret of that connection is compromised. 6576 That is, TLS does not provide post-compromise security/future 6577 secrecy/backward secrecy with respect to the traffic secret. Indeed, 6578 an attacker who learns a traffic secret can compute all future 6579 traffic secrets on that connection. Systems which want such 6580 guarantees need to do a fresh handshake and establish a new 6581 connection with an (EC)DHE exchange. 6583 E.2.1. External References 6585 The reader should refer to the following references for analysis of 6586 the TLS record layer: [BMMT15] [BT16] [BDFKPPRSZZ16] [BBK17] 6587 [Anon18]. 6589 E.3. Traffic Analysis 6591 TLS is susceptible to a variety of traffic analysis attacks based on 6592 observing the length and timing of encrypted packets [CLINIC] 6593 [HCJ16]. This is particularly easy when there is a small set of 6594 possible messages to be distinguished, such as for a video server 6595 hosting a fixed corpus of content, but still provides usable 6596 information even in more complicated scenarios. 6598 TLS does not provide any specific defenses against this form of 6599 attack but does include a padding mechanism for use by applications: 6600 The plaintext protected by the AEAD function consists of content plus 6601 variable-length padding, which allows the application to produce 6602 arbitrary length encrypted records as well as padding-only cover 6603 traffic to conceal the difference between periods of transmission and 6604 periods of silence. Because the padding is encrypted alongside the 6605 actual content, an attacker cannot directly determine the length of 6606 the padding, but may be able to measure it indirectly by the use of 6607 timing channels exposed during record processing (i.e., seeing how 6608 long it takes to process a record or trickling in records to see 6609 which ones elicit a response from the server). In general, it is not 6610 known how to remove all of these channels because even a constant 6611 time padding removal function will likely feed the content into data- 6612 dependent functions. At minimum, a fully constant time server or 6613 client would require close cooperation with the application layer 6614 protocol implementation, including making that higher level protocol 6615 constant time. 6617 Note: Robust traffic analysis defences will likely lead to inferior 6618 performance due to delay in transmitting packets and increased 6619 traffic volume. 6621 E.4. Side Channel Attacks 6623 In general, TLS does not have specific defenses against side-channel 6624 attacks (i.e., those which attack the communications via secondary 6625 channels such as timing) leaving those to the implementation of the 6626 relevant cryptographic primitives. However, certain features of TLS 6627 are designed to make it easier to write side-channel resistant code: 6629 - Unlike previous versions of TLS which used a composite MAC-then- 6630 encrypt structure, TLS 1.3 only uses AEAD algorithms, allowing 6631 implementations to use self-contained constant-time 6632 implementations of those primitives. 6634 - TLS uses a uniform "bad_record_mac" alert for all decryption 6635 errors, which is intended to prevent an attacker from gaining 6636 piecewise insight into portions of the message. Additional 6637 resistance is provided by terminating the connection on such 6638 errors; a new connection will have different cryptographic 6639 material, preventing attacks against the cryptographic primitives 6640 that require multiple trials. 6642 Information leakage through side channels can occur at layers above 6643 TLS, in application protocols and the applications that use them. 6644 Resistance to side-channel attacks depends on applications and 6645 application protocols separately ensuring that confidential 6646 information is not inadvertently leaked. 6648 E.5. Replay Attacks on 0-RTT 6650 Replayable 0-RTT data presents a number of security threats to TLS- 6651 using applications, unless those applications are specifically 6652 engineered to be safe under replay (minimally, this means idempotent, 6653 but in many cases may also require other stronger conditions, such as 6654 constant-time response). Potential attacks include: 6656 - Duplication of actions which cause side effects (e.g., purchasing 6657 an item or transferring money) to be duplicated, thus harming the 6658 site or the user. 6660 - Attackers can store and replay 0-RTT messages in order to re-order 6661 them with respect to other messages (e.g., moving a delete to 6662 after a create). 6664 - Exploiting cache timing behavior to discover the content of 0-RTT 6665 messages by replaying a 0-RTT message to a different cache node 6666 and then using a separate connection to measure request latency, 6667 to see if the two requests address the same resource. 6669 If data can be replayed a large number of times, additional attacks 6670 become possible, such as making repeated measurements of the the 6671 speed of cryptographic operations. In addition, they may be able to 6672 overload rate-limiting systems. For further description of these 6673 attacks, see [Mac17]. 6675 Ultimately, servers have the responsibility to protect themselves 6676 against attacks employing 0-RTT data replication. The mechanisms 6677 described in Section 8 are intended to prevent replay at the TLS 6678 layer but do not provide complete protection against receiving 6679 multiple copies of client data. TLS 1.3 falls back to the 1-RTT 6680 handshake when the server does not have any information about the 6681 client, e.g., because it is in a different cluster which does not 6682 share state or because the ticket has been deleted as described in 6683 Section 8.1. If the application layer protocol retransmits data in 6684 this setting, then it is possible for an attacker to induce message 6685 duplication by sending the ClientHello to both the original cluster 6686 (which processes the data immediately) and another cluster which will 6687 fall back to 1-RTT and process the data upon application layer 6688 replay. The scale of this attack is limited by the client's 6689 willingness to retry transactions and therefore only allows a limited 6690 amount of duplication, with each copy appearing as a new connection 6691 at the server. 6693 If implemented correctly, the mechanisms described in Section 8.1 and 6694 Section 8.2 prevent a replayed ClientHello and its associated 0-RTT 6695 data from being accepted multiple times by any cluster with 6696 consistent state; for servers which limit the use of 0-RTT to one 6697 cluster for a single ticket, then a given ClientHello and its 6698 associated 0-RTT data will only be accepted once. However, if state 6699 is not completely consistent, then an attacker might be able to have 6700 multiple copies of the data be accepted during the replication 6701 window. Because clients do not know the exact details of server 6702 behavior, they MUST NOT send messages in early data which are not 6703 safe to have replayed and which they would not be willing to retry 6704 across multiple 1-RTT connections. 6706 Application protocols MUST NOT use 0-RTT data without a profile that 6707 defines its use. That profile needs to identify which messages or 6708 interactions are safe to use with 0-RTT and how to handle the 6709 situation when the server rejects 0-RTT and falls back to 1-RTT. 6711 In addition, to avoid accidental misuse, TLS implementations MUST NOT 6712 enable 0-RTT (either sending or accepting) unless specifically 6713 requested by the application and MUST NOT automatically resend 0-RTT 6714 data if it is rejected by the server unless instructed by the 6715 application. Server-side applications may wish to implement special 6716 processing for 0-RTT data for some kinds of application traffic 6717 (e.g., abort the connection, request that data be resent at the 6718 application layer, or delay processing until the handshake 6719 completes). In order to allow applications to implement this kind of 6720 processing, TLS implementations MUST provide a way for the 6721 application to determine if the handshake has completed. 6723 E.5.1. Replay and Exporters 6725 Replays of the ClientHello produce the same early exporter, thus 6726 requiring additional care by applications which use these exporters. 6727 In particular, if these exporters are used as an authentication 6728 channel binding (e.g., by signing the output of the exporter) an 6729 attacker who compromises the PSK can transplant authenticators 6730 between connections without compromising the authentication key. 6732 In addition, the early exporter SHOULD NOT be used to generate 6733 server-to-client encryption keys because that would entail the reuse 6734 of those keys. This parallels the use of the early application 6735 traffic keys only in the client-to-server direction. 6737 E.6. Attacks on Static RSA 6739 Although TLS 1.3 does not use RSA key transport and so is not 6740 directly susceptible to Bleichenbacher-type attacks, if TLS 1.3 6741 servers also support static RSA in the context of previous versions 6742 of TLS, then it may be possible to impersonate the server for TLS 1.3 6743 connections [JSS15]. TLS 1.3 implementations can prevent this attack 6744 by disabling support for static RSA across all versions of TLS. In 6745 principle, implementations might also be able to separate 6746 certificates with different keyUsage bits for static RSA decryption 6747 and RSA signature, but this technique relies on clients refusing to 6748 accept signatures using keys in certificates that do not have the 6749 digitalSignature bit set, and many clients do not enforce this 6750 restriction. 6752 Appendix F. Working Group Information 6754 The discussion list for the IETF TLS working group is located at the 6755 e-mail address tls@ietf.org [1]. Information on the group and 6756 information on how to subscribe to the list is at 6757 https://www.ietf.org/mailman/listinfo/tls 6759 Archives of the list can be found at: https://www.ietf.org/mail- 6760 archive/web/tls/current/index.html 6762 Appendix G. Contributors 6764 - Martin Abadi 6765 University of California, Santa Cruz 6766 abadi@cs.ucsc.edu 6768 - Christopher Allen (co-editor of TLS 1.0) 6769 Alacrity Ventures 6770 ChristopherA@AlacrityManagement.com 6772 - Richard Barnes 6773 Cisco 6774 rlb@ipv.sx 6776 - Steven M. Bellovin 6777 Columbia University 6778 smb@cs.columbia.edu 6780 - David Benjamin 6781 Google 6782 davidben@google.com 6784 - Benjamin Beurdouche 6785 INRIA & Microsoft Research 6786 benjamin.beurdouche@ens.fr 6788 - Karthikeyan Bhargavan (co-author of [RFC7627]) 6789 INRIA 6790 karthikeyan.bhargavan@inria.fr 6792 - Simon Blake-Wilson (co-author of [RFC4492]) 6793 BCI 6794 sblakewilson@bcisse.com 6796 - Nelson Bolyard (co-author of [RFC4492]) 6797 Sun Microsystems, Inc. 6798 nelson@bolyard.com 6800 - Ran Canetti 6801 IBM 6802 canetti@watson.ibm.com 6804 - Matt Caswell 6805 OpenSSL 6806 matt@openssl.org 6808 - Stephen Checkoway 6809 University of Illinois at Chicago 6810 sfc@uic.edu 6812 - Pete Chown 6813 Skygate Technology Ltd 6814 pc@skygate.co.uk 6816 - Katriel Cohn-Gordon 6817 University of Oxford 6818 me@katriel.co.uk 6820 - Cas Cremers 6821 University of Oxford 6822 cas.cremers@cs.ox.ac.uk 6824 - Antoine Delignat-Lavaud (co-author of [RFC7627]) 6825 INRIA 6826 antoine.delignat-lavaud@inria.fr 6828 - Tim Dierks (co-editor of TLS 1.0, 1.1, and 1.2) 6829 Independent 6830 tim@dierks.org 6832 - Roelof DuToit 6833 Symantec Corporation 6834 roelof_dutoit@symantec.com 6836 - Taher Elgamal 6837 Securify 6838 taher@securify.com 6840 - Pasi Eronen 6841 Nokia 6842 pasi.eronen@nokia.com 6844 - Cedric Fournet 6845 Microsoft 6846 fournet@microsoft.com 6848 - Anil Gangolli 6849 anil@busybuddha.org 6851 - David M. Garrett 6852 dave@nulldereference.com 6854 - Illya Gerasymchuk 6855 Independent 6856 illya@iluxonchik.me 6858 - Alessandro Ghedini 6859 Cloudflare Inc. 6860 alessandro@cloudflare.com 6862 - Daniel Kahn Gillmor 6863 ACLU 6864 dkg@fifthhorseman.net 6866 - Matthew Green 6867 Johns Hopkins University 6868 mgreen@cs.jhu.edu 6870 - Jens Guballa 6871 ETAS 6872 jens.guballa@etas.com 6874 - Felix Guenther 6875 TU Darmstadt 6876 mail@felixguenther.info 6878 - Vipul Gupta (co-author of [RFC4492]) 6879 Sun Microsystems Laboratories 6880 vipul.gupta@sun.com 6882 - Chris Hawk (co-author of [RFC4492]) 6883 Corriente Networks LLC 6884 chris@corriente.net 6886 - Kipp Hickman 6888 - Alfred Hoenes 6890 - David Hopwood 6891 Independent Consultant 6892 david.hopwood@blueyonder.co.uk 6894 - Marko Horvat 6895 MPI-SWS 6896 mhorvat@mpi-sws.org 6898 - Jonathan Hoyland 6899 Royal Holloway, University of London 6901 - Subodh Iyengar 6902 Facebook 6903 subodh@fb.com 6905 - Benjamin Kaduk 6906 Akamai 6907 kaduk@mit.edu 6909 - Hubert Kario 6910 Red Hat Inc. 6911 hkario@redhat.com 6913 - Phil Karlton (co-author of SSL 3.0) 6915 - Leon Klingele 6916 Independent 6917 mail@leonklingele.de 6919 - Paul Kocher (co-author of SSL 3.0) 6920 Cryptography Research 6921 paul@cryptography.com 6923 - Hugo Krawczyk 6924 IBM 6925 hugokraw@us.ibm.com 6927 - Adam Langley (co-author of [RFC7627]) 6928 Google 6929 agl@google.com 6931 - Olivier Levillain 6932 ANSSI 6933 olivier.levillain@ssi.gouv.fr 6935 - Xiaoyin Liu 6936 University of North Carolina at Chapel Hill 6937 xiaoyin.l@outlook.com 6939 - Ilari Liusvaara 6940 Independent 6941 ilariliusvaara@welho.com 6943 - Atul Luykx 6944 K.U. Leuven 6945 atul.luykx@kuleuven.be 6947 - Colm MacCarthaigh 6948 Amazon Web Services 6949 colm@allcosts.net 6951 - Carl Mehner 6952 USAA 6953 carl.mehner@usaa.com 6955 - Jan Mikkelsen 6956 Transactionware 6957 janm@transactionware.com 6959 - Bodo Moeller (co-author of [RFC4492]) 6960 Google 6961 bodo@openssl.org 6963 - Kyle Nekritz 6964 Facebook 6965 knekritz@fb.com 6967 - Erik Nygren 6968 Akamai Technologies 6969 erik+ietf@nygren.org 6971 - Magnus Nystrom 6972 Microsoft 6973 mnystrom@microsoft.com 6975 - Kazuho Oku 6976 DeNA Co., Ltd. 6977 kazuhooku@gmail.com 6979 - Kenny Paterson 6980 Royal Holloway, University of London 6981 kenny.paterson@rhul.ac.uk 6983 - Alfredo Pironti (co-author of [RFC7627]) 6984 INRIA 6985 alfredo.pironti@inria.fr 6987 - Andrei Popov 6988 Microsoft 6989 andrei.popov@microsoft.com 6991 - Marsh Ray (co-author of [RFC7627]) 6992 Microsoft 6993 maray@microsoft.com 6995 - Robert Relyea 6996 Netscape Communications 6997 relyea@netscape.com 6999 - Kyle Rose 7000 Akamai Technologies 7001 krose@krose.org 7003 - Jim Roskind 7004 Amazon 7005 jroskind@amazon.com 7007 - Michael Sabin 7009 - Joe Salowey 7010 Tableau Software 7011 joe@salowey.net 7013 - Rich Salz 7014 Akamai 7015 rsalz@akamai.com 7017 - David Schinazi 7018 Apple Inc. 7019 dschinazi@apple.com 7021 - Sam Scott 7022 Royal Holloway, University of London 7023 me@samjs.co.uk 7025 - Dan Simon 7026 Microsoft, Inc. 7028 dansimon@microsoft.com 7030 - Brian Smith 7031 Independent 7032 brian@briansmith.org 7034 - Brian Sniffen 7035 Akamai Technologies 7036 ietf@bts.evenmere.org 7038 - Nick Sullivan 7039 Cloudflare Inc. 7040 nick@cloudflare.com 7042 - Bjoern Tackmann 7043 University of California, San Diego 7044 btackmann@eng.ucsd.edu 7046 - Tim Taubert 7047 Mozilla 7048 ttaubert@mozilla.com 7050 - Martin Thomson 7051 Mozilla 7052 mt@mozilla.com 7054 - Sean Turner 7055 sn3rd 7056 sean@sn3rd.com 7058 - Steven Valdez 7059 Google 7060 svaldez@google.com 7062 - Filippo Valsorda 7063 Cloudflare Inc. 7064 filippo@cloudflare.com 7066 - Thyla van der Merwe 7067 Royal Holloway, University of London 7068 tjvdmerwe@gmail.com 7070 - Victor Vasiliev 7071 Google 7072 vasilvv@google.com 7074 - Tom Weinstein 7075 - Hoeteck Wee 7076 Ecole Normale Superieure, Paris 7077 hoeteck@alum.mit.edu 7079 - David Wong 7080 NCC Group 7081 david.wong@nccgroup.trust 7083 - Christopher A. Wood 7084 Apple Inc. 7085 cawood@apple.com 7087 - Tim Wright 7088 Vodafone 7089 timothy.wright@vodafone.com 7091 - Peter Wu 7092 Independent 7093 peter@lekensteyn.nl 7095 - Kazu Yamamoto 7096 Internet Initiative Japan Inc. 7097 kazu@iij.ad.jp 7099 Author's Address 7101 Eric Rescorla 7102 RTFM, Inc. 7104 EMail: ekr@rtfm.com