idnits 2.17.1 draft-ietf-tls-tls13-16.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 24 instances of too long lines in the document, the longest one being 15 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 RFC5746, 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: psk_ke PSK-only key establishment. In this mode, the server MUST not supply a "key_share" value. == 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 'SHOULD not' in this paragraph: If the server rejects the "early_data" extension, the client application MAY opt to retransmit the data once the handshake has been completed. TLS stacks SHOULD not do this automatically and client applications MUST take care that the negotiated parameters are consistent with those it expected. For example, if the ALPN value has changed, it is likely unsafe to retransmit the original application layer data. == 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: Servers which are authenticating with a PSK MUST not send the CertificateRequest message. (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 (September 22, 2016) is 2772 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 751, but not defined -- Looks like a reference, but probably isn't: '0' on line 866 -- Looks like a reference, but probably isn't: '1' on line 5199 -- Looks like a reference, but probably isn't: '3' on line 937 -- Looks like a reference, but probably isn't: '9' on line 902 -- Looks like a reference, but probably isn't: '2' on line 4414 -- Looks like a reference, but probably isn't: '4' on line 938 -- Looks like a reference, but probably isn't: '8' on line 939 -- Looks like a reference, but probably isn't: '10' on line 1044 -- Looks like a reference, but probably isn't: '32' on line 4412 == Missing Reference: 'RFC7507' is mentioned on line 3324, but not defined ** Obsolete undefined reference: RFC 7507 (Obsoleted by RFC 8996) == Unused Reference: 'AES' is defined on line 3865, but no explicit reference was found in the text == Unused Reference: 'RFC5288' is defined on line 3904, but no explicit reference was found in the text == Unused Reference: 'RFC5289' is defined on line 3909, but no explicit reference was found in the text == Unused Reference: 'RFC5487' is defined on line 3914, but no explicit reference was found in the text == Unused Reference: 'RFC6209' is defined on line 3933, but no explicit reference was found in the text == Unused Reference: 'RFC6367' is defined on line 3938, but no explicit reference was found in the text == Unused Reference: 'RFC7251' is defined on line 3958, but no explicit reference was found in the text == Unused Reference: 'RFC7905' is defined on line 3977, but no explicit reference was found in the text == Unused Reference: 'GCM' is defined on line 4042, but no explicit reference was found in the text == Unused Reference: 'PKCS6' is defined on line 4060, but no explicit reference was found in the text == Unused Reference: 'PKCS7' is defined on line 4063, but no explicit reference was found in the text == Unused Reference: 'RFC0793' is defined on line 4072, but no explicit reference was found in the text == Unused Reference: 'RFC1948' is defined on line 4076, but no explicit reference was found in the text == Unused Reference: 'RFC4302' is defined on line 4095, but no explicit reference was found in the text == Unused Reference: 'RFC4303' is defined on line 4099, but no explicit reference was found in the text == Unused Reference: 'RFC5763' is defined on line 4161, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DH' ** Downref: Normative reference to an Informational draft: draft-irtf-cfrg-eddsa (ref. 'I-D.irtf-cfrg-eddsa') ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Downref: Normative reference to an Informational RFC: RFC 6209 ** Downref: Normative reference to an Informational RFC: RFC 6367 ** Obsolete normative reference: RFC 6961 (Obsoleted by RFC 8446) ** Downref: Normative reference to an Informational RFC: RFC 6979 ** Downref: Normative reference to an Informational RFC: RFC 7251 ** Downref: Normative reference to an Informational RFC: RFC 7443 ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) ** Downref: Normative reference to an Informational RFC: RFC 7748 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- Possible downref: Non-RFC (?) normative reference: ref. 'X962' == Outdated reference: A later version (-01) exists of draft-sandj-tls-iana-registry-updates-00 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 1948 (Obsoleted by RFC 6528) -- 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 4507 (Obsoleted by RFC 5077) -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5081 (Obsoleted by RFC 6091) -- 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 6962 (Obsoleted by RFC 9162) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 15 errors (**), 0 flaws (~~), 23 warnings (==), 36 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, 5746 (if September 22, 2016 5 approved) 6 Updates: 4492, 5705, 6066, 6961 (if 7 approved) 8 Intended status: Standards Track 9 Expires: March 26, 2017 11 The Transport Layer Security (TLS) Protocol Version 1.3 12 draft-ietf-tls-tls13-16 14 Abstract 16 This document specifies version 1.3 of the Transport Layer Security 17 (TLS) protocol. TLS allows client/server applications to communicate 18 over the Internet in a way that is designed to prevent eavesdropping, 19 tampering, and message forgery. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 26, 2017. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 This document may contain material from IETF Documents or IETF 54 Contributions published or made publicly available before November 55 10, 2008. The person(s) controlling the copyright in some of this 56 material may not have granted the IETF Trust the right to allow 57 modifications of such material outside the IETF Standards Process. 58 Without obtaining an adequate license from the person(s) controlling 59 the copyright in such materials, this document may not be modified 60 outside the IETF Standards Process, and derivative works of it may 61 not be created outside the IETF Standards Process, except to format 62 it for publication as an RFC or to translate it into languages other 63 than English. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 68 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 5 69 1.2. Major Differences from TLS 1.2 . . . . . . . . . . . . . 6 70 1.3. Updates Affecting TLS 1.2 . . . . . . . . . . . . . . . . 12 71 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 12 72 2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . . . 15 73 2.2. Resumption and Pre-Shared Key (PSK) . . . . . . . . . . . 16 74 2.3. Zero-RTT Data . . . . . . . . . . . . . . . . . . . . . . 18 75 3. Presentation Language . . . . . . . . . . . . . . . . . . . . 19 76 3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 19 77 3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 20 78 3.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 20 79 3.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 21 80 3.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 21 81 3.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 22 82 3.6.1. Variants . . . . . . . . . . . . . . . . . . . . . . 22 83 3.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 23 84 3.8. Decoding Errors . . . . . . . . . . . . . . . . . . . . . 24 85 4. Handshake Protocol . . . . . . . . . . . . . . . . . . . . . 24 86 4.1. Key Exchange Messages . . . . . . . . . . . . . . . . . . 25 87 4.1.1. Cryptographic Negotiation . . . . . . . . . . . . . . 26 88 4.1.2. Client Hello . . . . . . . . . . . . . . . . . . . . 27 89 4.1.3. Server Hello . . . . . . . . . . . . . . . . . . . . 29 90 4.1.4. Hello Retry Request . . . . . . . . . . . . . . . . . 31 91 4.2. Hello Extensions . . . . . . . . . . . . . . . . . . . . 32 92 4.2.1. Supported Versions . . . . . . . . . . . . . . . . . 34 93 4.2.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . 35 94 4.2.3. Signature Algorithms . . . . . . . . . . . . . . . . 35 95 4.2.4. Negotiated Groups . . . . . . . . . . . . . . . . . . 38 96 4.2.5. Key Share . . . . . . . . . . . . . . . . . . . . . . 39 97 4.2.6. Pre-Shared Key Extension . . . . . . . . . . . . . . 42 98 4.2.7. Early Data Indication . . . . . . . . . . . . . . . . 43 99 4.2.8. OCSP Status Extensions . . . . . . . . . . . . . . . 47 100 4.3. Server Parameters Messages . . . . . . . . . . . . . . . 47 101 4.3.1. Encrypted Extensions . . . . . . . . . . . . . . . . 47 102 4.3.2. Certificate Request . . . . . . . . . . . . . . . . . 48 103 4.4. Authentication Messages . . . . . . . . . . . . . . . . . 50 104 4.4.1. Certificate . . . . . . . . . . . . . . . . . . . . . 51 105 4.4.2. Certificate Verify . . . . . . . . . . . . . . . . . 54 106 4.4.3. Finished . . . . . . . . . . . . . . . . . . . . . . 56 107 4.5. Post-Handshake Messages . . . . . . . . . . . . . . . . . 58 108 4.5.1. New Session Ticket Message . . . . . . . . . . . . . 58 109 4.5.2. Post-Handshake Authentication . . . . . . . . . . . . 60 110 4.5.3. Key and IV Update . . . . . . . . . . . . . . . . . . 60 111 4.6. Handshake Layer and Key Changes . . . . . . . . . . . . . 61 112 5. Record Protocol . . . . . . . . . . . . . . . . . . . . . . . 61 113 5.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 62 114 5.2. Record Payload Protection . . . . . . . . . . . . . . . . 63 115 5.3. Per-Record Nonce . . . . . . . . . . . . . . . . . . . . 65 116 5.4. Record Padding . . . . . . . . . . . . . . . . . . . . . 66 117 5.5. Limits on Key Usage . . . . . . . . . . . . . . . . . . . 67 118 6. Alert Protocol . . . . . . . . . . . . . . . . . . . . . . . 67 119 6.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 68 120 6.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 70 121 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 72 122 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 72 123 7.2. Updating Traffic Keys and IVs . . . . . . . . . . . . . . 75 124 7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 75 125 7.3.1. Diffie-Hellman . . . . . . . . . . . . . . . . . . . 76 126 7.3.2. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 77 127 7.3.3. Exporters . . . . . . . . . . . . . . . . . . . . . . 77 128 8. Compliance Requirements . . . . . . . . . . . . . . . . . . . 78 129 8.1. MTI Cipher Suites . . . . . . . . . . . . . . . . . . . . 78 130 8.2. MTI Extensions . . . . . . . . . . . . . . . . . . . . . 78 131 9. Security Considerations . . . . . . . . . . . . . . . . . . . 79 132 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 133 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 83 134 11.1. Normative References . . . . . . . . . . . . . . . . . . 83 135 11.2. Informative References . . . . . . . . . . . . . . . . . 85 136 Appendix A. Protocol Data Structures and Constant Values . . . . 93 137 A.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 93 138 A.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 93 139 A.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 95 140 A.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 95 141 A.3.2. Server Parameters Messages . . . . . . . . . . . . . 99 142 A.3.3. Authentication Messages . . . . . . . . . . . . . . . 100 143 A.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 100 144 A.3.5. Updating Keys . . . . . . . . . . . . . . . . . . . . 101 146 A.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 101 147 Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 102 148 B.1. API considerations for 0-RTT . . . . . . . . . . . . . . 102 149 B.2. Random Number Generation and Seeding . . . . . . . . . . 102 150 B.3. Certificates and Authentication . . . . . . . . . . . . . 103 151 B.4. Cipher Suite Support . . . . . . . . . . . . . . . . . . 103 152 B.5. Implementation Pitfalls . . . . . . . . . . . . . . . . . 103 153 B.6. Client Tracking Prevention . . . . . . . . . . . . . . . 105 154 B.7. Unauthenticated Operation . . . . . . . . . . . . . . . . 105 155 Appendix C. Backward Compatibility . . . . . . . . . . . . . . . 105 156 C.1. Negotiating with an older server . . . . . . . . . . . . 106 157 C.2. Negotiating with an older client . . . . . . . . . . . . 107 158 C.3. Zero-RTT backwards compatibility . . . . . . . . . . . . 107 159 C.4. Backwards Compatibility Security Restrictions . . . . . . 108 160 Appendix D. Overview of Security Properties . . . . . . . . . . 109 161 D.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 109 162 D.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 111 163 Appendix E. Working Group Information . . . . . . . . . . . . . 112 164 Appendix F. Contributors . . . . . . . . . . . . . . . . . . . . 113 165 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 117 167 1. Introduction 169 DISCLAIMER: This is a WIP draft of TLS 1.3 and has not yet seen 170 significant security analysis. 172 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 173 draft is maintained in GitHub. Suggested changes should be submitted 174 as pull requests at https://github.com/tlswg/tls13-spec. 175 Instructions are on that page as well. Editorial changes can be 176 managed in GitHub, but any substantive change should be discussed on 177 the TLS mailing list. 179 The primary goal of TLS is to provide a secure channel between two 180 communicating peers. Specifically, the channel should provide the 181 following properties: 183 - Authentication: The server side of the channel is always 184 authenticated; the client side is optionally authenticated. 185 Authentication can happen via asymmetric cryptography (e.g., RSA 186 [RSA], ECDSA [ECDSA]) or a pre-shared symmetric key. 188 - Confidentiality: Data sent over the channel is not visible to 189 attackers. 191 - Integrity: Data sent over the channel cannot be modified by 192 attackers. 194 These properties should be true even in the face of an attacker who 195 has complete control of the network, as described in [RFC3552]. See 196 Appendix D for a more complete statement of the relevant security 197 properties. 199 TLS consists of two primary components: 201 - A handshake protocol (Section 4) that authenticates the 202 communicating parties, negotiates cryptographic modes and 203 parameters, and establishes shared keying material. The handshake 204 protocol is designed to resist tampering; an active attacker 205 should not be able to force the peers to negotiate different 206 parameters than they would if the connection were not under 207 attack. 209 - A record protocol (Section 5) that uses the parameters established 210 by the handshake protocol to protect traffic between the 211 communicating peers. The record protocol divides traffic up into 212 a series of records, each of which is independently protected 213 using the traffic keys. 215 TLS is application protocol independent; higher-level protocols can 216 layer on top of TLS transparently. The TLS standard, however, does 217 not specify how protocols add security with TLS; how to initiate TLS 218 handshaking and how to interpret the authentication certificates 219 exchanged are left to the judgment of the designers and implementors 220 of protocols that run on top of TLS. 222 This document defines TLS version 1.3. While TLS 1.3 is not directly 223 compatible with previous versions, all versions of TLS incorporate a 224 versioning mechanism which allows clients and servers to 225 interoperably negotiate a common version if one is supported. 227 1.1. Conventions and Terminology 229 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 230 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 231 "OPTIONAL" in this document are to be interpreted as described in RFC 232 2119 [RFC2119]. 234 The following terms are used: 236 client: The endpoint initiating the TLS connection. 238 connection: A transport-layer connection between two endpoints. 240 endpoint: Either the client or server of the connection. 242 handshake: An initial negotiation between client and server that 243 establishes the parameters of their transactions. 245 peer: An endpoint. When discussing a particular endpoint, "peer" 246 refers to the endpoint that is remote to the primary subject of 247 discussion. 249 receiver: An endpoint that is receiving records. 251 sender: An endpoint that is transmitting records. 253 session: An association between a client and a server resulting from 254 a handshake. 256 server: The endpoint which did not initiate the TLS connection. 258 1.2. Major Differences from TLS 1.2 260 (*) indicates changes to the wire protocol which may require 261 implementations to update. 263 draft-16 265 - Change RSASSA-PSS and EdDSA SignatureScheme codepoints for better 266 backwards compatibility (*) 268 - Move HelloRetryRequest.selected_group to an extension (*) 270 - Clarify the behavior of no exporter context and make it the same 271 as an empty context.(*) 273 - New KeyUpdate format that allows for requesting/not-requesting an 274 answer (*) 276 - New certificate_required alert (*) 278 - Forbid CertificateRequest with 0-RTT and PSK. 280 - Relax requirement to check SNI for 0-RTT. 282 draft-15 284 - New negotiation syntax as discussed in Berlin (*) 286 - Require CertificateRequest.context to be empty during handshake 287 (*) 289 - Forbid empty tickets (*) 290 - Forbid application data messages in between post-handshake 291 messages from the same flight (*) 293 - Clean up alert guidance (*) 295 - Clearer guidance on what is needed for TLS 1.2. 297 - Guidance on 0-RTT time windows. 299 - Rename a bunch of fields. 301 - Remove old PRNG text. 303 - Explicitly require checking that handshake records not span key 304 changes. 306 draft-14 308 - Allow cookies to be longer (*) 310 - Remove the "context" from EarlyDataIndication as it was undefined 311 and nobody used it (*) 313 - Remove 0-RTT EncryptedExtensions and replace the ticket_age 314 extension with an obfuscated version. Also necessitates a change 315 to NewSessionTicket (*). 317 - Move the downgrade sentinel to the end of ServerHello.Random to 318 accomodate tlsdate (*). 320 - Define ecdsa_sha1 (*). 322 - Allow resumption even after fatal alerts. This matches current 323 practice. 325 - Remove non-closure warning alerts. Require treating unknown 326 alerts as fatal. 328 - Make the rules for accepting 0-RTT less restrictive. 330 - Clarify 0-RTT backward-compatibility rules. 332 - Clarify how 0-RTT and PSK identities interact. 334 - Add a section describing the data limits for each cipher. 336 - Major editorial restructuring. 338 - Replace the Security Analysis section with a WIP draft. 340 draft-13 342 - Allow server to send SupportedGroups. 344 - Remove 0-RTT client authentication 346 - Remove (EC)DHE 0-RTT. 348 - Flesh out 0-RTT PSK mode and shrink EarlyDataIndication 350 - Turn PSK-resumption response into an index to save room 352 - Move CertificateStatus to an extension 354 - Extra fields in NewSessionTicket. 356 - Restructure key schedule and add a resumption_context value. 358 - Require DH public keys and secrets to be zero-padded to the size 359 of the group. 361 - Remove the redundant length fields in KeyShareEntry. 363 - Define a cookie field for HRR. 365 draft-12 367 - Provide a list of the PSK cipher suites. 369 - Remove the ability for the ServerHello to have no extensions (this 370 aligns the syntax with the text). 372 - Clarify that the server can send application data after its first 373 flight (0.5 RTT data) 375 - Revise signature algorithm negotiation to group hash, signature 376 algorithm, and curve together. This is backwards compatible. 378 - Make ticket lifetime mandatory and limit it to a week. 380 - Make the purpose strings lower-case. This matches how people are 381 implementing for interop. 383 - Define exporters. 385 - Editorial cleanup 386 - Port the CFRG curves & signatures work from RFC4492bis. 388 - Remove sequence number and version from additional_data, which is 389 now empty. 391 - Reorder values in HkdfLabel. 393 - Add support for version anti-downgrade mechanism. 395 - Update IANA considerations section and relax some of the policies. 397 - Unify authentication modes. Add post-handshake client 398 authentication. 400 - Remove early_handshake content type. Terminate 0-RTT data with an 401 alert. 403 - Reset sequence number upon key change (as proposed by Fournet et 404 al.) 406 draft-10 408 - Remove ClientCertificateTypes field from CertificateRequest and 409 add extensions. 411 - Merge client and server key shares into a single extension. 413 draft-09 415 - Change to RSA-PSS signatures for handshake messages. 417 - Remove support for DSA. 419 - Update key schedule per suggestions by Hugo, Hoeteck, and Bjoern 420 Tackmann. 422 - Add support for per-record padding. 424 - Switch to encrypted record ContentType. 426 - Change HKDF labeling to include protocol version and value 427 lengths. 429 - Shift the final decision to abort a handshake due to incompatible 430 certificates to the client rather than having servers abort early. 432 - Deprecate SHA-1 with signatures. 434 - Add MTI algorithms. 436 draft-08 438 - Remove support for weak and lesser used named curves. 440 - Remove support for MD5 and SHA-224 hashes with signatures. 442 - Update lists of available AEAD cipher suites and error alerts. 444 - Reduce maximum permitted record expansion for AEAD from 2048 to 445 256 octets. 447 - Require digital signatures even when a previous configuration is 448 used. 450 - Merge EarlyDataIndication and KnownConfiguration. 452 - Change code point for server_configuration to avoid collision with 453 server_hello_done. 455 - Relax certificate_list ordering requirement to match current 456 practice. 458 draft-07 460 - Integration of semi-ephemeral DH proposal. 462 - Add initial 0-RTT support. 464 - Remove resumption and replace with PSK + tickets. 466 - Move ClientKeyShare into an extension. 468 - Move to HKDF. 470 draft-06 472 - Prohibit RC4 negotiation for backwards compatibility. 474 - Freeze & deprecate record layer version field. 476 - Update format of signatures with context. 478 - Remove explicit IV. 480 - Prohibit SSL negotiation for backwards compatibility. 482 - Fix which MS is used for exporters. 484 draft-04 486 - Modify key computations to include session hash. 488 - Remove ChangeCipherSpec. 490 - Renumber the new handshake messages to be somewhat more consistent 491 with existing convention and to remove a duplicate registration. 493 - Remove renegotiation. 495 - Remove point format negotiation. 497 draft-03 499 - Remove GMT time. 501 - Merge in support for ECC from RFC 4492 but without explicit 502 curves. 504 - Remove the unnecessary length field from the AD input to AEAD 505 ciphers. 507 - Rename {Client,Server}KeyExchange to {Client,Server}KeyShare. 509 - Add an explicit HelloRetryRequest to reject the client's. 511 draft-02 513 - Increment version number. 515 - Rework handshake to provide 1-RTT mode. 517 - Remove custom DHE groups. 519 - Remove support for compression. 521 - Remove support for static RSA and DH key exchange. 523 - Remove support for non-AEAD ciphers. 525 1.3. Updates Affecting TLS 1.2 527 This document defines several changes that optionally affect 528 implementations of TLS 1.2: 530 - A version downgrade protection mechanism is described in 531 Section 4.1.3. 533 - RSASSA-PSS signature schemes are defined in Section 4.2.3. 535 An implementation of TLS 1.3 that also supports TLS 1.2 might need to 536 include changes to support these changes even when TLS 1.3 is not in 537 use. See the referenced sections for more details. 539 2. Protocol Overview 541 The cryptographic parameters of the session state are produced by the 542 TLS handshake protocol, which a TLS client and server use when first 543 communicating to agree on a protocol version, select cryptographic 544 algorithms, optionally authenticate each other, and establish shared 545 secret keying material. Once the handshake is complete, the peers 546 use the established keys to protect application layer traffic. 548 A failure of the handshake or other protocol error triggers the 549 termination of the connection, optionally preceded by an alert 550 message (Section 6). 552 TLS supports three basic key exchange modes: 554 - Diffie-Hellman (both the finite field and elliptic curve 555 varieties), 557 - A pre-shared symmetric key (PSK), and 559 - A combination of a symmetric key and Diffie-Hellman. 561 Figure 1 below shows the basic full TLS handshake: 563 Client Server 565 Key ^ ClientHello 566 Exch | + key_share* 567 v + pre_shared_key* --------> 568 ServerHello ^ Key 569 + key_share* | Exch 570 + pre_shared_key* v 571 {EncryptedExtensions} ^ Server 572 {CertificateRequest*} v Params 573 {Certificate*} ^ 574 {CertificateVerify*} | Auth 575 {Finished} v 576 <-------- [Application Data*] 577 ^ {Certificate*} 578 Auth | {CertificateVerify*} 579 v {Finished} --------> 580 [Application Data] <-------> [Application Data] 582 + Indicates extensions sent in the 583 previously noted message. 585 * Indicates optional or situation-dependent 586 messages that are not always sent. 588 {} Indicates messages protected using keys 589 derived from handshake_traffic_secret. 591 [] Indicates messages protected using keys 592 derived from traffic_secret_N 594 Figure 1: Message flow for full TLS Handshake 596 The handshake can be thought of as having three phases (indicated in 597 the diagram above): 599 - Key Exchange: Establish shared keying material and select the 600 cryptographic parameters. Everything after this phase is 601 encrypted. 603 - Server Parameters: Establish other handshake parameters (whether 604 the client is authenticated, application layer protocol support, 605 etc.). 607 - Authentication: Authenticate the server (and optionally the 608 client) and provide key confirmation and handshake integrity. 610 In the Key Exchange phase, the client sends the ClientHello 611 (Section 4.1.2) message, which contains a random nonce 612 (ClientHello.random); its offered protocol versions; a list of 613 symmetric cipher/HKDF hash pairs; some set of Diffie-Hellman key 614 shares (in the "key_share" extension Section 4.2.5), one or more pre- 615 shared key labels (in the "pre_shared_key" extension Section 4.2.6), 616 or both; and potentially some other extensions. 618 The server processes the ClientHello and determines the appropriate 619 cryptographic parameters for the connection. It then responds with 620 its own ServerHello, which indicates the negotiated connection 621 parameters. [Section 4.1.3]. The combination of the ClientHello and 622 the ServerHello determines the shared keys. If (EC)DHE key 623 establishment is in use, then the ServerHello contains a "key_share" 624 extension with the server's ephemeral Diffie-Hellman share which MUST 625 be in the same group as one of the client's shares. If PSK key 626 establishment is in use, then the ServerHello contains a 627 "pre_shared_key" extension indicating which of the client's offered 628 PSKs was selected. Note that implementations can use (EC)DHE and PSK 629 together, in which case both extensions will be supplied. 631 The server then sends two messages to establish the Server 632 Parameters: 634 EncryptedExtensions. responses to any extensions that are not 635 required to determine the cryptographic parameters. 636 [Section 4.3.1] 638 CertificateRequest. if certificate-based client authentication is 639 desired, the desired parameters for that certificate. This 640 message is omitted if client authentication is not desired. 641 [Section 4.3.2] 643 Finally, the client and server exchange Authentication messages. TLS 644 uses the same set of messages every time that authentication is 645 needed. Specifically: 647 Certificate. the certificate of the endpoint. This message is 648 omitted if the server is not authenticating with a certificate. 649 Note that if raw public keys [RFC7250] or the cached information 650 extension [RFC7924] are in use, then this message will not contain 651 a certificate but rather some other value corresponding to the 652 server's long-term key. [Section 4.4.1] 654 CertificateVerify. a signature over the entire handshake using the 655 public key in the Certificate message. This message is omitted if 656 the server is not authenticating via a certificate. 657 [Section 4.4.2] 659 Finished. a MAC (Message Authentication Code) over the entire 660 handshake. This message provides key confirmation, binds the 661 endpoint's identity to the exchanged keys, and in PSK mode also 662 authenticates the handshake. [Section 4.4.3] 664 Upon receiving the server's messages, the client responds with its 665 Authentication messages, namely Certificate and CertificateVerify (if 666 requested), and Finished. 668 At this point, the handshake is complete, and the client and server 669 may exchange application layer data. Application data MUST NOT be 670 sent prior to sending the Finished message. Note that while the 671 server may send application data prior to receiving the client's 672 Authentication messages, any data sent at that point is, of course, 673 being sent to an unauthenticated peer. 675 2.1. Incorrect DHE Share 677 If the client has not provided a sufficient "key_share" extension 678 (e.g., it includes only DHE or ECDHE groups unacceptable or 679 unsupported by the server), the server corrects the mismatch with a 680 HelloRetryRequest and the client needs to restart the handshake with 681 an appropriate "key_share" extension, as shown in Figure 2. If no 682 common cryptographic parameters can be negotiated, the server MUST 683 abort the handshake with an appropriate alert. 685 Client Server 687 ClientHello 688 + key_share --------> 689 <-------- HelloRetryRequest 691 ClientHello 692 + key_share --------> 693 ServerHello 694 + key_share 695 {EncryptedExtensions} 696 {CertificateRequest*} 697 {Certificate*} 698 {CertificateVerify*} 699 {Finished} 700 <-------- [Application Data*] 701 {Certificate*} 702 {CertificateVerify*} 703 {Finished} --------> 704 [Application Data] <-------> [Application Data] 706 Figure 2: Message flow for a full handshake with mismatched 707 parameters 709 Note: The handshake transcript includes the initial ClientHello/ 710 HelloRetryRequest exchange; it is not reset with the new ClientHello. 712 TLS also allows several optimized variants of the basic handshake, as 713 described in the following sections. 715 2.2. Resumption and Pre-Shared Key (PSK) 717 Although TLS PSKs can be established out of band, PSKs can also be 718 established in a previous session and then reused ("session 719 resumption"). Once a handshake has completed, the server can send 720 the client a PSK identity that corresponds to a key derived from the 721 initial handshake (see Section 4.5.1). The client can then use that 722 PSK identity in future handshakes to negotiate use of the PSK. If 723 the server accepts it, then the security context of the new 724 connection is tied to the original connection. In TLS 1.2 and below, 725 this functionality was provided by "session IDs" and "session 726 tickets" [RFC5077]. Both mechanisms are obsoleted in TLS 1.3. 728 PSKs can be used with (EC)DHE exchange in order to provide forward 729 secrecy in combination with shared keys, or can be used alone, at the 730 cost of losing forward secrecy. 732 Figure 3 shows a pair of handshakes in which the first establishes a 733 PSK and the second uses it: 735 Client Server 737 Initial Handshake: 738 ClientHello 739 + key_share --------> 740 ServerHello 741 + key_share 742 {EncryptedExtensions} 743 {CertificateRequest*} 744 {Certificate*} 745 {CertificateVerify*} 746 {Finished} 747 <-------- [Application Data*] 748 {Certificate*} 749 {CertificateVerify*} 750 {Finished} --------> 751 <-------- [NewSessionTicket] 752 [Application Data] <-------> [Application Data] 754 Subsequent Handshake: 755 ClientHello 756 + pre_shared_key 757 + key_share* --------> 758 ServerHello 759 + pre_shared_key 760 + key_share* 761 {EncryptedExtensions} 762 {Finished} 763 <-------- [Application Data*] 764 {Finished} --------> 765 [Application Data] <-------> [Application Data] 767 Figure 3: Message flow for resumption and PSK 769 As the server is authenticating via a PSK, it does not send a 770 Certificate or a CertificateVerify message. When a client offers 771 resumption via PSK, it SHOULD also supply a "key_share" extension to 772 the server as well to allow the server to decline resumption and fall 773 back to a full handshake, if needed. The server responds with a 774 "pre_shared_key" extension to negotiate use of PSK key establishment 775 and can (as shown here) respond with a "key_share" extension to do 776 (EC)DHE key establishment, thus providing forward secrecy. 778 2.3. Zero-RTT Data 780 When resuming via a PSK with an appropriate ticket (i.e., one with 781 the "early_data_info" extension), clients can also send data on their 782 first flight ("early data"). This data is encrypted solely under 783 keys derived using the first offered PSK as the static secret. As 784 shown in Figure 4, the Zero-RTT data is just added to the 1-RTT 785 handshake in the first flight. The rest of the handshake uses the 786 same messages as with a 1-RTT handshake with PSK resumption. 788 Client Server 790 ClientHello 791 + early_data 792 + pre_shared_key 793 + key_share* 794 (Finished) 795 (Application Data*) 796 (end_of_early_data) --------> 797 ServerHello 798 + early_data 799 + pre_shared_key 800 + key_share* 801 {EncryptedExtensions} 802 {Finished} 803 <-------- [Application Data*] 804 {Finished} --------> 806 [Application Data] <-------> [Application Data] 808 * Indicates optional or situation-dependent 809 messages that are not always sent. 811 () Indicates messages protected using keys 812 derived from client_early_traffic_secret. 814 {} Indicates messages protected using keys 815 derived from handshake_traffic_secret. 817 [] Indicates messages protected using keys 818 derived from traffic_secret_N 820 Figure 4: Message flow for a zero round trip handshake 822 [[OPEN ISSUE: Should it be possible to combine 0-RTT with the server 823 authenticating via a signature https://github.com/tlswg/tls13-spec/ 824 issues/443]] 825 IMPORTANT NOTE: The security properties for 0-RTT data are weaker 826 than those for other kinds of TLS data. Specifically: 828 1. This data is not forward secret, because it is encrypted solely 829 with the PSK. 831 2. There are no guarantees of non-replay between connections. 832 Unless the server takes special measures outside those provided 833 by TLS, the server has no guarantee that the same 0-RTT data was 834 not transmitted on multiple 0-RTT connections (See 835 Section 4.2.7.2 for more details). This is especially relevant 836 if the data is authenticated either with TLS client 837 authentication or inside the application layer protocol. 838 However, 0-RTT data cannot be duplicated within a connection 839 (i.e., the server will not process the same data twice for the 840 same connection) and an attacker will not be able to make 0-RTT 841 data appear to be 1-RTT data (because it is protected with 842 different keys.) 844 The remainder of this document provides a detailed description of 845 TLS. 847 3. Presentation Language 849 This document deals with the formatting of data in an external 850 representation. The following very basic and somewhat casually 851 defined presentation syntax will be used. The syntax draws from 852 several sources in its structure. Although it resembles the 853 programming language "C" in its syntax and XDR [RFC4506] in both its 854 syntax and intent, it would be risky to draw too many parallels. The 855 purpose of this presentation language is to document TLS only; it has 856 no general application beyond that particular goal. 858 3.1. Basic Block Size 860 The representation of all data items is explicitly specified. The 861 basic data block size is one byte (i.e., 8 bits). Multiple byte data 862 items are concatenations of bytes, from left to right, from top to 863 bottom. From the byte stream, a multi-byte item (a numeric in the 864 example) is formed (using C notation) by: 866 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 867 ... | byte[n-1]; 869 This byte ordering for multi-byte values is the commonplace network 870 byte order or big-endian format. 872 3.2. Miscellaneous 874 Comments begin with "/*" and end with "*/". 876 Optional components are denoted by enclosing them in "[[ ]]" double 877 brackets. 879 Single-byte entities containing uninterpreted data are of type 880 opaque. 882 3.3. Vectors 884 A vector (single-dimensioned array) is a stream of homogeneous data 885 elements. The size of the vector may be specified at documentation 886 time or left unspecified until runtime. In either case, the length 887 declares the number of bytes, not the number of elements, in the 888 vector. The syntax for specifying a new type, T', that is a fixed- 889 length vector of type T is 891 T T'[n]; 893 Here, T' occupies n bytes in the data stream, where n is a multiple 894 of the size of T. The length of the vector is not included in the 895 encoded stream. 897 In the following example, Datum is defined to be three consecutive 898 bytes that the protocol does not interpret, while Data is three 899 consecutive Datum, consuming a total of nine bytes. 901 opaque Datum[3]; /* three uninterpreted bytes */ 902 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 904 Variable-length vectors are defined by specifying a subrange of legal 905 lengths, inclusively, using the notation . When 906 these are encoded, the actual length precedes the vector's contents 907 in the byte stream. The length will be in the form of a number 908 consuming as many bytes as required to hold the vector's specified 909 maximum (ceiling) length. A variable-length vector with an actual 910 length field of zero is referred to as an empty vector. 912 T T'; 914 In the following example, mandatory is a vector that must contain 915 between 300 and 400 bytes of type opaque. It can never be empty. 916 The actual length field consumes two bytes, a uint16, which is 917 sufficient to represent the value 400 (see Section 3.4). On the 918 other hand, longer can represent up to 800 bytes of data, or 400 919 uint16 elements, and it may be empty. Its encoding will include a 920 two-byte actual length field prepended to the vector. The length of 921 an encoded vector must be an exact multiple of the length of a single 922 element (e.g., a 17-byte vector of uint16 would be illegal). 924 opaque mandatory<300..400>; 925 /* length field is 2 bytes, cannot be empty */ 926 uint16 longer<0..800>; 927 /* zero to 400 16-bit unsigned integers */ 929 3.4. Numbers 931 The basic numeric data type is an unsigned byte (uint8). All larger 932 numeric data types are formed from fixed-length series of bytes 933 concatenated as described in Section 3.1 and are also unsigned. The 934 following numeric types are predefined. 936 uint8 uint16[2]; 937 uint8 uint24[3]; 938 uint8 uint32[4]; 939 uint8 uint64[8]; 941 All values, here and elsewhere in the specification, are stored in 942 network byte (big-endian) order; the uint32 represented by the hex 943 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 945 3.5. Enumerateds 947 An additional sparse data type is available called enum. A field of 948 type enum can only assume the values declared in the definition. 949 Each definition is a different type. Only enumerateds of the same 950 type may be assigned or compared. Every element of an enumerated 951 must be assigned a value, as demonstrated in the following example. 952 Since the elements of the enumerated are not ordered, they can be 953 assigned any unique value, in any order. 955 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 957 An enumerated occupies as much space in the byte stream as would its 958 maximal defined ordinal value. The following definition would cause 959 one byte to be used to carry fields of type Color. 961 enum { red(3), blue(5), white(7) } Color; 963 One may optionally specify a value without its associated tag to 964 force the width definition without defining a superfluous element. 966 In the following example, Taste will consume two bytes in the data 967 stream but can only assume the values 1, 2, or 4. 969 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 971 The names of the elements of an enumeration are scoped within the 972 defined type. In the first example, a fully qualified reference to 973 the second element of the enumeration would be Color.blue. Such 974 qualification is not required if the target of the assignment is well 975 specified. 977 Color color = Color.blue; /* overspecified, legal */ 978 Color color = blue; /* correct, type implicit */ 980 For enumerateds that are never converted to external representation, 981 the numerical information may be omitted. 983 enum { low, medium, high } Amount; 985 3.6. Constructed Types 987 Structure types may be constructed from primitive types for 988 convenience. Each specification declares a new, unique type. The 989 syntax for definition is much like that of C. 991 struct { 992 T1 f1; 993 T2 f2; 994 ... 995 Tn fn; 996 } [[T]]; 998 The fields within a structure may be qualified using the type's name, 999 with a syntax much like that available for enumerateds. For example, 1000 T.f2 refers to the second field of the previous declaration. 1001 Structure definitions may be embedded. 1003 3.6.1. Variants 1005 Defined structures may have variants based on some knowledge that is 1006 available within the environment. The selector must be an enumerated 1007 type that defines the possible variants the structure defines. There 1008 must be a case arm for every element of the enumeration declared in 1009 the select. Case arms have limited fall-through: if two case arms 1010 follow in immediate succession with no fields in between, then they 1011 both contain the same fields. Thus, in the example below, "orange" 1012 and "banana" both contain V2. Note that this piece of syntax was 1013 added in TLS 1.2 [RFC5246]. 1015 The body of the variant structure may be given a label for reference. 1016 The mechanism by which the variant is selected at runtime is not 1017 prescribed by the presentation language. 1019 struct { 1020 T1 f1; 1021 T2 f2; 1022 .... 1023 Tn fn; 1024 select (E) { 1025 case e1: Te1; 1026 case e2: Te2; 1027 case e3: case e4: Te3; 1028 .... 1029 case en: Ten; 1030 } [[fv]]; 1031 } [[Tv]]; 1033 For example: 1035 enum { apple, orange, banana } VariantTag; 1037 struct { 1038 uint16 number; 1039 opaque string<0..10>; /* variable length */ 1040 } V1; 1042 struct { 1043 uint32 number; 1044 opaque string[10]; /* fixed length */ 1045 } V2; 1047 struct { 1048 select (VariantTag) { /* value of selector is implicit */ 1049 case apple: 1050 V1; /* VariantBody, tag = apple */ 1051 case orange: 1052 case banana: 1053 V2; /* VariantBody, tag = orange or banana */ 1054 } variant_body; /* optional label on variant */ 1055 } VariantRecord; 1057 3.7. Constants 1059 Typed constants can be defined for purposes of specification by 1060 declaring a symbol of the desired type and assigning values to it. 1062 Under-specified types (opaque, variable-length vectors, and 1063 structures that contain opaque) cannot be assigned values. No fields 1064 of a multi-element structure or vector may be omitted. 1066 For example: 1068 struct { 1069 uint8 f1; 1070 uint8 f2; 1071 } Example1; 1073 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 1075 3.8. Decoding Errors 1077 TLS defines two generic alerts (see Section 6) to use upon failure to 1078 parse a message. Peers which receive a message which cannot be 1079 parsed according to the syntax (e.g., have a length extending beyond 1080 the message boundary or contain an out-of-range length) MUST 1081 terminate the connection with a "decoding_error" alert. Peers which 1082 receive a message which is syntactically correct but semantically 1083 invalid (e.g., a DHE share of p - 1) MUST terminate the connection 1084 with an "illegal_parameter" alert. 1086 4. Handshake Protocol 1088 The handshake protocol is used to negotiate the secure attributes of 1089 a session. Handshake messages are supplied to the TLS record layer, 1090 where they are encapsulated within one or more TLSPlaintext or 1091 TLSCiphertext structures, which are processed and transmitted as 1092 specified by the current active session state. 1094 enum { 1095 client_hello(1), 1096 server_hello(2), 1097 new_session_ticket(4), 1098 hello_retry_request(6), 1099 encrypted_extensions(8), 1100 certificate(11), 1101 certificate_request(13), 1102 certificate_verify(15), 1103 finished(20), 1104 key_update(24), 1105 (255) 1106 } HandshakeType; 1108 struct { 1109 HandshakeType msg_type; /* handshake type */ 1110 uint24 length; /* bytes in message */ 1111 select (Handshake.msg_type) { 1112 case client_hello: ClientHello; 1113 case server_hello: ServerHello; 1114 case hello_retry_request: HelloRetryRequest; 1115 case encrypted_extensions: EncryptedExtensions; 1116 case certificate_request: CertificateRequest; 1117 case certificate: Certificate; 1118 case certificate_verify: CertificateVerify; 1119 case finished: Finished; 1120 case new_session_ticket: NewSessionTicket; 1121 case key_update: KeyUpdate; 1122 } body; 1123 } Handshake; 1125 Protocol messages MUST be sent in the order defined below (and shown 1126 in the diagrams in Section 2). A peer which receives a handshake 1127 message in an unexpected order MUST abort the handshake with an 1128 "unexpected_message" alert. results in an "unexpected_message" fatal 1129 error. Unneeded handshake messages are omitted, however. 1131 New handshake message types are assigned by IANA as described in 1132 Section 10. 1134 4.1. Key Exchange Messages 1136 The key exchange messages are used to exchange security capabilities 1137 between the client and server and to establish the traffic keys used 1138 to protect the handshake and data. 1140 4.1.1. Cryptographic Negotiation 1142 TLS cryptographic negotiation proceeds by the client offering the 1143 following four sets of options in its ClientHello: 1145 - A list of cipher suites which indicates the AEAD algorithm/HKDF 1146 hash pairs which the client supports. 1148 - A "supported_group" (Section 4.2.4) extension which indicates the 1149 (EC)DHE groups which the client supports and a "key_share" 1150 (Section 4.2.5) extension which contains (EC)DHE shares for some 1151 or all of these groups. 1153 - A "signature_algorithms" (Section 4.2.3) extension which indicates 1154 the signature algorithms which the client can accept. 1156 - A "pre_shared_key" (Section 4.2.6) extension which contains the 1157 identities of symmetric keys known to the client and the key 1158 exchange modes which each PSK supports. 1160 If the server does not select a PSK, then the first three of these 1161 options are entirely orthogonal: the server independently selects a 1162 cipher suite, an (EC)DHE group and key share for key establishment, 1163 and a signature algorithm/certificate pair to authenticate itself to 1164 the client. If there is overlap in the "supported_group" extension 1165 but the client did not offer a compatible "key_share" extension, then 1166 the server will respond with a HelloRetryRequest (Section 4.1.4) 1167 message. 1169 If the server selects a PSK, then the PSK will indicate which key 1170 establishment modes it can be used with (PSK alone or with (EC)DHE) 1171 and which authentication modes it can be used with (PSK alone or PSK 1172 with signatures). The server can then select those key establishment 1173 and authentication parameters to be consistent both with the PSK and 1174 the other extensions supplied by the client. Note that if the PSK 1175 can be used without (EC)DHE or without signatures, then non-overlap 1176 in either of these parameters need not be fatal. 1178 The server indicates its selected parameters in the ServerHello as 1179 follows: 1181 - If PSK is being used then the server will send a "pre_shared_key" 1182 extension indicating the selected key. 1184 - If PSK is not being used, then (EC)DHE and certificate-based 1185 authentication are always used. 1187 - When (EC)DHE is in use, the server will also provide a "key_share" 1188 extension. 1190 - When authenticating via a certificate, the server will send an 1191 empty "signature_algorithms" extension in the ServerHello and will 1192 subsequently send Certificate (Section 4.4.1) and 1193 CertificateVerify (Section 4.4.2) messages. 1195 If the server is unable to negotiate a supported set of parameters 1196 (i.e., there is no overlap between the client and server parameters), 1197 it MUST abort the handshake and and SHOULD send either a 1198 "handshake_failure" or "insufficient_security" fatal alert (see 1199 Section 6). 1201 4.1.2. Client Hello 1203 When this message will be sent: 1205 When a client first connects to a server, it is REQUIRED to send 1206 the ClientHello as its first message. The client will also send a 1207 ClientHello when the server has responded to its ClientHello with 1208 a HelloRetryRequest. In that case, the client MUST send the same 1209 ClientHello (without modification) except: 1211 - Including a new KeyShareEntry as the lowest priority share (i.e., 1212 appended to the list of shares in the "key_share" extension). 1214 - Removing the "early_data" extension (Section 4.2.7) if one was 1215 present. Early data is not permitted after HelloRetryRequest. 1217 - Including a "cookie" extension if one was provided in the 1218 HelloRetryRequest. 1220 Because TLS 1.3 forbids renegotiation, if a server receives a 1221 ClientHello at any other time, it MUST terminate the connection. 1223 If a server established a TLS connection with a previous version of 1224 TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST 1225 retain the previous protocol version. In particular, it MUST NOT 1226 negotiate TLS 1.3. A client that receives a TLS 1.3 ServerHello 1227 during renegotiation MUST abort the handshake with a 1228 "protocol_version" alert. 1230 Structure of this message: 1232 struct { 1233 uint8 major; 1234 uint8 minor; 1235 } ProtocolVersion; 1237 struct { 1238 opaque random_bytes[32]; 1239 } Random; 1241 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1243 struct { 1244 ProtocolVersion legacy_version = { 3, 3 }; /* TLS v1.2 */ 1245 Random random; 1246 opaque legacy_session_id<0..32>; 1247 CipherSuite cipher_suites<2..2^16-2>; 1248 opaque legacy_compression_methods<1..2^8-1>; 1249 Extension extensions<0..2^16-1>; 1250 } ClientHello; 1252 TLS allows extensions to follow the compression_methods field in an 1253 extensions block. The presence of extensions can be detected by 1254 determining whether there are bytes following the compression_methods 1255 at the end of the ClientHello. Note that this method of detecting 1256 optional data differs from the normal TLS method of having a 1257 variable-length field, but it is used for compatibility with TLS 1258 before extensions were defined. As of TLS 1.3, all clients and 1259 servers will send at least one extension (at least "key_share" or 1260 "pre_shared_key"). 1262 legacy_version In previous versions of TLS, this field was used for 1263 version negotiation and represented the highest version number 1264 supported by the client. Experience has shown that many servers 1265 do not properly implement version negotiation, leading to "version 1266 intolerance" in which the server rejects an otherwise acceptable 1267 ClientHello with a version number higher than it supports. 1268 In TLS 1.3, the client indicates its version preferences in the 1269 "suported_versions" extension (Section 4.2.1) and this field MUST 1270 be set to {3, 3}, which was the version number for TLS 1.2. (See 1271 Appendix C for details about backward compatibility.) 1273 random 32 bytes generated by a secure random number generator. See 1274 Appendix B for additional information. 1276 legacy_session_id Versions of TLS before TLS 1.3 supported a session 1277 resumption feature which has been merged with Pre-Shared Keys in 1278 this version (see Section 2.2). This field MUST be ignored by a 1279 server negotiating TLS 1.3 and SHOULD be set as a zero length 1280 vector (i.e., a single zero byte length field) by clients which do 1281 not have a cached session ID set by a pre-TLS 1.3 server. 1283 cipher_suites This is a list of the symmetric cipher options 1284 supported by the client, specifically the record protection 1285 algorithm (including secret key length) and a hash to be used with 1286 HKDF, in descending order of client preference. If the list 1287 contains cipher suites the server does not recognize, support, or 1288 wish to use, the server MUST ignore those cipher suites, and 1289 process the remaining ones as usual. Values are defined in 1290 Appendix A.4. 1292 legacy_compression_methods Versions of TLS before 1.3 supported 1293 compression with the list of supported compression methods being 1294 sent in this field. For every TLS 1.3 ClientHello, this vector 1295 MUST contain exactly one byte set to zero, which corresponds to 1296 the "null" compression method in prior versions of TLS. If a TLS 1297 1.3 ClientHello is received with any other value in this field, 1298 the server MUST abort the handshake with an "illegal_parameter" 1299 alert. Note that TLS 1.3 servers might receive TLS 1.2 or prior 1300 ClientHellos which contain other compression methods and MUST 1301 follow the procedures for the appropriate prior version of TLS. 1303 extensions Clients request extended functionality from servers by 1304 sending data in the extensions field. The actual "Extension" 1305 format is defined in Section 4.2. 1307 In the event that a client requests additional functionality using 1308 extensions, and this functionality is not supplied by the server, the 1309 client MAY abort the handshake. Note that TLS 1.3 ClientHello 1310 messages MUST always contain extensions, and a TLS 1.3 server MUST 1311 respond to any TLS 1.3 ClientHello without extensions or with data 1312 following the extensions block with a "decode_error" alert. TLS 1.3 1313 servers may receive TLS 1.2 ClientHello messages without extensions. 1314 If negotiating TLS 1.2, a server MUST check that the message either 1315 contains no data after legacy_compression_methods or that it contains 1316 a valid extensions block with no data following. If not, then it 1317 MUST abort the handshake with a "decode_error" alert. 1319 After sending the ClientHello message, the client waits for a 1320 ServerHello or HelloRetryRequest message. 1322 4.1.3. Server Hello 1324 When this message will be sent: 1326 The server will send this message in response to a ClientHello 1327 message when it was able to find an acceptable set of algorithms 1328 and the client's "key_share" extension was acceptable. If it is 1329 not able to find an acceptable set of parameters, the server will 1330 respond with a "handshake_failure" fatal alert. 1332 Structure of this message: 1334 struct { 1335 ProtocolVersion version; 1336 Random random; 1337 CipherSuite cipher_suite; 1338 Extension extensions<0..2^16-1>; 1339 } ServerHello; 1341 version This field contains the version of TLS negotiated for this 1342 session. Servers MUST select the lower of the highest supported 1343 server version and the version offered by the client in the 1344 ClientHello. In particular, servers MUST accept ClientHello 1345 messages with versions higher than those supported and negotiate 1346 the highest mutually supported version. For this version of the 1347 specification, the version is { 3, 4 }. (See Appendix C for 1348 details about backward compatibility.) 1350 random This structure is generated by the server and MUST be 1351 generated independently of the ClientHello.random. 1353 cipher_suite The single cipher suite selected by the server from the 1354 list in ClientHello.cipher_suites. A client which receives a 1355 cipher suite that was not offered MUST abort the handshake. 1357 extensions A list of extensions. Note that only extensions offered 1358 by the client can appear in the server's list. In TLS 1.3, as 1359 opposed to previous versions of TLS, the server's extensions are 1360 split between the ServerHello and the EncryptedExtensions 1361 Section 4.3.1 message. The ServerHello MUST only include 1362 extensions which are required to establish the cryptographic 1363 context. Currently the only such extensions are "key_share", 1364 "pre_shared_key", and "signature_algorithms". Clients MUST check 1365 the ServerHello for the presence of any forbidden extensions and 1366 if any are found MUST abort the handshake with a 1367 "illegal_parameter" alert. In prior versions of TLS, the 1368 extensions field could be omitted entirely if not needed, similar 1369 to ClientHello. As of TLS 1.3, all clients and servers will send 1370 at least one extension (at least "key_share" or "pre_shared_key"). 1372 TLS 1.3 has a downgrade protection mechanism embedded in the server's 1373 random value. TLS 1.3 server implementations which respond to a 1374 ClientHello indicating only support for TLS 1.2 or below MUST set the 1375 last eight bytes of their Random value to the bytes: 1377 44 4F 57 4E 47 52 44 01 1379 TLS 1.3 server implementations which respond to a ClientHello 1380 indicating only support for TLS 1.1 or below SHOULD set the last 1381 eight bytes of their Random value to the bytes: 1383 44 4F 57 4E 47 52 44 00 1385 TLS 1.3 clients receiving a TLS 1.2 or below ServerHello MUST check 1386 that the last eight octets are not equal to either of these values. 1387 TLS 1.2 clients SHOULD also perform this check if the ServerHello 1388 indicates TLS 1.1 or below. If a match is found, the client MUST 1389 abort the handshake with an "illegal_parameter" alert. This 1390 mechanism provides limited protection against downgrade attacks over 1391 and above that provided by the Finished exchange: because the 1392 ServerKeyExchange includes a signature over both random values, it is 1393 not possible for an active attacker to modify the randoms without 1394 detection as long as ephemeral ciphers are used. It does not provide 1395 downgrade protection when static RSA is used. 1397 Note: This is an update to TLS 1.2 so in practice many TLS 1.2 1398 clients and servers will not behave as specified above. 1400 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH Implementations of 1401 draft versions (see Section 4.2.1.1) of this specification SHOULD NOT 1402 implement this mechanism on either client and server. A pre-RFC 1403 client connecting to RFC servers, or vice versa, will appear to 1404 downgrade to TLS 1.2. With the mechanism enabled, this will cause an 1405 interoperability failure. 1407 4.1.4. Hello Retry Request 1409 When this message will be sent: 1411 Servers send this message in response to a ClientHello message if 1412 they were able to find an acceptable set of algorithms and groups 1413 that are mutually supported, but the client's ClientHello did not 1414 contain sufficient information to proceed with the handshake. If 1415 a server cannot successfully select algorithms, it MUST abort the 1416 handshake with a "handshake_failure" alert. 1418 Structure of this message: 1420 struct { 1421 ProtocolVersion server_version; 1422 Extension extensions<2..2^16-1>; 1423 } HelloRetryRequest; 1425 The version and extensions fields have the same meanings as their 1426 corresponding values in the ServerHello. The server SHOULD send only 1427 the extensions necessary for the client to generate a correct 1428 ClientHello pair (currently no such extensions exist). As with 1429 ServerHello, a HelloRetryRequest MUST NOT contain any extensions that 1430 were not first offered by the client in its ClientHello, with the 1431 exception of optionally the "cookie" (see Section 4.2.2) extension. 1433 Upon receipt of a HelloRetryRequest, the client MUST verify that the 1434 extensions block is not empty and otherwise MUST abort the handshake 1435 with a "decode_error" alert. Clients SHOULD also abort the handshake 1436 with an "unexpected_message" alert in response to any second 1437 HelloRetryRequest which was sent in the same connection (i.e., where 1438 the ClientHello was itself in response to a HelloRetryRequest). 1440 Otherwise, the client MUST process all extensions in the 1441 HelloRetryRequest and send a second updated ClientHello. The 1442 HelloRetryRequest extensions defined in this specification are: 1444 - cookie (see Section 4.2.2) 1446 - key_share (see Section 4.2.5) 1448 Note that HelloRetryRequest extensions are defined such that the 1449 original ClientHello may be computed from the new one, given minimal 1450 state about which HelloRetryRequest extensions were sent. For 1451 example, the key_share extension causes the new KeyShareEntry to be 1452 appended to the client_shares field, rather than replacing it. 1454 4.2. Hello Extensions 1456 The extension format is: 1458 struct { 1459 ExtensionType extension_type; 1460 opaque extension_data<0..2^16-1>; 1461 } Extension; 1463 enum { 1464 supported_groups(10), 1465 signature_algorithms(13), 1466 key_share(40), 1467 pre_shared_key(41), 1468 early_data(42), 1469 supported_versions(43), 1470 cookie(44), 1471 (65535) 1472 } ExtensionType; 1474 Here: 1476 - "extension_type" identifies the particular extension type. 1478 - "extension_data" contains information specific to the particular 1479 extension type. 1481 The initial set of extensions is defined in [RFC6066]. The list of 1482 extension types is maintained by IANA as described in Section 10. 1484 An extension type MUST NOT appear in the ServerHello or 1485 HelloRetryRequest unless the same extension type appeared in the 1486 corresponding ClientHello. If a client receives an extension type in 1487 ServerHello or HelloRetryRequest that it did not request in the 1488 associated ClientHello, it MUST abort the handshake with an 1489 "unsupported_extension" fatal alert. 1491 Nonetheless, "server-oriented" extensions may be provided within this 1492 framework. Such an extension (say, of type x) would require the 1493 client to first send an extension of type x in a ClientHello with 1494 empty extension_data to indicate that it supports the extension type. 1495 In this case, the client is offering the capability to understand the 1496 extension type, and the server is taking the client up on its offer. 1498 When multiple extensions of different types are present in the 1499 ClientHello or ServerHello messages, the extensions MAY appear in any 1500 order. There MUST NOT be more than one extension of the same type. 1502 Finally, note that extensions can be sent both when starting a new 1503 session and when in resumption-PSK mode. A client that requests 1504 session resumption does not in general know whether the server will 1505 accept this request, and therefore it SHOULD send the same extensions 1506 as it would send normally. 1508 In general, the specification of each extension type needs to 1509 describe the effect of the extension both during full handshake and 1510 session resumption. Most current TLS extensions are relevant only 1511 when a session is initiated: when an older session is resumed, the 1512 server does not process these extensions in ClientHello, and does not 1513 include them in ServerHello. However, some extensions may specify 1514 different behavior during session resumption. [[TODO: update this 1515 and the previous paragraph to cover PSK-based resumption.]] 1517 There are subtle (and not so subtle) interactions that may occur in 1518 this protocol between new features and existing features which may 1519 result in a significant reduction in overall security. The following 1520 considerations should be taken into account when designing new 1521 extensions: 1523 - Some cases where a server does not agree to an extension are error 1524 conditions, and some are simply refusals to support particular 1525 features. In general, error alerts should be used for the former, 1526 and a field in the server extension response for the latter. 1528 - Extensions should, as far as possible, be designed to prevent any 1529 attack that forces use (or non-use) of a particular feature by 1530 manipulation of handshake messages. This principle should be 1531 followed regardless of whether the feature is believed to cause a 1532 security problem. Often the fact that the extension fields are 1533 included in the inputs to the Finished message hashes will be 1534 sufficient, but extreme care is needed when the extension changes 1535 the meaning of messages sent in the handshake phase. Designers 1536 and implementors should be aware of the fact that until the 1537 handshake has been authenticated, active attackers can modify 1538 messages and insert, remove, or replace extensions. 1540 4.2.1. Supported Versions 1542 struct { 1543 ProtocolVersion versions<2..254>; 1544 } SupportedVersions; 1546 The "supported_versions" extension is used by the client to indicate 1547 which versions of TLS it supports. The extension contains a list of 1548 supported versions in preference order, with the most preferred 1549 version first. Implementations of this specification MUST send this 1550 extension containing all versions of TLS which they are prepared to 1551 negotiate (for this specification, that means minimally {3, 4}, but 1552 if previous versions of TLS are supported, they MUST be present as 1553 well). 1555 Servers which are compliant with this specification MUST use only the 1556 "supported_versions" extension, if present, to determine client 1557 preferences and MUST only select a version of TLS present in that 1558 extension. They MUST ignore any unknown versions. If the extension 1559 is not present, they MUST negotiate TLS 1.2 or prior as specified in 1560 [RFC5246], even if ClientHello.legacy_version is {3, 4} or later. 1562 The server MUST NOT send the "supported_versions" extension. The 1563 server's selected version is contained in the ServerHello.version 1564 field as in previous versions of TLS. 1566 4.2.1.1. Draft Version Indicator 1568 RFC EDITOR: PLEASE REMOVE THIS SECTION 1569 While the eventual version indicator for the RFC version of TLS 1.3 1570 will be {3, 4}, implementations of draft versions of this 1571 specification SHOULD instead advertise {0x7f, [draft-version]} in 1572 their "supported_versions" extension, in ServerHello.version, and 1573 HelloRetryRequest.server_version. This allows pre-RFC 1574 implementations to safely negotiate with each other, even if they 1575 would otherwise be incompatible. 1577 4.2.2. Cookie 1579 struct { 1580 opaque cookie<0..2^16-1>; 1581 } Cookie; 1583 Cookies serve two primary purposes: 1585 - Allowing the server to force the client to demonstrate 1586 reachability at their apparent network address (thus providing a 1587 measure of DoS protection). This is primarily useful for non- 1588 connection-oriented transports (see [RFC6347] for an example of 1589 this). 1591 - Allowing the server to offload state to the client, thus allowing 1592 it to send a HelloRetryRequest without storing any state. The 1593 server does this by pickling that post-ClientHello hash state into 1594 the cookie (protected with some suitable integrity algorithm). 1596 When sending a HelloRetryRequest, the server MAY provide a "cookie" 1597 extension to the client (this is an exception to the usual rule that 1598 the only extensions that may be sent are those that appear in the 1599 ClientHello). When sending the new ClientHello, the client MUST echo 1600 the value of the extension. Clients MUST NOT use cookies in 1601 subsequent connections. 1603 4.2.3. Signature Algorithms 1605 The client uses the "signature_algorithms" extension to indicate to 1606 the server which signature algorithms may be used in digital 1607 signatures. Clients which desire the server to authenticate via a 1608 certificate MUST send this extension. If a server is authenticating 1609 via a certificate and the client has not sent a 1610 "signature_algorithms" extension then the server MUST abort the 1611 handshake with a "missing_extension" alert (see Section 8.2). 1613 Servers which are authenticating via a certificate MUST indicate so 1614 by sending the client an empty "signature_algorithms" extension. 1616 The "extension_data" field of this extension in a ClientHello 1617 contains a "supported_signature_algorithms" value: 1619 enum { 1620 /* RSASSA-PKCS1-v1_5 algorithms */ 1621 rsa_pkcs1_sha1 (0x0201), 1622 rsa_pkcs1_sha256 (0x0401), 1623 rsa_pkcs1_sha384 (0x0501), 1624 rsa_pkcs1_sha512 (0x0601), 1626 /* ECDSA algorithms */ 1627 ecdsa_secp256r1_sha256 (0x0403), 1628 ecdsa_secp384r1_sha384 (0x0503), 1629 ecdsa_secp521r1_sha512 (0x0603), 1631 /* RSASSA-PSS algorithms */ 1632 rsa_pss_sha256 (0x0804), 1633 rsa_pss_sha384 (0x0805), 1634 rsa_pss_sha512 (0x0806), 1636 /* EdDSA algorithms */ 1637 ed25519 (0x0807), 1638 ed448 (0x0808), 1640 /* Reserved Code Points */ 1641 private_use (0xFE00..0xFFFF), 1642 (0xFFFF) 1643 } SignatureScheme; 1645 SignatureScheme supported_signature_algorithms<2..2^16-2>; 1647 Note: This enum is named "SignatureScheme" because there is already a 1648 "SignatureAlgorithm" type in TLS 1.2, which this replaces. We use 1649 the term "signature algorithm" throughout the text. 1651 Each SignatureScheme value lists a single signature algorithm that 1652 the client is willing to verify. The values are indicated in 1653 descending order of preference. Note that a signature algorithm 1654 takes as input an arbitrary-length message, rather than a digest. 1655 Algorithms which traditionally act on a digest should be defined in 1656 TLS to first hash the input with a specified hash algorithm and then 1657 proceed as usual. The code point groups listed above have the 1658 following meanings: 1660 RSASSA-PKCS1-v1_5 algorithms Indicates a signature algorithm using 1661 RSASSA-PKCS1-v1_5 [RFC3447] with the corresponding hash algorithm 1662 as defined in [SHS]. These values refer solely to signatures 1663 which appear in certificates (see Section 4.4.1.1) and are not 1664 defined for use in signed TLS handshake messages. 1666 ECDSA algorithms Indicates a signature algorithm using ECDSA 1667 [ECDSA], the corresponding curve as defined in ANSI X9.62 [X962] 1668 and FIPS 186-4 [DSS], and the corresponding hash algorithm as 1669 defined in [SHS]. The signature is represented as a DER-encoded 1670 [X690] ECDSA-Sig-Value structure. 1672 RSASSA-PSS algorithms Indicates a signature algorithm using RSASSA- 1673 PSS [RFC3447] with MGF1. The digest used in the mask generation 1674 function and the digest being signed are both the corresponding 1675 hash algorithm as defined in [SHS]. When used in signed TLS 1676 handshake messages, the length of the salt MUST be equal to the 1677 length of the digest output. This codepoint is defined for use 1678 with TLS 1.2 as well as TLS 1.3. 1680 EdDSA algorithms Indicates a signature algorithm using EdDSA as 1681 defined in [I-D.irtf-cfrg-eddsa] or its successors. Note that 1682 these correspond to the "PureEdDSA" algorithms and not the 1683 "prehash" variants. 1685 rsa_pkcs1_sha1, dsa_sha1, and ecdsa_sha1 SHOULD NOT be offered. 1686 Clients offering these values for backwards compatibility MUST list 1687 them as the lowest priority (listed after all other algorithms in the 1688 supported_signature_algorithms vector). TLS 1.3 servers MUST NOT 1689 offer a SHA-1 signed certificate unless no valid certificate chain 1690 can be produced without it (see Section 4.4.1.1). 1692 The signatures on certificates that are self-signed or certificates 1693 that are trust anchors are not validated since they begin a 1694 certification path (see [RFC5280], Section 3.2). A certificate that 1695 begins a certification path MAY use a signature algorithm that is not 1696 advertised as being supported in the "signature_algorithms" 1697 extension. 1699 Note that TLS 1.2 defines this extension differently. TLS 1.3 1700 implementations willing to negotiate TLS 1.2 MUST behave in 1701 accordance with the requirements of [RFC5246] when negotiating that 1702 version. In particular: 1704 - TLS 1.2 ClientHellos MAY omit this extension. 1706 - In TLS 1.2, the extension contained hash/signature pairs. The 1707 pairs are encoded in two octets, so SignatureScheme values have 1708 been allocated to align with TLS 1.2's encoding. Some legacy 1709 pairs are left unallocated. These algorithms are deprecated as of 1710 TLS 1.3. They MUST NOT be offered or negotiated by any 1711 implementation. In particular, MD5 [SLOTH] and SHA-224 MUST NOT 1712 be used. 1714 - ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature 1715 pairs. However, the old semantics did not constrain the signing 1716 curve. If TLS 1.2 is negotiated, implementations MUST be prepared 1717 to accept a signature that uses any curve that they advertised in 1718 the "supported_groups" extension. 1720 - Implementations that advertise support for RSASSA-PSS (which is 1721 mandatory in TLS 1.3), MUST be prepared to accept a signature 1722 using that scheme even when TLS 1.2 is negotiated. In TLS 1.2, 1723 RSASSA-PSS is used with RSA cipher suites. 1725 4.2.4. Negotiated Groups 1727 When sent by the client, the "supported_groups" extension indicates 1728 the named groups which the client supports for key exchange, ordered 1729 from most preferred to least preferred. 1731 Note: In versions of TLS prior to TLS 1.3, this extension was named 1732 "elliptic_curves" and only contained elliptic curve groups. See 1733 [RFC4492] and [RFC7919]. This extension was also used to negotiate 1734 ECDSA curves. Signature algorithms are now negotiated independently 1735 (see Section 4.2.3). 1737 The "extension_data" field of this extension contains a 1738 "NamedGroupList" value: 1740 enum { 1741 /* Elliptic Curve Groups (ECDHE) */ 1742 secp256r1 (23), secp384r1 (24), secp521r1 (25), 1743 x25519 (29), x448 (30), 1745 /* Finite Field Groups (DHE) */ 1746 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 1747 ffdhe6144 (259), ffdhe8192 (260), 1749 /* Reserved Code Points */ 1750 ffdhe_private_use (0x01FC..0x01FF), 1751 ecdhe_private_use (0xFE00..0xFEFF), 1752 (0xFFFF) 1753 } NamedGroup; 1755 struct { 1756 NamedGroup named_group_list<2..2^16-1>; 1757 } NamedGroupList; 1759 Elliptic Curve Groups (ECDHE) Indicates support of the corresponding 1760 named curve. Note that some curves are also recommended in ANSI 1761 X9.62 [X962] and FIPS 186-4 [DSS]. Others are recommended in 1762 [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for private 1763 use. 1765 Finite Field Groups (DHE) Indicates support of the corresponding 1766 finite field group, defined in [RFC7919]. Values 0x01FC through 1767 0x01FF are reserved for private use. 1769 Items in named_group_list are ordered according to the client's 1770 preferences (most preferred choice first). 1772 As of TLS 1.3, servers are permitted to send the "supported_groups" 1773 extension to the client. If the server has a group it prefers to the 1774 ones in the "key_share" extension but is still willing to accept the 1775 ClientHello, it SHOULD send "supported_groups" to update the client's 1776 view of its preferences; this extension SHOULD contain all groups the 1777 server supports, regardless of whether they are currently supported 1778 by the client. Clients MUST NOT act upon any information found in 1779 "supported_groups" prior to successful completion of the handshake, 1780 but MAY use the information learned from a successfully completed 1781 handshake to change what groups they offer to a server in subsequent 1782 connections. 1784 4.2.5. Key Share 1786 The "key_share" extension contains the endpoint's cryptographic 1787 parameters. 1789 Clients MAY send an empty client_shares vector in order to request 1790 group selection from the server at the cost of an additional round 1791 trip. (see Section 4.1.4) 1793 struct { 1794 NamedGroup group; 1795 opaque key_exchange<1..2^16-1>; 1796 } KeyShareEntry; 1798 group The named group for the key being exchanged. Finite Field 1799 Diffie-Hellman [DH] parameters are described in Section 4.2.5.1; 1800 Elliptic Curve Diffie-Hellman parameters are described in 1801 Section 4.2.5.2. 1803 key_exchange Key exchange information. The contents of this field 1804 are determined by the specified group and its corresponding 1805 definition. Endpoints MUST NOT send empty or otherwise invalid 1806 key_exchange values for any reason. 1808 The "extension_data" field of this extension contains a "KeyShare" 1809 value: 1811 struct { 1812 select (Handshake.msg_type) { 1813 case client_hello: 1814 KeyShareEntry client_shares<0..2^16-1>; 1816 case hello_retry_request: 1817 NamedGroup selected_group; 1819 case server_hello: 1820 KeyShareEntry server_share; 1821 }; 1822 } KeyShare; 1824 client_shares A list of offered KeyShareEntry values in descending 1825 order of client preference. This vector MAY be empty if the 1826 client is requesting a HelloRetryRequest. The ordering of values 1827 here SHOULD match that of the ordering of offered support in the 1828 "supported_groups" extension. 1830 selected_group The mutually supported group the server intends to 1831 negotiate and is requesting a retried ClientHello/KeyShare for. 1833 server_share A single KeyShareEntry value that is in the same group 1834 as one of the client's shares. 1836 Clients offer an arbitrary number of KeyShareEntry values, each 1837 representing a single set of key exchange parameters. For instance, 1838 a client might offer shares for several elliptic curves or multiple 1839 FFDHE groups. The key_exchange values for each KeyShareEntry MUST be 1840 generated independently. Clients MUST NOT offer multiple 1841 KeyShareEntry values for the same group. Clients MUST NOT offer any 1842 KeyShareEntry values for groups not listed in the client's 1843 "supported_groups" extension. Servers MAY check for violations of 1844 these rules and and MAY abort the handshake with an 1845 "illegal_parameter" alert if one is violated. 1847 Upon receipt of this extension in a HelloRetryRequest, the client 1848 MUST first verify that the selected_group field corresponds to a 1849 group which was provided in the "supported_groups" extension in the 1850 original ClientHello. It MUST then verify that the selected_group 1851 field does not correspond to a group which was provided in the 1852 "key_share" extension in the original ClientHello. If either of 1853 these checks fails, then the client MUST abort the handshake with an 1854 "illegal_parameter" alert. Otherwise, when sending the new 1855 ClientHello, the client MUST append a new KeyShareEntry for the group 1856 indicated in the selected_group field to the groups in its original 1857 KeyShare. The remaining KeyShareEntry values MUST be preserved. 1859 Note that a HelloRetryRequest might not include the "key_share" 1860 extension if other extensions are sent, such as if the server is only 1861 sending a cookie. 1863 If using (EC)DHE key establishment, servers offer exactly one 1864 KeyShareEntry in the ServerHello. This value MUST correspond to the 1865 KeyShareEntry value offered by the client that the server has 1866 selected for the negotiated key exchange. Servers MUST NOT send a 1867 KeyShareEntry for any group not indicated in the "supported_groups" 1868 extension. If a HelloRetryRequest was received, the client MUST 1869 verify that the selected NamedGroup matches that supplied in the 1870 selected_group field and MUST abort the connection with an 1871 "illegal_parameter" alert if it does not. 1873 [[TODO: Recommendation about what the client offers. Presumably 1874 which integer DH groups and which curves.]] 1876 4.2.5.1. Diffie-Hellman Parameters 1878 Diffie-Hellman [DH] parameters for both clients and servers are 1879 encoded in the opaque key_exchange field of a KeyShareEntry in a 1880 KeyShare structure. The opaque value contains the Diffie-Hellman 1881 public value (Y = g^X mod p), encoded as a big-endian integer, padded 1882 with zeros to the size of p in bytes. 1884 Note: For a given Diffie-Hellman group, the padding results in all 1885 public keys having the same length. 1887 Peers SHOULD validate each other's public key Y by ensuring that 1 < 1888 Y < p-1. This check ensures that the remote peer is properly behaved 1889 and isn't forcing the local system into a small subgroup. 1891 4.2.5.2. ECDHE Parameters 1893 ECDHE parameters for both clients and servers are encoded in the the 1894 opaque key_exchange field of a KeyShareEntry in a KeyShare structure. 1896 For secp256r1, secp384r1 and secp521r1, the contents are the byte 1897 string representation of an elliptic curve public value following the 1898 conversion routine in Section 4.3.6 of ANSI X9.62 [X962]. 1900 Although X9.62 supports multiple point formats, any given curve MUST 1901 specify only a single point format. All curves currently specified 1902 in this document MUST only be used with the uncompressed point format 1903 (the format for all ECDH functions is considered uncompressed). 1905 For x25519 and x448, the contents are the byte string inputs and 1906 outputs of the corresponding functions defined in [RFC7748], 32 bytes 1907 for x25519 and 56 bytes for x448. 1909 Note: Versions of TLS prior to 1.3 permitted point format 1910 negotiation; TLS 1.3 removes this feature in favor of a single point 1911 format for each curve. 1913 4.2.6. Pre-Shared Key Extension 1915 The "pre_shared_key" extension is used to indicate the identity of 1916 the pre-shared key to be used with a given handshake in association 1917 with PSK key establishment (see [RFC4279] for background). 1919 The "extension_data" field of this extension contains a 1920 "PreSharedKeyExtension" value: 1922 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 1923 enum { psk_auth(0), psk_sign_auth(1), (255) } PskAuthenticationMode; 1925 struct { 1926 PskKeyExchangeMode ke_modes<1..255>; 1927 PskAuthenticationMode auth_modes<1..255>; 1928 opaque identity<0..2^16-1>; 1929 } PskIdentity; 1931 struct { 1932 select (Handshake.msg_type) { 1933 case client_hello: 1934 PskIdentity identities<6..2^16-1>; 1936 case server_hello: 1937 uint16 selected_identity; 1938 }; 1939 } PreSharedKeyExtension; 1941 identities A list of the identities (labels for keys) that the 1942 client is willing to negotiate with the server. If sent alongside 1943 the "early_data" extension (see Section 4.2.7), the first identity 1944 is the one used for 0-RTT data. 1946 selected_identity The server's chosen identity expressed as a 1947 (0-based) index into the identities in the client's list. 1949 Each PSK offered by the client also indicates the authentication and 1950 key exchange modes with which the server can use it, with each list 1951 being in the order of the client's preference, with most preferred 1952 first. Any PSK MUST only be used with a single HKDF hash algorithm. 1954 This restriction is automatically enforced for PSKs established via 1955 NewSessionTicket (Section 4.5.1) but any externally-established PSKs 1956 MUST also follow this rule. 1958 PskKeyExchangeMode values have the following meanings: 1960 psk_ke PSK-only key establishment. In this mode, the server MUST 1961 not supply a "key_share" value. 1963 psk_dhe_ke PSK key establishment with (EC)DHE key establishment. In 1964 this mode, the client and servers MUST supply "key_share" values 1965 as described in Section 4.2.5. 1967 PskAuthenticationMode values have the following meanings: 1969 psk_auth PSK-only authentication. In this mode, the server MUST NOT 1970 supply either a Certificate or CertificateVerify message. [TODO: 1971 Add a signing mode.] 1973 In order to accept PSK key establishment, the server sends a 1974 "pre_shared_key" extension with the selected identity. Clients MUST 1975 verify that the server's selected_identity is within the range 1976 supplied by the client and that the "key_share" and 1977 "signature_algorithms" extensions are consistent with the indicated 1978 ke_modes and auth_modes values. If these values are not consistent, 1979 the client MUST abort the handshake with an "illegal_parameter" 1980 alert. 1982 If the server supplies an "early_data" extension, the client MUST 1983 verify that the server selected the first offered identity. If any 1984 other value is returned, the client MUST abort the handshake with an 1985 "unknown_psk_identity" alert. 1987 Note that although 0-RTT data is encrypted with the first PSK 1988 identity, the server MAY fall back to 1-RTT and select a different 1989 PSK identity if multiple identities are offered. 1991 4.2.7. Early Data Indication 1993 When PSK resumption is used, the client can send application data in 1994 its first flight of messages. If the client opts to do so, it MUST 1995 supply an "early_data" extension as well as the "pre_shared_key" 1996 extension. 1998 The "extension_data" field of this extension contains an 1999 "EarlyDataIndication" value: 2001 struct { 2002 select (Handshake.msg_type) { 2003 case client_hello: 2004 uint32 obfuscated_ticket_age; 2006 case server_hello: 2007 struct {}; 2008 }; 2009 } EarlyDataIndication; 2011 obfuscated_ticket_age The time since the client learned about the 2012 server configuration that it is using, in milliseconds. This 2013 value is added modulo 2^32 to with the "ticket_age_add" value that 2014 was included with the ticket, see Section 4.5.1. This addition 2015 prevents passive observers from correlating sessions unless 2016 tickets are reused. Note: because ticket lifetimes are restricted 2017 to a week, 32 bits is enough to represent any plausible age, even 2018 in milliseconds. 2020 A server MUST validate that the ticket_age is within a small 2021 tolerance of the time since the ticket was issued (see 2022 Section 4.2.7.2). If it is not, the server SHOULD proceed with the 2023 handshake but reject 0-RTT. 2025 The parameters for the 0-RTT data (symmetric cipher suite, ALPN, 2026 etc.) are the same as those which were negotiated in the connection 2027 which established the PSK. The PSK used to encrypt the early data 2028 MUST be the first PSK listed in the client's "pre_shared_key" 2029 extension. 2031 0-RTT messages sent in the first flight have the same content types 2032 as their corresponding messages sent in other flights (handshake, 2033 application_data, and alert respectively) but are protected under 2034 different keys. After all the 0-RTT application data messages (if 2035 any) have been sent, an "end_of_early_data" alert of type "warning" 2036 is sent to indicate the end of the flight. 0-RTT MUST always be 2037 followed by an "end_of_early_data" alert, which will be encrypted 2038 with the 0-RTT traffic keys. 2040 A server which receives an "early_data" extension can behave in one 2041 of two ways: 2043 - Ignore the extension and return no response. This indicates that 2044 the server has ignored any early data and an ordinary 1-RTT 2045 handshake is required. 2047 - Return an empty extension, indicating that it intends to process 2048 the early data. It is not possible for the server to accept only 2049 a subset of the early data messages. 2051 - Request that the client send another ClientHello by responding 2052 with a HelloRetryRequest. A client MUST NOT include the 2053 "early_data" extension in its followup ClientHello. 2055 In order to accept early data, the server server MUST have accepted a 2056 PSK cipher suite and selected the the first key offered in the 2057 client's "pre_shared_key" extension. In addition, it MUST verify 2058 that the following values are consistent with those negotiated in the 2059 connection during which the ticket was established. 2061 - The TLS version number, AEAD algorithm, and the hash for HKDF. 2063 - The selected ALPN [RFC7443] value, if any. 2065 Future extensions MUST define their interaction with 0-RTT. 2067 If any of these checks fail, the server MUST NOT respond with the 2068 extension and must discard all the remaining first flight data (thus 2069 falling back to 1-RTT). If the client attempts a 0-RTT handshake but 2070 the server rejects it, it will generally not have the 0-RTT record 2071 protection keys and must instead trial decrypt each record with the 2072 1-RTT handshake keys until it finds one that decrypts properly, and 2073 then pick up the handshake from that point. 2075 If the server chooses to accept the "early_data" extension, then it 2076 MUST comply with the same error handling requirements specified for 2077 all records when processing early data records. Specifically, if the 2078 server fails to decrypt any 0-RTT record following an accepted 2079 "early_data" extension it MUST terminate the connection with a 2080 "bad_record_mac" alert as per Section 5.2. 2082 If the server rejects the "early_data" extension, the client 2083 application MAY opt to retransmit the data once the handshake has 2084 been completed. TLS stacks SHOULD not do this automatically and 2085 client applications MUST take care that the negotiated parameters are 2086 consistent with those it expected. For example, if the ALPN value 2087 has changed, it is likely unsafe to retransmit the original 2088 application layer data. 2090 4.2.7.1. Processing Order 2092 Clients are permitted to "stream" 0-RTT data until they receive the 2093 server's Finished, only then sending the "end_of_early_data" alert. 2094 In order to avoid deadlock, when accepting "early_data", servers MUST 2095 process the client's Finished and then immediately send the 2096 ServerHello, rather than waiting for the client's "end_of_early_data" 2097 alert. 2099 4.2.7.2. Replay Properties 2101 As noted in Section 2.3, TLS provides a limited mechanism for replay 2102 protection for data sent by the client in the first flight. 2104 The "obfuscated_ticket_age" parameter in the client's "early_data" 2105 extension SHOULD be used by servers to limit the time over which the 2106 first flight might be replayed. A server can store the time at which 2107 it sends a session ticket to the client, or encode the time in the 2108 ticket. Then, each time it receives an "early_data" extension, it 2109 can subtract the base value and check to see if the value used by the 2110 client matches its expectations. 2112 The ticket age (the value with "ticket_age_add" subtracted) provided 2113 by the client will be shorter than the actual time elapsed on the 2114 server by a single round trip time. This difference is comprised of 2115 the delay in sending the NewSessionTicket message to the client, plus 2116 the time taken to send the ClientHello to the server. For this 2117 reason, a server SHOULD measure the round trip time prior to sending 2118 the NewSessionTicket message and account for that in the value it 2119 saves. 2121 To properly validate the ticket age, a server needs to save at least 2122 two items: 2124 - The time that the server generated the session ticket and the 2125 estimated round trip time can be added together to form a baseline 2126 time. 2128 - The "ticket_age_add" parameter from the NewSessionTicket is needed 2129 to recover the ticket age from the "obfuscated_ticket_age" 2130 parameter. 2132 There are several potential sources of error that make an exact 2133 measurement of time difficult. Variations in client and server 2134 clocks are likely to be minimal, outside of gross time corrections. 2135 Network propagation delays are most likely causes of a mismatch in 2136 legitimate values for elapsed time. Both the NewSessionTicket and 2137 ClientHello messages might be retransmitted and therefore delayed, 2138 which might be hidden by TCP. 2140 A small allowance for errors in clocks and variations in measurements 2141 is advisable. However, any allowance also increases the opportunity 2142 for replay. In this case, it is better to reject early data and fall 2143 back to a full 1-RTT handshake than to risk greater exposure to 2144 replay attacks. In common network topologies for browser clients, 2145 small allowances on the order of ten seconds are reasonable. Clock 2146 skew distributions are not symmetric, so the optimal tradeoff may 2147 involve an asymmetric replay window. 2149 4.2.8. OCSP Status Extensions 2151 [RFC6066] and [RFC6961] provide extensions to negotiate the server 2152 sending OCSP responses to the client. In TLS 1.2 and below, the 2153 server sends an empty extension to indicate negotiation of this 2154 extension and the OCSP information is carried in a CertificateStatus 2155 message. In TLS 1.3, the server's OCSP information is carried in an 2156 extension in EncryptedExtensions. Specifically: The body of the 2157 "status_request" or "status_request_v2" extension from the server 2158 MUST be a CertificateStatus structure as defined in [RFC6066] and 2159 [RFC6961] respectively. 2161 Note: This means that the certificate status appears prior to the 2162 certificates it applies to. This is slightly anomalous but matches 2163 the existing behavior for SignedCertificateTimestamps [RFC6962], and 2164 is more easily extensible in the handshake state machine. 2166 4.3. Server Parameters Messages 2168 The next two messages from the server, EncryptedExtensions and 2169 CertificateRequest, contain encrypted information from the server 2170 that determines the rest of the handshake. 2172 4.3.1. Encrypted Extensions 2174 When this message will be sent: 2176 In all handshakes, the server MUST send the EncryptedExtensions 2177 message immediately after the ServerHello message. This is the 2178 first message that is encrypted under keys derived from 2179 handshake_traffic_secret. 2181 Meaning of this message: 2183 The EncryptedExtensions message contains any extensions which 2184 should be protected, i.e., any which are not needed to establish 2185 the cryptographic context. 2187 The same extension types MUST NOT appear in both the ServerHello and 2188 EncryptedExtensions. All server-sent extensions other than those 2189 explicitly listed in Section 4.1.3 or designated in the IANA registry 2190 MUST only appear in EncryptedExtensions. Extensions which are 2191 designated to appear in ServerHello MUST NOT appear in 2192 EncryptedExtensions. Clients MUST check EncryptedExtensions for the 2193 presence of any forbidden extensions and if any are found MUST abort 2194 the handshake with an "illegal_parameter" alert. 2196 Structure of this message: 2198 struct { 2199 Extension extensions<0..2^16-1>; 2200 } EncryptedExtensions; 2202 extensions A list of extensions. 2204 4.3.2. Certificate Request 2206 When this message will be sent: 2208 A server which is authenticating with a certificate can optionally 2209 request a certificate from the client. This message, if sent, 2210 will follow EncryptedExtensions. 2212 Structure of this message: 2214 opaque DistinguishedName<1..2^16-1>; 2216 struct { 2217 opaque certificate_extension_oid<1..2^8-1>; 2218 opaque certificate_extension_values<0..2^16-1>; 2219 } CertificateExtension; 2221 struct { 2222 opaque certificate_request_context<0..2^8-1>; 2223 SignatureScheme 2224 supported_signature_algorithms<2..2^16-2>; 2225 DistinguishedName certificate_authorities<0..2^16-1>; 2226 CertificateExtension certificate_extensions<0..2^16-1>; 2227 } CertificateRequest; 2229 certificate_request_context An opaque string which identifies the 2230 certificate request and which will be echoed in the client's 2231 Certificate message. The certificate_request_context MUST be 2232 unique within the scope of this connection (thus preventing replay 2233 of client CertificateVerify messages). Within the handshake, this 2234 field MUST be empty. 2236 supported_signature_algorithms A list of the signature algorithms 2237 that the server is able to verify, listed in descending order of 2238 preference. Any certificates provided by the client MUST be 2239 signed using a signature algorithm found in 2240 supported_signature_algorithms. 2242 certificate_authorities A list of the distinguished names [X501] of 2243 acceptable certificate_authorities, represented in DER-encoded 2244 [X690] format. These distinguished names may specify a desired 2245 distinguished name for a root CA or for a subordinate CA; thus, 2246 this message can be used to describe known roots as well as a 2247 desired authorization space. If the certificate_authorities list 2248 is empty, then the client MAY send any certificate that meets the 2249 rest of the selection criteria in the CertificateRequest, unless 2250 there is some external arrangement to the contrary. 2252 certificate_extensions A list of certificate extension OIDs 2253 [RFC5280] with their allowed values, represented in DER-encoded 2254 [X690] format. Some certificate extension OIDs allow multiple 2255 values (e.g. Extended Key Usage). If the server has included a 2256 non-empty certificate_extensions list, the client certificate MUST 2257 contain all of the specified extension OIDs that the client 2258 recognizes. For each extension OID recognized by the client, all 2259 of the specified values MUST be present in the client certificate 2260 (but the certificate MAY have other values as well). However, the 2261 client MUST ignore and skip any unrecognized certificate extension 2262 OIDs. If the client has ignored some of the required certificate 2263 extension OIDs, and supplied a certificate that does not satisfy 2264 the request, the server MAY at its discretion either continue the 2265 session without client authentication, or abort the handshake with 2266 an "unsupported_certificate" alert. PKIX RFCs define a variety of 2267 certificate extension OIDs and their corresponding value types. 2268 Depending on the type, matching certificate extension values are 2269 not necessarily bitwise-equal. It is expected that TLS 2270 implementations will rely on their PKI libraries to perform 2271 certificate selection using certificate extension OIDs. This 2272 document defines matching rules for two standard certificate 2273 extensions defined in [RFC5280]: 2275 o The Key Usage extension in a certificate matches the request 2276 when all key usage bits asserted in the request are also 2277 asserted in the Key Usage certificate extension. 2279 o The Extended Key Usage extension in a certificate matches the 2280 request when all key purpose OIDs present in the request are 2281 also found in the Extended Key Usage certificate extension. 2282 The special anyExtendedKeyUsage OID MUST NOT be used in the 2283 request. 2285 Separate specifications may define matching rules for other 2286 certificate extensions. 2288 Servers which are authenticating with a PSK MUST not send the 2289 CertificateRequest message. 2291 4.4. Authentication Messages 2293 As discussed in Section 2, TLS uses a common set of messages for 2294 authentication, key confirmation, and handshake integrity: 2295 Certificate, CertificateVerify, and Finished. These messages are 2296 always sent as the last messages in their handshake flight. The 2297 Certificate and CertificateVerify messages are only sent under 2298 certain circumstances, as defined below. The Finished message is 2299 always sent as part of the Authentication block. 2301 The computations for the Authentication messages all uniformly take 2302 the following inputs: 2304 - The certificate and signing key to be used. 2306 - A Handshake Context based on the hash of the handshake messages 2308 - A base key to be used to compute a MAC key. 2310 Based on these inputs, the messages then contain: 2312 Certificate The certificate to be used for authentication and any 2313 supporting certificates in the chain. Note that certificate-based 2314 client authentication is not available in the 0-RTT case. 2316 CertificateVerify A signature over the value Hash(Handshake Context 2317 + Certificate) + Hash(resumption_context) See Section 4.5.1 for 2318 the definition of resumption_context. 2320 Finished A MAC over the value Hash(Handshake Context + Certificate + 2321 CertificateVerify) + Hash(resumption_context) using a MAC key 2322 derived from the base key. 2324 Because the CertificateVerify signs the Handshake Context + 2325 Certificate and the Finished MACs the Handshake Context + Certificate 2326 + CertificateVerify, this is mostly equivalent to keeping a running 2327 hash of the handshake messages (exactly so in the pure 1-RTT cases). 2328 Note, however, that subsequent post-handshake authentications do not 2329 include each other, just the messages through the end of the main 2330 handshake. 2332 The following table defines the Handshake Context and MAC Base Key 2333 for each scenario: 2335 +-----------+-----------------------------+-------------------------+ 2336 | Mode | Handshake Context | Base Key | 2337 +-----------+-----------------------------+-------------------------+ 2338 | 0-RTT | ClientHello | client_early_traffic_se | 2339 | | | cret | 2340 | | | | 2341 | 1-RTT | ClientHello ... later of En | [sender]_handshake_traf | 2342 | (Server) | cryptedExtensions/Certifica | fic_secret | 2343 | | teRequest | | 2344 | | | | 2345 | 1-RTT | ClientHello ... | [sender]_handshake_traf | 2346 | (Client) | ServerFinished | fic_secret | 2347 | | | | 2348 | Post- | ClientHello ... | [sender]_traffic_secret | 2349 | Handshake | ClientFinished + | _N | 2350 | | CertificateRequest | | 2351 +-----------+-----------------------------+-------------------------+ 2353 The [sender] in this table denotes the sending side. 2355 Note: The Handshake Context for the last three rows does not include 2356 any 0-RTT handshake messages, regardless of whether 0-RTT is used. 2358 4.4.1. Certificate 2360 When this message will be sent: 2362 The server MUST send a Certificate message whenever the agreed- 2363 upon key exchange method uses certificates for authentication 2364 (this includes all key exchange methods defined in this document 2365 except PSK). 2367 The client MUST send a Certificate message if and only if server 2368 has requested client authentication via a CertificateRequest 2369 message (Section 4.3.2). If the server requests client 2370 authentication but no suitable certificate is available, the 2371 client MUST send a Certificate message containing no certificates 2372 (i.e., with the "certificate_list" field having length 0). 2374 Meaning of this message: 2376 This message conveys the endpoint's certificate chain to the peer. 2378 Structure of this message: 2380 opaque ASN1Cert<1..2^24-1>; 2382 struct { 2383 opaque certificate_request_context<0..2^8-1>; 2384 ASN1Cert certificate_list<0..2^24-1>; 2385 } Certificate; 2387 certificate_request_context If this message is in response to a 2388 CertificateRequest, the value of certificate_request_context in 2389 that message. Otherwise, in the case of server authentication 2390 this field SHALL be zero length. 2392 certificate_list This is a sequence (chain) of certificates. The 2393 sender's certificate MUST come first in the list. Each following 2394 certificate SHOULD directly certify one preceding it. Because 2395 certificate validation requires that trust anchors be distributed 2396 independently, a certificate that specifies a trust anchor MAY be 2397 omitted from the chain, provided that supported peers are known to 2398 possess any omitted certificates. 2400 Note: Prior to TLS 1.3, "certificate_list" ordering required each 2401 certificate to certify the one immediately preceding it, however some 2402 implementations allowed some flexibility. Servers sometimes send 2403 both a current and deprecated intermediate for transitional purposes, 2404 and others are simply configured incorrectly, but these cases can 2405 nonetheless be validated properly. For maximum compatibility, all 2406 implementations SHOULD be prepared to handle potentially extraneous 2407 certificates and arbitrary orderings from any TLS version, with the 2408 exception of the end-entity certificate which MUST be first. 2410 The server's certificate list MUST always be non-empty. A client 2411 will send an empty certificate list if it does not have an 2412 appropriate certificate to send in response to the server's 2413 authentication request. 2415 4.4.1.1. Server Certificate Selection 2417 The following rules apply to the certificates sent by the server: 2419 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2420 negotiated otherwise (e.g., [RFC5081]). 2422 - The server's end-entity certificate's public key (and associated 2423 restrictions) MUST be compatible with the selected authentication 2424 algorithm (currently RSA or ECDSA). 2426 - The certificate MUST allow the key to be used for signing (i.e., 2427 the digitalSignature bit MUST be set if the Key Usage extension is 2428 present) with a signature scheme indicated in the client's 2429 "signature_algorithms" extension. 2431 - The "server_name" and "trusted_ca_keys" extensions [RFC6066] are 2432 used to guide certificate selection. As servers MAY require the 2433 presence of the "server_name" extension, clients SHOULD send this 2434 extension, when applicable. 2436 All certificates provided by the server MUST be signed by a signature 2437 algorithm that appears in the "signature_algorithms" extension 2438 provided by the client, if they are able to provide such a chain (see 2439 Section 4.2.3). Certificates that are self-signed or certificates 2440 that are expected to be trust anchors are not validated as part of 2441 the chain and therefore MAY be signed with any algorithm. 2443 If the server cannot produce a certificate chain that is signed only 2444 via the indicated supported algorithms, then it SHOULD continue the 2445 handshake by sending the client a certificate chain of its choice 2446 that may include algorithms that are not known to be supported by the 2447 client. This fallback chain MAY use the deprecated SHA-1 hash 2448 algorithm only if the "signature_algorithms" extension provided by 2449 the client permits it. If the client cannot construct an acceptable 2450 chain using the provided certificates and decides to abort the 2451 handshake, then it MUST abort the handshake with an 2452 "unsupported_certificate" alert. 2454 If the server has multiple certificates, it chooses one of them based 2455 on the above-mentioned criteria (in addition to other criteria, such 2456 as transport layer endpoint, local configuration and preferences). 2458 4.4.1.2. Client Certificate Selection 2460 The following rules apply to certificates sent by the client: 2462 In particular: 2464 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2465 negotiated otherwise (e.g., [RFC5081]). 2467 - If the certificate_authorities list in the certificate request 2468 message was non-empty, one of the certificates in the certificate 2469 chain SHOULD be issued by one of the listed CAs. 2471 - The certificates MUST be signed using an acceptable signature 2472 algorithm, as described in Section 4.3.2. Note that this relaxes 2473 the constraints on certificate-signing algorithms found in prior 2474 versions of TLS. 2476 - If the certificate_extensions list in the certificate request 2477 message was non-empty, the end-entity certificate MUST match the 2478 extension OIDs recognized by the client, as described in 2479 Section 4.3.2. 2481 Note that, as with the server certificate, there are certificates 2482 that use algorithm combinations that cannot be currently used with 2483 TLS. 2485 4.4.1.3. Receiving a Certificate Message 2487 In general, detailed certificate validation procedures are out of 2488 scope for TLS (see [RFC5280]). This section provides TLS-specific 2489 requirements. 2491 If the server supplies an empty Certificate message, the client MUST 2492 abort the handshake with a "decode_error" alert. 2494 If the client does not send any certificates, the server MAY at its 2495 discretion either continue the handshake without client 2496 authentication, or abort the handshake with a "certificate_required" 2497 alert. Also, if some aspect of the certificate chain was 2498 unacceptable (e.g., it was not signed by a known, trusted CA), the 2499 server MAY at its discretion either continue the handshake 2500 (considering the client unauthenticated) or abort the handshake. 2502 Any endpoint receiving any certificate signed using any signature 2503 algorithm using an MD5 hash MUST abort the handshake with a 2504 "bad_certificate" alert. SHA-1 is deprecated and it is RECOMMENDED 2505 that any endpoint receiving any certificate signed using any 2506 signature algorithm using a SHA-1 hash abort the handshake with a 2507 "bad_certificate" alert. All endpoints are RECOMMENDED to transition 2508 to SHA-256 or better as soon as possible to maintain interoperability 2509 with implementations currently in the process of phasing out SHA-1 2510 support. 2512 Note that a certificate containing a key for one signature algorithm 2513 MAY be signed using a different signature algorithm (for instance, an 2514 RSA key signed with an ECDSA key). 2516 4.4.2. Certificate Verify 2518 When this message will be sent: 2520 This message is used to provide explicit proof that an endpoint 2521 possesses the private key corresponding to its certificate and 2522 also provides integrity for the handshake up to this point. 2523 Servers MUST send this message when authenticating via a 2524 certificate. Clients MUST send this message whenever 2525 authenticating via a Certificate (i.e., when the Certificate 2526 message is non-empty). When sent, this message MUST appear 2527 immediately after the Certificate Message and immediately prior to 2528 the Finished message. 2530 Structure of this message: 2532 struct { 2533 SignatureScheme algorithm; 2534 opaque signature<0..2^16-1>; 2535 } CertificateVerify; 2537 The algorithm field specifies the signature algorithm used (see 2538 Section 4.2.3 for the definition of this field). The signature is a 2539 digital signature using that algorithm that covers the hash output 2540 described in Section 4.4 namely: 2542 Hash(Handshake Context + Certificate) + Hash(resumption_context) 2544 In TLS 1.3, the digital signature process takes as input: 2546 - A signing key 2548 - A context string 2550 - The actual content to be signed 2552 The digital signature is then computed using the signing key over the 2553 concatenation of: 2555 - 64 bytes of octet 32 2557 - The context string 2559 - A single 0 byte which servers as the separator 2561 - The content to be signed 2563 This structure is intended to prevent an attack on previous versions 2564 of previous versions of TLS in which the ServerKeyExchange format 2565 meant that attackers could obtain a signature of a message with a 2566 chosen, 32-byte prefix. The initial 64 byte pad clears that prefix. 2568 The context string for a server signature is "TLS 1.3, server 2569 CertificateVerify" and for a client signature is "TLS 1.3, client 2570 CertificateVerify". 2572 For example, if Hash(Handshake Context + Certificate) was 32 bytes of 2573 01 and Hash(resumption_context) was 32 bytes of 02 (these lengths 2574 would make sense for SHA-256, the input to the final signing process 2575 for a server CertificateVerify would be: 2577 2020202020202020202020202020202020202020202020202020202020202020 2578 2020202020202020202020202020202020202020202020202020202020202020 2579 544c5320312e332c207365727665722043657274696669636174655665726966 2580 79 2581 00 2582 0101010101010101010101010101010101010101010101010101010101010101 2583 0202020202020202020202020202020202020202020202020202020202020202 2585 If sent by a server, the signature algorithm MUST be one offered in 2586 the client's "signature_algorithms" extension unless no valid 2587 certificate chain can be produced without unsupported algorithms (see 2588 Section 4.2.3). 2590 If sent by a client, the signature algorithm used in the signature 2591 MUST be one of those present in the supported_signature_algorithms 2592 field of the CertificateRequest message. 2594 In addition, the signature algorithm MUST be compatible with the key 2595 in the sender's end-entity certificate. RSA signatures MUST use an 2596 RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS1-v1_5 2597 algorithms appear in "signature_algorithms". SHA-1 MUST NOT be used 2598 in any signatures in CertificateVerify. All SHA-1 signature 2599 algorithms in this specification are defined solely for use in legacy 2600 certificates, and are not valid for CertificateVerify signatures. 2602 Note: When used with non-certificate-based handshakes (e.g., PSK), 2603 the client's signature does not cover the server's certificate 2604 directly, although it does cover the server's Finished message, which 2605 transitively includes the server's certificate when the PSK derives 2606 from a certificate-authenticated handshake. [PSK-FINISHED] describes 2607 a concrete attack on this mode if the Finished is omitted from the 2608 signature. It is unsafe to use certificate-based client 2609 authentication when the client might potentially share the same PSK/ 2610 key-id pair with two different endpoints. In order to ensure this, 2611 implementations MUST NOT mix certificate-based client authentication 2612 with PSK. 2614 4.4.3. Finished 2616 When this message will be sent: 2618 The Finished message is the final message in the authentication 2619 block. It is essential for providing authentication of the 2620 handshake and of the computed keys. 2622 Meaning of this message: 2624 Recipients of Finished messages MUST verify that the contents are 2625 correct. Once a side has sent its Finished message and received 2626 and validated the Finished message from its peer, it may begin to 2627 send and receive application data over the connection. 2629 The key used to compute the finished message is computed from the 2630 Base key defined in Section 4.4 using HKDF (see Section 7.1). 2631 Specifically: 2633 finished_key = 2634 HKDF-Expand-Label(BaseKey, "finished", "", Hash.length) 2636 Structure of this message: 2638 struct { 2639 opaque verify_data[Hash.length]; 2640 } Finished; 2642 The verify_data value is computed as follows: 2644 verify_data = 2645 HMAC(finished_key, Hash( 2646 Handshake Context + 2647 Certificate* + 2648 CertificateVerify* 2649 ) + 2650 Hash(resumption_context) 2651 ) 2653 * Only included if present. 2655 Where HMAC [RFC2104] uses the Hash algorithm for the handshake. As 2656 noted above, the HMAC input can generally be implemented by a running 2657 hash, i.e., just the handshake hash at this point. 2659 In previous versions of TLS, the verify_data was always 12 octets 2660 long. In the current version of TLS, it is the size of the HMAC 2661 output for the Hash used for the handshake. 2663 Note: Alerts and any other record types are not handshake messages 2664 and are not included in the hash computations. 2666 Any records following a 1-RTT Finished message MUST be encrypted 2667 under the application traffic key. In particular, this includes any 2668 alerts sent by the server in response to client Certificate and 2669 CertificateVerify messages. 2671 4.5. Post-Handshake Messages 2673 TLS also allows other messages to be sent after the main handshake. 2674 These messages use a handshake content type and are encrypted under 2675 the application traffic key. 2677 Handshake messages sent after the handshake MUST NOT be interleaved 2678 with other record types. That is, if a message is split over two or 2679 more handshake records, there MUST NOT be any other records between 2680 them. 2682 4.5.1. New Session Ticket Message 2684 At any time after the server has received the client Finished 2685 message, it MAY send a NewSessionTicket message. This message 2686 creates a pre-shared key (PSK) binding between the ticket value and 2687 the following two values derived from the resumption master secret: 2689 resumption_psk = HKDF-Expand-Label( 2690 resumption_secret, 2691 "resumption psk", "", Hash.length) 2693 resumption_context = HKDF-Expand-Label( 2694 resumption_secret, 2695 "resumption context", "", Hash.length) 2697 The client MAY use this PSK for future handshakes by including the 2698 ticket value in the "pre_shared_key" extension in its ClientHello 2699 (Section 4.2.6). Servers MAY send multiple tickets on a single 2700 connection, either immediately after each other or after specific 2701 events. For instance, the server might send a new ticket after post- 2702 handshake authentication in order to encapsulate the additional 2703 client authentication state. Clients SHOULD attempt to use each 2704 ticket no more than once, with more recent tickets being used first. 2705 For handshakes that do not use a resumption_psk, the 2706 resumption_context is a string of Hash.length zeroes. [[Note: this 2707 will not be safe if/when we add additional server signatures with 2708 PSK: OPEN ISSUE https://github.com/tlswg/tls13-spec/issues/558]] 2710 Any ticket MUST only be resumed with a cipher suite that is identical 2711 to that negotiated connection where the ticket was established. 2713 enum { ticket_early_data_info(1), (65535) } TicketExtensionType; 2715 struct { 2716 TicketExtensionType extension_type; 2717 opaque extension_data<1..2^16-1>; 2718 } TicketExtension; 2720 struct { 2721 uint32 ticket_lifetime; 2722 PskKeyExchangeMode ke_modes<1..255>; 2723 PskAuthenticationMode auth_modes<1..255>; 2724 opaque ticket<1..2^16-1>; 2725 TicketExtension extensions<0..2^16-2>; 2726 } NewSessionTicket; 2728 ke_modes The key exchange modes with which this ticket can be used 2729 in descending order of server preference. 2731 auth_modes The authentication modes with which this ticket can be 2732 used in descending order of server preference. 2734 ticket_lifetime Indicates the lifetime in seconds as a 32-bit 2735 unsigned integer in network byte order from the time of ticket 2736 issuance. Servers MUST NOT use any value more than 604800 seconds 2737 (7 days). The value of zero indicates that the ticket should be 2738 discarded immediately. Clients MUST NOT cache session tickets for 2739 longer than 7 days, regardless of the ticket_lifetime. It MAY 2740 delete the ticket earlier based on local policy. A server MAY 2741 treat a ticket as valid for a shorter period of time than what is 2742 stated in the ticket_lifetime. 2744 ticket The value of the ticket to be used as the PSK identifier. 2745 The ticket itself is an opaque label. It MAY either be a database 2746 lookup key or a self-encrypted and self-authenticated value. 2747 Section 4 of [RFC5077] describes a recommended ticket construction 2748 mechanism. 2750 ticket_extensions A set of extension values for the ticket. Clients 2751 MUST ignore unrecognized extensions. 2753 This document defines one ticket extension, "ticket_early_data_info" 2755 struct { 2756 uint32 ticket_age_add; 2757 } TicketEarlyDataInfo; 2759 This extension indicates that the ticket may be used to send 0-RTT 2760 data (Section 4.2.7)). It contains one value: 2762 ticket_age_add A randomly generated 32-bit value that is used to 2763 obscure the age of the ticket that the client includes in the 2764 "early_data" extension. The client-side ticket age is added to 2765 this value modulo 2^32 to obtain the value that is transmitted by 2766 the client. 2768 4.5.2. Post-Handshake Authentication 2770 The server is permitted to request client authentication at any time 2771 after the handshake has completed by sending a CertificateRequest 2772 message. The client SHOULD respond with the appropriate 2773 Authentication messages. If the client chooses to authenticate, it 2774 MUST send Certificate, CertificateVerify, and Finished. If it 2775 declines, it MUST send a Certificate message containing no 2776 certificates followed by Finished. 2778 Note: Because client authentication may require prompting the user, 2779 servers MUST be prepared for some delay, including receiving an 2780 arbitrary number of other messages between sending the 2781 CertificateRequest and receiving a response. In addition, clients 2782 which receive multiple CertificateRequests in close succession MAY 2783 respond to them in a different order than they were received (the 2784 certificate_request_context value allows the server to disambiguate 2785 the responses). 2787 4.5.3. Key and IV Update 2789 enum { update_not_requested(0), update_requested(1), (255) 2790 } KeyUpdateRequest; 2792 struct { 2793 KeyUpdateRequest request_update; 2794 } KeyUpdate; 2796 request_update Indicates that the recipient of the KeyUpdate should 2797 respond with its own KeyUpdate. If an implementation receives any 2798 other value, it MUST terminate the connection with an 2799 "illegal_parameter" alert. 2801 The KeyUpdate handshake message is used to indicate that the sender 2802 is updating its sending cryptographic keys. This message can be sent 2803 by the server after sending its first flight and the client after 2804 sending its second flight. Implementations that receive a KeyUpdate 2805 message prior to receiving a Finished message as part of the 1-RTT 2806 handshake MUST terminate the connection with an "unexpected_message" 2807 alert. After sending a KeyUpdate message, the sender SHALL send all 2808 its traffic using the next generation of keys, computed as described 2809 in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update 2810 its receiving keys. 2812 If the request_udate field is set to "update_requested" then the 2813 receiver MUST send a KeyUpdate of its own with request_update set to 2814 "update_not_requested" prior to sending its next application data 2815 record. This mechanism allows either side to force an update to the 2816 entire connection, but causes an implementation which receives 2817 multiple KeyUpdates while it is silent to respond with a single 2818 update. Note that implementations may receive an arbitrary number of 2819 messages between sending a KeyUpdate and receiving the peer's 2820 KeyUpdate because those messages may already be in flight. However, 2821 because send and receive keys are derived from independent traffic 2822 secrets, retaining the receive traffic secret does not threaten the 2823 forward secrecy of data sent before the sender changed keys. 2825 If implementations independently send their own KeyUpdates with 2826 request_update set to "update_requested", and they cross in flight, 2827 then each side will also send a response, with the result that each 2828 side increments by two generations. 2830 Both sender and receiver MUST encrypt their KeyUpdate messages with 2831 the old keys. Additionally, both sides MUST enforce that a KeyUpdate 2832 with the old key is received before accepting any messages encrypted 2833 with the new key. Failure to do so may allow message truncation 2834 attacks. 2836 4.6. Handshake Layer and Key Changes 2838 Handshake messages MUST NOT span key changes. Because the 2839 ServerHello, Finished, and KeyUpdate messages signal a key change, 2840 upon receiving these messages a receiver MUST verify that the end of 2841 these messages aligns with a record boundary; if not, then it MUST 2842 terminate the connection with an "unexpected_message" alert. 2844 5. Record Protocol 2846 The TLS record protocol takes messages to be transmitted, fragments 2847 the data into manageable blocks, protects the records, and transmits 2848 the result. Received data is decrypted and verified, reassembled, 2849 and then delivered to higher-level clients. 2851 TLS records are typed, which allows multiple higher level protocols 2852 to be multiplexed over the same record layer. This document 2853 specifies three content types: handshake, application data, and 2854 alert. Implementations MUST NOT send record types not defined in 2855 this document unless negotiated by some extension. If a TLS 2856 implementation receives an unexpected record type, it MUST terminate 2857 the connection with an "unexpected_message" alert. New record 2858 content type values are assigned by IANA in the TLS Content Type 2859 Registry as described in Section 10. 2861 Application data messages are carried by the record layer and are 2862 fragmented and encrypted as described below. The messages are 2863 treated as transparent data to the record layer. 2865 5.1. Record Layer 2867 The TLS record layer receives uninterpreted data from higher layers 2868 in non-empty blocks of arbitrary size. 2870 The record layer fragments information blocks into TLSPlaintext 2871 records carrying data in chunks of 2^14 bytes or less. Message 2872 boundaries are not preserved in the record layer (i.e., multiple 2873 messages of the same ContentType MAY be coalesced into a single 2874 TLSPlaintext record, or a single message MAY be fragmented across 2875 several records). Alert messages (Section 6) MUST NOT be fragmented 2876 across records. 2878 enum { 2879 alert(21), 2880 handshake(22), 2881 application_data(23), 2882 (255) 2883 } ContentType; 2885 struct { 2886 ContentType type; 2887 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 2888 uint16 length; 2889 opaque fragment[TLSPlaintext.length]; 2890 } TLSPlaintext; 2892 type The higher-level protocol used to process the enclosed 2893 fragment. 2895 legacy_record_version This value MUST be set to { 3, 1 } for all 2896 records. This field is deprecated and MUST be ignored for all 2897 purposes. 2899 length The length (in bytes) of the following TLSPlaintext.fragment. 2900 The length MUST NOT exceed 2^14. 2902 fragment The data being transmitted. This value transparent and 2903 treated as an independent block to be dealt with by the higher- 2904 level protocol specified by the type field. 2906 This document describes TLS Version 1.3, which uses the version { 3, 2907 4 }. The version value 3.4 is historical, deriving from the use of { 2908 3, 1 } for TLS 1.0 and { 3, 0 } for SSL 3.0. In order to maximize 2909 backwards compatibility, the record layer version identifies as 2910 simply TLS 1.0. Endpoints supporting other versions negotiate the 2911 version to use by following the procedure and requirements in 2912 Appendix C. 2914 Implementations MUST NOT send zero-length fragments of Handshake or 2915 Alert types, even if those fragments contain padding. Zero-length 2916 fragments of Application data MAY be sent as they are potentially 2917 useful as a traffic analysis countermeasure. 2919 When record protection has not yet been engaged, TLSPlaintext 2920 structures are written directly onto the wire. Once record 2921 protection has started, TLSPlaintext records are protected and sent 2922 as described in the following section. 2924 5.2. Record Payload Protection 2926 The record protection functions translate a TLSPlaintext structure 2927 into a TLSCiphertext. The deprotection functions reverse the 2928 process. In TLS 1.3 as opposed to previous versions of TLS, all 2929 ciphers are modeled as "Authenticated Encryption with Additional 2930 Data" (AEAD) [RFC5116]. AEAD functions provide a unified encryption 2931 and authentication operation which turns plaintext into authenticated 2932 ciphertext and back again. Each encrypted record consists of a 2933 plaintext header followed by an encrypted body, which itself contains 2934 a type and optional padding. 2936 struct { 2937 opaque content[TLSPlaintext.length]; 2938 ContentType type; 2939 uint8 zeros[length_of_padding]; 2940 } TLSInnerPlaintext; 2942 struct { 2943 ContentType opaque_type = application_data(23); /* see TLSInnerPlaintext.type */ 2944 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 2945 uint16 length; 2946 opaque encrypted_record[length]; 2947 } TLSCiphertext; 2949 content The cleartext of TLSPlaintext.fragment. 2951 type The content type of the record. 2953 zeros An arbitrary-length run of zero-valued bytes may appear in the 2954 cleartext after the type field. This provides an opportunity for 2955 senders to pad any TLS record by a chosen amount as long as the 2956 total stays within record size limits. See Section 5.4 for more 2957 details. 2959 opaque_type The outer opaque_type field of a TLSCiphertext record is 2960 always set to the value 23 (application_data) for outward 2961 compatibility with middleboxes accustomed to parsing previous 2962 versions of TLS. The actual content type of the record is found 2963 in TLSInnerPlaintext.type after decryption. 2965 legacy_record_version The legacy_record_version field is identical 2966 to TLSPlaintext.legacy_record_version and is always { 3, 1 }. 2967 Note that the handshake protocol including the ClientHello and 2968 ServerHello messages authenticates the protocol version, so this 2969 value is redundant. 2971 length The length (in bytes) of the following 2972 TLSCiphertext.fragment, which is the sum of the lengths of the 2973 content and the padding, plus one for the inner content type. The 2974 length MUST NOT exceed 2^14 + 256. An endpoint that receives a 2975 record that exceeds this length MUST terminate the connection with 2976 a "record_overflow" alert. 2978 encrypted_record The AEAD encrypted form of the serialized 2979 TLSInnerPlaintext structure. 2981 AEAD algorithms take as input a single key, a nonce, a plaintext, and 2982 "additional data" to be included in the authentication check, as 2983 described in Section 2.1 of [RFC5116]. The key is either the 2984 client_write_key or the server_write_key, the nonce is derived from 2985 the sequence number (see Section 5.3) and the client_write_iv or 2986 server_write_iv, and the additional data input is empty (zero 2987 length). Derivation of traffic keys is defined in Section 7.3. 2989 The plaintext is the concatenation of TLSPlaintext.fragment, 2990 TLSPlaintext.type, and any padding bytes (zeros). 2992 The AEAD output consists of the ciphertext output by the AEAD 2993 encryption operation. The length of the plaintext is greater than 2994 TLSPlaintext.length due to the inclusion of TLSPlaintext.type and 2995 however much padding is supplied by the sender. The length of the 2996 AEAD output will generally be larger than the plaintext, but by an 2997 amount that varies with the AEAD algorithm. Since the ciphers might 2998 incorporate padding, the amount of overhead could vary with different 2999 lengths of plaintext. Symbolically, 3000 AEADEncrypted = 3001 AEAD-Encrypt(write_key, nonce, plaintext of fragment) 3003 In order to decrypt and verify, the cipher takes as input the key, 3004 nonce, and the AEADEncrypted value. The output is either the 3005 plaintext or an error indicating that the decryption failed. There 3006 is no separate integrity check. That is: 3008 plaintext of fragment = 3009 AEAD-Decrypt(write_key, nonce, AEADEncrypted) 3011 If the decryption fails, the receiver MUST terminate the connection 3012 with a "bad_record_mac" alert. 3014 An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion of 3015 greater than 255 bytes. An endpoint that receives a record from its 3016 peer with TLSCipherText.length larger than 2^14 + 256 octets MUST 3017 terminate the connection with a "record_overflow" alert. This limit 3018 is derived from the maximum TLSPlaintext length of 2^14 octets + 1 3019 octet for ContentType + the maximum AEAD expansion of 255 octets. 3021 5.3. Per-Record Nonce 3023 A 64-bit sequence number is maintained separately for reading and 3024 writing records. Each sequence number is set to zero at the 3025 beginning of a connection and whenever the key is changed. 3027 The sequence number is incremented after reading or writing each 3028 record. The first record transmitted under a particular set of 3029 traffic keys record key MUST use sequence number 0. 3031 Sequence numbers do not wrap. If a TLS implementation would need to 3032 wrap a sequence number, it MUST either rekey (Section 4.5.3) or 3033 terminate the connection. 3035 The length of the per-record nonce (iv_length) is set to max(8 bytes, 3036 N_MIN) for the AEAD algorithm (see [RFC5116] Section 4). An AEAD 3037 algorithm where N_MAX is less than 8 bytes MUST NOT be used with TLS. 3038 The per-record nonce for the AEAD construction is formed as follows: 3040 1. The 64-bit record sequence number is padded to the left with 3041 zeroes to iv_length. 3043 2. The padded sequence number is XORed with the static 3044 client_write_iv or server_write_iv, depending on the role. 3046 The resulting quantity (of length iv_length) is used as the per- 3047 record nonce. 3049 Note: This is a different construction from that in TLS 1.2, which 3050 specified a partially explicit nonce. 3052 5.4. Record Padding 3054 All encrypted TLS records can be padded to inflate the size of the 3055 TLSCipherText. This allows the sender to hide the size of the 3056 traffic from an observer. 3058 When generating a TLSCiphertext record, implementations MAY choose to 3059 pad. An unpadded record is just a record with a padding length of 3060 zero. Padding is a string of zero-valued bytes appended to the 3061 ContentType field before encryption. Implementations MUST set the 3062 padding octets to all zeros before encrypting. 3064 Application Data records may contain a zero-length 3065 TLSInnerPlaintext.content if the sender desires. This permits 3066 generation of plausibly-sized cover traffic in contexts where the 3067 presence or absence of activity may be sensitive. Implementations 3068 MUST NOT send Handshake or Alert records that have a zero-length 3069 TLSInnerPlaintext.content. 3071 The padding sent is automatically verified by the record protection 3072 mechanism: Upon successful decryption of a TLSCiphertext.fragment, 3073 the receiving implementation scans the field from the end toward the 3074 beginning until it finds a non-zero octet. This non-zero octet is 3075 the content type of the message. This padding scheme was selected 3076 because it allows padding of any encrypted TLS record by an arbitrary 3077 size (from zero up to TLS record size limits) without introducing new 3078 content types. The design also enforces all-zero padding octets, 3079 which allows for quick detection of padding errors. 3081 Implementations MUST limit their scanning to the cleartext returned 3082 from the AEAD decryption. If a receiving implementation does not 3083 find a non-zero octet in the cleartext, it MUST terminate the 3084 connection with an "unexpected_message" alert. 3086 The presence of padding does not change the overall record size 3087 limitations - the full fragment plaintext may not exceed 2^14 octets. 3089 Selecting a padding policy that suggests when and how much to pad is 3090 a complex topic, and is beyond the scope of this specification. If 3091 the application layer protocol atop TLS has its own padding, it may 3092 be preferable to pad application_data TLS records within the 3093 application layer. Padding for encrypted handshake and alert TLS 3094 records must still be handled at the TLS layer, though. Later 3095 documents may define padding selection algorithms, or define a 3096 padding policy request mechanism through TLS extensions or some other 3097 means. 3099 5.5. Limits on Key Usage 3101 There are cryptographic limits on the amount of plaintext which can 3102 be safely encrypted under a given set of keys. [AEAD-LIMITS] 3103 provides an analysis of these limits under the assumption that the 3104 underlying primitive (AES or ChaCha20) has no weaknesses. 3105 Implementations SHOULD do a key update Section 4.5.3 prior to 3106 reaching these limits. 3108 For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be 3109 encrypted on a given connection while keeping a safety margin of 3110 approximately 2^-57 for Authenticated Encryption (AE) security. For 3111 ChaCha20/Poly1305, the record sequence number would wrap before the 3112 safety limit is reached. 3114 6. Alert Protocol 3116 One of the content types supported by the TLS record layer is the 3117 alert type. Like other messages, alert messages are encrypted as 3118 specified by the current connection state. 3120 Alert messages convey the severity of the message (warning or fatal) 3121 and a description of the alert. Warning-level messages are used to 3122 indicate orderly closure of the connection (see Section 6.1). Upon 3123 receiving a warning-level alert, the TLS implementation SHOULD 3124 indicate end-of-data to the application and, if appropriate for the 3125 alert type, send a closure alert in response. 3127 Fatal-level messages are used to indicate abortive closure of the 3128 connection (See Section 6.2). Upon receiving a fatal-level alert, 3129 the TLS implementation SHOULD indicate an error to the application 3130 and MUST NOT allow any further data to be sent or received on the 3131 connection. Servers and clients MUST forget keys and secrets 3132 associated with a failed connection. Stateful implementations of 3133 session tickets (as in many clients) SHOULD discard tickets 3134 associated with failed connections. 3136 All the alerts listed in Section 6.2 MUST be sent as fatal and MUST 3137 be treated as fatal regardless of the AlertLevel in the message. 3138 Unknown alert types MUST be treated as fatal. 3140 enum { warning(1), fatal(2), (255) } AlertLevel; 3142 enum { 3143 close_notify(0), 3144 end_of_early_data(1), 3145 unexpected_message(10), 3146 bad_record_mac(20), 3147 record_overflow(22), 3148 handshake_failure(40), 3149 bad_certificate(42), 3150 unsupported_certificate(43), 3151 certificate_revoked(44), 3152 certificate_expired(45), 3153 certificate_unknown(46), 3154 illegal_parameter(47), 3155 unknown_ca(48), 3156 access_denied(49), 3157 decode_error(50), 3158 decrypt_error(51), 3159 protocol_version(70), 3160 insufficient_security(71), 3161 internal_error(80), 3162 inappropriate_fallback(86), 3163 user_canceled(90), 3164 missing_extension(109), 3165 unsupported_extension(110), 3166 certificate_unobtainable(111), 3167 unrecognized_name(112), 3168 bad_certificate_status_response(113), 3169 bad_certificate_hash_value(114), 3170 unknown_psk_identity(115), 3171 certificate_required(116), 3172 (255) 3173 } AlertDescription; 3175 struct { 3176 AlertLevel level; 3177 AlertDescription description; 3178 } Alert; 3180 6.1. Closure Alerts 3182 The client and the server must share knowledge that the connection is 3183 ending in order to avoid a truncation attack. Failure to properly 3184 close a connection does not prohibit a session from being resumed. 3186 close_notify This alert notifies the recipient that the sender will 3187 not send any more messages on this connection. Any data received 3188 after a closure MUST be ignored. 3190 end_of_early_data This alert is sent by the client to indicate that 3191 all 0-RTT application_data messages have been transmitted (or none 3192 will be sent at all) and that this is the end of the flight. This 3193 alert MUST be at the warning level. Servers MUST NOT send this 3194 alert and clients receiving it MUST terminate the connection with 3195 an "unexpected_message" alert. 3197 user_canceled This alert notifies the recipient that the sender is 3198 canceling the handshake for some reason unrelated to a protocol 3199 failure. If a user cancels an operation after the handshake is 3200 complete, just closing the connection by sending a "close_notify" 3201 is more appropriate. This alert SHOULD be followed by a 3202 "close_notify". This alert is generally a warning. 3204 Either party MAY initiate a close by sending a "close_notify" alert. 3205 Any data received after a closure alert is ignored. If a transport- 3206 level close is received prior to a "close_notify", the receiver 3207 cannot know that all the data that was sent has been received. 3209 Each party MUST send a "close_notify" alert before closing the write 3210 side of the connection, unless some other fatal alert has been 3211 transmitted. The other party MUST respond with a "close_notify" 3212 alert of its own and close down the connection immediately, 3213 discarding any pending writes. The initiator of the close need not 3214 wait for the responding "close_notify" alert before closing the read 3215 side of the connection. 3217 If the application protocol using TLS provides that any data may be 3218 carried over the underlying transport after the TLS connection is 3219 closed, the TLS implementation must receive the responding 3220 "close_notify" alert before indicating to the application layer that 3221 the TLS connection has ended. If the application protocol will not 3222 transfer any additional data, but will only close the underlying 3223 transport connection, then the implementation MAY choose to close the 3224 transport without waiting for the responding "close_notify". No part 3225 of this standard should be taken to dictate the manner in which a 3226 usage profile for TLS manages its data transport, including when 3227 connections are opened or closed. 3229 Note: It is assumed that closing a connection reliably delivers 3230 pending data before destroying the transport. 3232 6.2. Error Alerts 3234 Error handling in the TLS Handshake Protocol is very simple. When an 3235 error is detected, the detecting party sends a message to its peer. 3236 Upon transmission or receipt of a fatal alert message, both parties 3237 immediately close the connection. 3239 Whenever an implementation encounters a fatal error condition, it 3240 SHOULD send an appropriate fatal alert and MUST close the connection 3241 without sending or receiving any additional data. In the rest of 3242 this specification, the phrase "{terminate the connection, abort the 3243 handshake}" is used without a specific alert means that the 3244 implementation SHOULD send the alert indicated by the descriptions 3245 below. The phrase "{terminate the connection, abort the handshake} 3246 with a X alert" MUST send alert X if it sends any alert. All alerts 3247 defined in this section below, as well as all unknown alerts are 3248 universally considered fatal as of TLS 1.3 (see Section 6). 3250 The following error alerts are defined: 3252 unexpected_message An inappropriate message (e.g., the wrong 3253 handshake message, premature application data, etc.) was received. 3254 This alert should never be observed in communication between 3255 proper implementations. 3257 bad_record_mac This alert is returned if a record is received which 3258 cannot be deprotected. Because AEAD algorithms combine decryption 3259 and verification, this alert is used for all deprotection 3260 failures. This alert should never be observed in communication 3261 between proper implementations, except when messages were 3262 corrupted in the network. 3264 record_overflow A TLSCiphertext record was received that had a 3265 length more than 2^14 + 256 bytes, or a record decrypted to a 3266 TLSPlaintext record with more than 2^14 bytes. This alert should 3267 never be observed in communication between proper implementations, 3268 except when messages were corrupted in the network. 3270 handshake_failure Reception of a "handshake_failure" alert message 3271 indicates that the sender was unable to negotiate an acceptable 3272 set of security parameters given the options available. 3274 bad_certificate A certificate was corrupt, contained signatures that 3275 did not verify correctly, etc. 3277 unsupported_certificate A certificate was of an unsupported type. 3279 certificate_revoked A certificate was revoked by its signer. 3281 certificate_expired A certificate has expired or is not currently 3282 valid. 3284 certificate_unknown Some other (unspecified) issue arose in 3285 processing the certificate, rendering it unacceptable. 3287 illegal_parameter A field in the handshake was incorrect or 3288 inconsistent with other fields. This alert is used for errors 3289 which conform to the formal protocol syntax but are otherwise 3290 incorrect. 3292 unknown_ca A valid certificate chain or partial chain was received, 3293 but the certificate was not accepted because the CA certificate 3294 could not be located or couldn't be matched with a known, trusted 3295 CA. 3297 access_denied A valid certificate or PSK was received, but when 3298 access control was applied, the sender decided not to proceed with 3299 negotiation. 3301 decode_error A message could not be decoded because some field was 3302 out of the specified range or the length of the message was 3303 incorrect. This alert is used for errors where the message does 3304 not conform to the formal protocol syntax. This alert should 3305 never be observed in communication between proper implementations, 3306 except when messages were corrupted in the network. 3308 decrypt_error A handshake cryptographic operation failed, including 3309 being unable to correctly verify a signature or validate a 3310 Finished message. 3312 protocol_version The protocol version the peer has attempted to 3313 negotiate is recognized but not supported. (see Appendix C) 3315 insufficient_security Returned instead of "handshake_failure" when a 3316 negotiation has failed specifically because the server requires 3317 ciphers more secure than those supported by the client. 3319 internal_error An internal error unrelated to the peer or the 3320 correctness of the protocol (such as a memory allocation failure) 3321 makes it impossible to continue. 3323 inappropriate_fallback Sent by a server in response to an invalid 3324 connection retry attempt from a client. (see [RFC7507]) 3326 missing_extension Sent by endpoints that receive a hello message not 3327 containing an extension that is mandatory to send for the offered 3328 TLS version or other negotiated parameters. [[TODO: IANA 3329 Considerations.]] 3331 unsupported_extension Sent by endpoints receiving any hello message 3332 containing an extension known to be prohibited for inclusion in 3333 the given hello message, including any extensions in a ServerHello 3334 not first offered in the corresponding ClientHello. 3336 certificate_unobtainable Sent by servers when unable to obtain a 3337 certificate from a URL provided by the client via the 3338 "client_certificate_url" extension [RFC6066]. 3340 unrecognized_name Sent by servers when no server exists identified 3341 by the name provided by the client via the "server_name" extension 3342 [RFC6066]. 3344 bad_certificate_status_response Sent by clients when an invalid or 3345 unacceptable OCSP response is provided by the server via the 3346 "status_request" extension [RFC6066]. 3348 bad_certificate_hash_value Sent by servers when a retrieved object 3349 does not have the correct hash provided by the client via the 3350 "client_certificate_url" extension [RFC6066]. 3352 unknown_psk_identity Sent by servers when PSK key establishment is 3353 desired but no acceptable PSK identity is provided by the client. 3354 Sending this alert is OPTIONAL; servers MAY instead choose to send 3355 a "decrypt_error" alert to merely indicate an invalid PSK 3356 identity. 3358 certificate_required Sent by servers when a client certificate is 3359 desired but none was provided by the client. 3361 [[TODO: IANA Considerations for new alert values.]] 3363 New Alert values are assigned by IANA as described in Section 10. 3365 7. Cryptographic Computations 3367 In order to begin connection protection, the TLS Record Protocol 3368 requires specification of a suite of algorithms, a master secret, and 3369 the client and server random values. 3371 7.1. Key Schedule 3373 The TLS handshake establishes one or more input secrets which are 3374 combined to create the actual working keying material, as detailed 3375 below. The key derivation process makes use of the HKDF-Extract and 3376 HKDF-Expand functions as defined for HKDF [RFC5869], as well as the 3377 functions defined below: 3379 HKDF-Expand-Label(Secret, Label, HashValue, Length) = 3380 HKDF-Expand(Secret, HkdfLabel, Length) 3382 Where HkdfLabel is specified as: 3384 struct { 3385 uint16 length = Length; 3386 opaque label<9..255> = "TLS 1.3, " + Label; 3387 opaque hash_value<0..255> = HashValue; 3388 } HkdfLabel; 3390 Derive-Secret(Secret, Label, Messages) = 3391 HKDF-Expand-Label(Secret, Label, 3392 Hash(Messages) + 3393 Hash(resumption_context), Hash.length) 3395 The Hash function and the HKDF hash are the cipher suite hash 3396 algorithm. Hash.length is its output length. 3398 Given a set of n InputSecrets, the final "master secret" is computed 3399 by iteratively invoking HKDF-Extract with InputSecret_1, 3400 InputSecret_2, etc. The initial secret is simply a string of zeroes 3401 as long as the size of the Hash that is the basis for the HKDF. 3402 Concretely, for the present version of TLS 1.3, secrets are added in 3403 the following order: 3405 - PSK 3407 - (EC)DHE shared secret 3409 This produces a full key derivation schedule shown in the diagram 3410 below. In this diagram, the following formatting conventions apply: 3412 - HKDF-Extract is drawn as taking the Salt argument from the top and 3413 the IKM argument from the left. 3415 - Derive-Secret's Secret argument is indicated by the arrow coming 3416 in from the left. For instance, the Early Secret is the Secret 3417 for generating the client_early_traffic_secret. 3419 Note that the 0-RTT Finished message is not included in the Derive- 3420 Secret operation. 3422 0 3423 | 3424 v 3425 PSK -> HKDF-Extract 3426 | 3427 v 3428 Early Secret ---> Derive-Secret(., "client early traffic secret", 3429 | ClientHello) 3430 | = client_early_traffic_secret 3431 v 3432 (EC)DHE -> HKDF-Extract 3433 | 3434 v 3435 Handshake Secret 3436 | 3437 +---------> Derive-Secret(., "client handshake traffic secret", 3438 | ClientHello...ServerHello) 3439 | = client_handshake_traffic_secret 3440 | 3441 +---------> Derive-Secret(., "server handshake traffic secret", 3442 | ClientHello...ServerHello) 3443 | = server_handshake_traffic_secret 3444 | 3445 v 3446 0 -> HKDF-Extract 3447 | 3448 v 3449 Master Secret 3450 | 3451 +---------> Derive-Secret(., "client application traffic secret", 3452 | ClientHello...Server Finished) 3453 | = client_traffic_secret_0 3454 | 3455 +---------> Derive-Secret(., "server application traffic secret", 3456 | ClientHello...Server Finished) 3457 | = server_traffic_secret_0 3458 | 3459 +---------> Derive-Secret(., "exporter master secret", 3460 | ClientHello...Client Finished) 3461 | = exporter_secret 3462 | 3463 +---------> Derive-Secret(., "resumption master secret", 3464 ClientHello...Client Finished) 3465 = resumption_secret 3467 The general pattern here is that the secrets shown down the left side 3468 of the diagram are just raw entropy without context, whereas the 3469 secrets down the right side include handshake context and therefore 3470 can be used to derive working keys without additional context. Note 3471 that the different calls to Derive-Secret may take different Messages 3472 arguments, even with the same secret. In a 0-RTT exchange, Derive- 3473 Secret is called with four distinct transcripts; in a 1-RTT only 3474 exchange with three distinct transcripts. 3476 If a given secret is not available, then the 0-value consisting of a 3477 string of Hash.length zeroes is used. Note that this does not mean 3478 skipping rounds, so if PSK is not in use Early Secret will still be 3479 HKDF-Extract(0, 0). 3481 7.2. Updating Traffic Keys and IVs 3483 Once the handshake is complete, it is possible for either side to 3484 update its sending traffic keys using the KeyUpdate handshake message 3485 defined in Section 4.5.3. The next generation of traffic keys is 3486 computed by generating client_/server_traffic_secret_N+1 from 3487 client_/server_traffic_secret_N as described in this section then re- 3488 deriving the traffic keys as described in Section 7.3. 3490 The next-generation traffic_secret is computed as: 3492 traffic_secret_N+1 = HKDF-Expand-Label( 3493 traffic_secret_N, 3494 "application traffic secret", "", Hash.length) 3496 Once client/server_traffic_secret_N+1 and its associated traffic keys 3497 have been computed, implementations SHOULD delete client_/ 3498 server_traffic_secret_N and its associated traffic keys. 3500 7.3. Traffic Key Calculation 3502 The traffic keying material is generated from the following input 3503 values: 3505 - A secret value 3507 - A phase value indicating the phase of the protocol the keys are 3508 being generated for 3510 - A purpose value indicating the specific value being generated 3512 - The length of the key 3514 The keying material is computed using: 3516 key = HKDF-Expand-Label(Secret, 3517 phase + ", " + purpose, 3518 "", 3519 key_length) 3521 The following table describes the inputs to the key calculation for 3522 each class of traffic keys: 3524 +-------------+-----------------------------------+-----------------+ 3525 | Record Type | Secret | Phase | 3526 +-------------+-----------------------------------+-----------------+ 3527 | 0-RTT | client_early_traffic_secret | "early | 3528 | Handshake | | handshake key | 3529 | | | expansion" | 3530 | | | | 3531 | 0-RTT | client_early_traffic_secret | "early | 3532 | Application | | application | 3533 | | | data key | 3534 | | | expansion" | 3535 | | | | 3536 | Handshake | [sender]_handshake_traffic_secret | "handshake key | 3537 | | | expansion" | 3538 | | | | 3539 | Application | [sender]_traffic_secret_N | "application | 3540 | Data | | data key | 3541 | | | expansion" | 3542 +-------------+-----------------------------------+-----------------+ 3544 The [sender] in this table denotes the sending side. The following 3545 table indicates the purpose values for each type of key: 3547 +----------+---------+ 3548 | Key Type | Purpose | 3549 +----------+---------+ 3550 | key | "key" | 3551 | | | 3552 | iv | "iv" | 3553 +----------+---------+ 3555 All the traffic keying material is recomputed whenever the underlying 3556 Secret changes (e.g., when changing from the handshake to application 3557 data keys or upon a key update). 3559 7.3.1. Diffie-Hellman 3561 A conventional Diffie-Hellman computation is performed. The 3562 negotiated key (Z) is converted to byte string by encoding in big- 3563 endian, padded with zeros up to the size of the prime. This byte 3564 string is used as the shared secret, and is used in the key schedule 3565 as specified above. 3567 Note that this construction differs from previous versions of TLS 3568 which remove leading zeros. 3570 7.3.2. Elliptic Curve Diffie-Hellman 3572 For secp256r1, secp384r1 and secp521r1, ECDH calculations (including 3573 parameter and key generation as well as the shared secret 3574 calculation) are performed according to [IEEE1363] using the ECKAS- 3575 DH1 scheme with the identity map as key derivation function (KDF), so 3576 that the shared secret is the x-coordinate of the ECDH shared secret 3577 elliptic curve point represented as an octet string. Note that this 3578 octet string (Z in IEEE 1363 terminology) as output by FE2OSP, the 3579 Field Element to Octet String Conversion Primitive, has constant 3580 length for any given field; leading zeros found in this octet string 3581 MUST NOT be truncated. 3583 (Note that this use of the identity KDF is a technicality. The 3584 complete picture is that ECDH is employed with a non-trivial KDF 3585 because TLS does not directly use this secret for anything other than 3586 for computing other secrets.) 3588 ECDH functions are used as follows: 3590 - The public key to put into the KeyShareEntry.key_exchange 3591 structure is the result of applying the ECDH function to the 3592 secret key of appropriate length (into scalar input) and the 3593 standard public basepoint (into u-coordinate point input). 3595 - The ECDH shared secret is the result of applying ECDH function to 3596 the secret key (into scalar input) and the peer's public key (into 3597 u-coordinate point input). The output is used raw, with no 3598 processing. 3600 For X25519 and X448, see [RFC7748]. 3602 7.3.3. Exporters 3604 [RFC5705] defines keying material exporters for TLS in terms of the 3605 TLS PRF. This document replaces the PRF with HKDF, thus requiring a 3606 new construction. The exporter interface remains the same. If 3607 context is provided, the value is computed as: 3609 HKDF-Expand-Label(exporter_secret, label, context_value, key_length) 3611 If no context is provided, the value is computed as: 3613 HKDF-Expand-Label(exporter_secret, label, "", key_length) 3615 Note that providing no context computes the same value as providing 3616 an empty context. As of this document's publication, no allocated 3617 exporter label is used with both modes. Future specifications MUST 3618 NOT provide an empty context and no context with the same label and 3619 SHOULD provide a context, possibly empty, in all exporter 3620 computations. 3622 8. Compliance Requirements 3624 8.1. MTI Cipher Suites 3626 In the absence of an application profile standard specifying 3627 otherwise, a TLS-compliant application MUST implement the 3628 TLS_AES_128_GCM_SHA256 cipher suite and SHOULD implement the 3629 TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 cipher 3630 suites. 3632 A TLS-compliant application MUST support digital signatures with 3633 rsa_pkcs1_sha256 (for certificates), rsa_pss_sha256 (for 3634 CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A 3635 TLS-compliant application MUST support key exchange with secp256r1 3636 (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748]. 3638 8.2. MTI Extensions 3640 In the absence of an application profile standard specifying 3641 otherwise, a TLS-compliant application MUST implement the following 3642 TLS extensions: 3644 - Supported Versions ("supported_versions"; Section 4.2.1) 3646 - Signature Algorithms ("signature_algorithms"; Section 4.2.3) 3648 - Negotiated Groups ("supported_groups"; Section 4.2.4) 3650 - Key Share ("key_share"; Section 4.2.5) 3652 - Pre-Shared Key ("pre_shared_key"; Section 4.2.6) 3654 - Server Name Indication ("server_name"; Section 3 of [RFC6066]) 3656 - Cookie ("cookie"; Section 4.2.2) 3658 All implementations MUST send and use these extensions when offering 3659 applicable cipher suites: 3661 - "supported_versions" is REQUIRED for all ClientHello messages. 3663 - "signature_algorithms" is REQUIRED for certificate authenticated 3664 cipher suites. 3666 - "supported_groups" and "key_share" are REQUIRED for DHE or ECDHE 3667 cipher suites. 3669 - "pre_shared_key" is REQUIRED for PSK cipher suites. 3671 - "cookie" is REQUIRED for all cipher suites. 3673 When negotiating use of applicable cipher suites, endpoints MUST 3674 abort the handshake with a "missing_extension" alert if the required 3675 extension was not provided. Any endpoint that receives any invalid 3676 combination of cipher suites and extensions MAY abort the connection 3677 with a "missing_extension" alert, regardless of negotiated 3678 parameters. 3680 Additionally, all implementations MUST support use of the 3681 "server_name" extension with applications capable of using it. 3682 Servers MAY require clients to send a valid "server_name" extension. 3683 Servers requiring this extension SHOULD respond to a ClientHello 3684 lacking a "server_name" extension by terminating the connection with 3685 a "missing_extension" alert. 3687 9. Security Considerations 3689 Security issues are discussed throughout this memo, especially in 3690 Appendices B, C, and D. 3692 10. IANA Considerations 3694 This document uses several registries that were originally created in 3695 [RFC4346]. IANA has updated these to reference this document. The 3696 registries and their allocation policies are below: 3698 - TLS Cipher Suite Registry: Values with the first byte in the range 3699 0-254 (decimal) are assigned via Specification Required [RFC2434]. 3700 Values with the first byte 255 (decimal) are reserved for Private 3701 Use [RFC2434]. 3703 IANA [SHALL add/has added] the cipher suites listed in 3704 Appendix A.4 to the registry. The "Value" and "Description" 3705 columns are taken from the table. The "DTLS-OK" and "Recommended" 3706 columns are both marked as "Yes" for each new cipher suite. 3707 [[This assumes [I-D.sandj-tls-iana-registry-updates] has been 3708 applied.]] 3710 - TLS ContentType Registry: Future values are allocated via 3711 Standards Action [RFC2434]. 3713 - TLS Alert Registry: Future values are allocated via Standards 3714 Action [RFC2434]. 3716 - TLS HandshakeType Registry: Future values are allocated via 3717 Standards Action [RFC2434]. IANA [SHALL update/has updated] this 3718 registry to rename item 4 from "NewSessionTicket" to 3719 "new_session_ticket". 3721 This document also uses a registry originally created in [RFC4366]. 3722 IANA has updated it to reference this document. The registry and its 3723 allocation policy is listed below: 3725 - TLS ExtensionType Registry: Values with the first byte in the 3726 range 0-254 (decimal) are assigned via Specification Required 3727 [RFC2434]. Values with the first byte 255 (decimal) are reserved 3728 for Private Use [RFC2434]. IANA [SHALL update/has updated] this 3729 registry to include the "key_share", "pre_shared_key", and 3730 "early_data" extensions as defined in this document. 3732 IANA [shall update/has updated] this registry to add a 3733 "Recommended" column. IANA [shall/has] initially populated this 3734 column with the values in the table below. This table has been 3735 generated by marking Standards Track RFCs as "Yes" and all others 3736 as "No". 3738 IANA [shall update/has updated] this registry to include a "TLS 3739 1.3" column with the following four values: "Client", indicating 3740 that the server shall not send them. "Clear", indicating that 3741 they shall be in the ServerHello. "Encrypted", indicating that 3742 they shall be in the EncryptedExtensions block, and "No" 3743 indicating that they are not used in TLS 1.3. This column [shall 3744 be/has been] initially populated with the values in this document. 3746 IANA [shall update/has updated] this registry to include a 3747 "HelloRetryRequest" column with the following two values: "Yes", 3748 indicating it may be sent in HelloRetryRequest, and "No", 3749 indicating it may not be sent in HelloRetryRequest. This column 3750 [shall be/has been] initially populated with the values in this 3751 document. 3753 +------------------------------+----------+---------+---------------+ 3754 | Extension | Recommen | TLS 1.3 | HelloRetryReq | 3755 | | ded | | uest | 3756 +------------------------------+----------+---------+---------------+ 3757 | server_name [RFC6066] | Yes | Encrypt | No | 3758 | | | ed | | 3759 | | | | | 3760 | max_fragment_length | Yes | Encrypt | No | 3761 | [RFC6066] | | ed | | 3762 | | | | | 3763 | client_certificate_url | Yes | Encrypt | No | 3764 | [RFC6066] | | ed | | 3765 | | | | | 3766 | trusted_ca_keys [RFC6066] | Yes | Encrypt | No | 3767 | | | ed | | 3768 | | | | | 3769 | truncated_hmac [RFC6066] | Yes | No | No | 3770 | | | | | 3771 | status_request [RFC6066] | Yes | Encrypt | No | 3772 | | | ed | | 3773 | | | | | 3774 | user_mapping [RFC4681] | Yes | Encrypt | No | 3775 | | | ed | | 3776 | | | | | 3777 | client_authz [RFC5878] | No | No | No | 3778 | | | | | 3779 | server_authz [RFC5878] | No | No | No | 3780 | | | | | 3781 | cert_type [RFC6091] | Yes | Encrypt | No | 3782 | | | ed | | 3783 | | | | | 3784 | supported_groups [RFC7919] | Yes | Encrypt | No | 3785 | | | ed | | 3786 | | | | | 3787 | ec_point_formats [RFC4492] | Yes | No | No | 3788 | | | | | 3789 | srp [RFC5054] | No | No | No | 3790 | | | | | 3791 | signature_algorithms | Yes | Clear | No | 3792 | [RFC5246] | | | | 3793 | | | | | 3794 | use_srtp [RFC5764] | Yes | Encrypt | No | 3795 | | | ed | | 3796 | | | | | 3797 | heartbeat [RFC6520] | Yes | Encrypt | No | 3798 | | | ed | | 3799 | | | | | 3800 | application_layer_protocol_n | Yes | Encrypt | No | 3801 | egotiation [RFC7301] | | ed | | 3802 | | | | | 3803 | status_request_v2 [RFC6961] | Yes | Encrypt | No | 3804 | | | ed | | 3805 | | | | | 3806 | signed_certificate_timestamp | No | Encrypt | No | 3807 | [RFC6962] | | ed | | 3808 | | | | | 3809 | client_certificate_type | Yes | Encrypt | No | 3810 | [RFC7250] | | ed | | 3811 | | | | | 3812 | server_certificate_type | Yes | Encrypt | No | 3813 | [RFC7250] | | ed | | 3814 | | | | | 3815 | padding [RFC7685] | Yes | Client | No | 3816 | | | | | 3817 | encrypt_then_mac [RFC7366] | Yes | No | No | 3818 | | | | | 3819 | extended_master_secret | Yes | No | No | 3820 | [RFC7627] | | | | 3821 | | | | | 3822 | SessionTicket TLS [RFC4507] | Yes | No | No | 3823 | | | | | 3824 | renegotiation_info [RFC5746] | Yes | No | No | 3825 | | | | | 3826 | key_share [[this document]] | Yes | Clear | Yes | 3827 | | | | | 3828 | pre_shared_key [[this | Yes | Clear | No | 3829 | document]] | | | | 3830 | | | | | 3831 | early_data [[this document]] | Yes | Encrypt | No | 3832 | | | ed | | 3833 | | | | | 3834 | cookie [[this document]] | Yes | Client | Yes | 3835 | | | | | 3836 | supported_versions [[this | Yes | Client | No | 3837 | document]] | | | | 3838 +------------------------------+----------+---------+---------------+ 3840 In addition, this document defines two new registries to be 3841 maintained by IANA 3843 - TLS SignatureScheme Registry: Values with the first byte in the 3844 range 0-254 (decimal) are assigned via Specification Required 3845 [RFC2434]. Values with the first byte 255 (decimal) are reserved 3846 for Private Use [RFC2434]. Values with the first byte in the 3847 range 0-6 or with the second byte in the range 0-3 that are not 3848 currently allocated are reserved for backwards compatibility. 3849 This registry SHALL have a "Recommended" column. The registry 3850 [shall be/ has been] initially populated with the values described 3851 in Section 4.2.3. The following values SHALL be marked as 3852 "Recommended": ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, 3853 rsa_pss_sha256, rsa_pss_sha384, rsa_pss_sha512, ed25519. 3855 Finally, this document obsoletes the TLS HashAlgorithm Registry and 3856 the TLS SignatureAlgorithm Registry, both originally created in 3857 [RFC5246]. IANA [SHALL update/has updated] the TLS HashAlgorithm 3858 Registry to list values 7-223 as "Reserved" and the TLS 3859 SignatureAlgorithm Registry to list values 4-233 as "Reserved". 3861 11. References 3863 11.1. Normative References 3865 [AES] National Institute of Standards and Technology, 3866 "Specification for the Advanced Encryption Standard 3867 (AES)", NIST FIPS 197, November 2001. 3869 [DH] Diffie, W. and M. Hellman, "New Directions in 3870 Cryptography", IEEE Transactions on Information Theory, 3871 V.IT-22 n.6 , June 1977. 3873 [I-D.irtf-cfrg-eddsa] 3874 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 3875 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-08 3876 (work in progress), August 2016. 3878 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3879 Hashing for Message Authentication", RFC 2104, 3880 DOI 10.17487/RFC2104, February 1997, 3881 . 3883 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3884 Requirement Levels", BCP 14, RFC 2119, 3885 DOI 10.17487/RFC2119, March 1997, 3886 . 3888 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3889 IANA Considerations Section in RFCs", RFC 2434, 3890 DOI 10.17487/RFC2434, October 1998, 3891 . 3893 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3894 Standards (PKCS) #1: RSA Cryptography Specifications 3895 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 3896 2003, . 3898 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3899 Housley, R., and W. Polk, "Internet X.509 Public Key 3900 Infrastructure Certificate and Certificate Revocation List 3901 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3902 . 3904 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 3905 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 3906 DOI 10.17487/RFC5288, August 2008, 3907 . 3909 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3910 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3911 DOI 10.17487/RFC5289, August 2008, 3912 . 3914 [RFC5487] Badra, M., "Pre-Shared Key Cipher Suites for TLS with SHA- 3915 256/384 and AES Galois Counter Mode", RFC 5487, 3916 DOI 10.17487/RFC5487, March 2009, 3917 . 3919 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 3920 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 3921 March 2010, . 3923 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3924 Key Derivation Function (HKDF)", RFC 5869, 3925 DOI 10.17487/RFC5869, May 2010, 3926 . 3928 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 3929 Extensions: Extension Definitions", RFC 6066, 3930 DOI 10.17487/RFC6066, January 2011, 3931 . 3933 [RFC6209] Kim, W., Lee, J., Park, J., and D. Kwon, "Addition of the 3934 ARIA Cipher Suites to Transport Layer Security (TLS)", 3935 RFC 6209, DOI 10.17487/RFC6209, April 2011, 3936 . 3938 [RFC6367] Kanno, S. and M. Kanda, "Addition of the Camellia Cipher 3939 Suites to Transport Layer Security (TLS)", RFC 6367, 3940 DOI 10.17487/RFC6367, September 2011, 3941 . 3943 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 3944 Transport Layer Security (TLS)", RFC 6655, 3945 DOI 10.17487/RFC6655, July 2012, 3946 . 3948 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 3949 Multiple Certificate Status Request Extension", RFC 6961, 3950 DOI 10.17487/RFC6961, June 2013, 3951 . 3953 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 3954 Algorithm (DSA) and Elliptic Curve Digital Signature 3955 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 3956 2013, . 3958 [RFC7251] McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 3959 CCM Elliptic Curve Cryptography (ECC) Cipher Suites for 3960 TLS", RFC 7251, DOI 10.17487/RFC7251, June 2014, 3961 . 3963 [RFC7443] Patil, P., Reddy, T., Salgueiro, G., and M. Petit- 3964 Huguenin, "Application-Layer Protocol Negotiation (ALPN) 3965 Labels for Session Traversal Utilities for NAT (STUN) 3966 Usages", RFC 7443, DOI 10.17487/RFC7443, January 2015, 3967 . 3969 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 3970 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 3971 . 3973 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 3974 for Security", RFC 7748, DOI 10.17487/RFC7748, January 3975 2016, . 3977 [RFC7905] Langley, A., Chang, W., Mavrogiannopoulos, N., 3978 Strombergson, J., and S. Josefsson, "ChaCha20-Poly1305 3979 Cipher Suites for Transport Layer Security (TLS)", 3980 RFC 7905, DOI 10.17487/RFC7905, June 2016, 3981 . 3983 [SHS] National Institute of Standards and Technology, U.S. 3984 Department of Commerce, "Secure Hash Standard", NIST FIPS 3985 PUB 180-4, March 2012. 3987 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 3988 Specification of Basic Encoding Rules (BER), Canonical 3989 Encoding Rules (CER) and Distinguished Encoding Rules 3990 (DER)", ISO/IEC 8825-1:2002, 2002. 3992 [X962] ANSI, "Public Key Cryptography For The Financial Services 3993 Industry: The Elliptic Curve Digital Signature Algorithm 3994 (ECDSA)", ANSI X9.62, 1998. 3996 11.2. Informative References 3998 [AEAD-LIMITS] 3999 Luykx, A. and K. Paterson, "Limits on Authenticated 4000 Encryption Use in TLS", 2016, 4001 . 4003 [BBFKZG16] 4004 Bhargavan, K., Brzuska, C., Fournet, C., Kohlweiss, M., 4005 Zanella-Beguelin, S., and M. Green, "Downgrade Resilience 4006 in Key-Exchange Protocols", Proceedings of IEEE Symposium 4007 on Security and Privacy (Oakland) 2016 , 2016. 4009 [CHSV16] Cremers, C., Horvat, M., Scott, S., and T. van der Merwe, 4010 "Automated Analysis and Verification of TLS 1.3: 0-RTT, 4011 Resumption and Delayed Authentication", Proceedings of 4012 IEEE Symposium on Security and Privacy (Oakland) 2016 , 4013 2016. 4015 [CK01] Canetti, R. and H. Krawczyk, "Analysis of Key-Exchange 4016 Protocols and Their Use for Building Secure Channels", 4017 Proceedings of Eurocrypt 2001 , 2001. 4019 [DOW92] Diffie, W., van Oorschot, P., and M. Wiener, 4020 ""Authentication and authenticated key exchanges"", 4021 Designs, Codes and Cryptography , n.d.. 4023 [DSS] National Institute of Standards and Technology, U.S. 4024 Department of Commerce, "Digital Signature Standard, 4025 version 4", NIST FIPS PUB 186-4, 2013. 4027 [ECDSA] American National Standards Institute, "Public Key 4028 Cryptography for the Financial Services Industry: The 4029 Elliptic Curve Digital Signature Algorithm (ECDSA)", 4030 ANSI ANS X9.62-2005, November 2005. 4032 [FGSW16] Fischlin, M., Guenther, F., Schmidt, B., and B. Warinschi, 4033 "Key Confirmation in Key Exchange: A Formal Treatment and 4034 Implications for TLS 1.3", Proceedings of IEEE Symposium 4035 on Security and Privacy (Oakland) 2016 , 2016. 4037 [FI06] Finney, H., "Bleichenbacher's RSA signature forgery based 4038 on implementation error", August 2006, 4039 . 4042 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 4043 Operation: Galois/Counter Mode (GCM) and GMAC", 4044 NIST Special Publication 800-38D, November 2007. 4046 [I-D.sandj-tls-iana-registry-updates] 4047 Salowey, J. and S. Turner, "D/TLS IANA Registry Updates", 4048 draft-sandj-tls-iana-registry-updates-00 (work in 4049 progress), September 2016. 4051 [IEEE1363] 4052 IEEE, "Standard Specifications for Public Key 4053 Cryptography", IEEE 1363 , 2000. 4055 [LXZFH16] Li, X., Xu, J., Feng, D., Zhang, Z., and H. Hu, "Multiple 4056 Handshakes Security of TLS 1.3 Candidates", Proceedings of 4057 IEEE Symposium on Security and Privacy (Oakland) 2016 , 4058 2016. 4060 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate 4061 Syntax Standard, version 1.5", November 1993. 4063 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message 4064 Syntax Standard, version 1.5", November 1993. 4066 [PSK-FINISHED] 4067 Cremers, C., Horvat, M., van der Merwe, T., and S. Scott, 4068 "Revision 10: possible attack if client authentication is 4069 allowed during PSK", 2015, . 4072 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4073 RFC 793, DOI 10.17487/RFC0793, September 1981, 4074 . 4076 [RFC1948] Bellovin, S., "Defending Against Sequence Number Attacks", 4077 RFC 1948, DOI 10.17487/RFC1948, May 1996, 4078 . 4080 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 4081 Text on Security Considerations", BCP 72, RFC 3552, 4082 DOI 10.17487/RFC3552, July 2003, 4083 . 4085 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 4086 "Randomness Requirements for Security", BCP 106, RFC 4086, 4087 DOI 10.17487/RFC4086, June 2005, 4088 . 4090 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4091 Ciphersuites for Transport Layer Security (TLS)", 4092 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4093 . 4095 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 4096 DOI 10.17487/RFC4302, December 2005, 4097 . 4099 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 4100 RFC 4303, DOI 10.17487/RFC4303, December 2005, 4101 . 4103 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 4104 (TLS) Protocol Version 1.1", RFC 4346, 4105 DOI 10.17487/RFC4346, April 2006, 4106 . 4108 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 4109 and T. Wright, "Transport Layer Security (TLS) 4110 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006, 4111 . 4113 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4114 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4115 for Transport Layer Security (TLS)", RFC 4492, 4116 DOI 10.17487/RFC4492, May 2006, 4117 . 4119 [RFC4506] Eisler, M., Ed., "XDR: External Data Representation 4120 Standard", STD 67, RFC 4506, DOI 10.17487/RFC4506, May 4121 2006, . 4123 [RFC4507] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 4124 "Transport Layer Security (TLS) Session Resumption without 4125 Server-Side State", RFC 4507, DOI 10.17487/RFC4507, May 4126 2006, . 4128 [RFC4681] Santesson, S., Medvinsky, A., and J. Ball, "TLS User 4129 Mapping Extension", RFC 4681, DOI 10.17487/RFC4681, 4130 October 2006, . 4132 [RFC5054] Taylor, D., Wu, T., Mavrogiannopoulos, N., and T. Perrin, 4133 "Using the Secure Remote Password (SRP) Protocol for TLS 4134 Authentication", RFC 5054, DOI 10.17487/RFC5054, November 4135 2007, . 4137 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 4138 "Transport Layer Security (TLS) Session Resumption without 4139 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 4140 January 2008, . 4142 [RFC5081] Mavrogiannopoulos, N., "Using OpenPGP Keys for Transport 4143 Layer Security (TLS) Authentication", RFC 5081, 4144 DOI 10.17487/RFC5081, November 2007, 4145 . 4147 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 4148 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 4149 . 4151 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4152 (TLS) Protocol Version 1.2", RFC 5246, 4153 DOI 10.17487/RFC5246, August 2008, 4154 . 4156 [RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov, 4157 "Transport Layer Security (TLS) Renegotiation Indication 4158 Extension", RFC 5746, DOI 10.17487/RFC5746, February 2010, 4159 . 4161 [RFC5763] Fischl, J., Tschofenig, H., and E. Rescorla, "Framework 4162 for Establishing a Secure Real-time Transport Protocol 4163 (SRTP) Security Context Using Datagram Transport Layer 4164 Security (DTLS)", RFC 5763, DOI 10.17487/RFC5763, May 4165 2010, . 4167 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 4168 Security (DTLS) Extension to Establish Keys for the Secure 4169 Real-time Transport Protocol (SRTP)", RFC 5764, 4170 DOI 10.17487/RFC5764, May 2010, 4171 . 4173 [RFC5878] Brown, M. and R. Housley, "Transport Layer Security (TLS) 4174 Authorization Extensions", RFC 5878, DOI 10.17487/RFC5878, 4175 May 2010, . 4177 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 4178 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010, 4179 . 4181 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys 4182 for Transport Layer Security (TLS) Authentication", 4183 RFC 6091, DOI 10.17487/RFC6091, February 2011, 4184 . 4186 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 4187 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176, March 4188 2011, . 4190 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4191 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4192 January 2012, . 4194 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 4195 Layer Security (TLS) and Datagram Transport Layer Security 4196 (DTLS) Heartbeat Extension", RFC 6520, 4197 DOI 10.17487/RFC6520, February 2012, 4198 . 4200 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 4201 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 4202 . 4204 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 4205 Protocol (HTTP/1.1): Message Syntax and Routing", 4206 RFC 7230, DOI 10.17487/RFC7230, June 2014, 4207 . 4209 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4210 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4211 Transport Layer Security (TLS) and Datagram Transport 4212 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4213 June 2014, . 4215 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 4216 "Transport Layer Security (TLS) Application-Layer Protocol 4217 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 4218 July 2014, . 4220 [RFC7366] Gutmann, P., "Encrypt-then-MAC for Transport Layer 4221 Security (TLS) and Datagram Transport Layer Security 4222 (DTLS)", RFC 7366, DOI 10.17487/RFC7366, September 2014, 4223 . 4225 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 4226 DOI 10.17487/RFC7465, February 2015, 4227 . 4229 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 4230 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 4231 DOI 10.17487/RFC7568, June 2015, 4232 . 4234 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 4235 Langley, A., and M. Ray, "Transport Layer Security (TLS) 4236 Session Hash and Extended Master Secret Extension", 4237 RFC 7627, DOI 10.17487/RFC7627, September 2015, 4238 . 4240 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello 4241 Padding Extension", RFC 7685, DOI 10.17487/RFC7685, 4242 October 2015, . 4244 [RFC7919] Gillmor, D., "Negotiated Finite Field Diffie-Hellman 4245 Ephemeral Parameters for Transport Layer Security (TLS)", 4246 RFC 7919, DOI 10.17487/RFC7919, August 2016, 4247 . 4249 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4250 (TLS) Cached Information Extension", RFC 7924, 4251 DOI 10.17487/RFC7924, July 2016, 4252 . 4254 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 4255 Obtaining Digital Signatures and Public-Key 4256 Cryptosystems", Communications of the ACM v. 21, n. 2, pp. 4257 120-126., February 1978. 4259 [SIGMA] Krawczyk, H., "SIGMA: the 'SIGn-and-MAc' approach to 4260 authenticated Di e-Hellman and its use in the IKE 4261 protocols", Proceedings of CRYPTO 2003 , 2003. 4263 [SLOTH] Bhargavan, K. and G. Leurent, "Transcript Collision 4264 Attacks: Breaking Authentication in TLS, IKE, and SSH", 4265 Network and Distributed System Security Symposium (NDSS 4266 2016) , 2016. 4268 [SSL2] Hickman, K., "The SSL Protocol", February 1995. 4270 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 4271 Protocol", November 1996. 4273 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 4274 practical", USENIX Security Symposium, 2003. 4276 [X501] "Information Technology - Open Systems Interconnection - 4277 The Directory: Models", ITU-T X.501, 1993. 4279 11.3. URIs 4281 [1] mailto:tls@ietf.org 4283 Appendix A. Protocol Data Structures and Constant Values 4285 This section describes protocol types and constants. Values listed 4286 as _RESERVED were used in previous versions of TLS and are listed 4287 here for completeness. TLS 1.3 implementations MUST NOT send them 4288 but might receive them from older TLS implementations. 4290 A.1. Record Layer 4292 enum { 4293 invalid_RESERVED(0), 4294 change_cipher_spec_RESERVED(20), 4295 alert(21), 4296 handshake(22), 4297 application_data(23), 4298 (255) 4299 } ContentType; 4301 struct { 4302 ContentType type; 4303 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 4304 uint16 length; 4305 opaque fragment[TLSPlaintext.length]; 4306 } TLSPlaintext; 4308 struct { 4309 opaque content[TLSPlaintext.length]; 4310 ContentType type; 4311 uint8 zeros[length_of_padding]; 4312 } TLSInnerPlaintext; 4314 struct { 4315 ContentType opaque_type = application_data(23); /* see TLSInnerPlaintext.type */ 4316 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 4317 uint16 length; 4318 opaque encrypted_record[length]; 4319 } TLSCiphertext; 4321 A.2. Alert Messages 4322 enum { warning(1), fatal(2), (255) } AlertLevel; 4324 enum { 4325 close_notify(0), 4326 end_of_early_data(1), 4327 unexpected_message(10), 4328 bad_record_mac(20), 4329 decryption_failed_RESERVED(21), 4330 record_overflow(22), 4331 decompression_failure_RESERVED(30), 4332 handshake_failure(40), 4333 no_certificate_RESERVED(41), 4334 bad_certificate(42), 4335 unsupported_certificate(43), 4336 certificate_revoked(44), 4337 certificate_expired(45), 4338 certificate_unknown(46), 4339 illegal_parameter(47), 4340 unknown_ca(48), 4341 access_denied(49), 4342 decode_error(50), 4343 decrypt_error(51), 4344 export_restriction_RESERVED(60), 4345 protocol_version(70), 4346 insufficient_security(71), 4347 internal_error(80), 4348 inappropriate_fallback(86), 4349 user_canceled(90), 4350 no_renegotiation_RESERVED(100), 4351 missing_extension(109), 4352 unsupported_extension(110), 4353 certificate_unobtainable(111), 4354 unrecognized_name(112), 4355 bad_certificate_status_response(113), 4356 bad_certificate_hash_value(114), 4357 unknown_psk_identity(115), 4358 certificate_required(116), 4359 (255) 4360 } AlertDescription; 4362 struct { 4363 AlertLevel level; 4364 AlertDescription description; 4365 } Alert; 4367 A.3. Handshake Protocol 4369 enum { 4370 hello_request_RESERVED(0), 4371 client_hello(1), 4372 server_hello(2), 4373 new_session_ticket(4), 4374 hello_retry_request(6), 4375 encrypted_extensions(8), 4376 certificate(11), 4377 server_key_exchange_RESERVED(12), 4378 certificate_request(13), 4379 server_hello_done_RESERVED(14), 4380 certificate_verify(15), 4381 client_key_exchange_RESERVED(16), 4382 finished(20), 4383 key_update(24), 4384 (255) 4385 } HandshakeType; 4387 struct { 4388 HandshakeType msg_type; /* handshake type */ 4389 uint24 length; /* bytes in message */ 4390 select (Handshake.msg_type) { 4391 case client_hello: ClientHello; 4392 case server_hello: ServerHello; 4393 case hello_retry_request: HelloRetryRequest; 4394 case encrypted_extensions: EncryptedExtensions; 4395 case certificate_request: CertificateRequest; 4396 case certificate: Certificate; 4397 case certificate_verify: CertificateVerify; 4398 case finished: Finished; 4399 case new_session_ticket: NewSessionTicket; 4400 case key_update: KeyUpdate; 4401 } body; 4402 } Handshake; 4404 A.3.1. Key Exchange Messages 4406 struct { 4407 uint8 major; 4408 uint8 minor; 4409 } ProtocolVersion; 4411 struct { 4412 opaque random_bytes[32]; 4413 } Random; 4414 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 4416 struct { 4417 ProtocolVersion legacy_version = { 3, 3 }; /* TLS v1.2 */ 4418 Random random; 4419 opaque legacy_session_id<0..32>; 4420 CipherSuite cipher_suites<2..2^16-2>; 4421 opaque legacy_compression_methods<1..2^8-1>; 4422 Extension extensions<0..2^16-1>; 4423 } ClientHello; 4425 struct { 4426 ProtocolVersion version; 4427 Random random; 4428 CipherSuite cipher_suite; 4429 Extension extensions<0..2^16-1>; 4430 } ServerHello; 4432 struct { 4433 ProtocolVersion server_version; 4434 Extension extensions<2..2^16-1>; 4435 } HelloRetryRequest; 4437 struct { 4438 ExtensionType extension_type; 4439 opaque extension_data<0..2^16-1>; 4440 } Extension; 4442 enum { 4443 supported_groups(10), 4444 signature_algorithms(13), 4445 key_share(40), 4446 pre_shared_key(41), 4447 early_data(42), 4448 supported_versions(43), 4449 cookie(44), 4450 (65535) 4451 } ExtensionType; 4453 struct { 4454 NamedGroup group; 4455 opaque key_exchange<1..2^16-1>; 4456 } KeyShareEntry; 4458 struct { 4459 select (Handshake.msg_type) { 4460 case client_hello: 4461 KeyShareEntry client_shares<0..2^16-1>; 4463 case hello_retry_request: 4464 NamedGroup selected_group; 4466 case server_hello: 4467 KeyShareEntry server_share; 4468 }; 4469 } KeyShare; 4471 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; 4472 enum { psk_auth(0), psk_sign_auth(1), (255) } PskAuthenticationMode; 4474 struct { 4475 PskKeyExchangeMode ke_modes<1..255>; 4476 PskAuthenticationMode auth_modes<1..255>; 4477 opaque identity<0..2^16-1>; 4478 } PskIdentity; 4480 struct { 4481 select (Handshake.msg_type) { 4482 case client_hello: 4483 PskIdentity identities<6..2^16-1>; 4485 case server_hello: 4486 uint16 selected_identity; 4487 }; 4488 } PreSharedKeyExtension; 4490 struct { 4491 select (Handshake.msg_type) { 4492 case client_hello: 4493 uint32 obfuscated_ticket_age; 4495 case server_hello: 4496 struct {}; 4497 }; 4498 } EarlyDataIndication; 4500 A.3.1.1. Version Extension 4502 struct { 4503 ProtocolVersion versions<2..254>; 4504 } SupportedVersions; 4506 A.3.1.2. Cookie Extension 4508 struct { 4509 opaque cookie<0..2^16-1>; 4510 } Cookie; 4512 A.3.1.3. Signature Algorithm Extension 4514 enum { 4515 /* RSASSA-PKCS1-v1_5 algorithms */ 4516 rsa_pkcs1_sha1 (0x0201), 4517 rsa_pkcs1_sha256 (0x0401), 4518 rsa_pkcs1_sha384 (0x0501), 4519 rsa_pkcs1_sha512 (0x0601), 4521 /* ECDSA algorithms */ 4522 ecdsa_secp256r1_sha256 (0x0403), 4523 ecdsa_secp384r1_sha384 (0x0503), 4524 ecdsa_secp521r1_sha512 (0x0603), 4526 /* RSASSA-PSS algorithms */ 4527 rsa_pss_sha256 (0x0804), 4528 rsa_pss_sha384 (0x0805), 4529 rsa_pss_sha512 (0x0806), 4531 /* EdDSA algorithms */ 4532 ed25519 (0x0807), 4533 ed448 (0x0808), 4535 /* Reserved Code Points */ 4536 dsa_sha1_RESERVED (0x0202), 4537 dsa_sha256_RESERVED (0x0402), 4538 dsa_sha384_RESERVED (0x0502), 4539 dsa_sha512_RESERVED (0x0602), 4540 ecdsa_sha1_RESERVED (0x0203), 4541 obsolete_RESERVED (0x0000..0x0200), 4542 obsolete_RESERVED (0x0204..0x0400), 4543 obsolete_RESERVED (0x0404..0x0500), 4544 obsolete_RESERVED (0x0504..0x0600), 4545 obsolete_RESERVED (0x0604..0x06FF), 4546 private_use (0xFE00..0xFFFF), 4547 (0xFFFF) 4548 } SignatureScheme; 4550 SignatureScheme supported_signature_algorithms<2..2^16-2>; 4552 A.3.1.4. Supported Groups Extension 4553 enum { 4554 /* Elliptic Curve Groups (ECDHE) */ 4555 obsolete_RESERVED (1..22), 4556 secp256r1 (23), secp384r1 (24), secp521r1 (25), 4557 obsolete_RESERVED (26..28), 4558 x25519 (29), x448 (30), 4560 /* Finite Field Groups (DHE) */ 4561 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 4562 ffdhe6144 (259), ffdhe8192 (260), 4564 /* Reserved Code Points */ 4565 ffdhe_private_use (0x01FC..0x01FF), 4566 ecdhe_private_use (0xFE00..0xFEFF), 4567 obsolete_RESERVED (0xFF01..0xFF02), 4568 (0xFFFF) 4569 } NamedGroup; 4571 struct { 4572 NamedGroup named_group_list<2..2^16-1>; 4573 } NamedGroupList; 4575 Values within "obsolete_RESERVED" ranges were used in previous 4576 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3 4577 implementations. The obsolete curves have various known/theoretical 4578 weaknesses or have had very little usage, in some cases only due to 4579 unintentional server configuration issues. They are no longer 4580 considered appropriate for general use and should be assumed to be 4581 potentially unsafe. The set of curves specified here is sufficient 4582 for interoperability with all currently deployed and properly 4583 configured TLS implementations. 4585 A.3.1.5. Deprecated Extensions 4587 The following extensions are no longer applicable to TLS 1.3, 4588 although TLS 1.3 clients MAY send them if they are willing to 4589 negotiate them with prior versions of TLS. TLS 1.3 servers MUST 4590 ignore these extensions if they are negotiating TLS 1.3: 4591 truncated_hmac [RFC6066], srp [RFC5054], encrypt_then_mac [RFC7366], 4592 extended_master_secret [RFC7627], SessionTicket [RFC5077], and 4593 renegotiation_info [RFC5746]. 4595 A.3.2. Server Parameters Messages 4596 struct { 4597 Extension extensions<0..2^16-1>; 4598 } EncryptedExtensions; 4600 opaque DistinguishedName<1..2^16-1>; 4602 struct { 4603 opaque certificate_extension_oid<1..2^8-1>; 4604 opaque certificate_extension_values<0..2^16-1>; 4605 } CertificateExtension; 4607 struct { 4608 opaque certificate_request_context<0..2^8-1>; 4609 SignatureScheme 4610 supported_signature_algorithms<2..2^16-2>; 4611 DistinguishedName certificate_authorities<0..2^16-1>; 4612 CertificateExtension certificate_extensions<0..2^16-1>; 4613 } CertificateRequest; 4615 A.3.3. Authentication Messages 4617 opaque ASN1Cert<1..2^24-1>; 4619 struct { 4620 opaque certificate_request_context<0..2^8-1>; 4621 ASN1Cert certificate_list<0..2^24-1>; 4622 } Certificate; 4624 struct { 4625 SignatureScheme algorithm; 4626 opaque signature<0..2^16-1>; 4627 } CertificateVerify; 4629 struct { 4630 opaque verify_data[Hash.length]; 4631 } Finished; 4633 A.3.4. Ticket Establishment 4634 enum { ticket_early_data_info(1), (65535) } TicketExtensionType; 4636 struct { 4637 TicketExtensionType extension_type; 4638 opaque extension_data<1..2^16-1>; 4639 } TicketExtension; 4641 struct { 4642 uint32 ticket_lifetime; 4643 PskKeyExchangeMode ke_modes<1..255>; 4644 PskAuthenticationMode auth_modes<1..255>; 4645 opaque ticket<1..2^16-1>; 4646 TicketExtension extensions<0..2^16-2>; 4647 } NewSessionTicket; 4649 A.3.5. Updating Keys 4651 enum { update_not_requested(0), update_requested(1), (255) 4652 } KeyUpdateRequest; 4654 struct { 4655 KeyUpdateRequest request_update; 4656 } KeyUpdate; 4658 A.4. Cipher Suites 4660 A symmetric cipher suite defines the pair of the AEAD algorithm and 4661 hash algorithm to be used with HKDF. Cipher suite names follow the 4662 naming convention: 4664 CipherSuite TLS_AEAD_HASH = VALUE; 4666 +-----------+------------------------------------------------+ 4667 | Component | Contents | 4668 +-----------+------------------------------------------------+ 4669 | TLS | The string "TLS" | 4670 | | | 4671 | AEAD | The AEAD algorithm used for record protection | 4672 | | | 4673 | HASH | The hash algorithm used with HKDF | 4674 | | | 4675 | VALUE | The two byte ID assigned for this cipher suite | 4676 +-----------+------------------------------------------------+ 4678 This specification defines the following cipher suites for use with 4679 TLS 1.3. 4681 +------------------------------+-------------+ 4682 | Description | Value | 4683 +------------------------------+-------------+ 4684 | TLS_AES_128_GCM_SHA256 | {0x13,0x01} | 4685 | | | 4686 | TLS_AES_256_GCM_SHA384 | {0x13,0x02} | 4687 | | | 4688 | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} | 4689 | | | 4690 | TLS_AES_128_CCM_SHA256 | {0x13,0x04} | 4691 | | | 4692 | TLS_AES_128_CCM_8_SHA256 | {0x13,0x05} | 4693 +------------------------------+-------------+ 4695 The corresponding AEAD algorithms AEAD_AES_128_GCM, AEAD_AES_256_GCM, 4696 and AEAD_AES_128_CCM are defined in [RFC5116]. 4697 AEAD_CHACHA20_POLY1305 is defined in [RFC7539]. AEAD_AES_128_CCM_8 4698 is defined in [RFC6655]. The corresponding hash algorithms are 4699 defined in [SHS]. 4701 Although TLS 1.3 uses the same cipher suite space as previous 4702 versions of TLS, TLS 1.3 cipher suites are defined differently, only 4703 specifying the symmetric ciphers, and cannot it be used for TLS 1.2. 4704 Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 4705 1.3. 4707 New cipher suite values are assigned by IANA as described in 4708 Section 10. 4710 Appendix B. Implementation Notes 4712 The TLS protocol cannot prevent many common security mistakes. This 4713 section provides several recommendations to assist implementors. 4715 B.1. API considerations for 0-RTT 4717 0-RTT data has very different security properties from data 4718 transmitted after a completed handshake: it can be replayed. 4719 Implementations SHOULD provide different functions for reading and 4720 writing 0-RTT data and data transmitted after the handshake, and 4721 SHOULD NOT automatically resend 0-RTT data if it is rejected by the 4722 server. 4724 B.2. Random Number Generation and Seeding 4726 TLS requires a cryptographically secure pseudorandom number generator 4727 (PRNG). In most cases, the operating system provides an appropriate 4728 facility such as /dev/urandom, which should be used absent other 4729 (performance) concerns. It is generally preferable to use an 4730 existing PRNG implementation in preference to crafting a new one, and 4731 many adequate cryptographic libraries are already available under 4732 favorable license terms. Should those prove unsatisfactory, 4733 [RFC4086] provides guidance on the generation of random values. 4735 B.3. Certificates and Authentication 4737 Implementations are responsible for verifying the integrity of 4738 certificates and should generally support certificate revocation 4739 messages. Certificates should always be verified to ensure proper 4740 signing by a trusted Certificate Authority (CA). The selection and 4741 addition of trusted CAs should be done very carefully. Users should 4742 be able to view information about the certificate and root CA. 4744 B.4. Cipher Suite Support 4746 TLS supports a range of key sizes and security levels, including some 4747 that provide no or minimal security. A proper implementation will 4748 probably not support many cipher suites. Applications SHOULD also 4749 enforce minimum and maximum key sizes. For example, certification 4750 paths containing keys or signatures weaker than 2048-bit RSA or 4751 224-bit ECDSA are not appropriate for secure applications. See also 4752 Appendix C.4. 4754 B.5. Implementation Pitfalls 4756 Implementation experience has shown that certain parts of earlier TLS 4757 specifications are not easy to understand, and have been a source of 4758 interoperability and security problems. Many of these areas have 4759 been clarified in this document, but this appendix contains a short 4760 list of the most important things that require special attention from 4761 implementors. 4763 TLS protocol issues: 4765 - Do you correctly handle handshake messages that are fragmented to 4766 multiple TLS records (see Section 5.1)? Including corner cases 4767 like a ClientHello that is split to several small fragments? Do 4768 you fragment handshake messages that exceed the maximum fragment 4769 size? In particular, the certificate and certificate request 4770 handshake messages can be large enough to require fragmentation. 4772 - Do you ignore the TLS record layer version number in all TLS 4773 records? (see Appendix C) 4775 - Have you ensured that all support for SSL, RC4, EXPORT ciphers, 4776 and MD5 (via the "signature_algorithm" extension) is completely 4777 removed from all possible configurations that support TLS 1.3 or 4778 later, and that attempts to use these obsolete capabilities fail 4779 correctly? (see Appendix C) 4781 - Do you handle TLS extensions in ClientHello correctly, including 4782 unknown extensions. 4784 - When the server has requested a client certificate, but no 4785 suitable certificate is available, do you correctly send an empty 4786 Certificate message, instead of omitting the whole message (see 4787 Section 4.4.1.2)? 4789 - When processing the plaintext fragment produced by AEAD-Decrypt 4790 and scanning from the end for the ContentType, do you avoid 4791 scanning past the start of the cleartext in the event that the 4792 peer has sent a malformed plaintext of all-zeros? 4794 - When processing a ClientHello containing a version of { 3, 5 } or 4795 higher, do you respond with the highest common version of TLS 4796 rather than requiring an exact match? Have you ensured this 4797 continues to be true with arbitrarily higher version numbers? 4798 (e.g. { 4, 0 }, { 9, 9 }, { 255, 255 }) 4800 - Do you properly ignore unrecognized cipher suites (Section 4.1.2), 4801 hello extensions (Section 4.2), named groups (Section 4.2.4), and 4802 signature algorithms (Section 4.2.3)? 4804 Cryptographic details: 4806 - What countermeasures do you use to prevent timing attacks 4807 [TIMING]? 4809 - When verifying RSA signatures, do you accept both NULL and missing 4810 parameters? Do you verify that the RSA padding doesn't have 4811 additional data after the hash value? [FI06] 4813 - When using Diffie-Hellman key exchange, do you correctly preserve 4814 leading zero bytes in the negotiated key (see Section 7.3.1)? 4816 - Does your TLS client check that the Diffie-Hellman parameters sent 4817 by the server are acceptable, (see Section 4.2.5.1)? 4819 - Do you use a strong and, most importantly, properly seeded random 4820 number generator (see Appendix B.2) when generating Diffie-Hellman 4821 private values, the ECDSA "k" parameter, and other security- 4822 critical values? It is RECOMMENDED that implementations implement 4823 "deterministic ECDSA" as specified in [RFC6979]. 4825 - Do you zero-pad Diffie-Hellman public key values to the group size 4826 (see Section 4.2.5.1)? 4828 B.6. Client Tracking Prevention 4830 Clients SHOULD NOT reuse a session ticket for multiple connections. 4831 Reuse of a session ticket allows passive observers to correlate 4832 different connections. Servers that issue session tickets SHOULD 4833 offer at least as many session tickets as the number of connections 4834 that a client might use; for example, a web browser using HTTP/1.1 4835 [RFC7230] might open six connections to a server. Servers SHOULD 4836 issue new session tickets with every connection. This ensures that 4837 clients are always able to use a new session ticket when creating a 4838 new connection. 4840 B.7. Unauthenticated Operation 4842 Previous versions of TLS offered explicitly unauthenticated cipher 4843 suites based on anonymous Diffie-Hellman. These modes have been 4844 deprecated in TLS 1.3. However, it is still possible to negotiate 4845 parameters that do not provide verifiable server authentication by 4846 several methods, including: 4848 - Raw public keys [RFC7250]. 4850 - Using a public key contained in a certificate but without 4851 validation of the certificate chain or any of its contents. 4853 Either technique used alone is vulnerable to man-in-the-middle 4854 attacks and therefore unsafe for general use. However, it is also 4855 possible to bind such connections to an external authentication 4856 mechanism via out-of-band validation of the server's public key, 4857 trust on first use, or channel bindings [RFC5929]. [[NOTE: TLS 1.3 4858 needs a new channel binding definition that has not yet been 4859 defined.]] If no such mechanism is used, then the connection has no 4860 protection against active man-in-the-middle attack; applications MUST 4861 NOT use TLS in such a way absent explicit configuration or a specific 4862 application profile. 4864 Appendix C. Backward Compatibility 4866 The TLS protocol provides a built-in mechanism for version 4867 negotiation between endpoints potentially supporting different 4868 versions of TLS. 4870 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 4871 also handle clients trying to use future versions of TLS as long as 4872 the ClientHello format remains compatible and the client supports the 4873 highest protocol version available in the server. 4875 Prior versions of TLS used the record layer version number for 4876 various purposes. (TLSPlaintext.legacy_record_version & 4877 TLSCiphertext.legacy_record_version) As of TLS 1.3, this field is 4878 deprecated and its value MUST be ignored by all implementations. 4879 Version negotiation is performed using only the handshake versions. 4880 (ClientHello.legacy_version, ClientHello "supported_versions" 4881 extension & ServerHello.version) In order to maximize 4882 interoperability with older endpoints, implementations that negotiate 4883 the use of TLS 1.0-1.2 SHOULD set the record layer version number to 4884 the negotiated version for the ServerHello and all records 4885 thereafter. 4887 For maximum compatibility with previously non-standard behavior and 4888 misconfigured deployments, all implementations SHOULD support 4889 validation of certification paths based on the expectations in this 4890 document, even when handling prior TLS versions' handshakes. (see 4891 Section 4.4.1.1) 4893 TLS 1.2 and prior supported an "Extended Master Secret" [RFC7627] 4894 extension which digested large parts of the handshake transcript into 4895 the master secret. Because TLS 1.3 always hashes in the transcript 4896 up to the server CertificateVerify, implementations which support 4897 both TLS 1.3 and earlier versions SHOULD indicate the use of the 4898 Extended Master Secret extension in their APIs whenever TLS 1.3 is 4899 used. 4901 C.1. Negotiating with an older server 4903 A TLS 1.3 client who wishes to negotiate with such older servers will 4904 send a normal TLS 1.3 ClientHello containing { 3, 3 } (TLS 1.2) in 4905 ClientHello.legacy_version but with the correct version in the 4906 "supported_versions" extension. If the server does not support TLS 4907 1.3 it will respond with a ServerHello containing an older version 4908 number. If the client agrees to use this version, the negotiation 4909 will proceed as appropriate for the negotiated protocol. A client 4910 resuming a session SHOULD initiate the connection using the version 4911 that was previously negotiated. 4913 Note that 0-RTT data is not compatible with older servers. See 4914 Appendix C.3. 4916 If the version chosen by the server is not supported by the client 4917 (or not acceptable), the client MUST abort the handshake with a 4918 "protocol_version" alert. 4920 If a TLS server receives a ClientHello containing a version number 4921 greater than the highest version supported by the server, it MUST 4922 reply according to the highest version supported by the server. 4924 Some legacy server implementations are known to not implement the TLS 4925 specification properly and might abort connections upon encountering 4926 TLS extensions or versions which it is not aware of. 4927 Interoperability with buggy servers is a complex topic beyond the 4928 scope of this document. Multiple connection attempts may be required 4929 in order to negotiate a backwards compatible connection, however this 4930 practice is vulnerable to downgrade attacks and is NOT RECOMMENDED. 4932 C.2. Negotiating with an older client 4934 A TLS server can also receive a ClientHello indicating a version 4935 number smaller than its highest supported version. If the 4936 "supported_versions" extension is present, the server MUST negotiate 4937 the highest server-supported version found in that extension. If the 4938 "supported_versions" extension is not present, the server MUST 4939 negotiate the minimum of ClientHello.legacy_version and TLS 1.2.For 4940 example, if the server supports TLS 1.0, 1.1, and 1.2, and 4941 legacy_version is TLS 1.0, the server will proceed with a TLS 1.0 4942 ServerHello. If the server only supports versions greater than 4943 ClientHello.legacy_version, it MUST abort the handshake with a 4944 "protocol_version" alert. 4946 Note that earlier versions of TLS did not clearly specify the record 4947 layer version number value in all cases 4948 (TLSPlaintext.legacy_record_version). Servers will receive various 4949 TLS 1.x versions in this field, however its value MUST always be 4950 ignored. 4952 C.3. Zero-RTT backwards compatibility 4954 0-RTT data is not compatible with older servers. An older server 4955 will respond to the ClientHello with an older ServerHello, but it 4956 will not correctly skip the 0-RTT data and fail to complete the 4957 handshake. This can cause issues when a client attempts to use 4958 0-RTT, particularly against multi-server deployments. For example, a 4959 deployment could deploy TLS 1.3 gradually with some servers 4960 implementing TLS 1.3 and some implementing TLS 1.2, or a TLS 1.3 4961 deployment could be downgraded to TLS 1.2. 4963 A client that attempts to send 0-RTT data MUST fail a connection if 4964 it receives a ServerHello with TLS 1.2 or older. A client that 4965 attempts to repair this error SHOULD NOT send a TLS 1.2 ClientHello, 4966 but instead send a TLS 1.3 ClientHello without 0-RTT data. 4968 To avoid this error condition, multi-server deployments SHOULD ensure 4969 a uniform and stable deployment of TLS 1.3 without 0-RTT prior to 4970 enabling 0-RTT. 4972 C.4. Backwards Compatibility Security Restrictions 4974 If an implementation negotiates use of TLS 1.2, then negotiation of 4975 cipher suites also supported by TLS 1.3 SHOULD be preferred, if 4976 available. 4978 The security of RC4 cipher suites is considered insufficient for the 4979 reasons cited in [RFC7465]. Implementations MUST NOT offer or 4980 negotiate RC4 cipher suites for any version of TLS for any reason. 4982 Old versions of TLS permitted the use of very low strength ciphers. 4983 Ciphers with a strength less than 112 bits MUST NOT be offered or 4984 negotiated for any version of TLS for any reason. 4986 The security of SSL 2.0 [SSL2] is considered insufficient for the 4987 reasons enumerated in [RFC6176], and MUST NOT be negotiated for any 4988 reason. 4990 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 4991 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 4992 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 4993 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 4994 order to negotiate older versions of TLS. 4996 Implementations MUST NOT send or accept any records with a version 4997 less than { 3, 0 }. 4999 The security of SSL 3.0 [SSL3] is considered insufficient for the 5000 reasons enumerated in [RFC7568], and MUST NOT be negotiated for any 5001 reason. 5003 Implementations MUST NOT send a ClientHello.legacy_version or 5004 ServerHello.version set to { 3, 0 } or less. Any endpoint receiving 5005 a Hello message with ClientHello.legacy_version or 5006 ServerHello.version set to { 3, 0 } MUST abort the handshake with a 5007 "protocol_version" alert. 5009 Implementations MUST NOT use the Truncated HMAC extension, defined in 5010 Section 7 of [RFC6066], as it is not applicable to AEAD algorithms 5011 and has been shown to be insecure in some scenarios. 5013 Appendix D. Overview of Security Properties 5015 [[TODO: This section is still a WIP and needs a bunch more work.]] 5017 A complete security analysis of TLS is outside the scope of this 5018 document. In this section, we provide an informal description the 5019 desired properties as well as references to more detailed work in the 5020 research literature which provides more formal definitions. 5022 We cover properties of the handshake separately from those of the 5023 record layer. 5025 D.1. Handshake 5027 The TLS handshake is an Authenticated Key Exchange (AKE) protocol 5028 which is intended to provide both one-way authenticated (server-only) 5029 and mutually authenticated (client and server) functionality. At the 5030 completion of the handshake, each side outputs its view on the 5031 following values: 5033 - A "session key" (the master secret) from which can be derived a 5034 set of working keys. 5036 - A set of cryptographic parameters (algorithms, etc.) 5038 - The identities of the communicating parties. 5040 We assume that the attacker has complete control of the network in 5041 between the parties [RFC3552]. Even under these conditions, the 5042 handshake should provide the properties listed below. Note that 5043 these properties are not necessarily independent, but reflect the 5044 protocol consumers' needs. 5046 Establishing the same session key. The handshake needs to output the 5047 same session key on both sides of the handshake, provided that it 5048 completes successfully on each endpoint (See [CK01]; defn 1, part 5049 1). 5051 Secrecy of the session key. The shared session key should be known 5052 only to the communicating parties, not to the attacker (See 5053 [CK01]; defn 1, part 2). Note that in a unilaterally 5054 authenticated connection, the attacker can establish its own 5055 session keys with the server, but those session keys are distinct 5056 from those established by the client. 5058 Peer Authentication. The client's view of the peer identity should 5059 reflect the server's identity. If the client is authenticated, 5060 the server's view of the peer identity should match the client's 5061 identity. 5063 Uniqueness of the session key: Any two distinct handshakes should 5064 produce distinct, unrelated session keys 5066 Downgrade protection. The cryptographic parameters should be the 5067 same on both sides and should be the same as if the peers had been 5068 communicating in the absence of an attack (See [BBFKZG16]; defns 8 5069 and 9}). 5071 Forward secret If the long-term keying material (in this case the 5072 signature keys in certificate-based authentication modes or the 5073 PSK in PSK-(EC)DHE modes) are compromised after the handshake is 5074 complete, this does not compromise the security of the session key 5075 (See [DOW92]). 5077 Protection of endpoint identities. The server's identity 5078 (certificate) should be protected against passive attackers. The 5079 client's identity should be protected against both passive and 5080 active attackers. 5082 Informally, the signature-based modes of TLS 1.3 provide for the 5083 establishment of a unique, secret, shared, key established by an 5084 (EC)DHE key exchange and authenticated by the server's signature over 5085 the handshake transcript, as well as tied to the server's identity by 5086 a MAC. If the client is authenticated by a certificate, it also 5087 signs over the handshake transcript and provides a MAC tied to both 5088 identities. [SIGMA] describes the analysis of this type of key 5089 exchange protocol. If fresh (EC)DHE keys are used for each 5090 connection, then the output keys are forward secret. 5092 The PSK and resumption-PSK modes bootstrap from a long-term shared 5093 secret into a unique per-connection short-term session key. This 5094 secret may have been established in a previous handshake. If 5095 PSK-(EC)DHE modes are used, this session key will also be forward 5096 secret. The resumption-PSK mode has been designed so that the 5097 resumption master secret computed by connection N and needed to form 5098 connection N+1 is separate from the traffic keys used by connection 5099 N, thus providing forward secrecy between the connections. 5101 If an exporter is used, then it produces values which are unique and 5102 secret (because they are generated from a unique session key). 5103 Exporters computed with different labels and contexts are 5104 computationally independent, so it is not feasible to compute one 5105 from another or the session secret from the exported value. Note: 5106 exporters can produce arbitrary-length values. If exporters are to 5107 be used as channel bindings, the exported value MUST be large enough 5108 to provide collision resistance. 5110 For all handshake modes, the Finished MAC (and where present, the 5111 signature), prevents downgrade attacks. In addition, the use of 5112 certain bytes in the random nonces as described in Section 4.1.3 5113 allows the detection of downgrade to previous TLS versions. 5115 As soon as the client and the server have exchanged enough 5116 information to establish shared keys, the remainder of the handshake 5117 is encrypted, thus providing protection against passive attackers. 5118 Because the server authenticates before the client, the client can 5119 ensure that it only reveals its identity to an authenticated server. 5120 Note that implementations must use the provided record padding 5121 mechanism during the handshake to avoid leaking information about the 5122 identities due to length. 5124 The 0-RTT mode of operation generally provides the same security 5125 properties as 1-RTT data, with the two exceptions that the 0-RTT 5126 encryption keys do not provide full forward secrecy and that the the 5127 server is not able to guarantee full uniqueness of the handshake 5128 (non-replayability) without keeping potentially undue amounts of 5129 state. See Section 4.2.7 for one mechanism to limit the exposure to 5130 replay. 5132 The reader should refer to the following references for analysis of 5133 the TLS handshake [CHSV16] [FGSW16] [LXZFH16]. 5135 D.2. Record Layer 5137 The record layer depends on the handshake producing a strong session 5138 key which can be used to derive bidirectional traffic keys and 5139 nonces. Assuming that is true, and the keys are used for no more 5140 data than indicated in Section 5.5 then the record layer should 5141 provide the following guarantees: 5143 Confidentiality. An attacker should not be able to determine the 5144 plaintext contents of a given record. 5146 Integrity. An attacker should not be able to craft a new record 5147 which is different from an existing record which will be accepted 5148 by the receiver. 5150 Order protection/non-replayability An attacker should not be able to 5151 cause the receiver to accept a record which it has already 5152 accepted or cause the receiver to accept record N+1 without having 5153 first processed record N. [[TODO: If we merge in DTLS to this 5154 document, we will need to update this guarantee.]] 5156 Length concealment. Given a record with a given external length, the 5157 attacker should not be able to determine the amount of the record 5158 that is content versus padding. 5160 Forward security after key change. If the traffic key update 5161 mechanism described in Section 4.5.3 has been used and the 5162 previous generation key is deleted, an attacker who compromises 5163 the endpoint should not be able to decrypt traffic encrypted with 5164 the old key. 5166 Informally, TLS 1.3 provides these properties by AEAD-protecting the 5167 plaintext with a strong key. AEAD encryption [RFC5116] provides 5168 confidentiality and integrity for the data. Non-replayability is 5169 provided by using a separate nonce for each record, with the nonce 5170 being derived from the record sequence number (Section 5.3), with the 5171 sequence number being maintained independently at both sides thus 5172 records which are delivered out of order result in AEAD deprotection 5173 failures. 5175 The plaintext protected by the AEAD function consists of content plus 5176 variable-length padding. Because the padding is also encrypted, the 5177 attacker cannot directly determine the length of the padding, but may 5178 be able to measure it indirectly by the use of timing channels 5179 exposed during record processing (i.e., seeing how long it takes to 5180 process a record). In general, it is not known how to remove this 5181 type of channel because even a constant time padding removal function 5182 will then feed the content into data-dependent functions. 5184 Generation N+1 keys are derived from generation N keys via a key 5185 derivation function Section 7.2. As long as this function is truly 5186 one way, it is not possible to compute the previous keys after a key 5187 change (forward secrecy). However, TLS does not provide security for 5188 data which is sent after the traffic secret is compromised, even afer 5189 a key update (backward secrecy); systems which want backward secrecy 5190 must do a fresh handshake and establish a new session key with an 5191 (EC)DHE exchange. 5193 The reader should refer to the following references for analysis of 5194 the TLS record layer. 5196 Appendix E. Working Group Information 5198 The discussion list for the IETF TLS working group is located at the 5199 e-mail address tls@ietf.org [1]. Information on the group and 5200 information on how to subscribe to the list is at 5201 https://www.ietf.org/mailman/listinfo/tls 5202 Archives of the list can be found at: https://www.ietf.org/mail- 5203 archive/web/tls/current/index.html 5205 Appendix F. Contributors 5207 - Martin Abadi 5208 University of California, Santa Cruz 5209 abadi@cs.ucsc.edu 5211 - Christopher Allen (co-editor of TLS 1.0) 5212 Alacrity Ventures 5213 ChristopherA@AlacrityManagement.com 5215 - Steven M. Bellovin 5216 Columbia University 5217 smb@cs.columbia.edu 5219 - David Benjamin 5220 Google 5221 davidben@google.com 5223 - Benjamin Beurdouche 5225 - Karthikeyan Bhargavan (co-author of [RFC7627]) 5226 INRIA 5227 karthikeyan.bhargavan@inria.fr 5229 - Simon Blake-Wilson (co-author of [RFC4492]) 5230 BCI 5231 sblakewilson@bcisse.com 5233 - Nelson Bolyard (co-author of [RFC4492]) 5234 Sun Microsystems, Inc. 5235 nelson@bolyard.com 5237 - Ran Canetti 5238 IBM 5239 canetti@watson.ibm.com 5241 - Pete Chown 5242 Skygate Technology Ltd 5243 pc@skygate.co.uk 5245 - Antoine Delignat-Lavaud (co-author of [RFC7627]) 5246 INRIA 5247 antoine.delignat-lavaud@inria.fr 5249 - Tim Dierks (co-editor of TLS 1.0, 1.1, and 1.2) 5250 Independent 5251 tim@dierks.org 5253 - Taher Elgamal 5254 Securify 5255 taher@securify.com 5257 - Pasi Eronen 5258 Nokia 5259 pasi.eronen@nokia.com 5261 - Cedric Fournet 5262 Microsoft 5263 fournet@microsoft.com 5265 - Anil Gangolli 5266 anil@busybuddha.org 5268 - David M. Garrett 5270 - Vipul Gupta (co-author of [RFC4492]) 5271 Sun Microsystems Laboratories 5272 vipul.gupta@sun.com 5274 - Chris Hawk (co-author of [RFC4492]) 5275 Corriente Networks LLC 5276 chris@corriente.net 5278 - Kipp Hickman 5280 - Alfred Hoenes 5282 - David Hopwood 5283 Independent Consultant 5284 david.hopwood@blueyonder.co.uk 5286 - Subodh Iyengar 5287 Facebook 5288 subodh@fb.com 5290 - Daniel Kahn Gillmor 5291 ACLU 5292 dkg@fifthhorseman.net 5294 - Hubert Kario 5295 Red Hat Inc. 5296 hkario@redhat.com 5298 - Phil Karlton (co-author of SSL 3.0) 5300 - Paul Kocher (co-author of SSL 3.0) 5301 Cryptography Research 5302 paul@cryptography.com 5304 - Hugo Krawczyk 5305 IBM 5306 hugo@ee.technion.ac.il 5308 - Adam Langley (co-author of [RFC7627]) 5309 Google 5310 agl@google.com 5312 - Xiaoyin Liu 5313 University of North Carolina at Chapel Hill 5314 xiaoyin.l@outlook.com 5316 - Ilari Liusvaara 5317 Independent 5318 ilariliusvaara@welho.com 5320 - Jan Mikkelsen 5321 Transactionware 5322 janm@transactionware.com 5324 - Bodo Moeller (co-author of [RFC4492]) 5325 Google 5326 bodo@openssl.org 5328 - Erik Nygren 5329 Akamai Technologies 5330 erik+ietf@nygren.org 5332 - Magnus Nystrom 5333 Microsoft 5334 mnystrom@microsoft.com 5336 - Alfredo Pironti (co-author of [RFC7627]) 5337 INRIA 5338 alfredo.pironti@inria.fr 5340 - Andrei Popov 5341 Microsoft 5342 andrei.popov@microsoft.com 5344 - Marsh Ray (co-author of [RFC7627]) 5345 Microsoft 5346 maray@microsoft.com 5348 - Robert Relyea 5349 Netscape Communications 5350 relyea@netscape.com 5352 - Kyle Rose 5353 Akamai Technologies 5354 krose@krose.org 5356 - Jim Roskind 5357 Netscape Communications 5358 jar@netscape.com 5360 - Michael Sabin 5362 - Dan Simon 5363 Microsoft, Inc. 5364 dansimon@microsoft.com 5366 - Nick Sullivan 5367 CloudFlare Inc. 5368 nick@cloudflare.com 5370 - Bjoern Tackmann 5371 University of California, San Diego 5372 btackmann@eng.ucsd.edu 5374 - Martin Thomson 5375 Mozilla 5376 mt@mozilla.com 5378 - Filippo Valsorda 5379 CloudFlare Inc. 5380 filippo@cloudflare.com 5382 - Tom Weinstein 5384 - Hoeteck Wee 5385 Ecole Normale Superieure, Paris 5386 hoeteck@alum.mit.edu 5388 - Tim Wright 5389 Vodafone 5390 timothy.wright@vodafone.com 5392 - Kazu Yamamoto 5393 Internet Initiative Japan Inc. 5395 kazu@iij.ad.jp 5397 Author's Address 5399 Eric Rescorla 5400 RTFM, Inc. 5402 EMail: ekr@rtfm.com