idnits 2.17.1 draft-ietf-tls-tls13-15.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 20 instances of too long lines in the document, the longest one being 6 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 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 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 (August 17, 2016) is 2809 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 726, but not defined -- Looks like a reference, but probably isn't: '0' on line 845 -- Looks like a reference, but probably isn't: '1' on line 4959 -- Looks like a reference, but probably isn't: '3' on line 916 -- Looks like a reference, but probably isn't: '9' on line 881 -- Looks like a reference, but probably isn't: '2' on line 4209 -- Looks like a reference, but probably isn't: '4' on line 917 -- Looks like a reference, but probably isn't: '8' on line 918 -- Looks like a reference, but probably isn't: '10' on line 1028 -- Looks like a reference, but probably isn't: '32' on line 4207 == Missing Reference: 'RFC7507' is mentioned on line 3174, but not defined ** Obsolete undefined reference: RFC 7507 (Obsoleted by RFC 8996) == Missing Reference: 'This RFC' is mentioned on line 4471, but not defined == Unused Reference: 'AES' is defined on line 3664, but no explicit reference was found in the text == Unused Reference: 'I-D.mattsson-tls-ecdhe-psk-aead' is defined on line 3677, but no explicit reference was found in the text == Unused Reference: 'RFC5288' is defined on line 3709, but no explicit reference was found in the text == Unused Reference: 'RFC5289' is defined on line 3714, but no explicit reference was found in the text == Unused Reference: 'RFC5487' is defined on line 3719, but no explicit reference was found in the text == Unused Reference: 'RFC6209' is defined on line 3738, but no explicit reference was found in the text == Unused Reference: 'RFC6367' is defined on line 3743, but no explicit reference was found in the text == Unused Reference: 'RFC6655' is defined on line 3748, but no explicit reference was found in the text == Unused Reference: 'RFC7251' is defined on line 3763, but no explicit reference was found in the text == Unused Reference: 'RFC7905' is defined on line 3778, but no explicit reference was found in the text == Unused Reference: 'GCM' is defined on line 3843, but no explicit reference was found in the text == Unused Reference: 'PKCS6' is defined on line 3861, but no explicit reference was found in the text == Unused Reference: 'PKCS7' is defined on line 3864, but no explicit reference was found in the text == Unused Reference: 'RFC0793' is defined on line 3873, but no explicit reference was found in the text == Unused Reference: 'RFC1948' is defined on line 3877, but no explicit reference was found in the text == Unused Reference: 'RFC4302' is defined on line 3896, but no explicit reference was found in the text == Unused Reference: 'RFC4303' is defined on line 3900, but no explicit reference was found in the text == Unused Reference: 'RFC5763' is defined on line 3962, 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' == Outdated reference: A later version (-08) exists of draft-irtf-cfrg-eddsa-06 ** 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 ** 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' -- 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: 14 errors (**), 0 flaws (~~), 25 warnings (==), 35 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 August 17, 2016 5 approved) 6 Updates: 4492, 6066, 6961 (if approved) 7 Intended status: Standards Track 8 Expires: February 18, 2017 10 The Transport Layer Security (TLS) Protocol Version 1.3 11 draft-ietf-tls-tls13-15 13 Abstract 15 This document specifies version 1.3 of the Transport Layer Security 16 (TLS) protocol. TLS allows client/server applications to communicate 17 over the Internet in a way that is designed to prevent eavesdropping, 18 tampering, and message forgery. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on February 18, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 This document may contain material from IETF Documents or IETF 53 Contributions published or made publicly available before November 54 10, 2008. The person(s) controlling the copyright in some of this 55 material may not have granted the IETF Trust the right to allow 56 modifications of such material outside the IETF Standards Process. 57 Without obtaining an adequate license from the person(s) controlling 58 the copyright in such materials, this document may not be modified 59 outside the IETF Standards Process, and derivative works of it may 60 not be created outside the IETF Standards Process, except to format 61 it for publication as an RFC or to translate it into languages other 62 than English. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 67 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 5 68 1.2. Major Differences from TLS 1.2 . . . . . . . . . . . . . 6 69 1.3. Updates Affecting TLS 1.2 . . . . . . . . . . . . . . . . 11 70 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 11 71 2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . . . 14 72 2.2. Resumption and Pre-Shared Key (PSK) . . . . . . . . . . . 15 73 2.3. Zero-RTT Data . . . . . . . . . . . . . . . . . . . . . . 17 74 3. Presentation Language . . . . . . . . . . . . . . . . . . . . 18 75 3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 18 76 3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 19 77 3.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 19 78 3.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 20 79 3.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 20 80 3.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 21 81 3.6.1. Variants . . . . . . . . . . . . . . . . . . . . . . 21 82 3.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 23 83 4. Handshake Protocol . . . . . . . . . . . . . . . . . . . . . 23 84 4.1. Key Exchange Messages . . . . . . . . . . . . . . . . . . 24 85 4.1.1. Cryptographic Negotiation . . . . . . . . . . . . . . 25 86 4.1.2. Client Hello . . . . . . . . . . . . . . . . . . . . 26 87 4.1.3. Server Hello . . . . . . . . . . . . . . . . . . . . 28 88 4.1.4. Hello Retry Request . . . . . . . . . . . . . . . . . 29 89 4.2. Hello Extensions . . . . . . . . . . . . . . . . . . . . 31 90 4.2.1. Cookie . . . . . . . . . . . . . . . . . . . . . . . 32 91 4.2.2. Signature Algorithms . . . . . . . . . . . . . . . . 33 92 4.2.3. Negotiated Groups . . . . . . . . . . . . . . . . . . 36 93 4.2.4. Key Share . . . . . . . . . . . . . . . . . . . . . . 37 94 4.2.5. Pre-Shared Key Extension . . . . . . . . . . . . . . 39 95 4.2.6. Early Data Indication . . . . . . . . . . . . . . . . 41 96 4.2.7. OCSP Status Extensions . . . . . . . . . . . . . . . 44 97 4.2.8. Encrypted Extensions . . . . . . . . . . . . . . . . 45 98 4.2.9. Certificate Request . . . . . . . . . . . . . . . . . 45 99 4.3. Authentication Messages . . . . . . . . . . . . . . . . . 47 100 4.3.1. Certificate . . . . . . . . . . . . . . . . . . . . . 49 101 4.3.2. Certificate Verify . . . . . . . . . . . . . . . . . 52 102 4.3.3. Finished . . . . . . . . . . . . . . . . . . . . . . 54 103 4.4. Post-Handshake Messages . . . . . . . . . . . . . . . . . 55 104 4.4.1. New Session Ticket Message . . . . . . . . . . . . . 56 105 4.4.2. Post-Handshake Authentication . . . . . . . . . . . . 57 106 4.4.3. Key and IV Update . . . . . . . . . . . . . . . . . . 58 107 4.5. Handshake Layer and Key Changes . . . . . . . . . . . . . 59 108 5. Record Protocol . . . . . . . . . . . . . . . . . . . . . . . 59 109 5.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 59 110 5.2. Record Payload Protection . . . . . . . . . . . . . . . . 61 111 5.3. Per-Record Nonce . . . . . . . . . . . . . . . . . . . . 63 112 5.4. Record Padding . . . . . . . . . . . . . . . . . . . . . 63 113 5.5. Limits on Key Usage . . . . . . . . . . . . . . . . . . . 64 114 6. Alert Protocol . . . . . . . . . . . . . . . . . . . . . . . 65 115 6.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 66 116 6.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 67 117 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 70 118 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 70 119 7.2. Updating Traffic Keys and IVs . . . . . . . . . . . . . . 73 120 7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 73 121 7.3.1. Diffie-Hellman . . . . . . . . . . . . . . . . . . . 74 122 7.3.2. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 75 123 7.3.3. Exporters . . . . . . . . . . . . . . . . . . . . . . 75 124 8. Compliance Requirements . . . . . . . . . . . . . . . . . . . 75 125 8.1. MTI Cipher Suites . . . . . . . . . . . . . . . . . . . . 76 126 8.2. MTI Extensions . . . . . . . . . . . . . . . . . . . . . 76 127 9. Security Considerations . . . . . . . . . . . . . . . . . . . 77 128 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 129 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 80 130 11.1. Normative References . . . . . . . . . . . . . . . . . . 80 131 11.2. Informative References . . . . . . . . . . . . . . . . . 83 132 Appendix A. Protocol Data Structures and Constant Values . . . . 90 133 A.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 90 134 A.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 90 135 A.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 92 136 A.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 92 137 A.3.2. Server Parameters Messages . . . . . . . . . . . . . 96 138 A.3.3. Authentication Messages . . . . . . . . . . . . . . . 97 139 A.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 97 140 A.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 98 141 A.4.1. Unauthenticated Operation . . . . . . . . . . . . . . 99 142 Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 100 143 B.1. API considerations for 0-RTT . . . . . . . . . . . . . . 100 144 B.2. Random Number Generation and Seeding . . . . . . . . . . 100 145 B.3. Certificates and Authentication . . . . . . . . . . . . . 100 146 B.4. Cipher Suite Support . . . . . . . . . . . . . . . . . . 100 147 B.5. Implementation Pitfalls . . . . . . . . . . . . . . . . . 101 148 B.6. Client Tracking Prevention . . . . . . . . . . . . . . . 102 149 Appendix C. Backward Compatibility . . . . . . . . . . . . . . . 102 150 C.1. Negotiating with an older server . . . . . . . . . . . . 103 151 C.2. Negotiating with an older client . . . . . . . . . . . . 104 152 C.3. Zero-RTT backwards compatibility . . . . . . . . . . . . 104 153 C.4. Backwards Compatibility Security Restrictions . . . . . . 105 154 Appendix D. Overview of Security Properties . . . . . . . . . . 106 155 D.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 106 156 D.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 108 157 Appendix E. Working Group Information . . . . . . . . . . . . . 109 158 Appendix F. Contributors . . . . . . . . . . . . . . . . . . . . 109 159 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 113 161 1. Introduction 163 DISCLAIMER: This is a WIP draft of TLS 1.3 and has not yet seen 164 significant security analysis. 166 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 167 draft is maintained in GitHub. Suggested changes should be submitted 168 as pull requests at https://github.com/tlswg/tls13-spec. 169 Instructions are on that page as well. Editorial changes can be 170 managed in GitHub, but any substantive change should be discussed on 171 the TLS mailing list. 173 The primary goal of TLS is to provide a secure channel between two 174 communicating peers. Specifically, the channel should provide the 175 following properties. 177 - Authentication: The server side of the channel is always 178 authenticated; the client side is optionally authenticated. 179 Authentication can happen via asymmetric cryptography (e.g., RSA 180 [RSA], ECDSA [ECDSA]) or a pre-shared symmetric key. 182 - Confidentiality: Data sent over the channel is not visible to 183 attackers. 185 - Integrity: Data sent over the channel cannot be modified by 186 attackers. 188 These properties should be true even in the face of an attacker who 189 has complete control of the network, as described in [RFC3552]. See 190 Appendix D for a more complete statement of the relevant security 191 properties. 193 TLS consists of two primary components: 195 - A handshake protocol (Section 4) which authenticates the 196 communicating parties, negotiates cryptographic modes and 197 parameters, and establishes shared keying material. The handshake 198 protocol is designed to resist tampering; an active attacker 199 should not be able to force the peers to negotiate different 200 parameters than they would if the connection were not under 201 attack. 203 - A record protocol (Section 5) which uses the parameters 204 established by the handshake protocol to protect traffic between 205 the communicating peers. The record protocol divides traffic up 206 into a series of records, each of which is independently protected 207 using the traffic keys. 209 TLS is application protocol independent; higher-level protocols can 210 layer on top of TLS transparently. The TLS standard, however, does 211 not specify how protocols add security with TLS; the decisions on how 212 to initiate TLS handshaking and how to interpret the authentication 213 certificates exchanged are left to the judgment of the designers and 214 implementors of protocols that run on top of TLS. 216 This document defines TLS version 1.3. While TLS 1.3 is not directly 217 compatible with previous versions, all versions of TLS incorporate a 218 versioning mechanism which allows clients and servers to 219 interoperably negotiate a common version if one is supported. 221 1.1. Conventions and Terminology 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 225 "OPTIONAL" in this document are to be interpreted as described in RFC 226 2119 [RFC2119]. 228 The following terms are used: 230 client: The endpoint initiating the TLS connection. 232 connection: A transport-layer connection between two endpoints. 234 endpoint: Either the client or server of the connection. 236 handshake: An initial negotiation between client and server that 237 establishes the parameters of their transactions. 239 peer: An endpoint. When discussing a particular endpoint, "peer" 240 refers to the endpoint that is remote to the primary subject of 241 discussion. 243 receiver: An endpoint that is receiving records. 245 sender: An endpoint that is transmitting records. 247 session: An association between a client and a server resulting from 248 a handshake. 250 server: The endpoint which did not initiate the TLS connection. 252 1.2. Major Differences from TLS 1.2 254 (*) indicates changes to the wire protocol which may require 255 implementations to update. 257 draft-15 259 - New negotiation syntax as discussed in Berlin (*) 261 - Require CertificateRequest.context to be empty during handshake 262 (*) 264 - Forbid empty tickets (*) 266 - Forbid application data messages in between post-handshake 267 messages from the same flight (*) 269 - Clean up alert guidance (*) 271 - Clearer guidance on what is needed for TLS 1.2. 273 - Guidance on 0-RTT time windows. 275 - Rename a bunch of fields. 277 - Remove old PRNG text. 279 - Explicitly require checking that handshake records not span key 280 changes. 282 draft-14 284 - Allow cookies to be longer (*) 285 - Remove the "context" from EarlyDataIndication as it was undefined 286 and nobody used it (*) 288 - Remove 0-RTT EncryptedExtensions and replace the ticket_age 289 extension with an obfuscated version. Also necessitates a change 290 to NewSessionTicket (*). 292 - Move the downgrade sentinel to the end of ServerHello.Random to 293 accomodate tlsdate (*). 295 - Define ecdsa_sha1 (*). 297 - Allow resumption even after fatal alerts. This matches current 298 practice. 300 - Remove non-closure warning alerts. Require treating unknown 301 alerts as fatal. 303 - Make the rules for accepting 0-RTT less restrictive. 305 - Clarify 0-RTT backward-compatibility rules. 307 - Clarify how 0-RTT and PSK identities interact. 309 - Add a section describing the data limits for each cipher. 311 - Major editorial restructuring. 313 - Replace the Security Analysis section with a WIP draft. 315 draft-13 317 - Allow server to send SupportedGroups. 319 - Remove 0-RTT client authentication 321 - Remove (EC)DHE 0-RTT. 323 - Flesh out 0-RTT PSK mode and shrink EarlyDataIndication 325 - Turn PSK-resumption response into an index to save room 327 - Move CertificateStatus to an extension 329 - Extra fields in NewSessionTicket. 331 - Restructure key schedule and add a resumption_context value. 333 - Require DH public keys and secrets to be zero-padded to the size 334 of the group. 336 - Remove the redundant length fields in KeyShareEntry. 338 - Define a cookie field for HRR. 340 draft-12 342 - Provide a list of the PSK cipher suites. 344 - Remove the ability for the ServerHello to have no extensions (this 345 aligns the syntax with the text). 347 - Clarify that the server can send application data after its first 348 flight (0.5 RTT data) 350 - Revise signature algorithm negotiation to group hash, signature 351 algorithm, and curve together. This is backwards compatible. 353 - Make ticket lifetime mandatory and limit it to a week. 355 - Make the purpose strings lower-case. This matches how people are 356 implementing for interop. 358 - Define exporters. 360 - Editorial cleanup 362 draft-11 364 - Port the CFRG curves & signatures work from RFC4492bis. 366 - Remove sequence number and version from additional_data, which is 367 now empty. 369 - Reorder values in HkdfLabel. 371 - Add support for version anti-downgrade mechanism. 373 - Update IANA considerations section and relax some of the policies. 375 - Unify authentication modes. Add post-handshake client 376 authentication. 378 - Remove early_handshake content type. Terminate 0-RTT data with an 379 alert. 381 - Reset sequence number upon key change (as proposed by Fournet et 382 al.) 384 draft-10 386 - Remove ClientCertificateTypes field from CertificateRequest and 387 add extensions. 389 - Merge client and server key shares into a single extension. 391 draft-09 393 - Change to RSA-PSS signatures for handshake messages. 395 - Remove support for DSA. 397 - Update key schedule per suggestions by Hugo, Hoeteck, and Bjoern 398 Tackmann. 400 - Add support for per-record padding. 402 - Switch to encrypted record ContentType. 404 - Change HKDF labeling to include protocol version and value 405 lengths. 407 - Shift the final decision to abort a handshake due to incompatible 408 certificates to the client rather than having servers abort early. 410 - Deprecate SHA-1 with signatures. 412 - Add MTI algorithms. 414 draft-08 416 - Remove support for weak and lesser used named curves. 418 - Remove support for MD5 and SHA-224 hashes with signatures. 420 - Update lists of available AEAD cipher suites and error alerts. 422 - Reduce maximum permitted record expansion for AEAD from 2048 to 423 256 octets. 425 - Require digital signatures even when a previous configuration is 426 used. 428 - Merge EarlyDataIndication and KnownConfiguration. 430 - Change code point for server_configuration to avoid collision with 431 server_hello_done. 433 - Relax certificate_list ordering requirement to match current 434 practice. 436 draft-07 438 - Integration of semi-ephemeral DH proposal. 440 - Add initial 0-RTT support. 442 - Remove resumption and replace with PSK + tickets. 444 - Move ClientKeyShare into an extension. 446 - Move to HKDF. 448 draft-06 450 - Prohibit RC4 negotiation for backwards compatibility. 452 - Freeze & deprecate record layer version field. 454 - Update format of signatures with context. 456 - Remove explicit IV. 458 draft-05 460 - Prohibit SSL negotiation for backwards compatibility. 462 - Fix which MS is used for exporters. 464 draft-04 466 - Modify key computations to include session hash. 468 - Remove ChangeCipherSpec. 470 - Renumber the new handshake messages to be somewhat more consistent 471 with existing convention and to remove a duplicate registration. 473 - Remove renegotiation. 475 - Remove point format negotiation. 477 draft-03 478 - Remove GMT time. 480 - Merge in support for ECC from RFC 4492 but without explicit 481 curves. 483 - Remove the unnecessary length field from the AD input to AEAD 484 ciphers. 486 - Rename {Client,Server}KeyExchange to {Client,Server}KeyShare. 488 - Add an explicit HelloRetryRequest to reject the client's. 490 draft-02 492 - Increment version number. 494 - Rework handshake to provide 1-RTT mode. 496 - Remove custom DHE groups. 498 - Remove support for compression. 500 - Remove support for static RSA and DH key exchange. 502 - Remove support for non-AEAD ciphers. 504 1.3. Updates Affecting TLS 1.2 506 This document defines several changes that optionally affect 507 implementations of TLS 1.2: 509 - A version downgrade protection mechanism is described in 510 Section 4.1.3. 512 - RSASSA-PSS signature schemes are defined in Section 4.2.2. 514 An implementation of TLS 1.3 that also supports TLS 1.2 might need to 515 include changes to support these changes even when TLS 1.3 is not in 516 use. See the referenced sections for more details. 518 2. Protocol Overview 520 The cryptographic parameters of the session state are produced by the 521 TLS handshake protocol. When a TLS client and server first start 522 communicating, they agree on a protocol version, select cryptographic 523 algorithms, optionally authenticate each other, and establish shared 524 secret keying material. Once the handshake is complete, the peers 525 use the established keys to protect application layer traffic. 527 TLS supports three basic key exchange modes: 529 - Diffie-Hellman (of both the finite field and elliptic curve 530 varieties). 532 - A pre-shared symmetric key (PSK) 534 - A combination of a symmetric key and Diffie-Hellman 536 Figure 1 below shows the basic full TLS handshake: 538 Client Server 540 Key ^ ClientHello 541 Exch | + key_share* 542 v + pre_shared_key* --------> 543 ServerHello ^ Key 544 + key_share* | Exch 545 + pre_shared_key* v 546 {EncryptedExtensions} ^ Server 547 {CertificateRequest*} v Params 548 {Certificate*} ^ 549 {CertificateVerify*} | Auth 550 {Finished} v 551 <-------- [Application Data*] 552 ^ {Certificate*} 553 Auth | {CertificateVerify*} 554 v {Finished} --------> 555 [Application Data] <-------> [Application Data] 557 + Indicates extensions sent in the 558 previously noted message. 560 * Indicates optional or situation-dependent 561 messages that are not always sent. 563 {} Indicates messages protected using keys 564 derived from handshake_traffic_secret. 566 [] Indicates messages protected using keys 567 derived from traffic_secret_N 569 Figure 1: Message flow for full TLS Handshake 571 The handshake can be thought of as having three phases, indicated in 572 the diagram above. 574 - Key Exchange: Establish shared keying material and select the 575 cryptographic parameters. Everything after this phase is 576 encrypted. 578 - Server Parameters: Establish other handshake parameters. (whether 579 the client is authenticated, application layer protocol support, 580 etc.) 582 - Authentication: Authenticate the server (and optionally the 583 client) and provide key confirmation and handshake integrity. 585 In the Key Exchange phase, the client sends the ClientHello 586 (Section 4.1.2) message, which contains a random nonce 587 (ClientHello.random), its offered protocol version, a list of 588 symmetric cipher/HKDF hash pairs, some set of Diffie-Hellman key 589 shares (in the "key_share" extension Section 4.2.4), one or more pre- 590 shared key labels (in the "pre_shared_key" extension Section 4.2.5), 591 or both, and potentially some other extensions. 593 The server processes the ClientHello and determines the appropriate 594 cryptographic parameters for the connection. It then responds with 595 its own ServerHello which indicates the negotiated connection 596 parameters. [Section 4.1.3]. The combination of the ClientHello and 597 the ServerHello determines the shared keys. If (EC)DHE key 598 establishment is in use, then the ServerHello will contain a 599 "key_share" extension with the server's ephemeral Diffie-Hellman 600 share which MUST be in the same group as one of the client's shares. 601 If PSK key establishment is in use, then the ServerHello will contain 602 a "pre_shared_key" extension indicating which of the client's offered 603 PSKs was selected. Note that implementations can use (EC)DHE and PSK 604 together, in which case both extensions will be supplied. 606 The server then sends two messages to establish the Server 607 Parameters: 609 EncryptedExtensions. responses to any extensions which are not 610 required in order to determine the cryptographic parameters. 611 [Section 4.2.8] 613 CertificateRequest. if certificate-based client authentication is 614 desired, the desired parameters for that certificate. This 615 message will be omitted if client authentication is not desired. 617 Finally, the client and server exchange Authentication messages. TLS 618 uses the same set of messages every time that authentication is 619 needed. Specifically: 621 Certificate. the certificate of the endpoint. This message is 622 omitted if the server is not authenticating with a certificate. 623 Note that if raw public keys [RFC7250] or the cached information 624 extension [RFC7924] are in use, then this message will not contain 625 a certificate but rather some other value corresponding to the 626 server's long-term key. [Section 4.3.1] 628 CertificateVerify. a signature over the entire handshake using the 629 public key in the Certificate message. This message is omitted if 630 the server is not authenticating via a certificate. 631 [Section 4.3.2] 633 Finished. a MAC (Message Authentication Code) over the entire 634 handshake. This message provides key confirmation, binds the 635 endpoint's identity to the exchanged keys, and in PSK mode also 636 authenticates the handshake. [Section 4.3.3] 638 Upon receiving the server's messages, the client responds with its 639 Authentication messages, namely Certificate and CertificateVerify (if 640 requested), and Finished. 642 At this point, the handshake is complete, and the client and server 643 may exchange application layer data. Application data MUST NOT be 644 sent prior to sending the Finished message. Note that while the 645 server may send application data prior to receiving the client's 646 Authentication messages, any data sent at that point is, of course, 647 being sent to an unauthenticated peer. 649 2.1. Incorrect DHE Share 651 If the client has not provided a sufficient "key_share" extension 652 (e.g. it includes only DHE or ECDHE groups unacceptable or 653 unsupported by the server), the server corrects the mismatch with a 654 HelloRetryRequest and the client will need to restart the handshake 655 with an appropriate "key_share" extension, as shown in Figure 2. If 656 no common cryptographic parameters can be negotiated, the server will 657 send a "handshake_failure" or "insufficient_security" fatal alert 658 (see Section 6). 660 Client Server 662 ClientHello 663 + key_share --------> 664 <-------- HelloRetryRequest 666 ClientHello 667 + key_share --------> 668 ServerHello 669 + key_share 670 {EncryptedExtensions} 671 {CertificateRequest*} 672 {Certificate*} 673 {CertificateVerify*} 674 {Finished} 675 <-------- [Application Data*] 676 {Certificate*} 677 {CertificateVerify*} 678 {Finished} --------> 679 [Application Data] <-------> [Application Data] 681 Figure 2: Message flow for a full handshake with mismatched 682 parameters 684 Note: The handshake transcript includes the initial ClientHello/ 685 HelloRetryRequest exchange; it is not reset with the new ClientHello. 687 TLS also allows several optimized variants of the basic handshake, as 688 described in the following sections. 690 2.2. Resumption and Pre-Shared Key (PSK) 692 Although TLS PSKs can be established out of band, PSKs can also be 693 established in a previous session and then reused ("session 694 resumption"). Once a handshake has completed, the server can send 695 the client a PSK identity which corresponds to a key derived from the 696 initial handshake (See Section 4.4.1). The client can then use that 697 PSK identity in future handshakes to negotiate use of the PSK. If 698 the server accepts it, then the security context of the new 699 connection is tied to the original connection. In TLS 1.2 and below, 700 this functionality was provided by "session IDs" and "session 701 tickets" [RFC5077]. Both mechanisms are obsoleted in TLS 1.3. 703 PSKs can be used with (EC)DHE exchange in order to provide forward 704 secrecy in combination with shared keys, or can be used alone, at the 705 cost of losing forward secrecy. 707 Figure 3 shows a pair of handshakes in which the first establishes a 708 PSK and the second uses it: 710 Client Server 712 Initial Handshake: 713 ClientHello 714 + key_share --------> 715 ServerHello 716 + key_share 717 {EncryptedExtensions} 718 {CertificateRequest*} 719 {Certificate*} 720 {CertificateVerify*} 721 {Finished} 722 <-------- [Application Data*] 723 {Certificate*} 724 {CertificateVerify*} 725 {Finished} --------> 726 <-------- [NewSessionTicket] 727 [Application Data] <-------> [Application Data] 729 Subsequent Handshake: 730 ClientHello 731 + pre_shared_key 732 + key_share* --------> 733 ServerHello 734 + pre_shared_key 735 + key_share* 736 {EncryptedExtensions} 737 {Finished} 738 <-------- [Application Data*] 739 {Finished} --------> 740 [Application Data] <-------> [Application Data] 742 Figure 3: Message flow for resumption and PSK 744 As the server is authenticating via a PSK, it does not send a 745 Certificate or a CertificateVerify. When a client offers resumption 746 via PSK it SHOULD also supply a "key_share" extension to the server 747 as well to allow the server to decline resumption and fall back to a 748 full handshake, if needed. The server responds with a 749 "pre_shared_key" extension to negotiate use of PSK key establishment 750 and can (as shown here) respond with a "key_share" extension to do 751 (EC)DHE key establishment, thus providing forward secrecy. 753 2.3. Zero-RTT Data 755 When resuming via a PSK with an appropriate ticket (i.e., one with 756 the "allow_early_data" flag), clients can also send data on their 757 first flight ("early data"). This data is encrypted solely under 758 keys derived using the first offered PSK as the static secret. As 759 shown in Figure 4, the Zero-RTT data is just added to the 1-RTT 760 handshake in the first flight. The rest of the handshake uses the 761 same messages. 763 Client Server 765 ClientHello 766 + early_data 767 + pre_shared_key 768 + key_share* 769 (Finished) 770 (Application Data*) 771 (end_of_early_data) --------> 772 ServerHello 773 + early_data 774 + pre_shared_key 775 + key_share* 776 {EncryptedExtensions} 777 {CertificateRequest*} 778 {Finished} 779 <-------- [Application Data*] 780 {Certificate*} 781 {CertificateVerify*} 782 {Finished} --------> 784 [Application Data] <-------> [Application Data] 786 * Indicates optional or situation-dependent 787 messages that are not always sent. 789 () Indicates messages protected using keys 790 derived from early_traffic_secret. 792 {} Indicates messages protected using keys 793 derived from handshake_traffic_secret. 795 [] Indicates messages protected using keys 796 derived from traffic_secret_N 798 Figure 4: Message flow for a zero round trip handshake 800 [[OPEN ISSUE: Should it be possible to combine 0-RTT with the server 801 authenticating via a signature https://github.com/tlswg/tls13-spec/ 802 issues/443]] 804 IMPORTANT NOTE: The security properties for 0-RTT data are weaker 805 than those for other kinds of TLS data. Specifically: 807 1. This data is not forward secret, because it is encrypted solely 808 with the PSK. 810 2. There are no guarantees of non-replay between connections. 811 Unless the server takes special measures outside those provided 812 by TLS, the server has no guarantee that the same 0-RTT data was 813 not transmitted on multiple 0-RTT connections (See 814 Section 4.2.6.2 for more details). This is especially relevant 815 if the data is authenticated either with TLS client 816 authentication or inside the application layer protocol. 817 However, 0-RTT data cannot be duplicated within a connection 818 (i.e., the server will not process the same data twice for the 819 same connection) and an attacker will not be able to make 0-RTT 820 data appear to be 1-RTT data (because it is protected with 821 different keys.) 823 The remainder of this document provides a detailed description of 824 TLS. 826 3. Presentation Language 828 This document deals with the formatting of data in an external 829 representation. The following very basic and somewhat casually 830 defined presentation syntax will be used. The syntax draws from 831 several sources in its structure. Although it resembles the 832 programming language "C" in its syntax and XDR [RFC4506] in both its 833 syntax and intent, it would be risky to draw too many parallels. The 834 purpose of this presentation language is to document TLS only; it has 835 no general application beyond that particular goal. 837 3.1. Basic Block Size 839 The representation of all data items is explicitly specified. The 840 basic data block size is one byte (i.e., 8 bits). Multiple byte data 841 items are concatenations of bytes, from left to right, from top to 842 bottom. From the byte stream, a multi-byte item (a numeric in the 843 example) is formed (using C notation) by: 845 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 846 ... | byte[n-1]; 848 This byte ordering for multi-byte values is the commonplace network 849 byte order or big-endian format. 851 3.2. Miscellaneous 853 Comments begin with "/*" and end with "*/". 855 Optional components are denoted by enclosing them in "[[ ]]" double 856 brackets. 858 Single-byte entities containing uninterpreted data are of type 859 opaque. 861 3.3. Vectors 863 A vector (single-dimensioned array) is a stream of homogeneous data 864 elements. The size of the vector may be specified at documentation 865 time or left unspecified until runtime. In either case, the length 866 declares the number of bytes, not the number of elements, in the 867 vector. The syntax for specifying a new type, T', that is a fixed- 868 length vector of type T is 870 T T'[n]; 872 Here, T' occupies n bytes in the data stream, where n is a multiple 873 of the size of T. The length of the vector is not included in the 874 encoded stream. 876 In the following example, Datum is defined to be three consecutive 877 bytes that the protocol does not interpret, while Data is three 878 consecutive Datum, consuming a total of nine bytes. 880 opaque Datum[3]; /* three uninterpreted bytes */ 881 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 883 Variable-length vectors are defined by specifying a subrange of legal 884 lengths, inclusively, using the notation . When 885 these are encoded, the actual length precedes the vector's contents 886 in the byte stream. The length will be in the form of a number 887 consuming as many bytes as required to hold the vector's specified 888 maximum (ceiling) length. A variable-length vector with an actual 889 length field of zero is referred to as an empty vector. 891 T T'; 893 In the following example, mandatory is a vector that must contain 894 between 300 and 400 bytes of type opaque. It can never be empty. 895 The actual length field consumes two bytes, a uint16, which is 896 sufficient to represent the value 400 (see Section 3.4). On the 897 other hand, longer can represent up to 800 bytes of data, or 400 898 uint16 elements, and it may be empty. Its encoding will include a 899 two-byte actual length field prepended to the vector. The length of 900 an encoded vector must be an even multiple of the length of a single 901 element (for example, a 17-byte vector of uint16 would be illegal). 903 opaque mandatory<300..400>; 904 /* length field is 2 bytes, cannot be empty */ 905 uint16 longer<0..800>; 906 /* zero to 400 16-bit unsigned integers */ 908 3.4. Numbers 910 The basic numeric data type is an unsigned byte (uint8). All larger 911 numeric data types are formed from fixed-length series of bytes 912 concatenated as described in Section 3.1 and are also unsigned. The 913 following numeric types are predefined. 915 uint8 uint16[2]; 916 uint8 uint24[3]; 917 uint8 uint32[4]; 918 uint8 uint64[8]; 920 All values, here and elsewhere in the specification, are stored in 921 network byte (big-endian) order; the uint32 represented by the hex 922 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 924 Note that in some cases (e.g., DH parameters) it is necessary to 925 represent integers as opaque vectors. In such cases, they are 926 represented as unsigned integers (i.e., additional leading zero 927 octets are not used even if the most significant bit is set). 929 3.5. Enumerateds 931 An additional sparse data type is available called enum. A field of 932 type enum can only assume the values declared in the definition. 933 Each definition is a different type. Only enumerateds of the same 934 type may be assigned or compared. Every element of an enumerated 935 must be assigned a value, as demonstrated in the following example. 936 Since the elements of the enumerated are not ordered, they can be 937 assigned any unique value, in any order. 939 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 941 An enumerated occupies as much space in the byte stream as would its 942 maximal defined ordinal value. The following definition would cause 943 one byte to be used to carry fields of type Color. 945 enum { red(3), blue(5), white(7) } Color; 947 One may optionally specify a value without its associated tag to 948 force the width definition without defining a superfluous element. 950 In the following example, Taste will consume two bytes in the data 951 stream but can only assume the values 1, 2, or 4. 953 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 955 The names of the elements of an enumeration are scoped within the 956 defined type. In the first example, a fully qualified reference to 957 the second element of the enumeration would be Color.blue. Such 958 qualification is not required if the target of the assignment is well 959 specified. 961 Color color = Color.blue; /* overspecified, legal */ 962 Color color = blue; /* correct, type implicit */ 964 For enumerateds that are never converted to external representation, 965 the numerical information may be omitted. 967 enum { low, medium, high } Amount; 969 3.6. Constructed Types 971 Structure types may be constructed from primitive types for 972 convenience. Each specification declares a new, unique type. The 973 syntax for definition is much like that of C. 975 struct { 976 T1 f1; 977 T2 f2; 978 ... 979 Tn fn; 980 } [[T]]; 982 The fields within a structure may be qualified using the type's name, 983 with a syntax much like that available for enumerateds. For example, 984 T.f2 refers to the second field of the previous declaration. 985 Structure definitions may be embedded. 987 3.6.1. Variants 989 Defined structures may have variants based on some knowledge that is 990 available within the environment. The selector must be an enumerated 991 type that defines the possible variants the structure defines. There 992 must be a case arm for every element of the enumeration declared in 993 the select. Case arms have limited fall-through: if two case arms 994 follow in immediate succession with no fields in between, then they 995 both contain the same fields. Thus, in the example below, "orange" 996 and "banana" both contain V2. Note that this is a new piece of 997 syntax in TLS 1.2. 999 The body of the variant structure may be given a label for reference. 1000 The mechanism by which the variant is selected at runtime is not 1001 prescribed by the presentation language. 1003 struct { 1004 T1 f1; 1005 T2 f2; 1006 .... 1007 Tn fn; 1008 select (E) { 1009 case e1: Te1; 1010 case e2: Te2; 1011 case e3: case e4: Te3; 1012 .... 1013 case en: Ten; 1014 } [[fv]]; 1015 } [[Tv]]; 1017 For example: 1019 enum { apple, orange, banana } VariantTag; 1021 struct { 1022 uint16 number; 1023 opaque string<0..10>; /* variable length */ 1024 } V1; 1026 struct { 1027 uint32 number; 1028 opaque string[10]; /* fixed length */ 1029 } V2; 1031 struct { 1032 select (VariantTag) { /* value of selector is implicit */ 1033 case apple: 1034 V1; /* VariantBody, tag = apple */ 1035 case orange: 1036 case banana: 1037 V2; /* VariantBody, tag = orange or banana */ 1038 } variant_body; /* optional label on variant */ 1039 } VariantRecord; 1041 3.7. Constants 1043 Typed constants can be defined for purposes of specification by 1044 declaring a symbol of the desired type and assigning values to it. 1046 Under-specified types (opaque, variable-length vectors, and 1047 structures that contain opaque) cannot be assigned values. No fields 1048 of a multi-element structure or vector may be elided. 1050 For example: 1052 struct { 1053 uint8 f1; 1054 uint8 f2; 1055 } Example1; 1057 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 1059 4. Handshake Protocol 1061 The handshake protocol is used to negotiate the secure attributes of 1062 a session. Handshake messages are supplied to the TLS record layer, 1063 where they are encapsulated within one or more TLSPlaintext or 1064 TLSCiphertext structures, which are processed and transmitted as 1065 specified by the current active session state. 1067 enum { 1068 client_hello(1), 1069 server_hello(2), 1070 new_session_ticket(4), 1071 hello_retry_request(6), 1072 encrypted_extensions(8), 1073 certificate(11), 1074 certificate_request(13), 1075 certificate_verify(15), 1076 finished(20), 1077 key_update(24), 1078 (255) 1079 } HandshakeType; 1081 struct { 1082 HandshakeType msg_type; /* handshake type */ 1083 uint24 length; /* bytes in message */ 1084 select (HandshakeType) { 1085 case client_hello: ClientHello; 1086 case server_hello: ServerHello; 1087 case hello_retry_request: HelloRetryRequest; 1088 case encrypted_extensions: EncryptedExtensions; 1089 case certificate_request: CertificateRequest; 1090 case certificate: Certificate; 1091 case certificate_verify: CertificateVerify; 1092 case finished: Finished; 1093 case new_session_ticket: NewSessionTicket; 1094 case key_update: KeyUpdate; 1095 } body; 1096 } Handshake; 1098 Protocol messages MUST be sent in the order defined below (and shown 1099 in the diagrams in Section 2). Sending handshake messages in an 1100 unexpected order results in an "unexpected_message" fatal error. 1101 Unneeded handshake messages are omitted, however. 1103 New handshake message types are assigned by IANA as described in 1104 Section 10. 1106 4.1. Key Exchange Messages 1108 The key exchange messages are used to exchange security capabilities 1109 between the client and server and to establish the traffic keys used 1110 to protect the handshake and data. 1112 4.1.1. Cryptographic Negotiation 1114 TLS cryptographic negotiation proceeds by the client offering the 1115 following four sets of options in its ClientHello. 1117 - A list of cipher suites which indicates the AEAD cipher/HKDF hash 1118 pairs which the client supports 1120 - A "supported_group" (Section 4.2.3) extension which indicates the 1121 (EC)DHE groups which the client supports and a "key_share" 1122 (Section 4.2.4) extension which contains (EC)DHE shares for some 1123 or all of these groups 1125 - A "signature_algorithms" (Section 4.2.2) extension which indicates 1126 the signature algorithms which the client can accept. 1128 - A "pre_shared_key" (Section 4.2.5) extension which contains the 1129 identities of symmetric keys known to the client and the key 1130 exchange modes which each PSK supports. 1132 If the server does not select a PSK, then the first three of these 1133 options are entirely orthogonal: the server independently selects a 1134 cipher suite, an (EC)DHE group and key share for key establishment, 1135 and a signature algorithm/certificate pair to authenticate itself to 1136 the client. If any of these parameters has no overlap between the 1137 client and server parameters, then the handshake will fail. If there 1138 is overlap in the "supported_group" extension but the client did not 1139 offer a compatible "key_share" extension, then the server will 1140 respond with a HelloRetryRequest (Section 4.1.4) message. 1142 If the server selects a PSK, then the PSK will indicate which key 1143 establishment modes it can be used with (PSK alone or with (EC)DHE) 1144 and which authentication modes it can be used with (PSK alone or PSK 1145 with signatures). The server can then select those key establishment 1146 and authentication parameters to be consistent both with the PSK and 1147 the other extensions supplied by the client. Note that if the PSK 1148 can be used without (EC)DHE or without signatures, then non-overlap 1149 in either of these parameters need not be fatal. 1151 The server indicates its selected parameters in the ServerHello as 1152 follows: If PSK is being used then the server will send a 1153 "pre_shared_key" extension indicating the selected key. If PSK is 1154 not being used, then (EC)DHE and certificate-based authentication are 1155 always used. When (EC)DHE is in use, the server will also provide a 1156 "key_share" extension. When authenticating via a certificate, the 1157 server will send an empty "signature_algorithnms" extension in the 1158 ServerHello and will subsequently send Certificate (Section 4.3.1) 1159 and CertificateVerify (Section 4.3.2) messages. 1161 If the server is unable to negotiate a supported set of parameters, 1162 it MUST return a "handshake_failure" alert and close the connection. 1164 4.1.2. Client Hello 1166 When this message will be sent: 1168 When a client first connects to a server, it is required to send 1169 the ClientHello as its first message. The client will also send a 1170 ClientHello when the server has responded to its ClientHello with 1171 a HelloRetryRequest that selects cryptographic parameters that 1172 don't match the client's "key_share" extension. In that case, the 1173 client MUST send the same ClientHello (without modification) 1174 except: 1176 - Including a new KeyShareEntry as the lowest priority share (i.e., 1177 appended to the list of shares in the "key_share" extension). 1179 - Removing the EarlyDataIndication Section 4.2.6 extension if one 1180 was present. Early data is not permitted after HelloRetryRequest. 1182 If a server receives a ClientHello at any other time, it MUST send a 1183 fatal "unexpected_message" alert and close the connection. 1185 Structure of this message: 1187 struct { 1188 uint8 major; 1189 uint8 minor; 1190 } ProtocolVersion; 1192 struct { 1193 opaque random_bytes[32]; 1194 } Random; 1196 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1198 struct { 1199 ProtocolVersion max_supported_version = { 3, 4 }; /* TLS v1.3 */ 1200 Random random; 1201 opaque legacy_session_id<0..32>; 1202 CipherSuite cipher_suites<2..2^16-2>; 1203 opaque legacy_compression_methods<1..2^8-1>; 1204 Extension extensions<0..2^16-1>; 1205 } ClientHello; 1207 TLS allows extensions to follow the compression_methods field in an 1208 extensions block. The presence of extensions can be detected by 1209 determining whether there are bytes following the compression_methods 1210 at the end of the ClientHello. Note that this method of detecting 1211 optional data differs from the normal TLS method of having a 1212 variable-length field, but it is used for compatibility with TLS 1213 before extensions were defined. As of TLS 1.3, all clients and 1214 servers will send at least one extension (at least "key_share" or 1215 "pre_shared_key"). 1217 max_supported_version The latest (highest valued) version of the TLS 1218 protocol offered by the client. This SHOULD be the same as the 1219 latest version supported. For this version of the specification, 1220 the version will be { 3, 4 }. (See Appendix C for details about 1221 backward compatibility.) 1223 random 32 bytes generated by a secure random number generator. See 1224 Appendix B for additional information. 1226 legacy_session_id Versions of TLS before TLS 1.3 supported a session 1227 resumption feature which has been merged with Pre-Shared Keys in 1228 this version (see Section 2.2). This field MUST be ignored by a 1229 server negotiating TLS 1.3 and SHOULD be set as a zero length 1230 vector (i.e., a single zero byte length field) by clients which do 1231 not have a cached session ID set by a pre-TLS 1.3 server. 1233 cipher_suites This is a list of the symmetric cipher options 1234 supported by the client, specifically the record protection 1235 algorithm (including secret key length) and a hash to be used with 1236 HKDF, in descending order of client preference. If the list 1237 contains cipher suites the server does not recognize, support, or 1238 wish to use, the server MUST ignore those cipher suites, and 1239 process the remaining ones as usual. Values are defined in 1240 Appendix A.4. 1242 legacy_compression_methods Versions of TLS before 1.3 supported 1243 compression with the list of supported compression methods being 1244 sent in this field. For every TLS 1.3 ClientHello, this vector 1245 MUST contain exactly one byte set to zero, which corresponds to 1246 the "null" compression method in prior versions of TLS. If a TLS 1247 1.3 ClientHello is received with any other value in this field, 1248 the server MUST generate a fatal "illegal_parameter" alert. Note 1249 that TLS 1.3 servers might receive TLS 1.2 or prior ClientHellos 1250 which contain other compression methods and MUST follow the 1251 procedures for the appropriate prior version of TLS. 1253 extensions Clients request extended functionality from servers by 1254 sending data in the extensions field. The actual "Extension" 1255 format is defined in Section 4.2. 1257 In the event that a client requests additional functionality using 1258 extensions, and this functionality is not supplied by the server, the 1259 client MAY abort the handshake. Note that TLS 1.3 ClientHello 1260 messages MUST always contain extensions, and a TLS 1.3 server MUST 1261 respond to any TLS 1.3 ClientHello without extensions with a fatal 1262 "decode_error" alert. TLS 1.3 servers may receive TLS 1.2 1263 ClientHello messages without extensions. If negotiating TLS 1.2, a 1264 server MUST check that the amount of data in the message precisely 1265 matches one of these formats; if not, then it MUST send a fatal 1266 "decode_error" alert. 1268 After sending the ClientHello message, the client waits for a 1269 ServerHello or HelloRetryRequest message. 1271 4.1.3. Server Hello 1273 When this message will be sent: 1275 The server will send this message in response to a ClientHello 1276 message when it was able to find an acceptable set of algorithms 1277 and the client's "key_share" extension was acceptable. If it is 1278 not able to find an acceptable set of parameters, the server will 1279 respond with a "handshake_failure" fatal alert. 1281 Structure of this message: 1283 struct { 1284 ProtocolVersion version; 1285 Random random; 1286 CipherSuite cipher_suite; 1287 Extension extensions<0..2^16-1>; 1288 } ServerHello; 1290 version This field contains the version of TLS negotiated for this 1291 session. Servers MUST select the lower of the highest supported 1292 server version and the version offered by the client in the 1293 ClientHello. In particular, servers MUST accept ClientHello 1294 messages with versions higher than those supported and negotiate 1295 the highest mutually supported version. For this version of the 1296 specification, the version is { 3, 4 }. (See Appendix C for 1297 details about backward compatibility.) 1299 random This structure is generated by the server and MUST be 1300 generated independently of the ClientHello.random. 1302 cipher_suite The single cipher suite selected by the server from the 1303 list in ClientHello.cipher_suites. 1305 extensions A list of extensions. Note that only extensions offered 1306 by the client can appear in the server's list. In TLS 1.3, as 1307 opposed to previous versions of TLS, the server's extensions are 1308 split between the ServerHello and the EncryptedExtensions 1309 Section 4.2.8 message. The ServerHello MUST only include 1310 extensions which are required to establish the cryptographic 1311 context. Currently the only such extensions are "key_share", 1312 "pre_shared_key", and "early_data". Clients MUST check the 1313 ServerHello for the presence of any forbidden extensions and if 1314 any are found MUST terminate the handshake with a 1315 "illegal_parameter" alert. In prior versions of TLS, the 1316 extensions field could be omitted entirely if not needed, similar 1317 to ClientHello. As of TLS 1.3, all clients and servers will send 1318 at least one extension (at least "key_share" or "pre_shared_key"). 1320 TLS 1.3 has a downgrade protection mechanism embedded in the server's 1321 random value. TLS 1.3 server implementations which respond to a 1322 ClientHello with a max_supported_version indicating TLS 1.2 or below 1323 MUST set the last eight bytes of their Random value to the bytes: 1325 44 4F 57 4E 47 52 44 01 1327 TLS 1.2 server implementations which respond to a ClientHello with a 1328 max_supported_version indicating TLS 1.1 or below SHOULD set the last 1329 eight bytes of their Random value to the bytes: 1331 44 4F 57 4E 47 52 44 00 1333 TLS 1.3 clients receiving a TLS 1.2 or below ServerHello MUST check 1334 that the last eight octets are not equal to either of these values. 1335 TLS 1.2 clients SHOULD also perform this check if the ServerHello 1336 indicates TLS 1.1 or below. If a match is found, the client MUST 1337 abort the handshake with a fatal "illegal_parameter" alert. This 1338 mechanism provides limited protection against downgrade attacks over 1339 and above that provided by the Finished exchange: because the 1340 ServerKeyExchange includes a signature over both random values, it is 1341 not possible for an active attacker to modify the randoms without 1342 detection as long as ephemeral ciphers are used. It does not provide 1343 downgrade protection when static RSA is used. 1345 Note: This is an update to TLS 1.2 so in practice many TLS 1.2 1346 clients and servers will not behave as specified above. 1348 4.1.4. Hello Retry Request 1350 When this message will be sent: 1352 Servers send this message in response to a ClientHello message if 1353 they were able to find an acceptable set of algorithms and groups 1354 that are mutually supported, but the client's KeyShare did not 1355 contain an acceptable offer. If it cannot find such a match, it 1356 will respond with a fatal "handshake_failure" alert. 1358 Structure of this message: 1360 struct { 1361 ProtocolVersion server_version; 1362 NamedGroup selected_group; 1363 Extension extensions<0..2^16-1>; 1364 } HelloRetryRequest; 1366 selected_group The mutually supported group the server intends to 1367 negotiate and is requesting a retried ClientHello/KeyShare for. 1369 The version and extensions fields have the same meanings as their 1370 corresponding values in the ServerHello. The server SHOULD send only 1371 the extensions necessary for the client to generate a correct 1372 ClientHello pair (currently no such extensions exist). As with 1373 ServerHello, a HelloRetryRequest MUST NOT contain any extensions that 1374 were not first offered by the client in its ClientHello. 1376 Upon receipt of a HelloRetryRequest, the client MUST first verify 1377 that the selected_group field corresponds to a group which was 1378 provided in the "supported_groups" extension in the original 1379 ClientHello. It MUST then verify that the selected_group field does 1380 not correspond to a group which was provided in the "key_share" 1381 extension in the original ClientHello. If either of these checks 1382 fails, then the client MUST abort the handshake with a fatal 1383 "illegal_parameter" alert. Clients SHOULD also abort with 1384 "unexpected_message" in response to any second HelloRetryRequest 1385 which was sent in the same connection (i.e., where the ClientHello 1386 was itself in response to a HelloRetryRequest). 1388 Otherwise, the client MUST send a ClientHello with an updated 1389 KeyShare extension to the server. The client MUST append a new 1390 KeyShareEntry for the group indicated in the selected_group field to 1391 the groups in its original KeyShare. 1393 Upon re-sending the ClientHello and receiving the server's 1394 ServerHello/KeyShare, the client MUST verify that the selected 1395 NamedGroup matches that supplied in the HelloRetryRequest and MUST 1396 abort the connection with a fatal "illegal_parameter" alert if it 1397 does not. 1399 4.2. Hello Extensions 1401 The extension format is: 1403 struct { 1404 ExtensionType extension_type; 1405 opaque extension_data<0..2^16-1>; 1406 } Extension; 1408 enum { 1409 supported_groups(10), 1410 signature_algorithms(13), 1411 key_share(40), 1412 pre_shared_key(41), 1413 early_data(42), 1414 cookie(44), 1415 (65535) 1416 } ExtensionType; 1418 Here: 1420 - "extension_type" identifies the particular extension type. 1422 - "extension_data" contains information specific to the particular 1423 extension type. 1425 The initial set of extensions is defined in [RFC6066]. The list of 1426 extension types is maintained by IANA as described in Section 10. 1428 An extension type MUST NOT appear in the ServerHello or 1429 HelloRetryRequest unless the same extension type appeared in the 1430 corresponding ClientHello. If a client receives an extension type in 1431 ServerHello or HelloRetryRequest that it did not request in the 1432 associated ClientHello, it MUST abort the handshake with an 1433 "unsupported_extension" fatal alert. 1435 Nonetheless, "server-oriented" extensions may be provided within this 1436 framework. Such an extension (say, of type x) would require the 1437 client to first send an extension of type x in a ClientHello with 1438 empty extension_data to indicate that it supports the extension type. 1439 In this case, the client is offering the capability to understand the 1440 extension type, and the server is taking the client up on its offer. 1442 When multiple extensions of different types are present in the 1443 ClientHello or ServerHello messages, the extensions MAY appear in any 1444 order. There MUST NOT be more than one extension of the same type. 1446 Finally, note that extensions can be sent both when starting a new 1447 session and when in resumption-PSK mode. A client that requests 1448 session resumption does not in general know whether the server will 1449 accept this request, and therefore it SHOULD send the same extensions 1450 as it would send normally. 1452 In general, the specification of each extension type needs to 1453 describe the effect of the extension both during full handshake and 1454 session resumption. Most current TLS extensions are relevant only 1455 when a session is initiated: when an older session is resumed, the 1456 server does not process these extensions in ClientHello, and does not 1457 include them in ServerHello. However, some extensions may specify 1458 different behavior during session resumption. [[TODO: update this 1459 and the previous paragraph to cover PSK-based resumption.]] 1461 There are subtle (and not so subtle) interactions that may occur in 1462 this protocol between new features and existing features which may 1463 result in a significant reduction in overall security. The following 1464 considerations should be taken into account when designing new 1465 extensions: 1467 - Some cases where a server does not agree to an extension are error 1468 conditions, and some are simply refusals to support particular 1469 features. In general, error alerts should be used for the former, 1470 and a field in the server extension response for the latter. 1472 - Extensions should, as far as possible, be designed to prevent any 1473 attack that forces use (or non-use) of a particular feature by 1474 manipulation of handshake messages. This principle should be 1475 followed regardless of whether the feature is believed to cause a 1476 security problem. Often the fact that the extension fields are 1477 included in the inputs to the Finished message hashes will be 1478 sufficient, but extreme care is needed when the extension changes 1479 the meaning of messages sent in the handshake phase. Designers 1480 and implementors should be aware of the fact that until the 1481 handshake has been authenticated, active attackers can modify 1482 messages and insert, remove, or replace extensions. 1484 4.2.1. Cookie 1486 struct { 1487 opaque cookie<0..2^16-1>; 1488 } Cookie; 1490 Cookies serve two primary purposes: 1492 - Allowing the server to force the client to demonstrate 1493 reachability at their apparent network address (thus providing a 1494 measure of DoS protection). This is primarily useful for non- 1495 connection-oriented transports (see [RFC6347] for an example of 1496 this). 1498 - Allowing the server to offload state to the client, thus allowing 1499 it to send a HelloRetryRequest without storing any state. The 1500 server does this by pickling that post-ClientHello hash state into 1501 the cookie (protected with some suitable integrity algorithm). 1503 When sending a HelloRetryRequest, the server MAY provide a "cookie" 1504 extension to the client (this is an exception to the usual rule that 1505 the only extensions that may be sent are those that appear in the 1506 ClientHello). When sending the new ClientHello, the client MUST echo 1507 the value of the extension. Clients MUST NOT use cookies in 1508 subsequent connections. 1510 4.2.2. Signature Algorithms 1512 The client uses the "signature_algorithms" extension to indicate to 1513 the server which signature algorithms may be used in digital 1514 signatures. Clients which desire the server to authenticate via a 1515 certificate MUST send this extension. If a server is authenticating 1516 via a certificate and the client has not sent a 1517 "signature_algorithms" extension then the server MUST close the 1518 connection with a fatal "missing_extension" alert (see Section 8.2). 1520 Servers which are authenticating via a certificate MUST indicate so 1521 by sending the client an empty "signature_algorithms" extension. 1523 The "extension_data" field of this extension contains a 1524 "supported_signature_algorithms" value: 1526 enum { 1527 /* RSASSA-PKCS1-v1_5 algorithms */ 1528 rsa_pkcs1_sha1 (0x0201), 1529 rsa_pkcs1_sha256 (0x0401), 1530 rsa_pkcs1_sha384 (0x0501), 1531 rsa_pkcs1_sha512 (0x0601), 1533 /* ECDSA algorithms */ 1534 ecdsa_secp256r1_sha256 (0x0403), 1535 ecdsa_secp384r1_sha384 (0x0503), 1536 ecdsa_secp521r1_sha512 (0x0603), 1538 /* RSASSA-PSS algorithms */ 1539 rsa_pss_sha256 (0x0700), 1540 rsa_pss_sha384 (0x0701), 1541 rsa_pss_sha512 (0x0702), 1543 /* EdDSA algorithms */ 1544 ed25519 (0x0703), 1545 ed448 (0x0704), 1547 /* Reserved Code Points */ 1548 private_use (0xFE00..0xFFFF), 1549 (0xFFFF) 1550 } SignatureScheme; 1552 SignatureScheme supported_signature_algorithms<2..2^16-2>; 1554 Note: This enum is named "SignatureScheme" because there is already a 1555 "SignatureAlgorithm" type in TLS 1.2, which this replaces. We use 1556 the term "signature algorithm" throughout the text. 1558 Each SignatureScheme value lists a single signature algorithm that 1559 the client is willing to verify. The values are indicated in 1560 descending order of preference. Note that a signature algorithm 1561 takes as input an arbitrary-length message, rather than a digest. 1562 Algorithms which traditionally act on a digest should be defined in 1563 TLS to first hash the input with a specified hash function and then 1564 proceed as usual. The code point groups listed above have the 1565 following meanings: 1567 RSASSA-PKCS1-v1_5 algorithms Indicates a signature algorithm using 1568 RSASSA-PKCS1-v1_5 [RFC3447] with the corresponding hash algorithm 1569 as defined in [SHS]. These values refer solely to signatures 1570 which appear in certificates (see Section 4.3.1.1) and are not 1571 defined for use in signed TLS handshake messages. 1573 ECDSA algorithms Indicates a signature algorithm using ECDSA 1574 [ECDSA], the corresponding curve as defined in ANSI X9.62 [X962] 1575 and FIPS 186-4 [DSS], and the corresponding hash algorithm as 1576 defined in [SHS]. The signature is represented as a DER-encoded 1577 [X690] ECDSA-Sig-Value structure. 1579 RSASSA-PSS algorithms Indicates a signature algorithm using RSASSA- 1580 PSS [RFC3447] with MGF1. The digest used in the mask generation 1581 function and the digest being signed are both the corresponding 1582 hash algorithm as defined in [SHS]. When used in signed TLS 1583 handshake messages, the length of the salt MUST be equal to the 1584 length of the digest output. This codepoint is defined for use 1585 with TLS 1.2 as well as TLS 1.3. A server uses RSASSA-PSS 1586 signatures with RSA cipher suites. 1588 EdDSA algorithms Indicates a signature algorithm using EdDSA as 1589 defined in [I-D.irtf-cfrg-eddsa] or its successors. Note that 1590 these correspond to the "PureEdDSA" algorithms and not the 1591 "prehash" variants. A server uses EdDSA signatures with ECDSA 1592 cipher suites. 1594 rsa_pkcs1_sha1, dsa_sha1, and ecdsa_sha1 SHOULD NOT be offered. 1595 Clients offering these values for backwards compatibility MUST list 1596 them as the lowest priority (listed after all other algorithms in the 1597 supported_signature_algorithms vector). TLS 1.3 servers MUST NOT 1598 offer a SHA-1 signed certificate unless no valid certificate chain 1599 can be produced without it (see Section 4.3.1.1). 1601 The signatures on certificates that are self-signed or certificates 1602 that are trust anchors are not validated since they begin a 1603 certification path (see [RFC5280], Section 3.2). A certificate that 1604 begins a certification path MAY use a signature algorithm that is not 1605 advertised as being supported in the "signature_algorithms" 1606 extension. 1608 Note that TLS 1.2 defines this extension differently. TLS 1.3 1609 implementations willing to negotiate TLS 1.2 MUST behave in 1610 accordance with the requirements of [RFC5246] when negotiating that 1611 version. In particular: 1613 - TLS 1.2 ClientHellos MAY omit this extension. 1615 - In TLS 1.2, the extension contained hash/signature pairs. The 1616 pairs are encoded in two octets, so SignatureScheme values have 1617 been allocated to align with TLS 1.2's encoding. Some legacy 1618 pairs are left unallocated. These algorithms are deprecated as of 1619 TLS 1.3. They MUST NOT be offered or negotiated by any 1620 implementation. In particular, MD5 [SLOTH] and SHA-224 MUST NOT 1621 be used. 1623 - ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature 1624 pairs. However, the old semantics did not constrain the signing 1625 curve. If TLS 1.2 is negotiated, implementations MUST be prepared 1626 to accept a signature that uses any curve that they advertised in 1627 the "supported_groups" extension. 1629 - Implementations that advertise support for RSASSA-PSS (which is 1630 mandatory in TLS 1.3), MUST be prepared to accept a signature 1631 using that scheme even when TLS 1.2 is negotiated. 1633 4.2.3. Negotiated Groups 1635 When sent by the client, the "supported_groups" extension indicates 1636 the named groups which the client supports for key exchange, ordered 1637 from most preferred to least preferred. 1639 Note: In versions of TLS prior to TLS 1.3, this extension was named 1640 "elliptic_curves" and only contained elliptic curve groups. See 1641 [RFC4492] and [I-D.ietf-tls-negotiated-ff-dhe]. This extension was 1642 also used to negotiate ECDSA curves. Signature algorithms are now 1643 negotiated independently (see Section 4.2.2). 1645 The "extension_data" field of this extension contains a 1646 "NamedGroupList" value: 1648 enum { 1649 /* Elliptic Curve Groups (ECDHE) */ 1650 secp256r1 (23), secp384r1 (24), secp521r1 (25), 1651 x25519 (29), x448 (30), 1653 /* Finite Field Groups (DHE) */ 1654 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 1655 ffdhe6144 (259), ffdhe8192 (260), 1657 /* Reserved Code Points */ 1658 ffdhe_private_use (0x01FC..0x01FF), 1659 ecdhe_private_use (0xFE00..0xFEFF), 1660 (0xFFFF) 1661 } NamedGroup; 1663 struct { 1664 NamedGroup named_group_list<1..2^16-1>; 1665 } NamedGroupList; 1667 Elliptic Curve Groups (ECDHE) Indicates support of the corresponding 1668 named curve. Note that some curves are also recommended in ANSI 1669 X9.62 [X962] and FIPS 186-4 [DSS]. Others are recommended in 1670 [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for private 1671 use. 1673 Finite Field Groups (DHE) Indicates support of the corresponding 1674 finite field group, defined in [I-D.ietf-tls-negotiated-ff-dhe]. 1675 Values 0x01FC through 0x01FF are reserved for private use. 1677 Items in named_group_list are ordered according to the client's 1678 preferences (most preferred choice first). 1680 As of TLS 1.3, servers are permitted to send the "supported_groups" 1681 extension to the client. If the server has a group it prefers to the 1682 ones in the "key_share" extension but is still willing to accept the 1683 ClientHello, it SHOULD send "supported_groups" to update the client's 1684 view of its preferences. Clients MUST NOT act upon any information 1685 found in "supported_groups" prior to successful completion of the 1686 handshake, but MAY use the information learned from a successfully 1687 completed handshake to change what groups they offer to a server in 1688 subsequent connections. 1690 4.2.4. Key Share 1692 The "key_share" extension contains the endpoint's cryptographic 1693 parameters. 1695 Clients MAY send an empty client_shares vector in order to request 1696 group selection from the server at the cost of an additional round 1697 trip. (see Section 4.1.4) 1699 struct { 1700 NamedGroup group; 1701 opaque key_exchange<1..2^16-1>; 1702 } KeyShareEntry; 1704 group The named group for the key being exchanged. Finite Field 1705 Diffie-Hellman [DH] parameters are described in Section 4.2.4.1; 1706 Elliptic Curve Diffie-Hellman parameters are described in 1707 Section 4.2.4.2. 1709 key_exchange Key exchange information. The contents of this field 1710 are determined by the specified group and its corresponding 1711 definition. Endpoints MUST NOT send empty or otherwise invalid 1712 key_exchange values for any reason. 1714 The "extension_data" field of this extension contains a "KeyShare" 1715 value: 1717 struct { 1718 select (role) { 1719 case client: 1720 KeyShareEntry client_shares<0..2^16-1>; 1722 case server: 1723 KeyShareEntry server_share; 1724 } 1725 } KeyShare; 1727 client_shares A list of offered KeyShareEntry values in descending 1728 order of client preference. This vector MAY be empty if the 1729 client is requesting a HelloRetryRequest. The ordering of values 1730 here SHOULD match that of the ordering of offered support in the 1731 "supported_groups" extension. 1733 server_share A single KeyShareEntry value that is in the same group 1734 as one of the client's shares. 1736 Clients offer an arbitrary number of KeyShareEntry values, each 1737 representing a single set of key exchange parameters. For instance, 1738 a client might offer shares for several elliptic curves or multiple 1739 FFDHE groups. The key_exchange values for each KeyShareEntry MUST by 1740 generated independently. Clients MUST NOT offer multiple 1741 KeyShareEntry values for the same group. Clients MUST NOT offer any 1742 KeyShareEntry values for groups not listed in the client's 1743 "supported_groups" extension. Servers MAY check for violations of 1744 these rules and and MAY abort the connection with a fatal 1745 "illegal_parameter" alert if one is violated. 1747 If using (EC)DHE key establishment, servers offer exactly one 1748 KeyShareEntry. This value MUST correspond to the KeyShareEntry value 1749 offered by the client that the server has selected for the negotiated 1750 key exchange. Servers MUST NOT send a KeyShareEntry for any group 1751 not indicated in the "supported_groups" extension. 1753 [[TODO: Recommendation about what the client offers. Presumably 1754 which integer DH groups and which curves.]] 1756 4.2.4.1. Diffie-Hellman Parameters 1758 Diffie-Hellman [DH] parameters for both clients and servers are 1759 encoded in the opaque key_exchange field of a KeyShareEntry in a 1760 KeyShare structure. The opaque value contains the Diffie-Hellman 1761 public value (Y = g^X mod p), encoded as a big-endian integer, padded 1762 with zeros to the size of p in bytes. 1764 Note: For a given Diffie-Hellman group, the padding results in all 1765 public keys having the same length. 1767 Peers SHOULD validate each other's public key Y by ensuring that 1 < 1768 Y < p-1. This check ensures that the remote peer is properly behaved 1769 and isn't forcing the local system into a small subgroup. 1771 4.2.4.2. ECDHE Parameters 1773 ECDHE parameters for both clients and servers are encoded in the the 1774 opaque key_exchange field of a KeyShareEntry in a KeyShare structure. 1776 For secp256r1, secp384r1 and secp521r1, the contents are the byte 1777 string representation of an elliptic curve public value following the 1778 conversion routine in Section 4.3.6 of ANSI X9.62 [X962]. 1780 Although X9.62 supports multiple point formats, any given curve MUST 1781 specify only a single point format. All curves currently specified 1782 in this document MUST only be used with the uncompressed point format 1783 (the format for all ECDH functions is considered uncompressed). 1785 For x25519 and x448, the contents are the byte string inputs and 1786 outputs of the corresponding functions defined in [RFC7748], 32 bytes 1787 for x25519 and 56 bytes for x448. 1789 Note: Versions of TLS prior to 1.3 permitted point negotiation; TLS 1790 1.3 removes this feature in favor of a single point format for each 1791 curve. 1793 4.2.5. Pre-Shared Key Extension 1795 The "pre_shared_key" extension is used to indicate the identity of 1796 the pre-shared key to be used with a given handshake in association 1797 with PSK key establishment (see [RFC4279] for background). 1799 The "extension_data" field of this extension contains a 1800 "PreSharedKeyExtension" value: 1802 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeModes; 1803 enum { psk_auth(0), psk_sign_auth(1), (255) } PskAuthenticationModes; 1805 opaque psk_identity<0..2^16-1>; 1807 struct { 1808 PskKeMode ke_modes<1..255>; 1809 PskAuthMode auth_modes<1..255>; 1810 opaque identity<0..2^16-1>; 1811 } PskIdentity; 1813 struct { 1814 select (Role) { 1815 case client: 1816 psk_identity identities<2..2^16-1>; 1818 case server: 1819 uint16 selected_identity; 1820 } 1821 } PreSharedKeyExtension; 1823 identities A list of the identities (labels for keys) that the 1824 client is willing to negotiate with the server. If sent alongside 1825 the "early_data" extension (see Section 4.2.6), the first identity 1826 is the one used for 0-RTT data. 1828 selected_identity The server's chosen identity expressed as a 1829 (0-based) index into the identies in the client's list. 1831 Each PSK offered by the client also indicates the authentication and 1832 key exchange modes with which the server can use it, with each list 1833 being in the order of the client's preference, with most preferred 1834 first. 1836 PskKeyExchangeModes have the following meanings: 1838 psk_ke PSK-only key establishment. In this mode, the server MUST 1839 not supply a "key_share" value. 1841 psk_dhe_ke PSK key establishment with (EC)DHE key establishment. In 1842 this mode, the client and servers MUST supply "key_share" values 1843 as described in Section 4.2.4. 1845 PskAuthenticationModes have the following meanings: 1847 psk_auth PSK-only authentication. In this mode, the server MUST NOT 1848 supply either a Certificate or CertificateVerify message. [TODO: 1849 Add a signing mode.] 1851 In order to accept PSK key establishment, the server sends a 1852 "pre_shared_key" extension with the selected identity. Clients MUST 1853 verify that the server's selected_identity is within the range 1854 supplied by the client and that the "key_share" and 1855 "signature_algorithms" extensions are consistent with the indicated 1856 ke_modes and auth_modes values. If these values are not consistent, 1857 the client MUST generate an "illegal_parameter" alert and close the 1858 connection. 1860 If the server supplies an "early_data" extension, the client MUST 1861 verify that the server selected the first offered identity. If any 1862 other value is returned, the client MUST generate a fatal 1863 "unknown_psk_identity" alert and close the connection. 1865 Note that although 0-RTT data is encrypted with the first PSK 1866 identity, the server MAY fall back to 1-RTT and select a different 1867 PSK identity if multiple identities are offered. 1869 4.2.6. Early Data Indication 1871 When PSK resumption is used, the client can send application data in 1872 its first flight of messages. If the client opts to do so, it MUST 1873 supply an "early_data" extension as well as the "pre_shared_key" 1874 extension. 1876 The "extension_data" field of this extension contains an 1877 "EarlyDataIndication" value: 1879 struct { 1880 select (Role) { 1881 case client: 1882 uint32 obfuscated_ticket_age; 1884 case server: 1885 struct {}; 1886 } 1887 } EarlyDataIndication; 1889 obfuscated_ticket_age The time since the client learned about the 1890 server configuration that it is using, in milliseconds. This 1891 value is added modulo 2^32 to with the "ticket_age_add" value that 1892 was included with the ticket, see Section 4.4.1. This addition 1893 prevents passive observers from correlating sessions unless 1894 tickets are reused. Note: because ticket lifetimes are restricted 1895 to a week, 32 bits is enough to represent any plausible age, even 1896 in milliseconds. 1898 A server MUST validate that the ticket_age is within a small 1899 tolerance of the time since the ticket was issued (see 1900 Section 4.2.6.2). 1902 The parameters for the 0-RTT data (symmetric cipher suite, ALPN, 1903 etc.) are the same as those which were negotiated in the connection 1904 which established the PSK. The PSK used to encrypt the early data 1905 MUST be the first PSK listed in the client's "pre_shared_key" 1906 extension. 1908 0-RTT messages sent in the first flight have the same content types 1909 as their corresponding messages sent in other flights (handshake, 1910 application_data, and alert respectively) but are protected under 1911 different keys. After all the 0-RTT application data messages (if 1912 any) have been sent, an "end_of_early_data" alert of type "warning" 1913 is sent to indicate the end of the flight. 0-RTT MUST always be 1914 followed by an "end_of_early_data" alert. 1916 A server which receives an "early_data" extension can behave in one 1917 of two ways: 1919 - Ignore the extension and return no response. This indicates that 1920 the server has ignored any early data and an ordinary 1-RTT 1921 handshake is required. 1923 - Return an empty extension, indicating that it intends to process 1924 the early data. It is not possible for the server to accept only 1925 a subset of the early data messages. 1927 In order to accept early data, the server server MUST have accepted a 1928 PSK cipher suite and selected the the first key offered in the 1929 client's "pre_shared_key" extension. In addition, it MUST verify 1930 that the following values are consistent with those negotiated in the 1931 connection during which the ticket was established. 1933 - The TLS version number, AEAD algorithm, and the hash for HKDF. 1935 - The selected ALPN [RFC7443] value, if any. 1937 - The server_name [RFC6066] value provided by the client, if any. 1939 Future extensions MUST define their interaction with 0-RTT. 1941 If any of these checks fail, the server MUST NOT respond with the 1942 extension and must discard all the remaining first flight data (thus 1943 falling back to 1-RTT). If the client attempts a 0-RTT handshake but 1944 the server rejects it, it will generally not have the 0-RTT record 1945 protection keys and must instead trial decrypt each record with the 1946 1-RTT handshake keys until it finds one that decrypts properly, and 1947 then pick up the handshake from that point. 1949 If the server chooses to accept the "early_data" extension, then it 1950 MUST comply with the same error handling requirements specified for 1951 all records when processing early data records. Specifically, 1952 decryption failure of any 0-RTT record following an accepted 1953 "early_data" extension MUST produce a fatal "bad_record_mac" alert as 1954 per Section 5.2. 1956 If the server rejects the "early_data" extension, the client 1957 application MAY opt to retransmit the data once the handshake has 1958 been completed. TLS stacks SHOULD not do this automatically and 1959 client applications MUST take care that the negotiated parameters are 1960 consistent with those it expected. For example, if the ALPN value 1961 has changed, it is likely unsafe to retransmit the original 1962 application layer data. 1964 4.2.6.1. Processing Order 1966 Clients are permitted to "stream" 0-RTT data until they receive the 1967 server's Finished, only then sending the "end_of_early_data" alert. 1968 In order to avoid deadlock, when accepting "early_data", servers MUST 1969 process the client's Finished and then immediately send the 1970 ServerHello, rather than waiting for the client's "end_of_early_data" 1971 alert. 1973 4.2.6.2. Replay Properties 1975 As noted in Section 2.3, TLS provides a limited mechanism for replay 1976 protection for data sent by the client in the first flight. 1978 The "obfuscated_ticket_age" parameter in the client's "early_data" 1979 extension SHOULD be used by servers to limit the time over which the 1980 first flight might be replayed. A server can store the time at which 1981 it sends a session ticket to the client, or encode the time in the 1982 ticket. Then, each time it receives an "early_data" extension, it 1983 can subtract the base value and check to see if the value used by the 1984 client matches its expectations. 1986 The ticket age (the value with "ticket_age_add" subtracted) provided 1987 by the client will be shorter than the actual time elapsed on the 1988 server by a single round trip time. This difference is comprised of 1989 the delay in sending the NewSessionTicket message to the client, plus 1990 the time taken to send the ClientHello to the server. For this 1991 reason, a server SHOULD measure the round trip time prior to sending 1992 the NewSessionTicket message and account for that in the value it 1993 saves. 1995 To properly validate the ticket age, a server needs to save at least 1996 two items: 1998 - The time that the server generated the session ticket and the 1999 estimated round trip time can be added together to form a baseline 2000 time. 2002 - The "ticket_age_add" parameter from the NewSessionTicket is needed 2003 to recover the ticket age from the "obfuscated_ticket_age" 2004 parameter. 2006 There are several potential sources of error that make an exact 2007 measurement of time difficult. Variations in client and server 2008 clocks are likely to be minimal, outside of gross time corrections. 2009 Network propagation delays are most likely causes of a mismatch in 2010 legitimate values for elapsed time. Both the NewSessionTicket and 2011 ClientHello messages might be retransmitted and therefore delayed, 2012 which might be hidden by TCP. 2014 A small allowance for errors in clocks and variations in measurements 2015 is advisable. However, any allowance also increases the opportunity 2016 for replay. In this case, it is better to reject early data and fall 2017 back to a full 1-RTT handshake than to risk greater exposure to 2018 replay attacks. In common network topologies for browser clients, 2019 small allowances on the order of ten seconds are reasonable. Clock 2020 skew distributions are not symmetric, so the optimal tradeoff may 2021 involve an asymmetric replay window. 2023 4.2.7. OCSP Status Extensions 2025 [RFC6066] and [RFC6961] provide extensions to negotiate the server 2026 sending OCSP responses to the client. In TLS 1.2 and below, the 2027 server sends an empty extension to indicate negotiation of this 2028 extension and the OCSP information is carried in a CertificateStatus 2029 message. In TLS 1.3, the server's OCSP information is carried in an 2030 extension in EncryptedExtensions. Specifically: The body of the 2031 "status_request" or "status_request_v2" extension from the server 2032 MUST be a CertificateStatus structure as defined in [RFC6066] and 2033 [RFC6961] respectively. 2035 Note: This means that the certificate status appears prior to the 2036 certificates it applies to. This is slightly anomalous but matches 2037 the existing behavior for SignedCertificateTimestamps [RFC6962], and 2038 is more easily extensible in the handshake state machine. 2040 4.2.8. Encrypted Extensions 2042 When this message will be sent: 2044 In all handshakes, the server MUST send the EncryptedExtensions 2045 message immediately after the ServerHello message. This is the 2046 first message that is encrypted under keys derived from 2047 handshake_traffic_secret. 2049 Meaning of this message: 2051 The EncryptedExtensions message contains any extensions which 2052 should be protected, i.e., any which are not needed to establish 2053 the cryptographic context. 2055 The same extension types MUST NOT appear in both the ServerHello and 2056 EncryptedExtensions. If the same extension appears in both 2057 locations, the client MUST rely only on the value in the 2058 EncryptedExtensions block. All server-sent extensions other than 2059 those explicitly listed in Section 4.1.3 or designated in the IANA 2060 registry MUST only appear in EncryptedExtensions. Extensions which 2061 are designated to appear in ServerHello MUST NOT appear in 2062 EncryptedExtensions. Clients MUST check EncryptedExtensions for the 2063 presence of any forbidden extensions and if any are found MUST 2064 terminate the handshake with an "illegal_parameter" alert. 2066 Structure of this message: 2068 struct { 2069 Extension extensions<0..2^16-1>; 2070 } EncryptedExtensions; 2072 extensions A list of extensions. 2074 4.2.9. Certificate Request 2076 When this message will be sent: 2078 A server which is authenticating with a certificate can optionally 2079 request a certificate from the client. This message, if sent, 2080 will follow EncryptedExtensions. 2082 Structure of this message: 2084 opaque DistinguishedName<1..2^16-1>; 2086 struct { 2087 opaque certificate_extension_oid<1..2^8-1>; 2088 opaque certificate_extension_values<0..2^16-1>; 2089 } CertificateExtension; 2091 struct { 2092 opaque certificate_request_context<0..2^8-1>; 2093 SignatureScheme 2094 supported_signature_algorithms<2..2^16-2>; 2095 DistinguishedName certificate_authorities<0..2^16-1>; 2096 CertificateExtension certificate_extensions<0..2^16-1>; 2097 } CertificateRequest; 2099 certificate_request_context An opaque string which identifies the 2100 certificate request and which will be echoed in the client's 2101 Certificate message. The certificate_request_context MUST be 2102 unique within the scope of this connection (thus preventing replay 2103 of client CertificateVerify messages). Within the handshake, this 2104 field MUST be empty. 2106 supported_signature_algorithms A list of the signature algorithms 2107 that the server is able to verify, listed in descending order of 2108 preference. Any certificates provided by the client MUST be 2109 signed using a signature algorithm found in 2110 supported_signature_algorithms. 2112 certificate_authorities A list of the distinguished names [X501] of 2113 acceptable certificate_authorities, represented in DER-encoded 2114 [X690] format. These distinguished names may specify a desired 2115 distinguished name for a root CA or for a subordinate CA; thus, 2116 this message can be used to describe known roots as well as a 2117 desired authorization space. If the certificate_authorities list 2118 is empty, then the client MAY send any certificate that meets the 2119 rest of the selection criteria in the CertificateRequest, unless 2120 there is some external arrangement to the contrary. 2122 certificate_extensions A list of certificate extension OIDs 2123 [RFC5280] with their allowed values, represented in DER-encoded 2124 [X690] format. Some certificate extension OIDs allow multiple 2125 values (e.g. Extended Key Usage). If the server has included a 2126 non-empty certificate_extensions list, the client certificate MUST 2127 contain all of the specified extension OIDs that the client 2128 recognizes. For each extension OID recognized by the client, all 2129 of the specified values MUST be present in the client certificate 2130 (but the certificate MAY have other values as well). However, the 2131 client MUST ignore and skip any unrecognized certificate extension 2132 OIDs. If the client has ignored some of the required certificate 2133 extension OIDs, and supplied a certificate that does not satisfy 2134 the request, the server MAY at its discretion either continue the 2135 session without client authentication, or terminate the session 2136 with a fatal unsupported_certificate alert. PKIX RFCs define a 2137 variety of certificate extension OIDs and their corresponding 2138 value types. Depending on the type, matching certificate 2139 extension values are not necessarily bitwise-equal. It is 2140 expected that TLS implementations will rely on their PKI libraries 2141 to perform certificate selection using certificate extension OIDs. 2142 This document defines matching rules for two standard certificate 2143 extensions defined in [RFC5280]: 2145 o The Key Usage extension in a certificate matches the request 2146 when all key usage bits asserted in the request are also 2147 asserted in the Key Usage certificate extension. 2149 o The Extended Key Usage extension in a certificate matches the 2150 request when all key purpose OIDs present in the request are 2151 also found in the Extended Key Usage certificate extension. 2152 The special anyExtendedKeyUsage OID MUST NOT be used in the 2153 request. 2155 Separate specifications may define matching rules for other 2156 certificate extensions. 2158 Note: It is a fatal "unexpected_message" alert for an anonymous 2159 server to request client authentication. 2161 4.3. Authentication Messages 2163 As discussed in Section 2, TLS uses a common set of messages for 2164 authentication, key confirmation, and handshake integrity: 2165 Certificate, CertificateVerify, and Finished. These messages are 2166 always sent as the last messages in their handshake flight. The 2167 Certificate and CertificateVerify messages are only sent under 2168 certain circumstances, as defined below. The Finished message is 2169 always sent as part of the Authentication block. 2171 The computations for the Authentication messages all uniformly take 2172 the following inputs: 2174 - The certificate and signing key to be used. 2176 - A Handshake Context based on the hash of the handshake messages 2178 - A base key to be used to compute a MAC key. 2180 Based on these inputs, the messages then contain: 2182 Certificate The certificate to be used for authentication and any 2183 supporting certificates in the chain. Note that certificate-based 2184 client authentication is not available in the 0-RTT case. 2186 CertificateVerify A signature over the value Hash(Handshake Context 2187 + Certificate) + Hash(resumption_context) See Section 4.4.1 for 2188 the definition of resumption_context. 2190 Finished A MAC over the value Hash(Handshake Context + Certificate + 2191 CertificateVerify) + Hash(resumption_context) using a MAC key 2192 derived from the base key. 2194 Because the CertificateVerify signs the Handshake Context + 2195 Certificate and the Finished MACs the Handshake Context + Certificate 2196 + CertificateVerify, this is mostly equivalent to keeping a running 2197 hash of the handshake messages (exactly so in the pure 1-RTT cases). 2198 Note, however, that subsequent post-handshake authentications do not 2199 include each other, just the messages through the end of the main 2200 handshake. 2202 The following table defines the Handshake Context and MAC Base Key 2203 for each scenario: 2205 +------------+--------------------------------+---------------------+ 2206 | Mode | Handshake Context | Base Key | 2207 +------------+--------------------------------+---------------------+ 2208 | 0-RTT | ClientHello | early_traffic_secre | 2209 | | | t | 2210 | | | | 2211 | 1-RTT | ClientHello ... later of Encry | handshake_traffic_s | 2212 | (Server) | ptedExtensions/CertificateRequ | ecret | 2213 | | est | | 2214 | | | | 2215 | 1-RTT | ClientHello ... ServerFinished | handshake_traffic_s | 2216 | (Client) | | ecret | 2217 | | | | 2218 | Post- | ClientHello ... ClientFinished | traffic_secret_0 | 2219 | Handshake | + CertificateRequest | | 2220 +------------+--------------------------------+---------------------+ 2222 Note: The Handshake Context for the last three rows does not include 2223 any 0-RTT handshake messages, regardless of whether 0-RTT is used. 2225 4.3.1. Certificate 2227 When this message will be sent: 2229 The server MUST send a Certificate message whenever the agreed- 2230 upon key exchange method uses certificates for authentication 2231 (this includes all key exchange methods defined in this document 2232 except PSK). 2234 The client MUST send a Certificate message if and only if server 2235 has requested client authentication via a CertificateRequest 2236 message (Section 4.2.9). If the server requests client 2237 authentication but no suitable certificate is available, the 2238 client MUST send a Certificate message containing no certificates 2239 (i.e., with the "certificate_list" field having length 0). 2241 Meaning of this message: 2243 This message conveys the endpoint's certificate chain to the peer. 2245 Structure of this message: 2247 opaque ASN1Cert<1..2^24-1>; 2249 struct { 2250 opaque certificate_request_context<0..2^8-1>; 2251 ASN1Cert certificate_list<0..2^24-1>; 2252 } Certificate; 2254 certificate_request_context If this message is in response to a 2255 CertificateRequest, the value of certificate_request_context in 2256 that message. Otherwise, in the case of server authentication 2257 this field SHALL be zero length. 2259 certificate_list This is a sequence (chain) of certificates. The 2260 sender's certificate MUST come first in the list. Each following 2261 certificate SHOULD directly certify one preceding it. Because 2262 certificate validation requires that trust anchors be distributed 2263 independently, a certificate that specifies a trust anchor MAY be 2264 omitted from the chain, provided that supported peers are known to 2265 possess any omitted certificates. 2267 Note: Prior to TLS 1.3, "certificate_list" ordering required each 2268 certificate to certify the one immediately preceding it, however some 2269 implementations allowed some flexibility. Servers sometimes send 2270 both a current and deprecated intermediate for transitional purposes, 2271 and others are simply configured incorrectly, but these cases can 2272 nonetheless be validated properly. For maximum compatibility, all 2273 implementations SHOULD be prepared to handle potentially extraneous 2274 certificates and arbitrary orderings from any TLS version, with the 2275 exception of the end-entity certificate which MUST be first. 2277 The server's certificate list MUST always be non-empty. A client 2278 will send an empty certificate list if it does not have an 2279 appropriate certificate to send in response to the server's 2280 authentication request. 2282 4.3.1.1. Server Certificate Selection 2284 The following rules apply to the certificates sent by the server: 2286 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2287 negotiated otherwise (e.g., [RFC5081]). 2289 - The server's end-entity certificate's public key (and associated 2290 restrictions) MUST be compatible with the selected authentication 2291 algorithm (currently RSA or ECDSA). 2293 - The certificate MUST allow the key to be used for signing (i.e., 2294 the digitalSignature bit MUST be set if the Key Usage extension is 2295 present) with a signature scheme indicated in the client's 2296 "signature_algorithms" extension. 2298 - The "server_name" and "trusted_ca_keys" extensions [RFC6066] are 2299 used to guide certificate selection. As servers MAY require the 2300 presence of the "server_name" extension, clients SHOULD send this 2301 extension, when applicable. 2303 All certificates provided by the server MUST be signed by a signature 2304 algorithm that appears in the "signature_algorithms" extension 2305 provided by the client, if they are able to provide such a chain (see 2306 Section 4.2.2). Certificates that are self-signed or certificates 2307 that are expected to be trust anchors are not validated as part of 2308 the chain and therefore MAY be signed with any algorithm. 2310 If the server cannot produce a certificate chain that is signed only 2311 via the indicated supported algorithms, then it SHOULD continue the 2312 handshake by sending the client a certificate chain of its choice 2313 that may include algorithms that are not known to be supported by the 2314 client. This fallback chain MAY use the deprecated SHA-1 hash 2315 algorithm only if the "signature_algorithms" extension provided by 2316 the client permits it. If the client cannot construct an acceptable 2317 chain using the provided certificates and decides to abort the 2318 handshake, then it MUST send an "unsupported_certificate" alert 2319 message and close the connection. 2321 If the server has multiple certificates, it chooses one of them based 2322 on the above-mentioned criteria (in addition to other criteria, such 2323 as transport layer endpoint, local configuration and preferences). 2325 4.3.1.2. Client Certificate Selection 2327 The following rules apply to certificates sent by the client: 2329 In particular: 2331 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2332 negotiated otherwise (e.g., [RFC5081]). 2334 - If the certificate_authorities list in the certificate request 2335 message was non-empty, one of the certificates in the certificate 2336 chain SHOULD be issued by one of the listed CAs. 2338 - The certificates MUST be signed using an acceptable signature 2339 algorithm, as described in Section 4.2.9. Note that this relaxes 2340 the constraints on certificate-signing algorithms found in prior 2341 versions of TLS. 2343 - If the certificate_extensions list in the certificate request 2344 message was non-empty, the end-entity certificate MUST match the 2345 extension OIDs recognized by the client, as described in 2346 Section 4.2.9. 2348 Note that, as with the server certificate, there are certificates 2349 that use algorithm combinations that cannot be currently used with 2350 TLS. 2352 4.3.1.3. Receiving a Certificate Message 2354 In general, detailed certificate validation procedures are out of 2355 scope for TLS (see [RFC5280]). This section provides TLS-specific 2356 requirements. 2358 If the server supplies an empty Certificate message, the client MUST 2359 terminate the handshake with a fatal "decode_error" alert. 2361 If the client does not send any certificates, the server MAY at its 2362 discretion either continue the handshake without client 2363 authentication, or respond with a fatal "handshake_failure" alert. 2364 Also, if some aspect of the certificate chain was unacceptable (e.g., 2365 it was not signed by a known, trusted CA), the server MAY at its 2366 discretion either continue the handshake (considering the client 2367 unauthenticated) or send a fatal alert. 2369 Any endpoint receiving any certificate signed using any signature 2370 algorithm using an MD5 hash MUST send a "bad_certificate" alert 2371 message and close the connection. SHA-1 is deprecated and therefore 2372 NOT RECOMMENDED. All endpoints are RECOMMENDED to transition to 2373 SHA-256 or better as soon as possible to maintain interoperability 2374 with implementations currently in the process of phasing out SHA-1 2375 support. 2377 Note that a certificate containing a key for one signature algorithm 2378 MAY be signed using a different signature algorithm (for instance, an 2379 RSA key signed with an ECDSA key). 2381 Endpoints that reject certification paths due to use of a deprecated 2382 hash MUST send a fatal "bad_certificate" alert message before closing 2383 the connection. 2385 4.3.2. Certificate Verify 2387 When this message will be sent: 2389 This message is used to provide explicit proof that an endpoint 2390 possesses the private key corresponding to its certificate and 2391 also provides integrity for the handshake up to this point. 2392 Servers MUST send this message when authenticating via a 2393 certificate. Clients MUST send this message whenever 2394 authenticating via a Certificate (i.e., when the Certificate 2395 message is non-empty). When sent, this message MUST appear 2396 immediately after the Certificate Message and immediately prior to 2397 the Finished message. 2399 Structure of this message: 2401 struct { 2402 SignatureScheme algorithm; 2403 opaque signature<0..2^16-1>; 2404 } CertificateVerify; 2406 The algorithm field specifies the signature algorithm used (see 2407 Section 4.2.2 for the definition of this field). The signature is a 2408 digital signature using that algorithm that covers the hash output 2409 described in Section 4.3 namely: 2411 Hash(Handshake Context + Certificate) + Hash(resumption_context) 2413 In TLS 1.3, the digital signature process takes as input: 2415 - A signing key 2416 - A context string 2418 - The actual content to be signed 2420 The digital signature is then computed using the signing key over the 2421 concatenation of: 2423 - 64 bytes of octet 32 2425 - The context string 2427 - A single 0 byte which servers as the separator 2429 - The content to be signed 2431 This structure is intended to prevent an attack on previous versions 2432 of previous versions of TLS in which the ServerKeyExchange format 2433 meant that attackers could obtain a signature of a message with a 2434 chosen, 32-byte prefix. The initial 64 byte pad clears that prefix. 2436 The context string for a server signature is "TLS 1.3, server 2437 CertificateVerify" and for a client signature is "TLS 1.3, client 2438 CertificateVerify". 2440 For example, if Hash(Handshake Context + Certificate) was 32 bytes of 2441 01 and Hash(resumption_context) was 32 bytes of 02 (these lengths 2442 would make sense for SHA-256, the input to the final signing process 2443 for a server CertificateVerify would be: 2445 2020202020202020202020202020202020202020202020202020202020202020 2446 2020202020202020202020202020202020202020202020202020202020202020 2447 544c5320312e332c207365727665722043657274696669636174655665726966 2448 79 2449 00 2450 0101010101010101010101010101010101010101010101010101010101010101 2451 0202020202020202020202020202020202020202020202020202020202020202 2453 If sent by a server, the signature algorithm MUST be one offered in 2454 the client's "signature_algorithms" extension unless no valid 2455 certificate chain can be produced without unsupported algorithms (see 2456 Section 4.2.2). 2458 If sent by a client, the signature algorithm used in the signature 2459 MUST be one of those present in the supported_signature_algorithms 2460 field of the CertificateRequest message. 2462 In addition, the signature algorithm MUST be compatible with the key 2463 in the sender's end-entity certificate. RSA signatures MUST use an 2464 RSASSA-PSS algorithm, regardless of whether RSASSA-PKCS1-v1_5 2465 algorithms appear in "signature_algorithms". SHA-1 MUST NOT be used 2466 in any signatures in CertificateVerify. All SHA-1 signature 2467 algorithms in this specification are defined solely for use in legacy 2468 certificates, and are not valid for CertificateVerify signatures. 2470 Note: When used with non-certificate-based handshakes (e.g., PSK), 2471 the client's signature does not cover the server's certificate 2472 directly, although it does cover the server's Finished message, which 2473 transitively includes the server's certificate when the PSK derives 2474 from a certificate-authenticated handshake. [PSK-FINISHED] describes 2475 a concrete attack on this mode if the Finished is omitted from the 2476 signature. It is unsafe to use certificate-based client 2477 authentication when the client might potentially share the same PSK/ 2478 key-id pair with two different endpoints. In order to ensure this, 2479 implementations MUST NOT mix certificate-based client authentication 2480 with pure PSK modes (i.e., those where the PSK was not derived from a 2481 previous non-PSK handshake). 2483 4.3.3. Finished 2485 When this message will be sent: 2487 The Finished message is the final message in the authentication 2488 block. It is essential for providing authentication of the 2489 handshake and of the computed keys. 2491 Meaning of this message: 2493 Recipients of Finished messages MUST verify that the contents are 2494 correct. Once a side has sent its Finished message and received 2495 and validated the Finished message from its peer, it may begin to 2496 send and receive application data over the connection. 2498 The key used to compute the finished message is computed from the 2499 Base key defined in Section 4.3 using HKDF (see Section 7.1). 2500 Specifically: 2502 client_finished_key = 2503 HKDF-Expand-Label(BaseKey, "client finished", "", Hash.Length) 2505 server_finished_key = 2506 HKDF-Expand-Label(BaseKey, "server finished", "", Hash.Length) 2508 Structure of this message: 2510 struct { 2511 opaque verify_data[Hash.length]; 2512 } Finished; 2514 The verify_data value is computed as follows: 2516 verify_data = 2517 HMAC(finished_key, Hash( 2518 Handshake Context + 2519 Certificate* + 2520 CertificateVerify* 2521 ) + 2522 Hash(resumption_context) 2523 ) 2525 * Only included if present. 2527 Where HMAC [RFC2104] uses the Hash algorithm for the handshake. As 2528 noted above, the HMAC input can generally be implemented by a running 2529 hash, i.e., just the handshake hash at this point. 2531 In previous versions of TLS, the verify_data was always 12 octets 2532 long. In the current version of TLS, it is the size of the HMAC 2533 output for the Hash used for the handshake. 2535 Note: Alerts and any other record types are not handshake messages 2536 and are not included in the hash computations. 2538 Any records following a 1-RTT Finished message MUST be encrypted 2539 under the application traffic key. In particular, this includes any 2540 alerts sent by the server in response to client Certificate and 2541 CertificateVerify messages. 2543 4.4. Post-Handshake Messages 2545 TLS also allows other messages to be sent after the main handshake. 2546 These messages use a handshake content type and are encrypted under 2547 the application traffic key. 2549 Handshake messages sent after the handshake MUST NOT be interleaved 2550 with other record types. That is, if a message is split over two or 2551 more handshake records, there MUST NOT be any other records between 2552 them. 2554 4.4.1. New Session Ticket Message 2556 At any time after the server has received the client Finished 2557 message, it MAY send a NewSessionTicket message. This message 2558 creates a pre-shared key (PSK) binding between the ticket value and 2559 the following two values derived from the resumption master secret: 2561 resumption_psk = HKDF-Expand-Label( 2562 resumption_secret, 2563 "resumption psk", "", Hash.Length) 2565 resumption_context = HKDF-Expand-Label( 2566 resumption_secret, 2567 "resumption context", "", Hash.Length) 2569 The client MAY use this PSK for future handshakes by including the 2570 ticket value in the "pre_shared_key" extension in its ClientHello 2571 (Section 4.2.5). Servers MAY send multiple tickets on a single 2572 connection, either immediately after each other or after specific 2573 events. For instance, the server might send a new ticket after post- 2574 handshake authentication in order to encapsulate the additional 2575 client authentication state. Clients SHOULD attempt to use each 2576 ticket no more than once, with more recent tickets being used first. 2577 For handshakes that do not use a resumption_psk, the 2578 resumption_context is a string of Hash.Length zeroes. [[Note: this 2579 will not be safe if/when we add additional server signatures with 2580 PSK: OPEN ISSUE https://github.com/tlswg/tls13-spec/issues/558]] 2582 Any ticket MUST only be resumed with a cipher suite that is identical 2583 to that negotiated connection where the ticket was established. 2585 enum { (65535) } TicketExtensionType; 2587 struct { 2588 TicketExtensionType extension_type; 2589 opaque extension_data<1..2^16-1>; 2590 } TicketExtension; 2592 struct { 2593 uint32 ticket_lifetime; 2594 PskKeMode ke_modes<1..255>; 2595 PskAuthMode auth_modes<1..255>; 2596 opaque ticket<1..2^16-1>; 2597 TicketExtension extensions<0..2^16-2>; 2598 } NewSessionTicket; 2600 ke_modes The key exchange modes with which this ticket can be used 2601 in descending order of server preference. 2603 auth_modes The authentication modes with which this ticket can be 2604 used in descending order of server preference. 2606 ticket_lifetime Indicates the lifetime in seconds as a 32-bit 2607 unsigned integer in network byte order from the time of ticket 2608 issuance. Servers MUST NOT use any value more than 604800 seconds 2609 (7 days). The value of zero indicates that the ticket should be 2610 discarded immediately. Clients MUST NOT cache session tickets for 2611 longer than 7 days, regardless of the ticket_lifetime. It MAY 2612 delete the ticket earlier based on local policy. A server MAY 2613 treat a ticket as valid for a shorter period of time than what is 2614 stated in the ticket_lifetime. 2616 ticket The value of the ticket to be used as the PSK identifier. 2617 The ticket itself is an opaque label. It MAY either be a database 2618 lookup key or a self-encrypted and self-authenticated value. 2619 Section 4 of [RFC5077] describes a recommended ticket construction 2620 mechanism. 2622 ticket_extensions A set of extension values for the ticket. Clients 2623 MUST ignore unrecognized extensions. 2625 This document defines one ticket extension, "ticket_early_data_info" 2627 struct { 2628 uint32 ticket_age_add; 2629 } TicketEarlyDataInfo; 2631 This extension indicates that the ticket may be used to send 0-RTT 2632 data (Section 4.2.6)). It contains one value: 2634 ticket_age_add A randomly generated 32-bit value that is used to 2635 obscure the age of the ticket that the client includes in the 2636 "early_data" extension. The client-side ticket age is added to 2637 this value modulo 2^32 to obtain the value that is transmitted by 2638 the client. 2640 4.4.2. Post-Handshake Authentication 2642 The server is permitted to request client authentication at any time 2643 after the handshake has completed by sending a CertificateRequest 2644 message. The client SHOULD respond with the appropriate 2645 Authentication messages. If the client chooses to authenticate, it 2646 MUST send Certificate, CertificateVerify, and Finished. If it 2647 declines, it MUST send a Certificate message containing no 2648 certificates followed by Finished. 2650 Note: Because client authentication may require prompting the user, 2651 servers MUST be prepared for some delay, including receiving an 2652 arbitrary number of other messages between sending the 2653 CertificateRequest and receiving a response. In addition, clients 2654 which receive multiple CertificateRequests in close succession MAY 2655 respond to them in a different order than they were received (the 2656 certificate_request_context value allows the server to disambiguate 2657 the responses). 2659 4.4.3. Key and IV Update 2661 struct {} KeyUpdate; 2663 The KeyUpdate handshake message is used to indicate that the sender 2664 is updating its sending cryptographic keys. This message can be sent 2665 by the server after sending its first flight and the client after 2666 sending its second flight. Implementations that receive a KeyUpdate 2667 message prior to receiving a Finished message as part of the 1-RTT 2668 handshake MUST generate a fatal "unexpected_message" alert. After 2669 sending a KeyUpdate message, the sender SHALL send all its traffic 2670 using the next generation of keys, computed as described in 2671 Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update 2672 their receiving keys and if they have not already updated their 2673 sending state up to or past the then current receiving generation 2674 MUST send their own KeyUpdate prior to sending any other messages. 2675 This mechanism allows either side to force an update to the entire 2676 connection. Note that implementations may receive an arbitrary 2677 number of messages between sending a KeyUpdate and receiving the 2678 peer's KeyUpdate because those messages may already be in flight. 2680 Note that if implementations independently send their own KeyUpdates 2681 and they cross in flight, this only results in an update of one 2682 generation; when each side receives the other side's update it just 2683 updates its receive keys and notes that the generations match and 2684 thus no send update is needed. 2686 Note that the side which sends its KeyUpdate first needs to retain 2687 its receive traffic keys (though not the traffic secret) for the 2688 previous generation of keys until it receives the KeyUpdate from the 2689 other side. 2691 Both sender and receiver MUST encrypt their KeyUpdate messages with 2692 the old keys. Additionally, both sides MUST enforce that a KeyUpdate 2693 with the old key is received before accepting any messages encrypted 2694 with the new key. Failure to do so may allow message truncation 2695 attacks. 2697 4.5. Handshake Layer and Key Changes 2699 Handshake messages MUST NOT span key changes. Because the 2700 ServerHello, Finished, and KeyUpdate messages signal a key change, 2701 upon receiving these messages a receiver MUST verify that the end of 2702 these messages aligns with a record boundary; if not, then it MUST 2703 send a fatal "unexpected_message" alert. 2705 5. Record Protocol 2707 The TLS record protocol takes messages to be transmitted, fragments 2708 the data into manageable blocks, protects the records, and transmits 2709 the result. Received data is decrypted and verified, reassembled, 2710 and then delivered to higher-level clients. 2712 TLS records are typed, which allows multiple higher level protocols 2713 to be multiplexed over the same record layer. This document 2714 specifies three content types: handshake, application data, and 2715 alert. Implementations MUST NOT send record types not defined in 2716 this document unless negotiated by some extension. If a TLS 2717 implementation receives an unexpected record type, it MUST send an 2718 "unexpected_message" alert. New record content type values are 2719 assigned by IANA in the TLS Content Type Registry as described in 2720 Section 10. 2722 Application data messages are carried by the record layer and are 2723 fragmented and encrypted as described below. The messages are 2724 treated as transparent data to the record layer. 2726 5.1. Record Layer 2728 The TLS record layer receives uninterpreted data from higher layers 2729 in non-empty blocks of arbitrary size. 2731 The record layer fragments information blocks into TLSPlaintext 2732 records carrying data in chunks of 2^14 bytes or less. Message 2733 boundaries are not preserved in the record layer (i.e., multiple 2734 messages of the same ContentType MAY be coalesced into a single 2735 TLSPlaintext record, or a single message MAY be fragmented across 2736 several records). Alert messages (Section 6) MUST NOT be fragmented 2737 across records. 2739 enum { 2740 alert(21), 2741 handshake(22), 2742 application_data(23) 2743 (255) 2744 } ContentType; 2746 struct { 2747 ContentType type; 2748 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 2749 uint16 length; 2750 opaque fragment[TLSPlaintext.length]; 2751 } TLSPlaintext; 2753 type The higher-level protocol used to process the enclosed 2754 fragment. 2756 legacy_record_version This value MUST be set to { 3, 1 } for all 2757 records. This field is deprecated and MUST be ignored for all 2758 purposes. 2760 length The length (in bytes) of the following TLSPlaintext.fragment. 2761 The length MUST NOT exceed 2^14. 2763 fragment The data being transmitted. This value transparent and 2764 treated as an independent block to be dealt with by the higher- 2765 level protocol specified by the type field. 2767 This document describes TLS Version 1.3, which uses the version { 3, 2768 4 }. The version value 3.4 is historical, deriving from the use of { 2769 3, 1 } for TLS 1.0 and { 3, 0 } for SSL 3.0. In order to maximize 2770 backwards compatibility, the record layer version identifies as 2771 simply TLS 1.0. Endpoints supporting other versions negotiate the 2772 version to use by following the procedure and requirements in 2773 Appendix C. 2775 Implementations MUST NOT send zero-length fragments of Handshake or 2776 Alert types, even if those fragments contain padding. Zero-length 2777 fragments of Application data MAY be sent as they are potentially 2778 useful as a traffic analysis countermeasure. 2780 When record protection has not yet been engaged, TLSPlaintext 2781 structures are written directly onto the wire. Once record 2782 protection has started, TLSPlaintext records are protected and sent 2783 as described in the following section. 2785 5.2. Record Payload Protection 2787 The record protection functions translate a TLSPlaintext structure 2788 into a TLSCiphertext. The deprotection functions reverse the 2789 process. In TLS 1.3 as opposed to previous versions of TLS, all 2790 ciphers are modeled as "Authenticated Encryption with Additional 2791 Data" (AEAD) [RFC5116]. AEAD functions provide a unified encryption 2792 and authentication operation which turns plaintext into authenticated 2793 ciphertext and back again. Each encrypted record consists of a 2794 plaintext header followed by an encrypted body, which itself contains 2795 a type and optional padding. 2797 struct { 2798 opaque content[TLSPlaintext.length]; 2799 ContentType type; 2800 uint8 zeros[length_of_padding]; 2801 } TLSInnerPlaintext; 2803 struct { 2804 ContentType opaque_type = application_data(23); /* see fragment.type */ 2805 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 2806 uint16 length; 2807 opaque encrypted_record[length]; 2808 } TLSCiphertext; 2810 content The cleartext of TLSPlaintext.fragment. 2812 type The content type of the record. 2814 zeros An arbitrary-length run of zero-valued bytes may appear in the 2815 cleartext after the type field. This provides an opportunity for 2816 senders to pad any TLS record by a chosen amount as long as the 2817 total stays within record size limits. See Section 5.4 for more 2818 details. 2820 opaque_type The outer opaque_type field of a TLSCiphertext record is 2821 always set to the value 23 (application_data) for outward 2822 compatibility with middleboxes accustomed to parsing previous 2823 versions of TLS. The actual content type of the record is found 2824 in fragment.type after decryption. 2826 legacy_record_version The legacy_record_version field is identical 2827 to TLSPlaintext.legacy_record_version and is always { 3, 1 }. 2828 Note that the handshake protocol including the ClientHello and 2829 ServerHello messages authenticates the protocol version, so this 2830 value is redundant. 2832 length The length (in bytes) of the following 2833 TLSCiphertext.fragment, which is the sum of the lengths of the 2834 content and the padding, plus one for the inner content type. The 2835 length MUST NOT exceed 2^14 + 256. An endpoint that receives a 2836 record that exceeds this length MUST generate a fatal 2837 "record_overflow" alert. 2839 encrypted_record The AEAD encrypted form of the serialized 2840 TLSInnerPlaintext structure. 2842 AEAD ciphers take as input a single key, a nonce, a plaintext, and 2843 "additional data" to be included in the authentication check, as 2844 described in Section 2.1 of [RFC5116]. The key is either the 2845 client_write_key or the server_write_key, the nonce is derived from 2846 the sequence number (see Section 5.3) and the client_write_iv or 2847 server_write_iv, and the additional data input is empty (zero 2848 length). Derivation of traffic keys is defined in Section 7.3. 2850 The plaintext is the concatenation of TLSPlaintext.fragment, 2851 TLSPlaintext.type, and any padding bytes (zeros). 2853 The AEAD output consists of the ciphertext output by the AEAD 2854 encryption operation. The length of the plaintext is greater than 2855 TLSPlaintext.length due to the inclusion of TLSPlaintext.type and 2856 however much padding is supplied by the sender. The length of the 2857 AEAD output will generally be larger than the plaintext, but by an 2858 amount that varies with the AEAD cipher. Since the ciphers might 2859 incorporate padding, the amount of overhead could vary with different 2860 lengths of plaintext. Symbolically, 2862 AEADEncrypted = 2863 AEAD-Encrypt(write_key, nonce, plaintext of fragment) 2865 In order to decrypt and verify, the cipher takes as input the key, 2866 nonce, and the AEADEncrypted value. The output is either the 2867 plaintext or an error indicating that the decryption failed. There 2868 is no separate integrity check. That is: 2870 plaintext of fragment = 2871 AEAD-Decrypt(write_key, nonce, AEADEncrypted) 2873 If the decryption fails, a fatal "bad_record_mac" alert MUST be 2874 generated. 2876 An AEAD cipher MUST NOT produce an expansion of greater than 255 2877 bytes. An endpoint that receives a record from its peer with 2878 TLSCipherText.length larger than 2^14 + 256 octets MUST generate a 2879 fatal "record_overflow" alert. This limit is derived from the 2880 maximum TLSPlaintext length of 2^14 octets + 1 octet for ContentType 2881 + the maximum AEAD expansion of 255 octets. 2883 5.3. Per-Record Nonce 2885 A 64-bit sequence number is maintained separately for reading and 2886 writing records. Each sequence number is set to zero at the 2887 beginning of a connection and whenever the key is changed. 2889 The sequence number is incremented after reading or writing each 2890 record. The first record transmitted under a particular set of 2891 traffic keys record key MUST use sequence number 0. 2893 Sequence numbers do not wrap. If a TLS implementation would need to 2894 wrap a sequence number, it MUST either rekey (Section 4.4.3) or 2895 terminate the connection. 2897 The length of the per-record nonce (iv_length) is set to max(8 bytes, 2898 N_MIN) for the AEAD algorithm (see [RFC5116] Section 4). An AEAD 2899 algorithm where N_MAX is less than 8 bytes MUST NOT be used with TLS. 2900 The per-record nonce for the AEAD construction is formed as follows: 2902 1. The 64-bit record sequence number is padded to the left with 2903 zeroes to iv_length. 2905 2. The padded sequence number is XORed with the static 2906 client_write_iv or server_write_iv, depending on the role. 2908 The resulting quantity (of length iv_length) is used as the per- 2909 record nonce. 2911 Note: This is a different construction from that in TLS 1.2, which 2912 specified a partially explicit nonce. 2914 5.4. Record Padding 2916 All encrypted TLS records can be padded to inflate the size of the 2917 TLSCipherText. This allows the sender to hide the size of the 2918 traffic from an observer. 2920 When generating a TLSCiphertext record, implementations MAY choose to 2921 pad. An unpadded record is just a record with a padding length of 2922 zero. Padding is a string of zero-valued bytes appended to the 2923 ContentType field before encryption. Implementations MUST set the 2924 padding octets to all zeros before encrypting. 2926 Application Data records may contain a zero-length fragment.content 2927 if the sender desires. This permits generation of plausibly-sized 2928 cover traffic in contexts where the presence or absence of activity 2929 may be sensitive. Implementations MUST NOT send Handshake or Alert 2930 records that have a zero-length fragment.content. 2932 The padding sent is automatically verified by the record protection 2933 mechanism: Upon successful decryption of a TLSCiphertext.fragment, 2934 the receiving implementation scans the field from the end toward the 2935 beginning until it finds a non-zero octet. This non-zero octet is 2936 the content type of the message. This padding scheme was selected 2937 because it allows padding of any encrypted TLS record by an arbitrary 2938 size (from zero up to TLS record size limits) without introducing new 2939 content types. The design also enforces all-zero padding octets, 2940 which allows for quick detection of padding errors. 2942 Implementations MUST limit their scanning to the cleartext returned 2943 from the AEAD decryption. If a receiving implementation does not 2944 find a non-zero octet in the cleartext, it should treat the record as 2945 having an unexpected ContentType, sending an "unexpected_message" 2946 alert. 2948 The presence of padding does not change the overall record size 2949 limitations - the full fragment plaintext may not exceed 2^14 octets. 2951 Selecting a padding policy that suggests when and how much to pad is 2952 a complex topic, and is beyond the scope of this specification. If 2953 the application layer protocol atop TLS has its own padding padding, 2954 it may be preferable to pad application_data TLS records within the 2955 application layer. Padding for encrypted handshake and alert TLS 2956 records must still be handled at the TLS layer, though. Later 2957 documents may define padding selection algorithms, or define a 2958 padding policy request mechanism through TLS extensions or some other 2959 means. 2961 5.5. Limits on Key Usage 2963 There are cryptographic limits on the amount of plaintext which can 2964 be safely encrypted under a given set of keys. [AEAD-LIMITS] 2965 provides an analysis of these limits under the assumption that the 2966 underlying primitive (AES or ChaCha20) has no weaknesses. 2967 Implementations SHOULD do a key update Section 4.4.3 prior to 2968 reaching these limits. 2970 For AES-GCM, up to 2^24.5 full-size records may be encrypted on a 2971 given connection while keeping a safety margin of approximately 2^-57 2972 for Authenticated Encryption (AE) security. For ChaCha20/Poly1305, 2973 the record sequence number will wrap before the safety limit is 2974 reached. 2976 6. Alert Protocol 2978 One of the content types supported by the TLS record layer is the 2979 alert type. Like other messages, alert messages are encrypted as 2980 specified by the current connection state. 2982 Alert messages convey the severity of the message (warning or fatal) 2983 and a description of the alert. Warning-level messages are used to 2984 indicate orderly closure of the connection (see Section 6.1). Upon 2985 receiving a warning-level alert, the TLS implementation SHOULD 2986 indicate end-of-data to the application and, if appropriate for the 2987 alert type, send a closure alert in response. 2989 Fatal-level messages are used to indicate abortive closure of the 2990 connection (See Section 6.2). Upon receiving a fatal-level alert, 2991 the TLS implementation SHOULD indicate an error to the application 2992 and MUST NOT allow any further data to be sent or received on the 2993 connection. Servers and clients MUST forget keys and secrets 2994 associated with a failed connection. Stateful implementations of 2995 session tickets (as in many clients) SHOULD discard tickets 2996 associated with failed connections. 2998 All the alerts listed in Section 6.2 MUST be sent as fatal and MUST 2999 be treated as fatal regardless of the AlertLevel in the message. 3000 Unknown alert types MUST be treated as fatal. 3002 enum { warning(1), fatal(2), (255) } AlertLevel; 3004 enum { 3005 close_notify(0), 3006 end_of_early_data(1), 3007 unexpected_message(10), 3008 bad_record_mac(20), 3009 record_overflow(22), 3010 handshake_failure(40), 3011 bad_certificate(42), 3012 unsupported_certificate(43), 3013 certificate_revoked(44), 3014 certificate_expired(45), 3015 certificate_unknown(46), 3016 illegal_parameter(47), 3017 unknown_ca(48), 3018 access_denied(49), 3019 decode_error(50), 3020 decrypt_error(51), 3021 protocol_version(70), 3022 insufficient_security(71), 3023 internal_error(80), 3024 inappropriate_fallback(86), 3025 user_canceled(90), 3026 missing_extension(109), 3027 unsupported_extension(110), 3028 certificate_unobtainable(111), 3029 unrecognized_name(112), 3030 bad_certificate_status_response(113), 3031 bad_certificate_hash_value(114), 3032 unknown_psk_identity(115), 3033 (255) 3034 } AlertDescription; 3036 struct { 3037 AlertLevel level; 3038 AlertDescription description; 3039 } Alert; 3041 6.1. Closure Alerts 3043 The client and the server must share knowledge that the connection is 3044 ending in order to avoid a truncation attack. Failure to properly 3045 close a connection does not prohibit a session from being resumed. 3047 close_notify This alert notifies the recipient that the sender will 3048 not send any more messages on this connection. Any data received 3049 after a closure MUST be ignored. 3051 end_of_early_data This alert is sent by the client to indicate that 3052 all 0-RTT application_data messages have been transmitted (or none 3053 will be sent at all) and that this is the end of the flight. This 3054 alert MUST be at the warning level. Servers MUST NOT send this 3055 alert and clients receiving it MUST terminate the connection with 3056 an "unexpected_message" alert. 3058 user_canceled This alert notifies the recipient that the sender is 3059 canceling the handshake for some reason unrelated to a protocol 3060 failure. If a user cancels an operation after the handshake is 3061 complete, just closing the connection by sending a "close_notify" 3062 is more appropriate. This alert SHOULD be followed by a 3063 "close_notify". This alert is generally a warning. 3065 Either party MAY initiate a close by sending a "close_notify" alert. 3066 Any data received after a closure alert is ignored. If a transport- 3067 level close is received prior to a "close_notify", the receiver 3068 cannot know that all the data that was sent has been received. 3070 Each party MUST send a "close_notify" alert before closing the write 3071 side of the connection, unless some other fatal alert has been 3072 transmitted. The other party MUST respond with a "close_notify" 3073 alert of its own and close down the connection immediately, 3074 discarding any pending writes. The initiator of the close need not 3075 wait for the responding "close_notify" alert before closing the read 3076 side of the connection. 3078 If the application protocol using TLS provides that any data may be 3079 carried over the underlying transport after the TLS connection is 3080 closed, the TLS implementation must receive the responding 3081 "close_notify" alert before indicating to the application layer that 3082 the TLS connection has ended. If the application protocol will not 3083 transfer any additional data, but will only close the underlying 3084 transport connection, then the implementation MAY choose to close the 3085 transport without waiting for the responding "close_notify". No part 3086 of this standard should be taken to dictate the manner in which a 3087 usage profile for TLS manages its data transport, including when 3088 connections are opened or closed. 3090 Note: It is assumed that closing a connection reliably delivers 3091 pending data before destroying the transport. 3093 6.2. Error Alerts 3095 Error handling in the TLS Handshake Protocol is very simple. When an 3096 error is detected, the detecting party sends a message to its peer. 3097 Upon transmission or receipt of a fatal alert message, both parties 3098 immediately close the connection. Whenever an implementation 3099 encounters a condition which is defined as a fatal alert, it MUST 3100 send the appropriate alert prior to closing the connection. All 3101 alerts defined in this section below, as well as all unknown alerts 3102 are universally considered fatal as of TLS 1.3 (see Section 6). 3104 The following error alerts are defined: 3106 unexpected_message An inappropriate message was received. This 3107 alert should never be observed in communication between proper 3108 implementations. 3110 bad_record_mac This alert is returned if a record is received which 3111 cannot be deprotected. Because AEAD algorithms combine decryption 3112 and verification, this alert is used for all deprotection 3113 failures. This alert should never be observed in communication 3114 between proper implementations, except when messages were 3115 corrupted in the network. 3117 record_overflow A TLSCiphertext record was received that had a 3118 length more than 2^14 + 256 bytes, or a record decrypted to a 3119 TLSPlaintext record with more than 2^14 bytes. This alert should 3120 never be observed in communication between proper implementations, 3121 except when messages were corrupted in the network. 3123 handshake_failure Reception of a "handshake_failure" alert message 3124 indicates that the sender was unable to negotiate an acceptable 3125 set of security parameters given the options available. 3127 bad_certificate A certificate was corrupt, contained signatures that 3128 did not verify correctly, etc. 3130 unsupported_certificate A certificate was of an unsupported type. 3132 certificate_revoked A certificate was revoked by its signer. 3134 certificate_expired A certificate has expired or is not currently 3135 valid. 3137 certificate_unknown Some other (unspecified) issue arose in 3138 processing the certificate, rendering it unacceptable. 3140 illegal_parameter A field in the handshake was out of range or 3141 inconsistent with other fields. 3143 unknown_ca A valid certificate chain or partial chain was received, 3144 but the certificate was not accepted because the CA certificate 3145 could not be located or couldn't be matched with a known, trusted 3146 CA. 3148 access_denied A valid certificate or PSK was received, but when 3149 access control was applied, the sender decided not to proceed with 3150 negotiation. 3152 decode_error A message could not be decoded because some field was 3153 out of the specified range or the length of the message was 3154 incorrect. This alert should never be observed in communication 3155 between proper implementations, except when messages were 3156 corrupted in the network. 3158 decrypt_error A handshake cryptographic operation failed, including 3159 being unable to correctly verify a signature or validate a 3160 Finished message. 3162 protocol_version The protocol version the peer has attempted to 3163 negotiate is recognized but not supported. (see Appendix C) 3165 insufficient_security Returned instead of "handshake_failure" when a 3166 negotiation has failed specifically because the server requires 3167 ciphers more secure than those supported by the client. 3169 internal_error An internal error unrelated to the peer or the 3170 correctness of the protocol (such as a memory allocation failure) 3171 makes it impossible to continue. 3173 inappropriate_fallback Sent by a server in response to an invalid 3174 connection retry attempt from a client. (see [RFC7507]) 3176 missing_extension Sent by endpoints that receive a hello message not 3177 containing an extension that is mandatory to send for the offered 3178 TLS version. [[TODO: IANA Considerations.]] 3180 unsupported_extension Sent by endpoints receiving any hello message 3181 containing an extension known to be prohibited for inclusion in 3182 the given hello message, including any extensions in a ServerHello 3183 not first offered in the corresponding ClientHello. 3185 certificate_unobtainable Sent by servers when unable to obtain a 3186 certificate from a URL provided by the client via the 3187 "client_certificate_url" extension [RFC6066]. 3189 unrecognized_name Sent by servers when no server exists identified 3190 by the name provided by the client via the "server_name" extension 3191 [RFC6066]. 3193 bad_certificate_status_response Sent by clients when an invalid or 3194 unacceptable OCSP response is provided by the server via the 3195 "status_request" extension [RFC6066]. This alert is always fatal. 3197 bad_certificate_hash_value Sent by servers when a retrieved object 3198 does not have the correct hash provided by the client via the 3199 "client_certificate_url" extension [RFC6066]. 3201 unknown_psk_identity Sent by servers when PSK key establishment is 3202 desired but no acceptable PSK identity is provided by the client. 3203 Sending this alert is OPTIONAL; servers MAY instead choose to send 3204 a "decrypt_error" alert to merely indicate an invalid PSK 3205 identity. 3207 New Alert values are assigned by IANA as described in Section 10. 3209 7. Cryptographic Computations 3211 In order to begin connection protection, the TLS Record Protocol 3212 requires specification of a suite of algorithms, a master secret, and 3213 the client and server random values. 3215 7.1. Key Schedule 3217 The TLS handshake establishes one or more input secrets which are 3218 combined to create the actual working keying material, as detailed 3219 below. The key derivation process makes use of the HKDF-Extract and 3220 HKDF-Expand functions as defined for HKDF [RFC5869], as well as the 3221 functions defined below: 3223 HKDF-Expand-Label(Secret, Label, HashValue, Length) = 3224 HKDF-Expand(Secret, HkdfLabel, Length) 3226 Where HkdfLabel is specified as: 3228 struct HkdfLabel 3229 { 3230 uint16 length = Length; 3231 opaque label<9..255> = "TLS 1.3, " + Label; 3232 opaque hash_value<0..255> = HashValue; 3233 }; 3235 Derive-Secret(Secret, Label, Messages) = 3236 HKDF-Expand-Label(Secret, Label, 3237 Hash(Messages) + 3238 Hash(resumption_context), Hash.Length) 3240 The Hash function and the HKDF hash are the cipher suite hash 3241 function. Hash.Length is its output length. 3243 Given a set of n InputSecrets, the final "master secret" is computed 3244 by iteratively invoking HKDF-Extract with InputSecret_1, 3245 InputSecret_2, etc. The initial secret is simply a string of zeroes 3246 as long as the size of the Hash that is the basis for the HKDF. 3247 Concretely, for the present version of TLS 1.3, secrets are added in 3248 the following order: 3250 - PSK 3252 - (EC)DHE shared secret 3254 This produces a full key derivation schedule shown in the diagram 3255 below. In this diagram, the following formatting conventions apply: 3257 - HKDF-Extract is drawn as taking the Salt argument from the top and 3258 the IKM argument from the left. 3260 - Derive-Secret's Secret argument is indicated by the arrow coming 3261 in from the left. For instance, the Early Secret is the Secret 3262 for generating the early_traffic_secret. 3264 Note that the 0-RTT Finished message is not included in the Derive- 3265 Secret operation. 3267 0 3268 | 3269 v 3270 PSK -> HKDF-Extract 3271 | 3272 v 3273 Early Secret ---> Derive-Secret(., "early traffic secret", 3274 | ClientHello) 3275 | = early_traffic_secret 3276 v 3277 (EC)DHE -> HKDF-Extract 3278 | 3279 v 3280 Handshake 3281 Secret -----> Derive-Secret(., "handshake traffic secret", 3282 | ClientHello...ServerHello) 3283 | = handshake_traffic_secret 3284 v 3285 0 -> HKDF-Extract 3286 | 3287 v 3288 Master Secret 3289 | 3290 +---------> Derive-Secret(., "application traffic secret", 3291 | ClientHello...Server Finished) 3292 | = traffic_secret_0 3293 | 3294 +---------> Derive-Secret(., "exporter master secret", 3295 | ClientHello...Client Finished) 3296 | = exporter_secret 3297 | 3298 +---------> Derive-Secret(., "resumption master secret", 3299 ClientHello...Client Finished) 3300 = resumption_secret 3302 The general pattern here is that the secrets shown down the left side 3303 of the diagram are just raw entropy without context, whereas the 3304 secrets down the right side include handshake context and therefore 3305 can be used to derive working keys without additional context. Note 3306 that the different calls to Derive-Secret may take different Messages 3307 arguments, even with the same secret. In a 0-RTT exchange, Derive- 3308 Secret is called with four distinct transcripts; in a 1-RTT only 3309 exchange with three distinct transcripts. 3311 If a given secret is not available, then the 0-value consisting of a 3312 string of Hash.length zeroes is used. Note that this does not mean 3313 skipping rounds, so if PSK is not in use Early Secret will still be 3314 HKDF-Extract(0, 0). 3316 7.2. Updating Traffic Keys and IVs 3318 Once the handshake is complete, it is possible for either side to 3319 update its sending traffic keys using the KeyUpdate handshake message 3320 defined in Section 4.4.3. The next generation of traffic keys is 3321 computed by generating traffic_secret_N+1 from traffic_secret_N as 3322 described in this section then re-deriving the traffic keys as 3323 described in Section 7.3. 3325 The next-generation traffic_secret is computed as: 3327 traffic_secret_N+1 = HKDF-Expand-Label( 3328 traffic_secret_N, 3329 "application traffic secret", "", Hash.Length) 3331 Once traffic_secret_N+1 and its associated traffic keys have been 3332 computed, implementations SHOULD delete traffic_secret_N. Once the 3333 directional keys are no longer needed, they SHOULD be deleted as 3334 well. 3336 7.3. Traffic Key Calculation 3338 The traffic keying material is generated from the following input 3339 values: 3341 - A secret value 3343 - A phase value indicating the phase of the protocol the keys are 3344 being generated for 3346 - A purpose value indicating the specific value being generated 3348 - The length of the key 3350 The keying material is computed using: 3352 key = HKDF-Expand-Label(Secret, 3353 phase + ", " + purpose, 3354 "", 3355 key_length) 3357 The following table describes the inputs to the key calculation for 3358 each class of traffic keys: 3360 +-------------+--------------------------+--------------------------+ 3361 | Record Type | Secret | Phase | 3362 +-------------+--------------------------+--------------------------+ 3363 | 0-RTT | early_traffic_secret | "early handshake key | 3364 | Handshake | | expansion" | 3365 | | | | 3366 | 0-RTT | early_traffic_secret | "early application data | 3367 | Application | | key expansion" | 3368 | | | | 3369 | Handshake | handshake_traffic_secret | "handshake key | 3370 | | | expansion" | 3371 | | | | 3372 | Application | traffic_secret_N | "application data key | 3373 | Data | | expansion" | 3374 +-------------+--------------------------+--------------------------+ 3376 The following table indicates the purpose values for each type of 3377 key: 3379 +------------------+--------------------+ 3380 | Key Type | Purpose | 3381 +------------------+--------------------+ 3382 | client_write_key | "client write key" | 3383 | | | 3384 | server_write_key | "server write key" | 3385 | | | 3386 | client_write_iv | "client write iv" | 3387 | | | 3388 | server_write_iv | "server write iv" | 3389 +------------------+--------------------+ 3391 All the traffic keying material is recomputed whenever the underlying 3392 Secret changes (e.g., when changing from the handshake to application 3393 data keys or upon a key update). 3395 7.3.1. Diffie-Hellman 3397 A conventional Diffie-Hellman computation is performed. The 3398 negotiated key (Z) is converted to byte string by encoding in big- 3399 endian, padded with zeros up to the size of the prime. This byte 3400 string is used as the shared secret, and is used in the key schedule 3401 as specified above. 3403 Note that this construction differs from previous versions of TLS 3404 which remove leading zeros. 3406 7.3.2. Elliptic Curve Diffie-Hellman 3408 For secp256r1, secp384r1 and secp521r1, ECDH calculations (including 3409 parameter and key generation as well as the shared secret 3410 calculation) are performed according to [IEEE1363] using the ECKAS- 3411 DH1 scheme with the identity map as key derivation function (KDF), so 3412 that the shared secret is the x-coordinate of the ECDH shared secret 3413 elliptic curve point represented as an octet string. Note that this 3414 octet string (Z in IEEE 1363 terminology) as output by FE2OSP, the 3415 Field Element to Octet String Conversion Primitive, has constant 3416 length for any given field; leading zeros found in this octet string 3417 MUST NOT be truncated. 3419 (Note that this use of the identity KDF is a technicality. The 3420 complete picture is that ECDH is employed with a non-trivial KDF 3421 because TLS does not directly use this secret for anything other than 3422 for computing other secrets.) 3424 ECDH functions are used as follows: 3426 - The public key to put into the KeyShareEntry.key_exchange 3427 structure is the result of applying the ECDH function to the 3428 secret key of appropriate length (into scalar input) and the 3429 standard public basepoint (into u-coordinate point input). 3431 - The ECDH shared secret is the result of applying ECDH function to 3432 the secret key (into scalar input) and the peer's public key (into 3433 u-coordinate point input). The output is used raw, with no 3434 processing. 3436 For X25519 and X448, see [RFC7748]. 3438 7.3.3. Exporters 3440 [RFC5705] defines keying material exporters for TLS in terms of the 3441 TLS PRF. This document replaces the PRF with HKDF, thus requiring a 3442 new construction. The exporter interface remains the same, however 3443 the value is computed as: 3445 HKDF-Expand-Label(exporter_secret, 3446 label, context_value, key_length) 3448 8. Compliance Requirements 3449 8.1. MTI Cipher Suites 3451 In the absence of an application profile standard specifying 3452 otherwise, a TLS-compliant application MUST implement the 3453 TLS_AES_128_GCM_SHA256 cipher suite and SHOULD implement the 3454 TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 cipher 3455 suites. 3457 A TLS-compliant application MUST support digital signatures with 3458 rsa_pkcs1_sha256 (for certificates), rsa_pss_sha256 (for 3459 CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A 3460 TLS-compliant application MUST support key exchange with secp256r1 3461 (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748]. 3463 8.2. MTI Extensions 3465 In the absence of an application profile standard specifying 3466 otherwise, a TLS-compliant application MUST implement the following 3467 TLS extensions: 3469 - Signature Algorithms ("signature_algorithms"; Section 4.2.2) 3471 - Negotiated Groups ("supported_groups"; Section 4.2.3) 3473 - Key Share ("key_share"; Section 4.2.4) 3475 - Pre-Shared Key ("pre_shared_key"; Section 4.2.5) 3477 - Server Name Indication ("server_name"; Section 3 of [RFC6066]) 3479 - Cookie ("cookie"; Section 4.2.1) 3481 All implementations MUST send and use these extensions when offering 3482 applicable cipher suites: 3484 - "signature_algorithms" is REQUIRED for certificate authenticated 3485 cipher suites. 3487 - "supported_groups" and "key_share" are REQUIRED for DHE or ECDHE 3488 cipher suites. 3490 - "pre_shared_key" is REQUIRED for PSK cipher suites. 3492 - "cookie" is REQUIRED for all cipher suites. 3494 When negotiating use of applicable cipher suites, endpoints MUST 3495 abort the connection with a "missing_extension" alert if the required 3496 extension was not provided. Any endpoint that receives any invalid 3497 combination of cipher suites and extensions MAY abort the connection 3498 with a "missing_extension" alert, regardless of negotiated 3499 parameters. 3501 Additionally, all implementations MUST support use of the 3502 "server_name" extension with applications capable of using it. 3503 Servers MAY require clients to send a valid "server_name" extension. 3504 Servers requiring this extension SHOULD respond to a ClientHello 3505 lacking a "server_name" extension with a fatal "missing_extension" 3506 alert. 3508 Servers MUST NOT send the "signature_algorithms" extension; if a 3509 client receives this extension it MUST respond with a fatal 3510 "unsupported_extension" alert and close the connection. 3512 9. Security Considerations 3514 Security issues are discussed throughout this memo, especially in 3515 Appendices B, C, and D. 3517 10. IANA Considerations 3519 This document uses several registries that were originally created in 3520 [RFC4346]. IANA has updated these to reference this document. The 3521 registries and their allocation policies are below: 3523 - TLS Cipher Suite Registry: Values with the first byte in the range 3524 0-254 (decimal) are assigned via Specification Required [RFC2434]. 3525 Values with the first byte 255 (decimal) are reserved for Private 3526 Use [RFC2434]. IANA [SHALL add/has added] a "Recommended" column 3527 to the cipher suite registry. All cipher suites listed in 3528 Appendix A.4 are marked as "Yes". All other cipher suites are 3529 marked as "No". IANA [SHALL add/has added] add a note to this 3530 column reading: 3532 Cipher suites marked as "Yes" are those allocated via Standards 3533 Track RFCs. Cipher suites marked as "No" are not; cipher 3534 suites marked "No" range from "good" to "bad" from a 3535 cryptographic standpoint. 3537 - TLS ContentType Registry: Future values are allocated via 3538 Standards Action [RFC2434]. 3540 - TLS Alert Registry: Future values are allocated via Standards 3541 Action [RFC2434]. 3543 - TLS HandshakeType Registry: Future values are allocated via 3544 Standards Action [RFC2434]. IANA [SHALL update/has updated] this 3545 registry to rename item 4 from "NewSessionTicket" to 3546 "new_session_ticket". 3548 This document also uses a registry originally created in [RFC4366]. 3549 IANA has updated it to reference this document. The registry and its 3550 allocation policy is listed below: 3552 - TLS ExtensionType Registry: Values with the first byte in the 3553 range 0-254 (decimal) are assigned via Specification Required 3554 [RFC2434]. Values with the first byte 255 (decimal) are reserved 3555 for Private Use [RFC2434]. IANA [SHALL update/has updated] this 3556 registry to include the "key_share", "pre_shared_key", and 3557 "early_data" extensions as defined in this document. 3559 IANA [shall update/has updated] this registry to include a "TLS 3560 1.3" column with the following four values: "Client", indicating 3561 that the server shall not send them. "Clear", indicating that 3562 they shall be in the ServerHello. "Encrypted", indicating that 3563 they shall be in the EncryptedExtensions block, and "No" 3564 indicating that they are not used in TLS 1.3. This column [shall 3565 be/has been] initially populated with the values in this document. 3566 IANA [shall update/has updated] this registry to add a 3567 "Recommended" column. IANA [shall/has] initially populated this 3568 column with the values in the table below. This table has been 3569 generated by marking Standards Track RFCs as "Yes" and all others 3570 as "No". 3572 +-------------------------------+-----------+-----------------------+ 3573 | Extension | Recommend | TLS 1.3 | 3574 | | ed | | 3575 +-------------------------------+-----------+-----------------------+ 3576 | server_name [RFC6066] | Yes | Encrypted | 3577 | | | | 3578 | max_fragment_length [RFC6066] | Yes | Encrypted | 3579 | | | | 3580 | client_certificate_url | Yes | Encrypted | 3581 | [RFC6066] | | | 3582 | | | | 3583 | trusted_ca_keys [RFC6066] | Yes | Encrypted | 3584 | | | | 3585 | truncated_hmac [RFC6066] | Yes | No | 3586 | | | | 3587 | status_request [RFC6066] | Yes | Encrypted | 3588 | | | | 3589 | user_mapping [RFC4681] | Yes | Encrypted | 3590 | | | | 3591 | client_authz [RFC5878] | No | Encrypted | 3592 | | | | 3593 | server_authz [RFC5878] | No | Encrypted | 3594 | | | | 3595 | cert_type [RFC6091] | Yes | Encrypted | 3596 | | | | 3597 | supported_groups [RFC-ietf- | Yes | Encrypted | 3598 | tls-negotiated-ff-dhe] | | | 3599 | | | | 3600 | ec_point_formats [RFC4492] | Yes | No | 3601 | | | | 3602 | srp [RFC5054] | No | No | 3603 | | | | 3604 | signature_algorithms | Yes | Client | 3605 | [RFC5246] | | | 3606 | | | | 3607 | use_srtp [RFC5764] | Yes | Encrypted | 3608 | | | | 3609 | heartbeat [RFC6520] | Yes | Encrypted | 3610 | | | | 3611 | application_layer_protocol_ne | Yes | Encrypted | 3612 | gotiation [RFC7301] | | | 3613 | | | | 3614 | status_request_v2 [RFC6961] | Yes | Encrypted | 3615 | | | | 3616 | signed_certificate_timestamp | No | Encrypted | 3617 | [RFC6962] | | | 3618 | | | | 3619 | client_certificate_type | Yes | Encrypted | 3620 | [RFC7250] | | | 3621 | | | | 3622 | server_certificate_type | Yes | Encrypted | 3623 | [RFC7250] | | | 3624 | | | | 3625 | padding [RFC7685] | Yes | Client | 3626 | | | | 3627 | encrypt_then_mac [RFC7366] | Yes | No | 3628 | | | | 3629 | extended_master_secret | Yes | No | 3630 | [RFC7627] | | | 3631 | | | | 3632 | SessionTicket TLS [RFC4507] | Yes | No | 3633 | | | | 3634 | renegotiation_info [RFC5746] | Yes | No | 3635 | | | | 3636 | key_share [[this document]] | Yes | Clear | 3637 | | | | 3638 | pre_shared_key [[this | Yes | Clear | 3639 | document]] | | | 3640 | | | | 3641 | early_data [[this document]] | Yes | Encrypted | 3642 | | | | 3643 | cookie [[this document]] | Yes | Encrypted/HelloRetryR | 3644 | | | equest | 3645 +-------------------------------+-----------+-----------------------+ 3647 In addition, this document defines two new registries to be 3648 maintained by IANA 3650 - TLS SignatureScheme Registry: Values with the first byte in the 3651 range 0-254 (decimal) are assigned via Specification Required 3652 [RFC2434]. Values with the first byte 255 (decimal) are reserved 3653 for Private Use [RFC2434]. This registry SHALL have a 3654 "Recommended" column. The registry [shall be/ has been] initially 3655 populated with the values described in Section 4.2.2. The 3656 following values SHALL be marked as "Recommended": 3657 ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, rsa_pss_sha256, 3658 rsa_pss_sha384, rsa_pss_sha512, ed25519. 3660 11. References 3662 11.1. Normative References 3664 [AES] National Institute of Standards and Technology, 3665 "Specification for the Advanced Encryption Standard 3666 (AES)", NIST FIPS 197, November 2001. 3668 [DH] Diffie, W. and M. Hellman, "New Directions in 3669 Cryptography", IEEE Transactions on Information Theory, 3670 V.IT-22 n.6 , June 1977. 3672 [I-D.irtf-cfrg-eddsa] 3673 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 3674 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-06 3675 (work in progress), August 2016. 3677 [I-D.mattsson-tls-ecdhe-psk-aead] 3678 Mattsson, J. and D. Migault, "ECDHE_PSK with AES-GCM and 3679 AES-CCM Cipher Suites for Transport Layer Security (TLS)", 3680 draft-mattsson-tls-ecdhe-psk-aead-05 (work in progress), 3681 April 2016. 3683 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3684 Hashing for Message Authentication", RFC 2104, 3685 DOI 10.17487/RFC2104, February 1997, 3686 . 3688 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3689 Requirement Levels", BCP 14, RFC 2119, 3690 DOI 10.17487/RFC2119, March 1997, 3691 . 3693 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3694 IANA Considerations Section in RFCs", RFC 2434, 3695 DOI 10.17487/RFC2434, October 1998, 3696 . 3698 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3699 Standards (PKCS) #1: RSA Cryptography Specifications 3700 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 3701 2003, . 3703 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3704 Housley, R., and W. Polk, "Internet X.509 Public Key 3705 Infrastructure Certificate and Certificate Revocation List 3706 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3707 . 3709 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 3710 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 3711 DOI 10.17487/RFC5288, August 2008, 3712 . 3714 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3715 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3716 DOI 10.17487/RFC5289, August 2008, 3717 . 3719 [RFC5487] Badra, M., "Pre-Shared Key Cipher Suites for TLS with SHA- 3720 256/384 and AES Galois Counter Mode", RFC 5487, 3721 DOI 10.17487/RFC5487, March 2009, 3722 . 3724 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 3725 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 3726 March 2010, . 3728 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3729 Key Derivation Function (HKDF)", RFC 5869, 3730 DOI 10.17487/RFC5869, May 2010, 3731 . 3733 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 3734 Extensions: Extension Definitions", RFC 6066, 3735 DOI 10.17487/RFC6066, January 2011, 3736 . 3738 [RFC6209] Kim, W., Lee, J., Park, J., and D. Kwon, "Addition of the 3739 ARIA Cipher Suites to Transport Layer Security (TLS)", 3740 RFC 6209, DOI 10.17487/RFC6209, April 2011, 3741 . 3743 [RFC6367] Kanno, S. and M. Kanda, "Addition of the Camellia Cipher 3744 Suites to Transport Layer Security (TLS)", RFC 6367, 3745 DOI 10.17487/RFC6367, September 2011, 3746 . 3748 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 3749 Transport Layer Security (TLS)", RFC 6655, 3750 DOI 10.17487/RFC6655, July 2012, 3751 . 3753 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 3754 Multiple Certificate Status Request Extension", RFC 6961, 3755 DOI 10.17487/RFC6961, June 2013, 3756 . 3758 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 3759 Algorithm (DSA) and Elliptic Curve Digital Signature 3760 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 3761 2013, . 3763 [RFC7251] McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 3764 CCM Elliptic Curve Cryptography (ECC) Cipher Suites for 3765 TLS", RFC 7251, DOI 10.17487/RFC7251, June 2014, 3766 . 3768 [RFC7443] Patil, P., Reddy, T., Salgueiro, G., and M. Petit- 3769 Huguenin, "Application-Layer Protocol Negotiation (ALPN) 3770 Labels for Session Traversal Utilities for NAT (STUN) 3771 Usages", RFC 7443, DOI 10.17487/RFC7443, January 2015, 3772 . 3774 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 3775 for Security", RFC 7748, DOI 10.17487/RFC7748, January 3776 2016, . 3778 [RFC7905] Langley, A., Chang, W., Mavrogiannopoulos, N., 3779 Strombergson, J., and S. Josefsson, "ChaCha20-Poly1305 3780 Cipher Suites for Transport Layer Security (TLS)", 3781 RFC 7905, DOI 10.17487/RFC7905, June 2016, 3782 . 3784 [SHS] National Institute of Standards and Technology, U.S. 3785 Department of Commerce, "Secure Hash Standard", NIST FIPS 3786 PUB 180-4, March 2012. 3788 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 3789 Specification of Basic Encoding Rules (BER), Canonical 3790 Encoding Rules (CER) and Distinguished Encoding Rules 3791 (DER)", ISO/IEC 8825-1:2002, 2002. 3793 [X962] ANSI, "Public Key Cryptography For The Financial Services 3794 Industry: The Elliptic Curve Digital Signature Algorithm 3795 (ECDSA)", ANSI X9.62, 1998. 3797 11.2. Informative References 3799 [AEAD-LIMITS] 3800 Luykx, A. and K. Paterson, "Limits on Authenticated 3801 Encryption Use in TLS", 2016, 3802 . 3804 [BBFKZG16] 3805 Bhargavan, K., Brzuska, C., Fournet, C., Kohlweiss, M., 3806 Zanella-Beguelin, S., and M. Green, "Downgrade Resilience 3807 in Key-Exchange Protocols", Proceedings of IEEE Symposium 3808 on Security and Privacy (Oakland) 2016 , 2016. 3810 [CHSV16] Cremers, C., Horvat, M., Scott, S., and T. van der Merwe, 3811 "Automated Analysis and Verification of TLS 1.3: 0-RTT, 3812 Resumption and Delayed Authentication", Proceedings of 3813 IEEE Symposium on Security and Privacy (Oakland) 2016 , 3814 2016. 3816 [CK01] Canetti, R. and H. Krawczyk, "Analysis of Key-Exchange 3817 Protocols and Their Use for Building Secure Channels", 3818 Proceedings of Eurocrypt 2001 , 2001. 3820 [DOW92] Diffie, W., van Oorschot, P., and M. Wiener, 3821 ""Authentication and authenticated key exchanges"", 3822 Designs, Codes and Cryptography , n.d.. 3824 [DSS] National Institute of Standards and Technology, U.S. 3825 Department of Commerce, "Digital Signature Standard, 3826 version 4", NIST FIPS PUB 186-4, 2013. 3828 [ECDSA] American National Standards Institute, "Public Key 3829 Cryptography for the Financial Services Industry: The 3830 Elliptic Curve Digital Signature Algorithm (ECDSA)", 3831 ANSI ANS X9.62-2005, November 2005. 3833 [FGSW16] Fischlin, M., Guenther, F., Schmidt, B., and B. Warinschi, 3834 "Key Confirmation in Key Exchange: A Formal Treatment and 3835 Implications for TLS 1.3", Proceedings of IEEE Symposium 3836 on Security and Privacy (Oakland) 2016 , 2016. 3838 [FI06] Finney, H., "Bleichenbacher's RSA signature forgery based 3839 on implementation error", August 2006, 3840 . 3843 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 3844 Operation: Galois/Counter Mode (GCM) and GMAC", 3845 NIST Special Publication 800-38D, November 2007. 3847 [I-D.ietf-tls-negotiated-ff-dhe] 3848 Gillmor, D., "Negotiated Finite Field Diffie-Hellman 3849 Ephemeral Parameters for TLS", draft-ietf-tls-negotiated- 3850 ff-dhe-10 (work in progress), June 2015. 3852 [IEEE1363] 3853 IEEE, "Standard Specifications for Public Key 3854 Cryptography", IEEE 1363 , 2000. 3856 [LXZFH16] Li, X., Xu, J., Feng, D., Zhang, Z., and H. Hu, "Multiple 3857 Handshakes Security of TLS 1.3 Candidates", Proceedings of 3858 IEEE Symposium on Security and Privacy (Oakland) 2016 , 3859 2016. 3861 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate 3862 Syntax Standard, version 1.5", November 1993. 3864 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message 3865 Syntax Standard, version 1.5", November 1993. 3867 [PSK-FINISHED] 3868 Cremers, C., Horvat, M., van der Merwe, T., and S. Scott, 3869 "Revision 10: possible attack if client authentication is 3870 allowed during PSK", 2015, . 3873 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3874 RFC 793, DOI 10.17487/RFC0793, September 1981, 3875 . 3877 [RFC1948] Bellovin, S., "Defending Against Sequence Number Attacks", 3878 RFC 1948, DOI 10.17487/RFC1948, May 1996, 3879 . 3881 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 3882 Text on Security Considerations", BCP 72, RFC 3552, 3883 DOI 10.17487/RFC3552, July 2003, 3884 . 3886 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 3887 "Randomness Requirements for Security", BCP 106, RFC 4086, 3888 DOI 10.17487/RFC4086, June 2005, 3889 . 3891 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 3892 Ciphersuites for Transport Layer Security (TLS)", 3893 RFC 4279, DOI 10.17487/RFC4279, December 2005, 3894 . 3896 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 3897 DOI 10.17487/RFC4302, December 2005, 3898 . 3900 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 3901 RFC 4303, DOI 10.17487/RFC4303, December 2005, 3902 . 3904 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 3905 (TLS) Protocol Version 1.1", RFC 4346, 3906 DOI 10.17487/RFC4346, April 2006, 3907 . 3909 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 3910 and T. Wright, "Transport Layer Security (TLS) 3911 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006, 3912 . 3914 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 3915 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 3916 for Transport Layer Security (TLS)", RFC 4492, 3917 DOI 10.17487/RFC4492, May 2006, 3918 . 3920 [RFC4506] Eisler, M., Ed., "XDR: External Data Representation 3921 Standard", STD 67, RFC 4506, DOI 10.17487/RFC4506, May 3922 2006, . 3924 [RFC4507] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 3925 "Transport Layer Security (TLS) Session Resumption without 3926 Server-Side State", RFC 4507, DOI 10.17487/RFC4507, May 3927 2006, . 3929 [RFC4681] Santesson, S., Medvinsky, A., and J. Ball, "TLS User 3930 Mapping Extension", RFC 4681, DOI 10.17487/RFC4681, 3931 October 2006, . 3933 [RFC5054] Taylor, D., Wu, T., Mavrogiannopoulos, N., and T. Perrin, 3934 "Using the Secure Remote Password (SRP) Protocol for TLS 3935 Authentication", RFC 5054, DOI 10.17487/RFC5054, November 3936 2007, . 3938 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 3939 "Transport Layer Security (TLS) Session Resumption without 3940 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 3941 January 2008, . 3943 [RFC5081] Mavrogiannopoulos, N., "Using OpenPGP Keys for Transport 3944 Layer Security (TLS) Authentication", RFC 5081, 3945 DOI 10.17487/RFC5081, November 2007, 3946 . 3948 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 3949 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 3950 . 3952 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3953 (TLS) Protocol Version 1.2", RFC 5246, 3954 DOI 10.17487/RFC5246, August 2008, 3955 . 3957 [RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov, 3958 "Transport Layer Security (TLS) Renegotiation Indication 3959 Extension", RFC 5746, DOI 10.17487/RFC5746, February 2010, 3960 . 3962 [RFC5763] Fischl, J., Tschofenig, H., and E. Rescorla, "Framework 3963 for Establishing a Secure Real-time Transport Protocol 3964 (SRTP) Security Context Using Datagram Transport Layer 3965 Security (DTLS)", RFC 5763, DOI 10.17487/RFC5763, May 3966 2010, . 3968 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 3969 Security (DTLS) Extension to Establish Keys for the Secure 3970 Real-time Transport Protocol (SRTP)", RFC 5764, 3971 DOI 10.17487/RFC5764, May 2010, 3972 . 3974 [RFC5878] Brown, M. and R. Housley, "Transport Layer Security (TLS) 3975 Authorization Extensions", RFC 5878, DOI 10.17487/RFC5878, 3976 May 2010, . 3978 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 3979 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010, 3980 . 3982 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys 3983 for Transport Layer Security (TLS) Authentication", 3984 RFC 6091, DOI 10.17487/RFC6091, February 2011, 3985 . 3987 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 3988 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176, March 3989 2011, . 3991 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3992 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 3993 January 2012, . 3995 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 3996 Layer Security (TLS) and Datagram Transport Layer Security 3997 (DTLS) Heartbeat Extension", RFC 6520, 3998 DOI 10.17487/RFC6520, February 2012, 3999 . 4001 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 4002 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 4003 . 4005 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 4006 Protocol (HTTP/1.1): Message Syntax and Routing", 4007 RFC 7230, DOI 10.17487/RFC7230, June 2014, 4008 . 4010 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4011 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4012 Transport Layer Security (TLS) and Datagram Transport 4013 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4014 June 2014, . 4016 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 4017 "Transport Layer Security (TLS) Application-Layer Protocol 4018 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 4019 July 2014, . 4021 [RFC7366] Gutmann, P., "Encrypt-then-MAC for Transport Layer 4022 Security (TLS) and Datagram Transport Layer Security 4023 (DTLS)", RFC 7366, DOI 10.17487/RFC7366, September 2014, 4024 . 4026 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 4027 DOI 10.17487/RFC7465, February 2015, 4028 . 4030 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 4031 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 4032 DOI 10.17487/RFC7568, June 2015, 4033 . 4035 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 4036 Langley, A., and M. Ray, "Transport Layer Security (TLS) 4037 Session Hash and Extended Master Secret Extension", 4038 RFC 7627, DOI 10.17487/RFC7627, September 2015, 4039 . 4041 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello 4042 Padding Extension", RFC 7685, DOI 10.17487/RFC7685, 4043 October 2015, . 4045 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4046 (TLS) Cached Information Extension", RFC 7924, 4047 DOI 10.17487/RFC7924, July 2016, 4048 . 4050 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 4051 Obtaining Digital Signatures and Public-Key 4052 Cryptosystems", Communications of the ACM v. 21, n. 2, pp. 4053 120-126., February 1978. 4055 [SIGMA] Krawczyk, H., "SIGMA: the 'SIGn-and-MAc' approach to 4056 authenticated Di e-Hellman and its use in the IKE 4057 protocols", Proceedings of CRYPTO 2003 , 2003. 4059 [SLOTH] Bhargavan, K. and G. Leurent, "Transcript Collision 4060 Attacks: Breaking Authentication in TLS, IKE, and SSH", 4061 Network and Distributed System Security Symposium (NDSS 4062 2016) , 2016. 4064 [SSL2] Hickman, K., "The SSL Protocol", February 1995. 4066 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 4067 Protocol", November 1996. 4069 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 4070 practical", USENIX Security Symposium, 2003. 4072 [X501] "Information Technology - Open Systems Interconnection - 4073 The Directory: Models", ITU-T X.501, 1993. 4075 11.3. URIs 4077 [1] mailto:tls@ietf.org 4079 Appendix A. Protocol Data Structures and Constant Values 4081 This section describes protocol types and constants. Values listed 4082 as _RESERVED were used in previous versions of TLS and are listed 4083 here for completeness. TLS 1.3 implementations MUST NOT send them 4084 but might receive them from older TLS implementations. 4086 A.1. Record Layer 4088 enum { 4089 invalid_RESERVED(0), 4090 change_cipher_spec_RESERVED(20), 4091 alert(21), 4092 handshake(22), 4093 application_data(23) 4094 (255) 4095 } ContentType; 4097 struct { 4098 ContentType type; 4099 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 4100 uint16 length; 4101 opaque fragment[TLSPlaintext.length]; 4102 } TLSPlaintext; 4104 struct { 4105 opaque content[TLSPlaintext.length]; 4106 ContentType type; 4107 uint8 zeros[length_of_padding]; 4108 } TLSInnerPlaintext; 4110 struct { 4111 ContentType opaque_type = application_data(23); /* see fragment.type */ 4112 ProtocolVersion legacy_record_version = { 3, 1 }; /* TLS v1.x */ 4113 uint16 length; 4114 opaque encrypted_record[length]; 4115 } TLSCiphertext; 4117 A.2. Alert Messages 4118 enum { warning(1), fatal(2), (255) } AlertLevel; 4120 enum { 4121 close_notify(0), 4122 end_of_early_data(1), 4123 unexpected_message(10), 4124 bad_record_mac(20), 4125 decryption_failed_RESERVED(21), 4126 record_overflow(22), 4127 decompression_failure_RESERVED(30), 4128 handshake_failure(40), 4129 no_certificate_RESERVED(41), 4130 bad_certificate(42), 4131 unsupported_certificate(43), 4132 certificate_revoked(44), 4133 certificate_expired(45), 4134 certificate_unknown(46), 4135 illegal_parameter(47), 4136 unknown_ca(48), 4137 access_denied(49), 4138 decode_error(50), 4139 decrypt_error(51), 4140 export_restriction_RESERVED(60), 4141 protocol_version(70), 4142 insufficient_security(71), 4143 internal_error(80), 4144 inappropriate_fallback(86), 4145 user_canceled(90), 4146 no_renegotiation_RESERVED(100), 4147 missing_extension(109), 4148 unsupported_extension(110), 4149 certificate_unobtainable(111), 4150 unrecognized_name(112), 4151 bad_certificate_status_response(113), 4152 bad_certificate_hash_value(114), 4153 unknown_psk_identity(115), 4154 (255) 4155 } AlertDescription; 4157 struct { 4158 AlertLevel level; 4159 AlertDescription description; 4160 } Alert; 4162 A.3. Handshake Protocol 4164 enum { 4165 hello_request_RESERVED(0), 4166 client_hello(1), 4167 server_hello(2), 4168 new_session_ticket(4), 4169 hello_retry_request(6), 4170 encrypted_extensions(8), 4171 certificate(11), 4172 server_key_exchange_RESERVED(12), 4173 certificate_request(13), 4174 server_hello_done_RESERVED(14), 4175 certificate_verify(15), 4176 client_key_exchange_RESERVED(16), 4177 finished(20), 4178 key_update(24), 4179 (255) 4180 } HandshakeType; 4182 struct { 4183 HandshakeType msg_type; /* handshake type */ 4184 uint24 length; /* bytes in message */ 4185 select (HandshakeType) { 4186 case client_hello: ClientHello; 4187 case server_hello: ServerHello; 4188 case hello_retry_request: HelloRetryRequest; 4189 case encrypted_extensions: EncryptedExtensions; 4190 case certificate_request: CertificateRequest; 4191 case certificate: Certificate; 4192 case certificate_verify: CertificateVerify; 4193 case finished: Finished; 4194 case new_session_ticket: NewSessionTicket; 4195 case key_update: KeyUpdate; 4196 } body; 4197 } Handshake; 4199 A.3.1. Key Exchange Messages 4201 struct { 4202 uint8 major; 4203 uint8 minor; 4204 } ProtocolVersion; 4206 struct { 4207 opaque random_bytes[32]; 4208 } Random; 4209 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 4211 struct { 4212 ProtocolVersion max_supported_version = { 3, 4 }; /* TLS v1.3 */ 4213 Random random; 4214 opaque legacy_session_id<0..32>; 4215 CipherSuite cipher_suites<2..2^16-2>; 4216 opaque legacy_compression_methods<1..2^8-1>; 4217 Extension extensions<0..2^16-1>; 4218 } ClientHello; 4220 struct { 4221 ProtocolVersion version; 4222 Random random; 4223 CipherSuite cipher_suite; 4224 Extension extensions<0..2^16-1>; 4225 } ServerHello; 4227 struct { 4228 ProtocolVersion server_version; 4229 NamedGroup selected_group; 4230 Extension extensions<0..2^16-1>; 4231 } HelloRetryRequest; 4233 struct { 4234 ExtensionType extension_type; 4235 opaque extension_data<0..2^16-1>; 4236 } Extension; 4238 enum { 4239 supported_groups(10), 4240 signature_algorithms(13), 4241 key_share(40), 4242 pre_shared_key(41), 4243 early_data(42), 4244 cookie(44), 4245 (65535) 4246 } ExtensionType; 4248 struct { 4249 NamedGroup group; 4250 opaque key_exchange<1..2^16-1>; 4251 } KeyShareEntry; 4253 struct { 4254 select (role) { 4255 case client: 4256 KeyShareEntry client_shares<0..2^16-1>; 4258 case server: 4259 KeyShareEntry server_share; 4260 } 4261 } KeyShare; 4263 enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeModes; 4264 enum { psk_auth(0), psk_sign_auth(1), (255) } PskAuthenticationModes; 4266 opaque psk_identity<0..2^16-1>; 4268 struct { 4269 PskKeMode ke_modes<1..255>; 4270 PskAuthMode auth_modes<1..255>; 4271 opaque identity<0..2^16-1>; 4272 } PskIdentity; 4274 struct { 4275 select (Role) { 4276 case client: 4277 psk_identity identities<2..2^16-1>; 4279 case server: 4280 uint16 selected_identity; 4281 } 4282 } PreSharedKeyExtension; 4284 struct { 4285 select (Role) { 4286 case client: 4287 uint32 obfuscated_ticket_age; 4289 case server: 4290 struct {}; 4291 } 4292 } EarlyDataIndication; 4294 A.3.1.1. Cookie Extension 4296 struct { 4297 opaque cookie<0..2^16-1>; 4298 } Cookie; 4300 A.3.1.2. Signature Algorithm Extension 4301 enum { 4302 /* RSASSA-PKCS1-v1_5 algorithms */ 4303 rsa_pkcs1_sha1 (0x0201), 4304 rsa_pkcs1_sha256 (0x0401), 4305 rsa_pkcs1_sha384 (0x0501), 4306 rsa_pkcs1_sha512 (0x0601), 4308 /* ECDSA algorithms */ 4309 ecdsa_secp256r1_sha256 (0x0403), 4310 ecdsa_secp384r1_sha384 (0x0503), 4311 ecdsa_secp521r1_sha512 (0x0603), 4313 /* RSASSA-PSS algorithms */ 4314 rsa_pss_sha256 (0x0700), 4315 rsa_pss_sha384 (0x0701), 4316 rsa_pss_sha512 (0x0702), 4318 /* EdDSA algorithms */ 4319 ed25519 (0x0703), 4320 ed448 (0x0704), 4322 /* Reserved Code Points */ 4323 dsa_sha1_RESERVED (0x0202), 4324 dsa_sha256_RESERVED (0x0402), 4325 dsa_sha384_RESERVED (0x0502), 4326 dsa_sha512_RESERVED (0x0602), 4327 ecdsa_sha1_RESERVED (0x0203), 4328 obsolete_RESERVED (0x0000..0x0200), 4329 obsolete_RESERVED (0x0204..0x0400), 4330 obsolete_RESERVED (0x0404..0x0500), 4331 obsolete_RESERVED (0x0504..0x0600), 4332 obsolete_RESERVED (0x0604..0x06FF), 4333 private_use (0xFE00..0xFFFF), 4334 (0xFFFF) 4335 } SignatureScheme; 4337 SignatureScheme supported_signature_algorithms<2..2^16-2>; 4339 A.3.1.3. Supported Groups Extension 4340 enum { 4341 /* Elliptic Curve Groups (ECDHE) */ 4342 obsolete_RESERVED (1..22), 4343 secp256r1 (23), secp384r1 (24), secp521r1 (25), 4344 obsolete_RESERVED (26..28), 4345 x25519 (29), x448 (30), 4347 /* Finite Field Groups (DHE) */ 4348 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 4349 ffdhe6144 (259), ffdhe8192 (260), 4351 /* Reserved Code Points */ 4352 ffdhe_private_use (0x01FC..0x01FF), 4353 ecdhe_private_use (0xFE00..0xFEFF), 4354 obsolete_RESERVED (0xFF01..0xFF02), 4355 (0xFFFF) 4356 } NamedGroup; 4358 struct { 4359 NamedGroup named_group_list<1..2^16-1>; 4360 } NamedGroupList; 4362 Values within "obsolete_RESERVED" ranges were used in previous 4363 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3 4364 implementations. The obsolete curves have various known/theoretical 4365 weaknesses or have had very little usage, in some cases only due to 4366 unintentional server configuration issues. They are no longer 4367 considered appropriate for general use and should be assumed to be 4368 potentially unsafe. The set of curves specified here is sufficient 4369 for interoperability with all currently deployed and properly 4370 configured TLS implementations. 4372 A.3.1.4. Deprecated Extensions 4374 The following extensions are no longer applicable to TLS 1.3, 4375 although TLS 1.3 clients MAY send them if they are willing to 4376 negotiate them with prior versions of TLS. TLS 1.3 servers MUST 4377 ignore these extensions if they are negotiating TLS 1.3: 4378 truncated_hmac [RFC6066], srp [RFC5054], encrypt_then_mac [RFC7366], 4379 extended_master_secret [RFC7627], SessionTicket [RFC5077], and 4380 renegotiation_info [RFC5746]. 4382 A.3.2. Server Parameters Messages 4383 struct { 4384 Extension extensions<0..2^16-1>; 4385 } EncryptedExtensions; 4387 opaque DistinguishedName<1..2^16-1>; 4389 struct { 4390 opaque certificate_extension_oid<1..2^8-1>; 4391 opaque certificate_extension_values<0..2^16-1>; 4392 } CertificateExtension; 4394 struct { 4395 opaque certificate_request_context<0..2^8-1>; 4396 SignatureScheme 4397 supported_signature_algorithms<2..2^16-2>; 4398 DistinguishedName certificate_authorities<0..2^16-1>; 4399 CertificateExtension certificate_extensions<0..2^16-1>; 4400 } CertificateRequest; 4402 A.3.3. Authentication Messages 4404 opaque ASN1Cert<1..2^24-1>; 4406 struct { 4407 opaque certificate_request_context<0..2^8-1>; 4408 ASN1Cert certificate_list<0..2^24-1>; 4409 } Certificate; 4411 struct { 4412 SignatureScheme algorithm; 4413 opaque signature<0..2^16-1>; 4414 } CertificateVerify; 4416 struct { 4417 opaque verify_data[Hash.length]; 4418 } Finished; 4420 A.3.4. Ticket Establishment 4421 enum { (65535) } TicketExtensionType; 4423 struct { 4424 TicketExtensionType extension_type; 4425 opaque extension_data<1..2^16-1>; 4426 } TicketExtension; 4428 struct { 4429 uint32 ticket_lifetime; 4430 PskKeMode ke_modes<1..255>; 4431 PskAuthMode auth_modes<1..255>; 4432 opaque ticket<1..2^16-1>; 4433 TicketExtension extensions<0..2^16-2>; 4434 } NewSessionTicket; 4436 A.4. Cipher Suites 4438 A symmetric cipher suite defines the pair of the AEAD cipher and hash 4439 function to be used with HKDF. Cipher suites follow the naming 4440 convention: Cipher suite names follow the naming convention: 4442 CipherSuite TLS13_CIPHER_HASH = VALUE; 4444 +-----------+-------------------------------------------------+ 4445 | Component | Contents | 4446 +-----------+-------------------------------------------------+ 4447 | TLS | The string "TLS" | 4448 | | | 4449 | CIPHER | The symmetric cipher used for record protection | 4450 | | | 4451 | HASH | The hash algorithm used with HKDF | 4452 | | | 4453 | VALUE | The two byte ID assigned for this cipher suite | 4454 +-----------+-------------------------------------------------+ 4456 The "CIPHER" component commonly has sub-components used to designate 4457 the cipher name, bits, and mode, if applicable. For example, 4458 "AES_256_GCM" represents 256-bit AES in the GCM mode of operation. 4460 +------------------------------+-------------+---------------+ 4461 | Cipher Suite Name | Value | Specification | 4462 +------------------------------+-------------+---------------+ 4463 | TLS_AES_128_GCM_SHA256 | {0x13,0x01} | [This RFC] | 4464 | | | | 4465 | TLS_AES_256_GCM_SHA384 | {0x13,0x02} | [This RFC] | 4466 | | | | 4467 | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} | [This RFC] | 4468 | | | | 4469 | TLS_AES_128_CCM_SHA256 | {0x13,0x04} | [This RFC] | 4470 | | | | 4471 | TLS_AES_128_CCM_8_SHA256 | {0x13,0x05} | [This RFC] | 4472 +------------------------------+-------------+---------------+ 4474 Although TLS 1.3 uses the same cipher suite space as previous 4475 versions of TLS, TLS 1.3 cipher suites are defined differently, only 4476 specifying the symmetric ciphers, and cannot it be used for TLS 1.2. 4477 Similarly, TLS 1.2 and lower cipher suites cannot be used with TLS 4478 1.3. 4480 New cipher suite values are assigned by IANA as described in 4481 Section 10. 4483 A.4.1. Unauthenticated Operation 4485 Previous versions of TLS offered explicitly unauthenticated cipher 4486 suites based on anonymous Diffie-Hellman. These cipher suites have 4487 been deprecated in TLS 1.3. However, it is still possible to 4488 negotiate cipher suites that do not provide verifiable server 4489 authentication by several methods, including: 4491 - Raw public keys [RFC7250]. 4493 - Using a public key contained in a certificate but without 4494 validation of the certificate chain or any of its contents. 4496 Either technique used alone is are vulnerable to man-in-the-middle 4497 attacks and therefore unsafe for general use. However, it is also 4498 possible to bind such connections to an external authentication 4499 mechanism via out-of-band validation of the server's public key, 4500 trust on first use, or channel bindings [RFC5929]. [[NOTE: TLS 1.3 4501 needs a new channel binding definition that has not yet been 4502 defined.]] If no such mechanism is used, then the connection has no 4503 protection against active man-in-the-middle attack; applications MUST 4504 NOT use TLS in such a way absent explicit configuration or a specific 4505 application profile. 4507 Appendix B. Implementation Notes 4509 The TLS protocol cannot prevent many common security mistakes. This 4510 section provides several recommendations to assist implementors. 4512 B.1. API considerations for 0-RTT 4514 0-RTT data has very different security properties from data 4515 transmitted after a completed handshake: it can be replayed. 4516 Implementations SHOULD provide different functions for reading and 4517 writing 0-RTT data and data transmitted after the handshake, and 4518 SHOULD NOT automatically resend 0-RTT data if it is rejected by the 4519 server. 4521 B.2. Random Number Generation and Seeding 4523 TLS requires a cryptographically secure pseudorandom number generator 4524 (PRNG). In most cases, the operating system provides an appropriate 4525 facility such as /dev/urandom, which should be used absent other 4526 (performance) concerns. It is generally preferrable to use an 4527 existing PRNG implementation in preference to crafting a new one, and 4528 many adequate cryptographic libraries are already available under 4529 favorable license terms. Should those prove unsatisfactory, 4530 [RFC4086] provides guidance on the generation of random values. 4532 B.3. Certificates and Authentication 4534 Implementations are responsible for verifying the integrity of 4535 certificates and should generally support certificate revocation 4536 messages. Certificates should always be verified to ensure proper 4537 signing by a trusted Certificate Authority (CA). The selection and 4538 addition of trusted CAs should be done very carefully. Users should 4539 be able to view information about the certificate and root CA. 4541 B.4. Cipher Suite Support 4543 TLS supports a range of key sizes and security levels, including some 4544 that provide no or minimal security. A proper implementation will 4545 probably not support many cipher suites. Applications SHOULD also 4546 enforce minimum and maximum key sizes. For example, certification 4547 paths containing keys or signatures weaker than 2048-bit RSA or 4548 224-bit ECDSA are not appropriate for secure applications. See also 4549 Appendix C.4. 4551 B.5. Implementation Pitfalls 4553 Implementation experience has shown that certain parts of earlier TLS 4554 specifications are not easy to understand, and have been a source of 4555 interoperability and security problems. Many of these areas have 4556 been clarified in this document, but this appendix contains a short 4557 list of the most important things that require special attention from 4558 implementors. 4560 TLS protocol issues: 4562 - Do you correctly handle handshake messages that are fragmented to 4563 multiple TLS records (see Section 5.1)? Including corner cases 4564 like a ClientHello that is split to several small fragments? Do 4565 you fragment handshake messages that exceed the maximum fragment 4566 size? In particular, the certificate and certificate request 4567 handshake messages can be large enough to require fragmentation. 4569 - Do you ignore the TLS record layer version number in all TLS 4570 records? (see Appendix C) 4572 - Have you ensured that all support for SSL, RC4, EXPORT ciphers, 4573 and MD5 (via the "signature_algorithm" extension) is completely 4574 removed from all possible configurations that support TLS 1.3 or 4575 later, and that attempts to use these obsolete capabilities fail 4576 correctly? (see Appendix C) 4578 - Do you handle TLS extensions in ClientHello correctly, including 4579 unknown extensions or omitting the extensions field completely? 4581 - When the server has requested a client certificate, but no 4582 suitable certificate is available, do you correctly send an empty 4583 Certificate message, instead of omitting the whole message (see 4584 Section 4.3.1.2)? 4586 - When processing the plaintext fragment produced by AEAD-Decrypt 4587 and scanning from the end for the ContentType, do you avoid 4588 scanning past the start of the cleartext in the event that the 4589 peer has sent a malformed plaintext of all-zeros? 4591 - When processing a ClientHello containing a version of { 3, 5 } or 4592 higher, do you respond with the highest common version of TLS 4593 rather than requiring an exact match? Have you ensured this 4594 continues to be true with arbitrarily higher version numbers? 4595 (e.g. { 4, 0 }, { 9, 9 }, { 255, 255 }) 4597 - Do you properly ignore unrecognized cipher suites (Section 4.1.2), 4598 hello extensions (Section 4.2), named groups (Section 4.2.3), and 4599 signature algorithms (Section 4.2.2)? 4601 Cryptographic details: 4603 - What countermeasures do you use to prevent timing attacks against 4604 RSA signing operations [TIMING]? 4606 - When verifying RSA signatures, do you accept both NULL and missing 4607 parameters? Do you verify that the RSA padding doesn't have 4608 additional data after the hash value? [FI06] 4610 - When using Diffie-Hellman key exchange, do you correctly preserve 4611 leading zero bytes in the negotiated key (see Section 7.3.1)? 4613 - Does your TLS client check that the Diffie-Hellman parameters sent 4614 by the server are acceptable, (see Section 4.2.4.1)? 4616 - Do you use a strong and, most importantly, properly seeded random 4617 number generator (see Appendix B.2) when generating Diffie-Hellman 4618 private values, the ECDSA "k" parameter, and other security- 4619 critical values? It is RECOMMENDED that implementations implement 4620 "deterministic ECDSA" as specified in [RFC6979]. 4622 - Do you zero-pad Diffie-Hellman public key values to the group size 4623 (see Section 4.2.4.1)? 4625 B.6. Client Tracking Prevention 4627 Clients SHOULD NOT reuse a session ticket for multiple connections. 4628 Reuse of a session ticket allows passive observers to correlate 4629 different connections. Servers that issue session tickets SHOULD 4630 offer at least as many session tickets as the number of connections 4631 that a client might use; for example, a web browser using HTTP/1.1 4632 [RFC7230] might open six connections to a server. Servers SHOULD 4633 issue new session tickets with every connection. This ensures that 4634 clients are always able to use a new session ticket when creating a 4635 new connection. 4637 Appendix C. Backward Compatibility 4639 The TLS protocol provides a built-in mechanism for version 4640 negotiation between endpoints potentially supporting different 4641 versions of TLS. 4643 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 4644 also handle clients trying to use future versions of TLS as long as 4645 the ClientHello format remains compatible and the client supports the 4646 highest protocol version available in the server. 4648 Prior versions of TLS used the record layer version number for 4649 various purposes. (TLSPlaintext.legacy_record_version & 4650 TLSCiphertext.legacy_record_version) As of TLS 1.3, this field is 4651 deprecated and its value MUST be ignored by all implementations. 4652 Version negotiation is performed using only the handshake versions. 4653 (ClientHello.max_supported_version & ServerHello.version) In order to 4654 maximize interoperability with older endpoints, implementations that 4655 negotiate the use of TLS 1.0-1.2 SHOULD set the record layer version 4656 number to the negotiated version for the ServerHello and all records 4657 thereafter. 4659 For maximum compatibility with previously non-standard behavior and 4660 misconfigured deployments, all implementations SHOULD support 4661 validation of certification paths based on the expectations in this 4662 document, even when handling prior TLS versions' handshakes. (see 4663 Section 4.3.1.1) 4665 TLS 1.2 and prior supported an "Extended Master Secret" [RFC7627] 4666 extension which digested large parts of the handshake transcript into 4667 the master secret. Because TLS 1.3 always hashes in the transcript 4668 up to the server CertificateVerify, implementations which support 4669 both TLS 1.3 and earlier versions SHOULD indicate the use of the 4670 Extended Master Secret extension in their APIs whenever TLS 1.3 is 4671 used. 4673 C.1. Negotiating with an older server 4675 A TLS 1.3 client who wishes to negotiate with such older servers will 4676 send a normal TLS 1.3 ClientHello containing { 3, 4 } (TLS 1.3) in 4677 ClientHello.max_supported_version. If the server does not support 4678 this version it will respond with a ServerHello containing an older 4679 version number. If the client agrees to use this version, the 4680 negotiation will proceed as appropriate for the negotiated protocol. 4681 A client resuming a session SHOULD initiate the connection using the 4682 version that was previously negotiated. 4684 Note that 0-RTT data is not compatible with older servers. See 4685 Appendix C.3. 4687 If the version chosen by the server is not supported by the client 4688 (or not acceptable), the client MUST send a "protocol_version" alert 4689 message and close the connection. 4691 If a TLS server receives a ClientHello containing a version number 4692 greater than the highest version supported by the server, it MUST 4693 reply according to the highest version supported by the server. 4695 Some legacy server implementations are known to not implement the TLS 4696 specification properly and might abort connections upon encountering 4697 TLS extensions or versions which it is not aware of. 4698 Interoperability with buggy servers is a complex topic beyond the 4699 scope of this document. Multiple connection attempts may be required 4700 in order to negotiate a backwards compatible connection, however this 4701 practice is vulnerable to downgrade attacks and is NOT RECOMMENDED. 4703 C.2. Negotiating with an older client 4705 A TLS server can also receive a ClientHello containing a version 4706 number smaller than the highest supported version. If the server 4707 wishes to negotiate with old clients, it will proceed as appropriate 4708 for the highest version supported by the server that is not greater 4709 than ClientHello.max_supported_version. For example, if the server 4710 supports TLS 1.0, 1.1, and 1.2, and max_supported_version is TLS 1.0, 4711 the server will proceed with a TLS 1.0 ServerHello. If the server 4712 only supports versions greater than max_supported_version, it MUST 4713 send a "protocol_version" alert message and close the connection. 4715 Note that earlier versions of TLS did not clearly specify the record 4716 layer version number value in all cases 4717 (TLSPlaintext.legacy_record_version). Servers will receive various 4718 TLS 1.x versions in this field, however its value MUST always be 4719 ignored. 4721 C.3. Zero-RTT backwards compatibility 4723 0-RTT data is not compatible with older servers. An older server 4724 will respond to the ClientHello with an older ServerHello, but it 4725 will not correctly skip the 0-RTT data and fail to complete the 4726 handshake. This can cause issues when a client attempts to use 4727 0-RTT, particularly against multi-server deployments. For example, a 4728 deployment could deploy TLS 1.3 gradually with some servers 4729 implementing TLS 1.3 and some implementing TLS 1.2, or a TLS 1.3 4730 deployment could be downgraded to TLS 1.2. 4732 A client that attempts to send 0-RTT data MUST fail a connection if 4733 it receives a ServerHello with TLS 1.2 or older. A client that 4734 attempts to repair this error SHOULD NOT send a TLS 1.2 ClientHello, 4735 but instead send a TLS 1.3 ClientHello without 0-RTT data. 4737 To avoid this error condition, multi-server deployments SHOULD ensure 4738 a uniform and stable deployment of TLS 1.3 without 0-RTT prior to 4739 enabling 0-RTT. 4741 C.4. Backwards Compatibility Security Restrictions 4743 If an implementation negotiates use of TLS 1.2, then negotiation of 4744 cipher suites also supported by TLS 1.3 SHOULD be preferred, if 4745 available. 4747 The security of RC4 cipher suites is considered insufficient for the 4748 reasons cited in [RFC7465]. Implementations MUST NOT offer or 4749 negotiate RC4 cipher suites for any version of TLS for any reason. 4751 Old versions of TLS permitted the use of very low strength ciphers. 4752 Ciphers with a strength less than 112 bits MUST NOT be offered or 4753 negotiated for any version of TLS for any reason. 4755 The security of SSL 2.0 [SSL2] is considered insufficient for the 4756 reasons enumerated in [RFC6176], and MUST NOT be negotiated for any 4757 reason. 4759 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 4760 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 4761 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 4762 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 4763 order to negotiate older versions of TLS. 4765 Implementations MUST NOT send or accept any records with a version 4766 less than { 3, 0 }. 4768 The security of SSL 3.0 [SSL3] is considered insufficient for the 4769 reasons enumerated in [RFC7568], and MUST NOT be negotiated for any 4770 reason. 4772 Implementations MUST NOT send a ClientHello.max_supported_version or 4773 ServerHello.version set to { 3, 0 } or less. Any endpoint receiving 4774 a Hello message with ClientHello.max_supported_version or 4775 ServerHello.version set to { 3, 0 } MUST respond with a 4776 "protocol_version" alert message and close the connection. 4778 Implementations MUST NOT use the Truncated HMAC extension, defined in 4779 Section 7 of [RFC6066], as it is not applicable to AEAD ciphers and 4780 has been shown to be insecure in some scenarios. 4782 Appendix D. Overview of Security Properties 4784 [[TODO: This section is still a WIP and needs a bunch more work.]] 4786 A complete security analysis of TLS is outside the scope of this 4787 document. In this section, we provide an informal description the 4788 desired properties as well as references to more detailed work in the 4789 research literature which provides more formal definitions. 4791 We cover properties of the handshake separately from those of the 4792 record layer. 4794 D.1. Handshake 4796 The TLS handshake is an Authenticated Key Exchange (AKE) protocol 4797 which is intended to provide both one-way authenticated (server-only) 4798 and mutually authenticated (client and server) functionality. At the 4799 completion of the handshake, each side outputs its view on the 4800 following values: 4802 - A "session key" (the master secret) from which can be derived a 4803 set of working keys. 4805 - A set of cryptographic parameters (algorithms, etc.) 4807 - The identities of the communicating parties. 4809 We assume that the attacker has complete control of the network in 4810 between the parties [RFC3552]. Even under these conditions, the 4811 handshake should provide the properties listed below. Note that 4812 these properties are not necessarily independent, but reflect the 4813 protocol consumers' needs. 4815 Establishing the same session key. The handshake needs to output the 4816 same session key on both sides of the handshake, provided that it 4817 completes successfully on each endpoint (See [CK01]; defn 1, part 4818 1). 4820 Secrecy of the session key. The shared session key should be known 4821 only to the communicating parties, not to the attacker (See 4822 [CK01]; defn 1, part 2). Note that in a unilaterally 4823 authenticated connection, the attacker can establish its own 4824 session keys with the server, but those session keys are distinct 4825 from those established by the client. 4827 Peer Authentication. The client's view of the peer identity should 4828 reflect the server's identity. If the client is authenticated, 4829 the server's view of the peer identity should match the client's 4830 identity. 4832 Uniqueness of the session key: Any two distinct handshakes should 4833 produce distinct, unrelated session keys 4835 Downgrade protection. The cryptographic parameters should be the 4836 same on both sides and should be the same as if the peers had been 4837 communicating in the absence of an attack (See [BBFKZG16]; defns 8 4838 and 9}). 4840 Forward secret If the long-term keying material (in this case the 4841 signature keys in certificate-based authentication modes or the 4842 PSK in PSK-(EC)DHE modes) are compromised after the handshake is 4843 complete, this does not compromise the security of the session key 4844 (See [DOW92]). 4846 Protection of endpoint identities. The server's identity 4847 (certificate) should be protected against passive attackers. The 4848 client's identity should be protected against both passive and 4849 active attackers. 4851 Informally, the signature-based modes of TLS 1.3 provide for the 4852 establishment of a unique, secret, shared, key established by an 4853 (EC)DHE key exchange and authenticated by the server's signature over 4854 the handshake transcript, as well as tied to the server's identity by 4855 a MAC. If the client is authenticated by a certificate, it also 4856 signs over the handshake transcript and provides a MAC tied to both 4857 identities. [SIGMA] describes the analysis of this type of key 4858 exchange protocol. If fresh (EC)DHE keys are used for each 4859 connection, then the output keys are forward secret. 4861 The PSK and resumption-PSK modes bootstrap from a long-term shared 4862 secret into a unique per-connection short-term session key. This 4863 secret may have been established in a previous handshake. If 4864 PSK-(EC)DHE modes are used, this session key will also be forward 4865 secret. The resumption-PSK mode has been designed so that the 4866 resumption master secret computed by connection N and needed to form 4867 connection N+1 is separate from the traffic keys used by connection 4868 N, thus providing forward secrecy between the connections. 4870 For all handshake modes, the Finished MAC (and where present, the 4871 signature), prevents downgrade attacks. In addition, the use of 4872 certain bytes in the random nonces as described in Section 4.1.3 4873 allows the detection of downgrade to previous TLS versions. 4875 As soon as the client and the server have exchanged enough 4876 information to establish shared keys, the remainder of the handshake 4877 is encrypted, thus providing protection against passive attackers. 4878 Because the server authenticates before the client, the client can 4879 ensure that it only reveals its identity to an authenticated server. 4880 Note that implementations must use the provided record padding 4881 mechanism during the handshake to avoid leaking information about the 4882 identities due to length. 4884 The 0-RTT mode of operation generally provides the same security 4885 properties as 1-RTT data, with the two exceptions that the 0-RTT 4886 encryption keys do not provide full forward secrecy and that the the 4887 server is not able to guarantee full uniqueness of the handshake 4888 (non-replayability) without keeping potentially undue amounts of 4889 state. See Section 4.2.6 for one mechanism to limit the exposure to 4890 replay. 4892 The reader should refer to the following references for analysis of 4893 the TLS handshake [CHSV16] [FGSW16] [LXZFH16]. 4895 D.2. Record Layer 4897 The record layer depends on the handshake producing a strong session 4898 key which can be used to derive bidirectional traffic keys and 4899 nonces. Assuming that is true, and the keys are used for no more 4900 data than indicated in Section 5.5 then the record layer should 4901 provide the following guarantees: 4903 Confidentiality. An attacker should not be able to determine the 4904 plaintext contents of a given record. 4906 Integrity. An attacker should not be able to craft a new record 4907 which is different from an existing record which will be accepted 4908 by the receiver. 4910 Order protection/non-replayability An attacker should not be able to 4911 cause the receiver to accept a record which it has already 4912 accepted or cause the receiver to accept record N+1 without having 4913 first processed record N. [[TODO: If we merge in DTLS to this 4914 document, we will need to update this guarantee.]] 4916 Length concealment. Given a record with a given external length, the 4917 attacker should not be able to determine the amount of the record 4918 that is content versus padding. 4920 Forward security after key change. If the traffic key update 4921 mechanism described in Section 4.4.3 has been used and the 4922 previous generation key is deleted, an attacker who compromises 4923 the endpoint should not be able to decrypt traffic encrypted with 4924 the old key. 4926 Informally, TLS 1.3 provides these properties by AEAD-protecting the 4927 plaintext with a strong key. AEAD encryption [RFC5116] provides 4928 confidentiality and integrity for the data. Non-replayability is 4929 provided by using a separate nonce for each record, with the nonce 4930 being derived from the record sequence number (Section 5.3), with the 4931 sequence number being maintained independently at both sides thus 4932 records which are delivered out of order result in AEAD deprotection 4933 failures. 4935 The plaintext protected by the AEAD function consists of content plus 4936 variable-length padding. Because the padding is also encrypted, the 4937 attacker cannot directly determine the length of the padding, but may 4938 be able to measure it indirectly by the use of timing channels 4939 exposed during record processing (i.e., seeing how long it takes to 4940 process a record). In general, it is not known how to remove this 4941 type of channel because even a constant time padding removal function 4942 will then feed the content into data-dependent functions. 4944 Generation N+1 keys are derived from generation N keys via a key 4945 derivation function Section 7.2. As long as this function is truly 4946 one way, it is not possible to compute the previous keys after a key 4947 change (forward secrecy). However, TLS does not provide security for 4948 data which is sent after the traffic secret is compromised, even afer 4949 a key update (backward secrecy); systems which want backward secrecy 4950 must do a fresh handshake and establish a new session key with an 4951 (EC)DHE exchange. 4953 The reader should refer to the following references for analysis of 4954 the TLS record layer. 4956 Appendix E. Working Group Information 4958 The discussion list for the IETF TLS working group is located at the 4959 e-mail address tls@ietf.org [1]. Information on the group and 4960 information on how to subscribe to the list is at 4961 https://www.ietf.org/mailman/listinfo/tls 4963 Archives of the list can be found at: https://www.ietf.org/mail- 4964 archive/web/tls/current/index.html 4966 Appendix F. Contributors 4968 - Martin Abadi 4969 University of California, Santa Cruz 4970 abadi@cs.ucsc.edu 4972 - Christopher Allen (co-editor of TLS 1.0) 4973 Alacrity Ventures 4974 ChristopherA@AlacrityManagement.com 4976 - Steven M. Bellovin 4977 Columbia University 4978 smb@cs.columbia.edu 4980 - David Benjamin 4981 Google 4982 davidben@google.com 4984 - Benjamin Beurdouche 4986 - Karthikeyan Bhargavan (co-author of [RFC7627]) 4987 INRIA 4988 karthikeyan.bhargavan@inria.fr 4990 - Simon Blake-Wilson (co-author of [RFC4492]) 4991 BCI 4992 sblakewilson@bcisse.com 4994 - Nelson Bolyard (co-author of [RFC4492]) 4995 Sun Microsystems, Inc. 4996 nelson@bolyard.com 4998 - Ran Canetti 4999 IBM 5000 canetti@watson.ibm.com 5002 - Pete Chown 5003 Skygate Technology Ltd 5004 pc@skygate.co.uk 5006 - Antoine Delignat-Lavaud (co-author of [RFC7627]) 5007 INRIA 5008 antoine.delignat-lavaud@inria.fr 5010 - Tim Dierks (co-editor of TLS 1.0, 1.1, and 1.2) 5011 Independent 5012 tim@dierks.org 5014 - Taher Elgamal 5015 Securify 5016 taher@securify.com 5018 - Pasi Eronen 5019 Nokia 5020 pasi.eronen@nokia.com 5022 - Cedric Fournet 5023 Microsoft 5024 fournet@microsoft.com 5026 - Anil Gangolli 5027 anil@busybuddha.org 5029 - David M. Garrett 5031 - Vipul Gupta (co-author of [RFC4492]) 5032 Sun Microsystems Laboratories 5033 vipul.gupta@sun.com 5035 - Chris Hawk (co-author of [RFC4492]) 5036 Corriente Networks LLC 5037 chris@corriente.net 5039 - Kipp Hickman 5041 - Alfred Hoenes 5043 - David Hopwood 5044 Independent Consultant 5045 david.hopwood@blueyonder.co.uk 5047 - Subodh Iyengar 5048 Facebook 5049 subodh@fb.com 5051 - Daniel Kahn Gillmor 5052 ACLU 5053 dkg@fifthhorseman.net 5055 - Phil Karlton (co-author of SSL 3.0) 5057 - Paul Kocher (co-author of SSL 3.0) 5058 Cryptography Research 5059 paul@cryptography.com 5061 - Hugo Krawczyk 5062 IBM 5063 hugo@ee.technion.ac.il 5065 - Adam Langley (co-author of [RFC7627]) 5066 Google 5067 agl@google.com 5069 - Ilari Liusvaara 5070 Independent 5071 ilariliusvaara@welho.com 5073 - Jan Mikkelsen 5074 Transactionware 5075 janm@transactionware.com 5077 - Bodo Moeller (co-author of [RFC4492]) 5078 Google 5079 bodo@openssl.org 5081 - Erik Nygren 5082 Akamai Technologies 5083 erik+ietf@nygren.org 5085 - Magnus Nystrom 5086 RSA Security 5087 magnus@rsasecurity.com 5089 - Alfredo Pironti (co-author of [RFC7627]) 5090 INRIA 5091 alfredo.pironti@inria.fr 5093 - Andrei Popov 5094 Microsoft 5095 andrei.popov@microsoft.com 5097 - Marsh Ray (co-author of [RFC7627]) 5098 Microsoft 5099 maray@microsoft.com 5101 - Robert Relyea 5102 Netscape Communications 5103 relyea@netscape.com 5105 - Kyle Rose 5106 Akamai Technologies 5107 krose@krose.org 5109 - Jim Roskind 5110 Netscape Communications 5111 jar@netscape.com 5113 - Michael Sabin 5115 - Dan Simon 5116 Microsoft, Inc. 5117 dansimon@microsoft.com 5119 - Nick Sullivan 5120 CloudFlare Inc. 5121 nick@cloudflare.com 5123 - Bjoern Tackmann 5124 University of California, San Diego 5125 btackmann@eng.ucsd.edu 5127 - Martin Thomson 5128 Mozilla 5129 mt@mozilla.com 5131 - Filippo Valsorda 5132 CloudFlare Inc. 5133 filippo@cloudflare.com 5135 - Tom Weinstein 5137 - Hoeteck Wee 5138 Ecole Normale Superieure, Paris 5139 hoeteck@alum.mit.edu 5141 - Tim Wright 5142 Vodafone 5143 timothy.wright@vodafone.com 5145 Author's Address 5147 Eric Rescorla 5148 RTFM, Inc. 5150 EMail: ekr@rtfm.com