idnits 2.17.1 draft-ietf-tls-rfc4346-bis-08.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 4631. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4642. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4649. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4655. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 23 instances of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 765 has weird spacing: '...gorithm bul...' == Line 2385 has weird spacing: '...ixed_dh a c...' == Line 2386 has weird spacing: '...ixed_dh a c...' == Line 2524 has weird spacing: '...ed_ecdh the...' == Line 3437 has weird spacing: '...gorithm bul...' == (1 more instance...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a TLS connection during the first handshake on that channel, but MUST not be negotiated, as it provides no more protection than an unsecured connection. -- 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 318 -- Looks like a reference, but probably isn't: '1' on line 318 -- Looks like a reference, but probably isn't: '3' on line 3923 -- Looks like a reference, but probably isn't: '9' on line 354 -- Looks like a reference, but probably isn't: '2' on line 3112 -- Looks like a reference, but probably isn't: '4' on line 390 -- Looks like a reference, but probably isn't: '8' on line 391 -- Looks like a reference, but probably isn't: '10' on line 491 -- Looks like a reference, but probably isn't: '20' on line 577 -- Looks like a reference, but probably isn't: '48' on line 3447 -- Looks like a reference, but probably isn't: '32' on line 3449 == Missing Reference: 'ChangeCipherSpec' is mentioned on line 1647, but not defined -- Looks like a reference, but probably isn't: '28' on line 3108 == Missing Reference: '4366bis' is mentioned on line 2194, but not defined -- Looks like a reference, but probably isn't: '46' on line 3243 -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. '3DES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DES' -- 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. 'SHA' ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) == Outdated reference: A later version (-05) exists of draft-mcgrew-auth-enc-02 -- 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-00 -- Obsolete informational reference (is this intentional?): RFC 5081 (ref. 'TLSPGP') (Obsoleted by RFC 6091) Summary: 7 errors (**), 0 flaws (~~), 12 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 January 2008 (Expires July 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 6 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 13 64 6. The TLS Record Protocol 14 65 6.1. Connection States 15 66 6.2. Record layer 18 67 6.2.1. Fragmentation 18 68 6.2.2. Record Compression and Decompression 19 69 6.2.3. Record Payload Protection 20 70 6.2.3.1. Null or Standard Stream Cipher 21 71 6.2.3.2. CBC Block Cipher 21 72 6.2.3.3. AEAD ciphers 23 73 6.3. Key Calculation 24 74 7. The TLS Handshaking Protocols 25 75 7.1. Change Cipher Spec Protocol 26 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 32 80 7.4. Handshake Protocol 35 81 7.4.1. Hello Messages 36 82 7.4.1.1. Hello Request 36 83 7.4.1.2. Client Hello 37 84 7.4.1.3. Server Hello 40 85 7.4.1.4 Hello Extensions 42 86 7.4.1.4.1 Signature Algorithms 43 87 7.4.2. Server Certificate 45 88 7.4.3. Server Key Exchange Message 47 89 7.4.4. Certificate Request 50 90 7.4.5 Server hello done 52 91 7.4.6. Client Certificate 52 92 7.4.7. Client Key Exchange Message 54 93 7.4.7.1. RSA Encrypted Premaster Secret Message 54 94 7.4.7.2. Client Diffie-Hellman Public Value 57 95 7.4.8. Certificate verify 57 96 7.4.9. Finished 58 97 8. Cryptographic Computations 60 98 8.1. Computing the Master Secret 60 99 8.1.1. RSA 61 100 8.1.2. Diffie-Hellman 61 101 9. Mandatory Cipher Suites 61 102 10. Application Data Protocol 61 103 11. Security Considerations 61 104 12. IANA Considerations 61 105 A. Protocol Constant Values 64 106 A.1. Record Layer 64 107 A.2. Change Cipher Specs Message 65 108 A.3. Alert Messages 65 109 A.4. Handshake Protocol 66 110 A.4.1. Hello Messages 66 111 A.4.2. Server Authentication and Key Exchange Messages 68 112 A.4.3. Client Authentication and Key Exchange Messages 69 113 A.4.4. Handshake Finalization Message 70 114 A.5. The Cipher Suite 70 115 A.6. The Security Parameters 73 116 B. Glossary 75 117 C. Cipher Suite Definitions 79 118 D. Implementation Notes 81 119 D.1 Random Number Generation and Seeding 81 120 D.2 Certificates and Authentication 81 121 D.3 Cipher Suites 81 122 D.4 Implementation Pitfalls 81 123 E. Backward Compatibility 84 124 E.1 Compatibility with TLS 1.0/1.1 and SSL 3.0 84 125 E.2 Compatibility with SSL 2.0 85 126 E.3. Avoiding Man-in-the-Middle Version Rollback 87 127 F. Security Analysis 88 128 F.1. Handshake Protocol 88 129 F.1.1. Authentication and Key Exchange 88 130 F.1.1.1. Anonymous Key Exchange 88 131 F.1.1.2. RSA Key Exchange and Authentication 89 132 F.1.1.3. Diffie-Hellman Key Exchange with Authentication 89 133 F.1.2. Version Rollback Attacks 90 134 F.1.3. Detecting Attacks Against the Handshake Protocol 91 135 F.1.4. Resuming Sessions 91 136 F.2. Protecting Application Data 91 137 F.3. Explicit IVs 92 138 F.4. Security of Composite Cipher Modes 92 139 F.5 Denial of Service 93 140 F.6 Final Notes 93 142 1. Introduction 144 The primary goal of the TLS Protocol is to provide privacy and data 145 integrity between two communicating applications. The protocol is 146 composed of two layers: the TLS Record Protocol and the TLS Handshake 147 Protocol. At the lowest level, layered on top of some reliable 148 transport protocol (e.g., TCP[TCP]), is the TLS Record Protocol. The 149 TLS Record Protocol provides connection security that has two basic 150 properties: 152 - The connection is private. Symmetric cryptography is used for 153 data encryption (e.g., DES [DES], RC4 [SCH] etc.). The keys for 154 this symmetric encryption are generated uniquely for each 155 connection and are based on a secret negotiated by another 156 protocol (such as the TLS Handshake Protocol). The Record Protocol 157 can also be used without encryption. 159 - The connection is reliable. Message transport includes a message 160 integrity check using a keyed MAC. Secure hash functions (e.g., 161 SHA, MD5, etc.) are used for MAC computations. The Record Protocol 162 can operate without a MAC, but is generally only used in this mode 163 while another protocol is using the Record Protocol as a transport 164 for negotiating security parameters. 166 The TLS Record Protocol is used for encapsulation of various higher- 167 level protocols. One such encapsulated protocol, the TLS Handshake 168 Protocol, allows the server and client to authenticate each other and 169 to negotiate an encryption algorithm and cryptographic keys before 170 the application protocol transmits or receives its first byte of 171 data. The TLS Handshake Protocol provides connection security that 172 has three basic properties: 174 - The peer's identity can be authenticated using asymmetric, or 175 public key, cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 176 authentication can be made optional, but is generally required for 177 at least one of the peers. 179 - The negotiation of a shared secret is secure: the negotiated 180 secret is unavailable to eavesdroppers, and for any authenticated 181 connection the secret cannot be obtained, even by an attacker who 182 can place himself in the middle of the connection. 184 - The negotiation is reliable: no attacker can modify the 185 negotiation communication without being detected by the parties to 186 the communication. 188 One advantage of TLS is that it is application protocol independent. 189 Higher-level protocols can layer on top of the TLS Protocol 190 transparently. The TLS standard, however, does not specify how 191 protocols add security with TLS; the decisions on how to initiate TLS 192 handshaking and how to interpret the authentication certificates 193 exchanged are left to the judgment of the designers and implementors 194 of protocols that run on top of TLS. 196 1.1. Requirements Terminology 198 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 199 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 200 document are to be interpreted as described in RFC 2119 [REQ]. 202 1.2. Major Differences from TLS 1.1 204 This document is a revision of the TLS 1.1 [TLS1.1] protocol which 205 contains improved flexibility, particularly for negotiation of 206 cryptographic algorithms. The major changes are: 208 - The MD5/SHA-1 combination in the PRF has been replaced with cipher 209 suite specified PRFs. All cipher suites in this document use 210 P_SHA256. 212 - The MD5/SHA-1 combination in the digitally-signed element has been 213 replaced with a single hash. 215 - Substantial cleanup to the clients and servers ability to specify 216 which hash and signature algorithms they will accept. Note that 217 this also relaxes some of the constraints on signature and hash 218 algorithms from previous versions of TLS. 220 - Addition of support for authenticated encryption with additional 221 data modes. 223 - TLS Extensions definition and AES Cipher Suites were merged in 224 from external [TLSEXT] and [TLSAES]. 226 - Tighter checking of EncryptedPreMasterSecret version numbers. 228 - Tightened up a number of requirements. 230 - Verify_data length now depends on the cipher suite (default is 231 still 12). 233 - Cleaned up description of Bleichenbacher/Klima attack defenses. 235 - Alerts MUST now be sent in many cases. 236 - After a certificate_request, if no certificates are available, 237 clients now MUST send an empty certificate list. 239 - TLS_RSA_WITH_AES_128_CBC_SHA is now the mandatory to implement 240 cipher suite. 242 - Added HMAC-SHA256 cipher suites 244 - IDEA and DES are now deprecated. 246 - Support for the SSLv2 backward-compatible hello is now a MAY, not 247 a SHOULD. This will probably become a SHOULD NOT in the future. 249 - Added an Implementation Pitfalls sections 251 - The usual clarifications and editorial work. 252 2. Goals 254 The goals of TLS Protocol, in order of their priority, are as 255 follows: 257 1. Cryptographic security: TLS should be used to establish a secure 258 connection between two parties. 260 2. Interoperability: Independent programmers should be able to 261 develop applications utilizing TLS that can successfully exchange 262 cryptographic parameters without knowledge of one another's code. 264 3. Extensibility: TLS seeks to provide a framework into which new 265 public key and bulk encryption methods can be incorporated as 266 necessary. This will also accomplish two sub-goals: preventing the 267 need to create a new protocol (and risking the introduction of 268 possible new weaknesses) and avoiding the need to implement an 269 entire new security library. 271 4. Relative efficiency: Cryptographic operations tend to be highly 272 CPU intensive, particularly public key operations. For this 273 reason, the TLS protocol has incorporated an optional session 274 caching scheme to reduce the number of connections that need to be 275 established from scratch. Additionally, care has been taken to 276 reduce network activity. 278 3. Goals of This Document 280 This document and the TLS protocol itself are based on the SSL 3.0 281 Protocol Specification as published by Netscape. The differences 282 between this protocol and SSL 3.0 are not dramatic, but they are 283 significant enough that the various versions of TLS and SSL 3.0 do 284 not interoperate (although each protocol incorporates a mechanism by 285 which an implementation can back down to prior versions). This 286 document is intended primarily for readers who will be implementing 287 the protocol and for those doing cryptographic analysis of it. The 288 specification has been written with this in mind, and it is intended 289 to reflect the needs of those two groups. For that reason, many of 290 the algorithm-dependent data structures and rules are included in the 291 body of the text (as opposed to in an appendix), providing easier 292 access to them. 294 This document is not intended to supply any details of service 295 definition or of interface definition, although it does cover select 296 areas of policy as they are required for the maintenance of solid 297 security. 299 4. Presentation Language 301 This document deals with the formatting of data in an external 302 representation. The following very basic and somewhat casually 303 defined presentation syntax will be used. The syntax draws from 304 several sources in its structure. Although it resembles the 305 programming language "C" in its syntax and XDR [XDR] in both its 306 syntax and intent, it would be risky to draw too many parallels. The 307 purpose of this presentation language is to document TLS only; it has 308 no general application beyond that particular goal. 310 4.1. Basic Block Size 312 The representation of all data items is explicitly specified. The 313 basic data block size is one byte (i.e., 8 bits). Multiple byte data 314 items are concatenations of bytes, from left to right, from top to 315 bottom. From the bytestream, a multi-byte item (a numeric in the 316 example) is formed (using C notation) by: 318 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 319 ... | byte[n-1]; 321 This byte ordering for multi-byte values is the commonplace network 322 byte order or big endian format. 324 4.2. Miscellaneous 326 Comments begin with "/*" and end with "*/". 328 Optional components are denoted by enclosing them in "[[ ]]" double 329 brackets. 331 Single-byte entities containing uninterpreted data are of type 332 opaque. 334 4.3. Vectors 336 A vector (single dimensioned array) is a stream of homogeneous data 337 elements. The size of the vector may be specified at documentation 338 time or left unspecified until runtime. In either case, the length 339 declares the number of bytes, not the number of elements, in the 340 vector. The syntax for specifying a new type, T', that is a fixed- 341 length vector of type T is 343 T T'[n]; 345 Here, T' occupies n bytes in the data stream, where n is a multiple 346 of the size of T. The length of the vector is not included in the 347 encoded stream. 349 In the following example, Datum is defined to be three consecutive 350 bytes that the protocol does not interpret, while Data is three 351 consecutive Datum, consuming a total of nine bytes. 353 opaque Datum[3]; /* three uninterpreted bytes */ 354 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 356 Variable-length vectors are defined by specifying a subrange of legal 357 lengths, inclusively, using the notation . When 358 these are encoded, the actual length precedes the vector's contents 359 in the byte stream. The length will be in the form of a number 360 consuming as many bytes as required to hold the vector's specified 361 maximum (ceiling) length. A variable-length vector with an actual 362 length field of zero is referred to as an empty vector. 364 T T'; 366 In the following example, mandatory is a vector that must contain 367 between 300 and 400 bytes of type opaque. It can never be empty. The 368 actual length field consumes two bytes, a uint16, sufficient to 369 represent the value 400 (see Section 4.4). On the other hand, longer 370 can represent up to 800 bytes of data, or 400 uint16 elements, and it 371 may be empty. Its encoding will include a two-byte actual length 372 field prepended to the vector. The length of an encoded vector must 373 be an even multiple of the length of a single element (for example, a 374 17-byte vector of uint16 would be illegal). 376 opaque mandatory<300..400>; 377 /* length field is 2 bytes, cannot be empty */ 378 uint16 longer<0..800>; 379 /* zero to 400 16-bit unsigned integers */ 381 4.4. Numbers 383 The basic numeric data type is an unsigned byte (uint8). All larger 384 numeric data types are formed from fixed-length series of bytes 385 concatenated as described in Section 4.1 and are also unsigned. The 386 following numeric types are predefined. 388 uint8 uint16[2]; 389 uint8 uint24[3]; 390 uint8 uint32[4]; 391 uint8 uint64[8]; 393 All values, here and elsewhere in the specification, are stored in 394 "network" or "big-endian" order; the uint32 represented by the hex 395 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 397 Note that in some cases (e.g., DH parameters) it is necessary to 398 represent integers as opaque vectors. In such cases, they are 399 represented as unsigned integers (i.e., leading zero octets are not 400 required even if the most significant bit is set). 402 4.5. Enumerateds 404 An additional sparse data type is available called enum. A field of 405 type enum can only assume the values declared in the definition. 406 Each definition is a different type. Only enumerateds of the same 407 type may be assigned or compared. Every element of an enumerated must 408 be assigned a value, as demonstrated in the following example. Since 409 the elements of the enumerated are not ordered, they can be assigned 410 any unique value, in any order. 412 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 414 Enumerateds occupy as much space in the byte stream as would its 415 maximal defined ordinal value. The following definition would cause 416 one byte to be used to carry fields of type Color. 418 enum { red(3), blue(5), white(7) } Color; 420 One may optionally specify a value without its associated tag to 421 force the width definition without defining a superfluous element. 422 In the following example, Taste will consume two bytes in the data 423 stream but can only assume the values 1, 2, or 4. 425 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 427 The names of the elements of an enumeration are scoped within the 428 defined type. In the first example, a fully qualified reference to 429 the second element of the enumeration would be Color.blue. Such 430 qualification is not required if the target of the assignment is well 431 specified. 433 Color color = Color.blue; /* overspecified, legal */ 434 Color color = blue; /* correct, type implicit */ 436 For enumerateds that are never converted to external representation, 437 the numerical information may be omitted. 439 enum { low, medium, high } Amount; 441 4.6. Constructed Types 443 Structure types may be constructed from primitive types for 444 convenience. Each specification declares a new, unique type. The 445 syntax for definition is much like that of C. 447 struct { 448 T1 f1; 449 T2 f2; 450 ... 451 Tn fn; 452 } [[T]]; 454 The fields within a structure may be qualified using the type's name, 455 with a syntax much like that available for enumerateds. For example, 456 T.f2 refers to the second field of the previous declaration. 457 Structure definitions may be embedded. 459 4.6.1. Variants 461 Defined structures may have variants based on some knowledge that is 462 available within the environment. The selector must be an enumerated 463 type that defines the possible variants the structure defines. There 464 must be a case arm for every element of the enumeration declared in 465 the select. The body of the variant structure may be given a label 466 for reference. The mechanism by which the variant is selected at 467 runtime is not prescribed by the presentation language. 469 struct { 470 T1 f1; 471 T2 f2; 472 .... 473 Tn fn; 474 select (E) { 475 case e1: Te1; 476 case e2: Te2; 477 .... 478 case en: Ten; 479 } [[fv]]; 480 } [[Tv]]; 482 For example: 484 enum { apple, orange } VariantTag; 485 struct { 486 uint16 number; 487 opaque string<0..10>; /* variable length */ 488 } V1; 489 struct { 490 uint32 number; 491 opaque string[10]; /* fixed length */ 492 } V2; 493 struct { 494 select (VariantTag) { /* value of selector is implicit */ 495 case apple: V1; /* VariantBody, tag = apple */ 496 case orange: V2; /* VariantBody, tag = orange */ 497 } variant_body; /* optional label on variant */ 498 } VariantRecord; 500 Variant structures may be qualified (narrowed) by specifying a value 501 for the selector prior to the type. For example, an 503 orange VariantRecord 505 is a narrowed type of a VariantRecord containing a variant_body of 506 type V2. 508 4.7. Cryptographic Attributes 510 The five cryptographic operations digital signing, stream cipher 511 encryption, block cipher encryption, authenticated encryption with 512 additional data (AEAD) encryption and public key encryption are 513 designated digitally-signed, stream-ciphered, block-ciphered, aead- 514 ciphered, and public-key-encrypted, respectively. A field's 515 cryptographic processing is specified by prepending an appropriate 516 key word designation before the field's type specification. 517 Cryptographic keys are implied by the current session state (see 518 Section 6.1). 520 In digital signing, one-way hash functions are used as input for a 521 signing algorithm. A digitally-signed element is encoded as an opaque 522 vector <0..2^16-1>, where the length is specified by the signing 523 algorithm and key. 525 In RSA signing, the opaque vector contains the signature generated 526 using the RSASSA-PKCS1-v1_5 signature scheme defined in [PKCS1]. As 527 discussed in [PKCS1], the DigestInfo MUST be DER encoded and for hash 528 algorithms without parameters (which include SHA-1) the 529 DigestInfo.AlgorithmIdentifier.parameters field MUST be NULL but 530 implementations MUST accept both without parameters and with NULL 531 parameters. Note that earlier versions of TLS used a different RSA 532 signature scheme which did not include a DigestInfo encoding. 534 In DSS, the 20 bytes of the SHA-1 hash are run directly through the 535 Digital Signing Algorithm with no additional hashing. This produces 536 two values, r and s. The DSS signature is an opaque vector, as above, 537 the contents of which are the DER encoding of: 539 Dss-Sig-Value ::= SEQUENCE { 540 r INTEGER, 541 s INTEGER 542 } 544 Note: In current terminology, DSA refers to the Digital Signature 545 Algorithm and DSS refers to the NIST standard. For historical 546 reasons, this document uses DSS and DSA interchangeably 547 to refer to the DSA algorithm, as was done in SSLv3. 549 In stream cipher encryption, the plaintext is exclusive-ORed with an 550 identical amount of output generated from a cryptographically secure 551 keyed pseudorandom number generator. 553 In block cipher encryption, every block of plaintext encrypts to a 554 block of ciphertext. All block cipher encryption is done in CBC 555 (Cipher Block Chaining) mode, and all items that are block-ciphered 556 will be an exact multiple of the cipher block length. 558 In AEAD encryption, the plaintext is simultaneously encrypted and 559 integrity protected. The input may be of any length and aead-ciphered 560 output is generally larger than the input in order to accomodate the 561 integrity check value. 563 In public key encryption, a public key algorithm is used to encrypt 564 data in such a way that it can be decrypted only with the matching 565 private key. A public-key-encrypted element is encoded as an opaque 566 vector <0..2^16-1>, where the length is specified by the encryption 567 algorithm and key. 569 RSA encryption is done using the RSAES-PKCS1-v1_5 encryption scheme 570 defined in [PKCS1]. 572 In the following example 574 stream-ciphered struct { 575 uint8 field1; 576 uint8 field2; 577 digitally-signed opaque hash[20]; 578 } UserType; 580 the contents of hash are used as input for the signing algorithm, and 581 then the entire structure is encrypted with a stream cipher. The 582 length of this structure, in bytes, would be equal to two bytes for 583 field1 and field2, plus two bytes for the length of the signature, 584 plus the length of the output of the signing algorithm. This is known 585 because the algorithm and key used for the signing are known prior to 586 encoding or decoding this structure. 588 4.8. Constants 590 Typed constants can be defined for purposes of specification by 591 declaring a symbol of the desired type and assigning values to it. 592 Under-specified types (opaque, variable length vectors, and 593 structures that contain opaque) cannot be assigned values. No fields 594 of a multi-element structure or vector may be elided. 596 For example: 598 struct { 599 uint8 f1; 600 uint8 f2; 601 } Example1; 603 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 605 5. HMAC and the Pseudorandom Function 607 The TLS record layer uses a keyed Message Authentication Code (MAC) 608 to protect message integrity. The cipher suites defined in this 609 document use a construction known as HMAC, described in [HMAC], which 610 is based on a hash function. Other cipher suites MAY define their own 611 MAC constructions, if needed. 613 In addition, a construction is required to do expansion of secrets 614 into blocks of data for the purposes of key generation or validation. 615 This pseudo-random function (PRF) takes as input a secret, a seed, 616 and an identifying label and produces an output of arbitrary length. 618 In this section, we define one PRF, based on HMAC. This PRF with the 619 SHA-256 hash function is used for all cipher suites defined in this 620 document and in TLS documents published prior to this document when 621 TLS 1.2 is negotiated. New cipher suites MUST explicitly specify a 622 PRF and in general SHOULD use the TLS PRF with SHA-256 or a stronger 623 standard hash function. 625 First, we define a data expansion function, P_hash(secret, data) that 626 uses a single hash function to expand a secret and seed into an 627 arbitrary quantity of output: 629 P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) + 630 HMAC_hash(secret, A(2) + seed) + 631 HMAC_hash(secret, A(3) + seed) + ... 633 Where + indicates concatenation. 635 A() is defined as: 637 A(0) = seed 638 A(i) = HMAC_hash(secret, A(i-1)) 640 P_hash can be iterated as many times as is necessary to produce the 641 required quantity of data. For example, if P_SHA256 is being used to 642 create 80 bytes of data, it will have to be iterated three times 643 (through A(3)), creating 96 bytes of output data; the last 16 bytes 644 of the final iteration will then be discarded, leaving 80 bytes of 645 output data. 647 TLS's PRF is created by applying P_hash to the secret as: 649 PRF(secret, label, seed) = P_(secret, label + seed) 651 The label is an ASCII string. It should be included in the exact form 652 it is given without a length byte or trailing null character. For 653 example, the label "slithy toves" would be processed by hashing the 654 following bytes: 656 73 6C 69 74 68 79 20 74 6F 76 65 73 658 6. The TLS Record Protocol 660 The TLS Record Protocol is a layered protocol. At each layer, 661 messages may include fields for length, description, and content. 662 The Record Protocol takes messages to be transmitted, fragments the 663 data into manageable blocks, optionally compresses the data, applies 664 a MAC, encrypts, and transmits the result. Received data is 665 decrypted, verified, decompressed, reassembled, and then delivered to 666 higher-level clients. 668 Four record protocol clients are described in this document: the 669 handshake protocol, the alert protocol, the change cipher spec 670 protocol, and the application data protocol. In order to allow 671 extension of the TLS protocol, additional record types can be 672 supported by the record protocol. New record type values are assigned 673 by IANA as described in Section 12. 675 Implementations MUST NOT send record types not defined in this 676 document unless negotiated by some extension. If a TLS 677 implementation receives an unexpected record type, it MUST send an 678 unexpected_message alert. 680 Any protocol designed for use over TLS MUST be carefully designed to 681 deal with all possible attacks against it. Note that because the 682 type and length of a record are not protected by encryption, care 683 SHOULD be taken to minimize the value of traffic analysis of these 684 values. 686 6.1. Connection States 688 A TLS connection state is the operating environment of the TLS Record 689 Protocol. It specifies a compression algorithm, an encryption 690 algorithm, and a MAC algorithm. In addition, the parameters for these 691 algorithms are known: the MAC key and the bulk encryption keys for 692 the connection in both the read and the write directions. Logically, 693 there are always four connection states outstanding: the current read 694 and write states, and the pending read and write states. All records 695 are processed under the current read and write states. The security 696 parameters for the pending states can be set by the TLS Handshake 697 Protocol, and the Change Cipher Spec can selectively make either of 698 the pending states current, in which case the appropriate current 699 state is disposed of and replaced with the pending state; the pending 700 state is then reinitialized to an empty state. It is illegal to make 701 a state that has not been initialized with security parameters a 702 current state. The initial current state always specifies that no 703 encryption, compression, or MAC will be used. 705 The security parameters for a TLS Connection read and write state are 706 set by providing the following values: 708 connection end 709 Whether this entity is considered the "client" or the "server" in 710 this connection. 712 PRF algorithm 713 An algorithm used to generate keys from the master secret (see 714 Sections 5 and 6.3). 716 bulk encryption algorithm 717 An algorithm to be used for bulk encryption. This specification 718 includes the key size of this algorithm, whether it is a block, 719 stream, or AEAD cipher, the block size of the cipher (if 720 appropriate), and the lengths of explicit and implicit 721 initialization vectors (or nonces). 723 MAC algorithm 724 An algorithm to be used for message authentication. This 725 specification includes the size of the value returned by the MAC 726 algorithm. 728 compression algorithm 729 An algorithm to be used for data compression. This specification 730 must include all information the algorithm requires to do 731 compression. 733 master secret 734 A 48-byte secret shared between the two peers in the connection. 736 client random 737 A 32-byte value provided by the client. 739 server random 740 A 32-byte value provided by the server. 742 These parameters are defined in the presentation language as: 744 enum { server, client } ConnectionEnd; 746 enum { tls_prf_sha256 } PRFAlgorithm; 748 enum { null, rc4, 3des, aes } 749 BulkCipherAlgorithm; 751 enum { stream, block, aead } CipherType; 753 enum { null, hmac_md5, hmac_sha, hmac_sha256, hmac_sha384, 754 hmac_sha512} MACAlgorithm; 756 /* The use of "sha" above is historical and denotes SHA-1 */ 758 enum { null(0), (255) } CompressionMethod; 759 /* The algorithms specified in CompressionMethod, 760 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 762 struct { 763 ConnectionEnd entity; 764 PRFAlgorithm prf_algorithm; 765 BulkCipherAlgorithm bulk_cipher_algorithm; 766 CipherType cipher_type; 767 uint8 enc_key_length; 768 uint8 block_length; 769 uint8 fixed_iv_length; 770 uint8 record_iv_length; 771 MACAlgorithm mac_algorithm; 772 uint8 mac_length; 773 uint8 mac_key_length; 774 CompressionMethod compression_algorithm; 775 opaque master_secret[48]; 776 opaque client_random[32]; 777 opaque server_random[32]; 778 } SecurityParameters; 780 The record layer will use the security parameters to generate the 781 following six items (some of which are not required by all ciphers, 782 and are thus empty): 784 client write MAC key 785 server write MAC key 786 client write encryption key 787 server write encryption key 788 client write IV 789 server write IV 791 The client write parameters are used by the server when receiving and 792 processing records and vice-versa. The algorithm used for generating 793 these items from the security parameters is described in Section 6.3. 795 Once the security parameters have been set and the keys have been 796 generated, the connection states can be instantiated by making them 797 the current states. These current states MUST be updated for each 798 record processed. Each connection state includes the following 799 elements: 801 compression state 802 The current state of the compression algorithm. 804 cipher state 805 The current state of the encryption algorithm. This will consist 806 of the scheduled key for that connection. For stream ciphers, this 807 will also contain whatever state information is necessary to allow 808 the stream to continue to encrypt or decrypt data. 810 MAC key 811 The MAC key for this connection, as generated above. 813 sequence number 814 Each connection state contains a sequence number, which is 815 maintained separately for read and write states. The sequence 816 number MUST be set to zero whenever a connection state is made the 817 active state. Sequence numbers are of type uint64 and may not 818 exceed 2^64-1. Sequence numbers do not wrap. If a TLS 819 implementation would need to wrap a sequence number, it must 820 renegotiate instead. A sequence number is incremented after each 821 record: specifically, the first record transmitted under a 822 particular connection state MUST use sequence number 0. 824 6.2. Record layer 826 The TLS Record Layer receives uninterpreted data from higher layers 827 in non-empty blocks of arbitrary size. 829 6.2.1. Fragmentation 831 The record layer fragments information blocks into TLSPlaintext 832 records carrying data in chunks of 2^14 bytes or less. Client message 833 boundaries are not preserved in the record layer (i.e., multiple 834 client messages of the same ContentType MAY be coalesced into a 835 single TLSPlaintext record, or a single message MAY be fragmented 836 across several records). 838 struct { 839 uint8 major; 840 uint8 minor; 841 } ProtocolVersion; 843 enum { 844 change_cipher_spec(20), alert(21), handshake(22), 845 application_data(23), (255) 846 } ContentType; 848 struct { 849 ContentType type; 850 ProtocolVersion version; 851 uint16 length; 852 opaque fragment[TLSPlaintext.length]; 853 } TLSPlaintext; 855 type 856 The higher-level protocol used to process the enclosed fragment. 858 version 859 The version of the protocol being employed. This document 860 describes TLS Version 1.2, which uses the version { 3, 3 }. The 861 version value 3.3 is historical, deriving from the use of 3.1 for 862 TLS 1.0. (See Appendix A.1). Note that a client that supports 863 multiple versions of TLS may not know what version will be 864 employed before it receives ServerHello. See Appendix E for 865 discussion about what record layer version number should be 866 employed for ClientHello. 868 length 869 The length (in bytes) of the following TLSPlaintext.fragment. The 870 length MUST NOT exceed 2^14. 872 fragment 873 The application data. This data is transparent and treated as an 874 independent block to be dealt with by the higher-level protocol 875 specified by the type field. 877 Implementations MUST NOT send zero-length fragments of Handshake, 878 Alert, or Change Cipher Spec content types. Zero-length fragments of 879 Application data MAY be sent as they are potentially useful as a 880 traffic analysis countermeasure. 882 Note: Data of different TLS Record layer content types MAY be 883 interleaved. Application data is generally of lower precedence for 884 transmission than other content types. However, records MUST be 885 delivered to the network in the same order as they are protected by 886 the record layer. Recipients MUST receive and process interleaved 887 application layer traffic during handshakes subsequent to the first 888 one on a connection. 890 6.2.2. Record Compression and Decompression 892 All records are compressed using the compression algorithm defined in 893 the current session state. There is always an active compression 894 algorithm; however, initially it is defined as 895 CompressionMethod.null. The compression algorithm translates a 896 TLSPlaintext structure into a TLSCompressed structure. Compression 897 functions are initialized with default state information whenever a 898 connection state is made active. 900 Compression must be lossless and may not increase the content length 901 by more than 1024 bytes. If the decompression function encounters a 902 TLSCompressed.fragment that would decompress to a length in excess of 903 2^14 bytes, it MUST report a fatal decompression failure error. 905 struct { 906 ContentType type; /* same as TLSPlaintext.type */ 907 ProtocolVersion version;/* same as TLSPlaintext.version */ 908 uint16 length; 909 opaque fragment[TLSCompressed.length]; 910 } TLSCompressed; 912 length 913 The length (in bytes) of the following TLSCompressed.fragment. 914 The length MUST NOT exceed 2^14 + 1024. 916 fragment 917 The compressed form of TLSPlaintext.fragment. 919 Note: A CompressionMethod.null operation is an identity operation; no 920 fields are altered. 922 Implementation note: Decompression functions are responsible for 923 ensuring that messages cannot cause internal buffer overflows. 925 6.2.3. Record Payload Protection 927 The encryption and MAC functions translate a TLSCompressed structure 928 into a TLSCiphertext. The decryption functions reverse the process. 929 The MAC of the record also includes a sequence number so that 930 missing, extra, or repeated messages are detectable. 932 struct { 933 ContentType type; 934 ProtocolVersion version; 935 uint16 length; 936 select (SecurityParameters.cipher_type) { 937 case stream: GenericStreamCipher; 938 case block: GenericBlockCipher; 939 case aead: GenericAEADCipher; 940 } fragment; 941 } TLSCiphertext; 943 type 944 The type field is identical to TLSCompressed.type. 946 version 947 The version field is identical to TLSCompressed.version. 949 length 950 The length (in bytes) of the following TLSCiphertext.fragment. 951 The length MUST NOT exceed 2^14 + 2048. 953 fragment 954 The encrypted form of TLSCompressed.fragment, with the MAC. 956 6.2.3.1. Null or Standard Stream Cipher 958 Stream ciphers (including BulkCipherAlgorithm.null, see Appendix A.6) 959 convert TLSCompressed.fragment structures to and from stream 960 TLSCiphertext.fragment structures. 962 stream-ciphered struct { 963 opaque content[TLSCompressed.length]; 964 opaque MAC[SecurityParameters.mac_length]; 965 } GenericStreamCipher; 967 The MAC is generated as: 969 MAC(MAC_write_key, seq_num + 970 TLSCompressed.type + 971 TLSCompressed.version + 972 TLSCompressed.length + 973 TLSCompressed.fragment); 975 where "+" denotes concatenation. 977 seq_num 978 The sequence number for this record. 980 MAC 981 The MAC algorithm specified by SecurityParameters.mac_algorithm. 983 Note that the MAC is computed before encryption. The stream cipher 984 encrypts the entire block, including the MAC. For stream ciphers that 985 do not use a synchronization vector (such as RC4), the stream cipher 986 state from the end of one record is simply used on the subsequent 987 packet. If the cipher suite is TLS_NULL_WITH_NULL_NULL, encryption 988 consists of the identity operation (i.e., the data is not encrypted, 989 and the MAC size is zero, implying that no MAC is used). 990 TLSCiphertext.length is TLSCompressed.length plus 991 SecurityParameters.mac_length. 993 6.2.3.2. CBC Block Cipher 994 For block ciphers (such as 3DES, or AES), the encryption and MAC 995 functions convert TLSCompressed.fragment structures to and from block 996 TLSCiphertext.fragment structures. 998 struct { 999 opaque IV[SecurityParameters.record_iv_length]; 1000 block-ciphered struct { 1001 opaque content[TLSCompressed.length]; 1002 opaque MAC[SecurityParameters.mac_length]; 1003 uint8 padding[GenericBlockCipher.padding_length]; 1004 uint8 padding_length; 1005 }; 1006 } GenericBlockCipher; 1008 The MAC is generated as described in Section 6.2.3.1. 1010 IV 1011 The Initialization Vector (IV) SHOULD be chosen at random, and 1012 MUST be unpredictable. Note that in versions of TLS prior to 1.1, 1013 there was no IV field, and the last ciphertext block of the 1014 previous record (the "CBC residue") was used as the IV. This was 1015 changed to prevent the attacks described in [CBCATT]. For block 1016 ciphers, the IV length is of length 1017 SecurityParameters.record_iv_length which is equal to the 1018 SecurityParameters.block_size. 1020 padding 1021 Padding that is added to force the length of the plaintext to be 1022 an integral multiple of the block cipher's block length. The 1023 padding MAY be any length up to 255 bytes, as long as it results 1024 in the TLSCiphertext.length being an integral multiple of the 1025 block length. Lengths longer than necessary might be desirable to 1026 frustrate attacks on a protocol that are based on analysis of the 1027 lengths of exchanged messages. Each uint8 in the padding data 1028 vector MUST be filled with the padding length value. The receiver 1029 MUST check this padding and MUST use the bad_record_mac alert to 1030 indicate padding errors. 1032 padding_length 1033 The padding length MUST be such that the total size of the 1034 GenericBlockCipher structure is a multiple of the cipher's block 1035 length. Legal values range from zero to 255, inclusive. This 1036 length specifies the length of the padding field exclusive of the 1037 padding_length field itself. 1039 The encrypted data length (TLSCiphertext.length) is one more than the 1040 sum of SecurityParameters.block_length, TLSCompressed.length, 1041 SecurityParameters.mac_length, and padding_length. 1043 Example: If the block length is 8 bytes, the content length 1044 (TLSCompressed.length) is 61 bytes, and the MAC length is 20 bytes, 1045 then the length before padding is 82 bytes (this does not include the 1046 IV. Thus, the padding length modulo 8 must be equal to 6 in order to 1047 make the total length an even multiple of 8 bytes (the block length). 1048 The padding length can be 6, 14, 22, and so on, through 254. If the 1049 padding length were the minimum necessary, 6, the padding would be 6 1050 bytes, each containing the value 6. Thus, the last 8 octets of the 1051 GenericBlockCipher before block encryption would be xx 06 06 06 06 06 1052 06 06, where xx is the last octet of the MAC. 1054 Note: With block ciphers in CBC mode (Cipher Block Chaining), it is 1055 critical that the entire plaintext of the record be known before any 1056 ciphertext is transmitted. Otherwise, it is possible for the attacker 1057 to mount the attack described in [CBCATT]. 1059 Implementation Note: Canvel et al. [CBCTIME] have demonstrated a 1060 timing attack on CBC padding based on the time required to compute 1061 the MAC. In order to defend against this attack, implementations MUST 1062 ensure that record processing time is essentially the same whether or 1063 not the padding is correct. In general, the best way to do this is 1064 to compute the MAC even if the padding is incorrect, and only then 1065 reject the packet. For instance, if the pad appears to be incorrect, 1066 the implementation might assume a zero-length pad and then compute 1067 the MAC. This leaves a small timing channel, since MAC performance 1068 depends to some extent on the size of the data fragment, but it is 1069 not believed to be large enough to be exploitable, due to the large 1070 block size of existing MACs and the small size of the timing signal. 1072 6.2.3.3. AEAD ciphers 1074 For AEAD [AEAD] ciphers (such as [CCM] or [GCM]) the AEAD function 1075 converts TLSCompressed.fragment structures to and from AEAD 1076 TLSCiphertext.fragment structures. 1078 struct { 1079 opaque nonce_explicit[SecurityParameters.record_iv_length]; 1080 aead-ciphered struct { 1081 opaque content[TLSCompressed.length]; 1082 }; 1083 } GenericAEADCipher; 1085 AEAD ciphers take as input a single key, a nonce, a plaintext, and 1086 "additional data" to be included in the authentication check, as 1087 described in Section 2.1 of [AEAD]. The key is either the 1088 client_write_key or the server_write_key. No MAC key is used. 1090 Each AEAD cipher suite MUST specify how the nonce supplied to the 1091 AEAD operation is constructed, and what is the length of the 1092 GenericAEADCipher.nonce_explicit part. In many cases, it is 1093 appropriate to use the partially implicit nonce technique described 1094 in Section 3.2.1 of [AEAD]; with record_iv_length being the length of 1095 the explicit part. In this case, the implicit part SHOULD be derived 1096 from key_block as client_write_iv and server_write_iv (as described 1097 in Section 6.3), and the explicit part is included in 1098 GenericAEAEDCipher.nonce_explicit. 1100 The plaintext is the TLSCompressed.fragment. 1102 The additional authenticated data, which we denote as 1103 additional_data, is defined as follows: 1105 additional_data = seq_num + TLSCompressed.type + 1106 TLSCompressed.version + TLSCompressed.length; 1108 Where "+" denotes concatenation. 1110 The aead_output consists of the ciphertext output by the AEAD 1111 encryption operation. The length will generally be larger than 1112 TLSCompressed.length, but by an amount that varies with the AEAD 1113 cipher. Since the ciphers might incorporate padding, the amount of 1114 overhead could vary with different TLSCompressed.length values. Each 1115 AEAD cipher MUST NOT produce an expansion of greater than 1024 bytes. 1116 Symbolically, 1118 AEADEncrypted = AEAD-Encrypt(key, nonce, plaintext, 1119 additional_data) 1121 In order to decrypt and verify, the cipher takes as input the key, 1122 nonce, the "additional_data", and the AEADEncrypted value. The output 1123 is either the plaintext or an error indicating that the decryption 1124 failed. There is no separate integrity check. I.e., 1126 TLSCompressed.fragment = AEAD-Decrypt(write_key, nonce, 1127 AEADEncrypted, 1128 additional_data) 1130 If the decryption fails, a fatal bad_record_mac alert MUST be 1131 generated. 1133 6.3. Key Calculation 1135 The Record Protocol requires an algorithm to generates keys required 1136 by the current connection state (see Appendix A.6) from the security 1137 parameters provided by the handshake protocol. 1139 The master secret is expanded into a sequence of secure bytes, which 1140 is then split to a client write MAC key, a server write MAC key, a 1141 client write encryption key, and a server write encryption key. Each 1142 of these is generated from the byte sequence in that order. Unused 1143 values are empty. Some AEAD ciphers may additionally require a 1144 client write IV and a server write IV (see Section 6.2.3.3). 1146 When keys and MAC keys are generated, the master secret is used as an 1147 entropy source. 1149 To generate the key material, compute 1151 key_block = PRF(SecurityParameters.master_secret, 1152 "key expansion", 1153 SecurityParameters.server_random + 1154 SecurityParameters.client_random); 1156 until enough output has been generated. Then the key_block is 1157 partitioned as follows: 1159 client_write_MAC_key[SecurityParameters.mac_key_length] 1160 server_write_MAC_key[SecurityParameters.mac_key_length] 1161 client_write_key[SecurityParameters.enc_key_length] 1162 server_write_key[SecurityParameters.enc_key_length] 1163 client_write_IV[SecurityParameters.fixed_iv_length] 1164 server_write_IV[SecurityParameters.fixed_iv_length] 1166 The client_write_IV and server_write_IV are only generated for 1167 implicit nonce techniques as described in Section 3.2.1 of [AEAD]. 1169 Implementation note: The currently defined cipher suite which 1170 requires the most material is AES_256_CBC_SHA. It requires 2 x 32 1171 byte keys and 2 x 20 byte MAC keys, for a total 104 bytes of key 1172 material. 1174 7. The TLS Handshaking Protocols 1176 TLS has three subprotocols that are used to allow peers to agree upon 1177 security parameters for the record layer, to authenticate themselves, 1178 to instantiate negotiated security parameters, and to report error 1179 conditions to each other. 1181 The Handshake Protocol is responsible for negotiating a session, 1182 which consists of the following items: 1184 session identifier 1185 An arbitrary byte sequence chosen by the server to identify an 1186 active or resumable session state. 1188 peer certificate 1189 X509v3 [PKIX] certificate of the peer. This element of the state 1190 may be null. 1192 compression method 1193 The algorithm used to compress data prior to encryption. 1195 cipher spec 1196 Specifies the bulk data encryption algorithm (such as null, DES, 1197 etc.) and a MAC algorithm (such as MD5 or SHA). It also defines 1198 cryptographic attributes such as the mac_length. (See Appendix A.6 1199 for formal definition.) 1201 master secret 1202 48-byte secret shared between the client and server. 1204 is resumable 1205 A flag indicating whether the session can be used to initiate new 1206 connections. 1208 These items are then used to create security parameters for use by 1209 the Record Layer when protecting application data. Many connections 1210 can be instantiated using the same session through the resumption 1211 feature of the TLS Handshake Protocol. 1213 7.1. Change Cipher Spec Protocol 1215 The change cipher spec protocol exists to signal transitions in 1216 ciphering strategies. The protocol consists of a single message, 1217 which is encrypted and compressed under the current (not the pending) 1218 connection state. The message consists of a single byte of value 1. 1220 struct { 1221 enum { change_cipher_spec(1), (255) } type; 1222 } ChangeCipherSpec; 1224 The change cipher spec message is sent by both the client and the 1225 server to notify the receiving party that subsequent records will be 1226 protected under the newly negotiated CipherSpec and keys. Reception 1227 of this message causes the receiver to instruct the Record Layer to 1228 immediately copy the read pending state into the read current state. 1229 Immediately after sending this message, the sender MUST instruct the 1230 record layer to make the write pending state the write active state. 1231 (See Section 6.1.) The change cipher spec message is sent during the 1232 handshake after the security parameters have been agreed upon, but 1233 before the verifying finished message is sent. 1235 Note: If a rehandshake occurs while data is flowing on a connection, 1236 the communicating parties may continue to send data using the old 1237 CipherSpec. However, once the ChangeCipherSpec has been sent, the new 1238 CipherSpec MUST be used. The first side to send the ChangeCipherSpec 1239 does not know that the other side has finished computing the new 1240 keying material (e.g., if it has to perform a time consuming public 1241 key operation). Thus, a small window of time, during which the 1242 recipient must buffer the data, MAY exist. In practice, with modern 1243 machines this interval is likely to be fairly short. 1245 7.2. Alert Protocol 1247 One of the content types supported by the TLS Record layer is the 1248 alert type. Alert messages convey the severity of the message and a 1249 description of the alert. Alert messages with a level of fatal result 1250 in the immediate termination of the connection. In this case, other 1251 connections corresponding to the session may continue, but the 1252 session identifier MUST be invalidated, preventing the failed session 1253 from being used to establish new connections. Like other messages, 1254 alert messages are encrypted and compressed, as specified by the 1255 current connection state. 1257 enum { warning(1), fatal(2), (255) } AlertLevel; 1259 enum { 1260 close_notify(0), 1261 unexpected_message(10), 1262 bad_record_mac(20), 1263 decryption_failed_RESERVED(21), 1264 record_overflow(22), 1265 decompression_failure(30), 1266 handshake_failure(40), 1267 no_certificate_RESERVED(41), 1268 bad_certificate(42), 1269 unsupported_certificate(43), 1270 certificate_revoked(44), 1271 certificate_expired(45), 1272 certificate_unknown(46), 1273 illegal_parameter(47), 1274 unknown_ca(48), 1275 access_denied(49), 1276 decode_error(50), 1277 decrypt_error(51), 1278 export_restriction_RESERVED(60), 1279 protocol_version(70), 1280 insufficient_security(71), 1281 internal_error(80), 1282 user_canceled(90), 1283 no_renegotiation(100), 1284 unsupported_extension(110), 1285 (255) 1286 } AlertDescription; 1288 struct { 1289 AlertLevel level; 1290 AlertDescription description; 1291 } Alert; 1293 7.2.1. Closure Alerts 1295 The client and the server must share knowledge that the connection is 1296 ending in order to avoid a truncation attack. Either party may 1297 initiate the exchange of closing messages. 1299 close_notify 1300 This message notifies the recipient that the sender will not send 1301 any more messages on this connection. Note that as of TLS 1.1, 1302 failure to properly close a connection no longer requires that a 1303 session not be resumed. This is a change from TLS 1.0 to conform 1304 with widespread implementation practice. 1306 Either party may initiate a close by sending a close_notify alert. 1307 Any data received after a closure alert is ignored. 1309 Unless some other fatal alert has been transmitted, each party is 1310 required to send a close_notify alert before closing the write side 1311 of the connection. The other party MUST respond with a close_notify 1312 alert of its own and close down the connection immediately, 1313 discarding any pending writes. It is not required for the initiator 1314 of the close to wait for the responding close_notify alert before 1315 closing the read side of the connection. 1317 If the application protocol using TLS provides that any data may be 1318 carried over the underlying transport after the TLS connection is 1319 closed, the TLS implementation must receive the responding 1320 close_notify alert before indicating to the application layer that 1321 the TLS connection has ended. If the application protocol will not 1322 transfer any additional data, but will only close the underlying 1323 transport connection, then the implementation MAY choose to close the 1324 transport without waiting for the responding close_notify. No part of 1325 this standard should be taken to dictate the manner in which a usage 1326 profile for TLS manages its data transport, including when 1327 connections are opened or closed. 1329 Note: It is assumed that closing a connection reliably delivers 1330 pending data before destroying the transport. 1332 7.2.2. Error Alerts 1334 Error handling in the TLS Handshake protocol is very simple. When an 1335 error is detected, the detecting party sends a message to the other 1336 party. Upon transmission or receipt of a fatal alert message, both 1337 parties immediately close the connection. Servers and clients MUST 1338 forget any session-identifiers, keys, and secrets associated with a 1339 failed connection. Thus, any connection terminated with a fatal alert 1340 MUST NOT be resumed. 1342 Whenever an implementation encounters a condition which is defined as 1343 a fatal alert, it MUST send the appropriate alert prior to closing 1344 the connection. For all errors where an alert level is not explicitly 1345 specified, the sending party MAY determine at its discretion whether 1346 to treat this as a fatal error or not. If the implementation chooses 1347 to send an alert but intends to close the connection immediately 1348 afterwards, it MUST send that alert at the fatal alert level. 1350 If an alert with a level of warning is sent and received, generally 1351 the connection can continue normally. If the receiving party decides 1352 not to proceed with the connection (e.g., after having received a 1353 no_renegotiation alert that it is not willing to accept), it SHOULD 1354 send a fatal alert to terminate the connection. Given this, the 1355 sending party cannot, in general, know how the receiving party will 1356 behave. Therefore, warning alerts are not very useful when the 1357 sending party wants to continue the connection, and thus are 1358 sometimes omitted. For example, if a peer decides to accept an 1359 expired certificate (perhaps after confirming this with the user) and 1360 wants to continue the connection, it would not generally send a 1361 certificate_expired alert. 1363 The following error alerts are defined: 1365 unexpected_message 1366 An inappropriate message was received. This alert is always fatal 1367 and should never be observed in communication between proper 1368 implementations. 1370 bad_record_mac 1371 This alert is returned if a record is received with an incorrect 1372 MAC. This alert also MUST be returned if an alert is sent because 1373 a TLSCiphertext decrypted in an invalid way: either it wasn't an 1374 even multiple of the block length, or its padding values, when 1375 checked, weren't correct. This message is always fatal and should 1376 never be observed in communication between proper implementations 1377 (except when messages were corrupted in the network). 1379 decryption_failed_RESERVED 1380 This alert was used in some earlier versions of TLS, and may have 1381 permitted certain attacks against the CBC mode [CBCATT]. It MUST 1382 NOT be sent by compliant implementations. 1384 record_overflow 1385 A TLSCiphertext record was received that had a length more than 1386 2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1387 with more than 2^14+1024 bytes. This message is always fatal and 1388 should never be observed in communication between proper 1389 implementations (except when messages were corrupted in the 1390 network). 1392 decompression_failure 1393 The decompression function received improper input (e.g., data 1394 that would expand to excessive length). This message is always 1395 fatal and should never be observed in communication between proper 1396 implementations. 1398 handshake_failure 1399 Reception of a handshake_failure alert message indicates that the 1400 sender was unable to negotiate an acceptable set of security 1401 parameters given the options available. This is a fatal error. 1403 no_certificate_RESERVED 1404 This alert was used in SSLv3 but not any version of TLS. It MUST 1405 NOT be sent by compliant implementations. 1407 bad_certificate 1408 A certificate was corrupt, contained signatures that did not 1409 verify correctly, etc. 1411 unsupported_certificate 1412 A certificate was of an unsupported type. 1414 certificate_revoked 1415 A certificate was revoked by its signer. 1417 certificate_expired 1418 A certificate has expired or is not currently valid. 1420 certificate_unknown 1421 Some other (unspecified) issue arose in processing the 1422 certificate, rendering it unacceptable. 1424 illegal_parameter 1425 A field in the handshake was out of range or inconsistent with 1426 other fields. This message is always fatal. 1428 unknown_ca 1429 A valid certificate chain or partial chain was received, but the 1430 certificate was not accepted because the CA certificate could not 1431 be located or couldn't be matched with a known, trusted CA. This 1432 message is always fatal. 1434 access_denied 1435 A valid certificate was received, but when access control was 1436 applied, the sender decided not to proceed with negotiation. This 1437 message is always fatal. 1439 decode_error 1440 A message could not be decoded because some field was out of the 1441 specified range or the length of the message was incorrect. This 1442 message is always fatal and should never be observed in 1443 communication between proper implementations (except when messages 1444 were corrupted in the network). 1446 decrypt_error 1447 A handshake cryptographic operation failed, including being unable 1448 to correctly verify a signature or validate a finished message. 1449 This message is always fatal. 1451 export_restriction_RESERVED 1452 This alert was used in some earlier versions of TLS. It MUST NOT 1453 be sent by compliant implementations. 1455 protocol_version 1456 The protocol version the client has attempted to negotiate is 1457 recognized but not supported. (For example, old protocol versions 1458 might be avoided for security reasons). This message is always 1459 fatal. 1461 insufficient_security 1462 Returned instead of handshake_failure when a negotiation has 1463 failed specifically because the server requires ciphers more 1464 secure than those supported by the client. This message is always 1465 fatal. 1467 internal_error 1468 An internal error unrelated to the peer or the correctness of the 1469 protocol (such as a memory allocation failure) makes it impossible 1470 to continue. This message is always fatal. 1472 user_canceled 1473 This handshake is being canceled for some reason unrelated to a 1474 protocol failure. If the user cancels an operation after the 1475 handshake is complete, just closing the connection by sending a 1476 close_notify is more appropriate. This alert should be followed by 1477 a close_notify. This message is generally a warning. 1479 no_renegotiation 1480 Sent by the client in response to a hello request or by the server 1481 in response to a client hello after initial handshaking. Either 1482 of these would normally lead to renegotiation; when that is not 1483 appropriate, the recipient should respond with this alert. At 1484 that point, the original requester can decide whether to proceed 1485 with the connection. One case where this would be appropriate is 1486 where a server has spawned a process to satisfy a request; the 1487 process might receive security parameters (key length, 1488 authentication, etc.) at startup and it might be difficult to 1489 communicate changes to these parameters after that point. This 1490 message is always a warning. 1492 unsupported_extension 1493 sent by clients that receive an extended server hello containing 1494 an extension that they did not put in the corresponding client 1495 hello. This message is always fatal. 1497 For all errors where an alert level is not explicitly specified, the 1498 sending party MAY determine at its discretion whether this is a fatal 1499 error or not; if an alert with a level of warning is received, the 1500 receiving party MAY decide at its discretion whether to treat this as 1501 a fatal error or not. However, all messages that are transmitted 1502 with a level of fatal MUST be treated as fatal messages. 1504 New Alert values are assigned by IANA as described in Section 12. 1506 7.3. Handshake Protocol Overview 1508 The cryptographic parameters of the session state are produced by the 1509 TLS Handshake Protocol, which operates on top of the TLS Record 1510 Layer. When a TLS client and server first start communicating, they 1511 agree on a protocol version, select cryptographic algorithms, 1512 optionally authenticate each other, and use public-key encryption 1513 techniques to generate shared secrets. 1515 The TLS Handshake Protocol involves the following steps: 1517 - Exchange hello messages to agree on algorithms, exchange random 1518 values, and check for session resumption. 1520 - Exchange the necessary cryptographic parameters to allow the 1521 client and server to agree on a premaster secret. 1523 - Exchange certificates and cryptographic information to allow the 1524 client and server to authenticate themselves. 1526 - Generate a master secret from the premaster secret and exchanged 1527 random values. 1529 - Provide security parameters to the record layer. 1531 - Allow the client and server to verify that their peer has 1532 calculated the same security parameters and that the handshake 1533 occurred without tampering by an attacker. 1535 Note that higher layers should not be overly reliant on whether TLS 1536 always negotiates the strongest possible connection between two 1537 peers. There are a number of ways in which a man in the middle 1538 attacker can attempt to make two entities drop down to the least 1539 secure method they support. The protocol has been designed to 1540 minimize this risk, but there are still attacks available: for 1541 example, an attacker could block access to the port a secure service 1542 runs on, or attempt to get the peers to negotiate an unauthenticated 1543 connection. The fundamental rule is that higher levels must be 1544 cognizant of what their security requirements are and never transmit 1545 information over a channel less secure than what they require. The 1546 TLS protocol is secure in that any cipher suite offers its promised 1547 level of security: if you negotiate 3DES with a 1024 bit RSA key 1548 exchange with a host whose certificate you have verified, you can 1549 expect to be that secure. 1551 These goals are achieved by the handshake protocol, which can be 1552 summarized as follows: The client sends a client hello message to 1553 which the server must respond with a server hello message, or else a 1554 fatal error will occur and the connection will fail. The client hello 1555 and server hello are used to establish security enhancement 1556 capabilities between client and server. The client hello and server 1557 hello establish the following attributes: Protocol Version, Session 1558 ID, Cipher Suite, and Compression Method. Additionally, two random 1559 values are generated and exchanged: ClientHello.random and 1560 ServerHello.random. 1562 The actual key exchange uses up to four messages: the server 1563 certificate, the server key exchange, the client certificate, and the 1564 client key exchange. New key exchange methods can be created by 1565 specifying a format for these messages and by defining the use of the 1566 messages to allow the client and server to agree upon a shared 1567 secret. This secret MUST be quite long; currently defined key 1568 exchange methods exchange secrets that range from 46 bytes upwards. 1570 Following the hello messages, the server will send its certificate, 1571 if it is to be authenticated. Additionally, a server key exchange 1572 message may be sent, if it is required (e.g., if their server has no 1573 certificate, or if its certificate is for signing only). If the 1574 server is authenticated, it may request a certificate from the 1575 client, if that is appropriate to the cipher suite selected. Next, 1576 the server will send the server hello done message, indicating that 1577 the hello-message phase of the handshake is complete. The server will 1578 then wait for a client response. If the server has sent a certificate 1579 request message, the client MUST send the certificate message. The 1580 client key exchange message is now sent, and the content of that 1581 message will depend on the public key algorithm selected between the 1582 client hello and the server hello. If the client has sent a 1583 certificate with signing ability, a digitally-signed certificate 1584 verify message is sent to explicitly verify possession of the private 1585 key in the certificate. 1587 At this point, a change cipher spec message is sent by the client, 1588 and the client copies the pending Cipher Spec into the current Cipher 1589 Spec. The client then immediately sends the finished message under 1590 the new algorithms, keys, and secrets. In response, the server will 1591 send its own change cipher spec message, transfer the pending to the 1592 current Cipher Spec, and send its finished message under the new 1593 Cipher Spec. At this point, the handshake is complete, and the client 1594 and server may begin to exchange application layer data. (See flow 1595 chart below.) Application data MUST NOT be sent prior to the 1596 completion of the first handshake (before a cipher suite other than 1597 TLS_NULL_WITH_NULL_NULL is established). 1599 Client Server 1601 ClientHello --------> 1602 ServerHello 1603 Certificate* 1604 ServerKeyExchange* 1605 CertificateRequest* 1606 <-------- ServerHelloDone 1607 Certificate* 1608 ClientKeyExchange 1609 CertificateVerify* 1610 [ChangeCipherSpec] 1611 Finished --------> 1612 [ChangeCipherSpec] 1613 <-------- Finished 1614 Application Data <-------> Application Data 1616 Fig. 1. Message flow for a full handshake 1618 * Indicates optional or situation-dependent messages that are not 1619 always sent. 1621 Note: To help avoid pipeline stalls, ChangeCipherSpec is an 1622 independent TLS Protocol content type, and is not actually a TLS 1623 handshake message. 1625 When the client and server decide to resume a previous session or 1626 duplicate an existing session (instead of negotiating new security 1627 parameters), the message flow is as follows: 1629 The client sends a ClientHello using the Session ID of the session to 1630 be resumed. The server then checks its session cache for a match. If 1631 a match is found, and the server is willing to re-establish the 1632 connection under the specified session state, it will send a 1633 ServerHello with the same Session ID value. At this point, both 1634 client and server MUST send change cipher spec messages and proceed 1635 directly to finished messages. Once the re-establishment is complete, 1636 the client and server MAY begin to exchange application layer data. 1637 (See flow chart below.) If a Session ID match is not found, the 1638 server generates a new session ID and the TLS client and server 1639 perform a full handshake. 1641 Client Server 1643 ClientHello --------> 1644 ServerHello 1645 [ChangeCipherSpec] 1646 <-------- Finished 1647 [ChangeCipherSpec] 1648 Finished --------> 1649 Application Data <-------> Application Data 1651 Fig. 2. Message flow for an abbreviated handshake 1653 The contents and significance of each message will be presented in 1654 detail in the following sections. 1656 7.4. Handshake Protocol 1658 The TLS Handshake Protocol is one of the defined higher-level clients 1659 of the TLS Record Protocol. This protocol is used to negotiate the 1660 secure attributes of a session. Handshake messages are supplied to 1661 the TLS Record Layer, where they are encapsulated within one or more 1662 TLSPlaintext structures, which are processed and transmitted as 1663 specified by the current active session state. 1665 enum { 1666 hello_request(0), client_hello(1), server_hello(2), 1667 certificate(11), server_key_exchange (12), 1668 certificate_request(13), server_hello_done(14), 1669 certificate_verify(15), client_key_exchange(16), 1670 finished(20), (255) 1671 } HandshakeType; 1673 struct { 1674 HandshakeType msg_type; /* handshake type */ 1675 uint24 length; /* bytes in message */ 1676 select (HandshakeType) { 1677 case hello_request: HelloRequest; 1678 case client_hello: ClientHello; 1679 case server_hello: ServerHello; 1680 case certificate: Certificate; 1681 case server_key_exchange: ServerKeyExchange; 1682 case certificate_request: CertificateRequest; 1683 case server_hello_done: ServerHelloDone; 1684 case certificate_verify: CertificateVerify; 1685 case client_key_exchange: ClientKeyExchange; 1686 case finished: Finished; 1687 } body; 1688 } Handshake; 1690 The handshake protocol messages are presented below in the order they 1691 MUST be sent; sending handshake messages in an unexpected order 1692 results in a fatal error. Unneeded handshake messages can be omitted, 1693 however. Note one exception to the ordering: the Certificate message 1694 is used twice in the handshake (from server to client, then from 1695 client to server), but described only in its first position. The one 1696 message that is not bound by these ordering rules is the Hello 1697 Request message, which can be sent at any time, but which SHOULD be 1698 ignored by the client if it arrives in the middle of a handshake. 1700 New Handshake message types are assigned by IANA as described in 1701 Section 12. 1703 7.4.1. Hello Messages 1705 The hello phase messages are used to exchange security enhancement 1706 capabilities between the client and server. When a new session 1707 begins, the Record Layer's connection state encryption, hash, and 1708 compression algorithms are initialized to null. The current 1709 connection state is used for renegotiation messages. 1711 7.4.1.1. Hello Request 1713 When this message will be sent: 1715 The hello request message MAY be sent by the server at any time. 1717 Meaning of this message: 1719 Hello request is a simple notification that the client should 1720 begin the negotiation process anew by sending a client hello 1721 message when convenient. This message is not intended to establish 1722 which side is the client or server but merely to initiate a new 1723 negotiation. Servers SHOULD NOT send a HelloRequest immediately 1724 upon the client's initial connection. It is the client's job to 1725 send a ClientHello at that time. 1727 This message will be ignored by the client if the client is 1728 currently negotiating a session. This message may be ignored by 1729 the client if it does not wish to renegotiate a session, or the 1730 client may, if it wishes, respond with a no_renegotiation alert. 1731 Since handshake messages are intended to have transmission 1732 precedence over application data, it is expected that the 1733 negotiation will begin before no more than a few records are 1734 received from the client. If the server sends a hello request but 1735 does not receive a client hello in response, it may close the 1736 connection with a fatal alert. 1738 After sending a hello request, servers SHOULD NOT repeat the 1739 request until the subsequent handshake negotiation is complete. 1741 Structure of this message: 1743 struct { } HelloRequest; 1745 Note: This message MUST NOT be included in the message hashes that 1746 are maintained throughout the handshake and used in the finished 1747 messages and the certificate verify message. 1749 7.4.1.2. Client Hello 1751 When this message will be sent: 1753 When a client first connects to a server it is required to send 1754 the client hello as its first message. The client can also send a 1755 client hello in response to a hello request or on its own 1756 initiative in order to renegotiate the security parameters in an 1757 existing connection. 1759 Structure of this message: 1761 The client hello message includes a random structure, which is 1762 used later in the protocol. 1764 struct { 1765 uint32 gmt_unix_time; 1766 opaque random_bytes[28]; 1767 } Random; 1769 gmt_unix_time 1770 The current time and date in standard UNIX 32-bit format 1771 (seconds since the midnight starting Jan 1, 1970, GMT, ignoring 1772 leap seconds) according to the sender's internal clock. Clocks 1773 are not required to be set correctly by the basic TLS Protocol; 1774 higher-level or application protocols may define additional 1775 requirements. 1777 random_bytes 1778 28 bytes generated by a secure random number generator. 1780 The client hello message includes a variable-length session 1781 identifier. If not empty, the value identifies a session between the 1782 same client and server whose security parameters the client wishes to 1783 reuse. The session identifier MAY be from an earlier connection, this 1784 connection, or from another currently active connection. The second 1785 option is useful if the client only wishes to update the random 1786 structures and derived values of a connection, and the third option 1787 makes it possible to establish several independent secure connections 1788 without repeating the full handshake protocol. These independent 1789 connections may occur sequentially or simultaneously; a SessionID 1790 becomes valid when the handshake negotiating it completes with the 1791 exchange of Finished messages and persists until it is removed due to 1792 aging or because a fatal error was encountered on a connection 1793 associated with the session. The actual contents of the SessionID are 1794 defined by the server. 1796 opaque SessionID<0..32>; 1798 Warning: Because the SessionID is transmitted without encryption or 1799 immediate MAC protection, servers MUST NOT place confidential 1800 information in session identifiers or let the contents of fake 1801 session identifiers cause any breach of security. (Note that the 1802 content of the handshake as a whole, including the SessionID, is 1803 protected by the Finished messages exchanged at the end of the 1804 handshake.) 1806 The cipher suite list, passed from the client to the server in the 1807 client hello message, contains the combinations of cryptographic 1808 algorithms supported by the client in order of the client's 1809 preference (favorite choice first). Each cipher suite defines a key 1810 exchange algorithm, a bulk encryption algorithm (including secret key 1811 length), a MAC algorithm, and a PRF. The server will select a cipher 1812 suite or, if no acceptable choices are presented, return a handshake 1813 failure alert and close the connection. 1815 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1817 The client hello includes a list of compression algorithms supported 1818 by the client, ordered according to the client's preference. 1820 enum { null(0), (255) } CompressionMethod; 1822 struct { 1823 ProtocolVersion client_version; 1824 Random random; 1825 SessionID session_id; 1826 CipherSuite cipher_suites<2..2^16-2>; 1827 CompressionMethod compression_methods<1..2^8-1>; 1828 select (extensions_present) { 1829 case false: 1830 struct {}; 1831 case true: 1832 Extension extensions<0..2^16-1>; 1833 }; 1834 } ClientHello; 1836 TLS allows extensions to follow the compression_methods field in an 1837 extensions block. The presence of extensions can be detected by 1838 determining whether there are bytes following the compression_methods 1839 at the end of the ClientHello. Note that this method of detecting 1840 optional data differs from the normal TLS method of having a 1841 variable-length field but is used for compatibility with TLS before 1842 extensions were defined. 1844 client_version 1845 The version of the TLS protocol by which the client wishes to 1846 communicate during this session. This SHOULD be the latest 1847 (highest valued) version supported by the client. For this version 1848 of the specification, the version will be 3.3 (See Appendix E for 1849 details about backward compatibility). 1851 random 1852 A client-generated random structure. 1854 session_id 1855 The ID of a session the client wishes to use for this connection. 1856 This field is empty if no session_id is available, or it the 1857 client wishes to generate new security parameters. 1859 cipher_suites 1860 This is a list of the cryptographic options supported by the 1861 client, with the client's first preference first. If the 1862 session_id field is not empty (implying a session resumption 1863 request) this vector MUST include at least the cipher_suite from 1864 that session. Values are defined in Appendix A.5. 1866 compression_methods 1867 This is a list of the compression methods supported by the client, 1868 sorted by client preference. If the session_id field is not empty 1869 (implying a session resumption request) it MUST include the 1870 compression_method from that session. This vector MUST contain, 1871 and all implementations MUST support, CompressionMethod.null. 1872 Thus, a client and server will always be able to agree on a 1873 compression method. 1875 extensions 1876 Clients MAY request extended functionality from servers by sending 1877 data in the extensions Here the new "extensions" field contains a 1878 list of extensions. The actual "Extension" format is defined in 1879 Section 7.4.1.4. 1881 In the event that a client requests additional functionality using 1882 extensions, and this functionality is not supplied by the server, the 1883 client MAY abort the handshake. A server MUST accept client hello 1884 messages both with and without the extensions field, and (as for all 1885 other messages) MUST check that the amount of data in the message 1886 precisely matches one of these formats; if not, then it MUST send a 1887 fatal "decode_error" alert. 1889 After sending the client hello message, the client waits for a server 1890 hello message. Any other handshake message returned by the server 1891 except for a hello request is treated as a fatal error. 1893 7.4.1.3. Server Hello 1895 When this message will be sent: 1897 The server will send this message in response to a client hello 1898 message when it was able to find an acceptable set of algorithms. 1899 If it cannot find such a match, it will respond with a handshake 1900 failure alert. 1902 Structure of this message: 1904 struct { 1905 ProtocolVersion server_version; 1906 Random random; 1907 SessionID session_id; 1908 CipherSuite cipher_suite; 1909 CompressionMethod compression_method; 1910 select (extensions_present) { 1911 case false: 1912 struct {}; 1913 case true: 1914 Extension extensions<0..2^16-1>; 1915 }; 1916 } ServerHello; 1918 The presence of extensions can be detected by determining whether 1919 there are bytes following the compression_method field at the end of 1920 the ServerHello. 1922 server_version 1923 This field will contain the lower of that suggested by the client 1924 in the client hello and the highest supported by the server. For 1925 this version of the specification, the version is 3.3. (See 1926 Appendix E for details about backward compatibility.) 1928 random 1929 This structure is generated by the server and MUST be 1930 independently generated from the ClientHello.random. 1932 session_id 1933 This is the identity of the session corresponding to this 1934 connection. If the ClientHello.session_id was non-empty, the 1935 server will look in its session cache for a match. If a match is 1936 found and the server is willing to establish the new connection 1937 using the specified session state, the server will respond with 1938 the same value as was supplied by the client. This indicates a 1939 resumed session and dictates that the parties must proceed 1940 directly to the finished messages. Otherwise this field will 1941 contain a different value identifying the new session. The server 1942 may return an empty session_id to indicate that the session will 1943 not be cached and therefore cannot be resumed. If a session is 1944 resumed, it must be resumed using the same cipher suite it was 1945 originally negotiated with. Note that there is no requirement that 1946 the server resume any session even if it had formerly provided a 1947 session_id. Client MUST be prepared to do a full negotiation -- 1948 including negotiating new cipher suites -- during any handshake. 1950 cipher_suite 1951 The single cipher suite selected by the server from the list in 1952 ClientHello.cipher_suites. For resumed sessions, this field is the 1953 value from the state of the session being resumed. 1955 compression_method 1956 The single compression algorithm selected by the server from the 1957 list in ClientHello.compression_methods. For resumed sessions this 1958 field is the value from the resumed session state. 1960 extensions 1961 A list of extensions. Note that only extensions offered by the 1962 client can appear in the server's list. 1964 7.4.1.4 Hello Extensions 1966 The extension format is: 1968 struct { 1969 ExtensionType extension_type; 1970 opaque extension_data<0..2^16-1>; 1971 } Extension; 1973 enum { 1974 signature_algorithms(TBD-BY-IANA), (65535) 1975 } ExtensionType; 1977 Here: 1979 - "extension_type" identifies the particular extension type. 1981 - "extension_data" contains information specific to the particular 1982 extension type. 1984 The initial set of extensions is defined in a companion document 1985 [TLSEXT]. The list of extension types is maintained by IANA as 1986 described in Section 12. 1988 There are subtle (and not so subtle) interactions that may occur in 1989 this protocol between new features and existing features which may 1990 result in a significant reduction in overall security, The following 1991 considerations should be taken into account when designing new 1992 extensions: 1994 - Some cases where a server does not agree to an extension are error 1995 conditions, and some simply a refusal to support a particular 1996 feature. In general error alerts should be used for the former, 1997 and a field in the server extension response for the latter. 1999 - Extensions should as far as possible be designed to prevent any 2000 attack that forces use (or non-use) of a particular feature by 2001 manipulation of handshake messages. This principle should be 2002 followed regardless of whether the feature is believed to cause a 2003 security problem. 2005 Often the fact that the extension fields are included in the 2006 inputs to the Finished message hashes will be sufficient, but 2007 extreme care is needed when the extension changes the meaning of 2008 messages sent in the handshake phase. Designers and implementors 2009 should be aware of the fact that until the handshake has been 2010 authenticated, active attackers can modify messages and insert, 2011 remove, or replace extensions. 2013 - It would be technically possible to use extensions to change major 2014 aspects of the design of TLS; for example the design of cipher 2015 suite negotiation. This is not recommended; it would be more 2016 appropriate to define a new version of TLS - particularly since 2017 the TLS handshake algorithms have specific protection against 2018 version rollback attacks based on the version number, and the 2019 possibility of version rollback should be a significant 2020 consideration in any major design change. 2022 7.4.1.4.1 Signature Algorithms 2024 The client uses the "signature_algorithms" extension to indicate to 2025 the server which signature/hash algorithm pairs may be used in 2026 digital signatures. The "extension_data" field of this extension 2027 contains a "supported_signature_algorithms" value. 2029 enum { 2030 none(0), md5(1), sha1(2), sha256(3), sha384(4), 2031 sha512(5), (255) 2032 } HashAlgorithm; 2034 enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) } 2035 SignatureAlgorithm; 2037 struct { 2038 HashAlgorithm hash; 2039 SignatureAlgorithm signature; 2040 } SignatureAndHashAlgorithm; 2042 SignatureAndHashAlgorithm 2043 supported_signature_algorithms<2..2^16-2>; 2045 Each SignatureAndHashAlgorithm value lists a single hash/signature 2046 pair which the client is willing to verify. The values are indicated 2047 in descending order of preference. 2049 Note: Because not all signature algorithms and hash algorithms may be 2050 accepted by an implementation (e.g., DSA with SHA-1, but not 2051 SHA-256), algorithms here are listed in pairs. 2053 hash 2054 This field indicates the hash algorithm which may be used. The 2055 values indicate support for unhashed data, MD5 [MD5], SHA-1, 2056 SHA-256, SHA-384, and SHA-512 [SHA] respectively. The "none" value 2057 is provided for future extensibility, in case of a signature 2058 algorithm which does not require hashing before signing. 2060 signature 2061 This field indicates the signature algorithm which may be used. 2062 The values indicate anonymous signatures, RSASSA-PKCS1-v1_5 2063 [PKCS1] and DSA [DSS] respectively. The "anonymous" value is 2064 meaningless in this context but used in Section 7.4.3. It MUST NOT 2065 appear in this extension. 2067 The semantics of this extension are somewhat complicated because the 2068 cipher suite indicates permissible signature algorithms but not hash 2069 algorithm. Sections 7.4.2 and 7.4.3 describe the appropriate rules. 2071 If the client supports only the default hash and signature algorithms 2072 (listed in this section), it MAY omit the signature_algorithms 2073 extension. If the client does not support the default algorithms, or 2074 supports other hash and signature algorithms (and it is willing to 2075 use them for verifying messages sent by server; server certificates 2076 and server key exchange), it MUST send the signature_algorithms 2077 extension listing the algorithms it is willing to accept. 2079 If the client does not send the signature_algorithms extension, the 2080 server MUST assume the following: 2082 - If the negotiated key exchange algorithm is one of (RSA, DHE_RSA, 2083 DH_RSA, RSA_PSK, ECDH_RSA, ECDHE_RSA), behave as if client had sent 2084 the value (sha1,rsa). 2086 - If the negotiated key exchange algorithm is one of (DHE_DSS, 2087 DH_DSS), behave as if the client had sent the value (sha1,dsa). 2089 - If the negotiated key exchnage algorithm is one of (ECDH_ECDSA, 2090 ECDHE_ECDSA), behave as if the client had sent value (sha1,ecdsa). 2092 Note: this is a change from TLS 1.1 where there are no explicit rules 2093 but as a practical matter one can assume that the peer supports MD5 2094 and SHA-1. 2096 Note: this extension is not meaningful for TLS versions prior to 1.2. 2097 Clients MUST NOT offer it if they are offering prior versions. 2098 However, even if clients do offer it, the rules specified in [TLSEXT] 2099 require servers to ignore extensions they do not understand. 2101 Servers MUST NOT send this extension. TLS servers MUST support 2102 receiving this extension. 2104 7.4.2. Server Certificate 2106 When this message will be sent: 2108 The server MUST send a certificate whenever the agreed-upon key 2109 exchange method uses certificates for authentication (this 2110 includes all key exchange methods defined in this document except 2111 DH_anon). This message will always immediately follow the server 2112 hello message. 2114 Meaning of this message: 2116 This message conveys the server's certificate chain to the client. 2117 The certificate MUST be appropriate for the negotiated cipher 2118 suite's key exchange algorithm, and any negotiated extensions. 2120 Structure of this message: 2122 opaque ASN.1Cert<1..2^24-1>; 2124 struct { 2125 ASN.1Cert certificate_list<0..2^24-1>; 2126 } Certificate; 2128 certificate_list 2129 This is a sequence (chain) of certificates. The sender's 2130 certificate MUST come first in the list. Each following 2131 certificate MUST directly certify the one preceding it. Because 2132 certificate validation requires that root keys be distributed 2133 independently, the self-signed certificate that specifies the root 2134 certificate authority MAY optionally be omitted from the chain, 2135 under the assumption that the remote end must already possess it 2136 in order to validate it in any case. 2138 The same message type and structure will be used for the client's 2139 response to a certificate request message. Note that a client MAY 2140 send no certificates if it does not have an appropriate certificate 2141 to send in response to the server's authentication request. 2143 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 2144 vector because PKCS #6 [PKCS6] extended certificates are not used. 2145 Also, PKCS #7 defines a SET rather than a SEQUENCE, making the task 2146 of parsing the list more difficult. 2148 The following rules apply to the certificates sent by the server: 2150 - The certificate type MUST be X.509v3, unless explicitly negotiated 2151 otherwise (e.g., [TLSPGP]). 2153 - The end entity certificate's public key (and associated 2154 restrictions) MUST be compatible with the selected key exchange 2155 algorithm. 2157 Key Exchange Alg. Certificate Key Type 2159 RSA RSA public key; the certificate MUST 2160 RSA_PSK allow the key to be used for encryption 2161 (the keyEncipherment bit MUST be set 2162 if the key usage extension is present). 2163 Note: RSA_PSK is defined in [TLSPSK]. 2165 DHE_RSA RSA public key; the certificate MUST 2166 ECDHE_RSA allow the key to be used for signing 2167 (the digitalSignature bit MUST be set 2168 if the key usage extension is present) 2169 with the signature scheme and hash 2170 algorithm that will be employed in the 2171 server key exchange message. 2173 DHE_DSS DSA public key; the certificate MUST 2174 allow the key to be used for signing with 2175 the hash algorithm that will be employed 2176 in the server key exchange message. 2178 DH_DSS Diffie-Hellman public key; the 2179 DH_RSA keyAgreement bit MUST be set if the 2180 key usage extension is present. 2182 ECDH_ECDSA ECDH-capable public key; the public key 2183 ECDH_RSA MUST use a curve and point format supported 2184 by the client, as described in [TLSECC]. 2186 ECDHE_ECDSA ECDSA-capable public key; the certificate 2187 MUST allow the key to be used for signing 2188 with the hash algorithm that will be 2189 employed in the server key exchange 2190 message. The public key MUST use a curve 2191 and point format supported by the client, 2192 as described in [TLSECC]. 2194 - The "server_name" and "trusted_ca_keys" extensions [4366bis] are 2195 used to guide certificate selection. 2197 If the client provided a "signature_algorithms" extension, then all 2198 certificates provided by the server MUST be signed by a 2199 hash/signature algorithm pair that appears in that extension. Note 2200 that this implies that a certificate containing a key for one 2201 signature algorithm MAY be signed using a different signature 2202 algorithm (for instance, an RSA key signed with a DSA key.) This is a 2203 departure from TLS 1.1, which required that the algorithms be the 2204 same. Note that this also implies that the DH_DSS, DH_RSA, 2205 ECDH_ECDSA, and ECDH_RSA key exchange algorithms do not restrict the 2206 algorithm used to sign the certificate. Fixed DH certificates MAY be 2207 signed with any hash/signature algorithm pair appearing in the 2208 extension. The naming is historical. 2210 If the server has multiple certificates, it chooses one of them based 2211 on the above-mentioned criteria (in addition to other criteria, such 2212 as transport layer endpoint, local configuration and preferences, 2213 etc.). If the server has a single certificate it SHOULD attempt to 2214 validate that it meets these criteria. 2216 Note that there are certificates that use algorithms and/or algorithm 2217 combinations that cannot be currently used with TLS. For example, a 2218 certificate with RSASSA-PSS signature key (id-RSASSA-PSS OID in 2219 SubjectPublicKeyInfo) cannot be used because TLS defines no 2220 corresponding signature algorithm. 2222 As cipher suites that specify new key exchange methods are specified 2223 for the TLS Protocol, they will imply certificate format and the 2224 required encoded keying information. 2226 7.4.3. Server Key Exchange Message 2228 When this message will be sent: 2230 This message will be sent immediately after the server certificate 2231 message (or the server hello message, if this is an anonymous 2232 negotiation). 2234 The server key exchange message is sent by the server only when 2235 the server certificate message (if sent) does not contain enough 2236 data to allow the client to exchange a premaster secret. This is 2237 true for the following key exchange methods: 2239 DHE_DSS 2240 DHE_RSA 2241 DH_anon 2243 It is not legal to send the server key exchange message for the 2244 following key exchange methods: 2246 RSA 2247 DH_DSS 2248 DH_RSA 2250 Meaning of this message: 2252 This message conveys cryptographic information to allow the client 2253 to communicate the premaster secret: a Diffie-Hellman public key 2254 with which the client can complete a key exchange (with the result 2255 being the premaster secret) or a public key for some other 2256 algorithm. 2258 Structure of this message: 2260 enum { diffie_hellman, rsa } KeyExchangeAlgorithm; 2262 struct { 2263 opaque dh_p<1..2^16-1>; 2264 opaque dh_g<1..2^16-1>; 2265 opaque dh_Ys<1..2^16-1>; 2266 } ServerDHParams; /* Ephemeral DH parameters */ 2268 dh_p 2269 The prime modulus used for the Diffie-Hellman operation. 2271 dh_g 2272 The generator used for the Diffie-Hellman operation. 2274 dh_Ys 2275 The server's Diffie-Hellman public value (g^X mod p). 2277 struct { 2278 select (KeyExchangeAlgorithm) { 2279 case diffie_hellman: 2280 ServerDHParams params; 2281 Signature signed_params; 2282 }; 2283 } ServerKeyExchange; 2285 struct { 2286 select (KeyExchangeAlgorithm) { 2287 case diffie_hellman: 2288 ServerDHParams params; 2289 }; 2290 } ServerParams; 2292 params 2293 The server's key exchange parameters. 2295 signed_params 2296 For non-anonymous key exchanges, a hash of the corresponding 2297 params value, with the signature appropriate to that hash 2298 applied. 2300 hash 2301 Hash(ClientHello.random + ServerHello.random + ServerParams) 2302 where Hash is the chosen hash value and Hash.length is 2303 its output. 2305 struct { 2306 select (SignatureAlgorithm) { 2307 case anonymous: struct { }; 2308 case rsa: 2309 SignatureAndHashAlgorithm signature_algorithm; /*NEW*/ 2310 digitally-signed struct { 2311 opaque hash[Hash.length]; 2312 }; 2313 case dsa: 2314 SignatureAndHashAlgorithm signature_algorithm; /*NEW*/ 2315 digitally-signed struct { 2316 opaque hash[Hash.length]; 2317 }; 2318 }; 2319 }; 2320 } Signature; 2322 If the client has offered the "signature_algorithms" extension, the 2323 signature algorithm and hash algorithm MUST be a pair listed in that 2324 extension. Note that there is a possibility for inconsistencies here. 2325 For instance, the client might offer DHE_DSS key exchange but omit 2326 any DSS pairs from its "signature_algorithms" extension. In order to 2327 negotiate correctly, the server MUST check any candidate cipher 2328 suites against the "signature_algorithms" extension before selecting 2329 them. This is somewhat inelegant but is a compromise designed to 2330 minimize changes to the original cipher suite design. 2332 In addition, the hash and signature algorithms MUST be compatible 2333 with the key in the server's end-entity certificate. RSA keys MAY be 2334 used with any permitted hash algorithm, subject to restrictions in 2335 the certificate, if any. 2337 Because DSA signatures do not contain any secure indication of hash 2338 algorithm, there is a risk of hash substitution if multiple hashes 2339 may be used with any key. Currently, DSS [DSS] may only be used with 2340 SHA-1. Future revisions of DSS [DSS-3] are expected to allow other 2341 digest algorithms, as well as guidance as to which digest algorithms 2342 should be used with each key size. In addition, future revisions of 2343 [PKIX] may specify mechanisms for certificates to indicate which 2344 digest algorithms are to be used with DSA. 2346 As additional cipher suites are defined for TLS that include new key 2347 exchange algorithms, the server key exchange message will be sent if 2348 and only if the certificate type associated with the key exchange 2349 algorithm does not provide enough information for the client to 2350 exchange a premaster secret. 2352 7.4.4. Certificate Request 2354 When this message will be sent: 2356 A non-anonymous server can optionally request a certificate from 2357 the client, if appropriate for the selected cipher suite. This 2358 message, if sent, will immediately follow the Server Key Exchange 2359 message (if it is sent; otherwise, the Server Certificate 2360 message). 2362 Structure of this message: 2364 enum { 2365 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 2366 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 2367 fortezza_dms_RESERVED(20), (255) 2368 } ClientCertificateType; 2370 opaque DistinguishedName<1..2^16-1>; 2372 struct { 2373 ClientCertificateType certificate_types<1..2^8-1>; 2374 SignatureAndHashAlgorithm 2375 supported_signature_algorithms<2^16-1>; 2376 DistinguishedName certificate_authorities<0..2^16-1>; 2377 } CertificateRequest; 2379 certificate_types 2380 A list of the types of certificate types which the client may 2381 offer. 2383 rsa_sign a certificate containing an RSA key 2384 dss_sign a certificate containing a DSS key 2385 rsa_fixed_dh a certificate containing a static DH key. 2386 dss_fixed_dh a certificate containing a static DH key 2388 supported_signature_algorithms 2389 A list of the hash/signature algorithm pairs that the server is 2390 able to verify, listed in descending order of preference. 2392 certificate_authorities 2393 A list of the distinguished names [X501] of acceptable 2394 certificate_authorities, represented in DER-encoded format. These 2395 distinguished names may specify a desired distinguished name for a 2396 root CA or for a subordinate CA; thus, this message can be used 2397 both to describe known roots and a desired authorization space. If 2398 the certificate_authorities list is empty then the client MAY send 2399 any certificate of the appropriate ClientCertificateType, unless 2400 there is some external arrangement to the contrary. 2402 The interaction of the certificate_types and 2403 supported_signature_algorithms fields is somewhat complicated. 2404 certificate_types has been present in TLS since SSLv3, but was 2405 somewhat underspecified. Much of its functionality is superseded by 2406 supported_signature_algorithms. The following rules apply: 2408 - Any certificates provided by the client MUST be signed using a 2409 hash/signature algorithm pair found in 2410 supported_signature_algorithms. 2412 - The end-entity certificate provided by the client MUST contain a 2413 key which is compatible with certificate_types. If the key is a 2414 signature key, it MUST be usable with some hash/signature 2415 algorithm pair in supported_signature_algorithms. 2417 - For historical reasons, the names of some client certificate types 2418 include the algorithm used to sign the certificate. For example, 2419 in earlier versions of TLS, rsa_fixed_dh meant a certificate 2420 signed with RSA and containing a static DH key. In TLS 1.2, this 2421 functionality has been obsoleted by the 2422 supported_signature_algorithms, and the certificate type no longer 2423 restricts the algorithm used to sign the certificate. For 2424 example, if the server sends dss_fixed_dh certificate type and 2425 {{sha1, dsa}, {sha1, rsa}} signature types, the client MAY reply 2426 with a certificate containing a static DH key, signed with RSA- 2427 SHA1. 2429 New ClientCertificateType values are assigned by IANA as described in 2430 Section 12. 2432 Note: Values listed as RESERVED may not be used. They were used in 2433 SSLv3. 2435 Note: It is a fatal handshake_failure alert for an anonymous server 2436 to request client authentication. 2438 7.4.5 Server hello done 2440 When this message will be sent: 2442 The server hello done message is sent by the server to indicate 2443 the end of the server hello and associated messages. After sending 2444 this message, the server will wait for a client response. 2446 Meaning of this message: 2448 This message means that the server is done sending messages to 2449 support the key exchange, and the client can proceed with its 2450 phase of the key exchange. 2452 Upon receipt of the server hello done message, the client SHOULD 2453 verify that the server provided a valid certificate, if required 2454 and check that the server hello parameters are acceptable. 2456 Structure of this message: 2458 struct { } ServerHelloDone; 2460 7.4.6. Client Certificate 2462 When this message will be sent: 2464 This is the first message the client can send after receiving a 2465 server hello done message. This message is only sent if the server 2466 requests a certificate. If no suitable certificate is available, 2467 the client MUST send a certificate message containing no 2468 certificates. That is, the certificate_list structure has a length 2469 of zero. If the client does not send any certificates, the server 2470 MAY at its discretion either continue the handshake without client 2471 authentication, or respond with a fatal handshake_failure alert. 2472 Also, if some aspect of the certificate chain was unacceptable 2473 (e.g., it was not signed by a known, trusted CA), the server MAY 2474 at its discretion either continue the handshake (considering the 2475 client unauthenticated) or send a fatal alert. 2477 Client certificates are sent using the Certificate structure 2478 defined in Section 7.4.2. 2480 Meaning of this message: 2482 This message conveys the client's certificate chain to the server; 2483 the server will use it when verifying the certificate verify 2484 message (when the client authentication is based on signing), or 2485 calculate the premaster secret (for non-ephemeral Diffie-Hellman). 2487 The certificate MUST be appropriate for the negotiated cipher 2488 suite's key exchange algorithm, and any negotiated extensions. 2490 In particular: 2492 - The certificate type MUST be X.509v3, unless explicitly negotiated 2493 otherwise (e.g. [TLSPGP]). 2495 - The end-entity certificate's public key (and associated 2496 restrictions) has to be compatible with the certificate types 2497 listed in CertificateRequest: 2499 Client Cert. Type Certificate Key Type 2501 rsa_sign RSA public key; the certificate MUST allow 2502 the key to be used for signing with the 2503 signature scheme and hash algorithm that 2504 will be employed in the certificate verify 2505 message. 2507 dss_sign DSA public key; the certificate MUST allow 2508 the key to be used for signing with the 2509 hash algorithm that will be employed in 2510 the certificate verify message. 2512 ecdsa_sign ECDSA-capable public key; the certificate 2513 MUST allow the key to be used for signing 2514 with the hash algorithm that will be 2515 employed in the certificate verify 2516 message; the public key MUST use a 2517 curve and point format supported by the 2518 server. 2520 rsa_fixed_dh Diffie-Hellman public key; MUST use 2521 dss_fixed_dh the same parameters as server's key. 2523 rsa_fixed_ecdh ECDH-capable public key; MUST use 2524 ecdsa_fixed_ecdh the same curve as server's key, and 2525 MUST use a point format supported by 2526 the server. 2528 - If the certificate_authorities list in the certificate request 2529 message was non-empty, one of the certificates in the certificate 2530 chain SHOULD be issued by one of the listed CAs. 2532 - The certificates MUST be signed using an acceptable hash/ 2533 signature algorithm pair, as described in Section 7.4.4. Note that 2534 this relaxes the constraints on certificate signing algorithms 2535 found in prior versions of TLS. 2537 Note that as with the server certificate, there are certificates that 2538 use algorithms/algorithm combinations that cannot be currently used 2539 with TLS. 2541 7.4.7. Client Key Exchange Message 2543 When this message will be sent: 2545 This message is always sent by the client. It MUST immediately 2546 follow the client certificate message, if it is sent. Otherwise it 2547 MUST be the first message sent by the client after it receives the 2548 server hello done message. 2550 Meaning of this message: 2552 With this message, the premaster secret is set, either though 2553 direct transmission of the RSA-encrypted secret, or by the 2554 transmission of Diffie-Hellman parameters that will allow each 2555 side to agree upon the same premaster secret. 2557 When the client is using an ephemeral Diffie-Hellman exponent, 2558 then this message contains the client's Diffie-Hellman public 2559 value. If the client is sending a certificate containing a static 2560 DH exponent (i.e., it is doing fixed_dh client authentication) 2561 then this message MUST be sent but MUST be empty. 2563 Structure of this message: 2565 The choice of messages depends on which key exchange method has 2566 been selected. See Section 7.4.3 for the KeyExchangeAlgorithm 2567 definition. 2569 struct { 2570 select (KeyExchangeAlgorithm) { 2571 case rsa: EncryptedPreMasterSecret; 2572 case diffie_hellman: ClientDiffieHellmanPublic; 2573 } exchange_keys; 2574 } ClientKeyExchange; 2576 7.4.7.1. RSA Encrypted Premaster Secret Message 2578 Meaning of this message: 2580 If RSA is being used for key agreement and authentication, the 2581 client generates a 48-byte premaster secret, encrypts it using the 2582 public key from the server's certificate and sends the result in 2583 an encrypted premaster secret message. This structure is a variant 2584 of the client key exchange message and is not a message in itself. 2586 Structure of this message: 2588 struct { 2589 ProtocolVersion client_version; 2590 opaque random[46]; 2591 } PreMasterSecret; 2593 client_version 2594 The latest (newest) version supported by the client. This is 2595 used to detect version roll-back attacks. 2597 random 2598 46 securely-generated random bytes. 2600 struct { 2601 public-key-encrypted PreMasterSecret pre_master_secret; 2602 } EncryptedPreMasterSecret; 2604 pre_master_secret 2605 This random value is generated by the client and is used to 2606 generate the master secret, as specified in Section 8.1. 2608 Note: The version number in the PreMasterSecret is the version 2609 offered by the client in the ClientHello.client_version, not the 2610 version negotiated for the connection. This feature is designed to 2611 prevent rollback attacks. Unfortunately, some old implementations 2612 use the negotiated version instead and therefore checking the version 2613 number may lead to failure to interoperate with such incorrect client 2614 implementations. 2616 Client implementations MUST always send the correct version number in 2617 PreMasterSecret. If ClientHello.client_version is TLS 1.1 or higher, 2618 server implementations MUST check the version number as described in 2619 the note below. If the version number is 1.0 or earlier, server 2620 implementations SHOULD check the version number, but MAY have a 2621 configuration option to disable the check. Note that if the check 2622 fails, the PreMasterSecret SHOULD be randomized as described below. 2624 Note: Attacks discovered by Bleichenbacher [BLEI] and Klima et al. 2625 [KPR03] can be used to attack a TLS server that reveals whether a 2626 particular message, when decrypted, is properly PKCS#1 formatted, 2627 contains a valid PreMasterSecret structure, or has the correct 2628 version number. 2630 The best way to avoid these vulnerabilities is to treat incorrectly 2631 formatted messages in a manner indistinguishable from correctly 2632 formatted RSA blocks. In other words: 2634 1. Generate a string R of 46 random bytes 2636 2. Decrypt the message M 2638 3. If the PKCS#1 padding is not correct, or the length of 2639 message M is not exactly 48 bytes: 2640 premaster secret = ClientHello.client_version || R 2641 else If ClientHello.client_version <= TLS 1.0, and 2642 version number check is explicitly disabled: 2643 premaster secret = M 2644 else: 2645 premaster secret = ClientHello.client_version || M[2..47] 2647 In any case, a TLS server MUST NOT generate an alert if processing an 2648 RSA-encrypted premaster secret message fails, or the version number 2649 is not as expected. Instead, it MUST continue the handshake with a 2650 randomly generated premaster secret. It may be useful to log the 2651 real cause of failure for troubleshooting purposes; however, care 2652 must be taken to avoid leaking the information to an attacker 2653 (through, e.g., timing, log files, or other channels.) 2655 The RSAES-OAEP encryption scheme defined in [PKCS1] is more secure 2656 against the Bleichenbacher attack. However, for maximal compatibility 2657 with earlier versions of TLS, this specification uses the RSAES- 2658 PKCS1-v1_5 scheme. No variants of the Bleichenbacher attack are known 2659 to exist provided that the above recommendations are followed. 2661 Implementation Note: Public-key-encrypted data is represented as an 2662 opaque vector <0..2^16-1> (see Section 4.7). Thus, the RSA-encrypted 2663 PreMasterSecret in a ClientKeyExchange is preceded by two length 2664 bytes. These bytes are redundant in the case of RSA because the 2665 EncryptedPreMasterSecret is the only data in the ClientKeyExchange 2666 and its length can therefore be unambiguously determined. The SSLv3 2667 specification was not clear about the encoding of public-key- 2668 encrypted data, and therefore many SSLv3 implementations do not 2669 include the the length bytes, encoding the RSA encrypted data 2670 directly in the ClientKeyExchange message. 2672 This specification requires correct encoding of the 2673 EncryptedPreMasterSecret complete with length bytes. The resulting 2674 PDU is incompatible with many SSLv3 implementations. Implementors 2675 upgrading from SSLv3 MUST modify their implementations to generate 2676 and accept the correct encoding. Implementors who wish to be 2677 compatible with both SSLv3 and TLS should make their implementation's 2678 behavior dependent on the protocol version. 2680 Implementation Note: It is now known that remote timing-based attacks 2681 on TLS are possible, at least when the client and server are on the 2682 same LAN. Accordingly, implementations that use static RSA keys MUST 2683 use RSA blinding or some other anti-timing technique, as described in 2684 [TIMING]. 2686 7.4.7.2. Client Diffie-Hellman Public Value 2688 Meaning of this message: 2690 This structure conveys the client's Diffie-Hellman public value 2691 (Yc) if it was not already included in the client's certificate. 2692 The encoding used for Yc is determined by the enumerated 2693 PublicValueEncoding. This structure is a variant of the client key 2694 exchange message, and not a message in itself. 2696 Structure of this message: 2698 enum { implicit, explicit } PublicValueEncoding; 2700 implicit 2701 If the client has sent a certificate which contains a suitable 2702 Diffie-Hellman key (for fixed_dh client authentication) then Yc 2703 is implicit and does not need to be sent again. In this case, 2704 the client key exchange message will be sent, but it MUST be 2705 empty. 2707 explicit 2708 Yc needs to be sent. 2710 struct { 2711 select (PublicValueEncoding) { 2712 case implicit: struct { }; 2713 case explicit: opaque dh_Yc<1..2^16-1>; 2714 } dh_public; 2715 } ClientDiffieHellmanPublic; 2717 dh_Yc 2718 The client's Diffie-Hellman public value (Yc). 2720 7.4.8. Certificate verify 2722 When this message will be sent: 2724 This message is used to provide explicit verification of a client 2725 certificate. This message is only sent following a client 2726 certificate that has signing capability (i.e. all certificates 2727 except those containing fixed Diffie-Hellman parameters). When 2728 sent, it MUST immediately follow the client key exchange message. 2730 Structure of this message: 2732 struct { 2733 SignatureAndHashAlgorithm signature_algorithm; 2734 digitally-signed struct { 2735 opaque handshake_messages[handshake_messages_length]; 2736 } 2737 } CertificateVerify; 2739 Here handshake_messages refers to all handshake messages sent or 2740 received starting at client hello up to but not including this 2741 message, including the type and length fields of the handshake 2742 messages. This is the concatenation of all the Handshake 2743 structures as defined in 7.4 exchanged thus far. Note that this 2744 requires both sides to either buffer the messages or compute 2745 running hashes for all potential hash algorithms up to the time of 2746 the CertificateVerify computation. Servers can minimize this 2747 computation cost by offering a restricted set of digest algorithms 2748 in the CertificateRequest message. 2750 The hash and signature algorithms used in the signature MUST be 2751 one of those present in the supported_signature_algorithms field 2752 of the CertificateRequest message. In addition, the hash and 2753 signature algorithms MUST be compatible with the key in the 2754 client's end-entity certificate. RSA keys MAY be used with any 2755 permitted hash algorith, subject to restrictions in the 2756 certificate, if any. 2758 Because DSA signatures do not contain any secure indication of 2759 hash algorithm, there is a risk of hash substitution if multiple 2760 hashes may be used with any key. Currently, DSS [DSS] may only be 2761 used with SHA-1. Future revisions of DSS [DSS-3] are expected to 2762 allow other digest algorithms, as well as guidance as to which 2763 digest algorithms should be used with each key size. In addition, 2764 future revisions of [PKIX] may specify mechanisms for certificates 2765 to indicate which digest algorithms are to be used with DSA. 2767 7.4.9. Finished 2769 When this message will be sent: 2771 A finished message is always sent immediately after a change 2772 cipher spec message to verify that the key exchange and 2773 authentication processes were successful. It is essential that a 2774 change cipher spec message be received between the other handshake 2775 messages and the Finished message. 2777 Meaning of this message: 2779 The finished message is the first protected with the just- 2780 negotiated algorithms, keys, and secrets. Recipients of finished 2781 messages MUST verify that the contents are correct. Once a side 2782 has sent its Finished message and received and validated the 2783 Finished message from its peer, it may begin to send and receive 2784 application data over the connection. 2786 Structure of this message: 2788 struct { 2789 opaque verify_data[verify_data_length]; 2790 } Finished; 2792 verify_data 2793 PRF(master_secret, finished_label, Hash(handshake_messages)) 2794 [0..verify_data_length-1]; 2796 finished_label 2797 For Finished messages sent by the client, the string "client 2798 finished". For Finished messages sent by the server, the string 2799 "server finished". 2801 Hash denotes a Hash of the handshake messages. For the PRF defined 2802 in Section 5, the Hash MUST be the Hash used as the basis for the 2803 PRF. Any cipher suite which defines a different PRF MUST also 2804 define the Hash to use in the Finished computation. 2806 In previous versions of TLS, the verify_data was always 12 octets 2807 long. In the current version of TLS, it depends on the cipher 2808 suite. Any cipher suite which does not explicitly specify 2809 verify_data_length has a verify_data_length equal to 12. This 2810 includes all existing cipher suites. Note that this 2811 representation has the same encoding as with previous versions. 2812 Future cipher suites MAY specify other lengths but such length 2813 MUST be at least 12 bytes. 2815 handshake_messages 2816 All of the data from all messages in this handshake (not 2817 including any HelloRequest messages) up to but not including 2818 this message. This is only data visible at the handshake layer 2819 and does not include record layer headers. This is the 2820 concatenation of all the Handshake structures as defined in 2821 7.4, exchanged thus far. 2823 It is a fatal error if a finished message is not preceded by a change 2824 cipher spec message at the appropriate point in the handshake. 2826 The value handshake_messages includes all handshake messages starting 2827 at client hello up to, but not including, this finished message. This 2828 may be different from handshake_messages in Section 7.4.8 because it 2829 would include the certificate verify message (if sent). Also, the 2830 handshake_messages for the finished message sent by the client will 2831 be different from that for the finished message sent by the server, 2832 because the one that is sent second will include the prior one. 2834 Note: Change cipher spec messages, alerts, and any other record types 2835 are not handshake messages and are not included in the hash 2836 computations. Also, Hello Request messages are omitted from handshake 2837 hashes. 2839 8. Cryptographic Computations 2841 In order to begin connection protection, the TLS Record Protocol 2842 requires specification of a suite of algorithms, a master secret, and 2843 the client and server random values. The authentication, encryption, 2844 and MAC algorithms are determined by the cipher_suite selected by the 2845 server and revealed in the server hello message. The compression 2846 algorithm is negotiated in the hello messages, and the random values 2847 are exchanged in the hello messages. All that remains is to calculate 2848 the master secret. 2850 8.1. Computing the Master Secret 2852 For all key exchange methods, the same algorithm is used to convert 2853 the pre_master_secret into the master_secret. The pre_master_secret 2854 should be deleted from memory once the master_secret has been 2855 computed. 2857 master_secret = PRF(pre_master_secret, "master secret", 2858 ClientHello.random + ServerHello.random) 2859 [0..47]; 2861 The master secret is always exactly 48 bytes in length. The length of 2862 the premaster secret will vary depending on key exchange method. 2864 8.1.1. RSA 2866 When RSA is used for server authentication and key exchange, a 2867 48-byte pre_master_secret is generated by the client, encrypted under 2868 the server's public key, and sent to the server. The server uses its 2869 private key to decrypt the pre_master_secret. Both parties then 2870 convert the pre_master_secret into the master_secret, as specified 2871 above. 2873 8.1.2. Diffie-Hellman 2875 A conventional Diffie-Hellman computation is performed. The 2876 negotiated key (Z) is used as the pre_master_secret, and is converted 2877 into the master_secret, as specified above. Leading bytes of Z that 2878 contain all zero bits are stripped before it is used as the 2879 pre_master_secret. 2881 Note: Diffie-Hellman parameters are specified by the server and may 2882 be either ephemeral or contained within the server's certificate. 2884 9. Mandatory Cipher Suites 2886 In the absence of an application profile standard specifying 2887 otherwise, a TLS compliant application MUST implement the cipher 2888 suite TLS_RSA_WITH_AES_128_CBC_SHA. 2890 10. Application Data Protocol 2892 Application data messages are carried by the Record Layer and are 2893 fragmented, compressed, and encrypted based on the current connection 2894 state. The messages are treated as transparent data to the record 2895 layer. 2897 11. Security Considerations 2899 Security issues are discussed throughout this memo, especially in 2900 Appendices D, E, and F. 2902 12. IANA Considerations 2904 This document uses several registries that were originally created in 2905 [TLS1.1]. IANA is requested to update (has updated) these to 2906 reference this document. The registries and their allocation policies 2907 (unchanged from [TLS1.1]) are listed below. 2909 - TLS ClientCertificateType Identifiers Registry: Future values in 2910 the range 0-63 (decimal) inclusive are assigned via Standards 2911 Action [RFC2434]. Values in the range 64-223 (decimal) inclusive 2912 are assigned Specification Required [RFC2434]. Values from 224-255 2913 (decimal) inclusive are reserved for Private Use [RFC2434]. 2915 - TLS Cipher Suite Registry: Future values with the first byte in the 2916 range 0-191 (decimal) inclusive are assigned via Standards Action 2917 [RFC2434]. Values with the first byte in the range 192-254 2918 (decimal) are assigned via Specification Required [RFC2434]. 2919 Values with the first byte 255 (decimal) are reserved for Private 2920 Use [RFC2434]. This document defines several new HMAC-SHA256 based 2921 cipher suites, whose values (in Appendix A.5) are to be (have 2922 been) allocated from the TLS Cipher Suite registry. 2924 - TLS ContentType Registry: Future values are allocated via 2925 Standards Action [RFC2434]. 2927 - TLS Alert Registry: Future values are allocated via Standards 2928 Action [RFC2434]. 2930 - TLS HandshakeType Registry: Future values are allocated via 2931 Standards Action [RFC2434]. 2933 This document also uses a registry originally created in [RFC4366]. 2934 IANA is requested to update (has updated) it to reference this 2935 document. The registry and its allocation policy (unchanged from 2936 [RFC4366]) is listed below: 2938 - TLS ExtensionType Registry: Future values are allocated via IETF 2939 Consensus [RFC2434] 2941 In addition, this document defines two new registries to be 2942 maintained by IANA: 2944 - TLS SignatureAlgorithm Registry: The registry will be initially 2945 populated with the values described in Section 7.4.1.4.1. Future 2946 values in the range 0-63 (decimal) inclusive are assigned via 2947 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 2948 inclusive are assigned via Specification Required [RFC2434]. 2949 Values from 224-255 (decimal) inclusive are reserved for Private 2950 Use [RFC2434]. 2952 - TLS HashAlgorithm Registry: The registry will be initially 2953 populated with the values described in Section 7.4.1.4.1. Future 2954 values in the range 0-63 (decimal) inclusive are assigned via 2955 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 2956 inclusive are assigned via Specification Required [RFC2434]. 2957 Values from 224-255 (decimal) inclusive are reserved for Private 2958 Use [RFC2434]. 2960 This document defines one new TLS extension, signature_algorithms, 2961 which is to be (has been) allocated value TBD-BY-IANA in the TLS 2962 ExtensionType registry. 2964 This document also uses the TLS Compression Method Identifiers 2965 Registry, defined in [RFC3749]. IANA is requested to allocate value 2966 0 for the "null" compression method. 2968 Appendix A. Protocol Constant Values 2970 This section describes protocol types and constants. 2972 A.1. Record Layer 2974 struct { 2975 uint8 major; 2976 uint8 minor; 2977 } ProtocolVersion; 2979 ProtocolVersion version = { 3, 3 }; /* TLS v1.2*/ 2981 enum { 2982 change_cipher_spec(20), alert(21), handshake(22), 2983 application_data(23), (255) 2984 } ContentType; 2986 struct { 2987 ContentType type; 2988 ProtocolVersion version; 2989 uint16 length; 2990 opaque fragment[TLSPlaintext.length]; 2991 } TLSPlaintext; 2993 struct { 2994 ContentType type; 2995 ProtocolVersion version; 2996 uint16 length; 2997 opaque fragment[TLSCompressed.length]; 2998 } TLSCompressed; 3000 struct { 3001 ContentType type; 3002 ProtocolVersion version; 3003 uint16 length; 3004 select (SecurityParameters.cipher_type) { 3005 case stream: GenericStreamCipher; 3006 case block: GenericBlockCipher; 3007 case aead: GenericAEADCipher; 3008 } fragment; 3009 } TLSCiphertext; 3011 stream-ciphered struct { 3012 opaque content[TLSCompressed.length]; 3013 opaque MAC[SecurityParameters.mac_length]; 3014 } GenericStreamCipher; 3015 struct { 3016 opaque IV[SecurityParameters.record_iv_length]; 3017 block-ciphered struct { 3018 opaque content[TLSCompressed.length]; 3019 opaque MAC[SecurityParameters.mac_length]; 3020 uint8 padding[GenericBlockCipher.padding_length]; 3021 uint8 padding_length; 3022 }; 3023 } GenericBlockCipher; 3025 aead-ciphered struct { 3026 opaque IV[SecurityParameters.record_iv_length]; 3027 opaque aead_output[AEADEncrypted.length]; 3028 } GenericAEADCipher; 3030 A.2. Change Cipher Specs Message 3032 struct { 3033 enum { change_cipher_spec(1), (255) } type; 3034 } ChangeCipherSpec; 3036 A.3. Alert Messages 3038 enum { warning(1), fatal(2), (255) } AlertLevel; 3040 enum { 3041 close_notify(0), 3042 unexpected_message(10), 3043 bad_record_mac(20), 3044 decryption_failed_RESERVED(21), 3045 record_overflow(22), 3046 decompression_failure(30), 3047 handshake_failure(40), 3048 no_certificate_RESERVED(41), 3049 bad_certificate(42), 3050 unsupported_certificate(43), 3051 certificate_revoked(44), 3052 certificate_expired(45), 3053 certificate_unknown(46), 3054 illegal_parameter(47), 3055 unknown_ca(48), 3056 access_denied(49), 3057 decode_error(50), 3058 decrypt_error(51), 3059 export_restriction_RESERVED(60), 3060 protocol_version(70), 3061 insufficient_security(71), 3062 internal_error(80), 3063 user_canceled(90), 3064 no_renegotiation(100), 3065 unsupported_extension(110), /* new */ 3066 (255) 3067 } AlertDescription; 3069 struct { 3070 AlertLevel level; 3071 AlertDescription description; 3072 } Alert; 3074 A.4. Handshake Protocol 3076 enum { 3077 hello_request(0), client_hello(1), server_hello(2), 3078 certificate(11), server_key_exchange (12), 3079 certificate_request(13), server_hello_done(14), 3080 certificate_verify(15), client_key_exchange(16), 3081 finished(20) 3082 (255) 3083 } HandshakeType; 3085 struct { 3086 HandshakeType msg_type; 3087 uint24 length; 3088 select (HandshakeType) { 3089 case hello_request: HelloRequest; 3090 case client_hello: ClientHello; 3091 case server_hello: ServerHello; 3092 case certificate: Certificate; 3093 case server_key_exchange: ServerKeyExchange; 3094 case certificate_request: CertificateRequest; 3095 case server_hello_done: ServerHelloDone; 3096 case certificate_verify: CertificateVerify; 3097 case client_key_exchange: ClientKeyExchange; 3098 case finished: Finished; 3099 } body; 3100 } Handshake; 3102 A.4.1. Hello Messages 3104 struct { } HelloRequest; 3106 struct { 3107 uint32 gmt_unix_time; 3108 opaque random_bytes[28]; 3109 } Random; 3110 opaque SessionID<0..32>; 3112 uint8 CipherSuite[2]; 3114 enum { null(0), (255) } CompressionMethod; 3116 struct { 3117 ProtocolVersion client_version; 3118 Random random; 3119 SessionID session_id; 3120 CipherSuite cipher_suites<2..2^16-2>; 3121 CompressionMethod compression_methods<1..2^8-1>; 3122 select (extensions_present) { 3123 case false: 3124 struct {}; 3125 case true: 3126 Extension extensions<0..2^16-1>; 3127 }; 3128 } ClientHello; 3130 struct { 3131 ProtocolVersion server_version; 3132 Random random; 3133 SessionID session_id; 3134 CipherSuite cipher_suite; 3135 CompressionMethod compression_method; 3136 select (extensions_present) { 3137 case false: 3138 struct {}; 3139 case true: 3140 Extension extensions<0..2^16-1>; 3141 }; 3142 } ServerHello; 3144 struct { 3145 ExtensionType extension_type; 3146 opaque extension_data<0..2^16-1>; 3147 } Extension; 3149 enum { 3150 signature_algorithms(TBD-BY-IANA), (65535) 3151 } ExtensionType; 3153 enum{ 3154 none(0), md5(1), sha1(2), sha256(3), sha384(4), 3155 sha512(5), (255) 3156 } HashAlgorithm; 3157 enum { anonymous(0), rsa(1), dsa(2), (255) } SignatureAlgorithm; 3159 struct { 3160 HashAlgorithm hash; 3161 SignatureAlgorithm signature; 3162 } SignatureAndHashAlgorithm; 3164 SignatureAndHashAlgorithm 3165 supported_signature_algorithms<2..2^16-1>; 3167 A.4.2. Server Authentication and Key Exchange Messages 3169 opaque ASN.1Cert<2^24-1>; 3171 struct { 3172 ASN.1Cert certificate_list<0..2^24-1>; 3173 } Certificate; 3175 enum { rsa, diffie_hellman } KeyExchangeAlgorithm; 3177 struct { 3178 opaque dh_p<1..2^16-1>; 3179 opaque dh_g<1..2^16-1>; 3180 opaque dh_Ys<1..2^16-1>; 3181 } ServerDHParams; 3183 struct { 3184 select (KeyExchangeAlgorithm) { 3185 case diffie_hellman: 3186 ServerDHParams params; 3187 Signature signed_params; 3188 } 3189 } ServerKeyExchange; 3191 struct { 3192 select (KeyExchangeAlgorithm) { 3193 case diffie_hellman: 3194 ServerDHParams params; 3195 }; 3196 } ServerParams; 3198 struct { 3199 select (SignatureAlgorithm) { 3200 case anonymous: struct { }; 3201 case rsa: 3202 SignatureAndHashAlgorithm signature_algorithm; /*NEW*/ 3203 digitally-signed struct { 3204 opaque hash[Hash.length]; 3206 }; 3207 case dsa: 3208 SignatureAndHashAlgorithm signature_algorithm; /*NEW*/ 3209 digitally-signed struct { 3210 opaque hash[Hash.length]; 3211 }; 3212 }; 3213 }; 3214 } Signature; 3216 enum { 3217 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 3218 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 3219 fortezza_dms_RESERVED(20), 3220 (255) 3221 } ClientCertificateType; 3223 opaque DistinguishedName<1..2^16-1>; 3225 struct { 3226 ClientCertificateType certificate_types<1..2^8-1>; 3227 DistinguishedName certificate_authorities<0..2^16-1>; 3228 } CertificateRequest; 3230 struct { } ServerHelloDone; 3232 A.4.3. Client Authentication and Key Exchange Messages 3234 struct { 3235 select (KeyExchangeAlgorithm) { 3236 case rsa: EncryptedPreMasterSecret; 3237 case diffie_hellman: ClientDiffieHellmanPublic; 3238 } exchange_keys; 3239 } ClientKeyExchange; 3241 struct { 3242 ProtocolVersion client_version; 3243 opaque random[46]; 3244 } PreMasterSecret; 3246 struct { 3247 public-key-encrypted PreMasterSecret pre_master_secret; 3248 } EncryptedPreMasterSecret; 3250 enum { implicit, explicit } PublicValueEncoding; 3252 struct { 3253 select (PublicValueEncoding) { 3254 case implicit: struct {}; 3255 case explicit: opaque DH_Yc<1..2^16-1>; 3256 } dh_public; 3257 } ClientDiffieHellmanPublic; 3259 struct { 3260 Signature signature; 3261 } CertificateVerify; 3263 A.4.4. Handshake Finalization Message 3265 struct { 3266 opaque verify_data[verify_data_length]; 3267 } Finished; 3269 A.5. The Cipher Suite 3271 The following values define the cipher suite codes used in the client 3272 hello and server hello messages. 3274 A cipher suite defines a cipher specification supported in TLS 3275 Version 1.2. 3277 TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a 3278 TLS connection during the first handshake on that channel, but MUST 3279 not be negotiated, as it provides no more protection than an 3280 unsecured connection. 3282 CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 }; 3284 The following CipherSuite definitions require that the server provide 3285 an RSA certificate that can be used for key exchange. The server may 3286 request any signature-capable certificate in the certificate request 3287 message. 3289 CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 }; 3290 CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 }; 3291 CipherSuite TLS_RSA_WITH_NULL_SHA256 = { 0x00,TBD1 }; 3292 CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 }; 3293 CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 }; 3294 CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A }; 3295 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x2F }; 3296 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x35 }; 3297 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,TBD2 }; 3298 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,TBD3 }; 3300 The following cipher suite definitions are used for server- 3301 authenticated (and optionally client-authenticated) Diffie-Hellman. 3302 DH denotes cipher suites in which the server's certificate contains 3303 the Diffie-Hellman parameters signed by the certificate authority 3304 (CA). DHE denotes ephemeral Diffie-Hellman, where the Diffie-Hellman 3305 parameters are signed by a a signature-capable certificate, which has 3306 been signed by the CA. The signing algorithm used by the server is 3307 specified after the DHE parameter. The server can request any 3308 signature-capable certificate from the client for client 3309 authentication or it may request a Diffie-Hellman certificate. Any 3310 Diffie-Hellman certificate provided by the client must use the 3311 parameters (group and generator) described by the server. 3313 CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D }; 3314 CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 }; 3315 CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 }; 3316 CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 }; 3317 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x30 }; 3318 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x31 }; 3319 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x32 }; 3320 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x33 }; 3321 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x36 }; 3322 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x37 }; 3323 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x38 }; 3324 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x39 }; 3325 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA256 = { 0x00, TBD4 }; 3326 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA256 = { 0x00, TBD5 }; 3327 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 = { 0x00, TBD6 }; 3328 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 = { 0x00, TBD7 }; 3329 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA256 = { 0x00, TBD8 }; 3330 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA256 = { 0x00, TBD9 }; 3331 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 = { 0x00, TBD10 }; 3332 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 = { 0x00, TBD11 }; 3334 The following cipher suites are used for completely anonymous Diffie- 3335 Hellman communications in which neither party is authenticated. Note 3336 that this mode is vulnerable to man-in-the-middle attacks. Using 3337 this mode therefore is of limited use: These cipher suites MUST NOT 3338 be used by TLS 1.2 implementations unless the application layer has 3339 specifically requested to allow anonymous key exchange. (Anonymous 3340 key exchange may sometimes be acceptable, for example, to support 3341 opportunistic encryption when no set-up for authentication is in 3342 place, or when TLS is used as part of more complex security protocols 3343 that have other means to ensure authentication.) 3345 CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 }; 3346 CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B }; 3347 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA = { 0x00,0x34 }; 3348 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA = { 0x00,0x3A }; 3349 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA256 = { 0x00, TBD12 }; 3350 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA256 = { 0x00, TBD13 }; 3352 Note that using non-anonymous key exchange without actually verifying 3353 the key exchange is essentially equivalent to anonymous key exchange, 3354 and the same precautions apply. While non-anonymous key exchange 3355 will generally involve a higher computational and communicational 3356 cost than anonymous key exchange, it may be in the interest of 3357 interoperability not to disable non-anonymous key exchange when the 3358 application layer is allowing anonymous key exchange. 3360 SSLv3, TLS 1.0, and TLS 1.1 supported DES and IDEA. DES had a 56-bit 3361 key which is too weak for modern use. Triple-DES (3DES) has an 3362 effective key strength of 112 bits and is still acceptable. IDEA and 3363 is no longer in wide use. Cipher suites using RC2, DES, and IDEA are 3364 hereby deprecated for TLS 1.2. TLS 1.2 implementations MUST NOT 3365 negotiate these cipher suites in TLS 1.2 mode. However, for backward 3366 compatibility they may be offered in the ClientHello for use with TLS 3367 1.0 or SSLv3 only servers. TLS 1.2 clients MUST check that the server 3368 did not choose one of these cipher suites during the handshake. These 3369 cipher suites are listed below for informational purposes and to 3370 reserve the numbers. 3372 CipherSuite TLS_RSA_WITH_IDEA_CBC_SHA = { 0x00,0x07 }; 3373 CipherSuite TLS_RSA_WITH_DES_CBC_SHA = { 0x00,0x09 }; 3374 CipherSuite TLS_DH_DSS_WITH_DES_CBC_SHA = { 0x00,0x0C }; 3375 CipherSuite TLS_DH_RSA_WITH_DES_CBC_SHA = { 0x00,0x0F }; 3376 CipherSuite TLS_DHE_RSA_WITH_DES_CBC_SHA = { 0x00,0x15 }; 3377 CipherSuite TLS_DHE_DSS_WITH_DES_CBC_SHA = { 0x00,0x12 }; 3378 CipherSuite TLS_DH_anon_WITH_DES_CBC_SHA = { 0x00,0x1A }; 3380 When SSLv3 and TLS 1.0 were designed, the United States restricted 3381 the export of cryptographic software containing certain strong 3382 encryption algorithms. A series of cipher suites were designed to 3383 operate at reduced key lengths in order to comply with those 3384 regulations. Due to advances in computer performance, these 3385 algorithms are now unacceptably weak and export restrictions have 3386 since been loosened. TLS 1.2 implementations MUST NOT negotiate these 3387 cipher suites in TLS 1.2 mode. However, for backward compatibility 3388 they may be offered in the ClientHello for use with TLS 1.0 or SSLv3 3389 only servers. TLS 1.2 clients MUST check that the server did not 3390 choose one of these cipher suites during the handshake. These 3391 ciphersuites are listed below for informational purposes and to 3392 reserve the numbers. 3394 CipherSuite TLS_RSA_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x03 }; 3395 CipherSuite TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = { 0x00,0x06 }; 3396 CipherSuite TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x08 }; 3397 CipherSuite TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0B }; 3398 CipherSuite TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0E }; 3399 CipherSuite TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x11 }; 3400 CipherSuite TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x14 }; 3401 CipherSuite TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x17 }; 3402 CipherSuite TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x19 }; 3404 New cipher suite values are assigned by IANA as described in Section 3405 12. 3407 Note: The cipher suite values { 0x00, 0x1C } and { 0x00, 0x1D } are 3408 reserved to avoid collision with Fortezza-based cipher suites in SSL 3409 3. 3411 A.6. The Security Parameters 3413 These security parameters are determined by the TLS Handshake 3414 Protocol and provided as parameters to the TLS Record Layer in order 3415 to initialize a connection state. SecurityParameters includes: 3417 enum { null(0), (255) } CompressionMethod; 3419 enum { server, client } ConnectionEnd; 3421 enum { tls_prf_sha256 } PRFAlgorithm; 3423 enum { null, rc4, 3des, aes } 3424 BulkCipherAlgorithm; 3426 enum { stream, block, aead } CipherType; 3428 enum { null, hmac_md5, hmac_sha, hmac_sha256, hmac_sha384, 3429 hmac_sha512} MACAlgorithm; 3431 /* The algorithms specified in CompressionMethod, 3432 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 3434 struct { 3435 ConnectionEnd entity; 3436 PRFAlgorithm prf_algorithm; 3437 BulkCipherAlgorithm bulk_cipher_algorithm; 3438 CipherType cipher_type; 3439 uint8 enc_key_length; 3440 uint8 block_length; 3441 uint8 fixed_iv_length; 3442 uint8 record_iv_length; 3443 MACAlgorithm mac_algorithm; 3444 uint8 mac_length; 3445 uint8 mac_key_length; 3446 CompressionMethod compression_algorithm; 3447 opaque master_secret[48]; 3448 opaque client_random[32]; 3449 opaque server_random[32]; 3450 } SecurityParameters; 3452 Appendix B. Glossary 3454 Advanced Encryption Standard (AES) 3455 AES is a widely used symmetric encryption algorithm. AES is a 3456 block cipher with a 128, 192, or 256 bit keys and a 16 byte block 3457 size. [AES] TLS currently only supports the 128 and 256 bit key 3458 sizes. 3460 application protocol 3461 An application protocol is a protocol that normally layers 3462 directly on top of the transport layer (e.g., TCP/IP). Examples 3463 include HTTP, TELNET, FTP, and SMTP. 3465 asymmetric cipher 3466 See public key cryptography. 3468 authenticated encryption with additional data (AEAD) 3469 A symmetric encryption algorithm that simultaneously provides 3470 confidentiality and message integrity. 3472 authentication 3473 Authentication is the ability of one entity to determine the 3474 identity of another entity. 3476 block cipher 3477 A block cipher is an algorithm that operates on plaintext in 3478 groups of bits, called blocks. 64 bits is a common block size. 3480 bulk cipher 3481 A symmetric encryption algorithm used to encrypt large quantities 3482 of data. 3484 cipher block chaining (CBC) 3485 CBC is a mode in which every plaintext block encrypted with a 3486 block cipher is first exclusive-ORed with the previous ciphertext 3487 block (or, in the case of the first block, with the initialization 3488 vector). For decryption, every block is first decrypted, then 3489 exclusive-ORed with the previous ciphertext block (or IV). 3491 certificate 3492 As part of the X.509 protocol (a.k.a. ISO Authentication 3493 framework), certificates are assigned by a trusted Certificate 3494 Authority and provide a strong binding between a party's identity 3495 or some other attributes and its public key. 3497 client 3498 The application entity that initiates a TLS connection to a 3499 server. This may or may not imply that the client initiated the 3500 underlying transport connection. The primary operational 3501 difference between the server and client is that the server is 3502 generally authenticated, while the client is only optionally 3503 authenticated. 3505 client write key 3506 The key used to encrypt data written by the client. 3508 client write MAC key 3509 The secret data used to authenticate data written by the client. 3511 connection 3512 A connection is a transport (in the OSI layering model definition) 3513 that provides a suitable type of service. For TLS, such 3514 connections are peer-to-peer relationships. The connections are 3515 transient. Every connection is associated with one session. 3517 Data Encryption Standard 3518 DES is a very widely used symmetric encryption algorithm. DES is a 3519 block cipher with a 56 bit key and an 8 byte block size. Note that 3520 in TLS, for key generation purposes, DES is treated as having an 8 3521 byte key length (64 bits), but it still only provides 56 bits of 3522 protection. (The low bit of each key byte is presumed to be set to 3523 produce odd parity in that key byte.) DES can also be operated in 3524 a mode where three independent keys and three encryptions are used 3525 for each block of data; this uses 168 bits of key (24 bytes in the 3526 TLS key generation method) and provides the equivalent of 112 bits 3527 of security. [DES], [3DES] 3529 Digital Signature Standard (DSS) 3530 A standard for digital signing, including the Digital Signing 3531 Algorithm, approved by the National Institute of Standards and 3532 Technology, defined in NIST FIPS PUB 186, "Digital Signature 3533 Standard", published May, 1994 by the U.S. Dept. of Commerce. 3534 [DSS] 3536 digital signatures 3537 Digital signatures utilize public key cryptography and one-way 3538 hash functions to produce a signature of the data that can be 3539 authenticated, and is difficult to forge or repudiate. 3541 handshake 3542 An initial negotiation between client and server that establishes 3543 the parameters of their transactions. 3545 Initialization Vector (IV) 3546 When a block cipher is used in CBC mode, the initialization vector 3547 is exclusive-ORed with the first plaintext block prior to 3548 encryption. 3550 IDEA 3551 A 64-bit block cipher designed by Xuejia Lai and James Massey. 3552 [IDEA] 3554 Message Authentication Code (MAC) 3555 A Message Authentication Code is a one-way hash computed from a 3556 message and some secret data. It is difficult to forge without 3557 knowing the secret data. Its purpose is to detect if the message 3558 has been altered. 3560 master secret 3561 Secure secret data used for generating encryption keys, MAC 3562 secrets, and IVs. 3564 MD5 3565 MD5 is a secure hashing function that converts an arbitrarily long 3566 data stream into a hash of fixed size (16 bytes). [MD5] 3568 public key cryptography 3569 A class of cryptographic techniques employing two-key ciphers. 3570 Messages encrypted with the public key can only be decrypted with 3571 the associated private key. Conversely, messages signed with the 3572 private key can be verified with the public key. 3574 one-way hash function 3575 A one-way transformation that converts an arbitrary amount of data 3576 into a fixed-length hash. It is computationally hard to reverse 3577 the transformation or to find collisions. MD5 and SHA are examples 3578 of one-way hash functions. 3580 RC2 3581 A block cipher developed by Ron Rivest, described in [RC2]. 3583 RC4 3584 A stream cipher invented by Ron Rivest. A compatible cipher is 3585 described in [SCH]. 3587 RSA 3588 A very widely used public-key algorithm that can be used for 3589 either encryption or digital signing. [RSA] 3591 server 3592 The server is the application entity that responds to requests for 3593 connections from clients. See also under client. 3595 session 3596 A TLS session is an association between a client and a server. 3597 Sessions are created by the handshake protocol. Sessions define a 3598 set of cryptographic security parameters that can be shared among 3599 multiple connections. Sessions are used to avoid the expensive 3600 negotiation of new security parameters for each connection. 3602 session identifier 3603 A session identifier is a value generated by a server that 3604 identifies a particular session. 3606 server write key 3607 The key used to encrypt data written by the server. 3609 server write MAC key 3610 The secret data used to authenticate data written by the server. 3612 SHA 3613 The Secure Hash Algorithm is defined in FIPS PUB 180-2. It 3614 produces a 20-byte output. Note that all references to SHA 3615 actually use the modified SHA-1 algorithm. [SHA] 3617 SHA-256 3618 The 256-bit Secure Hash Algorithm is defined in FIPS PUB 180-2. It 3619 produces a 32-byte output. 3621 SSL 3622 Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on 3623 SSL Version 3.0 3625 stream cipher 3626 An encryption algorithm that converts a key into a 3627 cryptographically strong keystream, which is then exclusive-ORed 3628 with the plaintext. 3630 symmetric cipher 3631 See bulk cipher. 3633 Transport Layer Security (TLS) 3634 This protocol; also, the Transport Layer Security working group of 3635 the Internet Engineering Task Force (IETF). See "Comments" at the 3636 end of this document. 3638 Appendix C. Cipher Suite Definitions 3640 Cipher Suite Key Cipher Mac 3641 Exchange 3643 TLS_NULL_WITH_NULL_NULL NULL NULL NULL 3644 TLS_RSA_WITH_NULL_MD5 RSA NULL MD5 3645 TLS_RSA_WITH_NULL_SHA RSA NULL SHA 3646 TLS_RSA_WITH_NULL_SHA256 RSA NULL SHA256 3647 TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5 3648 TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA 3649 TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA 3650 TLS_RSA_WITH_AES_128_CBC_SHA RSA AES_128_CBC SHA 3651 TLS_RSA_WITH_AES_256_CBC_SHA RSA AES_256_CBC SHA 3652 TLS_RSA_WITH_AES_128_CBC_SHA256 RSA AES_128_CBC SHA256 3653 TLS_RSA_WITH_AES_256_CBC_SHA256 RSA AES_256_CBC SHA256 3654 TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA 3655 TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA 3656 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA 3657 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA 3658 TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5 3659 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA 3660 TLS_DH_DSS_WITH_AES_128_CBC_SHA DH_DSS AES_128_CBC SHA 3661 TLS_DH_RSA_WITH_AES_128_CBC_SHA DH_RSA AES_128_CBC SHA 3662 TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE_DSS AES_128_CBC SHA 3663 TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE_RSA AES_128_CBC SHA 3664 TLS_DH_anon_WITH_AES_128_CBC_SHA DH_anon AES_128_CBC SHA 3665 TLS_DH_DSS_WITH_AES_256_CBC_SHA DH_DSS AES_256_CBC SHA 3666 TLS_DH_RSA_WITH_AES_256_CBC_SHA DH_RSA AES_256_CBC SHA 3667 TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE_DSS AES_256_CBC SHA 3668 TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE_RSA AES_256_CBC SHA 3669 TLS_DH_anon_WITH_AES_256_CBC_SHA DH_anon AES_256_CBC SHA 3670 TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH_DSS AES_128_CBC SHA256 3671 TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH_RSA AES_128_CBC SHA256 3672 TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE_DSS AES_128_CBC SHA256 3673 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE_RSA AES_128_CBC SHA256 3674 TLS_DH_anon_WITH_AES_128_CBC_SHA256 DH_anon AES_128_CBC SHA256 3675 TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH_DSS AES_256_CBC SHA256 3676 TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH_RSA AES_256_CBC SHA256 3677 TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE_DSS AES_256_CBC SHA256 3678 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE_RSA AES_256_CBC SHA256 3679 TLS_DH_anon_WITH_AES_256_CBC_SHA256 DH_anon AES_256_CBC SHA256 3681 Key Expanded IV Block 3682 Cipher Type Material Key Material Size Size 3684 NULL Stream 0 0 0 N/A 3685 RC4_128 Stream 16 16 0 N/A 3686 3DES_EDE_CBC Block 24 24 8 8 3687 AES_128_CBC Block 16 16 16 16 3688 AES_256_CBC Block 32 32 16 16 3690 MAC Algorithm mac_length mac_key_length 3692 NULL N/A 0 0 3693 MD5 HMAC-MD5 16 16 3694 SHA HMAC-SHA1 20 20 3695 SHA256 HMAC-SHA256 32 32 3697 Type 3698 Indicates whether this is a stream cipher or a block cipher 3699 running in CBC mode. 3701 Key Material 3702 The number of bytes from the key_block that are used for 3703 generating the write keys. 3705 Expanded Key Material 3706 The number of bytes actually fed into the encryption algorithm. 3708 IV Size 3709 The amount of data needed to be generated for the initialization 3710 vector. Zero for stream ciphers; equal to the block size for block 3711 ciphers (this is equal to SecurityParameters.record_iv_length). 3713 Block Size 3714 The amount of data a block cipher enciphers in one chunk; a block 3715 cipher running in CBC mode can only encrypt an even multiple of 3716 its block size. 3718 Appendix D. Implementation Notes 3720 The TLS protocol cannot prevent many common security mistakes. This 3721 section provides several recommendations to assist implementors. 3723 D.1 Random Number Generation and Seeding 3725 TLS requires a cryptographically secure pseudorandom number generator 3726 (PRNG). Care must be taken in designing and seeding PRNGs. PRNGs 3727 based on secure hash operations, most notably SHA-1, are acceptable, 3728 but cannot provide more security than the size of the random number 3729 generator state. 3731 To estimate the amount of seed material being produced, add the 3732 number of bits of unpredictable information in each seed byte. For 3733 example, keystroke timing values taken from a PC compatible's 18.2 Hz 3734 timer provide 1 or 2 secure bits each, even though the total size of 3735 the counter value is 16 bits or more. Seeding a 128-bit PRNG would 3736 thus require approximately 100 such timer values. 3738 [RANDOM] provides guidance on the generation of random values. 3740 D.2 Certificates and Authentication 3742 Implementations are responsible for verifying the integrity of 3743 certificates and should generally support certificate revocation 3744 messages. Certificates should always be verified to ensure proper 3745 signing by a trusted Certificate Authority (CA). The selection and 3746 addition of trusted CAs should be done very carefully. Users should 3747 be able to view information about the certificate and root CA. 3749 D.3 Cipher Suites 3751 TLS supports a range of key sizes and security levels, including some 3752 that provide no or minimal security. A proper implementation will 3753 probably not support many cipher suites. For instance, anonymous 3754 Diffie-Hellman is strongly discouraged because it cannot prevent man- 3755 in-the-middle attacks. Applications should also enforce minimum and 3756 maximum key sizes. For example, certificate chains containing 512-bit 3757 RSA keys or signatures are not appropriate for high-security 3758 applications. 3760 D.4 Implementation Pitfalls 3762 Implementation experience has shown that certain parts of earlier TLS 3763 specifications are not easy to understand, and have been a source of 3764 interoperability and security problems. Many of these areas have been 3765 clarified in this document, but this appendix contains a short list 3766 of the most important things that require special attention from 3767 implementors. 3769 TLS protocol issues: 3771 - Do you correctly handle handshake messages that are fragmented 3772 to multiple TLS records (see Section 6.2.1)? Including corner 3773 cases like a ClientHello that is split to several small 3774 fragments? Do you fragment handshake messages that exceed the 3775 maximum fragment size? In particular, the certificate and 3776 certificate request handshake messages can be large enough to 3777 require fragmentation. 3779 - Do you ignore the TLS record layer version number in all TLS 3780 records before ServerHello (see Appendix E.1)? 3782 - Do you handle TLS extensions in ClientHello correctly, 3783 including omitting the extensions field completely? 3785 - Do you support renegotiation, both client and server initiated? 3786 While renegotiation is an optional feature, supporting 3787 it is highly recommended. 3789 - When the server has requested a client certificate, but no 3790 suitable certificate is available, do you correctly send 3791 an empty Certificate message, instead of omitting the whole 3792 message (see Section 7.4.6)? 3794 Cryptographic details: 3796 - In RSA-encrypted Premaster Secret, do you correctly send and 3797 verify the version number? When an error is encountered, do 3798 you continue the handshake to avoid the Bleichenbacher 3799 attack (see Section 7.4.7.1)? 3801 - What countermeasures do you use to prevent timing attacks against 3802 RSA decryption and signing operations (see Section 7.4.7.1)? 3804 - When verifying RSA signatures, do you accept both NULL and 3805 missing parameters (see Section 4.7)? Do you verify that the 3806 RSA padding doesn't have additional data after the hash value? 3807 [FI06] 3809 - When using Diffie-Hellman key exchange, do you correctly strip 3810 leading zero bytes from the negotiated key (see Section 8.1.2)? 3812 - Does your TLS client check that the Diffie-Hellman parameters 3813 sent by the server are acceptable (see Section F.1.1.3)? 3815 - How do you generate unpredictable IVs for CBC mode ciphers 3816 (see Section 6.2.3.2)? 3818 - Do you accept long CBC mode padding (up to 255 bytes; see 3819 Section 6.2.3.2)? 3821 - How do you address CBC mode timing attacks (Section 6.2.3.2)? 3823 - Do you use a strong and, most importantly, properly seeded 3824 random number generator (see Appendix D.1) for generating the 3825 premaster secret (for RSA key exchange), Diffie-Hellman private 3826 values, the DSA "k" parameter, and other security-critical 3827 values? 3829 Appendix E. Backward Compatibility 3831 E.1 Compatibility with TLS 1.0/1.1 and SSL 3.0 3833 Since there are various versions of TLS (1.0, 1.1, 1.2, and any 3834 future versions) and SSL (2.0 and 3.0), means are needed to negotiate 3835 the specific protocol version to use. The TLS protocol provides a 3836 built-in mechanism for version negotiation so as not to bother other 3837 protocol components with the complexities of version selection. 3839 TLS versions 1.0, 1.1, and 1.2, and SSL 3.0 are very similar, and use 3840 compatible ClientHello messages; thus, supporting all of them is 3841 relatively easy. Similarly, servers can easily handle clients trying 3842 to use future versions of TLS as long as the ClientHello format 3843 remains compatible, and the client support the highest protocol 3844 version available in the server. 3846 A TLS 1.2 client who wishes to negotiate with such older servers will 3847 send a normal TLS 1.2 ClientHello, containing { 3, 3 } (TLS 1.2) in 3848 ClientHello.client_version. If the server does not support this 3849 version, it will respond with ServerHello containing an older version 3850 number. If the client agrees to use this version, the negotiation 3851 will proceed as appropriate for the negotiated protocol. 3853 If the version chosen by the server is not supported by the client 3854 (or not acceptable), the client MUST send a "protocol_version" alert 3855 message and close the connection. 3857 If a TLS server receives a ClientHello containing a version number 3858 greater than the highest version supported by the server, it MUST 3859 reply according to the highest version supported by the server. 3861 A TLS server can also receive a ClientHello containing version number 3862 smaller than the highest supported version. If the server wishes to 3863 negotiate with old clients, it will proceed as appropriate for the 3864 highest version supported by the server that is not greater than 3865 ClientHello.client_version. For example, if the server supports TLS 3866 1.0, 1.1, and 1.2, and client_version is TLS 1.0, the server will 3867 proceed with a TLS 1.0 ServerHello. If server supports (or is willing 3868 to use) only versions greater than client_version, it MUST send a 3869 "protocol_version" alert message and close the connection. 3871 Whenever a client already knows the highest protocol known to a 3872 server (for example, when resuming a session), it SHOULD initiate the 3873 connection in that native protocol. 3875 Note: some server implementations are known to implement version 3876 negotiation incorrectly. For example, there are buggy TLS 1.0 servers 3877 that simply close the connection when the client offers a version 3878 newer than TLS 1.0. Also, it is known that some servers will refuse 3879 connection if any TLS extensions are included in ClientHello. 3880 Interoperability with such buggy servers is a complex topic beyond 3881 the scope of this document, and may require multiple connection 3882 attempts by the client. 3884 Earlier versions of the TLS specification were not fully clear on 3885 what the record layer version number (TLSPlaintext.version) should 3886 contain when sending ClientHello (i.e., before it is known which 3887 version of the protocol will be employed). Thus, TLS servers 3888 compliant with this specification MUST accept any value {03,XX} as 3889 the record layer version number for ClientHello. 3891 TLS clients that wish to negotiate with older servers MAY send any 3892 value {03,XX} as the record layer version number. Typical values 3893 would be {03,00}, the lowest version number supported by the client, 3894 and the value of ClientHello.client_version. No single value will 3895 guarantee interoperability with all old servers, but this is a 3896 complex topic beyond the scope of this document. 3898 E.2 Compatibility with SSL 2.0 3900 TLS 1.2 clients that wish to support SSL 2.0 servers MUST send 3901 version 2.0 CLIENT-HELLO messages defined in [SSL2]. The message MUST 3902 contain the same version number as would be used for ordinary 3903 ClientHello, and MUST encode the supported TLS cipher suites in the 3904 CIPHER-SPECS-DATA field as described below. 3906 Warning: The ability to send version 2.0 CLIENT-HELLO messages will 3907 be phased out with all due haste, since the newer ClientHello format 3908 provides better mechanisms for moving to newer versions and 3909 negotiating extensions. TLS 1.2 clients SHOULD NOT support SSL 2.0. 3911 However, even TLS servers that do not support SSL 2.0 MAY accept 3912 version 2.0 CLIENT-HELLO messages. The message is presented below in 3913 sufficient detail for TLS server implementors; the true definition is 3914 still assumed to be [SSL2]. 3916 For negotiation purposes, 2.0 CLIENT-HELLO is interpreted the same 3917 way as a ClientHello with a "null" compression method and no 3918 extensions. Note that this message MUST be sent directly on the wire, 3919 not wrapped as a TLS record. For the purposes of calculating Finished 3920 and CertificateVerify, the msg_length field is not considered to be a 3921 part of the handshake message. 3923 uint8 V2CipherSpec[3]; 3924 struct { 3925 uint16 msg_length; 3926 uint8 msg_type; 3927 Version version; 3928 uint16 cipher_spec_length; 3929 uint16 session_id_length; 3930 uint16 challenge_length; 3931 V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length]; 3932 opaque session_id[V2ClientHello.session_id_length]; 3933 opaque challenge[V2ClientHello.challenge_length; 3934 } V2ClientHello; 3936 msg_length 3937 The highest bit MUST be 1; the remaining bits contain the length 3938 of the following data in bytes. 3940 msg_type 3941 This field, in conjunction with the version field, identifies a 3942 version 2 client hello message. The value MUST be one (1). 3944 version 3945 Equal to ClientHello.client_version. 3947 cipher_spec_length 3948 This field is the total length of the field cipher_specs. It 3949 cannot be zero and MUST be a multiple of the V2CipherSpec length 3950 (3). 3952 session_id_length 3953 This field MUST have a value of zero for a client that claims to 3954 support TLS 1.2. 3956 challenge_length 3957 The length in bytes of the client's challenge to the server to 3958 authenticate itself. Historically, permissible values are between 3959 16 and 32 bytes inclusive. When using the SSLv2 backward 3960 compatible handshake the client SHOULD use a 32 byte challenge. 3962 cipher_specs 3963 This is a list of all CipherSpecs the client is willing and able 3964 to use. In addition to the 2.0 cipher specs defined in [SSL2], 3965 this includes the TLS cipher suites normally sent in 3966 ClientHello.cipher_suites, each cipher suite prefixed by a zero 3967 byte. For example, TLS cipher suite {0x00,0x0A} would be sent as 3968 {0x00,0x00,0x0A}. 3970 session_id 3971 This field MUST be empty. 3973 challenge 3974 Corresponds to ClientHello.random. If the challenge length is less 3975 than 32, the TLS server will pad the data with leading (note: not 3976 trailing) zero bytes to make it 32 bytes long. 3978 Note: Requests to resume a TLS session MUST use a TLS client hello. 3980 E.3. Avoiding Man-in-the-Middle Version Rollback 3982 When TLS clients fall back to Version 2.0 compatibility mode, they 3983 MUST use special PKCS#1 block formatting. This is done so that TLS 3984 servers will reject Version 2.0 sessions with TLS-capable clients. 3986 When a client negotiates SSL 2.0 but also supports TLS, it MUST set 3987 the right-hand (least-significant) 8 random bytes of the PKCS padding 3988 (not including the terminal null of the padding) for the RSA 3989 encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY 3990 to 0x03 (the other padding bytes are random). 3992 When a TLS-capable server negotiates SSL 2.0 it SHOULD, after 3993 decrypting the ENCRYPTED-KEY-DATA field, check that these eight 3994 padding bytes are 0x03. If they are not, the server SHOULD generate a 3995 random value for SECRET-KEY-DATA, and continue the handshake (which 3996 will eventually fail since the keys will not match). Note that 3997 reporting the error situation to the client could make the server 3998 vulnerable to attacks described in [BLEI]. 4000 Appendix F. Security Analysis 4002 The TLS protocol is designed to establish a secure connection between 4003 a client and a server communicating over an insecure channel. This 4004 document makes several traditional assumptions, including that 4005 attackers have substantial computational resources and cannot obtain 4006 secret information from sources outside the protocol. Attackers are 4007 assumed to have the ability to capture, modify, delete, replay, and 4008 otherwise tamper with messages sent over the communication channel. 4009 This appendix outlines how TLS has been designed to resist a variety 4010 of attacks. 4012 F.1. Handshake Protocol 4014 The handshake protocol is responsible for selecting a CipherSpec and 4015 generating a Master Secret, which together comprise the primary 4016 cryptographic parameters associated with a secure session. The 4017 handshake protocol can also optionally authenticate parties who have 4018 certificates signed by a trusted certificate authority. 4020 F.1.1. Authentication and Key Exchange 4022 TLS supports three authentication modes: authentication of both 4023 parties, server authentication with an unauthenticated client, and 4024 total anonymity. Whenever the server is authenticated, the channel is 4025 secure against man-in-the-middle attacks, but completely anonymous 4026 sessions are inherently vulnerable to such attacks. Anonymous 4027 servers cannot authenticate clients. If the server is authenticated, 4028 its certificate message must provide a valid certificate chain 4029 leading to an acceptable certificate authority. Similarly, 4030 authenticated clients must supply an acceptable certificate to the 4031 server. Each party is responsible for verifying that the other's 4032 certificate is valid and has not expired or been revoked. 4034 The general goal of the key exchange process is to create a 4035 pre_master_secret known to the communicating parties and not to 4036 attackers. The pre_master_secret will be used to generate the 4037 master_secret (see Section 8.1). The master_secret is required to 4038 generate the finished messages, encryption keys, and MAC keys (see 4039 Sections 7.4.9 and 6.3). By sending a correct finished message, 4040 parties thus prove that they know the correct pre_master_secret. 4042 F.1.1.1. Anonymous Key Exchange 4044 Completely anonymous sessions can be established using Diffie-Hellman 4045 for key exchange. The server's public parameters are contained in the 4046 server key exchange message and the client's are sent in the client 4047 key exchange message. Eavesdroppers who do not know the private 4048 values should not be able to find the Diffie-Hellman result (i.e. the 4049 pre_master_secret). 4051 Warning: Completely anonymous connections only provide protection 4052 against passive eavesdropping. Unless an independent tamper-proof 4053 channel is used to verify that the finished messages were not 4054 replaced by an attacker, server authentication is required in 4055 environments where active man-in-the-middle attacks are a concern. 4057 F.1.1.2. RSA Key Exchange and Authentication 4059 With RSA, key exchange and server authentication are combined. The 4060 public key is contained in the server's certificate. Note that 4061 compromise of the server's static RSA key results in a loss of 4062 confidentiality for all sessions protected under that static key. TLS 4063 users desiring Perfect Forward Secrecy should use DHE cipher suites. 4064 The damage done by exposure of a private key can be limited by 4065 changing one's private key (and certificate) frequently. 4067 After verifying the server's certificate, the client encrypts a 4068 pre_master_secret with the server's public key. By successfully 4069 decoding the pre_master_secret and producing a correct finished 4070 message, the server demonstrates that it knows the private key 4071 corresponding to the server certificate. 4073 When RSA is used for key exchange, clients are authenticated using 4074 the certificate verify message (see Section 7.4.8). The client signs 4075 a value derived from all preceding handshake messages. These 4076 handshake messages include the server certificate, which binds the 4077 signature to the server, and ServerHello.random, which binds the 4078 signature to the current handshake process. 4080 F.1.1.3. Diffie-Hellman Key Exchange with Authentication 4082 When Diffie-Hellman key exchange is used, the server can either 4083 supply a certificate containing fixed Diffie-Hellman parameters or 4084 use the server key exchange message to send a set of temporary 4085 Diffie-Hellman parameters signed with a DSS or RSA certificate. 4086 Temporary parameters are hashed with the hello.random values before 4087 signing to ensure that attackers do not replay old parameters. In 4088 either case, the client can verify the certificate or signature to 4089 ensure that the parameters belong to the server. 4091 If the client has a certificate containing fixed Diffie-Hellman 4092 parameters, its certificate contains the information required to 4093 complete the key exchange. Note that in this case the client and 4094 server will generate the same Diffie-Hellman result (i.e., 4095 pre_master_secret) every time they communicate. To prevent the 4096 pre_master_secret from staying in memory any longer than necessary, 4097 it should be converted into the master_secret as soon as possible. 4098 Client Diffie-Hellman parameters must be compatible with those 4099 supplied by the server for the key exchange to work. 4101 If the client has a standard DSS or RSA certificate or is 4102 unauthenticated, it sends a set of temporary parameters to the server 4103 in the client key exchange message, then optionally uses a 4104 certificate verify message to authenticate itself. 4106 If the same DH keypair is to be used for multiple handshakes, either 4107 because the client or server has a certificate containing a fixed DH 4108 keypair or because the server is reusing DH keys, care must be taken 4109 to prevent small subgroup attacks. Implementations SHOULD follow the 4110 guidelines found in [SUBGROUP]. 4112 Small subgroup attacks are most easily avoided by using one of the 4113 DHE cipher suites and generating a fresh DH private key (X) for each 4114 handshake. If a suitable base (such as 2) is chosen, g^X mod p can be 4115 computed very quickly, therefore the performance cost is minimized. 4116 Additionally, using a fresh key for each handshake provides Perfect 4117 Forward Secrecy. Implementations SHOULD generate a new X for each 4118 handshake when using DHE cipher suites. 4120 Because TLS allows the server to provide arbitrary DH groups, the 4121 client should verify that the DH group is of suitable size as defined 4122 by local policy. The client SHOULD also verify that the DH public 4123 exponent appears to be of adequate size. [KEYSIZ] provides a useful 4124 guide to the strength of various group sizes. The server MAY choose 4125 to assist the client by providing a known group, such as those 4126 defined in [IKEALG] or [MODP]. These can be verified by simple 4127 comparison. 4129 F.1.2. Version Rollback Attacks 4131 Because TLS includes substantial improvements over SSL Version 2.0, 4132 attackers may try to make TLS-capable clients and servers fall back 4133 to Version 2.0. This attack can occur if (and only if) two TLS- 4134 capable parties use an SSL 2.0 handshake. 4136 Although the solution using non-random PKCS #1 block type 2 message 4137 padding is inelegant, it provides a reasonably secure way for Version 4138 3.0 servers to detect the attack. This solution is not secure against 4139 attackers who can brute force the key and substitute a new ENCRYPTED- 4140 KEY-DATA message containing the same key (but with normal padding) 4141 before the application specified wait threshold has expired. Altering 4142 the padding of the least significant 8 bytes of the PKCS padding does 4143 not impact security for the size of the signed hashes and RSA key 4144 lengths used in the protocol, since this is essentially equivalent to 4145 increasing the input block size by 8 bytes. 4147 F.1.3. Detecting Attacks Against the Handshake Protocol 4149 An attacker might try to influence the handshake exchange to make the 4150 parties select different encryption algorithms than they would 4151 normally chooses. 4153 For this attack, an attacker must actively change one or more 4154 handshake messages. If this occurs, the client and server will 4155 compute different values for the handshake message hashes. As a 4156 result, the parties will not accept each others' finished messages. 4157 Without the master_secret, the attacker cannot repair the finished 4158 messages, so the attack will be discovered. 4160 F.1.4. Resuming Sessions 4162 When a connection is established by resuming a session, new 4163 ClientHello.random and ServerHello.random values are hashed with the 4164 session's master_secret. Provided that the master_secret has not been 4165 compromised and that the secure hash operations used to produce the 4166 encryption keys and MAC keys are secure, the connection should be 4167 secure and effectively independent from previous connections. 4168 Attackers cannot use known encryption keys or MAC secrets to 4169 compromise the master_secret without breaking the secure hash 4170 operations. 4172 Sessions cannot be resumed unless both the client and server agree. 4173 If either party suspects that the session may have been compromised, 4174 or that certificates may have expired or been revoked, it should 4175 force a full handshake. An upper limit of 24 hours is suggested for 4176 session ID lifetimes, since an attacker who obtains a master_secret 4177 may be able to impersonate the compromised party until the 4178 corresponding session ID is retired. Applications that may be run in 4179 relatively insecure environments should not write session IDs to 4180 stable storage. 4182 F.2. Protecting Application Data 4184 The master_secret is hashed with the ClientHello.random and 4185 ServerHello.random to produce unique data encryption keys and MAC 4186 secrets for each connection. 4188 Outgoing data is protected with a MAC before transmission. To prevent 4189 message replay or modification attacks, the MAC is computed from the 4190 MAC key, the sequence number, the message length, the message 4191 contents, and two fixed character strings. The message type field is 4192 necessary to ensure that messages intended for one TLS Record Layer 4193 client are not redirected to another. The sequence number ensures 4194 that attempts to delete or reorder messages will be detected. Since 4195 sequence numbers are 64 bits long, they should never overflow. 4196 Messages from one party cannot be inserted into the other's output, 4197 since they use independent MAC keys. Similarly, the server-write and 4198 client-write keys are independent, so stream cipher keys are used 4199 only once. 4201 If an attacker does break an encryption key, all messages encrypted 4202 with it can be read. Similarly, compromise of a MAC key can make 4203 message modification attacks possible. Because MACs are also 4204 encrypted, message-alteration attacks generally require breaking the 4205 encryption algorithm as well as the MAC. 4207 Note: MAC keys may be larger than encryption keys, so messages can 4208 remain tamper resistant even if encryption keys are broken. 4210 F.3. Explicit IVs 4212 [CBCATT] describes a chosen plaintext attack on TLS that depends on 4213 knowing the IV for a record. Previous versions of TLS [TLS1.0] used 4214 the CBC residue of the previous record as the IV and therefore 4215 enabled this attack. This version uses an explicit IV in order to 4216 protect against this attack. 4218 F.4. Security of Composite Cipher Modes 4220 TLS secures transmitted application data via the use of symmetric 4221 encryption and authentication functions defined in the negotiated 4222 cipher suite. The objective is to protect both the integrity and 4223 confidentiality of the transmitted data from malicious actions by 4224 active attackers in the network. It turns out that the order in 4225 which encryption and authentication functions are applied to the data 4226 plays an important role for achieving this goal [ENCAUTH]. 4228 The most robust method, called encrypt-then-authenticate, first 4229 applies encryption to the data and then applies a MAC to the 4230 ciphertext. This method ensures that the integrity and 4231 confidentiality goals are obtained with ANY pair of encryption and 4232 MAC functions, provided that the former is secure against chosen 4233 plaintext attacks and that the MAC is secure against chosen-message 4234 attacks. TLS uses another method, called authenticate-then-encrypt, 4235 in which first a MAC is computed on the plaintext and then the 4236 concatenation of plaintext and MAC is encrypted. This method has 4237 been proven secure for CERTAIN combinations of encryption functions 4238 and MAC functions, but it is not guaranteed to be secure in general. 4239 In particular, it has been shown that there exist perfectly secure 4240 encryption functions (secure even in the information-theoretic sense) 4241 that combined with any secure MAC function, fail to provide the 4242 confidentiality goal against an active attack. Therefore, new cipher 4243 suites and operation modes adopted into TLS need to be analyzed under 4244 the authenticate-then-encrypt method to verify that they achieve the 4245 stated integrity and confidentiality goals. 4247 Currently, the security of the authenticate-then-encrypt method has 4248 been proven for some important cases. One is the case of stream 4249 ciphers in which a computationally unpredictable pad of the length of 4250 the message, plus the length of the MAC tag, is produced using a 4251 pseudo-random generator and this pad is xor-ed with the concatenation 4252 of plaintext and MAC tag. The other is the case of CBC mode using a 4253 secure block cipher. In this case, security can be shown if one 4254 applies one CBC encryption pass to the concatenation of plaintext and 4255 MAC and uses a new, independent, and unpredictable IV for each new 4256 pair of plaintext and MAC. In versions of TLS prior to 1.1, CBC mode 4257 was used properly EXCEPT that it used a predictable IV in the form of 4258 the last block of the previous ciphertext. This made TLS open to 4259 chosen plaintext attacks. This version of the protocol is immune to 4260 those attacks. For exact details in the encryption modes proven 4261 secure, see [ENCAUTH]. 4263 F.5 Denial of Service 4265 TLS is susceptible to a number of denial of service (DoS) attacks. 4266 In particular, an attacker who initiates a large number of TCP 4267 connections can cause a server to consume large amounts of CPU doing 4268 RSA decryption. However, because TLS is generally used over TCP, it 4269 is difficult for the attacker to hide his point of origin if proper 4270 TCP SYN randomization is used [SEQNUM] by the TCP stack. 4272 Because TLS runs over TCP, it is also susceptible to a number of 4273 denial of service attacks on individual connections. In particular, 4274 attackers can forge RSTs, thereby terminating connections, or forge 4275 partial TLS records, thereby causing the connection to stall. These 4276 attacks cannot in general be defended against by a TCP-using 4277 protocol. Implementors or users who are concerned with this class of 4278 attack should use IPsec AH [AH] or ESP [ESP]. 4280 F.6 Final Notes 4282 For TLS to be able to provide a secure connection, both the client 4283 and server systems, keys, and applications must be secure. In 4284 addition, the implementation must be free of security errors. 4286 The system is only as strong as the weakest key exchange and 4287 authentication algorithm supported, and only trustworthy 4288 cryptographic functions should be used. Short public keys and 4289 anonymous servers should be used with great caution. Implementations 4290 and users must be careful when deciding which certificates and 4291 certificate authorities are acceptable; a dishonest certificate 4292 authority can do tremendous damage. 4294 Changes in This Version 4295 [RFC Editor: Please delete this] 4297 - Added a new pitfall about fragmenting messages when necessary 4298 [Issue #71] 4300 - Added Updates: RFC 4492 [Issue #83] 4302 - Long CBC padding pitfall [Issue #73] 4304 - Fixed ProtocolVersion structure [Issue #79] 4306 - Cleaned up extensions text [Issue #78] 4308 - Clarified alerts some [Issue #85] 4310 - Added AES to the table in Appendix C [Issue #72] 4312 - Tightened up when signature_algorithms is used 4313 (it is now a MUST if you support other than SHA-1) 4314 and the interpretation when it is absent is also a MUST 4315 [Issue #67] 4317 - Cleaned up "cipher suite" so it's always two words outside 4318 of when it refers to the syntactic type [Issue #68] 4320 - Misc editorial. 4322 - Added support for SHA256 cipher suites 4324 - Clarified warning alert behavior and client certificate omission 4325 behavior [Issue #84] 4327 Normative References 4329 [AES] National Institute of Standards and Technology, 4330 "Specification for the Advanced Encryption Standard (AES)" 4331 FIPS 197. November 26, 2001. 4333 [3DES] National Institute of Standards and Technology, 4334 "Recommendation for the Triple Data Encryption Algorithm 4335 (TDEA) Block Cipher", NIST Special Publication 800-67, May 4336 2004. 4338 [DES] National Institute of Standards and Technology, "Data 4339 Encryption Standard (DES)", FIPS PUB 46-3, October 1999. 4341 [DSS] NIST FIPS PUB 186-2, "Digital Signature Standard," National 4342 Institute of Standards and Technology, U.S. Department of 4343 Commerce, 2000. 4345 [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4346 Hashing for Message Authentication", RFC 2104, February 4347 1997. 4349 [MD5] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321, 4350 April 1992. 4352 [PKCS1] J. Jonsson, B. Kaliski, "Public-Key Cryptography Standards 4353 (PKCS) #1: RSA Cryptography Specifications Version 2.1", RFC 4354 3447, February 2003. 4356 [PKIX] Housley, R., Ford, W., Polk, W. and D. Solo, "Internet X.509 4357 Public Key Infrastructure Certificate and Certificate 4358 Revocation List (CRL) Profile", RFC 3280, April 2002. 4360 [SCH] B. Schneier. "Applied Cryptography: Protocols, Algorithms, 4361 and Source Code in C, 2nd ed.", Published by John Wiley & 4362 Sons, Inc. 1996. 4364 [SHA] NIST FIPS PUB 180-2, "Secure Hash Standard," National 4365 Institute of Standards and Technology, U.S. Department of 4366 Commerce., August 2001. 4368 [REQ] Bradner, S., "Key words for use in RFCs to Indicate 4369 Requirement Levels", BCP 14, RFC 2119, March 1997. 4371 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4372 IANA Considerations Section in RFCs", BCP 25, RFC 2434, 4373 October 1998. 4375 Informative References 4377 [AEAD] Mcgrew, D., "Authenticated Encryption", February 2007, 4378 draft-mcgrew-auth-enc-02.txt. 4380 [AH] Kent, S., and Atkinson, R., "IP Authentication Header", RFC 4381 4302, December 2005. 4383 [BLEI] Bleichenbacher D., "Chosen Ciphertext Attacks against 4384 Protocols Based on RSA Encryption Standard PKCS #1" in 4385 Advances in Cryptology -- CRYPTO'98, LNCS vol. 1462, pages: 4386 1-12, 1998. 4388 [CBCATT] Moeller, B., "Security of CBC Ciphersuites in SSL/TLS: 4389 Problems and Countermeasures", 4390 http://www.openssl.org/~bodo/tls-cbc.txt. 4392 [CBCTIME] Canvel, B., Hiltgen, A., Vaudenay, S., and M. Vuagnoux, 4393 "Password Interception in a SSL/TLS Channel", Advances in 4394 Cryptology -- CRYPTO 2003, LNCS vol. 2729, 2003. 4396 [CCM] "NIST Special Publication 800-38C: The CCM Mode for 4397 Authentication and Confidentiality", 4398 http://csrc.nist.gov/publications/nistpubs/800-38C/ 4399 SP800-38C.pdf 4401 [DSS-3] NIST FIPS PUB 186-3 Draft, "Digital Signature Standard," 4402 National Institute of Standards and Technology, U.S. 4403 Department of Commerce, 2006. 4405 [ENCAUTH] Krawczyk, H., "The Order of Encryption and Authentication 4406 for Protecting Communications (Or: How Secure is SSL?)", 4407 Crypto 2001. 4409 [ESP] Kent, S., and Atkinson, R., "IP Encapsulating Security 4410 Payload (ESP)", RFC 4303, December 2005. 4412 [FI06] Hal Finney, "Bleichenbacher's RSA signature forgery based on 4413 implementation error", ietf-openpgp@imc.org mailing list, 27 4414 August 2006, http://www.imc.org/ietf-openpgp/mail- 4415 archive/msg14307.html. 4417 [GCM] "NIST Special Publication 800-38D DRAFT (June, 2007): 4418 Recommendation for Block Cipher Modes of Operation: 4419 Galois/Counter Mode (GCM) and GMAC" 4421 [IDEA] X. Lai, "On the Design and Security of Block Ciphers," ETH 4422 Series in Information Processing, v. 1, Konstanz: Hartung- 4423 Gorre Verlag, 1992. 4425 [IKEALG] Schiller, J., "Cryptographic Algorithms for Use in the 4426 Internet Key Exchange Version 2 (IKEv2)", RFC 4307, December 4427 2005. 4429 [KEYSIZ] Orman, H., and Hoffman, P., "Determining Strengths For 4430 Public Keys Used For Exchanging Symmetric Keys" RFC 3766, 4431 April 2004. 4433 [KPR03] Klima, V., Pokorny, O., Rosa, T., "Attacking RSA-based 4434 Sessions in SSL/TLS", http://eprint.iacr.org/2003/052/, 4435 March 2003. 4437 [MODP] Kivinen, T. and M. Kojo, "More Modular Exponential (MODP) 4438 Diffie-Hellman groups for Internet Key Exchange (IKE)", RFC 4439 3526, May 2003. 4441 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate Syntax 4442 Standard," version 1.5, November 1993. 4444 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message Syntax 4445 Standard," version 1.5, November 1993. 4447 [RANDOM] Eastlake, D., 3rd, Schiller, J., and S. Crocker, "Randomness 4448 Requirements for Security", BCP 106, RFC 4086, June 2005. 4450 [RC2] Rivest, R., "A Description of the RC2(r) Encryption 4451 Algorithm", RFC 2268, March 1998. 4453 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 4454 Compression Methods", RFC 3749, May 2004. 4456 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 4457 Wright, T., "Transport Layer Security (TLS) Extensions", RFC 4458 4366, April 2006. 4460 [RSA] R. Rivest, A. Shamir, and L. M. Adleman, "A Method for 4461 Obtaining Digital Signatures and Public-Key Cryptosystems," 4462 Communications of the ACM, v. 21, n. 2, Feb 1978, pp. 4463 120-126. 4465 [SEQNUM] Bellovin. S., "Defending Against Sequence Number Attacks", 4466 RFC 1948, May 1996. 4468 [SSL2] Hickman, Kipp, "The SSL Protocol", Netscape Communications 4469 Corp., Feb 9, 1995. 4471 [SSL3] A. Freier, P. Karlton, and P. Kocher, "The SSL 3.0 4472 Protocol", Netscape Communications Corp., Nov 18, 1996. 4474 [SUBGROUP] Zuccherato, R., "Methods for Avoiding the "Small-Subgroup" 4475 Attacks on the Diffie-Hellman Key Agreement Method for 4476 S/MIME", RFC 2785, March 2000. 4478 [TCP] Postel, J., "Transmission Control Protocol," STD 7, RFC 793, 4479 September 1981. 4481 [TIMING] Boneh, D., Brumley, D., "Remote timing attacks are 4482 practical", USENIX Security Symposium 2003. 4484 [TLSAES] Chown, P., "Advanced Encryption Standard (AES) Ciphersuites 4485 for Transport Layer Security (TLS)", RFC 3268, June 2002. 4487 [TLSECC] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and 4488 Moeller, B., "Elliptic Curve Cryptography (ECC) Cipher 4489 Suites for Transport Layer Security (TLS)", RFC 4492, May 4490 2006. 4492 [TLSEXT] Eastlake, D.E., "Transport Layer Security (TLS) Extensions: 4493 Extension Definitions", July 2007, draft-ietf-tls- 4494 rfc4366-bis-00.txt. 4496 [TLSPGP] Mavrogiannopoulos, N., "Using OpenPGP keys for TLS 4497 authentication", RFC 5081, November 2007. 4499 [TLSPSK] Eronen, P., Tschofenig, H., "Pre-Shared Key Ciphersuites for 4500 Transport Layer Security (TLS)", RFC 4279, December 2005. 4502 [TLS1.0] Dierks, T., and C. Allen, "The TLS Protocol, Version 1.0", 4503 RFC 2246, January 1999. 4505 [TLS1.1] Dierks, T., and E. Rescorla, "The TLS Protocol, Version 4506 1.1", RFC 4346, April, 2006. 4508 [X501] ITU-T Recommendation X.501: Information Technology - Open 4509 Systems Interconnection - The Directory: Models, 1993. 4511 [XDR] Eisler, M., "External Data Representation Standard", RFC 4512 4506, May 2006. 4514 Credits 4516 Working Group Chairs 4518 Eric Rescorla 4519 EMail: ekr@networkresonance.com 4521 Pasi Eronen 4522 pasi.eronen@nokia.com 4524 Editors 4525 Tim Dierks Eric Rescorla 4526 Independent Network Resonance, Inc. 4527 EMail: tim@dierks.org EMail: ekr@networkresonance.com 4529 Other contributors 4531 Christopher Allen (co-editor of TLS 1.0) 4532 Alacrity Ventures 4533 ChristopherA@AlacrityManagement.com 4535 Martin Abadi 4536 University of California, Santa Cruz 4537 abadi@cs.ucsc.edu 4539 Steven M. Bellovin 4540 Columbia University 4541 smb@cs.columbia.edu 4543 Simon Blake-Wilson 4544 BCI 4545 EMail: sblakewilson@bcisse.com 4547 Ran Canetti 4548 IBM 4549 canetti@watson.ibm.com 4551 Pete Chown 4552 Skygate Technology Ltd 4553 pc@skygate.co.uk 4555 Taher Elgamal 4556 taher@securify.com 4557 Securify 4559 Anil Gangolli 4560 anil@busybuddha.org 4562 Kipp Hickman 4564 Alfred Hoenes 4566 David Hopwood 4567 Independent Consultant 4568 EMail: david.hopwood@blueyonder.co.uk 4570 Phil Karlton (co-author of SSLv3) 4571 Paul Kocher (co-author of SSLv3) 4572 Cryptography Research 4573 paul@cryptography.com 4575 Hugo Krawczyk 4576 IBM 4577 hugo@ee.technion.ac.il 4579 Jan Mikkelsen 4580 Transactionware 4581 EMail: janm@transactionware.com 4583 Magnus Nystrom 4584 RSA Security 4585 EMail: magnus@rsasecurity.com 4587 Robert Relyea 4588 Netscape Communications 4589 relyea@netscape.com 4591 Jim Roskind 4592 Netscape Communications 4593 jar@netscape.com 4595 Michael Sabin 4597 Dan Simon 4598 Microsoft, Inc. 4599 dansimon@microsoft.com 4601 Tom Weinstein 4603 Tim Wright 4604 Vodafone 4605 EMail: timothy.wright@vodafone.com 4607 Comments 4609 The discussion list for the IETF TLS working group is located at the 4610 e-mail address . Information on the group and 4611 information on how to subscribe to the list is at 4612 4614 Archives of the list can be found at: 4615 4617 Full Copyright Statement 4619 Copyright (C) The IETF Trust (2008). 4621 This document is subject to the rights, licenses and restrictions 4622 contained in BCP 78, and except as set forth therein, the authors 4623 retain all their rights. 4625 This document and the information contained herein are provided on an 4626 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4627 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4628 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4629 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4630 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4631 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4633 Intellectual Property 4635 The IETF takes no position regarding the validity or scope of any 4636 Intellectual Property Rights or other rights that might be claimed to 4637 pertain to the implementation or use of the technology described in 4638 this document or the extent to which any license under such rights 4639 might or might not be available; nor does it represent that it has 4640 made any independent effort to identify any such rights. Information 4641 on the procedures with respect to rights in RFC documents can be 4642 found in BCP 78 and BCP 79. 4644 Copies of IPR disclosures made to the IETF Secretariat and any 4645 assurances of licenses to be made available, or the result of an 4646 attempt made to obtain a general license or permission for the use of 4647 such proprietary rights by implementers or users of this 4648 specification can be obtained from the IETF on-line IPR repository at 4649 http://www.ietf.org/ipr. 4651 The IETF invites any interested party to bring to its attention any 4652 copyrights, patents or patent applications, or other proprietary 4653 rights that may cover technology that may be required to implement 4654 this standard. Please address the information to the IETF at 4655 ietf-ipr@ietf.org. 4657 Acknowledgment 4659 Funding for the RFC Editor function is provided by the IETF 4660 Administrative Support Activity (IASA).