idnits 2.17.1 draft-ietf-tls-rfc5246-bis-00.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 : ---------------------------------------------------------------------------- -- 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 809 has weird spacing: '...gorithm bul...' == Line 2462 has weird spacing: '...ixed_dh a c...' == Line 2463 has weird spacing: '...ixed_dh a c...' == Line 2599 has weird spacing: '...ed_ecdh sam...' == Line 3724 has weird spacing: '...gorithm bul...' == (1 more instance...) (Using the creation date from RFC4492, updated by this document, for RFC5378 checks: 1998-03-18) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 17, 2014) is 3633 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '0' is mentioned on line 333, but not defined == Missing Reference: '3' is mentioned on line 4230, but not defined == Missing Reference: '9' is mentioned on line 369, but not defined == Missing Reference: '2' is mentioned on line 3443, but not defined == Missing Reference: '4' is mentioned on line 405, but not defined == Missing Reference: '8' is mentioned on line 406, but not defined == Missing Reference: '10' is mentioned on line 516, but not defined == Missing Reference: '48' is mentioned on line 3734, but not defined == Missing Reference: '32' is mentioned on line 3736, but not defined == Missing Reference: 'ChangeCipherSpec' is mentioned on line 1691, but not defined == Missing Reference: '28' is mentioned on line 3438, but not defined == Missing Reference: '46' is mentioned on line 3571, but not defined == Missing Reference: 'TLSECC' is mentioned on line 3509, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- 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 3280 (Obsoleted by RFC 5280) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) -- Possible downref: Non-RFC (?) normative reference: ref. 'SCH' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'TRIPLEDES' -- Possible downref: Non-RFC (?) normative reference: ref. 'X680' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- 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 4307 (Obsoleted by RFC 8247) -- 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 5081 (Obsoleted by RFC 6091) Summary: 5 errors (**), 0 flaws (~~), 20 warnings (==), 24 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Dierks 3 Internet-Draft Independent 4 Obsoletes: 3268, 4346, 4366, 5246 E. Rescorla 5 (if approved) RTFM, Inc. 6 Updates: 4492 (if approved) April 17, 2014 7 Intended status: Standards Track 8 Expires: October 19, 2014 10 The Transport Layer Security (TLS) Protocol Version 1.3 11 draft-ietf-tls-rfc5246-bis-00 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 October 19, 2014. 38 Copyright Notice 40 Copyright (c) 2014 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 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.1. Requirements Terminology . . . . . . . . . . . . . . . . 5 57 1.2. Major Differences from TLS 1.1 . . . . . . . . . . . . . 5 58 2. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3. Goals of This Document . . . . . . . . . . . . . . . . . . . 7 60 4. Presentation Language . . . . . . . . . . . . . . . . . . . . 7 61 4.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 7 62 4.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 8 63 4.3. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 4.4. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 4.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 9 66 4.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 10 67 4.6.1. Variants . . . . . . . . . . . . . . . . . . . . . . 11 68 4.7. Cryptographic Attributes . . . . . . . . . . . . . . . . 12 69 4.8. Constants . . . . . . . . . . . . . . . . . . . . . . . . 14 70 5. HMAC and the Pseudorandom Function . . . . . . . . . . . . . 14 71 6. The TLS Record Protocol . . . . . . . . . . . . . . . . . . . 16 72 6.1. Connection States . . . . . . . . . . . . . . . . . . . . 16 73 6.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 19 74 6.2.1. Fragmentation . . . . . . . . . . . . . . . . . . . . 19 75 6.2.2. Record Compression and Decompression . . . . . . . . 21 76 6.2.3. Record Payload Protection . . . . . . . . . . . . . . 21 77 6.3. Key Calculation . . . . . . . . . . . . . . . . . . . . . 26 78 7. The TLS Handshaking Protocols . . . . . . . . . . . . . . . . 27 79 7.1. Change Cipher Spec Protocol . . . . . . . . . . . . . . . 28 80 7.2. Alert Protocol . . . . . . . . . . . . . . . . . . . . . 28 81 7.2.1. Closure Alerts . . . . . . . . . . . . . . . . . . . 29 82 7.2.2. Error Alerts . . . . . . . . . . . . . . . . . . . . 30 83 7.3. Handshake Protocol Overview . . . . . . . . . . . . . . . 34 84 7.4. Handshake Protocol . . . . . . . . . . . . . . . . . . . 37 85 7.4.1. Hello Messages . . . . . . . . . . . . . . . . . . . 38 86 7.4.2. Server Certificate . . . . . . . . . . . . . . . . . 48 87 7.4.3. Server Key Exchange Message . . . . . . . . . . . . . 50 88 7.4.4. Certificate Request . . . . . . . . . . . . . . . . . 53 89 7.4.5. Server Hello Done . . . . . . . . . . . . . . . . . . 55 90 7.4.6. Client Certificate . . . . . . . . . . . . . . . . . 56 91 7.4.7. Client Key Exchange Message . . . . . . . . . . . . . 57 92 7.4.8. Certificate Verify . . . . . . . . . . . . . . . . . 62 93 7.4.9. Finished . . . . . . . . . . . . . . . . . . . . . . 63 94 8. Cryptographic Computations . . . . . . . . . . . . . . . . . 65 95 8.1. Computing the Master Secret . . . . . . . . . . . . . . . 65 96 8.1.1. RSA . . . . . . . . . . . . . . . . . . . . . . . . . 65 97 8.1.2. Diffie-Hellman . . . . . . . . . . . . . . . . . . . 66 98 9. Mandatory Cipher Suites . . . . . . . . . . . . . . . . . . . 66 99 10. Application Data Protocol . . . . . . . . . . . . . . . . . . 66 100 11. Security Considerations . . . . . . . . . . . . . . . . . . . 66 101 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 66 102 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 103 13.1. Normative References . . . . . . . . . . . . . . . . . . 68 104 13.2. Informative References . . . . . . . . . . . . . . . . . 69 105 Appendix A. Protocol Data Structures and Constant Values . . . . 72 106 A.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 72 107 A.2. Change Cipher Specs Message . . . . . . . . . . . . . . . 73 108 A.3. Alert Messages . . . . . . . . . . . . . . . . . . . . . 74 109 A.4. Handshake Protocol . . . . . . . . . . . . . . . . . . . 75 110 A.4.1. Hello Messages . . . . . . . . . . . . . . . . . . . 75 111 A.4.2. Server Authentication and Key Exchange Messages . . . 77 112 A.4.3. Client Authentication and Key Exchange Messages . . . 78 113 A.4.4. Handshake Finalization Message . . . . . . . . . . . 79 114 A.5. The Cipher Suite . . . . . . . . . . . . . . . . . . . . 79 115 A.6. The Security Parameters . . . . . . . . . . . . . . . . . 81 116 A.7. Changes to RFC 4492 . . . . . . . . . . . . . . . . . . . 82 117 Appendix B. Glossary . . . . . . . . . . . . . . . . . . . . . . 82 118 Appendix C. Cipher Suite Definitions . . . . . . . . . . . . . . 86 119 Appendix D. Implementation Notes . . . . . . . . . . . . . . . . 88 120 D.1. Random Number Generation and Seeding . . . . . . . . . . 88 121 D.2. Certificates and Authentication . . . . . . . . . . . . . 88 122 D.3. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 89 123 D.4. Implementation Pitfalls . . . . . . . . . . . . . . . . . 89 124 Appendix E. Backward Compatibility . . . . . . . . . . . . . . . 90 125 E.1. Compatibility with TLS 1.0/1.1 and SSL 3.0 . . . . . . . 90 126 E.2. Compatibility with SSL 2.0 . . . . . . . . . . . . . . . 92 127 E.3. Avoiding Man-in-the-Middle Version Rollback . . . . . . . 93 128 Appendix F. Security Analysis . . . . . . . . . . . . . . . . . 94 129 F.1. Handshake Protocol . . . . . . . . . . . . . . . . . . . 94 130 F.1.1. Authentication and Key Exchange . . . . . . . . . . . 94 131 F.1.2. Version Rollback Attacks . . . . . . . . . . . . . . 97 132 F.1.3. Detecting Attacks Against the Handshake Protocol . . 97 133 F.1.4. Resuming Sessions . . . . . . . . . . . . . . . . . . 97 134 F.2. Protecting Application Data . . . . . . . . . . . . . . . 98 135 F.3. Explicit IVs . . . . . . . . . . . . . . . . . . . . . . 98 136 F.4. Security of Composite Cipher Modes . . . . . . . . . . . 98 137 F.5. Denial of Service . . . . . . . . . . . . . . . . . . . . 99 138 F.6. Final Notes . . . . . . . . . . . . . . . . . . . . . . . 100 139 Appendix G. Working Group Information . . . . . . . . . . . . . 100 140 Appendix H. Contributors . . . . . . . . . . . . . . . . . . . . 100 142 1. Introduction 144 DISCLAIMER: This document is simply a copy of RFC 5246 translated 145 into markdown format with no intentional technical or editorial 146 changes beyond updating the references and minor reformatting 147 introduced by the translation. It is being submitted as-is to create 148 a clearer revision history for future versions. Any errata in TLS 149 1.2 remain in this version. Thanks to Mark Nottingham for doing the 150 markdown translation. 152 The primary goal of the TLS protocol is to provide privacy and data 153 integrity between two communicating applications. The protocol is 154 composed of two layers: the TLS Record Protocol and the TLS Handshake 155 Protocol. At the lowest level, layered on top of some reliable 156 transport protocol (e.g., TCP [RFC0793]), is the TLS Record Protocol. 157 The TLS Record Protocol provides connection security that has two 158 basic properties: 160 - The connection is private. Symmetric cryptography is used for 161 data encryption (e.g., AES [AES], RC4 [SCH], etc.). The keys for 162 this symmetric encryption are generated uniquely for each 163 connection and are based on a secret negotiated by another 164 protocol (such as the TLS Handshake Protocol). The Record 165 Protocol can also be used without encryption. 167 - The connection is reliable. Message transport includes a message 168 integrity check using a keyed MAC. Secure hash functions (e.g., 169 SHA-1, etc.) are used for MAC computations. The Record Protocol 170 can operate without a MAC, but is generally only used in this mode 171 while another protocol is using the Record Protocol as a transport 172 for negotiating security parameters. 174 The TLS Record Protocol is used for encapsulation of various higher- 175 level protocols. One such encapsulated protocol, the TLS Handshake 176 Protocol, allows the server and client to authenticate each other and 177 to negotiate an encryption algorithm and cryptographic keys before 178 the application protocol transmits or receives its first byte of 179 data. The TLS Handshake Protocol provides connection security that 180 has three basic properties: 182 - The peer's identity can be authenticated using asymmetric, or 183 public key, cryptography (e.g., RSA [RSA], DSA [DSS], etc.). This 184 authentication can be made optional, but is generally required for 185 at least one of the peers. 187 - The negotiation of a shared secret is secure: the negotiated 188 secret is unavailable to eavesdroppers, and for any authenticated 189 connection the secret cannot be obtained, even by an attacker who 190 can place himself in the middle of the connection. 192 - The negotiation is reliable: no attacker can modify the 193 negotiation communication without being detected by the parties to 194 the communication. 196 One advantage of TLS is that it is application protocol independent. 197 Higher-level protocols can layer on top of the TLS protocol 198 transparently. The TLS standard, however, does not specify how 199 protocols add security with TLS; the decisions on how to initiate TLS 200 handshaking and how to interpret the authentication certificates 201 exchanged are left to the judgment of the designers and implementors 202 of protocols that run on top of TLS. 204 1.1. Requirements Terminology 206 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 207 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 208 document are to be interpreted as described in RFC 2119 [RFC2119]. 210 1.2. Major Differences from TLS 1.1 212 This document is a revision of the TLS 1.1 [RFC4346] protocol which 213 contains improved flexibility, particularly for negotiation of 214 cryptographic algorithms. The major changes are: 216 - The MD5/SHA-1 combination in the pseudorandom function (PRF) has 217 been replaced with cipher-suite-specified PRFs. All cipher suites 218 in this document use P_SHA256. 220 - The MD5/SHA-1 combination in the digitally-signed element has been 221 replaced with a single hash. Signed elements now include a field 222 that explicitly specifies the hash algorithm used. 224 - Substantial cleanup to the client's and server's ability to 225 specify which hash and signature algorithms they will accept. 226 Note that this also relaxes some of the constraints on signature 227 and hash algorithms from previous versions of TLS. 229 - Addition of support for authenticated encryption with additional 230 data modes. 232 - TLS Extensions definition and AES Cipher Suites were merged in 233 from external [TLSEXT] and [RFC3268]. 235 - Tighter checking of EncryptedPreMasterSecret version numbers. 237 - Tightened up a number of requirements. 239 - Verify_data length now depends on the cipher suite (default is 240 still 12). 242 - Cleaned up description of Bleichenbacher/Klima attack defenses. 244 - Alerts MUST now be sent in many cases. 246 - After a certificate_request, if no certificates are available, 247 clients now MUST send an empty certificate list. 249 - TLS_RSA_WITH_AES_128_CBC_SHA is now the mandatory to implement 250 cipher suite. 252 - Added HMAC-SHA256 cipher suites. 254 - Removed IDEA and DES cipher suites. They are now deprecated and 255 will be documented in a separate document. 257 - Support for the SSLv2 backward-compatible hello is now a MAY, not 258 a SHOULD, with sending it a SHOULD NOT. Support will probably 259 become a SHOULD NOT in the future. 261 - Added limited "fall-through" to the presentation language to allow 262 multiple case arms to have the same encoding. 264 - Added an Implementation Pitfalls sections 266 - The usual clarifications and editorial work. 268 2. Goals 270 The goals of the TLS protocol, in order of priority, are as follows: 272 1. Cryptographic security: TLS should be used to establish a secure 273 connection between two parties. 275 2. Interoperability: Independent programmers should be able to 276 develop applications utilizing TLS that can successfully exchange 277 cryptographic parameters without knowledge of one another's code. 279 3. Extensibility: TLS seeks to provide a framework into which new 280 public key and bulk encryption methods can be incorporated as 281 necessary. This will also accomplish two sub-goals: preventing 282 the need to create a new protocol (and risking the introduction 283 of possible new weaknesses) and avoiding the need to implement an 284 entire new security library. 286 4. Relative efficiency: Cryptographic operations tend to be highly 287 CPU intensive, particularly public key operations. For this 288 reason, the TLS protocol has incorporated an optional session 289 caching scheme to reduce the number of connections that need to 290 be established from scratch. Additionally, care has been taken 291 to reduce network activity. 293 3. Goals of This Document 295 This document and the TLS protocol itself are based on the SSL 3.0 296 Protocol Specification as published by Netscape. The differences 297 between this protocol and SSL 3.0 are not dramatic, but they are 298 significant enough that the various versions of TLS and SSL 3.0 do 299 not interoperate (although each protocol incorporates a mechanism by 300 which an implementation can back down to prior versions). This 301 document is intended primarily for readers who will be implementing 302 the protocol and for those doing cryptographic analysis of it. The 303 specification has been written with this in mind, and it is intended 304 to reflect the needs of those two groups. For that reason, many of 305 the algorithm-dependent data structures and rules are included in the 306 body of the text (as opposed to in an appendix), providing easier 307 access to them. 309 This document is not intended to supply any details of service 310 definition or of interface definition, although it does cover select 311 areas of policy as they are required for the maintenance of solid 312 security. 314 4. Presentation Language 316 This document deals with the formatting of data in an external 317 representation. The following very basic and somewhat casually 318 defined presentation syntax will be used. The syntax draws from 319 several sources in its structure. Although it resembles the 320 programming language "C" in its syntax and XDR [RFC4506] in both its 321 syntax and intent, it would be risky to draw too many parallels. The 322 purpose of this presentation language is to document TLS only; it has 323 no general application beyond that particular goal. 325 4.1. Basic Block Size 327 The representation of all data items is explicitly specified. The 328 basic data block size is one byte (i.e., 8 bits). Multiple byte data 329 items are concatenations of bytes, from left to right, from top to 330 bottom. From the byte stream, a multi-byte item (a numeric in the 331 example) is formed (using C notation) by: 333 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 334 ... | byte[n-1]; 336 This byte ordering for multi-byte values is the commonplace network 337 byte order or big-endian format. 339 4.2. Miscellaneous 341 Comments begin with "/*" and end with "*/". 343 Optional components are denoted by enclosing them in "[[ ]]" double 344 brackets. 346 Single-byte entities containing uninterpreted data are of type 347 opaque. 349 4.3. Vectors 351 A vector (single-dimensioned array) is a stream of homogeneous data 352 elements. The size of the vector may be specified at documentation 353 time or left unspecified until runtime. In either case, the length 354 declares the number of bytes, not the number of elements, in the 355 vector. The syntax for specifying a new type, T', that is a fixed- 356 length vector of type T is 358 T T'[n]; 360 Here, T' occupies n bytes in the data stream, where n is a multiple 361 of the size of T. The length of the vector is not included in the 362 encoded stream. 364 In the following example, Datum is defined to be three consecutive 365 bytes that the protocol does not interpret, while Data is three 366 consecutive Datum, consuming a total of nine bytes. 368 opaque Datum[3]; /* three uninterpreted bytes */ 369 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 371 Variable-length vectors are defined by specifying a subrange of legal 372 lengths, inclusively, using the notation . When 373 these are encoded, the actual length precedes the vector's contents 374 in the byte stream. The length will be in the form of a number 375 consuming as many bytes as required to hold the vector's specified 376 maximum (ceiling) length. A variable-length vector with an actual 377 length field of zero is referred to as an empty vector. 379 T T'; 381 In the following example, mandatory is a vector that must contain 382 between 300 and 400 bytes of type opaque. It can never be empty. 383 The actual length field consumes two bytes, a uint16, which is 384 sufficient to represent the value 400 (see Section 4.4). On the 385 other hand, longer can represent up to 800 bytes of data, or 400 386 uint16 elements, and it may be empty. Its encoding will include a 387 two-byte actual length field prepended to the vector. The length of 388 an encoded vector must be an even multiple of the length of a single 389 element (for example, a 17-byte vector of uint16 would be illegal). 391 opaque mandatory<300..400>; 392 /* length field is 2 bytes, cannot be empty */ 393 uint16 longer<0..800>; 394 /* zero to 400 16-bit unsigned integers */ 396 4.4. Numbers 398 The basic numeric data type is an unsigned byte (uint8). All larger 399 numeric data types are formed from fixed-length series of bytes 400 concatenated as described in Section 4.1 and are also unsigned. The 401 following numeric types are predefined. 403 uint8 uint16[2]; 404 uint8 uint24[3]; 405 uint8 uint32[4]; 406 uint8 uint64[8]; 408 All values, here and elsewhere in the specification, are stored in 409 network byte (big-endian) order; the uint32 represented by the hex 410 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 412 Note that in some cases (e.g., DH parameters) it is necessary to 413 represent integers as opaque vectors. In such cases, they are 414 represented as unsigned integers (i.e., leading zero octets are not 415 required even if the most significant bit is set). 417 4.5. Enumerateds 419 An additional sparse data type is available called enum. A field of 420 type enum can only assume the values declared in the definition. 421 Each definition is a different type. Only enumerateds of the same 422 type may be assigned or compared. Every element of an enumerated 423 must be assigned a value, as demonstrated in the following example. 424 Since the elements of the enumerated are not ordered, they can be 425 assigned any unique value, in any order. 427 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 429 An enumerated occupies as much space in the byte stream as would its 430 maximal defined ordinal value. The following definition would cause 431 one byte to be used to carry fields of type Color. 433 enum { red(3), blue(5), white(7) } Color; 435 One may optionally specify a value without its associated tag to 436 force the width definition without defining a superfluous element. 438 In the following example, Taste will consume two bytes in the data 439 stream but can only assume the values 1, 2, or 4. 441 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 443 The names of the elements of an enumeration are scoped within the 444 defined type. In the first example, a fully qualified reference to 445 the second element of the enumeration would be Color.blue. Such 446 qualification is not required if the target of the assignment is well 447 specified. 449 Color color = Color.blue; /* overspecified, legal */ 450 Color color = blue; /* correct, type implicit */ 452 For enumerateds that are never converted to external representation, 453 the numerical information may be omitted. 455 enum { low, medium, high } Amount; 457 4.6. Constructed Types 459 Structure types may be constructed from primitive types for 460 convenience. Each specification declares a new, unique type. The 461 syntax for definition is much like that of C. 463 struct { 464 T1 f1; 465 T2 f2; 466 ... 467 Tn fn; 468 } [[T]]; 470 The fields within a structure may be qualified using the type's name, 471 with a syntax much like that available for enumerateds. For example, 472 T.f2 refers to the second field of the previous declaration. 473 Structure definitions may be embedded. 475 4.6.1. Variants 477 Defined structures may have variants based on some knowledge that is 478 available within the environment. The selector must be an enumerated 479 type that defines the possible variants the structure defines. There 480 must be a case arm for every element of the enumeration declared in 481 the select. Case arms have limited fall-through: if two case arms 482 follow in immediate succession with no fields in between, then they 483 both contain the same fields. Thus, in the example below, "orange" 484 and "banana" both contain V2. Note that this is a new piece of 485 syntax in TLS 1.2. 487 The body of the variant structure may be given a label for reference. 488 The mechanism by which the variant is selected at runtime is not 489 prescribed by the presentation language. 491 struct { 492 T1 f1; 493 T2 f2; 494 .... 495 Tn fn; 496 select (E) { 497 case e1: Te1; 498 case e2: Te2; 499 case e3: case e4: Te3; 500 .... 501 case en: Ten; 502 } [[fv]]; 503 } [[Tv]]; 505 For example: 507 enum { apple, orange, banana } VariantTag; 509 struct { 510 uint16 number; 511 opaque string<0..10>; /* variable length */ 512 } V1; 514 struct { 515 uint32 number; 516 opaque string[10]; /* fixed length */ 517 } V2; 519 struct { 520 select (VariantTag) { /* value of selector is implicit */ 521 case apple: 522 V1; /* VariantBody, tag = apple */ 523 case orange: 524 case banana: 525 V2; /* VariantBody, tag = orange or banana */ 526 } variant_body; /* optional label on variant */ 527 } VariantRecord; 529 4.7. Cryptographic Attributes 531 The five cryptographic operations -- digital signing, stream cipher 532 encryption, block cipher encryption, authenticated encryption with 533 additional data (AEAD) encryption, and public key encryption -- are 534 designated digitally-signed, stream-ciphered, block-ciphered, aead- 535 ciphered, and public-key-encrypted, respectively. A field's 536 cryptographic processing is specified by prepending an appropriate 537 key word designation before the field's type specification. 538 Cryptographic keys are implied by the current session state (see 539 Section 6.1). 541 A digitally-signed element is encoded as a struct DigitallySigned: 543 struct { 544 SignatureAndHashAlgorithm algorithm; 545 opaque signature<0..2^16-1>; 546 } DigitallySigned; 548 The algorithm field specifies the algorithm used (see 549 Section 7.4.1.4.1 for the definition of this field). Note that the 550 introduction of the algorithm field is a change from previous 551 versions. The signature is a digital signature using those 552 algorithms over the contents of the element. The contents themselves 553 do not appear on the wire but are simply calculated. The length of 554 the signature is specified by the signing algorithm and key. 556 In RSA signing, the opaque vector contains the signature generated 557 using the RSASSA-PKCS1-v1_5 signature scheme defined in [RFC3447]. 558 As discussed in [RFC3447], the DigestInfo MUST be DER-encoded [X680] 559 [X690]. For hash algorithms without parameters (which includes 560 SHA-1), the DigestInfo.AlgorithmIdentifier.parameters field MUST be 561 NULL, but implementations MUST accept both without parameters and 562 with NULL parameters. Note that earlier versions of TLS used a 563 different RSA signature scheme that did not include a DigestInfo 564 encoding. 566 In DSA, the 20 bytes of the SHA-1 hash are run directly through the 567 Digital Signing Algorithm with no additional hashing. This produces 568 two values, r and s. The DSA signature is an opaque vector, as 569 above, the contents of which are the DER encoding of: 571 Dss-Sig-Value ::= SEQUENCE { 572 r INTEGER, 573 s INTEGER 574 } 576 Note: In current terminology, DSA refers to the Digital Signature 577 Algorithm and DSS refers to the NIST standard. In the original SSL 578 and TLS specs, "DSS" was used universally. This document uses "DSA" 579 to refer to the algorithm, "DSS" to refer to the standard, and it 580 uses "DSS" in the code point definitions for historical continuity. 582 In stream cipher encryption, the plaintext is exclusive-ORed with an 583 identical amount of output generated from a cryptographically secure 584 keyed pseudorandom number generator. 586 In block cipher encryption, every block of plaintext encrypts to a 587 block of ciphertext. All block cipher encryption is done in CBC 588 (Cipher Block Chaining) mode, and all items that are block-ciphered 589 will be an exact multiple of the cipher block length. 591 In AEAD encryption, the plaintext is simultaneously encrypted and 592 integrity protected. The input may be of any length, and aead- 593 ciphered output is generally larger than the input in order to 594 accommodate the integrity check value. 596 In public key encryption, a public key algorithm is used to encrypt 597 data in such a way that it can be decrypted only with the matching 598 private key. A public-key-encrypted element is encoded as an opaque 599 vector <0..2^16-1>, where the length is specified by the encryption 600 algorithm and key. 602 RSA encryption is done using the RSAES-PKCS1-v1_5 encryption scheme 603 defined in [RFC3447]. 605 In the following example 607 stream-ciphered struct { 608 uint8 field1; 609 uint8 field2; 610 digitally-signed opaque { 611 uint8 field3<0..255>; 612 uint8 field4; 613 }; 614 } UserType; 616 The contents of the inner struct (field3 and field4) are used as 617 input for the signature/hash algorithm, and then the entire structure 618 is encrypted with a stream cipher. The length of this structure, in 619 bytes, would be equal to two bytes for field1 and field2, plus two 620 bytes for the signature and hash algorithm, plus two bytes for the 621 length of the signature, plus the length of the output of the signing 622 algorithm. The length of the signature is known because the 623 algorithm and key used for the signing are known prior to encoding or 624 decoding this structure. 626 4.8. Constants 628 Typed constants can be defined for purposes of specification by 629 declaring a symbol of the desired type and assigning values to it. 631 Under-specified types (opaque, variable-length vectors, and 632 structures that contain opaque) cannot be assigned values. No fields 633 of a multi-element structure or vector may be elided. 635 For example: 637 struct { 638 uint8 f1; 639 uint8 f2; 640 } Example1; 642 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 644 5. HMAC and the Pseudorandom Function 646 The TLS record layer uses a keyed Message Authentication Code (MAC) 647 to protect message integrity. The cipher suites defined in this 648 document use a construction known as HMAC, described in [RFC2104], 649 which is based on a hash function. Other cipher suites MAY define 650 their own MAC constructions, if needed. 652 In addition, a construction is required to do expansion of secrets 653 into blocks of data for the purposes of key generation or validation. 654 This pseudorandom function (PRF) takes as input a secret, a seed, and 655 an identifying label and produces an output of arbitrary length. 657 In this section, we define one PRF, based on HMAC. This PRF with the 658 SHA-256 hash function is used for all cipher suites defined in this 659 document and in TLS documents published prior to this document when 660 TLS 1.2 is negotiated. New cipher suites MUST explicitly specify a 661 PRF and, in general, SHOULD use the TLS PRF with SHA-256 or a 662 stronger standard hash function. 664 First, we define a data expansion function, P_hash(secret, data), 665 that uses a single hash function to expand a secret and seed into an 666 arbitrary quantity of output: 668 P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) + 669 HMAC_hash(secret, A(2) + seed) + 670 HMAC_hash(secret, A(3) + seed) + ... 672 where + indicates concatenation. 674 A() is defined as: 676 A(0) = seed 677 A(i) = HMAC_hash(secret, A(i-1)) 679 P_hash can be iterated as many times as necessary to produce the 680 required quantity of data. For example, if P_SHA256 is being used to 681 create 80 bytes of data, it will have to be iterated three times 682 (through A(3)), creating 96 bytes of output data; the last 16 bytes 683 of the final iteration will then be discarded, leaving 80 bytes of 684 output data. 686 TLS's PRF is created by applying P_hash to the secret as: 688 PRF(secret, label, seed) = P_(secret, label + seed) 690 The label is an ASCII string. It should be included in the exact 691 form it is given without a length byte or trailing null character. 692 For example, the label "slithy toves" would be processed by hashing 693 the following bytes: 695 73 6C 69 74 68 79 20 74 6F 76 65 73 697 6. The TLS Record Protocol 699 The TLS Record Protocol is a layered protocol. At each layer, 700 messages may include fields for length, description, and content. 701 The Record Protocol takes messages to be transmitted, fragments the 702 data into manageable blocks, optionally compresses the data, applies 703 a MAC, encrypts, and transmits the result. Received data is 704 decrypted, verified, decompressed, reassembled, and then delivered to 705 higher-level clients. 707 Four protocols that use the record protocol are described in this 708 document: the handshake protocol, the alert protocol, the change 709 cipher spec protocol, and the application data protocol. In order to 710 allow extension of the TLS protocol, additional record content types 711 can be supported by the record protocol. New record content type 712 values are assigned by IANA in the TLS Content Type Registry as 713 described in Section 12. 715 Implementations MUST NOT send record types not defined in this 716 document unless negotiated by some extension. If a TLS 717 implementation receives an unexpected record type, it MUST send an 718 unexpected_message alert. 720 Any protocol designed for use over TLS must be carefully designed to 721 deal with all possible attacks against it. As a practical matter, 722 this means that the protocol designer must be aware of what security 723 properties TLS does and does not provide and cannot safely rely on 724 the latter. 726 Note in particular that type and length of a record are not protected 727 by encryption. If this information is itself sensitive, application 728 designers may wish to take steps (padding, cover traffic) to minimize 729 information leakage. 731 6.1. Connection States 733 A TLS connection state is the operating environment of the TLS Record 734 Protocol. It specifies a compression algorithm, an encryption 735 algorithm, and a MAC algorithm. In addition, the parameters for 736 these algorithms are known: the MAC key and the bulk encryption keys 737 for the connection in both the read and the write directions. 738 Logically, there are always four connection states outstanding: the 739 current read and write states, and the pending read and write states. 740 All records are processed under the current read and write states. 741 The security parameters for the pending states can be set by the TLS 742 Handshake Protocol, and the ChangeCipherSpec can selectively make 743 either of the pending states current, in which case the appropriate 744 current state is disposed of and replaced with the pending state; the 745 pending state is then reinitialized to an empty state. It is illegal 746 to make a state that has not been initialized with security 747 parameters a current state. The initial current state always 748 specifies that no encryption, compression, or MAC will be used. 750 The security parameters for a TLS Connection read and write state are 751 set by providing the following values: 753 connection end 754 Whether this entity is considered the "client" or the "server" in 755 this connection. 757 PRF algorithm 758 An algorithm used to generate keys from the master secret (see 759 Section 5 and Section 6.3). 761 bulk encryption algorithm 762 An algorithm to be used for bulk encryption. This specification 763 includes the key size of this algorithm, whether it is a block, 764 stream, or AEAD cipher, the block size of the cipher (if 765 appropriate), and the lengths of explicit and implicit 766 initialization vectors (or nonces). 768 MAC algorithm 769 An algorithm to be used for message authentication. This 770 specification includes the size of the value returned by the MAC 771 algorithm. 773 compression algorithm 774 An algorithm to be used for data compression. This specification 775 must include all information the algorithm requires to do 776 compression. 778 master secret 779 A 48-byte secret shared between the two peers in the connection. 781 client random 782 A 32-byte value provided by the client. 784 server random 785 A 32-byte value provided by the server. 787 These parameters are defined in the presentation language as: 789 enum { server, client } ConnectionEnd; 791 enum { tls_prf_sha256 } PRFAlgorithm; 793 enum { null, rc4, 3des, aes } 794 BulkCipherAlgorithm; 796 enum { stream, block, aead } CipherType; 798 enum { null, hmac_md5, hmac_sha1, hmac_sha256, 799 hmac_sha384, hmac_sha512} MACAlgorithm; 801 enum { null(0), (255) } CompressionMethod; 803 /* The algorithms specified in CompressionMethod, PRFAlgorithm, 804 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 806 struct { 807 ConnectionEnd entity; 808 PRFAlgorithm prf_algorithm; 809 BulkCipherAlgorithm bulk_cipher_algorithm; 810 CipherType cipher_type; 811 uint8 enc_key_length; 812 uint8 block_length; 813 uint8 fixed_iv_length; 814 uint8 record_iv_length; 815 MACAlgorithm mac_algorithm; 816 uint8 mac_length; 817 uint8 mac_key_length; 818 CompressionMethod compression_algorithm; 819 opaque master_secret[48]; 820 opaque client_random[32]; 821 opaque server_random[32]; 822 } SecurityParameters; 824 The record layer will use the security parameters to generate the 825 following six items (some of which are not required by all ciphers, 826 and are thus empty): 828 client write MAC key 829 server write MAC key 830 client write encryption key 831 server write encryption key 832 client write IV 833 server write IV 835 The client write parameters are used by the server when receiving and 836 processing records and vice versa. The algorithm used for generating 837 these items from the security parameters is described in Section 6.3 839 Once the security parameters have been set and the keys have been 840 generated, the connection states can be instantiated by making them 841 the current states. These current states MUST be updated for each 842 record processed. Each connection state includes the following 843 elements: 845 compression state 846 The current state of the compression algorithm. 848 cipher state 849 The current state of the encryption algorithm. This will consist 850 of the scheduled key for that connection. For stream ciphers, 851 this will also contain whatever state information is necessary to 852 allow the stream to continue to encrypt or decrypt data. 854 MAC key 855 The MAC key for this connection, as generated above. 857 sequence number 858 Each connection state contains a sequence number, which is 859 maintained separately for read and write states. The sequence 860 number MUST be set to zero whenever a connection state is made the 861 active state. Sequence numbers are of type uint64 and may not 862 exceed 2^64-1. Sequence numbers do not wrap. If a TLS 863 implementation would need to wrap a sequence number, it must 864 renegotiate instead. A sequence number is incremented after each 865 record: specifically, the first record transmitted under a 866 particular connection state MUST use sequence number 0. 868 6.2. Record Layer 870 The TLS record layer receives uninterpreted data from higher layers 871 in non-empty blocks of arbitrary size. 873 6.2.1. Fragmentation 875 The record layer fragments information blocks into TLSPlaintext 876 records carrying data in chunks of 2^14 bytes or less. Client 877 message boundaries are not preserved in the record layer (i.e., 878 multiple client messages of the same ContentType MAY be coalesced 879 into a single TLSPlaintext record, or a single message MAY be 880 fragmented across several records). 882 struct { 883 uint8 major; 884 uint8 minor; 885 } ProtocolVersion; 887 enum { 888 change_cipher_spec(20), alert(21), handshake(22), 889 application_data(23), (255) 890 } ContentType; 892 struct { 893 ContentType type; 894 ProtocolVersion version; 895 uint16 length; 896 opaque fragment[TLSPlaintext.length]; 897 } TLSPlaintext; 899 type 900 The higher-level protocol used to process the enclosed fragment. 902 version 903 The version of the protocol being employed. This document 904 describes TLS Version 1.2, which uses the version { 3, 3 }. The 905 version value 3.3 is historical, deriving from the use of {3, 1} 906 for TLS 1.0. (See Appendix A.1.) Note that a client that 907 supports multiple versions of TLS may not know what version will 908 be employed before it receives the ServerHello. See Appendix E 909 for discussion about what record layer version number should be 910 employed for ClientHello. 912 length 913 The length (in bytes) of the following TLSPlaintext.fragment. The 914 length MUST NOT exceed 2^14. 916 fragment 917 The application data. This data is transparent and treated as an 918 independent block to be dealt with by the higher-level protocol 919 specified by the type field. 921 Implementations MUST NOT send zero-length fragments of Handshake, 922 Alert, or ChangeCipherSpec content types. Zero-length fragments of 923 Application data MAY be sent as they are potentially useful as a 924 traffic analysis countermeasure. 926 Note: Data of different TLS record layer content types MAY be 927 interleaved. Application data is generally of lower precedence for 928 transmission than other content types. However, records MUST be 929 delivered to the network in the same order as they are protected by 930 the record layer. Recipients MUST receive and process interleaved 931 application layer traffic during handshakes subsequent to the first 932 one on a connection. 934 6.2.2. Record Compression and Decompression 936 All records are compressed using the compression algorithm defined in 937 the current session state. There is always an active compression 938 algorithm; however, initially it is defined as 939 CompressionMethod.null. The compression algorithm translates a 940 TLSPlaintext structure into a TLSCompressed structure. Compression 941 functions are initialized with default state information whenever a 942 connection state is made active. [RFC3749] describes compression 943 algorithms for TLS. 945 Compression must be lossless and may not increase the content length 946 by more than 1024 bytes. If the decompression function encounters a 947 TLSCompressed.fragment that would decompress to a length in excess of 948 2^14 bytes, it MUST report a fatal decompression failure error. 950 struct { 951 ContentType type; /* same as TLSPlaintext.type */ 952 ProtocolVersion version;/* same as TLSPlaintext.version */ 953 uint16 length; 954 opaque fragment[TLSCompressed.length]; 955 } TLSCompressed; 957 length 958 The length (in bytes) of the following TLSCompressed.fragment. 959 The length MUST NOT exceed 2^14 + 1024. 961 fragment 962 The compressed form of TLSPlaintext.fragment. 964 Note: A CompressionMethod.null operation is an identity operation; no 965 fields are altered. 967 Implementation note: Decompression functions are responsible for 968 ensuring that messages cannot cause internal buffer overflows. 970 6.2.3. Record Payload Protection 972 The encryption and MAC functions translate a TLSCompressed structure 973 into a TLSCiphertext. The decryption functions reverse the process. 974 The MAC of the record also includes a sequence number so that 975 missing, extra, or repeated messages are detectable. 977 struct { 978 ContentType type; 979 ProtocolVersion version; 980 uint16 length; 981 select (SecurityParameters.cipher_type) { 982 case stream: GenericStreamCipher; 983 case block: GenericBlockCipher; 984 case aead: GenericAEADCipher; 985 } fragment; 986 } TLSCiphertext; 988 type 989 The type field is identical to TLSCompressed.type. 991 version 992 The version field is identical to TLSCompressed.version. 994 length 995 The length (in bytes) of the following TLSCiphertext.fragment. 996 The length MUST NOT exceed 2^14 + 2048. 998 fragment 999 The encrypted form of TLSCompressed.fragment, with the MAC. 1001 6.2.3.1. Null or Standard Stream Cipher 1003 Stream ciphers (including BulkCipherAlgorithm.null; see Appendix A.6) 1004 convert TLSCompressed.fragment structures to and from stream 1005 TLSCiphertext.fragment structures. 1007 stream-ciphered struct { 1008 opaque content[TLSCompressed.length]; 1009 opaque MAC[SecurityParameters.mac_length]; 1010 } GenericStreamCipher; 1012 The MAC is generated as: 1014 MAC(MAC_write_key, seq_num + 1015 TLSCompressed.type + 1016 TLSCompressed.version + 1017 TLSCompressed.length + 1018 TLSCompressed.fragment); 1020 where "+" denotes concatenation. 1022 seq_num 1023 The sequence number for this record. 1025 MAC 1026 The MAC algorithm specified by SecurityParameters.mac_algorithm. 1028 Note that the MAC is computed before encryption. The stream cipher 1029 encrypts the entire block, including the MAC. For stream ciphers 1030 that do not use a synchronization vector (such as RC4), the stream 1031 cipher state from the end of one record is simply used on the 1032 subsequent packet. If the cipher suite is TLS_NULL_WITH_NULL_NULL, 1033 encryption consists of the identity operation (i.e., the data is not 1034 encrypted, and the MAC size is zero, implying that no MAC is used). 1035 For both null and stream ciphers, TLSCiphertext.length is 1036 TLSCompressed.length plus SecurityParameters.mac_length. 1038 6.2.3.2. CBC Block Cipher 1040 For block ciphers (such as 3DES or AES), the encryption and MAC 1041 functions convert TLSCompressed.fragment structures to and from block 1042 TLSCiphertext.fragment structures. 1044 struct { 1045 opaque IV[SecurityParameters.record_iv_length]; 1046 block-ciphered struct { 1047 opaque content[TLSCompressed.length]; 1048 opaque MAC[SecurityParameters.mac_length]; 1049 uint8 padding[GenericBlockCipher.padding_length]; 1050 uint8 padding_length; 1051 }; 1052 } GenericBlockCipher; 1054 The MAC is generated as described in Section 6.2.3.1. 1056 IV 1057 The Initialization Vector (IV) SHOULD be chosen at random, and 1058 MUST be unpredictable. Note that in versions of TLS prior to 1.1, 1059 there was no IV field, and the last ciphertext block of the 1060 previous record (the "CBC residue") was used as the IV. This was 1061 changed to prevent the attacks described in [CBCATT]. For block 1062 ciphers, the IV length is of length 1063 SecurityParameters.record_iv_length, which is equal to the 1064 SecurityParameters.block_size. 1066 padding 1067 Padding that is added to force the length of the plaintext to be 1068 an integral multiple of the block cipher's block length. The 1069 padding MAY be any length up to 255 bytes, as long as it results 1070 in the TLSCiphertext.length being an integral multiple of the 1071 block length. Lengths longer than necessary might be desirable to 1072 frustrate attacks on a protocol that are based on analysis of the 1073 lengths of exchanged messages. Each uint8 in the padding data 1074 vector MUST be filled with the padding length value. The receiver 1075 MUST check this padding and MUST use the bad_record_mac alert to 1076 indicate padding errors. 1078 padding_length 1079 The padding length MUST be such that the total size of the 1080 GenericBlockCipher structure is a multiple of the cipher's block 1081 length. Legal values range from zero to 255, inclusive. This 1082 length specifies the length of the padding field exclusive of the 1083 padding_length field itself. 1085 The encrypted data length (TLSCiphertext.length) is one more than the 1086 sum of SecurityParameters.block_length, TLSCompressed.length, 1087 SecurityParameters.mac_length, and padding_length. 1089 Example: If the block length is 8 bytes, the content length 1090 (TLSCompressed.length) is 61 bytes, and the MAC length is 20 bytes, 1091 then the length before padding is 82 bytes (this does not include the 1092 IV. Thus, the padding length modulo 8 must be equal to 6 in order to 1093 make the total length an even multiple of 8 bytes (the block length). 1094 The padding length can be 6, 14, 22, and so on, through 254. If the 1095 padding length were the minimum necessary, 6, the padding would be 6 1096 bytes, each containing the value 6. Thus, the last 8 octets of the 1097 GenericBlockCipher before block encryption would be xx 06 06 06 06 06 1098 06 06, where xx is the last octet of the MAC. 1100 Note: With block ciphers in CBC mode (Cipher Block Chaining), it is 1101 critical that the entire plaintext of the record be known before any 1102 ciphertext is transmitted. Otherwise, it is possible for the 1103 attacker to mount the attack described in [CBCATT]. 1105 Implementation note: Canvel et al. [CBCTIME] have demonstrated a 1106 timing attack on CBC padding based on the time required to compute 1107 the MAC. In order to defend against this attack, implementations 1108 MUST ensure that record processing time is essentially the same 1109 whether or not the padding is correct. In general, the best way to 1110 do this is to compute the MAC even if the padding is incorrect, and 1111 only then reject the packet. For instance, if the pad appears to be 1112 incorrect, the implementation might assume a zero-length pad and then 1113 compute the MAC. This leaves a small timing channel, since MAC 1114 performance depends to some extent on the size of the data fragment, 1115 but it is not believed to be large enough to be exploitable, due to 1116 the large block size of existing MACs and the small size of the 1117 timing signal. 1119 6.2.3.3. AEAD Ciphers 1121 For AEAD [RFC5116] ciphers (such as [CCM] or [GCM]), the AEAD 1122 function converts TLSCompressed.fragment structures to and from AEAD 1123 TLSCiphertext.fragment structures. 1125 struct { 1126 opaque nonce_explicit[SecurityParameters.record_iv_length]; 1127 aead-ciphered struct { 1128 opaque content[TLSCompressed.length]; 1129 }; 1130 } GenericAEADCipher; 1132 AEAD ciphers take as input a single key, a nonce, a plaintext, and 1133 "additional data" to be included in the authentication check, as 1134 described in Section 2.1 of [RFC5116]. The key is either the 1135 client_write_key or the server_write_key. No MAC key is used. 1137 Each AEAD cipher suite MUST specify how the nonce supplied to the 1138 AEAD operation is constructed, and what is the length of the 1139 GenericAEADCipher.nonce_explicit part. In many cases, it is 1140 appropriate to use the partially implicit nonce technique described 1141 in Section 3.2.1 of [RFC5116]; with record_iv_length being the length 1142 of the explicit part. In this case, the implicit part SHOULD be 1143 derived from key_block as client_write_iv and server_write_iv (as 1144 described in Section 6.3), and the explicit part is included in 1145 GenericAEAEDCipher.nonce_explicit. 1147 The plaintext is the TLSCompressed.fragment. 1149 The additional authenticated data, which we denote as 1150 additional_data, is defined as follows: 1152 additional_data = seq_num + TLSCompressed.type + 1153 TLSCompressed.version + TLSCompressed.length; 1155 where "+" denotes concatenation. 1157 The aead_output consists of the ciphertext output by the AEAD 1158 encryption operation. The length will generally be larger than 1159 TLSCompressed.length, but by an amount that varies with the AEAD 1160 cipher. Since the ciphers might incorporate padding, the amount of 1161 overhead could vary with different TLSCompressed.length values. Each 1162 AEAD cipher MUST NOT produce an expansion of greater than 1024 bytes. 1163 Symbolically, 1165 AEADEncrypted = AEAD-Encrypt(write_key, nonce, plaintext, 1166 additional_data) 1168 In order to decrypt and verify, the cipher takes as input the key, 1169 nonce, the "additional_data", and the AEADEncrypted value. The 1170 output is either the plaintext or an error indicating that the 1171 decryption failed. There is no separate integrity check. That is: 1173 TLSCompressed.fragment = AEAD-Decrypt(write_key, nonce, 1174 AEADEncrypted, 1175 additional_data) 1177 If the decryption fails, a fatal bad_record_mac alert MUST be 1178 generated. 1180 6.3. Key Calculation 1182 The Record Protocol requires an algorithm to generate keys required 1183 by the current connection state (see Appendix A.6) from the security 1184 parameters provided by the handshake protocol. 1186 The master secret is expanded into a sequence of secure bytes, which 1187 is then split to a client write MAC key, a server write MAC key, a 1188 client write encryption key, and a server write encryption key. Each 1189 of these is generated from the byte sequence in that order. Unused 1190 values are empty. Some AEAD ciphers may additionally require a 1191 client write IV and a server write IV (see Section 6.2.3.3). 1193 When keys and MAC keys are generated, the master secret is used as an 1194 entropy source. 1196 To generate the key material, compute 1198 key_block = PRF(SecurityParameters.master_secret, 1199 "key expansion", 1200 SecurityParameters.server_random + 1201 SecurityParameters.client_random); 1203 until enough output has been generated. Then, the key_block is 1204 partitioned as follows: 1206 client_write_MAC_key[SecurityParameters.mac_key_length] 1207 server_write_MAC_key[SecurityParameters.mac_key_length] 1208 client_write_key[SecurityParameters.enc_key_length] 1209 server_write_key[SecurityParameters.enc_key_length] 1210 client_write_IV[SecurityParameters.fixed_iv_length] 1211 server_write_IV[SecurityParameters.fixed_iv_length] 1213 Currently, the client_write_IV and server_write_IV are only generated 1214 for implicit nonce techniques as described in Section 3.2.1 of 1215 [RFC5116]. 1217 Implementation note: The currently defined cipher suite which 1218 requires the most material is AES_256_CBC_SHA256. It requires 2 x 32 1219 byte keys and 2 x 32 byte MAC keys, for a total 128 bytes of key 1220 material. 1222 7. The TLS Handshaking Protocols 1224 TLS has three subprotocols that are used to allow peers to agree upon 1225 security parameters for the record layer, to authenticate themselves, 1226 to instantiate negotiated security parameters, and to report error 1227 conditions to each other. 1229 The Handshake Protocol is responsible for negotiating a session, 1230 which consists of the following items: 1232 session identifier 1233 An arbitrary byte sequence chosen by the server to identify an 1234 active or resumable session state. 1236 peer certificate 1237 X509v3 [RFC3280] certificate of the peer. This element of the 1238 state may be null. 1240 compression method 1241 The algorithm used to compress data prior to encryption. 1243 cipher spec 1244 Specifies the pseudorandom function (PRF) used to generate keying 1245 material, the bulk data encryption algorithm (such as null, AES, 1246 etc.) and the MAC algorithm (such as HMAC-SHA1). It also defines 1247 cryptographic attributes such as the mac_length. (See 1248 Appendix A.6 for formal definition.) 1250 master secret 1251 48-byte secret shared between the client and server. 1253 is resumable 1254 A flag indicating whether the session can be used to initiate new 1255 connections. 1257 These items are then used to create security parameters for use by 1258 the record layer when protecting application data. Many connections 1259 can be instantiated using the same session through the resumption 1260 feature of the TLS Handshake Protocol. 1262 7.1. Change Cipher Spec Protocol 1264 The change cipher spec protocol exists to signal transitions in 1265 ciphering strategies. The protocol consists of a single message, 1266 which is encrypted and compressed under the current (not the pending) 1267 connection state. The message consists of a single byte of value 1. 1269 struct { 1270 enum { change_cipher_spec(1), (255) } type; 1271 } ChangeCipherSpec; 1273 The ChangeCipherSpec message is sent by both the client and the 1274 server to notify the receiving party that subsequent records will be 1275 protected under the newly negotiated CipherSpec and keys. Reception 1276 of this message causes the receiver to instruct the record layer to 1277 immediately copy the read pending state into the read current state. 1278 Immediately after sending this message, the sender MUST instruct the 1279 record layer to make the write pending state the write active state. 1280 (See Section 6.1.) The ChangeCipherSpec message is sent during the 1281 handshake after the security parameters have been agreed upon, but 1282 before the verifying Finished message is sent. 1284 Note: If a rehandshake occurs while data is flowing on a connection, 1285 the communicating parties may continue to send data using the old 1286 CipherSpec. However, once the ChangeCipherSpec has been sent, the 1287 new CipherSpec MUST be used. The first side to send the 1288 ChangeCipherSpec does not know that the other side has finished 1289 computing the new keying material (e.g., if it has to perform a time- 1290 consuming public key operation). Thus, a small window of time, 1291 during which the recipient must buffer the data, MAY exist. In 1292 practice, with modern machines this interval is likely to be fairly 1293 short. 1295 7.2. Alert Protocol 1297 One of the content types supported by the TLS record layer is the 1298 alert type. Alert messages convey the severity of the message 1299 (warning or fatal) and a description of the alert. Alert messages 1300 with a level of fatal result in the immediate termination of the 1301 connection. In this case, other connections corresponding to the 1302 session may continue, but the session identifier MUST be invalidated, 1303 preventing the failed session from being used to establish new 1304 connections. Like other messages, alert messages are encrypted and 1305 compressed, as specified by the current connection state. 1307 enum { warning(1), fatal(2), (255) } AlertLevel; 1309 enum { 1310 close_notify(0), 1311 unexpected_message(10), 1312 bad_record_mac(20), 1313 decryption_failed_RESERVED(21), 1314 record_overflow(22), 1315 decompression_failure(30), 1316 handshake_failure(40), 1317 no_certificate_RESERVED(41), 1318 bad_certificate(42), 1319 unsupported_certificate(43), 1320 certificate_revoked(44), 1321 certificate_expired(45), 1322 certificate_unknown(46), 1323 illegal_parameter(47), 1324 unknown_ca(48), 1325 access_denied(49), 1326 decode_error(50), 1327 decrypt_error(51), 1328 export_restriction_RESERVED(60), 1329 protocol_version(70), 1330 insufficient_security(71), 1331 internal_error(80), 1332 user_canceled(90), 1333 no_renegotiation(100), 1334 unsupported_extension(110), 1335 (255) 1336 } AlertDescription; 1338 struct { 1339 AlertLevel level; 1340 AlertDescription description; 1341 } Alert; 1343 7.2.1. Closure Alerts 1345 The client and the server must share knowledge that the connection is 1346 ending in order to avoid a truncation attack. Either party may 1347 initiate the exchange of closing messages. 1349 close_notify 1350 This message notifies the recipient that the sender will not send 1351 any more messages on this connection. Note that as of TLS 1.1, 1352 failure to properly close a connection no longer requires that a 1353 session not be resumed. This is a change from TLS 1.0 to conform 1354 with widespread implementation practice. 1356 Either party may initiate a close by sending a close_notify alert. 1357 Any data received after a closure alert is ignored. 1359 Unless some other fatal alert has been transmitted, each party is 1360 required to send a close_notify alert before closing the write side 1361 of the connection. The other party MUST respond with a close_notify 1362 alert of its own and close down the connection immediately, 1363 discarding any pending writes. It is not required for the initiator 1364 of the close to wait for the responding close_notify alert before 1365 closing the read side of the connection. 1367 If the application protocol using TLS provides that any data may be 1368 carried over the underlying transport after the TLS connection is 1369 closed, the TLS implementation must receive the responding 1370 close_notify alert before indicating to the application layer that 1371 the TLS connection has ended. If the application protocol will not 1372 transfer any additional data, but will only close the underlying 1373 transport connection, then the implementation MAY choose to close the 1374 transport without waiting for the responding close_notify. No part 1375 of this standard should be taken to dictate the manner in which a 1376 usage profile for TLS manages its data transport, including when 1377 connections are opened or closed. 1379 Note: It is assumed that closing a connection reliably delivers 1380 pending data before destroying the transport. 1382 7.2.2. Error Alerts 1384 Error handling in the TLS Handshake protocol is very simple. When an 1385 error is detected, the detecting party sends a message to the other 1386 party. Upon transmission or receipt of a fatal alert message, both 1387 parties immediately close the connection. Servers and clients MUST 1388 forget any session-identifiers, keys, and secrets associated with a 1389 failed connection. Thus, any connection terminated with a fatal 1390 alert MUST NOT be resumed. 1392 Whenever an implementation encounters a condition which is defined as 1393 a fatal alert, it MUST send the appropriate alert prior to closing 1394 the connection. For all errors where an alert level is not 1395 explicitly specified, the sending party MAY determine at its 1396 discretion whether to treat this as a fatal error or not. If the 1397 implementation chooses to send an alert but intends to close the 1398 connection immediately afterwards, it MUST send that alert at the 1399 fatal alert level. 1401 If an alert with a level of warning is sent and received, generally 1402 the connection can continue normally. If the receiving party decides 1403 not to proceed with the connection (e.g., after having received a 1404 no_renegotiation alert that it is not willing to accept), it SHOULD 1405 send a fatal alert to terminate the connection. Given this, the 1406 sending party cannot, in general, know how the receiving party will 1407 behave. Therefore, warning alerts are not very useful when the 1408 sending party wants to continue the connection, and thus are 1409 sometimes omitted. For example, if a peer decides to accept an 1410 expired certificate (perhaps after confirming this with the user) and 1411 wants to continue the connection, it would not generally send a 1412 certificate_expired alert. 1414 The following error alerts are defined: 1416 unexpected_message 1417 An inappropriate message was received. This alert is always fatal 1418 and should never be observed in communication between proper 1419 implementations. 1421 bad_record_mac 1422 This alert is returned if a record is received with an incorrect 1423 MAC. This alert also MUST be returned if an alert is sent because 1424 a TLSCiphertext decrypted in an invalid way: either it wasn't an 1425 even multiple of the block length, or its padding values, when 1426 checked, weren't correct. This message is always fatal and should 1427 never be observed in communication between proper implementations 1428 (except when messages were corrupted in the network). 1430 decryption_failed_RESERVED 1431 This alert was used in some earlier versions of TLS, and may have 1432 permitted certain attacks against the CBC mode [CBCATT]. It MUST 1433 NOT be sent by compliant implementations. 1435 record_overflow 1436 A TLSCiphertext record was received that had a length more than 1437 2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1438 with more than 2^14+1024 bytes. This message is always fatal and 1439 should never be observed in communication between proper 1440 implementations (except when messages were corrupted in the 1441 network). 1443 decompression_failure 1444 The decompression function received improper input (e.g., data 1445 that would expand to excessive length). This message is always 1446 fatal and should never be observed in communication between proper 1447 implementations. 1449 handshake_failure 1450 Reception of a handshake_failure alert message indicates that the 1451 sender was unable to negotiate an acceptable set of security 1452 parameters given the options available. This is a fatal error. 1454 no_certificate_RESERVED 1455 This alert was used in SSLv3 but not any version of TLS. It MUST 1456 NOT be sent by compliant implementations. 1458 bad_certificate 1459 A certificate was corrupt, contained signatures that did not 1460 verify correctly, etc. 1462 unsupported_certificate 1463 A certificate was of an unsupported type. 1465 certificate_revoked 1466 A certificate was revoked by its signer. 1468 certificate_expired 1469 A certificate has expired or is not currently valid. 1471 certificate_unknown 1472 Some other (unspecified) issue arose in processing the 1473 certificate, rendering it unacceptable. 1475 illegal_parameter 1476 A field in the handshake was out of range or inconsistent with 1477 other fields. This message is always fatal. 1479 unknown_ca 1480 A valid certificate chain or partial chain was received, but the 1481 certificate was not accepted because the CA certificate could not 1482 be located or couldn't be matched with a known, trusted CA. This 1483 message is always fatal. 1485 access_denied 1486 A valid certificate was received, but when access control was 1487 applied, the sender decided not to proceed with negotiation. This 1488 message is always fatal. 1490 decode_error 1491 A message could not be decoded because some field was out of the 1492 specified range or the length of the message was incorrect. This 1493 message is always fatal and should never be observed in 1494 communication between proper implementations (except when messages 1495 were corrupted in the network). 1497 decrypt_error 1498 A handshake cryptographic operation failed, including being unable 1499 to correctly verify a signature or validate a Finished message. 1500 This message is always fatal. 1502 export_restriction_RESERVED 1503 This alert was used in some earlier versions of TLS. It MUST NOT 1504 be sent by compliant implementations. 1506 protocol_version 1507 The protocol version the client has attempted to negotiate is 1508 recognized but not supported. (For example, old protocol versions 1509 might be avoided for security reasons.) This message is always 1510 fatal. 1512 insufficient_security 1513 Returned instead of handshake_failure when a negotiation has 1514 failed specifically because the server requires ciphers more 1515 secure than those supported by the client. This message is always 1516 fatal. 1518 internal_error 1519 An internal error unrelated to the peer or the correctness of the 1520 protocol (such as a memory allocation failure) makes it impossible 1521 to continue. This message is always fatal. 1523 user_canceled 1524 This handshake is being canceled for some reason unrelated to a 1525 protocol failure. If the user cancels an operation after the 1526 handshake is complete, just closing the connection by sending a 1527 close_notify is more appropriate. This alert should be followed 1528 by a close_notify. This message is generally a warning. 1530 no_renegotiation 1531 Sent by the client in response to a hello request or by the server 1532 in response to a client hello after initial handshaking. Either 1533 of these would normally lead to renegotiation; when that is not 1534 appropriate, the recipient should respond with this alert. At 1535 that point, the original requester can decide whether to proceed 1536 with the connection. One case where this would be appropriate is 1537 where a server has spawned a process to satisfy a request; the 1538 process might receive security parameters (key length, 1539 authentication, etc.) at startup, and it might be difficult to 1540 communicate changes to these parameters after that point. This 1541 message is always a warning. 1543 unsupported_extension 1544 sent by clients that receive an extended server hello containing 1545 an extension that they did not put in the corresponding client 1546 hello. This message is always fatal. 1548 New Alert values are assigned by IANA as described in Section 12. 1550 7.3. Handshake Protocol Overview 1552 The cryptographic parameters of the session state are produced by the 1553 TLS Handshake Protocol, which operates on top of the TLS record 1554 layer. When a TLS client and server first start communicating, they 1555 agree on a protocol version, select cryptographic algorithms, 1556 optionally authenticate each other, and use public-key encryption 1557 techniques to generate shared secrets. 1559 The TLS Handshake Protocol involves the following steps: 1561 - Exchange hello messages to agree on algorithms, exchange random 1562 values, and check for session resumption. 1564 - Exchange the necessary cryptographic parameters to allow the 1565 client and server to agree on a premaster secret. 1567 - Exchange certificates and cryptographic information to allow the 1568 client and server to authenticate themselves. 1570 - Generate a master secret from the premaster secret and exchanged 1571 random values. 1573 - Provide security parameters to the record layer. 1575 - Allow the client and server to verify that their peer has 1576 calculated the same security parameters and that the handshake 1577 occurred without tampering by an attacker. 1579 Note that higher layers should not be overly reliant on whether TLS 1580 always negotiates the strongest possible connection between two 1581 peers. There are a number of ways in which a man-in-the-middle 1582 attacker can attempt to make two entities drop down to the least 1583 secure method they support. The protocol has been designed to 1584 minimize this risk, but there are still attacks available: for 1585 example, an attacker could block access to the port a secure service 1586 runs on, or attempt to get the peers to negotiate an unauthenticated 1587 connection. The fundamental rule is that higher levels must be 1588 cognizant of what their security requirements are and never transmit 1589 information over a channel less secure than what they require. The 1590 TLS protocol is secure in that any cipher suite offers its promised 1591 level of security: if you negotiate 3DES with a 1024-bit RSA key 1592 exchange with a host whose certificate you have verified, you can 1593 expect to be that secure. 1595 These goals are achieved by the handshake protocol, which can be 1596 summarized as follows: The client sends a ClientHello message to 1597 which the server must respond with a ServerHello message, or else a 1598 fatal error will occur and the connection will fail. The ClientHello 1599 and ServerHello are used to establish security enhancement 1600 capabilities between client and server. The ClientHello and 1601 ServerHello establish the following attributes: Protocol Version, 1602 Session ID, Cipher Suite, and Compression Method. Additionally, two 1603 random values are generated and exchanged: ClientHello.random and 1604 ServerHello.random. 1606 The actual key exchange uses up to four messages: the server 1607 Certificate, the ServerKeyExchange, the client Certificate, and the 1608 ClientKeyExchange. New key exchange methods can be created by 1609 specifying a format for these messages and by defining the use of the 1610 messages to allow the client and server to agree upon a shared 1611 secret. This secret MUST be quite long; currently defined key 1612 exchange methods exchange secrets that range from 46 bytes upwards. 1614 Following the hello messages, the server will send its certificate in 1615 a Certificate message if it is to be authenticated. Additionally, a 1616 ServerKeyExchange message may be sent, if it is required (e.g., if 1617 the server has no certificate, or if its certificate is for signing 1618 only). If the server is authenticated, it may request a certificate 1619 from the client, if that is appropriate to the cipher suite selected. 1620 Next, the server will send the ServerHelloDone message, indicating 1621 that the hello-message phase of the handshake is complete. The 1622 server will then wait for a client response. If the server has sent 1623 a CertificateRequest message, the client MUST send the Certificate 1624 message. The ClientKeyExchange message is now sent, and the content 1625 of that message will depend on the public key algorithm selected 1626 between the ClientHello and the ServerHello. If the client has sent 1627 a certificate with signing ability, a digitally-signed 1628 CertificateVerify message is sent to explicitly verify possession of 1629 the private key in the certificate. 1631 At this point, a ChangeCipherSpec message is sent by the client, and 1632 the client copies the pending Cipher Spec into the current Cipher 1633 Spec. The client then immediately sends the Finished message under 1634 the new algorithms, keys, and secrets. In response, the server will 1635 send its own ChangeCipherSpec message, transfer the pending to the 1636 current Cipher Spec, and send its Finished message under the new 1637 Cipher Spec. At this point, the handshake is complete, and the 1638 client and server may begin to exchange application layer data. (See 1639 flow chart below.) Application data MUST NOT be sent prior to the 1640 completion of the first handshake (before a cipher suite other than 1641 TLS_NULL_WITH_NULL_NULL is established). 1643 Client Server 1645 ClientHello --------> 1646 ServerHello 1647 Certificate* 1648 ServerKeyExchange* 1649 CertificateRequest* 1650 <-------- ServerHelloDone 1651 Certificate* 1652 ClientKeyExchange 1653 CertificateVerify* 1654 [ChangeCipherSpec] 1655 Finished --------> 1656 [ChangeCipherSpec] 1657 <-------- Finished 1658 Application Data <-------> Application Data 1660 Figure 1. Message flow for a full handshake 1662 * Indicates optional or situation-dependent messages that are not 1663 always sent. 1665 Note: To help avoid pipeline stalls, ChangeCipherSpec is an 1666 independent TLS protocol content type, and is not actually a TLS 1667 handshake message. 1669 When the client and server decide to resume a previous session or 1670 duplicate an existing session (instead of negotiating new security 1671 parameters), the message flow is as follows: 1673 The client sends a ClientHello using the Session ID of the session to 1674 be resumed. The server then checks its session cache for a match. 1675 If a match is found, and the server is willing to re-establish the 1676 connection under the specified session state, it will send a 1677 ServerHello with the same Session ID value. At this point, both 1678 client and server MUST send ChangeCipherSpec messages and proceed 1679 directly to Finished messages. Once the re-establishment is 1680 complete, the client and server MAY begin to exchange application 1681 layer data. (See flow chart below.) If a Session ID match is not 1682 found, the server generates a new session ID, and the TLS client and 1683 server perform a full handshake. 1685 Client Server 1687 ClientHello --------> 1688 ServerHello 1689 [ChangeCipherSpec] 1690 <-------- Finished 1691 [ChangeCipherSpec] 1692 Finished --------> 1693 Application Data <-------> Application Data 1695 Figure 2. Message flow for an abbreviated handshake 1697 The contents and significance of each message will be presented in 1698 detail in the following sections. 1700 7.4. Handshake Protocol 1702 The TLS Handshake Protocol is one of the defined higher-level clients 1703 of the TLS Record Protocol. This protocol is used to negotiate the 1704 secure attributes of a session. Handshake messages are supplied to 1705 the TLS record layer, where they are encapsulated within one or more 1706 TLSPlaintext structures, which are processed and transmitted as 1707 specified by the current active session state. 1709 enum { 1710 hello_request(0), client_hello(1), server_hello(2), 1711 certificate(11), server_key_exchange (12), 1712 certificate_request(13), server_hello_done(14), 1713 certificate_verify(15), client_key_exchange(16), 1714 finished(20), (255) 1715 } HandshakeType; 1717 struct { 1718 HandshakeType msg_type; /* handshake type */ 1719 uint24 length; /* bytes in message */ 1720 select (HandshakeType) { 1721 case hello_request: HelloRequest; 1722 case client_hello: ClientHello; 1723 case server_hello: ServerHello; 1724 case certificate: Certificate; 1725 case server_key_exchange: ServerKeyExchange; 1726 case certificate_request: CertificateRequest; 1727 case server_hello_done: ServerHelloDone; 1728 case certificate_verify: CertificateVerify; 1729 case client_key_exchange: ClientKeyExchange; 1730 case finished: Finished; 1731 } body; 1732 } Handshake; 1734 The handshake protocol messages are presented below in the order they 1735 MUST be sent; sending handshake messages in an unexpected order 1736 results in a fatal error. Unneeded handshake messages can be 1737 omitted, however. Note one exception to the ordering: the 1738 Certificate message is used twice in the handshake (from server to 1739 client, then from client to server), but described only in its first 1740 position. The one message that is not bound by these ordering rules 1741 is the HelloRequest message, which can be sent at any time, but which 1742 SHOULD be ignored by the client if it arrives in the middle of a 1743 handshake. 1745 New handshake message types are assigned by IANA as described in 1746 Section 12. 1748 7.4.1. Hello Messages 1750 The hello phase messages are used to exchange security enhancement 1751 capabilities between the client and server. When a new session 1752 begins, the record layer's connection state encryption, hash, and 1753 compression algorithms are initialized to null. The current 1754 connection state is used for renegotiation messages. 1756 7.4.1.1. Hello Request 1758 When this message will be sent: 1760 The HelloRequest message MAY be sent by the server at any time. 1762 Meaning of this message: 1764 HelloRequest is a simple notification that the client should begin 1765 the negotiation process anew. In response, the client should send 1766 a ClientHello message when convenient. This message is not 1767 intended to establish which side is the client or server but 1768 merely to initiate a new negotiation. Servers SHOULD NOT send a 1769 HelloRequest immediately upon the client's initial connection. It 1770 is the client's job to send a ClientHello at that time. 1772 This message will be ignored by the client if the client is 1773 currently negotiating a session. This message MAY be ignored by 1774 the client if it does not wish to renegotiate a session, or the 1775 client may, if it wishes, respond with a no_renegotiation alert. 1776 Since handshake messages are intended to have transmission 1777 precedence over application data, it is expected that the 1778 negotiation will begin before no more than a few records are 1779 received from the client. If the server sends a HelloRequest but 1780 does not receive a ClientHello in response, it may close the 1781 connection with a fatal alert. 1783 After sending a HelloRequest, servers SHOULD NOT repeat the 1784 request until the subsequent handshake negotiation is complete. 1786 Structure of this message: 1788 struct { } HelloRequest; 1790 This message MUST NOT be included in the message hashes that are 1791 maintained throughout the handshake and used in the Finished messages 1792 and the certificate verify message. 1794 7.4.1.2. Client Hello 1796 When this message will be sent: 1798 When a client first connects to a server, it is required to send 1799 the ClientHello as its first message. The client can also send a 1800 ClientHello in response to a HelloRequest or on its own initiative 1801 in order to renegotiate the security parameters in an existing 1802 connection. 1804 Structure of this message: 1806 The ClientHello message includes a random structure, which is used 1807 later in the protocol. 1809 struct { 1810 uint32 gmt_unix_time; 1811 opaque random_bytes[28]; 1812 } Random; 1814 gmt_unix_time 1815 The current time and date in standard UNIX 32-bit format (seconds 1816 since the midnight starting Jan 1, 1970, UTC, ignoring leap 1817 seconds) according to the sender's internal clock. Clocks are not 1818 required to be set correctly by the basic TLS protocol; higher- 1819 level or application protocols may define additional requirements. 1820 Note that, for historical reasons, the data element is named using 1821 GMT, the predecessor of the current worldwide time base, UTC. 1823 random_bytes 1824 28 bytes generated by a secure random number generator. 1826 The ClientHello message includes a variable-length session 1827 identifier. If not empty, the value identifies a session between the 1828 same client and server whose security parameters the client wishes to 1829 reuse. The session identifier MAY be from an earlier connection, 1830 this connection, or from another currently active connection. The 1831 second option is useful if the client only wishes to update the 1832 random structures and derived values of a connection, and the third 1833 option makes it possible to establish several independent secure 1834 connections without repeating the full handshake protocol. These 1835 independent connections may occur sequentially or simultaneously; a 1836 SessionID becomes valid when the handshake negotiating it completes 1837 with the exchange of Finished messages and persists until it is 1838 removed due to aging or because a fatal error was encountered on a 1839 connection associated with the session. The actual contents of the 1840 SessionID are defined by the server. 1842 opaque SessionID<0..32>; 1844 Warning: Because the SessionID is transmitted without encryption or 1845 immediate MAC protection, servers MUST NOT place confidential 1846 information in session identifiers or let the contents of fake 1847 session identifiers cause any breach of security. (Note that the 1848 content of the handshake as a whole, including the SessionID, is 1849 protected by the Finished messages exchanged at the end of the 1850 handshake.) 1852 The cipher suite list, passed from the client to the server in the 1853 ClientHello message, contains the combinations of cryptographic 1854 algorithms supported by the client in order of the client's 1855 preference (favorite choice first). Each cipher suite defines a key 1856 exchange algorithm, a bulk encryption algorithm (including secret key 1857 length), a MAC algorithm, and a PRF. The server will select a cipher 1858 suite or, if no acceptable choices are presented, return a handshake 1859 failure alert and close the connection. If the list contains cipher 1860 suites the server does not recognize, support, or wish to use, the 1861 server MUST ignore those cipher suites, and process the remaining 1862 ones as usual. 1864 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1866 The ClientHello includes a list of compression algorithms supported 1867 by the client, ordered according to the client's preference. 1869 enum { null(0), (255) } CompressionMethod; 1871 struct { 1872 ProtocolVersion client_version; 1873 Random random; 1874 SessionID session_id; 1875 CipherSuite cipher_suites<2..2^16-2>; 1876 CompressionMethod compression_methods<1..2^8-1>; 1877 select (extensions_present) { 1878 case false: 1879 struct {}; 1880 case true: 1881 Extension extensions<0..2^16-1>; 1882 }; 1883 } ClientHello; 1885 TLS allows extensions to follow the compression_methods field in an 1886 extensions block. The presence of extensions can be detected by 1887 determining whether there are bytes following the compression_methods 1888 at the end of the ClientHello. Note that this method of detecting 1889 optional data differs from the normal TLS method of having a 1890 variable-length field, but it is used for compatibility with TLS 1891 before extensions were defined. 1893 client_version 1894 The version of the TLS protocol by which the client wishes to 1895 communicate during this session. This SHOULD be the latest 1896 (highest valued) version supported by the client. For this 1897 version of the specification, the version will be 3.3 (see 1898 Appendix E for details about backward compatibility). 1900 random 1901 A client-generated random structure. 1903 session_id 1904 The ID of a session the client wishes to use for this connection. 1905 This field is empty if no session_id is available, or if the 1906 client wishes to generate new security parameters. 1908 cipher_suites 1909 This is a list of the cryptographic options supported by the 1910 client, with the client's first preference first. If the 1911 session_id field is not empty (implying a session resumption 1912 request), this vector MUST include at least the cipher_suite from 1913 that session. Values are defined in Appendix A.5. 1915 compression_methods 1916 This is a list of the compression methods supported by the client, 1917 sorted by client preference. If the session_id field is not empty 1918 (implying a session resumption request), it MUST include the 1919 compression_method from that session. This vector MUST contain, 1920 and all implementations MUST support, CompressionMethod.null. 1921 Thus, a client and server will always be able to agree on a 1922 compression method. 1924 extensions 1925 Clients MAY request extended functionality from servers by sending 1926 data in the extensions field. The actual "Extension" format is 1927 defined in Section 7.4.1.4. 1929 In the event that a client requests additional functionality using 1930 extensions, and this functionality is not supplied by the server, the 1931 client MAY abort the handshake. A server MUST accept ClientHello 1932 messages both with and without the extensions field, and (as for all 1933 other messages) it MUST check that the amount of data in the message 1934 precisely matches one of these formats; if not, then it MUST send a 1935 fatal "decode_error" alert. 1937 After sending the ClientHello message, the client waits for a 1938 ServerHello message. Any handshake message returned by the server, 1939 except for a HelloRequest, is treated as a fatal error. 1941 7.4.1.3. Server Hello 1943 When this message will be sent: 1945 The server will send this message in response to a ClientHello 1946 message when it was able to find an acceptable set of algorithms. 1947 If it cannot find such a match, it will respond with a handshake 1948 failure alert. 1950 Structure of this message: 1952 struct { 1953 ProtocolVersion server_version; 1954 Random random; 1955 SessionID session_id; 1956 CipherSuite cipher_suite; 1957 CompressionMethod compression_method; 1958 select (extensions_present) { 1959 case false: 1960 struct {}; 1961 case true: 1962 Extension extensions<0..2^16-1>; 1963 }; 1964 } ServerHello; 1966 The presence of extensions can be detected by determining whether 1967 there are bytes following the compression_method field at the end of 1968 the ServerHello. 1970 server_version 1971 This field will contain the lower of that suggested by the client 1972 in the client hello and the highest supported by the server. For 1973 this version of the specification, the version is 3.3. (See 1974 Appendix E for details about backward compatibility.) 1976 random 1977 This structure is generated by the server and MUST be 1978 independently generated from the ClientHello.random. 1980 session_id 1981 This is the identity of the session corresponding to this 1982 connection. If the ClientHello.session_id was non-empty, the 1983 server will look in its session cache for a match. If a match is 1984 found and the server is willing to establish the new connection 1985 using the specified session state, the server will respond with 1986 the same value as was supplied by the client. This indicates a 1987 resumed session and dictates that the parties must proceed 1988 directly to the Finished messages. Otherwise, this field will 1989 contain a different value identifying the new session. The server 1990 may return an empty session_id to indicate that the session will 1991 not be cached and therefore cannot be resumed. If a session is 1992 resumed, it must be resumed using the same cipher suite it was 1993 originally negotiated with. Note that there is no requirement 1994 that the server resume any session even if it had formerly 1995 provided a session_id. Clients MUST be prepared to do a full 1996 negotiation -- including negotiating new cipher suites -- during 1997 any handshake. 1999 cipher_suite 2000 The single cipher suite selected by the server from the list in 2001 ClientHello.cipher_suites. For resumed sessions, this field is 2002 the value from the state of the session being resumed. 2004 compression_method 2005 The single compression algorithm selected by the server from the 2006 list in ClientHello.compression_methods. For resumed sessions, 2007 this field is the value from the resumed session state. 2009 extensions 2010 A list of extensions. Note that only extensions offered by the 2011 client can appear in the server's list. 2013 7.4.1.4. Hello Extensions 2015 The extension format is: 2017 struct { 2018 ExtensionType extension_type; 2019 opaque extension_data<0..2^16-1>; 2020 } Extension; 2022 enum { 2023 signature_algorithms(13), (65535) 2024 } ExtensionType; 2026 Here: 2028 - "extension_type" identifies the particular extension type. 2030 - "extension_data" contains information specific to the particular 2031 extension type. 2033 The initial set of extensions is defined in a companion document 2034 [TLSEXT]. The list of extension types is maintained by IANA as 2035 described in Section 12. 2037 An extension type MUST NOT appear in the ServerHello unless the same 2038 extension type appeared in the corresponding ClientHello. If a 2039 client receives an extension type in ServerHello that it did not 2040 request in the associated ClientHello, it MUST abort the handshake 2041 with an unsupported_extension fatal alert. 2043 Nonetheless, "server-oriented" extensions may be provided in the 2044 future within this framework. Such an extension (say, of type x) 2045 would require the client to first send an extension of type x in a 2046 ClientHello with empty extension_data to indicate that it supports 2047 the extension type. In this case, the client is offering the 2048 capability to understand the extension type, and the server is taking 2049 the client up on its offer. 2051 When multiple extensions of different types are present in the 2052 ClientHello or ServerHello messages, the extensions MAY appear in any 2053 order. There MUST NOT be more than one extension of the same type. 2055 Finally, note that extensions can be sent both when starting a new 2056 session and when requesting session resumption. Indeed, a client 2057 that requests session resumption does not in general know whether the 2058 server will accept this request, and therefore it SHOULD send the 2059 same extensions as it would send if it were not attempting 2060 resumption. 2062 In general, the specification of each extension type needs to 2063 describe the effect of the extension both during full handshake and 2064 session resumption. Most current TLS extensions are relevant only 2065 when a session is initiated: when an older session is resumed, the 2066 server does not process these extensions in Client Hello, and does 2067 not include them in Server Hello. However, some extensions may 2068 specify different behavior during session resumption. 2070 There are subtle (and not so subtle) interactions that may occur in 2071 this protocol between new features and existing features which may 2072 result in a significant reduction in overall security. The following 2073 considerations should be taken into account when designing new 2074 extensions: 2076 - Some cases where a server does not agree to an extension are error 2077 conditions, and some are simply refusals to support particular 2078 features. In general, error alerts should be used for the former, 2079 and a field in the server extension response for the latter. 2081 - Extensions should, as far as possible, be designed to prevent any 2082 attack that forces use (or non-use) of a particular feature by 2083 manipulation of handshake messages. This principle should be 2084 followed regardless of whether the feature is believed to cause a 2085 security problem. 2087 Often the fact that the extension fields are included in the 2088 inputs to the Finished message hashes will be sufficient, but 2089 extreme care is needed when the extension changes the meaning of 2090 messages sent in the handshake phase. Designers and implementors 2091 should be aware of the fact that until the handshake has been 2092 authenticated, active attackers can modify messages and insert, 2093 remove, or replace extensions. 2095 - It would be technically possible to use extensions to change major 2096 aspects of the design of TLS; for example the design of cipher 2097 suite negotiation. This is not recommended; it would be more 2098 appropriate to define a new version of TLS -- particularly since 2099 the TLS handshake algorithms have specific protection against 2100 version rollback attacks based on the version number, and the 2101 possibility of version rollback should be a significant 2102 consideration in any major design change. 2104 7.4.1.4.1. Signature Algorithms 2106 The client uses the "signature_algorithms" extension to indicate to 2107 the server which signature/hash algorithm pairs may be used in 2108 digital signatures. The "extension_data" field of this extension 2109 contains a "supported_signature_algorithms" value. 2111 enum { 2112 none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5), 2113 sha512(6), (255) 2114 } HashAlgorithm; 2116 enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) } 2117 SignatureAlgorithm; 2119 struct { 2120 HashAlgorithm hash; 2121 SignatureAlgorithm signature; 2122 } SignatureAndHashAlgorithm; 2124 SignatureAndHashAlgorithm 2125 supported_signature_algorithms<2..2^16-2>; 2127 Each SignatureAndHashAlgorithm value lists a single hash/signature 2128 pair that the client is willing to verify. The values are indicated 2129 in descending order of preference. 2131 Note: Because not all signature algorithms and hash algorithms may be 2132 accepted by an implementation (e.g., DSA with SHA-1, but not SHA- 2133 256), algorithms here are listed in pairs. 2135 hash 2136 This field indicates the hash algorithm which may be used. The 2137 values indicate support for unhashed data, MD5 [RFC1321], SHA-1, 2138 SHA-224, SHA-256, SHA-384, and SHA-512 [SHS], respectively. The 2139 "none" value is provided for future extensibility, in case of a 2140 signature algorithm which does not require hashing before signing. 2142 signature 2143 This field indicates the signature algorithm that may be used. 2144 The values indicate anonymous signatures, RSASSA-PKCS1-v1_5 2145 [RFC3447] and DSA [DSS], and ECDSA [ECDSA], respectively. The 2146 "anonymous" value is meaningless in this context but used in 2147 Section 7.4.3. It MUST NOT appear in this extension. 2149 The semantics of this extension are somewhat complicated because the 2150 cipher suite indicates permissible signature algorithms but not hash 2151 algorithms. Section 7.4.2 and Section 7.4.3 describe the appropriate 2152 rules. 2154 If the client supports only the default hash and signature algorithms 2155 (listed in this section), it MAY omit the signature_algorithms 2156 extension. If the client does not support the default algorithms, or 2157 supports other hash and signature algorithms (and it is willing to 2158 use them for verifying messages sent by the server, i.e., server 2159 certificates and server key exchange), it MUST send the 2160 signature_algorithms extension, listing the algorithms it is willing 2161 to accept. 2163 If the client does not send the signature_algorithms extension, the 2164 server MUST do the following: 2166 - If the negotiated key exchange algorithm is one of (RSA, DHE_RSA, 2167 DH_RSA, RSA_PSK, ECDH_RSA, ECDHE_RSA), behave as if client had 2168 sent the value {sha1,rsa}. 2170 - If the negotiated key exchange algorithm is one of (DHE_DSS, 2171 DH_DSS), behave as if the client had sent the value {sha1,dsa}. 2173 - If the negotiated key exchange algorithm is one of (ECDH_ECDSA, 2174 ECDHE_ECDSA), behave as if the client had sent value {sha1,ecdsa}. 2176 Note: this is a change from TLS 1.1 where there are no explicit 2177 rules, but as a practical matter one can assume that the peer 2178 supports MD5 and SHA-1. 2180 Note: this extension is not meaningful for TLS versions prior to 1.2. 2181 Clients MUST NOT offer it if they are offering prior versions. 2182 However, even if clients do offer it, the rules specified in [TLSEXT] 2183 require servers to ignore extensions they do not understand. 2185 Servers MUST NOT send this extension. TLS servers MUST support 2186 receiving this extension. 2188 When performing session resumption, this extension is not included in 2189 Server Hello, and the server ignores the extension in Client Hello 2190 (if present). 2192 7.4.2. Server Certificate 2194 When this message will be sent: 2196 The server MUST send a Certificate message whenever the agreed- 2197 upon key exchange method uses certificates for authentication 2198 (this includes all key exchange methods defined in this document 2199 except DH_anon). This message will always immediately follow the 2200 ServerHello message. 2202 Meaning of this message: 2204 This message conveys the server's certificate chain to the client. 2206 The certificate MUST be appropriate for the negotiated cipher 2207 suite's key exchange algorithm and any negotiated extensions. 2209 Structure of this message: 2211 opaque ASN.1Cert<1..2^24-1>; 2213 struct { 2214 ASN.1Cert certificate_list<0..2^24-1>; 2215 } Certificate; 2217 certificate_list 2218 This is a sequence (chain) of certificates. The sender's 2219 certificate MUST come first in the list. Each following 2220 certificate MUST directly certify the one preceding it. Because 2221 certificate validation requires that root keys be distributed 2222 independently, the self-signed certificate that specifies the root 2223 certificate authority MAY be omitted from the chain, under the 2224 assumption that the remote end must already possess it in order to 2225 validate it in any case. 2227 The same message type and structure will be used for the client's 2228 response to a certificate request message. Note that a client MAY 2229 send no certificates if it does not have an appropriate certificate 2230 to send in response to the server's authentication request. 2232 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 2233 vector because PKCS #6 [PKCS6] extended certificates are not used. 2234 Also, PKCS #7 defines a SET rather than a SEQUENCE, making the task 2235 of parsing the list more difficult. 2237 The following rules apply to the certificates sent by the server: 2239 - The certificate type MUST be X.509v3, unless explicitly negotiated 2240 otherwise (e.g., [RFC5081]). 2242 - The end entity certificate's public key (and associated 2243 restrictions) MUST be compatible with the selected key exchange 2244 algorithm. 2246 Key Exchange Alg. Certificate Key Type 2248 RSA RSA public key; the certificate MUST allow the 2249 RSA_PSK key to be used for encryption (the 2250 keyEncipherment bit MUST be set if the key 2251 usage extension is present). 2252 Note: RSA_PSK is defined in [RFC4279]. 2254 DHE_RSA RSA public key; the certificate MUST allow the 2255 ECDHE_RSA key to be used for signing (the 2256 digitalSignature bit MUST be set if the key 2257 usage extension is present) with the signature 2258 scheme and hash algorithm that will be employed 2259 in the server key exchange message. 2260 Note: ECDHE_RSA is defined in [RFC4492]. 2262 DHE_DSS DSA public key; the certificate MUST allow the 2263 key to be used for signing with the hash 2264 algorithm that will be employed in the server 2265 key exchange message. 2267 DH_DSS Diffie-Hellman public key; the keyAgreement bit 2268 DH_RSA MUST be set if the key usage extension is 2269 present. 2271 ECDH_ECDSA ECDH-capable public key; the public key MUST 2272 ECDH_RSA use a curve and point format supported by the 2273 client, as described in [RFC4492]. 2275 ECDHE_ECDSA ECDSA-capable public key; the certificate MUST 2276 allow the key to be used for signing with the 2277 hash algorithm that will be employed in the 2278 server key exchange message. The public key 2279 MUST use a curve and point format supported by 2280 the client, as described in [RFC4492]. 2282 - The "server_name" and "trusted_ca_keys" extensions [TLSEXT] are 2283 used to guide certificate selection. 2285 If the client provided a "signature_algorithms" extension, then all 2286 certificates provided by the server MUST be signed by a hash/ 2287 signature algorithm pair that appears in that extension. Note that 2288 this implies that a certificate containing a key for one signature 2289 algorithm MAY be signed using a different signature algorithm (for 2290 instance, an RSA key signed with a DSA key). This is a departure 2291 from TLS 1.1, which required that the algorithms be the same. Note 2292 that this also implies that the DH_DSS, DH_RSA, ECDH_ECDSA, and 2293 ECDH_RSA key exchange algorithms do not restrict the algorithm used 2294 to sign the certificate. Fixed DH certificates MAY be signed with 2295 any hash/signature algorithm pair appearing in the extension. The 2296 names DH_DSS, DH_RSA, ECDH_ECDSA, and ECDH_RSA are historical. 2298 If the server has multiple certificates, it chooses one of them based 2299 on the above-mentioned criteria (in addition to other criteria, such 2300 as transport layer endpoint, local configuration and preferences, 2301 etc.). If the server has a single certificate, it SHOULD attempt to 2302 validate that it meets these criteria. 2304 Note that there are certificates that use algorithms and/or algorithm 2305 combinations that cannot be currently used with TLS. For example, a 2306 certificate with RSASSA-PSS signature key (id-RSASSA-PSS OID in 2307 SubjectPublicKeyInfo) cannot be used because TLS defines no 2308 corresponding signature algorithm. 2310 As cipher suites that specify new key exchange methods are specified 2311 for the TLS protocol, they will imply the certificate format and the 2312 required encoded keying information. 2314 7.4.3. Server Key Exchange Message 2316 When this message will be sent: 2318 This message will be sent immediately after the server Certificate 2319 message (or the ServerHello message, if this is an anonymous 2320 negotiation). 2322 The ServerKeyExchange message is sent by the server only when the 2323 server Certificate message (if sent) does not contain enough data 2324 to allow the client to exchange a premaster secret. This is true 2325 for the following key exchange methods: 2327 DHE_DSS 2328 DHE_RSA 2329 DH_anon 2331 It is not legal to send the ServerKeyExchange message for the 2332 following key exchange methods: 2334 RSA 2335 DH_DSS 2336 DH_RSA 2338 Other key exchange algorithms, such as those defined in [RFC4492], 2339 MUST specify whether the ServerKeyExchange message is sent or not; 2340 and if the message is sent, its contents. 2342 Meaning of this message: 2344 This message conveys cryptographic information to allow the client 2345 to communicate the premaster secret: a Diffie-Hellman public key 2346 with which the client can complete a key exchange (with the result 2347 being the premaster secret) or a public key for some other 2348 algorithm. 2350 Structure of this message: 2352 enum { dhe_dss, dhe_rsa, dh_anon, rsa, dh_dss, dh_rsa 2353 /* may be extended, e.g., for ECDH -- see [RFC4492] */ 2354 } KeyExchangeAlgorithm; 2356 struct { 2357 opaque dh_p<1..2^16-1>; 2358 opaque dh_g<1..2^16-1>; 2359 opaque dh_Ys<1..2^16-1>; 2360 } ServerDHParams; /* Ephemeral DH parameters */ 2362 dh_p 2363 The prime modulus used for the Diffie-Hellman operation. 2365 dh_g 2366 The generator used for the Diffie-Hellman operation. 2368 dh_Ys 2369 The server's Diffie-Hellman public value (g^X mod p). 2371 struct { 2372 select (KeyExchangeAlgorithm) { 2373 case dh_anon: 2374 ServerDHParams params; 2375 case dhe_dss: 2376 case dhe_rsa: 2377 ServerDHParams params; 2378 digitally-signed struct { 2379 opaque client_random[32]; 2380 opaque server_random[32]; 2381 ServerDHParams params; 2382 } signed_params; 2383 case rsa: 2384 case dh_dss: 2385 case dh_rsa: 2386 struct {} ; 2387 /* message is omitted for rsa, dh_dss, and dh_rsa */ 2388 /* may be extended, e.g., for ECDH -- see [RFC4492] */ 2389 }; 2390 } ServerKeyExchange; 2392 params 2393 The server's key exchange parameters. 2395 signed_params 2396 For non-anonymous key exchanges, a signature over the server's key 2397 exchange parameters. 2399 If the client has offered the "signature_algorithms" extension, the 2400 signature algorithm and hash algorithm MUST be a pair listed in that 2401 extension. Note that there is a possibility for inconsistencies 2402 here. For instance, the client might offer DHE_DSS key exchange but 2403 omit any DSA pairs from its "signature_algorithms" extension. In 2404 order to negotiate correctly, the server MUST check any candidate 2405 cipher suites against the "signature_algorithms" extension before 2406 selecting them. This is somewhat inelegant but is a compromise 2407 designed to minimize changes to the original cipher suite design. 2409 In addition, the hash and signature algorithms MUST be compatible 2410 with the key in the server's end-entity certificate. RSA keys MAY be 2411 used with any permitted hash algorithm, subject to restrictions in 2412 the certificate, if any. 2414 Because DSA signatures do not contain any secure indication of hash 2415 algorithm, there is a risk of hash substitution if multiple hashes 2416 may be used with any key. Currently, DSA [DSS] may only be used with 2417 SHA-1. Future revisions of DSS [DSS-3] are expected to allow the use 2418 of other digest algorithms with DSA, as well as guidance as to which 2419 digest algorithms should be used with each key size. In addition, 2420 future revisions of [RFC3280] may specify mechanisms for certificates 2421 to indicate which digest algorithms are to be used with DSA. 2423 As additional cipher suites are defined for TLS that include new key 2424 exchange algorithms, the server key exchange message will be sent if 2425 and only if the certificate type associated with the key exchange 2426 algorithm does not provide enough information for the client to 2427 exchange a premaster secret. 2429 7.4.4. Certificate Request 2431 When this message will be sent: 2433 A non-anonymous server can optionally request a certificate from 2434 the client, if appropriate for the selected cipher suite. This 2435 message, if sent, will immediately follow the ServerKeyExchange 2436 message (if it is sent; otherwise, this message follows the 2437 server's Certificate message). 2439 Structure of this message: 2441 enum { 2442 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 2443 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 2444 fortezza_dms_RESERVED(20), (255) 2445 } ClientCertificateType; 2447 opaque DistinguishedName<1..2^16-1>; 2449 struct { 2450 ClientCertificateType certificate_types<1..2^8-1>; 2451 SignatureAndHashAlgorithm 2452 supported_signature_algorithms<2^16-1>; 2453 DistinguishedName certificate_authorities<0..2^16-1>; 2454 } CertificateRequest; 2456 certificate_types 2457 A list of the types of certificate types that the client may 2458 offer. 2460 rsa_sign a certificate containing an RSA key 2461 dss_sign a certificate containing a DSA key 2462 rsa_fixed_dh a certificate containing a static DH key. 2463 dss_fixed_dh a certificate containing a static DH key 2465 supported_signature_algorithms 2466 A list of the hash/signature algorithm pairs that the server is 2467 able to verify, listed in descending order of preference. 2469 certificate_authorities 2470 A list of the distinguished names [X501] of acceptable 2471 certificate_authorities, represented in DER-encoded format. These 2472 distinguished names may specify a desired distinguished name for a 2473 root CA or for a subordinate CA; thus, this message can be used to 2474 describe known roots as well as a desired authorization space. If 2475 the certificate_authorities list is empty, then the client MAY 2476 send any certificate of the appropriate ClientCertificateType, 2477 unless there is some external arrangement to the contrary. 2479 The interaction of the certificate_types and 2480 supported_signature_algorithms fields is somewhat complicated. 2481 certificate_types has been present in TLS since SSLv3, but was 2482 somewhat underspecified. Much of its functionality is superseded by 2483 supported_signature_algorithms. The following rules apply: 2485 - Any certificates provided by the client MUST be signed using a 2486 hash/signature algorithm pair found in 2487 supported_signature_algorithms. 2489 - The end-entity certificate provided by the client MUST contain a 2490 key that is compatible with certificate_types. If the key is a 2491 signature key, it MUST be usable with some hash/signature 2492 algorithm pair in supported_signature_algorithms. 2494 - For historical reasons, the names of some client certificate types 2495 include the algorithm used to sign the certificate. For example, 2496 in earlier versions of TLS, rsa_fixed_dh meant a certificate 2497 signed with RSA and containing a static DH key. In TLS 1.2, this 2498 functionality has been obsoleted by the 2499 supported_signature_algorithms, and the certificate type no longer 2500 restricts the algorithm used to sign the certificate. For 2501 example, if the server sends dss_fixed_dh certificate type and 2502 {{sha1, dsa}, {sha1, rsa}} signature types, the client MAY reply 2503 with a certificate containing a static DH key, signed with RSA- 2504 SHA1. 2506 New ClientCertificateType values are assigned by IANA as described in 2507 Section 12. 2509 Note: Values listed as RESERVED may not be used. They were used in 2510 SSLv3. 2512 Note: It is a fatal handshake_failure alert for an anonymous server 2513 to request client authentication. 2515 7.4.5. Server Hello Done 2517 When this message will be sent: 2519 The ServerHelloDone message is sent by the server to indicate the 2520 end of the ServerHello and associated messages. After sending 2521 this message, the server will wait for a client response. 2523 Meaning of this message: 2525 This message means that the server is done sending messages to 2526 support the key exchange, and the client can proceed with its 2527 phase of the key exchange. 2529 Upon receipt of the ServerHelloDone message, the client SHOULD 2530 verify that the server provided a valid certificate, if required, 2531 and check that the server hello parameters are acceptable. 2533 Structure of this message: 2535 struct { } ServerHelloDone; 2537 7.4.6. Client Certificate 2539 When this message will be sent: 2541 This is the first message the client can send after receiving a 2542 ServerHelloDone message. This message is only sent if the server 2543 requests a certificate. If no suitable certificate is available, 2544 the client MUST send a certificate message containing no 2545 certificates. That is, the certificate_list structure has a 2546 length of zero. If the client does not send any certificates, the 2547 server MAY at its discretion either continue the handshake without 2548 client authentication, or respond with a fatal handshake_failure 2549 alert. Also, if some aspect of the certificate chain was 2550 unacceptable (e.g., it was not signed by a known, trusted CA), the 2551 server MAY at its discretion either continue the handshake 2552 (considering the client unauthenticated) or send a fatal alert. 2554 Client certificates are sent using the Certificate structure 2555 defined in Section 7.4.2. 2557 Meaning of this message: 2559 This message conveys the client's certificate chain to the server; 2560 the server will use it when verifying the CertificateVerify 2561 message (when the client authentication is based on signing) or 2562 calculating the premaster secret (for non-ephemeral Diffie- 2563 Hellman). The certificate MUST be appropriate for the negotiated 2564 cipher suite's key exchange algorithm, and any negotiated 2565 extensions. 2567 In particular: 2569 - The certificate type MUST be X.509v3, unless explicitly negotiated 2570 otherwise (e.g., [RFC5081]). 2572 - The end-entity certificate's public key (and associated 2573 restrictions) has to be compatible with the certificate types 2574 listed in CertificateRequest: 2576 Client Cert. Type Certificate Key Type 2578 rsa_sign RSA public key; the certificate MUST allow the 2579 key to be used for signing with the signature 2580 scheme and hash algorithm that will be 2581 employed in the certificate verify message. 2583 dss_sign DSA public key; the certificate MUST allow the 2584 key to be used for signing with the hash 2585 algorithm that will be employed in the 2586 certificate verify message. 2588 ecdsa_sign ECDSA-capable public key; the certificate MUST 2589 allow the key to be used for signing with the 2590 hash algorithm that will be employed in the 2591 certificate verify message; the public key 2592 MUST use a curve and point format supported by 2593 the server. 2595 rsa_fixed_dh Diffie-Hellman public key; MUST use the same 2596 dss_fixed_dh parameters as server's key. 2598 rsa_fixed_ecdh ECDH-capable public key; MUST use the 2599 ecdsa_fixed_ecdh same curve as the server's key, and MUST use a 2600 point format supported by the server. 2602 - If the certificate_authorities list in the certificate request 2603 message was non-empty, one of the certificates in the certificate 2604 chain SHOULD be issued by one of the listed CAs. 2606 - The certificates MUST be signed using an acceptable hash/ 2607 signature algorithm pair, as described in Section 7.4.4. Note 2608 that this relaxes the constraints on certificate-signing 2609 algorithms found in prior versions of TLS. 2611 Note that, as with the server certificate, there are certificates 2612 that use algorithms/algorithm combinations that cannot be currently 2613 used with TLS. 2615 7.4.7. Client Key Exchange Message 2617 When this message will be sent: 2619 This message is always sent by the client. It MUST immediately 2620 follow the client certificate message, if it is sent. Otherwise, 2621 it MUST be the first message sent by the client after it receives 2622 the ServerHelloDone message. 2624 Meaning of this message: 2626 With this message, the premaster secret is set, either by direct 2627 transmission of the RSA-encrypted secret or by the transmission of 2628 Diffie-Hellman parameters that will allow each side to agree upon 2629 the same premaster secret. 2631 When the client is using an ephemeral Diffie-Hellman exponent, 2632 then this message contains the client's Diffie-Hellman public 2633 value. If the client is sending a certificate containing a static 2634 DH exponent (i.e., it is doing fixed_dh client authentication), 2635 then this message MUST be sent but MUST be empty. 2637 Structure of this message: 2639 The choice of messages depends on which key exchange method has 2640 been selected. See Section 7.4.3 for the KeyExchangeAlgorithm 2641 definition. 2643 struct { 2644 select (KeyExchangeAlgorithm) { 2645 case rsa: 2646 EncryptedPreMasterSecret; 2647 case dhe_dss: 2648 case dhe_rsa: 2649 case dh_dss: 2650 case dh_rsa: 2651 case dh_anon: 2652 ClientDiffieHellmanPublic; 2653 } exchange_keys; 2654 } ClientKeyExchange; 2656 7.4.7.1. RSA-Encrypted Premaster Secret Message 2658 Meaning of this message: 2660 If RSA is being used for key agreement and authentication, the 2661 client generates a 48-byte premaster secret, encrypts it using the 2662 public key from the server's certificate, and sends the result in 2663 an encrypted premaster secret message. This structure is a 2664 variant of the ClientKeyExchange message and is not a message in 2665 itself. 2667 Structure of this message: 2669 struct { 2670 ProtocolVersion client_version; 2671 opaque random[46]; 2672 } PreMasterSecret; 2674 client_version 2675 The latest (newest) version supported by the client. This is 2676 used to detect version rollback attacks. 2678 random 2679 46 securely-generated random bytes. 2681 struct { 2682 public-key-encrypted PreMasterSecret pre_master_secret; 2683 } EncryptedPreMasterSecret; 2685 pre_master_secret 2686 This random value is generated by the client and is used to 2687 generate the master secret, as specified in 2688 [Section 8.1]. 2690 Note: The version number in the PreMasterSecret is the version 2691 offered by the client in the ClientHello.client_version, not the 2692 version negotiated for the connection. This feature is designed to 2693 prevent rollback attacks. Unfortunately, some old implementations 2694 use the negotiated version instead, and therefore checking the 2695 version number may lead to failure to interoperate with such 2696 incorrect client implementations. 2698 Client implementations MUST always send the correct version number in 2699 PreMasterSecret. If ClientHello.client_version is TLS 1.1 or higher, 2700 server implementations MUST check the version number as described in 2701 the note below. If the version number is TLS 1.0 or earlier, server 2702 implementations SHOULD check the version number, but MAY have a 2703 configuration option to disable the check. Note that if the check 2704 fails, the PreMasterSecret SHOULD be randomized as described below. 2706 Note: Attacks discovered by Bleichenbacher [BLEI] and Klima et al. 2707 [KPR03] can be used to attack a TLS server that reveals whether a 2708 particular message, when decrypted, is properly PKCS#1 formatted, 2709 contains a valid PreMasterSecret structure, or has the correct 2710 version number. 2712 As described by Klima [KPR03], these vulnerabilities can be avoided 2713 by treating incorrectly formatted message blocks and/or mismatched 2714 version numbers in a manner indistinguishable from correctly 2715 formatted RSA blocks. In other words: 2717 1. Generate a string R of 46 random bytes 2719 2. Decrypt the message to recover the plaintext M 2721 3. If the PKCS#1 padding is not correct, or the length of message M 2722 is not exactly 48 bytes: 2724 pre_master_secret = ClientHello.client_version || R 2726 else If ClientHello.client_version <= TLS 1.0, and version number 2727 check is explicitly disabled: 2729 pre_master_secret = M 2731 else: 2733 pre_master_secret = ClientHello.client_version || M[2..47] 2735 Note that explicitly constructing the pre_master_secret with the 2736 ClientHello.client_version produces an invalid master_secret if the 2737 client has sent the wrong version in the original pre_master_secret. 2739 An alternative approach is to treat a version number mismatch as a 2740 PKCS-1 formatting error and randomize the premaster secret 2741 completely: 2743 1. Generate a string R of 48 random bytes 2745 2. Decrypt the message to recover the plaintext M 2747 3. If the PKCS#1 padding is not correct, or the length of message M 2748 is not exactly 48 bytes: 2750 pre_master_secret = R 2752 else If ClientHello.client_version <= TLS 1.0, and version number 2753 check is explicitly disabled: 2755 premaster secret = M 2756 else If M[0..1] != ClientHello.client_version: 2758 premaster secret = R 2760 else: 2762 premaster secret = M 2764 Although no practical attacks against this construction are known, 2765 Klima et al. [KPR03] describe some theoretical attacks, and 2766 therefore the first construction described is RECOMMENDED. 2768 In any case, a TLS server MUST NOT generate an alert if processing an 2769 RSA-encrypted premaster secret message fails, or the version number 2770 is not as expected. Instead, it MUST continue the handshake with a 2771 randomly generated premaster secret. It may be useful to log the 2772 real cause of failure for troubleshooting purposes; however, care 2773 must be taken to avoid leaking the information to an attacker 2774 (through, e.g., timing, log files, or other channels.) 2776 The RSAES-OAEP encryption scheme defined in [RFC3447] is more secure 2777 against the Bleichenbacher attack. However, for maximal 2778 compatibility with earlier versions of TLS, this specification uses 2779 the RSAES-PKCS1-v1_5 scheme. No variants of the Bleichenbacher 2780 attack are known to exist provided that the above recommendations are 2781 followed. 2783 Implementation note: Public-key-encrypted data is represented as an 2784 opaque vector <0..2^16-1> (see Section 4.7). Thus, the RSA-encrypted 2785 PreMasterSecret in a ClientKeyExchange is preceded by two length 2786 bytes. These bytes are redundant in the case of RSA because the 2787 EncryptedPreMasterSecret is the only data in the ClientKeyExchange 2788 and its length can therefore be unambiguously determined. The SSLv3 2789 specification was not clear about the encoding of public-key- 2790 encrypted data, and therefore many SSLv3 implementations do not 2791 include the length bytes -- they encode the RSA-encrypted data 2792 directly in the ClientKeyExchange message. 2794 This specification requires correct encoding of the 2795 EncryptedPreMasterSecret complete with length bytes. The resulting 2796 PDU is incompatible with many SSLv3 implementations. Implementors 2797 upgrading from SSLv3 MUST modify their implementations to generate 2798 and accept the correct encoding. Implementors who wish to be 2799 compatible with both SSLv3 and TLS should make their implementation's 2800 behavior dependent on the protocol version. 2802 Implementation note: It is now known that remote timing-based attacks 2803 on TLS are possible, at least when the client and server are on the 2804 same LAN. Accordingly, implementations that use static RSA keys MUST 2805 use RSA blinding or some other anti-timing technique, as described in 2806 [TIMING]. 2808 7.4.7.2. Client Diffie-Hellman Public Value 2810 Meaning of this message: 2812 This structure conveys the client's Diffie-Hellman public value 2813 (Yc) if it was not already included in the client's certificate. 2814 The encoding used for Yc is determined by the enumerated 2815 PublicValueEncoding. This structure is a variant of the client 2816 key exchange message, and not a message in itself. 2818 Structure of this message: 2820 enum { implicit, explicit } PublicValueEncoding; 2822 implicit 2823 If the client has sent a certificate which contains a suitable 2824 Diffie-Hellman key (for fixed_dh client authentication), then 2825 Yc is implicit and does not need to be sent again. In this 2826 case, the client key exchange message will be sent, but it MUST 2827 be empty. 2829 explicit 2830 Yc needs to be sent. 2832 struct { 2833 select (PublicValueEncoding) { 2834 case implicit: struct { }; 2835 case explicit: opaque dh_Yc<1..2^16-1>; 2836 } dh_public; 2837 } ClientDiffieHellmanPublic; 2839 dh_Yc 2840 The client's Diffie-Hellman public value (Yc). 2842 7.4.8. Certificate Verify 2844 When this message will be sent: 2846 This message is used to provide explicit verification of a client 2847 certificate. This message is only sent following a client 2848 certificate that has signing capability (i.e., all certificates 2849 except those containing fixed Diffie-Hellman parameters). When 2850 sent, it MUST immediately follow the client key exchange message. 2852 Structure of this message: 2854 struct { 2855 digitally-signed struct { 2856 opaque handshake_messages[handshake_messages_length]; 2857 } 2858 } CertificateVerify; 2860 Here handshake_messages refers to all handshake messages sent or 2861 received, starting at client hello and up to, but not including, 2862 this message, including the type and length fields of the 2863 handshake messages. This is the concatenation of all the 2864 Handshake structures (as defined in Section 7.4) exchanged thus 2865 far. Note that this requires both sides to either buffer the 2866 messages or compute running hashes for all potential hash 2867 algorithms up to the time of the CertificateVerify computation. 2868 Servers can minimize this computation cost by offering a 2869 restricted set of digest algorithms in the CertificateRequest 2870 message. 2872 The hash and signature algorithms used in the signature MUST be 2873 one of those present in the supported_signature_algorithms field 2874 of the CertificateRequest message. In addition, the hash and 2875 signature algorithms MUST be compatible with the key in the 2876 client's end-entity certificate. RSA keys MAY be used with any 2877 permitted hash algorithm, subject to restrictions in the 2878 certificate, if any. 2880 Because DSA signatures do not contain any secure indication of 2881 hash algorithm, there is a risk of hash substitution if multiple 2882 hashes may be used with any key. Currently, DSA [DSS] may only be 2883 used with SHA-1. Future revisions of DSS [DSS-3] are expected to 2884 allow the use of other digest algorithms with DSA, as well as 2885 guidance as to which digest algorithms should be used with each 2886 key size. In addition, future revisions of [RFC3280] may specify 2887 mechanisms for certificates to indicate which digest algorithms 2888 are to be used with DSA. 2890 7.4.9. Finished 2892 When this message will be sent: 2894 A Finished message is always sent immediately after a change 2895 cipher spec message to verify that the key exchange and 2896 authentication processes were successful. It is essential that a 2897 change cipher spec message be received between the other handshake 2898 messages and the Finished message. 2900 Meaning of this message: 2902 The Finished message is the first one protected with the just 2903 negotiated algorithms, keys, and secrets. Recipients of Finished 2904 messages MUST verify that the contents are correct. Once a side 2905 has sent its Finished message and received and validated the 2906 Finished message from its peer, it may begin to send and receive 2907 application data over the connection. 2909 Structure of this message: 2911 struct { 2912 opaque verify_data[verify_data_length]; 2913 } Finished; 2915 verify_data 2916 PRF(master_secret, finished_label, Hash(handshake_messages)) 2917 [0..verify_data_length-1]; 2919 finished_label 2920 For Finished messages sent by the client, the string 2921 "client finished". For Finished messages sent by the server, 2922 the string "server finished". 2924 Hash denotes a Hash of the handshake messages. For the PRF 2925 defined in Section 5, the Hash MUST be the Hash used as the basis 2926 for the PRF. Any cipher suite which defines a different PRF MUST 2927 also define the Hash to use in the Finished computation. 2929 In previous versions of TLS, the verify_data was always 12 octets 2930 long. In the current version of TLS, it depends on the cipher 2931 suite. Any cipher suite which does not explicitly specify 2932 verify_data_length has a verify_data_length equal to 12. This 2933 includes all existing cipher suites. Note that this 2934 representation has the same encoding as with previous versions. 2935 Future cipher suites MAY specify other lengths but such length 2936 MUST be at least 12 bytes. 2938 handshake_messages 2939 All of the data from all messages in this handshake (not including 2940 any HelloRequest messages) up to, but not including, this message. 2941 This is only data visible at the handshake layer and does not 2942 include record layer headers. This is the concatenation of all 2943 the Handshake structures as defined in Section 7.4, exchanged thus 2944 far. 2946 It is a fatal error if a Finished message is not preceded by a 2947 ChangeCipherSpec message at the appropriate point in the handshake. 2949 The value handshake_messages includes all handshake messages starting 2950 at ClientHello up to, but not including, this Finished message. This 2951 may be different from handshake_messages in Section 7.4.8 because it 2952 would include the CertificateVerify message (if sent). Also, the 2953 handshake_messages for the Finished message sent by the client will 2954 be different from that for the Finished message sent by the server, 2955 because the one that is sent second will include the prior one. 2957 Note: ChangeCipherSpec messages, alerts, and any other record types 2958 are not handshake messages and are not included in the hash 2959 computations. Also, HelloRequest messages are omitted from handshake 2960 hashes. 2962 8. Cryptographic Computations 2964 In order to begin connection protection, the TLS Record Protocol 2965 requires specification of a suite of algorithms, a master secret, and 2966 the client and server random values. The authentication, encryption, 2967 and MAC algorithms are determined by the cipher_suite selected by the 2968 server and revealed in the ServerHello message. The compression 2969 algorithm is negotiated in the hello messages, and the random values 2970 are exchanged in the hello messages. All that remains is to 2971 calculate the master secret. 2973 8.1. Computing the Master Secret 2975 For all key exchange methods, the same algorithm is used to convert 2976 the pre_master_secret into the master_secret. The pre_master_secret 2977 should be deleted from memory once the master_secret has been 2978 computed. 2980 master_secret = PRF(pre_master_secret, "master secret", 2981 ClientHello.random + ServerHello.random) 2982 [0..47]; 2984 The master secret is always exactly 48 bytes in length. The length 2985 of the premaster secret will vary depending on key exchange method. 2987 8.1.1. RSA 2989 When RSA is used for server authentication and key exchange, a 48- 2990 byte pre_master_secret is generated by the client, encrypted under 2991 the server's public key, and sent to the server. The server uses its 2992 private key to decrypt the pre_master_secret. Both parties then 2993 convert the pre_master_secret into the master_secret, as specified 2994 above. 2996 8.1.2. Diffie-Hellman 2998 A conventional Diffie-Hellman computation is performed. The 2999 negotiated key (Z) is used as the pre_master_secret, and is converted 3000 into the master_secret, as specified above. Leading bytes of Z that 3001 contain all zero bits are stripped before it is used as the 3002 pre_master_secret. 3004 Note: Diffie-Hellman parameters are specified by the server and may 3005 be either ephemeral or contained within the server's certificate. 3007 9. Mandatory Cipher Suites 3009 In the absence of an application profile standard specifying 3010 otherwise, a TLS-compliant application MUST implement the cipher 3011 suite TLS_RSA_WITH_AES_128_CBC_SHA (see Appendix A.5 for the 3012 definition). 3014 10. Application Data Protocol 3016 Application data messages are carried by the record layer and are 3017 fragmented, compressed, and encrypted based on the current connection 3018 state. The messages are treated as transparent data to the record 3019 layer. 3021 11. Security Considerations 3023 Security issues are discussed throughout this memo, especially in 3024 Appendices D, E, and F. 3026 12. IANA Considerations 3028 This document uses several registries that were originally created in 3029 [RFC4346]. IANA has updated these to reference this document. The 3030 registries and their allocation policies (unchanged from [RFC4346]) 3031 are listed below. 3033 - TLS ClientCertificateType Identifiers Registry: Future values in 3034 the range 0-63 (decimal) inclusive are assigned via Standards 3035 Action [RFC2434]. Values in the range 64-223 (decimal) inclusive 3036 are assigned via Specification Required [RFC2434]. Values from 3037 224-255 (decimal) inclusive are reserved for Private Use 3038 [RFC2434]. 3040 - TLS Cipher Suite Registry: Future values with the first byte in 3041 the range 0-191 (decimal) inclusive are assigned via Standards 3042 Action [RFC2434]. Values with the first byte in the range 192-254 3043 (decimal) are assigned via Specification Required [RFC2434]. 3044 Values with the first byte 255 (decimal) are reserved for Private 3045 Use [RFC2434]. 3047 - This document defines several new HMAC-SHA256-based cipher suites, 3048 whose values (in Appendix A.5) have been allocated from the TLS 3049 Cipher Suite registry. 3051 - TLS ContentType Registry: Future values are allocated via 3052 Standards Action [RFC2434]. 3054 - TLS Alert Registry: Future values are allocated via Standards 3055 Action [RFC2434]. 3057 - TLS HandshakeType Registry: Future values are allocated via 3058 Standards Action [RFC2434]. 3060 This document also uses a registry originally created in [RFC4366]. 3061 IANA has updated it to reference this document. The registry and its 3062 allocation policy (unchanged from [RFC4366]) is listed below: 3064 - TLS ExtensionType Registry: Future values are allocated via IETF 3065 Consensus [RFC2434]. IANA has updated this registry to include 3066 the signature_algorithms extension and its corresponding value 3067 (see Section 7.4.1.4). 3069 In addition, this document defines two new registries to be 3070 maintained by IANA: 3072 - TLS SignatureAlgorithm Registry: The registry has been initially 3073 populated with the values described in Section 7.4.1.4.1. Future 3074 values in the range 0-63 (decimal) inclusive are assigned via 3075 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 3076 inclusive are assigned via Specification Required [RFC2434]. 3077 Values from 224-255 (decimal) inclusive are reserved for Private 3078 Use [RFC2434]. 3080 - TLS HashAlgorithm Registry: The registry has been initially 3081 populated with the values described in Section 7.4.1.4.1. Future 3082 values in the range 0-63 (decimal) inclusive are assigned via 3083 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 3084 inclusive are assigned via Specification Required [RFC2434]. 3085 Values from 224-255 (decimal) inclusive are reserved for Private 3086 Use [RFC2434]. 3088 This document also uses the TLS Compression Method Identifiers 3089 Registry, defined in [RFC3749]. IANA has allocated value 0 for the 3090 "null" compression method. 3092 13. References 3094 13.1. Normative References 3096 [AES] National Institute of Standards and Technology, 3097 "Specification for the Advanced Encryption Standard 3098 (AES)", NIST FIPS 197, November 2001. 3100 [DSS] National Institute of Standards and Technology, U.S. 3101 Department of Commerce, "Digital Signature Standard", 3102 NIST FIPS PUB 186-2, 2000. 3104 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", 3105 RFC 1321, April 1992. 3107 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3108 Hashing for Message Authentication", RFC 2104, 3109 February 1997. 3111 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3112 Requirement Levels", BCP 14, RFC 2119, March 1997. 3114 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3115 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 3116 October 1998. 3118 [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet 3119 X.509 Public Key Infrastructure Certificate and 3120 Certificate Revocation List (CRL) Profile", RFC 3280, 3121 April 2002. 3123 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3124 Standards (PKCS) #1: RSA Cryptography Specifications 3125 Version 2.1", RFC 3447, February 2003. 3127 [SCH] Schneier, B., "Applied Cryptography: Protocols, 3128 Algorithms, and Source Code in C, 2nd ed.", 1996. 3130 [SHS] National Institute of Standards and Technology, U.S. 3131 Department of Commerce, "Secure Hash Standard", 3132 NIST FIPS PUB 180-2, August 2002. 3134 [TRIPLEDES] National Institute of Standards and Technology, 3135 "Recommendation for the Triple Data Encryption Algorithm 3136 (TDEA) Block Cipher", NIST Special Publication 800-67, 3137 May 2004. 3139 [X680] ITU-T, "Information technology - Abstract Syntax 3140 Notation One (ASN.1): Specification of basic notation", 3141 ISO/IEC 8824-1:2002, 2002. 3143 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 3144 Specification of Basic Encoding Rules (BER), Canonical 3145 Encoding Rules (CER) and Distinguished Encoding Rules 3146 (DER)", ISO/IEC 8825-1:2002, 2002. 3148 13.2. Informative References 3150 [BLEI] Bleichenbacher, D., "Chosen Ciphertext Attacks against 3151 Protocols Based on RSA Encryption Standard PKCS", 3152 CRYPTO98 LNCS vol. 1462, pages: 1-12, 1998, Advances in 3153 Cryptology, 1998. 3155 [CBCATT] Moeller, B., "Security of CBC Ciphersuites in SSL/TLS: 3156 Problems and Countermeasures", May 2004, 3157 . 3159 [CBCTIME] Canvel, B., Hiltgen, A., Vaudenay, S., and M. Vuagnoux, 3160 "Password Interception in a SSL/TLS Channel", CRYPTO 3161 2003 LNCS vol. 2729, 2003. 3163 [CCM] "NIST Special Publication 800-38C: The CCM Mode for 3164 Authentication and Confidentiality", May 2004, . 3168 [DES] "Data Encryption Standard (DES)", NIST FIPS PUB 46-3, 3169 October 1999. 3171 [DSS-3] National Institute of Standards and Technology, U.S., 3172 "Digital Signature Standard", NIST FIPS PUB 186-3 Draft, 3173 2006. 3175 [ECDSA] American National Standards Institute, "Public Key 3176 Cryptography for the Financial Services Industry: The 3177 Elliptic Curve Digital Signature Algorithm (ECDSA)", 3178 ANSI ANS X9.62-2005, November 2005. 3180 [ENCAUTH] Krawczyk, H., "The Order of Encryption and 3181 Authentication for Protecting Communications (Or: How 3182 Secure is SSL?)", 2001. 3184 [FI06] "Bleichenbacher's RSA signature forgery based on 3185 implementation error", August 2006, . 3188 [GCM] Dworkin, M., "Recommendation for Block Cipher Modes of 3189 Operation: Galois/Counter Mode (GCM) and GMAC", 3190 NIST Special Publication 800-38D, November 2007. 3192 [KPR03] Klima, V., Pokorny, O., and T. Rosa, "Attacking RSA- 3193 based Sessions in SSL/TLS", March 2003, 3194 . 3196 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate 3197 Syntax Standard, version 1.5", November 1993. 3199 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message 3200 Syntax Standard, version 1.5", November 1993. 3202 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3203 RFC 793, September 1981. 3205 [RFC1948] Bellovin, S., "Defending Against Sequence Number 3206 Attacks", RFC 1948, May 1996. 3208 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 3209 RFC 2246, January 1999. 3211 [RFC2785] Zuccherato, R., "Methods for Avoiding the "Small- 3212 Subgroup" Attacks on the Diffie-Hellman Key Agreement 3213 Method for S/MIME", RFC 2785, March 2000. 3215 [RFC3268] Chown, P., "Advanced Encryption Standard (AES) 3216 Ciphersuites for Transport Layer Security (TLS)", 3217 RFC 3268, June 2002. 3219 [RFC3526] Kivinen, T. and M. Kojo, "More Modular Exponential 3220 (MODP) Diffie-Hellman groups for Internet Key Exchange 3221 (IKE)", RFC 3526, May 2003. 3223 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 3224 Compression Methods", RFC 3749, May 2004. 3226 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 3227 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 3228 RFC 3766, April 2004. 3230 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 3231 Requirements for Security", BCP 106, RFC 4086, 3232 June 2005. 3234 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key 3235 Ciphersuites for Transport Layer Security (TLS)", 3236 RFC 4279, December 2005. 3238 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 3239 December 2005. 3241 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 3242 RFC 4303, December 2005. 3244 [RFC4307] Schiller, J., "Cryptographic Algorithms for Use in the 3245 Internet Key Exchange Version 2 (IKEv2)", RFC 4307, 3246 December 2005. 3248 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer 3249 Security (TLS) Protocol Version 1.1", RFC 4346, 3250 April 2006. 3252 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, 3253 J., and T. Wright, "Transport Layer Security (TLS) 3254 Extensions", RFC 4366, April 2006. 3256 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and 3257 B. Moeller, "Elliptic Curve Cryptography (ECC) Cipher 3258 Suites for Transport Layer Security (TLS)", RFC 4492, 3259 May 2006. 3261 [RFC4506] Eisler, M., "XDR: External Data Representation 3262 Standard", STD 67, RFC 4506, May 2006. 3264 [RFC5081] Mavrogiannopoulos, N., "Using OpenPGP Keys for Transport 3265 Layer Security (TLS) Authentication", RFC 5081, 3266 November 2007. 3268 [RFC5116] McGrew, D., "An Interface and Algorithms for 3269 Authenticated Encryption", RFC 5116, January 2008. 3271 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 3272 Obtaining Digital Signatures and Public-Key 3273 Cryptosystems", Communications of the ACM v. 21, n. 2, 3274 pp. 120-126., February 1978. 3276 [SSL2] Netscape Communications Corp., "The SSL Protocol", 3277 February 1995. 3279 [SSL3] Freier, A., Karlton, P., and P. Kocher, "The SSL 3.0 3280 Protocol", November 1996. 3282 [TIMING] Boneh, D. and D. Brumley, "Remote timing attacks are 3283 practical", USENIX Security Symposium, 2003. 3285 [TLSEXT] Eastlake 3rd, D., "Transport Layer Security (TLS) 3286 Extensions: Extension Definitions", February 2008. 3288 [X501] "Information Technology - Open Systems Interconnection - 3289 The Directory: Models", ITU-T X.501, 1993. 3291 URIs 3293 [1] 3295 Appendix A. Protocol Data Structures and Constant Values 3297 This section describes protocol types and constants. 3299 A.1. Record Layer 3301 struct { 3302 uint8 major; 3303 uint8 minor; 3304 } ProtocolVersion; 3306 ProtocolVersion version = { 3, 3 }; /* TLS v1.2*/ 3308 enum { 3309 change_cipher_spec(20), alert(21), handshake(22), 3310 application_data(23), (255) 3311 } ContentType; 3313 struct { 3314 ContentType type; 3315 ProtocolVersion version; 3316 uint16 length; 3317 opaque fragment[TLSPlaintext.length]; 3318 } TLSPlaintext; 3320 struct { 3321 ContentType type; 3322 ProtocolVersion version; 3323 uint16 length; 3324 opaque fragment[TLSCompressed.length]; 3325 } TLSCompressed; 3327 struct { 3328 ContentType type; 3329 ProtocolVersion version; 3330 uint16 length; 3331 select (SecurityParameters.cipher_type) { 3332 case stream: GenericStreamCipher; 3333 case block: GenericBlockCipher; 3334 case aead: GenericAEADCipher; 3335 } fragment; 3336 } TLSCiphertext; 3338 stream-ciphered struct { 3339 opaque content[TLSCompressed.length]; 3340 opaque MAC[SecurityParameters.mac_length]; 3341 } GenericStreamCipher; 3343 struct { 3344 opaque IV[SecurityParameters.record_iv_length]; 3345 block-ciphered struct { 3346 opaque content[TLSCompressed.length]; 3347 opaque MAC[SecurityParameters.mac_length]; 3348 uint8 padding[GenericBlockCipher.padding_length]; 3349 uint8 padding_length; 3350 }; 3351 } GenericBlockCipher; 3353 struct { 3354 opaque nonce_explicit[SecurityParameters.record_iv_length]; 3355 aead-ciphered struct { 3356 opaque content[TLSCompressed.length]; 3357 }; 3358 } GenericAEADCipher; 3360 A.2. Change Cipher Specs Message 3362 struct { 3363 enum { change_cipher_spec(1), (255) } type; 3364 } ChangeCipherSpec; 3366 A.3. Alert Messages 3368 enum { warning(1), fatal(2), (255) } AlertLevel; 3370 enum { 3371 close_notify(0), 3372 unexpected_message(10), 3373 bad_record_mac(20), 3374 decryption_failed_RESERVED(21), 3375 record_overflow(22), 3376 decompression_failure(30), 3377 handshake_failure(40), 3378 no_certificate_RESERVED(41), 3379 bad_certificate(42), 3380 unsupported_certificate(43), 3381 certificate_revoked(44), 3382 certificate_expired(45), 3383 certificate_unknown(46), 3384 illegal_parameter(47), 3385 unknown_ca(48), 3386 access_denied(49), 3387 decode_error(50), 3388 decrypt_error(51), 3389 export_restriction_RESERVED(60), 3390 protocol_version(70), 3391 insufficient_security(71), 3392 internal_error(80), 3393 user_canceled(90), 3394 no_renegotiation(100), 3395 unsupported_extension(110), /* new */ 3396 (255) 3397 } AlertDescription; 3399 struct { 3400 AlertLevel level; 3401 AlertDescription description; 3402 } Alert; 3404 A.4. Handshake Protocol 3406 enum { 3407 hello_request(0), client_hello(1), server_hello(2), 3408 certificate(11), server_key_exchange (12), 3409 certificate_request(13), server_hello_done(14), 3410 certificate_verify(15), client_key_exchange(16), 3411 finished(20) 3412 (255) 3413 } HandshakeType; 3415 struct { 3416 HandshakeType msg_type; 3417 uint24 length; 3418 select (HandshakeType) { 3419 case hello_request: HelloRequest; 3420 case client_hello: ClientHello; 3421 case server_hello: ServerHello; 3422 case certificate: Certificate; 3423 case server_key_exchange: ServerKeyExchange; 3424 case certificate_request: CertificateRequest; 3425 case server_hello_done: ServerHelloDone; 3426 case certificate_verify: CertificateVerify; 3427 case client_key_exchange: ClientKeyExchange; 3428 case finished: Finished; 3429 } body; 3430 } Handshake; 3432 A.4.1. Hello Messages 3434 struct { } HelloRequest; 3436 struct { 3437 uint32 gmt_unix_time; 3438 opaque random_bytes[28]; 3439 } Random; 3441 opaque SessionID<0..32>; 3443 uint8 CipherSuite[2]; 3445 enum { null(0), (255) } CompressionMethod; 3447 struct { 3448 ProtocolVersion client_version; 3449 Random random; 3450 SessionID session_id; 3451 CipherSuite cipher_suites<2..2^16-2>; 3452 CompressionMethod compression_methods<1..2^8-1>; 3453 select (extensions_present) { 3454 case false: 3455 struct {}; 3456 case true: 3457 Extension extensions<0..2^16-1>; 3458 }; 3459 } ClientHello; 3461 struct { 3462 ProtocolVersion server_version; 3463 Random random; 3464 SessionID session_id; 3465 CipherSuite cipher_suite; 3466 CompressionMethod compression_method; 3467 select (extensions_present) { 3468 case false: 3469 struct {}; 3470 case true: 3471 Extension extensions<0..2^16-1>; 3472 }; 3473 } ServerHello; 3475 struct { 3476 ExtensionType extension_type; 3477 opaque extension_data<0..2^16-1>; 3478 } Extension; 3480 enum { 3481 signature_algorithms(13), (65535) 3482 } ExtensionType; 3484 enum{ 3485 none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5), 3486 sha512(6), (255) 3487 } HashAlgorithm; 3488 enum { 3489 anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) 3490 } SignatureAlgorithm; 3492 struct { 3493 HashAlgorithm hash; 3494 SignatureAlgorithm signature; 3495 } SignatureAndHashAlgorithm; 3497 SignatureAndHashAlgorithm 3498 supported_signature_algorithms<2..2^16-1>; 3500 A.4.2. Server Authentication and Key Exchange Messages 3502 opaque ASN.1Cert<2^24-1>; 3504 struct { 3505 ASN.1Cert certificate_list<0..2^24-1>; 3506 } Certificate; 3508 enum { dhe_dss, dhe_rsa, dh_anon, rsa,dh_dss, dh_rsa 3509 /* may be extended, e.g., for ECDH -- see [TLSECC] */ 3510 } KeyExchangeAlgorithm; 3512 struct { 3513 opaque dh_p<1..2^16-1>; 3514 opaque dh_g<1..2^16-1>; 3515 opaque dh_Ys<1..2^16-1>; 3516 } ServerDHParams; /* Ephemeral DH parameters */ 3518 struct { 3519 select (KeyExchangeAlgorithm) { 3520 case dh_anon: 3521 ServerDHParams params; 3522 case dhe_dss: 3523 case dhe_rsa: 3524 ServerDHParams params; 3525 digitally-signed struct { 3526 opaque client_random[32]; 3527 opaque server_random[32]; 3528 ServerDHParams params; 3529 } signed_params; 3530 case rsa: 3531 case dh_dss: 3532 case dh_rsa: 3533 struct {} ; 3534 /* message is omitted for rsa, dh_dss, and dh_rsa */ 3535 /* may be extended, e.g., for ECDH --- see [RFC4492] */ 3536 } ServerKeyExchange; 3538 enum { 3539 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 3540 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 3541 fortezza_dms_RESERVED(20), 3542 (255) 3543 } ClientCertificateType; 3545 opaque DistinguishedName<1..2^16-1>; 3547 struct { 3548 ClientCertificateType certificate_types<1..2^8-1>; 3549 DistinguishedName certificate_authorities<0..2^16-1>; 3550 } CertificateRequest; 3552 struct { } ServerHelloDone; 3554 A.4.3. Client Authentication and Key Exchange Messages 3556 struct { 3557 select (KeyExchangeAlgorithm) { 3558 case rsa: 3559 EncryptedPreMasterSecret; 3560 case dhe_dss: 3561 case dhe_rsa: 3562 case dh_dss: 3563 case dh_rsa: 3564 case dh_anon: 3565 ClientDiffieHellmanPublic; 3566 } exchange_keys; 3567 } ClientKeyExchange; 3569 struct { 3570 ProtocolVersion client_version; 3571 opaque random[46]; 3572 } PreMasterSecret; 3574 struct { 3575 public-key-encrypted PreMasterSecret pre_master_secret; 3576 } EncryptedPreMasterSecret; 3578 enum { implicit, explicit } PublicValueEncoding; 3580 struct { 3581 select (PublicValueEncoding) { 3582 case implicit: struct {}; 3583 case explicit: opaque DH_Yc<1..2^16-1>; 3584 } dh_public; 3585 } ClientDiffieHellmanPublic; 3587 struct { 3588 digitally-signed struct { 3589 opaque handshake_messages[handshake_messages_length]; 3590 } 3591 } CertificateVerify; 3593 A.4.4. Handshake Finalization Message 3595 struct { 3596 opaque verify_data[verify_data_length]; 3597 } Finished; 3599 A.5. The Cipher Suite 3601 The following values define the cipher suite codes used in the 3602 ClientHello and ServerHello messages. 3604 A cipher suite defines a cipher specification supported in TLS 3605 Version 1.2. 3607 TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a 3608 TLS connection during the first handshake on that channel, but MUST 3609 NOT be negotiated, as it provides no more protection than an 3610 unsecured connection. 3612 CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 }; 3614 The following CipherSuite definitions require that the server provide 3615 an RSA certificate that can be used for key exchange. The server may 3616 request any signature-capable certificate in the certificate request 3617 message. 3619 CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 }; 3620 CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 }; 3621 CipherSuite TLS_RSA_WITH_NULL_SHA256 = { 0x00,0x3B }; 3622 CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 }; 3623 CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 }; 3624 CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A }; 3625 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x2F }; 3626 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x35 }; 3627 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,0x3C }; 3628 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,0x3D }; 3630 The following cipher suite definitions are used for server- 3631 authenticated (and optionally client-authenticated) Diffie-Hellman. 3632 DH denotes cipher suites in which the server's certificate contains 3633 the Diffie-Hellman parameters signed by the certificate authority 3634 (CA). DHE denotes ephemeral Diffie-Hellman, where the Diffie-Hellman 3635 parameters are signed by a signature-capable certificate, which has 3636 been signed by the CA. The signing algorithm used by the server is 3637 specified after the DHE component of the CipherSuite name. The 3638 server can request any signature-capable certificate from the client 3639 for client authentication, or it may request a Diffie-Hellman 3640 certificate. Any Diffie-Hellman certificate provided by the client 3641 must use the parameters (group and generator) described by the 3642 server. 3644 CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D }; 3645 CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 }; 3646 CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 }; 3647 CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 }; 3648 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x30 }; 3649 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x31 }; 3650 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x32 }; 3651 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x33 }; 3652 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x36 }; 3653 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x37 }; 3654 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x38 }; 3655 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x39 }; 3656 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA256 = { 0x00,0x3E }; 3657 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,0x3F }; 3658 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 = { 0x00,0x40 }; 3659 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,0x67 }; 3660 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA256 = { 0x00,0x68 }; 3661 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,0x69 }; 3662 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 = { 0x00,0x6A }; 3663 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,0x6B }; 3665 The following cipher suites are used for completely anonymous Diffie- 3666 Hellman communications in which neither party is authenticated. Note 3667 that this mode is vulnerable to man-in-the- middle attacks. Using 3668 this mode therefore is of limited use: These cipher suites MUST NOT 3669 be used by TLS 1.2 implementations unless the application layer has 3670 specifically requested to allow anonymous key exchange. (Anonymous 3671 key exchange may sometimes be acceptable, for example, to support 3672 opportunistic encryption when no set-up for authentication is in 3673 place, or when TLS is used as part of more complex security protocols 3674 that have other means to ensure authentication.) 3676 CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 }; 3677 CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B }; 3678 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA = { 0x00,0x34 }; 3679 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA = { 0x00,0x3A }; 3680 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA256 = { 0x00,0x6C }; 3681 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA256 = { 0x00,0x6D }; 3683 Note that using non-anonymous key exchange without actually verifying 3684 the key exchange is essentially equivalent to anonymous key exchange, 3685 and the same precautions apply. While non-anonymous key exchange 3686 will generally involve a higher computational and communicational 3687 cost than anonymous key exchange, it may be in the interest of 3688 interoperability not to disable non-anonymous key exchange when the 3689 application layer is allowing anonymous key exchange. 3691 New cipher suite values have been assigned by IANA as described in 3692 Section 12. 3694 Note: The cipher suite values { 0x00, 0x1C } and { 0x00, 0x1D } are 3695 reserved to avoid collision with Fortezza-based cipher suites in SSL 3696 3. 3698 A.6. The Security Parameters 3700 These security parameters are determined by the TLS Handshake 3701 Protocol and provided as parameters to the TLS record layer in order 3702 to initialize a connection state. SecurityParameters includes: 3704 enum { null(0), (255) } CompressionMethod; 3706 enum { server, client } ConnectionEnd; 3708 enum { tls_prf_sha256 } PRFAlgorithm; 3710 enum { null, rc4, 3des, aes } BulkCipherAlgorithm; 3712 enum { stream, block, aead } CipherType; 3714 enum { null, hmac_md5, hmac_sha1, hmac_sha256, hmac_sha384, 3715 hmac_sha512} MACAlgorithm; 3717 /* Other values may be added to the algorithms specified in 3718 CompressionMethod, PRFAlgorithm, BulkCipherAlgorithm, and 3719 MACAlgorithm. */ 3721 struct { 3722 ConnectionEnd entity; 3723 PRFAlgorithm prf_algorithm; 3724 BulkCipherAlgorithm bulk_cipher_algorithm; 3725 CipherType cipher_type; 3726 uint8 enc_key_length; 3727 uint8 block_length; 3728 uint8 fixed_iv_length; 3729 uint8 record_iv_length; 3730 MACAlgorithm mac_algorithm; 3731 uint8 mac_length; 3732 uint8 mac_key_length; 3733 CompressionMethod compression_algorithm; 3734 opaque master_secret[48]; 3735 opaque client_random[32]; 3736 opaque server_random[32]; 3738 } SecurityParameters; 3740 A.7. Changes to RFC 4492 3742 RFC 4492 [RFC4492] adds Elliptic Curve cipher suites to TLS. This 3743 document changes some of the structures used in that document. This 3744 section details the required changes for implementors of both RFC 3745 4492 and TLS 1.2. Implementors of TLS 1.2 who are not implementing 3746 RFC 4492 do not need to read this section. 3748 This document adds a "signature_algorithm" field to the digitally- 3749 signed element in order to identify the signature and digest 3750 algorithms used to create a signature. This change applies to 3751 digital signatures formed using ECDSA as well, thus allowing ECDSA 3752 signatures to be used with digest algorithms other than SHA-1, 3753 provided such use is compatible with the certificate and any 3754 restrictions imposed by future revisions of [RFC3280]. 3756 As described in Section 7.4.2 and Section 7.4.6, the restrictions on 3757 the signature algorithms used to sign certificates are no longer tied 3758 to the cipher suite (when used by the server) or the 3759 ClientCertificateType (when used by the client). Thus, the 3760 restrictions on the algorithm used to sign certificates specified in 3761 Sections 2 and 3 of RFC 4492 are also relaxed. As in this document, 3762 the restrictions on the keys in the end-entity certificate remain. 3764 Appendix B. Glossary 3766 Advanced Encryption Standard (AES) 3767 AES [AES] is a widely used symmetric encryption algorithm. AES is 3768 a block cipher with a 128-, 192-, or 256-bit keys and a 16-byte 3769 block size. TLS currently only supports the 128- and 256-bit key 3770 sizes. 3772 application protocol 3773 An application protocol is a protocol that normally layers 3774 directly on top of the transport layer (e.g., TCP/IP). Examples 3775 include HTTP, TELNET, FTP, and SMTP. 3777 asymmetric cipher 3778 See public key cryptography. 3780 authenticated encryption with additional data (AEAD) 3781 A symmetric encryption algorithm that simultaneously provides 3782 confidentiality and message integrity. 3784 authentication 3785 Authentication is the ability of one entity to determine the 3786 identity of another entity. 3788 block cipher 3789 A block cipher is an algorithm that operates on plaintext in 3790 groups of bits, called blocks. 64 bits was, and 128 bits is, a 3791 common block size. 3793 bulk cipher 3794 A symmetric encryption algorithm used to encrypt large quantities 3795 of data. 3797 cipher block chaining (CBC) 3798 CBC is a mode in which every plaintext block encrypted with a 3799 block cipher is first exclusive-ORed with the previous ciphertext 3800 block (or, in the case of the first block, with the initialization 3801 vector). For decryption, every block is first decrypted, then 3802 exclusive-ORed with the previous ciphertext block (or IV). 3804 certificate 3805 As part of the X.509 protocol (a.k.a. ISO Authentication 3806 framework), certificates are assigned by a trusted Certificate 3807 Authority and provide a strong binding between a party's identity 3808 or some other attributes and its public key. 3810 client 3811 The application entity that initiates a TLS connection to a 3812 server. This may or may not imply that the client initiated the 3813 underlying transport connection. The primary operational 3814 difference between the server and client is that the server is 3815 generally authenticated, while the client is only optionally 3816 authenticated. 3818 client write key 3819 The key used to encrypt data written by the client. 3821 client write MAC key 3822 The secret data used to authenticate data written by the client. 3824 connection 3825 A connection is a transport (in the OSI layering model definition) 3826 that provides a suitable type of service. For TLS, such 3827 connections are peer-to-peer relationships. The connections are 3828 transient. Every connection is associated with one session. 3830 Data Encryption Standard 3831 DES [DES] still is a very widely used symmetric encryption 3832 algorithm although it is considered as rather weak now. DES is a 3833 block cipher with a 56-bit key and an 8-byte block size. Note 3834 that in TLS, for key generation purposes, DES is treated as having 3835 an 8-byte key length (64 bits), but it still only provides 56 bits 3836 of protection. (The low bit of each key byte is presumed to be 3837 set to produce odd parity in that key byte.) DES can also be 3838 operated in a mode [TRIPLEDES] where three independent keys and 3839 three encryptions are used for each block of data; this uses 168 3840 bits of key (24 bytes in the TLS key generation method) and 3841 provides the equivalent of 112 bits of security. 3843 Digital Signature Standard (DSS) 3844 A standard for digital signing, including the Digital Signing 3845 Algorithm, approved by the National Institute of Standards and 3846 Technology, defined in NIST FIPS PUB 186-2, "Digital Signature 3847 Standard", published January 2000 by the U.S. Department of 3848 Commerce [DSS]. A significant update [DSS-3] has been drafted and 3849 was published in March 2006. 3851 digital signatures 3852 Digital signatures utilize public key cryptography and one-way 3853 hash functions to produce a signature of the data that can be 3854 authenticated, and is difficult to forge or repudiate. 3856 handshake 3857 An initial negotiation between client and server that establishes 3858 the parameters of their transactions. 3860 Initialization Vector (IV) 3861 When a block cipher is used in CBC mode, the initialization vector 3862 is exclusive-ORed with the first plaintext block prior to 3863 encryption. 3865 Message Authentication Code (MAC) 3866 A Message Authentication Code is a one-way hash computed from a 3867 message and some secret data. It is difficult to forge without 3868 knowing the secret data. Its purpose is to detect if the message 3869 has been altered. 3871 master secret 3872 Secure secret data used for generating encryption keys, MAC 3873 secrets, and IVs. 3875 MD5 3876 MD5 [RFC1321] is a hashing function that converts an arbitrarily 3877 long data stream into a hash of fixed size (16 bytes). Due to 3878 significant progress in cryptanalysis, at the time of publication 3879 of this document, MD5 no longer can be considered a 'secure' 3880 hashing function. 3882 public key cryptography 3883 A class of cryptographic techniques employing two-key ciphers. 3884 Messages encrypted with the public key can only be decrypted with 3885 the associated private key. Conversely, messages signed with the 3886 private key can be verified with the public key. 3888 one-way hash function 3889 A one-way transformation that converts an arbitrary amount of data 3890 into a fixed-length hash. It is computationally hard to reverse 3891 the transformation or to find collisions. MD5 and SHA are 3892 examples of one-way hash functions. 3894 RC4 3895 A stream cipher invented by Ron Rivest. A compatible cipher is 3896 described in [SCH]. 3898 RSA 3899 A very widely used public key algorithm that can be used for 3900 either encryption or digital signing. [RSA] 3902 server 3903 The server is the application entity that responds to requests for 3904 connections from clients. See also "client". 3906 session 3907 A TLS session is an association between a client and a server. 3908 Sessions are created by the handshake protocol. Sessions define a 3909 set of cryptographic security parameters that can be shared among 3910 multiple connections. Sessions are used to avoid the expensive 3911 negotiation of new security parameters for each connection. 3913 session identifier 3914 A session identifier is a value generated by a server that 3915 identifies a particular session. 3917 server write key 3918 The key used to encrypt data written by the server. 3920 server write MAC key 3921 The secret data used to authenticate data written by the server. 3923 SHA 3924 The Secure Hash Algorithm [SHS] is defined in FIPS PUB 180-2. It 3925 produces a 20-byte output. Note that all references to SHA 3926 (without a numerical suffix) actually use the modified SHA-1 3927 algorithm. 3929 SHA-256 3930 The 256-bit Secure Hash Algorithm is defined in FIPS PUB 180-2. 3931 It produces a 32-byte output. 3933 SSL 3934 Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on 3935 SSL Version 3.0. 3937 stream cipher 3938 An encryption algorithm that converts a key into a 3939 cryptographically strong keystream, which is then exclusive-ORed 3940 with the plaintext. 3942 symmetric cipher 3943 See bulk cipher. 3945 Transport Layer Security (TLS) 3946 This protocol; also, the Transport Layer Security working group of 3947 the Internet Engineering Task Force (IETF). See "Working Group 3948 Information" at the end of this document (see page 99). 3950 Appendix C. Cipher Suite Definitions 3952 Cipher Suite Key Cipher Mac 3953 Exchange 3955 TLS_NULL_WITH_NULL_NULL NULL NULL NULL 3956 TLS_RSA_WITH_NULL_MD5 RSA NULL MD5 3957 TLS_RSA_WITH_NULL_SHA RSA NULL SHA 3958 TLS_RSA_WITH_NULL_SHA256 RSA NULL SHA256 3959 TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5 3960 TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA 3961 TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA 3962 TLS_RSA_WITH_AES_128_CBC_SHA RSA AES_128_CBC SHA 3963 TLS_RSA_WITH_AES_256_CBC_SHA RSA AES_256_CBC SHA 3964 TLS_RSA_WITH_AES_128_CBC_SHA256 RSA AES_128_CBC SHA256 3965 TLS_RSA_WITH_AES_256_CBC_SHA256 RSA AES_256_CBC SHA256 3966 TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA 3967 TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA 3968 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA 3969 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA 3970 TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5 3971 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA 3972 TLS_DH_DSS_WITH_AES_128_CBC_SHA DH_DSS AES_128_CBC SHA 3973 TLS_DH_RSA_WITH_AES_128_CBC_SHA DH_RSA AES_128_CBC SHA 3974 TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE_DSS AES_128_CBC SHA 3975 TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE_RSA AES_128_CBC SHA 3976 TLS_DH_anon_WITH_AES_128_CBC_SHA DH_anon AES_128_CBC SHA 3977 TLS_DH_DSS_WITH_AES_256_CBC_SHA DH_DSS AES_256_CBC SHA 3978 TLS_DH_RSA_WITH_AES_256_CBC_SHA DH_RSA AES_256_CBC SHA 3979 TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE_DSS AES_256_CBC SHA 3980 TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE_RSA AES_256_CBC SHA 3981 TLS_DH_anon_WITH_AES_256_CBC_SHA DH_anon AES_256_CBC SHA 3982 TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH_DSS AES_128_CBC SHA256 3983 TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH_RSA AES_128_CBC SHA256 3984 TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE_DSS AES_128_CBC SHA256 3985 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE_RSA AES_128_CBC SHA256 3986 TLS_DH_anon_WITH_AES_128_CBC_SHA256 DH_anon AES_128_CBC SHA256 3987 TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH_DSS AES_256_CBC SHA256 3988 TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH_RSA AES_256_CBC SHA256 3989 TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE_DSS AES_256_CBC SHA256 3990 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE_RSA AES_256_CBC SHA256 3991 TLS_DH_anon_WITH_AES_256_CBC_SHA256 DH_anon AES_256_CBC SHA256 3993 Key IV Block 3994 Cipher Type Material Size Size 3995 ------------ ------ -------- ---- ----- 3996 NULL Stream 0 0 N/A 3997 RC4_128 Stream 16 0 N/A 3998 3DES_EDE_CBC Block 24 8 8 3999 AES_128_CBC Block 16 16 16 4000 AES_256_CBC Block 32 16 16 4002 MAC Algorithm mac_length mac_key_length 4003 -------- ----------- ---------- -------------- 4004 NULL N/A 0 0 4005 MD5 HMAC-MD5 16 16 4006 SHA HMAC-SHA1 20 20 4007 SHA256 HMAC-SHA256 32 32 4009 Type 4010 Indicates whether this is a stream cipher or a block cipher 4011 running in CBC mode. 4013 Key Material 4014 The number of bytes from the key_block that are used for 4015 generating the write keys. 4017 IV Size 4018 The amount of data needed to be generated for the initialization 4019 vector. Zero for stream ciphers; equal to the block size for 4020 block ciphers (this is equal to 4021 SecurityParameters.record_iv_length). 4023 Block Size 4024 The amount of data a block cipher enciphers in one chunk; a block 4025 cipher running in CBC mode can only encrypt an even multiple of 4026 its block size. 4028 Appendix D. Implementation Notes 4030 The TLS protocol cannot prevent many common security mistakes. This 4031 section provides several recommendations to assist implementors. 4033 D.1. Random Number Generation and Seeding 4035 TLS requires a cryptographically secure pseudorandom number generator 4036 (PRNG). Care must be taken in designing and seeding PRNGs. PRNGs 4037 based on secure hash operations, most notably SHA-1, are acceptable, 4038 but cannot provide more security than the size of the random number 4039 generator state. 4041 To estimate the amount of seed material being produced, add the 4042 number of bits of unpredictable information in each seed byte. For 4043 example, keystroke timing values taken from a PC compatible's 18.2 Hz 4044 timer provide 1 or 2 secure bits each, even though the total size of 4045 the counter value is 16 bits or more. Seeding a 128-bit PRNG would 4046 thus require approximately 100 such timer values. 4048 [RFC4086] provides guidance on the generation of random values. 4050 D.2. Certificates and Authentication 4052 Implementations are responsible for verifying the integrity of 4053 certificates and should generally support certificate revocation 4054 messages. Certificates should always be verified to ensure proper 4055 signing by a trusted Certificate Authority (CA). The selection and 4056 addition of trusted CAs should be done very carefully. Users should 4057 be able to view information about the certificate and root CA. 4059 D.3. Cipher Suites 4061 TLS supports a range of key sizes and security levels, including some 4062 that provide no or minimal security. A proper implementation will 4063 probably not support many cipher suites. For instance, anonymous 4064 Diffie-Hellman is strongly discouraged because it cannot prevent man- 4065 in-the-middle attacks. Applications should also enforce minimum and 4066 maximum key sizes. For example, certificate chains containing 512- 4067 bit RSA keys or signatures are not appropriate for high-security 4068 applications. 4070 D.4. Implementation Pitfalls 4072 Implementation experience has shown that certain parts of earlier TLS 4073 specifications are not easy to understand, and have been a source of 4074 interoperability and security problems. Many of these areas have 4075 been clarified in this document, but this appendix contains a short 4076 list of the most important things that require special attention from 4077 implementors. 4079 TLS protocol issues: 4081 - Do you correctly handle handshake messages that are fragmented to 4082 multiple TLS records (see Section 6.2.1)? Including corner cases 4083 like a ClientHello that is split to several small fragments? Do 4084 you fragment handshake messages that exceed the maximum fragment 4085 size? In particular, the certificate and certificate request 4086 handshake messages can be large enough to require fragmentation. 4088 - Do you ignore the TLS record layer version number in all TLS 4089 records before ServerHello (see Appendix E.1)? 4091 - Do you handle TLS extensions in ClientHello correctly, including 4092 omitting the extensions field completely? 4094 - Do you support renegotiation, both client and server initiated? 4095 While renegotiation is an optional feature, supporting it is 4096 highly recommended. 4098 - When the server has requested a client certificate, but no 4099 suitable certificate is available, do you correctly send an empty 4100 Certificate message, instead of omitting the whole message (see 4101 Section 7.4.6)? 4103 Cryptographic details: 4105 - In the RSA-encrypted Premaster Secret, do you correctly send and 4106 verify the version number? When an error is encountered, do you 4107 continue the handshake to avoid the Bleichenbacher attack (see 4108 Section 7.4.7.1)? 4110 - What countermeasures do you use to prevent timing attacks against 4111 RSA decryption and signing operations (see Section 7.4.7.1)? 4113 - When verifying RSA signatures, do you accept both NULL and missing 4114 parameters (see Section 4.7)? Do you verify that the RSA padding 4115 doesn't have additional data after the hash value? [FI06] 4117 - When using Diffie-Hellman key exchange, do you correctly strip 4118 leading zero bytes from the negotiated key (see Section 8.1.2)? 4120 - Does your TLS client check that the Diffie-Hellman parameters sent 4121 by the server are acceptable (see Appendix F.1.1.3)? 4123 - How do you generate unpredictable IVs for CBC mode ciphers (see 4124 Section 6.2.3.2)? 4126 - Do you accept long CBC mode padding (up to 255 bytes; see 4127 Section 6.2.3.2? 4129 - How do you address CBC mode timing attacks (Section 6.2.3.2)? 4131 - Do you use a strong and, most importantly, properly seeded random 4132 number generator (see Appendix D.1) for generating the premaster 4133 secret (for RSA key exchange), Diffie-Hellman private values, the 4134 DSA "k" parameter, and other security-critical values? 4136 Appendix E. Backward Compatibility 4138 E.1. Compatibility with TLS 1.0/1.1 and SSL 3.0 4140 Since there are various versions of TLS (1.0, 1.1, 1.2, and any 4141 future versions) and SSL (2.0 and 3.0), means are needed to negotiate 4142 the specific protocol version to use. The TLS protocol provides a 4143 built-in mechanism for version negotiation so as not to bother other 4144 protocol components with the complexities of version selection. 4146 TLS versions 1.0, 1.1, and 1.2, and SSL 3.0 are very similar, and use 4147 compatible ClientHello messages; thus, supporting all of them is 4148 relatively easy. Similarly, servers can easily handle clients trying 4149 to use future versions of TLS as long as the ClientHello format 4150 remains compatible, and the client supports the highest protocol 4151 version available in the server. 4153 A TLS 1.2 client who wishes to negotiate with such older servers will 4154 send a normal TLS 1.2 ClientHello, containing { 3, 3 } (TLS 1.2) in 4155 ClientHello.client_version. If the server does not support this 4156 version, it will respond with a ServerHello containing an older 4157 version number. If the client agrees to use this version, the 4158 negotiation will proceed as appropriate for the negotiated protocol. 4160 If the version chosen by the server is not supported by the client 4161 (or not acceptable), the client MUST send a "protocol_version" alert 4162 message and close the connection. 4164 If a TLS server receives a ClientHello containing a version number 4165 greater than the highest version supported by the server, it MUST 4166 reply according to the highest version supported by the server. 4168 A TLS server can also receive a ClientHello containing a version 4169 number smaller than the highest supported version. If the server 4170 wishes to negotiate with old clients, it will proceed as appropriate 4171 for the highest version supported by the server that is not greater 4172 than ClientHello.client_version. For example, if the server supports 4173 TLS 1.0, 1.1, and 1.2, and client_version is TLS 1.0, the server will 4174 proceed with a TLS 1.0 ServerHello. If server supports (or is 4175 willing to use) only versions greater than client_version, it MUST 4176 send a "protocol_version" alert message and close the connection. 4178 Whenever a client already knows the highest protocol version known to 4179 a server (for example, when resuming a session), it SHOULD initiate 4180 the connection in that native protocol. 4182 Note: some server implementations are known to implement version 4183 negotiation incorrectly. For example, there are buggy TLS 1.0 4184 servers that simply close the connection when the client offers a 4185 version newer than TLS 1.0. Also, it is known that some servers will 4186 refuse the connection if any TLS extensions are included in 4187 ClientHello. Interoperability with such buggy servers is a complex 4188 topic beyond the scope of this document, and may require multiple 4189 connection attempts by the client. 4191 Earlier versions of the TLS specification were not fully clear on 4192 what the record layer version number (TLSPlaintext.version) should 4193 contain when sending ClientHello (i.e., before it is known which 4194 version of the protocol will be employed). Thus, TLS servers 4195 compliant with this specification MUST accept any value {03,XX} as 4196 the record layer version number for ClientHello. 4198 TLS clients that wish to negotiate with older servers MAY send any 4199 value {03,XX} as the record layer version number. Typical values 4200 would be {03,00}, the lowest version number supported by the client, 4201 and the value of ClientHello.client_version. No single value will 4202 guarantee interoperability with all old servers, but this is a 4203 complex topic beyond the scope of this document. 4205 E.2. Compatibility with SSL 2.0 4207 TLS 1.2 clients that wish to support SSL 2.0 servers MUST send 4208 version 2.0 CLIENT-HELLO messages defined in [SSL2]. The message 4209 MUST contain the same version number as would be used for ordinary 4210 ClientHello, and MUST encode the supported TLS cipher suites in the 4211 CIPHER-SPECS-DATA field as described below. 4213 Warning: The ability to send version 2.0 CLIENT-HELLO messages will 4214 be phased out with all due haste, since the newer ClientHello format 4215 provides better mechanisms for moving to newer versions and 4216 negotiating extensions. TLS 1.2 clients SHOULD NOT support SSL 2.0. 4218 However, even TLS servers that do not support SSL 2.0 MAY accept 4219 version 2.0 CLIENT-HELLO messages. The message is presented below in 4220 sufficient detail for TLS server implementors; the true definition is 4221 still assumed to be [SSL2]. 4223 For negotiation purposes, 2.0 CLIENT-HELLO is interpreted the same 4224 way as a ClientHello with a "null" compression method and no 4225 extensions. Note that this message MUST be sent directly on the 4226 wire, not wrapped as a TLS record. For the purposes of calculating 4227 Finished and CertificateVerify, the msg_length field is not 4228 considered to be a part of the handshake message. 4230 uint8 V2CipherSpec[3]; 4231 struct { 4232 uint16 msg_length; 4233 uint8 msg_type; 4234 Version version; 4235 uint16 cipher_spec_length; 4236 uint16 session_id_length; 4237 uint16 challenge_length; 4238 V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length]; 4239 opaque session_id[V2ClientHello.session_id_length]; 4240 opaque challenge[V2ClientHello.challenge_length; 4241 } V2ClientHello; 4243 msg_length 4244 The highest bit MUST be 1; the remaining bits contain the length 4245 of the following data in bytes. 4247 msg_type 4248 This field, in conjunction with the version field, identifies a 4249 version 2 ClientHello message. The value MUST be 1. 4251 version 4252 Equal to ClientHello.client_version. 4254 cipher_spec_length 4255 This field is the total length of the field cipher_specs. It 4256 cannot be zero and MUST be a multiple of the V2CipherSpec length 4257 (3). 4259 session_id_length 4260 This field MUST have a value of zero for a client that claims to 4261 support TLS 1.2. 4263 challenge_length 4264 The length in bytes of the client's challenge to the server to 4265 authenticate itself. Historically, permissible values are between 4266 16 and 32 bytes inclusive. When using the SSLv2 backward- 4267 compatible handshake the client SHOULD use a 32-byte challenge. 4269 cipher_specs 4270 This is a list of all CipherSpecs the client is willing and able 4271 to use. In addition to the 2.0 cipher specs defined in [SSL2], 4272 this includes the TLS cipher suites normally sent in 4273 ClientHello.cipher_suites, with each cipher suite prefixed by a 4274 zero byte. For example, the TLS cipher suite {0x00,0x0A} would be 4275 sent as {0x00,0x00,0x0A}. 4277 session_id 4278 This field MUST be empty. 4280 challenge 4281 Corresponds to ClientHello.random. If the challenge length is 4282 less than 32, the TLS server will pad the data with leading (note: 4283 not trailing) zero bytes to make it 32 bytes long. 4285 Note: Requests to resume a TLS session MUST use a TLS client hello. 4287 E.3. Avoiding Man-in-the-Middle Version Rollback 4289 When TLS clients fall back to Version 2.0 compatibility mode, they 4290 MUST use special PKCS#1 block formatting. This is done so that TLS 4291 servers will reject Version 2.0 sessions with TLS-capable clients. 4293 When a client negotiates SSL 2.0 but also supports TLS, it MUST set 4294 the right-hand (least-significant) 8 random bytes of the PKCS padding 4295 (not including the terminal null of the padding) for the RSA 4296 encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY 4297 to 0x03 (the other padding bytes are random). 4299 When a TLS-capable server negotiates SSL 2.0 it SHOULD, after 4300 decrypting the ENCRYPTED-KEY-DATA field, check that these 8 padding 4301 bytes are 0x03. If they are not, the server SHOULD generate a random 4302 value for SECRET-KEY-DATA, and continue the handshake (which will 4303 eventually fail since the keys will not match). Note that reporting 4304 the error situation to the client could make the server vulnerable to 4305 attacks described in [BLEI]. 4307 Appendix F. Security Analysis 4309 The TLS protocol is designed to establish a secure connection between 4310 a client and a server communicating over an insecure channel. This 4311 document makes several traditional assumptions, including that 4312 attackers have substantial computational resources and cannot obtain 4313 secret information from sources outside the protocol. Attackers are 4314 assumed to have the ability to capture, modify, delete, replay, and 4315 otherwise tamper with messages sent over the communication channel. 4316 This appendix outlines how TLS has been designed to resist a variety 4317 of attacks. 4319 F.1. Handshake Protocol 4321 The handshake protocol is responsible for selecting a cipher spec and 4322 generating a master secret, which together comprise the primary 4323 cryptographic parameters associated with a secure session. The 4324 handshake protocol can also optionally authenticate parties who have 4325 certificates signed by a trusted certificate authority. 4327 F.1.1. Authentication and Key Exchange 4329 TLS supports three authentication modes: authentication of both 4330 parties, server authentication with an unauthenticated client, and 4331 total anonymity. Whenever the server is authenticated, the channel 4332 is secure against man-in-the-middle attacks, but completely anonymous 4333 sessions are inherently vulnerable to such attacks. Anonymous 4334 servers cannot authenticate clients. If the server is authenticated, 4335 its certificate message must provide a valid certificate chain 4336 leading to an acceptable certificate authority. Similarly, 4337 authenticated clients must supply an acceptable certificate to the 4338 server. Each party is responsible for verifying that the other's 4339 certificate is valid and has not expired or been revoked. 4341 The general goal of the key exchange process is to create a 4342 pre_master_secret known to the communicating parties and not to 4343 attackers. The pre_master_secret will be used to generate the 4344 master_secret (see Section 8.1). The master_secret is required to 4345 generate the Finished messages, encryption keys, and MAC keys (see 4346 Section 7.4.9 and Section 6.3). By sending a correct Finished 4347 message, parties thus prove that they know the correct 4348 pre_master_secret. 4350 F.1.1.1. Anonymous Key Exchange 4352 Completely anonymous sessions can be established using Diffie-Hellman 4353 for key exchange. The server's public parameters are contained in 4354 the server key exchange message, and the client's are sent in the 4355 client key exchange message. Eavesdroppers who do not know the 4356 private values should not be able to find the Diffie-Hellman result 4357 (i.e., the pre_master_secret). 4359 Warning: Completely anonymous connections only provide protection 4360 against passive eavesdropping. Unless an independent tamper-proof 4361 channel is used to verify that the Finished messages were not 4362 replaced by an attacker, server authentication is required in 4363 environments where active man-in-the-middle attacks are a concern. 4365 F.1.1.2. RSA Key Exchange and Authentication 4367 With RSA, key exchange and server authentication are combined. The 4368 public key is contained in the server's certificate. Note that 4369 compromise of the server's static RSA key results in a loss of 4370 confidentiality for all sessions protected under that static key. 4371 TLS users desiring Perfect Forward Secrecy should use DHE cipher 4372 suites. The damage done by exposure of a private key can be limited 4373 by changing one's private key (and certificate) frequently. 4375 After verifying the server's certificate, the client encrypts a 4376 pre_master_secret with the server's public key. By successfully 4377 decoding the pre_master_secret and producing a correct Finished 4378 message, the server demonstrates that it knows the private key 4379 corresponding to the server certificate. 4381 When RSA is used for key exchange, clients are authenticated using 4382 the certificate verify message (see Section 7.4.8). The client signs 4383 a value derived from all preceding handshake messages. These 4384 handshake messages include the server certificate, which binds the 4385 signature to the server, and ServerHello.random, which binds the 4386 signature to the current handshake process. 4388 F.1.1.3. Diffie-Hellman Key Exchange with Authentication 4390 When Diffie-Hellman key exchange is used, the server can either 4391 supply a certificate containing fixed Diffie-Hellman parameters or 4392 use the server key exchange message to send a set of temporary 4393 Diffie-Hellman parameters signed with a DSA or RSA certificate. 4394 Temporary parameters are hashed with the hello.random values before 4395 signing to ensure that attackers do not replay old parameters. In 4396 either case, the client can verify the certificate or signature to 4397 ensure that the parameters belong to the server. 4399 If the client has a certificate containing fixed Diffie-Hellman 4400 parameters, its certificate contains the information required to 4401 complete the key exchange. Note that in this case the client and 4402 server will generate the same Diffie-Hellman result (i.e., 4403 pre_master_secret) every time they communicate. To prevent the 4404 pre_master_secret from staying in memory any longer than necessary, 4405 it should be converted into the master_secret as soon as possible. 4406 Client Diffie-Hellman parameters must be compatible with those 4407 supplied by the server for the key exchange to work. 4409 If the client has a standard DSA or RSA certificate or is 4410 unauthenticated, it sends a set of temporary parameters to the server 4411 in the client key exchange message, then optionally uses a 4412 certificate verify message to authenticate itself. 4414 If the same DH keypair is to be used for multiple handshakes, either 4415 because the client or server has a certificate containing a fixed DH 4416 keypair or because the server is reusing DH keys, care must be taken 4417 to prevent small subgroup attacks. Implementations SHOULD follow the 4418 guidelines found in [RFC2785]. 4420 Small subgroup attacks are most easily avoided by using one of the 4421 DHE cipher suites and generating a fresh DH private key (X) for each 4422 handshake. If a suitable base (such as 2) is chosen, g^X mod p can 4423 be computed very quickly; therefore, the performance cost is 4424 minimized. Additionally, using a fresh key for each handshake 4425 provides Perfect Forward Secrecy. Implementations SHOULD generate a 4426 new X for each handshake when using DHE cipher suites. 4428 Because TLS allows the server to provide arbitrary DH groups, the 4429 client should verify that the DH group is of suitable size as defined 4430 by local policy. The client SHOULD also verify that the DH public 4431 exponent appears to be of adequate size. [RFC3766] provides a useful 4432 guide to the strength of various group sizes. The server MAY choose 4433 to assist the client by providing a known group, such as those 4434 defined in [RFC4307] or [RFC3526]. These can be verified by simple 4435 comparison. 4437 F.1.2. Version Rollback Attacks 4439 Because TLS includes substantial improvements over SSL Version 2.0, 4440 attackers may try to make TLS-capable clients and servers fall back 4441 to Version 2.0. This attack can occur if (and only if) two TLS- 4442 capable parties use an SSL 2.0 handshake. 4444 Although the solution using non-random PKCS #1 block type 2 message 4445 padding is inelegant, it provides a reasonably secure way for Version 4446 3.0 servers to detect the attack. This solution is not secure 4447 against attackers who can brute-force the key and substitute a new 4448 ENCRYPTED-KEY-DATA message containing the same key (but with normal 4449 padding) before the application-specified wait threshold has expired. 4450 Altering the padding of the least-significant 8 bytes of the PKCS 4451 padding does not impact security for the size of the signed hashes 4452 and RSA key lengths used in the protocol, since this is essentially 4453 equivalent to increasing the input block size by 8 bytes. 4455 F.1.3. Detecting Attacks Against the Handshake Protocol 4457 An attacker might try to influence the handshake exchange to make the 4458 parties select different encryption algorithms than they would 4459 normally choose. 4461 For this attack, an attacker must actively change one or more 4462 handshake messages. If this occurs, the client and server will 4463 compute different values for the handshake message hashes. As a 4464 result, the parties will not accept each others' Finished messages. 4465 Without the master_secret, the attacker cannot repair the Finished 4466 messages, so the attack will be discovered. 4468 F.1.4. Resuming Sessions 4470 When a connection is established by resuming a session, new 4471 ClientHello.random and ServerHello.random values are hashed with the 4472 session's master_secret. Provided that the master_secret has not 4473 been compromised and that the secure hash operations used to produce 4474 the encryption keys and MAC keys are secure, the connection should be 4475 secure and effectively independent from previous connections. 4476 Attackers cannot use known encryption keys or MAC secrets to 4477 compromise the master_secret without breaking the secure hash 4478 operations. 4480 Sessions cannot be resumed unless both the client and server agree. 4481 If either party suspects that the session may have been compromised, 4482 or that certificates may have expired or been revoked, it should 4483 force a full handshake. An upper limit of 24 hours is suggested for 4484 session ID lifetimes, since an attacker who obtains a master_secret 4485 may be able to impersonate the compromised party until the 4486 corresponding session ID is retired. Applications that may be run in 4487 relatively insecure environments should not write session IDs to 4488 stable storage. 4490 F.2. Protecting Application Data 4492 The master_secret is hashed with the ClientHello.random and 4493 ServerHello.random to produce unique data encryption keys and MAC 4494 secrets for each connection. 4496 Outgoing data is protected with a MAC before transmission. To 4497 prevent message replay or modification attacks, the MAC is computed 4498 from the MAC key, the sequence number, the message length, the 4499 message contents, and two fixed character strings. The message type 4500 field is necessary to ensure that messages intended for one TLS 4501 record layer client are not redirected to another. The sequence 4502 number ensures that attempts to delete or reorder messages will be 4503 detected. Since sequence numbers are 64 bits long, they should never 4504 overflow. Messages from one party cannot be inserted into the 4505 other's output, since they use independent MAC keys. Similarly, the 4506 server write and client write keys are independent, so stream cipher 4507 keys are used only once. 4509 If an attacker does break an encryption key, all messages encrypted 4510 with it can be read. Similarly, compromise of a MAC key can make 4511 message-modification attacks possible. Because MACs are also 4512 encrypted, message-alteration attacks generally require breaking the 4513 encryption algorithm as well as the MAC. 4515 Note: MAC keys may be larger than encryption keys, so messages can 4516 remain tamper resistant even if encryption keys are broken. 4518 F.3. Explicit IVs 4520 [CBCATT] describes a chosen plaintext attack on TLS that depends on 4521 knowing the IV for a record. Previous versions of TLS [RFC2246] used 4522 the CBC residue of the previous record as the IV and therefore 4523 enabled this attack. This version uses an explicit IV in order to 4524 protect against this attack. 4526 F.4. Security of Composite Cipher Modes 4528 TLS secures transmitted application data via the use of symmetric 4529 encryption and authentication functions defined in the negotiated 4530 cipher suite. The objective is to protect both the integrity and 4531 confidentiality of the transmitted data from malicious actions by 4532 active attackers in the network. It turns out that the order in 4533 which encryption and authentication functions are applied to the data 4534 plays an important role for achieving this goal [ENCAUTH]. 4536 The most robust method, called encrypt-then-authenticate, first 4537 applies encryption to the data and then applies a MAC to the 4538 ciphertext. This method ensures that the integrity and 4539 confidentiality goals are obtained with ANY pair of encryption and 4540 MAC functions, provided that the former is secure against chosen 4541 plaintext attacks and that the MAC is secure against chosen-message 4542 attacks. TLS uses another method, called authenticate-then-encrypt, 4543 in which first a MAC is computed on the plaintext and then the 4544 concatenation of plaintext and MAC is encrypted. This method has 4545 been proven secure for CERTAIN combinations of encryption functions 4546 and MAC functions, but it is not guaranteed to be secure in general. 4547 In particular, it has been shown that there exist perfectly secure 4548 encryption functions (secure even in the information-theoretic sense) 4549 that combined with any secure MAC function, fail to provide the 4550 confidentiality goal against an active attack. Therefore, new cipher 4551 suites and operation modes adopted into TLS need to be analyzed under 4552 the authenticate-then-encrypt method to verify that they achieve the 4553 stated integrity and confidentiality goals. 4555 Currently, the security of the authenticate-then-encrypt method has 4556 been proven for some important cases. One is the case of stream 4557 ciphers in which a computationally unpredictable pad of the length of 4558 the message, plus the length of the MAC tag, is produced using a 4559 pseudorandom generator and this pad is exclusive-ORed with the 4560 concatenation of plaintext and MAC tag. The other is the case of CBC 4561 mode using a secure block cipher. In this case, security can be 4562 shown if one applies one CBC encryption pass to the concatenation of 4563 plaintext and MAC and uses a new, independent, and unpredictable IV 4564 for each new pair of plaintext and MAC. In versions of TLS prior to 4565 1.1, CBC mode was used properly EXCEPT that it used a predictable IV 4566 in the form of the last block of the previous ciphertext. This made 4567 TLS open to chosen plaintext attacks. This version of the protocol 4568 is immune to those attacks. For exact details in the encryption 4569 modes proven secure, see [ENCAUTH]. 4571 F.5. Denial of Service 4573 TLS is susceptible to a number of denial-of-service (DoS) attacks. 4574 In particular, an attacker who initiates a large number of TCP 4575 connections can cause a server to consume large amounts of CPU for 4576 doing RSA decryption. However, because TLS is generally used over 4577 TCP, it is difficult for the attacker to hide his point of origin if 4578 proper TCP SYN randomization is used [RFC1948] by the TCP stack. 4580 Because TLS runs over TCP, it is also susceptible to a number of DoS 4581 attacks on individual connections. In particular, attackers can 4582 forge RSTs, thereby terminating connections, or forge partial TLS 4583 records, thereby causing the connection to stall. These attacks 4584 cannot in general be defended against by a TCP-using protocol. 4585 Implementors or users who are concerned with this class of attack 4586 should use IPsec AH [RFC4302] or ESP [RFC4303]. 4588 F.6. Final Notes 4590 For TLS to be able to provide a secure connection, both the client 4591 and server systems, keys, and applications must be secure. In 4592 addition, the implementation must be free of security errors. 4594 The system is only as strong as the weakest key exchange and 4595 authentication algorithm supported, and only trustworthy 4596 cryptographic functions should be used. Short public keys and 4597 anonymous servers should be used with great caution. Implementations 4598 and users must be careful when deciding which certificates and 4599 certificate authorities are acceptable; a dishonest certificate 4600 authority can do tremendous damage. 4602 Appendix G. Working Group Information 4604 The discussion list for the IETF TLS working group is located at the 4605 e-mail address tls@ietf.org [1]. Information on the group and 4606 information on how to subscribe to the list is at 4607 https://www1.ietf.org/mailman/listinfo/tls 4609 Archives of the list can be found at: 4610 http://www.ietf.org/mail-archive/web/tls/current/index.html 4612 Appendix H. Contributors 4614 Christopher Allen (co-editor of TLS 1.0) 4615 Alacrity Ventures 4616 ChristopherA@AlacrityManagement.com 4618 Martin Abadi 4619 University of California, Santa Cruz 4620 abadi@cs.ucsc.edu 4622 Steven M. Bellovin 4623 Columbia University 4624 smb@cs.columbia.edu 4626 Simon Blake-Wilson 4627 BCI 4628 sblakewilson@bcisse.com 4629 Ran Canetti 4630 IBM 4631 canetti@watson.ibm.com 4633 Pete Chown 4634 Skygate Technology Ltd 4635 pc@skygate.co.uk 4637 Taher Elgamal 4638 taher@securify.com 4639 Securify 4641 Pasi Eronen 4642 pasi.eronen@nokia.com 4643 Nokia 4645 Anil Gangolli 4646 anil@busybuddha.org 4648 Kipp Hickman 4650 Alfred Hoenes 4652 David Hopwood 4653 Independent Consultant 4654 david.hopwood@blueyonder.co.uk 4656 Phil Karlton (co-author of SSLv3) 4658 Paul Kocher (co-author of SSLv3) 4659 Cryptography Research 4660 paul@cryptography.com 4662 Hugo Krawczyk 4663 IBM 4664 hugo@ee.technion.ac.il 4666 Jan Mikkelsen 4667 Transactionware 4668 janm@transactionware.com 4670 Magnus Nystrom 4671 RSA Security 4672 magnus@rsasecurity.com 4674 Robert Relyea 4675 Netscape Communications 4676 relyea@netscape.com 4677 Jim Roskind 4678 Netscape Communications 4679 jar@netscape.com 4681 Michael Sabin 4683 Dan Simon 4684 Microsoft, Inc. 4685 dansimon@microsoft.com 4687 Tom Weinstein 4689 Tim Wright 4690 Vodafone 4691 timothy.wright@vodafone.com 4693 Authors' Addresses 4695 Tim Dierks 4696 Independent 4698 EMail: tim@dierks.org 4700 Eric Rescorla 4701 RTFM, Inc. 4703 EMail: ekr@rtfm.com