idnits 2.17.1 draft-ietf-tls-tls13-11.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 7 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 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 == Line 857 has weird spacing: '...gorithm rec...' == Line 4701 has weird spacing: '...gorithm rec...' (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 (December 28, 2015) is 3035 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) -- Looks like a reference, but probably isn't: '0' on line 458 -- Looks like a reference, but probably isn't: '1' on line 5088 -- Looks like a reference, but probably isn't: '3' on line 529 -- Looks like a reference, but probably isn't: '9' on line 494 -- Looks like a reference, but probably isn't: '2' on line 4330 -- Looks like a reference, but probably isn't: '4' on line 530 -- Looks like a reference, but probably isn't: '8' on line 531 -- Looks like a reference, but probably isn't: '10' on line 641 -- Looks like a reference, but probably isn't: '48' on line 4705 -- Looks like a reference, but probably isn't: '32' on line 4707 == Missing Reference: 'RFC7507' is mentioned on line 1391, but not defined ** Obsolete undefined reference: RFC 7507 (Obsoleted by RFC 8996) == Missing Reference: 'NewSessionTicket' is mentioned on line 1772, but not defined == Unused Reference: 'I-D.ietf-tls-chacha20-poly1305' is defined on line 3879, but no explicit reference was found in the text == Unused Reference: 'RFC6209' is defined on line 3942, but no explicit reference was found in the text == Unused Reference: 'RFC6367' is defined on line 3947, but no explicit reference was found in the text == Unused Reference: 'RFC7251' is defined on line 3957, but no explicit reference was found in the text == Unused Reference: 'PKCS6' is defined on line 4003, but no explicit reference was found in the text == Unused Reference: 'PKCS7' is defined on line 4006, but no explicit reference was found in the text == Unused Reference: 'RFC7301' is defined on line 4149, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DH' ** Downref: Normative reference to an Informational draft: draft-irtf-cfrg-curves (ref. 'I-D.irtf-cfrg-curves') == Outdated reference: A later version (-08) exists of draft-irtf-cfrg-eddsa-01 ** 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 ** Downref: Normative reference to an Informational RFC: RFC 7251 -- 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 6961 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6962 (Obsoleted by RFC 9162) Summary: 11 errors (**), 0 flaws (~~), 13 warnings (==), 33 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Rescorla 3 Internet-Draft RTFM, Inc. 4 Obsoletes: 5077, 5246, 5746 (if December 28, 2015 5 approved) 6 Updates: 4492 (if approved) 7 Intended status: Standards Track 8 Expires: June 30, 2016 10 The Transport Layer Security (TLS) Protocol Version 1.3 11 draft-ietf-tls-tls13-11 13 Abstract 15 This document specifies Version 1.3 of the Transport Layer Security 16 (TLS) protocol. The TLS protocol allows client/server applications 17 to communicate over the Internet in a way that is designed to prevent 18 eavesdropping, 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 June 30, 2016. 37 Copyright Notice 39 Copyright (c) 2015 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 2. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 3. Goals of This Document . . . . . . . . . . . . . . . . . . . 9 71 4. Presentation Language . . . . . . . . . . . . . . . . . . . . 10 72 4.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 10 73 4.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 10 74 4.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 4.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 11 76 4.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 12 77 4.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 13 78 4.6.1. Variants . . . . . . . . . . . . . . . . . . . . . . 13 79 4.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 14 80 4.8. Cryptographic Attributes . . . . . . . . . . . . . . . . 14 81 4.8.1. Digital Signing . . . . . . . . . . . . . . . . . . . 15 82 4.8.2. Authenticated Encryption with Additional Data (AEAD) 16 83 5. The TLS Record Protocol . . . . . . . . . . . . . . . . . . . 17 84 5.1. Connection States . . . . . . . . . . . . . . . . . . . . 17 85 5.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 19 86 5.2.1. Fragmentation . . . . . . . . . . . . . . . . . . . . 19 87 5.2.2. Record Payload Protection . . . . . . . . . . . . . . 21 88 5.2.3. Record Padding . . . . . . . . . . . . . . . . . . . 23 89 6. The TLS Handshaking Protocols . . . . . . . . . . . . . . . . 24 90 6.1. Alert Protocol . . . . . . . . . . . . . . . . . . . . . 25 91 6.1.1. Closure Alerts . . . . . . . . . . . . . . . . . . . 26 92 6.1.2. Error Alerts . . . . . . . . . . . . . . . . . . . . 28 93 6.2. Handshake Protocol Overview . . . . . . . . . . . . . . . 31 94 6.2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . 35 95 6.2.2. Zero-RTT Exchange . . . . . . . . . . . . . . . . . . 36 96 6.2.3. Resumption and PSK . . . . . . . . . . . . . . . . . 37 98 6.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 39 99 6.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 40 100 6.3.2. Hello Extensions . . . . . . . . . . . . . . . . . . 46 101 6.3.3. Server Parameters . . . . . . . . . . . . . . . . . . 58 102 6.3.4. Authentication Messages . . . . . . . . . . . . . . . 63 103 6.3.5. Post-Handshake Messages . . . . . . . . . . . . . . . 71 104 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 73 105 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 73 106 7.2. Updating Traffic Keys and IVs . . . . . . . . . . . . . . 75 107 7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 76 108 7.3.1. The Handshake Hash . . . . . . . . . . . . . . . . . 77 109 7.3.2. Diffie-Hellman . . . . . . . . . . . . . . . . . . . 77 110 7.3.3. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 77 111 8. Mandatory Algorithms . . . . . . . . . . . . . . . . . . . . 78 112 8.1. MTI Cipher Suites . . . . . . . . . . . . . . . . . . . . 78 113 8.2. MTI Extensions . . . . . . . . . . . . . . . . . . . . . 78 114 9. Application Data Protocol . . . . . . . . . . . . . . . . . . 79 115 10. Security Considerations . . . . . . . . . . . . . . . . . . . 80 116 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 80 117 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 83 118 12.1. Normative References . . . . . . . . . . . . . . . . . . 83 119 12.2. Informative References . . . . . . . . . . . . . . . . . 85 120 Appendix A. Protocol Data Structures and Constant Values . . . . 91 121 A.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 91 122 A.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 91 123 A.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 93 124 A.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 93 125 A.3.2. Server Parameters Messages . . . . . . . . . . . . . 98 126 A.3.3. Authentication Messages . . . . . . . . . . . . . . . 98 127 A.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 99 128 A.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 99 129 A.4.1. Unauthenticated Operation . . . . . . . . . . . . . . 102 130 A.5. The Security Parameters . . . . . . . . . . . . . . . . . 102 131 A.6. Changes to RFC 4492 . . . . . . . . . . . . . . . . . . . 103 132 Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 104 133 B.1. Random Number Generation and Seeding . . . . . . . . . . 104 134 B.2. Certificates and Authentication . . . . . . . . . . . . . 104 135 B.3. Cipher Suite Support . . . . . . . . . . . . . . . . . . 104 136 B.4. Implementation Pitfalls . . . . . . . . . . . . . . . . . 104 137 Appendix C. Backward Compatibility . . . . . . . . . . . . . . . 106 138 C.1. Negotiating with an older server . . . . . . . . . . . . 106 139 C.2. Negotiating with an older client . . . . . . . . . . . . 107 140 C.3. Backwards Compatibility Security Restrictions . . . . . . 107 141 Appendix D. Security Analysis . . . . . . . . . . . . . . . . . 108 142 D.1. Handshake Protocol . . . . . . . . . . . . . . . . . . . 108 143 D.1.1. Authentication and Key Exchange . . . . . . . . . . . 109 144 D.1.2. Version Rollback Attacks . . . . . . . . . . . . . . 109 145 D.1.3. Detecting Attacks Against the Handshake Protocol . . 110 147 D.2. Protecting Application Data . . . . . . . . . . . . . . . 110 148 D.3. Denial of Service . . . . . . . . . . . . . . . . . . . . 110 149 D.4. Final Notes . . . . . . . . . . . . . . . . . . . . . . . 111 150 Appendix E. Working Group Information . . . . . . . . . . . . . 111 151 Appendix F. Contributors . . . . . . . . . . . . . . . . . . . . 111 152 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 115 154 1. Introduction 156 DISCLAIMER: This is a WIP draft of TLS 1.3 and has not yet seen 157 significant security analysis. 159 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 160 draft is maintained in GitHub. Suggested changes should be submitted 161 as pull requests at https://github.com/tlswg/tls13-spec. 162 Instructions are on that page as well. Editorial changes can be 163 managed in GitHub, but any substantive change should be discussed on 164 the TLS mailing list. 166 The primary goal of the TLS protocol is to provide privacy and data 167 integrity between two communicating peers. The TLS protocol is 168 composed of two layers: the TLS Record Protocol and the TLS Handshake 169 Protocol. At the lowest level, layered on top of some reliable 170 transport protocol (e.g., TCP [RFC0793]), is the TLS Record Protocol. 171 The TLS Record Protocol provides connection security that has two 172 basic properties: 174 - The connection is private. Symmetric cryptography is used for 175 data encryption (e.g., AES [AES]). The keys for this symmetric 176 encryption are generated uniquely for each connection and are 177 based on a secret negotiated by another protocol (such as the TLS 178 Handshake Protocol). 180 - The connection is reliable. Messages include an authentication 181 tag which protects them against modification. 183 Note: The TLS Record Protocol can operate in an insecure mode but is 184 generally only used in this mode while another protocol is using the 185 TLS Record Protocol as a transport for negotiating security 186 parameters. 188 The TLS Record Protocol is used for encapsulation of various higher- 189 level protocols. One such encapsulated protocol, the TLS Handshake 190 Protocol, allows the server and client to authenticate each other and 191 to negotiate an encryption algorithm and cryptographic keys before 192 the application protocol transmits or receives its first byte of 193 data. The TLS Handshake Protocol provides connection security that 194 has three basic properties: 196 - The peer's identity can be authenticated using asymmetric, or 197 public key, cryptography (e.g., RSA [RSA], ECDSA [ECDSA]). This 198 authentication can be made optional, but is generally required for 199 at least one of the peers. 201 - The negotiation of a shared secret is secure: the negotiated 202 secret is unavailable to eavesdroppers, and for any authenticated 203 connection the secret cannot be obtained, even by an attacker who 204 can place himself in the middle of the connection. 206 - The negotiation is reliable: no attacker can modify the 207 negotiation communication without being detected by the parties to 208 the communication. 210 One advantage of TLS is that it is application protocol independent. 211 Higher-level protocols can layer on top of the TLS protocol 212 transparently. The TLS standard, however, does not specify how 213 protocols add security with TLS; the decisions on how to initiate TLS 214 handshaking and how to interpret the authentication certificates 215 exchanged are left to the judgment of the designers and implementors 216 of protocols that run on top of TLS. 218 1.1. Conventions and Terminology 220 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 221 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 222 "OPTIONAL" in this document are to be interpreted as described in RFC 223 2119 [RFC2119]. 225 The following terms are used: 227 client: The endpoint initiating the TLS connection. 229 connection: A transport-layer connection between two endpoints. 231 endpoint: Either the client or server of the connection. 233 handshake: An initial negotiation between client and server that 234 establishes the parameters of their transactions. 236 peer: An endpoint. When discussing a particular endpoint, "peer" 237 refers to the endpoint that is remote to the primary subject of 238 discussion. 240 receiver: An endpoint that is receiving records. 242 sender: An endpoint that is transmitting records. 244 session: An association between a client and a server resulting from 245 a handshake. 247 server: The endpoint which did not initiate the TLS connection. 249 1.2. Major Differences from TLS 1.2 251 draft-11 253 - Port the CFRG curves & signatures work from RFC4492bis. 255 - Remove sequence number and version from additional_data, which is 256 now empty. 258 - Reorder values in HkdfLabel. 260 - Add support for version anti-downgrade mechanism. 262 - Update IANA considerations section and relax some of the policies. 264 - Unify authentication modes. Add post-handshake client 265 authentication. 267 - Remove early_handshake content type. Terminate 0-RTT data with an 268 alert. 270 - Reset sequence number upon key change (as proposed by Fournet et 271 al.) 273 draft-10 275 - Remove ClientCertificateTypes field from CertificateRequest and 276 add extensions. 278 - Merge client and server key shares into a single extension. 280 draft-09 282 - Change to RSA-PSS signatures for handshake messages. 284 - Remove support for DSA. 286 - Update key schedule per suggestions by Hugo, Hoeteck, and Bjoern 287 Tackmann. 289 - Add support for per-record padding. 291 - Switch to encrypted record ContentType. 293 - Change HKDF labeling to include protocol version and value 294 lengths. 296 - Shift the final decision to abort a handshake due to incompatible 297 certificates to the client rather than having servers abort early. 299 - Deprecate SHA-1 with signatures. 301 - Add MTI algorithms. 303 draft-08 305 - Remove support for weak and lesser used named curves. 307 - Remove support for MD5 and SHA-224 hashes with signatures. 309 - Update lists of available AEAD cipher suites and error alerts. 311 - Reduce maximum permitted record expansion for AEAD from 2048 to 312 256 octets. 314 - Require digital signatures even when a previous configuration is 315 used. 317 - Merge EarlyDataIndication and KnownConfiguration. 319 - Change code point for server_configuration to avoid collision with 320 server_hello_done. 322 - Relax certificate_list ordering requirement to match current 323 practice. 325 draft-07 327 - Integration of semi-ephemeral DH proposal. 329 - Add initial 0-RTT support. 331 - Remove resumption and replace with PSK + tickets. 333 - Move ClientKeyShare into an extension. 335 - Move to HKDF. 337 draft-06 339 - Prohibit RC4 negotiation for backwards compatibility. 341 - Freeze & deprecate record layer version field. 343 - Update format of signatures with context. 345 - Remove explicit IV. 347 draft-05 349 - Prohibit SSL negotiation for backwards compatibility. 351 - Fix which MS is used for exporters. 353 draft-04 355 - Modify key computations to include session hash. 357 - Remove ChangeCipherSpec. 359 - Renumber the new handshake messages to be somewhat more consistent 360 with existing convention and to remove a duplicate registration. 362 - Remove renegotiation. 364 - Remove point format negotiation. 366 draft-03 368 - Remove GMT time. 370 - Merge in support for ECC from RFC 4492 but without explicit 371 curves. 373 - Remove the unnecessary length field from the AD input to AEAD 374 ciphers. 376 - Rename {Client,Server}KeyExchange to {Client,Server}KeyShare. 378 - Add an explicit HelloRetryRequest to reject the client's. 380 draft-02 382 - Increment version number. 384 - Rework handshake to provide 1-RTT mode. 386 - Remove custom DHE groups. 388 - Remove support for compression. 390 - Remove support for static RSA and DH key exchange. 392 - Remove support for non-AEAD ciphers. 394 2. Goals 396 The goals of the TLS protocol, in order of priority, are as follows: 398 1. Cryptographic security: TLS should be used to establish a secure 399 connection between two parties. 401 2. Interoperability: Independent programmers should be able to 402 develop applications utilizing TLS that can successfully exchange 403 cryptographic parameters without knowledge of one another's code. 405 3. Extensibility: TLS seeks to provide a framework into which new 406 public key and record protection methods can be incorporated as 407 necessary. This will also accomplish two sub-goals: preventing 408 the need to create a new protocol (and risking the introduction 409 of possible new weaknesses) and avoiding the need to implement an 410 entire new security library. 412 4. Relative efficiency: Cryptographic operations tend to be highly 413 CPU intensive, particularly public key operations. For this 414 reason, the TLS protocol has incorporated an optional session 415 caching scheme to reduce the number of connections that need to 416 be established from scratch. Additionally, care has been taken 417 to reduce network activity. 419 3. Goals of This Document 421 This document and the TLS protocol itself have evolved from the SSL 422 3.0 Protocol Specification as published by Netscape. The differences 423 between this version and previous versions are significant enough 424 that the various versions of TLS and SSL 3.0 do not interoperate 425 (although each protocol incorporates a mechanism by which an 426 implementation can back down to prior versions). This document is 427 intended primarily for readers who will be implementing the protocol 428 and for those doing cryptographic analysis of it. The specification 429 has been written with this in mind, and it is intended to reflect the 430 needs of those two groups. For that reason, many of the algorithm- 431 dependent data structures and rules are included in the body of the 432 text (as opposed to in an appendix), providing easier access to them. 434 This document is not intended to supply any details of service 435 definition or of interface definition, although it does cover select 436 areas of policy as they are required for the maintenance of solid 437 security. 439 4. Presentation Language 441 This document deals with the formatting of data in an external 442 representation. The following very basic and somewhat casually 443 defined presentation syntax will be used. The syntax draws from 444 several sources in its structure. Although it resembles the 445 programming language "C" in its syntax and XDR [RFC4506] in both its 446 syntax and intent, it would be risky to draw too many parallels. The 447 purpose of this presentation language is to document TLS only; it has 448 no general application beyond that particular goal. 450 4.1. Basic Block Size 452 The representation of all data items is explicitly specified. The 453 basic data block size is one byte (i.e., 8 bits). Multiple byte data 454 items are concatenations of bytes, from left to right, from top to 455 bottom. From the byte stream, a multi-byte item (a numeric in the 456 example) is formed (using C notation) by: 458 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 459 ... | byte[n-1]; 461 This byte ordering for multi-byte values is the commonplace network 462 byte order or big-endian format. 464 4.2. Miscellaneous 466 Comments begin with "/*" and end with "*/". 468 Optional components are denoted by enclosing them in "[[ ]]" double 469 brackets. 471 Single-byte entities containing uninterpreted data are of type 472 opaque. 474 4.3. Vectors 476 A vector (single-dimensioned array) is a stream of homogeneous data 477 elements. The size of the vector may be specified at documentation 478 time or left unspecified until runtime. In either case, the length 479 declares the number of bytes, not the number of elements, in the 480 vector. The syntax for specifying a new type, T', that is a fixed- 481 length vector of type T is 483 T T'[n]; 485 Here, T' occupies n bytes in the data stream, where n is a multiple 486 of the size of T. The length of the vector is not included in the 487 encoded stream. 489 In the following example, Datum is defined to be three consecutive 490 bytes that the protocol does not interpret, while Data is three 491 consecutive Datum, consuming a total of nine bytes. 493 opaque Datum[3]; /* three uninterpreted bytes */ 494 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 496 Variable-length vectors are defined by specifying a subrange of legal 497 lengths, inclusively, using the notation . When 498 these are encoded, the actual length precedes the vector's contents 499 in the byte stream. The length will be in the form of a number 500 consuming as many bytes as required to hold the vector's specified 501 maximum (ceiling) length. A variable-length vector with an actual 502 length field of zero is referred to as an empty vector. 504 T T'; 506 In the following example, mandatory is a vector that must contain 507 between 300 and 400 bytes of type opaque. It can never be empty. 508 The actual length field consumes two bytes, a uint16, which is 509 sufficient to represent the value 400 (see Section 4.4). On the 510 other hand, longer can represent up to 800 bytes of data, or 400 511 uint16 elements, and it may be empty. Its encoding will include a 512 two-byte actual length field prepended to the vector. The length of 513 an encoded vector must be an even multiple of the length of a single 514 element (for example, a 17-byte vector of uint16 would be illegal). 516 opaque mandatory<300..400>; 517 /* length field is 2 bytes, cannot be empty */ 518 uint16 longer<0..800>; 519 /* zero to 400 16-bit unsigned integers */ 521 4.4. Numbers 523 The basic numeric data type is an unsigned byte (uint8). All larger 524 numeric data types are formed from fixed-length series of bytes 525 concatenated as described in Section 4.1 and are also unsigned. The 526 following numeric types are predefined. 528 uint8 uint16[2]; 529 uint8 uint24[3]; 530 uint8 uint32[4]; 531 uint8 uint64[8]; 533 All values, here and elsewhere in the specification, are stored in 534 network byte (big-endian) order; the uint32 represented by the hex 535 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 537 Note that in some cases (e.g., DH parameters) it is necessary to 538 represent integers as opaque vectors. In such cases, they are 539 represented as unsigned integers (i.e., leading zero octets are not 540 required even if the most significant bit is set). 542 4.5. Enumerateds 544 An additional sparse data type is available called enum. A field of 545 type enum can only assume the values declared in the definition. 546 Each definition is a different type. Only enumerateds of the same 547 type may be assigned or compared. Every element of an enumerated 548 must be assigned a value, as demonstrated in the following example. 549 Since the elements of the enumerated are not ordered, they can be 550 assigned any unique value, in any order. 552 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 554 An enumerated occupies as much space in the byte stream as would its 555 maximal defined ordinal value. The following definition would cause 556 one byte to be used to carry fields of type Color. 558 enum { red(3), blue(5), white(7) } Color; 560 One may optionally specify a value without its associated tag to 561 force the width definition without defining a superfluous element. 563 In the following example, Taste will consume two bytes in the data 564 stream but can only assume the values 1, 2, or 4. 566 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 568 The names of the elements of an enumeration are scoped within the 569 defined type. In the first example, a fully qualified reference to 570 the second element of the enumeration would be Color.blue. Such 571 qualification is not required if the target of the assignment is well 572 specified. 574 Color color = Color.blue; /* overspecified, legal */ 575 Color color = blue; /* correct, type implicit */ 577 For enumerateds that are never converted to external representation, 578 the numerical information may be omitted. 580 enum { low, medium, high } Amount; 582 4.6. Constructed Types 584 Structure types may be constructed from primitive types for 585 convenience. Each specification declares a new, unique type. The 586 syntax for definition is much like that of C. 588 struct { 589 T1 f1; 590 T2 f2; 591 ... 592 Tn fn; 593 } [[T]]; 595 The fields within a structure may be qualified using the type's name, 596 with a syntax much like that available for enumerateds. For example, 597 T.f2 refers to the second field of the previous declaration. 598 Structure definitions may be embedded. 600 4.6.1. Variants 602 Defined structures may have variants based on some knowledge that is 603 available within the environment. The selector must be an enumerated 604 type that defines the possible variants the structure defines. There 605 must be a case arm for every element of the enumeration declared in 606 the select. Case arms have limited fall-through: if two case arms 607 follow in immediate succession with no fields in between, then they 608 both contain the same fields. Thus, in the example below, "orange" 609 and "banana" both contain V2. Note that this is a new piece of 610 syntax in TLS 1.2. 612 The body of the variant structure may be given a label for reference. 613 The mechanism by which the variant is selected at runtime is not 614 prescribed by the presentation language. 616 struct { 617 T1 f1; 618 T2 f2; 619 .... 620 Tn fn; 621 select (E) { 622 case e1: Te1; 623 case e2: Te2; 624 case e3: case e4: Te3; 625 .... 626 case en: Ten; 627 } [[fv]]; 628 } [[Tv]]; 630 For example: 632 enum { apple, orange, banana } VariantTag; 634 struct { 635 uint16 number; 636 opaque string<0..10>; /* variable length */ 637 } V1; 639 struct { 640 uint32 number; 641 opaque string[10]; /* fixed length */ 642 } V2; 644 struct { 645 select (VariantTag) { /* value of selector is implicit */ 646 case apple: 647 V1; /* VariantBody, tag = apple */ 648 case orange: 649 case banana: 650 V2; /* VariantBody, tag = orange or banana */ 651 } variant_body; /* optional label on variant */ 652 } VariantRecord; 654 4.7. Constants 656 Typed constants can be defined for purposes of specification by 657 declaring a symbol of the desired type and assigning values to it. 659 Under-specified types (opaque, variable-length vectors, and 660 structures that contain opaque) cannot be assigned values. No fields 661 of a multi-element structure or vector may be elided. 663 For example: 665 struct { 666 uint8 f1; 667 uint8 f2; 668 } Example1; 670 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 672 4.8. Cryptographic Attributes 674 The two cryptographic operations -- digital signing, and 675 authenticated encryption with additional data (AEAD) -- are 676 designated digitally-signed, and aead-ciphered, respectively. A 677 field's cryptographic processing is specified by prepending an 678 appropriate key word designation before the field's type 679 specification. Cryptographic keys are implied by the current session 680 state (see Section 5.1). 682 4.8.1. Digital Signing 684 A digitally-signed element is encoded as a struct DigitallySigned: 686 struct { 687 SignatureAndHashAlgorithm algorithm; 688 opaque signature<0..2^16-1>; 689 } DigitallySigned; 691 The algorithm field specifies the algorithm used (see Section 6.3.2.1 692 for the definition of this field). Note that the algorithm field was 693 introduced in TLS 1.2, and is not in earlier versions. The signature 694 is a digital signature using those algorithms over the contents of 695 the element. The contents themselves do not appear on the wire but 696 are simply calculated. The length of the signature is specified by 697 the signing algorithm and key. 699 In previous versions of TLS, the ServerKeyExchange format meant that 700 attackers can obtain a signature of a message with a chosen, 32-byte 701 prefix. Because TLS 1.3 servers are likely to also implement prior 702 versions, the contents of the element always start with 64 bytes of 703 octet 32 in order to clear that chosen-prefix. 705 Following that padding is a context string used to disambiguate 706 signatures for different purposes. The context string will be 707 specified whenever a digitally-signed element is used. A single 0 708 byte is appended to the context to act as a separator. 710 Finally, the specified contents of the digitally-signed structure 711 follow the NUL after the context string. (See the example at the end 712 of this section.) 714 In RSA signing, the opaque vector contains the signature generated 715 using the RSASSA-PSS signature scheme defined in [RFC3447] with MGF1. 716 The digest used in the mask generation function MUST be the same as 717 the digest which is being signed (i.e., what appears in 718 algorithm.signature). The length of the salt MUST be equal to the 719 length of the digest output. Note that previous versions of TLS used 720 RSASSA-PKCS1-v1_5, not RSASSA-PSS. 722 All ECDSA computations MUST be performed according to ANSI X9.62 723 [X962] or its successors. Data to be signed/verified is hashed, and 724 the result run directly through the ECDSA algorithm with no 725 additional hashing. The SignatureAndHashAlgorithm parameter in the 726 DigitallySigned object indicates the digest algorithm which was used 727 in the signature. Signature-only curves MUST NOT be used for ECDSA 728 unless otherwise noted. 730 All EdDSA computations MUST be performed according to 731 [I-D.irtf-cfrg-eddsa] or its successors. Data to be signed/verified 732 is passed as-is to the EdDSA algorithm with no hashing. The 733 signature output is placed as-is in the signature field. The 734 SignatureAndHashAlgorithm.hash value MUST set to none(0). 736 In the following example 738 struct { 739 uint8 field1; 740 uint8 field2; 741 digitally-signed opaque { 742 uint8 field3<0..255>; 743 uint8 field4; 744 }; 745 } UserType; 747 Assume that the context string for the signature was specified as 748 "Example". The input for the signature/hash algorithm would be: 750 2020202020202020202020202020202020202020202020202020202020202020 751 2020202020202020202020202020202020202020202020202020202020202020 752 4578616d706c6500 754 followed by the encoding of the inner struct (field3 and field4). 756 The length of the structure, in bytes, would be equal to two bytes 757 for field1 and field2, plus two bytes for the signature and hash 758 algorithm, plus two bytes for the length of the signature, plus the 759 length of the output of the signing algorithm. The length of the 760 signature is known because the algorithm and key used for the signing 761 are known prior to encoding or decoding this structure. 763 4.8.2. Authenticated Encryption with Additional Data (AEAD) 765 In AEAD encryption, the plaintext is simultaneously encrypted and 766 integrity protected. The input may be of any length, and aead- 767 ciphered output is generally larger than the input in order to 768 accommodate the integrity check value. 770 5. The TLS Record Protocol 772 The TLS Record Protocol is a layered protocol. At each layer, 773 messages may include fields for length, description, and content. 774 The TLS Record Protocol takes messages to be transmitted, fragments 775 the data into manageable blocks, protects the records, and transmits 776 the result. Received data is decrypted and verified, reassembled, 777 and then delivered to higher-level clients. 779 Three protocols that use the TLS Record Protocol are described in 780 this document: the TLS Handshake Protocol, the Alert Protocol, and 781 the application data protocol. In order to allow extension of the 782 TLS protocol, additional record content types can be supported by the 783 TLS Record Protocol. New record content type values are assigned by 784 IANA in the TLS Content Type Registry as described in Section 11. 786 Implementations MUST NOT send record types not defined in this 787 document unless negotiated by some extension. If a TLS 788 implementation receives an unexpected record type, it MUST send an 789 "unexpected_message" alert. 791 Any protocol designed for use over TLS must be carefully designed to 792 deal with all possible attacks against it. As a practical matter, 793 this means that the protocol designer must be aware of what security 794 properties TLS does and does not provide and cannot safely rely on 795 the latter. 797 Note in particular that the length of a record or absence of traffic 798 itself is not protected by encryption unless the sender uses the 799 supplied padding mechanism - see Section 5.2.3 for more details. 801 5.1. Connection States 803 [[TODO: I plan to totally rewrite or remove this. IT seems like just 804 cruft.]] 806 A TLS connection state is the operating environment of the TLS Record 807 Protocol. It specifies a record protection algorithm and its 808 parameters as well as the record protection keys and IVs for the 809 connection in both the read and the write directions. The security 810 parameters are set by the TLS Handshake Protocol, which also 811 determines when new cryptographic keys are installed and used for 812 record protection. The initial current state always specifies that 813 records are not protected. 815 The security parameters for a TLS Connection read and write state are 816 set by providing the following values: 818 connection end 819 Whether this entity is considered the "client" or the "server" in 820 this connection. 822 Hash algorithm 823 An algorithm used to generate keys from the appropriate secret 824 (see Section 7.1 and Section 7.3). 826 record protection algorithm 827 The algorithm to be used for record protection. This algorithm 828 must be of the AEAD type and thus provides integrity and 829 confidentiality as a single primitive. This specification 830 includes the key size of this algorithm and of the nonce for the 831 AEAD algorithm. 833 master secret 834 A 48-byte secret shared between the two peers in the connection 835 and used to generate keys for protecting data. 837 client random 838 A 32-byte value provided by the client. 840 server random 841 A 32-byte value provided by the server. 843 These parameters are defined in the presentation language as: 845 enum { server, client } ConnectionEnd; 847 enum { tls_kdf_sha256, tls_kdf_sha384 } KDFAlgorithm; 849 enum { aes_gcm } RecordProtAlgorithm; 851 /* The algorithms specified in KDFAlgorithm and 852 RecordProtAlgorithm may be added to. */ 854 struct { 855 ConnectionEnd entity; 856 KDFAlgorithm kdf_algorithm; 857 RecordProtAlgorithm record_prot_algorithm; 858 uint8 enc_key_length; 859 uint8 iv_length; 860 opaque hs_master_secret[48]; 861 opaque master_secret[48]; 862 opaque client_random[32]; 863 opaque server_random[32]; 864 } SecurityParameters; 866 [TODO: update this to handle new key hierarchy.] 868 The connection state will use the security parameters to generate the 869 following four items: 871 client write key 872 server write key 873 client write iv 874 server write iv 876 The client write parameters are used by the server when receiving and 877 processing records and vice versa. The algorithm used for generating 878 these items from the security parameters is described in Section 7.3. 880 Once the security parameters have been set and the keys have been 881 generated, the connection states can be instantiated by making them 882 the current states. These current states MUST be updated for each 883 record processed. Each connection state includes the following 884 elements: 886 cipher state 887 The current state of the encryption algorithm. This will consist 888 of the scheduled key for that connection. 890 sequence number 891 Each connection state contains a sequence number, which is 892 maintained separately for read and write states. The sequence 893 number is set to zero at the beginning of a connection, and 894 whenever the key is changed. The sequence number is incremented 895 after each record: specifically, the first record transmitted 896 under a particular connection state and record key MUST use 897 sequence number 0. Sequence numbers are of type uint64 and MUST 898 NOT exceed 2^64-1. Sequence numbers do not wrap. If a TLS 899 implementation would need to wrap a sequence number, it MUST 900 either rekey (Section 6.3.5.3) or terminate the connection. 902 5.2. Record Layer 904 The TLS record layer receives uninterpreted data from higher layers 905 in non-empty blocks of arbitrary size. 907 5.2.1. Fragmentation 909 The record layer fragments information blocks into TLSPlaintext 910 records carrying data in chunks of 2^14 bytes or less. Client 911 message boundaries are not preserved in the record layer (i.e., 912 multiple client messages of the same ContentType MAY be coalesced 913 into a single TLSPlaintext record, or a single message MAY be 914 fragmented across several records). Alert messages Section 6.1 MUST 915 NOT be fragmented across records. 917 struct { 918 uint8 major; 919 uint8 minor; 920 } ProtocolVersion; 922 enum { 923 alert(21), 924 handshake(22), 925 application_data(23) 926 (255) 927 } ContentType; 929 struct { 930 ContentType type; 931 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 932 uint16 length; 933 opaque fragment[TLSPlaintext.length]; 934 } TLSPlaintext; 936 type 937 The higher-level protocol used to process the enclosed fragment. 939 record_version 940 The protocol version the current record is compatible with. This 941 value MUST be set to { 3, 1 } for all records. This field is 942 deprecated and MUST be ignored for all purposes. 944 length 945 The length (in bytes) of the following TLSPlaintext.fragment. The 946 length MUST NOT exceed 2^14. 948 fragment 949 The application data. This data is transparent and treated as an 950 independent block to be dealt with by the higher-level protocol 951 specified by the type field. 953 This document describes TLS Version 1.3, which uses the version { 3, 954 4 }. The version value 3.4 is historical, deriving from the use of { 955 3, 1 } for TLS 1.0 and { 3, 0 } for SSL 3.0. In order to maximize 956 backwards compatibility, the record layer version identifies as 957 simply TLS 1.0. Endpoints supporting other versions negotiate the 958 version to use by following the procedure and requirements in 959 Appendix C. 961 Implementations MUST NOT send zero-length fragments of Handshake or 962 Alert types, even if those fragments contain padding. Zero-length 963 fragments of Application data MAY be sent as they are potentially 964 useful as a traffic analysis countermeasure. 966 When record protection has not yet been engaged, TLSPlaintext 967 structures are written directly onto the wire. Once record 968 protection has started, TLSPlaintext records are protected and sent 969 as described in the following section. 971 5.2.2. Record Payload Protection 973 The record protection functions translate a TLSPlaintext structure 974 into a TLSCiphertext. The deprotection functions reverse the 975 process. In TLS 1.3 as opposed to previous versions of TLS, all 976 ciphers are modeled as "Authenticated Encryption with Additional 977 Data" (AEAD) [RFC5116]. AEAD functions provide a unified encryption 978 and authentication operation which turns plaintext into authenticated 979 ciphertext and back again. 981 AEAD ciphers take as input a single key, a nonce, a plaintext, and 982 "additional data" to be included in the authentication check, as 983 described in Section 2.1 of [RFC5116]. The key is either the 984 client_write_key or the server_write_key and in TLS 1.3 the 985 additional data input is empty (zero length). 987 struct { 988 ContentType opaque_type = application_data(23); /* see fragment.type */ 989 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 990 uint16 length; 991 aead-ciphered struct { 992 opaque content[TLSPlaintext.length]; 993 ContentType type; 994 uint8 zeros[length_of_padding]; 995 } fragment; 996 } TLSCiphertext; 998 opaque_type 999 The outer opaque_type field of a TLSCiphertext record is always 1000 set to the value 23 (application_data) for outward compatibility 1001 with middleboxes used to parsing previous versions of TLS. The 1002 actual content type of the record is found in fragment.type after 1003 decryption. 1005 record_version 1006 The record_version field is identical to 1007 TLSPlaintext.record_version and is always { 3, 1 }. Note that the 1008 handshake protocol including the ClientHello and ServerHello 1009 messages authenticates the protocol version, so this value is 1010 redundant. 1012 length 1013 The length (in bytes) of the following TLSCiphertext.fragment. 1014 The length MUST NOT exceed 2^14 + 256. An endpoint that receives 1015 a record that exceeds this length MUST generate a fatal 1016 "record_overflow" alert. 1018 fragment.content 1019 The cleartext of TLSPlaintext.fragment. 1021 fragment.type 1022 The actual content type of the record. 1024 fragment.zeros 1025 An arbitrary-length run of zero-valued bytes may appear in the 1026 cleartext after the type field. This provides an opportunity for 1027 senders to pad any TLS record by a chosen amount as long as the 1028 total stays within record size limits. See Section 5.2.3 for more 1029 details. 1031 fragment 1032 The AEAD encrypted form of TLSPlaintext.fragment + 1033 TLSPlaintext.type + zeros, where "+" denotes concatenation. 1035 The length of the per-record nonce (iv_length) is set to max(8 bytes, 1036 N_MIN) for the AEAD algorithm (see [RFC5116] Section 4). An AEAD 1037 algorithm where N_MAX is less than 8 bytes MUST NOT be used with TLS. 1038 The per-record nonce for the AEAD construction is formed as follows: 1040 1. The 64-bit record sequence number is padded to the left with 1041 zeroes to iv_length. 1043 2. The padded sequence number is XORed with the static 1044 client_write_iv or server_write_iv, depending on the role. 1046 The resulting quantity (of length iv_length) is used as the per- 1047 record nonce. 1049 Note: This is a different construction from that in TLS 1.2, which 1050 specified a partially explicit nonce. 1052 The plaintext is the concatenation of TLSPlaintext.fragment and 1053 TLSPlaintext.type. 1055 The AEAD output consists of the ciphertext output by the AEAD 1056 encryption operation. The length of the plaintext is greater than 1057 TLSPlaintext.length due to the inclusion of TLSPlaintext.type and 1058 however much padding is supplied by the sender. The length of 1059 aead_output will generally be larger than the plaintext, but by an 1060 amount that varies with the AEAD cipher. Since the ciphers might 1061 incorporate padding, the amount of overhead could vary with different 1062 lengths of plaintext. Symbolically, 1064 AEADEncrypted = 1065 AEAD-Encrypt(write_key, nonce, plaintext of fragment) 1067 In order to decrypt and verify, the cipher takes as input the key, 1068 nonce, and the AEADEncrypted value. The output is either the 1069 plaintext or an error indicating that the decryption failed. There 1070 is no separate integrity check. That is: 1072 plaintext of fragment = 1073 AEAD-Decrypt(write_key, nonce, AEADEncrypted) 1075 If the decryption fails, a fatal "bad_record_mac" alert MUST be 1076 generated. 1078 An AEAD cipher MUST NOT produce an expansion of greater than 255 1079 bytes. An endpoint that receives a record from its peer with 1080 TLSCipherText.length larger than 2^14 + 256 octets MUST generate a 1081 fatal "record_overflow" alert. This limit is derived from the 1082 maximum TLSPlaintext length of 2^14 octets + 1 octet for ContentType 1083 + the maximum AEAD expansion of 255 octets. 1085 5.2.3. Record Padding 1087 All encrypted TLS records can be padded to inflate the size of the 1088 TLSCipherText. This allows the sender to hide the size of the 1089 traffic from an observer. 1091 When generating a TLSCiphertext record, implementations MAY choose to 1092 pad. An unpadded record is just a record with a padding length of 1093 zero. Padding is a string of zero-valued bytes appended to the 1094 ContentType field before encryption. Implementations MUST set the 1095 padding octets to all zeros before encrypting. 1097 Application Data records may contain a zero-length fragment.content 1098 if the sender desires. This permits generation of plausibly-sized 1099 cover traffic in contexts where the presence or absence of activity 1100 may be sensitive. Implementations MUST NOT send Handshake or Alert 1101 records that have a zero-length fragment.content. 1103 The padding sent is automatically verified by the record protection 1104 mechanism: Upon successful decryption of a TLSCiphertext.fragment, 1105 the receiving implementation scans the field from the end toward the 1106 beginning until it finds a non-zero octet. This non-zero octet is 1107 the content type of the message. 1109 Implementations MUST limit their scanning to the cleartext returned 1110 from the AEAD decryption. If a receiving implementation does not 1111 find a non-zero octet in the cleartext, it should treat the record as 1112 having an unexpected ContentType, sending an "unexpected_message" 1113 alert. 1115 The presence of padding does not change the overall record size 1116 limitations - the full fragment plaintext may not exceed 2^14 octets. 1118 Versions of TLS prior to 1.3 had limited support for padding. This 1119 padding scheme was selected because it allows padding of any 1120 encrypted TLS record by an arbitrary size (from zero up to TLS record 1121 size limits) without introducing new content types. The design also 1122 enforces all-zero padding octets, which allows for quick detection of 1123 padding errors. 1125 Selecting a padding policy that suggests when and how much to pad is 1126 a complex topic, and is beyond the scope of this specification. If 1127 the application layer protocol atop TLS permits padding, it may be 1128 preferable to pad application_data TLS records within the application 1129 layer. Padding for encrypted handshake and alert TLS records must 1130 still be handled at the TLS layer, though. Later documents may 1131 define padding selection algorithms, or define a padding policy 1132 request mechanism through TLS extensions or some other means. 1134 6. The TLS Handshaking Protocols 1136 TLS has three subprotocols that are used to allow peers to agree upon 1137 security parameters for the record layer, to authenticate themselves, 1138 to instantiate negotiated security parameters, and to report error 1139 conditions to each other. 1141 The TLS Handshake Protocol is responsible for negotiating a session, 1142 which consists of the following items: 1144 peer certificate 1145 X509v3 [RFC5280] certificate of the peer. This element of the 1146 state may be null. 1148 cipher spec 1149 Specifies the authentication and key establishment algorithms, the 1150 hash for use with HKDF to generate keying material, and the record 1151 protection algorithm (See Appendix A.5 for formal definition.) 1153 resumption master secret 1154 a secret shared between the client and server that can be used as 1155 a PSK in future connections. 1157 These items are then used to create security parameters for use by 1158 the record layer when protecting application data. Many connections 1159 can be instantiated using the same session using a PSK established in 1160 an initial handshake. 1162 6.1. Alert Protocol 1164 One of the content types supported by the TLS record layer is the 1165 alert type. Alert messages convey the severity of the message 1166 (warning or fatal) and a description of the alert. Alert messages 1167 with a level of fatal result in the immediate termination of the 1168 connection. In this case, other connections corresponding to the 1169 session may continue, but the session identifier MUST be invalidated, 1170 preventing the failed session from being used to establish new 1171 connections. Like other messages, alert messages are encrypted as 1172 specified by the current connection state. 1174 enum { warning(1), fatal(2), (255) } AlertLevel; 1176 enum { 1177 close_notify(0), 1178 end_of_early_data(1), 1179 unexpected_message(10), /* fatal */ 1180 bad_record_mac(20), /* fatal */ 1181 record_overflow(22), /* fatal */ 1182 handshake_failure(40), /* fatal */ 1183 bad_certificate(42), 1184 unsupported_certificate(43), 1185 certificate_revoked(44), 1186 certificate_expired(45), 1187 certificate_unknown(46), 1188 illegal_parameter(47), /* fatal */ 1189 unknown_ca(48), /* fatal */ 1190 access_denied(49), /* fatal */ 1191 decode_error(50), /* fatal */ 1192 decrypt_error(51), /* fatal */ 1193 protocol_version(70), /* fatal */ 1194 insufficient_security(71), /* fatal */ 1195 internal_error(80), /* fatal */ 1196 inappropriate_fallback(86), /* fatal */ 1197 user_canceled(90), 1198 missing_extension(109), /* fatal */ 1199 unsupported_extension(110), /* fatal */ 1200 certificate_unobtainable(111), 1201 unrecognized_name(112), 1202 bad_certificate_status_response(113), /* fatal */ 1203 bad_certificate_hash_value(114), /* fatal */ 1204 unknown_psk_identity(115), 1205 (255) 1206 } AlertDescription; 1208 struct { 1209 AlertLevel level; 1210 AlertDescription description; 1211 } Alert; 1213 6.1.1. Closure Alerts 1215 The client and the server must share knowledge that the connection is 1216 ending in order to avoid a truncation attack. Failure to properly 1217 close a connection does not prohibit a session from being resumed. 1219 close_notify 1220 This alert notifies the recipient that the sender will not send 1221 any more messages on this connection. Any data received after a 1222 closure MUST be ignored. 1224 end_of_early_data 1225 This alert is sent by the client to indicate that all 0-RTT 1226 application_data messages have been transmitted (or none will be 1227 sent at all) and that this is the end of the flight. This alert 1228 MUST be at the warning level. Servers MUST NOT send this alert 1229 and clients receiving it MUST terminate the connection with an 1230 "unexpected_message" alert. 1232 user_canceled 1233 This alert notifies the recipient that the sender is canceling the 1234 handshake for some reason unrelated to a protocol failure. If a 1235 user cancels an operation after the handshake is complete, just 1236 closing the connection by sending a "close_notify" is more 1237 appropriate. This alert SHOULD be followed by a "close_notify". 1238 This alert is generally a warning. 1240 Either party MAY initiate a close by sending a "close_notify" alert. 1241 Any data received after a closure alert is ignored. If a transport- 1242 level close is received prior to a "close_notify", the receiver 1243 cannot know that all the data that was sent has been received. 1245 Each party MUST send a "close_notify" alert before closing the write 1246 side of the connection, unless some other fatal alert has been 1247 transmitted. The other party MUST respond with a "close_notify" 1248 alert of its own and close down the connection immediately, 1249 discarding any pending writes. The initiator of the close need not 1250 wait for the responding "close_notify" alert before closing the read 1251 side of the connection. 1253 If the application protocol using TLS provides that any data may be 1254 carried over the underlying transport after the TLS connection is 1255 closed, the TLS implementation must receive the responding 1256 "close_notify" alert before indicating to the application layer that 1257 the TLS connection has ended. If the application protocol will not 1258 transfer any additional data, but will only close the underlying 1259 transport connection, then the implementation MAY choose to close the 1260 transport without waiting for the responding "close_notify". No part 1261 of this standard should be taken to dictate the manner in which a 1262 usage profile for TLS manages its data transport, including when 1263 connections are opened or closed. 1265 Note: It is assumed that closing a connection reliably delivers 1266 pending data before destroying the transport. 1268 6.1.2. Error Alerts 1270 Error handling in the TLS Handshake Protocol is very simple. When an 1271 error is detected, the detecting party sends a message to its peer. 1272 Upon transmission or receipt of a fatal alert message, both parties 1273 immediately close the connection. Servers and clients MUST forget 1274 any session-identifiers, keys, and secrets associated with a failed 1275 connection. Thus, any connection terminated with a fatal alert MUST 1276 NOT be resumed. 1278 Whenever an implementation encounters a condition which is defined as 1279 a fatal alert, it MUST send the appropriate alert prior to closing 1280 the connection. For all errors where an alert level is not 1281 explicitly specified, the sending party MAY determine at its 1282 discretion whether to treat this as a fatal error or not. If the 1283 implementation chooses to send an alert but intends to close the 1284 connection immediately afterwards, it MUST send that alert at the 1285 fatal alert level. 1287 If an alert with a level of warning is sent and received, generally 1288 the connection can continue normally. If the receiving party decides 1289 not to proceed with the connection (e.g., after having received a 1290 "user_canceled" alert that it is not willing to accept), it SHOULD 1291 send a fatal alert to terminate the connection. Given this, the 1292 sending peer cannot, in general, know how the receiving party will 1293 behave. Therefore, warning alerts are not very useful when the 1294 sending party wants to continue the connection, and thus are 1295 sometimes omitted. For example, if a party decides to accept an 1296 expired certificate (perhaps after confirming this with the user) and 1297 wants to continue the connection, it would not generally send a 1298 "certificate_expired" alert. 1300 The following error alerts are defined: 1302 unexpected_message 1303 An inappropriate message was received. This alert is always fatal 1304 and should never be observed in communication between proper 1305 implementations. 1307 bad_record_mac 1308 This alert is returned if a record is received which cannot be 1309 deprotected. Because AEAD algorithms combine decryption and 1310 verification, this alert is used for all deprotection failures. 1311 This alert is always fatal and should never be observed in 1312 communication between proper implementations (except when messages 1313 were corrupted in the network). 1315 record_overflow 1316 A TLSCiphertext record was received that had a length more than 1317 2^14 + 256 bytes, or a record decrypted to a TLSPlaintext record 1318 with more than 2^14 bytes. This alert is always fatal and should 1319 never be observed in communication between proper implementations 1320 (except when messages were corrupted in the network). 1322 handshake_failure 1323 Reception of a "handshake_failure" alert message indicates that 1324 the sender was unable to negotiate an acceptable set of security 1325 parameters given the options available. This alert is always 1326 fatal. 1328 bad_certificate 1329 A certificate was corrupt, contained signatures that did not 1330 verify correctly, etc. 1332 unsupported_certificate 1333 A certificate was of an unsupported type. 1335 certificate_revoked 1336 A certificate was revoked by its signer. 1338 certificate_expired 1339 A certificate has expired or is not currently valid. 1341 certificate_unknown 1342 Some other (unspecified) issue arose in processing the 1343 certificate, rendering it unacceptable. 1345 illegal_parameter 1346 A field in the handshake was out of range or inconsistent with 1347 other fields. This alert is always fatal. 1349 unknown_ca 1350 A valid certificate chain or partial chain was received, but the 1351 certificate was not accepted because the CA certificate could not 1352 be located or couldn't be matched with a known, trusted CA. This 1353 alert is always fatal. 1355 access_denied 1356 A valid certificate or PSK was received, but when access control 1357 was applied, the sender decided not to proceed with negotiation. 1358 This alert is always fatal. 1360 decode_error 1361 A message could not be decoded because some field was out of the 1362 specified range or the length of the message was incorrect. This 1363 alert is always fatal and should never be observed in 1364 communication between proper implementations (except when messages 1365 were corrupted in the network). 1367 decrypt_error 1368 A handshake cryptographic operation failed, including being unable 1369 to correctly verify a signature or validate a Finished message. 1370 This alert is always fatal. 1372 protocol_version 1373 The protocol version the peer has attempted to negotiate is 1374 recognized but not supported. (For example, old protocol versions 1375 might be avoided for security reasons.) This alert is always 1376 fatal. 1378 insufficient_security 1379 Returned instead of "handshake_failure" when a negotiation has 1380 failed specifically because the server requires ciphers more 1381 secure than those supported by the client. This alert is always 1382 fatal. 1384 internal_error 1385 An internal error unrelated to the peer or the correctness of the 1386 protocol (such as a memory allocation failure) makes it impossible 1387 to continue. This alert is always fatal. 1389 inappropriate_fallback 1390 Sent by a server in response to an invalid connection retry 1391 attempt from a client. (see [RFC7507]) This alert is always fatal. 1393 missing_extension 1394 Sent by endpoints that receive a hello message not containing an 1395 extension that is mandatory to send for the offered TLS version. 1396 This message is always fatal. [[TODO: IANA Considerations.]] 1398 unsupported_extension 1399 Sent by endpoints receiving any hello message containing an 1400 extension known to be prohibited for inclusion in the given hello 1401 message, including any extensions in a ServerHello not first 1402 offered in the corresponding ClientHello. This alert is always 1403 fatal. 1405 certificate_unobtainable 1406 Sent by servers when unable to obtain a certificate from a URL 1407 provided by the client via the "client_certificate_url" extension 1408 [RFC6066]. 1410 unrecognized_name 1411 Sent by servers when no server exists identified by the name 1412 provided by the client via the "server_name" extension [RFC6066]. 1414 bad_certificate_status_response 1415 Sent by clients when an invalid or unacceptable OCSP response is 1416 provided by the server via the "status_request" extension 1417 [RFC6066]. This alert is always fatal. 1419 bad_certificate_hash_value 1420 Sent by servers when a retrieved object does not have the correct 1421 hash provided by the client via the "client_certificate_url" 1422 extension [RFC6066]. This alert is always fatal. 1424 unknown_psk_identity 1425 Sent by servers when a PSK cipher suite is selected but no 1426 acceptable PSK identity is provided by the client. Sending this 1427 alert is OPTIONAL; servers MAY instead choose to send a 1428 "decrypt_error" alert to merely indicate an invalid PSK identity. 1429 [[TODO: This doesn't really make sense with the current PSK 1430 negotiation scheme where the client provides multiple PSKs in 1431 flight 1. https://github.com/tlswg/tls13-spec/issues/230]] 1433 New Alert values are assigned by IANA as described in Section 11. 1435 6.2. Handshake Protocol Overview 1437 The cryptographic parameters of the session state are produced by the 1438 TLS Handshake Protocol, which operates on top of the TLS record 1439 layer. When a TLS client and server first start communicating, they 1440 agree on a protocol version, select cryptographic algorithms, 1441 optionally authenticate each other, and establish shared secret 1442 keying material. 1444 TLS supports three basic key exchange modes: 1446 - Diffie-Hellman (of both the finite field and elliptic curve 1447 varieties). 1449 - A pre-shared symmetric key (PSK) 1451 - A combination of a symmetric key and Diffie-Hellman 1453 Which mode is used depends on the negotiated cipher suite. 1454 Conceptually, the handshake establishes three secrets which are used 1455 to derive all the keys. 1457 Ephemeral Secret (ES): A secret which is derived from fresh (EC)DHE 1458 shares for this connection. Keying material derived from ES is 1459 intended to be forward secret (with the exception of pre-shared key 1460 only modes). 1462 Static Secret (SS): A secret which may be derived from static or 1463 semi-static keying material, such as a pre-shared key or the server's 1464 semi-static (EC)DH share. 1466 Master Secret (MS): A secret derived from both the static and the 1467 ephemeral secret. 1469 In some cases, as with the DH handshake shown in Figure 1, the 1470 ephemeral and shared secrets are the same, but having both allows for 1471 a uniform key derivation scheme for all cipher modes. 1473 The basic TLS Handshake for DH is shown in Figure 1: 1475 Client Server 1477 Key / ClientHello 1478 Exch \ + key_share --------> 1479 ServerHello \ Key 1480 + key_share / Exch 1481 {EncryptedExtensions} ^ 1482 {CertificateRequest*} | Server 1483 {ServerConfiguration*} v Params 1484 {Certificate*} ^ 1485 {CertificateVerify*} | Auth 1486 <-------- {Finished} v 1487 ^ {Certificate*} 1488 Auth | {CertificateVerify*} 1489 v {Finished} --------> 1490 [Application Data] <-------> [Application Data] 1492 + Indicates extensions sent in the 1493 previously noted message. 1495 * Indicates optional or situation-dependent 1496 messages that are not always sent. 1498 {} Indicates messages protected using keys 1499 derived from the ephemeral secret. 1501 [] Indicates messages protected using keys 1502 derived from the master secret. 1504 Figure 1: Message flow for full TLS Handshake 1506 The handshake can be thought of as having three phases, indicated in 1507 the diagram above. 1509 Key Exchange: establish shared keying material and select the 1510 cryptographic parameters. Everything after this phase is encrypted. 1512 Server Parameters: establish other handshake parameters (whether the 1513 client is authenticated, support for 0-RTT, etc.) 1515 Authentication: authenticate the server (and optionally the client) 1516 and provide key confirmation and handshake integrity. 1518 In the Key Exchange phase, the client sends the ClientHello 1519 (Section 6.3.1.1) message, which contains a random nonce 1520 (ClientHello.random), its offered protocol version, cipher suite, and 1521 extensions, and one or more Diffie-Hellman key shares in the 1522 "key_share" extension Section 6.3.2.3. 1524 The server processes the ClientHello and determines the appropriate 1525 cryptographic parameters for the connection. It then responds with 1526 its own ServerHello which indicates the negotiated connection 1527 parameters. [Section 6.3.1.2] If DH is in use, this will contain a 1528 "key_share" extension with the server's ephemeral Diffie-Hellman 1529 share which MUST be in the same group as one of the shares offered by 1530 the client. The server's KeyShare and the client's KeyShare 1531 corresponding to the negotiated key exchange are used together to 1532 derive the Static Secret and Ephemeral Secret (in this mode they are 1533 the same). [Section 6.3.2.3] 1535 The server then sends three messages to establish the Server 1536 Parameters: 1538 EncryptedExtensions 1539 responses to any extensions which are not required in order to 1540 determine the cryptographic parameters. [Section 6.3.3.1] 1542 CertificateRequest 1543 if certificate-based client authentication is desired, the desired 1544 parameters for that certificate. This message will be omitted if 1545 client authentication is not desired. [[OPEN ISSUE: See 1546 https://github.com/tlswg/tls13-spec/issues/184]]. 1547 [Section 6.3.3.2] 1549 ServerConfiguration 1550 supplies a configuration for 0-RTT handshakes (see Section 6.2.2). 1551 [Section 6.3.3.3] 1553 Finally, the client and server exchange Authentication messages. TLS 1554 uses the same set of messages every time that authentication is 1555 needed. Specifically: 1557 Certificate 1558 the certificate of the endpoint. This message is omitted if 1559 certificate authentication is not being used. [Section 6.3.4.1] 1561 CertificateVerify 1562 a signature over the entire handshake using the public key in the 1563 Certificate message. This message will be omitted if the server 1564 is not authenticating via a certificate. [Section 6.3.4.2] 1566 Finished 1567 a MAC over the entire handshake. This message provides key 1568 confirmation, binds the endpoint's identity to the exchanged keys, 1569 and in some modes (0-RTT and PSK) also authenticates the handshake 1570 using the the Static Secret. [Section 6.3.4.3] 1572 Upon receiving the server's messages, the client responds with its 1573 Authentication messages, namely Certificate and CertificateVerify (if 1574 requested), and Finished. 1576 At this point, the handshake is complete, and the client and server 1577 may exchange application layer data. Application data MUST NOT be 1578 sent prior to sending the Finished message. Note that while the 1579 server may send application data prior to receiving the client's 1580 Authentication messages, any data sent at that point is of course 1581 being sent to an unauthenticated peer. 1583 [[TODO: Move this elsewhere? Note that higher layers should not be 1584 overly reliant on whether TLS always negotiates the strongest 1585 possible connection between two endpoints. There are a number of 1586 ways in which a man-in-the-middle attacker can attempt to make two 1587 entities drop down to the least secure method they support (i.e., 1588 perform a downgrade attack). The TLS protocol has been designed to 1589 minimize this risk, but there are still attacks available: for 1590 example, an attacker could block access to the port a secure service 1591 runs on, or attempt to get the peers to negotiate an unauthenticated 1592 connection. The fundamental rule is that higher levels must be 1593 cognizant of what their security requirements are and never transmit 1594 information over a channel less secure than what they require. The 1595 TLS protocol is secure in that any cipher suite offers its promised 1596 level of security: if you negotiate AES-GCM [GCM] with a 255-bit 1597 ECDHE key exchange with a host whose certificate chain you have 1598 verified, you can expect that to be reasonably "secure" against 1599 algorithmic attacks, at least in the year 2015.]] 1601 6.2.1. Incorrect DHE Share 1603 If the client has not provided an appropriate "key_share" extension 1604 (e.g. it includes only DHE or ECDHE groups unacceptable or 1605 unsupported by the server), the server corrects the mismatch with a 1606 HelloRetryRequest and the client will need to restart the handshake 1607 with an appropriate "key_share" extension, as shown in Figure 2: 1609 Client Server 1611 ClientHello 1612 + key_share --------> 1613 <-------- HelloRetryRequest 1615 ClientHello 1616 + key_share --------> 1617 ServerHello 1618 + key_share 1619 {EncryptedExtensions} 1620 {CertificateRequest*} 1621 {ServerConfiguration*} 1622 {Certificate*} 1623 {CertificateVerify*} 1624 <-------- {Finished} 1625 {Certificate*} 1626 {CertificateVerify*} 1627 {Finished} --------> 1628 [Application Data] <-------> [Application Data] 1630 Figure 2: Message flow for a full handshake with mismatched 1631 parameters 1633 [[OPEN ISSUE: Should we restart the handshake hash? 1634 https://github.com/tlswg/tls13-spec/issues/104.]] [[OPEN ISSUE: We 1635 need to make sure that this flow doesn't introduce downgrade issues. 1636 Potential options include continuing the handshake hashes (as long as 1637 clients don't change their opinion of the server's capabilities with 1638 aborted handshakes) and requiring the client to send the same 1639 ClientHello (as is currently done) and then checking you get the same 1640 negotiated parameters.]] 1642 If no common cryptographic parameters can be negotiated, the server 1643 will send a "handshake_failure" or "insufficient_security" fatal 1644 alert (see Section 6.1). 1646 TLS also allows several optimized variants of the basic handshake, as 1647 described below. 1649 6.2.2. Zero-RTT Exchange 1651 TLS 1.3 supports a "0-RTT" mode in which the client can both 1652 authenticate and send application on its first flight, thus reducing 1653 handshake latency. In order to enable this functionality, the server 1654 provides a ServerConfiguration message containing a long-term (EC)DH 1655 share. On future connections to the same server, the client can use 1656 that share to protect the first-flight data. 1658 Client Server 1660 ClientHello 1661 + key_share 1662 + early_data 1663 ^ (Certificate*) 1664 0-RTT | (CertificateVerify*) 1665 Data | (Finished) 1666 v (Application Data*) 1667 (end_of_early_data) --------> 1668 ServerHello 1669 + early_data 1670 + key_share 1671 {EncryptedExtensions} 1672 {CertificateRequest*} 1673 {ServerConfiguration*} 1674 {Certificate*} 1675 {CertificateVerify*} 1676 <-------- {Finished} 1677 {Certificate*} 1678 {CertificateVerify*} 1679 {Finished} --------> 1681 [Application Data] <-------> [Application Data] 1683 * Indicates optional or situation-dependent 1684 messages that are not always sent. 1686 () Indicates messages protected using keys 1687 derived from the static secret. 1689 {} Indicates messages protected using keys 1690 derived from the ephemeral secret. 1692 [] Indicates messages protected using keys 1693 derived from the master secret. 1695 Figure 3: Message flow for a zero round trip handshake 1697 As shown in Figure 3, the Zero-RTT data is just added to the 1-RTT 1698 handshake in the first flight. Specifically, the client sends its 1699 Authentication messages after the ClientHello, followed by any 1700 application data. The rest of the handshake messages are the same as 1701 with Figure 1. This implies that the server can request client 1702 authentication even if the client offers a certificate on its first 1703 flight. This is consistent with the server being able to ask for 1704 client authentication after the handshake is complete (see 1705 Section 6.3.5.2). When offering PSK support, the "pre_shared_key" 1706 extension will be used instead of (or in addition to) the "key_share" 1707 extension as specified above. 1709 IMPORTANT NOTE: The security properties for 0-RTT data (regardless of 1710 the cipher suite) are weaker than those for other kinds of TLS data. 1711 Specifically: 1713 1. This data is not forward secret, because it is encrypted solely 1714 with the server's semi-static (EC)DH share. 1716 2. There are no guarantees of non-replay between connections. 1717 Unless the server takes special measures outside those provided 1718 by TLS (See Section 6.3.2.5.2), the server has no guarantee that 1719 the same 0-RTT data was not transmitted on multiple 0-RTT 1720 connections. This is especially relevant if the data is 1721 authenticated either with TLS client authentication or inside the 1722 application layer protocol. However, 0-RTT data cannot be 1723 duplicated within a connection (i.e., the server will not process 1724 the same data twice for the same connection) and also cannot be 1725 sent as if it were ordinary TLS data. 1727 3. If the server key is compromised, then the attacker can tamper 1728 with the 0-RTT data without detection. If the client's ephemeral 1729 share is compromised and client authentication is used, then the 1730 attacker can impersonate the client on subsequent connections. 1732 6.2.3. Resumption and PSK 1734 Finally, TLS provides a pre-shared key (PSK) mode which allows a 1735 client and server who share an existing secret (e.g., a key 1736 established out of band) to establish a connection authenticated by 1737 that key. PSKs can also be established in a previous session and 1738 then reused ("session resumption"). Once a handshake has completed, 1739 the server can send the client a PSK identity which corresponds to a 1740 key derived from the initial handshake (See Section 6.3.5.1). The 1741 client can then use that PSK identity in future handshakes to 1742 negotiate use of the PSK; if the server accepts it, then the security 1743 context of the original connection is tied to the new connection. In 1744 TLS 1.2 and below, this functionality was provided by "session 1745 resumption" and "session tickets" [RFC5077]. Both mechanisms are 1746 obsoleted in TLS 1.3. 1748 PSK cipher suites can either use PSK in combination with an (EC)DHE 1749 exchange in order to provide forward secrecy in combination with 1750 shared keys, or can use PSKs alone, at the cost of losing forward 1751 secrecy. 1753 Figure 4 shows a pair of handshakes in which the first establishes a 1754 PSK and the second uses it: 1756 Client Server 1758 Initial Handshake: 1759 ClientHello 1760 + key_share --------> 1761 ServerHello 1762 + key_share 1763 {EncryptedExtensions} 1764 {CertificateRequest*} 1765 {ServerConfiguration*} 1766 {Certificate*} 1767 {CertificateVerify*} 1768 <-------- {Finished} 1769 {Certificate*} 1770 {CertificateVerify*} 1771 {Finished} --------> 1772 <-------- [NewSessionTicket] 1773 [Application Data] <-------> [Application Data] 1775 Subsequent Handshake: 1776 ClientHello 1777 + key_share 1778 + pre_shared_key --------> 1779 ServerHello 1780 + pre_shared_key 1781 {EncryptedExtensions} 1782 <-------- {Finished} 1783 {Finished} --------> 1784 [Application Data] <-------> [Application Data] 1786 Figure 4: Message flow for resumption and PSK 1788 As the server is authenticating via a PSK, it does not send a 1789 Certificate or a CertificateVerify. PSK-based resumption cannot be 1790 used to provide a new ServerConfiguration. Note that the client 1791 supplies a KeyShare to the server as well, which allows the server to 1792 decline resumption and fall back to a full handshake. 1794 The contents and significance of each message will be presented in 1795 detail in the following sections. 1797 6.3. Handshake Protocol 1799 The TLS Handshake Protocol is one of the defined higher-level clients 1800 of the TLS Record Protocol. This protocol is used to negotiate the 1801 secure attributes of a session. Handshake messages are supplied to 1802 the TLS record layer, where they are encapsulated within one or more 1803 TLSPlaintext or TLSCiphertext structures, which are processed and 1804 transmitted as specified by the current active session state. 1806 enum { 1807 client_hello(1), 1808 server_hello(2), 1809 session_ticket(4), 1810 hello_retry_request(6), 1811 encrypted_extensions(8), 1812 certificate(11), 1813 certificate_request(13), 1814 certificate_verify(15), 1815 server_configuration(17), 1816 finished(20), 1817 key_update(24), 1818 (255) 1819 } HandshakeType; 1821 struct { 1822 HandshakeType msg_type; /* handshake type */ 1823 uint24 length; /* bytes in message */ 1824 select (HandshakeType) { 1825 case client_hello: ClientHello; 1826 case server_hello: ServerHello; 1827 case hello_retry_request: HelloRetryRequest; 1828 case encrypted_extensions: EncryptedExtensions; 1829 case certificate_request: CertificateRequest; 1830 case server_configuration:ServerConfiguration; 1831 case certificate: Certificate; 1832 case certificate_verify: CertificateVerify; 1833 case finished: Finished; 1834 case session_ticket: NewSessionTicket; 1835 case key_update: KeyUpdate; 1836 } body; 1837 } Handshake; 1839 The TLS Handshake Protocol messages are presented below in the order 1840 they MUST be sent; sending handshake messages in an unexpected order 1841 results in an "unexpected_message" fatal error. Unneeded handshake 1842 messages can be omitted, however. 1844 New handshake message types are assigned by IANA as described in 1845 Section 11. 1847 6.3.1. Key Exchange Messages 1849 The key exchange messages are used to exchange security capabilities 1850 between the client and server and to establish the traffic keys used 1851 to protect the handshake and the data. 1853 6.3.1.1. Client Hello 1855 When this message will be sent: 1857 When a client first connects to a server, it is required to send 1858 the ClientHello as its first message. The client will also send a 1859 ClientHello when the server has responded to its ClientHello with 1860 a ServerHello that selects cryptographic parameters that don't 1861 match the client's "key_share" extension. In that case, the 1862 client MUST send the same ClientHello (without modification) 1863 except including a new KeyShareEntry as the lowest priority share 1864 (i.e., appended to the list of shares in the KeyShare message). 1865 [[OPEN ISSUE: New random values? See: https://github.com/tlswg/ 1866 tls13-spec/issues/185]] If a server receives a ClientHello at any 1867 other time, it MUST send a fatal "unexpected_message" alert and 1868 close the connection. 1870 Structure of this message: 1872 The ClientHello message includes a random structure, which is used 1873 later in the protocol. 1875 struct { 1876 opaque random_bytes[32]; 1877 } Random; 1879 random_bytes 1880 32 bytes generated by a secure random number generator. See 1881 Appendix B for additional information. 1883 TLS 1.3 server implementations which respond to a ClientHello with a 1884 client_version indicating TLS 1.2 or below MUST set the first eight 1885 bytes of their Random value to the bytes: 1887 44 4F 57 4E 47 52 44 01 1889 TLS 1.2 server implementations which respond to a ClientHello with a 1890 client_version indicating TLS 1.1 or below SHOULD set the first eight 1891 bytes of their Random value to the bytes: 1893 44 4F 57 4E 47 52 44 00 1895 TLS 1.3 clients receiving a TLS 1.2 or below ServerHello MUST check 1896 that the top eight octets are not equal to either of these values. 1897 TLS 1.2 clients SHOULD also perform this check if the ServerHello 1898 indicates TLS 1.1 or below. If a match is found the client MUST 1899 abort the handshake with a fatal "illegal_parameter" alert. This 1900 mechanism provides limited protection against downgrade attacks over 1901 and above that provided by the Finished exchange: because the 1902 ServerKeyExchange includes a signature over both random values, it is 1903 not possible for an active attacker to modify the randoms without 1904 detection as long as ephemeral ciphers are used. It does not provide 1905 downgrade protection when static RSA is used. 1907 Note: This is an update to TLS 1.2 so in practice many TLS 1.2 1908 clients and servers will not behave as specified above. 1910 Note: Versions of TLS prior to TLS 1.3 used the top 32 bits of the 1911 Random value to encode the time since the UNIX epoch. The sentinel 1912 value above was selected to avoid conflicting with any valid TLS 1.2 1913 Random value and to have a low (2^{-64}) probability of colliding 1914 with randomly selected Random values. 1916 The cipher suite list, passed from the client to the server in the 1917 ClientHello message, contains the combinations of cryptographic 1918 algorithms supported by the client in order of the client's 1919 preference (favorite choice first). Each cipher suite defines a key 1920 exchange algorithm, a record protection algorithm (including secret 1921 key length) and a hash to be used with HKDF. The server will select 1922 a cipher suite or, if no acceptable choices are presented, return a 1923 "handshake_failure" alert and close the connection. If the list 1924 contains cipher suites the server does not recognize, support, or 1925 wish to use, the server MUST ignore those cipher suites, and process 1926 the remaining ones as usual. 1928 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1930 struct { 1931 ProtocolVersion client_version = { 3, 4 }; /* TLS v1.3 */ 1932 Random random; 1933 opaque legacy_session_id<0..32>; 1934 CipherSuite cipher_suites<2..2^16-2>; 1935 opaque legacy_compression_methods<1..2^8-1>; 1936 Extension extensions<0..2^16-1>; 1937 } ClientHello; 1939 TLS allows extensions to follow the compression_methods field in an 1940 extensions block. The presence of extensions can be detected by 1941 determining whether there are bytes following the compression_methods 1942 at the end of the ClientHello. Note that this method of detecting 1943 optional data differs from the normal TLS method of having a 1944 variable-length field, but it is used for compatibility with TLS 1945 before extensions were defined. 1947 client_version 1948 The version of the TLS protocol by which the client wishes to 1949 communicate during this session. This SHOULD be the latest 1950 (highest valued) version supported by the client. For this 1951 version of the specification, the version will be { 3, 4 }. (See 1952 Appendix C for details about backward compatibility.) 1954 random 1955 A client-generated random structure. 1957 legacy_session_id 1958 Versions of TLS before TLS 1.3 supported a session resumption 1959 feature which has been merged with Pre-Shared Keys in this version 1960 (see Section 6.2.3). This field MUST be ignored by a server 1961 negotiating TLS 1.3 and SHOULD be set as a zero length vector 1962 (i.e., a single zero byte length field) by clients which do not 1963 have a cached session ID set by a pre-TLS 1.3 server. 1965 cipher_suites 1966 This is a list of the cryptographic options supported by the 1967 client, with the client's first preference first. Values are 1968 defined in Appendix A.4. 1970 legacy_compression_methods 1971 Versions of TLS before 1.3 supported compression and the list of 1972 compression methods was supplied in this field. For any TLS 1.3 1973 ClientHello, this vector MUST contain exactly one byte set to 1974 zero, which corresponds to the "null" compression method in prior 1975 versions of TLS. If a TLS 1.3 ClientHello is received with any 1976 other value in this field, the server MUST generate a fatal 1977 "illegal_parameter" alert. Note that TLS 1.3 servers might 1978 receive TLS 1.2 or prior ClientHellos which contain other 1979 compression methods and MUST follow the procedures for the 1980 appropriate prior version of TLS. 1982 extensions 1983 Clients MAY request extended functionality from servers by sending 1984 data in the extensions field. The actual "Extension" format is 1985 defined in Section 6.3.2. 1987 In the event that a client requests additional functionality using 1988 extensions, and this functionality is not supplied by the server, the 1989 client MAY abort the handshake. A server MUST accept ClientHello 1990 messages both with and without the extensions field, and (as for all 1991 other messages) it MUST check that the amount of data in the message 1992 precisely matches one of these formats; if not, then it MUST send a 1993 fatal "decode_error" alert. 1995 After sending the ClientHello message, the client waits for a 1996 ServerHello or HelloRetryRequest message. 1998 6.3.1.2. Server Hello 2000 When this message will be sent: 2002 The server will send this message in response to a ClientHello 2003 message when it was able to find an acceptable set of algorithms 2004 and the client's "key_share" extension was acceptable. If the 2005 client proposed groups are not acceptable by the server, it will 2006 respond with a "handshake_failure" fatal alert. 2008 Structure of this message: 2010 struct { 2011 ProtocolVersion server_version; 2012 Random random; 2013 CipherSuite cipher_suite; 2014 select (extensions_present) { 2015 case false: 2016 struct {}; 2017 case true: 2018 Extension extensions<0..2^16-1>; 2019 }; 2020 } ServerHello; 2022 The presence of extensions can be detected by determining whether 2023 there are bytes following the cipher_suite field at the end of the 2024 ServerHello. 2026 server_version 2027 This field will contain the lower of that suggested by the client 2028 in the ClientHello and the highest supported by the server. For 2029 this version of the specification, the version is { 3, 4 }. (See 2030 Appendix C for details about backward compatibility.) 2032 random 2033 This structure is generated by the server and MUST be generated 2034 independently of the ClientHello.random. 2036 cipher_suite 2037 The single cipher suite selected by the server from the list in 2038 ClientHello.cipher_suites. For resumed sessions, this field is 2039 the value from the state of the session being resumed. [[TODO: 2040 interaction with PSK.]] 2042 extensions 2043 A list of extensions. Note that only extensions offered by the 2044 client can appear in the server's list. In TLS 1.3 as opposed to 2045 previous versions of TLS, the server's extensions are split 2046 between the ServerHello and the EncryptedExtensions 2047 Section 6.3.3.1 message. The ServerHello MUST only include 2048 extensions which are required to establish the cryptographic 2049 context. Currently the only such extensions are "key_share", 2050 "pre_shared_key", and "early_data". Clients MUST check the 2051 ServerHello for the presence of any forbidden extensions and if 2052 any are found MUST terminate the handshake with a 2053 "illegal_parameter" alert. 2055 6.3.1.3. Hello Retry Request 2057 When this message will be sent: 2059 Servers send this message in response to a ClientHello message 2060 when it was able to find an acceptable set of algorithms and 2061 groups that are mutually supported, but the client's KeyShare did 2062 not contain an acceptable offer. If it cannot find such a match, 2063 it will respond with a fatal "handshake_failure" alert. 2065 Structure of this message: 2067 struct { 2068 ProtocolVersion server_version; 2069 CipherSuite cipher_suite; 2070 NamedGroup selected_group; 2071 Extension extensions<0..2^16-1>; 2072 } HelloRetryRequest; 2074 [[OPEN ISSUE: Merge in DTLS Cookies?]] 2076 selected_group 2077 The mutually supported group the server intends to negotiate and 2078 is requesting a retried ClientHello/KeyShare for. 2080 The server_version, cipher_suite, and extensions fields have the same 2081 meanings as their corresponding values in the ServerHello. The 2082 server SHOULD send only the extensions necessary for the client to 2083 generate a correct ClientHello pair. As with ServerHello, a 2084 HelloRetryRequest MUST NOT contain any extensions that were not first 2085 offered by the client in its ClientHello. 2087 Upon receipt of a HelloRetryRequest, the client MUST first verify 2088 that the selected_group field corresponds to a group which was 2089 provided in the "supported_groups" extension in the original 2090 ClientHello. It MUST then verify that the selected_group field does 2091 not correspond to a group which was provided in the "key_share" 2092 extension in the original ClientHello. If either of these checks 2093 fails, then the client MUST abort the handshake with a fatal 2094 "handshake_failure" alert. Clients SHOULD also abort with 2095 "handshake_failure" in response to any second HelloRetryRequest which 2096 was sent in the same connection (i.e., where the ClientHello was 2097 itself in response to a HelloRetryRequest). 2099 Otherwise, the client MUST send a ClientHello with an updated 2100 KeyShare extension to the server. The client MUST append a new 2101 KeyShareEntry for the group indicated in the selected_group field to 2102 the groups in its original KeyShare. 2104 Upon re-sending the ClientHello and receiving the server's 2105 ServerHello/KeyShare, the client MUST verify that the selected 2106 CipherSuite and NamedGroup match that supplied in the 2107 HelloRetryRequest. If either of these values differ, the client MUST 2108 abort the connection with a fatal "handshake_failure" alert. 2110 [[OPEN ISSUE: https://github.com/tlswg/tls13-spec/issues/104]] 2112 6.3.2. Hello Extensions 2114 The extension format is: 2116 struct { 2117 ExtensionType extension_type; 2118 opaque extension_data<0..2^16-1>; 2119 } Extension; 2121 enum { 2122 supported_groups(10), 2123 signature_algorithms(13), 2124 early_data(TBD), 2125 pre_shared_key(TBD), 2126 key_share(TBD), 2127 (65535) 2128 } ExtensionType; 2130 Here: 2132 - "extension_type" identifies the particular extension type. 2134 - "extension_data" contains information specific to the particular 2135 extension type. 2137 The initial set of extensions is defined in [RFC6066]. The list of 2138 extension types is maintained by IANA as described in Section 11. 2140 An extension type MUST NOT appear in the ServerHello or 2141 HelloRetryRequest unless the same extension type appeared in the 2142 corresponding ClientHello. If a client receives an extension type in 2143 ServerHello or HelloRetryRequest that it did not request in the 2144 associated ClientHello, it MUST abort the handshake with an 2145 "unsupported_extension" fatal alert. 2147 Nonetheless, "server-oriented" extensions may be provided in the 2148 future within this framework. Such an extension (say, of type x) 2149 would require the client to first send an extension of type x in a 2150 ClientHello with empty extension_data to indicate that it supports 2151 the extension type. In this case, the client is offering the 2152 capability to understand the extension type, and the server is taking 2153 the client up on its offer. 2155 When multiple extensions of different types are present in the 2156 ClientHello or ServerHello messages, the extensions MAY appear in any 2157 order. There MUST NOT be more than one extension of the same type. 2159 Finally, note that extensions can be sent both when starting a new 2160 session and when requesting session resumption or 0-RTT mode. 2161 Indeed, a client that requests session resumption does not in general 2162 know whether the server will accept this request, and therefore it 2163 SHOULD send the same extensions as it would send if it were not 2164 attempting resumption. 2166 In general, the specification of each extension type needs to 2167 describe the effect of the extension both during full handshake and 2168 session resumption. Most current TLS extensions are relevant only 2169 when a session is initiated: when an older session is resumed, the 2170 server does not process these extensions in ClientHello, and does not 2171 include them in ServerHello. However, some extensions may specify 2172 different behavior during session resumption. [[TODO: update this 2173 and the previous paragraph to cover PSK-based resumption.]] 2175 There are subtle (and not so subtle) interactions that may occur in 2176 this protocol between new features and existing features which may 2177 result in a significant reduction in overall security. The following 2178 considerations should be taken into account when designing new 2179 extensions: 2181 - Some cases where a server does not agree to an extension are error 2182 conditions, and some are simply refusals to support particular 2183 features. In general, error alerts should be used for the former, 2184 and a field in the server extension response for the latter. 2186 - Extensions should, as far as possible, be designed to prevent any 2187 attack that forces use (or non-use) of a particular feature by 2188 manipulation of handshake messages. This principle should be 2189 followed regardless of whether the feature is believed to cause a 2190 security problem. Often the fact that the extension fields are 2191 included in the inputs to the Finished message hashes will be 2192 sufficient, but extreme care is needed when the extension changes 2193 the meaning of messages sent in the handshake phase. Designers 2194 and implementors should be aware of the fact that until the 2195 handshake has been authenticated, active attackers can modify 2196 messages and insert, remove, or replace extensions. 2198 - It would be technically possible to use extensions to change major 2199 aspects of the design of TLS; for example the design of cipher 2200 suite negotiation. This is not recommended; it would be more 2201 appropriate to define a new version of TLS -- particularly since 2202 the TLS handshake algorithms have specific protection against 2203 version rollback attacks based on the version number, and the 2204 possibility of version rollback should be a significant 2205 consideration in any major design change. 2207 6.3.2.1. Signature Algorithms 2209 The client uses the "signature_algorithms" extension to indicate to 2210 the server which signature/hash algorithm pairs may be used in 2211 digital signatures. 2213 Clients which offer one or more cipher suites which use certificate 2214 authentication (i.e., any non-PSK cipher suite) MUST send the 2215 "signature_algorithms" extension. If this extension is not provided 2216 and no alternative cipher suite is available, the server MUST close 2217 the connection with a fatal "missing_extension" alert. (see 2218 Section 8.2) 2220 The "extension_data" field of this extension contains a 2221 "supported_signature_algorithms" value: 2223 enum { 2224 none(0), 2225 sha1(2), 2226 sha256(4), sha384(5), sha512(6), 2227 (255) 2228 } HashAlgorithm; 2230 enum { 2231 rsa(1), 2232 dsa(2), 2233 ecdsa(3), 2234 rsapss(4), 2235 eddsa(5), 2236 (255) 2237 } SignatureAlgorithm; 2239 struct { 2240 HashAlgorithm hash; 2241 SignatureAlgorithm signature; 2242 } SignatureAndHashAlgorithm; 2244 SignatureAndHashAlgorithm 2245 supported_signature_algorithms<2..2^16-2>; 2247 [[TODO: IANA considerations for new SignatureAlgorithm value]] 2249 Each SignatureAndHashAlgorithm value lists a single hash/signature 2250 pair that the client is willing to verify. The values are indicated 2251 in descending order of preference. 2253 Note: Because not all signature algorithms and hash algorithms may be 2254 accepted by an implementation (e.g., ECDSA with SHA-256, but not SHA- 2255 384), algorithms here are listed in pairs. 2257 hash 2258 This field indicates the hash algorithms which may be used. The 2259 values indicate support for unhashed data, SHA-1, SHA-256, SHA- 2260 384, and SHA-512 [SHS], respectively. The "none" value is 2261 provided for signature algorithms which do not require hashing 2262 before signing, such as EdDSA. Previous versions of TLS supported 2263 MD5, SHA-1, and SHA-224. These algorithms are now deprecated. 2264 MD5 and SHA-224 MUST NOT be offered by TLS 1.3 implementations; 2265 SHA-1 SHOULD NOT be offered. Clients MAY offer support for SHA-1 2266 for backwards compatibility, either with TLS 1.2 servers or for 2267 servers that have certification paths with signatures based on 2268 SHA-1. 2270 signature 2271 This field indicates the signature algorithm that may be used. 2272 The values indicate RSASSA-PKCS1-v1_5 [RFC3447], DSA [DSS], ECDSA 2273 [ECDSA], RSASSA-PSS [RFC3447], and EdDSA [I-D.irtf-cfrg-eddsa] 2274 respectively. Because all RSA signatures used in signed TLS 2275 handshake messages (see Section 4.8.1), as opposed to those in 2276 certificates, are RSASSA-PSS, the "rsa" value refers solely to 2277 signatures which appear in certificates. The use of DSA and 2278 anonymous is deprecated. Previous versions of TLS supported DSA. 2279 DSA is deprecated as of TLS 1.3 and SHOULD NOT be offered or 2280 negotiated by any implementation. 2282 The semantics of this extension are somewhat complicated because the 2283 cipher suite indicates permissible signature algorithms but not hash 2284 algorithms. Section 6.3.4.1.1 and Section 6.3.2.3 describe the 2285 appropriate rules. 2287 Clients offering support for SHA-1 for backwards compatibility MUST 2288 do so by listing those hash/signature pairs as the lowest priority 2289 (listed after all other pairs in the supported_signature_algorithms 2290 vector). TLS 1.3 servers MUST NOT offer a SHA-1 signed certificate 2291 unless no valid certificate chain can be produced without it (see 2292 Section 6.3.4.1.1). 2294 The signatures on certificates that are self-signed or certificates 2295 that are trust anchors are not validated since they begin a 2296 certification path (see [RFC5280], Section 3.2). A certificate that 2297 begins a certification path MAY use a hash or signature algorithm 2298 that is not advertised as being supported in the 2299 "signature_algorithms" extension. 2301 Note: TLS 1.3 servers might receive TLS 1.2 ClientHellos which do not 2302 contain this extension. If those servers are willing to negotiate 2303 TLS 1.2, they MUST behave in accordance with the requirements of 2304 [RFC5246] when negotiating that version. 2306 6.3.2.2. Negotiated Groups 2308 When sent by the client, the "supported_groups" extension indicates 2309 the named groups which the client supports, ordered from most 2310 preferred to least preferred. 2312 Note: In versions of TLS prior to TLS 1.3, this extension was named 2313 "elliptic_curves" and only contained elliptic curve groups. See 2314 [RFC4492] and [I-D.ietf-tls-negotiated-ff-dhe]. 2316 Clients which offer one or more (EC)DHE cipher suites MUST send at 2317 least one supported NamedGroup value and servers MUST NOT negotiate 2318 any of these cipher suites unless a supported value was provided. If 2319 this extension is not provided and no alternative cipher suite is 2320 available, the server MUST close the connection with a fatal 2321 "missing_extension" alert. (see Section 8.2) If the extension is 2322 provided, but no compatible group is offered, the server MUST NOT 2323 negotiate a cipher suite of the relevant type. For instance, if a 2324 client supplies only ECDHE groups, the server MUST NOT negotiate 2325 finite field Diffie-Hellman. If no acceptable group can be selected 2326 across all cipher suites, then the server MUST generate a fatal 2327 "handshake_failure" alert. 2329 The "extension_data" field of this extension contains a 2330 "NamedGroupList" value: 2332 enum { 2333 // Elliptic Curve Groups. 2334 secp256r1 (23), secp384r1 (24), secp521r1 (25), 2336 // ECDH functions. 2337 ecdh_x25519 (29), ecdh_x448 (30), 2339 // Signature-only curves. 2340 eddsa_ed25519 (31), eddsa_ed448 (32), 2342 // Finite Field Groups. 2343 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 2344 ffdhe6144 (259), ffdhe8192 (260), 2346 // Reserved Code Points. 2347 ffdhe_private_use (0x01FC..0x01FF), 2348 ecdhe_private_use (0xFE00..0xFEFF), 2349 (0xFFFF) 2350 } NamedGroup; 2352 struct { 2353 NamedGroup named_group_list<1..2^16-1>; 2354 } NamedGroupList; 2356 secp256r1, etc. 2357 Indicates support of the corresponding named curve. Note that 2358 some curves are also recommended in ANSI X9.62 [X962] and FIPS 2359 186-4 [DSS]. Values 0xFE00 through 0xFEFF are reserved for 2360 private use. 2362 ecdh_x25519 and ecdh_x448 2363 Indicates support of the corresponding ECDH functions X25519 and 2364 X448. 2366 eddsa_ed25519 and eddsa_ed448 2367 Indicates support of the corresponding curve for signatures. 2369 ffdhe2048, etc. 2370 Indicates support of the corresponding finite field group, defined 2371 in [I-D.ietf-tls-negotiated-ff-dhe]. Values 0x01FC through 0x01FF 2372 are reserved for private use. 2374 Items in named_group_list are ordered according to the client's 2375 preferences (most preferred choice first). 2377 As an example, a client that only supports secp256r1 (aka NIST P-256; 2378 value 23 = 0x0017) and secp384r1 (aka NIST P-384; value 24 = 0x0018) 2379 and prefers to use secp256r1 would include a TLS extension consisting 2380 of the following octets. Note that the first two octets indicate the 2381 extension type ("supported_groups" extension): 2383 00 0A 00 06 00 04 00 17 00 18 2385 NOTE: A server participating in an ECDHE-ECDSA key exchange may use 2386 different curves for (i) the ECDSA or EdDSA key in its certificate, 2387 and (ii) the ephemeral ECDH key in its "key_share" extension. The 2388 server must consider the supported groups in both cases. 2390 [[TODO: IANA Considerations.]] 2392 6.3.2.3. Key Share 2394 The "key_share" extension contains the endpoint's cryptographic 2395 parameters for non-PSK key establishment methods (currently DHE or 2396 ECDHE). 2398 Clients which offer one or more (EC)DHE cipher suites MUST send this 2399 extension and SHOULD send at least one supported KeyShareEntry value. 2400 Servers MUST NOT negotiate any of these cipher suites unless a 2401 supported value was provided. If this extension is not provided in a 2402 ServerHello or ClientHello, and the peer is offering (EC)DHE cipher 2403 suites, then the endpoint MUST close the connection with a fatal 2404 "missing_extension" alert. (see Section 8.2) Clients MAY send an 2405 empty client_shares vector in order to request group selection from 2406 the server at the cost of an additional round trip. (see 2407 Section 6.3.1.3) 2409 struct { 2410 NamedGroup group; 2411 opaque key_exchange<1..2^16-1>; 2412 } KeyShareEntry; 2414 group 2415 The named group for the key being exchanged. Finite Field Diffie- 2416 Hellman [DH] parameters are described in Section 6.3.2.3.1; 2417 Elliptic Curve Diffie-Hellman parameters are described in 2418 Section 6.3.2.3.2. Signature-only curves, currently eddsa_ed25519 2419 (31) and eddsa_ed448 (32), MUST NOT be used for key exchange. 2421 key_exchange 2422 Key exchange information. The contents of this field are 2423 determined by the specified group and its corresponding 2424 definition. Endpoints MUST NOT send empty or otherwise invalid 2425 key_exchange values for any reason. 2427 The "extension_data" field of this extension contains a "KeyShare" 2428 value: 2430 struct { 2431 select (role) { 2432 case client: 2433 KeyShareEntry client_shares<4..2^16-1>; 2435 case server: 2436 KeyShareEntry server_share; 2437 } 2438 } KeyShare; 2440 client_shares 2441 A list of offered KeyShareEntry values in descending order of 2442 client preference. This vector MAY be empty if the client is 2443 requesting a HelloRetryRequest. The ordering of values here 2444 SHOULD match that of the ordering of offered support in the 2445 "supported_groups" extension. 2447 server_share 2448 A single KeyShareEntry value for the negotiated cipher suite. 2450 Servers offer exactly one KeyShareEntry value, which corresponds to 2451 the key exchange used for the negotiated cipher suite. 2453 Clients offer an arbitrary number of KeyShareEntry values, each 2454 representing a single set of key exchange parameters. For instance, 2455 a client might offer shares for several elliptic curves or multiple 2456 integer DH groups. The key_exchange values for each KeyShareEntry 2457 MUST by generated independently. Clients MUST NOT offer multiple 2458 KeyShareEntry values for the same parameters. Clients and servers 2459 MUST NOT offer any KeyShareEntry values for groups not listed in the 2460 client's "supported_groups" extension. Servers MUST NOT offer a 2461 KeyShareEntry value for a group not offered by the client in its 2462 corresponding KeyShare. Implementations receiving any KeyShare 2463 containing any of these prohibited values MUST abort the connection 2464 with a fatal "illegal_parameter" alert. 2466 If the server selects an (EC)DHE cipher suite and no mutually 2467 supported group is available between the two endpoints' KeyShare 2468 offers, yet there is a mutually supported group that can be found via 2469 the "supported_groups" extension, then the server MUST reply with a 2470 HelloRetryRequest. If there is no mutually supported group at all, 2471 the server MUST NOT negotiate an (EC)DHE cipher suite. 2473 [[TODO: Recommendation about what the client offers. Presumably 2474 which integer DH groups and which curves.]] 2476 6.3.2.3.1. Diffie-Hellman Parameters 2478 Diffie-Hellman [DH] parameters for both clients and servers are 2479 encoded in the opaque key_exchange field of a KeyShareEntry in a 2480 KeyShare structure. The opaque value contains the Diffie-Hellman 2481 public value (dh_Y = g^X mod p), encoded as a big-endian integer. 2483 opaque dh_Y<1..2^16-1>; 2485 6.3.2.3.2. ECDHE Parameters 2487 ECDHE parameters for both clients and servers are encoded in the the 2488 opaque key_exchange field of a KeyShareEntry in a KeyShare structure. 2489 The opaque value conveys the Elliptic Curve Diffie-Hellman public 2490 value (ecdh_Y) represented as a byte string ECPoint.point. 2492 opaque point <1..2^8-1>; 2494 point 2495 For secp256r1, secp384r1 and secp521r1, this is the byte string 2496 representation of an elliptic curve point following the conversion 2497 routine in Section 4.3.6 of ANSI X9.62 [X962]. For ecdh_x25519 2498 and ecdh_x448, this is raw opaque octet-string representation of 2499 point (in the format those functions use), 32 octets for 2500 ecdh_x25519 and 56 octets for ecdh_x448. 2502 Although X9.62 supports multiple point formats, any given curve MUST 2503 specify only a single point format. All curves currently specified 2504 in this document MUST only be used with the uncompressed point format 2505 (the format for all ECDH functions is considered uncompressed). 2507 Note: Versions of TLS prior to 1.3 permitted point negotiation; TLS 2508 1.3 removes this feature in favor of a single point format for each 2509 curve. 2511 6.3.2.4. Pre-Shared Key Extension 2513 The "pre_shared_key" extension is used to indicate the identity of 2514 the pre-shared key to be used with a given handshake in association 2515 with a PSK or (EC)DHE-PSK cipher suite (see [RFC4279] for 2516 background). 2518 Clients which offer one or more PSK cipher suites MUST send at least 2519 one supported psk_identity value and servers MUST NOT negotiate any 2520 of these cipher suites unless a supported value was provided. If 2521 this extension is not provided and no alternative cipher suite is 2522 available, the server MUST close the connection with a fatal 2523 "missing_extension" alert. (see Section 8.2) 2524 The "extension_data" field of this extension contains a 2525 "PreSharedKeyExtension" value: 2527 opaque psk_identity<0..2^16-1>; 2529 struct { 2530 select (Role) { 2531 case client: 2532 psk_identity identities<2..2^16-1>; 2534 case server: 2535 psk_identity identity; 2536 } 2537 } PreSharedKeyExtension; 2539 identity 2540 An opaque label for the pre-shared key. 2542 If no suitable identity is provided, the server MUST NOT negotiate a 2543 PSK cipher suite and MAY respond with an "unknown_psk_identity" alert 2544 message. Sending this alert is OPTIONAL; servers MAY instead choose 2545 to send a "decrypt_error" alert to merely indicate an invalid PSK 2546 identity or instead negotiate use of a non-PSK cipher suite, if 2547 available. 2549 If the server selects a PSK cipher suite, it MUST send a 2550 "pre_shared_key" extension with the identity that it selected. The 2551 client MUST verify that the server has selected one of the identities 2552 that the client supplied. If any other identity is returned, the 2553 client MUST generate a fatal "unknown_psk_identity" alert and close 2554 the connection. 2556 6.3.2.5. Early Data Indication 2558 In cases where TLS clients have previously interacted with the server 2559 and the server has supplied a ServerConfiguration (Section 6.3.3.3), 2560 the client can send application data and its Certificate/ 2561 CertificateVerify messages (if client authentication is required). 2562 If the client opts to do so, it MUST supply an "early_data" 2563 extension. 2565 The "extension_data" field of this extension contains an 2566 "EarlyDataIndication" value: 2568 struct { 2569 select (Role) { 2570 case client: 2571 opaque configuration_id<1..2^16-1>; 2572 CipherSuite cipher_suite; 2573 Extension extensions<0..2^16-1>; 2574 opaque context<0..255>; 2576 case server: 2577 struct {}; 2578 } 2579 } EarlyDataIndication; 2581 configuration_id 2582 The label for the configuration in question. 2584 cipher_suite 2585 The cipher suite which the client is using to encrypt the early 2586 data. 2588 extensions 2589 The extensions required to define the cryptographic configuration 2590 for the clients early data (see below for details). 2592 context 2593 An optional context value that can be used for anti-replay (see 2594 below). 2596 The client specifies the cryptographic configuration for the 0-RTT 2597 data using the "configuration_id", "cipher_suite", and "extensions" 2598 values. For configurations received in-band (in a previous TLS 2599 connection) the client MUST: 2601 - Send the same cryptographic determining parameters 2602 (Section Section 6.3.2.5.1) with the previous connection. If a 2603 0-RTT handshake is being used with a PSK that was negotiated via a 2604 non-PSK handshake, then the client MUST use the same symmetric 2605 cipher parameters as were negotiated on that handshake but with a 2606 PSK cipher suite. 2608 - Indicate the same parameters as the server indicated in that 2609 connection. 2611 0-RTT messages sent in the first flight have the same content types 2612 as their corresponding messages sent in other flights (handshake, 2613 application_data, and alert respectively) but are protected under 2614 different keys. After all the 0-RTT application data messages (if 2615 any) have been sent, a "end_of_early_data" alert of type "warning" is 2616 sent to indicate the end of the flight. Clients which do 0-RTT MUST 2617 always send "end_of_early_data" even if the ServerConfiguration 2618 indicates that no application data is allowed (EarlyDataType of 2619 "client_authentication"), though in that case it MUST NOT send any 2620 non-empty data records (i.e., those which consist of anything other 2621 than padding). 2623 A server which receives an "early_data" extension can behave in one 2624 of two ways: 2626 - Ignore the extension and return no response. This indicates that 2627 the server has ignored any early data and an ordinary 1-RTT 2628 handshake is required. 2630 - Return an empty extension, indicating that it intends to process 2631 the early data. It is not possible for the server to accept only 2632 a subset of the early data messages. 2634 Prior to accepting the "early_data" extension, the server MUST 2635 perform the following checks: 2637 - The configuration_id matches a known server configuration. 2639 - The client's cryptographic determining parameters match the 2640 parameters that the server has negotiated based on the rest of the 2641 ClientHello. If (EC)DHE is selected, this includes verifying that 2642 (1) the ClientHello contains a key from the same group that is 2643 indicated by the server configuration and (2) that the server has 2644 negotiated that group and will therefore include a share from that 2645 group in its own "key_share" extension. 2647 If any of these checks fail, the server MUST NOT respond with the 2648 extension and must discard all the remaining first flight data (thus 2649 falling back to 1-RTT). If the client attempts a 0-RTT handshake but 2650 the server rejects it, it will generally not have the 0-RTT record 2651 protection keys and will instead trial decrypt each record with the 2652 1-RTT handshake keys until it finds one that decrypts properly, and 2653 then pick up the handshake from that point. 2655 If the server choosed to accept the "early_data" extension, then it 2656 MUST comply with the same error handling requirements specified for 2657 all records when processing early data records. Specifically, 2658 decryption failure of any 0-RTT record following an accepted 2659 "early_data" extension MUST produce a fatal "bad_record_mac" alert as 2660 per Section 5.2.2. 2662 [[TODO: How does the client behave if the indication is rejected.]] 2664 [[OPEN ISSUE: This just specifies the signaling for 0-RTT but not the 2665 the 0-RTT cryptographic transforms, including: 2667 - What is in the handshake hash (including potentially some 2668 speculative data from the server). 2670 - What is signed in the client's CertificateVerify. 2672 - Whether we really want the Finished to not include the server's 2673 data at all. 2675 What's here now needs a lot of cleanup before it is clear and 2676 correct.]] 2678 6.3.2.5.1. Cryptographic Determining Parameters 2680 In order to allow the server to decrypt 0-RTT data, the client needs 2681 to provide enough information to allow the server to decrypt the 2682 traffic without negotiation. This is accomplished by having the 2683 client indicate the "cryptographic determining parameters" in its 2684 ClientHello, which are necessary to decrypt the client's packets 2685 (i.e., those present in the ServerHello). This includes the 2686 following values: 2688 - The cipher suite identifier. 2690 - If (EC)DHE is being used, the server's version of "key_share". 2692 - If PSK is being used, the server's version of the "pre_shared_key" 2693 (indicating the PSK the client is using). 2695 6.3.2.5.2. Replay Properties 2697 As noted in Section 6.2.2, TLS does not provide any inter-connection 2698 mechanism for replay protection for data sent by the client in the 2699 first flight. As a special case, implementations where the server 2700 configuration, is delivered out of band (as has been proposed for 2701 DTLS-SRTP [RFC5763]), MAY use a unique server configuration 2702 identifier for each connection, thus preventing replay. 2703 Implementations are responsible for ensuring uniqueness of the 2704 identifier in this case. 2706 6.3.3. Server Parameters 2707 6.3.3.1. Encrypted Extensions 2709 When this message will be sent: 2711 The EncryptedExtensions message MUST be sent immediately after the 2712 ServerHello message. This is the first message that is encrypted 2713 under keys derived from ES. 2715 Meaning of this message: 2717 The EncryptedExtensions message simply contains any extensions 2718 which should be protected, i.e., any which are not needed to 2719 establish the cryptographic context. The same extension types 2720 MUST NOT appear in both the ServerHello and EncryptedExtensions. 2721 If the same extension appears in both locations, the client MUST 2722 rely only on the value in the EncryptedExtensions block. All 2723 server-sent extensions other than those explicitly listed in 2724 Section 6.3.1.2 or designated in the IANA registry MUST only 2725 appear in EncryptedExtensions. Extensions which are designated to 2726 appear in ServerHello MUST NOT appear in EncryptedExtensions. 2727 Clients MUST check EncryptedExtensions for the presence of any 2728 forbidden extensions and if any are found MUST terminate the 2729 handshake with a "illegal_parameter" alert. 2731 Structure of this message: 2733 struct { 2734 Extension extensions<0..2^16-1>; 2735 } EncryptedExtensions; 2737 extensions 2738 A list of extensions. 2740 6.3.3.2. Certificate Request 2742 When this message will be sent: 2744 A non-anonymous server can optionally request a certificate from 2745 the client, if appropriate for the selected cipher suite. This 2746 message, if sent, will follow EncryptedExtensions. 2748 Structure of this message: 2750 opaque DistinguishedName<1..2^16-1>; 2752 struct { 2753 opaque certificate_extension_oid<1..2^8-1>; 2754 opaque certificate_extension_values<0..2^16-1>; 2755 } CertificateExtension; 2757 struct { 2758 opaque certificate_request_context<0..2^8-1>; 2759 SignatureAndHashAlgorithm 2760 supported_signature_algorithms<2..2^16-2>; 2761 DistinguishedName certificate_authorities<0..2^16-1>; 2762 CertificateExtension certificate_extensions<0..2^16-1>; 2763 } CertificateRequest; 2765 certificate_request_context 2766 An opaque string which identifies the certificate request and 2767 which will be echoed in the client's Certificate message. The 2768 certificate_request_context MUST be unique within the scope of 2769 this connection (thus preventing replay of client 2770 CertificateVerify messages). 2772 supported_signature_algorithms 2773 A list of the hash/signature algorithm pairs that the server is 2774 able to verify, listed in descending order of preference. Any 2775 certificates provided by the client MUST be signed using a hash/ 2776 signature algorithm pair found in supported_signature_algorithms. 2778 certificate_authorities 2779 A list of the distinguished names [X501] of acceptable 2780 certificate_authorities, represented in DER-encoded [X690] format. 2781 These distinguished names may specify a desired distinguished name 2782 for a root CA or for a subordinate CA; thus, this message can be 2783 used to describe known roots as well as a desired authorization 2784 space. If the certificate_authorities list is empty, then the 2785 client MAY send any certificate that meets the rest of the 2786 selection criteria in the CertificateRequest, unless there is some 2787 external arrangement to the contrary. 2789 certificate_extensions 2790 A list of certificate extension OIDs [RFC5280] with their allowed 2791 values, represented in DER-encoded [X690] format. Some 2792 certificate extension OIDs allow multiple values (e.g. Extended 2793 Key Usage). If the server has included a non-empty 2794 certificate_extensions list, the client certificate MUST contain 2795 all of the specified extension OIDs that the client recognizes. 2796 For each extension OID recognized by the client, all of the 2797 specified values MUST be present in the client certificate (but 2798 the certificate MAY have other values as well). However, the 2799 client MUST ignore and skip any unrecognized certificate extension 2800 OIDs. If the client has ignored some of the required certificate 2801 extension OIDs, and supplied a certificate that does not satisfy 2802 the request, the server MAY at its discretion either continue the 2803 session without client authentication, or terminate the session 2804 with a fatal unsupported_certificate alert. PKIX RFCs define a 2805 variety of certificate extension OIDs and their corresponding 2806 value types. Depending on the type, matching certificate 2807 extension values are not necessarily bitwise-equal. It is 2808 expected that TLS implementations will rely on their PKI libraries 2809 to perform certificate selection using certificate extension OIDs. 2810 This document defines matching rules for two standard certificate 2811 extensions defined in [RFC5280]: 2813 o The Key Usage extension in a certificate matches the request 2814 when all key usage bits asserted in the request are also 2815 asserted in the Key Usage certificate extension. 2817 o The Extended Key Usage extension in a certificate matches the 2818 request when all key purpose OIDs present in the request are 2819 also found in the Extended Key Usage certificate extension. 2820 The special anyExtendedKeyUsage OID MUST NOT be used in the 2821 request. 2823 Separate specifications may define matching rules for other 2824 certificate extensions. 2826 Note: It is a fatal "handshake_failure" alert for an anonymous server 2827 to request client authentication. 2829 6.3.3.3. Server Configuration 2831 When this message will be sent: 2833 This message is used to provide a server configuration which the 2834 client can use in the future to skip handshake negotiation and 2835 (optionally) to allow 0-RTT handshakes. The ServerConfiguration 2836 message is sent as the last message before the CertificateVerify. 2838 Structure of this Message: 2840 enum { (65535) } ConfigurationExtensionType; 2842 enum { client_authentication(1), early_data(2), 2843 client_authentication_and_data(3), (255) } EarlyDataType; 2845 struct { 2846 ConfigurationExtensionType extension_type; 2847 opaque extension_data<0..2^16-1>; 2848 } ConfigurationExtension; 2850 struct { 2851 opaque configuration_id<1..2^16-1>; 2852 uint32 expiration_date; 2853 KeyShareEntry static_key_share; 2854 EarlyDataType early_data_type; 2855 ConfigurationExtension extensions<0..2^16-1>; 2856 } ServerConfiguration; 2858 configuration_id 2859 The configuration identifier to be used in 0-RTT mode. 2861 expiration_date 2862 The last time when this configuration is expected to be valid (in 2863 seconds since the Unix epoch). Servers MUST NOT use any value 2864 more than 604800 seconds (7 days) in the future. Clients MUST NOT 2865 cache configurations for longer than 7 days, regardless of the 2866 expiration_date. [[OPEN ISSUE: Is this the right value? The idea 2867 is just to minimize exposure.]] 2869 static_key_share 2870 The long-term DH key that is being established for this 2871 configuration. 2873 early_data_type 2874 The type of 0-RTT handshake that this configuration is to be used 2875 for (see Section 6.3.2.5). If "client_authentication" or 2876 "client_authentication_and_data", then the client MUST select the 2877 certificate for future handshakes based on the CertificateRequest 2878 parameters supplied in this handshake. The server MUST NOT send 2879 either of these two options unless it also requested a certificate 2880 on this handshake. [[OPEN ISSUE: Should we relax this?]] 2882 extensions 2883 This field is a placeholder for future extensions to the 2884 ServerConfiguration format. 2886 The semantics of this message are to establish a shared state between 2887 the client and server for use with the "known_configuration" 2888 extension with the key specified in key and with the handshake 2889 parameters negotiated by this handshake. 2891 When the ServerConfiguration message is sent, the server MUST also 2892 send a Certificate message and a CertificateVerify message, even if 2893 the "known_configuration" extension was used for this handshake, thus 2894 requiring a signature over the configuration before it can be used by 2895 the client. Clients MUST NOT rely on the ServerConfiguration message 2896 until successfully receiving and processing the server's Certificate, 2897 CertificateVerify, and Finished. If there is a failure in processing 2898 those messages, the client MUST discard the ServerConfiguration. 2900 6.3.4. Authentication Messages 2902 As discussed in Section 6.2, TLS uses a common set of messages for 2903 authentication, key confirmation, and handshake integrity: 2904 Certificate, CertificateVerify, and Finished. These messages are 2905 always sent as the last messages in their handshake flight. The 2906 Certificate and CertificateVerify messages are only sent under 2907 certain circumstances, as defined below. The Finished message is 2908 always sent as part of the Authentication block. 2910 The computations for the Authentication messages all uniformly take 2911 the following inputs: 2913 - The certificate and signing key to be used. 2915 - A Handshake Context based on the handshake hash (see 2916 Section 7.3.1). 2918 - A base key to be used to compute a MAC key. 2920 Based on these inputs, the messages then contain: 2922 Certificate 2923 The certificate to be used for authentication and any supporting 2924 certificates in the chain. 2926 CertificateVerify 2927 A signature over the hash of Handshake Context + Certificate. 2929 Finished 2930 A MAC over the hash of Handshake Context + Certificate + 2931 CertificateVerify using a MAC key derived from the base key. 2933 Because the CertificateVerify signs the Handshake Context + 2934 Certificate and the Finished MACs the Handshake Context + Certificate 2935 + CertificateVerify, this is mostly equivalent to keeping a running 2936 hash of the handshake messages (exactly so in the pure 1-RTT cases). 2937 Note, however, that subsequent post-handshake authentications do not 2938 include each other, just the messages through the end of the main 2939 handshake. 2941 The following table defines the Handshake Context and MAC Key for 2942 each scenario: 2944 +----------------+-----------------------------------------+--------+ 2945 | Mode | Handshake Context | Base | 2946 | | | Key | 2947 +----------------+-----------------------------------------+--------+ 2948 | 0-RTT | ClientHello + ServerConfiguration + | xSS | 2949 | | Server Certificate + CertificateRequest | | 2950 | | (where ServerConfiguration, etc. are | | 2951 | | from the previous handshake) | | 2952 | | | | 2953 | 1-RTT (Server) | ClientHello ... ServerConfiguration | master | 2954 | | | secret | 2955 | | | | 2956 | 1-RTT (Client) | ClientHello ... ServerFinished | master | 2957 | | | secret | 2958 | | | | 2959 | Post-Handshake | ClientHello ... ClientFinished + | master | 2960 | | CertificateRequest | secret | 2961 +----------------+-----------------------------------------+--------+ 2963 Note 1: The ServerConfiguration, CertificateRequest, and Server 2964 Certificate in the 0-RTT case are the messages from the handshake 2965 where the ServerConfiguration was established. 2967 Note 2: The Handshake Context for the last three rows does not 2968 include any 0-RTT handshake messages, regardless of whether 0-RTT 2969 is used. 2971 6.3.4.1. Certificate 2973 When this message will be sent: 2975 The server MUST send a Certificate message whenever the agreed- 2976 upon key exchange method uses certificates for authentication 2977 (this includes all key exchange methods defined in this document 2978 except PSK). 2980 The client MUST send a Certificate message whenever the server has 2981 requested client authentication via a CertificateRequest message 2982 (Section 6.3.3.2) or when the EarlyDataType provided with the 2983 server configuration indicates a need for client authentication. 2985 This message is only sent if the server requests a certificate via 2986 one of these mechanisms. If no suitable certificate is available, 2987 the client MUST send a Certificate message containing no 2988 certificates (i.e., with the "certificate_list" field having 2989 length 0). 2991 Meaning of this message: 2993 This message conveys the endpoint's certificate chain to the peer. 2995 The certificate MUST be appropriate for the negotiated cipher 2996 suite's key exchange algorithm and any negotiated extensions. 2998 Structure of this message: 3000 opaque ASN1Cert<1..2^24-1>; 3002 struct { 3003 opaque certificate_request_context<0..255>; 3004 ASN1Cert certificate_list<0..2^24-1>; 3005 } Certificate; 3007 certificate_request_context: 3008 If this message is in response to a CertificateRequest, the value 3009 if certificate_request_context in that message. Otherwise, in the 3010 case of server authentication or client authentication in 0-RTT, 3011 this field SHALL be zero length. 3013 certificate_list 3014 This is a sequence (chain) of certificates. The sender's 3015 certificate MUST come first in the list. Each following 3016 certificate SHOULD directly certify one preceding it. Because 3017 certificate validation requires that trust anchors be distributed 3018 independently, a certificate that specifies a trust anchor MAY be 3019 omitted from the chain, provided that supported peers are known to 3020 possess any omitted certificates. 3022 Note: Prior to TLS 1.3, "certificate_list" ordering required each 3023 certificate to certify the one immediately preceding it, however some 3024 implementations allowed some flexibility. Servers sometimes send 3025 both a current and deprecated intermediate for transitional purposes, 3026 and others are simply configured incorrectly, but these cases can 3027 nonetheless be validated properly. For maximum compatibility, all 3028 implementations SHOULD be prepared to handle potentially extraneous 3029 certificates and arbitrary orderings from any TLS version, with the 3030 exception of the end-entity certificate which MUST be first. 3032 The server's certificate list MUST always be non-empty. A client 3033 will MAY send an empty certificate list if it does not have an 3034 appropriate certificate to send in response to the server's 3035 authentication request. 3037 6.3.4.1.1. Server Certificate Selection 3039 The following rules apply to the certificates sent by the server: 3041 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 3042 negotiated otherwise (e.g., [RFC5081]). 3044 - The server's end-entity certificate's public key (and associated 3045 restrictions) MUST be compatible with the selected key exchange 3046 algorithm. 3048 +----------------------+---------------------------+ 3049 | Key Exchange Alg. | Certificate Key Type | 3050 +----------------------+---------------------------+ 3051 | DHE_RSA or ECDHE_RSA | RSA public key | 3052 | | | 3053 | ECDHE_ECDSA | ECDSA or EdDSA public key | 3054 +----------------------+---------------------------+ 3056 - The certificate MUST allow the key to be used for signing (i.e., 3057 the digitalSignature bit MUST be set if the Key Usage extension is 3058 present) with a signature scheme and hash algorithm pair indicated 3059 in the client's "signature_algorithms" extension. 3061 - An ECDSA or EdDSA public key MUST use a curve and point format 3062 supported by the client, as described in [RFC4492]. 3064 - The "server_name" and "trusted_ca_keys" extensions [RFC6066] are 3065 used to guide certificate selection. As servers MAY require the 3066 presence of the "server_name" extension, clients SHOULD send this 3067 extension. 3069 All certificates provided by the server MUST be signed by a hash/ 3070 signature algorithm pair that appears in the "signature_algorithms" 3071 extension provided by the client, if they are able to provide such a 3072 chain (see Section 6.3.2.1). Certificates that are self-signed or 3073 certificates that are expected to be trust anchors are not validated 3074 as part of the chain and therefore MAY be signed with any algorithm. 3076 If the server cannot produce a certificate chain that is signed only 3077 via the indicated supported pairs, then it SHOULD continue the 3078 handshake by sending the client a certificate chain of its choice 3079 that may include algorithms that are not known to be supported by the 3080 client. This fallback chain MAY use the deprecated SHA-1 hash 3081 algorithm only if the "signature_algorithms" extension provided by 3082 the client permits it. If the client cannot construct an acceptable 3083 chain using the provided certificates and decides to abort the 3084 handshake, then it MUST send an "unsupported_certificate" alert 3085 message and close the connection. 3087 If the server has multiple certificates, it chooses one of them based 3088 on the above-mentioned criteria (in addition to other criteria, such 3089 as transport layer endpoint, local configuration and preferences). 3091 As cipher suites that specify new key exchange methods are specified 3092 for the TLS protocol, they will imply the certificate format and the 3093 required encoded keying information. 3095 6.3.4.1.2. Client Certificate Selection 3097 The following rules apply to certificates sent by the client: 3099 In particular: 3101 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 3102 negotiated otherwise (e.g., [RFC5081]). 3104 - If the certificate_authorities list in the certificate request 3105 message was non-empty, one of the certificates in the certificate 3106 chain SHOULD be issued by one of the listed CAs. 3108 - The certificates MUST be signed using an acceptable hash/ 3109 signature algorithm pair, as described in Section 6.3.3.2. Note 3110 that this relaxes the constraints on certificate-signing 3111 algorithms found in prior versions of TLS. 3113 - If the certificate_extensions list in the certificate request 3114 message was non-empty, the end-entity certificate MUST match the 3115 extension OIDs recognized by the client, as described in 3116 Section 6.3.3.2. 3118 Note that, as with the server certificate, there are certificates 3119 that use algorithm combinations that cannot be currently used with 3120 TLS. 3122 6.3.4.1.3. Receiving a Certificate Message 3124 In general, detailed certificate validation procedures are out of 3125 scope for TLS (see [RFC5280]). This section provides TLS-specific 3126 requirements. 3128 If server supplies an empty Certificate message, the client MUST 3129 terminate the handshake with a fatal "decode_error" alert. 3131 If the client does not send any certificates, the server MAY at its 3132 discretion either continue the handshake without client 3133 authentication, or respond with a fatal "handshake_failure" alert. 3134 Also, if some aspect of the certificate chain was unacceptable (e.g., 3135 it was not signed by a known, trusted CA), the server MAY at its 3136 discretion either continue the handshake (considering the client 3137 unauthenticated) or send a fatal alert. 3139 Any endpoint receiving any certificate signed using any signature 3140 algorithm using an MD5 hash MUST send a "bad_certificate" alert 3141 message and close the connection. 3143 SHA-1 is deprecated and therefore NOT RECOMMENDED. Endpoints that 3144 reject certification paths due to use of a deprecated hash MUST send 3145 a fatal "bad_certificate" alert message before closing the 3146 connection. All endpoints are RECOMMENDED to transition to SHA-256 3147 or better as soon as possible to maintain interoperability with 3148 implementations currently in the process of phasing out SHA-1 3149 support. 3151 Note that a certificate containing a key for one signature algorithm 3152 MAY be signed using a different signature algorithm (for instance, an 3153 RSA key signed with a ECDSA key). 3155 6.3.4.2. Certificate Verify 3157 When this message will be sent: 3159 This message is used to provide explicit proof that an endpoint 3160 possesses the private key corresponding to its certificate and 3161 also provides integrity for the handshake up to this point. 3162 Servers MUST send this message when using a cipher suite which is 3163 authenticated via a certificate. Clients MUST send this message 3164 whenever authenticating via a Certificate (i.e., when the 3165 Certificate message is non-empty). When sent, this message MUST 3166 appear immediately after the Certificate Message and immediately 3167 prior to the Finished message. 3169 Structure of this message: 3171 struct { 3172 digitally-signed struct { 3173 opaque hashed_data[hash_length]; 3174 }; 3175 } CertificateVerify; 3176 Where hashed_data is the hash output described in Section 6.3.4, 3177 namely Hash(Handshake Context + Certificate). 3179 The context string for a server signature is "TLS 1.3, server 3180 CertificateVerify" and for a client signature is "TLS 1.3, client 3181 CertificateVerify". A hash of the handshake messages is signed 3182 rather than the messages themselves because the digitally-signed 3183 format requires padding and context bytes at the beginning of the 3184 input. Thus, by signing a digest of the messages, an 3185 implementation need only maintain one running hash per hash type 3186 for CertificateVerify, Finished and other messages. 3188 If sent by a server, the signature algorithm and hash algorithm 3189 MUST be a pair offered in the client's "signature_algorithms" 3190 extension unless no valid certificate chain can be produced 3191 without unsupported algorithms (see Section 6.3.2.1). Note that 3192 there is a possibility for inconsistencies here. For instance, 3193 the client might offer ECDHE_ECDSA key exchange but omit any ECDSA 3194 and EdDSA pairs from its "signature_algorithms" extension. In 3195 order to negotiate correctly, the server MUST check any candidate 3196 cipher suites against the "signature_algorithms" extension before 3197 selecting them. This is somewhat inelegant but is a compromise 3198 designed to minimize changes to the original cipher suite design. 3200 If sent by a client, the hash and signature algorithms used in the 3201 signature MUST be one of those present in the 3202 supported_signature_algorithms field of the CertificateRequest 3203 message. 3205 In addition, the hash and signature algorithms MUST be compatible 3206 with the key in the sender's end-entity certificate. RSA keys MAY 3207 be used with any permitted hash algorithm, subject to restrictions 3208 in the certificate, if any. RSA signatures MUST be based on 3209 RSASSA-PSS, regardless of whether RSASSA-PKCS-v1_5 appears in 3210 "signature_algorithms". SHA-1 MUST NOT be used in any signatures 3211 in CertificateVerify, regardless of whether SHA-1 appears in 3212 "signature_algorithms". 3214 Note: when used with non-certificate-based handshakes (e.g., PSK), 3215 the client's signature does not cover the server's certificate 3216 directly, although it does cover the server's Finished message, which 3217 transitively includes the server's certificate when the PSK derives 3218 from a certificate-authenticated handshake. [PSK-FINISHED] describes 3219 a concrete attack on this mode if the Finished is omitted from the 3220 signature. It is unsafe to use certificate-based client 3221 authentication when the client might potentially share the same PSK/ 3222 key-id pair with two different endpoints. In order to ensure this, 3223 implementations MUST NOT mix certificate-based client authentication 3224 with pure PSK modes (i.e., those where the PSK was not derived from a 3225 previous non-PSK handshake). 3227 6.3.4.3. Finished 3229 When this message will be sent: 3231 The Finished message is the final message in the authentication 3232 block. It is essential for providing authentication of the 3233 handshake and of the computed keys. 3235 Meaning of this message: 3237 Recipients of Finished messages MUST verify that the contents are 3238 correct. Once a side has sent its Finished message and received 3239 and validated the Finished message from its peer, it may begin to 3240 send and receive application data over the connection. This data 3241 will be protected under keys derived from the ephemeral secret 3242 (see Section 7). 3244 The key used to compute the finished message is computed from the 3245 Base key defined in Section 6.3.4 using HKDF (see Section 7.1). 3246 Specifically: 3248 client_finished_key = 3249 HKDF-Expand-Label(BaseKey, "client finished", "", L) 3251 server_finished_key = 3252 HKDF-Expand-Label(BaseKey, "server finished", "", L) 3254 Structure of this message: 3256 struct { 3257 opaque verify_data[verify_data_length]; 3258 } Finished; 3260 The verify_data value is computed as follows: 3262 verify_data = 3263 HMAC(finished_key, Hash( 3264 Handshake Context + Certificate* + CertificateVerify* 3265 )) 3267 * Only included if present. 3269 Where HMAC [RFC2104] uses the Hash algorithm for the handshake. As 3270 noted above: the HMAC input can generally be implemented by a running 3271 hash, i.e., just the handshake hash at this point. 3273 In previous versions of TLS, the verify_data was always 12 octets 3274 long. In the current version of TLS, it is the size of the HMAC 3275 output for the Hash used for the handshake. 3277 Note: Alerts and any other record types are not handshake messages 3278 and are not included in the hash computations. 3280 6.3.5. Post-Handshake Messages 3282 TLS also allows other messages to be sent after the main handshake. 3283 These message use a handshake content type and are encrypted under 3284 the application traffic key. 3286 6.3.5.1. New Session Ticket Message 3288 After the server has received the client Finished message, it MAY 3289 send a NewSessionTicket message. This message creates a pre-shared 3290 key (PSK) binding between the resumption master secret and the ticket 3291 label. The client MAY use this PSK for future handshakes by 3292 including it in the "pre_shared_key" extension in its ClientHello 3293 (Section 6.3.2.4) and supplying a suitable PSK cipher suite. 3295 struct { 3296 uint32 ticket_lifetime_hint; 3297 opaque ticket<0..2^16-1>; 3298 } NewSessionTicket; 3300 ticket_lifetime_hint 3301 Indicates the lifetime in seconds as a 32-bit unsigned integer in 3302 network byte order from the time of ticket issuance. A value of 3303 zero is reserved to indicate that the lifetime of the ticket is 3304 unspecified. 3306 ticket 3307 The value of the ticket to be used as the PSK identifier. 3309 The ticket lifetime hint is informative only. A client SHOULD delete 3310 the ticket and associated state when the time expires. It MAY delete 3311 the ticket earlier based on local policy. A server MAY treat a 3312 ticket as valid for a shorter or longer period of time than what is 3313 stated in the ticket_lifetime_hint. 3315 The ticket itself is an opaque label. It MAY either be a database 3316 lookup key or a self-encrypted and self-authenticated value. 3317 Section 4 of [RFC5077] describes a recommended ticket construction 3318 mechanism. 3320 [[TODO: Should we require that tickets be bound to the existing 3321 symmetric cipher suite. See the TODO above about early_data and 3322 PSK.??] 3324 6.3.5.2. Post-Handshake Authentication 3326 The server is permitted to request client authentication at any time 3327 after the handshake has completed by sending a CertificateRequest 3328 message. The client SHOULD respond with the appropriate 3329 Authentication messages. If the client chooses to authenticate, it 3330 MUST send Certificate, CertificateVerify, and Finished. If it 3331 declines, it MUST send a Certificate message containing no 3332 certificates followed by Finished. 3334 Note: Because client authentication may require prompting the user, 3335 servers MUST be prepared for some delay, including receiving an 3336 arbitrary number of other messages between sending the 3337 CertificateRequest and receiving a response. In addition, clients 3338 which receive multiple CertificateRequests in close succession MAY 3339 respond to them in a different order than they were received (the 3340 certificate_request_context value allows the server to disambiguate 3341 the responses). 3343 6.3.5.3. Key and IV Update 3345 struct {} KeyUpdate; 3347 The KeyUpdate handshake message is used to indicate that the sender 3348 is updating its sending cryptographic keys. This message can be sent 3349 by the server after sending its first flight and the client after 3350 sending its second flight. Implementations that receive a KeyUpdate 3351 message prior to receiving a Finished message as part of the 1-RTT 3352 handshake MUST generate a fatal "unexpected_message" alert. After 3353 sending a KeyUpdate message, the sender SHALL send all its traffic 3354 using the next generation of keys, computed as described in 3355 Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update 3356 their receiving keys and if they have not already updated their 3357 sending state up to or past the then current receiving generation 3358 MUST send their own KeyUpdate prior to sending any other messages. 3359 This mechanism allows either side to force an update to the entire 3360 connection. Note that implementations may receive an arbitrary 3361 number of messages between sending a KeyUpdate and receiving the 3362 peer's KeyUpdate because those messages may already be in flight. 3364 Note that if implementations independently send their own KeyUpdates 3365 and they cross in flight, this only results in an update of one 3366 generation; when each side receives the other side's update it just 3367 updates its receive keys and notes that the generations match and 3368 thus no send update is needed. 3370 Note that the side which sends its KeyUpdate first needs to retain 3371 the traffic keys (though not the traffic secret) for the previous 3372 generation of keys until it receives the KeyUpdate from the other 3373 side. 3375 7. Cryptographic Computations 3377 In order to begin connection protection, the TLS Record Protocol 3378 requires specification of a suite of algorithms, a master secret, and 3379 the client and server random values. The authentication, key 3380 exchange, and record protection algorithms are determined by the 3381 cipher_suite selected by the server and revealed in the ServerHello 3382 message. The random values are exchanged in the hello messages. All 3383 that remains is to calculate the key schedule. 3385 7.1. Key Schedule 3387 The TLS handshake establishes secret keying material which is then 3388 used to protect traffic. This keying material is derived from the 3389 two input secret values: Static Secret (SS) and Ephemeral Secret 3390 (ES). 3392 The exact source of each of these secrets depends on the operational 3393 mode (DHE, ECDHE, PSK, etc.) and is summarized in the table below: 3395 +-----------------+------------------------+------------------------+ 3396 | Key Exchange | Static Secret (SS) | Ephemeral Secret (ES) | 3397 +-----------------+------------------------+------------------------+ 3398 | (EC)DHE (full | Client ephemeral w/ | Client ephemeral w/ | 3399 | handshake) | server ephemeral | server ephemeral | 3400 | | | | 3401 | (EC)DHE (w/ | Client ephemeral w/ | Client ephemeral w/ | 3402 | 0-RTT) | server static | server ephemeral | 3403 | | | | 3404 | PSK | Pre-Shared Key | Pre-shared key | 3405 | | | | 3406 | PSK + (EC)DHE | Pre-Shared Key | Client ephemeral w/ | 3407 | | | server ephemeral | 3408 +-----------------+------------------------+------------------------+ 3410 These shared secret values are used to generate cryptographic keys as 3411 shown below. 3413 The derivation process is as follows, where L denotes the length of 3414 the underlying hash function for HKDF [RFC5869]. SS and ES denote 3415 the sources from the table above. 3417 HKDF-Expand-Label(Secret, Label, HashValue, Length) = 3418 HKDF-Expand(Secret, HkdfLabel, Length) 3420 Where HkdfLabel is specified as: 3422 struct HkdfLabel { 3423 uint16 length; 3424 opaque label<9..255>; 3425 opaque hash_value<0..255>; 3426 }; 3428 Where: 3429 - HkdfLabel.length is Length 3430 - HkdfLabel.label is "TLS 1.3, " + Label 3431 - HkdfLabel.hash_value is HashValue. 3433 1. xSS = HKDF-Extract(0, SS). Note that HKDF-Extract always 3434 produces a value the same length as the underlying hash 3435 function. 3437 2. xES = HKDF-Extract(0, ES) 3439 3. mSS = HKDF-Expand-Label(xSS, "expanded static secret", 3440 handshake_hash, L) 3442 4. mES = HKDF-Expand-Label(xES, "expanded ephemeral secret", 3443 handshake_hash, L) 3445 5. master_secret = HKDF-Extract(mSS, mES) 3447 6. traffic_secret_0 = HKDF-Expand-Label(master_secret, 3448 "traffic secret", 3449 handshake_hash, L) 3451 Where handshake_hash includes all messages up through the 3452 server CertificateVerify message, but not including any 3453 0-RTT handshake messages (the server's Finished is not 3454 included because the master_secret is need to compute 3455 the finished key). [[OPEN ISSUE: Should we be including 3456 0-RTT handshake messages here and below?. 3457 https://github.com/tlswg/tls13-spec/issues/351 3458 ]] At this point, 3459 SS, ES, xSS, xES, mSS, and mSS SHOULD be securely deleted, 3460 along with any ephemeral (EC)DH secrets. 3462 7. resumption_secret = HKDF-Expand-Label(master_secret, 3463 "resumption master secret" 3464 handshake_hash, L) 3466 8. exporter_secret = HKDF-Expand-Label(master_secret, 3467 "exporter master secret", 3468 handshake_hash, L) 3470 Where handshake_hash contains the entire handshake up to 3471 and including the client's Finished, but not including 3472 any 0-RTT handshake messages or post-handshake messages. 3473 AT this point master_secret SHOULD be securely deleted. 3475 The traffic keys are computed from xSS, xES, and the traffic_secret 3476 as described in Section 7.3 below. The traffic_secret may be updated 3477 throughout the connection as described in Section 7.2. 3479 Note: although the steps above are phrased as individual HKDF-Extract 3480 and HKDF-Expand operations, because each HKDF-Expand operation is 3481 paired with an HKDF-Extract, it is possible to implement this key 3482 schedule with a black-box HKDF API, albeit at some loss of efficiency 3483 as some HKDF-Extract operations will be repeated. 3485 7.2. Updating Traffic Keys and IVs 3487 Once the handshake is complete, it is possible for either side to 3488 update its sending traffic keys using the KeyUpdate handshake message 3489 Section 6.3.5.3. The next generation of traffic keys is computed by 3490 generating traffic_secret_N+1 from traffic_secret_N as described in 3491 this section then re-deriving the traffic keys as described in 3492 Section 7.3. 3494 The next-generation traffic_secret is computed as: 3496 traffic_secret_N+1 = HKDF-Expand-Label(traffic_secret_N, "traffic 3497 secret", "", L) 3499 Once traffic_secret_N+1 and its associated traffic keys have been 3500 computed, implementations SHOULD delete traffic_secret_N. Once the 3501 directional keys are no longer needed, they SHOULD be deleted as 3502 well. 3504 7.3. Traffic Key Calculation 3506 The traffic keying material is generated from the following input 3507 values: 3509 - A secret value 3511 - A phase value indicating the phase of the protocol the keys are 3512 being generated for. 3514 - A purpose value indicating the specific value being generated 3516 - The length of the key. 3518 - The handshake context which is used to generate the keys. 3520 The keying material is computed using: 3522 key = HKDF-Expand-Label(Secret, 3523 phase + ", " + purpose, 3524 handshake_context, 3525 key_length) 3527 The following table describes the inputs to the key calculation for 3528 each class of traffic keys: 3530 +-------------+---------+-----------------+-------------------------+ 3531 | Record Type | Secret | Label | Handshake Context | 3532 +-------------+---------+-----------------+-------------------------+ 3533 | 0-RTT | xSS | "early | ClientHello + | 3534 | Handshake | | handshake key | ServerConfiguration + | 3535 | | | expansion" | Server Certificate | 3536 | | | | | 3537 | 0-RTT | xSS | "early | ClientHello + | 3538 | Application | | application | ServerConfiguration + | 3539 | | | data key | Server Certificate | 3540 | | | expansion" | | 3541 | | | | | 3542 | Handshake | xES | "handshake key | ClientHello... | 3543 | | | expansion" | ServerHello | 3544 | | | | | 3545 | Application | traffic | "application | ClientHello... Server | 3546 | Data | secret | data key | Finished | 3547 | | | expansion" | | 3548 +-------------+---------+-----------------+-------------------------+ 3550 The following table indicates the purpose values for each type of 3551 key: 3553 +------------------+--------------------+ 3554 | Key Type | Purpose | 3555 +------------------+--------------------+ 3556 | Client Write Key | "client write key" | 3557 | | | 3558 | Server Write Key | "server write key" | 3559 | | | 3560 | Client Write IV | "client write IV" | 3561 | | | 3562 | Server Write IV | "server write IV" | 3563 +------------------+--------------------+ 3565 All the traffic keying material is recomputed whenever the underlying 3566 Secret changes (e.g., when changing from the handshake to application 3567 data keys or upon a key update). 3569 7.3.1. The Handshake Hash 3571 The handshake hash is defined as the hash of all handshake messages 3572 sent or received, starting at ClientHello up to the present time, 3573 with the exception of the client's 0-RTT authentication messages 3574 (Certificate, CertificateVerify, and Finished) including the type and 3575 length fields of the handshake messages. This is the concatenation 3576 the exchanged Handshake structures in plaintext form (even if they 3577 were encrypted on the wire). [[OPEN ISSUE: See 3578 https://github.com/tlswg/tls13-spec/issues/351 for the question of 3579 whether the 0-RTT handshake messages are hashed.]] 3581 7.3.2. Diffie-Hellman 3583 A conventional Diffie-Hellman computation is performed. The 3584 negotiated key (Z) is used as the shared secret, and is used in the 3585 key schedule as specified above. Leading bytes of Z that contain all 3586 zero bits are stripped before it is used as the input to HKDF. 3588 7.3.3. Elliptic Curve Diffie-Hellman 3590 For secp256r1, secp384r1 and secp521r1, ECDH calculations (including 3591 parameter and key generation as well as the shared secret 3592 calculation) are performed according to [IEEE1363] using the ECKAS- 3593 DH1 scheme with the identity map as key derivation function (KDF), so 3594 that the shared secret is the x-coordinate of the ECDH shared secret 3595 elliptic curve point represented as an octet string. Note that this 3596 octet string (Z in IEEE 1363 terminology) as output by FE2OSP, the 3597 Field Element to Octet String Conversion Primitive, has constant 3598 length for any given field; leading zeros found in this octet string 3599 MUST NOT be truncated. 3601 (Note that this use of the identity KDF is a technicality. The 3602 complete picture is that ECDH is employed with a non-trivial KDF 3603 because TLS does not directly use this secret for anything other than 3604 for computing other secrets.) 3606 ECDH functions are used as follows: 3608 - The public key to put into ECPoint.point structure is the result 3609 of applying the ECDH function to the secret key of appropriate 3610 length (into scalar input) and the standard public basepoint (into 3611 u-coordinate point input). 3613 - The ECDH shared secret is the result of applying ECDH function to 3614 the secret key (into scalar input) and the peer's public key (into 3615 u-coordinate point input). The output is used raw, with no 3616 processing. 3618 For X25519 and X448, see [I-D.irtf-cfrg-curves]. 3620 8. Mandatory Algorithms 3622 8.1. MTI Cipher Suites 3624 In the absence of an application profile standard specifying 3625 otherwise, a TLS-compliant application MUST implement the following 3626 cipher suites: 3628 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 3629 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 3631 These cipher suites MUST support both digital signatures and key 3632 exchange with secp256r1 (NIST P-256) and SHOULD support key exchange 3633 with X25519 [I-D.irtf-cfrg-curves]. 3635 A TLS-compliant application SHOULD implement the following cipher 3636 suites: 3638 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 3639 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 3640 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 3641 TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 3643 8.2. MTI Extensions 3645 In the absence of an application profile standard specifying 3646 otherwise, a TLS-compliant application MUST implement the following 3647 TLS extensions: 3649 - Signature Algorithms ("signature_algorithms"; Section 6.3.2.1) 3651 - Negotiated Groups ("supported_groups"; Section 6.3.2.2) 3653 - Key Share ("key_share"; Section 6.3.2.3) 3655 - Pre-Shared Key ("pre_shared_key"; Section 6.3.2.4) 3657 - Server Name Indication ("server_name"; Section 3 of [RFC6066]) 3659 All implementations MUST send and use these extensions when offering 3660 applicable cipher suites: 3662 - "signature_algorithms" is REQUIRED for certificate authenticated 3663 cipher suites 3665 - "supported_groups" and "key_share" are REQUIRED for DHE or ECDHE 3666 cipher suites 3668 - "pre_shared_key" is REQUIRED for PSK cipher suites 3670 When negotiating use of applicable cipher suites, endpoints MUST 3671 abort the connection with a "missing_extension" alert if the required 3672 extension was not provided. Any endpoint that receives any invalid 3673 combination of cipher suites and extensions MAY abort the connection 3674 with a "missing_extension" alert, regardless of negotiated 3675 parameters. 3677 Additionally, all implementations MUST support use of the 3678 "server_name" extension with applications capable of using it. 3679 Servers MAY require clients to send a valid "server_name" extension. 3680 Servers requiring this extension SHOULD respond to a ClientHello 3681 lacking a "server_name" extension with a fatal "missing_extension" 3682 alert. 3684 Some of these extensions exist only for the client to provide 3685 additional data to the server in a backwards-compatible way and thus 3686 have no meaning when sent from a server. The client-only extensions 3687 defined in this document are: "signature_algorithms" & 3688 "supported_groups". Servers MUST NOT send these extensions. Clients 3689 receiving any of these extensions MUST respond with a fatal 3690 "unsupported_extension" alert and close the connection. 3692 9. Application Data Protocol 3694 Application data messages are carried by the record layer and are 3695 fragmented and encrypted based on the current connection state. The 3696 messages are treated as transparent data to the record layer. 3698 10. Security Considerations 3700 Security issues are discussed throughout this memo, especially in 3701 Appendices B, C, and D. 3703 11. IANA Considerations 3705 [[TODO: Rename "RSA" in TLS SignatureAlgorithm Registry to RSASSA- 3706 PKCS1-v1_5 ]] 3708 This document uses several registries that were originally created in 3709 [RFC4346]. IANA has updated these to reference this document. The 3710 registries and their allocation policies are below: 3712 - TLS Cipher Suite Registry: Values with the first byte in the range 3713 0-254 (decimal) are assigned via Specification Required [RFC2434]. 3714 Values with the first byte 255 (decimal) are reserved for Private 3715 Use [RFC2434]. IANA [SHALL add/has added] a "Recommended" column 3716 to the cipher suite registry. All cipher suites listed in 3717 Appendix A.4 are marked as "Yes". All other cipher suites are 3718 marked as "No". IANA [SHALL add/has added] add a note to this 3719 column reading: 3721 Cipher suites marked as "Yes" are those allocated via Standards 3722 Track RFCs. Cipher suites marked as "No" are not; cipher 3723 suites marked "No" range from "good" to "bad" from a 3724 cryptographic standpoint. 3726 - TLS ContentType Registry: Future values are allocated via 3727 Standards Action [RFC2434]. 3729 - TLS Alert Registry: Future values are allocated via Standards 3730 Action [RFC2434]. 3732 - TLS HandshakeType Registry: Future values are allocated via 3733 Standards Action [RFC2434]. 3735 This document also uses a registry originally created in [RFC4366]. 3736 IANA has updated it to reference this document. The registry and its 3737 allocation policy is listed below: 3739 - TLS ExtensionType Registry: Values with the first byte in the 3740 range 0-254 (decimal) are assigned via Specification Required 3741 [RFC2434]. Values with the first byte 255 (decimal) are reserved 3742 for Private Use [RFC2434]. IANA [SHALL update/has updated] this 3743 registry to include the "key_share", "pre_shared_key", and 3744 "early_data" extensions as defined in this document. 3746 IANA [shall update/has updated] this registry to include a "TLS 3747 1.3" column with the following four values: "Client", indicating 3748 that the server shall not send them. "Clear", indicating that 3749 they shall be in the ServerHello. "Encrypted", indicating that 3750 they shall be in the EncryptedExtensions block, and "No" 3751 indicating that they are not used in TLS 1.3. This column [shall 3752 be/has been] initially populated with the values in this document. 3753 IANA [shall update/has updated] this registry to add a 3754 "Recommended" column. IANA [shall/has] initially populated this 3755 column with the values in the table below. This table has been 3756 generated by marking Standards Track RFCs as "Yes" and all others 3757 as "No". 3759 +-------------------------------------------+------------+----------+ 3760 | Extension | Recommende | TLS 1.3 | 3761 | | d | | 3762 +-------------------------------------------+------------+----------+ 3763 | server_name [RFC6066] | Yes | Encrypte | 3764 | | | d | 3765 | | | | 3766 | max_fragment_length [RFC6066] | Yes | Encrypte | 3767 | | | d | 3768 | | | | 3769 | client_certificate_url [RFC6066] | Yes | Encrypte | 3770 | | | d | 3771 | | | | 3772 | trusted_ca_keys [RFC6066] | Yes | Encrypte | 3773 | | | d | 3774 | | | | 3775 | truncated_hmac [RFC6066] | Yes | No | 3776 | | | | 3777 | status_request [RFC6066] | Yes | No | 3778 | | | | 3779 | user_mapping [RFC4681] | Yes | Encrypte | 3780 | | | d | 3781 | | | | 3782 | client_authz [RFC5878] | No | Encrypte | 3783 | | | d | 3784 | | | | 3785 | server_authz [RFC5878] | No | Encrypte | 3786 | | | d | 3787 | | | | 3788 | cert_type [RFC6091] | Yes | Encrypte | 3789 | | | d | 3790 | | | | 3791 | supported_groups [RFC-ietf-tls- | Yes | Client | 3792 | negotiated-ff-dhe] | | | 3793 | | | | 3794 | ec_point_formats [RFC4492] | Yes | No | 3795 | | | | 3796 | srp [RFC5054] | No | No | 3797 | | | | 3798 | signature_algorithms [RFC5246] | Yes | Client | 3799 | | | | 3800 | use_srtp [RFC5764] | Yes | Encrypte | 3801 | | | d | 3802 | | | | 3803 | heartbeat [RFC6520] | Yes | Encrypte | 3804 | | | d | 3805 | | | | 3806 | application_layer_protocol_negotiation[RF | Yes | Encrypte | 3807 | C7301] | | d | 3808 | | | | 3809 | status_request_v2 [RFC6961] | Yes | Encrypte | 3810 | | | d | 3811 | | | | 3812 | signed_certificate_timestamp [RFC6962] | No | Encrypte | 3813 | | | d | 3814 | | | | 3815 | client_certificate_type [RFC7250] | Yes | Encrypte | 3816 | | | d | 3817 | | | | 3818 | server_certificate_type [RFC7250] | Yes | Encrypte | 3819 | | | d | 3820 | | | | 3821 | padding [RFC7685] | Yes | Client | 3822 | | | | 3823 | encrypt_then_mac [RFC7366] | Yes | No | 3824 | | | | 3825 | extended_master_secret [RFC7627] | Yes | No | 3826 | | | | 3827 | SessionTicket TLS [RFC4507] | Yes | No | 3828 | | | | 3829 | renegotiation_info [RFC5746] | Yes | No | 3830 | | | | 3831 | key_share [[this document]] | Yes | Clear | 3832 | | | | 3833 | pre_shared_key [[this document]] | Yes | Clear | 3834 | | | | 3835 | early_data [[this document]] | Yes | Clear | 3836 +-------------------------------------------+------------+----------+ 3838 This document reuses two registries defined in [RFC5246]. 3840 - TLS SignatureAlgorithm Registry: The registry has been initially 3841 populated with the values described in Section 6.3.2.1. Future 3842 values in the range 0-63 (decimal) inclusive are assigned via 3843 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 3844 inclusive are assigned via Specification Required [RFC2434]. 3845 Values from 224-255 (decimal) inclusive are reserved for Private 3846 Use [RFC2434]. 3848 - TLS HashAlgorithm Registry: The registry has been initially 3849 populated with the values described in Section 6.3.2.1. Future 3850 values in the range 0-63 (decimal) inclusive are assigned via 3851 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 3852 inclusive are assigned via Specification Required [RFC2434]. 3853 Values from 224-255 (decimal) inclusive are reserved for Private 3854 Use [RFC2434]. 3856 In addition, this document defines a new registry to be maintained by 3857 IANA. 3859 - TLS ConfigurationExtensionType Registry: Values with the first 3860 byte in the range 0-254 (decimal) are assigned via Specification 3861 Required [RFC2434]. Values with the first byte 255 (decimal) are 3862 reserved for Private Use [RFC2434]. This registry SHALL have a 3863 "Recommended" column. The registry [shall be/ has been] initially 3864 populated with the values described in Section 6.3.3.3, with all 3865 values marked with "Recommended" value "Yes". 3867 12. References 3869 12.1. Normative References 3871 [AES] National Institute of Standards and Technology, 3872 "Specification for the Advanced Encryption Standard 3873 (AES)", NIST FIPS 197, November 2001. 3875 [DH] Diffie, W. and M. Hellman, "New Directions in 3876 Cryptography", IEEE Transactions on Information Theory, 3877 V.IT-22 n.6 , June 1977. 3879 [I-D.ietf-tls-chacha20-poly1305] 3880 Langley, A., Chang, W., Mavrogiannopoulos, N., 3881 Strombergson, J., and S. Josefsson, "ChaCha20-Poly1305 3882 Cipher Suites for Transport Layer Security (TLS)", draft- 3883 ietf-tls-chacha20-poly1305-04 (work in progress), December 3884 2015. 3886 [I-D.irtf-cfrg-curves] 3887 Langley, A. and M. Hamburg, "Elliptic Curves for 3888 Security", draft-irtf-cfrg-curves-11 (work in progress), 3889 October 2015. 3891 [I-D.irtf-cfrg-eddsa] 3892 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 3893 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-01 3894 (work in progress), December 2015. 3896 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3897 Hashing for Message Authentication", RFC 2104, 3898 DOI 10.17487/RFC2104, February 1997, 3899 . 3901 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3902 Requirement Levels", BCP 14, RFC 2119, 3903 DOI 10.17487/RFC2119, March 1997, 3904 . 3906 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3907 IANA Considerations Section in RFCs", RFC 2434, 3908 DOI 10.17487/RFC2434, October 1998, 3909 . 3911 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3912 Standards (PKCS) #1: RSA Cryptography Specifications 3913 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 3914 2003, . 3916 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3917 Housley, R., and W. Polk, "Internet X.509 Public Key 3918 Infrastructure Certificate and Certificate Revocation List 3919 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3920 . 3922 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 3923 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 3924 DOI 10.17487/RFC5288, August 2008, 3925 . 3927 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3928 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3929 DOI 10.17487/RFC5289, August 2008, 3930 . 3932 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3933 Key Derivation Function (HKDF)", RFC 5869, 3934 DOI 10.17487/RFC5869, May 2010, 3935 . 3937 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 3938 Extensions: Extension Definitions", RFC 6066, 3939 DOI 10.17487/RFC6066, January 2011, 3940 . 3942 [RFC6209] Kim, W., Lee, J., Park, J., and D. Kwon, "Addition of the 3943 ARIA Cipher Suites to Transport Layer Security (TLS)", 3944 RFC 6209, DOI 10.17487/RFC6209, April 2011, 3945 . 3947 [RFC6367] Kanno, S. and M. Kanda, "Addition of the Camellia Cipher 3948 Suites to Transport Layer Security (TLS)", RFC 6367, 3949 DOI 10.17487/RFC6367, September 2011, 3950 . 3952 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 3953 Transport Layer Security (TLS)", RFC 6655, 3954 DOI 10.17487/RFC6655, July 2012, 3955 . 3957 [RFC7251] McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 3958 CCM Elliptic Curve Cryptography (ECC) Cipher Suites for 3959 TLS", RFC 7251, DOI 10.17487/RFC7251, June 2014, 3960 . 3962 [SHS] National Institute of Standards and Technology, U.S. 3963 Department of Commerce, "Secure Hash Standard", NIST FIPS 3964 PUB 180-4, March 2012. 3966 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 3967 Specification of Basic Encoding Rules (BER), Canonical 3968 Encoding Rules (CER) and Distinguished Encoding Rules 3969 (DER)", ISO/IEC 8825-1:2002, 2002. 3971 [X962] ANSI, "Public Key Cryptography For The Financial Services 3972 Industry: The Elliptic Curve Digital Signature Algorithm 3973 (ECDSA)", ANSI X9.62, 1998. 3975 12.2. Informative References 3977 [DSS] National Institute of Standards and Technology, U.S. 3978 Department of Commerce, "Digital Signature Standard, 3979 version 4", NIST FIPS PUB 186-4, 2013. 3981 [ECDSA] American National Standards Institute, "Public Key 3982 Cryptography for the Financial Services Industry: The 3983 Elliptic Curve Digital Signature Algorithm (ECDSA)", 3984 ANSI ANS X9.62-2005, November 2005. 3986 [FI06] "Bleichenbacher's RSA signature forgery based on 3987 implementation error", August 2006, . 3990 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 3991 Operation: Galois/Counter Mode (GCM) and GMAC", 3992 NIST Special Publication 800-38D, November 2007. 3994 [I-D.ietf-tls-negotiated-ff-dhe] 3995 Gillmor, D., "Negotiated Finite Field Diffie-Hellman 3996 Ephemeral Parameters for TLS", draft-ietf-tls-negotiated- 3997 ff-dhe-10 (work in progress), June 2015. 3999 [IEEE1363] 4000 IEEE, "Standard Specifications for Public Key 4001 Cryptography", IEEE 1363 , 2000. 4003 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate 4004 Syntax Standard, version 1.5", November 1993. 4006 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message 4007 Syntax Standard, version 1.5", November 1993. 4009 [PSK-FINISHED] 4010 Cremers, C., Horvat, M., van der Merwe, T., and S. Scott, 4011 "Revision 10: possible attack if client authentication is 4012 allowed during PSK", 2015, . 4015 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4016 RFC 793, DOI 10.17487/RFC0793, September 1981, 4017 . 4019 [RFC1948] Bellovin, S., "Defending Against Sequence Number Attacks", 4020 RFC 1948, DOI 10.17487/RFC1948, May 1996, 4021 . 4023 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 4024 "Randomness Requirements for Security", BCP 106, RFC 4086, 4025 DOI 10.17487/RFC4086, June 2005, 4026 . 4028 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4029 Ciphersuites for Transport Layer Security (TLS)", 4030 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4031 . 4033 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 4034 DOI 10.17487/RFC4302, December 2005, 4035 . 4037 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 4038 RFC 4303, DOI 10.17487/RFC4303, December 2005, 4039 . 4041 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 4042 (TLS) Protocol Version 1.1", RFC 4346, 4043 DOI 10.17487/RFC4346, April 2006, 4044 . 4046 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 4047 and T. Wright, "Transport Layer Security (TLS) 4048 Extensions", RFC 4366, DOI 10.17487/RFC4366, April 2006, 4049 . 4051 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4052 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4053 for Transport Layer Security (TLS)", RFC 4492, 4054 DOI 10.17487/RFC4492, May 2006, 4055 . 4057 [RFC4506] Eisler, M., Ed., "XDR: External Data Representation 4058 Standard", STD 67, RFC 4506, DOI 10.17487/RFC4506, May 4059 2006, . 4061 [RFC4507] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 4062 "Transport Layer Security (TLS) Session Resumption without 4063 Server-Side State", RFC 4507, DOI 10.17487/RFC4507, May 4064 2006, . 4066 [RFC4681] Santesson, S., Medvinsky, A., and J. Ball, "TLS User 4067 Mapping Extension", RFC 4681, DOI 10.17487/RFC4681, 4068 October 2006, . 4070 [RFC5054] Taylor, D., Wu, T., Mavrogiannopoulos, N., and T. Perrin, 4071 "Using the Secure Remote Password (SRP) Protocol for TLS 4072 Authentication", RFC 5054, DOI 10.17487/RFC5054, November 4073 2007, . 4075 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 4076 "Transport Layer Security (TLS) Session Resumption without 4077 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 4078 January 2008, . 4080 [RFC5081] Mavrogiannopoulos, N., "Using OpenPGP Keys for Transport 4081 Layer Security (TLS) Authentication", RFC 5081, 4082 DOI 10.17487/RFC5081, November 2007, 4083 . 4085 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 4086 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 4087 . 4089 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4090 (TLS) Protocol Version 1.2", RFC 5246, 4091 DOI 10.17487/RFC5246, August 2008, 4092 . 4094 [RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov, 4095 "Transport Layer Security (TLS) Renegotiation Indication 4096 Extension", RFC 5746, DOI 10.17487/RFC5746, February 2010, 4097 . 4099 [RFC5763] Fischl, J., Tschofenig, H., and E. Rescorla, "Framework 4100 for Establishing a Secure Real-time Transport Protocol 4101 (SRTP) Security Context Using Datagram Transport Layer 4102 Security (DTLS)", RFC 5763, DOI 10.17487/RFC5763, May 4103 2010, . 4105 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 4106 Security (DTLS) Extension to Establish Keys for the Secure 4107 Real-time Transport Protocol (SRTP)", RFC 5764, 4108 DOI 10.17487/RFC5764, May 2010, 4109 . 4111 [RFC5878] Brown, M. and R. Housley, "Transport Layer Security (TLS) 4112 Authorization Extensions", RFC 5878, DOI 10.17487/RFC5878, 4113 May 2010, . 4115 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 4116 for TLS", RFC 5929, DOI 10.17487/RFC5929, July 2010, 4117 . 4119 [RFC6091] Mavrogiannopoulos, N. and D. Gillmor, "Using OpenPGP Keys 4120 for Transport Layer Security (TLS) Authentication", 4121 RFC 6091, DOI 10.17487/RFC6091, February 2011, 4122 . 4124 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 4125 (SSL) Version 2.0", RFC 6176, DOI 10.17487/RFC6176, March 4126 2011, . 4128 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 4129 Layer Security (TLS) and Datagram Transport Layer Security 4130 (DTLS) Heartbeat Extension", RFC 6520, 4131 DOI 10.17487/RFC6520, February 2012, 4132 . 4134 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 4135 Multiple Certificate Status Request Extension", RFC 6961, 4136 DOI 10.17487/RFC6961, June 2013, 4137 . 4139 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 4140 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 4141 . 4143 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4144 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4145 Transport Layer Security (TLS) and Datagram Transport 4146 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4147 June 2014, . 4149 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 4150 "Transport Layer Security (TLS) Application-Layer Protocol 4151 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 4152 July 2014, . 4154 [RFC7366] Gutmann, P., "Encrypt-then-MAC for Transport Layer 4155 Security (TLS) and Datagram Transport Layer Security 4156 (DTLS)", RFC 7366, DOI 10.17487/RFC7366, September 2014, 4157 . 4159 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 4160 DOI 10.17487/RFC7465, February 2015, 4161 . 4163 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 4164 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 4165 DOI 10.17487/RFC7568, June 2015, 4166 . 4168 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 4169 Langley, A., and M. Ray, "Transport Layer Security (TLS) 4170 Session Hash and Extended Master Secret Extension", 4171 RFC 7627, DOI 10.17487/RFC7627, September 2015, 4172 . 4174 [RFC7685] Langley, A., "A Transport Layer Security (TLS) ClientHello 4175 Padding Extension", RFC 7685, DOI 10.17487/RFC7685, 4176 October 2015, . 4178 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 4179 Obtaining Digital Signatures and Public-Key 4180 Cryptosystems", Communications of the ACM v. 21, n. 2, pp. 4181 120-126., February 1978. 4183 [SSL2] Netscape Communications Corp., "The SSL Protocol", 4184 February 1995. 4186 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 4187 Protocol", November 1996. 4189 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 4190 practical", USENIX Security Symposium, 2003. 4192 [X501] "Information Technology - Open Systems Interconnection - 4193 The Directory: Models", ITU-T X.501, 1993. 4195 12.3. URIs 4197 [1] mailto:tls@ietf.org 4199 Appendix A. Protocol Data Structures and Constant Values 4201 This section describes protocol types and constants. Values listed 4202 as _RESERVED were used in previous versions of TLS and are listed 4203 here for completeness. TLS 1.3 implementations MUST NOT send them 4204 but might receive them from older TLS implementations. 4206 A.1. Record Layer 4208 struct { 4209 uint8 major; 4210 uint8 minor; 4211 } ProtocolVersion; 4213 enum { 4214 invalid_RESERVED(0), 4215 change_cipher_spec_RESERVED(20), 4216 alert(21), 4217 handshake(22), 4218 application_data(23) 4219 (255) 4220 } ContentType; 4222 struct { 4223 ContentType type; 4224 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 4225 uint16 length; 4226 opaque fragment[TLSPlaintext.length]; 4227 } TLSPlaintext; 4229 struct { 4230 ContentType opaque_type = application_data(23); /* see fragment.type */ 4231 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 4232 uint16 length; 4233 aead-ciphered struct { 4234 opaque content[TLSPlaintext.length]; 4235 ContentType type; 4236 uint8 zeros[length_of_padding]; 4237 } fragment; 4238 } TLSCiphertext; 4240 A.2. Alert Messages 4241 enum { warning(1), fatal(2), (255) } AlertLevel; 4243 enum { 4244 close_notify(0), 4245 end_of_early_data(1), 4246 unexpected_message(10), /* fatal */ 4247 bad_record_mac(20), /* fatal */ 4248 decryption_failed_RESERVED(21), /* fatal */ 4249 record_overflow(22), /* fatal */ 4250 decompression_failure_RESERVED(30), /* fatal */ 4251 handshake_failure(40), /* fatal */ 4252 no_certificate_RESERVED(41), /* fatal */ 4253 bad_certificate(42), 4254 unsupported_certificate(43), 4255 certificate_revoked(44), 4256 certificate_expired(45), 4257 certificate_unknown(46), 4258 illegal_parameter(47), /* fatal */ 4259 unknown_ca(48), /* fatal */ 4260 access_denied(49), /* fatal */ 4261 decode_error(50), /* fatal */ 4262 decrypt_error(51), /* fatal */ 4263 export_restriction_RESERVED(60), /* fatal */ 4264 protocol_version(70), /* fatal */ 4265 insufficient_security(71), /* fatal */ 4266 internal_error(80), /* fatal */ 4267 inappropriate_fallback(86), /* fatal */ 4268 user_canceled(90), 4269 no_renegotiation_RESERVED(100), /* fatal */ 4270 missing_extension(109), /* fatal */ 4271 unsupported_extension(110), /* fatal */ 4272 certificate_unobtainable(111), 4273 unrecognized_name(112), 4274 bad_certificate_status_response(113), /* fatal */ 4275 bad_certificate_hash_value(114), /* fatal */ 4276 unknown_psk_identity(115), 4277 (255) 4278 } AlertDescription; 4280 struct { 4281 AlertLevel level; 4282 AlertDescription description; 4283 } Alert; 4285 A.3. Handshake Protocol 4287 enum { 4288 hello_request_RESERVED(0), 4289 client_hello(1), 4290 server_hello(2), 4291 session_ticket(4), 4292 hello_retry_request(6), 4293 encrypted_extensions(8), 4294 certificate(11), 4295 server_key_exchange_RESERVED(12), 4296 certificate_request(13), 4297 server_hello_done_RESERVED(14), 4298 certificate_verify(15), 4299 client_key_exchange_RESERVED(16), 4300 server_configuration(17), 4301 finished(20), 4302 key_update(24), 4303 (255) 4304 } HandshakeType; 4306 struct { 4307 HandshakeType msg_type; /* handshake type */ 4308 uint24 length; /* bytes in message */ 4309 select (HandshakeType) { 4310 case client_hello: ClientHello; 4311 case server_hello: ServerHello; 4312 case hello_retry_request: HelloRetryRequest; 4313 case encrypted_extensions: EncryptedExtensions; 4314 case certificate_request: CertificateRequest; 4315 case server_configuration:ServerConfiguration; 4316 case certificate: Certificate; 4317 case certificate_verify: CertificateVerify; 4318 case finished: Finished; 4319 case session_ticket: NewSessionTicket; 4320 case key_update: KeyUpdate; 4321 } body; 4322 } Handshake; 4324 A.3.1. Key Exchange Messages 4326 struct { 4327 opaque random_bytes[32]; 4328 } Random; 4330 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 4332 struct { 4333 ProtocolVersion client_version = { 3, 4 }; /* TLS v1.3 */ 4334 Random random; 4335 opaque legacy_session_id<0..32>; 4336 CipherSuite cipher_suites<2..2^16-2>; 4337 opaque legacy_compression_methods<1..2^8-1>; 4338 Extension extensions<0..2^16-1>; 4339 } ClientHello; 4341 struct { 4342 ProtocolVersion server_version; 4343 Random random; 4344 CipherSuite cipher_suite; 4345 select (extensions_present) { 4346 case false: 4347 struct {}; 4348 case true: 4349 Extension extensions<0..2^16-1>; 4350 }; 4351 } ServerHello; 4353 struct { 4354 ProtocolVersion server_version; 4355 CipherSuite cipher_suite; 4356 NamedGroup selected_group; 4357 Extension extensions<0..2^16-1>; 4358 } HelloRetryRequest; 4360 struct { 4361 ExtensionType extension_type; 4362 opaque extension_data<0..2^16-1>; 4363 } Extension; 4365 enum { 4366 supported_groups(10), 4367 signature_algorithms(13), 4368 early_data(TBD), 4369 pre_shared_key(TBD), 4370 key_share(TBD), 4371 (65535) 4372 } ExtensionType; 4374 struct { 4375 NamedGroup group; 4376 opaque key_exchange<1..2^16-1>; 4377 } KeyShareEntry; 4379 struct { 4380 select (role) { 4381 case client: 4382 KeyShareEntry client_shares<4..2^16-1>; 4384 case server: 4385 KeyShareEntry server_share; 4386 } 4387 } KeyShare; 4389 opaque dh_Y<1..2^16-1>; 4391 opaque point <1..2^8-1>; 4393 opaque psk_identity<0..2^16-1>; 4395 struct { 4396 select (Role) { 4397 case client: 4398 psk_identity identities<2..2^16-1>; 4400 case server: 4401 psk_identity identity; 4402 } 4403 } PreSharedKeyExtension; 4405 struct { 4406 select (Role) { 4407 case client: 4408 opaque configuration_id<1..2^16-1>; 4409 CipherSuite cipher_suite; 4410 Extension extensions<0..2^16-1>; 4411 opaque context<0..255>; 4413 case server: 4414 struct {}; 4415 } 4416 } EarlyDataIndication; 4418 A.3.1.1. Signature Algorithm Extension 4419 enum { 4420 none(0), 4421 md5_RESERVED(1), 4422 sha1(2), 4423 sha224_RESERVED(3), 4424 sha256(4), sha384(5), sha512(6), 4425 (255) 4426 } HashAlgorithm; 4428 enum { 4429 anonymous_RESERVED(0), 4430 rsa(1), 4431 dsa(2), 4432 ecdsa(3), 4433 rsapss(4), 4434 eddsa(5), 4435 (255) 4436 } SignatureAlgorithm; 4438 struct { 4439 HashAlgorithm hash; 4440 SignatureAlgorithm signature; 4441 } SignatureAndHashAlgorithm; 4443 SignatureAndHashAlgorithm 4444 supported_signature_algorithms<2..2^16-2>; 4446 A.3.1.2. Named Group Extension 4447 enum { 4448 // Elliptic Curve Groups. 4449 obsolete_RESERVED (1..22), 4450 secp256r1 (23), secp384r1 (24), secp521r1 (25), 4452 // ECDH functions. 4453 ecdh_x25519 (29), ecdh_x448 (30), 4455 // Signature-only curves. 4456 eddsa_ed25519 (31), eddsa_ed448 (32), 4458 // Finite Field Groups. 4459 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 4460 ffdhe6144 (259), ffdhe8192 (260), 4462 // Reserved Code Points. 4463 ffdhe_private_use (0x01FC..0x01FF), 4464 ecdhe_private_use (0xFE00..0xFEFF), 4465 obsolete_RESERVED (0xFF01..0xFF02), 4466 (0xFFFF) 4467 } NamedGroup; 4469 struct { 4470 NamedGroup named_group_list<1..2^16-1>; 4471 } NamedGroupList; 4473 Values within "obsolete_RESERVED" ranges were used in previous 4474 versions of TLS and MUST NOT be offered or negotiated by TLS 1.3 4475 implementations. The obsolete curves have various known/theoretical 4476 weaknesses or have had very little usage, in some cases only due to 4477 unintentional server configuration issues. They are no longer 4478 considered appropriate for general use and should be assumed to be 4479 potentially unsafe. The set of curves specified here is sufficient 4480 for interoperability with all currently deployed and properly 4481 configured TLS implementations. 4483 A.3.1.3. Deprecated Extensions 4485 The following extensions are no longer applicable to TLS 1.3, 4486 although TLS 1.3 clients MAY send them if they are willing to 4487 negotiate them with prior versions of TLS. TLS 1.3 servers MUST 4488 ignore these extensions if they are negotiating TLS 1.3: 4489 truncated_hmac [RFC6066], srp [RFC5054], encrypt_then_mac [RFC7366], 4490 extended_master_secret [RFC7627], SessionTicket [RFC5077], and 4491 renegotiation_info [RFC5746]. 4493 A.3.2. Server Parameters Messages 4495 struct { 4496 Extension extensions<0..2^16-1>; 4497 } EncryptedExtensions; 4499 opaque DistinguishedName<1..2^16-1>; 4501 struct { 4502 opaque certificate_extension_oid<1..2^8-1>; 4503 opaque certificate_extension_values<0..2^16-1>; 4504 } CertificateExtension; 4506 struct { 4507 opaque certificate_request_context<0..2^8-1>; 4508 SignatureAndHashAlgorithm 4509 supported_signature_algorithms<2..2^16-2>; 4510 DistinguishedName certificate_authorities<0..2^16-1>; 4511 CertificateExtension certificate_extensions<0..2^16-1>; 4512 } CertificateRequest; 4514 enum { (65535) } ConfigurationExtensionType; 4516 enum { client_authentication(1), early_data(2), 4517 client_authentication_and_data(3), (255) } EarlyDataType; 4519 struct { 4520 ConfigurationExtensionType extension_type; 4521 opaque extension_data<0..2^16-1>; 4522 } ConfigurationExtension; 4524 struct { 4525 opaque configuration_id<1..2^16-1>; 4526 uint32 expiration_date; 4527 KeyShareEntry static_key_share; 4528 EarlyDataType early_data_type; 4529 ConfigurationExtension extensions<0..2^16-1>; 4530 } ServerConfiguration; 4532 A.3.3. Authentication Messages 4533 opaque ASN1Cert<1..2^24-1>; 4535 struct { 4536 opaque certificate_request_context<0..255>; 4537 ASN1Cert certificate_list<0..2^24-1>; 4538 } Certificate; 4540 struct { 4541 digitally-signed struct { 4542 opaque hashed_data[hash_length]; 4543 }; 4544 } CertificateVerify; 4546 struct { 4547 opaque verify_data[verify_data_length]; 4548 } Finished; 4550 A.3.4. Ticket Establishment 4552 struct { 4553 uint32 ticket_lifetime_hint; 4554 opaque ticket<0..2^16-1>; 4555 } NewSessionTicket; 4557 A.4. Cipher Suites 4559 A cipher suite defines a cipher specification supported in TLS and 4560 negotiated via hello messages in the TLS handshake. Cipher suite 4561 names follow a general naming convention composed of a series of 4562 component algorithm names separated by underscores: 4564 CipherSuite TLS_KEA_SIGN_WITH_CIPHER_HASH = VALUE; 4565 +-----------+-------------------------------------------------+ 4566 | Component | Contents | 4567 +-----------+-------------------------------------------------+ 4568 | TLS | The string "TLS" | 4569 | | | 4570 | KEA | The key exchange algorithm | 4571 | | | 4572 | SIGN | The signature algorithm | 4573 | | | 4574 | WITH | The string "WITH" | 4575 | | | 4576 | CIPHER | The symmetric cipher used for record protection | 4577 | | | 4578 | HASH | The hash algorithm used with HKDF | 4579 | | | 4580 | VALUE | The two byte ID assigned for this cipher suite | 4581 +-----------+-------------------------------------------------+ 4583 The "CIPHER" component commonly has sub-components used to designate 4584 the cipher name, bits, and mode, if applicable. For example, 4585 "AES_256_GCM" represents 256-bit AES in the GCM mode of operation. 4586 Cipher suite names that lack a "HASH" value that are defined for use 4587 with TLS 1.2 or later use the SHA-256 hash algorithm by default. 4589 The primary key exchange algorithm used in TLS is Ephemeral Diffie- 4590 Hellman [DH]. The finite field based version is denoted "DHE" and 4591 the elliptic curve based version is denoted "ECDHE". Prior versions 4592 of TLS supported non-ephemeral key exchanges, however these are not 4593 supported by TLS 1.3. 4595 See the definitions of each cipher suite in its specification 4596 document for the full details of each combination of algorithms that 4597 is specified. 4599 The following is a list of standards track server-authenticated (and 4600 optionally client-authenticated) cipher suites which are currently 4601 available in TLS 1.3: 4603 +-------------------------------+----------+------------------------+ 4604 | Cipher Suite Name | Value | Specification | 4605 +-------------------------------+----------+------------------------+ 4606 | TLS_DHE_RSA_WITH_AES_128_GCM_ | {0x00,0x | [RFC5288] | 4607 | SHA256 | 9E} | | 4608 | | | | 4609 | TLS_DHE_RSA_WITH_AES_256_GCM_ | {0x00,0x | [RFC5288] | 4610 | SHA384 | 9F} | | 4611 | | | | 4612 | TLS_ECDHE_ECDSA_WITH_AES_128_ | {0xC0,0x | [RFC5289] | 4613 | GCM_SHA256 | 2B} | | 4614 | | | | 4615 | TLS_ECDHE_ECDSA_WITH_AES_256_ | {0xC0,0x | [RFC5289] | 4616 | GCM_SHA384 | 2C} | | 4617 | | | | 4618 | TLS_ECDHE_RSA_WITH_AES_128_GC | {0xC0,0x | [RFC5289] | 4619 | M_SHA256 | 2F} | | 4620 | | | | 4621 | TLS_ECDHE_RSA_WITH_AES_256_GC | {0xC0,0x | [RFC5289] | 4622 | M_SHA384 | 30} | | 4623 | | | | 4624 | TLS_DHE_RSA_WITH_AES_128_CCM | {0xC0,0x | [RFC6655] | 4625 | | 9E} | | 4626 | | | | 4627 | TLS_DHE_RSA_WITH_AES_256_CCM | {0xC0,0x | [RFC6655] | 4628 | | 9F} | | 4629 | | | | 4630 | TLS_DHE_RSA_WITH_AES_128_CCM_ | {0xC0,0x | [RFC6655] | 4631 | 8 | A2} | | 4632 | | | | 4633 | TLS_DHE_RSA_WITH_AES_256_CCM_ | {0xC0,0x | [RFC6655] | 4634 | 8 | A3} | | 4635 | | | | 4636 | TLS_ECDHE_RSA_WITH_CHACHA20_P | {TBD,TBD | [I-D.ietf-tls-chacha20 | 4637 | OLY1305_SHA256 | } | -poly1305] | 4638 | | | | 4639 | TLS_ECDHE_ECDSA_WITH_CHACHA20 | {TBD,TBD | [I-D.ietf-tls-chacha20 | 4640 | _POLY1305_SHA256 | } | -poly1305] | 4641 | | | | 4642 | TLS_DHE_RSA_WITH_CHACHA20_POL | {TBD,TBD | [I-D.ietf-tls-chacha20 | 4643 | Y1305_SHA256 | } | -poly1305] | 4644 +-------------------------------+----------+------------------------+ 4646 [[TODO: CHACHA20_POLY1305_SHA256 cipher suite IDs are TBD.]] 4648 Note: ECDHE AES GCM was not yet standards track prior to the 4649 publication of this specification. This document promotes it to 4650 Standards Track. 4652 All cipher suites in this section are specified for use with both TLS 4653 1.2 and TLS 1.3, as well as the corresponding versions of DTLS. (see 4654 Appendix C) 4656 New cipher suite values are assigned by IANA as described in 4657 Section 11. 4659 A.4.1. Unauthenticated Operation 4661 Previous versions of TLS offered explicitly unauthenticated cipher 4662 suites based on anonymous Diffie-Hellman. These cipher suites have 4663 been deprecated in TLS 1.3. However, it is still possible to 4664 negotiate cipher suites that do not provide verifiable server 4665 authentication by several methods, including: 4667 - Raw public keys [RFC7250]. 4669 - Using a public key contained in a certificate but without 4670 validation of the certificate chain or any of its contents. 4672 Either technique used alone is are vulnerable to man-in-the-middle 4673 attacks and therefore unsafe for general use. However, it is also 4674 possible to bind such connections to an external authentication 4675 mechanism via out-of-band validation of the server's public key, 4676 trust on first use, or channel bindings [RFC5929]. [[NOTE: TLS 1.3 4677 needs a new channel binding definition that has not yet been 4678 defined.]] If no such mechanism is used, then the connection has no 4679 protection against active man-in-the-middle attack; applications MUST 4680 NOT use TLS in such a way absent explicit configuration or a specific 4681 application profile. 4683 A.5. The Security Parameters 4685 These security parameters are determined by the TLS Handshake 4686 Protocol and provided as parameters to the TLS record layer in order 4687 to initialize a connection state. SecurityParameters includes: 4689 enum { server, client } ConnectionEnd; 4691 enum { tls_kdf_sha256, tls_kdf_sha384 } KDFAlgorithm; 4693 enum { aes_gcm } RecordProtAlgorithm; 4695 /* The algorithms specified in KDFAlgorithm and 4696 RecordProtAlgorithm may be added to. */ 4698 struct { 4699 ConnectionEnd entity; 4700 KDFAlgorithm kdf_algorithm; 4701 RecordProtAlgorithm record_prot_algorithm; 4702 uint8 enc_key_length; 4703 uint8 iv_length; 4704 opaque hs_master_secret[48]; 4705 opaque master_secret[48]; 4706 opaque client_random[32]; 4707 opaque server_random[32]; 4708 } SecurityParameters; 4710 A.6. Changes to RFC 4492 4712 RFC 4492 [RFC4492] adds Elliptic Curve cipher suites to TLS. This 4713 document changes some of the structures used in that document. This 4714 section details the required changes for implementors of both RFC 4715 4492 and TLS 1.2. Implementors of TLS 1.2 who are not implementing 4716 RFC 4492 do not need to read this section. 4718 This document adds an "algorithm" field to the digitally-signed 4719 element in order to identify the signature and digest algorithms used 4720 to create a signature. This change applies to digital signatures 4721 formed using ECDSA as well, thus allowing ECDSA signatures to be used 4722 with digest algorithms other than SHA-1, provided such use is 4723 compatible with the certificate and any restrictions imposed by 4724 future revisions of [RFC5280]. 4726 As described in Section 6.3.4.1.1, the restrictions on the signature 4727 algorithms used to sign certificates are no longer tied to the cipher 4728 suite. Thus, the restrictions on the algorithm used to sign 4729 certificates specified in Sections 2 and 3 of RFC 4492 are also 4730 relaxed. As in this document, the restrictions on the keys in the 4731 end-entity certificate remain. 4733 Appendix B. Implementation Notes 4735 The TLS protocol cannot prevent many common security mistakes. This 4736 section provides several recommendations to assist implementors. 4738 B.1. Random Number Generation and Seeding 4740 TLS requires a cryptographically secure pseudorandom number generator 4741 (PRNG). Care must be taken in designing and seeding PRNGs. PRNGs 4742 based on secure hash operations, most notably SHA-256, are 4743 acceptable, but cannot provide more security than the size of the 4744 random number generator state. 4746 To estimate the amount of seed material being produced, add the 4747 number of bits of unpredictable information in each seed byte. For 4748 example, keystroke timing values taken from a PC compatible 18.2 Hz 4749 timer provide 1 or 2 secure bits each, even though the total size of 4750 the counter value is 16 bits or more. Seeding a 128-bit PRNG would 4751 thus require approximately 100 such timer values. 4753 [RFC4086] provides guidance on the generation of random values. 4755 B.2. Certificates and Authentication 4757 Implementations are responsible for verifying the integrity of 4758 certificates and should generally support certificate revocation 4759 messages. Certificates should always be verified to ensure proper 4760 signing by a trusted Certificate Authority (CA). The selection and 4761 addition of trusted CAs should be done very carefully. Users should 4762 be able to view information about the certificate and root CA. 4764 B.3. Cipher Suite Support 4766 TLS supports a range of key sizes and security levels, including some 4767 that provide no or minimal security. A proper implementation will 4768 probably not support many cipher suites. Applications SHOULD also 4769 enforce minimum and maximum key sizes. For example, certification 4770 paths containing keys or signatures weaker than 2048-bit RSA or 4771 224-bit ECDSA are not appropriate for secure applications. See also 4772 Appendix C.3. 4774 B.4. Implementation Pitfalls 4776 Implementation experience has shown that certain parts of earlier TLS 4777 specifications are not easy to understand, and have been a source of 4778 interoperability and security problems. Many of these areas have 4779 been clarified in this document, but this appendix contains a short 4780 list of the most important things that require special attention from 4781 implementors. 4783 TLS protocol issues: 4785 - Do you correctly handle handshake messages that are fragmented to 4786 multiple TLS records (see Section 5.2.1)? Including corner cases 4787 like a ClientHello that is split to several small fragments? Do 4788 you fragment handshake messages that exceed the maximum fragment 4789 size? In particular, the certificate and certificate request 4790 handshake messages can be large enough to require fragmentation. 4792 - Do you ignore the TLS record layer version number in all TLS 4793 records? (see Appendix C) 4795 - Have you ensured that all support for SSL, RC4, EXPORT ciphers, 4796 and MD5 (via the "signature_algorithm" extension) is completely 4797 removed from all possible configurations that support TLS 1.3 or 4798 later, and that attempts to use these obsolete capabilities fail 4799 correctly? (see Appendix C) 4801 - Do you handle TLS extensions in ClientHello correctly, including 4802 omitting the extensions field completely? 4804 - When the server has requested a client certificate, but no 4805 suitable certificate is available, do you correctly send an empty 4806 Certificate message, instead of omitting the whole message (see 4807 Section 6.3.4.1.2)? 4809 - When processing the plaintext fragment produced by AEAD-Decrypt 4810 and scanning from the end for the ContentType, do you avoid 4811 scanning past the start of the cleartext in the event that the 4812 peer has sent a malformed plaintext of all-zeros? 4814 Cryptographic details: 4816 - What countermeasures do you use to prevent timing attacks against 4817 RSA signing operations [TIMING]? 4819 - When verifying RSA signatures, do you accept both NULL and missing 4820 parameters (see Section 4.8)? Do you verify that the RSA padding 4821 doesn't have additional data after the hash value? [FI06] 4823 - When using Diffie-Hellman key exchange, do you correctly strip 4824 leading zero bytes from the negotiated key (see Section 7.3.2)? 4826 - Does your TLS client check that the Diffie-Hellman parameters sent 4827 by the server are acceptable (see Appendix D.1.1.1)? 4829 - Do you use a strong and, most importantly, properly seeded random 4830 number generator (see Appendix B.1) Diffie-Hellman private values, 4831 the ECDSA "k" parameter, and other security-critical values? 4833 Appendix C. Backward Compatibility 4835 The TLS protocol provides a built-in mechanism for version 4836 negotiation between endpoints potentially supporting different 4837 versions of TLS. 4839 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 4840 also handle clients trying to use future versions of TLS as long as 4841 the ClientHello format remains compatible and the client supports the 4842 highest protocol version available in the server. 4844 Prior versions of TLS used the record layer version number for 4845 various purposes. (TLSPlaintext.record_version & 4846 TLSCiphertext.record_version) As of TLS 1.3, this field is deprecated 4847 and its value MUST be ignored by all implementations. Version 4848 negotiation is performed using only the handshake versions. 4849 (ClientHello.client_version & ServerHello.server_version) In order to 4850 maximize interoperability with older endpoints, implementations that 4851 negotiate the use of TLS 1.0-1.2 SHOULD set the record layer version 4852 number to the negotiated version for the ServerHello and all records 4853 thereafter. 4855 For maximum compatibility with previously non-standard behavior and 4856 misconfigured deployments, all implementations SHOULD support 4857 validation of certification paths based on the expectations in this 4858 document, even when handling prior TLS versions' handshakes. (see 4859 Section 6.3.4.1.1) 4861 C.1. Negotiating with an older server 4863 A TLS 1.3 client who wishes to negotiate with such older servers will 4864 send a normal TLS 1.3 ClientHello containing { 3, 4 } (TLS 1.3) in 4865 ClientHello.client_version. If the server does not support this 4866 version it will respond with a ServerHello containing an older 4867 version number. If the client agrees to use this version, the 4868 negotiation will proceed as appropriate for the negotiated protocol. 4869 A client resuming a session SHOULD initiate the connection using the 4870 version that was previously negotiated. 4872 If the version chosen by the server is not supported by the client 4873 (or not acceptable), the client MUST send a "protocol_version" alert 4874 message and close the connection. 4876 If a TLS server receives a ClientHello containing a version number 4877 greater than the highest version supported by the server, it MUST 4878 reply according to the highest version supported by the server. 4880 Some legacy server implementations are known to not implement the TLS 4881 specification properly and might abort connections upon encountering 4882 TLS extensions or versions which it is not aware of. 4883 Interoperability with buggy servers is a complex topic beyond the 4884 scope of this document. Multiple connection attempts may be required 4885 in order to negotiate a backwards compatible connection, however this 4886 practice is vulnerable to downgrade attacks and is NOT RECOMMENDED. 4888 C.2. Negotiating with an older client 4890 A TLS server can also receive a ClientHello containing a version 4891 number smaller than the highest supported version. If the server 4892 wishes to negotiate with old clients, it will proceed as appropriate 4893 for the highest version supported by the server that is not greater 4894 than ClientHello.client_version. For example, if the server supports 4895 TLS 1.0, 1.1, and 1.2, and client_version is TLS 1.0, the server will 4896 proceed with a TLS 1.0 ServerHello. If the server only supports 4897 versions greater than client_version, it MUST send a 4898 "protocol_version" alert message and close the connection. 4900 Note that earlier versions of TLS did not clearly specify the record 4901 layer version number value in all cases 4902 (TLSPlaintext.record_version). Servers will receive various TLS 1.x 4903 versions in this field, however its value MUST always be ignored. 4905 C.3. Backwards Compatibility Security Restrictions 4907 If an implementation negotiates use of TLS 1.2, then negotiation of 4908 cipher suites also supported by TLS 1.3 SHOULD be preferred, if 4909 available. 4911 The security of RC4 cipher suites is considered insufficient for the 4912 reasons cited in [RFC7465]. Implementations MUST NOT offer or 4913 negotiate RC4 cipher suites for any version of TLS for any reason. 4915 Old versions of TLS permitted the use of very low strength ciphers. 4916 Ciphers with a strength less than 112 bits MUST NOT be offered or 4917 negotiated for any version of TLS for any reason. 4919 The security of SSL 2.0 [SSL2] is considered insufficient for the 4920 reasons enumerated in [RFC6176], and MUST NOT be negotiated for any 4921 reason. 4923 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 4924 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 4925 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 4926 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 4927 order to negotiate older versions of TLS. 4929 Implementations MUST NOT send or accept any records with a version 4930 less than { 3, 0 }. 4932 The security of SSL 3.0 [SSL3] is considered insufficient for the 4933 reasons enumerated in [RFC7568], and MUST NOT be negotiated for any 4934 reason. 4936 Implementations MUST NOT send a ClientHello.client_version or 4937 ServerHello.server_version set to { 3, 0 } or less. Any endpoint 4938 receiving a Hello message with ClientHello.client_version or 4939 ServerHello.server_version set to { 3, 0 } MUST respond with a 4940 "protocol_version" alert message and close the connection. 4942 Implementations MUST NOT use the Truncated HMAC extension, defined in 4943 Section 7 of [RFC6066], as it is not applicable to AEAD ciphers and 4944 has been shown to be insecure in some scenarios. 4946 Appendix D. Security Analysis 4948 [[TODO: The entire security analysis needs a rewrite.]] 4950 The TLS protocol is designed to establish a secure connection between 4951 a client and a server communicating over an insecure channel. This 4952 document makes several traditional assumptions, including that 4953 attackers have substantial computational resources and cannot obtain 4954 secret information from sources outside the protocol. Attackers are 4955 assumed to have the ability to capture, modify, delete, replay, and 4956 otherwise tamper with messages sent over the communication channel. 4957 This appendix outlines how TLS has been designed to resist a variety 4958 of attacks. 4960 D.1. Handshake Protocol 4962 The TLS Handshake Protocol is responsible for selecting a cipher spec 4963 and generating a master secret, which together comprise the primary 4964 cryptographic parameters associated with a secure session. The TLS 4965 Handshake Protocol can also optionally authenticate parties who have 4966 certificates signed by a trusted certificate authority. 4968 D.1.1. Authentication and Key Exchange 4970 TLS supports three authentication modes: authentication of both 4971 parties, server authentication with an unauthenticated client, and 4972 total anonymity. Whenever the server is authenticated, the channel 4973 is secure against man-in-the-middle attacks, but completely anonymous 4974 sessions are inherently vulnerable to such attacks. Anonymous 4975 servers cannot authenticate clients. If the server is authenticated, 4976 its certificate message must provide a valid certificate chain 4977 leading to an acceptable certificate authority. Similarly, 4978 authenticated clients must supply an acceptable certificate to the 4979 server. Each party is responsible for verifying that the other's 4980 certificate is valid and has not expired or been revoked. 4982 [[TODO: Rewrite this because the master_secret is not used this way 4983 any more after Hugo's changes.]] The general goal of the key exchange 4984 process is to create a master_secret known to the communicating 4985 parties and not to attackers (see Section 7.1). The master_secret is 4986 required to generate the Finished messages and record protection keys 4987 (see Section 6.3.4.3 and Section 7.3). By sending a correct Finished 4988 message, parties thus prove that they know the correct master_secret. 4990 D.1.1.1. Diffie-Hellman Key Exchange with Authentication 4992 When Diffie-Hellman key exchange is used, the client and server use 4993 the "key_share" extension to send temporary Diffie-Hellman 4994 parameters. The signature in the certificate verify message (if 4995 present) covers the entire handshake up to that point and thus 4996 attests the certificate holder's desire to use the the ephemeral DHE 4997 keys. 4999 Peers SHOULD validate each other's public key Y (dh_Ys offered by the 5000 server or DH_Yc offered by the client) by ensuring that 1 < Y < p-1. 5001 This simple check ensures that the remote peer is properly behaved 5002 and isn't forcing the local system into a small subgroup. 5004 Additionally, using a fresh key for each handshake provides Perfect 5005 Forward Secrecy. Implementations SHOULD generate a new X for each 5006 handshake when using DHE cipher suites. 5008 D.1.2. Version Rollback Attacks 5010 Because TLS includes substantial improvements over SSL Version 2.0, 5011 attackers may try to make TLS-capable clients and servers fall back 5012 to Version 2.0. This attack can occur if (and only if) two TLS- 5013 capable parties use an SSL 2.0 handshake. (See also Appendix C.3.) 5014 Although the solution using non-random PKCS #1 block type 2 message 5015 padding is inelegant, it provides a reasonably secure way for Version 5016 3.0 servers to detect the attack. This solution is not secure 5017 against attackers who can brute-force the key and substitute a new 5018 ENCRYPTED-KEY-DATA message containing the same key (but with normal 5019 padding) before the application-specified wait threshold has expired. 5020 Altering the padding of the least-significant 8 bytes of the PKCS 5021 padding does not impact security for the size of the signed hashes 5022 and RSA key lengths used in the protocol, since this is essentially 5023 equivalent to increasing the input block size by 8 bytes. 5025 D.1.3. Detecting Attacks Against the Handshake Protocol 5027 An attacker might try to influence the handshake exchange to make the 5028 parties select different encryption algorithms than they would 5029 normally choose. 5031 For this attack, an attacker must actively change one or more 5032 handshake messages. If this occurs, the client and server will 5033 compute different values for the handshake message hashes. As a 5034 result, the parties will not accept each others' Finished messages. 5035 Without the static secret, the attacker cannot repair the Finished 5036 messages, so the attack will be discovered. 5038 D.2. Protecting Application Data 5040 The shared secrets are hashed with the handshake transcript to 5041 produce unique record protection secrets for each connection. 5043 Outgoing data is protected using an AEAD algorithm before 5044 transmission. The authentication data includes the sequence number, 5045 message type, message length, and the message contents. The message 5046 type field is necessary to ensure that messages intended for one TLS 5047 record layer client are not redirected to another. The sequence 5048 number ensures that attempts to delete or reorder messages will be 5049 detected. Since sequence numbers are 64 bits long, they should never 5050 overflow. Messages from one party cannot be inserted into the 5051 other's output, since they use independent keys. 5053 D.3. Denial of Service 5055 TLS is susceptible to a number of denial-of-service (DoS) attacks. 5056 In particular, an attacker who initiates a large number of TCP 5057 connections can cause a server to consume large amounts of CPU doing 5058 asymmetric crypto operations. However, because TLS is generally used 5059 over TCP, it is difficult for the attacker to hide their point of 5060 origin if proper TCP SYN randomization is used [RFC1948] by the TCP 5061 stack. 5063 Because TLS runs over TCP, it is also susceptible to a number of DoS 5064 attacks on individual connections. In particular, attackers can 5065 forge RSTs, thereby terminating connections, or forge partial TLS 5066 records, thereby causing the connection to stall. These attacks 5067 cannot in general be defended against by a TCP-using protocol. 5068 Implementors or users who are concerned with this class of attack 5069 should use IPsec AH [RFC4302] or ESP [RFC4303]. 5071 D.4. Final Notes 5073 For TLS to be able to provide a secure connection, both the client 5074 and server systems, keys, and applications must be secure. In 5075 addition, the implementation must be free of security errors. 5077 The system is only as strong as the weakest key exchange and 5078 authentication algorithm supported, and only trustworthy 5079 cryptographic functions should be used. Short public keys and 5080 anonymous servers should be used with great caution. Implementations 5081 and users must be careful when deciding which certificates and 5082 certificate authorities are acceptable; a dishonest certificate 5083 authority can do tremendous damage. 5085 Appendix E. Working Group Information 5087 The discussion list for the IETF TLS working group is located at the 5088 e-mail address tls@ietf.org [1]. Information on the group and 5089 information on how to subscribe to the list is at 5090 https://www1.ietf.org/mailman/listinfo/tls 5092 Archives of the list can be found at: https://www.ietf.org/mail- 5093 archive/web/tls/current/index.html 5095 Appendix F. Contributors 5097 - Martin Abadi 5098 University of California, Santa Cruz 5099 abadi@cs.ucsc.edu 5101 - Christopher Allen (co-editor of TLS 1.0) 5102 Alacrity Ventures 5103 ChristopherA@AlacrityManagement.com 5105 - Steven M. Bellovin 5106 Columbia University 5107 smb@cs.columbia.edu 5109 - Benjamin Beurdouche 5110 - Karthikeyan Bhargavan (co-author of [RFC7627]) 5111 INRIA 5112 karthikeyan.bhargavan@inria.fr 5114 - Simon Blake-Wilson (co-author of [RFC4492]) 5115 BCI 5116 sblakewilson@bcisse.com 5118 - Nelson Bolyard (co-author of [RFC4492]) 5119 Sun Microsystems, Inc. 5120 nelson@bolyard.com 5122 - Ran Canetti 5123 IBM 5124 canetti@watson.ibm.com 5126 - Pete Chown 5127 Skygate Technology Ltd 5128 pc@skygate.co.uk 5130 - Antoine Delignat-Lavaud (co-author of [RFC7627]) 5131 INRIA 5132 antoine.delignat-lavaud@inria.fr 5134 - Tim Dierks (co-editor of TLS 1.0, 1.1, and 1.2) 5135 Independent 5136 tim@dierks.org 5138 - Taher Elgamal 5139 Securify 5140 taher@securify.com 5142 - Pasi Eronen 5143 Nokia 5144 pasi.eronen@nokia.com 5146 - Cedric Fournet 5147 Microsoft 5148 fournet@microsoft.com 5150 - Anil Gangolli 5151 anil@busybuddha.org 5153 - David M. Garrett 5155 - Vipul Gupta (co-author of [RFC4492]) 5156 Sun Microsystems Laboratories 5157 vipul.gupta@sun.com 5159 - Chris Hawk (co-author of [RFC4492]) 5160 Corriente Networks LLC 5161 chris@corriente.net 5163 - Kipp Hickman 5165 - Alfred Hoenes 5167 - David Hopwood 5168 Independent Consultant 5169 david.hopwood@blueyonder.co.uk 5171 - Daniel Kahn Gillmor 5172 ACLU 5173 dkg@fifthhorseman.net 5175 - Phil Karlton (co-author of SSL 3.0) 5177 - Paul Kocher (co-author of SSL 3.0) 5178 Cryptography Research 5179 paul@cryptography.com 5181 - Hugo Krawczyk 5182 IBM 5183 hugo@ee.technion.ac.il 5185 - Adam Langley (co-author of [RFC7627]) 5186 Google 5187 agl@google.com 5189 - Ilari Liusvaara 5190 Independent 5191 ilariliusvaara@welho.com 5193 - Jan Mikkelsen 5194 Transactionware 5195 janm@transactionware.com 5197 - Bodo Moeller (co-author of [RFC4492]) 5198 Google 5199 bodo@openssl.org 5201 - Erik Nygren 5202 Akamai Technologies 5203 erik+ietf@nygren.org 5205 - Magnus Nystrom 5206 RSA Security 5207 magnus@rsasecurity.com 5209 - Alfredo Pironti (co-author of [RFC7627]) 5210 INRIA 5211 alfredo.pironti@inria.fr 5213 - Andrei Popov 5214 Microsoft 5215 andrei.popov@microsoft.com 5217 - Marsh Ray (co-author of [RFC7627]) 5218 Microsoft 5219 maray@microsoft.com 5221 - Robert Relyea 5222 Netscape Communications 5223 relyea@netscape.com 5225 - Jim Roskind 5226 Netscape Communications 5227 jar@netscape.com 5229 - Michael Sabin 5231 - Dan Simon 5232 Microsoft, Inc. 5233 dansimon@microsoft.com 5235 - Bjoern Tackmann 5236 University of California, San Diego 5237 btackmann@eng.ucsd.edu 5239 - Martin Thomson 5240 Mozilla 5241 mt@mozilla.com 5243 - Tom Weinstein 5245 - Hoeteck Wee 5246 Ecole Normale Superieure, Paris 5247 hoeteck@alum.mit.edu 5249 - Tim Wright 5250 Vodafone 5251 timothy.wright@vodafone.com 5253 Author's Address 5255 Eric Rescorla 5256 RTFM, Inc. 5258 EMail: ekr@rtfm.com