idnits 2.17.1 draft-ietf-tls-tls13-20.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 26 instances of too long lines in the document, the longest one being 5 characters in excess of 72. -- The draft header indicates that this document obsoletes RFC5077, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document obsoletes RFC5246, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC6066, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC5705, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC6961, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC4492, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "post_handshake_auth" extension is used to indicate that a client is willing to perform post-handshake authentication Section 4.6.2. Servers MUST not send a post-handshake CertificateRequest to clients which do not offer this extension. Servers MUST NOT send this extension. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The presence of padding does not change the overall record size limitations - the full encoded TLSInnerPlaintext MUST not exceed 2^14 octets. If the maximum fragment length is reduced, such as by the max_fragment_length extension from [RFC6066], then the reduced limit applies to the full plaintext, including the padding. (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 (April 28, 2017) is 2554 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 936, but not defined -- Looks like a reference, but probably isn't: '0' on line 1081 -- Looks like a reference, but probably isn't: '1' on line 5954 -- Looks like a reference, but probably isn't: '3' on line 1152 -- Looks like a reference, but probably isn't: '9' on line 1117 -- Looks like a reference, but probably isn't: '2' on line 4996 -- Looks like a reference, but probably isn't: '4' on line 1153 -- Looks like a reference, but probably isn't: '8' on line 1154 -- Looks like a reference, but probably isn't: '10' on line 1268 -- Looks like a reference, but probably isn't: '32' on line 4994 == Unused Reference: 'RFC4681' is defined on line 4674, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DH' -- Possible downref: Non-RFC (?) normative reference: ref. 'GCM' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Obsolete normative reference: RFC 6961 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6962 (Obsoleted by RFC 9162) ** Downref: Normative reference to an Informational RFC: RFC 6979 ** Obsolete normative reference: RFC 7507 (Obsoleted by RFC 8996) ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) ** Downref: Normative reference to an Informational RFC: RFC 7748 ** Downref: Normative reference to an Informational RFC: RFC 8017 ** Downref: Normative reference to an Informational RFC: RFC 8032 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- Possible downref: Non-RFC (?) normative reference: ref. 'X962' -- No information found for draft-10 - is the name correct? -- No information found for draft-10 - is the name correct? -- Duplicate reference: draft-10, mentioned in 'DFGS16', was also mentioned in 'DFGS15'. == Outdated reference: A later version (-05) exists of draft-ietf-tls-iana-registry-updates-01 == Outdated reference: A later version (-07) exists of draft-ietf-tls-tls13-vectors-00 -- 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: 12 errors (**), 0 flaws (~~), 7 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 (if approved) April 28, 2017 5 Updates: 4492, 5705, 6066, 6961 (if 6 approved) 7 Intended status: Standards Track 8 Expires: October 30, 2017 10 The Transport Layer Security (TLS) Protocol Version 1.3 11 draft-ietf-tls-tls13-20 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 October 30, 2017. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (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 . . . . . . . . . . . . . . . . . . . . . . . . 4 67 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 6 68 1.2. Change Log . . . . . . . . . . . . . . . . . . . . . . . 6 69 1.3. Major Differences from TLS 1.2 . . . . . . . . . . . . . 14 70 1.4. Updates Affecting TLS 1.2 . . . . . . . . . . . . . . . . 15 71 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 16 72 2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . . . 19 73 2.2. Resumption and Pre-Shared Key (PSK) . . . . . . . . . . . 20 74 2.3. Zero-RTT Data . . . . . . . . . . . . . . . . . . . . . . 22 75 3. Presentation Language . . . . . . . . . . . . . . . . . . . . 24 76 3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 24 77 3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 24 78 3.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 25 79 3.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 26 80 3.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 26 81 3.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 27 82 3.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 27 83 3.8. Variants . . . . . . . . . . . . . . . . . . . . . . . . 28 84 4. Handshake Protocol . . . . . . . . . . . . . . . . . . . . . 29 85 4.1. Key Exchange Messages . . . . . . . . . . . . . . . . . . 30 86 4.1.1. Cryptographic Negotiation . . . . . . . . . . . . . . 30 87 4.1.2. Client Hello . . . . . . . . . . . . . . . . . . . . 31 88 4.1.3. Server Hello . . . . . . . . . . . . . . . . . . . . 34 89 4.1.4. Hello Retry Request . . . . . . . . . . . . . . . . . 36 90 4.2. Extensions . . . . . . . . . . . . . . . . . . . . . . . 37 91 4.2.1. Supported Versions . . . . . . . . . . . . . . . . . 40 92 4.2.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . 41 93 4.2.3. Signature Algorithms . . . . . . . . . . . . . . . . 42 94 4.2.4. Certificate Authorities . . . . . . . . . . . . . . . 45 95 4.2.5. Post-Handshake Client Authentication . . . . . . . . 46 96 4.2.6. Negotiated Groups . . . . . . . . . . . . . . . . . . 46 97 4.2.7. Key Share . . . . . . . . . . . . . . . . . . . . . . 47 98 4.2.8. Pre-Shared Key Exchange Modes . . . . . . . . . . . . 51 99 4.2.9. Early Data Indication . . . . . . . . . . . . . . . . 51 100 4.2.10. Pre-Shared Key Extension . . . . . . . . . . . . . . 54 101 4.3. Server Parameters . . . . . . . . . . . . . . . . . . . . 58 102 4.3.1. Encrypted Extensions . . . . . . . . . . . . . . . . 58 103 4.3.2. Certificate Request . . . . . . . . . . . . . . . . . 59 104 4.4. Authentication Messages . . . . . . . . . . . . . . . . . 61 105 4.4.1. The Transcript Hash . . . . . . . . . . . . . . . . . 62 106 4.4.2. Certificate . . . . . . . . . . . . . . . . . . . . . 63 107 4.4.3. Certificate Verify . . . . . . . . . . . . . . . . . 67 108 4.4.4. Finished . . . . . . . . . . . . . . . . . . . . . . 69 109 4.5. End of Early Data . . . . . . . . . . . . . . . . . . . . 70 110 4.6. Post-Handshake Messages . . . . . . . . . . . . . . . . . 71 111 4.6.1. New Session Ticket Message . . . . . . . . . . . . . 71 112 4.6.2. Post-Handshake Authentication . . . . . . . . . . . . 73 113 4.6.3. Key and IV Update . . . . . . . . . . . . . . . . . . 73 114 5. Record Protocol . . . . . . . . . . . . . . . . . . . . . . . 74 115 5.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 75 116 5.2. Record Payload Protection . . . . . . . . . . . . . . . . 77 117 5.3. Per-Record Nonce . . . . . . . . . . . . . . . . . . . . 79 118 5.4. Record Padding . . . . . . . . . . . . . . . . . . . . . 79 119 5.5. Limits on Key Usage . . . . . . . . . . . . . . . . . . . 81 120 6. Alert Protocol . . . . . . . . . . . . . . . . . . . . . . . 81 121 6.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 82 122 6.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 83 123 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 86 124 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 86 125 7.2. Updating Traffic Keys and IVs . . . . . . . . . . . . . . 89 126 7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 90 127 7.4. (EC)DHE Shared Secret Calculation . . . . . . . . . . . . 90 128 7.4.1. Finite Field Diffie-Hellman . . . . . . . . . . . . . 90 129 7.4.2. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 91 130 7.5. Exporters . . . . . . . . . . . . . . . . . . . . . . . . 91 131 8. Compliance Requirements . . . . . . . . . . . . . . . . . . . 92 132 8.1. Mandatory-to-Implement Cipher Suites . . . . . . . . . . 92 133 8.2. Mandatory-to-Implement Extensions . . . . . . . . . . . . 92 134 9. Security Considerations . . . . . . . . . . . . . . . . . . . 94 135 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 94 136 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 95 137 11.1. Normative References . . . . . . . . . . . . . . . . . . 95 138 11.2. Informative References . . . . . . . . . . . . . . . . . 97 139 Appendix A. State Machine . . . . . . . . . . . . . . . . . . . 105 140 A.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 105 141 A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 105 142 Appendix B. Protocol Data Structures and Constant Values . . . . 106 143 B.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 106 144 B.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 107 145 B.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 109 146 B.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 109 147 B.3.2. Server Parameters Messages . . . . . . . . . . . . . 114 148 B.3.3. Authentication Messages . . . . . . . . . . . . . . . 115 149 B.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 116 150 B.3.5. Updating Keys . . . . . . . . . . . . . . . . . . . . 116 151 B.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 117 152 Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 118 153 C.1. API considerations for 0-RTT . . . . . . . . . . . . . . 118 154 C.2. Random Number Generation and Seeding . . . . . . . . . . 118 155 C.3. Certificates and Authentication . . . . . . . . . . . . . 118 156 C.4. Implementation Pitfalls . . . . . . . . . . . . . . . . . 119 157 C.5. Client Tracking Prevention . . . . . . . . . . . . . . . 120 158 C.6. Unauthenticated Operation . . . . . . . . . . . . . . . . 120 159 Appendix D. Backward Compatibility . . . . . . . . . . . . . . . 121 160 D.1. Negotiating with an older server . . . . . . . . . . . . 122 161 D.2. Negotiating with an older client . . . . . . . . . . . . 122 162 D.3. Zero-RTT backwards compatibility . . . . . . . . . . . . 123 163 D.4. Backwards Compatibility Security Restrictions . . . . . . 123 164 Appendix E. Overview of Security Properties . . . . . . . . . . 124 165 E.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 124 166 E.1.1. Key Derivation and HKDF . . . . . . . . . . . . . . . 127 167 E.1.2. Client Authentication . . . . . . . . . . . . . . . . 128 168 E.1.3. 0-RTT . . . . . . . . . . . . . . . . . . . . . . . . 128 169 E.1.4. Post-Compromise Security . . . . . . . . . . . . . . 128 170 E.1.5. External References . . . . . . . . . . . . . . . . . 128 171 E.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 129 172 E.2.1. External References . . . . . . . . . . . . . . . . . 130 173 E.3. Traffic Analysis . . . . . . . . . . . . . . . . . . . . 130 174 E.4. Side Channel Attacks . . . . . . . . . . . . . . . . . . 130 175 Appendix F. Working Group Information . . . . . . . . . . . . . 131 176 Appendix G. Contributors . . . . . . . . . . . . . . . . . . . . 131 177 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 137 179 1. Introduction 181 DISCLAIMER: This is a WIP draft of TLS 1.3 and has not yet seen 182 significant security analysis. 184 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 185 draft is maintained in GitHub. Suggested changes should be submitted 186 as pull requests at https://github.com/tlswg/tls13-spec. 187 Instructions are on that page as well. Editorial changes can be 188 managed in GitHub, but any substantive change should be discussed on 189 the TLS mailing list. 191 The primary goal of TLS is to provide a secure channel between two 192 communicating peers. Specifically, the channel should provide the 193 following properties: 195 - Authentication: The server side of the channel is always 196 authenticated; the client side is optionally authenticated. 197 Authentication can happen via asymmetric cryptography (e.g., RSA 198 [RSA], ECDSA [ECDSA]) or a pre-shared key (PSK). 200 - Confidentiality: Data sent over the channel is only visible to the 201 endpoints. TLS does not hide the length of the data it transmits, 202 though endpoints are able to pad in order to obscure lengths. 204 - Integrity: Data sent over the channel cannot be modified by 205 attackers. 207 These properties should be true even in the face of an attacker who 208 has complete control of the network, as described in [RFC3552]. See 209 Appendix E for a more complete statement of the relevant security 210 properties. 212 TLS consists of two primary components: 214 - A handshake protocol (Section 4) that authenticates the 215 communicating parties, negotiates cryptographic modes and 216 parameters, and establishes shared keying material. The handshake 217 protocol is designed to resist tampering; an active attacker 218 should not be able to force the peers to negotiate different 219 parameters than they would if the connection were not under 220 attack. 222 - A record protocol (Section 5) that uses the parameters established 223 by the handshake protocol to protect traffic between the 224 communicating peers. The record protocol divides traffic up into 225 a series of records, each of which is independently protected 226 using the traffic keys. 228 TLS is application protocol independent; higher-level protocols can 229 layer on top of TLS transparently. The TLS standard, however, does 230 not specify how protocols add security with TLS; how to initiate TLS 231 handshaking and how to interpret the authentication certificates 232 exchanged are left to the judgment of the designers and implementors 233 of protocols that run on top of TLS. 235 This document defines TLS version 1.3. While TLS 1.3 is not directly 236 compatible with previous versions, all versions of TLS incorporate a 237 versioning mechanism which allows clients and servers to 238 interoperably negotiate a common version if one is supported. 240 This document supersedes and obsoletes previous versions of TLS 241 including version 1.2 [RFC5246]. It also obsoletes the TLS ticket 242 mechanism defined in [RFC5077] and replaces it with the mechanism 243 defined in Section 2.2. Section 4.2.6 updates [RFC4492] by modifying 244 the protocol attributes used to negotiate Elliptic Curves. Because 245 TLS 1.3 changes the way keys are derived it updates [RFC5705] as 246 described in Section 7.5 it also changes how OCSP messages are 247 carried and therefore updates [RFC6066] and obsoletes [RFC6961] as 248 described in section Section 4.4.2.1. 250 1.1. Conventions and Terminology 252 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 253 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 254 "OPTIONAL" in this document are to be interpreted as described in RFC 255 2119 [RFC2119]. 257 The following terms are used: 259 client: The endpoint initiating the TLS connection. 261 connection: A transport-layer connection between two endpoints. 263 endpoint: Either the client or server of the connection. 265 handshake: An initial negotiation between client and server that 266 establishes the parameters of their subsequent interactions. 268 peer: An endpoint. When discussing a particular endpoint, "peer" 269 refers to the endpoint that is not the primary subject of discussion. 271 receiver: An endpoint that is receiving records. 273 sender: An endpoint that is transmitting records. 275 server: The endpoint which did not initiate the TLS connection. 277 1.2. Change Log 279 RFC EDITOR PLEASE DELETE THIS SECTION. 281 (*) indicates changes to the wire protocol which may require 282 implementations to update. 284 draft-20 286 - Add "post_handshake_auth" extension to negotiate post-handshake 287 authentication (*). 289 - Shorten labels for HKDF-Expand-Label so that we can fit within one 290 compression block (*). 292 - Define how RFC 7250 works (*). 294 - Re-enable post-handshake client authentication even when you do 295 PSK. The previous prohibition was editorial error. 297 - Remove cert_type and user_mapping, which don't work on TLS 1.3 298 anyway. 300 - Added the no_application_protocol alert from [RFC7301] to the list 301 of extensions. 303 - Added discussion of traffic analysis and side channel attacks. 305 draft-19 307 - Hash context_value input to Exporters (*) 309 - Add an additional Derive-Secret stage to Exporters (*). 311 - Hash ClientHello1 in the transcript when HRR is used. This 312 reduces the state that needs to be carried in cookies. (*) 314 - Restructure CertificateRequest to have the selectors in 315 extensions. This also allowed defining a 316 "certificate_authorities" extension which can be used by the 317 client instead of trusted_ca_keys (*). 319 - Tighten record framing requirements and require checking of them 320 (*). 322 - Consolidate "ticket_early_data_info" and "early_data" into a 323 single extension (*). 325 - Change end_of_early_data to be a handshake message (*). 327 - Add pre-extract Derive-Secret stages to key schedule (*). 329 - Remove spurious requirement to implement "pre_shared_key". 331 - Clarify location of "early_data" from server (it goes in EE, as 332 indicated by the table in S 10). 334 - Require peer public key validation 336 - Add state machine diagram. 338 - Remove unnecessary resumption_psk which is the only thing expanded 339 from the resumption master secret. (*). 341 - Fix signature_algorithms entry in extensions table. 343 - Restate rule from RFC 6066 that you can't resume unless SNI is the 344 same. 346 draft-17 348 - Remove 0-RTT Finished and resumption_context, and replace with a 349 psk_binder field in the PSK itself (*) 351 - Restructure PSK key exchange negotiation modes (*) 353 - Add max_early_data_size field to TicketEarlyDataInfo (*) 355 - Add a 0-RTT exporter and change the transcript for the regular 356 exporter (*) 358 - Merge TicketExtensions and Extensions registry. Changes 359 ticket_early_data_info code point (*) 361 - Replace Client.key_shares in response to HRR (*) 363 - Remove redundant labels for traffic key derivation (*) 365 - Harmonize requirements about cipher suite matching: for resumption 366 you need to match KDF but for 0-RTT you need whole cipher suite. 367 This allows PSKs to actually negotiate cipher suites. (*) 369 - Move SCT and OCSP into Certificate.extensions (*) 371 - Explicitly allow non-offered extensions in NewSessionTicket 373 - Explicitly allow predicting client Finished for NST 375 - Clarify conditions for allowing 0-RTT with PSK 377 draft-16 379 - Revise version negotiation (*) 381 - Change RSASSA-PSS and EdDSA SignatureScheme codepoints for better 382 backwards compatibility (*) 384 - Move HelloRetryRequest.selected_group to an extension (*) 386 - Clarify the behavior of no exporter context and make it the same 387 as an empty context.(*) 389 - New KeyUpdate format that allows for requesting/not-requesting an 390 answer. This also means changes to the key schedule to support 391 independent updates (*) 393 - New certificate_required alert (*) 395 - Forbid CertificateRequest with 0-RTT and PSK. 397 - Relax requirement to check SNI for 0-RTT. 399 draft-15 401 - New negotiation syntax as discussed in Berlin (*) 403 - Require CertificateRequest.context to be empty during handshake 404 (*) 406 - Forbid empty tickets (*) 408 - Forbid application data messages in between post-handshake 409 messages from the same flight (*) 411 - Clean up alert guidance (*) 413 - Clearer guidance on what is needed for TLS 1.2. 415 - Guidance on 0-RTT time windows. 417 - Rename a bunch of fields. 419 - Remove old PRNG text. 421 - Explicitly require checking that handshake records not span key 422 changes. 424 draft-14 426 - Allow cookies to be longer (*) 428 - Remove the "context" from EarlyDataIndication as it was undefined 429 and nobody used it (*) 431 - Remove 0-RTT EncryptedExtensions and replace the ticket_age 432 extension with an obfuscated version. Also necessitates a change 433 to NewSessionTicket (*). 435 - Move the downgrade sentinel to the end of ServerHello.Random to 436 accommodate tlsdate (*). 438 - Define ecdsa_sha1 (*). 440 - Allow resumption even after fatal alerts. This matches current 441 practice. 443 - Remove non-closure warning alerts. Require treating unknown 444 alerts as fatal. 446 - Make the rules for accepting 0-RTT less restrictive. 448 - Clarify 0-RTT backward-compatibility rules. 450 - Clarify how 0-RTT and PSK identities interact. 452 - Add a section describing the data limits for each cipher. 454 - Major editorial restructuring. 456 - Replace the Security Analysis section with a WIP draft. 458 draft-13 460 - Allow server to send SupportedGroups. 462 - Remove 0-RTT client authentication 464 - Remove (EC)DHE 0-RTT. 466 - Flesh out 0-RTT PSK mode and shrink EarlyDataIndication 468 - Turn PSK-resumption response into an index to save room 470 - Move CertificateStatus to an extension 472 - Extra fields in NewSessionTicket. 474 - Restructure key schedule and add a resumption_context value. 476 - Require DH public keys and secrets to be zero-padded to the size 477 of the group. 479 - Remove the redundant length fields in KeyShareEntry. 481 - Define a cookie field for HRR. 483 draft-12 485 - Provide a list of the PSK cipher suites. 487 - Remove the ability for the ServerHello to have no extensions (this 488 aligns the syntax with the text). 490 - Clarify that the server can send application data after its first 491 flight (0.5 RTT data) 493 - Revise signature algorithm negotiation to group hash, signature 494 algorithm, and curve together. This is backwards compatible. 496 - Make ticket lifetime mandatory and limit it to a week. 498 - Make the purpose strings lower-case. This matches how people are 499 implementing for interop. 501 - Define exporters. 503 - Editorial cleanup 505 draft-11 507 - Port the CFRG curves & signatures work from RFC4492bis. 509 - Remove sequence number and version from additional_data, which is 510 now empty. 512 - Reorder values in HkdfLabel. 514 - Add support for version anti-downgrade mechanism. 516 - Update IANA considerations section and relax some of the policies. 518 - Unify authentication modes. Add post-handshake client 519 authentication. 521 - Remove early_handshake content type. Terminate 0-RTT data with an 522 alert. 524 - Reset sequence number upon key change (as proposed by Fournet et 525 al.) 527 - Remove ClientCertificateTypes field from CertificateRequest and 528 add extensions. 530 - Merge client and server key shares into a single extension. 532 draft-09 534 - Change to RSA-PSS signatures for handshake messages. 536 - Remove support for DSA. 538 - Update key schedule per suggestions by Hugo, Hoeteck, and Bjoern 539 Tackmann. 541 - Add support for per-record padding. 543 - Switch to encrypted record ContentType. 545 - Change HKDF labeling to include protocol version and value 546 lengths. 548 - Shift the final decision to abort a handshake due to incompatible 549 certificates to the client rather than having servers abort early. 551 - Deprecate SHA-1 with signatures. 553 - Add MTI algorithms. 555 draft-08 557 - Remove support for weak and lesser used named curves. 559 - Remove support for MD5 and SHA-224 hashes with signatures. 561 - Update lists of available AEAD cipher suites and error alerts. 563 - Reduce maximum permitted record expansion for AEAD from 2048 to 564 256 octets. 566 - Require digital signatures even when a previous configuration is 567 used. 569 - Merge EarlyDataIndication and KnownConfiguration. 571 - Change code point for server_configuration to avoid collision with 572 server_hello_done. 574 - Relax certificate_list ordering requirement to match current 575 practice. 577 draft-07 579 - Integration of semi-ephemeral DH proposal. 581 - Add initial 0-RTT support. 583 - Remove resumption and replace with PSK + tickets. 585 - Move ClientKeyShare into an extension. 587 - Move to HKDF. 589 draft-06 591 - Prohibit RC4 negotiation for backwards compatibility. 593 - Freeze & deprecate record layer version field. 595 - Update format of signatures with context. 597 - Remove explicit IV. 599 draft-05 601 - Prohibit SSL negotiation for backwards compatibility. 603 - Fix which MS is used for exporters. 605 draft-04 607 - Modify key computations to include session hash. 609 - Remove ChangeCipherSpec. 611 - Renumber the new handshake messages to be somewhat more consistent 612 with existing convention and to remove a duplicate registration. 614 - Remove renegotiation. 616 - Remove point format negotiation. 618 draft-03 620 - Remove GMT time. 622 - Merge in support for ECC from RFC 4492 but without explicit 623 curves. 625 - Remove the unnecessary length field from the AD input to AEAD 626 ciphers. 628 - Rename {Client,Server}KeyExchange to {Client,Server}KeyShare. 630 - Add an explicit HelloRetryRequest to reject the client's. 632 draft-02 634 - Increment version number. 636 - Rework handshake to provide 1-RTT mode. 638 - Remove custom DHE groups. 640 - Remove support for compression. 642 - Remove support for static RSA and DH key exchange. 644 - Remove support for non-AEAD ciphers. 646 1.3. Major Differences from TLS 1.2 648 The following is a list of the major functional differences between 649 TLS 1.2 and TLS 1.3. It is not intended to be exhaustive and there 650 are many minor differences. 652 - The list of supported symmetric algorithms has been pruned of all 653 algorithms that are considered legacy. Those that remain all use 654 Authenticated Encryption with Associated Data (AEAD) algorithms. 655 The ciphersuite concept has been changed to separate the 656 authentication and key exchange mechanisms from the record 657 protection algorithm (including secret key length) and a hash to 658 be used with the key derivation function and HMAC. 660 - A Zero-RTT mode was added, saving a round-trip at connection setup 661 for some application data, at the cost of certain security 662 properties. 664 - All handshake messages after the ServerHello are now encrypted. 665 The newly introduced EncryptedExtension message allows various 666 extensions previously sent in clear in the ServerHello to also 667 enjoy confidentiality protection. 669 - The key derivation functions have been re-designed. The new 670 design allows easier analysis by cryptographers due to their 671 improved key separation properties. The HMAC-based Extract-and- 672 Expand Key Derivation Function (HKDF) is used as an underlying 673 primitive. 675 - The handshake state machine has been significantly restructured to 676 be more consistent and to remove superfluous messages such as 677 ChangeCipherSpec. 679 - ECC is now in the base spec and includes new signature algorithms, 680 such as ed25519 and ed448. TLS 1.3 removed point format 681 negotiation in favor of a single point format for each curve. 683 - Other cryptographic improvements including the removal of 684 compression and custom DHE groups, changing the RSA padding to use 685 PSS, and the removal of DSA. 687 - The TLS 1.2 version negotiation mechanism has been deprecated in 688 favor of a version list in an extension. This increases 689 compatibility with servers which incorrectly implemented version 690 negotiation. 692 - Session resumption with and without server-side state as well as 693 the PSK-based ciphersuites of earlier TLS versions have been 694 replaced by a single new PSK exchange. 696 1.4. Updates Affecting TLS 1.2 698 This document defines several changes that optionally affect 699 implementations of TLS 1.2: 701 - A version downgrade protection mechanism is described in 702 Section 4.1.3. 704 - RSASSA-PSS signature schemes are defined in Section 4.2.3. 706 - The "supported_versions" ClientHello extension can be used to 707 negotiate the version of TLS to use, in preference to the 708 legacy_version field of the ClientHello. 710 An implementation of TLS 1.3 that also supports TLS 1.2 might need to 711 include changes to support these changes even when TLS 1.3 is not in 712 use. See the referenced sections for more details. 714 2. Protocol Overview 716 The cryptographic parameters of the connection state are produced by 717 the TLS handshake protocol, which a TLS client and server use when 718 first communicating to agree on a protocol version, select 719 cryptographic algorithms, optionally authenticate each other, and 720 establish shared secret keying material. Once the handshake is 721 complete, the peers use the established keys to protect application 722 layer traffic. 724 A failure of the handshake or other protocol error triggers the 725 termination of the connection, optionally preceded by an alert 726 message (Section 6). 728 TLS supports three basic key exchange modes: 730 - (EC)DHE (Diffie-Hellman, both the finite field and elliptic curve 731 varieties), 733 - PSK-only, and 735 - PSK with (EC)DHE 737 Figure 1 below shows the basic full TLS handshake: 739 Client Server 741 Key ^ ClientHello 742 Exch | + key_share* 743 | + signature_algorithms* 744 | + psk_key_exchange_modes* 745 v + pre_shared_key* --------> 746 ServerHello ^ Key 747 + key_share* | Exch 748 + pre_shared_key* v 749 {EncryptedExtensions} ^ Server 750 {CertificateRequest*} v Params 751 {Certificate*} ^ 752 {CertificateVerify*} | Auth 753 {Finished} v 754 <-------- [Application Data*] 755 ^ {Certificate*} 756 Auth | {CertificateVerify*} 757 v {Finished} --------> 758 [Application Data] <-------> [Application Data] 760 + Indicates noteworthy extensions sent in the 761 previously noted message. 763 * Indicates optional or situation-dependent 764 messages/extensions that are not always sent. 766 {} Indicates messages protected using keys 767 derived from a [sender]_handshake_traffic_secret. 769 [] Indicates messages protected using keys 770 derived from [sender]_application_traffic_secret_N 772 Figure 1: Message flow for full TLS Handshake 774 The handshake can be thought of as having three phases (indicated in 775 the diagram above): 777 - Key Exchange: Establish shared keying material and select the 778 cryptographic parameters. Everything after this phase is 779 encrypted. 781 - Server Parameters: Establish other handshake parameters (whether 782 the client is authenticated, application layer protocol support, 783 etc.). 785 - Authentication: Authenticate the server (and optionally the 786 client) and provide key confirmation and handshake integrity. 788 In the Key Exchange phase, the client sends the ClientHello 789 (Section 4.1.2) message, which contains a random nonce 790 (ClientHello.random); its offered protocol versions; a list of 791 symmetric cipher/HKDF hash pairs; some set of Diffie-Hellman key 792 shares (in the "key_share" extension Section 4.2.7), a set of pre- 793 shared key labels (in the "pre_shared_key" extension Section 4.2.10) 794 or both; and potentially some other extensions. 796 The server processes the ClientHello and determines the appropriate 797 cryptographic parameters for the connection. It then responds with 798 its own ServerHello (Section 4.1.3), which indicates the negotiated 799 connection parameters. The combination of the ClientHello and the 800 ServerHello determines the shared keys. If (EC)DHE key establishment 801 is in use, then the ServerHello contains a "key_share" extension with 802 the server's ephemeral Diffie-Hellman share which MUST be in the same 803 group as one of the client's shares. If PSK key establishment is in 804 use, then the ServerHello contains a "pre_shared_key" extension 805 indicating which of the client's offered PSKs was selected. Note 806 that implementations can use (EC)DHE and PSK together, in which case 807 both extensions will be supplied. 809 The server then sends two messages to establish the Server 810 Parameters: 812 EncryptedExtensions: responses to ClientHello extensions that are 813 not required to determine the cryptographic parameters, other than 814 those that are specific to individual certificates. 815 [Section 4.3.1] 817 CertificateRequest: if certificate-based client authentication is 818 desired, the desired parameters for that certificate. This 819 message is omitted if client authentication is not desired. 820 [Section 4.3.2] 822 Finally, the client and server exchange Authentication messages. TLS 823 uses the same set of messages every time that authentication is 824 needed. Specifically: 826 Certificate: the certificate of the endpoint and any per-certificate 827 extensions. This message is omitted by the server if not 828 authenticating with a certificate and by the client if the server 829 did not send CertificateRequest (thus indicating that the client 830 should not authenticate with a certificate). Note that if raw 831 public keys [RFC7250] or the cached information extension 832 [RFC7924] are in use, then this message will not contain a 833 certificate but rather some other value corresponding to the 834 server's long-term key. [Section 4.4.2] 836 CertificateVerify: a signature over the entire handshake using the 837 private key corresponding to the public key in the Certificate 838 message. This message is omitted if the endpoint is not 839 authenticating via a certificate. [Section 4.4.3] 841 Finished: a MAC (Message Authentication Code) over the entire 842 handshake. This message provides key confirmation, binds the 843 endpoint's identity to the exchanged keys, and in PSK mode also 844 authenticates the handshake. [Section 4.4.4] 846 Upon receiving the server's messages, the client responds with its 847 Authentication messages, namely Certificate and CertificateVerify (if 848 requested), and Finished. 850 At this point, the handshake is complete, and the client and server 851 may exchange application-layer data. Application data MUST NOT be 852 sent prior to sending the Finished message. Note that while the 853 server may send application data prior to receiving the client's 854 Authentication messages, any data sent at that point is, of course, 855 being sent to an unauthenticated peer. 857 2.1. Incorrect DHE Share 859 If the client has not provided a sufficient "key_share" extension 860 (e.g., it includes only DHE or ECDHE groups unacceptable to or 861 unsupported by the server), the server corrects the mismatch with a 862 HelloRetryRequest and the client needs to restart the handshake with 863 an appropriate "key_share" extension, as shown in Figure 2. If no 864 common cryptographic parameters can be negotiated, the server MUST 865 abort the handshake with an appropriate alert. 867 Client Server 869 ClientHello 870 + key_share --------> 871 <-------- HelloRetryRequest 872 + key_share 874 ClientHello 875 + key_share --------> 876 ServerHello 877 + key_share 878 {EncryptedExtensions} 879 {CertificateRequest*} 880 {Certificate*} 881 {CertificateVerify*} 882 {Finished} 883 <-------- [Application Data*] 884 {Certificate*} 885 {CertificateVerify*} 886 {Finished} --------> 887 [Application Data] <-------> [Application Data] 889 Figure 2: Message flow for a full handshake with mismatched 890 parameters 892 Note: The handshake transcript includes the initial ClientHello/ 893 HelloRetryRequest exchange; it is not reset with the new ClientHello. 895 TLS also allows several optimized variants of the basic handshake, as 896 described in the following sections. 898 2.2. Resumption and Pre-Shared Key (PSK) 900 Although TLS PSKs can be established out of band, PSKs can also be 901 established in a previous connection and then reused ("session 902 resumption"). Once a handshake has completed, the server can send 903 the client a PSK identity that corresponds to a key derived from the 904 initial handshake (see Section 4.6.1). The client can then use that 905 PSK identity in future handshakes to negotiate use of the PSK. If 906 the server accepts it, then the security context of the new 907 connection is tied to the original connection and the key derived 908 from the initial handshake is used to bootstrap the cryptographic 909 state instead of a full handshake. In TLS 1.2 and below, this 910 functionality was provided by "session IDs" and "session tickets" 911 [RFC5077]. Both mechanisms are obsoleted in TLS 1.3. 913 PSKs can be used with (EC)DHE key exchange in order to provide 914 forward secrecy in combination with shared keys, or can be used 915 alone, at the cost of losing forward secrecy. 917 Figure 3 shows a pair of handshakes in which the first establishes a 918 PSK and the second uses it: 920 Client Server 922 Initial Handshake: 923 ClientHello 924 + key_share --------> 925 ServerHello 926 + key_share 927 {EncryptedExtensions} 928 {CertificateRequest*} 929 {Certificate*} 930 {CertificateVerify*} 931 {Finished} 932 <-------- [Application Data*] 933 {Certificate*} 934 {CertificateVerify*} 935 {Finished} --------> 936 <-------- [NewSessionTicket] 937 [Application Data] <-------> [Application Data] 939 Subsequent Handshake: 940 ClientHello 941 + key_share* 942 + psk_key_exchange_modes 943 + pre_shared_key --------> 944 ServerHello 945 + pre_shared_key 946 + key_share* 947 {EncryptedExtensions} 948 {Finished} 949 <-------- [Application Data*] 950 {Finished} --------> 951 [Application Data] <-------> [Application Data] 953 Figure 3: Message flow for resumption and PSK 955 As the server is authenticating via a PSK, it does not send a 956 Certificate or a CertificateVerify message. When a client offers 957 resumption via PSK, it SHOULD also supply a "key_share" extension to 958 the server to allow the server to decline resumption and fall back to 959 a full handshake, if needed. The server responds with a 960 "pre_shared_key" extension to negotiate use of PSK key establishment 961 and can (as shown here) respond with a "key_share" extension to do 962 (EC)DHE key establishment, thus providing forward secrecy. 964 When PSKs are provisioned out of band, the PSK identity and the KDF 965 to be used with the PSK MUST also be provisioned. Note: When using 966 an out-of-band provisioned pre-shared secret, a critical 967 consideration is using sufficient entropy during the key generation, 968 as discussed in [RFC4086]. Deriving a shared secret from a password 969 or other low-entropy sources is not secure. A low-entropy secret, or 970 password, is subject to dictionary attacks based on the PSK binder. 971 The specified PSK authentication is not a strong password-based 972 authenticated key exchange even when used with Diffie-Hellman key 973 establishment. 975 2.3. Zero-RTT Data 977 When clients and servers share a PSK (either obtained externally or 978 via a previous handshake), TLS 1.3 allows clients to send data on the 979 first flight ("early data"). The client uses the PSK to authenticate 980 the server and to encrypt the early data. 982 When clients use a PSK obtained externally to send early data, then 983 the following additional information MUST be provisioned to both 984 parties: 986 - The cipher suite for use with this PSK 988 - The Application-Layer Protocol Negotiation (ALPN) protocol, if any 989 is to be used 991 - The Server Name Indication (SNI), if any is to be used 993 As shown in Figure 4, the 0-RTT data is just added to the 1-RTT 994 handshake in the first flight. The rest of the handshake uses the 995 same messages as with a 1-RTT handshake with PSK resumption. 997 Client Server 999 ClientHello 1000 + early_data 1001 + key_share* 1002 + psk_key_exchange_modes 1003 + pre_shared_key 1004 (Application Data*) --------> 1005 ServerHello 1006 + pre_shared_key 1007 + key_share* 1008 {EncryptedExtensions} 1009 + early_data* 1010 {Finished} 1011 <-------- [Application Data*] 1012 (EndOfEarlyData) 1013 {Finished} --------> 1015 [Application Data] <-------> [Application Data] 1017 + Indicates noteworthy extensions sent in the 1018 previously noted message. 1020 * Indicates optional or situation-dependent 1021 messages/extensions that are not always sent. 1023 () Indicates messages protected using keys 1024 derived from client_early_traffic_secret. 1026 {} Indicates messages protected using keys 1027 derived from a [sender]_handshake_traffic_secret. 1029 [] Indicates messages protected using keys 1030 derived from [sender]_application_traffic_secret_N 1032 Figure 4: Message flow for a zero round trip handshake 1034 IMPORTANT NOTE: The security properties for 0-RTT data are weaker 1035 than those for other kinds of TLS data. Specifically: 1037 1. This data is not forward secret, as it is encrypted solely under 1038 keys derived using the offered PSK. 1040 2. There are no guarantees of non-replay between connections. 1041 Unless the server takes special measures outside those provided 1042 by TLS, the server has no guarantee that the same 0-RTT data was 1043 not transmitted on multiple 0-RTT connections (see 1044 Section 4.2.10.4 for more details). This is especially relevant 1045 if the data is authenticated either with TLS client 1046 authentication or inside the application layer protocol. 1047 However, 0-RTT data cannot be duplicated within a connection 1048 (i.e., the server will not process the same data twice for the 1049 same connection) and an attacker will not be able to make 0-RTT 1050 data appear to be 1-RTT data (because it is protected with 1051 different keys.) 1053 Protocols MUST NOT use 0-RTT data without a profile that defines its 1054 use. That profile needs to identify which messages or interactions 1055 are safe to use with 0-RTT. In addition, to avoid accidental misuse, 1056 implementations SHOULD NOT enable 0-RTT unless specifically 1057 requested. Implementations SHOULD provide special functions for 1058 0-RTT data to ensure that an application is always aware that it is 1059 sending or receiving data that might be replayed. 1061 The same warnings apply to any use of the 1062 early_exporter_master_secret. 1064 The remainder of this document provides a detailed description of 1065 TLS. 1067 3. Presentation Language 1069 This document deals with the formatting of data in an external 1070 representation. The following very basic and somewhat casually 1071 defined presentation syntax will be used. 1073 3.1. Basic Block Size 1075 The representation of all data items is explicitly specified. The 1076 basic data block size is one byte (i.e., 8 bits). Multiple byte data 1077 items are concatenations of bytes, from left to right, from top to 1078 bottom. From the byte stream, a multi-byte item (a numeric in the 1079 example) is formed (using C notation) by: 1081 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 1082 ... | byte[n-1]; 1084 This byte ordering for multi-byte values is the commonplace network 1085 byte order or big-endian format. 1087 3.2. Miscellaneous 1089 Comments begin with "/*" and end with "*/". 1091 Optional components are denoted by enclosing them in "[[ ]]" double 1092 brackets. 1094 Single-byte entities containing uninterpreted data are of type 1095 opaque. 1097 3.3. Vectors 1099 A vector (single-dimensioned array) is a stream of homogeneous data 1100 elements. The size of the vector may be specified at documentation 1101 time or left unspecified until runtime. In either case, the length 1102 declares the number of bytes, not the number of elements, in the 1103 vector. The syntax for specifying a new type, T', that is a fixed- 1104 length vector of type T is 1106 T T'[n]; 1108 Here, T' occupies n bytes in the data stream, where n is a multiple 1109 of the size of T. The length of the vector is not included in the 1110 encoded stream. 1112 In the following example, Datum is defined to be three consecutive 1113 bytes that the protocol does not interpret, while Data is three 1114 consecutive Datum, consuming a total of nine bytes. 1116 opaque Datum[3]; /* three uninterpreted bytes */ 1117 Datum Data[9]; /* 3 consecutive 3-byte vectors */ 1119 Variable-length vectors are defined by specifying a subrange of legal 1120 lengths, inclusively, using the notation . When 1121 these are encoded, the actual length precedes the vector's contents 1122 in the byte stream. The length will be in the form of a number 1123 consuming as many bytes as required to hold the vector's specified 1124 maximum (ceiling) length. A variable-length vector with an actual 1125 length field of zero is referred to as an empty vector. 1127 T T'; 1129 In the following example, mandatory is a vector that must contain 1130 between 300 and 400 bytes of type opaque. It can never be empty. 1131 The actual length field consumes two bytes, a uint16, which is 1132 sufficient to represent the value 400 (see Section 3.4). Similarly, 1133 longer can represent up to 800 bytes of data, or 400 uint16 elements, 1134 and it may be empty. Its encoding will include a two-byte actual 1135 length field prepended to the vector. The length of an encoded 1136 vector must be an exact multiple of the length of a single element 1137 (e.g., a 17-byte vector of uint16 would be illegal). 1139 opaque mandatory<300..400>; 1140 /* length field is 2 bytes, cannot be empty */ 1141 uint16 longer<0..800>; 1142 /* zero to 400 16-bit unsigned integers */ 1144 3.4. Numbers 1146 The basic numeric data type is an unsigned byte (uint8). All larger 1147 numeric data types are formed from fixed-length series of bytes 1148 concatenated as described in Section 3.1 and are also unsigned. The 1149 following numeric types are predefined. 1151 uint8 uint16[2]; 1152 uint8 uint24[3]; 1153 uint8 uint32[4]; 1154 uint8 uint64[8]; 1156 All values, here and elsewhere in the specification, are stored in 1157 network byte (big-endian) order; the uint32 represented by the hex 1158 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 1160 3.5. Enumerateds 1162 An additional sparse data type is available called enum. Each 1163 definition is a different type. Only enumerateds of the same type 1164 may be assigned or compared. Every element of an enumerated must be 1165 assigned a value, as demonstrated in the following example. Since 1166 the elements of the enumerated are not ordered, they can be assigned 1167 any unique value, in any order. 1169 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 1171 Future extensions or additions to the protocol may define new values. 1172 Implementations need to be able to parse and ignore unknown values 1173 unless the definition of the field states otherwise. 1175 An enumerated occupies as much space in the byte stream as would its 1176 maximal defined ordinal value. The following definition would cause 1177 one byte to be used to carry fields of type Color. 1179 enum { red(3), blue(5), white(7) } Color; 1181 One may optionally specify a value without its associated tag to 1182 force the width definition without defining a superfluous element. 1184 In the following example, Taste will consume two bytes in the data 1185 stream but can only assume the values 1, 2, or 4 in the current 1186 version of the protocol. 1188 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 1190 The names of the elements of an enumeration are scoped within the 1191 defined type. In the first example, a fully qualified reference to 1192 the second element of the enumeration would be Color.blue. Such 1193 qualification is not required if the target of the assignment is well 1194 specified. 1196 Color color = Color.blue; /* overspecified, legal */ 1197 Color color = blue; /* correct, type implicit */ 1199 The names assigned to enumerateds do not need to be unique. The 1200 numerical value can describe a range over which the same name 1201 applies. The value includes the minimum and maximum inclusive values 1202 in that range, separated by two period characters. This is 1203 principally useful for reserving regions of the space. 1205 enum { sad(0), meh(1..254), happy(255) } Mood; 1207 3.6. Constructed Types 1209 Structure types may be constructed from primitive types for 1210 convenience. Each specification declares a new, unique type. The 1211 syntax for definition is much like that of C. 1213 struct { 1214 T1 f1; 1215 T2 f2; 1216 ... 1217 Tn fn; 1218 } [[T]]; 1220 The fields within a structure may be qualified using the type's name, 1221 with a syntax much like that available for enumerateds. For example, 1222 T.f2 refers to the second field of the previous declaration. 1223 Structure definitions may be embedded. Anonymous structs may also be 1224 defined inside other structures. 1226 3.7. Constants 1228 Fields and variables may be assigned a fixed value using "=", as in: 1230 struct { 1231 T1 f1 = 8; /* T.f1 must always be 8 */ 1232 T2 f2; 1233 } T; 1235 3.8. Variants 1237 Defined structures may have variants based on some knowledge that is 1238 available within the environment. The selector must be an enumerated 1239 type that defines the possible variants the structure defines. The 1240 body of the variant structure may be given a label for reference. 1241 The mechanism by which the variant is selected at runtime is not 1242 prescribed by the presentation language. 1244 struct { 1245 T1 f1; 1246 T2 f2; 1247 .... 1248 Tn fn; 1249 select (E) { 1250 case e1: Te1; 1251 case e2: Te2; 1252 .... 1253 case en: Ten; 1254 } [[fv]]; 1255 } [[Tv]]; 1257 For example: 1259 enum { apple(0), orange(1) } VariantTag; 1261 struct { 1262 uint16 number; 1263 opaque string<0..10>; /* variable length */ 1264 } V1; 1266 struct { 1267 uint32 number; 1268 opaque string[10]; /* fixed length */ 1269 } V2; 1271 struct { 1272 VariantTag type; 1273 select (VariantRecord.type) { 1274 case apple: V1; 1275 case orange: V2; 1276 }; 1277 } VariantRecord; 1279 4. Handshake Protocol 1281 The handshake protocol is used to negotiate the secure attributes of 1282 a connection. Handshake messages are supplied to the TLS record 1283 layer, where they are encapsulated within one or more TLSPlaintext or 1284 TLSCiphertext structures, which are processed and transmitted as 1285 specified by the current active connection state. 1287 enum { 1288 client_hello(1), 1289 server_hello(2), 1290 new_session_ticket(4), 1291 end_of_early_data(5), 1292 hello_retry_request(6), 1293 encrypted_extensions(8), 1294 certificate(11), 1295 certificate_request(13), 1296 certificate_verify(15), 1297 finished(20), 1298 key_update(24), 1299 message_hash(254), 1300 (255) 1301 } HandshakeType; 1303 struct { 1304 HandshakeType msg_type; /* handshake type */ 1305 uint24 length; /* bytes in message */ 1306 select (Handshake.msg_type) { 1307 case client_hello: ClientHello; 1308 case server_hello: ServerHello; 1309 case end_of_early_data: EndOfEarlyData; 1310 case hello_retry_request: HelloRetryRequest; 1311 case encrypted_extensions: EncryptedExtensions; 1312 case certificate_request: CertificateRequest; 1313 case certificate: Certificate; 1314 case certificate_verify: CertificateVerify; 1315 case finished: Finished; 1316 case new_session_ticket: NewSessionTicket; 1317 case key_update: KeyUpdate; 1318 } body; 1319 } Handshake; 1321 Protocol messages MUST be sent in the order defined in Section 4.4.1 1322 and shown in the diagrams in Section 2. A peer which receives a 1323 handshake message in an unexpected order MUST abort the handshake 1324 with an "unexpected_message" alert. However, unneeded handshake 1325 messages are omitted. 1327 New handshake message types are assigned by IANA as described in 1328 Section 10. 1330 4.1. Key Exchange Messages 1332 The key exchange messages are used to exchange security capabilities 1333 between the client and server and to establish the traffic keys used 1334 to protect the handshake and data. 1336 4.1.1. Cryptographic Negotiation 1338 TLS cryptographic negotiation proceeds by the client offering the 1339 following four sets of options in its ClientHello: 1341 - A list of cipher suites which indicates the AEAD algorithm/HKDF 1342 hash pairs which the client supports. 1344 - A "supported_groups" (Section 4.2.6) extension which indicates the 1345 (EC)DHE groups which the client supports and a "key_share" 1346 (Section 4.2.7) extension which contains (EC)DHE shares for some 1347 or all of these groups. 1349 - A "signature_algorithms" (Section 4.2.3) extension which indicates 1350 the signature algorithms which the client can accept. 1352 - A "pre_shared_key" (Section 4.2.10) extension which contains a 1353 list of symmetric key identities known to the client and a 1354 "psk_key_exchange_modes" (Section 4.2.8) extension which indicates 1355 the key exchange modes that may be used with PSKs. 1357 If the server does not select a PSK, then the first three of these 1358 options are entirely orthogonal: the server independently selects a 1359 cipher suite, an (EC)DHE group and key share for key establishment, 1360 and a signature algorithm/certificate pair to authenticate itself to 1361 the client. If there is no overlap between the received 1362 "supported_groups" and the groups supported by the server then the 1363 server MUST abort the handshake. 1365 If the server selects a PSK, then it MUST also select a key 1366 establishment mode from the set indicated by client's 1367 "psk_key_exchange_modes" extension (at present, PSK alone or with 1368 (EC)DHE). Note that if the PSK can be used without (EC)DHE then non- 1369 overlap in the "supported_groups" parameters need not be fatal, as it 1370 is in the non-PSK case discussed in the previous paragraph. 1372 If the server selects an (EC)DHE group and the client did not offer a 1373 compatible "key_share" extension in the initial ClientHello, the 1374 server MUST respond with a HelloRetryRequest (Section 4.1.4) message. 1376 If the server successfully selects parameters and does not require a 1377 HelloRetryRequest, it indicates the selected parameters in the 1378 ServerHello as follows: 1380 - If PSK is being used, then the server will send a "pre_shared_key" 1381 extension indicating the selected key. 1383 - If PSK is not being used, then (EC)DHE and certificate-based 1384 authentication are always used. 1386 - When (EC)DHE is in use, the server will also provide a "key_share" 1387 extension. 1389 - When authenticating via a certificate, the server will send the 1390 Certificate (Section 4.4.2) and CertificateVerify (Section 4.4.3) 1391 messages. In TLS 1.3 as defined by this document, either a PSK or 1392 a certificate is always used, but not both. Future documents may 1393 define how to use them together. 1395 If the server is unable to negotiate a supported set of parameters 1396 (i.e., there is no overlap between the client and server parameters), 1397 it MUST abort the handshake with either a "handshake_failure" or 1398 "insufficient_security" fatal alert (see Section 6). 1400 4.1.2. Client Hello 1402 When a client first connects to a server, it is REQUIRED to send the 1403 ClientHello as its first message. The client will also send a 1404 ClientHello when the server has responded to its ClientHello with a 1405 HelloRetryRequest. In that case, the client MUST send the same 1406 ClientHello (without modification) except: 1408 - If a "key_share" extension was supplied in the HelloRetryRequest, 1409 replacing the list of shares with a list containing a single 1410 KeyShareEntry from the indicated group. 1412 - Removing the "early_data" extension (Section 4.2.9) if one was 1413 present. Early data is not permitted after HelloRetryRequest. 1415 - Including a "cookie" extension if one was provided in the 1416 HelloRetryRequest. 1418 - Updating the "pre_shared_key" extension if present by recomputing 1419 the "obfuscated_ticket_age" and binder values and (optionally) 1420 removing any PSKs which are incompatible with the server's 1421 indicated cipher suite. 1423 Because TLS 1.3 forbids renegotiation, if a server has negotiated TLS 1424 1.3 and receives a ClientHello at any other time, it MUST terminate 1425 the connection. 1427 If a server established a TLS connection with a previous version of 1428 TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST 1429 retain the previous protocol version. In particular, it MUST NOT 1430 negotiate TLS 1.3. 1432 Structure of this message: 1434 uint16 ProtocolVersion; 1435 opaque Random[32]; 1437 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1439 struct { 1440 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 1441 Random random; 1442 opaque legacy_session_id<0..32>; 1443 CipherSuite cipher_suites<2..2^16-2>; 1444 opaque legacy_compression_methods<1..2^8-1>; 1445 Extension extensions<8..2^16-1>; 1446 } ClientHello; 1448 legacy_version In previous versions of TLS, this field was used for 1449 version negotiation and represented the highest version number 1450 supported by the client. Experience has shown that many servers 1451 do not properly implement version negotiation, leading to "version 1452 intolerance" in which the server rejects an otherwise acceptable 1453 ClientHello with a version number higher than it supports. In TLS 1454 1.3, the client indicates its version preferences in the 1455 "supported_versions" extension (Section 4.2.1) and the 1456 legacy_version field MUST be set to 0x0303, which is the version 1457 number for TLS 1.2. (See Appendix D for details about backward 1458 compatibility.) 1460 random 32 bytes generated by a secure random number generator. See 1461 Appendix C for additional information. 1463 legacy_session_id Versions of TLS before TLS 1.3 supported a 1464 "session resumption" feature which has been merged with Pre-Shared 1465 Keys in this version (see Section 2.2). This field MUST be 1466 ignored by a server negotiating TLS 1.3 and MUST be set as a zero 1467 length vector (i.e., a single zero byte length field) by clients 1468 that do not have a cached session ID set by a pre-TLS 1.3 server. 1470 cipher_suites This is a list of the symmetric cipher options 1471 supported by the client, specifically the record protection 1472 algorithm (including secret key length) and a hash to be used with 1473 HKDF, in descending order of client preference. If the list 1474 contains cipher suites the server does not recognize, support, or 1475 wish to use, the server MUST ignore those cipher suites, and 1476 process the remaining ones as usual. Values are defined in 1477 Appendix B.4. If the client is attempting a PSK key 1478 establishment, it SHOULD advertise at least one cipher suite 1479 indicating a Hash associated with the PSK. 1481 legacy_compression_methods Versions of TLS before 1.3 supported 1482 compression with the list of supported compression methods being 1483 sent in this field. For every TLS 1.3 ClientHello, this vector 1484 MUST contain exactly one byte set to zero, which corresponds to 1485 the "null" compression method in prior versions of TLS. If a TLS 1486 1.3 ClientHello is received with any other value in this field, 1487 the server MUST abort the handshake with an "illegal_parameter" 1488 alert. Note that TLS 1.3 servers might receive TLS 1.2 or prior 1489 ClientHellos which contain other compression methods and MUST 1490 follow the procedures for the appropriate prior version of TLS. 1491 TLS 1.3 ClientHellos are identified as having a legacy_version of 1492 0x0303 and a supported_versions extension present with 0x0304 as 1493 the highest version indicated therein. 1495 extensions Clients request extended functionality from servers by 1496 sending data in the extensions field. The actual "Extension" 1497 format is defined in Section 4.2. In TLS 1.3, use of certain 1498 extensions is mandatory, as functionality is moved into extensions 1499 to preserve ClientHello compatibility with previous versions of 1500 TLS. Servers MUST ignore unrecognized extensions. 1502 All versions of TLS allow extensions to optionally follow the 1503 compression_methods field as an extensions field. TLS 1.3 1504 ClientHello messages always contain extensions (minimally, 1505 "supported_versions", or they will be interpreted as TLS 1.2 1506 ClientHello messages), however TLS 1.3 servers might receive 1507 ClientHello messages without an extensions field from prior versions 1508 of TLS. The presence of extensions can be detected by determining 1509 whether there are bytes following the compression_methods field at 1510 the end of the ClientHello. Note that this method of detecting 1511 optional data differs from the normal TLS method of having a 1512 variable-length field, but it is used for compatibility with TLS 1513 before extensions were defined. TLS 1.3 servers will need to perform 1514 this check first and only attempt to negotiate TLS 1.3 if a 1515 "supported_version" extension is present. If negotiating a version 1516 of TLS prior to 1.3, a server MUST check that the message either 1517 contains no data after legacy_compression_methods or that it contains 1518 a valid extensions block with no data following. If not, then it 1519 MUST abort the handshake with a "decode_error" alert. 1521 In the event that a client requests additional functionality using 1522 extensions, and this functionality is not supplied by the server, the 1523 client MAY abort the handshake. 1525 After sending the ClientHello message, the client waits for a 1526 ServerHello or HelloRetryRequest message. If early data is in use, 1527 the client may transmit early application data Section 2.3 while 1528 waiting for the next handshake message. 1530 4.1.3. Server Hello 1532 The server will send this message in response to a ClientHello 1533 message if it is able to find an acceptable set of parameters and the 1534 ClientHello contains sufficient information to proceed with the 1535 handshake. 1537 Structure of this message: 1539 struct { 1540 ProtocolVersion version; 1541 Random random; 1542 CipherSuite cipher_suite; 1543 Extension extensions<6..2^16-1>; 1544 } ServerHello; 1546 version This field contains the version of TLS negotiated for this 1547 connection. Servers MUST select a version from the list in 1548 ClientHello's supported_versions extension, or otherwise negotiate 1549 TLS 1.2 or previous. A client that receives a version that was 1550 not offered MUST abort the handshake. For this version of the 1551 specification, the version is 0x0304. (See Appendix D for details 1552 about backward compatibility.) 1554 random 32 bytes generated by a secure random number generator. See 1555 Appendix C for additional information. The last eight bytes MUST 1556 be overwritten as described below if negotiating TLS 1.2 or TLS 1557 1.1. This structure is generated by the server and MUST be 1558 generated independently of the ClientHello.random. 1560 cipher_suite The single cipher suite selected by the server from the 1561 list in ClientHello.cipher_suites. A client which receives a 1562 cipher suite that was not offered MUST abort the handshake. 1564 extensions A list of extensions. The ServerHello MUST only include 1565 extensions which are required to establish the cryptographic 1566 context. Currently the only such extensions are "key_share" and 1567 "pre_shared_key". All current TLS 1.3 ServerHello messages will 1568 contain one of these two extensions, or both when using a PSK with 1569 (EC)DHE key establishment. 1571 TLS 1.3 has a downgrade protection mechanism embedded in the server's 1572 random value. TLS 1.3 servers which negotiate TLS 1.2 or below in 1573 response to a ClientHello MUST set the last eight bytes of their 1574 Random value specially. 1576 If negotiating TLS 1.2, TLS 1.3 servers MUST set the last eight bytes 1577 of their Random value to the bytes: 1579 44 4F 57 4E 47 52 44 01 1581 If negotiating TLS 1.1 or below, TLS 1.3 servers MUST and TLS 1.2 1582 servers SHOULD set the last eight bytes of their Random value to the 1583 bytes: 1585 44 4F 57 4E 47 52 44 00 1587 TLS 1.3 clients receiving a TLS 1.2 or below ServerHello MUST check 1588 that the last eight bytes are not equal to either of these values. 1589 TLS 1.2 clients SHOULD also check that the last eight bytes are not 1590 equal to the second value if the ServerHello indicates TLS 1.1 or 1591 below. If a match is found, the client MUST abort the handshake with 1592 an "illegal_parameter" alert. This mechanism provides limited 1593 protection against downgrade attacks over and above that provided by 1594 the Finished exchange: because the ServerKeyExchange, a message 1595 present in TLS 1.2 and below, includes a signature over both random 1596 values, it is not possible for an active attacker to modify the 1597 random values without detection as long as ephemeral ciphers are 1598 used. It does not provide downgrade protection when static RSA is 1599 used. 1601 Note: This is a change from [RFC5246], so in practice many TLS 1.2 1602 clients and servers will not behave as specified above. 1604 A client that receives a TLS 1.3 ServerHello during renegotiation 1605 MUST abort the handshake with a "protocol_version" alert. Note that 1606 renegotiation is only possible when a version of TLS prior to 1.3 has 1607 been negotiated. 1609 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH Implementations of 1610 draft versions (see Section 4.2.1.1) of this specification SHOULD NOT 1611 implement this mechanism on either client and server. A pre-RFC 1612 client connecting to RFC servers, or vice versa, will appear to 1613 downgrade to TLS 1.2. With the mechanism enabled, this will cause an 1614 interoperability failure. 1616 4.1.4. Hello Retry Request 1618 The server will send this message in response to a ClientHello 1619 message if it is able to find an acceptable set of parameters but the 1620 ClientHello does not contain sufficient information to proceed with 1621 the handshake. 1623 Structure of this message: 1625 struct { 1626 ProtocolVersion server_version; 1627 CipherSuite cipher_suite; 1628 Extension extensions<2..2^16-1>; 1629 } HelloRetryRequest; 1631 The version, cipher_suite, and extensions fields have the same 1632 meanings as their corresponding values in the ServerHello. The 1633 server SHOULD send only the extensions necessary for the client to 1634 generate a correct ClientHello pair. As with ServerHello, a 1635 HelloRetryRequest MUST NOT contain any extensions that were not first 1636 offered by the client in its ClientHello, with the exception of 1637 optionally the "cookie" (see Section 4.2.2) extension. 1639 Upon receipt of a HelloRetryRequest, the client MUST verify that the 1640 extensions block is not empty and otherwise MUST abort the handshake 1641 with a "decode_error" alert. Clients MUST abort the handshake with 1642 an "illegal_parameter" alert if the HelloRetryRequest would not 1643 result in any change in the ClientHello. If a client receives a 1644 second HelloRetryRequest in the same connection (i.e., where the 1645 ClientHello was itself in response to a HelloRetryRequest), it MUST 1646 abort the handshake with an "unexpected_message" alert. 1648 Otherwise, the client MUST process all extensions in the 1649 HelloRetryRequest and send a second updated ClientHello. The 1650 HelloRetryRequest extensions defined in this specification are: 1652 - cookie (see Section 4.2.2) 1654 - key_share (see Section 4.2.7) 1656 In addition, in its updated ClientHello, the client SHOULD NOT offer 1657 any pre-shared keys associated with a hash other than that of the 1658 selected cipher suite. This allows the client to avoid having to 1659 compute partial hash transcripts for multiple hashes in the second 1660 ClientHello. A client which receives a cipher suite that was not 1661 offered MUST abort the handshake. Servers MUST ensure that they 1662 negotiate the same cipher suite when receiving a conformant updated 1663 ClientHello (if the server selects the cipher suite as the first step 1664 in the negotiation, then this will happen automatically). Upon 1665 receiving the ServerHello, clients MUST check that the cipher suite 1666 supplied in the ServerHello is the same as that in the 1667 HelloRetryRequest and otherwise abort the handshake with an 1668 "illegal_parameter" alert. 1670 4.2. Extensions 1672 A number of TLS messages contain tag-length-value encoded extensions 1673 structures. 1675 struct { 1676 ExtensionType extension_type; 1677 opaque extension_data<0..2^16-1>; 1678 } Extension; 1680 enum { 1681 server_name(0), /* RFC 6066 */ 1682 max_fragment_length(1), /* RFC 6066 */ 1683 status_request(5), /* RFC 6066 */ 1684 supported_groups(10), /* RFC 4492, 7919 */ 1685 signature_algorithms(13), /* RFC 5246 */ 1686 use_srtp(14), /* RFC 5764 */ 1687 heartbeat(15), /* RFC 6520 */ 1688 application_layer_protocol_negotiation(16), /* RFC 7301 */ 1689 signed_certificate_timestamp(18), /* RFC 6962 */ 1690 client_certificate_type(19), /* RFC 7250 */ 1691 server_certificate_type(20) /* RFC 7250 */ 1692 padding(21), /* RFC 7685 */ 1693 key_share(40), /* [[this document]] */ 1694 pre_shared_key(41), /* [[this document]] */ 1695 early_data(42), /* [[this document]] */ 1696 supported_versions(43), /* [[this document]] */ 1697 cookie(44), /* [[this document]] */ 1698 psk_key_exchange_modes(45), /* [[this document]] */ 1699 certificate_authorities(47), /* [[this document]] */ 1700 oid_filters(48), /* [[this document]] */ 1701 post_handshake_auth(49), /* [[this document]] */ 1702 (65535) 1703 } ExtensionType; 1705 Here: 1707 - "extension_type" identifies the particular extension type. 1709 - "extension_data" contains information specific to the particular 1710 extension type. 1712 The list of extension types is maintained by IANA as described in 1713 Section 10. 1715 Extensions are generally structured in a request/response fashion, 1716 though some extensions are just indications with no corresponding 1717 response. The client sends its extension requests in the ClientHello 1718 message and the server sends its extension responses in the 1719 ServerHello, EncryptedExtensions and HelloRetryRequest messages. The 1720 server sends extension requests in the CertificateRequest message 1721 which a client MAY respond to with a Certificate message. The server 1722 MAY also send unsolicited extensions in the NewSessionTicket, though 1723 the client does not respond directly to these. 1725 Implementations MUST NOT send extension responses if the remote 1726 endpoint did not send the corresponding extension requests, with the 1727 exception of the "cookie" extension in HelloRetryRequest. Upon 1728 receiving such an extension, an endpoint MUST abort the handshake 1729 with an "unsupported_extension" alert. 1731 The table below indicates the messages where a given extension may 1732 appear, using the following notation: CH (ClientHello), SH 1733 (ServerHello), EE (EncryptedExtensions), CT (Certificate), CR 1734 (CertificateRequest), NST (NewSessionTicket) and HRR 1735 (HelloRetryRequest). If an implementation receives an extension 1736 which it recognizes and which is not specified for the message in 1737 which it appears it MUST abort the handshake with an 1738 "illegal_parameter" alert. 1740 +--------------------------------------------------+-------------+ 1741 | Extension | TLS 1.3 | 1742 +--------------------------------------------------+-------------+ 1743 | server_name [RFC6066] | CH, EE | 1744 | | | 1745 | max_fragment_length [RFC6066] | CH, EE | 1746 | | | 1747 | status_request [RFC6066] | CH, CR, CT | 1748 | | | 1749 | supported_groups [RFC7919] | CH, EE | 1750 | | | 1751 | signature_algorithms [RFC5246] | CH, CR | 1752 | | | 1753 | use_srtp [RFC5764] | CH, EE | 1754 | | | 1755 | heartbeat [RFC6520] | CH, EE | 1756 | | | 1757 | application_layer_protocol_negotiation [RFC7301] | CH, EE | 1758 | | | 1759 | signed_certificate_timestamp [RFC6962] | CH, CR, CT | 1760 | | | 1761 | client_certificate_type [RFC7250] | CH, EE | 1762 | | | 1763 | server_certificate_type [RFC7250] | CH, CT | 1764 | | | 1765 | padding [RFC7685] | CH | 1766 | | | 1767 | key_share [[this document]] | CH, SH, HRR | 1768 | | | 1769 | pre_shared_key [[this document]] | CH, SH | 1770 | | | 1771 | psk_key_exchange_modes [[this document]] | CH | 1772 | | | 1773 | early_data [[this document]] | CH, EE, NST | 1774 | | | 1775 | cookie [[this document]] | CH, HRR | 1776 | | | 1777 | supported_versions [[this document]] | CH | 1778 | | | 1779 | certificate_authorities [[this document]] | CH, CR | 1780 | | | 1781 | oid_filters [[this document]] | CR | 1782 | | | 1783 | post_handshake_auth [[this document]] | CH | 1784 +--------------------------------------------------+-------------+ 1786 When multiple extensions of different types are present, the 1787 extensions MAY appear in any order, with the exception of 1788 "pre_shared_key" Section 4.2.10 which MUST be the last extension in 1789 the ClientHello. There MUST NOT be more than one extension of the 1790 same type in a given extension block. 1792 In TLS 1.3, unlike TLS 1.2, extensions are renegotiated with each 1793 handshake even when in resumption-PSK mode. However, 0-RTT 1794 parameters are those negotiated in the previous handshake; mismatches 1795 may require rejecting 0-RTT (see Section 4.2.9). 1797 There are subtle (and not so subtle) interactions that may occur in 1798 this protocol between new features and existing features which may 1799 result in a significant reduction in overall security. The following 1800 considerations should be taken into account when designing new 1801 extensions: 1803 - Some cases where a server does not agree to an extension are error 1804 conditions, and some are simply refusals to support particular 1805 features. In general, error alerts should be used for the former, 1806 and a field in the server extension response for the latter. 1808 - Extensions should, as far as possible, be designed to prevent any 1809 attack that forces use (or non-use) of a particular feature by 1810 manipulation of handshake messages. This principle should be 1811 followed regardless of whether the feature is believed to cause a 1812 security problem. Often the fact that the extension fields are 1813 included in the inputs to the Finished message hashes will be 1814 sufficient, but extreme care is needed when the extension changes 1815 the meaning of messages sent in the handshake phase. Designers 1816 and implementors should be aware of the fact that until the 1817 handshake has been authenticated, active attackers can modify 1818 messages and insert, remove, or replace extensions. 1820 4.2.1. Supported Versions 1822 struct { 1823 ProtocolVersion versions<2..254>; 1824 } SupportedVersions; 1826 The "supported_versions" extension is used by the client to indicate 1827 which versions of TLS it supports. The extension contains a list of 1828 supported versions in preference order, with the most preferred 1829 version first. Implementations of this specification MUST send this 1830 extension containing all versions of TLS which they are prepared to 1831 negotiate (for this specification, that means minimally 0x0304, but 1832 if previous versions of TLS are supported, they MUST be present as 1833 well). 1835 If this extension is not present, servers which are compliant with 1836 this specification MUST negotiate TLS 1.2 or prior as specified in 1837 [RFC5246], even if ClientHello.legacy_version is 0x0304 or later. 1838 Servers MAY abort the handshake upon receiving a ClientHello with 1839 legacy_version 0x0304 or later. 1841 If this extension is present, servers MUST ignore the 1842 ClientHello.legacy_version value and MUST use only the 1843 "supported_versions" extension to determine client preferences. 1844 Servers MUST only select a version of TLS present in that extension 1845 and MUST ignore any unknown versions that are present in that 1846 extension. Note that this mechanism makes it possible to negotiate a 1847 version prior to TLS 1.2 if one side supports a sparse range. 1848 Implementations of TLS 1.3 which choose to support prior versions of 1849 TLS SHOULD support TLS 1.2. Servers should be prepared to receive 1850 ClientHellos that include this extension but do not include 0x0304 in 1851 the list of versions. 1853 The server MUST NOT send the "supported_versions" extension. The 1854 server's selected version is contained in the ServerHello.version 1855 field as in previous versions of TLS. 1857 4.2.1.1. Draft Version Indicator 1859 RFC EDITOR: PLEASE REMOVE THIS SECTION 1861 While the eventual version indicator for the RFC version of TLS 1.3 1862 will be 0x0304, implementations of draft versions of this 1863 specification SHOULD instead advertise 0x7f00 | draft_version in 1864 ServerHello.version, and HelloRetryRequest.server_version. For 1865 instance, draft-17 would be encoded as the 0x7f11. This allows pre- 1866 RFC implementations to safely negotiate with each other, even if they 1867 would otherwise be incompatible. 1869 4.2.2. Cookie 1871 struct { 1872 opaque cookie<1..2^16-1>; 1873 } Cookie; 1875 Cookies serve two primary purposes: 1877 - Allowing the server to force the client to demonstrate 1878 reachability at their apparent network address (thus providing a 1879 measure of DoS protection). This is primarily useful for non- 1880 connection-oriented transports (see [RFC6347] for an example of 1881 this). 1883 - Allowing the server to offload state to the client, thus allowing 1884 it to send a HelloRetryRequest without storing any state. The 1885 server can do this by storing the hash of the ClientHello in the 1886 HelloRetryRequest cookie (protected with some suitable integrity 1887 algorithm). 1889 When sending a HelloRetryRequest, the server MAY provide a "cookie" 1890 extension to the client (this is an exception to the usual rule that 1891 the only extensions that may be sent are those that appear in the 1892 ClientHello). When sending the new ClientHello, the client MUST copy 1893 the contents of the extension received in the HelloRetryRequest into 1894 a "cookie" extension in the new ClientHello. Clients MUST NOT use 1895 cookies in subsequent connections. 1897 4.2.3. Signature Algorithms 1899 The client uses the "signature_algorithms" extension to indicate to 1900 the server which signature algorithms may be used in digital 1901 signatures. Clients which desire the server to authenticate itself 1902 via a certificate MUST send this extension. If a server is 1903 authenticating via a certificate and the client has not sent a 1904 "signature_algorithms" extension, then the server MUST abort the 1905 handshake with a "missing_extension" alert (see Section 8.2). 1907 The "extension_data" field of this extension in a ClientHello 1908 contains a SignatureSchemeList value: 1910 enum { 1911 /* RSASSA-PKCS1-v1_5 algorithms */ 1912 rsa_pkcs1_sha256(0x0401), 1913 rsa_pkcs1_sha384(0x0501), 1914 rsa_pkcs1_sha512(0x0601), 1916 /* ECDSA algorithms */ 1917 ecdsa_secp256r1_sha256(0x0403), 1918 ecdsa_secp384r1_sha384(0x0503), 1919 ecdsa_secp521r1_sha512(0x0603), 1921 /* RSASSA-PSS algorithms */ 1922 rsa_pss_sha256(0x0804), 1923 rsa_pss_sha384(0x0805), 1924 rsa_pss_sha512(0x0806), 1926 /* EdDSA algorithms */ 1927 ed25519(0x0807), 1928 ed448(0x0808), 1930 /* Legacy algorithms */ 1931 rsa_pkcs1_sha1(0x0201), 1932 ecdsa_sha1(0x0203), 1934 /* Reserved Code Points */ 1935 private_use(0xFE00..0xFFFF), 1936 (0xFFFF) 1937 } SignatureScheme; 1939 struct { 1940 SignatureScheme supported_signature_algorithms<2..2^16-2>; 1941 } SignatureSchemeList; 1943 Note: This enum is named "SignatureScheme" because there is already a 1944 "SignatureAlgorithm" type in TLS 1.2, which this replaces. We use 1945 the term "signature algorithm" throughout the text. 1947 Each SignatureScheme value lists a single signature algorithm that 1948 the client is willing to verify. The values are indicated in 1949 descending order of preference. Note that a signature algorithm 1950 takes as input an arbitrary-length message, rather than a digest. 1951 Algorithms which traditionally act on a digest should be defined in 1952 TLS to first hash the input with a specified hash algorithm and then 1953 proceed as usual. The code point groups listed above have the 1954 following meanings: 1956 RSASSA-PKCS1-v1_5 algorithms Indicates a signature algorithm using 1957 RSASSA-PKCS1-v1_5 [RFC8017] with the corresponding hash algorithm 1958 as defined in [SHS]. These values refer solely to signatures 1959 which appear in certificates (see Section 4.4.2.2) and are not 1960 defined for use in signed TLS handshake messages. 1962 ECDSA algorithms Indicates a signature algorithm using ECDSA 1963 [ECDSA], the corresponding curve as defined in ANSI X9.62 [X962] 1964 and FIPS 186-4 [DSS], and the corresponding hash algorithm as 1965 defined in [SHS]. The signature is represented as a DER-encoded 1966 [X690] ECDSA-Sig-Value structure. 1968 RSASSA-PSS algorithms Indicates a signature algorithm using RSASSA- 1969 PSS [RFC8017] with mask generation function 1. The digest used in 1970 the mask generation function and the digest being signed are both 1971 the corresponding hash algorithm as defined in [SHS]. When used 1972 in signed TLS handshake messages, the length of the salt MUST be 1973 equal to the length of the digest output. This codepoint is new 1974 in this document and is also defined for use with TLS 1.2. 1976 EdDSA algorithms Indicates a signature algorithm using EdDSA as 1977 defined in [RFC8032] or its successors. Note that these 1978 correspond to the "PureEdDSA" algorithms and not the "prehash" 1979 variants. 1981 Legacy algorithms Indicates algorithms which are being deprecated 1982 because they use algorithms with known weaknesses, specifically 1983 SHA-1 which is used in this context with either with RSA using 1984 RSASSA-PKCS1-v1_5 or ECDSA. These values refer solely to 1985 signatures which appear in certificates (see Section 4.4.2.2) and 1986 are not defined for use in signed TLS handshake messages. 1987 Endpoints SHOULD NOT negotiate these algorithms but are permitted 1988 to do so solely for backward compatibility. Clients offering 1989 these values MUST list them as the lowest priority (listed after 1990 all other algorithms in SignatureSchemeList). TLS 1.3 servers 1991 MUST NOT offer a SHA-1 signed certificate unless no valid 1992 certificate chain can be produced without it (see 1993 Section 4.4.2.2). 1995 The signatures on certificates that are self-signed or certificates 1996 that are trust anchors are not validated since they begin a 1997 certification path (see [RFC5280], Section 3.2). A certificate that 1998 begins a certification path MAY use a signature algorithm that is not 1999 advertised as being supported in the "signature_algorithms" 2000 extension. 2002 Note that TLS 1.2 defines this extension differently. TLS 1.3 2003 implementations willing to negotiate TLS 1.2 MUST behave in 2004 accordance with the requirements of [RFC5246] when negotiating that 2005 version. In particular: 2007 - TLS 1.2 ClientHellos MAY omit this extension. 2009 - In TLS 1.2, the extension contained hash/signature pairs. The 2010 pairs are encoded in two octets, so SignatureScheme values have 2011 been allocated to align with TLS 1.2's encoding. Some legacy 2012 pairs are left unallocated. These algorithms are deprecated as of 2013 TLS 1.3. They MUST NOT be offered or negotiated by any 2014 implementation. In particular, MD5 [SLOTH], SHA-224, and DSA MUST 2015 NOT be used. 2017 - ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature 2018 pairs. However, the old semantics did not constrain the signing 2019 curve. If TLS 1.2 is negotiated, implementations MUST be prepared 2020 to accept a signature that uses any curve that they advertised in 2021 the "supported_groups" extension. 2023 - Implementations that advertise support for RSASSA-PSS (which is 2024 mandatory in TLS 1.3), MUST be prepared to accept a signature 2025 using that scheme even when TLS 1.2 is negotiated. In TLS 1.2, 2026 RSASSA-PSS is used with RSA cipher suites. 2028 4.2.4. Certificate Authorities 2030 The "certificate_authorities" extension is used to indicate the 2031 certificate authorities which an endpoint supports and which SHOULD 2032 be used by the receiving endpoint to guide certificate selection. 2034 The body of the "certificate_authorities" extension consists of a 2035 CertificateAuthoritiesExtension structure. 2037 opaque DistinguishedName<1..2^16-1>; 2039 struct { 2040 DistinguishedName authorities<3..2^16-1>; 2041 } CertificateAuthoritiesExtension; 2043 authorities A list of the distinguished names [X501] of acceptable 2044 certificate authorities, represented in DER-encoded [X690] format. 2045 These distinguished names specify a desired distinguished name for 2046 trust anchor or subordinate CA; thus, this message can be used to 2047 describe known trust anchors as well as a desired authorization 2048 space. 2050 The client MAY send the "certificate_authorities" extension in the 2051 ClientHello message. The server MAY send it in the 2052 CertificateRequest message. 2054 The "trusted_ca_keys" extension, which serves a similar purpose 2055 [RFC6066], but is more complicated, is not used in TLS 1.3 (although 2056 it may appear in ClientHello messages from clients which are offering 2057 prior versions of TLS). 2059 4.2.5. Post-Handshake Client Authentication 2061 The "post_handshake_auth" extension is used to indicate that a client 2062 is willing to perform post-handshake authentication Section 4.6.2. 2063 Servers MUST not send a post-handshake CertificateRequest to clients 2064 which do not offer this extension. Servers MUST NOT send this 2065 extension. 2067 The "extension_data" field of the "post_handshake_auth" extension is 2068 zero length. 2070 4.2.6. Negotiated Groups 2072 When sent by the client, the "supported_groups" extension indicates 2073 the named groups which the client supports for key exchange, ordered 2074 from most preferred to least preferred. 2076 Note: In versions of TLS prior to TLS 1.3, this extension was named 2077 "elliptic_curves" and only contained elliptic curve groups. See 2078 [RFC4492] and [RFC7919]. This extension was also used to negotiate 2079 ECDSA curves. Signature algorithms are now negotiated independently 2080 (see Section 4.2.3). 2082 The "extension_data" field of this extension contains a 2083 "NamedGroupList" value: 2085 enum { 2086 /* Elliptic Curve Groups (ECDHE) */ 2087 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 2088 x25519(0x001D), x448(0x001E), 2090 /* Finite Field Groups (DHE) */ 2091 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096 (0x0102), 2092 ffdhe6144(0x0103), ffdhe8192(0x0104), 2094 /* Reserved Code Points */ 2095 ffdhe_private_use(0x01FC..0x01FF), 2096 ecdhe_private_use(0xFE00..0xFEFF), 2097 (0xFFFF) 2098 } NamedGroup; 2100 struct { 2101 NamedGroup named_group_list<2..2^16-1>; 2102 } NamedGroupList; 2104 Elliptic Curve Groups (ECDHE) Indicates support for the 2105 corresponding named curve, defined either in FIPS 186-4 [DSS] or 2106 in [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for 2107 private use. 2109 Finite Field Groups (DHE) Indicates support of the corresponding 2110 finite field group, defined in [RFC7919]. Values 0x01FC through 2111 0x01FF are reserved for private use. 2113 Items in named_group_list are ordered according to the client's 2114 preferences (most preferred choice first). 2116 As of TLS 1.3, servers are permitted to send the "supported_groups" 2117 extension to the client. If the server has a group it prefers to the 2118 ones in the "key_share" extension but is still willing to accept the 2119 ClientHello, it SHOULD send "supported_groups" to update the client's 2120 view of its preferences; this extension SHOULD contain all groups the 2121 server supports, regardless of whether they are currently supported 2122 by the client. Clients MUST NOT act upon any information found in 2123 "supported_groups" prior to successful completion of the handshake, 2124 but MAY use the information learned from a successfully completed 2125 handshake to change what groups they use in their "key_share" 2126 extension in subsequent connections. 2128 4.2.7. Key Share 2130 The "key_share" extension contains the endpoint's cryptographic 2131 parameters. 2133 Clients MAY send an empty client_shares vector in order to request 2134 group selection from the server at the cost of an additional round 2135 trip. (see Section 4.1.4) 2137 struct { 2138 NamedGroup group; 2139 opaque key_exchange<1..2^16-1>; 2140 } KeyShareEntry; 2142 group The named group for the key being exchanged. Finite Field 2143 Diffie-Hellman [DH] parameters are described in Section 4.2.7.1; 2144 Elliptic Curve Diffie-Hellman parameters are described in 2145 Section 4.2.7.2. 2147 key_exchange Key exchange information. The contents of this field 2148 are determined by the specified group and its corresponding 2149 definition. 2151 The "extension_data" field of this extension contains a "KeyShare" 2152 value: 2154 struct { 2155 select (Handshake.msg_type) { 2156 case client_hello: 2157 KeyShareEntry client_shares<0..2^16-1>; 2159 case hello_retry_request: 2160 NamedGroup selected_group; 2162 case server_hello: 2163 KeyShareEntry server_share; 2164 }; 2165 } KeyShare; 2167 client_shares A list of offered KeyShareEntry values in descending 2168 order of client preference. This vector MAY be empty if the 2169 client is requesting a HelloRetryRequest. Each KeyShareEntry 2170 value MUST correspond to a group offered in the "supported_groups" 2171 extension and MUST appear in the same order. However, the values 2172 MAY be a non-contiguous subset of the "supported_groups" extension 2173 and MAY omit the most preferred groups. Such a situation could 2174 arise if the most preferred groups are new and unlikely to be 2175 supported in enough places to make pregenerating key shares for 2176 them efficient. 2178 selected_group The mutually supported group the server intends to 2179 negotiate and is requesting a retried ClientHello/KeyShare for. 2181 server_share A single KeyShareEntry value that is in the same group 2182 as one of the client's shares. 2184 Clients offer an arbitrary number of KeyShareEntry values, each 2185 representing a single set of key exchange parameters. For instance, 2186 a client might offer shares for several elliptic curves or multiple 2187 FFDHE groups. The key_exchange values for each KeyShareEntry MUST be 2188 generated independently. Clients MUST NOT offer multiple 2189 KeyShareEntry values for the same group. Clients MUST NOT offer any 2190 KeyShareEntry values for groups not listed in the client's 2191 "supported_groups" extension. Servers MAY check for violations of 2192 these rules and abort the handshake with an "illegal_parameter" alert 2193 if one is violated. 2195 Upon receipt of this extension in a HelloRetryRequest, the client 2196 MUST verify that (1) the selected_group field corresponds to a group 2197 which was provided in the "supported_groups" extension in the 2198 original ClientHello; and (2) the selected_group field does not 2199 correspond to a group which was provided in the "key_share" extension 2200 in the original ClientHello. If either of these checks fails, then 2201 the client MUST abort the handshake with an "illegal_parameter" 2202 alert. Otherwise, when sending the new ClientHello, the client MUST 2203 replace the original "key_share" extension with one containing only a 2204 new KeyShareEntry for the group indicated in the selected_group field 2205 of the triggering HelloRetryRequest. 2207 If using (EC)DHE key establishment, servers offer exactly one 2208 KeyShareEntry in the ServerHello. This value MUST be in the same 2209 group as the KeyShareEntry value offered by the client that the 2210 server has selected for the negotiated key exchange. Servers MUST 2211 NOT send a KeyShareEntry for any group not indicated in the 2212 "supported_groups" extension and MUST NOT send a KeyShareEntry when 2213 using the "psk_ke" PskKeyExchangeMode. If a HelloRetryRequest was 2214 received by the client, the client MUST verify that the selected 2215 NamedGroup in the ServerHello is the same as that in the 2216 HelloRetryRequest. If this check fails, the client MUST abort the 2217 handshake with an "illegal_parameter" alert. 2219 4.2.7.1. Diffie-Hellman Parameters 2221 Diffie-Hellman [DH] parameters for both clients and servers are 2222 encoded in the opaque key_exchange field of a KeyShareEntry in a 2223 KeyShare structure. The opaque value contains the Diffie-Hellman 2224 public value (Y = g^X mod p) for the specified group (see [RFC7919] 2225 for group definitions) encoded as a big-endian integer and padded to 2226 the left with zeros to the size of p in bytes. 2228 Note: For a given Diffie-Hellman group, the padding results in all 2229 public keys having the same length. 2231 Peers MUST validate each other's public key Y by ensuring that 1 < Y 2232 < p-1. This check ensures that the remote peer is properly behaved 2233 and isn't forcing the local system into a small subgroup. 2235 4.2.7.2. ECDHE Parameters 2237 ECDHE parameters for both clients and servers are encoded in the the 2238 opaque key_exchange field of a KeyShareEntry in a KeyShare structure. 2240 For secp256r1, secp384r1 and secp521r1, the contents are the 2241 serialized value of the following struct: 2243 struct { 2244 uint8 legacy_form = 4; 2245 opaque X[coordinate_length]; 2246 opaque Y[coordinate_length]; 2247 } UncompressedPointRepresentation; 2249 X and Y respectively are the binary representations of the X and Y 2250 values in network byte order. There are no internal length markers, 2251 so each number representation occupies as many octets as implied by 2252 the curve parameters. For P-256 this means that each of X and Y use 2253 32 octets, padded on the left by zeros if necessary. For P-384 they 2254 take 48 octets each, and for P-521 they take 66 octets each. 2256 For the curves secp256r1, secp384r1 and secp521r1, peers MUST 2257 validate each other's public value Y by ensuring that the point is a 2258 valid point on the elliptic curve. The appropriate validation 2259 procedures are defined in Section 4.3.7 of [X962] and alternatively 2260 in Section 5.6.2.6 of [KEYAGREEMENT]. This process consists of three 2261 steps: (1) verify that Y is not the point at infinity (O), (2) verify 2262 that for Y = (x, y) both integers are in the correct interval, (3) 2263 ensure that (x, y) is a correct solution to the elliptic curve 2264 equation. For these curves, implementers do not need to verify 2265 membership in the correct subgroup. 2267 For X25519 and X448, the contents of the public value are the byte 2268 string inputs and outputs of the corresponding functions defined in 2269 [RFC7748], 32 bytes for X25519 and 56 bytes for X448. 2271 Note: Versions of TLS prior to 1.3 permitted point format 2272 negotiation; TLS 1.3 removes this feature in favor of a single point 2273 format for each curve. 2275 4.2.8. Pre-Shared Key Exchange Modes 2277 In order to use PSKs, clients MUST also send a 2278 "psk_key_exchange_modes" extension. The semantics of this extension 2279 are that the client only supports the use of PSKs with these modes, 2280 which restricts both the use of PSKs offered in this ClientHello and 2281 those which the server might supply via NewSessionTicket. 2283 A client MUST provide a "psk_key_exchange_modes" extension if it 2284 offers a "pre_shared_key" extension. If clients offer 2285 "pre_shared_key" without a "psk_key_exchange_modes" extension, 2286 servers MUST abort the handshake. Servers MUST NOT select a key 2287 exchange mode that is not listed by the client. This extension also 2288 restricts the modes for use with PSK resumption; servers SHOULD NOT 2289 send NewSessionTicket with tickets that are not compatible with the 2290 advertised modes; however, if a server does so, the impact will just 2291 be that the client's attempts at resumption fail. 2293 The server MUST NOT send a "psk_key_exchange_modes" extension. 2295 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 2297 struct { 2298 PskKeyExchangeMode ke_modes<1..255>; 2299 } PskKeyExchangeModes; 2301 psk_ke PSK-only key establishment. In this mode, the server MUST 2302 NOT supply a "key_share" value. 2304 psk_dhe_ke PSK with (EC)DHE key establishment. In this mode, the 2305 client and servers MUST supply "key_share" values as described in 2306 Section 4.2.7. 2308 4.2.9. Early Data Indication 2310 When a PSK is used, the client can send application data in its first 2311 flight of messages. If the client opts to do so, it MUST supply an 2312 "early_data" extension as well as the "pre_shared_key" extension. 2314 The "extension_data" field of this extension contains an 2315 "EarlyDataIndication" value. 2317 struct {} Empty; 2319 struct { 2320 select (Handshake.msg_type) { 2321 case new_session_ticket: uint32 max_early_data_size; 2322 case client_hello: Empty; 2323 case encrypted_extensions: Empty; 2324 }; 2325 } EarlyDataIndication; 2327 See Section 4.6.1 for the use of the max_early_data_size field. 2329 The parameters for the 0-RTT data (symmetric cipher suite, ALPN 2330 protocol, etc.) are the same as those which were negotiated in the 2331 connection which established the PSK. The PSK used to encrypt the 2332 early data MUST be the first PSK listed in the client's 2333 "pre_shared_key" extension. 2335 For PSKs provisioned via NewSessionTicket, a server MUST validate 2336 that the ticket age for the selected PSK identity (computed by 2337 subtracting ticket_age_add from PskIdentity.obfuscated_ticket_age 2338 modulo 2^32) is within a small tolerance of the time since the ticket 2339 was issued (see Section 4.2.10.4). If it is not, the server SHOULD 2340 proceed with the handshake but reject 0-RTT, and SHOULD NOT take any 2341 other action that assumes that this ClientHello is fresh. 2343 0-RTT messages sent in the first flight have the same (encrypted) 2344 content types as their corresponding messages sent in other flights 2345 (handshake and application_data) but are protected under different 2346 keys. After receiving the server's Finished message, if the server 2347 has accepted early data, an EndOfEarlyData message will be sent to 2348 indicate the key change. This message will be encrypted with the 2349 0-RTT traffic keys. 2351 A server which receives an "early_data" extension MUST behave in one 2352 of three ways: 2354 - Ignore the extension and return a regular 1-RTT response. The 2355 server then ignores early data by attempting to decrypt received 2356 records in the handshake traffic keys until it is able to receive 2357 the client's second flight and complete an ordinary 1-RTT 2358 handshake, skipping records that fail to decrypt, up to the 2359 configured max_early_data_size. 2361 - Request that the client send another ClientHello by responding 2362 with a HelloRetryRequest. A client MUST NOT include the 2363 "early_data" extension in its followup ClientHello. The server 2364 then ignores early data by skipping all records with external 2365 content type of "application_data" (indicating that they are 2366 encrypted). 2368 - Return its own extension in EncryptedExtensions, indicating that 2369 it intends to process the early data. It is not possible for the 2370 server to accept only a subset of the early data messages. Even 2371 though the server sends a message accepting early data, the actual 2372 early data itself may already be in flight by the time the server 2373 generates this message. 2375 In order to accept early data, the server MUST have accepted a PSK 2376 cipher suite and selected the first key offered in the client's 2377 "pre_shared_key" extension. In addition, it MUST verify that the 2378 following values are consistent with those negotiated in the 2379 connection during which the ticket was established. 2381 - The TLS version number and cipher suite. 2383 - The selected ALPN [RFC7301] protocol, if any. 2385 Future extensions MUST define their interaction with 0-RTT. 2387 If any of these checks fail, the server MUST NOT respond with the 2388 extension and must discard all the first flight data using one of the 2389 first two mechanisms listed above (thus falling back to 1-RTT or 2390 2-RTT). If the client attempts a 0-RTT handshake but the server 2391 rejects it, the server will generally not have the 0-RTT record 2392 protection keys and must instead use trial decryption (either with 2393 the 1-RTT handshake keys or by looking for a cleartext ClientHello in 2394 the case of HelloRetryRequest) to find the first non-0RTT message. 2396 If the server chooses to accept the "early_data" extension, then it 2397 MUST comply with the same error handling requirements specified for 2398 all records when processing early data records. Specifically, if the 2399 server fails to decrypt any 0-RTT record following an accepted 2400 "early_data" extension it MUST terminate the connection with a 2401 "bad_record_mac" alert as per Section 5.2. 2403 If the server rejects the "early_data" extension, the client 2404 application MAY opt to retransmit early data once the handshake has 2405 been completed. Note that automatic re-transmission of early data 2406 could result in assumptions about the status of the connection being 2407 incorrect. For instance, when the negotiated connection selects a 2408 different ALPN protocol from what was used for the early data, an 2409 application might need to construct different messages. Similarly, 2410 if early data assumes anything about the connection state, it might 2411 be sent in error after the handshake completes. 2413 A TLS implementation SHOULD NOT automatically re-send early data; 2414 applications are in a better position to decide when re-transmission 2415 is appropriate. A TLS implementation MUST NOT automatically re-send 2416 early data unless the negotiated connection selects the same ALPN 2417 protocol. 2419 4.2.10. Pre-Shared Key Extension 2421 The "pre_shared_key" extension is used to indicate the identity of 2422 the pre-shared key to be used with a given handshake in association 2423 with PSK key establishment. 2425 The "extension_data" field of this extension contains a 2426 "PreSharedKeyExtension" value: 2428 struct { 2429 opaque identity<1..2^16-1>; 2430 uint32 obfuscated_ticket_age; 2431 } PskIdentity; 2433 opaque PskBinderEntry<32..255>; 2435 struct { 2436 select (Handshake.msg_type) { 2437 case client_hello: 2438 PskIdentity identities<7..2^16-1>; 2439 PskBinderEntry binders<33..2^16-1>; 2441 case server_hello: 2442 uint16 selected_identity; 2443 }; 2445 } PreSharedKeyExtension; 2447 identity A label for a key. For instance, a ticket defined in 2448 Appendix B.3.4, or a label for a pre-shared key established 2449 externally. 2451 obfuscated_ticket_age An obfuscated version of the age of the key. 2452 Section 4.2.10.1 describes how to form this value for identities 2453 established via the NewSessionTicket message. For identities 2454 established externally an obfuscated_ticket_age of 0 SHOULD be 2455 used, and servers MUST ignore the value. 2457 identities A list of the identities that the client is willing to 2458 negotiate with the server. If sent alongside the "early_data" 2459 extension (see Section 4.2.9), the first identity is the one used 2460 for 0-RTT data. 2462 binders A series of HMAC values, one for each PSK offered in the 2463 "pre_shared_keys" extension and in the same order, computed as 2464 described below. 2466 selected_identity The server's chosen identity expressed as a 2467 (0-based) index into the identities in the client's list. 2469 Each PSK is associated with a single Hash algorithm. For PSKs 2470 established via the ticket mechanism (Section 4.6.1), this is the 2471 Hash used for the KDF on the connection where the ticket was 2472 established. For externally established PSKs, the Hash algorithm 2473 MUST be set when the PSK is established, or default to SHA-256 if no 2474 such algorithm is defined. The server must ensure that it selects a 2475 compatible PSK (if any) and cipher suite. 2477 Implementor's note: the most straightforward way to implement the 2478 PSK/cipher suite matching requirements is to negotiate the cipher 2479 suite first and then exclude any incompatible PSKs. Any unknown PSKs 2480 (e.g., they are not in the PSK database or are encrypted with an 2481 unknown key) SHOULD simply be ignored. If no acceptable PSKs are 2482 found, the server SHOULD perform a non-PSK handshake if possible. 2484 Prior to accepting PSK key establishment, the server MUST validate 2485 the corresponding binder value (see Section 4.2.10.2 below). If this 2486 value is not present or does not validate, the server MUST abort the 2487 handshake. Servers SHOULD NOT attempt to validate multiple binders; 2488 rather they SHOULD select a single PSK and validate solely the binder 2489 that corresponds to that PSK. In order to accept PSK key 2490 establishment, the server sends a "pre_shared_key" extension 2491 indicating the selected identity. 2493 Clients MUST verify that the server's selected_identity is within the 2494 range supplied by the client, that the server selected a cipher suite 2495 indicating a Hash associated with the PSK and that a server 2496 "key_share" extension is present if required by the ClientHello 2497 "psk_key_exchange_modes". If these values are not consistent the 2498 client MUST abort the handshake with an "illegal_parameter" alert. 2500 If the server supplies an "early_data" extension, the client MUST 2501 verify that the server's selected_identity is 0. If any other value 2502 is returned, the client MUST abort the handshake with an 2503 "illegal_parameter" alert. 2505 This extension MUST be the last extension in the ClientHello (this 2506 facilitates implementation as described below). Servers MUST check 2507 that it is the last extension and otherwise fail the handshake with 2508 an "illegal_parameter" alert. 2510 4.2.10.1. Ticket Age 2512 The client's view of the age of a ticket is the time since the 2513 receipt of the NewSessionTicket message. Clients MUST NOT attempt to 2514 use tickets which have ages greater than the "ticket_lifetime" value 2515 which was provided with the ticket. The "obfuscated_ticket_age" 2516 field of each PskIdentity contains an obfuscated version of the 2517 ticket age formed by taking the age in milliseconds and adding the 2518 "ticket_age_add" value that was included with the ticket, see 2519 Section 4.6.1 modulo 2^32. This addition prevents passive observers 2520 from correlating connections unless tickets are reused. Note that 2521 the "ticket_lifetime" field in the NewSessionTicket message is in 2522 seconds but the "obfuscated_ticket_age" is in milliseconds. Because 2523 ticket lifetimes are restricted to a week, 32 bits is enough to 2524 represent any plausible age, even in milliseconds. 2526 4.2.10.2. PSK Binder 2528 The PSK binder value forms a binding between a PSK and the current 2529 handshake, as well as between the handshake in which the PSK was 2530 generated (if via a NewSessionTicket message) and the handshake where 2531 it was used. Each entry in the binders list is computed as an HMAC 2532 over a transcript hash (see Section 4.4.1) containing a partial 2533 ClientHello up to and including the PreSharedKeyExtension.identities 2534 field. That is, it includes all of the ClientHello but not the 2535 binders list itself. The length fields for the message (including 2536 the overall length, the length of the extensions block, and the 2537 length of the "pre_shared_key" extension) are all set as if binders 2538 of the correct lengths were present. 2540 The PskBinderEntry is computed in the same way as the Finished 2541 message (Section 4.4.4) but with the BaseKey being the binder_key 2542 derived via the key schedule from the corresponding PSK which is 2543 being offered (see Section 7.1). 2545 If the handshake includes a HelloRetryRequest, the initial 2546 ClientHello and HelloRetryRequest are included in the transcript 2547 along with the new ClientHello. For instance, if the client sends 2548 ClientHello1, its binder will be computed over: 2550 Transcript-Hash(ClientHello1[truncated]) 2552 If the server responds with HelloRetryRequest, and the client then 2553 sends ClientHello2, its binder will be computed over: 2555 Transcript-Hash(ClientHello1, 2556 HelloRetryRequest, 2557 ClientHello2[truncated]) 2559 The full ClientHello1 is included in all other handshake hash 2560 computations. Note that in the first flight, ClientHello1[truncated] 2561 is hashed directly, but in the second flight, ClientHello1 is hashed 2562 and then reinjected as a "handshake_hash" message, as described in 2563 Section 4.4.1. 2565 4.2.10.3. Processing Order 2567 Clients are permitted to "stream" 0-RTT data until they receive the 2568 server's Finished, only then sending the EndOfEarlyData message. In 2569 order to avoid deadlocks, when accepting "early_data", servers MUST 2570 process the client's ClientHello and then immediately send the 2571 ServerHello, rather than waiting for the client's EndOfEarlyData 2572 message. 2574 4.2.10.4. Replay Properties 2576 As noted in Section 2.3, TLS provides a limited mechanism for replay 2577 protection for data sent by the client in the first flight. This 2578 mechanism is intended to ensure that attackers cannot replay 2579 ClientHello messages at a time substantially after the original 2580 ClientHello was sent. 2582 To properly validate the ticket age, a server needs to store the 2583 following values, either locally or by encoding them in the ticket: 2585 - The time that the server generated the session ticket. 2587 - The estimated round trip time between the client and server; this 2588 can be estimated by measuring the time between sending the 2589 Finished message and receiving the first message in the client's 2590 second flight, or potentially using information from the operating 2591 system. 2593 - The "ticket_age_add" parameter from the NewSessionTicket message 2594 in which the ticket was established. 2596 The server can determine the client's view of the age of the ticket 2597 by subtracting the ticket's "ticket_age_add value" from the 2598 "obfuscated_ticket_age" parameter in the client's "pre_shared_key" 2599 extension. The server can independently determine its view of the 2600 age of the ticket by subtracting the the time the ticket was issued 2601 from the current time. If the client and server clocks were running 2602 at the same rate, the client's view of would be shorter than the 2603 actual time elapsed on the server by a single round trip time. This 2604 difference is comprised of the delay in sending the NewSessionTicket 2605 message to the client, plus the time taken to send the ClientHello to 2606 the server. 2608 The mismatch between the client's and server's views of age is thus 2609 given by: 2611 mismatch = (client's view + RTT estimate) - (server's view) 2613 There are several potential sources of error that make an exact 2614 measurement of time difficult. Variations in client and server clock 2615 rates are likely to be minimal, though potentially with gross time 2616 corrections. Network propagation delays are the most likely causes 2617 of a mismatch in legitimate values for elapsed time. Both the 2618 NewSessionTicket and ClientHello messages might be retransmitted and 2619 therefore delayed, which might be hidden by TCP. For browser clients 2620 on the Internet, this implies that an allowance on the order of ten 2621 seconds to account for errors in clocks and variations in 2622 measurements is advisable; other deployment scenarios may have 2623 different needs. Outside the selected range, the server SHOULD 2624 reject early data and fall back to a full 1-RTT handshake. Clock 2625 skew distributions are not symmetric, so the optimal tradeoff may 2626 involve an asymmetric range of permissible mismatch values. 2628 4.3. Server Parameters 2630 The next two messages from the server, EncryptedExtensions and 2631 CertificateRequest, contain information from the server that 2632 determines the rest of the handshake. These messages are encrypted 2633 with keys derived from the server_handshake_traffic_secret. 2635 4.3.1. Encrypted Extensions 2637 In all handshakes, the server MUST send the EncryptedExtensions 2638 message immediately after the ServerHello message. This is the first 2639 message that is encrypted under keys derived from the 2640 server_handshake_traffic_secret. 2642 The EncryptedExtensions message contains extensions that can be 2643 protected, i.e., any which are not needed to establish the 2644 cryptographic context, but which are not associated with individual 2645 certificates. The client MUST check EncryptedExtensions for the 2646 presence of any forbidden extensions and if any are found MUST abort 2647 the handshake with an "illegal_parameter" alert. 2649 Structure of this message: 2651 struct { 2652 Extension extensions<0..2^16-1>; 2653 } EncryptedExtensions; 2655 extensions A list of extensions. For more information, see the 2656 table in Section 4.2. 2658 4.3.2. Certificate Request 2660 A server which is authenticating with a certificate MAY optionally 2661 request a certificate from the client. This message, if sent, MUST 2662 follow EncryptedExtensions. 2664 Structure of this message: 2666 struct { 2667 opaque certificate_request_context<0..2^8-1>; 2668 Extension extensions<2..2^16-1>; 2669 } CertificateRequest; 2671 certificate_request_context An opaque string which identifies the 2672 certificate request and which will be echoed in the client's 2673 Certificate message. The certificate_request_context MUST be 2674 unique within the scope of this connection (thus preventing replay 2675 of client CertificateVerify messages). This field SHALL be zero 2676 length unless used for the post-handshake authentication exchanges 2677 described in Section 4.6.2. When requesting post-handshake 2678 authentication, the server SHOULD make the context unpredictable 2679 to the client (e.g., by randomly generating it) in order to 2680 prevent an attacker who has temporary access to the client's 2681 private key from pre-computing valid CertificateVerify messages. 2683 extensions A set of extensions describing the parameters of the 2684 certificate being requested. The "signature_algorithms" extension 2685 MUST be specified, and other extensions may optionally be included 2686 if defined for this message. Clients MUST ignore unrecognized 2687 extensions. 2689 In prior versions of TLS, the CertificateRequest message carried a 2690 list of signature algorithms and certificate authorities which the 2691 server would accept. In TLS 1.3 the former is expressed by sending 2692 the "signature_algorithms" extension. The latter is expressed by 2693 sending the "certificate_authorities" extension (see Section 4.2.4). 2695 Servers which are authenticating with a PSK MUST NOT send the 2696 CertificateRequest message in the main handshake, though they MAY 2697 send it in post-handshake authentication (see Section 4.6.2) provided 2698 that the client has sent the "post_handshake_auth" extension (see 2699 Section 4.2.5). 2701 4.3.2.1. OID Filters 2703 The "oid_filters" extension allows servers to provide a set of OID/ 2704 value pairs which it would like the client's certificate to match. 2705 This extension MUST only be sent in the CertificateRequest message. 2707 struct { 2708 opaque certificate_extension_oid<1..2^8-1>; 2709 opaque certificate_extension_values<0..2^16-1>; 2710 } OIDFilter; 2712 struct { 2713 OIDFilter filters<0..2^16-1>; 2714 } OIDFilterExtension; 2716 filters A list of certificate extension OIDs [RFC5280] with their 2717 allowed values, represented in DER-encoded [X690] format. Some 2718 certificate extension OIDs allow multiple values (e.g., Extended 2719 Key Usage). If the server has included a non-empty 2720 certificate_extensions list, the client certificate included in 2721 the response MUST contain all of the specified extension OIDs that 2722 the client recognizes. For each extension OID recognized by the 2723 client, all of the specified values MUST be present in the client 2724 certificate (but the certificate MAY have other values as well). 2725 However, the client MUST ignore and skip any unrecognized 2726 certificate extension OIDs. If the client ignored some of the 2727 required certificate extension OIDs and supplied a certificate 2728 that does not satisfy the request, the server MAY at its 2729 discretion either continue the connection without client 2730 authentication, or abort the handshake with an 2731 "unsupported_certificate" alert. PKIX RFCs define a variety of 2732 certificate extension OIDs and their corresponding value types. 2733 Depending on the type, matching certificate extension values are 2734 not necessarily bitwise-equal. It is expected that TLS 2735 implementations will rely on their PKI libraries to perform 2736 certificate selection using certificate extension OIDs. This 2737 document defines matching rules for two standard certificate 2738 extensions defined in [RFC5280]: 2740 o The Key Usage extension in a certificate matches the request 2741 when all key usage bits asserted in the request are also 2742 asserted in the Key Usage certificate extension. 2744 o The Extended Key Usage extension in a certificate matches the 2745 request when all key purpose OIDs present in the request are 2746 also found in the Extended Key Usage certificate extension. 2747 The special anyExtendedKeyUsage OID MUST NOT be used in the 2748 request. 2750 Separate specifications may define matching rules for other 2751 certificate extensions. 2753 4.4. Authentication Messages 2755 As discussed in Section 2, TLS generally uses a common set of 2756 messages for authentication, key confirmation, and handshake 2757 integrity: Certificate, CertificateVerify, and Finished. (The 2758 PreSharedKey binders also perform key confirmation, in a similar 2759 fashion.) These three messages are always sent as the last messages 2760 in their handshake flight. The Certificate and CertificateVerify 2761 messages are only sent under certain circumstances, as defined below. 2762 The Finished message is always sent as part of the Authentication 2763 block. These messages are encrypted under keys derived from 2764 [sender]_handshake_traffic_secret. 2766 The computations for the Authentication messages all uniformly take 2767 the following inputs: 2769 - The certificate and signing key to be used. 2771 - A Handshake Context consisting of the set of messages to be 2772 included in the transcript hash. 2774 - A base key to be used to compute a MAC key. 2776 Based on these inputs, the messages then contain: 2778 Certificate The certificate to be used for authentication, and any 2779 supporting certificates in the chain. Note that certificate-based 2780 client authentication is not available in the 0-RTT case. 2782 CertificateVerify A signature over the value Transcript- 2783 Hash(Handshake Context, Certificate) 2785 Finished A MAC over the value Transcript-Hash(Handshake Context, 2786 Certificate, CertificateVerify) using a MAC key derived from the 2787 base key. 2789 The following table defines the Handshake Context and MAC Base Key 2790 for each scenario: 2792 +-----------+----------------------------+--------------------------+ 2793 | Mode | Handshake Context | Base Key | 2794 +-----------+----------------------------+--------------------------+ 2795 | Server | ClientHello ... later of E | server_handshake_traffic | 2796 | | ncryptedExtensions/Certifi | _secret | 2797 | | cateRequest | | 2798 | | | | 2799 | Client | ClientHello ... later of | client_handshake_traffic | 2800 | | server | _secret | 2801 | | Finished/EndOfEarlyData | | 2802 | | | | 2803 | Post- | ClientHello ... client | client_application_traff | 2804 | Handshake | Finished + | ic_secret_N | 2805 | | CertificateRequest | | 2806 +-----------+----------------------------+--------------------------+ 2808 4.4.1. The Transcript Hash 2810 Many of the cryptographic computations in TLS make use of a 2811 transcript hash. This value is computed by hashing the concatenation 2812 of each included handshake message, including the handshake message 2813 header carrying the handshake message type and length fields, but not 2814 including record layer headers. I.e., 2816 Transcript-Hash(M1, M2, ... MN) = Hash(M1 || M2 ... MN) 2818 As an exception to this general rule, when the server responds to a 2819 ClientHello with a HelloRetryRequest, the value of ClientHello1 is 2820 replaced with a special synthetic handshake message of handshake type 2821 "message_hash" containing Hash(ClientHello1). I.e., 2823 Transcript-Hash(ClientHello1, HelloRetryRequest, ... MN) = 2824 Hash(message_hash || // Handshake Type 2825 00 00 Hash.length || // Handshake message length 2826 Hash(ClientHello1) || // Hash of ClientHello1 2827 HelloRetryRequest ... MN) 2829 The reason for this construction is to allow the server to do a 2830 stateless HelloRetryRequest by storing just the hash of ClientHello1 2831 in the cookie, rather than requiring it to export the entire 2832 intermediate hash state (see Section 4.2.2). 2834 For concreteness, the transcript hash is always taken from the 2835 following sequence of handshake messages, starting at the first 2836 ClientHello and including only those messages that were sent: 2837 ClientHello, HelloRetryRequest, ClientHello, ServerHello, 2838 EncryptedExtensions, server CertificateRequest, server Certificate, 2839 server CertificateVerify, server Finished, EndOfEarlyData, client 2840 Certificate, client CertificateVerify, client Finished. 2842 In general, implementations can implement the transcript by keeping a 2843 running transcript hash value based on the negotiated hash. Note, 2844 however, that subsequent post-handshake authentications do not 2845 include each other, just the messages through the end of the main 2846 handshake. 2848 4.4.2. Certificate 2850 This message conveys the endpoint's certificate chain to the peer. 2852 The server MUST send a Certificate message whenever the agreed-upon 2853 key exchange method uses certificates for authentication (this 2854 includes all key exchange methods defined in this document except 2855 PSK). 2857 The client MUST send a Certificate message if and only if the server 2858 has requested client authentication via a CertificateRequest message 2859 (Section 4.3.2). If the server requests client authentication but no 2860 suitable certificate is available, the client MUST send a Certificate 2861 message containing no certificates (i.e., with the "certificate_list" 2862 field having length 0). 2864 Structure of this message: 2866 struct { 2867 select(certificate_type){ 2868 case RawPublicKey: 2869 // From RFC 7250 ASN.1_subjectPublicKeyInfo 2870 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 2872 case X.509: 2873 opaque cert_data<1..2^24-1>; 2874 } 2875 Extension extensions<0..2^16-1>; 2876 } CertificateEntry; 2878 struct { 2879 opaque certificate_request_context<0..2^8-1>; 2880 CertificateEntry certificate_list<0..2^24-1>; 2881 } Certificate; 2883 certificate_request_context If this message is in response to a 2884 CertificateRequest, the value of certificate_request_context in 2885 that message. Otherwise (in the case of server authentication), 2886 this field SHALL be zero length. 2888 certificate_list This is a sequence (chain) of CertificateEntry 2889 structures, each containing a single certificate and set of 2890 extensions. 2892 extensions: A set of extension values for the CertificateEntry. The 2893 "Extension" format is defined in Section 4.2. Valid extensions 2894 include OCSP Status extensions ([RFC6066] and [RFC6961]) and 2895 SignedCertificateTimestamps ([RFC6962]). An extension MUST only 2896 be present in a Certificate message if the corresponding 2897 ClientHello extension was presented in the initial handshake. If 2898 an extension applies to the entire chain, it SHOULD be included in 2899 the first CertificateEntry. 2901 If the corresponding certificate type extension 2902 ("server_certificate_type" or "client_certificate_type") was not used 2903 or the X.509 certificate type was negotiated, then each 2904 CertificateEntry contains an X.509 certificate. The sender's 2905 certificate MUST come in the first CertificateEntry in the list. 2906 Each following certificate SHOULD directly certify one preceding it. 2907 Because certificate validation requires that trust anchors be 2908 distributed independently, a certificate that specifies a trust 2909 anchor MAY be omitted from the chain, provided that supported peers 2910 are known to possess any omitted certificates. 2912 Note: Prior to TLS 1.3, "certificate_list" ordering required each 2913 certificate to certify the one immediately preceding it; however, 2914 some implementations allowed some flexibility. Servers sometimes 2915 send both a current and deprecated intermediate for transitional 2916 purposes, and others are simply configured incorrectly, but these 2917 cases can nonetheless be validated properly. For maximum 2918 compatibility, all implementations SHOULD be prepared to handle 2919 potentially extraneous certificates and arbitrary orderings from any 2920 TLS version, with the exception of the end-entity certificate which 2921 MUST be first. 2923 If the RawPublicKey certificate type was negotiated, then the 2924 certificate_list MUST contain no more than one CertificateEntry, 2925 which contains an ASN1_subjectPublicKeyInfo value as defined in 2926 [RFC7250], Section 3. 2928 The OpenPGP certificate type [RFC6091] MUST NOT be used with TLS 1.3. 2930 The server's certificate_list MUST always be non-empty. A client 2931 will send an empty certificate_list if it does not have an 2932 appropriate certificate to send in response to the server's 2933 authentication request. 2935 4.4.2.1. OCSP Status and SCT Extensions 2937 [RFC6066] and [RFC6961] provide extensions to negotiate the server 2938 sending OCSP responses to the client. In TLS 1.2 and below, the 2939 server replies with an empty extension to indicate negotiation of 2940 this extension and the OCSP information is carried in a 2941 CertificateStatus message. In TLS 1.3, the server's OCSP information 2942 is carried in an extension in the CertificateEntry containing the 2943 associated certificate. Specifically: The body of the 2944 "status_request" extension from the server MUST be a 2945 CertificateStatus structure as defined in [RFC6066], which is 2946 interpreted as defined in [RFC6960]. 2948 A server MAY request that a client present an OCSP response with its 2949 certificate by sending an empty "status_request" extension in its 2950 CertificateRequest message. If the client opts to send an OCSP 2951 response, the body of its "status_request" extension MUST be a 2952 CertificateStatus structure as defined in [RFC6066]. 2954 Similarly, [RFC6962] provides a mechanism for a server to send a 2955 Signed Certificate Timestamp (SCT) as an extension in the ServerHello 2956 in TLS 1.2 and below. In TLS 1.3, the server's SCT information is 2957 carried in an extension in CertificateEntry. 2959 4.4.2.2. Server Certificate Selection 2961 The following rules apply to the certificates sent by the server: 2963 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2964 negotiated otherwise (e.g., [RFC7250]). 2966 - The server's end-entity certificate's public key (and associated 2967 restrictions) MUST be compatible with the selected authentication 2968 algorithm (currently RSA or ECDSA). 2970 - The certificate MUST allow the key to be used for signing (i.e., 2971 the digitalSignature bit MUST be set if the Key Usage extension is 2972 present) with a signature scheme indicated in the client's 2973 "signature_algorithms" extension. 2975 - The "server_name" and "trusted_ca_keys" extensions [RFC6066] are 2976 used to guide certificate selection. As servers MAY require the 2977 presence of the "server_name" extension, clients SHOULD send this 2978 extension, when applicable. 2980 All certificates provided by the server MUST be signed by a signature 2981 algorithm that appears in the "signature_algorithms" extension 2982 provided by the client, if they are able to provide such a chain (see 2983 Section 4.2.3). Certificates that are self-signed or certificates 2984 that are expected to be trust anchors are not validated as part of 2985 the chain and therefore MAY be signed with any algorithm. 2987 If the server cannot produce a certificate chain that is signed only 2988 via the indicated supported algorithms, then it SHOULD continue the 2989 handshake by sending the client a certificate chain of its choice 2990 that may include algorithms that are not known to be supported by the 2991 client. This fallback chain MAY use the deprecated SHA-1 hash 2992 algorithm only if the "signature_algorithms" extension provided by 2993 the client permits it. If the client cannot construct an acceptable 2994 chain using the provided certificates and decides to abort the 2995 handshake, then it MUST abort the handshake with an 2996 "unsupported_certificate" alert. 2998 If the server has multiple certificates, it chooses one of them based 2999 on the above-mentioned criteria (in addition to other criteria, such 3000 as transport layer endpoint, local configuration and preferences). 3002 4.4.2.3. Client Certificate Selection 3004 The following rules apply to certificates sent by the client: 3006 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 3007 negotiated otherwise (e.g., [RFC7250]). 3009 - If the "certificate_authorities" extension in the 3010 CertificateRequest message was present, at least one of the 3011 certificates in the certificate chain SHOULD be issued by one of 3012 the listed CAs. 3014 - The certificates MUST be signed using an acceptable signature 3015 algorithm, as described in Section 4.3.2. Note that this relaxes 3016 the constraints on certificate-signing algorithms found in prior 3017 versions of TLS. 3019 - If the certificate_extensions list in the CertificateRequest 3020 message was non-empty, the end-entity certificate MUST match the 3021 extension OIDs recognized by the client, as described in 3022 Section 4.3.2. 3024 Note that, as with the server certificate, there are certificates 3025 that use algorithm combinations that cannot be currently used with 3026 TLS. 3028 4.4.2.4. Receiving a Certificate Message 3030 In general, detailed certificate validation procedures are out of 3031 scope for TLS (see [RFC5280]). This section provides TLS-specific 3032 requirements. 3034 If the server supplies an empty Certificate message, the client MUST 3035 abort the handshake with a "decode_error" alert. 3037 If the client does not send any certificates, the server MAY at its 3038 discretion either continue the handshake without client 3039 authentication, or abort the handshake with a "certificate_required" 3040 alert. Also, if some aspect of the certificate chain was 3041 unacceptable (e.g., it was not signed by a known, trusted CA), the 3042 server MAY at its discretion either continue the handshake 3043 (considering the client unauthenticated) or abort the handshake. 3045 Any endpoint receiving any certificate signed using any signature 3046 algorithm using an MD5 hash MUST abort the handshake with a 3047 "bad_certificate" alert. SHA-1 is deprecated and it is RECOMMENDED 3048 that any endpoint receiving any certificate signed using any 3049 signature algorithm using a SHA-1 hash abort the handshake with a 3050 "bad_certificate" alert. All endpoints are RECOMMENDED to transition 3051 to SHA-256 or better as soon as possible to maintain interoperability 3052 with implementations currently in the process of phasing out SHA-1 3053 support. 3055 Note that a certificate containing a key for one signature algorithm 3056 MAY be signed using a different signature algorithm (for instance, an 3057 RSA key signed with an ECDSA key). 3059 4.4.3. Certificate Verify 3061 This message is used to provide explicit proof that an endpoint 3062 possesses the private key corresponding to its certificate and also 3063 provides integrity for the handshake up to this point. Servers MUST 3064 send this message when authenticating via a certificate. Clients 3065 MUST send this message whenever authenticating via a certificate 3066 (i.e., when the Certificate message is non-empty). When sent, this 3067 message MUST appear immediately after the Certificate message and 3068 immediately prior to the Finished message. 3070 Structure of this message: 3072 struct { 3073 SignatureScheme algorithm; 3074 opaque signature<0..2^16-1>; 3075 } CertificateVerify; 3077 The algorithm field specifies the signature algorithm used (see 3078 Section 4.2.3 for the definition of this field). The signature is a 3079 digital signature using that algorithm. The content that is covered 3080 under the signature is the hash output as described in Section 4.4, 3081 namely: 3083 Transcript-Hash(Handshake Context, Certificate) 3085 The digital signature is then computed over the concatenation of: 3087 - A string that consists of octet 32 (0x20) repeated 64 times 3089 - The context string 3091 - A single 0 byte which serves as the separator 3093 - The content to be signed 3095 This structure is intended to prevent an attack on previous versions 3096 of TLS in which the ServerKeyExchange format meant that attackers 3097 could obtain a signature of a message with a chosen 32-byte prefix 3098 (ClientHello.random). The initial 64-byte pad clears that prefix 3099 along with the server-controlled ServerHello.random. 3101 The context string for a server signature is "TLS 1.3, server 3102 CertificateVerify" and for a client signature is "TLS 1.3, client 3103 CertificateVerify". It is used to provide separation between 3104 signatures made in different contexts, helping against potential 3105 cross-protocol attacks. 3107 For example, if the transcript hash was 32 bytes of 01 (this length 3108 would make sense for SHA-256), the content covered by the digital 3109 signature for a server CertificateVerify would be: 3111 2020202020202020202020202020202020202020202020202020202020202020 3112 2020202020202020202020202020202020202020202020202020202020202020 3113 544c5320312e332c207365727665722043657274696669636174655665726966 3114 79 3115 00 3116 0101010101010101010101010101010101010101010101010101010101010101 3118 On the sender side the process for computing the signature field of 3119 the CertificateVerify message takes as input: 3121 - The content covered by the digital signature 3123 - The private signing key corresponding to the certificate sent in 3124 the previous message 3126 If the CertificateVerify message is sent by a server, the signature 3127 algorithm MUST be one offered in the client's "signature_algorithms" 3128 extension unless no valid certificate chain can be produced without 3129 unsupported algorithms (see Section 4.2.3). 3131 If sent by a client, the signature algorithm used in the signature 3132 MUST be one of those present in the supported_signature_algorithms 3133 field of the "signature_algorithms" extension in the 3134 CertificateRequest message. 3136 In addition, the signature algorithm MUST be compatible with the key 3137 in the sender's end-entity certificate. RSA signatures MUST use an 3138 RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS1-v1_5 3139 algorithms appear in "signature_algorithms". SHA-1 MUST NOT be used 3140 in any signatures in CertificateVerify. All SHA-1 signature 3141 algorithms in this specification are defined solely for use in legacy 3142 certificates, and are not valid for CertificateVerify signatures. 3144 The receiver of a CertificateVerify message MUST verify the signature 3145 field. The verification process takes as input: 3147 - The content covered by the digital signature 3149 - The public key contained in the end-entity certificate found in 3150 the associated Certificate message. 3152 - The digital signature received in the signature field of the 3153 CertificateVerify message 3155 If the verification fails, the receiver MUST terminate the handshake 3156 with a "decrypt_error" alert. 3158 4.4.4. Finished 3160 The Finished message is the final message in the authentication 3161 block. It is essential for providing authentication of the handshake 3162 and of the computed keys. 3164 Recipients of Finished messages MUST verify that the contents are 3165 correct and if incorrect MUST terminate the connection with a 3166 "decrypt_error" alert. 3168 Once a side has sent its Finished message and received and validated 3169 the Finished message from its peer, it may begin to send and receive 3170 application data over the connection. Early data may be sent prior 3171 to the receipt of the peer's Finished message, per Section 4.2.9. 3173 The key used to compute the finished message is computed from the 3174 Base key defined in Section 4.4 using HKDF (see Section 7.1). 3175 Specifically: 3177 finished_key = 3178 HKDF-Expand-Label(BaseKey, "finished", "", Hash.length) 3180 Structure of this message: 3182 struct { 3183 opaque verify_data[Hash.length]; 3184 } Finished; 3186 The verify_data value is computed as follows: 3188 verify_data = 3189 HMAC(finished_key, 3190 Transcript-Hash(Handshake Context, 3191 Certificate*, CertificateVerify*)) 3193 * Only included if present. 3195 Where HMAC [RFC2104] uses the Hash algorithm for the handshake. As 3196 noted above, the HMAC input can generally be implemented by a running 3197 hash, i.e., just the handshake hash at this point. 3199 In previous versions of TLS, the verify_data was always 12 octets 3200 long. In TLS 1.3, it is the size of the HMAC output for the Hash 3201 used for the handshake. 3203 Note: Alerts and any other record types are not handshake messages 3204 and are not included in the hash computations. 3206 Any records following a 1-RTT Finished message MUST be encrypted 3207 under the appropriate application traffic key as described in 3208 Section 7.2. In particular, this includes any alerts sent by the 3209 server in response to client Certificate and CertificateVerify 3210 messages. 3212 4.5. End of Early Data 3214 struct {} EndOfEarlyData; 3216 If the server sent an "early_data" extension, the client MUST send an 3217 EndOfEarlyData after receiving the server Finished. This indicates 3218 that all 0-RTT application_data messages, if any, have been 3219 transmitted and that the following records are protected under 3220 handshake traffic keys. Servers MUST NOT send this message and 3221 clients receiving it MUST terminate the connection with an 3222 "unexpected_message" alert. This message is encrypted under keys 3223 derived from the client_early_traffic_secret. 3225 4.6. Post-Handshake Messages 3227 TLS also allows other messages to be sent after the main handshake. 3228 These messages use a handshake content type and are encrypted under 3229 the appropriate application traffic key. 3231 4.6.1. New Session Ticket Message 3233 At any time after the server has received the client Finished 3234 message, it MAY send a NewSessionTicket message. This message 3235 creates a pre-shared key (PSK) binding between the ticket value and 3236 the resumption master secret. 3238 The client MAY use this PSK for future handshakes by including the 3239 ticket value in the "pre_shared_key" extension in its ClientHello 3240 (Section 4.2.10). Servers MAY send multiple tickets on a single 3241 connection, either immediately after each other or after specific 3242 events. For instance, the server might send a new ticket after post- 3243 handshake authentication in order to encapsulate the additional 3244 client authentication state. Clients SHOULD attempt to use each 3245 ticket no more than once, with more recent tickets being used first. 3247 Any ticket MUST only be resumed with a cipher suite that has the same 3248 KDF hash as that used to establish the original connection, and only 3249 if the client provides the same SNI value as in the original 3250 connection, as described in Section 3 of [RFC6066]. 3252 Note: Although the resumption master secret depends on the client's 3253 second flight, servers which do not request client authentication MAY 3254 compute the remainder of the transcript independently and then send a 3255 NewSessionTicket immediately upon sending its Finished rather than 3256 waiting for the client Finished. This might be appropriate in cases 3257 where the client is expected to open multiple TLS connections in 3258 parallel and would benefit from the reduced overhead of a resumption 3259 handshake, for example. 3261 struct { 3262 uint32 ticket_lifetime; 3263 uint32 ticket_age_add; 3264 opaque ticket<1..2^16-1>; 3265 Extension extensions<0..2^16-2>; 3266 } NewSessionTicket; 3268 ticket_lifetime Indicates the lifetime in seconds as a 32-bit 3269 unsigned integer in network byte order from the time of ticket 3270 issuance. Servers MUST NOT use any value more than 604800 seconds 3271 (7 days). The value of zero indicates that the ticket should be 3272 discarded immediately. Clients MUST NOT cache tickets for longer 3273 than 7 days, regardless of the ticket_lifetime, and MAY delete the 3274 ticket earlier based on local policy. A server MAY treat a ticket 3275 as valid for a shorter period of time than what is stated in the 3276 ticket_lifetime. 3278 ticket_age_add A securely generated, random 32-bit value that is 3279 used to obscure the age of the ticket that the client includes in 3280 the "pre_shared_key" extension. The client-side ticket age is 3281 added to this value modulo 2^32 to obtain the value that is 3282 transmitted by the client. The server MUST generate a fresh value 3283 for each ticket it sends. 3285 ticket The value of the ticket to be used as the PSK identity. The 3286 ticket itself is an opaque label. It MAY either be a database 3287 lookup key or a self-encrypted and self-authenticated value. 3288 Section 4 of [RFC5077] describes a recommended ticket construction 3289 mechanism. 3291 extensions A set of extension values for the ticket. The 3292 "Extension" format is defined in Section 4.2. Clients MUST ignore 3293 unrecognized extensions. 3295 The sole extension currently defined for NewSessionTicket is 3296 "early_data", indicating that the ticket may be used to send 0-RTT 3297 data (Section 4.2.9)). It contains the following value: 3299 max_early_data_size The maximum amount of 0-RTT data that the client 3300 is allowed to send when using this ticket, in bytes. Only 3301 Application Data payload (i.e., plaintext but not padding or the 3302 inner content type byte) is counted. A server receiving more than 3303 max_early_data_size bytes of 0-RTT data SHOULD terminate the 3304 connection with an "unexpected_message" alert. Note that servers 3305 that reject early data due to lack of cryptographic material will 3306 be unable to differentiate padding from content, so clients SHOULD 3307 NOT depend on being able to send large quantities of padding in 3308 early data records. 3310 Note that in principle it is possible to continue issuing new tickets 3311 which indefinitely extend the lifetime of the keying material 3312 originally derived from an initial non-PSK handshake (which was most 3313 likely tied to the peer's certificate). It is RECOMMENDED that 3314 implementations place limits on the total lifetime of such keying 3315 material; these limits should take into account the lifetime of the 3316 peer's certificate, the likelihood of intervening revocation, and the 3317 time since the peer's online CertificateVerify signature. 3319 4.6.2. Post-Handshake Authentication 3321 When the client has sent the "post_handshake_auth" extension (see 3322 Section 4.2.5), a server MAY request client authentication at any 3323 time after the handshake has completed by sending a 3324 CertificateRequest message. The client MUST respond with the 3325 appropriate Authentication messages (see Section 4.4). If the client 3326 chooses to authenticate, it MUST send Certificate, CertificateVerify, 3327 and Finished. If it declines, it MUST send a Certificate message 3328 containing no certificates followed by Finished. All of the client's 3329 messages for a given response MUST appear consecutively on the wire 3330 with no intervening messages of other types. 3332 A client that receives a CertificateRequest message without having 3333 sent the "post_handshake_auth" extension MUST send an 3334 "unexpected_message" fatal alert. 3336 Note: Because client authentication could involve prompting the user, 3337 servers MUST be prepared for some delay, including receiving an 3338 arbitrary number of other messages between sending the 3339 CertificateRequest and receiving a response. In addition, clients 3340 which receive multiple CertificateRequests in close succession MAY 3341 respond to them in a different order than they were received (the 3342 certificate_request_context value allows the server to disambiguate 3343 the responses). 3345 4.6.3. Key and IV Update 3347 enum { 3348 update_not_requested(0), update_requested(1), (255) 3349 } KeyUpdateRequest; 3351 struct { 3352 KeyUpdateRequest request_update; 3353 } KeyUpdate; 3355 request_update Indicates whether the recipient of the KeyUpdate 3356 should respond with its own KeyUpdate. If an implementation 3357 receives any other value, it MUST terminate the connection with an 3358 "illegal_parameter" alert. 3360 The KeyUpdate handshake message is used to indicate that the sender 3361 is updating its sending cryptographic keys. This message can be sent 3362 by either peer after it has sent a Finished message. Implementations 3363 that receive a KeyUpdate message prior to receiving a Finished 3364 message MUST terminate the connection with an "unexpected_message" 3365 alert. After sending a KeyUpdate message, the sender SHALL send all 3366 its traffic using the next generation of keys, computed as described 3367 in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update 3368 its receiving keys. 3370 If the request_update field is set to "update_requested" then the 3371 receiver MUST send a KeyUpdate of its own with request_update set to 3372 "update_not_requested" prior to sending its next application data 3373 record. This mechanism allows either side to force an update to the 3374 entire connection, but causes an implementation which receives 3375 multiple KeyUpdates while it is silent to respond with a single 3376 update. Note that implementations may receive an arbitrary number of 3377 messages between sending a KeyUpdate with request_update set to 3378 update_requested and receiving the peer's KeyUpdate, because those 3379 messages may already be in flight. However, because send and receive 3380 keys are derived from independent traffic secrets, retaining the 3381 receive traffic secret does not threaten the forward secrecy of data 3382 sent before the sender changed keys. 3384 If implementations independently send their own KeyUpdates with 3385 request_update set to "update_requested", and they cross in flight, 3386 then each side will also send a response, with the result that each 3387 side increments by two generations. 3389 Both sender and receiver MUST encrypt their KeyUpdate messages with 3390 the old keys. Additionally, both sides MUST enforce that a KeyUpdate 3391 with the old key is received before accepting any messages encrypted 3392 with the new key. Failure to do so may allow message truncation 3393 attacks. 3395 5. Record Protocol 3397 The TLS record protocol takes messages to be transmitted, fragments 3398 the data into manageable blocks, protects the records, and transmits 3399 the result. Received data is verified and decrypted, reassembled, 3400 and then delivered to higher-level clients. 3402 TLS records are typed, which allows multiple higher-level protocols 3403 to be multiplexed over the same record layer. This document 3404 specifies three content types: handshake, application data, and 3405 alert. Implementations MUST NOT send record types not defined in 3406 this document unless negotiated by some extension. If a TLS 3407 implementation receives an unexpected record type, it MUST terminate 3408 the connection with an "unexpected_message" alert. New record 3409 content type values are assigned by IANA in the TLS Content Type 3410 Registry as described in Section 10. 3412 5.1. Record Layer 3414 The record layer fragments information blocks into TLSPlaintext 3415 records carrying data in chunks of 2^14 bytes or less. Message 3416 boundaries are handled differently depending on the underlying 3417 ContentType. Any future content types MUST specify appropriate 3418 rules. Note that these rules are stricter than what was enforced in 3419 TLS 1.2. 3421 Handshake messages MAY be coalesced into a single TLSPlaintext record 3422 or fragmented across several records, provided that: 3424 - Handshake messages MUST NOT be interleaved with other record 3425 types. That is, if a handshake message is split over two or more 3426 records, there MUST NOT be any other records between them. 3428 - Handshake messages MUST NOT span key changes. Implementations 3429 MUST verify that all messages immediately preceding a key change 3430 align with a record boundary; if not, then they MUST terminate the 3431 connection with an "unexpected_message" alert. Because the 3432 ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate 3433 messages can immediately precede a key change, implementations 3434 MUST send these messages in alignment with a record boundary. 3436 Implementations MUST NOT send zero-length fragments of Handshake 3437 types, even if those fragments contain padding. 3439 Alert messages (Section 6) MUST NOT be fragmented across records and 3440 multiple Alert messages MUST NOT be coalesced into a single 3441 TLSPlaintext record. In other words, a record with an Alert type 3442 MUST contain exactly one message. 3444 Application Data messages contain data that is opaque to TLS. 3445 Application Data messages are always protected. Zero-length 3446 fragments of Application Data MAY be sent as they are potentially 3447 useful as a traffic analysis countermeasure. 3449 enum { 3450 invalid(0), 3451 alert(21), 3452 handshake(22), 3453 application_data(23), 3454 (255) 3455 } ContentType; 3457 struct { 3458 ContentType type; 3459 ProtocolVersion legacy_record_version; 3460 uint16 length; 3461 opaque fragment[TLSPlaintext.length]; 3462 } TLSPlaintext; 3464 type The higher-level protocol used to process the enclosed 3465 fragment. 3467 legacy_record_version This value MUST be set to 0x0301 for all 3468 records generated by a TLS 1.3 implementation. This field is 3469 deprecated and MUST be ignored for all purposes. Previous 3470 versions of TLS would use other values in this field under some 3471 circumstances. 3473 length The length (in bytes) of the following TLSPlaintext.fragment. 3474 The length MUST NOT exceed 2^14 bytes. An endpoint that receives 3475 a record that exceeds this length MUST terminate the connection 3476 with a "record_overflow" alert. 3478 fragment The data being transmitted. This value is transparent and 3479 is treated as an independent block to be dealt with by the higher- 3480 level protocol specified by the type field. 3482 This document describes TLS 1.3, which uses the version 0x0304. This 3483 version value is historical, deriving from the use of 0x0301 for TLS 3484 1.0 and 0x0300 for SSL 3.0. In order to maximize backwards 3485 compatibility, the record layer version identifies as simply TLS 1.0. 3486 Endpoints supporting multiple versions negotiate the version to use 3487 by following the procedure and requirements in Appendix D. 3489 When record protection has not yet been engaged, TLSPlaintext 3490 structures are written directly onto the wire. Once record 3491 protection has started, TLSPlaintext records are protected and sent 3492 as described in the following section. 3494 5.2. Record Payload Protection 3496 The record protection functions translate a TLSPlaintext structure 3497 into a TLSCiphertext. The deprotection functions reverse the 3498 process. In TLS 1.3, as opposed to previous versions of TLS, all 3499 ciphers are modeled as "Authenticated Encryption with Additional 3500 Data" (AEAD) [RFC5116]. AEAD functions provide an unified encryption 3501 and authentication operation which turns plaintext into authenticated 3502 ciphertext and back again. Each encrypted record consists of a 3503 plaintext header followed by an encrypted body, which itself contains 3504 a type and optional padding. 3506 struct { 3507 opaque content[TLSPlaintext.length]; 3508 ContentType type; 3509 uint8 zeros[length_of_padding]; 3510 } TLSInnerPlaintext; 3512 struct { 3513 ContentType opaque_type = 23; /* application_data */ 3514 ProtocolVersion legacy_record_version = 0x0301; /* TLS v1.x */ 3515 uint16 length; 3516 opaque encrypted_record[length]; 3517 } TLSCiphertext; 3519 content The byte encoding of a handshake or an alert message, or the 3520 raw bytes of the application's data to send. 3522 type The content type of the record. 3524 zeros An arbitrary-length run of zero-valued bytes may appear in the 3525 cleartext after the type field. This provides an opportunity for 3526 senders to pad any TLS record by a chosen amount as long as the 3527 total stays within record size limits. See Section 5.4 for more 3528 details. 3530 opaque_type The outer opaque_type field of a TLSCiphertext record is 3531 always set to the value 23 (application_data) for outward 3532 compatibility with middleboxes accustomed to parsing previous 3533 versions of TLS. The actual content type of the record is found 3534 in TLSInnerPlaintext.type after decryption. 3536 legacy_record_version The legacy_record_version field is always 3537 0x0301. TLS 1.3 TLSCiphertexts are not generated until after TLS 3538 1.3 has been negotiated, so there are no historical compatibility 3539 concerns where other values might be received. Implementations 3540 MAY verify that the legacy_record_version field is 0x0301 and 3541 abort the connection if it is not. Note that the handshake 3542 protocol including the ClientHello and ServerHello messages 3543 authenticates the protocol version, so this value is redundant. 3545 length The length (in bytes) of the following 3546 TLSCiphertext.encrypted_record, which is the sum of the lengths of 3547 the content and the padding, plus one for the inner content type, 3548 plus any expansion added by the AEAD algorithm. The length MUST 3549 NOT exceed 2^14 + 256 bytes. An endpoint that receives a record 3550 that exceeds this length MUST terminate the connection with a 3551 "record_overflow" alert. 3553 encrypted_record The AEAD-encrypted form of the serialized 3554 TLSInnerPlaintext structure. 3556 AEAD algorithms take as input a single key, a nonce, a plaintext, and 3557 "additional data" to be included in the authentication check, as 3558 described in Section 2.1 of [RFC5116]. The key is either the 3559 client_write_key or the server_write_key, the nonce is derived from 3560 the sequence number (see Section 5.3) and the client_write_iv or 3561 server_write_iv, and the additional data input is empty (zero 3562 length). Derivation of traffic keys is defined in Section 7.3. 3564 The plaintext input to the AEAD is the the encoded TLSInnerPlaintext 3565 structure. 3567 The AEAD output consists of the ciphertext output from the AEAD 3568 encryption operation. The length of the plaintext is greater than 3569 the corresponding TLSPlaintext.length due to the inclusion of 3570 TLSInnerPlaintext.type and any padding supplied by the sender. The 3571 length of the AEAD output will generally be larger than the 3572 plaintext, but by an amount that varies with the AEAD algorithm. 3573 Since the ciphers might incorporate padding, the amount of overhead 3574 could vary with different lengths of plaintext. Symbolically, 3576 AEADEncrypted = 3577 AEAD-Encrypt(write_key, nonce, plaintext) 3579 In order to decrypt and verify, the cipher takes as input the key, 3580 nonce, and the AEADEncrypted value. The output is either the 3581 plaintext or an error indicating that the decryption failed. There 3582 is no separate integrity check. That is: 3584 plaintext of encrypted_record = 3585 AEAD-Decrypt(peer_write_key, nonce, AEADEncrypted) 3587 If the decryption fails, the receiver MUST terminate the connection 3588 with a "bad_record_mac" alert. 3590 An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion 3591 greater than 255 octets. An endpoint that receives a record from its 3592 peer with TLSCiphertext.length larger than 2^14 + 256 octets MUST 3593 terminate the connection with a "record_overflow" alert. This limit 3594 is derived from the maximum TLSPlaintext length of 2^14 octets + 1 3595 octet for ContentType + the maximum AEAD expansion of 255 octets. 3597 5.3. Per-Record Nonce 3599 A 64-bit sequence number is maintained separately for reading and 3600 writing records. Each sequence number is set to zero at the 3601 beginning of a connection and whenever the key is changed. 3603 The appropriate sequence number is incremented by one after reading 3604 or writing each record. The first record transmitted under a 3605 particular set of traffic keys MUST use sequence number 0. 3607 Because the size of sequence numbers is 64-bit, they should not wrap. 3608 If a TLS implementation would need to wrap a sequence number, it MUST 3609 either re-key (Section 4.6.3) or terminate the connection. 3611 Each AEAD algorithm will specify a range of possible lengths for the 3612 per-record nonce, from N_MIN bytes to N_MAX bytes of input 3613 ([RFC5116]). The length of the TLS per-record nonce (iv_length) is 3614 set to the larger of 8 bytes and N_MIN for the AEAD algorithm (see 3615 [RFC5116] Section 4). An AEAD algorithm where N_MAX is less than 8 3616 bytes MUST NOT be used with TLS. The per-record nonce for the AEAD 3617 construction is formed as follows: 3619 1. The 64-bit record sequence number is encoded in network byte 3620 order and padded to the left with zeros to iv_length. 3622 2. The padded sequence number is XORed with the static 3623 client_write_iv or server_write_iv, depending on the role. 3625 The resulting quantity (of length iv_length) is used as the per- 3626 record nonce. 3628 Note: This is a different construction from that in TLS 1.2, which 3629 specified a partially explicit nonce. 3631 5.4. Record Padding 3633 All encrypted TLS records can be padded to inflate the size of the 3634 TLSCiphertext. This allows the sender to hide the size of the 3635 traffic from an observer. 3637 When generating a TLSCiphertext record, implementations MAY choose to 3638 pad. An unpadded record is just a record with a padding length of 3639 zero. Padding is a string of zero-valued bytes appended to the 3640 ContentType field before encryption. Implementations MUST set the 3641 padding octets to all zeros before encrypting. 3643 Application Data records may contain a zero-length 3644 TLSInnerPlaintext.content if the sender desires. This permits 3645 generation of plausibly-sized cover traffic in contexts where the 3646 presence or absence of activity may be sensitive. Implementations 3647 MUST NOT send Handshake or Alert records that have a zero-length 3648 TLSInnerPlaintext.content; if such a message is received, the 3649 receiving implementation MUST terminate the connection with an 3650 "unexpected_message" alert. 3652 The padding sent is automatically verified by the record protection 3653 mechanism; upon successful decryption of a 3654 TLSCiphertext.encrypted_record, the receiving implementation scans 3655 the field from the end toward the beginning until it finds a non-zero 3656 octet. This non-zero octet is the content type of the message. This 3657 padding scheme was selected because it allows padding of any 3658 encrypted TLS record by an arbitrary size (from zero up to TLS record 3659 size limits) without introducing new content types. The design also 3660 enforces all-zero padding octets, which allows for quick detection of 3661 padding errors. 3663 Implementations MUST limit their scanning to the cleartext returned 3664 from the AEAD decryption. If a receiving implementation does not 3665 find a non-zero octet in the cleartext, it MUST terminate the 3666 connection with an "unexpected_message" alert. 3668 The presence of padding does not change the overall record size 3669 limitations - the full encoded TLSInnerPlaintext MUST not exceed 2^14 3670 octets. If the maximum fragment length is reduced, such as by the 3671 max_fragment_length extension from [RFC6066], then the reduced limit 3672 applies to the full plaintext, including the padding. 3674 Selecting a padding policy that suggests when and how much to pad is 3675 a complex topic, and is beyond the scope of this specification. If 3676 the application layer protocol atop TLS has its own padding, it may 3677 be preferable to pad application_data TLS records within the 3678 application layer. Padding for encrypted handshake and alert TLS 3679 records must still be handled at the TLS layer, though. Later 3680 documents may define padding selection algorithms, or define a 3681 padding policy request mechanism through TLS extensions or some other 3682 means. 3684 5.5. Limits on Key Usage 3686 There are cryptographic limits on the amount of plaintext which can 3687 be safely encrypted under a given set of keys. [AEAD-LIMITS] 3688 provides an analysis of these limits under the assumption that the 3689 underlying primitive (AES or ChaCha20) has no weaknesses. 3690 Implementations SHOULD do a key update as described in Section 4.6.3 3691 prior to reaching these limits. 3693 For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be 3694 encrypted on a given connection while keeping a safety margin of 3695 approximately 2^-57 for Authenticated Encryption (AE) security. For 3696 ChaCha20/Poly1305, the record sequence number would wrap before the 3697 safety limit is reached. 3699 6. Alert Protocol 3701 One of the content types supported by the TLS record layer is the 3702 alert type. Like other messages, alert messages are encrypted as 3703 specified by the current connection state. 3705 Alert messages convey a description of the alert and a legacy field 3706 that conveyed the severity of the message in previous versions of 3707 TLS. In TLS 1.3, the severity is implicit in the type of alert being 3708 sent, and the 'level' field can safely be ignored. The 3709 "close_notify" alert is used to indicate orderly closure of the 3710 connection. Upon receiving such an alert, the TLS implementation 3711 SHOULD indicate end-of-data to the application. 3713 Error alerts indicate abortive closure of the connection (see 3714 Section 6.2). Upon receiving an error alert, the TLS implementation 3715 SHOULD indicate an error to the application and MUST NOT allow any 3716 further data to be sent or received on the connection. Servers and 3717 clients MUST forget keys and secrets associated with a failed 3718 connection. Stateful implementations of tickets (as in many clients) 3719 SHOULD discard tickets associated with failed connections. 3721 All the alerts listed in Section 6.2 MUST be sent as fatal and MUST 3722 be treated as fatal regardless of the AlertLevel in the message. 3723 Unknown alert types MUST be treated as fatal. 3725 Note: TLS defines two generic alerts (see Section 6) to use upon 3726 failure to parse a message. Peers which receive a message which 3727 cannot be parsed according to the syntax (e.g., have a length 3728 extending beyond the message boundary or contain an out-of-range 3729 length) MUST terminate the connection with a "decode_error" alert. 3730 Peers which receive a message which is syntactically correct but 3731 semantically invalid (e.g., a DHE share of p - 1, or an invalid enum) 3732 MUST terminate the connection with an "illegal_parameter" alert. 3734 enum { warning(1), fatal(2), (255) } AlertLevel; 3736 enum { 3737 close_notify(0), 3738 unexpected_message(10), 3739 bad_record_mac(20), 3740 record_overflow(22), 3741 handshake_failure(40), 3742 bad_certificate(42), 3743 unsupported_certificate(43), 3744 certificate_revoked(44), 3745 certificate_expired(45), 3746 certificate_unknown(46), 3747 illegal_parameter(47), 3748 unknown_ca(48), 3749 access_denied(49), 3750 decode_error(50), 3751 decrypt_error(51), 3752 protocol_version(70), 3753 insufficient_security(71), 3754 internal_error(80), 3755 inappropriate_fallback(86), 3756 user_canceled(90), 3757 missing_extension(109), 3758 unsupported_extension(110), 3759 certificate_unobtainable(111), 3760 unrecognized_name(112), 3761 bad_certificate_status_response(113), 3762 bad_certificate_hash_value(114), 3763 unknown_psk_identity(115), 3764 certificate_required(116), 3765 no_application_protocol(120), 3766 (255) 3767 } AlertDescription; 3769 struct { 3770 AlertLevel level; 3771 AlertDescription description; 3772 } Alert; 3774 6.1. Closure Alerts 3776 The client and the server must share knowledge that the connection is 3777 ending in order to avoid a truncation attack. 3779 close_notify This alert notifies the recipient that the sender will 3780 not send any more messages on this connection. Any data received 3781 after a closure MUST be ignored. 3783 user_canceled This alert notifies the recipient that the sender is 3784 canceling the handshake for some reason unrelated to a protocol 3785 failure. If a user cancels an operation after the handshake is 3786 complete, just closing the connection by sending a "close_notify" 3787 is more appropriate. This alert SHOULD be followed by a 3788 "close_notify". This alert is generally a warning. 3790 Either party MAY initiate a close by sending a "close_notify" alert. 3791 Any data received after a closure alert MUST be ignored. If a 3792 transport-level close is received prior to a "close_notify", the 3793 receiver cannot know that all the data that was sent has been 3794 received. 3796 Each party MUST send a "close_notify" alert before closing the write 3797 side of the connection, unless some other fatal alert has been 3798 transmitted. The other party MUST respond with a "close_notify" 3799 alert of its own and close down the connection immediately, 3800 discarding any pending writes. The initiator of the close need not 3801 wait for the responding "close_notify" alert before closing the read 3802 side of the connection. 3804 If the application protocol using TLS provides that any data may be 3805 carried over the underlying transport after the TLS connection is 3806 closed, the TLS implementation MUST receive the responding 3807 "close_notify" alert before indicating to the application layer that 3808 the TLS connection has ended. If the application protocol will not 3809 transfer any additional data, but will only close the underlying 3810 transport connection, then the implementation MAY choose to close the 3811 transport without waiting for the responding "close_notify". No part 3812 of this standard should be taken to dictate the manner in which a 3813 usage profile for TLS manages its data transport, including when 3814 connections are opened or closed. 3816 Note: It is assumed that closing a connection reliably delivers 3817 pending data before destroying the transport. 3819 6.2. Error Alerts 3821 Error handling in the TLS Handshake Protocol is very simple. When an 3822 error is detected, the detecting party sends a message to its peer. 3823 Upon transmission or receipt of a fatal alert message, both parties 3824 MUST immediately close the connection. 3826 Whenever an implementation encounters a fatal error condition, it 3827 SHOULD send an appropriate fatal alert and MUST close the connection 3828 without sending or receiving any additional data. In the rest of 3829 this specification, when the phrases "terminate the connection" and 3830 "abort the handshake" are used without a specific alert it means that 3831 the implementation SHOULD send the alert indicated by the 3832 descriptions below. The phrases "terminate the connection with a X 3833 alert" and "abort the handshake with a X alert" mean that the 3834 implementation MUST send alert X if it sends any alert. All alerts 3835 defined in this section below, as well as all unknown alerts, are 3836 universally considered fatal as of TLS 1.3 (see Section 6). 3838 The following error alerts are defined: 3840 unexpected_message An inappropriate message (e.g., the wrong 3841 handshake message, premature application data, etc.) was received. 3842 This alert should never be observed in communication between 3843 proper implementations. 3845 bad_record_mac This alert is returned if a record is received which 3846 cannot be deprotected. Because AEAD algorithms combine decryption 3847 and verification, and also to avoid side channel attacks, this 3848 alert is used for all deprotection failures. This alert should 3849 never be observed in communication between proper implementations, 3850 except when messages were corrupted in the network. 3852 record_overflow A TLSCiphertext record was received that had a 3853 length more than 2^14 + 256 bytes, or a record decrypted to a 3854 TLSPlaintext record with more than 2^14 bytes. This alert should 3855 never be observed in communication between proper implementations, 3856 except when messages were corrupted in the network. 3858 handshake_failure Receipt of a "handshake_failure" alert message 3859 indicates that the sender was unable to negotiate an acceptable 3860 set of security parameters given the options available. 3862 bad_certificate A certificate was corrupt, contained signatures that 3863 did not verify correctly, etc. 3865 unsupported_certificate A certificate was of an unsupported type. 3867 certificate_revoked A certificate was revoked by its signer. 3869 certificate_expired A certificate has expired or is not currently 3870 valid. 3872 certificate_unknown Some other (unspecified) issue arose in 3873 processing the certificate, rendering it unacceptable. 3875 illegal_parameter A field in the handshake was incorrect or 3876 inconsistent with other fields. This alert is used for errors 3877 which conform to the formal protocol syntax but are otherwise 3878 incorrect. 3880 unknown_ca A valid certificate chain or partial chain was received, 3881 but the certificate was not accepted because the CA certificate 3882 could not be located or could not be matched with a known trust 3883 anchor. 3885 access_denied A valid certificate or PSK was received, but when 3886 access control was applied, the sender decided not to proceed with 3887 negotiation. 3889 decode_error A message could not be decoded because some field was 3890 out of the specified range or the length of the message was 3891 incorrect. This alert is used for errors where the message does 3892 not conform to the formal protocol syntax. This alert should 3893 never be observed in communication between proper implementations, 3894 except when messages were corrupted in the network. 3896 decrypt_error A handshake (not record-layer) cryptographic operation 3897 failed, including being unable to correctly verify a signature or 3898 validate a Finished message or a PSK binder. 3900 protocol_version The protocol version the peer has attempted to 3901 negotiate is recognized but not supported. (see Appendix D) 3903 insufficient_security Returned instead of "handshake_failure" when a 3904 negotiation has failed specifically because the server requires 3905 parameters more secure than those supported by the client. 3907 internal_error An internal error unrelated to the peer or the 3908 correctness of the protocol (such as a memory allocation failure) 3909 makes it impossible to continue. 3911 inappropriate_fallback Sent by a server in response to an invalid 3912 connection retry attempt from a client (see [RFC7507]). 3914 missing_extension Sent by endpoints that receive a hello message not 3915 containing an extension that is mandatory to send for the offered 3916 TLS version or other negotiated parameters. 3918 unsupported_extension Sent by endpoints receiving any hello message 3919 containing an extension known to be prohibited for inclusion in 3920 the given hello message, or including any extensions in a 3921 ServerHello or Certificate not first offered in the corresponding 3922 ClientHello. 3924 certificate_unobtainable Sent by servers when unable to obtain a 3925 certificate from a URL provided by the client via the 3926 "client_certificate_url" extension (see [RFC6066]). 3928 unrecognized_name Sent by servers when no server exists identified 3929 by the name provided by the client via the "server_name" extension 3930 (see [RFC6066]). 3932 bad_certificate_status_response Sent by clients when an invalid or 3933 unacceptable OCSP response is provided by the server via the 3934 "status_request" extension (see [RFC6066]). 3936 bad_certificate_hash_value Sent by servers when a retrieved object 3937 does not have the correct hash provided by the client via the 3938 "client_certificate_url" extension (see [RFC6066]). 3940 unknown_psk_identity Sent by servers when PSK key establishment is 3941 desired but no acceptable PSK identity is provided by the client. 3942 Sending this alert is OPTIONAL; servers MAY instead choose to send 3943 a "decrypt_error" alert to merely indicate an invalid PSK 3944 identity. 3946 certificate_required Sent by servers when a client certificate is 3947 desired but none was provided by the client. 3949 no_application_protocol Sent by servers when a client 3950 "application_layer_protocol_negotiation" extension advertises 3951 protocols that the server does not support. 3953 New Alert values are assigned by IANA as described in Section 10. 3955 7. Cryptographic Computations 3957 The TLS handshake establishes one or more input secrets which are 3958 combined to create the actual working keying material, as detailed 3959 below. The key derivation process incorporates both the input 3960 secrets and the handshake transcript. Note that because the 3961 handshake transcript includes the random values in the Hello 3962 messages, any given handshake will have different traffic secrets, 3963 even if the same input secrets are used, as is the case when the same 3964 PSK is used for multiple connections 3966 7.1. Key Schedule 3968 The key derivation process makes use of the HKDF-Extract and HKDF- 3969 Expand functions as defined for HKDF [RFC5869], as well as the 3970 functions defined below: 3972 HKDF-Expand-Label(Secret, Label, HashValue, Length) = 3973 HKDF-Expand(Secret, HkdfLabel, Length) 3975 Where HkdfLabel is specified as: 3977 struct { 3978 uint16 length = Length; 3979 opaque label<7..255> = "tls13 " + Label; 3980 opaque hash_value<0..255> = HashValue; 3981 } HkdfLabel; 3983 Derive-Secret(Secret, Label, Messages) = 3984 HKDF-Expand-Label(Secret, Label, 3985 Transcript-Hash(Messages), Hash.length) 3987 The Hash function and the HKDF hash are the cipher suite hash 3988 algorithm. Hash.length is its output length in bytes. Messages are 3989 the concatenation of the indicated handshake messages, including the 3990 handshake message type and length fields, but not including record 3991 layer headers. Note that in some cases a zero-length HashValue 3992 (indicated by "") is passed to HKDF-Expand-Label. 3994 Note: with common hash functions, any label longer than 12 characters 3995 requires an additional iteration of the hash function to compute. 3996 The labels in this specification have all been chosen to fit within 3997 this limit. 3999 Given a set of n InputSecrets, the final "master secret" is computed 4000 by iteratively invoking HKDF-Extract with InputSecret_1, 4001 InputSecret_2, etc. The initial secret is simply a string of 4002 Hash.length zero bytes. Concretely, for the present version of TLS 4003 1.3, secrets are added in the following order: 4005 - PSK (a pre-shared key established externally or a 4006 resumption_master_secret value from a previous connection) 4008 - (EC)DHE shared secret (Section 7.4) 4010 This produces a full key derivation schedule shown in the diagram 4011 below. In this diagram, the following formatting conventions apply: 4013 - HKDF-Extract is drawn as taking the Salt argument from the top and 4014 the IKM argument from the left. 4016 - Derive-Secret's Secret argument is indicated by the incoming 4017 arrow. For instance, the Early Secret is the Secret for 4018 generating the client_early_traffic_secret. 4020 0 4021 | 4022 v 4023 PSK -> HKDF-Extract = Early Secret 4024 | 4025 +-----> Derive-Secret(., 4026 | "ext binder" | 4027 | "res binder", 4028 | "") 4029 | = binder_key 4030 | 4031 +-----> Derive-Secret(., "c e traffic", 4032 | ClientHello) 4033 | = client_early_traffic_secret 4034 | 4035 +-----> Derive-Secret(., "e exp master", 4036 | ClientHello) 4037 | = early_exporter_master_secret 4038 v 4039 Derive-Secret(., "derived", "") 4040 | 4041 v 4042 (EC)DHE -> HKDF-Extract = Handshake Secret 4043 | 4044 +-----> Derive-Secret(., "c hs traffic", 4045 | ClientHello...ServerHello) 4046 | = client_handshake_traffic_secret 4047 | 4048 +-----> Derive-Secret(., "s hs traffic", 4049 | ClientHello...ServerHello) 4050 | = server_handshake_traffic_secret 4051 v 4052 Derive-Secret(., "derived", "") 4053 | 4054 v 4055 0 -> HKDF-Extract = Master Secret 4056 | 4057 +-----> Derive-Secret(., "c ap traffic", 4058 | ClientHello...server Finished) 4059 | = client_application_traffic_secret_0 4060 | 4061 +-----> Derive-Secret(., "s ap traffic", 4062 | ClientHello...server Finished) 4063 | = server_application_traffic_secret_0 4064 | 4065 +-----> Derive-Secret(., "exp master", 4066 | ClientHello...server Finished) 4067 | = exporter_master_secret 4068 | 4069 +-----> Derive-Secret(., "res master", 4070 ClientHello...client Finished) 4071 = resumption_master_secret 4073 The general pattern here is that the secrets shown down the left side 4074 of the diagram are just raw entropy without context, whereas the 4075 secrets down the right side include handshake context and therefore 4076 can be used to derive working keys without additional context. Note 4077 that the different calls to Derive-Secret may take different Messages 4078 arguments, even with the same secret. In a 0-RTT exchange, Derive- 4079 Secret is called with four distinct transcripts; in a 1-RTT-only 4080 exchange with three distinct transcripts. 4082 If a given secret is not available, then the 0-value consisting of a 4083 string of Hash.length zero bytes is used. Note that this does not 4084 mean skipping rounds, so if PSK is not in use Early Secret will still 4085 be HKDF-Extract(0, 0). For the computation of the binder_secret, the 4086 label is "ext binder" for external PSKs (those provisioned outside of 4087 TLS) and "res binder" for resumption PSKs (those provisioned as the 4088 resumption master secret of a previous handshake). The different 4089 labels prevent the substitution of one type of PSK for the other. 4091 There are multiple potential Early Secret values depending on which 4092 PSK the server ultimately selects. The client will need to compute 4093 one for each potential PSK; if no PSK is selected, it will then need 4094 to compute the early secret corresponding to the zero PSK. 4096 7.2. Updating Traffic Keys and IVs 4098 Once the handshake is complete, it is possible for either side to 4099 update its sending traffic keys using the KeyUpdate handshake message 4100 defined in Section 4.6.3. The next generation of traffic keys is 4101 computed by generating client_/server_application_traffic_secret_N+1 4102 from client_/server_application_traffic_secret_N as described in this 4103 section then re-deriving the traffic keys as described in 4104 Section 7.3. 4106 The next-generation application_traffic_secret is computed as: 4108 application_traffic_secret_N+1 = 4109 HKDF-Expand-Label(application_traffic_secret_N, 4110 "traffic upd", "", Hash.length) 4112 Once client/server_application_traffic_secret_N+1 and its associated 4113 traffic keys have been computed, implementations SHOULD delete 4114 client_/server_application_traffic_secret_N and its associated 4115 traffic keys. 4117 7.3. Traffic Key Calculation 4119 The traffic keying material is generated from the following input 4120 values: 4122 - A secret value 4124 - A purpose value indicating the specific value being generated 4126 - The length of the key 4128 The traffic keying material is generated from an input traffic secret 4129 value using: 4131 [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) 4132 [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length) 4134 [sender] denotes the sending side. The Secret value for each record 4135 type is shown in the table below. 4137 +-------------------+---------------------------------------+ 4138 | Record Type | Secret | 4139 +-------------------+---------------------------------------+ 4140 | 0-RTT Application | client_early_traffic_secret | 4141 | | | 4142 | Handshake | [sender]_handshake_traffic_secret | 4143 | | | 4144 | Application Data | [sender]_application_traffic_secret_N | 4145 +-------------------+---------------------------------------+ 4147 All the traffic keying material is recomputed whenever the underlying 4148 Secret changes (e.g., when changing from the handshake to application 4149 data keys or upon a key update). 4151 7.4. (EC)DHE Shared Secret Calculation 4153 7.4.1. Finite Field Diffie-Hellman 4155 For finite field groups, a conventional Diffie-Hellman computation is 4156 performed. The negotiated key (Z) is converted to a byte string by 4157 encoding in big-endian and padded with zeros up to the size of the 4158 prime. This byte string is used as the shared secret, and is used in 4159 the key schedule as specified above. 4161 Note that this construction differs from previous versions of TLS 4162 which remove leading zeros. 4164 7.4.2. Elliptic Curve Diffie-Hellman 4166 For secp256r1, secp384r1 and secp521r1, ECDH calculations (including 4167 parameter and key generation as well as the shared secret 4168 calculation) are performed according to [IEEE1363] using the ECKAS- 4169 DH1 scheme with the identity map as key derivation function (KDF), so 4170 that the shared secret is the x-coordinate of the ECDH shared secret 4171 elliptic curve point represented as an octet string. Note that this 4172 octet string (Z in IEEE 1363 terminology) as output by FE2OSP, the 4173 Field Element to Octet String Conversion Primitive, has constant 4174 length for any given field; leading zeros found in this octet string 4175 MUST NOT be truncated. 4177 (Note that this use of the identity KDF is a technicality. The 4178 complete picture is that ECDH is employed with a non-trivial KDF 4179 because TLS does not directly use this secret for anything other than 4180 for computing other secrets.) 4182 ECDH functions are used as follows: 4184 - The public key to put into the KeyShareEntry.key_exchange 4185 structure is the result of applying the ECDH function to the 4186 secret key of appropriate length (into scalar input) and the 4187 standard public basepoint (into u-coordinate point input). 4189 - The ECDH shared secret is the result of applying the ECDH function 4190 to the secret key (into scalar input) and the peer's public key 4191 (into u-coordinate point input). The output is used raw, with no 4192 processing. 4194 For X25519 and X448, implementations SHOULD use the approach 4195 specified in [RFC7748] to calculate the Diffie-Hellman shared secret. 4196 Implementations MUST check whether the computed Diffie-Hellman shared 4197 secret is the all-zero value and abort if so, as described in 4198 Section 6 of [RFC7748]. If implementers use an alternative 4199 implementation of these elliptic curves, they SHOULD perform the 4200 additional checks specified in Section 7 of [RFC7748]. 4202 7.5. Exporters 4204 [RFC5705] defines keying material exporters for TLS in terms of the 4205 TLS pseudorandom function (PRF). This document replaces the PRF with 4206 HKDF, thus requiring a new construction. The exporter interface 4207 remains the same. 4209 The exporter value is computed as: 4211 HKDF-Expand-Label(Derive-Secret(Secret, label, ""), 4212 "exporter", Hash(context_value), key_length) 4214 Where Secret is either the early_exporter_master_secret or the 4215 exporter_master_secret. Implementations MUST use the 4216 exporter_master_secret unless explicitly specified by the 4217 application. The early_exporter_master_secret is define for use in 4218 settings where an exporter is needed for 0-RTT data. A separate 4219 interface for the early exporter is RECOMMENDED, especially on a 4220 server where a single interface can make the early exporter 4221 inaccessible. 4223 If no context is provided, the context_value is zero-length. 4224 Consequently, providing no context computes the same value as 4225 providing an empty context. This is a change from previous versions 4226 of TLS where an empty context produced a different output to an 4227 absent context. As of this document's publication, no allocated 4228 exporter label is used both with and without a context. Future 4229 specifications MUST NOT define a use of exporters that permit both an 4230 empty context and no context with the same label. New uses of 4231 exporters SHOULD provide a context in all exporter computations, 4232 though the value could be empty. 4234 Requirements for the format of exporter labels are defined in section 4235 4 of [RFC5705]. 4237 8. Compliance Requirements 4239 8.1. Mandatory-to-Implement Cipher Suites 4241 In the absence of an application profile standard specifying 4242 otherwise, a TLS-compliant application MUST implement the 4243 TLS_AES_128_GCM_SHA256 [GCM] cipher suite and SHOULD implement the 4244 TLS_AES_256_GCM_SHA384 [GCM] and TLS_CHACHA20_POLY1305_SHA256 4245 [RFC7539] cipher suites. (see Appendix B.4) 4247 A TLS-compliant application MUST support digital signatures with 4248 rsa_pkcs1_sha256 (for certificates), rsa_pss_sha256 (for 4249 CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A 4250 TLS-compliant application MUST support key exchange with secp256r1 4251 (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748]. 4253 8.2. Mandatory-to-Implement Extensions 4255 In the absence of an application profile standard specifying 4256 otherwise, a TLS-compliant application MUST implement the following 4257 TLS extensions: 4259 - Supported Versions ("supported_versions"; Section 4.2.1) 4261 - Cookie ("cookie"; Section 4.2.2) 4263 - Signature Algorithms ("signature_algorithms"; Section 4.2.3) 4265 - Negotiated Groups ("supported_groups"; Section 4.2.6) 4267 - Key Share ("key_share"; Section 4.2.7) 4269 - Server Name Indication ("server_name"; Section 3 of [RFC6066]) 4271 All implementations MUST send and use these extensions when offering 4272 applicable features: 4274 - "supported_versions" is REQUIRED for all ClientHello messages. 4276 - "signature_algorithms" is REQUIRED for certificate authentication. 4278 - "supported_groups" and "key_share" are REQUIRED for DHE or ECDHE 4279 key exchange. 4281 - "pre_shared_key" is REQUIRED for PSK key agreement. 4283 A client is considered to be attempting to negotiate using this 4284 specification if the ClientHello contains a "supported_versions" 4285 extension 0x0304 the highest version number contained in its body. 4286 Such a ClientHello message MUST meet the following requirements: 4288 - If not containing a "pre_shared_key" extension, it MUST contain 4289 both a "signature_algorithms" extension and a "supported_groups" 4290 extension. 4292 - If containing a "supported_groups" extension, it MUST also contain 4293 a "key_share" extension, and vice versa. An empty 4294 KeyShare.client_shares vector is permitted. 4296 Servers receiving a ClientHello which does not conform to these 4297 requirements MUST abort the handshake with a "missing_extension" 4298 alert. 4300 Additionally, all implementations MUST support use of the 4301 "server_name" extension with applications capable of using it. 4302 Servers MAY require clients to send a valid "server_name" extension. 4303 Servers requiring this extension SHOULD respond to a ClientHello 4304 lacking a "server_name" extension by terminating the connection with 4305 a "missing_extension" alert. 4307 9. Security Considerations 4309 Security issues are discussed throughout this memo, especially in 4310 Appendix C, Appendix D, and Appendix E. 4312 10. IANA Considerations 4314 This document uses several registries that were originally created in 4315 [RFC4346]. IANA has updated these to reference this document. The 4316 registries and their allocation policies are below: 4318 - TLS Cipher Suite Registry: Values with the first byte in the range 4319 0-254 (decimal) are assigned via Specification Required [RFC5226]. 4320 Values with the first byte 255 (decimal) are reserved for Private 4321 Use [RFC5226]. 4323 IANA [SHALL add/has added] the cipher suites listed in 4324 Appendix B.4 to the registry. The "Value" and "Description" 4325 columns are taken from the table. The "DTLS-OK" and "Recommended" 4326 columns are both marked as "Yes" for each new cipher suite. 4327 [[This assumes [I-D.ietf-tls-iana-registry-updates] has been 4328 applied.]] 4330 - TLS ContentType Registry: Future values are allocated via 4331 Standards Action [RFC5226]. 4333 - TLS Alert Registry: Future values are allocated via Standards 4334 Action [RFC5226]. IANA [SHALL update/has updated] this registry 4335 to include values for "missing_extension" and 4336 "certificate_required". 4338 - TLS HandshakeType Registry: Future values are allocated via 4339 Standards Action [RFC5226]. IANA [SHALL update/has updated] this 4340 registry to rename item 4 from "NewSessionTicket" to 4341 "new_session_ticket" and to add the "hello_retry_request", 4342 "encrypted_extensions", "end_of_early_data", "key_update", and 4343 "handshake_hash" values. 4345 This document also uses the TLS ExtensionType Registry originally 4346 created in [RFC4366]. IANA has updated it to reference this 4347 document. The registry and its allocation policy is listed below: 4349 - IANA [SHALL update/has updated] this registry to include the 4350 "key_share", "pre_shared_key", "psk_key_exchange_modes", 4351 "early_data", "cookie", "supported_versions", 4352 "certificate_authorities", "oid_filters", and 4353 "post_handshake_auth" extensions with the values defined in this 4354 document and the Recommended value of "Yes". 4356 - IANA [SHALL update/has updated] this registry to include a "TLS 4357 1.3" column which lists the messages in which the extension may 4358 appear. This column [SHALL be/has been] initially populated from 4359 the table in Section 4.2 with any extension not listed there 4360 marked as "-" to indicate that it is not used by TLS 1.3. 4362 In addition, this document defines a new registry to be maintained by 4363 IANA: 4365 - TLS SignatureScheme Registry: Values with the first byte in the 4366 range 0-254 (decimal) are assigned via Specification Required 4367 [RFC5226]. Values with the first byte 255 (decimal) are reserved 4368 for Private Use [RFC5226]. Values with the first byte in the 4369 range 0-6 or with the second byte in the range 0-3 that are not 4370 currently allocated are reserved for backwards compatibility. 4371 This registry SHALL have a "Recommended" column. The registry 4372 [shall be/ has been] initially populated with the values described 4373 in Section 4.2.3. The following values SHALL be marked as 4374 "Recommended": ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, 4375 rsa_pss_sha256, rsa_pss_sha384, rsa_pss_sha512, ed25519. 4377 11. References 4379 11.1. Normative References 4381 [DH] Diffie, W. and M. Hellman, "New Directions in 4382 Cryptography", IEEE Transactions on Information Theory, 4383 V.IT-22 n.6 , June 1977. 4385 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 4386 Operation: Galois/Counter Mode (GCM) and GMAC", 4387 NIST Special Publication 800-38D, November 2007. 4389 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4390 Hashing for Message Authentication", RFC 2104, 4391 DOI 10.17487/RFC2104, February 1997, 4392 . 4394 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4395 Requirement Levels", BCP 14, RFC 2119, 4396 DOI 10.17487/RFC2119, March 1997, 4397 . 4399 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4400 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 4401 DOI 10.17487/RFC5226, May 2008, 4402 . 4404 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4405 Housley, R., and W. Polk, "Internet X.509 Public Key 4406 Infrastructure Certificate and Certificate Revocation List 4407 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4408 . 4410 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 4411 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 4412 March 2010, . 4414 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 4415 Key Derivation Function (HKDF)", RFC 5869, 4416 DOI 10.17487/RFC5869, May 2010, 4417 . 4419 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4420 Extensions: Extension Definitions", RFC 6066, 4421 DOI 10.17487/RFC6066, January 2011, 4422 . 4424 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4425 Transport Layer Security (TLS)", RFC 6655, 4426 DOI 10.17487/RFC6655, July 2012, 4427 . 4429 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 4430 Galperin, S., and C. Adams, "X.509 Internet Public Key 4431 Infrastructure Online Certificate Status Protocol - OCSP", 4432 RFC 6960, DOI 10.17487/RFC6960, June 2013, 4433 . 4435 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 4436 Multiple Certificate Status Request Extension", RFC 6961, 4437 DOI 10.17487/RFC6961, June 2013, 4438 . 4440 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 4441 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 4442 . 4444 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4445 Algorithm (DSA) and Elliptic Curve Digital Signature 4446 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4447 2013, . 4449 [RFC7507] Moeller, B. and A. Langley, "TLS Fallback Signaling Cipher 4450 Suite Value (SCSV) for Preventing Protocol Downgrade 4451 Attacks", RFC 7507, DOI 10.17487/RFC7507, April 2015, 4452 . 4454 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 4455 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 4456 . 4458 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 4459 for Security", RFC 7748, DOI 10.17487/RFC7748, January 4460 2016, . 4462 [RFC7919] Gillmor, D., "Negotiated Finite Field Diffie-Hellman 4463 Ephemeral Parameters for Transport Layer Security (TLS)", 4464 RFC 7919, DOI 10.17487/RFC7919, August 2016, 4465 . 4467 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 4468 "PKCS #1: RSA Cryptography Specifications Version 2.2", 4469 RFC 8017, DOI 10.17487/RFC8017, November 2016, 4470 . 4472 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 4473 Signature Algorithm (EdDSA)", RFC 8032, 4474 DOI 10.17487/RFC8032, January 2017, 4475 . 4477 [SHS] National Institute of Standards and Technology, U.S. 4478 Department of Commerce, "Secure Hash Standard", NIST FIPS 4479 PUB 180-4, March 2012. 4481 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 4482 Specification of Basic Encoding Rules (BER), Canonical 4483 Encoding Rules (CER) and Distinguished Encoding Rules 4484 (DER)", ISO/IEC 8825-1:2002, 2002. 4486 [X962] ANSI, "Public Key Cryptography For The Financial Services 4487 Industry: The Elliptic Curve Digital Signature Algorithm 4488 (ECDSA)", ANSI X9.62, 1998. 4490 11.2. Informative References 4492 [AEAD-LIMITS] 4493 Luykx, A. and K. Paterson, "Limits on Authenticated 4494 Encryption Use in TLS", 2016, 4495 . 4497 [BBFKZG16] 4498 Bhargavan, K., Brzuska, C., Fournet, C., Kohlweiss, M., 4499 Zanella-Beguelin, S., and M. Green, "Downgrade Resilience 4500 in Key-Exchange Protocols", Proceedings of IEEE Symposium 4501 on Security and Privacy (Oakland) 2016 , 2016. 4503 [BBK17] Bhargavan, K., Blanchet, B., and N. Kobeissi, "Verified 4504 Models and Reference Implementations for the TLS 1.3 4505 Standard Candidate", Proceedings of IEEE Symposium on 4506 Security and Privacy (Oakland) 2017 , 2017. 4508 [BDFKPPRSZZ16] 4509 Bhargavan, K., Delignat-Lavaud, A., Fournet, C., 4510 Kohlweiss, M., Pan, J., Protzenko, J., Rastogi, A., Swamy, 4511 N., Zanella-Beguelin, S., and J. Zinzindohoue, 4512 "Implementing and Proving the TLS 1.3 Record Layer", 4513 Proceedings of IEEE Symposium on Security and Privacy 4514 (Oakland) 2017 , December 2016, 4515 . 4517 [BMMT15] Badertscher, C., Matt, C., Maurer, U., and B. Tackmann, 4518 "Augmented Secure Channels and the Goal of the TLS 1.3 4519 Record Layer", ProvSec 2015 , September 2015, 4520 . 4522 [BT16] Bellare, M. and B. Tackmann, "The Multi-User Security of 4523 Authenticated Encryption: AES-GCM in TLS 1.3", Proceedings 4524 of CRYPTO 2016 , 2016, . 4526 [CCG16] Cohn-Gordon, K., Cremers, C., and L. Garratt, "On Post- 4527 Compromise Security", IEEE Computer Security Foundations 4528 Symposium , 2015. 4530 [CHHSV17] Cremers, C., Horvat, M., Hoyland, J., van der Merwe, T., 4531 and S. Scott, "Awkward Handshake: Possible mismatch of 4532 client/server view on client authentication in post- 4533 handshake mode in Revision 18", 2017, 4534 . 4537 [CHSV16] Cremers, C., Horvat, M., Scott, S., and T. van der Merwe, 4538 "Automated Analysis and Verification of TLS 1.3: 0-RTT, 4539 Resumption and Delayed Authentication", Proceedings of 4540 IEEE Symposium on Security and Privacy (Oakland) 2016 , 4541 2016, . 4543 [CK01] Canetti, R. and H. Krawczyk, "Analysis of Key-Exchange 4544 Protocols and Their Use for Building Secure Channels", 4545 Proceedings of Eurocrypt 2001 , 2001. 4547 [CLINIC] Miller, B., Huang, L., Joseph, A., and J. Tygar, "I Know 4548 Why You Went to the Clinic: Risks and Realization of HTTPS 4549 Traffic Analysis", Privacy Enhancing Technologies pp. 4550 143-163, DOI 10.1007/978-3-319-08506-7_8, 2014. 4552 [DFGS15] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 4553 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 4554 Pre-shared Key Handshake Protocol", Proceedings of ACM CCS 4555 2015 , 2015, . 4557 [DFGS16] Dowling, B., Fischlin, M., Guenther, F., and D. Stebila, 4558 "A Cryptographic Analysis of the TLS 1.3 draft-10 Full and 4559 Pre-shared Key Handshake Protocol", TRON 2016 , 2016, 4560 . 4562 [DOW92] Diffie, W., van Oorschot, P., and M. Wiener, 4563 ""Authentication and authenticated key exchanges"", 4564 Designs, Codes and Cryptography , 1992. 4566 [DSS] National Institute of Standards and Technology, U.S. 4567 Department of Commerce, "Digital Signature Standard, 4568 version 4", NIST FIPS PUB 186-4, 2013. 4570 [ECDSA] American National Standards Institute, "Public Key 4571 Cryptography for the Financial Services Industry: The 4572 Elliptic Curve Digital Signature Algorithm (ECDSA)", 4573 ANSI ANS X9.62-2005, November 2005. 4575 [FG17] Fischlin, M. and F. Guenther, "Replay Attacks on Zero 4576 Round-Trip Time: The Case of the TLS 1.3 Handshake 4577 Candidates", Proceedings of Euro S"P 2017 , 2017, 4578 . 4580 [FGSW16] Fischlin, M., Guenther, F., Schmidt, B., and B. Warinschi, 4581 "Key Confirmation in Key Exchange: A Formal Treatment and 4582 Implications for TLS 1.3", Proceedings of IEEE Symposium 4583 on Security and Privacy (Oakland) 2016 , 2016, 4584 . 4586 [FW15] Florian Weimer, ., "Factoring RSA Keys With TLS Perfect 4587 Forward Secrecy", September 2015. 4589 [HCJ16] Husak, M., Čermak, M., Jirsik, T., and P. 4590 Čeleda, "HTTPS traffic analysis and client 4591 identification using passive SSL/TLS fingerprinting", 4592 EURASIP Journal on Information Security Vol. 2016, 4593 DOI 10.1186/s13635-016-0030-7, February 2016. 4595 [HGFS15] Hlauschek, C., Gruber, M., Fankhauser, F., and C. Schanes, 4596 "Prying Open Pandora's Box: KCI Attacks against TLS", 4597 Proceedings of USENIX Workshop on Offensive Technologies , 4598 2015. 4600 [I-D.ietf-tls-iana-registry-updates] 4601 Salowey, J. and S. Turner, "D/TLS IANA Registry Updates", 4602 draft-ietf-tls-iana-registry-updates-01 (work in 4603 progress), April 2017. 4605 [I-D.ietf-tls-tls13-vectors] 4606 Thomson, M., "Example Handshake Traces for TLS 1.3", 4607 draft-ietf-tls-tls13-vectors-00 (work in progress), 4608 January 2017. 4610 [IEEE1363] 4611 IEEE, "Standard Specifications for Public Key 4612 Cryptography", IEEE 1363 , 2000. 4614 [KEYAGREEMENT] 4615 Barker, E., Lily Chen, ., Roginsky, A., and M. Smid, 4616 "Recommendation for Pair-Wise Key Establishment Schemes 4617 Using Discrete Logarithm Cryptography", NIST Special 4618 Publication 800-38D, May 2013. 4620 [Kraw10] Krawczyk, H., "Cryptographic Extraction and Key 4621 Derivation: The HKDF Scheme", Proceedings of CRYPTO 2010 , 4622 2010, . 4624 [Kraw16] Krawczyk, H., "A Unilateral-to-Mutual Authentication 4625 Compiler for Key Exchange (with Applications to Client 4626 Authentication in TLS 1.3", Proceedings of ACM CCS 2016 , 4627 2016, . 4629 [KW16] Krawczyk, H. and H. Wee, "The OPTLS Protocol and TLS 1.3", 4630 Proceedings of Euro S"P 2016 , 2016, 4631 . 4633 [LXZFH16] Li, X., Xu, J., Feng, D., Zhang, Z., and H. Hu, "Multiple 4634 Handshakes Security of TLS 1.3 Candidates", Proceedings of 4635 IEEE Symposium on Security and Privacy (Oakland) 2016 , 4636 2016, . 4638 [PSK-FINISHED] 4639 Cremers, C., Horvat, M., van der Merwe, T., and S. Scott, 4640 "Revision 10: possible attack if client authentication is 4641 allowed during PSK", 2015, . 4644 [REKEY] Abdalla, M. and M. Bellare, "Increasing the Lifetime of a 4645 Key: A Comparative Analysis of the Security of Re-keying 4646 Techniques", ASIACRYPT2000 , October 2000. 4648 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 4649 Text on Security Considerations", BCP 72, RFC 3552, 4650 DOI 10.17487/RFC3552, July 2003, 4651 . 4653 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 4654 "Randomness Requirements for Security", BCP 106, RFC 4086, 4655 DOI 10.17487/RFC4086, June 2005, 4656 . 4658 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 4659 (TLS) Protocol Version 1.1", RFC 4346, 4660 DOI 10.17487/RFC4346, April 2006, 4661 . 4663 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 4664 and T. Wright, "Transport Layer Security (TLS) 4665 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006, 4666 . 4668 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4669 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4670 for Transport Layer Security (TLS)", RFC 4492, 4671 DOI 10.17487/RFC4492, May 2006, 4672 . 4674 [RFC4681] Santesson, S., Medvinsky, A., and J. Ball, "TLS User 4675 Mapping Extension", RFC 4681, DOI 10.17487/RFC4681, 4676 October 2006, . 4678 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 4679 "Transport Layer Security (TLS) Session Resumption without 4680 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 4681 January 2008, . 4683 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 4684 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 4685 . 4687 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4688 (TLS) Protocol Version 1.2", RFC 5246, 4689 DOI 10.17487/RFC5246, August 2008, 4690 . 4692 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 4693 Security (DTLS) Extension to Establish Keys for the Secure 4694 Real-time Transport Protocol (SRTP)", RFC 5764, 4695 DOI 10.17487/RFC5764, May 2010, 4696 . 4698 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 4699 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010, 4700 . 4702 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys 4703 for Transport Layer Security (TLS) Authentication", 4704 RFC 6091, DOI 10.17487/RFC6091, February 2011, 4705 . 4707 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 4708 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176, March 4709 2011, . 4711 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4712 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4713 January 2012, . 4715 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 4716 Layer Security (TLS) and Datagram Transport Layer Security 4717 (DTLS) Heartbeat Extension", RFC 6520, 4718 DOI 10.17487/RFC6520, February 2012, 4719 . 4721 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 4722 Protocol (HTTP/1.1): Message Syntax and Routing", 4723 RFC 7230, DOI 10.17487/RFC7230, June 2014, 4724 . 4726 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4727 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4728 Transport Layer Security (TLS) and Datagram Transport 4729 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4730 June 2014, . 4732 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 4733 "Transport Layer Security (TLS) Application-Layer Protocol 4734 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 4735 July 2014, . 4737 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 4738 DOI 10.17487/RFC7465, February 2015, 4739 . 4741 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 4742 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 4743 DOI 10.17487/RFC7568, June 2015, 4744 . 4746 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 4747 Langley, A., and M. Ray, "Transport Layer Security (TLS) 4748 Session Hash and Extended Master Secret Extension", 4749 RFC 7627, DOI 10.17487/RFC7627, September 2015, 4750 . 4752 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello 4753 Padding Extension", RFC 7685, DOI 10.17487/RFC7685, 4754 October 2015, . 4756 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4757 (TLS) Cached Information Extension", RFC 7924, 4758 DOI 10.17487/RFC7924, July 2016, 4759 . 4761 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 4762 Obtaining Digital Signatures and Public-Key 4763 Cryptosystems", Communications of the ACM v. 21, n. 2, pp. 4764 120-126., February 1978. 4766 [SIGMA] Krawczyk, H., "SIGMA: the 'SIGn-and-MAc' approach to 4767 authenticated Diffie-Hellman and its use in the IKE 4768 protocols", Proceedings of CRYPTO 2003 , 2003. 4770 [SLOTH] Bhargavan, K. and G. Leurent, "Transcript Collision 4771 Attacks: Breaking Authentication in TLS, IKE, and SSH", 4772 Network and Distributed System Security Symposium (NDSS 4773 2016) , 2016. 4775 [SSL2] Hickman, K., "The SSL Protocol", February 1995. 4777 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 4778 Protocol", November 1996. 4780 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 4781 practical", USENIX Security Symposium, 2003. 4783 [X501] "Information Technology - Open Systems Interconnection - 4784 The Directory: Models", ITU-T X.501, 1993. 4786 11.3. URIs 4788 [1] mailto:tls@ietf.org 4790 Appendix A. State Machine 4792 This section provides a summary of the legal state transitions for 4793 the client and server handshakes. State names (in all capitals, 4794 e.g., START) have no formal meaning but are provided for ease of 4795 comprehension. Messages which are sent only sometimes are indicated 4796 in []. 4798 A.1. Client 4800 START <----+ 4801 Send ClientHello | | Recv HelloRetryRequest 4802 / v | 4803 | WAIT_SH ---+ 4804 Can | | Recv ServerHello 4805 send | V 4806 early | WAIT_EE 4807 data | | Recv EncryptedExtensions 4808 | +--------+--------+ 4809 | Using | | Using certificate 4810 | PSK | v 4811 | | WAIT_CERT_CR 4812 | | Recv | | Recv CertificateRequest 4813 | | Certificate | v 4814 | | | WAIT_CERT 4815 | | | | Recv Certificate 4816 | | v v 4817 | | WAIT_CV 4818 | | | Recv CertificateVerify 4819 | +> WAIT_FINISHED <+ 4820 | | Recv Finished 4821 \ | 4822 | [Send EndOfEarlyData] 4823 | [Send Certificate [+ CertificateVerify]] 4824 | Send Finished 4825 Can send v 4826 app data --> CONNECTED 4827 after 4828 here 4830 A.2. Server 4831 START <-----+ 4832 Recv ClientHello | | Send HelloRetryRequest 4833 v | 4834 RECVD_CH ----+ 4835 | Select parameters 4836 v 4837 NEGOTIATED 4838 | Send ServerHello 4839 | Send EncryptedExtensions 4840 | [Send CertificateRequest] 4841 Can send | [Send Certificate + CertificateVerify] 4842 app data --> | Send Finished 4843 after +--------+--------+ 4844 here No 0-RTT | | 0-RTT 4845 | v 4846 | WAIT_EOED <---+ 4847 | Recv | | | Recv 4848 | EndOfEarlyData | | | early data 4849 | | +-----+ 4850 +> WAIT_FLIGHT2 <-+ 4851 | 4852 +--------+--------+ 4853 No auth | | Client auth 4854 | | 4855 | v 4856 | WAIT_CERT 4857 | Recv | | Recv Certificate 4858 | empty | v 4859 | Certificate | WAIT_CV 4860 | | | Recv 4861 | v | CertificateVerify 4862 +-> WAIT_FINISHED <---+ 4863 | Recv Finished 4864 v 4865 CONNECTED 4867 Appendix B. Protocol Data Structures and Constant Values 4869 This section describes protocol types and constants. Values listed 4870 as _RESERVED were used in previous versions of TLS and are listed 4871 here for completeness. TLS 1.3 implementations MUST NOT send them 4872 but might receive them from older TLS implementations. 4874 B.1. Record Layer 4875 enum { 4876 invalid(0), 4877 change_cipher_spec_RESERVED(20), 4878 alert(21), 4879 handshake(22), 4880 application_data(23), 4881 (255) 4882 } ContentType; 4884 struct { 4885 ContentType type; 4886 ProtocolVersion legacy_record_version; 4887 uint16 length; 4888 opaque fragment[TLSPlaintext.length]; 4889 } TLSPlaintext; 4891 struct { 4892 opaque content[TLSPlaintext.length]; 4893 ContentType type; 4894 uint8 zeros[length_of_padding]; 4895 } TLSInnerPlaintext; 4897 struct { 4898 ContentType opaque_type = 23; /* application_data */ 4899 ProtocolVersion legacy_record_version = 0x0301; /* TLS v1.x */ 4900 uint16 length; 4901 opaque encrypted_record[length]; 4902 } TLSCiphertext; 4904 B.2. Alert Messages 4905 enum { warning(1), fatal(2), (255) } AlertLevel; 4907 enum { 4908 close_notify(0), 4909 unexpected_message(10), 4910 bad_record_mac(20), 4911 decryption_failed_RESERVED(21), 4912 record_overflow(22), 4913 decompression_failure_RESERVED(30), 4914 handshake_failure(40), 4915 no_certificate_RESERVED(41), 4916 bad_certificate(42), 4917 unsupported_certificate(43), 4918 certificate_revoked(44), 4919 certificate_expired(45), 4920 certificate_unknown(46), 4921 illegal_parameter(47), 4922 unknown_ca(48), 4923 access_denied(49), 4924 decode_error(50), 4925 decrypt_error(51), 4926 export_restriction_RESERVED(60), 4927 protocol_version(70), 4928 insufficient_security(71), 4929 internal_error(80), 4930 inappropriate_fallback(86), 4931 user_canceled(90), 4932 no_renegotiation_RESERVED(100), 4933 missing_extension(109), 4934 unsupported_extension(110), 4935 certificate_unobtainable(111), 4936 unrecognized_name(112), 4937 bad_certificate_status_response(113), 4938 bad_certificate_hash_value(114), 4939 unknown_psk_identity(115), 4940 certificate_required(116), 4941 no_application_protocol(120), 4942 (255) 4943 } AlertDescription; 4945 struct { 4946 AlertLevel level; 4947 AlertDescription description; 4948 } Alert; 4950 B.3. Handshake Protocol 4952 enum { 4953 hello_request_RESERVED(0), 4954 client_hello(1), 4955 server_hello(2), 4956 hello_verify_request_RESERVED(3), 4957 new_session_ticket(4), 4958 end_of_early_data(5), 4959 hello_retry_request(6), 4960 encrypted_extensions(8), 4961 certificate(11), 4962 server_key_exchange_RESERVED(12), 4963 certificate_request(13), 4964 server_hello_done_RESERVED(14), 4965 certificate_verify(15), 4966 client_key_exchange_RESERVED(16), 4967 finished(20), 4968 key_update(24), 4969 message_hash(254), 4970 (255) 4971 } HandshakeType; 4973 struct { 4974 HandshakeType msg_type; /* handshake type */ 4975 uint24 length; /* bytes in message */ 4976 select (Handshake.msg_type) { 4977 case client_hello: ClientHello; 4978 case server_hello: ServerHello; 4979 case end_of_early_data: EndOfEarlyData; 4980 case hello_retry_request: HelloRetryRequest; 4981 case encrypted_extensions: EncryptedExtensions; 4982 case certificate_request: CertificateRequest; 4983 case certificate: Certificate; 4984 case certificate_verify: CertificateVerify; 4985 case finished: Finished; 4986 case new_session_ticket: NewSessionTicket; 4987 case key_update: KeyUpdate; 4988 } body; 4989 } Handshake; 4991 B.3.1. Key Exchange Messages 4993 uint16 ProtocolVersion; 4994 opaque Random[32]; 4996 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 4997 struct { 4998 ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ 4999 Random random; 5000 opaque legacy_session_id<0..32>; 5001 CipherSuite cipher_suites<2..2^16-2>; 5002 opaque legacy_compression_methods<1..2^8-1>; 5003 Extension extensions<8..2^16-1>; 5004 } ClientHello; 5006 struct { 5007 ProtocolVersion version; 5008 Random random; 5009 CipherSuite cipher_suite; 5010 Extension extensions<6..2^16-1>; 5011 } ServerHello; 5013 struct { 5014 ProtocolVersion server_version; 5015 CipherSuite cipher_suite; 5016 Extension extensions<2..2^16-1>; 5017 } HelloRetryRequest; 5019 struct { 5020 ExtensionType extension_type; 5021 opaque extension_data<0..2^16-1>; 5022 } Extension; 5024 enum { 5025 server_name(0), /* RFC 6066 */ 5026 max_fragment_length(1), /* RFC 6066 */ 5027 status_request(5), /* RFC 6066 */ 5028 supported_groups(10), /* RFC 4492, 7919 */ 5029 signature_algorithms(13), /* RFC 5246 */ 5030 use_srtp(14), /* RFC 5764 */ 5031 heartbeat(15), /* RFC 6520 */ 5032 application_layer_protocol_negotiation(16), /* RFC 7301 */ 5033 signed_certificate_timestamp(18), /* RFC 6962 */ 5034 client_certificate_type(19), /* RFC 7250 */ 5035 server_certificate_type(20) /* RFC 7250 */ 5036 padding(21), /* RFC 7685 */ 5037 key_share(40), /* [[this document]] */ 5038 pre_shared_key(41), /* [[this document]] */ 5039 early_data(42), /* [[this document]] */ 5040 supported_versions(43), /* [[this document]] */ 5041 cookie(44), /* [[this document]] */ 5042 psk_key_exchange_modes(45), /* [[this document]] */ 5043 certificate_authorities(47), /* [[this document]] */ 5044 oid_filters(48), /* [[this document]] */ 5045 post_handshake_auth(49), /* [[this document]] */ 5046 (65535) 5047 } ExtensionType; 5049 struct { 5050 NamedGroup group; 5051 opaque key_exchange<1..2^16-1>; 5052 } KeyShareEntry; 5054 struct { 5055 select (Handshake.msg_type) { 5056 case client_hello: 5057 KeyShareEntry client_shares<0..2^16-1>; 5059 case hello_retry_request: 5060 NamedGroup selected_group; 5062 case server_hello: 5063 KeyShareEntry server_share; 5064 }; 5065 } KeyShare; 5067 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 5069 struct { 5070 PskKeyExchangeMode ke_modes<1..255>; 5071 } PskKeyExchangeModes; 5073 struct {} Empty; 5075 struct { 5076 select (Handshake.msg_type) { 5077 case new_session_ticket: uint32 max_early_data_size; 5078 case client_hello: Empty; 5079 case encrypted_extensions: Empty; 5080 }; 5081 } EarlyDataIndication; 5083 struct { 5084 opaque identity<1..2^16-1>; 5085 uint32 obfuscated_ticket_age; 5086 } PskIdentity; 5088 opaque PskBinderEntry<32..255>; 5090 struct { 5091 select (Handshake.msg_type) { 5092 case client_hello: 5094 PskIdentity identities<7..2^16-1>; 5095 PskBinderEntry binders<33..2^16-1>; 5097 case server_hello: 5098 uint16 selected_identity; 5099 }; 5101 } PreSharedKeyExtension; 5103 B.3.1.1. Version Extension 5105 struct { 5106 ProtocolVersion versions<2..254>; 5107 } SupportedVersions; 5109 B.3.1.2. Cookie Extension 5111 struct { 5112 opaque cookie<1..2^16-1>; 5113 } Cookie; 5115 B.3.1.3. Signature Algorithm Extension 5116 enum { 5117 /* RSASSA-PKCS1-v1_5 algorithms */ 5118 rsa_pkcs1_sha256(0x0401), 5119 rsa_pkcs1_sha384(0x0501), 5120 rsa_pkcs1_sha512(0x0601), 5122 /* ECDSA algorithms */ 5123 ecdsa_secp256r1_sha256(0x0403), 5124 ecdsa_secp384r1_sha384(0x0503), 5125 ecdsa_secp521r1_sha512(0x0603), 5127 /* RSASSA-PSS algorithms */ 5128 rsa_pss_sha256(0x0804), 5129 rsa_pss_sha384(0x0805), 5130 rsa_pss_sha512(0x0806), 5132 /* EdDSA algorithms */ 5133 ed25519(0x0807), 5134 ed448(0x0808), 5136 /* Legacy algorithms */ 5137 rsa_pkcs1_sha1(0x0201), 5138 ecdsa_sha1(0x0203), 5140 /* Reserved Code Points */ 5141 obsolete_RESERVED(0x0000..0x0200), 5142 dsa_sha1_RESERVED(0x0202), 5143 obsolete_RESERVED(0x0204..0x0400), 5144 dsa_sha256_RESERVED(0x0402), 5145 obsolete_RESERVED(0x0404..0x0500), 5146 dsa_sha384_RESERVED(0x0502), 5147 obsolete_RESERVED(0x0504..0x0600), 5148 dsa_sha512_RESERVED(0x0602), 5149 obsolete_RESERVED(0x0604..0x06FF), 5150 private_use(0xFE00..0xFFFF), 5151 (0xFFFF) 5152 } SignatureScheme; 5154 struct { 5155 SignatureScheme supported_signature_algorithms<2..2^16-2>; 5156 } SignatureSchemeList; 5158 B.3.1.4. Supported Groups Extension 5159 enum { 5160 /* Elliptic Curve Groups (ECDHE) */ 5161 obsolete_RESERVED(0x0001..0x0016), 5162 secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 5163 obsolete_RESERVED(0x001A..0x001C), 5164 x25519(0x001D), x448(0x001E), 5166 /* Finite Field Groups (DHE) */ 5167 ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096 (0x0102), 5168 ffdhe6144(0x0103), ffdhe8192(0x0104), 5170 /* Reserved Code Points */ 5171 ffdhe_private_use(0x01FC..0x01FF), 5172 ecdhe_private_use(0xFE00..0xFEFF), 5173 obsolete_RESERVED(0xFF01..0xFF02), 5174 (0xFFFF) 5175 } NamedGroup; 5177 struct { 5178 NamedGroup named_group_list<2..2^16-1>; 5179 } NamedGroupList; 5181 Values within "obsolete_RESERVED" ranges are used in previous 5182 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3 5183 implementations. The obsolete curves have various known/theoretical 5184 weaknesses or have had very little usage, in some cases only due to 5185 unintentional server configuration issues. They are no longer 5186 considered appropriate for general use and should be assumed to be 5187 potentially unsafe. The set of curves specified here is sufficient 5188 for interoperability with all currently deployed and properly 5189 configured TLS implementations. 5191 B.3.2. Server Parameters Messages 5192 opaque DistinguishedName<1..2^16-1>; 5194 struct { 5195 DistinguishedName authorities<3..2^16-1>; 5196 } CertificateAuthoritiesExtension; 5198 struct { 5199 Extension extensions<0..2^16-1>; 5200 } EncryptedExtensions; 5202 struct { 5203 opaque certificate_request_context<0..2^8-1>; 5204 Extension extensions<2..2^16-1>; 5205 } CertificateRequest; 5207 struct { 5208 opaque certificate_extension_oid<1..2^8-1>; 5209 opaque certificate_extension_values<0..2^16-1>; 5210 } OIDFilter; 5212 struct { 5213 OIDFilter filters<0..2^16-1>; 5214 } OIDFilterExtension; 5216 B.3.3. Authentication Messages 5217 struct { 5218 select(certificate_type){ 5219 case RawPublicKey: 5220 // From RFC 7250 ASN.1_subjectPublicKeyInfo 5221 opaque ASN1_subjectPublicKeyInfo<1..2^24-1>; 5223 case X.509: 5224 opaque cert_data<1..2^24-1>; 5225 } 5226 Extension extensions<0..2^16-1>; 5227 } CertificateEntry; 5229 struct { 5230 opaque certificate_request_context<0..2^8-1>; 5231 CertificateEntry certificate_list<0..2^24-1>; 5232 } Certificate; 5234 struct { 5235 SignatureScheme algorithm; 5236 opaque signature<0..2^16-1>; 5237 } CertificateVerify; 5239 struct { 5240 opaque verify_data[Hash.length]; 5241 } Finished; 5243 B.3.4. Ticket Establishment 5245 struct { 5246 uint32 ticket_lifetime; 5247 uint32 ticket_age_add; 5248 opaque ticket<1..2^16-1>; 5249 Extension extensions<0..2^16-2>; 5250 } NewSessionTicket; 5252 B.3.5. Updating Keys 5254 struct {} EndOfEarlyData; 5256 enum { 5257 update_not_requested(0), update_requested(1), (255) 5258 } KeyUpdateRequest; 5260 struct { 5261 KeyUpdateRequest request_update; 5262 } KeyUpdate; 5264 B.4. Cipher Suites 5266 A symmetric cipher suite defines the pair of the AEAD algorithm and 5267 hash algorithm to be used with HKDF. Cipher suite names follow the 5268 naming convention: 5270 CipherSuite TLS_AEAD_HASH = VALUE; 5272 +-----------+------------------------------------------------+ 5273 | Component | Contents | 5274 +-----------+------------------------------------------------+ 5275 | TLS | The string "TLS" | 5276 | | | 5277 | AEAD | The AEAD algorithm used for record protection | 5278 | | | 5279 | HASH | The hash algorithm used with HKDF | 5280 | | | 5281 | VALUE | The two byte ID assigned for this cipher suite | 5282 +-----------+------------------------------------------------+ 5284 This specification defines the following cipher suites for use with 5285 TLS 1.3. 5287 +------------------------------+-------------+ 5288 | Description | Value | 5289 +------------------------------+-------------+ 5290 | TLS_AES_128_GCM_SHA256 | {0x13,0x01} | 5291 | | | 5292 | TLS_AES_256_GCM_SHA384 | {0x13,0x02} | 5293 | | | 5294 | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} | 5295 | | | 5296 | TLS_AES_128_CCM_SHA256 | {0x13,0x04} | 5297 | | | 5298 | TLS_AES_128_CCM_8_SHA256 | {0x13,0x05} | 5299 +------------------------------+-------------+ 5301 The corresponding AEAD algorithms AEAD_AES_128_GCM, AEAD_AES_256_GCM, 5302 and AEAD_AES_128_CCM are defined in [RFC5116]. 5303 AEAD_CHACHA20_POLY1305 is defined in [RFC7539]. AEAD_AES_128_CCM_8 5304 is defined in [RFC6655]. The corresponding hash algorithms are 5305 defined in [SHS]. 5307 Although TLS 1.3 uses the same cipher suite space as previous 5308 versions of TLS, TLS 1.3 cipher suites are defined differently, only 5309 specifying the symmetric ciphers, and cannot be used for TLS 1.2. 5310 Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 5311 1.3. 5313 New cipher suite values are assigned by IANA as described in 5314 Section 10. 5316 Appendix C. Implementation Notes 5318 The TLS protocol cannot prevent many common security mistakes. This 5319 section provides several recommendations to assist implementors. 5320 [I-D.ietf-tls-tls13-vectors] provides test vectors for TLS 1.3 5321 handshakes. 5323 C.1. API considerations for 0-RTT 5325 0-RTT data has very different security properties from data 5326 transmitted after a completed handshake: it can be replayed. 5327 Implementations SHOULD provide different functions for reading and 5328 writing 0-RTT data and data transmitted after the handshake, and 5329 SHOULD NOT automatically resend 0-RTT data if it is rejected by the 5330 server. 5332 C.2. Random Number Generation and Seeding 5334 TLS requires a cryptographically secure pseudorandom number generator 5335 (PRNG). In most cases, the operating system provides an appropriate 5336 facility such as /dev/urandom, which should be used absent other 5337 (performance) concerns. It is generally preferable to use an 5338 existing PRNG implementation in preference to crafting a new one, and 5339 many adequate cryptographic libraries are already available under 5340 favorable license terms. Should those prove unsatisfactory, 5341 [RFC4086] provides guidance on the generation of random values. 5343 C.3. Certificates and Authentication 5345 Implementations are responsible for verifying the integrity of 5346 certificates and should generally support certificate revocation 5347 messages. Absent a specific indication from an application profile, 5348 Certificates should always be verified to ensure proper signing by a 5349 trusted Certificate Authority (CA). The selection and addition of 5350 trust anchors should be done very carefully. Users should be able to 5351 view information about the certificate and trust anchor. 5352 Applications SHOULD also enforce minimum and maximum key sizes. For 5353 example, certification paths containing keys or signatures weaker 5354 than 2048-bit RSA or 224-bit ECDSA are not appropriate for secure 5355 applications. 5357 C.4. Implementation Pitfalls 5359 Implementation experience has shown that certain parts of earlier TLS 5360 specifications are not easy to understand, and have been a source of 5361 interoperability and security problems. Many of these areas have 5362 been clarified in this document, but this appendix contains a short 5363 list of the most important things that require special attention from 5364 implementors. 5366 TLS protocol issues: 5368 - Do you correctly handle handshake messages that are fragmented to 5369 multiple TLS records (see Section 5.1)? Including corner cases 5370 like a ClientHello that is split to several small fragments? Do 5371 you fragment handshake messages that exceed the maximum fragment 5372 size? In particular, the Certificate and CertificateRequest 5373 handshake messages can be large enough to require fragmentation. 5375 - Do you ignore the TLS record layer version number in all 5376 unencrypted TLS records? (see Appendix D) 5378 - Have you ensured that all support for SSL, RC4, EXPORT ciphers, 5379 and MD5 (via the "signature_algorithms" extension) is completely 5380 removed from all possible configurations that support TLS 1.3 or 5381 later, and that attempts to use these obsolete capabilities fail 5382 correctly? (see Appendix D) 5384 - Do you handle TLS extensions in ClientHello correctly, including 5385 unknown extensions? 5387 - When the server has requested a client certificate, but no 5388 suitable certificate is available, do you correctly send an empty 5389 Certificate message, instead of omitting the whole message (see 5390 Section 4.4.2.3)? 5392 - When processing the plaintext fragment produced by AEAD-Decrypt 5393 and scanning from the end for the ContentType, do you avoid 5394 scanning past the start of the cleartext in the event that the 5395 peer has sent a malformed plaintext of all-zeros? 5397 - Do you properly ignore unrecognized cipher suites (Section 4.1.2), 5398 hello extensions (Section 4.2), named groups (Section 4.2.6), key 5399 shares Section 4.2.7, supported versions Section 4.2.1, and 5400 signature algorithms (Section 4.2.3) in the ClientHello? 5402 - As a server, do you send a HelloRetryRequest to clients which 5403 support a compatible (EC)DHE group but do not predict it in the 5404 "key_share" extension? As a client, do you correctly handle a 5405 HelloRetryRequest from the server? 5407 Cryptographic details: 5409 - What countermeasures do you use to prevent timing attacks 5410 [TIMING]? 5412 - When using Diffie-Hellman key exchange, do you correctly preserve 5413 leading zero bytes in the negotiated key (see Section 7.4.1)? 5415 - Does your TLS client check that the Diffie-Hellman parameters sent 5416 by the server are acceptable, (see Section 4.2.7.1)? 5418 - Do you use a strong and, most importantly, properly seeded random 5419 number generator (see Appendix C.2) when generating Diffie-Hellman 5420 private values, the ECDSA "k" parameter, and other security- 5421 critical values? It is RECOMMENDED that implementations implement 5422 "deterministic ECDSA" as specified in [RFC6979]. 5424 - Do you zero-pad Diffie-Hellman public key values to the group size 5425 (see Section 4.2.7.1)? 5427 - Do you verify signatures after making them to protect against RSA- 5428 CRT key leaks? [FW15] 5430 C.5. Client Tracking Prevention 5432 Clients SHOULD NOT reuse a ticket for multiple connections. Reuse of 5433 a ticket allows passive observers to correlate different connections. 5434 Servers that issue tickets SHOULD offer at least as many tickets as 5435 the number of connections that a client might use; for example, a web 5436 browser using HTTP/1.1 [RFC7230] might open six connections to a 5437 server. Servers SHOULD issue new tickets with every connection. 5438 This ensures that clients are always able to use a new ticket when 5439 creating a new connection. 5441 C.6. Unauthenticated Operation 5443 Previous versions of TLS offered explicitly unauthenticated cipher 5444 suites based on anonymous Diffie-Hellman. These modes have been 5445 deprecated in TLS 1.3. However, it is still possible to negotiate 5446 parameters that do not provide verifiable server authentication by 5447 several methods, including: 5449 - Raw public keys [RFC7250]. 5451 - Using a public key contained in a certificate but without 5452 validation of the certificate chain or any of its contents. 5454 Either technique used alone is vulnerable to man-in-the-middle 5455 attacks and therefore unsafe for general use. However, it is also 5456 possible to bind such connections to an external authentication 5457 mechanism via out-of-band validation of the server's public key, 5458 trust on first use, or a mechanism such as channel bindings (though 5459 the channel bindings described in [RFC5929] are not defined for TLS 5460 1.3). If no such mechanism is used, then the connection has no 5461 protection against active man-in-the-middle attack; applications MUST 5462 NOT use TLS in such a way absent explicit configuration or a specific 5463 application profile. 5465 Appendix D. Backward Compatibility 5467 The TLS protocol provides a built-in mechanism for version 5468 negotiation between endpoints potentially supporting different 5469 versions of TLS. 5471 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 5472 also handle clients trying to use future versions of TLS as long as 5473 the ClientHello format remains compatible and the client supports the 5474 highest protocol version available in the server. 5476 Prior versions of TLS used the record layer version number for 5477 various purposes. (TLSPlaintext.legacy_record_version and 5478 TLSCiphertext.legacy_record_version) As of TLS 1.3, this field is 5479 deprecated. The value of TLSPlaintext.legacy_record_version MUST be 5480 ignored by all implementations. The value of 5481 TLSCiphertext.legacy_record_version MAY be ignored, or MAY be 5482 validated to match the fixed constant value. Version negotiation is 5483 performed using only the handshake versions 5484 (ClientHello.legacy_version, ClientHello "supported_versions" 5485 extension, and ServerHello.version). In order to maximize 5486 interoperability with older endpoints, implementations that negotiate 5487 the use of TLS 1.0-1.2 SHOULD set the record layer version number to 5488 the negotiated version for the ServerHello and all records 5489 thereafter. 5491 For maximum compatibility with previously non-standard behavior and 5492 misconfigured deployments, all implementations SHOULD support 5493 validation of certification paths based on the expectations in this 5494 document, even when handling prior TLS versions' handshakes. (see 5495 Section 4.4.2.2) 5497 TLS 1.2 and prior supported an "Extended Master Secret" [RFC7627] 5498 extension which digested large parts of the handshake transcript into 5499 the master secret. Because TLS 1.3 always hashes in the transcript 5500 up to the server CertificateVerify, implementations which support 5501 both TLS 1.3 and earlier versions SHOULD indicate the use of the 5502 Extended Master Secret extension in their APIs whenever TLS 1.3 is 5503 used. 5505 D.1. Negotiating with an older server 5507 A TLS 1.3 client who wishes to negotiate with servers that do not 5508 support TLS 1.3 will send a normal TLS 1.3 ClientHello containing 5509 0x0303 (TLS 1.2) in ClientHello.legacy_version but with the correct 5510 version in the "supported_versions" extension. If the server does 5511 not support TLS 1.3 it will respond with a ServerHello containing an 5512 older version number. If the client agrees to use this version, the 5513 negotiation will proceed as appropriate for the negotiated protocol. 5514 A client using a ticket for resumption SHOULD initiate the connection 5515 using the version that was previously negotiated. 5517 Note that 0-RTT data is not compatible with older servers and SHOULD 5518 NOT be sent absent knowledge that the server supports TLS 1.3. See 5519 Appendix D.3. 5521 If the version chosen by the server is not supported by the client 5522 (or not acceptable), the client MUST abort the handshake with a 5523 "protocol_version" alert. 5525 Some legacy server implementations are known to not implement the TLS 5526 specification properly and might abort connections upon encountering 5527 TLS extensions or versions which they are not aware of. 5528 Interoperability with buggy servers is a complex topic beyond the 5529 scope of this document. Multiple connection attempts may be required 5530 in order to negotiate a backwards compatible connection; however, 5531 this practice is vulnerable to downgrade attacks and is NOT 5532 RECOMMENDED. 5534 D.2. Negotiating with an older client 5536 A TLS server can also receive a ClientHello indicating a version 5537 number smaller than its highest supported version. If the 5538 "supported_versions" extension is present, the server MUST negotiate 5539 using that extension as described in Section 4.2.1. If the 5540 "supported_versions" extension is not present, the server MUST 5541 negotiate the minimum of ClientHello.legacy_version and TLS 1.2. For 5542 example, if the server supports TLS 1.0, 1.1, and 1.2, and 5543 legacy_version is TLS 1.0, the server will proceed with a TLS 1.0 5544 ServerHello. If the "supported_versions" extension is absent and the 5545 server only supports versions greater than 5546 ClientHello.legacy_version, the server MUST abort the handshake with 5547 a "protocol_version" alert. 5549 Note that earlier versions of TLS did not clearly specify the record 5550 layer version number value in all cases 5551 (TLSPlaintext.legacy_record_version). Servers will receive various 5552 TLS 1.x versions in this field, but its value MUST always be ignored. 5554 D.3. Zero-RTT backwards compatibility 5556 0-RTT data is not compatible with older servers. An older server 5557 will respond to the ClientHello with an older ServerHello, but it 5558 will not correctly skip the 0-RTT data and will fail to complete the 5559 handshake. This can cause issues when a client attempts to use 5560 0-RTT, particularly against multi-server deployments. For example, a 5561 deployment could deploy TLS 1.3 gradually with some servers 5562 implementing TLS 1.3 and some implementing TLS 1.2, or a TLS 1.3 5563 deployment could be downgraded to TLS 1.2. 5565 A client that attempts to send 0-RTT data MUST fail a connection if 5566 it receives a ServerHello with TLS 1.2 or older. A client that 5567 attempts to repair this error SHOULD NOT send a TLS 1.2 ClientHello, 5568 but instead send a TLS 1.3 ClientHello without 0-RTT data. 5570 To avoid this error condition, multi-server deployments SHOULD ensure 5571 a uniform and stable deployment of TLS 1.3 without 0-RTT prior to 5572 enabling 0-RTT. 5574 D.4. Backwards Compatibility Security Restrictions 5576 Implementations negotiating use of older versions of TLS SHOULD 5577 prefer forward secure and AEAD cipher suites, when available. 5579 The security of RC4 cipher suites is considered insufficient for the 5580 reasons cited in [RFC7465]. Implementations MUST NOT offer or 5581 negotiate RC4 cipher suites for any version of TLS for any reason. 5583 Old versions of TLS permitted the use of very low strength ciphers. 5584 Ciphers with a strength less than 112 bits MUST NOT be offered or 5585 negotiated for any version of TLS for any reason. 5587 The security of SSL 3.0 [SSL3] is considered insufficient for the 5588 reasons enumerated in [RFC7568], and MUST NOT be negotiated for any 5589 reason. 5591 The security of SSL 2.0 [SSL2] is considered insufficient for the 5592 reasons enumerated in [RFC6176], and MUST NOT be negotiated for any 5593 reason. 5595 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 5596 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 5597 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 5598 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 5599 order to negotiate older versions of TLS. 5601 Implementations MUST NOT send a ClientHello.legacy_version or 5602 ServerHello.version set to 0x0300 or less. Any endpoint receiving a 5603 Hello message with ClientHello.legacy_version or ServerHello.version 5604 set to 0x0300 MUST abort the handshake with a "protocol_version" 5605 alert. 5607 Implementations MUST NOT send any records with a version less than 5608 0x0300. Implementations SHOULD NOT accept any records with a version 5609 less than 0x0300 (but may inadvertently do so if the record version 5610 number is ignored completely). 5612 Implementations MUST NOT use the Truncated HMAC extension, defined in 5613 Section 7 of [RFC6066], as it is not applicable to AEAD algorithms 5614 and has been shown to be insecure in some scenarios. 5616 Appendix E. Overview of Security Properties 5618 A complete security analysis of TLS is outside the scope of this 5619 document. In this section, we provide an informal description the 5620 desired properties as well as references to more detailed work in the 5621 research literature which provides more formal definitions. 5623 We cover properties of the handshake separately from those of the 5624 record layer. 5626 E.1. Handshake 5628 The TLS handshake is an Authenticated Key Exchange (AKE) protocol 5629 which is intended to provide both one-way authenticated (server-only) 5630 and mutually authenticated (client and server) functionality. At the 5631 completion of the handshake, each side outputs its view of the 5632 following values: 5634 - A set of "session keys" (the various secrets derived from the 5635 master secret) from which can be derived a set of working keys. 5637 - A set of cryptographic parameters (algorithms, etc.) 5639 - The identities of the communicating parties. 5641 We assume that the attacker has complete control of the network in 5642 between the parties [RFC3552]. Even under these conditions, the 5643 handshake should provide the properties listed below. Note that 5644 these properties are not necessarily independent, but reflect the 5645 protocol consumers' needs. 5647 Establishing the same session keys. The handshake needs to output 5648 the same set of session keys on both sides of the handshake, 5649 provided that it completes successfully on each endpoint (See 5650 [CK01]; defn 1, part 1). 5652 Secrecy of the session keys. The shared session keys should be known 5653 only to the communicating parties, not to the attacker (See 5654 [CK01]; defn 1, part 2). Note that in a unilaterally 5655 authenticated connection, the attacker can establish its own 5656 session keys with the server, but those session keys are distinct 5657 from those established by the client. 5659 Peer Authentication. The client's view of the peer identity should 5660 reflect the server's identity. If the client is authenticated, 5661 the server's view of the peer identity should match the client's 5662 identity. 5664 Uniqueness of the session keys: Any two distinct handshakes should 5665 produce distinct, unrelated session keys. Individual session keys 5666 produced by a handshake should also be distinct and unrelated. 5668 Downgrade protection. The cryptographic parameters should be the 5669 same on both sides and should be the same as if the peers had been 5670 communicating in the absence of an attack (See [BBFKZG16]; defns 8 5671 and 9}). 5673 Forward secret with respect to long-term keys If the long-term 5674 keying material (in this case the signature keys in certificate- 5675 based authentication modes or the external/resumption PSK in PSK 5676 with (EC)DHE modes) is compromised after the handshake is 5677 complete, this does not compromise the security of the session key 5678 (See [DOW92]). The forward secrecy property is not satisfied when 5679 PSK is used in the "psk_ke" PskKeyExchangeMode. 5681 Key Compromise Impersonation (KCI) resistance In a mutually- 5682 authenticated connection with certificates, peer authentication 5683 should hold even if the local long-term secret was compromised 5684 before the connection was established (see [HGFS15]). For 5685 example, if a client's signature key is compromised, it should not 5686 be possible to impersonate arbitrary servers to that client in 5687 subsequent handshakes. 5689 Protection of endpoint identities. The server's identity 5690 (certificate) should be protected against passive attackers. The 5691 client's identity should be protected against both passive and 5692 active attackers. 5694 Informally, the signature-based modes of TLS 1.3 provide for the 5695 establishment of a unique, secret, shared, key established by an 5696 (EC)DHE key exchange and authenticated by the server's signature over 5697 the handshake transcript, as well as tied to the server's identity by 5698 a MAC. If the client is authenticated by a certificate, it also 5699 signs over the handshake transcript and provides a MAC tied to both 5700 identities. [SIGMA] describes the analysis of this type of key 5701 exchange protocol. If fresh (EC)DHE keys are used for each 5702 connection, then the output keys are forward secret. 5704 The external PSK and resumption PSK bootstrap from a long-term shared 5705 secret into a unique per-connection set of short-term session keys. 5706 This secret may have been established in a previous handshake. If 5707 PSK with (EC)DHE key establishment is used, these session keys will 5708 also be forward secret. The resumption PSK has been designed so that 5709 the resumption master secret computed by connection N and needed to 5710 form connection N+1 is separate from the traffic keys used by 5711 connection N, thus providing forward secrecy between the connections. 5713 The PSK binder value forms a binding between a PSK and the current 5714 handshake, as well as between the session where the PSK was 5715 established and the session where it was used. This binding 5716 transitively includes the original handshake transcript, because that 5717 transcript is digested into the values which produce the Resumption 5718 Master Secret. This requires that both the KDF used to produce the 5719 resumption master secret and the MAC used to compute the binder be 5720 collision resistant. See Appendix E.1.1 for more on this. Note: The 5721 binder does not cover the binder values from other PSKs, though they 5722 are included in the Finished MAC. 5724 Note: TLS does not currently permit the server to send a 5725 certificate_request message in non-certificate-based handshakes 5726 (e.g., PSK). If this restriction were to be relaxed in future, the 5727 client's signature would not cover the server's certificate directly. 5728 However, if the PSK was established through a NewSessionTicket, the 5729 client's signature would transitively cover the server's certificate 5730 through the PSK binder. [PSK-FINISHED] describes a concrete attack 5731 on constructions that do not bind to the server's certificate. It is 5732 unsafe to use certificate-based client authentication when the client 5733 might potentially share the same PSK/key-id pair with two different 5734 endpoints. Implementations MUST NOT combine external PSKs with 5735 certificate-based authentication of either the client or the server. 5737 If an exporter is used, then it produces values which are unique and 5738 secret (because they are generated from a unique session key). 5740 Exporters computed with different labels and contexts are 5741 computationally independent, so it is not feasible to compute one 5742 from another or the session secret from the exported value. Note: 5743 exporters can produce arbitrary-length values. If exporters are to 5744 be used as channel bindings, the exported value MUST be large enough 5745 to provide collision resistance. The exporters provided in TLS 1.3 5746 are derived from the same handshake contexts as the early traffic 5747 keys and the application traffic keys respectively, and thus have 5748 similar security properties. Note that they do not include the 5749 client's certificate; future applications which wish to bind to the 5750 client's certificate may need to define a new exporter that includes 5751 the full handshake transcript. 5753 For all handshake modes, the Finished MAC (and where present, the 5754 signature), prevents downgrade attacks. In addition, the use of 5755 certain bytes in the random nonces as described in Section 4.1.3 5756 allows the detection of downgrade to previous TLS versions. 5758 As soon as the client and the server have exchanged enough 5759 information to establish shared keys, the remainder of the handshake 5760 is encrypted, thus providing protection against passive attackers. 5761 Because the server authenticates before the client, the client can 5762 ensure that it only reveals its identity to an authenticated server. 5763 Note that implementations must use the provided record padding 5764 mechanism during the handshake to avoid leaking information about the 5765 identities due to length. The client's proposed PSK identities are 5766 not encrypted, nor is the one that the server selects. 5768 E.1.1. Key Derivation and HKDF 5770 Key derivation in TLS 1.3 uses the HKDF function defined in [RFC5869] 5771 and its two components, HKDF-Extract and HKDF-Expand. The full 5772 rationale for the HKDF construction can be found in [Kraw10] and the 5773 rationale for the way it is used in TLS 1.3 in [KW16]. Throughout 5774 this document, each application of HKDF-Extract is followed by one or 5775 more invocations of HKDF-Expand. This ordering should always be 5776 followed (including in future revisions of this document), in 5777 particular, one SHOULD NOT use an output of HKDF-Extract as an input 5778 to another application of HKDF-Extract without an HKDF-Expand in 5779 between. Consecutive applications of HKDF-Expand are allowed as long 5780 as these are differentiated via the key and/or the labels. 5782 Note that HKDF-Expand implements a pseudorandom function (PRF) with 5783 both inputs and outputs of variable length. In some of the uses of 5784 HKDF in this document (e.g., for generating exporters and the 5785 resumption_master_secret), it is necessary that the application of 5786 HKDF-Expand be collision-resistant, namely, it should be infeasible 5787 to find two different inputs to HKDF-Expand that output the same 5788 value. This requires the underlying hash function to be collision 5789 resistant and the output length from HKDF-Expand to be of size at 5790 least 256 bits (or as much as needed for the hash function to prevent 5791 finding collisions). 5793 E.1.2. Client Authentication 5795 A client that has sent authentication data to a server, either during 5796 the handshake or in post-handshake authentication, cannot be sure if 5797 the server afterwards considers the client to be authenticated or 5798 not. If the client needs to determine if the server considers the 5799 connection to be unilaterally or mutually authenticated, this has to 5800 be provisioned by the application layer. See [CHHSV17] for details. 5801 In addition, the analysis of post-handshake authentication from 5802 [Kraw16] shows that the client identified by the certificate sent in 5803 the post-handshake phase possesses the traffic key. This party is 5804 therefore the client that participated in the original handshake or 5805 one to whom the original client delegated the traffic key (assuming 5806 that the traffic key has not been compromised). 5808 E.1.3. 0-RTT 5810 The 0-RTT mode of operation generally provides the same security 5811 properties as 1-RTT data, with the two exceptions that the 0-RTT 5812 encryption keys do not provide full forward secrecy and that the 5813 server is not able to guarantee full uniqueness of the handshake 5814 (non-replayability) without keeping potentially undue amounts of 5815 state. See Section 4.2.9 for one mechanism to limit the exposure to 5816 replay. 5818 E.1.4. Post-Compromise Security 5820 TLS does not provide security for handshakes which take place after 5821 the peer's long-term secret (signature key or external PSK) is 5822 compromised. It therefore does not provide post-compromise security 5823 [CCG16], sometimes also referred to as backwards or future security. 5824 This is in contrast to KCI resistance, which describes the security 5825 guarantees that a party has after its own long-term secret has been 5826 compromised. 5828 E.1.5. External References 5830 The reader should refer to the following references for analysis of 5831 the TLS handshake: [DFGS15] [CHSV16] [DFGS16] [KW16] [Kraw16] 5832 [FGSW16] [LXZFH16] [FG17] [BBK17]. 5834 E.2. Record Layer 5836 The record layer depends on the handshake producing strong traffic 5837 secrets which can be used to derive bidirectional encryption keys and 5838 nonces. Assuming that is true, and the keys are used for no more 5839 data than indicated in Section 5.5 then the record layer should 5840 provide the following guarantees: 5842 Confidentiality. An attacker should not be able to determine the 5843 plaintext contents of a given record. 5845 Integrity. An attacker should not be able to craft a new record 5846 which is different from an existing record which will be accepted 5847 by the receiver. 5849 Order protection/non-replayability An attacker should not be able to 5850 cause the receiver to accept a record which it has already 5851 accepted or cause the receiver to accept record N+1 without having 5852 first processed record N. 5854 Length concealment. Given a record with a given external length, the 5855 attacker should not be able to determine the amount of the record 5856 that is content versus padding. 5858 Forward security after key change. If the traffic key update 5859 mechanism described in Section 4.6.3 has been used and the 5860 previous generation key is deleted, an attacker who compromises 5861 the endpoint should not be able to decrypt traffic encrypted with 5862 the old key. 5864 Informally, TLS 1.3 provides these properties by AEAD-protecting the 5865 plaintext with a strong key. AEAD encryption [RFC5116] provides 5866 confidentiality and integrity for the data. Non-replayability is 5867 provided by using a separate nonce for each record, with the nonce 5868 being derived from the record sequence number (Section 5.3), with the 5869 sequence number being maintained independently at both sides thus 5870 records which are delivered out of order result in AEAD deprotection 5871 failures. 5873 The re-keying technique in TLS 1.3 (see Section 7.2) follows the 5874 construction of the serial generator in [REKEY], which shows that re- 5875 keying can allow keys to be used for a larger number of encryptions 5876 than without re-keying. This relies on the security of the HKDF- 5877 Expand-Label function as a pseudorandom function (PRF). In addition, 5878 as long as this function is truly one way, it is not possible to 5879 compute traffic keys from prior to a key change (forward secrecy). 5881 TLS does not provide security for data which is communicated on a 5882 connection after a traffic secret of that connection is compromised. 5883 That is, TLS does not provide post-compromise security/future 5884 secrecy/backward secrecy with respect to the traffic secret. Indeed, 5885 an attacker who learns a traffic secret can compute all future 5886 traffic secrets on that connection. Systems which want such 5887 guarantees need to do a fresh handshake and establish a new 5888 connection with an (EC)DHE exchange. 5890 E.2.1. External References 5892 The reader should refer to the following references for analysis of 5893 the TLS record layer: [BMMT15] [BT16] [BDFKPPRSZZ16] [BBK17]. 5895 E.3. Traffic Analysis 5897 TLS is susceptible to a variety of traffic analysis attacks based on 5898 observing the length and timing of encrypted packets [CLINIC] 5899 [HCJ16]. This is particularly easy when there is a small set of 5900 possible messages to be distinguished, such as for a video server 5901 hosting a fixed corpus of content, but still provides usable 5902 information even in more complicated scenarios. 5904 TLS does not provide any specific defenses against this form of 5905 attack but does include a padding mechanism for use by applications: 5906 The plaintext protected by the AEAD function consists of content plus 5907 variable-length padding, which allows the application to produce 5908 arbitrary length encrypted records as well as padding-only cover 5909 traffic to conceal the difference between periods of transmission and 5910 periods of silence. Because the padding is encrypted alongside the 5911 actual content, an attacker cannot directly determine the length of 5912 the padding, but may be able to measure it indirectly by the use of 5913 timing channels exposed during record processing (i.e., seeing how 5914 long it takes to process a record or trickling in records to see 5915 which ones elicit a response from the server). In general, it is not 5916 known how to remove all of these channels because even a constant 5917 time padding removal function will then feed the content into data- 5918 dependent functions. 5920 Note: Robust traffic analysis defences will likely lead to inferior 5921 performance due to delay in transmitting packets and increased 5922 traffic volume. 5924 E.4. Side Channel Attacks 5926 In general, TLS does not have specific defenses against side-channel 5927 attacks (i.e., those which attack the communications via secondary 5928 channels such as timing) leaving those to the implementation of the 5929 relevant cryptographic primitives. However, certain features of TLS 5930 are designed to make it easier to write side-channel resistant code: 5932 - Unlike previous versions of TLS which used a composite MAC-then- 5933 encrypt structure, TLS 1.3 only uses AEAD algorithms, allowing 5934 implementations to use self-contained constant-time 5935 implementations of those primitives. 5937 - TLS uses a uniform "bad_record_mac" alert for all decryption 5938 errors, which is intended to prevent an attacker from gaining 5939 piecewise insight into portions of the message. Additional 5940 resistance is provided by terminating the connection on such 5941 errors; a new connection will have different cryptographic 5942 material, preventing attacks against the cryptographic primitives 5943 that require multiple trials. 5945 Information leakage through side channels can occur at layers above 5946 TLS, in application protocols and the applications that use them. 5947 Resistance to side-channel attacks depends on applications and 5948 application protocols separately ensuring that confidential 5949 information is not inadvertently leaked. 5951 Appendix F. Working Group Information 5953 The discussion list for the IETF TLS working group is located at the 5954 e-mail address tls@ietf.org [1]. Information on the group and 5955 information on how to subscribe to the list is at 5956 https://www.ietf.org/mailman/listinfo/tls 5958 Archives of the list can be found at: https://www.ietf.org/mail- 5959 archive/web/tls/current/index.html 5961 Appendix G. Contributors 5963 - Martin Abadi 5964 University of California, Santa Cruz 5965 abadi@cs.ucsc.edu 5967 - Christopher Allen (co-editor of TLS 1.0) 5968 Alacrity Ventures 5969 ChristopherA@AlacrityManagement.com 5971 - Steven M. Bellovin 5972 Columbia University 5973 smb@cs.columbia.edu 5975 - David Benjamin 5976 Google 5977 davidben@google.com 5979 - Benjamin Beurdouche 5980 INRIA & Microsoft Research - Joint Center 5981 benjamin.beurdouche@ens.fr 5983 - Karthikeyan Bhargavan (co-author of [RFC7627]) 5984 INRIA 5985 karthikeyan.bhargavan@inria.fr 5987 - Simon Blake-Wilson (co-author of [RFC4492]) 5988 BCI 5989 sblakewilson@bcisse.com 5991 - Nelson Bolyard (co-author of [RFC4492]) 5992 Sun Microsystems, Inc. 5993 nelson@bolyard.com 5995 - Ran Canetti 5996 IBM 5997 canetti@watson.ibm.com 5999 - Pete Chown 6000 Skygate Technology Ltd 6001 pc@skygate.co.uk 6003 - Katriel Cohn-Gordon 6004 University of Oxford 6005 me@katriel.co.uk 6007 - Cas Cremers 6008 University of Oxford 6009 cas.cremers@cs.ox.ac.uk 6011 - Antoine Delignat-Lavaud (co-author of [RFC7627]) 6012 INRIA 6013 antoine.delignat-lavaud@inria.fr 6015 - Tim Dierks (co-editor of TLS 1.0, 1.1, and 1.2) 6016 Independent 6017 tim@dierks.org 6019 - Taher Elgamal 6020 Securify 6021 taher@securify.com 6023 - Pasi Eronen 6024 Nokia 6025 pasi.eronen@nokia.com 6027 - Cedric Fournet 6028 Microsoft 6029 fournet@microsoft.com 6031 - Anil Gangolli 6032 anil@busybuddha.org 6034 - David M. Garrett 6035 dave@nulldereference.com 6037 - Alessandro Ghedini 6038 Cloudflare Inc. 6039 alessandro@cloudflare.com 6041 - Daniel Kahn Gillmor 6042 ACLU 6043 dkg@fifthhorseman.net 6045 - Matthew Green 6046 Johns Hopkins University 6047 mgreen@cs.jhu.edu 6049 - Jens Guballa 6050 ETAS 6051 jens.guballa@etas.com 6053 - Felix Guenther 6054 TU Darmstadt 6055 mail@felixguenther.info 6057 - Vipul Gupta (co-author of [RFC4492]) 6058 Sun Microsystems Laboratories 6059 vipul.gupta@sun.com 6061 - Chris Hawk (co-author of [RFC4492]) 6062 Corriente Networks LLC 6063 chris@corriente.net 6065 - Kipp Hickman 6067 - Alfred Hoenes 6069 - David Hopwood 6070 Independent Consultant 6071 david.hopwood@blueyonder.co.uk 6073 - Marko Horvat 6074 MPI-SWS 6075 mhorvat@mpi-sws.org 6077 - Jonathan Hoyland 6078 Royal Holloway, University of London 6080 - Subodh Iyengar 6081 Facebook 6082 subodh@fb.com 6084 - Benjamin Kaduk 6085 Akamai 6086 kaduk@mit.edu 6088 - Hubert Kario 6089 Red Hat Inc. 6090 hkario@redhat.com 6092 - Phil Karlton (co-author of SSL 3.0) 6094 - Leon Klingele 6095 Independent 6096 mail@leonklingele.de 6098 - Paul Kocher (co-author of SSL 3.0) 6099 Cryptography Research 6100 paul@cryptography.com 6102 - Hugo Krawczyk 6103 IBM 6104 hugo@ee.technion.ac.il 6106 - Adam Langley (co-author of [RFC7627]) 6107 Google 6108 agl@google.com 6110 - Olivier Levillain 6111 ANSSI 6112 olivier.levillain@ssi.gouv.fr 6114 - Xiaoyin Liu 6115 University of North Carolina at Chapel Hill 6116 xiaoyin.l@outlook.com 6118 - Ilari Liusvaara 6119 Independent 6120 ilariliusvaara@welho.com 6122 - Atul Luykx 6123 K.U. Leuven 6124 atul.luykx@kuleuven.be 6126 - Carl Mehner 6127 USAA 6128 carl.mehner@usaa.com 6130 - Jan Mikkelsen 6131 Transactionware 6132 janm@transactionware.com 6134 - Bodo Moeller (co-author of [RFC4492]) 6135 Google 6136 bodo@openssl.org 6138 - Kyle Nekritz 6139 Facebook 6140 knekritz@fb.com 6142 - Erik Nygren 6143 Akamai Technologies 6144 erik+ietf@nygren.org 6146 - Magnus Nystrom 6147 Microsoft 6148 mnystrom@microsoft.com 6150 - Kazuho Oku 6151 DeNA Co., Ltd. 6152 kazuhooku@gmail.com 6154 - Kenny Paterson 6155 Royal Holloway, University of London 6156 kenny.paterson@rhul.ac.uk 6158 - Alfredo Pironti (co-author of [RFC7627]) 6159 INRIA 6160 alfredo.pironti@inria.fr 6162 - Andrei Popov 6163 Microsoft 6164 andrei.popov@microsoft.com 6166 - Marsh Ray (co-author of [RFC7627]) 6167 Microsoft 6168 maray@microsoft.com 6170 - Robert Relyea 6171 Netscape Communications 6172 relyea@netscape.com 6174 - Kyle Rose 6175 Akamai Technologies 6176 krose@krose.org 6178 - Jim Roskind 6179 Amazon 6180 jroskind@amazon.com 6182 - Michael Sabin 6184 - Joe Salowey 6185 Tableau Software 6186 joe@salowey.net 6188 - Rich Salz 6189 Akamai 6190 rsalz@akamai.com 6192 - Sam Scott 6193 Royal Holloway, University of London 6194 me@samjs.co.uk 6196 - Dan Simon 6197 Microsoft, Inc. 6198 dansimon@microsoft.com 6200 - Brian Sniffen 6201 Akamai Technologies 6202 ietf@bts.evenmere.org 6204 - Nick Sullivan 6205 Cloudflare Inc. 6206 nick@cloudflare.com 6208 - Bjoern Tackmann 6209 University of California, San Diego 6210 btackmann@eng.ucsd.edu 6212 - Tim Taubert 6213 Mozilla 6214 ttaubert@mozilla.com 6216 - Martin Thomson 6217 Mozilla 6218 mt@mozilla.com 6220 - Sean Turner 6221 sn3rd 6222 sean@sn3rd.com 6224 - Filippo Valsorda 6225 Cloudflare Inc. 6226 filippo@cloudflare.com 6228 - Thyla van der Merwe 6229 Royal Holloway, University of London 6230 tjvdmerwe@gmail.com 6232 - Tom Weinstein 6234 - Hoeteck Wee 6235 Ecole Normale Superieure, Paris 6236 hoeteck@alum.mit.edu 6238 - David Wong 6239 NCC Group 6240 david.wong@nccgroup.trust 6242 - Tim Wright 6243 Vodafone 6244 timothy.wright@vodafone.com 6246 - Kazu Yamamoto 6247 Internet Initiative Japan Inc. 6248 kazu@iij.ad.jp 6250 Author's Address 6252 Eric Rescorla 6253 RTFM, Inc. 6255 EMail: ekr@rtfm.com