idnits 2.17.1 draft-ietf-tls-rfc4346-bis-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 4646. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4657. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4664. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4670. 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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 801 has weird spacing: '...gorithm bul...' == Line 2415 has weird spacing: '...ixed_dh a c...' == Line 2416 has weird spacing: '...ixed_dh a c...' == Line 2553 has weird spacing: '...ed_ecdh sam...' == Line 3434 has weird spacing: '...gorithm bul...' == (1 more instance...) -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 327 -- Looks like a reference, but probably isn't: '1' on line 327 -- Looks like a reference, but probably isn't: '3' on line 3944 -- Looks like a reference, but probably isn't: '9' on line 362 -- Looks like a reference, but probably isn't: '2' on line 3153 -- Looks like a reference, but probably isn't: '4' on line 398 -- Looks like a reference, but probably isn't: '8' on line 399 -- Looks like a reference, but probably isn't: '10' on line 509 -- Looks like a reference, but probably isn't: '48' on line 3444 -- Looks like a reference, but probably isn't: '32' on line 3446 == Missing Reference: 'ChangeCipherSpec' is mentioned on line 1680, but not defined -- Looks like a reference, but probably isn't: '28' on line 3149 == Missing Reference: 'ECDSA' is mentioned on line 2100, but not defined -- Looks like a reference, but probably isn't: '46' on line 3282 == Unused Reference: 'ECSDSA' is defined on line 4416, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. '3DES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' ** Downref: Normative reference to an Informational RFC: RFC 2104 (ref. 'HMAC') ** Downref: Normative reference to an Informational RFC: RFC 1321 (ref. 'MD5') ** Obsolete normative reference: RFC 3447 (ref. 'PKCS1') (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 3280 (ref. 'PKIX') (Obsoleted by RFC 5280) -- Possible downref: Non-RFC (?) normative reference: ref. 'SCH' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) -- Possible downref: Non-RFC (?) normative reference: ref. 'X680' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- Obsolete informational reference (is this intentional?): RFC 4307 (ref. 'IKEALG') (Obsoleted by RFC 8247) -- Obsolete informational reference (is this intentional?): RFC 4366 (Obsoleted by RFC 5246, RFC 6066) -- Obsolete informational reference (is this intentional?): RFC 1948 (ref. 'SEQNUM') (Obsoleted by RFC 6528) -- Obsolete informational reference (is this intentional?): RFC 793 (ref. 'TCP') (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 3268 (ref. 'TLSAES') (Obsoleted by RFC 5246) -- Obsolete informational reference (is this intentional?): RFC 4492 (ref. 'TLSECC') (Obsoleted by RFC 8422) == Outdated reference: A later version (-12) exists of draft-ietf-tls-rfc4366-bis-01 -- Obsolete informational reference (is this intentional?): RFC 5081 (ref. 'TLSPGP') (Obsoleted by RFC 6091) Summary: 6 errors (**), 0 flaws (~~), 11 warnings (==), 34 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Tim Dierks 3 Obsoletes (if approved): RFC 3268, 4346, 4366 Independent 4 Updates (if approved): RFC 4492 Eric Rescorla 5 Intended status: Proposed Standard Network Resonance, Inc. 6 March 2008 (Expires September 2008) 8 The Transport Layer Security (TLS) Protocol 9 Version 1.2 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 Copyright Notice 36 Copyright (C) The IETF Trust (2008). 38 Abstract 40 This document specifies Version 1.2 of the Transport Layer Security 41 (TLS) protocol. The TLS protocol provides communications security 42 over the Internet. The protocol allows client/server applications to 43 communicate in a way that is designed to prevent eavesdropping, 44 tampering, or message forgery. 46 Table of Contents 48 1. Introduction 4 49 1.1. Requirements Terminology 5 50 1.2. Major Differences from TLS 1.1 5 51 2. Goals 6 52 3. Goals of This Document 7 53 4. Presentation Language 7 54 4.1. Basic Block Size 7 55 4.2. Miscellaneous 7 56 4.3. Vectors 8 57 4.4. Numbers 9 58 4.5. Enumerateds 9 59 4.6. Constructed Types 10 60 4.6.1. Variants 10 61 4.7. Cryptographic Attributes 11 62 4.8. Constants 13 63 5. HMAC and the Pseudorandom Function 14 64 6. The TLS Record Protocol 15 65 6.1. Connection States 16 66 6.2. Record layer 18 67 6.2.1. Fragmentation 19 68 6.2.2. Record Compression and Decompression 20 69 6.2.3. Record Payload Protection 21 70 6.2.3.1. Null or Standard Stream Cipher 21 71 6.2.3.2. CBC Block Cipher 22 72 6.2.3.3. AEAD ciphers 24 73 6.3. Key Calculation 25 74 7. The TLS Handshaking Protocols 26 75 7.1. Change Cipher Spec Protocol 27 76 7.2. Alert Protocol 27 77 7.2.1. Closure Alerts 28 78 7.2.2. Error Alerts 29 79 7.3. Handshake Protocol Overview 33 80 7.4. Handshake Protocol 37 81 7.4.1. Hello Messages 38 82 7.4.1.1. Hello Request 38 83 7.4.1.2. Client Hello 39 84 7.4.1.3. Server Hello 42 85 7.4.1.4 Hello Extensions 43 86 7.4.1.4.1 Signature Algorithms 45 87 7.4.2. Server Certificate 46 88 7.4.3. Server Key Exchange Message 49 89 7.4.4. Certificate Request 51 90 7.4.5 Server Hello Done 53 91 7.4.6. Client Certificate 53 92 7.4.7. Client Key Exchange Message 55 93 7.4.7.1. RSA Encrypted Premaster Secret Message 56 94 7.4.7.2. Client Diffie-Hellman Public Value 58 95 7.4.8. Certificate verify 59 96 7.4.9. Finished 60 97 8. Cryptographic Computations 62 98 8.1. Computing the Master Secret 62 99 8.1.1. RSA 62 100 8.1.2. Diffie-Hellman 62 101 9. Mandatory Cipher Suites 63 102 10. Application Data Protocol 63 103 11. Security Considerations 63 104 12. IANA Considerations 63 105 A. Protocol Data Structures and Constant Values 65 106 A.1. Record Layer 65 107 A.2. Change Cipher Specs Message 66 108 A.3. Alert Messages 66 109 A.4. Handshake Protocol 67 110 A.4.1. Hello Messages 67 111 A.4.2. Server Authentication and Key Exchange Messages 69 112 A.4.3. Client Authentication and Key Exchange Messages 70 113 A.4.4. Handshake Finalization Message 71 114 A.5. The Cipher Suite 71 115 A.6. The Security Parameters 73 116 A.7. Changes to RFC 4492 74 117 B. Glossary 74 118 C. Cipher Suite Definitions 79 119 D. Implementation Notes 81 120 D.1 Random Number Generation and Seeding 81 121 D.2 Certificates and Authentication 81 122 D.3 Cipher Suites 81 123 D.4 Implementation Pitfalls 81 124 E. Backward Compatibility 84 125 E.1 Compatibility with TLS 1.0/1.1 and SSL 3.0 84 126 E.2 Compatibility with SSL 2.0 85 127 E.3. Avoiding Man-in-the-Middle Version Rollback 87 128 F. Security Analysis 88 129 F.1. Handshake Protocol 88 130 F.1.1. Authentication and Key Exchange 88 131 F.1.1.1. Anonymous Key Exchange 88 132 F.1.1.2. RSA Key Exchange and Authentication 89 133 F.1.1.3. Diffie-Hellman Key Exchange with Authentication 89 134 F.1.2. Version Rollback Attacks 90 135 F.1.3. Detecting Attacks Against the Handshake Protocol 91 136 F.1.4. Resuming Sessions 91 137 F.2. Protecting Application Data 91 138 F.3. Explicit IVs 92 139 F.4. Security of Composite Cipher Modes 92 140 F.5 Denial of Service 93 141 F.6 Final Notes 93 143 1. Introduction 145 The primary goal of the TLS Protocol is to provide privacy and data 146 integrity between two communicating applications. The protocol is 147 composed of two layers: the TLS Record Protocol and the TLS Handshake 148 Protocol. At the lowest level, layered on top of some reliable 149 transport protocol (e.g., TCP[TCP]), is the TLS Record Protocol. The 150 TLS Record Protocol provides connection security that has two basic 151 properties: 153 - The connection is private. Symmetric cryptography is used for 154 data encryption (e.g., AES [AES], RC4 [SCH] etc.). The keys for 155 this symmetric encryption are generated uniquely for each 156 connection and are based on a secret negotiated by another 157 protocol (such as the TLS Handshake Protocol). The Record Protocol 158 can also be used without encryption. 160 - The connection is reliable. Message transport includes a message 161 integrity check using a keyed MAC. Secure hash functions (e.g., 162 SHA-1, etc.) are used for MAC computations. The Record Protocol 163 can operate without a MAC, but is generally only used in this mode 164 while another protocol is using the Record Protocol as a transport 165 for negotiating security parameters. 167 The TLS Record Protocol is used for encapsulation of various higher- 168 level protocols. One such encapsulated protocol, the TLS Handshake 169 Protocol, allows the server and client to authenticate each other and 170 to negotiate an encryption algorithm and cryptographic keys before 171 the application protocol transmits or receives its first byte of 172 data. The TLS Handshake Protocol provides connection security that 173 has three basic properties: 175 - The peer's identity can be authenticated using asymmetric, or 176 public key, cryptography (e.g., RSA [RSA], DSA [DSS], etc.). This 177 authentication can be made optional, but is generally required for 178 at least one of the peers. 180 - The negotiation of a shared secret is secure: the negotiated 181 secret is unavailable to eavesdroppers, and for any authenticated 182 connection the secret cannot be obtained, even by an attacker who 183 can place himself in the middle of the connection. 185 - The negotiation is reliable: no attacker can modify the 186 negotiation communication without being detected by the parties to 187 the communication. 189 One advantage of TLS is that it is application protocol independent. 190 Higher-level protocols can layer on top of the TLS Protocol 191 transparently. The TLS standard, however, does not specify how 192 protocols add security with TLS; the decisions on how to initiate TLS 193 handshaking and how to interpret the authentication certificates 194 exchanged are left to the judgment of the designers and implementors 195 of protocols that run on top of TLS. 197 1.1. Requirements Terminology 199 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 200 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 201 document are to be interpreted as described in RFC 2119 [REQ]. 203 1.2. Major Differences from TLS 1.1 205 This document is a revision of the TLS 1.1 [TLS1.1] protocol which 206 contains improved flexibility, particularly for negotiation of 207 cryptographic algorithms. The major changes are: 209 - The MD5/SHA-1 combination in the pseudorandom function (PRF) has 210 been replaced with cipher suite specified PRFs. All cipher suites 211 in this document use P_SHA256. 213 - The MD5/SHA-1 combination in the digitally-signed element has been 214 replaced with a single hash. Signed elements now include a field 215 that explicitly specifies the hash algorithm used. 217 - Substantial cleanup to the client's and server's ability to 218 specify which hash and signature algorithms they will accept. Note 219 that this also relaxes some of the constraints on signature and 220 hash algorithms from previous versions of TLS. 222 - Addition of support for authenticated encryption with additional 223 data modes. 225 - TLS Extensions definition and AES Cipher Suites were merged in 226 from external [TLSEXT] and [TLSAES]. 228 - Tighter checking of EncryptedPreMasterSecret version numbers. 230 - Tightened up a number of requirements. 232 - Verify_data length now depends on the cipher suite (default is 233 still 12). 235 - Cleaned up description of Bleichenbacher/Klima attack defenses. 237 - Alerts MUST now be sent in many cases. 239 - After a certificate_request, if no certificates are available, 240 clients now MUST send an empty certificate list. 242 - TLS_RSA_WITH_AES_128_CBC_SHA is now the mandatory to implement 243 cipher suite. 245 - Added HMAC-SHA256 cipher suites 247 - Removed IDEA and DES cipher suites. They are now deprecated and 248 will be documented in a separate document. 250 - Support for the SSLv2 backward-compatible hello is now a MAY, not 251 a SHOULD, with sending it a SHOULD NOT. Support will probably 252 become a SHOULD NOT in the future. 254 - Added limited "fall-through" to the presentation language to allow 255 multiple case arms to have the same encoding. 257 - Added an Implementation Pitfalls sections 259 - The usual clarifications and editorial work. 261 2. Goals 263 The goals of TLS Protocol, in order of their priority, are as 264 follows: 266 1. Cryptographic security: TLS should be used to establish a secure 267 connection between two parties. 269 2. Interoperability: Independent programmers should be able to 270 develop applications utilizing TLS that can successfully exchange 271 cryptographic parameters without knowledge of one another's code. 273 3. Extensibility: TLS seeks to provide a framework into which new 274 public key and bulk encryption methods can be incorporated as 275 necessary. This will also accomplish two sub-goals: preventing the 276 need to create a new protocol (and risking the introduction of 277 possible new weaknesses) and avoiding the need to implement an 278 entire new security library. 280 4. Relative efficiency: Cryptographic operations tend to be highly 281 CPU intensive, particularly public key operations. For this 282 reason, the TLS protocol has incorporated an optional session 283 caching scheme to reduce the number of connections that need to be 284 established from scratch. Additionally, care has been taken to 285 reduce network activity. 287 3. Goals of This Document 289 This document and the TLS protocol itself are based on the SSL 3.0 290 Protocol Specification as published by Netscape. The differences 291 between this protocol and SSL 3.0 are not dramatic, but they are 292 significant enough that the various versions of TLS and SSL 3.0 do 293 not interoperate (although each protocol incorporates a mechanism by 294 which an implementation can back down to prior versions). This 295 document is intended primarily for readers who will be implementing 296 the protocol and for those doing cryptographic analysis of it. The 297 specification has been written with this in mind, and it is intended 298 to reflect the needs of those two groups. For that reason, many of 299 the algorithm-dependent data structures and rules are included in the 300 body of the text (as opposed to in an appendix), providing easier 301 access to them. 303 This document is not intended to supply any details of service 304 definition or of interface definition, although it does cover select 305 areas of policy as they are required for the maintenance of solid 306 security. 308 4. Presentation Language 310 This document deals with the formatting of data in an external 311 representation. The following very basic and somewhat casually 312 defined presentation syntax will be used. The syntax draws from 313 several sources in its structure. Although it resembles the 314 programming language "C" in its syntax and XDR [XDR] in both its 315 syntax and intent, it would be risky to draw too many parallels. The 316 purpose of this presentation language is to document TLS only; it has 317 no general application beyond that particular goal. 319 4.1. Basic Block Size 321 The representation of all data items is explicitly specified. The 322 basic data block size is one byte (i.e., 8 bits). Multiple byte data 323 items are concatenations of bytes, from left to right, from top to 324 bottom. From the bytestream, a multi-byte item (a numeric in the 325 example) is formed (using C notation) by: 327 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 328 ... | byte[n-1]; 330 This byte ordering for multi-byte values is the commonplace network 331 byte order or big endian format. 333 4.2. Miscellaneous 334 Comments begin with "/*" and end with "*/". 336 Optional components are denoted by enclosing them in "[[ ]]" double 337 brackets. 339 Single-byte entities containing uninterpreted data are of type 340 opaque. 342 4.3. Vectors 344 A vector (single dimensioned array) is a stream of homogeneous data 345 elements. The size of the vector may be specified at documentation 346 time or left unspecified until runtime. In either case, the length 347 declares the number of bytes, not the number of elements, in the 348 vector. The syntax for specifying a new type, T', that is a fixed- 349 length vector of type T is 351 T T'[n]; 353 Here, T' occupies n bytes in the data stream, where n is a multiple 354 of the size of T. The length of the vector is not included in the 355 encoded stream. 357 In the following example, Datum is defined to be three consecutive 358 bytes that the protocol does not interpret, while Data is three 359 consecutive Datum, consuming a total of nine bytes. 361 opaque Datum[3]; /* three uninterpreted bytes */ 362 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 364 Variable-length vectors are defined by specifying a subrange of legal 365 lengths, inclusively, using the notation . When 366 these are encoded, the actual length precedes the vector's contents 367 in the byte stream. The length will be in the form of a number 368 consuming as many bytes as required to hold the vector's specified 369 maximum (ceiling) length. A variable-length vector with an actual 370 length field of zero is referred to as an empty vector. 372 T T'; 374 In the following example, mandatory is a vector that must contain 375 between 300 and 400 bytes of type opaque. It can never be empty. The 376 actual length field consumes two bytes, a uint16, sufficient to 377 represent the value 400 (see Section 4.4). On the other hand, longer 378 can represent up to 800 bytes of data, or 400 uint16 elements, and it 379 may be empty. Its encoding will include a two-byte actual length 380 field prepended to the vector. The length of an encoded vector must 381 be an even multiple of the length of a single element (for example, a 382 17-byte vector of uint16 would be illegal). 384 opaque mandatory<300..400>; 385 /* length field is 2 bytes, cannot be empty */ 386 uint16 longer<0..800>; 387 /* zero to 400 16-bit unsigned integers */ 389 4.4. Numbers 391 The basic numeric data type is an unsigned byte (uint8). All larger 392 numeric data types are formed from fixed-length series of bytes 393 concatenated as described in Section 4.1 and are also unsigned. The 394 following numeric types are predefined. 396 uint8 uint16[2]; 397 uint8 uint24[3]; 398 uint8 uint32[4]; 399 uint8 uint64[8]; 401 All values, here and elsewhere in the specification, are stored in 402 "network" or "big-endian" order; the uint32 represented by the hex 403 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 405 Note that in some cases (e.g., DH parameters) it is necessary to 406 represent integers as opaque vectors. In such cases, they are 407 represented as unsigned integers (i.e., leading zero octets are not 408 required even if the most significant bit is set). 410 4.5. Enumerateds 412 An additional sparse data type is available called enum. A field of 413 type enum can only assume the values declared in the definition. 414 Each definition is a different type. Only enumerateds of the same 415 type may be assigned or compared. Every element of an enumerated must 416 be assigned a value, as demonstrated in the following example. Since 417 the elements of the enumerated are not ordered, they can be assigned 418 any unique value, in any order. 420 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 422 Enumerateds occupy as much space in the byte stream as would its 423 maximal defined ordinal value. The following definition would cause 424 one byte to be used to carry fields of type Color. 426 enum { red(3), blue(5), white(7) } Color; 428 One may optionally specify a value without its associated tag to 429 force the width definition without defining a superfluous element. 431 In the following example, Taste will consume two bytes in the data 432 stream but can only assume the values 1, 2, or 4. 434 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 436 The names of the elements of an enumeration are scoped within the 437 defined type. In the first example, a fully qualified reference to 438 the second element of the enumeration would be Color.blue. Such 439 qualification is not required if the target of the assignment is well 440 specified. 442 Color color = Color.blue; /* overspecified, legal */ 443 Color color = blue; /* correct, type implicit */ 445 For enumerateds that are never converted to external representation, 446 the numerical information may be omitted. 448 enum { low, medium, high } Amount; 450 4.6. Constructed Types 452 Structure types may be constructed from primitive types for 453 convenience. Each specification declares a new, unique type. The 454 syntax for definition is much like that of C. 456 struct { 457 T1 f1; 458 T2 f2; 459 ... 460 Tn fn; 461 } [[T]]; 463 The fields within a structure may be qualified using the type's name, 464 with a syntax much like that available for enumerateds. For example, 465 T.f2 refers to the second field of the previous declaration. 466 Structure definitions may be embedded. 468 4.6.1. Variants 470 Defined structures may have variants based on some knowledge that is 471 available within the environment. The selector must be an enumerated 472 type that defines the possible variants the structure defines. There 473 must be a case arm for every element of the enumeration declared in 474 the select. Case arms have limited fall-through: if two case arms 475 follow in immediate succession with no fields in between, then they 476 both contain the same fields. Thus, in the example below, "orange" 477 and "banana" both contain V2. Note that this is a new piece of syntax 478 in TLS 1.2. 480 The body of the variant structure may be given a label for reference. 481 The mechanism by which the variant is selected at runtime is not 482 prescribed by the presentation language. 484 struct { 485 T1 f1; 486 T2 f2; 487 .... 488 Tn fn; 489 select (E) { 490 case e1: Te1; 491 case e2: Te2; 492 case e3: case e4: Te3; 493 .... 494 case en: Ten; 495 } [[fv]]; 496 } [[Tv]]; 498 For example: 500 enum { apple, orange, banana } VariantTag; 502 struct { 503 uint16 number; 504 opaque string<0..10>; /* variable length */ 505 } V1; 507 struct { 508 uint32 number; 509 opaque string[10]; /* fixed length */ 510 } V2; 512 struct { 513 select (VariantTag) { /* value of selector is implicit */ 514 case apple: 515 V1; /* VariantBody, tag = apple */ 516 case orange: 517 case banana: 518 V2; /* VariantBody, tag = orange or banana */ 519 } variant_body; /* optional label on variant */ 520 } VariantRecord; 522 4.7. Cryptographic Attributes 524 The five cryptographic operations digital signing, stream cipher 525 encryption, block cipher encryption, authenticated encryption with 526 additional data (AEAD) encryption and public key encryption are 527 designated digitally-signed, stream-ciphered, block-ciphered, aead- 528 ciphered, and public-key-encrypted, respectively. A field's 529 cryptographic processing is specified by prepending an appropriate 530 key word designation before the field's type specification. 531 Cryptographic keys are implied by the current session state (see 532 Section 6.1). 534 A digitally-signed element is encoded as a struct DigitallySigned: 536 struct { 537 SignatureAndHashAlgorithm algorithm; 538 opaque signature<0..2^16-1>; 539 } DigitallySigned; 541 The algorithm field specifies the algorithm used (see Section 542 7.4.1.4.1 for the definition of this field.) Note that the 543 introduction of the algorithm field is a change from previous 544 versions. The signature is a digital signature using those 545 algorithms over the contents of the element. The contents themselves 546 do not appear on the wire but are simply calculated. The length of 547 the signature is specified by the signing algorithm and key. 549 In RSA signing, the opaque vector contains the signature generated 550 using the RSASSA-PKCS1-v1_5 signature scheme defined in [PKCS1]. As 551 discussed in [PKCS1], the DigestInfo MUST be DER [X680] [X690] 552 encoded and for hash algorithms without parameters (which include 553 SHA-1) the DigestInfo.AlgorithmIdentifier.parameters field MUST be 554 NULL but implementations MUST accept both without parameters and with 555 NULL parameters. Note that earlier versions of TLS used a different 556 RSA signature scheme which did not include a DigestInfo encoding. 558 In DSA, the 20 bytes of the SHA-1 hash are run directly through the 559 Digital Signing Algorithm with no additional hashing. This produces 560 two values, r and s. The DSA signature is an opaque vector, as above, 561 the contents of which are the DER encoding of: 563 Dss-Sig-Value ::= SEQUENCE { 564 r INTEGER, 565 s INTEGER 566 } 568 Note: In current terminology, DSA refers to the Digital Signature 569 Algorithm and DSS refers to the NIST standard. In the original 570 SSL and TLS specs, "DSS" was used universally. This document 571 uses "DSA" to refer to the algorithm, "DSS" to refer to the 572 standard, and uses "DSS" in the code point definitions for 573 historical continuity. 575 In stream cipher encryption, the plaintext is exclusive-ORed with an 576 identical amount of output generated from a cryptographically secure 577 keyed pseudorandom number generator. 579 In block cipher encryption, every block of plaintext encrypts to a 580 block of ciphertext. All block cipher encryption is done in CBC 581 (Cipher Block Chaining) mode, and all items that are block-ciphered 582 will be an exact multiple of the cipher block length. 584 In AEAD encryption, the plaintext is simultaneously encrypted and 585 integrity protected. The input may be of any length and aead-ciphered 586 output is generally larger than the input in order to accomodate the 587 integrity check value. 589 In public key encryption, a public key algorithm is used to encrypt 590 data in such a way that it can be decrypted only with the matching 591 private key. A public-key-encrypted element is encoded as an opaque 592 vector <0..2^16-1>, where the length is specified by the encryption 593 algorithm and key. 595 RSA encryption is done using the RSAES-PKCS1-v1_5 encryption scheme 596 defined in [PKCS1]. 598 In the following example 600 stream-ciphered struct { 601 uint8 field1; 602 uint8 field2; 603 digitally-signed opaque { 604 uint8 field3<0..255>; 605 uint8 field4; 606 }; 607 } UserType; 609 The contents of the inner struct (field3 and field4) are used as 610 input for the signature/hash algorithm, and then the entire structure 611 is encrypted with a stream cipher. The length of this structure, in 612 bytes, would be equal to two bytes for field1 and field2, plus two 613 bytes for the signature and hash algorithm, plus two bytes for the 614 length of the signature, plus the length of the output of the signing 615 algorithm. This is known because the algorithm and key used for the 616 signing are known prior to encoding or decoding this structure. 618 4.8. Constants 620 Typed constants can be defined for purposes of specification by 621 declaring a symbol of the desired type and assigning values to it. 623 Under-specified types (opaque, variable length vectors, and 624 structures that contain opaque) cannot be assigned values. No fields 625 of a multi-element structure or vector may be elided. 627 For example: 629 struct { 630 uint8 f1; 631 uint8 f2; 632 } Example1; 634 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 636 5. HMAC and the Pseudorandom Function 638 The TLS record layer uses a keyed Message Authentication Code (MAC) 639 to protect message integrity. The cipher suites defined in this 640 document use a construction known as HMAC, described in [HMAC], which 641 is based on a hash function. Other cipher suites MAY define their own 642 MAC constructions, if needed. 644 In addition, a construction is required to do expansion of secrets 645 into blocks of data for the purposes of key generation or validation. 646 This pseudo-random function (PRF) takes as input a secret, a seed, 647 and an identifying label and produces an output of arbitrary length. 649 In this section, we define one PRF, based on HMAC. This PRF with the 650 SHA-256 hash function is used for all cipher suites defined in this 651 document and in TLS documents published prior to this document when 652 TLS 1.2 is negotiated. New cipher suites MUST explicitly specify a 653 PRF and in general SHOULD use the TLS PRF with SHA-256 or a stronger 654 standard hash function. 656 First, we define a data expansion function, P_hash(secret, data) that 657 uses a single hash function to expand a secret and seed into an 658 arbitrary quantity of output: 660 P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) + 661 HMAC_hash(secret, A(2) + seed) + 662 HMAC_hash(secret, A(3) + seed) + ... 664 Where + indicates concatenation. 666 A() is defined as: 668 A(0) = seed 669 A(i) = HMAC_hash(secret, A(i-1)) 671 P_hash can be iterated as many times as is necessary to produce the 672 required quantity of data. For example, if P_SHA256 is being used to 673 create 80 bytes of data, it will have to be iterated three times 674 (through A(3)), creating 96 bytes of output data; the last 16 bytes 675 of the final iteration will then be discarded, leaving 80 bytes of 676 output data. 678 TLS's PRF is created by applying P_hash to the secret as: 680 PRF(secret, label, seed) = P_(secret, label + seed) 682 The label is an ASCII string. It should be included in the exact form 683 it is given without a length byte or trailing null character. For 684 example, the label "slithy toves" would be processed by hashing the 685 following bytes: 687 73 6C 69 74 68 79 20 74 6F 76 65 73 689 6. The TLS Record Protocol 691 The TLS Record Protocol is a layered protocol. At each layer, 692 messages may include fields for length, description, and content. 693 The Record Protocol takes messages to be transmitted, fragments the 694 data into manageable blocks, optionally compresses the data, applies 695 a MAC, encrypts, and transmits the result. Received data is 696 decrypted, verified, decompressed, reassembled, and then delivered to 697 higher-level clients. 699 Four protocols that use the record protocol are described in this 700 document: the handshake protocol, the alert protocol, the change 701 cipher spec protocol, and the application data protocol. In order to 702 allow extension of the TLS protocol, additional record content types 703 can be supported by the record protocol. New record content type 704 values are assigned by IANA in the TLS Content Type Registry as 705 described in Section 12. 707 Implementations MUST NOT send record types not defined in this 708 document unless negotiated by some extension. If a TLS 709 implementation receives an unexpected record type, it MUST send an 710 unexpected_message alert. 712 Any protocol designed for use over TLS must be carefully designed to 713 deal with all possible attacks against it. As a practical matter, 714 this means that the protocol designer must be aware of what security 715 properties TLS does and does not provide and cannot safely rely on 716 the latter. 718 Note in particular that type and length of a record are not protected 719 by encryption. If this information is itself sensitive, application 720 designers may wish to take steps (padding, cover traffic) to minimize 721 information leakage. 723 6.1. Connection States 725 A TLS connection state is the operating environment of the TLS Record 726 Protocol. It specifies a compression algorithm, an encryption 727 algorithm, and a MAC algorithm. In addition, the parameters for these 728 algorithms are known: the MAC key and the bulk encryption keys for 729 the connection in both the read and the write directions. Logically, 730 there are always four connection states outstanding: the current read 731 and write states, and the pending read and write states. All records 732 are processed under the current read and write states. The security 733 parameters for the pending states can be set by the TLS Handshake 734 Protocol, and the ChangeCipherSpec can selectively make either of the 735 pending states current, in which case the appropriate current state 736 is disposed of and replaced with the pending state; the pending state 737 is then reinitialized to an empty state. It is illegal to make a 738 state that has not been initialized with security parameters a 739 current state. The initial current state always specifies that no 740 encryption, compression, or MAC will be used. 742 The security parameters for a TLS Connection read and write state are 743 set by providing the following values: 745 connection end 746 Whether this entity is considered the "client" or the "server" in 747 this connection. 749 PRF algorithm 750 An algorithm used to generate keys from the master secret (see 751 Sections 5 and 6.3). 753 bulk encryption algorithm 754 An algorithm to be used for bulk encryption. This specification 755 includes the key size of this algorithm, whether it is a block, 756 stream, or AEAD cipher, the block size of the cipher (if 757 appropriate), and the lengths of explicit and implicit 758 initialization vectors (or nonces). 760 MAC algorithm 761 An algorithm to be used for message authentication. This 762 specification includes the size of the value returned by the MAC 763 algorithm. 765 compression algorithm 766 An algorithm to be used for data compression. This specification 767 must include all information the algorithm requires to do 768 compression. 770 master secret 771 A 48-byte secret shared between the two peers in the connection. 773 client random 774 A 32-byte value provided by the client. 776 server random 777 A 32-byte value provided by the server. 779 These parameters are defined in the presentation language as: 781 enum { server, client } ConnectionEnd; 783 enum { tls_prf_sha256 } PRFAlgorithm; 785 enum { null, rc4, 3des, aes } 786 BulkCipherAlgorithm; 788 enum { stream, block, aead } CipherType; 790 enum { null, hmac_md5, hmac_sha1, hmac_sha256, 791 hmac_sha384, hmac_sha512} MACAlgorithm; 793 enum { null(0), (255) } CompressionMethod; 795 /* The algorithms specified in CompressionMethod, PRFAlgorithm 796 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 798 struct { 799 ConnectionEnd entity; 800 PRFAlgorithm prf_algorithm; 801 BulkCipherAlgorithm bulk_cipher_algorithm; 802 CipherType cipher_type; 803 uint8 enc_key_length; 804 uint8 block_length; 805 uint8 fixed_iv_length; 806 uint8 record_iv_length; 807 MACAlgorithm mac_algorithm; 808 uint8 mac_length; 809 uint8 mac_key_length; 810 CompressionMethod compression_algorithm; 811 opaque master_secret[48]; 812 opaque client_random[32]; 813 opaque server_random[32]; 815 } SecurityParameters; 817 The record layer will use the security parameters to generate the 818 following six items (some of which are not required by all ciphers, 819 and are thus empty): 821 client write MAC key 822 server write MAC key 823 client write encryption key 824 server write encryption key 825 client write IV 826 server write IV 828 The client write parameters are used by the server when receiving and 829 processing records and vice-versa. The algorithm used for generating 830 these items from the security parameters is described in Section 6.3. 832 Once the security parameters have been set and the keys have been 833 generated, the connection states can be instantiated by making them 834 the current states. These current states MUST be updated for each 835 record processed. Each connection state includes the following 836 elements: 838 compression state 839 The current state of the compression algorithm. 841 cipher state 842 The current state of the encryption algorithm. This will consist 843 of the scheduled key for that connection. For stream ciphers, this 844 will also contain whatever state information is necessary to allow 845 the stream to continue to encrypt or decrypt data. 847 MAC key 848 The MAC key for this connection, as generated above. 850 sequence number 851 Each connection state contains a sequence number, which is 852 maintained separately for read and write states. The sequence 853 number MUST be set to zero whenever a connection state is made the 854 active state. Sequence numbers are of type uint64 and may not 855 exceed 2^64-1. Sequence numbers do not wrap. If a TLS 856 implementation would need to wrap a sequence number, it must 857 renegotiate instead. A sequence number is incremented after each 858 record: specifically, the first record transmitted under a 859 particular connection state MUST use sequence number 0. 861 6.2. Record layer 862 The TLS Record Layer receives uninterpreted data from higher layers 863 in non-empty blocks of arbitrary size. 865 6.2.1. Fragmentation 867 The record layer fragments information blocks into TLSPlaintext 868 records carrying data in chunks of 2^14 bytes or less. Client message 869 boundaries are not preserved in the record layer (i.e., multiple 870 client messages of the same ContentType MAY be coalesced into a 871 single TLSPlaintext record, or a single message MAY be fragmented 872 across several records). 874 struct { 875 uint8 major; 876 uint8 minor; 877 } ProtocolVersion; 879 enum { 880 change_cipher_spec(20), alert(21), handshake(22), 881 application_data(23), (255) 882 } ContentType; 884 struct { 885 ContentType type; 886 ProtocolVersion version; 887 uint16 length; 888 opaque fragment[TLSPlaintext.length]; 889 } TLSPlaintext; 891 type 892 The higher-level protocol used to process the enclosed fragment. 894 version 895 The version of the protocol being employed. This document 896 describes TLS Version 1.2, which uses the version { 3, 3 }. The 897 version value 3.3 is historical, deriving from the use of {3, 1} 898 for TLS 1.0. (See Appendix A.1). Note that a client that supports 899 multiple versions of TLS may not know what version will be 900 employed before it receives the ServerHello. See Appendix E for 901 discussion about what record layer version number should be 902 employed for ClientHello. 904 length 905 The length (in bytes) of the following TLSPlaintext.fragment. The 906 length MUST NOT exceed 2^14. 908 fragment 909 The application data. This data is transparent and treated as an 910 independent block to be dealt with by the higher-level protocol 911 specified by the type field. 913 Implementations MUST NOT send zero-length fragments of Handshake, 914 Alert, or ChangeCipherSpec content types. Zero-length fragments of 915 Application data MAY be sent as they are potentially useful as a 916 traffic analysis countermeasure. 918 Note: Data of different TLS Record layer content types MAY be 919 interleaved. Application data is generally of lower precedence for 920 transmission than other content types. However, records MUST be 921 delivered to the network in the same order as they are protected by 922 the record layer. Recipients MUST receive and process interleaved 923 application layer traffic during handshakes subsequent to the first 924 one on a connection. 926 6.2.2. Record Compression and Decompression 928 All records are compressed using the compression algorithm defined in 929 the current session state. There is always an active compression 930 algorithm; however, initially it is defined as 931 CompressionMethod.null. The compression algorithm translates a 932 TLSPlaintext structure into a TLSCompressed structure. Compression 933 functions are initialized with default state information whenever a 934 connection state is made active. [RFC3749] describes compression 935 algorithms for TLS. 937 Compression must be lossless and may not increase the content length 938 by more than 1024 bytes. If the decompression function encounters a 939 TLSCompressed.fragment that would decompress to a length in excess of 940 2^14 bytes, it MUST report a fatal decompression failure error. 942 struct { 943 ContentType type; /* same as TLSPlaintext.type */ 944 ProtocolVersion version;/* same as TLSPlaintext.version */ 945 uint16 length; 946 opaque fragment[TLSCompressed.length]; 947 } TLSCompressed; 949 length 950 The length (in bytes) of the following TLSCompressed.fragment. 951 The length MUST NOT exceed 2^14 + 1024. 953 fragment 954 The compressed form of TLSPlaintext.fragment. 956 Note: A CompressionMethod.null operation is an identity operation; no 957 fields are altered. 959 Implementation note: Decompression functions are responsible for 960 ensuring that messages cannot cause internal buffer overflows. 962 6.2.3. Record Payload Protection 964 The encryption and MAC functions translate a TLSCompressed structure 965 into a TLSCiphertext. The decryption functions reverse the process. 966 The MAC of the record also includes a sequence number so that 967 missing, extra, or repeated messages are detectable. 969 struct { 970 ContentType type; 971 ProtocolVersion version; 972 uint16 length; 973 select (SecurityParameters.cipher_type) { 974 case stream: GenericStreamCipher; 975 case block: GenericBlockCipher; 976 case aead: GenericAEADCipher; 977 } fragment; 978 } TLSCiphertext; 980 type 981 The type field is identical to TLSCompressed.type. 983 version 984 The version field is identical to TLSCompressed.version. 986 length 987 The length (in bytes) of the following TLSCiphertext.fragment. 988 The length MUST NOT exceed 2^14 + 2048. 990 fragment 991 The encrypted form of TLSCompressed.fragment, with the MAC. 993 6.2.3.1. Null or Standard Stream Cipher 995 Stream ciphers (including BulkCipherAlgorithm.null, see Appendix A.6) 996 convert TLSCompressed.fragment structures to and from stream 997 TLSCiphertext.fragment structures. 999 stream-ciphered struct { 1000 opaque content[TLSCompressed.length]; 1001 opaque MAC[SecurityParameters.mac_length]; 1002 } GenericStreamCipher; 1004 The MAC is generated as: 1006 MAC(MAC_write_key, seq_num + 1007 TLSCompressed.type + 1008 TLSCompressed.version + 1009 TLSCompressed.length + 1010 TLSCompressed.fragment); 1012 where "+" denotes concatenation. 1014 seq_num 1015 The sequence number for this record. 1017 MAC 1018 The MAC algorithm specified by SecurityParameters.mac_algorithm. 1020 Note that the MAC is computed before encryption. The stream cipher 1021 encrypts the entire block, including the MAC. For stream ciphers that 1022 do not use a synchronization vector (such as RC4), the stream cipher 1023 state from the end of one record is simply used on the subsequent 1024 packet. If the cipher suite is TLS_NULL_WITH_NULL_NULL, encryption 1025 consists of the identity operation (i.e., the data is not encrypted, 1026 and the MAC size is zero, implying that no MAC is used). For both 1027 null and stream ciphers, TLSCiphertext.length is TLSCompressed.length 1028 plus SecurityParameters.mac_length. 1030 6.2.3.2. CBC Block Cipher 1032 For block ciphers (such as 3DES, or AES), the encryption and MAC 1033 functions convert TLSCompressed.fragment structures to and from block 1034 TLSCiphertext.fragment structures. 1036 struct { 1037 opaque IV[SecurityParameters.record_iv_length]; 1038 block-ciphered struct { 1039 opaque content[TLSCompressed.length]; 1040 opaque MAC[SecurityParameters.mac_length]; 1041 uint8 padding[GenericBlockCipher.padding_length]; 1042 uint8 padding_length; 1043 }; 1044 } GenericBlockCipher; 1046 The MAC is generated as described in Section 6.2.3.1. 1048 IV 1049 The Initialization Vector (IV) SHOULD be chosen at random, and 1050 MUST be unpredictable. Note that in versions of TLS prior to 1.1, 1051 there was no IV field, and the last ciphertext block of the 1052 previous record (the "CBC residue") was used as the IV. This was 1053 changed to prevent the attacks described in [CBCATT]. For block 1054 ciphers, the IV length is of length 1055 SecurityParameters.record_iv_length which is equal to the 1056 SecurityParameters.block_size. 1058 padding 1059 Padding that is added to force the length of the plaintext to be 1060 an integral multiple of the block cipher's block length. The 1061 padding MAY be any length up to 255 bytes, as long as it results 1062 in the TLSCiphertext.length being an integral multiple of the 1063 block length. Lengths longer than necessary might be desirable to 1064 frustrate attacks on a protocol that are based on analysis of the 1065 lengths of exchanged messages. Each uint8 in the padding data 1066 vector MUST be filled with the padding length value. The receiver 1067 MUST check this padding and MUST use the bad_record_mac alert to 1068 indicate padding errors. 1070 padding_length 1071 The padding length MUST be such that the total size of the 1072 GenericBlockCipher structure is a multiple of the cipher's block 1073 length. Legal values range from zero to 255, inclusive. This 1074 length specifies the length of the padding field exclusive of the 1075 padding_length field itself. 1077 The encrypted data length (TLSCiphertext.length) is one more than the 1078 sum of SecurityParameters.block_length, TLSCompressed.length, 1079 SecurityParameters.mac_length, and padding_length. 1081 Example: If the block length is 8 bytes, the content length 1082 (TLSCompressed.length) is 61 bytes, and the MAC length is 20 bytes, 1083 then the length before padding is 82 bytes (this does not include the 1084 IV. Thus, the padding length modulo 8 must be equal to 6 in order to 1085 make the total length an even multiple of 8 bytes (the block length). 1086 The padding length can be 6, 14, 22, and so on, through 254. If the 1087 padding length were the minimum necessary, 6, the padding would be 6 1088 bytes, each containing the value 6. Thus, the last 8 octets of the 1089 GenericBlockCipher before block encryption would be xx 06 06 06 06 06 1090 06 06, where xx is the last octet of the MAC. 1092 Note: With block ciphers in CBC mode (Cipher Block Chaining), it is 1093 critical that the entire plaintext of the record be known before any 1094 ciphertext is transmitted. Otherwise, it is possible for the attacker 1095 to mount the attack described in [CBCATT]. 1097 Implementation Note: Canvel et al. [CBCTIME] have demonstrated a 1098 timing attack on CBC padding based on the time required to compute 1099 the MAC. In order to defend against this attack, implementations MUST 1100 ensure that record processing time is essentially the same whether or 1101 not the padding is correct. In general, the best way to do this is 1102 to compute the MAC even if the padding is incorrect, and only then 1103 reject the packet. For instance, if the pad appears to be incorrect, 1104 the implementation might assume a zero-length pad and then compute 1105 the MAC. This leaves a small timing channel, since MAC performance 1106 depends to some extent on the size of the data fragment, but it is 1107 not believed to be large enough to be exploitable, due to the large 1108 block size of existing MACs and the small size of the timing signal. 1110 6.2.3.3. AEAD ciphers 1112 For AEAD [AEAD] ciphers (such as [CCM] or [GCM]) the AEAD function 1113 converts TLSCompressed.fragment structures to and from AEAD 1114 TLSCiphertext.fragment structures. 1116 struct { 1117 opaque nonce_explicit[SecurityParameters.record_iv_length]; 1118 aead-ciphered struct { 1119 opaque content[TLSCompressed.length]; 1120 }; 1121 } GenericAEADCipher; 1123 AEAD ciphers take as input a single key, a nonce, a plaintext, and 1124 "additional data" to be included in the authentication check, as 1125 described in Section 2.1 of [AEAD]. The key is either the 1126 client_write_key or the server_write_key. No MAC key is used. 1128 Each AEAD cipher suite MUST specify how the nonce supplied to the 1129 AEAD operation is constructed, and what is the length of the 1130 GenericAEADCipher.nonce_explicit part. In many cases, it is 1131 appropriate to use the partially implicit nonce technique described 1132 in Section 3.2.1 of [AEAD]; with record_iv_length being the length of 1133 the explicit part. In this case, the implicit part SHOULD be derived 1134 from key_block as client_write_iv and server_write_iv (as described 1135 in Section 6.3), and the explicit part is included in 1136 GenericAEAEDCipher.nonce_explicit. 1138 The plaintext is the TLSCompressed.fragment. 1140 The additional authenticated data, which we denote as 1141 additional_data, is defined as follows: 1143 additional_data = seq_num + TLSCompressed.type + 1144 TLSCompressed.version + TLSCompressed.length; 1146 Where "+" denotes concatenation. 1148 The aead_output consists of the ciphertext output by the AEAD 1149 encryption operation. The length will generally be larger than 1150 TLSCompressed.length, but by an amount that varies with the AEAD 1151 cipher. Since the ciphers might incorporate padding, the amount of 1152 overhead could vary with different TLSCompressed.length values. Each 1153 AEAD cipher MUST NOT produce an expansion of greater than 1024 bytes. 1154 Symbolically, 1156 AEADEncrypted = AEAD-Encrypt(key, nonce, plaintext, 1157 additional_data) 1159 In order to decrypt and verify, the cipher takes as input the key, 1160 nonce, the "additional_data", and the AEADEncrypted value. The output 1161 is either the plaintext or an error indicating that the decryption 1162 failed. There is no separate integrity check. I.e., 1164 TLSCompressed.fragment = AEAD-Decrypt(write_key, nonce, 1165 AEADEncrypted, 1166 additional_data) 1168 If the decryption fails, a fatal bad_record_mac alert MUST be 1169 generated. 1171 6.3. Key Calculation 1173 The Record Protocol requires an algorithm to generate keys required 1174 by the current connection state (see Appendix A.6) from the security 1175 parameters provided by the handshake protocol. 1177 The master secret is expanded into a sequence of secure bytes, which 1178 is then split to a client write MAC key, a server write MAC key, a 1179 client write encryption key, and a server write encryption key. Each 1180 of these is generated from the byte sequence in that order. Unused 1181 values are empty. Some AEAD ciphers may additionally require a 1182 client write IV and a server write IV (see Section 6.2.3.3). 1184 When keys and MAC keys are generated, the master secret is used as an 1185 entropy source. 1187 To generate the key material, compute 1189 key_block = PRF(SecurityParameters.master_secret, 1190 "key expansion", 1191 SecurityParameters.server_random + 1192 SecurityParameters.client_random); 1194 until enough output has been generated. Then the key_block is 1195 partitioned as follows: 1197 client_write_MAC_key[SecurityParameters.mac_key_length] 1198 server_write_MAC_key[SecurityParameters.mac_key_length] 1199 client_write_key[SecurityParameters.enc_key_length] 1200 server_write_key[SecurityParameters.enc_key_length] 1201 client_write_IV[SecurityParameters.fixed_iv_length] 1202 server_write_IV[SecurityParameters.fixed_iv_length] 1204 Currently, the client_write_IV and server_write_IV are only generated 1205 for implicit nonce techniques as described in Section 3.2.1 of 1206 [AEAD]. 1208 Implementation note: The currently defined cipher suite which 1209 requires the most material is AES_256_CBC_SHA256. It requires 2 x 32 1210 byte keys and 2 x 32 byte MAC keys, for a total 128 bytes of key 1211 material. 1213 7. The TLS Handshaking Protocols 1215 TLS has three subprotocols that are used to allow peers to agree upon 1216 security parameters for the record layer, to authenticate themselves, 1217 to instantiate negotiated security parameters, and to report error 1218 conditions to each other. 1220 The Handshake Protocol is responsible for negotiating a session, 1221 which consists of the following items: 1223 session identifier 1224 An arbitrary byte sequence chosen by the server to identify an 1225 active or resumable session state. 1227 peer certificate 1228 X509v3 [PKIX] certificate of the peer. This element of the state 1229 may be null. 1231 compression method 1232 The algorithm used to compress data prior to encryption. 1234 cipher spec 1235 Specifies the pseudorandom function (PRF) used to generate keying 1236 material, the bulk data encryption algorithm (such as null, AES, 1237 etc.) and a MAC algorithm (such as HMAC-SHA1). It also defines 1238 cryptographic attributes such as the mac_length. (See Appendix A.6 1239 for formal definition.) 1241 master secret 1242 48-byte secret shared between the client and server. 1244 is resumable 1245 A flag indicating whether the session can be used to initiate new 1246 connections. 1248 These items are then used to create security parameters for use by 1249 the Record Layer when protecting application data. Many connections 1250 can be instantiated using the same session through the resumption 1251 feature of the TLS Handshake Protocol. 1253 7.1. Change Cipher Spec Protocol 1255 The change cipher spec protocol exists to signal transitions in 1256 ciphering strategies. The protocol consists of a single message, 1257 which is encrypted and compressed under the current (not the pending) 1258 connection state. The message consists of a single byte of value 1. 1260 struct { 1261 enum { change_cipher_spec(1), (255) } type; 1262 } ChangeCipherSpec; 1264 The ChangeCipherSpec message is sent by both the client and the 1265 server to notify the receiving party that subsequent records will be 1266 protected under the newly negotiated CipherSpec and keys. Reception 1267 of this message causes the receiver to instruct the Record Layer to 1268 immediately copy the read pending state into the read current state. 1269 Immediately after sending this message, the sender MUST instruct the 1270 record layer to make the write pending state the write active state. 1271 (See Section 6.1.) The change cipher spec message is sent during the 1272 handshake after the security parameters have been agreed upon, but 1273 before the verifying finished message is sent. 1275 Note: If a rehandshake occurs while data is flowing on a connection, 1276 the communicating parties may continue to send data using the old 1277 CipherSpec. However, once the ChangeCipherSpec has been sent, the new 1278 CipherSpec MUST be used. The first side to send the ChangeCipherSpec 1279 does not know that the other side has finished computing the new 1280 keying material (e.g., if it has to perform a time consuming public 1281 key operation). Thus, a small window of time, during which the 1282 recipient must buffer the data, MAY exist. In practice, with modern 1283 machines this interval is likely to be fairly short. 1285 7.2. Alert Protocol 1287 One of the content types supported by the TLS Record layer is the 1288 alert type. Alert messages convey the severity of the message 1289 (warning or fatal) and a description of the alert. Alert messages 1290 with a level of fatal result in the immediate termination of the 1291 connection. In this case, other connections corresponding to the 1292 session may continue, but the session identifier MUST be invalidated, 1293 preventing the failed session from being used to establish new 1294 connections. Like other messages, alert messages are encrypted and 1295 compressed, as specified by the current connection state. 1297 enum { warning(1), fatal(2), (255) } AlertLevel; 1299 enum { 1300 close_notify(0), 1301 unexpected_message(10), 1302 bad_record_mac(20), 1303 decryption_failed_RESERVED(21), 1304 record_overflow(22), 1305 decompression_failure(30), 1306 handshake_failure(40), 1307 no_certificate_RESERVED(41), 1308 bad_certificate(42), 1309 unsupported_certificate(43), 1310 certificate_revoked(44), 1311 certificate_expired(45), 1312 certificate_unknown(46), 1313 illegal_parameter(47), 1314 unknown_ca(48), 1315 access_denied(49), 1316 decode_error(50), 1317 decrypt_error(51), 1318 export_restriction_RESERVED(60), 1319 protocol_version(70), 1320 insufficient_security(71), 1321 internal_error(80), 1322 user_canceled(90), 1323 no_renegotiation(100), 1324 unsupported_extension(110), 1325 (255) 1326 } AlertDescription; 1328 struct { 1329 AlertLevel level; 1330 AlertDescription description; 1331 } Alert; 1333 7.2.1. Closure Alerts 1335 The client and the server must share knowledge that the connection is 1336 ending in order to avoid a truncation attack. Either party may 1337 initiate the exchange of closing messages. 1339 close_notify 1340 This message notifies the recipient that the sender will not send 1341 any more messages on this connection. Note that as of TLS 1.1, 1342 failure to properly close a connection no longer requires that a 1343 session not be resumed. This is a change from TLS 1.0 to conform 1344 with widespread implementation practice. 1346 Either party may initiate a close by sending a close_notify alert. 1347 Any data received after a closure alert is ignored. 1349 Unless some other fatal alert has been transmitted, each party is 1350 required to send a close_notify alert before closing the write side 1351 of the connection. The other party MUST respond with a close_notify 1352 alert of its own and close down the connection immediately, 1353 discarding any pending writes. It is not required for the initiator 1354 of the close to wait for the responding close_notify alert before 1355 closing the read side of the connection. 1357 If the application protocol using TLS provides that any data may be 1358 carried over the underlying transport after the TLS connection is 1359 closed, the TLS implementation must receive the responding 1360 close_notify alert before indicating to the application layer that 1361 the TLS connection has ended. If the application protocol will not 1362 transfer any additional data, but will only close the underlying 1363 transport connection, then the implementation MAY choose to close the 1364 transport without waiting for the responding close_notify. No part of 1365 this standard should be taken to dictate the manner in which a usage 1366 profile for TLS manages its data transport, including when 1367 connections are opened or closed. 1369 Note: It is assumed that closing a connection reliably delivers 1370 pending data before destroying the transport. 1372 7.2.2. Error Alerts 1374 Error handling in the TLS Handshake protocol is very simple. When an 1375 error is detected, the detecting party sends a message to the other 1376 party. Upon transmission or receipt of a fatal alert message, both 1377 parties immediately close the connection. Servers and clients MUST 1378 forget any session-identifiers, keys, and secrets associated with a 1379 failed connection. Thus, any connection terminated with a fatal alert 1380 MUST NOT be resumed. 1382 Whenever an implementation encounters a condition which is defined as 1383 a fatal alert, it MUST send the appropriate alert prior to closing 1384 the connection. For all errors where an alert level is not explicitly 1385 specified, the sending party MAY determine at its discretion whether 1386 to treat this as a fatal error or not. If the implementation chooses 1387 to send an alert but intends to close the connection immediately 1388 afterwards, it MUST send that alert at the fatal alert level. 1390 If an alert with a level of warning is sent and received, generally 1391 the connection can continue normally. If the receiving party decides 1392 not to proceed with the connection (e.g., after having received a 1393 no_renegotiation alert that it is not willing to accept), it SHOULD 1394 send a fatal alert to terminate the connection. Given this, the 1395 sending party cannot, in general, know how the receiving party will 1396 behave. Therefore, warning alerts are not very useful when the 1397 sending party wants to continue the connection, and thus are 1398 sometimes omitted. For example, if a peer decides to accept an 1399 expired certificate (perhaps after confirming this with the user) and 1400 wants to continue the connection, it would not generally send a 1401 certificate_expired alert. 1403 The following error alerts are defined: 1405 unexpected_message 1406 An inappropriate message was received. This alert is always fatal 1407 and should never be observed in communication between proper 1408 implementations. 1410 bad_record_mac 1411 This alert is returned if a record is received with an incorrect 1412 MAC. This alert also MUST be returned if an alert is sent because 1413 a TLSCiphertext decrypted in an invalid way: either it wasn't an 1414 even multiple of the block length, or its padding values, when 1415 checked, weren't correct. This message is always fatal and should 1416 never be observed in communication between proper implementations 1417 (except when messages were corrupted in the network). 1419 decryption_failed_RESERVED 1420 This alert was used in some earlier versions of TLS, and may have 1421 permitted certain attacks against the CBC mode [CBCATT]. It MUST 1422 NOT be sent by compliant implementations. 1424 record_overflow 1425 A TLSCiphertext record was received that had a length more than 1426 2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1427 with more than 2^14+1024 bytes. This message is always fatal and 1428 should never be observed in communication between proper 1429 implementations (except when messages were corrupted in the 1430 network). 1432 decompression_failure 1433 The decompression function received improper input (e.g., data 1434 that would expand to excessive length). This message is always 1435 fatal and should never be observed in communication between proper 1436 implementations. 1438 handshake_failure 1439 Reception of a handshake_failure alert message indicates that the 1440 sender was unable to negotiate an acceptable set of security 1441 parameters given the options available. This is a fatal error. 1443 no_certificate_RESERVED 1444 This alert was used in SSLv3 but not any version of TLS. It MUST 1445 NOT be sent by compliant implementations. 1447 bad_certificate 1448 A certificate was corrupt, contained signatures that did not 1449 verify correctly, etc. 1451 unsupported_certificate 1452 A certificate was of an unsupported type. 1454 certificate_revoked 1455 A certificate was revoked by its signer. 1457 certificate_expired 1458 A certificate has expired or is not currently valid. 1460 certificate_unknown 1461 Some other (unspecified) issue arose in processing the 1462 certificate, rendering it unacceptable. 1464 illegal_parameter 1465 A field in the handshake was out of range or inconsistent with 1466 other fields. This message is always fatal. 1468 unknown_ca 1469 A valid certificate chain or partial chain was received, but the 1470 certificate was not accepted because the CA certificate could not 1471 be located or couldn't be matched with a known, trusted CA. This 1472 message is always fatal. 1474 access_denied 1475 A valid certificate was received, but when access control was 1476 applied, the sender decided not to proceed with negotiation. This 1477 message is always fatal. 1479 decode_error 1480 A message could not be decoded because some field was out of the 1481 specified range or the length of the message was incorrect. This 1482 message is always fatal and should never be observed in 1483 communication between proper implementations (except when messages 1484 were corrupted in the network). 1486 decrypt_error 1487 A handshake cryptographic operation failed, including being unable 1488 to correctly verify a signature or validate a finished message. 1489 This message is always fatal. 1491 export_restriction_RESERVED 1492 This alert was used in some earlier versions of TLS. It MUST NOT 1493 be sent by compliant implementations. 1495 protocol_version 1496 The protocol version the client has attempted to negotiate is 1497 recognized but not supported. (For example, old protocol versions 1498 might be avoided for security reasons). This message is always 1499 fatal. 1501 insufficient_security 1502 Returned instead of handshake_failure when a negotiation has 1503 failed specifically because the server requires ciphers more 1504 secure than those supported by the client. This message is always 1505 fatal. 1507 internal_error 1508 An internal error unrelated to the peer or the correctness of the 1509 protocol (such as a memory allocation failure) makes it impossible 1510 to continue. This message is always fatal. 1512 user_canceled 1513 This handshake is being canceled for some reason unrelated to a 1514 protocol failure. If the user cancels an operation after the 1515 handshake is complete, just closing the connection by sending a 1516 close_notify is more appropriate. This alert should be followed by 1517 a close_notify. This message is generally a warning. 1519 no_renegotiation 1520 Sent by the client in response to a hello request or by the server 1521 in response to a client hello after initial handshaking. Either 1522 of these would normally lead to renegotiation; when that is not 1523 appropriate, the recipient should respond with this alert. At 1524 that point, the original requester can decide whether to proceed 1525 with the connection. One case where this would be appropriate is 1526 where a server has spawned a process to satisfy a request; the 1527 process might receive security parameters (key length, 1528 authentication, etc.) at startup and it might be difficult to 1529 communicate changes to these parameters after that point. This 1530 message is always a warning. 1532 unsupported_extension 1533 sent by clients that receive an extended server hello containing 1534 an extension that they did not put in the corresponding client 1535 hello. This message is always fatal. 1537 New Alert values are assigned by IANA as described in Section 12. 1539 7.3. Handshake Protocol Overview 1541 The cryptographic parameters of the session state are produced by the 1542 TLS Handshake Protocol, which operates on top of the TLS Record 1543 Layer. When a TLS client and server first start communicating, they 1544 agree on a protocol version, select cryptographic algorithms, 1545 optionally authenticate each other, and use public-key encryption 1546 techniques to generate shared secrets. 1548 The TLS Handshake Protocol involves the following steps: 1550 - Exchange hello messages to agree on algorithms, exchange random 1551 values, and check for session resumption. 1553 - Exchange the necessary cryptographic parameters to allow the 1554 client and server to agree on a premaster secret. 1556 - Exchange certificates and cryptographic information to allow the 1557 client and server to authenticate themselves. 1559 - Generate a master secret from the premaster secret and exchanged 1560 random values. 1562 - Provide security parameters to the record layer. 1564 - Allow the client and server to verify that their peer has 1565 calculated the same security parameters and that the handshake 1566 occurred without tampering by an attacker. 1568 Note that higher layers should not be overly reliant on whether TLS 1569 always negotiates the strongest possible connection between two 1570 peers. There are a number of ways in which a man in the middle 1571 attacker can attempt to make two entities drop down to the least 1572 secure method they support. The protocol has been designed to 1573 minimize this risk, but there are still attacks available: for 1574 example, an attacker could block access to the port a secure service 1575 runs on, or attempt to get the peers to negotiate an unauthenticated 1576 connection. The fundamental rule is that higher levels must be 1577 cognizant of what their security requirements are and never transmit 1578 information over a channel less secure than what they require. The 1579 TLS protocol is secure in that any cipher suite offers its promised 1580 level of security: if you negotiate 3DES with a 1024 bit RSA key 1581 exchange with a host whose certificate you have verified, you can 1582 expect to be that secure. 1584 These goals are achieved by the handshake protocol, which can be 1585 summarized as follows: The client sends a client hello message to 1586 which the server must respond with a server hello message, or else a 1587 fatal error will occur and the connection will fail. The client hello 1588 and server hello are used to establish security enhancement 1589 capabilities between client and server. The client hello and server 1590 hello establish the following attributes: Protocol Version, Session 1591 ID, Cipher Suite, and Compression Method. Additionally, two random 1592 values are generated and exchanged: ClientHello.random and 1593 ServerHello.random. 1595 The actual key exchange uses up to four messages: the server 1596 Certificate, the ServerKeyExchange, the client Certificate, and the 1597 ClientKeyExchange. New key exchange methods can be created by 1598 specifying a format for these messages and by defining the use of the 1599 messages to allow the client and server to agree upon a shared 1600 secret. This secret MUST be quite long; currently defined key 1601 exchange methods exchange secrets that range from 46 bytes upwards. 1603 Following the hello messages, the server will send its certificate in 1604 a Certificate message if it is to be authenticated. Additionally, a 1605 ServerKeyExchange message may be sent, if it is required (e.g., if 1606 the server has no certificate, or if its certificate is for signing 1607 only). If the server is authenticated, it may request a certificate 1608 from the client, if that is appropriate to the cipher suite selected. 1609 Next, the server will send the ServerHelloDone message, indicating 1610 that the hello-message phase of the handshake is complete. The server 1611 will then wait for a client response. If the server has sent a 1612 CertificateRequest message, the client MUST send the Certificate 1613 message. The ClientKeyExchange message is now sent, and the content 1614 of that message will depend on the public key algorithm selected 1615 between the client hello and the server hello. If the client has sent 1616 a certificate with signing ability, a digitally-signed 1617 CertificateVerify message is sent to explicitly verify possession of 1618 the private key in the certificate. 1620 At this point, a ChangeCipherSpec message is sent by the client, and 1621 the client copies the pending Cipher Spec into the current Cipher 1622 Spec. The client then immediately sends the Finished message under 1623 the new algorithms, keys, and secrets. In response, the server will 1624 send its own ChangeCipherSpec message, transfer the pending to the 1625 current Cipher Spec, and send its Finished message under the new 1626 Cipher Spec. At this point, the handshake is complete, and the client 1627 and server may begin to exchange application layer data. (See flow 1628 chart below.) Application data MUST NOT be sent prior to the 1629 completion of the first handshake (before a cipher suite other than 1630 TLS_NULL_WITH_NULL_NULL is established). 1632 Client Server 1634 ClientHello --------> 1635 ServerHello 1636 Certificate* 1637 ServerKeyExchange* 1638 CertificateRequest* 1639 <-------- ServerHelloDone 1640 Certificate* 1641 ClientKeyExchange 1642 CertificateVerify* 1643 [ChangeCipherSpec] 1644 Finished --------> 1645 [ChangeCipherSpec] 1646 <-------- Finished 1647 Application Data <-------> Application Data 1649 Fig. 1. Message flow for a full handshake 1651 * Indicates optional or situation-dependent messages that are not 1652 always sent. 1654 Note: To help avoid pipeline stalls, ChangeCipherSpec is an 1655 independent TLS Protocol content type, and is not actually a TLS 1656 handshake message. 1658 When the client and server decide to resume a previous session or 1659 duplicate an existing session (instead of negotiating new security 1660 parameters), the message flow is as follows: 1662 The client sends a ClientHello using the Session ID of the session to 1663 be resumed. The server then checks its session cache for a match. If 1664 a match is found, and the server is willing to re-establish the 1665 connection under the specified session state, it will send a 1666 ServerHello with the same Session ID value. At this point, both 1667 client and server MUST send ChangeCipherSpec messages and proceed 1668 directly to Finished messages. Once the re-establishment is complete, 1669 the client and server MAY begin to exchange application layer data. 1670 (See flow chart below.) If a Session ID match is not found, the 1671 server generates a new session ID and the TLS client and server 1672 perform a full handshake. 1674 Client Server 1676 ClientHello --------> 1677 ServerHello 1678 [ChangeCipherSpec] 1679 <-------- Finished 1680 [ChangeCipherSpec] 1681 Finished --------> 1682 Application Data <-------> Application Data 1684 Fig. 2. Message flow for an abbreviated handshake 1686 The contents and significance of each message will be presented in 1687 detail in the following sections. 1689 7.4. Handshake Protocol 1691 The TLS Handshake Protocol is one of the defined higher-level clients 1692 of the TLS Record Protocol. This protocol is used to negotiate the 1693 secure attributes of a session. Handshake messages are supplied to 1694 the TLS Record Layer, where they are encapsulated within one or more 1695 TLSPlaintext structures, which are processed and transmitted as 1696 specified by the current active session state. 1698 enum { 1699 hello_request(0), client_hello(1), server_hello(2), 1700 certificate(11), server_key_exchange (12), 1701 certificate_request(13), server_hello_done(14), 1702 certificate_verify(15), client_key_exchange(16), 1703 finished(20), (255) 1704 } HandshakeType; 1706 struct { 1707 HandshakeType msg_type; /* handshake type */ 1708 uint24 length; /* bytes in message */ 1709 select (HandshakeType) { 1710 case hello_request: HelloRequest; 1711 case client_hello: ClientHello; 1712 case server_hello: ServerHello; 1713 case certificate: Certificate; 1714 case server_key_exchange: ServerKeyExchange; 1715 case certificate_request: CertificateRequest; 1716 case server_hello_done: ServerHelloDone; 1717 case certificate_verify: CertificateVerify; 1718 case client_key_exchange: ClientKeyExchange; 1719 case finished: Finished; 1720 } body; 1721 } Handshake; 1723 The handshake protocol messages are presented below in the order they 1724 MUST be sent; sending handshake messages in an unexpected order 1725 results in a fatal error. Unneeded handshake messages can be omitted, 1726 however. Note one exception to the ordering: the Certificate message 1727 is used twice in the handshake (from server to client, then from 1728 client to server), but described only in its first position. The one 1729 message that is not bound by these ordering rules is the HelloRequest 1730 message, which can be sent at any time, but which SHOULD be ignored 1731 by the client if it arrives in the middle of a handshake. 1733 New Handshake message types are assigned by IANA as described in 1734 Section 12. 1736 7.4.1. Hello Messages 1738 The hello phase messages are used to exchange security enhancement 1739 capabilities between the client and server. When a new session 1740 begins, the Record Layer's connection state encryption, hash, and 1741 compression algorithms are initialized to null. The current 1742 connection state is used for renegotiation messages. 1744 7.4.1.1. Hello Request 1746 When this message will be sent: 1748 The HelloRequest message MAY be sent by the server at any time. 1750 Meaning of this message: 1752 HelloRequest is a simple notification that the client should begin 1753 the negotiation process anew. In response, the client should a 1754 ClientHello message when convenient. This message is not intended 1755 to establish which side is the client or server but merely to 1756 initiate a new negotiation. Servers SHOULD NOT send a HelloRequest 1757 immediately upon the client's initial connection. It is the 1758 client's job to send a ClientHello at that time. 1760 This message will be ignored by the client if the client is 1761 currently negotiating a session. This message MAY be ignored by 1762 the client if it does not wish to renegotiate a session, or the 1763 client may, if it wishes, respond with a no_renegotiation alert. 1764 Since handshake messages are intended to have transmission 1765 precedence over application data, it is expected that the 1766 negotiation will begin before no more than a few records are 1767 received from the client. If the server sends a HelloRequest but 1768 does not receive a ClientHello in response, it may close the 1769 connection with a fatal alert. 1771 After sending a HelloRequest, servers SHOULD NOT repeat the 1772 request until the subsequent handshake negotiation is complete. 1774 Structure of this message: 1776 struct { } HelloRequest; 1778 This message MUST NOT be included in the message hashes that are 1779 maintained throughout the handshake and used in the finished messages 1780 and the certificate verify message. 1782 7.4.1.2. Client Hello 1784 When this message will be sent: 1786 When a client first connects to a server it is required to send 1787 the ClientHello as its first message. The client can also send a 1788 ClientHello in response to a HelloRequest or on its own initiative 1789 in order to renegotiate the security parameters in an existing 1790 connection. 1792 Structure of this message: 1794 The ClientHello message includes a random structure, which is used 1795 later in the protocol. 1797 struct { 1798 uint32 gmt_unix_time; 1799 opaque random_bytes[28]; 1800 } Random; 1802 gmt_unix_time 1803 The current time and date in standard UNIX 32-bit format 1804 (seconds since the midnight starting Jan 1, 1970, UTC, ignoring 1805 leap seconds) according to the sender's internal clock. Clocks 1806 are not required to be set correctly by the basic TLS Protocol; 1807 higher-level or application protocols may define additional 1808 requirements. Note that, for historical reasons, the data 1809 element is named using GMT, the predecessor of the current 1810 worldwide time base, UTC. 1812 random_bytes 1813 28 bytes generated by a secure random number generator. 1815 The ClientHello message includes a variable-length session 1816 identifier. If not empty, the value identifies a session between the 1817 same client and server whose security parameters the client wishes to 1818 reuse. The session identifier MAY be from an earlier connection, this 1819 connection, or from another currently active connection. The second 1820 option is useful if the client only wishes to update the random 1821 structures and derived values of a connection, and the third option 1822 makes it possible to establish several independent secure connections 1823 without repeating the full handshake protocol. These independent 1824 connections may occur sequentially or simultaneously; a SessionID 1825 becomes valid when the handshake negotiating it completes with the 1826 exchange of Finished messages and persists until it is removed due to 1827 aging or because a fatal error was encountered on a connection 1828 associated with the session. The actual contents of the SessionID are 1829 defined by the server. 1831 opaque SessionID<0..32>; 1833 Warning: Because the SessionID is transmitted without encryption or 1834 immediate MAC protection, servers MUST NOT place confidential 1835 information in session identifiers or let the contents of fake 1836 session identifiers cause any breach of security. (Note that the 1837 content of the handshake as a whole, including the SessionID, is 1838 protected by the Finished messages exchanged at the end of the 1839 handshake.) 1841 The cipher suite list, passed from the client to the server in the 1842 ClientHello message, contains the combinations of cryptographic 1843 algorithms supported by the client in order of the client's 1844 preference (favorite choice first). Each cipher suite defines a key 1845 exchange algorithm, a bulk encryption algorithm (including secret key 1846 length), a MAC algorithm, and a PRF. The server will select a cipher 1847 suite or, if no acceptable choices are presented, return a handshake 1848 failure alert and close the connection. If the list contains cipher 1849 suites the server does not recognize, support, or wish to use, the 1850 server MUST ignore those cipher suites, and process the remaining 1851 ones as usual. 1853 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1855 The ClientHello includes a list of compression algorithms supported 1856 by the client, ordered according to the client's preference. 1858 enum { null(0), (255) } CompressionMethod; 1860 struct { 1861 ProtocolVersion client_version; 1862 Random random; 1863 SessionID session_id; 1864 CipherSuite cipher_suites<2..2^16-2>; 1865 CompressionMethod compression_methods<1..2^8-1>; 1866 select (extensions_present) { 1867 case false: 1868 struct {}; 1869 case true: 1870 Extension extensions<0..2^16-1>; 1871 }; 1872 } ClientHello; 1874 TLS allows extensions to follow the compression_methods field in an 1875 extensions block. The presence of extensions can be detected by 1876 determining whether there are bytes following the compression_methods 1877 at the end of the ClientHello. Note that this method of detecting 1878 optional data differs from the normal TLS method of having a 1879 variable-length field but is used for compatibility with TLS before 1880 extensions were defined. 1882 client_version 1883 The version of the TLS protocol by which the client wishes to 1884 communicate during this session. This SHOULD be the latest 1885 (highest valued) version supported by the client. For this version 1886 of the specification, the version will be 3.3 (See Appendix E for 1887 details about backward compatibility). 1889 random 1890 A client-generated random structure. 1892 session_id 1893 The ID of a session the client wishes to use for this connection. 1894 This field is empty if no session_id is available, or if the 1895 client wishes to generate new security parameters. 1897 cipher_suites 1898 This is a list of the cryptographic options supported by the 1899 client, with the client's first preference first. If the 1900 session_id field is not empty (implying a session resumption 1901 request), this vector MUST include at least the cipher_suite from 1902 that session. Values are defined in Appendix A.5. 1904 compression_methods 1905 This is a list of the compression methods supported by the client, 1906 sorted by client preference. If the session_id field is not empty 1907 (implying a session resumption request), it MUST include the 1908 compression_method from that session. This vector MUST contain, 1909 and all implementations MUST support, CompressionMethod.null. 1910 Thus, a client and server will always be able to agree on a 1911 compression method. 1913 extensions 1914 Clients MAY request extended functionality from servers by sending 1915 data in the extensions field. The actual "Extension" format is 1916 defined in Section 7.4.1.4. 1918 In the event that a client requests additional functionality using 1919 extensions, and this functionality is not supplied by the server, the 1920 client MAY abort the handshake. A server MUST accept client hello 1921 messages both with and without the extensions field, and (as for all 1922 other messages) MUST check that the amount of data in the message 1923 precisely matches one of these formats; if not, then it MUST send a 1924 fatal "decode_error" alert. 1926 After sending the client hello message, the client waits for a 1927 ServerHello message. Any other handshake message returned by the 1928 server except for a HelloRequest is treated as a fatal error. 1930 7.4.1.3. Server Hello 1932 When this message will be sent: 1934 The server will send this message in response to a ClientHello 1935 message when it was able to find an acceptable set of algorithms. 1936 If it cannot find such a match, it will respond with a handshake 1937 failure alert. 1939 Structure of this message: 1941 struct { 1942 ProtocolVersion server_version; 1943 Random random; 1944 SessionID session_id; 1945 CipherSuite cipher_suite; 1946 CompressionMethod compression_method; 1947 select (extensions_present) { 1948 case false: 1949 struct {}; 1950 case true: 1951 Extension extensions<0..2^16-1>; 1952 }; 1953 } ServerHello; 1955 The presence of extensions can be detected by determining whether 1956 there are bytes following the compression_method field at the end of 1957 the ServerHello. 1959 server_version 1960 This field will contain the lower of that suggested by the client 1961 in the client hello and the highest supported by the server. For 1962 this version of the specification, the version is 3.3. (See 1963 Appendix E for details about backward compatibility.) 1965 random 1966 This structure is generated by the server and MUST be 1967 independently generated from the ClientHello.random. 1969 session_id 1970 This is the identity of the session corresponding to this 1971 connection. If the ClientHello.session_id was non-empty, the 1972 server will look in its session cache for a match. If a match is 1973 found and the server is willing to establish the new connection 1974 using the specified session state, the server will respond with 1975 the same value as was supplied by the client. This indicates a 1976 resumed session and dictates that the parties must proceed 1977 directly to the finished messages. Otherwise this field will 1978 contain a different value identifying the new session. The server 1979 may return an empty session_id to indicate that the session will 1980 not be cached and therefore cannot be resumed. If a session is 1981 resumed, it must be resumed using the same cipher suite it was 1982 originally negotiated with. Note that there is no requirement that 1983 the server resume any session even if it had formerly provided a 1984 session_id. Clients MUST be prepared to do a full negotiation -- 1985 including negotiating new cipher suites -- during any handshake. 1987 cipher_suite 1988 The single cipher suite selected by the server from the list in 1989 ClientHello.cipher_suites. For resumed sessions, this field is the 1990 value from the state of the session being resumed. 1992 compression_method 1993 The single compression algorithm selected by the server from the 1994 list in ClientHello.compression_methods. For resumed sessions this 1995 field is the value from the resumed session state. 1997 extensions 1998 A list of extensions. Note that only extensions offered by the 1999 client can appear in the server's list. 2001 7.4.1.4 Hello Extensions 2003 The extension format is: 2005 struct { 2006 ExtensionType extension_type; 2007 opaque extension_data<0..2^16-1>; 2008 } Extension; 2010 enum { 2011 signature_algorithms(TBD-BY-IANA), (65535) 2012 } ExtensionType; 2014 Here: 2016 - "extension_type" identifies the particular extension type. 2018 - "extension_data" contains information specific to the particular 2019 extension type. 2021 The initial set of extensions is defined in a companion document 2022 [TLSEXT]. The list of extension types is maintained by IANA as 2023 described in Section 12. 2025 There are subtle (and not so subtle) interactions that may occur in 2026 this protocol between new features and existing features which may 2027 result in a significant reduction in overall security. The following 2028 considerations should be taken into account when designing new 2029 extensions: 2031 - Some cases where a server does not agree to an extension are error 2032 conditions, and some simply a refusal to support a particular 2033 feature. In general error alerts should be used for the former, 2034 and a field in the server extension response for the latter. 2036 - Extensions should as far as possible be designed to prevent any 2037 attack that forces use (or non-use) of a particular feature by 2038 manipulation of handshake messages. This principle should be 2039 followed regardless of whether the feature is believed to cause a 2040 security problem. 2042 Often the fact that the extension fields are included in the 2043 inputs to the Finished message hashes will be sufficient, but 2044 extreme care is needed when the extension changes the meaning of 2045 messages sent in the handshake phase. Designers and implementors 2046 should be aware of the fact that until the handshake has been 2047 authenticated, active attackers can modify messages and insert, 2048 remove, or replace extensions. 2050 - It would be technically possible to use extensions to change major 2051 aspects of the design of TLS; for example the design of cipher 2052 suite negotiation. This is not recommended; it would be more 2053 appropriate to define a new version of TLS - particularly since 2054 the TLS handshake algorithms have specific protection against 2055 version rollback attacks based on the version number, and the 2056 possibility of version rollback should be a significant 2057 consideration in any major design change. 2059 7.4.1.4.1 Signature Algorithms 2061 The client uses the "signature_algorithms" extension to indicate to 2062 the server which signature/hash algorithm pairs may be used in 2063 digital signatures. The "extension_data" field of this extension 2064 contains a "supported_signature_algorithms" value. 2066 enum { 2067 none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5), 2068 sha512(6), (255) 2069 } HashAlgorithm; 2071 enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) } 2072 SignatureAlgorithm; 2074 struct { 2075 HashAlgorithm hash; 2076 SignatureAlgorithm signature; 2077 } SignatureAndHashAlgorithm; 2079 SignatureAndHashAlgorithm 2080 supported_signature_algorithms<2..2^16-2>; 2082 Each SignatureAndHashAlgorithm value lists a single hash/signature 2083 pair which the client is willing to verify. The values are indicated 2084 in descending order of preference. 2086 Note: Because not all signature algorithms and hash algorithms may be 2087 accepted by an implementation (e.g., DSA with SHA-1, but not 2088 SHA-256), algorithms here are listed in pairs. 2090 hash 2091 This field indicates the hash algorithm which may be used. The 2092 values indicate support for unhashed data, MD5 [MD5], SHA-1, 2093 SHA-224, SHA-256, SHA-384, and SHA-512 [SHS] respectively. The 2094 "none" value is provided for future extensibility, in case of a 2095 signature algorithm which does not require hashing before signing. 2097 signature 2098 This field indicates the signature algorithm which may be used. 2099 The values indicate anonymous signatures, RSASSA-PKCS1-v1_5 2100 [PKCS1] and DSA [DSS], and ECDSA [ECDSA], respectively. The 2101 "anonymous" value is meaningless in this context but used in 2102 Section 7.4.3. It MUST NOT appear in this extension. 2104 The semantics of this extension are somewhat complicated because the 2105 cipher suite indicates permissible signature algorithms but not hash 2106 algorithms. Sections 7.4.2 and 7.4.3 describe the appropriate rules. 2108 If the client supports only the default hash and signature algorithms 2109 (listed in this section), it MAY omit the signature_algorithms 2110 extension. If the client does not support the default algorithms, or 2111 supports other hash and signature algorithms (and it is willing to 2112 use them for verifying messages sent by the server, i.e., server 2113 certificates and server key exchange), it MUST send the 2114 signature_algorithms extension, listing the algorithms it is willing 2115 to accept. 2117 If the client does not send the signature_algorithms extension, the 2118 server MUST assume the following: 2120 - If the negotiated key exchange algorithm is one of (RSA, DHE_RSA, 2121 DH_RSA, RSA_PSK, ECDH_RSA, ECDHE_RSA), behave as if client had sent 2122 the value {sha1,rsa}. 2124 - If the negotiated key exchange algorithm is one of (DHE_DSS, 2125 DH_DSS), behave as if the client had sent the value {sha1,dsa}. 2127 - If the negotiated key exchange algorithm is one of (ECDH_ECDSA, 2128 ECDHE_ECDSA), behave as if the client had sent value {sha1,ecdsa}. 2130 Note: this is a change from TLS 1.1 where there are no explicit rules 2131 but as a practical matter one can assume that the peer supports MD5 2132 and SHA-1. 2134 Note: this extension is not meaningful for TLS versions prior to 1.2. 2135 Clients MUST NOT offer it if they are offering prior versions. 2136 However, even if clients do offer it, the rules specified in [TLSEXT] 2137 require servers to ignore extensions they do not understand. 2139 Servers MUST NOT send this extension. TLS servers MUST support 2140 receiving this extension. 2142 7.4.2. Server Certificate 2144 When this message will be sent: 2146 The server MUST send a Certificate message whenever the agreed- 2147 upon key exchange method uses certificates for authentication 2148 (this includes all key exchange methods defined in this document 2149 except DH_anon). This message will always immediately follow the 2150 server hello message. 2152 Meaning of this message: 2154 This message conveys the server's certificate chain to the client. 2156 The certificate MUST be appropriate for the negotiated cipher 2157 suite's key exchange algorithm, and any negotiated extensions. 2159 Structure of this message: 2161 opaque ASN.1Cert<1..2^24-1>; 2163 struct { 2164 ASN.1Cert certificate_list<0..2^24-1>; 2165 } Certificate; 2167 certificate_list 2168 This is a sequence (chain) of certificates. The sender's 2169 certificate MUST come first in the list. Each following 2170 certificate MUST directly certify the one preceding it. Because 2171 certificate validation requires that root keys be distributed 2172 independently, the self-signed certificate that specifies the root 2173 certificate authority MAY be omitted from the chain, under the 2174 assumption that the remote end must already possess it in order to 2175 validate it in any case. 2177 The same message type and structure will be used for the client's 2178 response to a certificate request message. Note that a client MAY 2179 send no certificates if it does not have an appropriate certificate 2180 to send in response to the server's authentication request. 2182 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 2183 vector because PKCS #6 [PKCS6] extended certificates are not used. 2184 Also, PKCS #7 defines a SET rather than a SEQUENCE, making the task 2185 of parsing the list more difficult. 2187 The following rules apply to the certificates sent by the server: 2189 - The certificate type MUST be X.509v3, unless explicitly negotiated 2190 otherwise (e.g., [TLSPGP]). 2192 - The end entity certificate's public key (and associated 2193 restrictions) MUST be compatible with the selected key exchange 2194 algorithm. 2196 Key Exchange Alg. Certificate Key Type 2198 RSA RSA public key; the certificate MUST 2199 RSA_PSK allow the key to be used for encryption 2200 (the keyEncipherment bit MUST be set 2201 if the key usage extension is present). 2202 Note: RSA_PSK is defined in [TLSPSK]. 2204 DHE_RSA RSA public key; the certificate MUST 2205 ECDHE_RSA allow the key to be used for signing 2206 (the digitalSignature bit MUST be set 2207 if the key usage extension is present) 2208 with the signature scheme and hash 2209 algorithm that will be employed in the 2210 server key exchange message. 2211 Note: ECDHE_RSA is defined in [TLSECC]. 2213 DHE_DSS DSA public key; the certificate MUST 2214 allow the key to be used for signing with 2215 the hash algorithm that will be employed 2216 in the server key exchange message. 2218 DH_DSS Diffie-Hellman public key; the 2219 DH_RSA keyAgreement bit MUST be set if the 2220 key usage extension is present. 2222 ECDH_ECDSA ECDH-capable public key; the public key 2223 ECDH_RSA MUST use a curve and point format supported 2224 by the client, as described in [TLSECC]. 2226 ECDHE_ECDSA ECDSA-capable public key; the certificate 2227 MUST allow the key to be used for signing 2228 with the hash algorithm that will be 2229 employed in the server key exchange 2230 message. The public key MUST use a curve 2231 and point format supported by the client, 2232 as described in [TLSECC]. 2234 - The "server_name" and "trusted_ca_keys" extensions [TLSEXT] are 2235 used to guide certificate selection. 2237 If the client provided a "signature_algorithms" extension, then all 2238 certificates provided by the server MUST be signed by a 2239 hash/signature algorithm pair that appears in that extension. Note 2240 that this implies that a certificate containing a key for one 2241 signature algorithm MAY be signed using a different signature 2242 algorithm (for instance, an RSA key signed with a DSA key.) This is a 2243 departure from TLS 1.1, which required that the algorithms be the 2244 same. Note that this also implies that the DH_DSS, DH_RSA, 2245 ECDH_ECDSA, and ECDH_RSA key exchange algorithms do not restrict the 2246 algorithm used to sign the certificate. Fixed DH certificates MAY be 2247 signed with any hash/signature algorithm pair appearing in the 2248 extension. The names DH_DSS, DH_RSA, ECDH_ECDSA, and ECDH_RSA are 2249 historical. 2251 If the server has multiple certificates, it chooses one of them based 2252 on the above-mentioned criteria (in addition to other criteria, such 2253 as transport layer endpoint, local configuration and preferences, 2254 etc.). If the server has a single certificate it SHOULD attempt to 2255 validate that it meets these criteria. 2257 Note that there are certificates that use algorithms and/or algorithm 2258 combinations that cannot be currently used with TLS. For example, a 2259 certificate with RSASSA-PSS signature key (id-RSASSA-PSS OID in 2260 SubjectPublicKeyInfo) cannot be used because TLS defines no 2261 corresponding signature algorithm. 2263 As cipher suites that specify new key exchange methods are specified 2264 for the TLS Protocol, they will the imply certificate format and the 2265 required encoded keying information. 2267 7.4.3. Server Key Exchange Message 2269 When this message will be sent: 2271 This message will be sent immediately after the server Certificate 2272 message (or the ServerHello message, if this is an anonymous 2273 negotiation). 2275 The ServerKeyExchange message is sent by the server only when the 2276 server Certificate message (if sent) does not contain enough data 2277 to allow the client to exchange a premaster secret. This is true 2278 for the following key exchange methods: 2280 DHE_DSS 2281 DHE_RSA 2282 DH_anon 2284 It is not legal to send the ServerKeyExchange message for the 2285 following key exchange methods: 2287 RSA 2288 DH_DSS 2289 DH_RSA 2291 Other key exchange algorithms, such as those defined in 2292 [TLSECC], MUST specify whether the ServerKeyExchange message is 2293 sent or not; and if the message is sent, its contents. 2295 Meaning of this message: 2297 This message conveys cryptographic information to allow the client 2298 to communicate the premaster secret: a Diffie-Hellman public key 2299 with which the client can complete a key exchange (with the result 2300 being the premaster secret) or a public key for some other 2301 algorithm. 2303 Structure of this message: 2305 enum { dhe_dss, dhe_rsa, dh_anon, rsa, dh_dss, dh_rsa 2306 /* may be extended, e.g. for ECDH -- see [TLSECC] */ 2307 } KeyExchangeAlgorithm; 2309 struct { 2310 opaque dh_p<1..2^16-1>; 2311 opaque dh_g<1..2^16-1>; 2312 opaque dh_Ys<1..2^16-1>; 2313 } ServerDHParams; /* Ephemeral DH parameters */ 2315 dh_p 2316 The prime modulus used for the Diffie-Hellman operation. 2318 dh_g 2319 The generator used for the Diffie-Hellman operation. 2321 dh_Ys 2322 The server's Diffie-Hellman public value (g^X mod p). 2324 struct { 2325 select (KeyExchangeAlgorithm) { 2326 case dh_anon: 2327 ServerDHParams params; 2328 case dhe_dss: 2329 case dhe_rsa: 2330 ServerDHParams params; 2331 digitally-signed struct { 2332 opaque client_random[32]; 2333 opaque server_random[32]; 2334 ServerDHParams params; 2335 } signed_params; 2336 case rsa: 2337 case dh_dss: 2338 case dh_rsa: 2339 struct {} ; 2340 /* message is omitted for rsa, dh_dss, and dh_rsa */ 2341 /* may be extended, e.g. for ECDH -- see [TLSECC] */ 2342 }; 2343 } ServerKeyExchange; 2345 params 2346 The server's key exchange parameters. 2348 signed_params 2349 For non-anonymous key exchanges, a signature over the 2350 server's key exchange parameters. 2352 If the client has offered the "signature_algorithms" extension, the 2353 signature algorithm and hash algorithm MUST be a pair listed in that 2354 extension. Note that there is a possibility for inconsistencies here. 2355 For instance, the client might offer DHE_DSS key exchange but omit 2356 any DSA pairs from its "signature_algorithms" extension. In order to 2357 negotiate correctly, the server MUST check any candidate cipher 2358 suites against the "signature_algorithms" extension before selecting 2359 them. This is somewhat inelegant but is a compromise designed to 2360 minimize changes to the original cipher suite design. 2362 In addition, the hash and signature algorithms MUST be compatible 2363 with the key in the server's end-entity certificate. RSA keys MAY be 2364 used with any permitted hash algorithm, subject to restrictions in 2365 the certificate, if any. 2367 Because DSA signatures do not contain any secure indication of hash 2368 algorithm, there is a risk of hash substitution if multiple hashes 2369 may be used with any key. Currently, DSA [DSS] may only be used with 2370 SHA-1. Future revisions of DSS [DSS-3] are expected to allow the use 2371 of other digest algorithms with DSA, as well as guidance as to which 2372 digest algorithms should be used with each key size. In addition, 2373 future revisions of [PKIX] may specify mechanisms for certificates to 2374 indicate which digest algorithms are to be used with DSA. 2376 As additional cipher suites are defined for TLS that include new key 2377 exchange algorithms, the server key exchange message will be sent if 2378 and only if the certificate type associated with the key exchange 2379 algorithm does not provide enough information for the client to 2380 exchange a premaster secret. 2382 7.4.4. Certificate Request 2384 When this message will be sent: 2386 A non-anonymous server can optionally request a certificate from 2387 the client, if appropriate for the selected cipher suite. This 2388 message, if sent, will immediately follow the ServerKeyExchange 2389 message (if it is sent; otherwise, the server's Certificate 2390 message). 2392 Structure of this message: 2394 enum { 2395 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 2396 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 2397 fortezza_dms_RESERVED(20), (255) 2398 } ClientCertificateType; 2400 opaque DistinguishedName<1..2^16-1>; 2402 struct { 2403 ClientCertificateType certificate_types<1..2^8-1>; 2404 SignatureAndHashAlgorithm 2405 supported_signature_algorithms<2^16-1>; 2406 DistinguishedName certificate_authorities<0..2^16-1>; 2407 } CertificateRequest; 2409 certificate_types 2410 A list of the types of certificate types which the client may 2411 offer. 2413 rsa_sign a certificate containing an RSA key 2414 dss_sign a certificate containing a DSA key 2415 rsa_fixed_dh a certificate containing a static DH key. 2416 dss_fixed_dh a certificate containing a static DH key 2418 supported_signature_algorithms 2419 A list of the hash/signature algorithm pairs that the server is 2420 able to verify, listed in descending order of preference. 2422 certificate_authorities 2423 A list of the distinguished names [X501] of acceptable 2424 certificate_authorities, represented in DER-encoded format. These 2425 distinguished names may specify a desired distinguished name for a 2426 root CA or for a subordinate CA; thus, this message can be used 2427 both to describe known roots and a desired authorization space. If 2428 the certificate_authorities list is empty then the client MAY send 2429 any certificate of the appropriate ClientCertificateType, unless 2430 there is some external arrangement to the contrary. 2432 The interaction of the certificate_types and 2433 supported_signature_algorithms fields is somewhat complicated. 2434 certificate_types has been present in TLS since SSLv3, but was 2435 somewhat underspecified. Much of its functionality is superseded by 2436 supported_signature_algorithms. The following rules apply: 2438 - Any certificates provided by the client MUST be signed using a 2439 hash/signature algorithm pair found in 2440 supported_signature_algorithms. 2442 - The end-entity certificate provided by the client MUST contain a 2443 key which is compatible with certificate_types. If the key is a 2444 signature key, it MUST be usable with some hash/signature 2445 algorithm pair in supported_signature_algorithms. 2447 - For historical reasons, the names of some client certificate types 2448 include the algorithm used to sign the certificate. For example, 2449 in earlier versions of TLS, rsa_fixed_dh meant a certificate 2450 signed with RSA and containing a static DH key. In TLS 1.2, this 2451 functionality has been obsoleted by the 2452 supported_signature_algorithms, and the certificate type no longer 2453 restricts the algorithm used to sign the certificate. For 2454 example, if the server sends dss_fixed_dh certificate type and 2455 {{sha1, dsa}, {sha1, rsa}} signature types, the client MAY reply 2456 with a certificate containing a static DH key, signed with RSA- 2457 SHA1. 2459 New ClientCertificateType values are assigned by IANA as described in 2460 Section 12. 2462 Note: Values listed as RESERVED may not be used. They were used in 2463 SSLv3. 2465 Note: It is a fatal handshake_failure alert for an anonymous server 2466 to request client authentication. 2468 7.4.5 Server Hello Done 2470 When this message will be sent: 2472 The ServerHelloDone message is sent by the server to indicate the 2473 end of the ServerHello and associated messages. After sending this 2474 message, the server will wait for a client response. 2476 Meaning of this message: 2478 This message means that the server is done sending messages to 2479 support the key exchange, and the client can proceed with its 2480 phase of the key exchange. 2482 Upon receipt of the ServerHelloDone message, the client SHOULD 2483 verify that the server provided a valid certificate, if required, 2484 and check that the server hello parameters are acceptable. 2486 Structure of this message: 2488 struct { } ServerHelloDone; 2490 7.4.6. Client Certificate 2491 When this message will be sent: 2493 This is the first message the client can send after receiving a 2494 server hello done message. This message is only sent if the server 2495 requests a certificate. If no suitable certificate is available, 2496 the client MUST send a certificate message containing no 2497 certificates. That is, the certificate_list structure has a length 2498 of zero. If the client does not send any certificates, the server 2499 MAY at its discretion either continue the handshake without client 2500 authentication, or respond with a fatal handshake_failure alert. 2501 Also, if some aspect of the certificate chain was unacceptable 2502 (e.g., it was not signed by a known, trusted CA), the server MAY 2503 at its discretion either continue the handshake (considering the 2504 client unauthenticated) or send a fatal alert. 2506 Client certificates are sent using the Certificate structure 2507 defined in Section 7.4.2. 2509 Meaning of this message: 2511 This message conveys the client's certificate chain to the server; 2512 the server will use it when verifying the CertificateVerify 2513 message (when the client authentication is based on signing) or 2514 calculating the premaster secret (for non-ephemeral Diffie- 2515 Hellman). The certificate MUST be appropriate for the negotiated 2516 cipher suite's key exchange algorithm, and any negotiated 2517 extensions. 2519 In particular: 2521 - The certificate type MUST be X.509v3, unless explicitly negotiated 2522 otherwise (e.g. [TLSPGP]). 2524 - The end-entity certificate's public key (and associated 2525 restrictions) has to be compatible with the certificate types 2526 listed in CertificateRequest: 2528 Client Cert. Type Certificate Key Type 2530 rsa_sign RSA public key; the certificate MUST allow 2531 the key to be used for signing with the 2532 signature scheme and hash algorithm that 2533 will be employed in the certificate verify 2534 message. 2536 dss_sign DSA public key; the certificate MUST allow 2537 the key to be used for signing with the 2538 hash algorithm that will be employed in 2539 the certificate verify message. 2541 ecdsa_sign ECDSA-capable public key; the certificate 2542 MUST allow the key to be used for signing 2543 with the hash algorithm that will be 2544 employed in the certificate verify 2545 message; the public key MUST use a 2546 curve and point format supported by the 2547 server. 2549 rsa_fixed_dh Diffie-Hellman public key; MUST use 2550 dss_fixed_dh the same parameters as server's key. 2552 rsa_fixed_ecdh ECDH-capable public key; MUST use the 2553 ecdsa_fixed_ecdh same curve as the server's key, and 2554 MUST use a point format supported by 2555 the server. 2557 - If the certificate_authorities list in the certificate request 2558 message was non-empty, one of the certificates in the certificate 2559 chain SHOULD be issued by one of the listed CAs. 2561 - The certificates MUST be signed using an acceptable hash/ 2562 signature algorithm pair, as described in Section 7.4.4. Note that 2563 this relaxes the constraints on certificate signing algorithms 2564 found in prior versions of TLS. 2566 Note that as with the server certificate, there are certificates that 2567 use algorithms/algorithm combinations that cannot be currently used 2568 with TLS. 2570 7.4.7. Client Key Exchange Message 2572 When this message will be sent: 2574 This message is always sent by the client. It MUST immediately 2575 follow the client certificate message, if it is sent. Otherwise it 2576 MUST be the first message sent by the client after it receives the 2577 server hello done message. 2579 Meaning of this message: 2581 With this message, the premaster secret is set, either through 2582 direct transmission of the RSA-encrypted secret, or by the 2583 transmission of Diffie-Hellman parameters that will allow each 2584 side to agree upon the same premaster secret. 2586 When the client is using an ephemeral Diffie-Hellman exponent, 2587 then this message contains the client's Diffie-Hellman public 2588 value. If the client is sending a certificate containing a static 2589 DH exponent (i.e., it is doing fixed_dh client authentication) 2590 then this message MUST be sent but MUST be empty. 2592 Structure of this message: 2594 The choice of messages depends on which key exchange method has 2595 been selected. See Section 7.4.3 for the KeyExchangeAlgorithm 2596 definition. 2598 struct { 2599 select (KeyExchangeAlgorithm) { 2600 case rsa: 2601 EncryptedPreMasterSecret; 2602 case dhe_dss: 2603 case dhe_rsa: 2604 case dh_dss: 2605 case dh_rsa: 2606 case dh_anon: 2607 ClientDiffieHellmanPublic; 2608 } exchange_keys; 2609 } ClientKeyExchange; 2611 7.4.7.1. RSA Encrypted Premaster Secret Message 2613 Meaning of this message: 2615 If RSA is being used for key agreement and authentication, the 2616 client generates a 48-byte premaster secret, encrypts it using the 2617 public key from the server's certificate and sends the result in 2618 an encrypted premaster secret message. This structure is a variant 2619 of the ClientKeyExchange message and is not a message in itself. 2621 Structure of this message: 2623 struct { 2624 ProtocolVersion client_version; 2625 opaque random[46]; 2626 } PreMasterSecret; 2628 client_version 2629 The latest (newest) version supported by the client. This is 2630 used to detect version roll-back attacks. 2632 random 2633 46 securely-generated random bytes. 2635 struct { 2636 public-key-encrypted PreMasterSecret pre_master_secret; 2637 } EncryptedPreMasterSecret; 2639 pre_master_secret 2640 This random value is generated by the client and is used to 2641 generate the master secret, as specified in Section 8.1. 2643 Note: The version number in the PreMasterSecret is the version 2644 offered by the client in the ClientHello.client_version, not the 2645 version negotiated for the connection. This feature is designed to 2646 prevent rollback attacks. Unfortunately, some old implementations 2647 use the negotiated version instead and therefore checking the version 2648 number may lead to failure to interoperate with such incorrect client 2649 implementations. 2651 Client implementations MUST always send the correct version number in 2652 PreMasterSecret. If ClientHello.client_version is TLS 1.1 or higher, 2653 server implementations MUST check the version number as described in 2654 the note below. If the version number is TLS 1.0 or earlier, server 2655 implementations SHOULD check the version number, but MAY have a 2656 configuration option to disable the check. Note that if the check 2657 fails, the PreMasterSecret SHOULD be randomized as described below. 2659 Note: Attacks discovered by Bleichenbacher [BLEI] and Klima et al. 2660 [KPR03] can be used to attack a TLS server that reveals whether a 2661 particular message, when decrypted, is properly PKCS#1 formatted, 2662 contains a valid PreMasterSecret structure, or has the correct 2663 version number. 2665 The best way to avoid these vulnerabilities is to treat incorrectly 2666 formatted messages in a manner indistinguishable from correctly 2667 formatted RSA blocks. In other words: 2669 1. Generate a string R of 46 random bytes 2671 2. Decrypt the message to recover the plaintext M 2673 3. If the PKCS#1 padding is not correct, or the length of 2674 message M is not exactly 48 bytes: 2675 premaster secret = ClientHello.client_version || R 2676 else If ClientHello.client_version <= TLS 1.0, and 2677 version number check is explicitly disabled: 2678 premaster secret = M 2679 else: 2680 premaster secret = ClientHello.client_version || M[2..47] 2682 Note that explicitly constructing the premaster_secret with the 2683 ClientHello.client_version produces an invalid master_secret if the 2684 client has sent the wrong version in the original premaster_secret. 2686 In any case, a TLS server MUST NOT generate an alert if processing an 2687 RSA-encrypted premaster secret message fails, or the version number 2688 is not as expected. Instead, it MUST continue the handshake with a 2689 randomly generated premaster secret. It may be useful to log the 2690 real cause of failure for troubleshooting purposes; however, care 2691 must be taken to avoid leaking the information to an attacker 2692 (through, e.g., timing, log files, or other channels.) 2694 The RSAES-OAEP encryption scheme defined in [PKCS1] is more secure 2695 against the Bleichenbacher attack. However, for maximal compatibility 2696 with earlier versions of TLS, this specification uses the RSAES- 2697 PKCS1-v1_5 scheme. No variants of the Bleichenbacher attack are known 2698 to exist provided that the above recommendations are followed. 2700 Implementation Note: Public-key-encrypted data is represented as an 2701 opaque vector <0..2^16-1> (see Section 4.7). Thus, the RSA-encrypted 2702 PreMasterSecret in a ClientKeyExchange is preceded by two length 2703 bytes. These bytes are redundant in the case of RSA because the 2704 EncryptedPreMasterSecret is the only data in the ClientKeyExchange 2705 and its length can therefore be unambiguously determined. The SSLv3 2706 specification was not clear about the encoding of public-key- 2707 encrypted data, and therefore many SSLv3 implementations do not 2708 include the length bytes, encoding the RSA encrypted data directly in 2709 the ClientKeyExchange message. 2711 This specification requires correct encoding of the 2712 EncryptedPreMasterSecret complete with length bytes. The resulting 2713 PDU is incompatible with many SSLv3 implementations. Implementors 2714 upgrading from SSLv3 MUST modify their implementations to generate 2715 and accept the correct encoding. Implementors who wish to be 2716 compatible with both SSLv3 and TLS should make their implementation's 2717 behavior dependent on the protocol version. 2719 Implementation Note: It is now known that remote timing-based attacks 2720 on TLS are possible, at least when the client and server are on the 2721 same LAN. Accordingly, implementations that use static RSA keys MUST 2722 use RSA blinding or some other anti-timing technique, as described in 2723 [TIMING]. 2725 7.4.7.2. Client Diffie-Hellman Public Value 2727 Meaning of this message: 2729 This structure conveys the client's Diffie-Hellman public value 2730 (Yc) if it was not already included in the client's certificate. 2731 The encoding used for Yc is determined by the enumerated 2732 PublicValueEncoding. This structure is a variant of the client key 2733 exchange message, and not a message in itself. 2735 Structure of this message: 2737 enum { implicit, explicit } PublicValueEncoding; 2739 implicit 2740 If the client has sent a certificate which contains a suitable 2741 Diffie-Hellman key (for fixed_dh client authentication) then Yc 2742 is implicit and does not need to be sent again. In this case, 2743 the client key exchange message will be sent, but it MUST be 2744 empty. 2746 explicit 2747 Yc needs to be sent. 2749 struct { 2750 select (PublicValueEncoding) { 2751 case implicit: struct { }; 2752 case explicit: opaque dh_Yc<1..2^16-1>; 2753 } dh_public; 2754 } ClientDiffieHellmanPublic; 2756 dh_Yc 2757 The client's Diffie-Hellman public value (Yc). 2759 7.4.8. Certificate verify 2761 When this message will be sent: 2763 This message is used to provide explicit verification of a client 2764 certificate. This message is only sent following a client 2765 certificate that has signing capability (i.e. all certificates 2766 except those containing fixed Diffie-Hellman parameters). When 2767 sent, it MUST immediately follow the client key exchange message. 2769 Structure of this message: 2771 struct { 2772 digitally-signed struct { 2773 opaque handshake_messages[handshake_messages_length]; 2774 } 2775 } CertificateVerify; 2777 Here handshake_messages refers to all handshake messages sent or 2778 received starting at client hello up to but not including this 2779 message, including the type and length fields of the handshake 2780 messages. This is the concatenation of all the Handshake 2781 structures as defined in 7.4 exchanged thus far. Note that this 2782 requires both sides to either buffer the messages or compute 2783 running hashes for all potential hash algorithms up to the time of 2784 the CertificateVerify computation. Servers can minimize this 2785 computation cost by offering a restricted set of digest algorithms 2786 in the CertificateRequest message. 2788 The hash and signature algorithms used in the signature MUST be 2789 one of those present in the supported_signature_algorithms field 2790 of the CertificateRequest message. In addition, the hash and 2791 signature algorithms MUST be compatible with the key in the 2792 client's end-entity certificate. RSA keys MAY be used with any 2793 permitted hash algorithm, subject to restrictions in the 2794 certificate, if any. 2796 Because DSA signatures do not contain any secure indication of 2797 hash algorithm, there is a risk of hash substitution if multiple 2798 hashes may be used with any key. Currently, DSA [DSS] may only be 2799 used with SHA-1. Future revisions of DSS [DSS-3] are expected to 2800 allow the use of other digest algorithms with DSA, as well as 2801 guidance as to which digest algorithms should be used with each 2802 key size. In addition, future revisions of [PKIX] may specify 2803 mechanisms for certificates to indicate which digest algorithms 2804 are to be used with DSA. 2806 7.4.9. Finished 2808 When this message will be sent: 2810 A Finished message is always sent immediately after a change 2811 cipher spec message to verify that the key exchange and 2812 authentication processes were successful. It is essential that a 2813 change cipher spec message be received between the other handshake 2814 messages and the Finished message. 2816 Meaning of this message: 2818 The finished message is the first one protected with the just 2819 negotiated algorithms, keys, and secrets. Recipients of finished 2820 messages MUST verify that the contents are correct. Once a side 2821 has sent its Finished message and received and validated the 2822 Finished message from its peer, it may begin to send and receive 2823 application data over the connection. 2825 Structure of this message: 2827 struct { 2828 opaque verify_data[verify_data_length]; 2829 } Finished; 2831 verify_data 2832 PRF(master_secret, finished_label, Hash(handshake_messages)) 2833 [0..verify_data_length-1]; 2835 finished_label 2836 For Finished messages sent by the client, the string "client 2837 finished". For Finished messages sent by the server, the string 2838 "server finished". 2840 Hash denotes a Hash of the handshake messages. For the PRF defined 2841 in Section 5, the Hash MUST be the Hash used as the basis for the 2842 PRF. Any cipher suite which defines a different PRF MUST also 2843 define the Hash to use in the Finished computation. 2845 In previous versions of TLS, the verify_data was always 12 octets 2846 long. In the current version of TLS, it depends on the cipher 2847 suite. Any cipher suite which does not explicitly specify 2848 verify_data_length has a verify_data_length equal to 12. This 2849 includes all existing cipher suites. Note that this 2850 representation has the same encoding as with previous versions. 2851 Future cipher suites MAY specify other lengths but such length 2852 MUST be at least 12 bytes. 2854 handshake_messages 2855 All of the data from all messages in this handshake (not 2856 including any HelloRequest messages) up to but not including 2857 this message. This is only data visible at the handshake layer 2858 and does not include record layer headers. This is the 2859 concatenation of all the Handshake structures as defined in 2860 7.4, exchanged thus far. 2862 It is a fatal error if a finished message is not preceded by a 2863 ChangeCipherSpec message at the appropriate point in the handshake. 2865 The value handshake_messages includes all handshake messages starting 2866 at ClientHello up to, but not including, this Finished message. This 2867 may be different from handshake_messages in Section 7.4.8 because it 2868 would include the CertificateVerify message (if sent). Also, the 2869 handshake_messages for the Finished message sent by the client will 2870 be different from that for the Finished message sent by the server, 2871 because the one that is sent second will include the prior one. 2873 Note: ChangeCipherSpec messages, alerts, and any other record types 2874 are not handshake messages and are not included in the hash 2875 computations. Also, HelloRequest messages are omitted from handshake 2876 hashes. 2878 8. Cryptographic Computations 2880 In order to begin connection protection, the TLS Record Protocol 2881 requires specification of a suite of algorithms, a master secret, and 2882 the client and server random values. The authentication, encryption, 2883 and MAC algorithms are determined by the cipher_suite selected by the 2884 server and revealed in the server hello message. The compression 2885 algorithm is negotiated in the hello messages, and the random values 2886 are exchanged in the hello messages. All that remains is to calculate 2887 the master secret. 2889 8.1. Computing the Master Secret 2891 For all key exchange methods, the same algorithm is used to convert 2892 the pre_master_secret into the master_secret. The pre_master_secret 2893 should be deleted from memory once the master_secret has been 2894 computed. 2896 master_secret = PRF(pre_master_secret, "master secret", 2897 ClientHello.random + ServerHello.random) 2898 [0..47]; 2900 The master secret is always exactly 48 bytes in length. The length of 2901 the premaster secret will vary depending on key exchange method. 2903 8.1.1. RSA 2905 When RSA is used for server authentication and key exchange, a 2906 48-byte pre_master_secret is generated by the client, encrypted under 2907 the server's public key, and sent to the server. The server uses its 2908 private key to decrypt the pre_master_secret. Both parties then 2909 convert the pre_master_secret into the master_secret, as specified 2910 above. 2912 8.1.2. Diffie-Hellman 2914 A conventional Diffie-Hellman computation is performed. The 2915 negotiated key (Z) is used as the pre_master_secret, and is converted 2916 into the master_secret, as specified above. Leading bytes of Z that 2917 contain all zero bits are stripped before it is used as the 2918 pre_master_secret. 2920 Note: Diffie-Hellman parameters are specified by the server and may 2921 be either ephemeral or contained within the server's certificate. 2923 9. Mandatory Cipher Suites 2925 In the absence of an application profile standard specifying 2926 otherwise, a TLS compliant application MUST implement the cipher 2927 suite TLS_RSA_WITH_AES_128_CBC_SHA (see Appendix A.5 for the 2928 definition). 2930 10. Application Data Protocol 2932 Application data messages are carried by the Record Layer and are 2933 fragmented, compressed, and encrypted based on the current connection 2934 state. The messages are treated as transparent data to the record 2935 layer. 2937 11. Security Considerations 2939 Security issues are discussed throughout this memo, especially in 2940 Appendices D, E, and F. 2942 12. IANA Considerations 2944 This document uses several registries that were originally created in 2945 [TLS1.1]. IANA is requested to update (has updated) these to 2946 reference this document. The registries and their allocation policies 2947 (unchanged from [TLS1.1]) are listed below. 2949 - TLS ClientCertificateType Identifiers Registry: Future values in 2950 the range 0-63 (decimal) inclusive are assigned via Standards 2951 Action [RFC2434]. Values in the range 64-223 (decimal) inclusive 2952 are assigned Specification Required [RFC2434]. Values from 224-255 2953 (decimal) inclusive are reserved for Private Use [RFC2434]. 2955 - TLS Cipher Suite Registry: Future values with the first byte in 2956 the range 0-191 (decimal) inclusive are assigned via Standards 2957 Action [RFC2434]. Values with the first byte in the range 192-254 2958 (decimal) are assigned via Specification Required [RFC2434]. 2959 Values with the first byte 255 (decimal) are reserved for Private 2960 Use [RFC2434]. 2962 - This document defines several new HMAC-SHA256 based cipher suites, 2963 whose values (in Appendix A.5) are to be (have been) allocated 2964 from the TLS Cipher Suite registry. 2966 - TLS ContentType Registry: Future values are allocated via 2967 Standards Action [RFC2434]. 2969 - TLS Alert Registry: Future values are allocated via Standards 2970 Action [RFC2434]. 2972 - TLS HandshakeType Registry: Future values are allocated via 2973 Standards Action [RFC2434]. 2975 This document also uses a registry originally created in [RFC4366]. 2976 IANA is requested to update (has updated) it to reference this 2977 document. The registry and its allocation policy (unchanged from 2978 [RFC4366]) is listed below: 2980 - TLS ExtensionType Registry: Future values are allocated via IETF 2981 Consensus [RFC2434]. IANA is requested to update this registry to 2982 include the signature_algorithms extension and fill in the 2983 appropriate value in Section 7.4.1.4. 2985 In addition, this document defines two new registries to be 2986 maintained by IANA: 2988 - TLS SignatureAlgorithm Registry: The registry will be initially 2989 populated with the values described in Section 7.4.1.4.1. Future 2990 values in the range 0-63 (decimal) inclusive are assigned via 2991 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 2992 inclusive are assigned via Specification Required [RFC2434]. 2993 Values from 224-255 (decimal) inclusive are reserved for Private 2994 Use [RFC2434]. 2996 - TLS HashAlgorithm Registry: The registry will be initially 2997 populated with the values described in Section 7.4.1.4.1. Future 2998 values in the range 0-63 (decimal) inclusive are assigned via 2999 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 3000 inclusive are assigned via Specification Required [RFC2434]. 3001 Values from 224-255 (decimal) inclusive are reserved for Private 3002 Use [RFC2434]. 3004 This document also uses the TLS Compression Method Identifiers 3005 Registry, defined in [RFC3749]. IANA is requested to allocate 3006 value 0 for the "null" compression method. 3008 Appendix A. Protocol Data Structures and Constant Values 3010 This section describes protocol types and constants. 3012 A.1. Record Layer 3014 struct { 3015 uint8 major; 3016 uint8 minor; 3017 } ProtocolVersion; 3019 ProtocolVersion version = { 3, 3 }; /* TLS v1.2*/ 3021 enum { 3022 change_cipher_spec(20), alert(21), handshake(22), 3023 application_data(23), (255) 3024 } ContentType; 3026 struct { 3027 ContentType type; 3028 ProtocolVersion version; 3029 uint16 length; 3030 opaque fragment[TLSPlaintext.length]; 3031 } TLSPlaintext; 3033 struct { 3034 ContentType type; 3035 ProtocolVersion version; 3036 uint16 length; 3037 opaque fragment[TLSCompressed.length]; 3038 } TLSCompressed; 3040 struct { 3041 ContentType type; 3042 ProtocolVersion version; 3043 uint16 length; 3044 select (SecurityParameters.cipher_type) { 3045 case stream: GenericStreamCipher; 3046 case block: GenericBlockCipher; 3047 case aead: GenericAEADCipher; 3048 } fragment; 3049 } TLSCiphertext; 3051 stream-ciphered struct { 3052 opaque content[TLSCompressed.length]; 3053 opaque MAC[SecurityParameters.mac_length]; 3054 } GenericStreamCipher; 3055 struct { 3056 opaque IV[SecurityParameters.record_iv_length]; 3057 block-ciphered struct { 3058 opaque content[TLSCompressed.length]; 3059 opaque MAC[SecurityParameters.mac_length]; 3060 uint8 padding[GenericBlockCipher.padding_length]; 3061 uint8 padding_length; 3062 }; 3063 } GenericBlockCipher; 3065 struct { 3066 opaque nonce_explicit[SecurityParameters.record_iv_length]; 3067 aead-ciphered struct { 3068 opaque content[TLSCompressed.length]; 3069 }; 3070 } GenericAEADCipher; 3071 A.2. Change Cipher Specs Message 3073 struct { 3074 enum { change_cipher_spec(1), (255) } type; 3075 } ChangeCipherSpec; 3077 A.3. Alert Messages 3079 enum { warning(1), fatal(2), (255) } AlertLevel; 3081 enum { 3082 close_notify(0), 3083 unexpected_message(10), 3084 bad_record_mac(20), 3085 decryption_failed_RESERVED(21), 3086 record_overflow(22), 3087 decompression_failure(30), 3088 handshake_failure(40), 3089 no_certificate_RESERVED(41), 3090 bad_certificate(42), 3091 unsupported_certificate(43), 3092 certificate_revoked(44), 3093 certificate_expired(45), 3094 certificate_unknown(46), 3095 illegal_parameter(47), 3096 unknown_ca(48), 3097 access_denied(49), 3098 decode_error(50), 3099 decrypt_error(51), 3100 export_restriction_RESERVED(60), 3101 protocol_version(70), 3102 insufficient_security(71), 3103 internal_error(80), 3104 user_canceled(90), 3105 no_renegotiation(100), 3106 unsupported_extension(110), /* new */ 3107 (255) 3108 } AlertDescription; 3110 struct { 3111 AlertLevel level; 3112 AlertDescription description; 3113 } Alert; 3115 A.4. Handshake Protocol 3117 enum { 3118 hello_request(0), client_hello(1), server_hello(2), 3119 certificate(11), server_key_exchange (12), 3120 certificate_request(13), server_hello_done(14), 3121 certificate_verify(15), client_key_exchange(16), 3122 finished(20) 3123 (255) 3124 } HandshakeType; 3126 struct { 3127 HandshakeType msg_type; 3128 uint24 length; 3129 select (HandshakeType) { 3130 case hello_request: HelloRequest; 3131 case client_hello: ClientHello; 3132 case server_hello: ServerHello; 3133 case certificate: Certificate; 3134 case server_key_exchange: ServerKeyExchange; 3135 case certificate_request: CertificateRequest; 3136 case server_hello_done: ServerHelloDone; 3137 case certificate_verify: CertificateVerify; 3138 case client_key_exchange: ClientKeyExchange; 3139 case finished: Finished; 3140 } body; 3141 } Handshake; 3143 A.4.1. Hello Messages 3145 struct { } HelloRequest; 3147 struct { 3148 uint32 gmt_unix_time; 3149 opaque random_bytes[28]; 3150 } Random; 3151 opaque SessionID<0..32>; 3153 uint8 CipherSuite[2]; 3155 enum { null(0), (255) } CompressionMethod; 3157 struct { 3158 ProtocolVersion client_version; 3159 Random random; 3160 SessionID session_id; 3161 CipherSuite cipher_suites<2..2^16-2>; 3162 CompressionMethod compression_methods<1..2^8-1>; 3163 select (extensions_present) { 3164 case false: 3165 struct {}; 3166 case true: 3167 Extension extensions<0..2^16-1>; 3168 }; 3169 } ClientHello; 3171 struct { 3172 ProtocolVersion server_version; 3173 Random random; 3174 SessionID session_id; 3175 CipherSuite cipher_suite; 3176 CompressionMethod compression_method; 3177 select (extensions_present) { 3178 case false: 3179 struct {}; 3180 case true: 3181 Extension extensions<0..2^16-1>; 3182 }; 3183 } ServerHello; 3185 struct { 3186 ExtensionType extension_type; 3187 opaque extension_data<0..2^16-1>; 3188 } Extension; 3190 enum { 3191 signature_algorithms(TBD-BY-IANA), (65535) 3192 } ExtensionType; 3194 enum{ 3195 none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5), 3196 sha512(6), (255) 3197 } HashAlgorithm; 3198 enum { 3199 anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) 3200 } SignatureAlgorithm; 3202 struct { 3203 HashAlgorithm hash; 3204 SignatureAlgorithm signature; 3205 } SignatureAndHashAlgorithm; 3207 SignatureAndHashAlgorithm 3208 supported_signature_algorithms<2..2^16-1>; 3210 A.4.2. Server Authentication and Key Exchange Messages 3212 opaque ASN.1Cert<2^24-1>; 3214 struct { 3215 ASN.1Cert certificate_list<0..2^24-1>; 3216 } Certificate; 3218 enum { dhe_dss, dhe_rsa, dh_anon, rsa,dh_dss, dh_rsa 3219 /* may be extended, e.g. for ECDH -- see [TLSECC] */ 3220 } KeyExchangeAlgorithm; 3222 struct { 3223 opaque dh_p<1..2^16-1>; 3224 opaque dh_g<1..2^16-1>; 3225 opaque dh_Ys<1..2^16-1>; 3226 } ServerDHParams; /* Ephemeral DH parameters */ 3228 struct { 3229 select (KeyExchangeAlgorithm) { 3230 case dh_anon: 3231 ServerDHParams params; 3232 case dhe_dss: 3233 case dhe_rsa: 3234 ServerDHParams params; 3235 digitally-signed struct { 3236 opaque client_random[32]; 3237 opaque server_random[32]; 3238 ServerDHParams params; 3239 } signed_params; 3240 case rsa: 3241 case dh_dss: 3242 case dh_rsa: 3243 struct {} ; 3244 /* message is omitted for rsa, dh_dss, and dh_rsa */ 3245 /* may be extended, e.g. for ECDH -- see [TLSECC] */ 3247 } ServerKeyExchange; 3249 enum { 3250 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 3251 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 3252 fortezza_dms_RESERVED(20), 3253 (255) 3254 } ClientCertificateType; 3256 opaque DistinguishedName<1..2^16-1>; 3258 struct { 3259 ClientCertificateType certificate_types<1..2^8-1>; 3260 DistinguishedName certificate_authorities<0..2^16-1>; 3261 } CertificateRequest; 3263 struct { } ServerHelloDone; 3265 A.4.3. Client Authentication and Key Exchange Messages 3267 struct { 3268 select (KeyExchangeAlgorithm) { 3269 case rsa: 3270 EncryptedPreMasterSecret; 3271 case dhe_dss: 3272 case dhe_rsa: 3273 case dh_dss: 3274 case dh_rsa: 3275 case dh_anon: 3276 ClientDiffieHellmanPublic; 3277 } exchange_keys; 3278 } ClientKeyExchange; 3280 struct { 3281 ProtocolVersion client_version; 3282 opaque random[46]; 3283 } PreMasterSecret; 3285 struct { 3286 public-key-encrypted PreMasterSecret pre_master_secret; 3287 } EncryptedPreMasterSecret; 3289 enum { implicit, explicit } PublicValueEncoding; 3291 struct { 3292 select (PublicValueEncoding) { 3293 case implicit: struct {}; 3294 case explicit: opaque DH_Yc<1..2^16-1>; 3295 } dh_public; 3296 } ClientDiffieHellmanPublic; 3298 struct { 3299 digitally-signed struct { 3300 opaque handshake_messages[handshake_messages_length]; 3301 } 3302 } CertificateVerify; 3304 A.4.4. Handshake Finalization Message 3306 struct { 3307 opaque verify_data[verify_data_length]; 3308 } Finished; 3310 A.5. The Cipher Suite 3312 The following values define the cipher suite codes used in the client 3313 hello and server hello messages. 3315 A cipher suite defines a cipher specification supported in TLS 3316 Version 1.2. 3318 TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a 3319 TLS connection during the first handshake on that channel, but MUST 3320 NOT be negotiated, as it provides no more protection than an 3321 unsecured connection. 3323 CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 }; 3325 The following CipherSuite definitions require that the server provide 3326 an RSA certificate that can be used for key exchange. The server may 3327 request any signature-capable certificate in the certificate request 3328 message. 3330 CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 }; 3331 CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 }; 3332 CipherSuite TLS_RSA_WITH_NULL_SHA256 = { 0x00,TBD1 }; 3333 CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 }; 3334 CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 }; 3335 CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A }; 3336 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x2F }; 3337 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x35 }; 3338 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,TBD2 }; 3339 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,TBD3 }; 3341 The following cipher suite definitions are used for server- 3342 authenticated (and optionally client-authenticated) Diffie-Hellman. 3343 DH denotes cipher suites in which the server's certificate contains 3344 the Diffie-Hellman parameters signed by the certificate authority 3345 (CA). DHE denotes ephemeral Diffie-Hellman, where the Diffie-Hellman 3346 parameters are signed by a signature-capable certificate, which has 3347 been signed by the CA. The signing algorithm used by the server is 3348 specified after the DHE component of the CipherSuite name. The server 3349 can request any signature-capable certificate from the client for 3350 client authentication or it may request a Diffie-Hellman certificate. 3351 Any Diffie-Hellman certificate provided by the client must use the 3352 parameters (group and generator) described by the server. 3354 CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D }; 3355 CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 }; 3356 CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 }; 3357 CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 }; 3358 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x30 }; 3359 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x31 }; 3360 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x32 }; 3361 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x33 }; 3362 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x36 }; 3363 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x37 }; 3364 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x38 }; 3365 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x39 }; 3366 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA256 = { 0x00,TBD4 }; 3367 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,TBD5 }; 3368 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 = { 0x00,TBD6 }; 3369 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,TBD7 }; 3370 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA256 = { 0x00,TBD8 }; 3371 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,TBD9 }; 3372 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 = { 0x00,TBDA }; 3373 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,TBDB }; 3375 The following cipher suites are used for completely anonymous Diffie- 3376 Hellman communications in which neither party is authenticated. Note 3377 that this mode is vulnerable to man-in-the-middle attacks. Using 3378 this mode therefore is of limited use: These cipher suites MUST NOT 3379 be used by TLS 1.2 implementations unless the application layer has 3380 specifically requested to allow anonymous key exchange. (Anonymous 3381 key exchange may sometimes be acceptable, for example, to support 3382 opportunistic encryption when no set-up for authentication is in 3383 place, or when TLS is used as part of more complex security protocols 3384 that have other means to ensure authentication.) 3386 CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 }; 3387 CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B }; 3388 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA = { 0x00,0x34 }; 3389 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA = { 0x00,0x3A }; 3390 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA256 = { 0x00,TBDC}; 3391 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA256 = { 0x00,TBDD}; 3393 Note that using non-anonymous key exchange without actually verifying 3394 the key exchange is essentially equivalent to anonymous key exchange, 3395 and the same precautions apply. While non-anonymous key exchange 3396 will generally involve a higher computational and communicational 3397 cost than anonymous key exchange, it may be in the interest of 3398 interoperability not to disable non-anonymous key exchange when the 3399 application layer is allowing anonymous key exchange. 3401 New cipher suite values are assigned by IANA as described in Section 3402 12. 3404 Note: The cipher suite values { 0x00, 0x1C } and { 0x00, 0x1D } are 3405 reserved to avoid collision with Fortezza-based cipher suites in SSL 3406 3. 3408 A.6. The Security Parameters 3410 These security parameters are determined by the TLS Handshake 3411 Protocol and provided as parameters to the TLS Record Layer in order 3412 to initialize a connection state. SecurityParameters includes: 3414 enum { null(0), (255) } CompressionMethod; 3416 enum { server, client } ConnectionEnd; 3418 enum { tls_prf_sha256 } PRFAlgorithm; 3420 enum { null, rc4, 3des, aes } 3421 BulkCipherAlgorithm; 3423 enum { stream, block, aead } CipherType; 3425 enum { null, hmac_md5, hmac_sha1, hmac_sha256, hmac_sha384, 3426 hmac_sha512} MACAlgorithm; 3428 /* The algorithms specified in CompressionMethod, PRFAlgorithm 3429 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 3431 struct { 3432 ConnectionEnd entity; 3433 PRFAlgorithm prf_algorithm; 3434 BulkCipherAlgorithm bulk_cipher_algorithm; 3435 CipherType cipher_type; 3436 uint8 enc_key_length; 3437 uint8 block_length; 3438 uint8 fixed_iv_length; 3439 uint8 record_iv_length; 3440 MACAlgorithm mac_algorithm; 3441 uint8 mac_length; 3442 uint8 mac_key_length; 3443 CompressionMethod compression_algorithm; 3444 opaque master_secret[48]; 3445 opaque client_random[32]; 3446 opaque server_random[32]; 3447 } SecurityParameters; 3449 A.7. Changes to RFC 4492 3451 RFC 4492 [TLSECC] adds Elliptic Curve cipher suites to TLS. This 3452 document changes some of the structures used in that document. This 3453 section details the required changes for implementors of both RFC 3454 4492 and TLS 1.2. Implementors of TLS 1.2 who are not implementing 3455 RFC 4492 do not need to read this section. 3457 This document adds a "signature_algorithm" field to the digitally- 3458 signed element in order to identify the signature and digest 3459 algorithms used to create a signature. This change applies to digital 3460 signatures formed using ECDSA as well, thus allowing ECDSA signatures 3461 to be used with digest algorithms other than SHA-1, provided such use 3462 is compatible with the certificate and any restrictions imposed by 3463 future revisions of [PKIX]. 3465 As described in Sections 7.4.2 and 7.4.6, the restrictions on the 3466 signature algorithms used to sign certificates are no longer tied to 3467 the cipher suite (when used by the server) or the 3468 ClientCertificateType (when used by the client). Thus, the 3469 restrictions on the algorithm used to sign certificates specified in 3470 Sections 2 and 3 of RFC 4492 are also relaxed. As in this document 3471 the restrictions on the keys in the end-entity certificate remain. 3473 Appendix B. Glossary 3475 Advanced Encryption Standard (AES) 3476 AES [AES] is a widely used symmetric encryption algorithm. AES is 3477 a block cipher with a 128, 192, or 256 bit keys and a 16 byte 3478 block size. TLS currently only supports the 128 and 256 bit key 3479 sizes. 3481 application protocol 3482 An application protocol is a protocol that normally layers 3483 directly on top of the transport layer (e.g., TCP/IP). Examples 3484 include HTTP, TELNET, FTP, and SMTP. 3486 asymmetric cipher 3487 See public key cryptography. 3489 authenticated encryption with additional data (AEAD) 3490 A symmetric encryption algorithm that simultaneously provides 3491 confidentiality and message integrity. 3493 authentication 3494 Authentication is the ability of one entity to determine the 3495 identity of another entity. 3497 block cipher 3498 A block cipher is an algorithm that operates on plaintext in 3499 groups of bits, called blocks. 64 bits was, and 128 bits, is a 3500 common block size. 3502 bulk cipher 3503 A symmetric encryption algorithm used to encrypt large quantities 3504 of data. 3506 cipher block chaining (CBC) 3507 CBC is a mode in which every plaintext block encrypted with a 3508 block cipher is first exclusive-ORed with the previous ciphertext 3509 block (or, in the case of the first block, with the initialization 3510 vector). For decryption, every block is first decrypted, then 3511 exclusive-ORed with the previous ciphertext block (or IV). 3513 certificate 3514 As part of the X.509 protocol (a.k.a. ISO Authentication 3515 framework), certificates are assigned by a trusted Certificate 3516 Authority and provide a strong binding between a party's identity 3517 or some other attributes and its public key. 3519 client 3520 The application entity that initiates a TLS connection to a 3521 server. This may or may not imply that the client initiated the 3522 underlying transport connection. The primary operational 3523 difference between the server and client is that the server is 3524 generally authenticated, while the client is only optionally 3525 authenticated. 3527 client write key 3528 The key used to encrypt data written by the client. 3530 client write MAC key 3531 The secret data used to authenticate data written by the client. 3533 connection 3534 A connection is a transport (in the OSI layering model definition) 3535 that provides a suitable type of service. For TLS, such 3536 connections are peer-to-peer relationships. The connections are 3537 transient. Every connection is associated with one session. 3539 Data Encryption Standard 3540 DES [DES] still is a very widely used symmetric encryption 3541 algorithm although it is considered as rather weak now. DES is a 3542 block cipher with a 56-bit key and an 8-byte block size. Note that 3543 in TLS, for key generation purposes, DES is treated as having an 3544 8-byte key length (64 bits), but it still only provides 56 bits of 3545 protection. (The low bit of each key byte is presumed to be set to 3546 produce odd parity in that key byte.) DES can also be operated in 3547 a mode [3DES] where three independent keys and three encryptions 3548 are used for each block of data; this uses 168 bits of key (24 3549 bytes in the TLS key generation method) and provides the 3550 equivalent of 112 bits of security. 3552 Digital Signature Standard (DSS) 3553 A standard for digital signing, including the Digital Signing 3554 Algorithm, approved by the National Institute of Standards and 3555 Technology, defined in NIST FIPS PUB 186-2, "Digital Signature 3556 Standard", published January 2000 by the U.S. Dept. of Commerce 3557 [DSS]. A significant update [DSS-3] has been drafted and 3558 published in March 2006. 3560 digital signatures 3561 Digital signatures utilize public key cryptography and one-way 3562 hash functions to produce a signature of the data that can be 3563 authenticated, and is difficult to forge or repudiate. 3565 handshake 3566 An initial negotiation between client and server that establishes 3567 the parameters of their transactions. 3569 Initialization Vector (IV) 3570 When a block cipher is used in CBC mode, the initialization vector 3571 is exclusive-ORed with the first plaintext block prior to 3572 encryption. 3574 Message Authentication Code (MAC) 3575 A Message Authentication Code is a one-way hash computed from a 3576 message and some secret data. It is difficult to forge without 3577 knowing the secret data. Its purpose is to detect if the message 3578 has been altered. 3580 master secret 3581 Secure secret data used for generating encryption keys, MAC 3582 secrets, and IVs. 3584 MD5 3585 MD5 [MD5] is a hashing function that converts an arbitrarily long 3586 data stream into a hash of fixed size (16 bytes). Due to 3587 significant progresses in cryptanalysis, at the time of 3588 publication of this document, MD5 no longer can be considered a 3589 'secure' hashing function. 3591 public key cryptography 3592 A class of cryptographic techniques employing two-key ciphers. 3593 Messages encrypted with the public key can only be decrypted with 3594 the associated private key. Conversely, messages signed with the 3595 private key can be verified with the public key. 3597 one-way hash function 3598 A one-way transformation that converts an arbitrary amount of data 3599 into a fixed-length hash. It is computationally hard to reverse 3600 the transformation or to find collisions. MD5 and SHA are examples 3601 of one-way hash functions. 3603 RC4 3604 A stream cipher invented by Ron Rivest. A compatible cipher is 3605 described in [SCH]. 3607 RSA 3608 A very widely used public-key algorithm that can be used for 3609 either encryption or digital signing. [RSA] 3611 server 3612 The server is the application entity that responds to requests for 3613 connections from clients. See also under client. 3615 session 3616 A TLS session is an association between a client and a server. 3617 Sessions are created by the handshake protocol. Sessions define a 3618 set of cryptographic security parameters that can be shared among 3619 multiple connections. Sessions are used to avoid the expensive 3620 negotiation of new security parameters for each connection. 3622 session identifier 3623 A session identifier is a value generated by a server that 3624 identifies a particular session. 3626 server write key 3627 The key used to encrypt data written by the server. 3629 server write MAC key 3630 The secret data used to authenticate data written by the server. 3632 SHA 3633 The Secure Hash Algorithm [SHS] is defined in FIPS PUB 180-2. It 3634 produces a 20-byte output. Note that all references to SHA 3635 (without a numerical suffix) actually use the modified SHA-1 3636 algorithm. 3638 SHA-256 3639 The 256-bit Secure Hash Algorithm is defined in FIPS PUB 180-2. It 3640 produces a 32-byte output. 3642 SSL 3643 Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on 3644 SSL Version 3.0 3646 stream cipher 3647 An encryption algorithm that converts a key into a 3648 cryptographically strong keystream, which is then exclusive-ORed 3649 with the plaintext. 3651 symmetric cipher 3652 See bulk cipher. 3654 Transport Layer Security (TLS) 3655 This protocol; also, the Transport Layer Security working group of 3656 the Internet Engineering Task Force (IETF). See "Comments" at the 3657 end of this document. 3659 Appendix C. Cipher Suite Definitions 3661 Cipher Suite Key Cipher Mac 3662 Exchange 3664 TLS_NULL_WITH_NULL_NULL NULL NULL NULL 3665 TLS_RSA_WITH_NULL_MD5 RSA NULL MD5 3666 TLS_RSA_WITH_NULL_SHA RSA NULL SHA 3667 TLS_RSA_WITH_NULL_SHA256 RSA NULL SHA256 3668 TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5 3669 TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA 3670 TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA 3671 TLS_RSA_WITH_AES_128_CBC_SHA RSA AES_128_CBC SHA 3672 TLS_RSA_WITH_AES_256_CBC_SHA RSA AES_256_CBC SHA 3673 TLS_RSA_WITH_AES_128_CBC_SHA256 RSA AES_128_CBC SHA256 3674 TLS_RSA_WITH_AES_256_CBC_SHA256 RSA AES_256_CBC SHA256 3675 TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA 3676 TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA 3677 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA 3678 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA 3679 TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5 3680 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA 3681 TLS_DH_DSS_WITH_AES_128_CBC_SHA DH_DSS AES_128_CBC SHA 3682 TLS_DH_RSA_WITH_AES_128_CBC_SHA DH_RSA AES_128_CBC SHA 3683 TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE_DSS AES_128_CBC SHA 3684 TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE_RSA AES_128_CBC SHA 3685 TLS_DH_anon_WITH_AES_128_CBC_SHA DH_anon AES_128_CBC SHA 3686 TLS_DH_DSS_WITH_AES_256_CBC_SHA DH_DSS AES_256_CBC SHA 3687 TLS_DH_RSA_WITH_AES_256_CBC_SHA DH_RSA AES_256_CBC SHA 3688 TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE_DSS AES_256_CBC SHA 3689 TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE_RSA AES_256_CBC SHA 3690 TLS_DH_anon_WITH_AES_256_CBC_SHA DH_anon AES_256_CBC SHA 3691 TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH_DSS AES_128_CBC SHA256 3692 TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH_RSA AES_128_CBC SHA256 3693 TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE_DSS AES_128_CBC SHA256 3694 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE_RSA AES_128_CBC SHA256 3695 TLS_DH_anon_WITH_AES_128_CBC_SHA256 DH_anon AES_128_CBC SHA256 3696 TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH_DSS AES_256_CBC SHA256 3697 TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH_RSA AES_256_CBC SHA256 3698 TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE_DSS AES_256_CBC SHA256 3699 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE_RSA AES_256_CBC SHA256 3700 TLS_DH_anon_WITH_AES_256_CBC_SHA256 DH_anon AES_256_CBC SHA256 3702 Key IV Block 3703 Cipher Type Material Size Size 3704 ------------ ------ -------- ---- ----- 3705 NULL Stream 0 0 N/A 3706 RC4_128 Stream 16 0 N/A 3707 3DES_EDE_CBC Block 24 8 8 3708 AES_128_CBC Block 16 16 16 3709 AES_256_CBC Block 32 16 16 3711 MAC Algorithm mac_length mac_key_length 3712 -------- ----------- ---------- -------------- 3713 NULL N/A 0 0 3714 MD5 HMAC-MD5 16 16 3715 SHA HMAC-SHA1 20 20 3716 SHA256 HMAC-SHA256 32 32 3718 Type 3719 Indicates whether this is a stream cipher or a block cipher 3720 running in CBC mode. 3722 Key Material 3723 The number of bytes from the key_block that are used for 3724 generating the write keys. 3726 Expanded Key Material 3727 The number of bytes actually fed into the encryption algorithm. 3729 IV Size 3730 The amount of data needed to be generated for the initialization 3731 vector. Zero for stream ciphers; equal to the block size for block 3732 ciphers (this is equal to SecurityParameters.record_iv_length). 3734 Block Size 3735 The amount of data a block cipher enciphers in one chunk; a block 3736 cipher running in CBC mode can only encrypt an even multiple of 3737 its block size. 3739 Appendix D. Implementation Notes 3741 The TLS protocol cannot prevent many common security mistakes. This 3742 section provides several recommendations to assist implementors. 3744 D.1 Random Number Generation and Seeding 3746 TLS requires a cryptographically secure pseudorandom number generator 3747 (PRNG). Care must be taken in designing and seeding PRNGs. PRNGs 3748 based on secure hash operations, most notably SHA-1, are acceptable, 3749 but cannot provide more security than the size of the random number 3750 generator state. 3752 To estimate the amount of seed material being produced, add the 3753 number of bits of unpredictable information in each seed byte. For 3754 example, keystroke timing values taken from a PC compatible's 18.2 Hz 3755 timer provide 1 or 2 secure bits each, even though the total size of 3756 the counter value is 16 bits or more. Seeding a 128-bit PRNG would 3757 thus require approximately 100 such timer values. 3759 [RANDOM] provides guidance on the generation of random values. 3761 D.2 Certificates and Authentication 3763 Implementations are responsible for verifying the integrity of 3764 certificates and should generally support certificate revocation 3765 messages. Certificates should always be verified to ensure proper 3766 signing by a trusted Certificate Authority (CA). The selection and 3767 addition of trusted CAs should be done very carefully. Users should 3768 be able to view information about the certificate and root CA. 3770 D.3 Cipher Suites 3772 TLS supports a range of key sizes and security levels, including some 3773 that provide no or minimal security. A proper implementation will 3774 probably not support many cipher suites. For instance, anonymous 3775 Diffie-Hellman is strongly discouraged because it cannot prevent man- 3776 in-the-middle attacks. Applications should also enforce minimum and 3777 maximum key sizes. For example, certificate chains containing 512-bit 3778 RSA keys or signatures are not appropriate for high-security 3779 applications. 3781 D.4 Implementation Pitfalls 3783 Implementation experience has shown that certain parts of earlier TLS 3784 specifications are not easy to understand, and have been a source of 3785 interoperability and security problems. Many of these areas have been 3786 clarified in this document, but this appendix contains a short list 3787 of the most important things that require special attention from 3788 implementors. 3790 TLS protocol issues: 3792 - Do you correctly handle handshake messages that are fragmented 3793 to multiple TLS records (see Section 6.2.1)? Including corner 3794 cases like a ClientHello that is split to several small 3795 fragments? Do you fragment handshake messages that exceed the 3796 maximum fragment size? In particular, the certificate and 3797 certificate request handshake messages can be large enough to 3798 require fragmentation. 3800 - Do you ignore the TLS record layer version number in all TLS 3801 records before ServerHello (see Appendix E.1)? 3803 - Do you handle TLS extensions in ClientHello correctly, 3804 including omitting the extensions field completely? 3806 - Do you support renegotiation, both client and server initiated? 3807 While renegotiation is an optional feature, supporting 3808 it is highly recommended. 3810 - When the server has requested a client certificate, but no 3811 suitable certificate is available, do you correctly send 3812 an empty Certificate message, instead of omitting the whole 3813 message (see Section 7.4.6)? 3815 Cryptographic details: 3817 - In RSA-encrypted Premaster Secret, do you correctly send and 3818 verify the version number? When an error is encountered, do 3819 you continue the handshake to avoid the Bleichenbacher 3820 attack (see Section 7.4.7.1)? 3822 - What countermeasures do you use to prevent timing attacks against 3823 RSA decryption and signing operations (see Section 7.4.7.1)? 3825 - When verifying RSA signatures, do you accept both NULL and 3826 missing parameters (see Section 4.7)? Do you verify that the 3827 RSA padding doesn't have additional data after the hash value? 3828 [FI06] 3830 - When using Diffie-Hellman key exchange, do you correctly strip 3831 leading zero bytes from the negotiated key (see Section 8.1.2)? 3833 - Does your TLS client check that the Diffie-Hellman parameters 3834 sent by the server are acceptable (see Section F.1.1.3)? 3836 - How do you generate unpredictable IVs for CBC mode ciphers 3837 (see Section 6.2.3.2)? 3839 - Do you accept long CBC mode padding (up to 255 bytes; see 3840 Section 6.2.3.2)? 3842 - How do you address CBC mode timing attacks (Section 6.2.3.2)? 3844 - Do you use a strong and, most importantly, properly seeded 3845 random number generator (see Appendix D.1) for generating the 3846 premaster secret (for RSA key exchange), Diffie-Hellman private 3847 values, the DSA "k" parameter, and other security-critical 3848 values? 3850 Appendix E. Backward Compatibility 3852 E.1 Compatibility with TLS 1.0/1.1 and SSL 3.0 3854 Since there are various versions of TLS (1.0, 1.1, 1.2, and any 3855 future versions) and SSL (2.0 and 3.0), means are needed to negotiate 3856 the specific protocol version to use. The TLS protocol provides a 3857 built-in mechanism for version negotiation so as not to bother other 3858 protocol components with the complexities of version selection. 3860 TLS versions 1.0, 1.1, and 1.2, and SSL 3.0 are very similar, and use 3861 compatible ClientHello messages; thus, supporting all of them is 3862 relatively easy. Similarly, servers can easily handle clients trying 3863 to use future versions of TLS as long as the ClientHello format 3864 remains compatible, and the client supports the highest protocol 3865 version available in the server. 3867 A TLS 1.2 client who wishes to negotiate with such older servers will 3868 send a normal TLS 1.2 ClientHello, containing { 3, 3 } (TLS 1.2) in 3869 ClientHello.client_version. If the server does not support this 3870 version, it will respond with ServerHello containing an older version 3871 number. If the client agrees to use this version, the negotiation 3872 will proceed as appropriate for the negotiated protocol. 3874 If the version chosen by the server is not supported by the client 3875 (or not acceptable), the client MUST send a "protocol_version" alert 3876 message and close the connection. 3878 If a TLS server receives a ClientHello containing a version number 3879 greater than the highest version supported by the server, it MUST 3880 reply according to the highest version supported by the server. 3882 A TLS server can also receive a ClientHello containing a version 3883 number smaller than the highest supported version. If the server 3884 wishes to negotiate with old clients, it will proceed as appropriate 3885 for the highest version supported by the server that is not greater 3886 than ClientHello.client_version. For example, if the server supports 3887 TLS 1.0, 1.1, and 1.2, and client_version is TLS 1.0, the server will 3888 proceed with a TLS 1.0 ServerHello. If server supports (or is willing 3889 to use) only versions greater than client_version, it MUST send a 3890 "protocol_version" alert message and close the connection. 3892 Whenever a client already knows the highest protocol version known to 3893 a server (for example, when resuming a session), it SHOULD initiate 3894 the connection in that native protocol. 3896 Note: some server implementations are known to implement version 3897 negotiation incorrectly. For example, there are buggy TLS 1.0 servers 3898 that simply close the connection when the client offers a version 3899 newer than TLS 1.0. Also, it is known that some servers will refuse 3900 the connection if any TLS extensions are included in ClientHello. 3901 Interoperability with such buggy servers is a complex topic beyond 3902 the scope of this document, and may require multiple connection 3903 attempts by the client. 3905 Earlier versions of the TLS specification were not fully clear on 3906 what the record layer version number (TLSPlaintext.version) should 3907 contain when sending ClientHello (i.e., before it is known which 3908 version of the protocol will be employed). Thus, TLS servers 3909 compliant with this specification MUST accept any value {03,XX} as 3910 the record layer version number for ClientHello. 3912 TLS clients that wish to negotiate with older servers MAY send any 3913 value {03,XX} as the record layer version number. Typical values 3914 would be {03,00}, the lowest version number supported by the client, 3915 and the value of ClientHello.client_version. No single value will 3916 guarantee interoperability with all old servers, but this is a 3917 complex topic beyond the scope of this document. 3919 E.2 Compatibility with SSL 2.0 3921 TLS 1.2 clients that wish to support SSL 2.0 servers MUST send 3922 version 2.0 CLIENT-HELLO messages defined in [SSL2]. The message MUST 3923 contain the same version number as would be used for ordinary 3924 ClientHello, and MUST encode the supported TLS cipher suites in the 3925 CIPHER-SPECS-DATA field as described below. 3927 Warning: The ability to send version 2.0 CLIENT-HELLO messages will 3928 be phased out with all due haste, since the newer ClientHello format 3929 provides better mechanisms for moving to newer versions and 3930 negotiating extensions. TLS 1.2 clients SHOULD NOT support SSL 2.0. 3932 However, even TLS servers that do not support SSL 2.0 MAY accept 3933 version 2.0 CLIENT-HELLO messages. The message is presented below in 3934 sufficient detail for TLS server implementors; the true definition is 3935 still assumed to be [SSL2]. 3937 For negotiation purposes, 2.0 CLIENT-HELLO is interpreted the same 3938 way as a ClientHello with a "null" compression method and no 3939 extensions. Note that this message MUST be sent directly on the wire, 3940 not wrapped as a TLS record. For the purposes of calculating Finished 3941 and CertificateVerify, the msg_length field is not considered to be a 3942 part of the handshake message. 3944 uint8 V2CipherSpec[3]; 3945 struct { 3946 uint16 msg_length; 3947 uint8 msg_type; 3948 Version version; 3949 uint16 cipher_spec_length; 3950 uint16 session_id_length; 3951 uint16 challenge_length; 3952 V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length]; 3953 opaque session_id[V2ClientHello.session_id_length]; 3954 opaque challenge[V2ClientHello.challenge_length; 3955 } V2ClientHello; 3957 msg_length 3958 The highest bit MUST be 1; the remaining bits contain the length 3959 of the following data in bytes. 3961 msg_type 3962 This field, in conjunction with the version field, identifies a 3963 version 2 client hello message. The value MUST be one (1). 3965 version 3966 Equal to ClientHello.client_version. 3968 cipher_spec_length 3969 This field is the total length of the field cipher_specs. It 3970 cannot be zero and MUST be a multiple of the V2CipherSpec length 3971 (3). 3973 session_id_length 3974 This field MUST have a value of zero for a client that claims to 3975 support TLS 1.2. 3977 challenge_length 3978 The length in bytes of the client's challenge to the server to 3979 authenticate itself. Historically, permissible values are between 3980 16 and 32 bytes inclusive. When using the SSLv2 backward 3981 compatible handshake the client SHOULD use a 32 byte challenge. 3983 cipher_specs 3984 This is a list of all CipherSpecs the client is willing and able 3985 to use. In addition to the 2.0 cipher specs defined in [SSL2], 3986 this includes the TLS cipher suites normally sent in 3987 ClientHello.cipher_suites, each cipher suite prefixed by a zero 3988 byte. For example, TLS cipher suite {0x00,0x0A} would be sent as 3989 {0x00,0x00,0x0A}. 3991 session_id 3992 This field MUST be empty. 3994 challenge 3995 Corresponds to ClientHello.random. If the challenge length is less 3996 than 32, the TLS server will pad the data with leading (note: not 3997 trailing) zero bytes to make it 32 bytes long. 3999 Note: Requests to resume a TLS session MUST use a TLS client hello. 4001 E.3. Avoiding Man-in-the-Middle Version Rollback 4003 When TLS clients fall back to Version 2.0 compatibility mode, they 4004 MUST use special PKCS#1 block formatting. This is done so that TLS 4005 servers will reject Version 2.0 sessions with TLS-capable clients. 4007 When a client negotiates SSL 2.0 but also supports TLS, it MUST set 4008 the right-hand (least-significant) 8 random bytes of the PKCS padding 4009 (not including the terminal null of the padding) for the RSA 4010 encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY 4011 to 0x03 (the other padding bytes are random). 4013 When a TLS-capable server negotiates SSL 2.0 it SHOULD, after 4014 decrypting the ENCRYPTED-KEY-DATA field, check that these eight 4015 padding bytes are 0x03. If they are not, the server SHOULD generate a 4016 random value for SECRET-KEY-DATA, and continue the handshake (which 4017 will eventually fail since the keys will not match). Note that 4018 reporting the error situation to the client could make the server 4019 vulnerable to attacks described in [BLEI]. 4021 Appendix F. Security Analysis 4023 The TLS protocol is designed to establish a secure connection between 4024 a client and a server communicating over an insecure channel. This 4025 document makes several traditional assumptions, including that 4026 attackers have substantial computational resources and cannot obtain 4027 secret information from sources outside the protocol. Attackers are 4028 assumed to have the ability to capture, modify, delete, replay, and 4029 otherwise tamper with messages sent over the communication channel. 4030 This appendix outlines how TLS has been designed to resist a variety 4031 of attacks. 4033 F.1. Handshake Protocol 4035 The handshake protocol is responsible for selecting a CipherSpec and 4036 generating a Master Secret, which together comprise the primary 4037 cryptographic parameters associated with a secure session. The 4038 handshake protocol can also optionally authenticate parties who have 4039 certificates signed by a trusted certificate authority. 4041 F.1.1. Authentication and Key Exchange 4043 TLS supports three authentication modes: authentication of both 4044 parties, server authentication with an unauthenticated client, and 4045 total anonymity. Whenever the server is authenticated, the channel is 4046 secure against man-in-the-middle attacks, but completely anonymous 4047 sessions are inherently vulnerable to such attacks. Anonymous 4048 servers cannot authenticate clients. If the server is authenticated, 4049 its certificate message must provide a valid certificate chain 4050 leading to an acceptable certificate authority. Similarly, 4051 authenticated clients must supply an acceptable certificate to the 4052 server. Each party is responsible for verifying that the other's 4053 certificate is valid and has not expired or been revoked. 4055 The general goal of the key exchange process is to create a 4056 pre_master_secret known to the communicating parties and not to 4057 attackers. The pre_master_secret will be used to generate the 4058 master_secret (see Section 8.1). The master_secret is required to 4059 generate the finished messages, encryption keys, and MAC keys (see 4060 Sections 7.4.9 and 6.3). By sending a correct finished message, 4061 parties thus prove that they know the correct pre_master_secret. 4063 F.1.1.1. Anonymous Key Exchange 4065 Completely anonymous sessions can be established using Diffie-Hellman 4066 for key exchange. The server's public parameters are contained in the 4067 server key exchange message and the client's are sent in the client 4068 key exchange message. Eavesdroppers who do not know the private 4069 values should not be able to find the Diffie-Hellman result (i.e. the 4070 pre_master_secret). 4072 Warning: Completely anonymous connections only provide protection 4073 against passive eavesdropping. Unless an independent tamper-proof 4074 channel is used to verify that the finished messages were not 4075 replaced by an attacker, server authentication is required in 4076 environments where active man-in-the-middle attacks are a concern. 4078 F.1.1.2. RSA Key Exchange and Authentication 4080 With RSA, key exchange and server authentication are combined. The 4081 public key is contained in the server's certificate. Note that 4082 compromise of the server's static RSA key results in a loss of 4083 confidentiality for all sessions protected under that static key. TLS 4084 users desiring Perfect Forward Secrecy should use DHE cipher suites. 4085 The damage done by exposure of a private key can be limited by 4086 changing one's private key (and certificate) frequently. 4088 After verifying the server's certificate, the client encrypts a 4089 pre_master_secret with the server's public key. By successfully 4090 decoding the pre_master_secret and producing a correct finished 4091 message, the server demonstrates that it knows the private key 4092 corresponding to the server certificate. 4094 When RSA is used for key exchange, clients are authenticated using 4095 the certificate verify message (see Section 7.4.8). The client signs 4096 a value derived from all preceding handshake messages. These 4097 handshake messages include the server certificate, which binds the 4098 signature to the server, and ServerHello.random, which binds the 4099 signature to the current handshake process. 4101 F.1.1.3. Diffie-Hellman Key Exchange with Authentication 4103 When Diffie-Hellman key exchange is used, the server can either 4104 supply a certificate containing fixed Diffie-Hellman parameters or 4105 use the server key exchange message to send a set of temporary 4106 Diffie-Hellman parameters signed with a DSA or RSA certificate. 4107 Temporary parameters are hashed with the hello.random values before 4108 signing to ensure that attackers do not replay old parameters. In 4109 either case, the client can verify the certificate or signature to 4110 ensure that the parameters belong to the server. 4112 If the client has a certificate containing fixed Diffie-Hellman 4113 parameters, its certificate contains the information required to 4114 complete the key exchange. Note that in this case the client and 4115 server will generate the same Diffie-Hellman result (i.e., 4116 pre_master_secret) every time they communicate. To prevent the 4117 pre_master_secret from staying in memory any longer than necessary, 4118 it should be converted into the master_secret as soon as possible. 4119 Client Diffie-Hellman parameters must be compatible with those 4120 supplied by the server for the key exchange to work. 4122 If the client has a standard DSA or RSA certificate or is 4123 unauthenticated, it sends a set of temporary parameters to the server 4124 in the client key exchange message, then optionally uses a 4125 certificate verify message to authenticate itself. 4127 If the same DH keypair is to be used for multiple handshakes, either 4128 because the client or server has a certificate containing a fixed DH 4129 keypair or because the server is reusing DH keys, care must be taken 4130 to prevent small subgroup attacks. Implementations SHOULD follow the 4131 guidelines found in [SUBGROUP]. 4133 Small subgroup attacks are most easily avoided by using one of the 4134 DHE cipher suites and generating a fresh DH private key (X) for each 4135 handshake. If a suitable base (such as 2) is chosen, g^X mod p can be 4136 computed very quickly, therefore the performance cost is minimized. 4137 Additionally, using a fresh key for each handshake provides Perfect 4138 Forward Secrecy. Implementations SHOULD generate a new X for each 4139 handshake when using DHE cipher suites. 4141 Because TLS allows the server to provide arbitrary DH groups, the 4142 client should verify that the DH group is of suitable size as defined 4143 by local policy. The client SHOULD also verify that the DH public 4144 exponent appears to be of adequate size. [KEYSIZ] provides a useful 4145 guide to the strength of various group sizes. The server MAY choose 4146 to assist the client by providing a known group, such as those 4147 defined in [IKEALG] or [MODP]. These can be verified by simple 4148 comparison. 4150 F.1.2. Version Rollback Attacks 4152 Because TLS includes substantial improvements over SSL Version 2.0, 4153 attackers may try to make TLS-capable clients and servers fall back 4154 to Version 2.0. This attack can occur if (and only if) two TLS- 4155 capable parties use an SSL 2.0 handshake. 4157 Although the solution using non-random PKCS #1 block type 2 message 4158 padding is inelegant, it provides a reasonably secure way for Version 4159 3.0 servers to detect the attack. This solution is not secure against 4160 attackers who can brute force the key and substitute a new ENCRYPTED- 4161 KEY-DATA message containing the same key (but with normal padding) 4162 before the application specified wait threshold has expired. Altering 4163 the padding of the least significant 8 bytes of the PKCS padding does 4164 not impact security for the size of the signed hashes and RSA key 4165 lengths used in the protocol, since this is essentially equivalent to 4166 increasing the input block size by 8 bytes. 4168 F.1.3. Detecting Attacks Against the Handshake Protocol 4170 An attacker might try to influence the handshake exchange to make the 4171 parties select different encryption algorithms than they would 4172 normally chooses. 4174 For this attack, an attacker must actively change one or more 4175 handshake messages. If this occurs, the client and server will 4176 compute different values for the handshake message hashes. As a 4177 result, the parties will not accept each others' finished messages. 4178 Without the master_secret, the attacker cannot repair the finished 4179 messages, so the attack will be discovered. 4181 F.1.4. Resuming Sessions 4183 When a connection is established by resuming a session, new 4184 ClientHello.random and ServerHello.random values are hashed with the 4185 session's master_secret. Provided that the master_secret has not been 4186 compromised and that the secure hash operations used to produce the 4187 encryption keys and MAC keys are secure, the connection should be 4188 secure and effectively independent from previous connections. 4189 Attackers cannot use known encryption keys or MAC secrets to 4190 compromise the master_secret without breaking the secure hash 4191 operations. 4193 Sessions cannot be resumed unless both the client and server agree. 4194 If either party suspects that the session may have been compromised, 4195 or that certificates may have expired or been revoked, it should 4196 force a full handshake. An upper limit of 24 hours is suggested for 4197 session ID lifetimes, since an attacker who obtains a master_secret 4198 may be able to impersonate the compromised party until the 4199 corresponding session ID is retired. Applications that may be run in 4200 relatively insecure environments should not write session IDs to 4201 stable storage. 4203 F.2. Protecting Application Data 4205 The master_secret is hashed with the ClientHello.random and 4206 ServerHello.random to produce unique data encryption keys and MAC 4207 secrets for each connection. 4209 Outgoing data is protected with a MAC before transmission. To prevent 4210 message replay or modification attacks, the MAC is computed from the 4211 MAC key, the sequence number, the message length, the message 4212 contents, and two fixed character strings. The message type field is 4213 necessary to ensure that messages intended for one TLS Record Layer 4214 client are not redirected to another. The sequence number ensures 4215 that attempts to delete or reorder messages will be detected. Since 4216 sequence numbers are 64 bits long, they should never overflow. 4217 Messages from one party cannot be inserted into the other's output, 4218 since they use independent MAC keys. Similarly, the server-write and 4219 client-write keys are independent, so stream cipher keys are used 4220 only once. 4222 If an attacker does break an encryption key, all messages encrypted 4223 with it can be read. Similarly, compromise of a MAC key can make 4224 message modification attacks possible. Because MACs are also 4225 encrypted, message-alteration attacks generally require breaking the 4226 encryption algorithm as well as the MAC. 4228 Note: MAC keys may be larger than encryption keys, so messages can 4229 remain tamper resistant even if encryption keys are broken. 4231 F.3. Explicit IVs 4233 [CBCATT] describes a chosen plaintext attack on TLS that depends on 4234 knowing the IV for a record. Previous versions of TLS [TLS1.0] used 4235 the CBC residue of the previous record as the IV and therefore 4236 enabled this attack. This version uses an explicit IV in order to 4237 protect against this attack. 4239 F.4. Security of Composite Cipher Modes 4241 TLS secures transmitted application data via the use of symmetric 4242 encryption and authentication functions defined in the negotiated 4243 cipher suite. The objective is to protect both the integrity and 4244 confidentiality of the transmitted data from malicious actions by 4245 active attackers in the network. It turns out that the order in 4246 which encryption and authentication functions are applied to the data 4247 plays an important role for achieving this goal [ENCAUTH]. 4249 The most robust method, called encrypt-then-authenticate, first 4250 applies encryption to the data and then applies a MAC to the 4251 ciphertext. This method ensures that the integrity and 4252 confidentiality goals are obtained with ANY pair of encryption and 4253 MAC functions, provided that the former is secure against chosen 4254 plaintext attacks and that the MAC is secure against chosen-message 4255 attacks. TLS uses another method, called authenticate-then-encrypt, 4256 in which first a MAC is computed on the plaintext and then the 4257 concatenation of plaintext and MAC is encrypted. This method has 4258 been proven secure for CERTAIN combinations of encryption functions 4259 and MAC functions, but it is not guaranteed to be secure in general. 4260 In particular, it has been shown that there exist perfectly secure 4261 encryption functions (secure even in the information-theoretic sense) 4262 that combined with any secure MAC function, fail to provide the 4263 confidentiality goal against an active attack. Therefore, new cipher 4264 suites and operation modes adopted into TLS need to be analyzed under 4265 the authenticate-then-encrypt method to verify that they achieve the 4266 stated integrity and confidentiality goals. 4268 Currently, the security of the authenticate-then-encrypt method has 4269 been proven for some important cases. One is the case of stream 4270 ciphers in which a computationally unpredictable pad of the length of 4271 the message, plus the length of the MAC tag, is produced using a 4272 pseudo-random generator and this pad is xor-ed with the concatenation 4273 of plaintext and MAC tag. The other is the case of CBC mode using a 4274 secure block cipher. In this case, security can be shown if one 4275 applies one CBC encryption pass to the concatenation of plaintext and 4276 MAC and uses a new, independent, and unpredictable IV for each new 4277 pair of plaintext and MAC. In versions of TLS prior to 1.1, CBC mode 4278 was used properly EXCEPT that it used a predictable IV in the form of 4279 the last block of the previous ciphertext. This made TLS open to 4280 chosen plaintext attacks. This version of the protocol is immune to 4281 those attacks. For exact details in the encryption modes proven 4282 secure, see [ENCAUTH]. 4284 F.5 Denial of Service 4286 TLS is susceptible to a number of denial of service (DoS) attacks. 4287 In particular, an attacker who initiates a large number of TCP 4288 connections can cause a server to consume large amounts of CPU doing 4289 RSA decryption. However, because TLS is generally used over TCP, it 4290 is difficult for the attacker to hide his point of origin if proper 4291 TCP SYN randomization is used [SEQNUM] by the TCP stack. 4293 Because TLS runs over TCP, it is also susceptible to a number of 4294 denial of service attacks on individual connections. In particular, 4295 attackers can forge RSTs, thereby terminating connections, or forge 4296 partial TLS records, thereby causing the connection to stall. These 4297 attacks cannot in general be defended against by a TCP-using 4298 protocol. Implementors or users who are concerned with this class of 4299 attack should use IPsec AH [AH] or ESP [ESP]. 4301 F.6 Final Notes 4303 For TLS to be able to provide a secure connection, both the client 4304 and server systems, keys, and applications must be secure. In 4305 addition, the implementation must be free of security errors. 4307 The system is only as strong as the weakest key exchange and 4308 authentication algorithm supported, and only trustworthy 4309 cryptographic functions should be used. Short public keys and 4310 anonymous servers should be used with great caution. Implementations 4311 and users must be careful when deciding which certificates and 4312 certificate authorities are acceptable; a dishonest certificate 4313 authority can do tremendous damage. 4315 Changes in This Version 4316 [RFC Editor: Please delete this] 4318 Clarified traffic analysis considerations 4320 Added support for SHA-224 for signatures (though not for HMAC). 4322 Consistent use of camelback style for references to messages (e.g., 4323 ServerHelloDone) in the text. 4325 Changed "DSS" to "DSA" where we are referring to the algorithm. 4327 Extensive editorial revisions from Alfred Hoenes. 4329 Normative References 4331 [AES] National Institute of Standards and Technology, 4332 "Specification for the Advanced Encryption Standard (AES)" 4333 FIPS 197. November 26, 2001. 4335 [3DES] National Institute of Standards and Technology, 4336 "Recommendation for the Triple Data Encryption Algorithm 4337 (TDEA) Block Cipher", NIST Special Publication 800-67, May 4338 2004. 4340 [DSS] NIST FIPS PUB 186-2, "Digital Signature Standard", National 4341 Institute of Standards and Technology, U.S. Department of 4342 Commerce, 2000. 4344 [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4345 Hashing for Message Authentication", RFC 2104, February 4346 1997. 4348 [MD5] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321, 4349 April 1992. 4351 [PKCS1] J. Jonsson, B. Kaliski, "Public-Key Cryptography Standards 4352 (PKCS) #1: RSA Cryptography Specifications Version 2.1", RFC 4353 3447, February 2003. 4355 [PKIX] Housley, R., Ford, W., Polk, W. and D. Solo, "Internet X.509 4356 Public Key Infrastructure Certificate and Certificate 4357 Revocation List (CRL) Profile", RFC 3280, April 2002. 4359 [SCH] B. Schneier. "Applied Cryptography: Protocols, Algorithms, 4360 and Source Code in C, 2nd ed.", Published by John Wiley & 4361 Sons, Inc. 1996. 4363 [SHS] NIST FIPS PUB 180-2, "Secure Hash Standard", National 4364 Institute of Standards and Technology, U.S. Department of 4365 Commerce, August 2002. 4367 [REQ] Bradner, S., "Key words for use in RFCs to Indicate 4368 Requirement Levels", BCP 14, RFC 2119, March 1997. 4370 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4371 IANA Considerations Section in RFCs", BCP 25, RFC 2434, 4372 October 1998. 4374 [X680] ITU-T Recommendation X.680 (2002) | ISO/IEC 8824-1:2002, 4375 Information technology - Abstract Syntax Notation One 4376 (ASN.1): Specification of basic notation. 4378 [X690] ITU-T Recommendation X.690 (2002) | ISO/IEC 8825-1:2002, 4379 Information technology - ASN.1 encoding Rules: Specification 4380 of Basic Encoding Rules (BER), Canonical Encoding Rules 4381 (CER) and Distinguished Encoding Rules (DER). 4383 Informative References 4385 [AEAD] Mcgrew, D., "An Interface and Algorithms for Authenticated 4386 Encryption", RFC 5116, January 2008. 4388 [AH] Kent, S., and Atkinson, R., "IP Authentication Header", RFC 4389 4302, December 2005. 4391 [BLEI] Bleichenbacher D., "Chosen Ciphertext Attacks against 4392 Protocols Based on RSA Encryption Standard PKCS #1" in 4393 Advances in Cryptology -- CRYPTO'98, LNCS vol. 1462, pages: 4394 1-12, 1998. 4396 [CBCATT] Moeller, B., "Security of CBC Ciphersuites in SSL/TLS: 4397 Problems and Countermeasures", 4398 http://www.openssl.org/~bodo/tls-cbc.txt. 4400 [CBCTIME] Canvel, B., Hiltgen, A., Vaudenay, S., and M. Vuagnoux, 4401 "Password Interception in a SSL/TLS Channel", Advances in 4402 Cryptology -- CRYPTO 2003, LNCS vol. 2729, 2003. 4404 [CCM] "NIST Special Publication 800-38C: The CCM Mode for 4405 Authentication and Confidentiality", 4406 http://csrc.nist.gov/publications/nistpubs/800-38C/ 4407 SP800-38C.pdf 4409 [DES] National Institute of Standards and Technology, "Data 4410 Encryption Standard (DES)", FIPS PUB 46-3, October 1999. 4412 [DSS-3] NIST FIPS PUB 186-3 Draft, "Digital Signature Standard", 4413 National Institute of Standards and Technology, U.S. 4414 Department of Commerce, 2006. 4416 [ECSDSA] American National Standards Institute, "Public Key 4417 Cryptography for the Financial Services Industry: The 4418 Elliptic Curve Digital Signature Algorithm (ECDSA)", ANS 4419 X9.62-2005, November 2005. 4421 [ENCAUTH] Krawczyk, H., "The Order of Encryption and Authentication 4422 for Protecting Communications (Or: How Secure is SSL?)", 4423 Crypto 2001. 4425 [ESP] Kent, S., and Atkinson, R., "IP Encapsulating Security 4426 Payload (ESP)", RFC 4303, December 2005. 4428 [FI06] Hal Finney, "Bleichenbacher's RSA signature forgery based on 4429 implementation error", ietf-openpgp@imc.org mailing list, 27 4430 August 2006, http://www.imc.org/ietf-openpgp/mail- 4431 archive/msg14307.html. 4433 [GCM] "NIST Special Publication 800-38D DRAFT (June, 2007): 4434 Recommendation for Block Cipher Modes of Operation: 4435 Galois/Counter Mode (GCM) and GMAC" 4437 [IKEALG] Schiller, J., "Cryptographic Algorithms for Use in the 4438 Internet Key Exchange Version 2 (IKEv2)", RFC 4307, December 4439 2005. 4441 [KEYSIZ] Orman, H., and Hoffman, P., "Determining Strengths For 4442 Public Keys Used For Exchanging Symmetric Keys" RFC 3766, 4443 April 2004. 4445 [KPR03] Klima, V., Pokorny, O., Rosa, T., "Attacking RSA-based 4446 Sessions in SSL/TLS", http://eprint.iacr.org/2003/052/, 4447 March 2003. 4449 [MODP] Kivinen, T. and M. Kojo, "More Modular Exponential (MODP) 4450 Diffie-Hellman groups for Internet Key Exchange (IKE)", RFC 4451 3526, May 2003. 4453 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate Syntax 4454 Standard", version 1.5, November 1993. 4456 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message Syntax 4457 Standard", version 1.5, November 1993. 4459 [RANDOM] Eastlake, D., 3rd, Schiller, J., and S. Crocker, "Randomness 4460 Requirements for Security", BCP 106, RFC 4086, June 2005. 4462 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 4463 Compression Methods", RFC 3749, May 2004. 4465 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 4466 Wright, T., "Transport Layer Security (TLS) Extensions", RFC 4467 4366, April 2006. 4469 [RSA] R. Rivest, A. Shamir, and L. M. Adleman, "A Method for 4470 Obtaining Digital Signatures and Public-Key Cryptosystems", 4471 Communications of the ACM, v. 21, n. 2, Feb 1978, pp. 4472 120-126. 4474 [SEQNUM] Bellovin. S., "Defending Against Sequence Number Attacks", 4475 RFC 1948, May 1996. 4477 [SSL2] Hickman, Kipp, "The SSL Protocol", Netscape Communications 4478 Corp., Feb 9, 1995. 4480 [SSL3] A. Freier, P. Karlton, and P. Kocher, "The SSL 3.0 4481 Protocol", Netscape Communications Corp., Nov 18, 1996. 4483 [SUBGROUP] Zuccherato, R., "Methods for Avoiding the "Small-Subgroup" 4484 Attacks on the Diffie-Hellman Key Agreement Method for 4485 S/MIME", RFC 2785, March 2000. 4487 [TCP] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 4488 September 1981. 4490 [TIMING] Boneh, D., Brumley, D., "Remote timing attacks are 4491 practical", USENIX Security Symposium 2003. 4493 [TLSAES] Chown, P., "Advanced Encryption Standard (AES) Ciphersuites 4494 for Transport Layer Security (TLS)", RFC 3268, June 2002. 4496 [TLSECC] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and 4497 Moeller, B., "Elliptic Curve Cryptography (ECC) Cipher 4498 Suites for Transport Layer Security (TLS)", RFC 4492, May 4499 2006. 4501 [TLSEXT] Eastlake, D.E., "Transport Layer Security (TLS) Extensions: 4502 Extension Definitions", January 2008, draft-ietf-tls- 4503 rfc4366-bis-01.txt. 4505 [TLSPGP] Mavrogiannopoulos, N., "Using OpenPGP keys for TLS 4506 authentication", RFC 5081, November 2007. 4508 [TLSPSK] Eronen, P., Tschofenig, H., "Pre-Shared Key Ciphersuites for 4509 Transport Layer Security (TLS)", RFC 4279, December 2005. 4511 [TLS1.0] Dierks, T., and C. Allen, "The TLS Protocol, Version 1.0", 4512 RFC 2246, January 1999. 4514 [TLS1.1] Dierks, T., and E. Rescorla, "The TLS Protocol, Version 4515 1.1", RFC 4346, April, 2006. 4517 [X501] ITU-T Recommendation X.501: Information Technology - Open 4518 Systems Interconnection - The Directory: Models, 1993. 4520 [XDR] Eisler, M., "External Data Representation Standard", STD 67, 4521 RFC 4506, May 2006. 4523 Credits 4525 Working Group Chairs 4527 Eric Rescorla 4528 EMail: ekr@networkresonance.com 4530 Pasi Eronen 4531 pasi.eronen@nokia.com 4533 Editors 4535 Tim Dierks Eric Rescorla 4536 Independent Network Resonance, Inc. 4537 EMail: tim@dierks.org EMail: ekr@networkresonance.com 4539 Other contributors 4541 Christopher Allen (co-editor of TLS 1.0) 4542 Alacrity Ventures 4543 ChristopherA@AlacrityManagement.com 4545 Martin Abadi 4546 University of California, Santa Cruz 4547 abadi@cs.ucsc.edu 4549 Steven M. Bellovin 4550 Columbia University 4551 smb@cs.columbia.edu 4553 Simon Blake-Wilson 4554 BCI 4555 EMail: sblakewilson@bcisse.com 4557 Ran Canetti 4558 IBM 4559 canetti@watson.ibm.com 4561 Pete Chown 4562 Skygate Technology Ltd 4563 pc@skygate.co.uk 4565 Taher Elgamal 4566 taher@securify.com 4567 Securify 4569 Pasi Eronen 4570 pasi.eronen@nokia.com 4571 Nokia 4573 Anil Gangolli 4574 anil@busybuddha.org 4576 Kipp Hickman 4578 Alfred Hoenes 4580 David Hopwood 4581 Independent Consultant 4582 EMail: david.hopwood@blueyonder.co.uk 4584 Phil Karlton (co-author of SSLv3) 4586 Paul Kocher (co-author of SSLv3) 4587 Cryptography Research 4588 paul@cryptography.com 4590 Hugo Krawczyk 4591 IBM 4592 hugo@ee.technion.ac.il 4594 Jan Mikkelsen 4595 Transactionware 4596 EMail: janm@transactionware.com 4598 Magnus Nystrom 4599 RSA Security 4600 EMail: magnus@rsasecurity.com 4602 Robert Relyea 4603 Netscape Communications 4604 relyea@netscape.com 4606 Jim Roskind 4607 Netscape Communications 4608 jar@netscape.com 4610 Michael Sabin 4612 Dan Simon 4613 Microsoft, Inc. 4614 dansimon@microsoft.com 4616 Tom Weinstein 4618 Tim Wright 4619 Vodafone 4620 EMail: timothy.wright@vodafone.com 4622 Comments 4624 The discussion list for the IETF TLS working group is located at the 4625 e-mail address . Information on the group and 4626 information on how to subscribe to the list is at 4627 4629 Archives of the list can be found at: 4630 4632 Full Copyright Statement 4634 Copyright (C) The IETF Trust (2008). 4636 This document is subject to the rights, licenses and restrictions 4637 contained in BCP 78, and except as set forth therein, the authors 4638 retain all their rights. 4640 This document and the information contained herein are provided on an 4641 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4642 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4643 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4644 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4645 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4646 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4648 Intellectual Property 4650 The IETF takes no position regarding the validity or scope of any 4651 Intellectual Property Rights or other rights that might be claimed to 4652 pertain to the implementation or use of the technology described in 4653 this document or the extent to which any license under such rights 4654 might or might not be available; nor does it represent that it has 4655 made any independent effort to identify any such rights. Information 4656 on the procedures with respect to rights in RFC documents can be 4657 found in BCP 78 and BCP 79. 4659 Copies of IPR disclosures made to the IETF Secretariat and any 4660 assurances of licenses to be made available, or the result of an 4661 attempt made to obtain a general license or permission for the use of 4662 such proprietary rights by implementers or users of this 4663 specification can be obtained from the IETF on-line IPR repository at 4664 http://www.ietf.org/ipr. 4666 The IETF invites any interested party to bring to its attention any 4667 copyrights, patents or patent applications, or other proprietary 4668 rights that may cover technology that may be required to implement 4669 this standard. Please address the information to the IETF at 4670 ietf-ipr@ietf.org. 4672 Acknowledgment 4674 Funding for the RFC Editor function is provided by the IETF 4675 Administrative Support Activity (IASA).