idnits 2.17.1 draft-ietf-tls-tls13-07.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 4 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 RFC3268, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document obsoletes RFC4346, 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 obsoletes RFC4366, 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 811 has weird spacing: '...gorithm rec...' == Line 2646 has weird spacing: '...ixed_dh a c...' == Line 2647 has weird spacing: '...ixed_dh a c...' == Line 2923 has weird spacing: '...ed_ecdh sam...' == Line 3128 has weird spacing: '...ication maste...' == (1 more instance...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The length of the per-record nonce (iv_length) is set to max(8 bytes, N_MIN) for the AEAD algorithm (see [RFC5116] Section 4). An AEAD algorithm where N_MAX is less than 8 bytes MUST not be used with TLS. The per-record nonce for the AEAD construction is formed as follows: == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If TLS client authentication is being used, then either "early_handshake" or "early_handshake_and_data" MUST be indicated in order to send the client authentication data on the first flight. In either case, the client Certificate and CertificateVerify (assuming that the Certificate is non-empty) MUST be sent on the first flight A server which receives an initial flight with only "early_data" and which expects certificate-based client authentication MUST not accept early data. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: expiration_date The last time when this configuration is expected to be valid (in seconds since the Unix epoch). Servers MUST NOT use any value more than 604800 seconds (7 days) in the future. Clients MUST not cache configurations for longer than 7 days, regardless of the expiration_date. [[OPEN ISSUE: Is this the right value? The idea is just to minimize exposure.]] (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 (July 08, 2015) is 3214 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 386 -- Looks like a reference, but probably isn't: '1' on line 3473 -- Looks like a reference, but probably isn't: '3' on line 457 -- Looks like a reference, but probably isn't: '9' on line 422 -- Looks like a reference, but probably isn't: '2' on line 4285 -- Looks like a reference, but probably isn't: '4' on line 458 -- Looks like a reference, but probably isn't: '8' on line 459 -- Looks like a reference, but probably isn't: '10' on line 569 -- Looks like a reference, but probably isn't: '48' on line 3886 -- Looks like a reference, but probably isn't: '32' on line 3888 == Missing Reference: 'NewSessionTicket' is mentioned on line 1613, but not defined -- Looks like a reference, but probably isn't: '13' on line 2129 -- Looks like a reference, but probably isn't: '6' on line 3173 == Unused Reference: 'RFC2104' is defined on line 3294, but no explicit reference was found in the text == Unused Reference: 'RFC5869' is defined on line 3322, but no explicit reference was found in the text == Unused Reference: 'RFC2246' is defined on line 3388, but no explicit reference was found in the text == Unused Reference: 'RFC3268' is defined on line 3391, but no explicit reference was found in the text == Unused Reference: 'RFC5705' is defined on line 3433, 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' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' ** Downref: Normative reference to an Informational RFC: RFC 1321 ** 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 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'X680' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- Possible downref: Non-RFC (?) normative reference: ref. 'X962' == Outdated reference: A later version (-06) exists of draft-ietf-tls-session-hash-05 -- 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 2246 (Obsoleted by RFC 4346) -- Obsolete informational reference (is this intentional?): RFC 3268 (Obsoleted by RFC 5246) -- Obsolete informational reference (is this intentional?): RFC 4346 (Obsoleted by RFC 5246) -- Obsolete informational reference (is this intentional?): RFC 4366 (Obsoleted by RFC 5246, RFC 6066) -- Obsolete informational reference (is this intentional?): RFC 4492 (Obsoleted by RFC 8422) -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5081 (Obsoleted by RFC 6091) Summary: 6 errors (**), 0 flaws (~~), 17 warnings (==), 37 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: 3268, 4346, 4366, 5246, 5077 July 08, 2015 5 (if approved) 6 Updates: 4492 (if approved) 7 Intended status: Standards Track 8 Expires: January 9, 2016 10 The Transport Layer Security (TLS) Protocol Version 1.3 11 draft-ietf-tls-tls13-07 13 Abstract 15 This document specifies Version 1.3 of the Transport Layer Security 16 (TLS) protocol. The TLS protocol provides communications security 17 over the Internet. The protocol allows client/server applications to 18 communicate in a way that is designed to prevent eavesdropping, 19 tampering, or message forgery. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 9, 2016. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 This document may contain material from IETF Documents or IETF 54 Contributions published or made publicly available before November 55 10, 2008. The person(s) controlling the copyright in some of this 56 material may not have granted the IETF Trust the right to allow 57 modifications of such material outside the IETF Standards Process. 58 Without obtaining an adequate license from the person(s) controlling 59 the copyright in such materials, this document may not be modified 60 outside the IETF Standards Process, and derivative works of it may 61 not be created outside the IETF Standards Process, except to format 62 it for publication as an RFC or to translate it into languages other 63 than English. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 68 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 5 69 1.2. Major Differences from TLS 1.2 . . . . . . . . . . . . . 6 70 2. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 3. Goals of This Document . . . . . . . . . . . . . . . . . . . 8 72 4. Presentation Language . . . . . . . . . . . . . . . . . . . . 8 73 4.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 8 74 4.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 9 75 4.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 4.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 4.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 10 78 4.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 11 79 4.6.1. Variants . . . . . . . . . . . . . . . . . . . . . . 12 80 4.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 13 81 4.8. Primitive Types . . . . . . . . . . . . . . . . . . . . . 13 82 4.9. Cryptographic Attributes . . . . . . . . . . . . . . . . 14 83 4.9.1. Digital Signing . . . . . . . . . . . . . . . . . . . 14 84 4.9.2. Authenticated Encryption with Additional Data (AEAD) 15 85 5. The TLS Record Protocol . . . . . . . . . . . . . . . . . . . 16 86 5.1. Connection States . . . . . . . . . . . . . . . . . . . . 17 87 5.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 19 88 5.2.1. Fragmentation . . . . . . . . . . . . . . . . . . . . 19 89 5.2.2. Record Payload Protection . . . . . . . . . . . . . . 20 90 6. The TLS Handshaking Protocols . . . . . . . . . . . . . . . . 22 91 6.1. Alert Protocol . . . . . . . . . . . . . . . . . . . . . 23 92 6.1.1. Closure Alerts . . . . . . . . . . . . . . . . . . . 24 93 6.1.2. Error Alerts . . . . . . . . . . . . . . . . . . . . 25 94 6.2. Handshake Protocol Overview . . . . . . . . . . . . . . . 29 95 6.2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . 32 96 6.2.2. Cached Server Configuration . . . . . . . . . . . . . 33 97 6.2.3. Zero-RTT Exchange . . . . . . . . . . . . . . . . . . 34 98 6.2.4. Resumption and PSK . . . . . . . . . . . . . . . . . 35 99 6.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 36 100 6.3.1. Hello Messages . . . . . . . . . . . . . . . . . . . 37 101 6.3.2. Server Key Share . . . . . . . . . . . . . . . . . . 54 102 6.3.3. Encrypted Extensions . . . . . . . . . . . . . . . . 55 103 6.3.4. Server Certificate . . . . . . . . . . . . . . . . . 55 104 6.3.5. Certificate Request . . . . . . . . . . . . . . . . . 58 105 6.3.6. Server Configuration . . . . . . . . . . . . . . . . 59 106 6.3.7. Server Certificate Verify . . . . . . . . . . . . . . 61 107 6.3.8. Server Finished . . . . . . . . . . . . . . . . . . . 62 108 6.3.9. Client Certificate . . . . . . . . . . . . . . . . . 63 109 6.3.10. Client Certificate Verify . . . . . . . . . . . . . . 64 110 6.3.11. New Session Ticket Message . . . . . . . . . . . . . 65 111 7. Cryptographic Computations . . . . . . . . . . . . . . . . . 66 112 7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 66 113 7.2. Traffic Key Calculation . . . . . . . . . . . . . . . . . 67 114 7.2.1. The Handshake Hash . . . . . . . . . . . . . . . . . 68 115 7.2.2. Diffie-Hellman . . . . . . . . . . . . . . . . . . . 69 116 7.2.3. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 69 117 8. Mandatory Cipher Suites . . . . . . . . . . . . . . . . . . . 70 118 9. Application Data Protocol . . . . . . . . . . . . . . . . . . 70 119 10. Security Considerations . . . . . . . . . . . . . . . . . . . 70 120 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 70 121 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 122 12.1. Normative References . . . . . . . . . . . . . . . . . . 72 123 12.2. Informative References . . . . . . . . . . . . . . . . . 73 124 12.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 76 125 Appendix A. Protocol Data Structures and Constant Values . . . . 77 126 A.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 77 127 A.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 77 128 A.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 78 129 A.3.1. Hello Messages . . . . . . . . . . . . . . . . . . . 79 130 A.3.2. Key Exchange Messages . . . . . . . . . . . . . . . . 82 131 A.3.3. Authentication Messages . . . . . . . . . . . . . . . 83 132 A.3.4. Handshake Finalization Messages . . . . . . . . . . . 84 133 A.3.5. Ticket Establishment . . . . . . . . . . . . . . . . 84 134 A.4. The Cipher Suite . . . . . . . . . . . . . . . . . . . . 84 135 A.5. The Security Parameters . . . . . . . . . . . . . . . . . 86 136 A.6. Changes to RFC 4492 . . . . . . . . . . . . . . . . . . . 86 137 Appendix B. Cipher Suite Definitions . . . . . . . . . . . . . . 87 138 Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 87 139 C.1. Random Number Generation and Seeding . . . . . . . . . . 87 140 C.2. Certificates and Authentication . . . . . . . . . . . . . 87 141 C.3. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 88 142 C.4. Implementation Pitfalls . . . . . . . . . . . . . . . . . 88 143 Appendix D. Backward Compatibility . . . . . . . . . . . . . . . 89 144 D.1. Negotiating with an older server . . . . . . . . . . . . 89 145 D.2. Negotiating with an older client . . . . . . . . . . . . 90 146 D.3. Backwards Compatibility Security Restrictions . . . . . . 90 147 Appendix E. Security Analysis . . . . . . . . . . . . . . . . . 91 148 E.1. Handshake Protocol . . . . . . . . . . . . . . . . . . . 91 149 E.1.1. Authentication and Key Exchange . . . . . . . . . . . 92 150 E.1.2. Version Rollback Attacks . . . . . . . . . . . . . . 93 151 E.1.3. Detecting Attacks Against the Handshake Protocol . . 93 152 E.2. Protecting Application Data . . . . . . . . . . . . . . . 93 153 E.3. Denial of Service . . . . . . . . . . . . . . . . . . . . 94 154 E.4. Final Notes . . . . . . . . . . . . . . . . . . . . . . . 94 155 Appendix F. Working Group Information . . . . . . . . . . . . . 94 156 Appendix G. Contributors . . . . . . . . . . . . . . . . . . . . 95 158 1. Introduction 160 DISCLAIMER: This is a WIP draft of TLS 1.3 and has not yet seen 161 significant security analysis. 163 RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 164 draft is maintained in GitHub. Suggested changes should be submitted 165 as pull requests at https://github.com/tlswg/tls13-spec. 166 Instructions are on that page as well. Editorial changes can be 167 managed in GitHub, but any substantive change should be discussed on 168 the TLS mailing list. 170 The primary goal of the TLS protocol is to provide privacy and data 171 integrity between two communicating applications. The protocol is 172 composed of two layers: the TLS Record Protocol and the TLS Handshake 173 Protocol. At the lowest level, layered on top of some reliable 174 transport protocol (e.g., TCP [RFC0793]), is the TLS Record Protocol. 175 The TLS Record Protocol provides connection security that has two 176 basic properties: 178 - The connection is private. Symmetric cryptography is used for 179 data encryption (e.g., AES [AES], etc.). The keys for this 180 symmetric encryption are generated uniquely for each connection 181 and are based on a secret negotiated by another protocol (such as 182 the TLS Handshake Protocol). The Record Protocol can also be used 183 without encryption, i.e., in integrity-only modes. 185 - The connection is reliable. Messages include an authentication 186 tag which protects them against modification. 188 - The Record Protocol can operate in an insecure mode but is 189 generally only used in this mode while another protocol is using 190 the Record Protocol as a transport for negotiating security 191 parameters. 193 The TLS Record Protocol is used for encapsulation of various higher- 194 level protocols. One such encapsulated protocol, the TLS Handshake 195 Protocol, allows the server and client to authenticate each other and 196 to negotiate an encryption algorithm and cryptographic keys before 197 the application protocol transmits or receives its first byte of 198 data. The TLS Handshake Protocol provides connection security that 199 has three basic properties: 201 - The peer's identity can be authenticated using asymmetric, or 202 public key, cryptography (e.g., RSA [RSA], DSA [DSS], etc.). This 203 authentication can be made optional, but is generally required for 204 at least one of the peers. 206 - The negotiation of a shared secret is secure: the negotiated 207 secret is unavailable to eavesdroppers, and for any authenticated 208 connection the secret cannot be obtained, even by an attacker who 209 can place himself in the middle of the connection. 211 - The negotiation is reliable: no attacker can modify the 212 negotiation communication without being detected by the parties to 213 the communication. 215 One advantage of TLS is that it is application protocol independent. 216 Higher-level protocols can layer on top of the TLS protocol 217 transparently. The TLS standard, however, does not specify how 218 protocols add security with TLS; the decisions on how to initiate TLS 219 handshaking and how to interpret the authentication certificates 220 exchanged are left to the judgment of the designers and implementors 221 of protocols that run on top of TLS. 223 1.1. Conventions and Terminology 225 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 226 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 227 "OPTIONAL" in this document are to be interpreted as described in RFC 228 2119 [RFC2119]. 230 The following terms are used: 232 client: The endpoint initiating the TLS connection. 234 connection: A transport-layer connection between two endpoints. 236 endpoint: Either the client or server of the connection. 238 handshake: An initial negotiation between client and server that 239 establishes the parameters of their transactions. 241 peer: An endpoint. When discussing a particular endpoint, "peer" 242 refers to the endpoint that is remote to the primary subject of 243 discussion. 245 receiver: An endpoint that is receiving records. 247 sender: An endpoint that is transmitting records. 249 session: An association between a client and a server resulting from 250 a handshake. 252 server: The endpoint which did not initiate the TLS connection. 254 1.2. Major Differences from TLS 1.2 256 draft-07 - Integration of semi-ephemeral DH proposal. 258 - Add initial 0-RTT support 260 - Remove resumption and replace with PSK + tickets 262 - Move ClientKeyShare into an extension. 264 - Move to HKDF 266 draft-06 268 - Prohibit RC4 negotiation for backwards compatibility. 270 - Freeze & deprecate record layer version field. 272 - Update format of signatures with context. 274 - Remove explicit IV. 276 draft-05 278 - Prohibit SSL negotiation for backwards compatibility. 280 - Fix which MS is used for exporters. 282 draft-04 284 - Modify key computations to include session hash. 286 - Remove ChangeCipherSpec 287 - Renumber the new handshake messages to be somewhat more consistent 288 with existing convention and to remove a duplicate registration. 290 - Remove renegotiation. 292 - Remove point format negotiation. 294 draft-03 296 - Remove GMT time. 298 - Merge in support for ECC from RFC 4492 but without explicit 299 curves. 301 - Remove the unnecessary length field from the AD input to AEAD 302 ciphers. 304 - Rename {Client,Server}KeyExchange to {Client,Server}KeyShare 306 - Add an explicit HelloRetryRequest to reject the client's 308 draft-02 310 - Increment version number. 312 - Reworked handshake to provide 1-RTT mode. 314 - Remove custom DHE groups. 316 - Removed support for compression. 318 - Removed support for static RSA and DH key exchange. 320 - Removed support for non-AEAD ciphers 322 2. Goals 324 The goals of the TLS protocol, in order of priority, are as follows: 326 1. Cryptographic security: TLS should be used to establish a secure 327 connection between two parties. 329 2. Interoperability: Independent programmers should be able to 330 develop applications utilizing TLS that can successfully exchange 331 cryptographic parameters without knowledge of one another's code. 333 3. Extensibility: TLS seeks to provide a framework into which new 334 public key and record protection methods can be incorporated as 335 necessary. This will also accomplish two sub-goals: preventing 336 the need to create a new protocol (and risking the introduction 337 of possible new weaknesses) and avoiding the need to implement an 338 entire new security library. 340 4. Relative efficiency: Cryptographic operations tend to be highly 341 CPU intensive, particularly public key operations. For this 342 reason, the TLS protocol has incorporated an optional session 343 caching scheme to reduce the number of connections that need to 344 be established from scratch. Additionally, care has been taken 345 to reduce network activity. 347 3. Goals of This Document 349 This document and the TLS protocol itself have evolved from the SSL 350 3.0 Protocol Specification as published by Netscape. The differences 351 between this protocol and previous versions are significant enough 352 that the various versions of TLS and SSL 3.0 do not interoperate 353 (although each protocol incorporates a mechanism by which an 354 implementation can back down to prior versions). This document is 355 intended primarily for readers who will be implementing the protocol 356 and for those doing cryptographic analysis of it. The specification 357 has been written with this in mind, and it is intended to reflect the 358 needs of those two groups. For that reason, many of the algorithm- 359 dependent data structures and rules are included in the body of the 360 text (as opposed to in an appendix), providing easier access to them. 362 This document is not intended to supply any details of service 363 definition or of interface definition, although it does cover select 364 areas of policy as they are required for the maintenance of solid 365 security. 367 4. Presentation Language 369 This document deals with the formatting of data in an external 370 representation. The following very basic and somewhat casually 371 defined presentation syntax will be used. The syntax draws from 372 several sources in its structure. Although it resembles the 373 programming language "C" in its syntax and XDR [RFC4506] in both its 374 syntax and intent, it would be risky to draw too many parallels. The 375 purpose of this presentation language is to document TLS only; it has 376 no general application beyond that particular goal. 378 4.1. Basic Block Size 380 The representation of all data items is explicitly specified. The 381 basic data block size is one byte (i.e., 8 bits). Multiple byte data 382 items are concatenations of bytes, from left to right, from top to 383 bottom. From the byte stream, a multi-byte item (a numeric in the 384 example) is formed (using C notation) by: 386 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 387 ... | byte[n-1]; 389 This byte ordering for multi-byte values is the commonplace network 390 byte order or big-endian format. 392 4.2. Miscellaneous 394 Comments begin with "/*" and end with "*/". 396 Optional components are denoted by enclosing them in "[[ ]]" double 397 brackets. 399 Single-byte entities containing uninterpreted data are of type 400 opaque. 402 4.3. Vectors 404 A vector (single-dimensioned array) is a stream of homogeneous data 405 elements. The size of the vector may be specified at documentation 406 time or left unspecified until runtime. In either case, the length 407 declares the number of bytes, not the number of elements, in the 408 vector. The syntax for specifying a new type, T', that is a fixed- 409 length vector of type T is 411 T T'[n]; 413 Here, T' occupies n bytes in the data stream, where n is a multiple 414 of the size of T. The length of the vector is not included in the 415 encoded stream. 417 In the following example, Datum is defined to be three consecutive 418 bytes that the protocol does not interpret, while Data is three 419 consecutive Datum, consuming a total of nine bytes. 421 opaque Datum[3]; /* three uninterpreted bytes */ 422 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 424 Variable-length vectors are defined by specifying a subrange of legal 425 lengths, inclusively, using the notation . When 426 these are encoded, the actual length precedes the vector's contents 427 in the byte stream. The length will be in the form of a number 428 consuming as many bytes as required to hold the vector's specified 429 maximum (ceiling) length. A variable-length vector with an actual 430 length field of zero is referred to as an empty vector. 432 T T'; 434 In the following example, mandatory is a vector that must contain 435 between 300 and 400 bytes of type opaque. It can never be empty. 436 The actual length field consumes two bytes, a uint16, which is 437 sufficient to represent the value 400 (see Section 4.4). On the 438 other hand, longer can represent up to 800 bytes of data, or 400 439 uint16 elements, and it may be empty. Its encoding will include a 440 two-byte actual length field prepended to the vector. The length of 441 an encoded vector must be an even multiple of the length of a single 442 element (for example, a 17-byte vector of uint16 would be illegal). 444 opaque mandatory<300..400>; 445 /* length field is 2 bytes, cannot be empty */ 446 uint16 longer<0..800>; 447 /* zero to 400 16-bit unsigned integers */ 449 4.4. Numbers 451 The basic numeric data type is an unsigned byte (uint8). All larger 452 numeric data types are formed from fixed-length series of bytes 453 concatenated as described in Section 4.1 and are also unsigned. The 454 following numeric types are predefined. 456 uint8 uint16[2]; 457 uint8 uint24[3]; 458 uint8 uint32[4]; 459 uint8 uint64[8]; 461 All values, here and elsewhere in the specification, are stored in 462 network byte (big-endian) order; the uint32 represented by the hex 463 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 465 Note that in some cases (e.g., DH parameters) it is necessary to 466 represent integers as opaque vectors. In such cases, they are 467 represented as unsigned integers (i.e., leading zero octets are not 468 required even if the most significant bit is set). 470 4.5. Enumerateds 472 An additional sparse data type is available called enum. A field of 473 type enum can only assume the values declared in the definition. 474 Each definition is a different type. Only enumerateds of the same 475 type may be assigned or compared. Every element of an enumerated 476 must be assigned a value, as demonstrated in the following example. 477 Since the elements of the enumerated are not ordered, they can be 478 assigned any unique value, in any order. 480 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 482 An enumerated occupies as much space in the byte stream as would its 483 maximal defined ordinal value. The following definition would cause 484 one byte to be used to carry fields of type Color. 486 enum { red(3), blue(5), white(7) } Color; 488 One may optionally specify a value without its associated tag to 489 force the width definition without defining a superfluous element. 491 In the following example, Taste will consume two bytes in the data 492 stream but can only assume the values 1, 2, or 4. 494 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 496 The names of the elements of an enumeration are scoped within the 497 defined type. In the first example, a fully qualified reference to 498 the second element of the enumeration would be Color.blue. Such 499 qualification is not required if the target of the assignment is well 500 specified. 502 Color color = Color.blue; /* overspecified, legal */ 503 Color color = blue; /* correct, type implicit */ 505 For enumerateds that are never converted to external representation, 506 the numerical information may be omitted. 508 enum { low, medium, high } Amount; 510 4.6. Constructed Types 512 Structure types may be constructed from primitive types for 513 convenience. Each specification declares a new, unique type. The 514 syntax for definition is much like that of C. 516 struct { 517 T1 f1; 518 T2 f2; 519 ... 520 Tn fn; 521 } [[T]]; 523 The fields within a structure may be qualified using the type's name, 524 with a syntax much like that available for enumerateds. For example, 525 T.f2 refers to the second field of the previous declaration. 526 Structure definitions may be embedded. 528 4.6.1. Variants 530 Defined structures may have variants based on some knowledge that is 531 available within the environment. The selector must be an enumerated 532 type that defines the possible variants the structure defines. There 533 must be a case arm for every element of the enumeration declared in 534 the select. Case arms have limited fall-through: if two case arms 535 follow in immediate succession with no fields in between, then they 536 both contain the same fields. Thus, in the example below, "orange" 537 and "banana" both contain V2. Note that this is a new piece of 538 syntax in TLS 1.2. 540 The body of the variant structure may be given a label for reference. 541 The mechanism by which the variant is selected at runtime is not 542 prescribed by the presentation language. 544 struct { 545 T1 f1; 546 T2 f2; 547 .... 548 Tn fn; 549 select (E) { 550 case e1: Te1; 551 case e2: Te2; 552 case e3: case e4: Te3; 553 .... 554 case en: Ten; 555 } [[fv]]; 556 } [[Tv]]; 558 For example: 560 enum { apple, orange, banana } VariantTag; 562 struct { 563 uint16 number; 564 opaque string<0..10>; /* variable length */ 565 } V1; 567 struct { 568 uint32 number; 569 opaque string[10]; /* fixed length */ 570 } V2; 572 struct { 573 select (VariantTag) { /* value of selector is implicit */ 574 case apple: 575 V1; /* VariantBody, tag = apple */ 576 case orange: 577 case banana: 578 V2; /* VariantBody, tag = orange or banana */ 579 } variant_body; /* optional label on variant */ 580 } VariantRecord; 582 4.7. Constants 584 Typed constants can be defined for purposes of specification by 585 declaring a symbol of the desired type and assigning values to it. 587 Under-specified types (opaque, variable-length vectors, and 588 structures that contain opaque) cannot be assigned values. No fields 589 of a multi-element structure or vector may be elided. 591 For example: 593 struct { 594 uint8 f1; 595 uint8 f2; 596 } Example1; 598 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 600 4.8. Primitive Types 602 The following common primitive types are defined and used 603 subsequently: 605 enum { false(0), true(1) } Boolean; 607 4.9. Cryptographic Attributes 609 The two cryptographic operations -- digital signing, and 610 authenticated encryption with additional data (AEAD) -- are 611 designated digitally-signed, and aead-ciphered, respectively. A 612 field's cryptographic processing is specified by prepending an 613 appropriate key word designation before the field's type 614 specification. Cryptographic keys are implied by the current session 615 state (see Section 5.1). 617 4.9.1. Digital Signing 619 A digitally-signed element is encoded as a struct DigitallySigned: 621 struct { 622 SignatureAndHashAlgorithm algorithm; 623 opaque signature<0..2^16-1>; 624 } DigitallySigned; 626 The algorithm field specifies the algorithm used (see 627 Section 6.3.1.4.1 for the definition of this field). Note that the 628 algorithm field was introduced in TLS 1.2, and is not in earlier 629 versions. The signature is a digital signature using those 630 algorithms over the contents of the element. The contents themselves 631 do not appear on the wire but are simply calculated. The length of 632 the signature is specified by the signing algorithm and key. 634 In previous versions of TLS, the ServerKeyExchange format meant that 635 attackers can obtain a signature of a message with a chosen, 32-byte 636 prefix. Because TLS 1.3 servers are likely to also implement prior 637 versions, the contents of the element always start with 64 bytes of 638 octet 32 in order to clear that chosen-prefix. 640 Following that padding is a NUL-terminated context string in order to 641 disambiguate signatures for different purposes. The context string 642 will be specified whenever a digitally-signed element is used. 644 Finally, the specified contents of the digitally-signed structure 645 follow the NUL at the end of the context string. (See the example at 646 the end of this section.) 648 In RSA signing, the opaque vector contains the signature generated 649 using the RSASSA-PKCS1-v1_5 signature scheme defined in [RFC3447]. 650 As discussed in [RFC3447], the DigestInfo MUST be DER-encoded [X680] 651 [X690]. For hash algorithms without parameters (which includes SHA- 652 1), the DigestInfo.AlgorithmIdentifier.parameters field MUST be NULL, 653 but implementations MUST accept both without parameters and with NULL 654 parameters. Note that earlier versions of TLS used a different RSA 655 signature scheme that did not include a DigestInfo encoding. 657 In DSA, the 20 bytes of the SHA-1 hash are run directly through the 658 Digital Signing Algorithm with no additional hashing. This produces 659 two values, r and s. The DSA signature is an opaque vector, as 660 above, the contents of which are the DER encoding of: 662 Dss-Sig-Value ::= SEQUENCE { 663 r INTEGER, 664 s INTEGER 665 } 667 Note: In current terminology, DSA refers to the Digital Signature 668 Algorithm and DSS refers to the NIST standard. In the original SSL 669 and TLS specs, "DSS" was used universally. This document uses "DSA" 670 to refer to the algorithm, "DSS" to refer to the standard, and it 671 uses "DSS" in the code point definitions for historical continuity. 673 All ECDSA computations MUST be performed according to ANSI X9.62 674 [X962] or its successors. Data to be signed/verified is hashed, and 675 the result run directly through the ECDSA algorithm with no 676 additional hashing. The default hash function is SHA-1 [SHS]. 677 However, an alternative hash function, such as one of the new SHA 678 hash functions specified in FIPS 180-2 may be used instead if the 679 certificate containing the EC public key explicitly requires use of 680 another hash function. (The mechanism for specifying the required 681 hash function has not been standardized, but this provision 682 anticipates such standardization and obviates the need to update this 683 document in response. Future PKIX RFCs may choose, for example, to 684 specify the hash function to be used with a public key in the 685 parameters field of subjectPublicKeyInfo.) [[OPEN ISSUE: This needs 686 updating per 4492-bis https://github.com/tlswg/tls13-spec/issues/59]] 688 4.9.2. Authenticated Encryption with Additional Data (AEAD) 690 In AEAD encryption, the plaintext is simultaneously encrypted and 691 integrity protected. The input may be of any length, and aead- 692 ciphered output is generally larger than the input in order to 693 accommodate the integrity check value. 695 In the following example 696 struct { 697 uint8 field1; 698 uint8 field2; 699 digitally-signed opaque { 700 uint8 field3<0..255>; 701 uint8 field4; 702 }; 703 } UserType; 705 Assume that the context string for the signature was specified as 706 "Example". The input for the signature/hash algorithm would be: 708 2020202020202020202020202020202020202020202020202020202020202020 709 2020202020202020202020202020202020202020202020202020202020202020 710 4578616d706c6500 712 followed by the encoding of the inner struct (field3 and field4). 714 The length of the structure, in bytes, would be equal to two bytes 715 for field1 and field2, plus two bytes for the signature and hash 716 algorithm, plus two bytes for the length of the signature, plus the 717 length of the output of the signing algorithm. The length of the 718 signature is known because the algorithm and key used for the signing 719 are known prior to encoding or decoding this structure. 721 5. The TLS Record Protocol 723 The TLS Record Protocol is a layered protocol. At each layer, 724 messages may include fields for length, description, and content. 725 The Record Protocol takes messages to be transmitted, fragments the 726 data into manageable blocks, protects the records, and transmits the 727 result. Received data is decrypted and verified, reassembled, and 728 then delivered to higher-level clients. 730 Three protocols that use the record protocol are described in this 731 document: the handshake protocol, the alert protocol, and the 732 application data protocol. In order to allow extension of the TLS 733 protocol, additional record content types can be supported by the 734 record protocol. New record content type values are assigned by IANA 735 in the TLS Content Type Registry as described in Section 11. 737 Implementations MUST NOT send record types not defined in this 738 document unless negotiated by some extension. If a TLS 739 implementation receives an unexpected record type, it MUST send an 740 "unexpected_message" alert. 742 Any protocol designed for use over TLS must be carefully designed to 743 deal with all possible attacks against it. As a practical matter, 744 this means that the protocol designer must be aware of what security 745 properties TLS does and does not provide and cannot safely rely on 746 the latter. 748 Note in particular that type and length of a record are not protected 749 by encryption. If this information is itself sensitive, application 750 designers may wish to take steps (padding, cover traffic) to minimize 751 information leakage. 753 5.1. Connection States 755 [[TODO: I plan to totally rewrite or remove this. IT seems like just 756 cruft.]] 758 A TLS connection state is the operating environment of the TLS Record 759 Protocol. It specifies a record protection algorithm and its 760 parameters as well as the record protection keys and IVs for the 761 connection in both the read and the write directions. The security 762 parameters are set by the TLS Handshake Protocol, which also 763 determines when new cryptographic keys are installed and used for 764 record protection. The initial current state always specifies that 765 records are not protected. 767 The security parameters for a TLS Connection read and write state are 768 set by providing the following values: 770 connection end 771 Whether this entity is considered the "client" or the "server" in 772 this connection. 774 Hash algorithm 775 An algorithm used to generate keys from the appropriate secret 776 (see Section 7.1 and Section 7.2). 778 record protection algorithm 779 The algorithm to be used for record protection. This algorithm 780 must be of the AEAD type and thus provides integrity and 781 confidentiality as a single primitive. It is possible to have 782 AEAD algorithms which do not provide any confidentiality and 783 Section 5.2.2 defines a special NULL_NULL AEAD algorithm for use 784 in the initial handshake). This specification includes the key 785 size of this algorithm and of the nonce for the AEAD algorithm. 787 master secret 788 A 48-byte secret shared between the two peers in the connection 789 and used to generate keys for protecting data. 791 client random 792 A 32-byte value provided by the client. 794 server random 795 A 32-byte value provided by the server. 797 These parameters are defined in the presentation language as: 799 enum { server, client } ConnectionEnd; 801 enum { tls_kdf_sha256, tls_kdf_sha384 } KDFAlgorithm; 803 enum { aes_gcm } RecordProtAlgorithm; 805 /* The algorithms specified in KDFAlgorithm and 806 RecordProtAlgorithm may be added to. */ 808 struct { 809 ConnectionEnd entity; 810 KDFAlgorithm kdf_algorithm; 811 RecordProtAlgorithm record_prot_algorithm; 812 uint8 enc_key_length; 813 uint8 iv_length; 814 opaque hs_master_secret[48]; 815 opaque master_secret[48]; 816 opaque client_random[32]; 817 opaque server_random[32]; 818 } SecurityParameters; 820 [TODO: update this to handle new key hierarchy.] 822 The connection state will use the security parameters to generate the 823 following four items: 825 client write key 826 server write key 827 client write iv 828 server write iv 830 The client write parameters are used by the server when receiving and 831 processing records and vice versa. The algorithm used for generating 832 these items from the security parameters is described in Section 7.2. 834 Once the security parameters have been set and the keys have been 835 generated, the connection states can be instantiated by making them 836 the current states. These current states MUST be updated for each 837 record processed. Each connection state includes the following 838 elements: 840 cipher state 841 The current state of the encryption algorithm. This will consist 842 of the scheduled key for that connection. 844 sequence number 845 Each connection state contains a sequence number, which is 846 maintained separately for read and write states. The sequence 847 number is set to zero at the beginning of a connection and 848 incremented by one thereafter. Sequence numbers are of type 849 uint64 and MUST NOT exceed 2^64-1. Sequence numbers do not wrap. 850 If a TLS implementation would need to wrap a sequence number, it 851 MUST terminate the connection. A sequence number is incremented 852 after each record: specifically, the first record transmitted 853 under a particular connection state MUST use sequence number 0. 854 NOTE: This is a change from previous versions of TLS, where 855 sequence numbers were reset whenever keys were changed. 857 5.2. Record Layer 859 The TLS record layer receives uninterpreted data from higher layers 860 in non-empty blocks of arbitrary size. 862 5.2.1. Fragmentation 864 The record layer fragments information blocks into TLSPlaintext 865 records carrying data in chunks of 2^14 bytes or less. Client 866 message boundaries are not preserved in the record layer (i.e., 867 multiple client messages of the same ContentType MAY be coalesced 868 into a single TLSPlaintext record, or a single message MAY be 869 fragmented across several records). 871 struct { 872 uint8 major; 873 uint8 minor; 874 } ProtocolVersion; 876 enum { 877 reserved(20), alert(21), handshake(22), 878 application_data(23), early_handshake(25), 879 (255) 880 } ContentType; 882 struct { 883 ContentType type; 884 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 885 uint16 length; 886 opaque fragment[TLSPlaintext.length]; 887 } TLSPlaintext; 889 type 890 The higher-level protocol used to process the enclosed fragment. 892 record_version 893 The protocol version the current record is compatible with. This 894 value MUST be set to { 3, 1 } for all records. This field is 895 deprecated and MUST be ignored for all purposes. 897 length 898 The length (in bytes) of the following TLSPlaintext.fragment. The 899 length MUST NOT exceed 2^14. 901 fragment 902 The application data. This data is transparent and treated as an 903 independent block to be dealt with by the higher-level protocol 904 specified by the type field. 906 This document describes TLS Version 1.3, which uses the version { 3, 907 4 }. The version value 3.4 is historical, deriving from the use of { 908 3, 1 } for TLS 1.0 and { 3, 0 } for SSL 3.0. In order to maximize 909 backwards compatibility, the record layer version identifies as 910 simply TLS 1.0. Endpoints supporting other versions negotiate the 911 version to use by following the procedure and requirements in 912 Appendix D. 914 Implementations MUST NOT send zero-length fragments of Handshake or 915 Alert types. Zero-length fragments of Application data MAY be sent 916 as they are potentially useful as a traffic analysis countermeasure. 918 5.2.2. Record Payload Protection 920 The record protection functions translate a TLSPlaintext structure 921 into a TLSCiphertext. The deprotection functions reverse the 922 process. In TLS 1.3 as opposed to previous versions of TLS, all 923 ciphers are modeled as "Authenticated Encryption with Additional 924 Data" (AEAD) [RFC5116]. AEAD functions provide a unified encryption 925 and authentication operation which turns plaintext into authenticated 926 ciphertext and back again. 928 AEAD ciphers take as input a single key, a nonce, a plaintext, and 929 "additional data" to be included in the authentication check, as 930 described in Section 2.1 of [RFC5116]. The key is either the 931 client_write_key or the server_write_key. 933 struct { 934 ContentType type; 935 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 936 uint16 length; 937 aead-ciphered struct { 938 opaque content[TLSPlaintext.length]; 939 } fragment; 940 } TLSCiphertext; 942 type 943 The type field is identical to TLSPlaintext.type. 945 record_version 946 The record_version field is identical to 947 TLSPlaintext.record_version and is always { 3, 1 }. Note that the 948 handshake protocol including the ClientHello and ServerHello 949 messages authenticates the protocol version, so this value is 950 redundant. 952 length 953 The length (in bytes) of the following TLSCiphertext.fragment. 954 The length MUST NOT exceed 2^14 + 2048. 956 fragment 957 The AEAD encrypted form of TLSPlaintext.fragment. 959 The length of the per-record nonce (iv_length) is set to max(8 bytes, 960 N_MIN) for the AEAD algorithm (see [RFC5116] Section 4). An AEAD 961 algorithm where N_MAX is less than 8 bytes MUST not be used with TLS. 962 The per-record nonce for the AEAD construction is formed as follows: 964 1. The 64-bit record sequence number is padded to the left with 965 zeroes to iv_length. 967 2. The padded sequence number is XORed with the static 968 client_write_iv or server_write_iv, depending on the role. 970 The resulting quantity (of length iv_length) is used as the per- 971 record nonce. 973 Note: This is a different construction from that in TLS 1.2, which 974 specified a partially explicit nonce. 976 The plaintext is the TLSPlaintext.fragment. 978 The additional authenticated data, which we denote as 979 additional_data, is defined as follows: 981 additional_data = seq_num + TLSPlaintext.type + 982 TLSPlaintext.record_version 984 where "+" denotes concatenation. 986 Note: In versions of TLS prior to 1.3, the additional_data included a 987 length field. This presents a problem for cipher constructions with 988 data-dependent padding (such as CBC). TLS 1.3 removes the length 989 field and relies on the AEAD cipher to provide integrity for the 990 length of the data. 992 The AEAD output consists of the ciphertext output by the AEAD 993 encryption operation. The length will generally be larger than 994 TLSPlaintext.length, but by an amount that varies with the AEAD 995 cipher. Since the ciphers might incorporate padding, the amount of 996 overhead could vary with different TLSPlaintext.length values. Each 997 AEAD cipher MUST NOT produce an expansion of greater than 1024 bytes. 998 Symbolically, 1000 AEADEncrypted = AEAD-Encrypt(write_key, nonce, plaintext, 1001 additional_data) 1003 [[OPEN ISSUE: Reduce these values? https://github.com/tlswg/tls13- 1004 spec/issues/55]] 1006 In order to decrypt and verify, the cipher takes as input the key, 1007 nonce, the "additional_data", and the AEADEncrypted value. The 1008 output is either the plaintext or an error indicating that the 1009 decryption failed. There is no separate integrity check. That is: 1011 TLSPlaintext.fragment = AEAD-Decrypt(write_key, nonce, 1012 AEADEncrypted, 1013 additional_data) 1015 If the decryption fails, a fatal "bad_record_mac" alert MUST be 1016 generated. 1018 As a special case, we define the NULL_NULL AEAD cipher which is 1019 simply the identity operation and thus provides no security. This 1020 cipher MUST ONLY be used with the initial TLS_NULL_WITH_NULL_NULL 1021 cipher suite. 1023 6. The TLS Handshaking Protocols 1025 TLS has three subprotocols that are used to allow peers to agree upon 1026 security parameters for the record layer, to authenticate themselves, 1027 to instantiate negotiated security parameters, and to report error 1028 conditions to each other. 1030 The Handshake Protocol is responsible for negotiating a session, 1031 which consists of the following items: 1033 peer certificate 1034 X509v3 [RFC5280] certificate of the peer. This element of the 1035 state may be null. 1037 cipher spec 1038 Specifies the authentication and key establishment algorithms, the 1039 hash for use with HKDF to generate keying material, and the record 1040 protection algorithm (See Appendix A.5 for formal definition.) 1042 resumption master secret 1043 a secret shared between the client and server that can be used as 1044 a PSK in future connections. 1046 These items are then used to create security parameters for use by 1047 the record layer when protecting application data. Many connections 1048 can be instantiated using the same session using a PSK established in 1049 an initial handshake. 1051 6.1. Alert Protocol 1053 One of the content types supported by the TLS record layer is the 1054 alert type. Alert messages convey the severity of the message 1055 (warning or fatal) and a description of the alert. Alert messages 1056 with a level of fatal result in the immediate termination of the 1057 connection. In this case, other connections corresponding to the 1058 session may continue, but the session identifier MUST be invalidated, 1059 preventing the failed session from being used to establish new 1060 connections. Like other messages, alert messages are encrypted as 1061 specified by the current connection state. 1063 enum { warning(1), fatal(2), (255) } AlertLevel; 1065 enum { 1066 close_notify(0), 1067 unexpected_message(10), /* fatal */ 1068 bad_record_mac(20), /* fatal */ 1069 decryption_failed_RESERVED(21), /* fatal */ 1070 record_overflow(22), /* fatal */ 1071 decompression_failure_RESERVED(30), /* fatal */ 1072 handshake_failure(40), /* fatal */ 1073 no_certificate_RESERVED(41), /* fatal */ 1074 bad_certificate(42), 1075 unsupported_certificate(43), 1076 certificate_revoked(44), 1077 certificate_expired(45), 1078 certificate_unknown(46), 1079 illegal_parameter(47), /* fatal */ 1080 unknown_ca(48), /* fatal */ 1081 access_denied(49), /* fatal */ 1082 decode_error(50), /* fatal */ 1083 decrypt_error(51), /* fatal */ 1084 export_restriction_RESERVED(60), /* fatal */ 1085 protocol_version(70), /* fatal */ 1086 insufficient_security(71), /* fatal */ 1087 internal_error(80), /* fatal */ 1088 user_canceled(90), 1089 no_renegotiation(100), /* fatal */ 1090 unsupported_extension(110), /* fatal */ 1091 (255) 1092 } AlertDescription; 1094 struct { 1095 AlertLevel level; 1096 AlertDescription description; 1097 } Alert; 1099 6.1.1. Closure Alerts 1101 The client and the server must share knowledge that the connection is 1102 ending in order to avoid a truncation attack. Either party may 1103 initiate the exchange of closing messages. 1105 close_notify 1106 This message notifies the recipient that the sender will not send 1107 any more messages on this connection. Note that as of TLS 1.1, 1108 failure to properly close a connection no longer requires that a 1109 session not be resumed. This is a change from TLS 1.0 to conform 1110 with widespread implementation practice. 1112 Either party MAY initiate a close by sending a "close_notify" alert. 1113 Any data received after a closure alert is ignored. If a transport- 1114 level close is received prior to a close_notify, the receiver cannot 1115 know that all the data that was sent has been received. 1117 Unless some other fatal alert has been transmitted, each party is 1118 required to send a "close_notify" alert before closing the write side 1119 of the connection. The other party MUST respond with a 1120 "close_notify" alert of its own and close down the connection 1121 immediately, discarding any pending writes. It is not required for 1122 the initiator of the close to wait for the responding "close_notify" 1123 alert before closing the read side of the connection. 1125 If the application protocol using TLS provides that any data may be 1126 carried over the underlying transport after the TLS connection is 1127 closed, the TLS implementation must receive the responding 1128 "close_notify" alert before indicating to the application layer that 1129 the TLS connection has ended. If the application protocol will not 1130 transfer any additional data, but will only close the underlying 1131 transport connection, then the implementation MAY choose to close the 1132 transport without waiting for the responding "close_notify". No part 1133 of this standard should be taken to dictate the manner in which a 1134 usage profile for TLS manages its data transport, including when 1135 connections are opened or closed. 1137 Note: It is assumed that closing a connection reliably delivers 1138 pending data before destroying the transport. 1140 6.1.2. Error Alerts 1142 Error handling in the TLS Handshake protocol is very simple. When an 1143 error is detected, the detecting party sends a message to the other 1144 party. Upon transmission or receipt of a fatal alert message, both 1145 parties immediately close the connection. Servers and clients MUST 1146 forget any session-identifiers, keys, and secrets associated with a 1147 failed connection. Thus, any connection terminated with a fatal 1148 alert MUST NOT be resumed. 1150 Whenever an implementation encounters a condition which is defined as 1151 a fatal alert, it MUST send the appropriate alert prior to closing 1152 the connection. For all errors where an alert level is not 1153 explicitly specified, the sending party MAY determine at its 1154 discretion whether to treat this as a fatal error or not. If the 1155 implementation chooses to send an alert but intends to close the 1156 connection immediately afterwards, it MUST send that alert at the 1157 fatal alert level. 1159 If an alert with a level of warning is sent and received, generally 1160 the connection can continue normally. If the receiving party decides 1161 not to proceed with the connection (e.g., after having received a 1162 "no_renegotiation" alert that it is not willing to accept), it SHOULD 1163 send a fatal alert to terminate the connection. Given this, the 1164 sending party cannot, in general, know how the receiving party will 1165 behave. Therefore, warning alerts are not very useful when the 1166 sending party wants to continue the connection, and thus are 1167 sometimes omitted. For example, if a peer decides to accept an 1168 expired certificate (perhaps after confirming this with the user) and 1169 wants to continue the connection, it would not generally send a 1170 "certificate_expired" alert. 1172 The following error alerts are defined: 1174 unexpected_message 1175 An inappropriate message was received. This alert is always fatal 1176 and should never be observed in communication between proper 1177 implementations. 1179 bad_record_mac 1180 This alert is returned if a record is received which cannot be 1181 deprotected. Because AEAD algorithms combine decryption and 1182 verification, this message is used for all deprotection failures. 1183 This message is always fatal and should never be observed in 1184 communication between proper implementations (except when messages 1185 were corrupted in the network). 1187 decryption_failed_RESERVED 1188 This alert was used in some earlier versions of TLS, and may have 1189 permitted certain attacks against the CBC mode [CBCATT]. It MUST 1190 NOT be sent by compliant implementations. This message is always 1191 fatal. 1193 record_overflow 1194 A TLSCiphertext record was received that had a length more than 1195 2^14+2048 bytes, or a record decrypted to a TLSPlaintext record 1196 with more than 2^14 bytes. This message is always fatal and 1197 should never be observed in communication between proper 1198 implementations (except when messages were corrupted in the 1199 network). 1201 decompression_failure_RESERVED 1202 This alert was used in previous versions of TLS. TLS 1.3 does not 1203 include compression and TLS 1.3 implementations MUST NOT send this 1204 alert when in TLS 1.3 mode. This message is always fatal. 1206 handshake_failure 1207 Reception of a "handshake_failure" alert message indicates that 1208 the sender was unable to negotiate an acceptable set of security 1209 parameters given the options available. This message is always 1210 fatal. 1212 no_certificate_RESERVED 1213 This alert was used in SSL 3.0 but not any version of TLS. It 1214 MUST NOT be sent by compliant implementations. This message is 1215 always fatal. 1217 bad_certificate 1218 A certificate was corrupt, contained signatures that did not 1219 verify correctly, etc. 1221 unsupported_certificate 1222 A certificate was of an unsupported type. 1224 certificate_revoked 1225 A certificate was revoked by its signer. 1227 certificate_expired 1228 A certificate has expired or is not currently valid. 1230 certificate_unknown 1231 Some other (unspecified) issue arose in processing the 1232 certificate, rendering it unacceptable. 1234 illegal_parameter 1235 A field in the handshake was out of range or inconsistent with 1236 other fields. This message is always fatal. 1238 unknown_ca 1239 A valid certificate chain or partial chain was received, but the 1240 certificate was not accepted because the CA certificate could not 1241 be located or couldn't be matched with a known, trusted CA. This 1242 message is always fatal. 1244 access_denied 1245 A valid certificate was received, but when access control was 1246 applied, the sender decided not to proceed with negotiation. This 1247 message is always fatal. 1249 decode_error 1250 A message could not be decoded because some field was out of the 1251 specified range or the length of the message was incorrect. This 1252 message is always fatal and should never be observed in 1253 communication between proper implementations (except when messages 1254 were corrupted in the network). 1256 decrypt_error 1257 A handshake cryptographic operation failed, including being unable 1258 to correctly verify a signature or validate a Finished message. 1259 This message is always fatal. 1261 export_restriction_RESERVED 1262 This alert was used in some earlier versions of TLS. It MUST NOT 1263 be sent by compliant implementations. This message is always 1264 fatal. 1266 protocol_version 1267 The protocol version the peer has attempted to negotiate is 1268 recognized but not supported. (For example, old protocol versions 1269 might be avoided for security reasons.) This message is always 1270 fatal. 1272 insufficient_security 1273 Returned instead of "handshake_failure" when a negotiation has 1274 failed specifically because the server requires ciphers more 1275 secure than those supported by the client. This message is always 1276 fatal. 1278 internal_error 1279 An internal error unrelated to the peer or the correctness of the 1280 protocol (such as a memory allocation failure) makes it impossible 1281 to continue. This message is always fatal. 1283 user_canceled 1284 This handshake is being canceled for some reason unrelated to a 1285 protocol failure. If the user cancels an operation after the 1286 handshake is complete, just closing the connection by sending a 1287 "close_notify" is more appropriate. This alert should be followed 1288 by a "close_notify". This message is generally a warning. 1290 no_renegotiation 1291 Sent by the client in response to a HelloRequest or by the server 1292 in response to a ClientHello after initial handshaking. Versions 1293 of TLS prior to TLS 1.3 supported renegotiation of a previously 1294 established connection; TLS 1.3 removes this feature. This 1295 message is always fatal. 1297 unsupported_extension 1298 sent by clients that receive an extended ServerHello containing an 1299 extension that they did not put in the corresponding ClientHello. 1300 This message is always fatal. 1302 New Alert values are assigned by IANA as described in Section 11. 1304 6.2. Handshake Protocol Overview 1306 The cryptographic parameters of the session state are produced by the 1307 TLS Handshake Protocol, which operates on top of the TLS record 1308 layer. When a TLS client and server first start communicating, they 1309 agree on a protocol version, select cryptographic algorithms, 1310 optionally authenticate each other, and establish shared secret 1311 keying material. 1313 TLS supports three basic key exchange modes: 1315 - Diffie-Hellman (of both the finite field and elliptic curve 1316 varieties). 1318 - A pre-shared symmetric key (PSK) 1320 - A combination of a symmetric key and Diffie-Hellman 1322 Which mode is used depends on the negotiated cipher suite. 1323 Conceptually, the handshake establishes two secrets which are used to 1324 derive all the keys. 1326 Ephemeral Secret (ES): A secret which is derived from fresh (EC)DHE 1327 shares for this connection. Keying material derived from ES is 1328 intended to be forward secure (with the exception of pre-shared key 1329 only modes). 1331 Static Secret (SS): A secret which may be derived from static or 1332 semi-static keying material, such as a pre-shared key or the server's 1333 semi-static (EC)DH share. 1335 In some cases, as with the DH handshake shown in Figure 1, these 1336 secrets are the same, but having both allows for a uniform key 1337 derivation scheme for all cipher modes. 1339 The basic TLS Handshake for DH is shown in Figure 1: 1341 Client Server 1343 ClientHello 1344 + ClientKeyShare --------> 1345 ServerHello 1346 ServerKeyShare* 1347 {EncryptedExtensions} 1348 {ServerConfiguration*} 1349 {Certificate*} 1350 {CertificateRequest*} 1351 {CertificateVerify*} 1352 <-------- {Finished} 1353 {Certificate*} 1354 {CertificateVerify*} 1355 {Finished} --------> 1356 [Application Data] <-------> [Application Data] 1358 * Indicates optional or situation-dependent messages that are not always sent. 1360 {} Indicates messages protected using keys derived from the ephemeral secret. 1362 [] Indicates messages protected using keys derived from the master secret. 1364 Figure 1: Message flow for full TLS Handshake 1366 The first message sent by the client is the ClientHello 1367 Section 6.3.1.1 which contains a random nonce (ClientHello.random), 1368 its offered protocol version, cipher suite, and extensions, and one 1369 or more Diffie-Hellman key shares in the ClientKeyShare extension 1370 Section 6.3.1.5. 1372 The server processes the ClientHello and determines the appropriate 1373 cryptographic parameters for the connection. It then responds with 1374 the following messages: 1376 ServerHello 1377 indicates the negotiated connection parameters. [Section 6.3.1.2] 1379 ServerKeyShare 1380 the server's ephemeral Diffie-Hellman Share which must be in the 1381 same group as one of the shares offered by the client. This 1382 message will be omitted if DH is not in use (i.e., a pure PSK 1383 cipher suite is selected). The ClientKeyShare and ServerKeyShare 1384 are used together to derive the Static Secret and Ephemeral Secret 1385 (in this mode they are the same). [Section 6.3.2] 1387 ServerConfiguration 1388 supplies a configuration for a future handshake (see 1389 Section 6.2.2). [Section 6.3.6] 1391 EncryptedExtensions 1392 responses to any extensions which are not required in order to 1393 determine the cryptographic parameters. [Section 6.3.3] 1395 Certificate 1396 the server certificate. This message will be omitted if the 1397 server is not authenticating via a certificates. [Section 6.3.4] 1399 CertificateRequest 1400 if certificate-based client authentication is desired, the desired 1401 parameters for that certificate. This message will be omitted if 1402 client authentication is not desired. [[OPEN ISSUE: See 1403 https://github.com/tlswg/tls13-spec/issues/184]]. [Section 6.3.5] 1405 CertificateVerify 1406 a signature over the entire handshake using the public key in the 1407 Certificate message. This message will be omitted if the server 1408 is not authenticating via a certificate. [Section 6.3.7] 1410 Finished 1411 a MAC over the entire handshake computed using the Static Secret. 1412 This message provides key confirmation and In some modes (see 1413 Section 6.2.2) it also authenticates the handshake using the the 1414 Static Secret. [Section 6.3.8] 1416 Upon receiving the server's messages, the client responds with his 1417 final flight of messages: 1419 Certificate 1420 the client's certificate. This message will be omitted if the 1421 client is not authenticating via a certificates. [Section 6.3.9] 1423 CertificateVerify 1424 a signature over the entire handshake using the public key in the 1425 Certificate message. This message will be omitted if the client 1426 is not authenticating via a certificate. [Section 6.3.10] 1428 Finished 1429 a MAC over the entire handshake computed using the Static Secret 1430 and providing key confirmation. [Section 6.3.8] 1432 At this point, the handshake is complete, and the client and server 1433 may exchange application layer data. Application data MUST NOT be 1434 sent prior to sending the Finished message. If client authentication 1435 is requested, the server MUST NOT send application data before it 1436 receives the client's Finished. 1438 [[TODO: Move this elsewhere? Note that higher layers should not be 1439 overly reliant on whether TLS always negotiates the strongest 1440 possible connection between two peers. There are a number of ways in 1441 which a man-in-the-middle attacker can attempt to make two entities 1442 drop down to the least secure method they support. The protocol has 1443 been designed to minimize this risk, but there are still attacks 1444 available. For example, an attacker could block access to the port a 1445 secure service runs on or attempt to get the peers to negotiate an 1446 unauthenticated connection. The fundamental rule is that higher 1447 levels must be cognizant of what their security requirements are and 1448 never transmit information over a channel less secure than what they 1449 require. The TLS protocol is secure in that any cipher suite offers 1450 its promised level of security: if you negotiate AES-GCM [GCM] with a 1451 255-bit ECDHE key exchange with a host whose certificate chain you 1452 have verified, you can expect that to be reasonably "secure" against 1453 algorithmic attacks, at least in the year 2015.]] 1455 6.2.1. Incorrect DHE Share 1457 If the client has not provided an appropriate ClientKeyShare (e.g. it 1458 includes only DHE or ECDHE groups unacceptable or unsupported by the 1459 server), the server corrects the mismatch with a HelloRetryRequest 1460 and the client will need to restart the handshake with an appropriate 1461 ClientKeyShare, as shown in Figure 2: 1463 Client Server 1465 ClientHello 1466 + ClientKeyShare --------> 1467 <-------- HelloRetryRequest 1469 ClientHello 1470 + ClientKeyShare --------> 1471 ServerHello 1472 ServerKeyShare 1473 {EncryptedExtensions*} 1474 {ServerConfiguration*} 1475 {Certificate*} 1476 {CertificateRequest*} 1477 {CertificateVerify*} 1478 <-------- {Finished} 1479 {Certificate*} 1480 {CertificateVerify*} 1481 {Finished} --------> 1482 [Application Data] <-------> [Application Data] 1484 Figure 2: Message flow for a full handshake with mismatched 1485 parameters 1487 [[OPEN ISSUE: Should we restart the handshake hash? 1488 https://github.com/tlswg/tls13-spec/issues/104.]] [[OPEN ISSUE: We 1489 need to make sure that this flow doesn't introduce downgrade issues. 1490 Potential options include continuing the handshake hashes (as long as 1491 clients don't change their opinion of the server's capabilities with 1492 aborted handshakes) and requiring the client to send the same 1493 ClientHello (as is currently done) and then checking you get the same 1494 negotiated parameters.]] 1496 If no common cryptographic parameters can be negotiated, the server 1497 will send a fatal alert. 1499 TLS also allows several optimized variants of the basic handshake, as 1500 described below. 1502 6.2.2. Cached Server Configuration 1504 During an initial handshake, the server can provide a 1505 ServerConfiguration message containing a long-term (EC)DH share. On 1506 future connections, the client can indicate to the server that it 1507 knows the server's configuration and if that configuration is valid 1508 the server can omit both the Certificate or CertificateVerify message 1509 (provided that a new configuration is not supplied in this 1510 handshake). 1512 When a known configuration is used, the server's long-term DHE key is 1513 combined with the client's ClientKeyShare to produce SS. ES is 1514 computed as above. This optimization allows the server to amortize 1515 the transmission of these messages and the server's signature over 1516 multiple handshakes, thus reducing the server's computational cost 1517 for cipher suites where signatures are slower than key agreement, 1518 principally RSA signatures paired with ECDHE. 1520 6.2.3. Zero-RTT Exchange 1522 When a cached ServerConfiguration is used, the client can also send 1523 application data as well as its Certificate and CertificateVerify (if 1524 client authentication is requested) on its first flight, thus 1525 reducing handshake latency, as shown below. 1527 Client Server 1529 ClientHello 1530 + ClientKeyShare 1531 (Certificate*) 1532 (CertificateVerify*) 1533 (Application Data) --------> 1534 ServerHello 1535 ServerKeyShare 1536 <-------- {Finished} 1537 {Finished} --------> 1539 [Application Data] <-------> [Application Data] 1541 () Indicates messages protected using keys derived from the static secret. 1543 Figure 3: Message flow for a zero round trip handshake 1545 Note: because sequence numbers continue to increment between the 1546 initial (early) application data and the application data sent after 1547 the handshake has complete, an attacker cannot remove early 1548 application data messages. 1550 IMPORTANT NOTE: The security properties for 0-RTT data (regardless of 1551 the cipher suite) are weaker than those for other kinds of TLS data. 1552 Specifically. 1554 1. This data is not forward secure, because it is encrypted solely 1555 with the server's semi-static (EC)DH share. 1557 2. There are no guarantees of non-replay between connections. 1558 Unless the server takes special measures outside those provided 1559 by TLS (See Section 6.3.1.5.5.1), the server has no guarantee 1560 that the same 0-RTT data was not transmitted on multiple 0-RTT 1561 connections. This is especially relevant if the data is 1562 authenticated either with TLS client authentication or inside the 1563 application layer protocol. However, 0-RTT data cannot be 1564 duplicated within a connection (i.e., the server will not process 1565 the same data twice for the same connection) and also cannot be 1566 sent as if it were ordinary TLS data. 1568 3. If the server key is compromised, and client authentication is 1569 used, then the attacker can impersonate the client to the server 1570 (as it knows the traffic key). 1572 6.2.4. Resumption and PSK 1574 Finally, TLS provides a pre-shared key (PSK) mode which allows a 1575 client and server who share an existing secret (e.g., a key 1576 established out of band) to establish a connection authenticated by 1577 that key. PSKs can also be established in a previous session and 1578 then reused ("session resumption"). Once a handshake has completed, 1579 the server can send the client a PSK identity which corresponds to a 1580 key derived from the initial handshake (See Section 6.3.11). The 1581 client can then use that PSK identity in future handshakes to 1582 negotiate use of the PSK; if the server accepts it, then the security 1583 context of the original connection is tied to the new connection. In 1584 TLS 1.2 and below, this functionality was provided by "session 1585 resumption" and "session tickets" [RFC5077]. Both mechanisms are 1586 obsoleted in TLS 1.3. 1588 PSK ciphersuites can either use PSK in combination with an (EC)DHE 1589 exchange in order to provide forward secrecy in combination with 1590 shared keys, or can use PSKs alone, at the cost of losing forward 1591 secrecy. 1593 Figure 4 shows a pair of handshakes in which the first establishes a 1594 PSK and the second uses it: 1596 Client Server 1598 Initial Handshake: 1600 ClientHello 1601 + ClientKeyShare --------> 1602 ServerHello 1603 ServerKeyShare 1604 {EncryptedExtensions} 1605 {ServerConfiguration*} 1606 {Certificate*} 1607 {CertificateRequest*} 1608 {CertificateVerify*} 1609 <-------- {Finished} 1610 {Certificate*} 1611 {CertificateVerify*} 1612 {Finished} --------> 1613 <-------- [NewSessionTicket] 1614 [Application Data] <-------> [Application Data] 1616 Subsequent Handshake: 1617 ClientHello 1618 + ClientKeyShare, 1619 PreSharedKeyExtension --------> 1620 ServerHello 1621 +PreSharedKeyExtension 1622 <-------- {Finished} 1623 {Certificate*} 1624 {Finished} --------> 1625 [Application Data] <-------> [Application Data] 1627 Figure 4: Message flow for resumption and PSK 1629 Note that the client supplies a ClientKeyShare to the server as well, 1630 which allows the server to decline resumption and fall back to a full 1631 handshake. However, because the server is authenticating via a PSK, 1632 it does not send a Certificate or a CertificateVerify. PSK-based 1633 resumption cannot be used to provide a new ServerConfiguration. 1635 The contents and significance of each message will be presented in 1636 detail in the following sections. 1638 6.3. Handshake Protocol 1640 The TLS Handshake Protocol is one of the defined higher-level clients 1641 of the TLS Record Protocol. This protocol is used to negotiate the 1642 secure attributes of a session. Handshake messages are supplied to 1643 the TLS record layer, where they are encapsulated within one or more 1644 TLSPlaintext or TLSCiphertext structures, which are processed and 1645 transmitted as specified by the current active session state. 1647 enum { 1648 reserved(0), client_hello(1), server_hello(2), 1649 session_ticket(4), hello_retry_request(6), 1650 server_key_share(7), certificate(11), reserved(12), 1651 certificate_request(13), server_configuration(14), 1652 certificate_verify(15), reserved(16), finished(20), (255) 1653 } HandshakeType; 1655 struct { 1656 HandshakeType msg_type; /* handshake type */ 1657 uint24 length; /* bytes in message */ 1658 select (HandshakeType) { 1659 case client_hello: ClientHello; 1660 case server_hello: ServerHello; 1661 case hello_retry_request: HelloRetryRequest; 1662 case server_key_share: ServerKeyShare; 1663 case server_configuration:ServerConfiguration; 1664 case certificate: Certificate; 1665 case certificate_request: CertificateRequest; 1666 case certificate_verify: CertificateVerify; 1667 case finished: Finished; 1668 case session_ticket: NewSessionTicket; 1669 } body; 1670 } Handshake; 1672 The handshake protocol messages are presented below in the order they 1673 MUST be sent; sending handshake messages in an unexpected order 1674 results in a fatal error. Unneeded handshake messages can be 1675 omitted, however. 1677 New handshake message types are assigned by IANA as described in 1678 Section 11. 1680 6.3.1. Hello Messages 1682 The hello phase messages are used to exchange security enhancement 1683 capabilities between the client and server. When a new session 1684 begins, the record layer's connection state AEAD algorithm is 1685 initialized to NULL_NULL. 1687 6.3.1.1. Client Hello 1689 When this message will be sent: 1691 When a client first connects to a server, it is required to send 1692 the ClientHello as its first message. The client will also send a 1693 ClientHello when the server has responded to its ClientHello with 1694 a ServerHello that selects cryptographic parameters that don't 1695 match the client's ClientKeyShare. In that case, the client MUST 1696 send the same ClientHello (without modification) except including 1697 a new ClientKeyShare. [[OPEN ISSUE: New random values? See: 1698 https://github.com/tlswg/tls13-spec/issues/185]] If a server 1699 receives a ClientHello at any other time, it MUST send a fatal 1700 "no_renegotiation" alert. 1702 Structure of this message: 1704 The ClientHello message includes a random structure, which is used 1705 later in the protocol. 1707 struct { 1708 opaque random_bytes[32]; 1709 } Random; 1711 random_bytes 1712 32 bytes generated by a secure random number generator. 1714 Note: Versions of TLS prior to TLS 1.3 used the top 32 bits of the 1715 Random value to encode the time since the UNIX epoch. 1717 The cipher suite list, passed from the client to the server in the 1718 ClientHello message, contains the combinations of cryptographic 1719 algorithms supported by the client in order of the client's 1720 preference (favorite choice first). Each cipher suite defines a key 1721 exchange algorithm, a record protection algorithm (including secret 1722 key length) and a hash to be used with HKDF. The server will select 1723 a cipher suite or, if no acceptable choices are presented, return a 1724 "handshake_failure" alert and close the connection. If the list 1725 contains cipher suites the server does not recognize, support, or 1726 wish to use, the server MUST ignore those cipher suites, and process 1727 the remaining ones as usual. 1729 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1731 enum { null(0), (255) } CompressionMethod; 1733 struct { 1734 ProtocolVersion client_version = { 3, 4 }; /* TLS v1.3 */ 1735 Random random; 1736 SessionID session_id; 1737 CipherSuite cipher_suites<2..2^16-2>; 1738 CompressionMethod compression_methods<1..2^8-1>; 1739 select (extensions_present) { 1740 case false: 1741 struct {}; 1742 case true: 1743 Extension extensions<0..2^16-1>; 1744 }; 1745 } ClientHello; 1747 TLS allows extensions to follow the compression_methods field in an 1748 extensions block. The presence of extensions can be detected by 1749 determining whether there are bytes following the compression_methods 1750 at the end of the ClientHello. Note that this method of detecting 1751 optional data differs from the normal TLS method of having a 1752 variable-length field, but it is used for compatibility with TLS 1753 before extensions were defined. 1755 client_version 1756 The version of the TLS protocol by which the client wishes to 1757 communicate during this session. This SHOULD be the latest 1758 (highest valued) version supported by the client. For this 1759 version of the specification, the version will be 3.4. (See 1760 Appendix D for details about backward compatibility.) 1762 random 1763 A client-generated random structure. 1765 session_id 1766 Versions of TLS prior to TLS 1.3 supported a session resumption 1767 feature which has been merged with Pre-Shared Keys in this version 1768 (see Section 6.2.4). This field MUST be ignored by a server 1769 negotiating TLS 1.3 and should be set as a zero length vector 1770 (i.e., a single zero byte length field) by clients which do not 1771 have a cached session_id set by a pre-TLS 1.3 server. 1773 cipher_suites 1774 This is a list of the cryptographic options supported by the 1775 client, with the client's first preference first. Values are 1776 defined in Appendix A.4. 1778 compression_methods 1779 Versions of TLS before 1.3 supported compression and the list of 1780 compression methods was supplied in this field. For any TLS 1.3 1781 ClientHello, this field MUST contain only the "null" compression 1782 method with the code point of 0. If a TLS 1.3 ClientHello is 1783 received with any other value in this field, the server MUST 1784 generate a fatal "illegal_parameter" alert. Note that TLS 1.3 1785 servers may receive TLS 1.2 or prior ClientHellos which contain 1786 other compression methods and MUST follow the procedures for the 1787 appropriate prior version of TLS. 1789 extensions 1790 Clients MAY request extended functionality from servers by sending 1791 data in the extensions field. The actual "Extension" format is 1792 defined in Section 6.3.1.4. 1794 In the event that a client requests additional functionality using 1795 extensions, and this functionality is not supplied by the server, the 1796 client MAY abort the handshake. A server MUST accept ClientHello 1797 messages both with and without the extensions field, and (as for all 1798 other messages) it MUST check that the amount of data in the message 1799 precisely matches one of these formats; if not, then it MUST send a 1800 fatal "decode_error" alert. 1802 After sending the ClientHello message, the client waits for a 1803 ServerHello or HelloRetryRequest message. 1805 6.3.1.2. Server Hello 1807 When this message will be sent: 1809 The server will send this message in response to a ClientHello 1810 message when it was able to find an acceptable set of algorithms 1811 and the client's ClientKeyShare extension was acceptable. If the 1812 client proposed groups are not acceptable by the server, it will 1813 respond with an "insufficient_security" fatal alert. 1815 Structure of this message: 1817 struct { 1818 ProtocolVersion server_version; 1819 Random random; 1820 uint8 session_id_len; // Must be 0. 1821 CipherSuite cipher_suite; 1822 select (extensions_present) { 1823 case false: 1824 struct {}; 1825 case true: 1826 Extension extensions<0..2^16-1>; 1827 }; 1828 } ServerHello; 1830 The presence of extensions can be detected by determining whether 1831 there are bytes following the cipher_suite field at the end of the 1832 ServerHello. 1834 server_version 1835 This field will contain the lower of that suggested by the client 1836 in the ClientHello and the highest supported by the server. For 1837 this version of the specification, the version is 3.4. (See 1838 Appendix D for details about backward compatibility.) 1840 random 1841 This structure is generated by the server and MUST be generated 1842 independently of the ClientHello.random. 1844 session_id_len 1845 A single 0 value for backward compatible formatting. [[OPEN 1846 ISSUE: Should we remove?]] 1848 cipher_suite 1849 The single cipher suite selected by the server from the list in 1850 ClientHello.cipher_suites. For resumed sessions, this field is 1851 the value from the state of the session being resumed. [[TODO: 1852 interaction with PSK.]] 1854 extensions 1855 A list of extensions. Note that only extensions offered by the 1856 client can appear in the server's list. In TLS 1.3 as opposed to 1857 previous versions of TLS, the server's extensions are split 1858 between the ServerHello and the EncryptedExtensions Section 6.3.3 1859 message. The ServerHello MUST only include extensions which are 1860 required to establish the cryptographic context. 1862 6.3.1.3. Hello Retry Request 1864 When this message will be sent: 1866 The server will send this message in response to a ClientHello 1867 message when it was able to find an acceptable set of algorithms 1868 and groups that are mutually supported, but the client's 1869 ClientKeyShare did not contain an acceptable offer. If it cannot 1870 find such a match, it will respond with a "handshake_failure" 1871 alert. 1873 Structure of this message: 1875 struct { 1876 ProtocolVersion server_version; 1877 CipherSuite cipher_suite; 1878 NamedGroup selected_group; 1879 Extension extensions<0..2^16-1>; 1880 } HelloRetryRequest; 1882 [[OPEN ISSUE: Merge in DTLS Cookies?]] 1884 selected_group 1885 The group which the client MUST use for its new ClientHello. 1887 The "server_version", "cipher_suite" and "extensions" fields have the 1888 same meanings as their corresponding values in the ServerHello. The 1889 server SHOULD send only the extensions necessary for the client to 1890 generate a correct ClientHello pair. 1892 Upon receipt of a HelloRetryRequest, the client MUST first verify 1893 that the "selected_group" field does not identify a group which was 1894 not in the original ClientHello. If it was present, then the client 1895 MUST abort the handshake with a fatal "handshake_failure" alert. 1896 Clients SHOULD also abort with "handshake_failure" in response to any 1897 second HelloRetryRequest which was sent in the same connection (i.e., 1898 where the ClientHello was itself in response to a HelloRetryRequest). 1900 Otherwise, the client MUST send a ClientHello with a new 1901 ClientKeyShare extension to the server. The ClientKeyShare MUST 1902 append a new ClientKeyShareOffer which is consistent with the 1903 "selected_group" field to the groups in the original ClientKeyShare. 1905 Upon re-sending the ClientHello and receiving the server's 1906 ServerHello/ServerKeyShare, the client MUST verify that the selected 1907 CipherSuite and NamedGroup match that supplied in the 1908 HelloRetryRequest. 1910 6.3.1.4. Hello Extensions 1912 The extension format is: 1914 struct { 1915 ExtensionType extension_type; 1916 opaque extension_data<0..2^16-1>; 1917 } Extension; 1919 enum { 1920 signature_algorithms(13), 1921 early_data(TBD), 1922 supported_groups(TBD), 1923 known_configuration(TBD), 1924 pre_shared_key(TBD) 1925 client_key_shares(TBD) 1926 (65535) 1927 } ExtensionType; 1929 Here: 1931 - "extension_type" identifies the particular extension type. 1933 - "extension_data" contains information specific to the particular 1934 extension type. 1936 The initial set of extensions is defined in [RFC6066]. The list of 1937 extension types is maintained by IANA as described in Section 11. 1939 An extension type MUST NOT appear in the ServerHello or 1940 HelloRetryRequest unless the same extension type appeared in the 1941 corresponding ClientHello. If a client receives an extension type in 1942 ServerHello or HelloRetryRequest that it did not request in the 1943 associated ClientHello, it MUST abort the handshake with an 1944 "unsupported_extension" fatal alert. 1946 Nonetheless, "server-oriented" extensions may be provided in the 1947 future within this framework. Such an extension (say, of type x) 1948 would require the client to first send an extension of type x in a 1949 ClientHello with empty extension_data to indicate that it supports 1950 the extension type. In this case, the client is offering the 1951 capability to understand the extension type, and the server is taking 1952 the client up on its offer. 1954 When multiple extensions of different types are present in the 1955 ClientHello or ServerHello messages, the extensions MAY appear in any 1956 order. There MUST NOT be more than one extension of the same type. 1958 Finally, note that extensions can be sent both when starting a new 1959 session and when requesting session resumption or 0-RTT mode. 1960 Indeed, a client that requests session resumption does not in general 1961 know whether the server will accept this request, and therefore it 1962 SHOULD send the same extensions as it would send if it were not 1963 attempting resumption. 1965 In general, the specification of each extension type needs to 1966 describe the effect of the extension both during full handshake and 1967 session resumption. Most current TLS extensions are relevant only 1968 when a session is initiated: when an older session is resumed, the 1969 server does not process these extensions in ClientHello, and does not 1970 include them in ServerHello. However, some extensions may specify 1971 different behavior during session resumption. [[TODO: update this 1972 and the previous paragraph to cover PSK-based resumption.]] 1974 There are subtle (and not so subtle) interactions that may occur in 1975 this protocol between new features and existing features which may 1976 result in a significant reduction in overall security. The following 1977 considerations should be taken into account when designing new 1978 extensions: 1980 - Some cases where a server does not agree to an extension are error 1981 conditions, and some are simply refusals to support particular 1982 features. In general, error alerts should be used for the former, 1983 and a field in the server extension response for the latter. 1985 - Extensions should, as far as possible, be designed to prevent any 1986 attack that forces use (or non-use) of a particular feature by 1987 manipulation of handshake messages. This principle should be 1988 followed regardless of whether the feature is believed to cause a 1989 security problem. Often the fact that the extension fields are 1990 included in the inputs to the Finished message hashes will be 1991 sufficient, but extreme care is needed when the extension changes 1992 the meaning of messages sent in the handshake phase. Designers 1993 and implementors should be aware of the fact that until the 1994 handshake has been authenticated, active attackers can modify 1995 messages and insert, remove, or replace extensions. 1997 - It would be technically possible to use extensions to change major 1998 aspects of the design of TLS; for example the design of cipher 1999 suite negotiation. This is not recommended; it would be more 2000 appropriate to define a new version of TLS -- particularly since 2001 the TLS handshake algorithms have specific protection against 2002 version rollback attacks based on the version number, and the 2003 possibility of version rollback should be a significant 2004 consideration in any major design change. 2006 6.3.1.4.1. Signature Algorithms 2008 The client uses the "signature_algorithms" extension to indicate to 2009 the server which signature/hash algorithm pairs may be used in 2010 digital signatures. The "extension_data" field of this extension 2011 contains a "supported_signature_algorithms" value. 2013 enum { 2014 none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5), 2015 sha512(6), (255) 2016 } HashAlgorithm; 2018 enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) } 2019 SignatureAlgorithm; 2021 struct { 2022 HashAlgorithm hash; 2023 SignatureAlgorithm signature; 2024 } SignatureAndHashAlgorithm; 2026 SignatureAndHashAlgorithm 2027 supported_signature_algorithms<2..2^16-2>; 2029 Each SignatureAndHashAlgorithm value lists a single hash/signature 2030 pair that the client is willing to verify. The values are indicated 2031 in descending order of preference. 2033 Note: Because not all signature algorithms and hash algorithms may be 2034 accepted by an implementation (e.g., DSA with SHA-1, but not SHA- 2035 256), algorithms here are listed in pairs. 2037 hash 2038 This field indicates the hash algorithm which may be used. The 2039 values indicate support for unhashed data, MD5 [RFC1321], SHA-1, 2040 SHA-224, SHA-256, SHA-384, and SHA-512 [SHS], respectively. The 2041 "none" value is provided for future extensibility, in case of a 2042 signature algorithm which does not require hashing before signing. 2044 signature 2045 This field indicates the signature algorithm that may be used. 2046 The values indicate anonymous signatures, RSASSA-PKCS1-v1_5 2047 [RFC3447] and DSA [DSS], and ECDSA [ECDSA], respectively. The 2048 "anonymous" value is meaningless in this context but used in 2049 Section 6.3.2. It MUST NOT appear in this extension. 2051 The semantics of this extension are somewhat complicated because the 2052 cipher suite indicates permissible signature algorithms but not hash 2053 algorithms. Section 6.3.4 and Section 6.3.2 describe the appropriate 2054 rules. 2056 If the client supports only the default hash and signature algorithms 2057 (listed in this section), it MAY omit the signature_algorithms 2058 extension. If the client does not support the default algorithms, or 2059 supports other hash and signature algorithms (and it is willing to 2060 use them for verifying messages sent by the server, i.e., server 2061 certificates and server key share), it MUST send the 2062 signature_algorithms extension, listing the algorithms it is willing 2063 to accept. 2065 If the client does not send the signature_algorithms extension, the 2066 server MUST do the following: 2068 - If the negotiated key exchange algorithm is one of (DHE_RSA, 2069 ECDHE_RSA), behave as if client had sent the value {sha1,rsa}. 2071 - If the negotiated key exchange algorithm is DHE_DSS, behave as if 2072 the client had sent the value {sha1,dsa}. 2074 - If the negotiated key exchange algorithm is ECDHE_ECDSA, behave as 2075 if the client had sent value {sha1,ecdsa}. 2077 Note: This extension is not meaningful for TLS versions prior to 1.2. 2078 Clients MUST NOT offer it if they are offering prior versions. 2079 However, even if clients do offer it, the rules specified in 2080 [RFC6066] require servers to ignore extensions they do not 2081 understand. 2083 Servers MUST NOT send this extension. TLS servers MUST support 2084 receiving this extension. 2086 6.3.1.4.2. Negotiated Groups 2088 When sent by the client, the "supported_groups" extension indicates 2089 the named groups which the client supports, ordered from most 2090 preferred to least preferred. 2092 Note: In versions of TLS prior to TLS 1.3, this extension was named 2093 "elliptic curves" and only contained elliptic curve groups. See 2094 [RFC4492] and [I-D.ietf-tls-negotiated-ff-dhe]. 2096 The "extension_data" field of this extension SHALL contain a 2097 "NamedGroupList" value: 2099 enum { 2100 // Elliptic Curve Groups. 2101 sect163k1 (1), sect163r1 (2), sect163r2 (3), 2102 sect193r1 (4), sect193r2 (5), sect233k1 (6), 2103 sect233r1 (7), sect239k1 (8), sect283k1 (9), 2104 sect283r1 (10), sect409k1 (11), sect409r1 (12), 2105 sect571k1 (13), sect571r1 (14), secp160k1 (15), 2106 secp160r1 (16), secp160r2 (17), secp192k1 (18), 2107 secp192r1 (19), secp224k1 (20), secp224r1 (21), 2108 secp256k1 (22), secp256r1 (23), secp384r1 (24), 2109 secp521r1 (25), 2111 // Finite Field Groups. 2112 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 2113 ffdhe6144 (259), ffdhe8192 (260), 2114 ffdhe_private_use (0x01FC..0x01FF), 2116 // Reserved Code Points. 2117 reserved (0xFE00..0xFEFF), 2118 reserved(0xFF01), 2119 reserved(0xFF02), 2120 (0xFFFF) 2121 } NamedGroup; 2123 struct { 2124 NamedGroup named_group_list<1..2^16-1>; 2125 } NamedGroupList; 2127 sect163k1, etc 2128 Indicates support of the corresponding named curve The named 2129 curves defined here are those specified in SEC 2 [13]. Note that 2130 many of these curves are also recommended in ANSI X9.62 [X962] and 2131 FIPS 186-2 [DSS]. Values 0xFE00 through 0xFEFF are reserved for 2132 private use. Values 0xFF01 and 0xFF02 were used in previous 2133 versions of TLS but MUST NOT be offered by TLS 1.3 2134 implementations. [[OPEN ISSUE: Triage curve list.]] 2136 ffdhe2432, etc 2137 Indicates support of the corresponding finite field group, defined 2138 in [I-D.ietf-tls-negotiated-ff-dhe] 2140 Items in named_curve_list are ordered according to the client's 2141 preferences (favorite choice first). 2143 As an example, a client that only supports secp192r1 (aka NIST P-192; 2144 value 19 = 0x0013) and secp224r1 (aka NIST P-224; value 21 = 0x0015) 2145 and prefers to use secp192r1 would include a TLS extension consisting 2146 of the following octets. Note that the first two octets indicate the 2147 extension type (Supported Group Extension): 2149 00 0A 00 06 00 04 00 13 00 15 2151 The client MUST supply a "named_groups" extension containing at least 2152 one group for each key exchange algorithm (currently DHE and ECDHE) 2153 for which it offers a cipher suite. If the client does not supply a 2154 "named_groups" extension with a compatible group, the server MUST NOT 2155 negotiate a cipher suite of the relevant type. For instance, if a 2156 client supplies only ECDHE groups, the server MUST NOT negotiate 2157 finite field Diffie-Hellman. If no acceptable group can be selected 2158 across all cipher suites, then the server MUST generate a fatal 2159 "handshake_failure" alert. 2161 NOTE: A server participating in an ECDHE-ECDSA key exchange may use 2162 different curves for (i) the ECDSA key in its certificate, and (ii) 2163 the ephemeral ECDH key in the ServerKeyExchange message. The server 2164 must consider the supported groups in both cases. 2166 [[TODO: IANA Considerations.]] 2168 6.3.1.5. Client Key Share 2170 The client_key_share extension MUST be provided by the client if it 2171 offers any cipher suites that involve non-PSK (currently DHE or 2172 ECDHE) key exchange. It contains the client's cryptographic 2173 parameters for zero or more key establishment methods. [[OPEN ISSUE: 2174 Would it be better to omit it if it's empty?. 2175 https://github.com/tlswg/tls13-spec/issues/190]] 2177 Meaning of this message: 2179 struct { 2180 NamedGroup group; 2181 opaque key_exchange<1..2^16-1>; 2182 } ClientKeyShareOffer; 2184 group 2185 The named group for the key share offer. This identifies the 2186 specific key exchange method that the ClientKeyShareOffer 2187 describes. Finite Field Diffie-Hellman [DH] parameters are 2188 described in Section 6.3.1.5.1; Elliptic Curve Diffie-Hellman 2189 parameters are described in Section 6.3.1.5.2. 2191 key_exchange 2192 Key exchange information. The contents of this field are 2193 determined by the value of NamedGroup entry and its corresponding 2194 definition. 2196 struct { 2197 ClientKeyShareOffer offers<0..2^16-1>; 2198 } ClientKeyShare; 2200 offers 2201 A list of ClientKeyShareOffer values in descending order of client 2202 preference. 2204 Clients may offer an arbitrary number of ClientKeyShareOffer values, 2205 each representing a single set of key agreement parameters; for 2206 instance a client might offer shares for several elliptic curves or 2207 multiple integer DH groups. The shares for each ClientKeyShareOffer 2208 MUST by generated independently. Clients MUST NOT offer multiple 2209 ClientKeyShareOffers for the same parameters. It is explicitly 2210 permitted to send an empty client_key_share extension as this is used 2211 to elicit the server's parameters if the client has no useful 2212 information. [TODO: Recommendation about what the client offers. 2213 Presumably which integer DH groups and which curves.] 2215 6.3.1.5.1. Diffie-Hellman Parameters 2217 Diffie-Hellman [DH] parameters for both clients and servers are 2218 encoded in the opaque key_exchange field of the ClientKeyShareOffer 2219 or ServerKeyShare structures. The opaque value contains the Diffie- 2220 Hellman public value (dh_Y = g^X mod p), encoded as a big-endian 2221 integer. 2223 opaque dh_Y<1..2^16-1>; 2225 6.3.1.5.2. ECDHE Parameters 2227 ECDHE parameters for both clients and servers are encoded in the 2228 opaque key_exchange field of the ClientKeyShareOffer or 2229 ServerKeyShare structures. The opaque value conveys the Elliptic 2230 Curve Diffie-Hellman public value (ecdh_Y) represented as a byte 2231 string ECPoint.point. 2233 opaque point <1..2^8-1>; 2235 point 2236 This is the byte string representation of an elliptic curve point 2237 following the conversion routine in Section 4.3.6 of ANSI X9.62 2238 [X962]. 2240 Although X9.62 supports multiple point formats, any given curve MUST 2241 specify only a single point format. All curves currently specified 2242 in this document MUST only be used with the uncompressed point 2243 format. 2245 Note: Versions of TLS prior to 1.3 permitted point negotiation; TLS 2246 1.3 removes this feature in favor of a single point format for each 2247 curve. 2249 [[OPEN ISSUE: We will need to adjust the compressed/uncompressed 2250 point issue if we have new curves that don't need point compression. 2251 This depends on the CFRG's recommendations. The expectation is that 2252 future curves will come with defined point formats and that existing 2253 curves conform to X9.62.]] 2255 6.3.1.5.3. Known Configuration Extension 2257 The known_configuration extension allows the client to indicate that 2258 it wishes to reuse the server's known configuration and semi-static 2259 (EC)DHE key (see Section 6.3.6 for how to establish these 2260 configurations. This extension allows the omission of the server 2261 certificate and signature, with three potential benefits: 2263 - Shortening the handshake because the certificate may be large. 2265 - Reducing cryptographic burden on the server if the server has an 2266 RSA certificate, as well as on the client if the server has an 2267 ECDSA certificate. 2269 - Allowing the client and server to do a 0-RTT exchange (See 2270 Section 6.2.3) 2272 The extension is defined as: 2274 struct { 2275 select (Role) { 2276 case client: 2277 opaque identifier<0..2^16-1>; 2279 case server: 2280 struct {}; 2281 } 2282 } KnownConfigurationExtension 2284 identifier 2285 An opaque label for the configuration in question. 2287 A client which wishes to reuse a known configuration MAY supply a 2288 single KnownConfigurationExtension value which indicates the known 2289 configuration it desires to use. It is a fatal error to supply more 2290 than one extension. A server which wishes to use the key replies 2291 with an empty extension (i.e., with a length field of 0) in its 2292 ServerHello. 2294 When the client and server mutually agree upon a known configuration 2295 via this mechanism, then the Static Secret (SS) is computed based on 2296 the server's (EC)DHE key from the identified configuration and the 2297 client's key found in the ClientKeyShare. If no key from an 2298 acceptable group is in the ClientKeyShare, the server MUST ignore the 2299 known_configuration extension. When this mechanism is used, the 2300 server MUST NOT send a Certificate/CertificateVerify message unless 2301 the ServerConfiguration message is also sent. 2303 When the known_configuration data extension is in use, the handshake 2304 hash is extended to include the server's configuration data and 2305 certificate (see Section 7.2.1) so as to tightly bind them together. 2307 6.3.1.5.4. Pre-Shared Key Extension 2309 The pre_shared_key extension is used to indicate the identity of the 2310 pre-shared key to be used with a given handshake in association with 2311 a PSK or (EC)DHE-PSK cipher suite (see [RFC4279] for background). 2313 opaque psk_identity<0..2^16-1>; 2315 struct { 2316 select (Role) { 2317 case client: 2318 psk_identity identities<0..2^16-1>; 2320 case server: 2321 psk_identity identity; 2323 } PreSharedKeyExtension; 2325 identifier 2326 An opaque label for the pre-shared key. 2328 When the client offers a PSK cipher suite, it MUST also supply a 2329 PreSharedKeyExtension to indicate the PSK(s) to be used. If no such 2330 extension is present, the server MUST NOT negotiate a PSK cipher 2331 suite. If no suitable identity is present, the server MUST NOT 2332 negotiate a PSK cipher suite. 2334 If the server selects a PSK cipher suite, it MUST send a 2335 PreSharedKeyExtension with the identity that it selected. The client 2336 MUST verify that the server has selected one of the identities that 2337 the client supplied. If any other identity is returned, the client 2338 MUST generate a fatal "handshake_failure" alert. 2340 6.3.1.5.5. Early Data Indication 2342 In cases where TLS clients have previously interacted with the server 2343 and the server has supplied a known configuration, the client can 2344 send application data and its Certificate/CertificateVerify messages 2345 (if client authentication is required). If the client opts to do so, 2346 it MUST supply an Early Data Indication extension. This technique 2347 MUST only be used along with the "known_configuration" extension. 2349 enum { early_handshake(1), early_data(2), 2350 early_handshake_and_data(3), (255) } EarlyDataType; 2352 struct { 2353 select (Role) { 2354 case client: 2355 opaque context<0..255>; 2356 EarlyDataType type; 2357 case server: 2358 struct {}; 2359 } 2360 } EarlyDataIndication; 2362 context 2363 An optional context value that can be used for anti-replay (see 2364 below). 2366 type 2367 The type of early data that is being sent. "early_handshake" means 2368 that only handshake data is being sent. "early_data" means that 2369 only data is being sent. "early_handshake_and_data" means that 2370 both are being sent. 2372 If TLS client authentication is being used, then either 2373 "early_handshake" or "early_handshake_and_data" MUST be indicated in 2374 order to send the client authentication data on the first flight. In 2375 either case, the client Certificate and CertificateVerify (assuming 2376 that the Certificate is non-empty) MUST be sent on the first flight A 2377 server which receives an initial flight with only "early_data" and 2378 which expects certificate-based client authentication MUST not accept 2379 early data. 2381 In order to allow servers to readily distinguish between messages 2382 sent in the first flight and in the second flight (in cases where the 2383 server does not accept the EarlyDataIndication extension), the client 2384 MUST send the handshake messages as content type "early_handshake". 2385 A server which does not accept the extension proceeds by skipping all 2386 records after the ClientHello and until the next client message of 2387 type "handshake". [[OPEN ISSUE: This relies on content types not 2388 being encrypted. If we had content types that were encrypted, this 2389 would basically require trial decryption.]] 2391 A server which receives an EarlyDataIndication extension can behave 2392 in one of two ways: 2394 - Ignore the extension and return no response. This indicates that 2395 the server has ignored any early data and an ordinary 1-RTT 2396 handshake is required. 2398 - Return an empty extension, indicating that it intends to process 2399 the early data. It is not possible for the server to accept only 2400 a subset of the early data messages. 2402 The server MUST first validate that the client's 2403 "known_configuration" extension is valid and that the client has 2404 suppled a valid key share in the "client_key_shares" extension. If 2405 not, it MUST ignore the extension and discard the early handshake 2406 data and early data. 2408 [[TODO: How does the client behave if the indication is rejected.]] 2410 [[OPEN ISSUE: This just specifies the signaling for 0-RTT but not the 2411 the 0-RTT cryptographic transforms, including: 2413 - What is in the handshake hash (including potentially some 2414 speculative data from the server.) 2416 - What is signed in the client's CertificateVerify 2418 - Whether we really want the Finished to not include the server's 2419 data at all. 2421 What's here now needs a lot of cleanup before it is clear and 2422 correct.]] 2424 [[TODO: We should really allow early_data to be used with PSKs. In 2425 order to make this work, we need to either: 2427 (a) explicitly signal the entire cryptographic parameter set (b) tie 2428 it to the PSK identifier (as is presently done in the 2429 known_configuration extension). 2431 These two should match. ]] 2433 6.3.1.5.5.1. Replay Properties 2435 As noted in Section 6.2.3, TLS does not provide any inter-connection 2436 mechanism for replay protection for data sent by the client in the 2437 first flight. As a special case, implementations where the server 2438 configuration, is delivered out of band (as has been proposed for 2439 DTLS-SRTP [RFC5763]), MAY use a unique server configuration 2440 identifier for each connection, thus preventing replay. 2441 Implementations are responsible for ensuring uniqueness of the 2442 identifier in this case. 2444 6.3.2. Server Key Share 2446 When this message will be sent: 2448 This message will be sent immediately after the ServerHello 2449 message if the client has provided a ClientKeyShare extension 2450 which is compatible with the selected cipher suite and group 2451 parameters. 2453 Meaning of this message: 2455 This message conveys cryptographic information to allow the client 2456 to compute a shared secret secret: a Diffie-Hellman public key 2457 with which the client can complete a key exchange (with the result 2458 being the shared secret) or a public key for some other algorithm. 2460 Structure of this message: 2462 struct { 2463 NamedGroup group; 2464 opaque key_exchange<1..2^16-1>; 2465 } ServerKeyShare; 2467 group 2468 The named group for the key share offer. This identifies the 2469 selected key exchange method from the ClientKeyShare 2470 (Section 6.3.1.5), identifying which value from the 2471 ClientKeyShareOffer the server has accepted as is responding to. 2473 key_exchange 2474 Key exchange information. The contents of this field are 2475 determined by the value of NamedGroup entry and its corresponding 2476 definition. 2478 6.3.3. Encrypted Extensions 2480 When this message will be sent: 2482 If this message is sent, it MUST be sent immediately after the 2483 server's ServerKeyShare. This is the first message that is 2484 encrypted under keys derived from ES. 2486 Meaning of this message: 2488 The EncryptedExtensions message simply contains any extensions 2489 which should be protected, i.e., any which are not needed to 2490 establish the cryptographic context. The same extension types 2491 MUST NOT appear in both the ServerHello and EncryptedExtensions. 2492 If the same extension appears in both locations, the client MUST 2493 rely only on the value in the EncryptedExtensions block. [[OPEN 2494 ISSUE: Should we just produce a canonical list of what goes where 2495 and have it be an error to have it in the wrong place? That seems 2496 simpler. Perhaps have a whitelist of which extensions can be 2497 unencrypted and everything else MUST be encrypted.]] 2499 Structure of this message: 2501 struct { 2502 Extension extensions<0..2^16-1>; 2503 } EncryptedExtensions; 2505 extensions 2506 A list of extensions. 2508 6.3.4. Server Certificate 2510 When this message will be sent: 2512 The server MUST send a Certificate message whenever the agreed- 2513 upon key exchange method uses certificates for authentication 2514 (this includes all key exchange methods defined in this document 2515 except DH_anon and PSK), unless the KnownKeyExtension is used. 2516 This message will always immediately follow either the 2517 EncryptedExtensions message if one is sent or the ServerKeyShare 2518 message. 2520 Meaning of this message: 2522 This message conveys the server's certificate chain to the client. 2524 The certificate MUST be appropriate for the negotiated cipher 2525 suite's key exchange algorithm and any negotiated extensions. 2527 Structure of this message: 2529 opaque ASN1Cert<1..2^24-1>; 2531 struct { 2532 ASN1Cert certificate_list<0..2^24-1>; 2533 } Certificate; 2535 certificate_list 2536 This is a sequence (chain) of certificates. The sender's 2537 certificate MUST come first in the list. Each following 2538 certificate MUST directly certify the one preceding it. Because 2539 certificate validation requires that root keys be distributed 2540 independently, the self-signed certificate that specifies the root 2541 certificate authority MAY be omitted from the chain, under the 2542 assumption that the remote end must already possess it in order to 2543 validate it in any case. 2545 The same message type and structure will be used for the client's 2546 response to a certificate request message. Note that a client MAY 2547 send no certificates if it does not have an appropriate certificate 2548 to send in response to the server's authentication request. 2550 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 2551 vector because PKCS #6 [PKCS6] extended certificates are not used. 2552 Also, PKCS #7 defines a SET rather than a SEQUENCE, making the task 2553 of parsing the list more difficult. 2555 The following rules apply to the certificates sent by the server: 2557 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2558 negotiated otherwise (e.g., [RFC5081]). 2560 - The end entity certificate's public key (and associated 2561 restrictions) MUST be compatible with the selected key exchange 2562 algorithm. 2564 Key Exchange Alg. Certificate Key Type 2566 DHE_RSA RSA public key; the certificate MUST allow the 2567 ECDHE_RSA key to be used for signing (the 2568 digitalSignature bit MUST be set if the key 2569 usage extension is present) with the signature 2570 scheme and hash algorithm that will be employed 2571 in the server key exchange message. 2572 Note: ECDHE_RSA is defined in [RFC4492]. 2574 DHE_DSS DSA public key; the certificate MUST allow the 2575 key to be used for signing with the hash 2576 algorithm that will be employed in the server 2577 key exchange message. 2579 ECDHE_ECDSA ECDSA-capable public key; the certificate MUST 2580 allow the key to be used for signing with the 2581 hash algorithm that will be employed in the 2582 server key exchange message. The public key 2583 MUST use a curve and point format supported by 2584 the client, as described in [RFC4492]. 2586 - The "server_name" and "trusted_ca_keys" extensions [RFC6066] are 2587 used to guide certificate selection. As servers MAY require the 2588 presence of the server_name extension, clients SHOULD send this 2589 extension. 2591 If the client provided a "signature_algorithms" extension, then all 2592 certificates provided by the server MUST be signed by a hash/ 2593 signature algorithm pair that appears in that extension. Note that 2594 this implies that a certificate containing a key for one signature 2595 algorithm MAY be signed using a different signature algorithm (for 2596 instance, an RSA key signed with a DSA key). 2598 If the server has multiple certificates, it chooses one of them based 2599 on the above-mentioned criteria (in addition to other criteria, such 2600 as transport layer endpoint, local configuration and preferences, 2601 etc.). If the server has a single certificate, it SHOULD attempt to 2602 validate that it meets these criteria. 2604 Note that there are certificates that use algorithms and/or algorithm 2605 combinations that cannot be currently used with TLS. For example, a 2606 certificate with RSASSA-PSS signature key (id-RSASSA-PSS OID in 2607 SubjectPublicKeyInfo) cannot be used because TLS defines no 2608 corresponding signature algorithm. 2610 As cipher suites that specify new key exchange methods are specified 2611 for the TLS protocol, they will imply the certificate format and the 2612 required encoded keying information. 2614 6.3.5. Certificate Request 2616 When this message will be sent: 2618 A non-anonymous server can optionally request a certificate from 2619 the client, if appropriate for the selected cipher suite. This 2620 message, if sent, will immediately follow the server's Certificate 2621 message). 2623 Structure of this message: 2625 enum { 2626 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 2627 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 2628 fortezza_dms_RESERVED(20), (255) 2629 } ClientCertificateType; 2631 opaque DistinguishedName<1..2^16-1>; 2633 struct { 2634 ClientCertificateType certificate_types<1..2^8-1>; 2635 SignatureAndHashAlgorithm 2636 supported_signature_algorithms<2..2^16-2>; 2637 DistinguishedName certificate_authorities<0..2^16-1>; 2638 } CertificateRequest; 2640 certificate_types 2641 A list of the types of certificate types that the client may 2642 offer. 2644 rsa_sign a certificate containing an RSA key 2645 dss_sign a certificate containing a DSA key 2646 rsa_fixed_dh a certificate containing a static DH key. 2647 dss_fixed_dh a certificate containing a static DH key 2649 supported_signature_algorithms 2650 A list of the hash/signature algorithm pairs that the server is 2651 able to verify, listed in descending order of preference. 2653 certificate_authorities 2654 A list of the distinguished names [X501] of acceptable 2655 certificate_authorities, represented in DER-encoded format. These 2656 distinguished names may specify a desired distinguished name for a 2657 root CA or for a subordinate CA; thus, this message can be used to 2658 describe known roots as well as a desired authorization space. If 2659 the certificate_authorities list is empty, then the client MAY 2660 send any certificate of the appropriate ClientCertificateType, 2661 unless there is some external arrangement to the contrary. 2663 The interaction of the certificate_types and 2664 supported_signature_algorithms fields is somewhat complicated. 2665 certificate_types has been present in TLS since SSL 3.0, but was 2666 somewhat underspecified. Much of its functionality is superseded by 2667 supported_signature_algorithms. The following rules apply: 2669 - Any certificates provided by the client MUST be signed using a 2670 hash/signature algorithm pair found in 2671 supported_signature_algorithms. 2673 - The end-entity certificate provided by the client MUST contain a 2674 key that is compatible with certificate_types. If the key is a 2675 signature key, it MUST be usable with some hash/signature 2676 algorithm pair in supported_signature_algorithms. 2678 - For historical reasons, the names of some client certificate types 2679 include the algorithm used to sign the certificate. For example, 2680 in earlier versions of TLS, rsa_fixed_dh meant a certificate 2681 signed with RSA and containing a static DH key. In TLS 1.2, this 2682 functionality has been obsoleted by the 2683 supported_signature_algorithms, and the certificate type no longer 2684 restricts the algorithm used to sign the certificate. For 2685 example, if the server sends dss_fixed_dh certificate type and 2686 {{sha1, dsa}, {sha1, rsa}} signature types, the client MAY reply 2687 with a certificate containing a static DH key, signed with RSA- 2688 SHA1. 2690 New ClientCertificateType values are assigned by IANA as described in 2691 Section 11. 2693 Note: Values listed as RESERVED MUST NOT be used. They were used in 2694 SSL 3.0. 2696 Note: It is a fatal "handshake_failure" alert for an anonymous server 2697 to request client authentication. 2699 6.3.6. Server Configuration 2701 When this message will be sent: 2703 This message is used to provide a server configuration which the 2704 client can use in future to skip handshake negotiation and 2705 (optionally) to allow 0-RTT handshakes. The ServerConfiguration 2706 message is sent as the last message before the CertificateVerify. 2708 Structure of this Message: 2710 struct { 2711 opaque configuration_id<1..2^16-1>; 2712 uint32 expiration_date; 2713 NamedGroup group; 2714 opaque server_key<1..2^16-1>; 2715 Boolean early_data_allowed; 2716 } ServerConfiguration; 2718 configuration_id 2719 The configuration identifier to be used with the known 2720 configuration extension Section 6.3.1.5.3. 2722 group 2723 The group for the long-term DH key that is being established for 2724 this configuration. 2726 expiration_date 2727 The last time when this configuration is expected to be valid (in 2728 seconds since the Unix epoch). Servers MUST NOT use any value 2729 more than 604800 seconds (7 days) in the future. Clients MUST not 2730 cache configurations for longer than 7 days, regardless of the 2731 expiration_date. [[OPEN ISSUE: Is this the right value? The idea 2732 is just to minimize exposure.]] 2734 server_key 2735 The long-term DH key that is being established for this 2736 configuration. 2738 early_data_allowed 2739 Whether the client may send data in its first flight (see 2740 Section 6.3.1.5.5). 2742 The semantics of this message are to establish a shared state between 2743 the client and server for use with the "known_configuration" 2744 extension with the key specified in key and with the handshake 2745 parameters negotiated by this handshake. [[OPEN ISSUE: Should this 2746 allow some sort of parameter negotiation?]] 2748 When the ServerConfiguration message is sent, the server MUST also 2749 send a Certificate message and a CertificateVerify message, even if 2750 the "known_configuration" extension was used for this handshake, thus 2751 requiring a signature over the configuration before it can be used by 2752 the client. 2754 6.3.7. Server Certificate Verify 2756 When this message will be sent: 2758 This message is used to provide explicit proof that the server 2759 possesses the private key corresponding to its certificate and 2760 also provides integrity for the handshake up to this point. This 2761 message is only sent when the server is authenticated via a 2762 certificate. When sent, it MUST be the last server handshake 2763 message prior to the Finished. 2765 Structure of this message: 2767 struct { 2768 digitally-signed struct { 2769 opaque handshake_hash[hash_length]; 2770 } 2771 } CertificateVerify; 2773 Where session_hash is as described in {{the-handshake-hash} and 2774 includes the messages sent or received, starting at ClientHello 2775 and up to, but not including, this message, including the type and 2776 length fields of the handshake messages. This is a digest of the 2777 concatenation of all the Handshake structures (as defined in 2778 Section 6.3) exchanged thus far. The digest MUST be the Hash used 2779 as the basis for HKDF. 2781 The context string for the signature is "TLS 1.3, server 2782 CertificateVerify". A hash of the handshake messages is signed 2783 rather than the messages themselves because the digitally-signed 2784 format requires padding and context bytes at the beginning of the 2785 input. Thus, by signing a digest of the messages, an 2786 implementation need only maintain one running hash per hash type 2787 for CertificateVerify, Finished and other messages. 2789 If the client has offered the "signature_algorithms" extension, 2790 the signature algorithm and hash algorithm MUST be a pair listed 2791 in that extension. Note that there is a possibility for 2792 inconsistencies here. For instance, the client might offer 2793 DHE_DSS key exchange but omit any DSA pairs from its 2794 "signature_algorithms" extension. In order to negotiate 2795 correctly, the server MUST check any candidate cipher suites 2796 against the "signature_algorithms" extension before selecting 2797 them. This is somewhat inelegant but is a compromise designed to 2798 minimize changes to the original cipher suite design. 2800 In addition, the hash and signature algorithms MUST be compatible 2801 with the key in the server's end-entity certificate. RSA keys MAY 2802 be used with any permitted hash algorithm, subject to restrictions 2803 in the certificate, if any. 2805 Because DSA signatures do not contain any secure indication of 2806 hash algorithm, there is a risk of hash substitution if multiple 2807 hashes may be used with any key. Currently, DSA [DSS] may only be 2808 used with SHA-1. Future revisions of DSS [DSS-3] are expected to 2809 allow the use of other digest algorithms with DSA, as well as 2810 guidance as to which digest algorithms should be used with each 2811 key size. In addition, future revisions of [RFC5280] may specify 2812 mechanisms for certificates to indicate which digest algorithms 2813 are to be used with DSA. [[TODO: Update this to deal with DSS-3 2814 and DSS-4. https://github.com/tlswg/tls13-spec/issues/59]] 2816 6.3.8. Server Finished 2818 When this message will be sent: 2820 The Server's Finished message is the final message sent by the 2821 server and is essential for providing authentication of the server 2822 side of the handshake and computed keys. 2824 Meaning of this message: 2826 Recipients of Finished messages MUST verify that the contents are 2827 correct. Once a side has sent its Finished message and received 2828 and validated the Finished message from its peer, it may begin to 2829 send and receive application data over the connection. This data 2830 will be protected under keys derived from the ephemeral secret 2831 (see Section 7). 2833 Structure of this message: 2835 struct { 2836 opaque verify_data[verify_data_length]; 2837 } Finished; 2839 The verify_data value is computed as follows: 2841 verify_data 2842 HMAC(finished_secret, finished_label + '\0' + handshake_hash) 2843 where HMAC uses the Hash algorithm for the handshake. See 2844 Section 7.2.1 for the definition of handshake_hash. 2846 finished_label 2847 For Finished messages sent by the client, the string "client 2848 finished". For Finished messages sent by the server, the string 2849 "server finished". 2851 In previous versions of TLS, the verify_data was always 12 octets 2852 long. In the current version of TLS, it is the size of the HMAC 2853 output for the Hash used for the handshake. 2855 Note: Alerts and any other record types are not handshake messages 2856 and are not included in the hash computations. Also, HelloRequest 2857 messages and the Finished message are omitted from handshake hashes. 2858 The input to the client and server Finished messages may not be the 2859 same because the server's Finished does not include the client's 2860 Certificate and CertificateVerify message. 2862 6.3.9. Client Certificate 2864 When this message will be sent: 2866 This message is the first handshake message the client can send 2867 after receiving the server's Finished. This message is only sent 2868 if the server requests a certificate. If no suitable certificate 2869 is available, the client MUST send a certificate message 2870 containing no certificates. That is, the certificate_list 2871 structure has a length of zero. If the client does not send any 2872 certificates, the server MAY at its discretion either continue the 2873 handshake without client authentication, or respond with a fatal 2874 "handshake_failure" alert. Also, if some aspect of the 2875 certificate chain was unacceptable (e.g., it was not signed by a 2876 known, trusted CA), the server MAY at its discretion either 2877 continue the handshake (considering the client unauthenticated) or 2878 send a fatal alert. 2880 Client certificates are sent using the Certificate structure 2881 defined in Section 6.3.4. 2883 Meaning of this message: 2885 This message conveys the client's certificate chain to the server; 2886 the server will use it when verifying the CertificateVerify 2887 message (when the client authentication is based on signing). The 2888 certificate MUST be appropriate for the negotiated cipher suite's 2889 key exchange algorithm, and any negotiated extensions. 2891 In particular: 2893 - The certificate type MUST be X.509v3 [RFC5280], unless explicitly 2894 negotiated otherwise (e.g., [RFC5081]). 2896 - The end-entity certificate's public key (and associated 2897 restrictions) has to be compatible with the certificate types 2898 listed in CertificateRequest: 2900 Client Cert. Type Certificate Key Type 2902 rsa_sign RSA public key; the certificate MUST allow the 2903 key to be used for signing with the signature 2904 scheme and hash algorithm that will be 2905 employed in the certificate verify message. 2907 dss_sign DSA public key; the certificate MUST allow the 2908 key to be used for signing with the hash 2909 algorithm that will be employed in the 2910 certificate verify message. 2912 ecdsa_sign ECDSA-capable public key; the certificate MUST 2913 allow the key to be used for signing with the 2914 hash algorithm that will be employed in the 2915 certificate verify message; the public key 2916 MUST use a curve and point format supported by 2917 the server. 2919 rsa_fixed_dh Diffie-Hellman public key; MUST use the same 2920 dss_fixed_dh parameters as server's key. 2922 rsa_fixed_ecdh ECDH-capable public key; MUST use the 2923 ecdsa_fixed_ecdh same curve as the server's key, and MUST use a 2924 point format supported by the server. 2926 - If the certificate_authorities list in the certificate request 2927 message was non-empty, one of the certificates in the certificate 2928 chain SHOULD be issued by one of the listed CAs. 2930 - The certificates MUST be signed using an acceptable hash/ 2931 signature algorithm pair, as described in Section 6.3.5. Note 2932 that this relaxes the constraints on certificate-signing 2933 algorithms found in prior versions of TLS. 2935 Note that, as with the server certificate, there are certificates 2936 that use algorithms/algorithm combinations that cannot be currently 2937 used with TLS. 2939 6.3.10. Client Certificate Verify 2941 When this message will be sent: 2943 This message is used to provide explicit verification of a client 2944 certificate. This message is only sent following a client 2945 certificate that has signing capability (i.e., all certificates 2946 except those containing fixed Diffie-Hellman parameters). When 2947 sent, it MUST immediately follow the client's Certificate message. 2949 The contents of the message are computed as described in 2950 Section 6.3.7, except that the context string is "TLS 1.3, client 2951 CertificateVerify". 2953 The hash and signature algorithms used in the signature MUST be 2954 one of those present in the supported_signature_algorithms field 2955 of the CertificateRequest message. In addition, the hash and 2956 signature algorithms MUST be compatible with the key in the 2957 client's end-entity certificate. RSA keys MAY be used with any 2958 permitted hash algorithm, subject to restrictions in the 2959 certificate, if any. 2961 Because DSA signatures do not contain any secure indication of 2962 hash algorithm, there is a risk of hash substitution if multiple 2963 hashes may be used with any key. Currently, DSA [DSS] may only be 2964 used with SHA-1. Future revisions of DSS [DSS-3] are expected to 2965 allow the use of other digest algorithms with DSA, as well as 2966 guidance as to which digest algorithms should be used with each 2967 key size. In addition, future revisions of [RFC5280] may specify 2968 mechanisms for certificates to indicate which digest algorithms 2969 are to be used with DSA. 2971 6.3.11. New Session Ticket Message 2973 After the server has received the client Finished message, it MAY 2974 send a NewSessionTicket message. This message MUST be sent before 2975 the server sends any application data traffic, and is encrypted under 2976 the application traffic key. This message creates a pre-shared key 2977 (PSK) binding between the resumption master secret and the ticket 2978 label. The client MAY use this PSK for future handshakes by 2979 including it in the pre_shared_key extension in its ClientHello 2980 (Section 6.3.1.5.4) and supplying a suitable PSK cipher suite. 2982 struct { 2983 uint32 ticket_lifetime_hint; 2984 opaque ticket<0..2^16-1>; 2985 } NewSessionTicket; 2987 ticket_lifetime_hint 2988 Indicates the lifetime in seconds as a 32-bit unsigned integer in 2989 network byte order. A value of zero is reserved to indicate that 2990 the lifetime of the ticket is unspecified. 2992 ticket 2993 The value of the ticket to be used as the PSK identifier. 2995 The ticket lifetime hint is informative only. A client SHOULD delete 2996 the ticket and associated state when the time expires. It MAY delete 2997 the ticket earlier based on local policy. A server MAY treat a 2998 ticket as valid for a shorter or longer period of time than what is 2999 stated in the ticket_lifetime_hint. 3001 The ticket itself is an opaque label. It MAY either be a database 3002 lookup key or a self-encrypted and self-authenticated value. 3003 Section 4 of [RFC5077] describes a recommended ticket construction 3004 mechanism. 3006 [[TODO: Should we require that tickets be bound to the existing 3007 symmetric cipher suite. See the TODO above about early_data and 3008 PSK.??] 3010 7. Cryptographic Computations 3012 In order to begin connection protection, the TLS Record Protocol 3013 requires specification of a suite of algorithms, a master secret, and 3014 the client and server random values. The authentication, key 3015 agreement, and record protection algorithms are determined by the 3016 cipher_suite selected by the server and revealed in the ServerHello 3017 message. The random values are exchanged in the hello messages. All 3018 that remains is to calculate the key schedule. 3020 7.1. Key Schedule 3022 The TLS handshake establishes secret keying material which is then 3023 used to protect traffic. This keying material is derived from the 3024 two input secret values: Static Secret (SS) and Ephemeral Secret 3025 (ES). 3027 The exact source of each of these secrets depends on the operational 3028 mode (DHE, ECDHE, PSK, etc.) and is summarized in the table below: 3030 Key Exchange Static Secret (SS) Ephemeral Secret (ES) 3031 ------------ ------------------ --------------------- 3032 (EC)DHE Client ephemeral Client ephemeral 3033 (full handshake) w/ server ephemeral w/ server ephemeral 3035 (EC)DHE Client ephemeral Client ephemeral 3036 (w/ known_configuration) w/ Known Key w/ server ephemeral 3038 PSK Pre-Shared Key Pre-shared key 3040 PSK + (EC)DHE Pre-Shared Key Client ephemeral 3041 w/ server ephemeral 3043 These shared secret values are used to generate cryptographic keys as 3044 shown below. 3046 The derivation process is as follows, where L denotes the length of 3047 the underlying hash function for HKDF. 3049 HKDF-Expand-Label(Secret, Label, HashValue, Length) = 3050 HKDF-Expand(Secret, Label + '\0' + HashValue, Length) 3052 1. xSS = HKDF(0, SS, "extractedSS", L) 3054 2. xES = HKDF(0, ES, "extractedES", L) 3056 3. master_secret= HKDF(xSS, xES, "master secret", L) 3058 4. finished_secret = HKDF-Expand-Label(xSS, 3059 "finished secret", 3060 handshake_hash, L) 3062 Where handshake_hash includes all the messages in the 3063 client's first flight and the server's flight, excluding 3064 the Finished messages (which are never included in the 3065 hashes). 3067 5. resumption_secret = HKDF-Expand-Label(master_secret, 3068 "resumption master secret" 3069 session_hash, L) 3071 Where session_hash is as defined in {{the-handshake-hash}}. 3073 6. exporter_secret = HKDF-Expand-Label(master_secret, 3074 "exporter master secret", 3075 session_hash, L) 3077 Where session_hash is the session hash as defined in 3078 {{the-handshake-hash}} (i.e., the entire handshake except 3079 for Finished). 3081 The traffic keys are computed from xSS, xES, and the master_secret as 3082 described in Section 7.2 below. 3084 7.2. Traffic Key Calculation 3086 [[OPEN ISSUE: This needs to be revised. Most likely we'll extract 3087 each key component separately. See https://github.com/tlswg/tls13- 3088 spec/issues/5]] 3090 The Record Protocol requires an algorithm to generate keys required 3091 by the current connection state (see Appendix A.5) from the security 3092 parameters provided by the handshake protocol. 3094 The traffic key computation takes four input values and returns a key 3095 block of sufficient size to produce the needed traffic keys: 3097 - A secret value 3099 - A string label that indicates the purpose of keys being generated. 3101 - The current handshake hash. 3103 - The total length in octets of the key block. 3105 The keying material is computed using: 3107 key_block = HKDF-Expand-Label(Secret, Label, 3108 handshake_hash, 3109 total_length) 3111 The key_block is partitioned as follows: 3113 client_write_key[SecurityParameters.enc_key_length] 3114 server_write_key[SecurityParameters.enc_key_length] 3115 client_write_IV[SecurityParameters.iv_length] 3116 server_write_IV[SecurityParameters.iv_length] 3118 The following table describes the inputs to the key calculation for 3119 each class of traffic keys: 3121 Record Type Secret Label Handshake Hash 3122 ----------- ------ ----- --------------- 3123 Early data xSS "early data key expansion" ClientHello 3125 Handshake xES "handshake key expansion" ClientHello... 3126 ServerKeyShare 3128 Application master "application data key expansion" All handshake 3129 secret messages but 3130 Finished 3131 (session_hash) 3133 7.2.1. The Handshake Hash 3135 handshake_hash = Hash( 3136 Hash(handshake_messages) || 3137 Hash(configuration) 3138 ) 3140 handshake_messages 3141 All handshake messages sent or received, starting at ClientHello 3142 up to the present time, with the exception of the Finished 3143 message, including the type and length fields of the handshake 3144 messages. This is the concatenation of all the exchanged 3145 Handshake structures in plaintext form (even if they were 3146 encrypted on the wire). 3148 configuration 3149 When the known_configuration extension is in use 3150 (Section 6.3.1.5.3, this contains the concatenation of the 3151 ServerConfiguration and Certificate messages from the handshake 3152 where the configuration was established. Note that this requires 3153 the client and server to memorize these values. 3155 This final value of the handshake hash is referred to as the "session 3156 hash" because it contains all the handshake messages required to 3157 establish the session. Note that if client authentication is not 3158 used, then the session hash is complete at the point when the server 3159 has sent its first flight. Otherwise, it is only complete when the 3160 client has sent its first flight, as it covers the client's 3161 Certificate and CertificateVerify. 3163 7.2.2. Diffie-Hellman 3165 A conventional Diffie-Hellman computation is performed. The 3166 negotiated key (Z) is used as the shared_secret, and is used in the 3167 key schedule as specified above. Leading bytes of Z that contain all 3168 zero bits are stripped before it is used as the input to HKDF. 3170 7.2.3. Elliptic Curve Diffie-Hellman 3172 All ECDH calculations (including parameter and key generation as well 3173 as the shared secret calculation) are performed according to [6] 3174 using the ECKAS-DH1 scheme with the identity map as key derivation 3175 function (KDF), so that the shared secret is the x-coordinate of the 3176 ECDH shared secret elliptic curve point represented as an octet 3177 string. Note that this octet string (Z in IEEE 1363 terminology) as 3178 output by FE2OSP, the Field Element to Octet String Conversion 3179 Primitive, has constant length for any given field; leading zeros 3180 found in this octet string MUST NOT be truncated. 3182 (Note that this use of the identity KDF is a technicality. The 3183 complete picture is that ECDH is employed with a non-trivial KDF 3184 because TLS does not directly use this secret for anything other than 3185 for computing other secrets.) 3187 8. Mandatory Cipher Suites 3189 In the absence of an application profile standard specifying 3190 otherwise, a TLS-compliant application MUST implement the cipher 3191 suite TODO:Needs to be selected [1]. (See Appendix A.4 for the 3192 definition.) 3194 9. Application Data Protocol 3196 Application data messages are carried by the record layer and are 3197 fragmented and encrypted based on the current connection state. The 3198 messages are treated as transparent data to the record layer. 3200 10. Security Considerations 3202 Security issues are discussed throughout this memo, especially in 3203 Appendices C, D, and E. 3205 11. IANA Considerations 3207 [[TODO: Update https://github.com/tlswg/tls13-spec/issues/62]] 3209 This document uses several registries that were originally created in 3210 [RFC4346]. IANA has updated these to reference this document. The 3211 registries and their allocation policies (unchanged from [RFC4346]) 3212 are listed below. 3214 - TLS ClientCertificateType Identifiers Registry: Future values in 3215 the range 0-63 (decimal) inclusive are assigned via Standards 3216 Action [RFC2434]. Values in the range 64-223 (decimal) inclusive 3217 are assigned via Specification Required [RFC2434]. Values from 3218 224-255 (decimal) inclusive are reserved for Private Use 3219 [RFC2434]. 3221 - TLS Cipher Suite Registry: Future values with the first byte in 3222 the range 0-191 (decimal) inclusive are assigned via Standards 3223 Action [RFC2434]. Values with the first byte in the range 192-254 3224 (decimal) are assigned via Specification Required [RFC2434]. 3225 Values with the first byte 255 (decimal) are reserved for Private 3226 Use [RFC2434]. 3228 - TLS ContentType Registry: Future values are allocated via 3229 Standards Action [RFC2434]. 3231 - TLS Alert Registry: Future values are allocated via Standards 3232 Action [RFC2434]. 3234 - TLS HandshakeType Registry: Future values are allocated via 3235 Standards Action [RFC2434]. 3237 This document also uses a registry originally created in [RFC4366]. 3238 IANA has updated it to reference this document. The registry and its 3239 allocation policy (unchanged from [RFC4366]) is listed below: 3241 - TLS ExtensionType Registry: Future values are allocated via IETF 3242 Consensus [RFC2434]. IANA has updated this registry to include 3243 the signature_algorithms extension and its corresponding value 3244 (see Section 6.3.1.4). 3246 This document also uses two registries originally created in 3247 [RFC4492]. IANA [should update/has updated] it to reference this 3248 document. The registries and their allocation policies are listed 3249 below. 3251 - TLS NamedCurve registry: Future values are allocated via IETF 3252 Consensus [RFC2434]. 3254 - TLS ECPointFormat Registry: Future values are allocated via IETF 3255 Consensus [RFC2434]. 3257 In addition, this document defines two new registries to be 3258 maintained by IANA: 3260 - TLS SignatureAlgorithm Registry: The registry has been initially 3261 populated with the values described in Section 6.3.1.4.1. Future 3262 values in the range 0-63 (decimal) inclusive are assigned via 3263 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 3264 inclusive are assigned via Specification Required [RFC2434]. 3265 Values from 224-255 (decimal) inclusive are reserved for Private 3266 Use [RFC2434]. 3268 - TLS HashAlgorithm Registry: The registry has been initially 3269 populated with the values described in Section 6.3.1.4.1. Future 3270 values in the range 0-63 (decimal) inclusive are assigned via 3271 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 3272 inclusive are assigned via Specification Required [RFC2434]. 3273 Values from 224-255 (decimal) inclusive are reserved for Private 3274 Use [RFC2434]. 3276 12. References 3277 12.1. Normative References 3279 [AES] National Institute of Standards and Technology, 3280 "Specification for the Advanced Encryption Standard 3281 (AES)", NIST FIPS 197, November 2001. 3283 [DH] Diffie, W. and M. Hellman, "New Directions in 3284 Cryptography", IEEE Transactions on Information Theory, 3285 V.IT-22 n.6 , June 1977. 3287 [DSS] National Institute of Standards and Technology, U.S. 3288 Department of Commerce, "Digital Signature Standard", NIST 3289 FIPS PUB 186-2, 2000. 3291 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 3292 April 1992. 3294 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3295 Hashing for Message Authentication", RFC 2104, February 3296 1997. 3298 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3299 Requirement Levels", BCP 14, RFC 2119, March 1997. 3301 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3302 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 3303 October 1998. 3305 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3306 Standards (PKCS) #1: RSA Cryptography Specifications 3307 Version 2.1", RFC 3447, February 2003. 3309 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3310 Housley, R., and W. Polk, "Internet X.509 Public Key 3311 Infrastructure Certificate and Certificate Revocation List 3312 (CRL) Profile", RFC 5280, May 2008. 3314 [RFC5288] Salowey, J., Choudhury, A., and D. McGrew, "AES Galois 3315 Counter Mode (GCM) Cipher Suites for TLS", RFC 5288, 3316 August 2008. 3318 [RFC5289] Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3319 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3320 August 2008. 3322 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3323 Key Derivation Function (HKDF)", RFC 5869, May 2010. 3325 [SHS] National Institute of Standards and Technology, U.S. 3326 Department of Commerce, "Secure Hash Standard", NIST FIPS 3327 PUB 180-2, August 2002. 3329 [X680] ITU-T, "Information technology - Abstract Syntax Notation 3330 One (ASN.1): Specification of basic notation", ISO/IEC 3331 8824-1:2002, 2002. 3333 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 3334 Specification of Basic Encoding Rules (BER), Canonical 3335 Encoding Rules (CER) and Distinguished Encoding Rules 3336 (DER)", ISO/IEC 8825-1:2002, 2002. 3338 [X962] ANSI, "Public Key Cryptography For The Financial Services 3339 Industry: The Elliptic Curve Digital Signature Algorithm 3340 (ECDSA)", ANSI X9.62, 1998. 3342 12.2. Informative References 3344 [CBCATT] Moeller, B., "Security of CBC Ciphersuites in SSL/TLS: 3345 Problems and Countermeasures", May 2004, 3346 . 3348 [DSS-3] National Institute of Standards and Technology, U.S., 3349 "Digital Signature Standard", NIST FIPS PUB 186-3 Draft, 3350 2006. 3352 [ECDSA] American National Standards Institute, "Public Key 3353 Cryptography for the Financial Services Industry: The 3354 Elliptic Curve Digital Signature Algorithm (ECDSA)", ANSI 3355 ANS X9.62-2005, November 2005. 3357 [FI06] "Bleichenbacher's RSA signature forgery based on 3358 implementation error", August 2006, . 3361 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 3362 Operation: Galois/Counter Mode (GCM) and GMAC", NIST 3363 Special Publication 800-38D, November 2007. 3365 [I-D.ietf-tls-negotiated-ff-dhe] 3366 Gillmor, D., "Negotiated Finite Field Diffie-Hellman 3367 Ephemeral Parameters for TLS", draft-ietf-tls-negotiated- 3368 ff-dhe-10 (work in progress), June 2015. 3370 [I-D.ietf-tls-session-hash] 3371 Bhargavan, K., Delignat-Lavaud, A., Pironti, A., Langley, 3372 A., and M. Ray, "Transport Layer Security (TLS) Session 3373 Hash and Extended Master Secret Extension", draft-ietf- 3374 tls-session-hash-05 (work in progress), April 2015. 3376 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate 3377 Syntax Standard, version 1.5", November 1993. 3379 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message 3380 Syntax Standard, version 1.5", November 1993. 3382 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 3383 793, September 1981. 3385 [RFC1948] Bellovin, S., "Defending Against Sequence Number Attacks", 3386 RFC 1948, May 1996. 3388 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 3389 RFC 2246, January 1999. 3391 [RFC3268] Chown, P., "Advanced Encryption Standard (AES) 3392 Ciphersuites for Transport Layer Security (TLS)", RFC 3393 3268, June 2002. 3395 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 3396 Requirements for Security", BCP 106, RFC 4086, June 2005. 3398 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 3399 for Transport Layer Security (TLS)", RFC 4279, December 3400 2005. 3402 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, December 3403 2005. 3405 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", RFC 3406 4303, December 2005. 3408 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 3409 (TLS) Protocol Version 1.1", RFC 4346, April 2006. 3411 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 3412 and T. Wright, "Transport Layer Security (TLS) 3413 Extensions", RFC 4366, April 2006. 3415 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 3416 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 3417 for Transport Layer Security (TLS)", RFC 4492, May 2006. 3419 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 3420 STD 67, RFC 4506, May 2006. 3422 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 3423 "Transport Layer Security (TLS) Session Resumption without 3424 Server-Side State", RFC 5077, January 2008. 3426 [RFC5081] Mavrogiannopoulos, N., "Using OpenPGP Keys for Transport 3427 Layer Security (TLS) Authentication", RFC 5081, November 3428 2007. 3430 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 3431 Encryption", RFC 5116, January 2008. 3433 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 3434 Layer Security (TLS)", RFC 5705, March 2010. 3436 [RFC5763] Fischl, J., Tschofenig, H., and E. Rescorla, "Framework 3437 for Establishing a Secure Real-time Transport Protocol 3438 (SRTP) Security Context Using Datagram Transport Layer 3439 Security (DTLS)", RFC 5763, May 2010. 3441 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 3442 Extension Definitions", RFC 6066, January 2011. 3444 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 3445 (SSL) Version 2.0", RFC 6176, March 2011. 3447 [RFC7465] Popov, A., "Prohibiting RC4 Cipher Suites", RFC 7465, 3448 February 2015. 3450 [RFC7568] Barnes, R., Thomson, M., Pironti, A., and A. Langley, 3451 "Deprecating Secure Sockets Layer Version 3.0", RFC 7568, 3452 June 2015. 3454 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 3455 Obtaining Digital Signatures and Public-Key 3456 Cryptosystems", Communications of the ACM v. 21, n. 2, pp. 3457 120-126., February 1978. 3459 [SSL2] Netscape Communications Corp., "The SSL Protocol", 3460 February 1995. 3462 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 3463 Protocol", November 1996. 3465 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 3466 practical", USENIX Security Symposium, 2003. 3468 [X501] "Information Technology - Open Systems Interconnection - 3469 The Directory: Models", ITU-T X.501, 1993. 3471 12.3. URIs 3473 [1] https://github.com/tlswg/tls13-spec/issues/32 3475 [2] mailto:tls@ietf.org 3477 Appendix A. Protocol Data Structures and Constant Values 3479 This section describes protocol types and constants. 3481 A.1. Record Layer 3483 struct { 3484 uint8 major; 3485 uint8 minor; 3486 } ProtocolVersion; 3488 enum { 3489 reserved(20), alert(21), handshake(22), 3490 application_data(23), early_handshake(25), 3491 (255) 3492 } ContentType; 3494 struct { 3495 ContentType type; 3496 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 3497 uint16 length; 3498 opaque fragment[TLSPlaintext.length]; 3499 } TLSPlaintext; 3501 struct { 3502 ContentType type; 3503 ProtocolVersion record_version = { 3, 1 }; /* TLS v1.x */ 3504 uint16 length; 3505 aead-ciphered struct { 3506 opaque content[TLSPlaintext.length]; 3507 } fragment; 3508 } TLSCiphertext; 3510 A.2. Alert Messages 3511 enum { warning(1), fatal(2), (255) } AlertLevel; 3513 enum { 3514 close_notify(0), 3515 unexpected_message(10), /* fatal */ 3516 bad_record_mac(20), /* fatal */ 3517 decryption_failed_RESERVED(21), /* fatal */ 3518 record_overflow(22), /* fatal */ 3519 decompression_failure_RESERVED(30), /* fatal */ 3520 handshake_failure(40), /* fatal */ 3521 no_certificate_RESERVED(41), /* fatal */ 3522 bad_certificate(42), 3523 unsupported_certificate(43), 3524 certificate_revoked(44), 3525 certificate_expired(45), 3526 certificate_unknown(46), 3527 illegal_parameter(47), /* fatal */ 3528 unknown_ca(48), /* fatal */ 3529 access_denied(49), /* fatal */ 3530 decode_error(50), /* fatal */ 3531 decrypt_error(51), /* fatal */ 3532 export_restriction_RESERVED(60), /* fatal */ 3533 protocol_version(70), /* fatal */ 3534 insufficient_security(71), /* fatal */ 3535 internal_error(80), /* fatal */ 3536 user_canceled(90), 3537 no_renegotiation(100), /* fatal */ 3538 unsupported_extension(110), /* fatal */ 3539 (255) 3540 } AlertDescription; 3542 struct { 3543 AlertLevel level; 3544 AlertDescription description; 3545 } Alert; 3547 A.3. Handshake Protocol 3548 enum { 3549 reserved(0), client_hello(1), server_hello(2), 3550 session_ticket(4), hello_retry_request(6), 3551 server_key_share(7), certificate(11), reserved(12), 3552 certificate_request(13), server_configuration(14), 3553 certificate_verify(15), reserved(16), finished(20), (255) 3554 } HandshakeType; 3556 struct { 3557 HandshakeType msg_type; /* handshake type */ 3558 uint24 length; /* bytes in message */ 3559 select (HandshakeType) { 3560 case client_hello: ClientHello; 3561 case server_hello: ServerHello; 3562 case hello_retry_request: HelloRetryRequest; 3563 case server_key_share: ServerKeyShare; 3564 case server_configuration:ServerConfiguration; 3565 case certificate: Certificate; 3566 case certificate_request: CertificateRequest; 3567 case certificate_verify: CertificateVerify; 3568 case finished: Finished; 3569 case session_ticket: NewSessionTicket; 3570 } body; 3571 } Handshake; 3573 A.3.1. Hello Messages 3575 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 3577 enum { null(0), (255) } CompressionMethod; 3579 struct { 3580 ProtocolVersion client_version = { 3, 4 }; /* TLS v1.3 */ 3581 Random random; 3582 SessionID session_id; 3583 CipherSuite cipher_suites<2..2^16-2>; 3584 CompressionMethod compression_methods<1..2^8-1>; 3585 select (extensions_present) { 3586 case false: 3587 struct {}; 3588 case true: 3589 Extension extensions<0..2^16-1>; 3590 }; 3591 } ClientHello; 3593 struct { 3594 ProtocolVersion server_version; 3595 Random random; 3596 uint8 session_id_len; // Must be 0. 3597 CipherSuite cipher_suite; 3598 select (extensions_present) { 3599 case false: 3600 struct {}; 3601 case true: 3602 Extension extensions<0..2^16-1>; 3603 }; 3604 } ServerHello; 3606 struct { 3607 ProtocolVersion server_version; 3608 CipherSuite cipher_suite; 3609 NamedGroup selected_group; 3610 Extension extensions<0..2^16-1>; 3611 } HelloRetryRequest; 3613 struct { 3614 ExtensionType extension_type; 3615 opaque extension_data<0..2^16-1>; 3616 } Extension; 3618 enum { 3619 signature_algorithms(13), 3620 early_data(TBD), 3621 supported_groups(TBD), 3622 known_configuration(TBD), 3623 pre_shared_key(TBD) 3624 client_key_shares(TBD) 3625 (65535) 3626 } ExtensionType; 3628 struct { 3629 select (Role) { 3630 case client: 3631 opaque identifier<0..2^16-1>; 3633 case server: 3634 struct {}; 3635 } 3636 } KnownConfigurationExtension 3638 opaque psk_identity<0..2^16-1>; 3640 struct { 3641 select (Role) { 3642 case client: 3643 psk_identity identities<0..2^16-1>; 3645 case server: 3646 psk_identity identity; 3648 } PreSharedKeyExtension; 3650 enum { early_handshake(1), early_data(2), 3651 early_handshake_and_data(3), (255) } EarlyDataType; 3653 struct { 3654 select (Role) { 3655 case client: 3656 opaque context<0..255>; 3657 EarlyDataType type; 3658 case server: 3659 struct {}; 3660 } 3661 } EarlyDataIndication; 3663 struct { 3664 Extension extensions<0..2^16-1>; 3665 } EncryptedExtensions; 3667 struct { 3668 opaque configuration_id<1..2^16-1>; 3669 uint32 expiration_date; 3670 NamedGroup group; 3671 opaque server_key<1..2^16-1>; 3672 Boolean early_data_allowed; 3673 } ServerConfiguration; 3675 A.3.1.1. Signature Algorithm Extension 3677 enum { 3678 none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5), 3679 sha512(6), (255) 3680 } HashAlgorithm; 3682 enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) } 3683 SignatureAlgorithm; 3685 struct { 3686 HashAlgorithm hash; 3687 SignatureAlgorithm signature; 3688 } SignatureAndHashAlgorithm; 3690 SignatureAndHashAlgorithm 3691 supported_signature_algorithms<2..2^16-2>; 3693 A.3.1.2. Named Group Extension 3695 enum { 3696 // Elliptic Curve Groups. 3697 sect163k1 (1), sect163r1 (2), sect163r2 (3), 3698 sect193r1 (4), sect193r2 (5), sect233k1 (6), 3699 sect233r1 (7), sect239k1 (8), sect283k1 (9), 3700 sect283r1 (10), sect409k1 (11), sect409r1 (12), 3701 sect571k1 (13), sect571r1 (14), secp160k1 (15), 3702 secp160r1 (16), secp160r2 (17), secp192k1 (18), 3703 secp192r1 (19), secp224k1 (20), secp224r1 (21), 3704 secp256k1 (22), secp256r1 (23), secp384r1 (24), 3705 secp521r1 (25), 3707 // Finite Field Groups. 3708 ffdhe2048 (256), ffdhe3072 (257), ffdhe4096 (258), 3709 ffdhe6144 (259), ffdhe8192 (260), 3710 ffdhe_private_use (0x01FC..0x01FF), 3712 // Reserved Code Points. 3713 reserved (0xFE00..0xFEFF), 3714 reserved(0xFF01), 3715 reserved(0xFF02), 3716 (0xFFFF) 3717 } NamedGroup; 3719 struct { 3720 NamedGroup named_group_list<1..2^16-1>; 3721 } NamedGroupList; 3723 A.3.2. Key Exchange Messages 3724 struct { 3725 NamedGroup group; 3726 opaque key_exchange<1..2^16-1>; 3727 } ClientKeyShareOffer; 3729 struct { 3730 ClientKeyShareOffer offers<0..2^16-1>; 3731 } ClientKeyShare; 3733 opaque dh_Y<1..2^16-1>; 3735 opaque point <1..2^8-1>; 3737 struct { 3738 NamedGroup group; 3739 opaque key_exchange<1..2^16-1>; 3740 } ServerKeyShare; 3742 A.3.3. Authentication Messages 3744 opaque ASN1Cert<1..2^24-1>; 3746 struct { 3747 ASN1Cert certificate_list<0..2^24-1>; 3748 } Certificate; 3750 enum { 3751 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 3752 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 3753 fortezza_dms_RESERVED(20), (255) 3754 } ClientCertificateType; 3756 opaque DistinguishedName<1..2^16-1>; 3758 struct { 3759 ClientCertificateType certificate_types<1..2^8-1>; 3760 SignatureAndHashAlgorithm 3761 supported_signature_algorithms<2..2^16-2>; 3762 DistinguishedName certificate_authorities<0..2^16-1>; 3763 } CertificateRequest; 3765 struct { 3766 digitally-signed struct { 3767 opaque handshake_hash[hash_length]; 3768 } 3769 } CertificateVerify; 3771 A.3.4. Handshake Finalization Messages 3773 struct { 3774 opaque verify_data[verify_data_length]; 3775 } Finished; 3777 A.3.5. Ticket Establishment 3779 struct { 3780 uint32 ticket_lifetime_hint; 3781 opaque ticket<0..2^16-1>; 3782 } NewSessionTicket; 3784 A.4. The Cipher Suite 3786 The following values define the cipher suite codes used in the 3787 ClientHello and ServerHello messages. A cipher suite defines a 3788 cipher specification supported in TLS. 3790 TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a 3791 TLS connection during the first handshake on that channel, but MUST 3792 NOT be negotiated, as it provides no more protection than an 3793 unsecured connection. 3795 CipherSuite TLS_NULL_WITH_NULL_NULL = {0x00,0x00}; 3797 The following cipher suite definitions, defined in [RFC5288], are 3798 used for server-authenticated (and optionally client-authenticated) 3799 Diffie-Hellman. DHE denotes ephemeral Diffie-Hellman, where the 3800 Diffie-Hellman parameters are signed by a signature-capable 3801 certificate, which has been signed by the CA. The signing algorithm 3802 used by the server is specified after the DHE component of the 3803 CipherSuite name. The server can request any signature-capable 3804 certificate from the client for client authentication. 3806 CipherSuite TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 = {0x00,0x9E}; 3807 CipherSuite TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 = {0x00,0x9F}; 3808 CipherSuite TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 = {0x00,0xA2}; 3809 CipherSuite TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 = {0x00,0xA3}; 3811 The following cipher suite definitions, defined in [RFC5289], are 3812 used for server-authenticated (and optionally client-authenticated) 3813 Elliptic Curve Diffie-Hellman. ECDHE denotes ephemeral Diffie- 3814 Hellman, where the Diffie-Hellman parameters are signed by a 3815 signature-capable certificate, which has been signed by the CA. The 3816 signing algorithm used by the server is specified after the DHE 3817 component of the CipherSuite name. The server can request any 3818 signature-capable certificate from the client for client 3819 authentication. 3821 CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = {0xC0,0x2B}; 3822 CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = {0xC0,0x2C}; 3823 CipherSuite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 = {0xC0,0x2F}; 3824 CipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 = {0xC0,0x30}; 3826 The following ciphers, defined in [RFC5288], are used for completely 3827 anonymous Diffie-Hellman communications in which neither party is 3828 authenticated. Note that this mode is vulnerable to man-in-the- 3829 middle attacks. Using this mode therefore is of limited use: These 3830 cipher suites MUST NOT be used by TLS implementations unless the 3831 application layer has specifically requested to allow anonymous key 3832 exchange. (Anonymous key exchange may sometimes be acceptable, for 3833 example, to support opportunistic encryption when no set-up for 3834 authentication is in place, or when TLS is used as part of more 3835 complex security protocols that have other means to ensure 3836 authentication.) 3838 CipherSuite TLS_DH_anon_WITH_AES_128_GCM_SHA256 = {0x00,0xA6}; 3839 CipherSuite TLS_DH_anon_WITH_AES_256_GCM_SHA384 = {0x00,0xA7}; 3841 [[TODO: Add all the defined AEAD ciphers. This currently only lists 3842 GCM. https://github.com/tlswg/tls13-spec/issues/53]] Note that using 3843 non-anonymous key exchange without actually verifying the key 3844 exchange is essentially equivalent to anonymous key exchange, and the 3845 same precautions apply. While non-anonymous key exchange will 3846 generally involve a higher computational and communicational cost 3847 than anonymous key exchange, it may be in the interest of 3848 interoperability not to disable non-anonymous key exchange when the 3849 application layer is allowing anonymous key exchange. 3851 o For cipher suites ending with _SHA256, HKDF is used with SHA-256 as 3852 the hash function. 3854 o For cipher suites ending with _SHA384, HKDF is used with SHA-384 as 3855 the hash function. 3857 New cipher suite values are assigned by IANA as described in 3858 Section 11. 3860 Note: The cipher suite values { 0x00, 0x1C } and { 0x00, 0x1D } are 3861 reserved to avoid collision with Fortezza-based cipher suites in SSL 3862 3.0. 3864 A.5. The Security Parameters 3866 These security parameters are determined by the TLS Handshake 3867 Protocol and provided as parameters to the TLS record layer in order 3868 to initialize a connection state. SecurityParameters includes: 3870 enum { server, client } ConnectionEnd; 3872 enum { tls_kdf_sha256, tls_kdf_sha384 } KDFAlgorithm; 3874 enum { aes_gcm } RecordProtAlgorithm; 3876 /* The algorithms specified in KDFAlgorithm and 3877 RecordProtAlgorithm may be added to. */ 3879 struct { 3880 ConnectionEnd entity; 3881 KDFAlgorithm kdf_algorithm; 3882 RecordProtAlgorithm record_prot_algorithm; 3883 uint8 enc_key_length; 3884 uint8 iv_length; 3885 opaque hs_master_secret[48]; 3886 opaque master_secret[48]; 3887 opaque client_random[32]; 3888 opaque server_random[32]; 3889 } SecurityParameters; 3891 A.6. Changes to RFC 4492 3893 RFC 4492 [RFC4492] adds Elliptic Curve cipher suites to TLS. This 3894 document changes some of the structures used in that document. This 3895 section details the required changes for implementors of both RFC 3896 4492 and TLS 1.2. Implementors of TLS 1.2 who are not implementing 3897 RFC 4492 do not need to read this section. 3899 This document adds a "signature_algorithm" field to the digitally- 3900 signed element in order to identify the signature and digest 3901 algorithms used to create a signature. This change applies to 3902 digital signatures formed using ECDSA as well, thus allowing ECDSA 3903 signatures to be used with digest algorithms other than SHA-1, 3904 provided such use is compatible with the certificate and any 3905 restrictions imposed by future revisions of [RFC5280]. 3907 As described in Section 6.3.4 and Section 6.3.9, the restrictions on 3908 the signature algorithms used to sign certificates are no longer tied 3909 to the cipher suite (when used by the server) or the 3910 ClientCertificateType (when used by the client). Thus, the 3911 restrictions on the algorithm used to sign certificates specified in 3912 Sections 2 and 3 of RFC 4492 are also relaxed. As in this document, 3913 the restrictions on the keys in the end-entity certificate remain. 3915 Appendix B. Cipher Suite Definitions 3917 Cipher Suite Key Record 3918 Exchange Protection Hash 3920 TLS_NULL_WITH_NULL_NULL NULL NULL_NULL N/A 3921 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE_RSA AES_128_GCM SHA256 3922 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE_RSA AES_256_GCM SHA384 3923 TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE_DSS AES_128_GCM SHA256 3924 TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE_DSS AES_256_GCM SHA384 3925 TLS_DH_anon_WITH_AES_128_GCM_SHA256 DH_anon AES_128_GCM SHA256 3926 TLS_DH_anon_WITH_AES_256_GCM_SHA384 DH_anon AES_128_GCM SHA384 3928 Appendix C. Implementation Notes 3930 The TLS protocol cannot prevent many common security mistakes. This 3931 section provides several recommendations to assist implementors. 3933 C.1. Random Number Generation and Seeding 3935 TLS requires a cryptographically secure pseudorandom number generator 3936 (PRNG). Care must be taken in designing and seeding PRNGs. PRNGs 3937 based on secure hash operations, most notably SHA-1, are acceptable, 3938 but cannot provide more security than the size of the random number 3939 generator state. 3941 To estimate the amount of seed material being produced, add the 3942 number of bits of unpredictable information in each seed byte. For 3943 example, keystroke timing values taken from a PC compatible 18.2 Hz 3944 timer provide 1 or 2 secure bits each, even though the total size of 3945 the counter value is 16 bits or more. Seeding a 128-bit PRNG would 3946 thus require approximately 100 such timer values. 3948 [RFC4086] provides guidance on the generation of random values. 3950 C.2. Certificates and Authentication 3952 Implementations are responsible for verifying the integrity of 3953 certificates and should generally support certificate revocation 3954 messages. Certificates should always be verified to ensure proper 3955 signing by a trusted Certificate Authority (CA). The selection and 3956 addition of trusted CAs should be done very carefully. Users should 3957 be able to view information about the certificate and root CA. 3959 C.3. Cipher Suites 3961 TLS supports a range of key sizes and security levels, including some 3962 that provide no or minimal security. A proper implementation will 3963 probably not support many cipher suites. For instance, anonymous 3964 Diffie-Hellman is strongly discouraged because it cannot prevent man- 3965 in-the-middle attacks. Applications should also enforce minimum and 3966 maximum key sizes. For example, certificate chains containing keys 3967 or signatures weaker than 2048-bit RSA or 224-bit ECDSA are not 3968 appropriate for secure applications. 3970 C.4. Implementation Pitfalls 3972 Implementation experience has shown that certain parts of earlier TLS 3973 specifications are not easy to understand, and have been a source of 3974 interoperability and security problems. Many of these areas have 3975 been clarified in this document, but this appendix contains a short 3976 list of the most important things that require special attention from 3977 implementors. 3979 TLS protocol issues: 3981 - Do you correctly handle handshake messages that are fragmented to 3982 multiple TLS records (see Section 5.2.1)? Including corner cases 3983 like a ClientHello that is split to several small fragments? Do 3984 you fragment handshake messages that exceed the maximum fragment 3985 size? In particular, the certificate and certificate request 3986 handshake messages can be large enough to require fragmentation. 3988 - Do you ignore the TLS record layer version number in all TLS 3989 records? (see Appendix D) 3991 - Have you ensured that all support for SSL, RC4, and EXPORT ciphers 3992 is completely removed from all possible configurations that 3993 support TLS 1.3 or later, and that attempts to use these obsolete 3994 capabilities fail correctly? (see Appendix D) 3996 - Do you handle TLS extensions in ClientHello correctly, including 3997 omitting the extensions field completely? 3999 - When the server has requested a client certificate, but no 4000 suitable certificate is available, do you correctly send an empty 4001 Certificate message, instead of omitting the whole message (see 4002 Section 6.3.9)? 4004 Cryptographic details: 4006 - What countermeasures do you use to prevent timing attacks against 4007 RSA signing operations [TIMING]. 4009 - When verifying RSA signatures, do you accept both NULL and missing 4010 parameters (see Section 4.9)? Do you verify that the RSA padding 4011 doesn't have additional data after the hash value? [FI06] 4013 - When using Diffie-Hellman key exchange, do you correctly strip 4014 leading zero bytes from the negotiated key (see Section 7.2.2)? 4016 - Does your TLS client check that the Diffie-Hellman parameters sent 4017 by the server are acceptable (see Appendix E.1.1.2)? 4019 - Do you use a strong and, most importantly, properly seeded random 4020 number generator (see Appendix C.1) Diffie-Hellman private values, 4021 the DSA "k" parameter, and other security-critical values? 4023 Appendix D. Backward Compatibility 4025 The TLS protocol provides a built-in mechanism for version 4026 negotiation between endpoints potentially supporting different 4027 versions of TLS. 4029 TLS 1.x and SSL 3.0 use compatible ClientHello messages. Servers can 4030 also handle clients trying to use future versions of TLS as long as 4031 the ClientHello format remains compatible and the client supports the 4032 highest protocol version available in the server. 4034 Prior versions of TLS used the record layer version number for 4035 various purposes. (TLSPlaintext.record_version & 4036 TLSCiphertext.record_version) As of TLS 1.3, this field is deprecated 4037 and its value MUST be ignored by all implementations. Version 4038 negotiation is performed using only the handshake versions. 4039 (ClientHello.client_version & ServerHello.server_version) In order to 4040 maximize interoperability with older endpoints, implementations that 4041 negotiate the usage of TLS 1.0-1.2 SHOULD set the record layer 4042 version number to the negotiated version for the ServerHello and all 4043 records thereafter. 4045 D.1. Negotiating with an older server 4047 A TLS 1.3 client who wishes to negotiate with such older servers will 4048 send a normal TLS 1.3 ClientHello containing { 3, 4 } (TLS 1.3) in 4049 ClientHello.client_version. If the server does not support this 4050 version it will respond with a ServerHello containing an older 4051 version number. If the client agrees to use this version, the 4052 negotiation will proceed as appropriate for the negotiated protocol. 4054 A client resuming a session SHOULD initiate the connection using the 4055 version that was previously negotiated. 4057 If the version chosen by the server is not supported by the client 4058 (or not acceptable), the client MUST send a "protocol_version" alert 4059 message and close the connection. 4061 If a TLS server receives a ClientHello containing a version number 4062 greater than the highest version supported by the server, it MUST 4063 reply according to the highest version supported by the server. 4065 Some legacy server implementations are known to not implement the TLS 4066 specification properly and might abort connections upon encountering 4067 TLS extensions or versions which it is not aware of. 4068 Interoperability with buggy servers is a complex topic beyond the 4069 scope of this document. Multiple connection attempts may be required 4070 in order to negotiate a backwards compatible connection, however this 4071 practice is vulnerable to downgrade attacks and is NOT RECOMMENDED. 4073 D.2. Negotiating with an older client 4075 A TLS server can also receive a ClientHello containing a version 4076 number smaller than the highest supported version. If the server 4077 wishes to negotiate with old clients, it will proceed as appropriate 4078 for the highest version supported by the server that is not greater 4079 than ClientHello.client_version. For example, if the server supports 4080 TLS 1.0, 1.1, and 1.2, and client_version is TLS 1.0, the server will 4081 proceed with a TLS 1.0 ServerHello. If the server only supports 4082 versions greater than client_version, it MUST send a 4083 "protocol_version" alert message and close the connection. 4085 Note that earlier versions of TLS did not clearly specify the record 4086 layer version number value in all cases 4087 (TLSPlaintext.record_version). Servers will receive various TLS 1.x 4088 versions in this field, however its value MUST always be ignored. 4090 D.3. Backwards Compatibility Security Restrictions 4092 If an implementation negotiates usage of TLS 1.2, then negotiation of 4093 cipher suites also supported by TLS 1.3 SHOULD be preferred, if 4094 available. 4096 The security of RC4 cipher suites is considered insufficient for the 4097 reasons cited in [RFC7465]. Implementations MUST NOT offer or 4098 negotiate RC4 cipher suites for any version of TLS for any reason. 4100 Old versions of TLS permitted the usage of very low strength ciphers. 4101 Ciphers with a strength less than 112 bits MUST NOT be offered or 4102 negotiated for any version of TLS for any reason. 4104 The security of SSL 2.0 [SSL2] is considered insufficient for the 4105 reasons enumerated in [RFC6176], and MUST NOT be negotiated for any 4106 reason. 4108 Implementations MUST NOT send an SSL version 2.0 compatible CLIENT- 4109 HELLO. Implementations MUST NOT negotiate TLS 1.3 or later using an 4110 SSL version 2.0 compatible CLIENT-HELLO. Implementations are NOT 4111 RECOMMENDED to accept an SSL version 2.0 compatible CLIENT-HELLO in 4112 order to negotiate older versions of TLS. 4114 Implementations MUST NOT send or accept any records with a version 4115 less than { 3, 0 }. 4117 The security of SSL 3.0 [SSL3] is considered insufficient for the 4118 reasons enumerated in [RFC7568], and MUST NOT be negotiated for any 4119 reason. 4121 Implementations MUST NOT send a ClientHello.client_version or 4122 ServerHello.server_version set to { 3, 0 } or less. Any endpoint 4123 receiving a Hello message with ClientHello.client_version or 4124 ServerHello.server_version set to { 3, 0 } MUST respond with a 4125 "protocol_version" alert message and close the connection. 4127 Appendix E. Security Analysis 4129 [[TODO: The entire security analysis needs a rewrite.]] 4131 The TLS protocol is designed to establish a secure connection between 4132 a client and a server communicating over an insecure channel. This 4133 document makes several traditional assumptions, including that 4134 attackers have substantial computational resources and cannot obtain 4135 secret information from sources outside the protocol. Attackers are 4136 assumed to have the ability to capture, modify, delete, replay, and 4137 otherwise tamper with messages sent over the communication channel. 4138 This appendix outlines how TLS has been designed to resist a variety 4139 of attacks. 4141 E.1. Handshake Protocol 4143 The handshake protocol is responsible for selecting a cipher spec and 4144 generating a master secret, which together comprise the primary 4145 cryptographic parameters associated with a secure session. The 4146 handshake protocol can also optionally authenticate parties who have 4147 certificates signed by a trusted certificate authority. 4149 E.1.1. Authentication and Key Exchange 4151 TLS supports three authentication modes: authentication of both 4152 parties, server authentication with an unauthenticated client, and 4153 total anonymity. Whenever the server is authenticated, the channel 4154 is secure against man-in-the-middle attacks, but completely anonymous 4155 sessions are inherently vulnerable to such attacks. Anonymous 4156 servers cannot authenticate clients. If the server is authenticated, 4157 its certificate message must provide a valid certificate chain 4158 leading to an acceptable certificate authority. Similarly, 4159 authenticated clients must supply an acceptable certificate to the 4160 server. Each party is responsible for verifying that the other's 4161 certificate is valid and has not expired or been revoked. 4163 [[TODO: Rewrite this because the master_secret is not used this way 4164 any more after Hugo's changes.]] The general goal of the key exchange 4165 process is to create a master_secret known to the communicating 4166 parties and not to attackers (see Section 7.1). The master_secret is 4167 required to generate the Finished messages and record protection keys 4168 (see Section 6.3.8 and Section 7.2). By sending a correct Finished 4169 message, parties thus prove that they know the correct master_secret. 4171 E.1.1.1. Anonymous Key Exchange 4173 Completely anonymous sessions can be established using Diffie-Hellman 4174 for key exchange. The server's public parameters are contained in 4175 the server key share message, and the client's are sent in the client 4176 key share message. Eavesdroppers who do not know the private values 4177 should not be able to find the Diffie-Hellman result. 4179 Warning: Completely anonymous connections only provide protection 4180 against passive eavesdropping. Unless an independent tamper-proof 4181 channel is used to verify that the Finished messages were not 4182 replaced by an attacker, server authentication is required in 4183 environments where active man-in-the-middle attacks are a concern. 4185 E.1.1.2. Diffie-Hellman Key Exchange with Authentication 4187 When Diffie-Hellman key exchange is used, the client and server use 4188 the client key exchange and server key exchange messages to send 4189 temporary Diffie-Hellman parameters. The signature in the 4190 certificate verify message (if present) covers the entire handshake 4191 up to that point and thus attests the certificate holder's desire to 4192 use the the ephemeral DHE keys. 4194 Peers SHOULD validate each other's public key Y (dh_Ys offered by the 4195 server or DH_Yc offered by the client) by ensuring that 1 < Y < p-1. 4197 This simple check ensures that the remote peer is properly behaved 4198 and isn't forcing the local system into a small subgroup. 4200 Additionally, using a fresh key for each handshake provides Perfect 4201 Forward Secrecy. Implementations SHOULD generate a new X for each 4202 handshake when using DHE cipher suites. 4204 E.1.2. Version Rollback Attacks 4206 Because TLS includes substantial improvements over SSL Version 2.0, 4207 attackers may try to make TLS-capable clients and servers fall back 4208 to Version 2.0. This attack can occur if (and only if) two TLS- 4209 capable parties use an SSL 2.0 handshake. 4211 Although the solution using non-random PKCS #1 block type 2 message 4212 padding is inelegant, it provides a reasonably secure way for Version 4213 3.0 servers to detect the attack. This solution is not secure 4214 against attackers who can brute-force the key and substitute a new 4215 ENCRYPTED-KEY-DATA message containing the same key (but with normal 4216 padding) before the application-specified wait threshold has expired. 4217 Altering the padding of the least-significant 8 bytes of the PKCS 4218 padding does not impact security for the size of the signed hashes 4219 and RSA key lengths used in the protocol, since this is essentially 4220 equivalent to increasing the input block size by 8 bytes. 4222 E.1.3. Detecting Attacks Against the Handshake Protocol 4224 An attacker might try to influence the handshake exchange to make the 4225 parties select different encryption algorithms than they would 4226 normally choose. 4228 For this attack, an attacker must actively change one or more 4229 handshake messages. If this occurs, the client and server will 4230 compute different values for the handshake message hashes. As a 4231 result, the parties will not accept each others' Finished messages. 4232 Without the static secret, the attacker cannot repair the Finished 4233 messages, so the attack will be discovered. 4235 E.2. Protecting Application Data 4237 The shared secrets are hashed with the handshake transcript to 4238 produce unique record protection secrets for each connection. 4240 Outgoing data is protected using an AEAD algorithm before 4241 transmission. The authentication data includes the sequence number, 4242 message type, message length, and the message contents. The message 4243 type field is necessary to ensure that messages intended for one TLS 4244 record layer client are not redirected to another. The sequence 4245 number ensures that attempts to delete or reorder messages will be 4246 detected. Since sequence numbers are 64 bits long, they should never 4247 overflow. Messages from one party cannot be inserted into the 4248 other's output, since they use independent keys. 4250 E.3. Denial of Service 4252 TLS is susceptible to a number of denial-of-service (DoS) attacks. 4253 In particular, an attacker who initiates a large number of TCP 4254 connections can cause a server to consume large amounts of CPU doing 4255 asymmetric crypto operations. However, because TLS is generally used 4256 over TCP, it is difficult for the attacker to hide his point of 4257 origin if proper TCP SYN randomization is used [RFC1948] by the TCP 4258 stack. 4260 Because TLS runs over TCP, it is also susceptible to a number of DoS 4261 attacks on individual connections. In particular, attackers can 4262 forge RSTs, thereby terminating connections, or forge partial TLS 4263 records, thereby causing the connection to stall. These attacks 4264 cannot in general be defended against by a TCP-using protocol. 4265 Implementors or users who are concerned with this class of attack 4266 should use IPsec AH [RFC4302] or ESP [RFC4303]. 4268 E.4. Final Notes 4270 For TLS to be able to provide a secure connection, both the client 4271 and server systems, keys, and applications must be secure. In 4272 addition, the implementation must be free of security errors. 4274 The system is only as strong as the weakest key exchange and 4275 authentication algorithm supported, and only trustworthy 4276 cryptographic functions should be used. Short public keys and 4277 anonymous servers should be used with great caution. Implementations 4278 and users must be careful when deciding which certificates and 4279 certificate authorities are acceptable; a dishonest certificate 4280 authority can do tremendous damage. 4282 Appendix F. Working Group Information 4284 The discussion list for the IETF TLS working group is located at the 4285 e-mail address tls@ietf.org [2]. Information on the group and 4286 information on how to subscribe to the list is at 4287 https://www1.ietf.org/mailman/listinfo/tls 4289 Archives of the list can be found at: https://www.ietf.org/mail- 4290 archive/web/tls/current/index.html 4292 Appendix G. Contributors 4294 Martin Abadi 4295 University of California, Santa Cruz 4296 abadi@cs.ucsc.edu 4298 Christopher Allen (co-editor of TLS 1.0) 4299 Alacrity Ventures 4300 ChristopherA@AlacrityManagement.com 4302 Steven M. Bellovin 4303 Columbia University 4304 smb@cs.columbia.edu 4306 Benjamin Beurdouche 4308 Karthikeyan Bhargavan (co-author of [I-D.ietf-tls-session-hash]) 4309 INRIA 4310 karthikeyan.bhargavan@inria.fr 4312 Simon Blake-Wilson (co-author of RFC4492) 4313 BCI 4314 sblakewilson@bcisse.com 4316 Nelson Bolyard 4317 Sun Microsystems, Inc. 4318 nelson@bolyard.com (co-author of RFC4492) 4320 Ran Canetti 4321 IBM 4322 canetti@watson.ibm.com 4324 Pete Chown 4325 Skygate Technology Ltd 4326 pc@skygate.co.uk 4328 Antoine Delignat-Lavaud (co-author of [I-D.ietf-tls-session-hash]) 4329 INRIA 4330 antoine.delignat-lavaud@inria.fr 4332 Tim Dierks (co-editor of TLS 1.0, 1.1, and 1.2) 4333 Independent 4334 tim@dierks.org 4336 Taher Elgamal 4337 Securify 4338 taher@securify.com 4339 Pasi Eronen 4340 Nokia 4341 pasi.eronen@nokia.com 4343 Anil Gangolli 4344 anil@busybuddha.org 4346 David M. Garrett 4348 Vipul Gupta (co-author of RFC4492) 4349 Sun Microsystems Laboratories 4350 vipul.gupta@sun.com 4352 Chris Hawk (co-author of RFC4492) 4353 Corriente Networks LLC 4354 chris@corriente.net 4356 Kipp Hickman 4358 Alfred Hoenes 4360 David Hopwood 4361 Independent Consultant 4362 david.hopwood@blueyonder.co.uk 4364 Daniel Kahn Gillmor 4365 ACLU 4366 dkg@fifthhorseman.net 4368 Phil Karlton (co-author of SSL 3.0) 4370 Paul Kocher (co-author of SSL 3.0) 4371 Cryptography Research 4372 paul@cryptography.com 4374 Hugo Krawczyk 4375 IBM 4376 hugo@ee.technion.ac.il 4378 Adam Langley (co-author of [I-D.ietf-tls-session-hash]) 4379 Google 4380 agl@google.com 4382 Ilari Liusvaara 4383 ilari.liusvaara@elisanet.fi 4385 Jan Mikkelsen 4386 Transactionware 4387 janm@transactionware.com 4389 Bodo Moeller (co-author of RFC4492) 4390 Google 4391 bodo@openssl.org 4393 Erik Nygren 4394 Akamai Technologies 4395 erik+ietf@nygren.org 4397 Magnus Nystrom 4398 RSA Security 4399 magnus@rsasecurity.com 4401 Alfredo Pironti (co-author of [I-D.ietf-tls-session-hash]) 4402 INRIA 4403 alfredo.pironti@inria.fr 4405 Marsh Ray (co-author of [I-D.ietf-tls-session-hash]) 4406 Microsoft 4407 maray@microsoft.com 4409 Robert Relyea 4410 Netscape Communications 4411 relyea@netscape.com 4413 Jim Roskind 4414 Netscape Communications 4415 jar@netscape.com 4417 Michael Sabin 4419 Dan Simon 4420 Microsoft, Inc. 4421 dansimon@microsoft.com 4423 Martin Thomson 4424 Mozilla 4425 mt@mozilla.com 4427 Tom Weinstein 4429 Tim Wright 4430 Vodafone 4431 timothy.wright@vodafone.com 4433 Author's Address 4435 Eric Rescorla 4436 RTFM, Inc. 4438 EMail: ekr@rtfm.com